@wowyuarm/dsh-agent-team 0.1.14-alpha.2 → 0.1.14

package/packages/tool-agent-team/lib/context-tools.js

@@ -8,10 +8,22 @@
  * order before the turn closes.
  * @module @wowyuarm/dsh-agent-team/context-tools
  */
+import { createHash } from 'node:crypto';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { member, service } from "./host-access.js";
 const MAX_HANDOFF_CHARS = 32 * 1024;
 const MAX_RELATED_FILES = 32;
+/**
+ * Short stable identifier for one timeline row: a digest of the anchor's own
+ * ref. Rows routinely share a label (`Team message` is a constant) and a price
+ * (the same completed turn prices both), so without it two distinct anchors
+ * read as one duplicated row. Deliberately NOT the ref and deliberately not
+ * actionable: a ref only means something on a restorable row, which prints it
+ * in full for `context_rollover`.
+ */
+function anchorId(checkpointRef) {
+    return createHash('sha256').update(checkpointRef).digest('hex').slice(0, 6);
+}
 const contextRollover = defineTool({
     name: 'context_rollover',
     description: 'context_rollover: end this context generation and continue as the same Team Member in a new one. Without checkpointRef the context starts fresh and empty, seeded only by your handoff — this is the default, cheapest path at context pressure, and the right choice for ordinary generation changes and pressure-driven handoffs. Omit checkpointRef unless you are deliberately returning to a restorable anchor you just selected from a context_timeline result: supply a checkpointRef only when that timeline listed it as restorable and you are citing its exact ref — never synthesize, guess, or reconstruct one; a fabricated ref rejects as a model-visible error. Write the handoff as one prose string covering: current objective and every active Thread/Claim; verified facts and evidence; inferences and unresolved conflicts; current external side effects and their verification state (files, git, jobs, browser state, remote calls); one explicit next step. A context change never rolls back any external effect — describe current state so the next generation can re-verify. Record anything worth keeping in your private memory/notes first. Collect or stop your background jobs before calling: a rollover is refused while jobs this Member owns are still running.',
@@ -108,7 +120,7 @@ const contextCheckpoint = defineTool({
 });
 const contextTimeline = defineTool({
     name: 'context_timeline',
-    description: 'Inspect the bounded structural timeline of this Member\'s context lineage: named checkpoints you recorded, Team boundaries (effect anchors: a committed team_message, a successful team_claim mutation, a follow/unfollow — rendered as `Team message`, `Team task claim change`, `Team attention change`; plus a Thread\'s first delivered notice, rendered as `First arrival: <refs>`), handoff and compaction boundaries, and the current head — across the current generation and its archived ancestors. Only the first delivery of a Thread\'s facts anchors; later re-deliveries and reminders produce no boundary. Returns approximate retained/discarded token estimates, current usage against the pressure budget, the Threads whose facts entered your context by each anchor, and which anchors are restorable. A Team boundary is a selectable default checkpoint exactly when it resolved at a completed turn and exactly one Thread is attributable to it; unattributable or multi-Thread boundaries state their reason. Structural only: no transcript content. A fresh context_rollover (no checkpointRef) never requires consulting this timeline first — call it directly. Use this tool only when you specifically intend a checkpointRef return: to pick the smallest sufficient ref, or to confirm that a fresh handoff is the better path when every anchor is marked non-restorable.',
+    description: 'Inspect the bounded structural timeline of this Member\'s context lineage: named checkpoints you recorded, Team boundaries (effect anchors: a committed team_message, a successful team_claim mutation, a follow/unfollow — rendered as `Team message`, `Team task claim change`, `Team attention change`; plus a Thread\'s first delivered notice, rendered as `First arrival: <refs>`), handoff and compaction boundaries, and the current head — across the current generation and its archived ancestors. Only the first delivery of a Thread\'s facts anchors; later re-deliveries and reminders produce no boundary. Returns approximate retained/discarded token estimates, current usage against the pressure budget, the Threads whose facts entered your context by each anchor, and which anchors are restorable. A Team boundary is a selectable default checkpoint exactly when the retained prefix through it stays inside one Thread and the return would shrink the working set below the handoff budget; a boundary spanning several Threads, or attributable to none, states its reason instead. Every row carries a short `anchor` id: it distinguishes rows that share a label and a price, and it is NOT a ref — only the `checkpointRef` printed on a restorable row may be cited to context_rollover. Structural only: no transcript content. A fresh context_rollover (no checkpointRef) never requires consulting this timeline first — call it directly. Use this tool only when you specifically intend a checkpointRef return: to pick the smallest sufficient ref, or to confirm that a fresh handoff is the better path when every anchor is marked non-restorable.',
     parameters: {
         limit: { type: 'number', description: 'Maximum number of items to return (default 12, at most 24).' },
     },
@@ -137,10 +149,12 @@ const contextTimeline = defineTool({
         // ref, label, source, size estimates, affected Threads, and
         // restorable/reason verdict, the model cannot pick a `checkpointRef` for
         // `context_rollover` — the summary line alone left the tool unusable for
-        // seeded returns. The Host bounds items (default 12, at most 24), so this
-        // list cannot grow unbounded. `incompleteFrom` states where and why the
-        // lineage walk stopped early, so history read up to that ancestor is
-        // known to be a truncation, not everything that exists.
+        // seeded returns. The short anchor id distinguishes rows that share a
+        // label and a price without ever printing a ref that is not usable. The
+        // Host bounds items (default 12, at most 24), so the list cannot grow
+        // unbounded. `incompleteFrom` states where and why the lineage walk
+        // stopped early, so history read up to that ancestor is known to be a
+        // truncation, not everything that exists.
         render: (_args, value) => {
             const lines = [`Context timeline: ${value.usageTokens} tokens used (handoff at ${value.handoffAt}, hard limit ${value.hardLimit}). ${value.items.length} item(s):`];
             for (const item of value.items) {
@@ -149,7 +163,7 @@ const contextTimeline = defineTool({
                 const restorable = item.restorable
                     ? `restorable — ref: ${item.checkpointRef}`
                     : `not restorable — ${item.reason ?? 'no reason given'}`;
-                lines.push(`- ${item.name} [source: ${item.source}] (${size}; ${threads}) — ${restorable}`);
+                lines.push(`- ${item.name} [source: ${item.source}; anchor ${anchorId(item.checkpointRef)}] (${size}; ${threads}) — ${restorable}`);
             }
             if (value.incompleteFrom !== undefined) {
                 lines.push(`History incomplete: the lineage walk stopped at Session ${value.incompleteFrom.sessionId} (${value.incompleteFrom.reason}); ancestors before it could not be read and are not reflected above.`);

package/packages/tool-agent-team/lib/index.js

@@ -1,4 +1,4 @@
-import { AGENT_TEAM_HUMAN_HANDLE, AgentTeamDmDeliveryError, markAgentTeamPreset } from '@wowyuarm/dsh-agent-team/host';
+import { AgentTeamDmDeliveryError, markAgentTeamPreset } from '@wowyuarm/dsh-agent-team/host';
 import { formatTeamTimestamp } from '@wowyuarm/dsh-agent-team/time-format';
 import { registerContextTools } from "./context-tools.js";
 import { service, workspaceOf, workspaceParam } from "./host-access.js";
@@ -626,7 +626,7 @@ const teamView = defineTool({
                 ...(participation.title === undefined ? {} : { title: participation.title }), default: participation.default })),
             channels: view.channels.map(channel => ({ channelRef: channel.channelRef, name: channel.name })),
             members: [
-                { memberId: view.humanMemberId, kind: 'human', handle: AGENT_TEAM_HUMAN_HANDLE, description: 'Human Team Member', presence: 'available' },
+                { memberId: view.humanMemberId, kind: 'human', handle: host.humanHandle(), description: 'Human Team Member', presence: 'available' },
                 ...host.members().filter(status => visibleMemberIds.has(status.member.memberId)).map(status => ({ memberId: status.member.memberId,
                     kind: 'agent', handle: status.member.handle, description: status.member.description, presence: status.presence })),
             ],

package/packages/tool-agent-team/lib/types/context-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-tools.d.ts","sourceRoot":"","sources":["../../src/context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAuKH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,CAIrG"}
+{"version":3,"file":"context-tools.d.ts","sourceRoot":"","sources":["../../src/context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsLH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,CAIrG"}

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

@@ -1,371 +0,0 @@
-/**
- * Context-management coordinator: the one deep module that turns a Member's
- * successful `context_rollover` tool result into its next private context
- * generation.
- *
- * Authority split (see docs/architecture.md):
- * - the Team ledger owns the Member→Session binding and rollover audit;
- * - the Session log projection owns intent, checkpoints, and delivery state;
- * - this coordinator owns only process locks and is always reconstructible.
- *
- * The coordinator reacts exclusively after the successful `tool/result` is
- * durably appended — never inside a tool body — so a render/finalize failure
- * can never outrun result durability. The actual swap waits for the
- * containing turn to end and the Agent to be idle, captures later input so no
- * old-generation model request opens, and then reuses the Member lifecycle:
- * commit rollover operation → dispose old Agent → archive old Session →
- * create/activate the new generation → deliver the handoff first.
- * @module @wowyuarm/dsh-agent-team/context-management
- */
-import { SessionId as SessionIdBrand } from '@deepseek-ai/dsh-session';
-import { createHash } from 'node:crypto';
-import { createCheckpointContinuationMessage, createHandoffMessage, isAgentTeamContextSource, isAgentTeamSource } from "./context-source.js";
-import { CONTEXT_CHECKPOINT_TOOL_NAME, CONTEXT_ROLLOVER_TOOL_NAME, continuationDelivered, foldContextProjection, } from "./context-projection.js";
-/** Stable summary of the one-shot rollover pressure notice (ticket 03 wires delivery). */
-export const CONTEXT_PRESSURE_NOTICE_SUMMARY = 'Context pressure: prepare a handoff';
-/**
- * Rebuild one Member's in-process intent from the projection's pending
- * rollover. Three call sites consume it — the live result, crash recovery
- * with the turn still open, and crash recovery past the turn end — and they
- * must agree field for field; this is the single definition of that list.
- */
-function intentFromPending(pending) {
-    return {
-        toolCallId: pending.toolCallId,
-        resultSeq: pending.resultSeq,
-        turn: pending.turn,
-        handoff: pending.handoff,
-        ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
-        relatedFiles: pending.relatedFiles,
-    };
-}
-export class ContextManagementCoordinator {
-    options;
-    members = new Map();
-    capturedInput = new Map();
-    /** Per-member latch for the in-process scheduling→delivery window. */
-    scheduledContinuations = new Set();
-    disposed = false;
-    constructor(options) {
-        this.options = options;
-    }
-    /** Whether one Member has a pending or in-flight rollover; tools use this to reject. */
-    isTransitioning(memberId) {
-        return this.members.has(memberId);
-    }
-    /**
-     * Root `session/event` observer for Member Sessions. The store's dispatch
-     * carrier is untagged, so the Host maps session ids to Members and calls
-     * this for every Member event. All reactions are gated on the projection
-     * state, which itself only records successful durable pairs.
-     */
-    onSessionEvent(memberId, agent, event) {
-        if (this.disposed)
-            return;
-        if (event.type === 'tool/result') {
-            this.onToolResult(memberId, agent, event);
-            return;
-        }
-        if (event.type === 'user/message') {
-            this.onUserMessage(memberId, agent, event);
-            return;
-        }
-        if (event.type === 'turn/end') {
-            this.onTurnEnd(memberId, agent);
-        }
-    }
-    /** Build the first handoff message of one generation; the lifecycle delivers it. */
-    handoffMessageFor(plan) {
-        return createHandoffMessage({
-            handoff: plan.handoff,
-            previousSessionId: plan.previousSessionId,
-            newSessionId: plan.newSessionId,
-            trigger: plan.trigger,
-            handoffEventSeq: plan.handoffEventSeq,
-            ...(plan.checkpointRef === undefined ? {} : { checkpointRef: plan.checkpointRef }),
-            ...(plan.relatedFiles.length === 0 ? {} : { relatedFiles: plan.relatedFiles }),
-        });
-    }
-    /**
-     * Whether one Agent's pending transition requires the admission gate: a
-     * pending rollover must stop old-generation turns from admitting queued
-     * input. The gate arms only for the old-generation Agent instance — the
-     * new generation activates mid-swap and must be free to consume the
-     * handoff and carried input immediately.
-     */
-    needsAdmissionGate(agent) {
-        const memberId = this.options.memberForAgent(agent)?.memberId;
-        if (memberId === undefined)
-            return false;
-        return this.members.get(memberId)?.agent === agent;
-    }
-    /**
-     * Capture the inbox messages queued for an old generation at its turn-stop
-     * boundary: non-Team input is preserved verbatim for delivery after the
-     * handoff; stale Team notices are dropped because the new generation
-     * rederives the Inbox from ledger facts. Removing them from the inbox lets
-     * the turn close cleanly instead of admitting another old-generation step.
-     */
-    captureQueuedInput(agent) {
-        const memberId = this.options.memberForAgent(agent)?.memberId;
-        if (memberId === undefined)
-            return [];
-        if (this.members.get(memberId)?.agent !== agent)
-            return [];
-        const removed = [...agent.inbox.nextStep, ...agent.inbox.nextTurn];
-        for (const message of removed)
-            agent.inbox.remove(message.id);
-        return this.captureInput(agent, removed);
-    }
-    /**
-     * Capture messages a racing pre-step already claimed from the inbox before
-     * rejecting that old-generation step. A rejected step's claimed message is
-     * otherwise neither discarded nor re-emitted, so the gate preserves it here.
-     */
-    captureClaimedInput(agent, messages) {
-        return this.captureInput(agent, messages);
-    }
-    captureInput(agent, messages) {
-        const memberId = this.options.memberForAgent(agent)?.memberId;
-        if (memberId === undefined)
-            return [];
-        if (this.members.get(memberId)?.agent !== agent)
-            return [];
-        const preserved = [];
-        for (const message of messages) {
-            if (this.isTeamNotice(message))
-                continue;
-            preserved.push(message);
-        }
-        if (preserved.length > 0)
-            this.capturedInput.set(memberId, [...(this.capturedInput.get(memberId) ?? []), ...preserved]);
-        return preserved;
-    }
-    /** Drain the captured input of one Member for delivery after the handoff. */
-    drainCapturedInput(memberId) {
-        const captured = this.capturedInput.get(memberId) ?? [];
-        this.capturedInput.delete(memberId);
-        return captured;
-    }
-    /**
-     * 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.
-     */
-    isTeamNotice(message) {
-        return isAgentTeamSource(message.source) && !isAgentTeamContextSource(message);
-    }
-    /** Drop one Member's bookkeeping; the Host calls this on dispose/removal. */
-    stopTracking(memberId) {
-        this.members.delete(memberId);
-        this.capturedInput.delete(memberId);
-    }
-    dispose() {
-        this.disposed = true;
-        this.members.clear();
-        this.capturedInput.clear();
-    }
-    onToolResult(memberId, agent, event) {
-        if (event.data.error !== undefined)
-            return;
-        const member = this.options.memberForAgent(agent);
-        if (member === undefined)
-            return;
-        const state = this.options.projectionForMember(memberId, member.sessionId);
-        if (state?.pending === null || state === undefined)
-            return;
-        const pending = state.pending;
-        // React only to the intent's own result landing durably, and only once.
-        if (pending.resultSeq !== event.seq)
-            return;
-        if (this.members.has(memberId))
-            return;
-        this.members.set(memberId, { agent, intent: intentFromPending(pending), turnEnded: false });
-    }
-    onUserMessage(memberId, _agent, event) {
-        // Quiet-continuation delivery bookkeeping is projection-owned; the
-        // coordinator only repairs a crash gap after restart, which the Host
-        // performs through repairContinuations during activation.
-        void memberId;
-        void event;
-    }
-    onTurnEnd(memberId, agent) {
-        // Checkpoint continuations first: a turn that resolved checkpoints owes
-        // each of them exactly one quiet next-turn follow-up. The projection's
-        // continuations state deduplicates across restarts; this in-memory latch
-        // closes the same-process window between scheduling and the delivery
-        // event landing in the log.
-        this.scheduleCheckpointContinuations(memberId, agent);
-        const transition = this.members.get(memberId);
-        if (transition === undefined || transition.turnEnded)
-            return;
-        const member = this.options.memberForAgent(agent);
-        if (member === undefined || transition.agent !== agent)
-            return;
-        transition.turnEnded = true;
-        // Wait for true idle (the turn-end event fires before the driver fully
-        // converges), then perform the swap off the session-event dispatch path.
-        void agent.whenIdle().then(() => {
-            if (this.disposed)
-                return;
-            const current = this.members.get(memberId);
-            if (current === undefined || current !== transition)
-                return;
-            if (this.options.agentForMember(memberId) !== agent)
-                return;
-            void this.performTransition(memberId, member, transition);
-        }, error => {
-            this.options.log(`context rollover idle wait failed: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
-            this.members.delete(memberId);
-        });
-    }
-    /**
-     * Claim the in-process latch for one resolved checkpoint continuation.
-     * Returns the latch key when this caller won it, or undefined when the
-     * checkpoint never concluded a turn, was already delivered durably, or is
-     * latched already. The caller releases the latch on its own failure path.
-     */
-    claimContinuationLatch(memberId, state, checkpoint) {
-        if (checkpoint.turnEndSeq === -1)
-            return undefined;
-        if (continuationDelivered(state, checkpoint.checkpointRef))
-            return undefined;
-        const latch = `${memberId}:${checkpoint.checkpointRef}`;
-        if (this.scheduledContinuations.has(latch))
-            return undefined;
-        this.scheduledContinuations.add(latch);
-        return latch;
-    }
-    /**
-     * Quiet follow-ups for checkpoints resolved by the turn that just ended.
-     * A successful `context_checkpoint` result concludes its turn; the Host
-     * continues work in the next turn with one host-generated notice. The
-     * projection folds delivery (the continuation user/message event), so a
-     * restart repairs a missing follow-up through repairContinuations without
-     * duplicating a delivered one; this live path latches per checkpoint in
-     * memory for the scheduling window.
-     */
-    scheduleCheckpointContinuations(memberId, agent) {
-        const member = this.options.memberForAgent(agent);
-        if (member === undefined)
-            return;
-        const state = this.options.projectionForMember(memberId, member.sessionId);
-        if (state === undefined)
-            return;
-        for (const checkpoint of state.checkpoints) {
-            const latch = this.claimContinuationLatch(memberId, state, checkpoint);
-            if (latch === undefined)
-                continue;
-            // The turn/end observer fires inside the session append publication
-            // (a synchronous followup would reenter the publishing append), and a
-            // next-turn message queued while the driver is still converging never
-            // latches a wake — the loop replays only maintenance/abort latches. So
-            // the continuation waits for true idle, then queues its own turn: the
-            // same discipline the rollover path uses.
-            void agent.whenIdle().then(() => {
-                if (this.disposed)
-                    return;
-                try {
-                    agent.followup(createCheckpointContinuationMessage(checkpoint.checkpointRef));
-                }
-                catch (error) {
-                    this.scheduledContinuations.delete(latch);
-                    this.options.log(`context continuation scheduling failed: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
-                }
-            }, () => {
-                this.scheduledContinuations.delete(latch);
-            });
-        }
-    }
-    async performTransition(memberId, member, transition) {
-        // Stable rollover identity derives from the previous Session and the
-        // successful tool call: a result seq is session-local and would collide
-        // across generations. Both inputs are unconstrained strings (provider
-        // call ids carry arbitrary lengths and characters; Session ids are
-        // caller-branded), so the pair is JSON-encoded — no delimiter can alias
-        // across the two fields — and hashed to a fixed-length url-safe hex
-        // digest instead of being embedded verbatim: the derived Session id and
-        // request id stay bounded and collision-resistant.
-        const stableKey = createHash('sha256').update(JSON.stringify([member.sessionId, transition.intent.toolCallId])).digest('hex');
-        const newSessionId = SessionIdBrand(`agent-team-rollover-${stableKey}`);
-        const plan = {
-            previousSessionId: member.sessionId,
-            newSessionId,
-            handoff: transition.intent.handoff,
-            handoffEventSeq: transition.intent.resultSeq,
-            trigger: 'model',
-            relatedFiles: transition.intent.relatedFiles,
-            ...(transition.intent.checkpointRef === undefined ? {} : { checkpointRef: transition.intent.checkpointRef }),
-            requestId: `agent-team:rollover:${stableKey}`,
-            carriedInput: this.drainCapturedInput(memberId),
-        };
-        const swap = this.options.executeTransition(memberId, plan);
-        transition.swapping = swap;
-        try {
-            await swap;
-            this.members.delete(memberId);
-        }
-        catch (error) {
-            this.options.log(`context rollover failed, leaving the previous generation recoverable: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
-            this.members.delete(memberId);
-        }
-    }
-    /**
-     * Crash-recovery hook the Host runs during Member activation: re-derive
-     * pending intent from the projection and finish a transition that a restart
-     * interrupted after the successful result was durable.
-     */
-    recoverPendingTransition(memberId, agent, sessionId) {
-        if (this.disposed || this.members.has(memberId))
-            return;
-        const state = this.options.projectionForMember(memberId, sessionId);
-        if (state?.pending === null || state === undefined)
-            return;
-        const pending = state.pending;
-        if (pending.turnEndSeq === -1) {
-            // The containing turn never ended durably; treat the intent as still
-            // waiting and observe the live events from here.
-            this.members.set(memberId, { agent, intent: intentFromPending(pending), turnEnded: false });
-            return;
-        }
-        // The turn already ended before the crash; the Agent is idle at
-        // activation, so the swap can proceed directly.
-        const member = this.options.memberForAgent(agent);
-        if (member === undefined)
-            return;
-        const transition = { agent, intent: intentFromPending(pending), turnEnded: true };
-        this.members.set(memberId, transition);
-        void this.performTransition(memberId, member, transition);
-    }
-    /**
-     * Crash-recovery for quiet continuations: schedule the follow-up for one
-     * resolved checkpoint exactly once when the result was durable but the
-     * delivery never landed. The projection's continuations state is the
-     * durable delivery record — a checkpoint whose delivery event exists in the
-     * log is never re-scheduled.
-     */
-    repairContinuations(agent, state) {
-        if (this.disposed)
-            return;
-        const memberId = this.options.memberForAgent(agent)?.memberId;
-        if (memberId === undefined)
-            return;
-        for (const checkpoint of state.checkpoints) {
-            const latch = this.claimContinuationLatch(memberId, state, checkpoint);
-            if (latch === undefined)
-                continue;
-            try {
-                agent.followup(createCheckpointContinuationMessage(checkpoint.checkpointRef));
-            }
-            catch (error) {
-                this.scheduledContinuations.delete(latch);
-                this.options.log(`context continuation repair failed: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-    }
-}
-/** Tool names this module owns; the preset validation requires all of them. */
-export const CONTEXT_TOOL_NAMES = Object.freeze([CONTEXT_CHECKPOINT_TOOL_NAME, CONTEXT_ROLLOVER_TOOL_NAME, 'context_timeline']);
-/** Re-exported for Host wiring: cold-fold helper for archived ancestors. */
-export { foldContextProjection };

package/packages/agent-team/lib/types/context-management.d.ts

@@ -1,154 +0,0 @@
-/**
- * Context-management coordinator: the one deep module that turns a Member's
- * successful `context_rollover` tool result into its next private context
- * generation.
- *
- * Authority split (see docs/architecture.md):
- * - the Team ledger owns the Member→Session binding and rollover audit;
- * - the Session log projection owns intent, checkpoints, and delivery state;
- * - this coordinator owns only process locks and is always reconstructible.
- *
- * The coordinator reacts exclusively after the successful `tool/result` is
- * durably appended — never inside a tool body — so a render/finalize failure
- * can never outrun result durability. The actual swap waits for the
- * containing turn to end and the Agent to be idle, captures later input so no
- * old-generation model request opens, and then reuses the Member lifecycle:
- * commit rollover operation → dispose old Agent → archive old Session →
- * create/activate the new generation → deliver the handoff first.
- * @module @wowyuarm/dsh-agent-team/context-management
- */
-import type { Agent } from '@deepseek-ai/dsh-agent';
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
-import type { UserMessage } from '@deepseek-ai/dsh-llm';
-import { foldContextProjection, type AgentTeamContextProjectionState } from './context-projection.ts';
-import type { AgentTeamAgentMember, AgentTeamMemberId, AgentTeamRolloverSessionRequest } from './types.ts';
-/** Stable summary of the one-shot rollover pressure notice (ticket 03 wires delivery). */
-export declare const CONTEXT_PRESSURE_NOTICE_SUMMARY = "Context pressure: prepare a handoff";
-export interface ContextManagementCoordinatorOptions {
-    /** Resolve the live Agent of one Member; undefined leaves intent parked. */
-    readonly agentForMember: (memberId: AgentTeamMemberId) => Agent | undefined;
-    /** Resolve the durable Member of one live Agent. */
-    readonly memberForAgent: (agent: Agent) => AgentTeamAgentMember | undefined;
-    /** Fold one Member Session's projection state from its durable events. */
-    readonly projectionForMember: (memberId: AgentTeamMemberId, sessionId: SessionId) => AgentTeamContextProjectionState | undefined;
-    /**
-     * Execute one prepared Member generation swap at a true idle boundary:
-     * commit, dispose, archive, create/activate, deliver the handoff first,
-     * then carried input and the rederived Inbox. Returns once the Member runs
-     * its new generation.
-     */
-    readonly executeTransition: (memberId: AgentTeamMemberId, plan: TransitionPlan) => Promise<void>;
-    /** Log one coordinator diagnostic. */
-    readonly log: (message: string) => void;
-}
-/** Everything the lifecycle needs to perform one rollover. */
-export interface TransitionPlan {
-    readonly previousSessionId: SessionId;
-    readonly newSessionId: SessionId;
-    readonly handoff: string;
-    readonly handoffEventSeq: number;
-    readonly trigger: 'model' | 'pressure';
-    readonly relatedFiles: readonly {
-        readonly path: string;
-        readonly reason: string;
-    }[];
-    readonly checkpointRef?: string | undefined;
-    readonly requestId: AgentTeamRolloverSessionRequest['requestId'];
-    /** Non-Team input that arrived during the transition, delivered after the handoff. */
-    readonly carriedInput: readonly UserMessage[];
-}
-export declare class ContextManagementCoordinator {
-    private readonly options;
-    private readonly members;
-    private readonly capturedInput;
-    /** Per-member latch for the in-process scheduling→delivery window. */
-    private readonly scheduledContinuations;
-    private disposed;
-    constructor(options: ContextManagementCoordinatorOptions);
-    /** Whether one Member has a pending or in-flight rollover; tools use this to reject. */
-    isTransitioning(memberId: AgentTeamMemberId): boolean;
-    /**
-     * Root `session/event` observer for Member Sessions. The store's dispatch
-     * carrier is untagged, so the Host maps session ids to Members and calls
-     * this for every Member event. All reactions are gated on the projection
-     * state, which itself only records successful durable pairs.
-     */
-    onSessionEvent(memberId: AgentTeamMemberId, agent: Agent, event: SessionEvent): void;
-    /** Build the first handoff message of one generation; the lifecycle delivers it. */
-    handoffMessageFor(plan: TransitionPlan): UserMessage;
-    /**
-     * Whether one Agent's pending transition requires the admission gate: a
-     * pending rollover must stop old-generation turns from admitting queued
-     * input. The gate arms only for the old-generation Agent instance — the
-     * new generation activates mid-swap and must be free to consume the
-     * handoff and carried input immediately.
-     */
-    needsAdmissionGate(agent: Agent): boolean;
-    /**
-     * Capture the inbox messages queued for an old generation at its turn-stop
-     * boundary: non-Team input is preserved verbatim for delivery after the
-     * handoff; stale Team notices are dropped because the new generation
-     * rederives the Inbox from ledger facts. Removing them from the inbox lets
-     * the turn close cleanly instead of admitting another old-generation step.
-     */
-    captureQueuedInput(agent: Agent): readonly UserMessage[];
-    /**
-     * Capture messages a racing pre-step already claimed from the inbox before
-     * rejecting that old-generation step. A rejected step's claimed message is
-     * otherwise neither discarded nor re-emitted, so the gate preserves it here.
-     */
-    captureClaimedInput(agent: Agent, messages: readonly UserMessage[]): readonly UserMessage[];
-    private captureInput;
-    /** Drain the captured input of one Member for delivery after the handoff. */
-    drainCapturedInput(memberId: AgentTeamMemberId): readonly UserMessage[];
-    /**
-     * 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.
-     */
-    private isTeamNotice;
-    /** Drop one Member's bookkeeping; the Host calls this on dispose/removal. */
-    stopTracking(memberId: AgentTeamMemberId): void;
-    dispose(): void;
-    private onToolResult;
-    private onUserMessage;
-    private onTurnEnd;
-    /**
-     * Claim the in-process latch for one resolved checkpoint continuation.
-     * Returns the latch key when this caller won it, or undefined when the
-     * checkpoint never concluded a turn, was already delivered durably, or is
-     * latched already. The caller releases the latch on its own failure path.
-     */
-    private claimContinuationLatch;
-    /**
-     * Quiet follow-ups for checkpoints resolved by the turn that just ended.
-     * A successful `context_checkpoint` result concludes its turn; the Host
-     * continues work in the next turn with one host-generated notice. The
-     * projection folds delivery (the continuation user/message event), so a
-     * restart repairs a missing follow-up through repairContinuations without
-     * duplicating a delivered one; this live path latches per checkpoint in
-     * memory for the scheduling window.
-     */
-    private scheduleCheckpointContinuations;
-    private performTransition;
-    /**
-     * Crash-recovery hook the Host runs during Member activation: re-derive
-     * pending intent from the projection and finish a transition that a restart
-     * interrupted after the successful result was durable.
-     */
-    recoverPendingTransition(memberId: AgentTeamMemberId, agent: Agent, sessionId: SessionId): void;
-    /**
-     * Crash-recovery for quiet continuations: schedule the follow-up for one
-     * resolved checkpoint exactly once when the result was durable but the
-     * delivery never landed. The projection's continuations state is the
-     * durable delivery record — a checkpoint whose delivery event exists in the
-     * log is never re-scheduled.
-     */
-    repairContinuations(agent: Agent, state: AgentTeamContextProjectionState): void;
-}
-/** Tool names this module owns; the preset validation requires all of them. */
-export declare const CONTEXT_TOOL_NAMES: readonly ["context_checkpoint", "context_rollover", "context_timeline"];
-/** Re-exported for Host wiring: cold-fold helper for archived ancestors. */
-export { foldContextProjection };
-//# sourceMappingURL=context-management.d.ts.map

package/packages/agent-team/lib/types/context-management.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-management.d.ts","sourceRoot":"","sources":["../../src/context-management.ts"],"names":[],"mappings":"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"}

package/packages/client-agent-team/lib/types/client/task-refs.d.ts

@@ -1,31 +0,0 @@
-import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
-import type { AgentTeamChannelRef, AgentTeamResolveTaskRefsRequest, AgentTeamResolveTaskRefsResult, AgentTeamTaskRef, AgentTeamThreadRef } from '@wowyuarm/dsh-agent-team/types';
-/** Navigation facts for one branded Task ref, resolved once per session. */
-export interface ResolvedTaskRef {
-    readonly taskRef: AgentTeamTaskRef;
-    readonly channelRef: AgentTeamChannelRef;
-    readonly threadRef: AgentTeamThreadRef;
-    readonly taskNumber: number;
-}
-/** React binding: re-renders the caller when any ref resolution lands. */
-export declare const useResolvedTaskRefVersion: () => number;
-export declare const cachedResolvedTaskRef: (taskRef: AgentTeamTaskRef) => ResolvedTaskRef | undefined;
-/** Store one resolution (click path) and wake every rendered link. */
-export declare const rememberResolvedTaskRef: (entry: ResolvedTaskRef) => void;
-/**
- * Click-path Host lookup: remember every resolved entry and hand them back
- * for immediate navigation. The Host keeps `resolved` in the same order as
- * the input `taskRefs` (one entry per resolvable input, unknowns omitted);
- * the pairing walk below relies on that contract, so it must be preserved
- * together with this implementation.
- */
-export declare const hostTaskRefLookup: (resolveTaskRefs: (request: AgentTeamResolveTaskRefsRequest) => Promise<RemoteResult<AgentTeamResolveTaskRefsResult>>, workspaceId: AgentTeamResolveTaskRefsRequest["workspaceId"]) => ((taskRefs: readonly AgentTeamTaskRef[]) => Promise<readonly ResolvedTaskRef[]>);
-/** Resolve one Task ref through the Host and jump to its home Channel Thread. */
-export declare const jumpToTaskThread: (resolveTaskRefs: (request: AgentTeamResolveTaskRefsRequest) => Promise<RemoteResult<AgentTeamResolveTaskRefsResult>>, workspaceId: AgentTeamResolveTaskRefsRequest["workspaceId"], taskRef: AgentTeamTaskRef, selectThread: (threadRef: AgentTeamThreadRef, channelRef?: AgentTeamChannelRef, taskRef?: AgentTeamTaskRef, taskNumber?: number) => void) => void;
-/**
- * Batch-resolve unknown refs through the Host lookup. Concurrent callers
- * deduplicate through the pending set; failures just clear the pending mark
- * so a later interaction can retry.
- */
-export declare const resolveUnknownTaskRefs: (refs: readonly AgentTeamTaskRef[], lookup: (taskRefs: readonly AgentTeamTaskRef[]) => Promise<readonly ResolvedTaskRef[]>) => Promise<void>;
-//# sourceMappingURL=task-refs.d.ts.map

package/packages/client-agent-team/lib/types/client/task-refs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"task-refs.d.ts","sourceRoot":"","sources":["../../../src/client/task-refs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AACpE,OAAO,KAAK,EACV,mBAAmB,EAAE,+BAA+B,EAAE,8BAA8B,EAAE,gBAAgB,EAAE,kBAAkB,EAC3H,MAAM,gCAAgC,CAAA;AAEvC,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAA;IACxC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAwBD,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,QAAO,MAAmE,CAAA;AAEhH,eAAO,MAAM,qBAAqB,GAAI,SAAS,gBAAgB,KAAG,eAAe,GAAG,SAAkC,CAAA;AAEtH,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,GAAI,OAAO,eAAe,KAAG,IAIhE,CAAA;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,iBAAiB,CAAC,OAAO,EAAE,+BAA+B,KAAK,OAAO,CAAC,YAAY,CAAC,8BAA8B,CAAC,CAAC,EACpH,aAAa,+BAA+B,CAAC,aAAa,CAAC,KAC1D,CAAC,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,KAAK,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAiB/E,CAAA;AAEH,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,GAC3B,iBAAiB,CAAC,OAAO,EAAE,+BAA+B,KAAK,OAAO,CAAC,YAAY,CAAC,8BAA8B,CAAC,CAAC,EACpH,aAAa,+BAA+B,CAAC,aAAa,CAAC,EAC3D,SAAS,gBAAgB,EACzB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,UAAU,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,IAAI,KACvI,IAMF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,SAAS,gBAAgB,EAAE,EACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,KAAK,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,KACrF,OAAO,CAAC,IAAI,CAmBd,CAAA"}