Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions PLUGIN.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ Discover `capabilities.fork` from the manifest; do not infer support from the pa
}
```

`messages` is in exactly the same order as `orderedMessages`, describes the raw `pluginSnapshot` rather than a folded view, and includes optional `text`, `toolName`, and `toolCallId`. Compare original text and role to establish the longest matching prefix; tool identities/content type must match too. Copy the corresponding ordered identities verbatim; `identityHash` and revisions are opaque and clients do not need a content-hash algorithm. A message the kernel hard-excludes from compression (`compress.protectedTools`) carries `"ref": null` in both arrays — it participates in ordering and identity but has no addressable ref; copy it verbatim like any other prefix entry. Only `mNNNNN` strings or `null` are legal ref values. Multimodal/opaque content that cannot be verified by this text projection returns `409`, `status: unavailable`, `code: SNAPSHOT_UNAVAILABLE`, not a guessed text match. Missing raw snapshots or inconsistent raw/ref/CCR mappings likewise fail closed. Raw snapshot retention is capped (`BILI_PUBLIC_SNAPSHOT_CAP_BYTES`, default 16 MiB, `0` disables): a session whose serialized raw snapshot grows past the cap stops being forkable — snapshot/fork answer `409 SNAPSHOT_UNAVAILABLE` — instead of retaining an unbounded raw copy forever.
`messages` is in exactly the same order as `orderedMessages`, describes the raw source view (the retained `pluginSnapshot`, or the session's most recent raw request view when no retained copy exists — never a folded view), and includes optional `text`, `toolName`, and `toolCallId`. Compare original text and role to establish the longest matching prefix; tool identities/content type must match too. Copy the corresponding ordered identities verbatim; `identityHash` and revisions are opaque and clients do not need a content-hash algorithm. A message the kernel hard-excludes from compression (`compress.protectedTools`) carries `"ref": null` in both arrays — it participates in ordering and identity but has no addressable ref; copy it verbatim like any other prefix entry. Only `mNNNNN` strings or `null` are legal ref values. Multimodal/opaque content that cannot be verified by this text projection returns `409`, `status: unavailable`, `code: SNAPSHOT_UNAVAILABLE`, not a guessed text match. When neither a retained copy nor a recent raw view exists, or the raw/ref/CCR mappings are inconsistent, the endpoint likewise fails closed with `409 SNAPSHOT_UNAVAILABLE`. That code is RETRYABLE: the condition clears on the parent's next model request (and the recent-raw-view source makes it rare after any traffic at all), so clients must retry on later requests instead of giving up inheritance permanently (#3011). Raw snapshot retention is capped (`BILI_PUBLIC_SNAPSHOT_CAP_BYTES`, default 16 MiB, `0` disables): a session whose serialized raw snapshot grows past the cap stops being forkable — snapshot/fork answer `409 SNAPSHOT_UNAVAILABLE` — instead of retaining an unbounded raw copy forever.

`POST /__bili/plugin/fork` body:

Expand All @@ -194,7 +194,7 @@ Discover `capabilities.fork` from the manifest; do not infer support from the pa

The branch is an ordered prefix, including an empty prefix. Compute its existing order hash as lowercase SHA-256 of UTF-8 `JSON.stringify(orderedMessages)` with each identity object's keys in order `rawId`, `ref`, `identityHash`; for a full prefix reuse snapshot `orderHash`. Do not hash descriptors or folded text. Extra child messages, including a final model reply that has not left the proxy yet, may be appended on the child's first model request after copying the matched prefix.

New success is `201`; exact payload replay is `200` with `replayed: true`, even after restart or later parent changes. Both return `status`, `parentRevision`, `childRevision`, `sessionId`, `branchPoint`, `inheritedBlocks`, and `expandedBlocks`. Reusing the child id with another parent, key or payload returns `409 CHILD_CONFLICT`. Invalid shapes/version/identifiers return `400 INVALID_REQUEST`; absent parent returns `404 PARENT_NOT_FOUND`; stale parent returns `409 PARENT_REVISION_CONFLICT`; altered order/raw/ref/identity returns `409 BRANCH_POINT_CONFLICT`. Missing nested originals return `409 PARENT_STATE_INCOMPLETE` with `status: unavailable`. Publication/persistence failure returns `503 FORK_FAILED` with `status: unavailable` and exposes no child; the same request may be retried.
New success is `201`; exact payload replay is `200` with `replayed: true`, even after restart or later parent changes. A child whose first stamped request landed before adoption may also complete late: the proxy registers the conversation during that request, so if the existing child has never been forked (no receipt, zero self-blocks) and its current raw view is still strictly equal to the requested prefix — same length, per-message identity, per-ref numbering — the proxy materializes the inheritance onto the existing session in place and answers `201` with `lateAdopted: true` (#3025). Both return `status`, `parentRevision`, `childRevision`, `sessionId`, `branchPoint`, `inheritedBlocks`, and `expandedBlocks`. Reusing the child id with another parent, key or payload — or a child that has since grown its own turns, folded its own history, or diverged in ref numbering — returns `409 CHILD_CONFLICT`. Invalid shapes/version/identifiers return `400 INVALID_REQUEST`; absent parent returns `404 PARENT_NOT_FOUND`; stale parent returns `409 PARENT_REVISION_CONFLICT`; altered order/raw/ref/identity returns `409 BRANCH_POINT_CONFLICT`. Missing nested originals return `409 PARENT_STATE_INCOMPLETE` with `status: unavailable`. Publication/persistence failure returns `503 FORK_FAILED` with `status: unavailable` and exposes no child; the same request may be retried.

Boundary handling is `exact` when complete blocks fit inside the prefix, `expanded` when a block crosses it (crossing summaries are omitted, affected nested descendants are expanded, matched originals are retained), and `unavailable` when safe reconstruction is impossible. Blocks, nested caches, raw messages, issued ref namespace, token snapshots, rules and prefix CCR payloads are independent copies. Note that the child inherits the parent's ENTIRE issued-ref namespace (dead refs included): refs are never reused, so forks keep allocating fresh refs without colliding with ids a sibling may still hold. The child never reads its parent's later state as a fallback. Registration and first-request resume heuristics do not replace its copied state. With existing persistence enabled, raw snapshots, receipts, nested originals and the child's CCR payloads survive restart; with persistence disabled, durability is not promised. Atomic child publication/idempotency covers concurrent requests to one proxy process; concurrent writers sharing one state directory across processes are not supported by this protocol.

Expand Down
64 changes: 44 additions & 20 deletions src/agent/fork-adopt.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,11 @@ type SnapshotResponse = {

type ForkAdoptionResult =
| { outcome: "adopted"; branchPoint: number; replayed: boolean }
| { outcome: "degraded"; reason: string };
// #3011: retryable carries the server's structured verdict (its error
// code / status class), NOT a re-parse of the reason string — the old
// regex /^(snapshot|fork) (error|http 5\d\d)/ missed the proxy's own
// documented-retryable 409 SNAPSHOT_UNAVAILABLE and gave up forever.
| { outcome: "degraded"; reason: string; retryable: boolean };

function forkStableJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(forkStableJson).join(",")}]`;
Expand Down Expand Up @@ -387,7 +391,12 @@ async function readBoundedErrorBody(res: Response): Promise<{ code: string; erro
* failure path returns { outcome: "degraded" } — the child then simply starts
* a fresh conversation, exactly today's behavior; adoption is best effort.
* A 409 PARENT_REVISION_CONFLICT (parent mutated between snapshot and fork)
* is retried once with a fresh snapshot before degrading.
* is retried once with a fresh snapshot before degrading. Degraded results
* carry `retryable` (#3011): whether a LATER attempt can succeed — network /
* 5xx / 409 SNAPSHOT_UNAVAILABLE are states the parent can outlive (a fresh
* parent request re-establishes its raw view); deterministic 4xx verdicts
* (unknown parent, diverged prefix, conflicting child) cannot change in this
* process. Consumers classify by the field, never by the reason text.
*/
export async function tryForkAdoption(opts: {
base: string;
Expand All @@ -404,10 +413,10 @@ export async function tryForkAdoption(opts: {
// projected above with pinned parity (#2469 stage 2).
const wire = detectWireFormat(opts.body);
if (wire === "google") {
return { outcome: "degraded", reason: `wire unsupported (${wire})` };
return { outcome: "degraded", reason: `wire unsupported (${wire})`, retryable: false };
}
const core = chatBodyToCore(opts.body);
if (core === null || core.length === 0) return { outcome: "degraded", reason: "body unmappable" };
if (core === null || core.length === 0) return { outcome: "degraded", reason: "body unmappable", retryable: true };
const snapshotUrl = `${opts.base}/__bili/plugin/snapshot?conversationId=${encodeURIComponent(opts.parentConversationId)}`;
for (let attempt = 0; attempt < 2; attempt += 1) {
let snapshot: Awaited<ReturnType<typeof snapshotOf>>;
Expand All @@ -418,15 +427,21 @@ export async function tryForkAdoption(opts: {
// SNAPSHOT_UNAVAILABLE + why) instead of hiding them behind a
// bare status code.
const detail = await readBoundedErrorBody(res);
return { outcome: "degraded", reason: `snapshot http ${res.status}${detail.code ? ` ${detail.code}` : ""}${detail.error ? ` (${detail.error})` : ""}` };
// #3011: classify by the proxy's structured verdict, not by
// re-parsing the reason string. 5xx and 409
// SNAPSHOT_UNAVAILABLE are conditions the parent can outlive
// (a fresh parent request re-establishes its raw view); every
// other 4xx names a state this process cannot fix.
const retryable = res.status >= 500 || (res.status === 409 && detail.code === "SNAPSHOT_UNAVAILABLE");
return { outcome: "degraded", reason: `snapshot http ${res.status}${detail.code ? ` ${detail.code}` : ""}${detail.error ? ` (${detail.error})` : ""}`, retryable };
}
snapshot = snapshotOf(await res.json());
} catch (err) {
return { outcome: "degraded", reason: `snapshot error ${err instanceof Error ? err.message : String(err)}` };
return { outcome: "degraded", reason: `snapshot error ${err instanceof Error ? err.message : String(err)}`, retryable: true };
}
if (snapshot === null) return { outcome: "degraded", reason: "snapshot malformed" };
if (snapshot === null) return { outcome: "degraded", reason: "snapshot malformed", retryable: false };
const branchPoint = matchForkPrefix(core, snapshot.orderedMessages);
if (branchPoint === 0) return { outcome: "degraded", reason: "no prefix match" };
if (branchPoint === 0) return { outcome: "degraded", reason: "no prefix match", retryable: false };
const prefix = snapshot.orderedMessages.slice(0, branchPoint);
const orderHash = branchPoint === snapshot.orderedMessages.length ? snapshot.orderHash : forkOrderHashOf(prefix);
const payload = {
Expand All @@ -447,7 +462,7 @@ export async function tryForkAdoption(opts: {
signal: AbortSignal.timeout(FORK_TIMEOUT_MS),
});
} catch (err) {
return { outcome: "degraded", reason: `fork error ${err instanceof Error ? err.message : String(err)}` };
return { outcome: "degraded", reason: `fork error ${err instanceof Error ? err.message : String(err)}`, retryable: true };
}
if (res.status === 201 || res.status === 200) {
let replayed = false;
Expand All @@ -465,9 +480,12 @@ export async function tryForkAdoption(opts: {
opts.log?.(`fork for ${opts.childConversationId} hit parent revision conflict, retrying once with a fresh snapshot (#2399)`);
continue;
}
return { outcome: "degraded", reason: `fork http ${res.status}${code ? ` ${code}` : ""}` };
// CHILD_CONFLICT / PARENT_STATE_INCOMPLETE / BRANCH_POINT_CONFLICT and
// friends are deterministic verdicts about THIS child's state — only
// 5xx can still change under a later attempt (#3011).
return { outcome: "degraded", reason: `fork http ${res.status}${code ? ` ${code}` : ""}`, retryable: res.status >= 500 };
}
return { outcome: "degraded", reason: "parent revision conflict retry exhausted" };
return { outcome: "degraded", reason: "parent revision conflict retry exhausted", retryable: false };
}

const forkCapabilityCache = new Map<string, boolean>();
Expand Down Expand Up @@ -562,15 +580,21 @@ export function createForkAdopter(log: (line: string) => void, opts?: { maxAttem
done.add(input.child);
return;
}
log(`fork adoption for ${input.child} degraded (${result.reason}) — the session continues without inherited compression state (#2399/#2469)`);
// Only transient failures (network / 5xx / unmappable body) leave the
// window open so a later request retries up to maxAttempts; every other
// outcome is terminal. Once this child's stamped request has landed, a
// retry can only ever meet CHILD_CONFLICT (the server registers the
// child conversation before any later fork POST), which latches here as
// a non-transient outcome (#2403 review).
const transient = /^(snapshot|fork) (error|http 5\d\d)/.test(result.reason) || result.reason === "body unmappable";
if (!transient || (attempts.get(input.child) ?? 0) >= maxAttempts) done.add(input.child);
// #3011: classify by the server's structured verdict on the result
// (retryable), never by re-parsing the reason string — the old regex
// missed 409 SNAPSHOT_UNAVAILABLE and gave up after one attempt.
// Transient outcomes leave the window open for later requests up to
// maxAttempts; every other outcome is terminal. Once this child's
// stamped request has landed, a retry can only ever meet
// CHILD_CONFLICT (the server registers the child conversation before
// any later fork POST), which latches here as non-retryable (#2403).
const exhausted = !result.retryable || (attempts.get(input.child) ?? 0) >= maxAttempts;
if (exhausted) {
log(`fork adoption for ${input.child} degraded (${result.reason}) — permanently disabled, no further retries in this process; the session continues without inherited compression state (#3011/#2399/#2469)`);
done.add(input.child);
} else {
log(`fork adoption for ${input.child} degraded (${result.reason}) — transient, will retry on a later request (attempt ${attempts.get(input.child)}/${maxAttempts}); the session continues without inherited compression state until adopted (#3011/#2399/#2469)`);
}
};
return {
async maybeAdopt(input): Promise<void> {
Expand Down
Loading
Loading