@wowyuarm/dsh-agent-team 0.1.8 → 0.1.10

package/packages/agent-team/lib/context-projection.js

@@ -0,0 +1,578 @@
+/**
+ * Host-only Session projection for Agent Team context management.
+ *
+ * One pure synchronous fold over a Member Session log derives every
+ * context-management fact the Host needs: pending rollover intent (a
+ * successful `context_rollover` call/result pair — under the legacy
+ * `new_context` name for Sessions recorded before the rename), explicit
+ * checkpoints (a
+ * successful `context_checkpoint` pair resolved by its containing `turn/end`),
+ * handoff/compaction boundaries, and quiet-continuation delivery state. The
+ * fold is the single authority for these facts — no second store, and callers
+ * never re-derive intent from raw events.
+ *
+ * A seeded child Session folds with `inheritedEventCount` respected: events
+ * inherited from the fork prefix are already resolved history, never fresh
+ * intent. The cold fold and the registered unit both start past the inherited
+ * cut, so an inherited historical rollover call can never schedule
+ * another transition in the child.
+ * @module @wowyuarm/dsh-agent-team/context-projection
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { AGENT_TEAM_PLUGIN_ID, continuationCheckpointRefOf, handoffOf, isAgentTeamContextSource, isCheckpointContinuationMessage } from "./context-source.js";
+/** Summary marker of the pre-compaction memory hint. */
+const PRE_COMPACTION_NOTICE_SUMMARY = 'Compaction is imminent; consider persisting key conclusions.';
+/** Team tool whose successful mutations are semantic timeline candidates. */
+const TEAM_CLAIM_TOOL_NAME = 'team_claim';
+/** Team tools whose successful Thread effects are semantic timeline candidates. */
+const TEAM_MESSAGE_TOOL_NAME = 'team_message';
+const TEAM_THREAD_TOOL_NAME = 'team_thread';
+/** Fixed action-category labels for effect boundaries (mirrors the claim label's shape). */
+const TEAM_MESSAGE_BOUNDARY_LABEL = 'Team message';
+const TEAM_ATTENTION_BOUNDARY_LABEL = 'Team attention change';
+const TEAM_CLAIM_BOUNDARY_LABEL = 'Team task claim change';
+/**
+ * Notice summaries that are pure reminders, never semantic Team facts: a
+ * progress nudge or a recovery instruction must not become a return anchor.
+ */
+const REMINDER_NOTICE_SUMMARIES = new Set(['Progress visibility reminder', 'Recovery: continue your interrupted work.']);
+/** Whether one notice summary is a pure reminder (never a semantic Team fact). */
+export function isReminderNoticeSummary(summary) {
+    return REMINDER_NOTICE_SUMMARIES.has(summary);
+}
+/** Stable tool names the projection recognizes. */
+export const CONTEXT_CHECKPOINT_TOOL_NAME = 'context_checkpoint';
+export const CONTEXT_ROLLOVER_TOOL_NAME = 'context_rollover';
+/**
+ * Legacy decoder name: the rollover tool was renamed `new_context` →
+ * `context_rollover`, and Sessions recorded before the rename still carry
+ * durable `new_context` call/result pairs. The projection keeps folding them
+ * — pending rollovers and crash recovery of existing Members depend on old
+ * events still resolving intent — but this is a log decoder, not a tool
+ * alias: no new call can carry the old name.
+ */
+export const NEW_CONTEXT_TOOL_NAME = 'new_context';
+/** Whether one recorded tool name is a rollover call under the current or the legacy name. */
+function isRolloverToolName(name) {
+    return name === CONTEXT_ROLLOVER_TOOL_NAME || name === NEW_CONTEXT_TOOL_NAME;
+}
+/** Whether one tool name can produce a Team-effect boundary from a successful call. */
+function isTeamEffectToolName(name) {
+    return name === TEAM_CLAIM_TOOL_NAME || name === TEAM_MESSAGE_TOOL_NAME || name === TEAM_THREAD_TOOL_NAME;
+}
+/** Whether one raw team_thread arguments string is an attention mutation (follow/unfollow). */
+function argumentsAreAttentionMutation(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return false;
+    const { action } = parsed;
+    return action === 'follow' || action === 'unfollow';
+}
+/** Whether one raw team_message arguments string is a Thread-effect attempt (start/reply — dm is not a Thread fact). */
+function argumentsAreMessageCommit(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return false;
+    const { action } = parsed;
+    return action === 'start' || action === 'reply';
+}
+const relatedFileSchema = z.object({ path: z.string().min(1), reason: z.string() }).strict();
+const checkpointRefSchema = z.string().regex(/^(context-checkpoint-[0-9a-f]{64}|team-boundary-[0-9a-f]{64})$/).transform(value => value);
+const openCallSchema = z.object({ callId: z.string().min(1), name: z.string(), arguments: z.string() }).strict();
+const carriedCandidateSchema = z.object({
+    message: z.any(),
+    surfacedTurn: z.number().int(),
+    consumed: z.boolean(),
+});
+const boundarySchema = z.object({
+    key: z.string().min(1),
+    source: z.enum(['team-boundary', 'handoff', 'compaction']),
+    label: z.string(),
+    seq: z.number().int().nonnegative(),
+    turn: z.number().int().nonnegative(),
+    turnEndSeq: z.number().int(),
+}).strict();
+const stateSchema = z.object({
+    checkpoints: z.array(z.object({
+        checkpointRef: checkpointRefSchema,
+        name: z.string(),
+        resultSeq: z.number().int().nonnegative(),
+        turn: z.number().int().nonnegative(),
+        turnEndSeq: z.number().int(),
+    }).strict()),
+    pending: z.object({
+        toolCallId: z.string().min(1),
+        resultSeq: z.number().int().nonnegative(),
+        turn: z.number().int().nonnegative(),
+        handoff: z.string(),
+        checkpointRef: checkpointRefSchema.optional(),
+        relatedFiles: z.array(relatedFileSchema),
+        turnEndSeq: z.number().int(),
+    }).strict().nullable(),
+    continuations: z.array(z.object({
+        checkpointRef: checkpointRefSchema,
+        deliveredSeq: z.number().int(),
+    }).strict()),
+    carriedCandidates: z.array(carriedCandidateSchema),
+    lastTurn: z.number().int().nonnegative(),
+    openCalls: z.array(openCallSchema),
+    boundaries: z.array(boundarySchema),
+    seenThreads: z.array(z.string()),
+    lastTurnEndSeq: z.number().int(),
+}).strict();
+/**
+ * Deterministic checkpoint ref from the recording session and tool call
+ * identity: a bounded, collision-resistant opaque token. Provider call ids
+ * are arbitrary-length free text that may repeat across generations and even
+ * collide between Sessions, so the ref derives from the SHA-256 of the exact
+ * `(sessionId, callId)` pair — same pair always reproduces the ref, any
+ * other pair is overwhelmingly unlikely to collide, and the token can never
+ * smuggle delimiters or unbounded content through a ref field.
+ */
+export function checkpointRefFor(sessionId, callId) {
+    return `context-checkpoint-${createHash('sha256').update(JSON.stringify([sessionId, callId])).digest('hex')}`;
+}
+/**
+ * Deterministic default-boundary ref for one delivered Team boundary: the
+ * same session-scoped hash shape as checkpoint refs, keyed on the boundary's
+ * anchoring event seq. Consecutive generations routinely repeat event seqs,
+ * so the Session identity must be part of the key or two generations'
+ * boundaries at the same seq collide — the timeline would silently drop the
+ * ancestor item and a `context_rollover` return would resolve the wrong boundary.
+ */
+export function boundaryRefFor(sessionId, seq) {
+    return `team-boundary-${createHash('sha256').update(JSON.stringify([sessionId, seq])).digest('hex')}`;
+}
+function emptyState() {
+    return { checkpoints: [], pending: null, continuations: [], carriedCandidates: [], lastTurn: 0, openCalls: [], boundaries: [], seenThreads: [], lastTurnEndSeq: -1 };
+}
+/**
+ * Cold-fold one immutable event log into the projection state. Events at or
+ * before `inheritedEventCount` belong to the fork prefix and are resolved
+ * history in this Session, so they never produce fresh intent. `sessionId` is
+ * the log's own Session identity — it keys checkpoint refs, so the same
+ * provider call id in two different Sessions produces two distinct refs.
+ */
+export function foldContextProjection(events, inheritedEventCount = 0, sessionId = '') {
+    let state = emptyState();
+    const inherited = Number(inheritedEventCount);
+    for (const event of events) {
+        if (event.seq < inherited)
+            continue;
+        state = applyContextEvent(state, event, sessionId);
+    }
+    return state;
+}
+/**
+ * The host-only projection unit; no wire view is published. The definition is
+ * a factory: each Session folds with its own identity so checkpoint refs
+ * derive from that Session's exact `(sessionId, callId)` pairs.
+ */
+export const agentTeamContextProjectionDefinition = (sessionId) => ({
+    key: 'agentTeamContext',
+    // v4: first-arrival boundary labels — notice-class boundaries label the
+    // Threads they first introduce (`First arrival: …`) instead of the
+    // notice's own summary, and the claim boundary label names its Task
+    // surface (`Team task claim change`). Labels are fold-time synthesized,
+    // not stored facts, so a persisted v3 row must not survive next to the
+    // new vocabulary: the ver mismatch refolds it from the full log.
+    stateVersion: 4,
+    stateSchema,
+    init: (_header, _inheritedEventCount) => emptyState(),
+    apply: (state, event) => applyContextEvent(state, event, sessionId),
+});
+/**
+ * Pure transition: previous state + one committed event → next state. Returns
+ * the same reference when the event is not this unit's.
+ */
+function applyContextEvent(state, event, sessionId) {
+    if (event.type === 'tool/call') {
+        if (!isRolloverToolName(event.data.name) && event.data.name !== CONTEXT_CHECKPOINT_TOOL_NAME && !isTeamEffectToolName(event.data.name))
+            return state;
+        // Only Team-effect calls that can produce a boundary are tracked; `list`
+        // and other non-mutations are not semantic timeline candidates.
+        if (event.data.name === TEAM_CLAIM_TOOL_NAME && !argumentsAreClaimMutation(event.data.arguments))
+            return state;
+        if (event.data.name === TEAM_THREAD_TOOL_NAME && !argumentsAreAttentionMutation(event.data.arguments))
+            return state;
+        if (event.data.name === TEAM_MESSAGE_TOOL_NAME && !argumentsAreMessageCommit(event.data.arguments))
+            return state;
+        return { ...state, openCalls: [...state.openCalls, { callId: event.data.callId, name: event.data.name, arguments: event.data.arguments }] };
+    }
+    if (event.type === 'tool/result') {
+        return applyToolResult(state, event.seq, event.data.turn, event.data.message, event.data.error !== undefined, sessionId, event.data.meta);
+    }
+    if (event.type === 'turn/end') {
+        return applyTurnEnd(state, event.seq, event.data.turn);
+    }
+    if (event.type === 'user/message') {
+        return applyUserMessage(state, event.seq, event.data, sessionId);
+    }
+    if (event.type === 'agent/inbox/spliced') {
+        return applyInboxSpliced(state, event.data);
+    }
+    if (event.type === 'assistant/message') {
+        return applyAssistantMessage(state, event);
+    }
+    if (event.type === 'turn/start') {
+        return event.data.turn === state.lastTurn ? state : { ...state, lastTurn: event.data.turn };
+    }
+    return state;
+}
+/**
+ * Structural timeline boundary from one delivered user message: a rollover
+ * handoff starts a generation; a compaction notice rewrites the visible
+ * surface. A structured Team notification is a boundary ONLY on the first
+ * arrival of each Thread's facts into this Session — the preserved
+ * "work just arrived" anchor; every later re-delivery of the same Thread is
+ * noise. Reminder notices (progress nudges, recovery instructions) never
+ * anchor. All anchor to the containing completed turn. Plain Human/agent
+ * prose and quiet checkpoint continuations are not boundaries.
+ */
+function boundaryFromUserMessage(sessionId, seq, message, seenThreads) {
+    const source = message.source;
+    if (handoffOf(message) !== undefined) {
+        return { key: `handoff:${seq}`, source: 'handoff', label: 'context handoff', seq, turn: -1, turnEndSeq: -1 };
+    }
+    if (source.kind !== 'plugin' || source.plugin !== AGENT_TEAM_PLUGIN_ID)
+        return undefined;
+    if (source.form === 'relay')
+        return undefined;
+    if (source.form === 'notice' && source.summary === PRE_COMPACTION_NOTICE_SUMMARY) {
+        return { key: `compaction:${seq}`, source: 'compaction', label: 'compaction notice', seq, turn: -1, turnEndSeq: -1 };
+    }
+    if (source.form === 'notice' && source.summary !== undefined && REMINDER_NOTICE_SUMMARIES.has(source.summary)) {
+        return { reminder: true };
+    }
+    // The Threads this delivery first introduces anchor the boundary; a
+    // delivery that introduces none (pure re-delivery) is noise.
+    const firstArrivals = threadsQuotedInMessage(message).filter(ref => !seenThreads.includes(ref));
+    if (firstArrivals.length === 0)
+        return undefined;
+    // The label states WHAT first arrived — the Thread refs this delivery
+    // introduced into the context — never the notice's own generic account
+    // (e.g. "unread work"): the timeline's decision surface needs the
+    // attribution before a checkpointRef pick, and it is only knowable here,
+    // at the fold, where first arrival is computed.
+    const label = `First arrival: ${firstArrivals.join(', ')}`;
+    return { key: boundaryRefFor(sessionId, seq), source: 'team-boundary', label, seq, turn: -1, turnEndSeq: -1, firstArrival: firstArrivals };
+}
+/** Thread refs structurally quoted in one delivered message body (`Thread: <ref>` lines). */
+function threadsQuotedInMessage(message) {
+    const refs = [];
+    const text = message.content.filter(block => block.type === 'text').map(block => block.text ?? '').join('\n');
+    for (const match of text.matchAll(/Thread: (thread:[0-9a-f-]{6,})/g)) {
+        if (!refs.includes(match[1]))
+            refs.push(match[1]);
+    }
+    return refs;
+}
+/**
+ * Fold one durable inbox splice. After a pending intent exists, every
+ * non-Team message inserted into the inbox is a carry candidate; the
+ * durable log is the truth, so a claim, removal, or cancel can never make
+ * the message vanish silently — only surfacing it onto the model-visible
+ * `user/message` surface consumes it.
+ */
+function applyInboxSpliced(state, data) {
+    if (state.pending === null || data.inserted.length === 0)
+        return state;
+    const fresh = data.inserted
+        .filter(message => !isTeamNotice(message))
+        .filter(message => !state.carriedCandidates.some(candidate => candidate.message.id === message.id))
+        .map(message => ({ message, surfacedTurn: -1, consumed: false }));
+    if (fresh.length === 0)
+        return state;
+    return { ...state, carriedCandidates: [...state.carriedCandidates, ...fresh] };
+}
+function applyToolResult(state, seq, turn, message, internalFailure, sessionId, meta) {
+    const block = message.content[0];
+    if (block === undefined || block.type !== 'tool-result')
+        return state;
+    // A landed result — success or failure — consumes its paired open call.
+    // Leaving a failed result's call open would dangle it forever, and a
+    // provider retry reusing the callId would pair its fresh success result
+    // with these stale arguments. An unpaired result (no matching open call)
+    // touches nothing.
+    const index = state.openCalls.findIndex(call => call.callId === block.toolCallId);
+    if (index === -1)
+        return state;
+    const recorded = state.openCalls[index];
+    const openCalls = state.openCalls.filter(call => call.callId !== block.toolCallId);
+    // A successful pair only: model-visible errors and internal failures carry
+    // neither checkpoint, rollover intent, nor an effect boundary — the
+    // failure-face contract also holds for a team_message whose presentation
+    // meta projection failed (that lands as a ToolOutputError result).
+    if (block.isError === true || internalFailure)
+        return { ...state, openCalls };
+    if (isRolloverToolName(recorded.name)) {
+        const parsed = parseRolloverArguments(recorded.arguments);
+        if (parsed === undefined)
+            return { ...state, openCalls };
+        // One pending intent per unresolved turn: a second successful call inside
+        // the SAME turn replaces nothing — the first owns the swap. A pending
+        // whose turn ended is the ready (or, after a restart, recoverable)
+        // intent, NOT spent: the coordinator's process lock normally rejects a
+        // later call before it can reach this fold. Only once that lock is gone
+        // (the transition failed or never ran) can a later-turn successful
+        // rollover replace the ended intent — the retry path that recovers the
+        // Member when the tool kept answering `scheduled` but no swap came.
+        if (state.pending !== null && state.pending.turnEndSeq === -1)
+            return { ...state, openCalls };
+        return { ...state, openCalls, pending: { ...parsed, toolCallId: recorded.callId, resultSeq: seq, turn, turnEndSeq: -1 } };
+    }
+    if (recorded.name === CONTEXT_CHECKPOINT_TOOL_NAME) {
+        const parsed = parseCheckpointArguments(recorded.arguments);
+        if (parsed === undefined)
+            return { ...state, openCalls };
+        const checkpointRef = checkpointRefFor(sessionId, block.toolCallId);
+        return {
+            ...state,
+            openCalls,
+            checkpoints: [...state.checkpoints, { checkpointRef, name: parsed.name, resultSeq: seq, turn, turnEndSeq: -1 }],
+        };
+    }
+    // Effect boundaries — the attribution matrix:
+    //   claim mutation → the Task ref from its call arguments (Task → Thread
+    //     resolution stays a query-time ledger concern);
+    //   team_message committed → reply/taskRef from args, start from the
+    //     structured presentation meta (`kind === 'committed'` guards every
+    //     typed rejection; no meta means no boundary — old logs refold without
+    //     start anchors by design, never by parsing render text);
+    //   team_thread follow/unfollow → the threadRef from its call arguments.
+    // A boundary without a resolvable ref is not produced.
+    const boundary = effectBoundaryFor(recorded, sessionId, seq, turn, meta);
+    if (boundary === undefined)
+        return { ...state, openCalls };
+    return { ...state, openCalls, boundaries: [...state.boundaries, boundary] };
+}
+/** The effect boundary one successful Team-effect call produces, if its attribution resolves. */
+function effectBoundaryFor(recorded, sessionId, seq, turn, meta) {
+    if (recorded.name === TEAM_CLAIM_TOOL_NAME) {
+        return { key: boundaryRefFor(sessionId, seq), source: 'team-boundary', label: TEAM_CLAIM_BOUNDARY_LABEL, seq, turn, turnEndSeq: -1 };
+    }
+    if (recorded.name === TEAM_THREAD_TOOL_NAME) {
+        return { key: boundaryRefFor(sessionId, seq), source: 'team-boundary', label: TEAM_ATTENTION_BOUNDARY_LABEL, seq, turn, turnEndSeq: -1 };
+    }
+    if (recorded.name === TEAM_MESSAGE_TOOL_NAME) {
+        // The structured meta projection is the single attribution source for a
+        // start (the Thread is born in the result); replies carry their ref in
+        // the call arguments already, but the committed guard is meta-side for
+        // every action — typed rejections are successful calls, not errors.
+        if (meta === undefined || typeof meta !== 'object' || meta === null)
+            return undefined;
+        const { kind, threadRef } = meta;
+        if (kind !== 'committed' || typeof threadRef !== 'string' || threadRef === '')
+            return undefined;
+        return { key: boundaryRefFor(sessionId, seq), source: 'team-boundary', label: TEAM_MESSAGE_BOUNDARY_LABEL, seq, turn, turnEndSeq: -1 };
+    }
+    return undefined;
+}
+function applyTurnEnd(state, seq, _turn) {
+    let changed = false;
+    const checkpoints = state.checkpoints.map(entry => {
+        if (entry.turnEndSeq !== -1)
+            return entry;
+        changed = true;
+        return { ...entry, turnEndSeq: seq };
+    });
+    let pending = state.pending;
+    if (pending !== null && pending.turnEndSeq === -1) {
+        pending = { ...pending, turnEndSeq: seq };
+        changed = true;
+    }
+    const boundaries = state.boundaries.map(entry => {
+        if (entry.turnEndSeq !== -1)
+            return entry;
+        changed = true;
+        return { ...entry, turnEndSeq: seq, turn: entry.turn === -1 ? _turn : entry.turn };
+    });
+    if (state.lastTurnEndSeq !== seq)
+        changed = true;
+    return changed ? { ...state, checkpoints, pending, boundaries, lastTurnEndSeq: seq } : state;
+}
+function applyUserMessage(state, seq, message, sessionId) {
+    let next = state;
+    // A surfaced candidate is NOT consumed yet: the loop appends user/message
+    // before the step runs, so cancellation can still land between them. Only
+    // a completed, uninterrupted assistant answer for the same turn proves the
+    // old generation handled it; anything else stays carried, so an aborted
+    // partial request re-delivers the input instead of silently dropping it.
+    const surfaced = next.carriedCandidates.some(candidate => !candidate.consumed && candidate.message.id === message.id);
+    if (surfaced) {
+        // The user/message event carries no turn field, but the projection folds
+        // in log order: the containing step/start preceded this message, and
+        // the fold tracks the current turn from turn/start. Candidates surface
+        // inside the turn the inbox claimed them for.
+        next = { ...next, carriedCandidates: next.carriedCandidates.map(candidate => candidate.message.id === message.id && !candidate.consumed ? { ...candidate, surfacedTurn: next.lastTurn } : candidate) };
+    }
+    // A structural boundary delivery (handoff start, first-arrival Team notice,
+    // compaction notice) becomes a timeline candidate anchored to the containing
+    // turn; it resolves when that turn ends. Threads the delivery first
+    // introduces join seenThreads so later re-deliveries produce nothing.
+    const boundary = boundaryFromUserMessage(sessionId, seq, message, next.seenThreads);
+    if (boundary !== undefined && !('reminder' in boundary)) {
+        if ('firstArrival' in boundary) {
+            const { firstArrival, ...timelineBoundary } = boundary;
+            next = {
+                ...next,
+                boundaries: [...next.boundaries, timelineBoundary],
+                seenThreads: [...next.seenThreads, ...firstArrival],
+            };
+        }
+        else {
+            next = { ...next, boundaries: [...next.boundaries, boundary] };
+        }
+    }
+    // The quiet continuation notice delivered for one checkpoint completes its
+    // delivery state; replay repair reads this to avoid re-scheduling it.
+    const continuation = continuationCheckpointRefOf(message);
+    if (continuation === undefined)
+        return next;
+    const checkpointRef = continuation;
+    const existing = next.continuations.find(entry => entry.checkpointRef === checkpointRef);
+    if (existing !== undefined) {
+        if (existing.deliveredSeq !== -1)
+            return next;
+        return { ...next, continuations: next.continuations.map(entry => entry === existing ? { ...entry, deliveredSeq: seq } : entry) };
+    }
+    return { ...next, continuations: [...next.continuations, { checkpointRef, deliveredSeq: seq }] };
+}
+/** A completed, uninterrupted assistant turn answers every candidate surfaced into it. */
+function applyAssistantMessage(state, event) {
+    if (state.carriedCandidates.length === 0 || event.data.interrupted === true)
+        return state;
+    let changed = false;
+    const carriedCandidates = state.carriedCandidates.map(candidate => {
+        if (candidate.consumed || candidate.surfacedTurn !== event.data.turn)
+            return candidate;
+        changed = true;
+        return { ...candidate, consumed: true };
+    });
+    return changed ? { ...state, carriedCandidates } : state;
+}
+/** The carried input one transition must deliver: unconsumed post-intent candidates, in queue order. */
+export function carriedInputOf(state) {
+    return state.carriedCandidates.filter(candidate => !candidate.consumed).map(candidate => candidate.message);
+}
+/**
+ * Whether one queued message is a Team-owned notice the rederived Inbox
+ * replaces. Handoff and continuation envelopes carry the same plugin
+ * attribution but are ordinary delivered context the new generation keeps, so
+ * they are excluded rather than dropped.
+ */
+function isTeamNotice(message) {
+    const source = message.source;
+    return source.kind === 'plugin' && source.plugin === AGENT_TEAM_PLUGIN_ID && !isAgentTeamContextSource(message);
+}
+/** Whether a quiet continuation for one checkpoint was already delivered in this Session. */
+export function continuationDelivered(state, checkpointRef) {
+    return state.continuations.some(entry => entry.checkpointRef === checkpointRef && entry.deliveredSeq !== -1);
+}
+/** Record that a continuation for one checkpoint is scheduled (delivery not yet seen). */
+export function withScheduledContinuation(state, checkpointRef) {
+    if (state.continuations.some(entry => entry.checkpointRef === checkpointRef))
+        return state;
+    return { ...state, continuations: [...state.continuations, { checkpointRef, deliveredSeq: -1 }] };
+}
+/** Whether one raw Team-claim arguments string is a mutation (not `list`). */
+function argumentsAreClaimMutation(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return false;
+    const { action } = parsed;
+    return action === 'claim' || action === 'done' || action === 'release';
+}
+function parseRolloverArguments(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const { handoff, checkpointRef, relatedFiles } = parsed;
+    if (typeof handoff !== 'string' || handoff.trim() === '')
+        return undefined;
+    if (checkpointRef !== undefined && typeof checkpointRef !== 'string')
+        return undefined;
+    if (relatedFiles !== undefined && !isRelatedFiles(relatedFiles))
+        return undefined;
+    return {
+        handoff,
+        ...(checkpointRef === undefined ? {} : { checkpointRef: checkpointRef }),
+        relatedFiles: relatedFiles === undefined ? [] : relatedFiles,
+    };
+}
+function parseCheckpointArguments(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const { name } = parsed;
+    if (typeof name !== 'string' || name.trim() === '')
+        return undefined;
+    return { name };
+}
+function isRelatedFiles(value) {
+    return Array.isArray(value) && value.every(file => typeof file === 'object' && file !== null
+        && typeof file.path === 'string' && typeof file.reason === 'string');
+}
+// Re-exported for callers that only want the predicate view of continuation
+// delivery without importing the source module's message constructors.
+export { isCheckpointContinuationMessage };
+/**
+ * Bounded structural timeline candidates, newest first: explicit checkpoints
+ * (resolved only), structural boundaries, then the current head. The Host
+ * prices retained/discarded tokens and applies restorability guards on top;
+ * this view is the single source of candidate anchors and labels.
+ */
+export function timelineCandidates(state, limit) {
+    const candidates = [];
+    for (const checkpoint of state.checkpoints) {
+        if (checkpoint.turnEndSeq === -1)
+            continue;
+        candidates.push({ ref: checkpoint.checkpointRef, label: checkpoint.name, source: 'agent', seq: checkpoint.resultSeq, turnEndSeq: checkpoint.turnEndSeq });
+    }
+    for (const boundary of state.boundaries) {
+        if (boundary.turnEndSeq === -1)
+            continue;
+        candidates.push({ ref: boundary.key, label: boundary.label, source: boundary.source, seq: boundary.seq, turnEndSeq: boundary.turnEndSeq });
+    }
+    if (state.lastTurnEndSeq !== -1) {
+        candidates.push({ ref: `head:${state.lastTurnEndSeq}`, label: 'current head', source: 'head', seq: state.lastTurnEndSeq, turnEndSeq: state.lastTurnEndSeq });
+    }
+    return candidates
+        .sort((a, b) => b.turnEndSeq - a.turnEndSeq || b.seq - a.seq)
+        .slice(0, Math.max(1, Math.trunc(limit)));
+}
+/** Find one resolved checkpoint entry by its stable ref, if it exists. */
+export function checkpointByRef(state, checkpointRef) {
+    return state.checkpoints.find(entry => entry.checkpointRef === checkpointRef && entry.turnEndSeq !== -1);
+}