@desplega.ai/agent-swarm 2.5.3 → 2.6.0

package/src/prompts/context-bound-note.ts

@@ -0,0 +1,48 @@
+// Worker-side hooks do not load base-prompt, which normally registers these
+// code-default templates.
+import "./session-templates.ts";
+import { resolveTemplateAsync, resolveTemplateFromCode } from "./resolver.ts";
+
+const CONTEXT_BOUND_NOTE_TEMPLATE = "system.agent.context.bound_note";
+
+/**
+ * `contextShare` for the note: " (21% of the 1,000,000-token window)", or ""
+ * when the model's window is unknown. Never a percent of the 200k fallback.
+ */
+function contextShare(contextTokens: number, model: string | undefined): string {
+  if (!model) return "";
+  try {
+    // Lazy and synchronous: the catalog snapshot is large and the Claude hook
+    // process loads this module on every tool call, but renders the note at
+    // most once. Sync so in-process sessions render no later than before.
+    const { clampContextPercent, getKnownContextWindowSize } =
+      require("../utils/context-window.ts") as typeof import("../utils/context-window.ts");
+    const window = getKnownContextWindowSize(model);
+    const percent = clampContextPercent(contextTokens, window);
+    if (!window || percent === null) return "";
+    return ` (${Math.round(percent)}% of the ${window.toLocaleString("en-US")}-token window)`;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Render the one-time context-bound note. `model` is the session's model, for
+ * the window share. Returns "" when an operator disabled the template; falls
+ * back to the code default if resolution fails.
+ */
+export async function renderContextBoundNote(
+  contextTokens: number,
+  model?: string,
+): Promise<string> {
+  const variables = {
+    contextTokens: Math.round(contextTokens).toLocaleString("en-US"),
+    contextShare: contextShare(contextTokens, model),
+  };
+  try {
+    const result = await resolveTemplateAsync(CONTEXT_BOUND_NOTE_TEMPLATE, variables);
+    return result.skipped ? "" : result.text;
+  } catch {
+    return resolveTemplateFromCode(CONTEXT_BOUND_NOTE_TEMPLATE, variables).text;
+  }
+}

package/src/prompts/session-templates.ts

@@ -202,7 +202,7 @@ agent-fs is the shared drive between agents and people. Documents (reports, dige
 Pages: only for polished artifacts shared with a wider audience or explicitly requested; see \`pages\` skill.
 A tool a person will use, with data and actions: build an app. See the \`apps\` skill.
 Link env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API, \`AGENT_FS_LIVE_URL\` for files. Report missing variables.
-For a file anyone outside the swarm opens, use an \`agent-fs share-create\` link; \`AGENT_FS_LIVE_URL\` links are for signed-in teammates.
+Give people the live app link \`\${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>\`. Make an \`agent-fs share-create\` link only when the requester asks for one or the reader has no agent-fs login.
 `,
   variables: [],
   category: "system",
@@ -353,6 +353,30 @@ Task: {{task}}{{progressLine}}
   category: "system",
 });
 
+/**
+ * One-time note injected into a worker session once its latest main-thread
+ * request crosses CONTEXT_BOUND_NOTE_TOKENS (`renderContextBoundNote`, via
+ * `src/hooks/context-bound-note.ts`).
+ */
+registerTemplate({
+  eventType: "system.agent.context.bound_note",
+  header: "",
+  defaultBody:
+    "Context is {{contextTokens}} tokens{{contextShare}}. Keep this task bounded: finish the current step, store-progress, and complete or defer instead of starting new exploration.",
+  variables: [
+    {
+      name: "contextTokens",
+      description: "Prompt size of the latest request (input + cache read + cache write tokens)",
+    },
+    {
+      name: "contextShare",
+      description:
+        'How full the model\'s context window is, e.g. " (21% of the 1,000,000-token window)". Empty when the window is unknown',
+    },
+  ],
+  category: "system",
+});
+
 /**
  * First message of a cursor session on the first-message path. Cursor keeps
  * its own system prompt there, so the swarm's rides on top of the task prompt.

package/src/providers/acp-targets.ts

@@ -359,7 +359,7 @@ const copilotTargetProfile: AcpTargetProfile = {
   },
 };
 
-/** Qwen Code's `--auth-type` choices (0.26.0). `qwen-oauth` needs a browser, so it is left out. */
+/** Qwen Code's `--auth-type` choices (0.26.1). `qwen-oauth` needs a browser, so it is left out. */
 const QWEN_AUTH_TYPES = ["openai", "openai-responses", "anthropic", "gemini", "vertex-ai"] as const;
 
 // Qwen Code is a Gemini CLI fork: QWEN_SYSTEM_MD replaces its built-in prompt

package/src/providers/amp-adapter.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "nod
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { contextBoundNoteThreshold, createContextBoundNote } from "../hooks/context-bound-note";
 import {
   type AmpMode,
   type AmpModelSelection,
@@ -44,7 +45,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1792756861-g6187a2";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1792929650-g000512";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";
@@ -442,6 +443,8 @@ interface QueuedSteer {
    * answer from the model that received it settles the steer.
    */
   receiver?: string | null;
+  /** The swarm's own note: rides a tool result or is dropped, never replayed as a new turn. */
+  internal?: boolean;
   resolve: (result: SteerDeliveryResult) => void;
 }
 
@@ -486,6 +489,8 @@ class AmpSession implements ProviderSession {
   private steeringSeq = 0;
   /** Accepted steering not yet consumed, by inbox file name. Each settles exactly once. */
   private steers = new Map<string, QueuedSteer>();
+  /** Fed each top-level request's prompt size; queues the one-time context-bound note. */
+  private readonly observeContextBound: (contextTokens: number | undefined) => Promise<void>;
 
   constructor(
     private proc: Bun.Subprocess<"pipe", "pipe", "pipe">,
@@ -523,6 +528,15 @@ class AmpSession implements ProviderSession {
         });
       }
     };
+    // The plugin's `tool.result` hook carries queued steering mid-turn; a note
+    // no tool result took is dropped at turn end (`onTurnEnd`).
+    this.observeContextBound = createContextBoundNote({
+      threshold: contextBoundNoteThreshold(run.env),
+      // A mode names no model in advance, so only a pinned model gets a window share.
+      model: () => run.selection.pin,
+      canDeliver: () => !this.inputClosed && !this.aborted,
+      inject: (note) => this.queueSteering(note, true),
+    });
     this.completion = this.runSession(prompt);
   }
 
@@ -553,13 +567,13 @@ class AmpSession implements ProviderSession {
    * check and the rename, no turn end can drain the inbox and close input, so
    * a message is either visible to the next drain or refused.
    */
-  private queueSteering(text: string): Promise<SteerDeliveryResult> {
+  private queueSteering(text: string, internal = false): Promise<SteerDeliveryResult> {
     const name = `${String(++this.steeringSeq).padStart(6, "0")}.json`;
     const temp = join(this.run.steeringInbox, `.${name}.tmp`);
     writeFileSync(temp, JSON.stringify(text), { mode: 0o600 });
     renameSync(temp, join(this.run.steeringInbox, name));
     return new Promise((resolve) => {
-      this.steers.set(name, { text, via: "inbox", resolve });
+      this.steers.set(name, { text, via: "inbox", internal, resolve });
     });
   }
 
@@ -631,8 +645,8 @@ class AmpSession implements ProviderSession {
    * Claim the messages no tool result carried, with the plugin's rename
    * protocol (`.json -> .stdin`). They stay open until Amp echoes them.
    */
-  private takeSteering(): { name: string; text: string }[] {
-    const taken: { name: string; text: string }[] = [];
+  private takeSteering(): { name: string; text: string; internal?: boolean }[] {
+    const taken: { name: string; text: string; internal?: boolean }[] = [];
     for (const [name, steer] of [...this.steers].sort(([a], [b]) => a.localeCompare(b))) {
       if (steer.via !== "inbox") continue;
       try {
@@ -641,7 +655,7 @@ class AmpSession implements ProviderSession {
         continue; // The plugin took it.
       }
       steer.via = "stdin";
-      taken.push({ name, text: steer.text });
+      taken.push({ name, text: steer.text, internal: steer.internal });
     }
     return taken;
   }
@@ -704,11 +718,16 @@ class AmpSession implements ProviderSession {
   /**
    * A top-level assistant message with no tool call ends the turn. Steering
    * that arrived after the last tool result reached no hook, so it goes in as
-   * the next user message and starts another turn.
+   * the next user message and starts another turn. The swarm's own note is
+   * withdrawn instead: it must not start a turn.
    */
   private onTurnEnd(): void {
     if (this.inputClosed) return;
-    for (const { name, text } of this.takeSteering()) {
+    for (const { name, text, internal } of this.takeSteering()) {
+      if (internal) {
+        this.settleSteer(name, { delivered: false, reason: "no tool result carried the note" });
+        continue;
+      }
       this.writeInput(text).catch((error) => {
         this.settleSteer(name, {
           delivered: false,
@@ -817,6 +836,9 @@ class AmpSession implements ProviderSession {
       });
       // The window is not in the stream; the final snapshot after the export carries it.
       if (used > 0) this.emitContext(used, output, null);
+      // Only when a tool result follows to carry the note; the turn end drops
+      // a note no tool result carried.
+      if (topLevel && calledTool) void this.observeContextBound(input + cacheRead + cacheCreation);
     }
     if (topLevel && !calledTool && message.stop_reason !== "tool_use") this.onTurnEnd();
   }

package/src/providers/claude-adapter.ts

@@ -17,6 +17,11 @@ import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { deriveDefaultRoute, routeCredentialStatus, routeUnsetEnv } from "@desplega/model-routing";
 import { type Span, trace } from "@opentelemetry/api";
+import {
+  contextBoundNoteMarkerPath,
+  contextStatePath,
+  recordContextState,
+} from "../hooks/context-bound-note";
 import {
   type RunStopHookSessionSummaryOpts,
   runStopHookSessionSummarySubprocess,
@@ -130,10 +135,17 @@ async function writeTaskFile(key: string | number, data: TaskFileData): Promise<
 }
 
 export async function cleanupTaskFile(key: string | number): Promise<void> {
-  try {
-    await unlink(getTaskFilePath(key));
-  } catch {
-    // File might already be deleted or never created
+  const taskFilePath = getTaskFilePath(key);
+  for (const path of [
+    taskFilePath,
+    contextStatePath(taskFilePath),
+    contextBoundNoteMarkerPath(taskFilePath),
+  ]) {
+    try {
+      await unlink(path);
+    } catch {
+      // File might already be deleted or never created
+    }
   }
 }
 
@@ -909,6 +921,8 @@ class ClaudeSession implements ProviderSession {
   private appliedReasoningEffort: ReasoningEffort | null;
   /** Last non-empty assistant text seen; surfaced as ProviderResult.output — same pattern as pi-mono/claude-managed. */
   private lastAssistantText = "";
+  /** Last value written to the context state file read by the context-bound note hook. */
+  private lastContextTokens: number | undefined;
   /** Per-session stream-json transcript used by the parent-owned session summarizer. */
   private transcript: string[];
   /** Keeps the session heartbeat fresh while Claude idles on background tasks. */
@@ -1263,6 +1277,17 @@ class ClaudeSession implements ProviderSession {
       if (normalized.contextWindowSize) this.contextWindowSize = normalized.contextWindowSize;
       if (normalized.cost) setCost(normalized.cost);
       if (normalized.assistantText) this.lastAssistantText = normalized.assistantText;
+      if (
+        normalized.requestContextTokens !== undefined &&
+        normalized.requestContextTokens !== this.lastContextTokens
+      ) {
+        this.lastContextTokens = normalized.requestContextTokens;
+        recordContextState(
+          getTaskFilePath(this.taskFileKey),
+          normalized.requestContextTokens,
+          this.model,
+        );
+      }
       this.transcript.push(...normalized.transcriptEntries);
       for (const event of normalized.events) this.emit(event);
 
@@ -1420,7 +1445,11 @@ export class ClaudeAdapter implements ProviderAdapter {
     // (headless) or block on the trust dialog (tmux), so seed trust for every session.
     if (isEnvFlagEnabled("CLAUDE_TRUST_PRESEED", true, sourceEnv)) {
       try {
-        await preseedClaudeTrustDialog(await resolveClaudeTrustDirs(config.cwd));
+        // Seed the ~/.claude.json the CLI reads: its HOME comes from the session env.
+        await preseedClaudeTrustDialog(
+          await resolveClaudeTrustDirs(config.cwd),
+          sourceEnv.HOME || undefined,
+        );
       } catch (err) {
         console.warn(
           `\x1b[33m[claude]\x1b[0m ${scrubSecrets(`Failed to pre-seed trust for ${config.cwd}: ${err}`)}`,

package/src/providers/claude-managed-adapter.ts

@@ -56,6 +56,7 @@ import type {
   BetaManagedAgentsSessionEvent as SessionEvent,
 } from "@anthropic-ai/sdk/resources/beta/sessions";
 
+import { contextBoundNoteThreshold, createContextBoundNote } from "../hooks/context-bound-note";
 import { checkToolLoop } from "../hooks/tool-loop-detection";
 import {
   CONTEXT_FORMULA,
@@ -63,6 +64,7 @@ import {
   computeContextUsedUnified,
   getContextWindowSize,
 } from "../utils/context-window";
+import { selectCredential } from "../utils/credentials";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { computeClaudeManagedCostUsd } from "./claude-managed-models";
 import { getRuntimeFeePerHour } from "./claude-managed-pricing";
@@ -268,6 +270,12 @@ class ClaudeManagedSession implements ProviderSession {
   private readonly taskId: string | null;
   private aborted = false;
   private settled = false;
+  /** Prompt size of the latest model request: input + cache read + cache write. */
+  private lastRequestContextTokens: number | undefined;
+  /** Fed the latest request's prompt size on each tool call; steers the one-time context-bound note. */
+  private readonly observeContextBound: (contextTokens: number | undefined) => Promise<void>;
+  /** Tool calls the stream started and has not returned a result for. */
+  private readonly openToolCalls = new Set<string>();
 
   constructor(
     client: ManagedAgentsClient,
@@ -286,6 +294,14 @@ class ClaudeManagedSession implements ProviderSession {
     this.completionPromise = new Promise<ProviderResult>((resolve) => {
       this.resolveCompletion = resolve;
     });
+    this.observeContextBound = createContextBoundNote({
+      threshold: contextBoundNoteThreshold(config.env ?? process.env),
+      model: () => this.cost.model,
+      // A message with no tool call left to return, or after idle or abort,
+      // would start another turn.
+      canDeliver: () => !this.settled && !this.aborted && this.openToolCalls.size > 0,
+      inject: (note) => this.deliverSteering({ mode: "steer", text: note }),
+    });
 
     // Phase 5: adapter-side swarm hooks. Lower-latency cancellation poll,
     // tool-loop detection (the handler also calls `checkToolLoop` on
@@ -497,6 +513,11 @@ class ClaudeManagedSession implements ProviderSession {
       case "agent.tool_use": {
         const tu = event as BetaManagedAgentsAgentToolUseEvent;
         this.runToolLoopCheck(tu.name, tu.input);
+        // Only on tool calls: a message after the final reply would start another
+        // turn. The stream can send the call before its request ends, so this may
+        // read the previous request: at most one request late.
+        this.openToolCalls.add(tu.id);
+        void this.observeContextBound(this.lastRequestContextTokens);
         this.emit({
           type: "tool_start",
           toolCallId: tu.id,
@@ -509,6 +530,8 @@ class ClaudeManagedSession implements ProviderSession {
         const tu = event as BetaManagedAgentsAgentMCPToolUseEvent;
         const fqToolName = `${tu.mcp_server_name}:${tu.name}`;
         this.runToolLoopCheck(fqToolName, tu.input);
+        this.openToolCalls.add(tu.id);
+        void this.observeContextBound(this.lastRequestContextTokens);
         this.emit({
           type: "tool_start",
           toolCallId: tu.id,
@@ -519,6 +542,7 @@ class ClaudeManagedSession implements ProviderSession {
       }
       case "agent.tool_result": {
         const tr = event as BetaManagedAgentsAgentToolResultEvent;
+        this.openToolCalls.delete(tr.tool_use_id);
         this.emit({
           type: "tool_end",
           toolCallId: tr.tool_use_id,
@@ -533,6 +557,7 @@ class ClaudeManagedSession implements ProviderSession {
       }
       case "agent.mcp_tool_result": {
         const tr = event as BetaManagedAgentsAgentMCPToolResultEvent;
+        this.openToolCalls.delete(tr.mcp_tool_use_id);
         this.emit({
           type: "tool_end",
           toolCallId: tr.mcp_tool_use_id,
@@ -571,6 +596,8 @@ class ClaudeManagedSession implements ProviderSession {
       case "span.model_request_end": {
         const sp = event as BetaManagedAgentsSpanModelRequestEndEvent;
         const usage = sp.model_usage;
+        this.lastRequestContextTokens =
+          usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
         this.cost.inputTokens = (this.cost.inputTokens ?? 0) + usage.input_tokens;
         this.cost.outputTokens = (this.cost.outputTokens ?? 0) + usage.output_tokens;
         this.cost.cacheReadTokens =
@@ -836,7 +863,11 @@ export class ClaudeManagedAdapter implements ProviderAdapter {
       );
     }
 
-    this.apiKey = process.env.ANTHROPIC_API_KEY as string;
+    this.apiKey = selectCredential(
+      process.env.ANTHROPIC_API_KEY as string,
+      undefined,
+      "ANTHROPIC_API_KEY",
+    ).selected;
     this.agentId = process.env.MANAGED_AGENT_ID as string;
     this.environmentId = process.env.MANAGED_ENVIRONMENT_ID as string;
 
@@ -853,6 +884,14 @@ export class ClaudeManagedAdapter implements ProviderAdapter {
   }
 
   async createSession(config: ProviderSessionConfig): Promise<ProviderSession> {
+    // Keep the runner's task selection instead of the container's pool.
+    const taskKey = config.env?.ANTHROPIC_API_KEY;
+    const client =
+      taskKey && this.client instanceof Anthropic
+        ? this.client.withOptions({
+            apiKey: selectCredential(taskKey, undefined, "ANTHROPIC_API_KEY").selected,
+          })
+        : this.client;
     // Native resume is deprecated. Follow-up continuity is delivered via the
     // context preamble (see src/commands/context-preamble.ts). Any stray
     // resumeSessionId is logged and ignored — we always create a fresh session.
@@ -916,16 +955,10 @@ export class ClaudeManagedAdapter implements ProviderAdapter {
     if (vaultIds.length > 0) {
       createParams.vault_ids = Array.from(new Set(vaultIds));
     }
-    const created = await Promise.resolve(this.client.beta.sessions.create(createParams));
+    const created = await Promise.resolve(client.beta.sessions.create(createParams));
     const sessionId = created.id;
 
-    return new ClaudeManagedSession(
-      this.client,
-      sessionId,
-      config,
-      userMessageContent,
-      seenEventIds,
-    );
+    return new ClaudeManagedSession(client, sessionId, config, userMessageContent, seenEventIds);
   }
 
   /**

package/src/providers/claude-sdk-session.ts

@@ -9,6 +9,7 @@ import {
   type SpawnedProcess,
   type SpawnOptions,
 } from "@anthropic-ai/claude-agent-sdk";
+import { recordContextState } from "../hooks/context-bound-note";
 import type { RunStopHookSessionSummaryOpts } from "../hooks/hook";
 import { getContextWindowSize } from "../utils/context-window";
 import {
@@ -316,6 +317,8 @@ class ClaudeSdkSession implements ProviderSession {
   private contextWindowSize: number;
   private transcript: string[];
   private lastAssistantText = "";
+  /** Last value written to the context state file read by the context-bound note hook. */
+  private lastContextTokens: number | undefined;
   private lastCost: CostData | undefined;
   private aborted = false;
   private abortReason = "cancelled";
@@ -434,6 +437,13 @@ class ClaudeSdkSession implements ProviderSession {
     if (normalized.contextWindowSize) this.contextWindowSize = normalized.contextWindowSize;
     if (normalized.cost) this.lastCost = normalized.cost;
     if (normalized.assistantText) this.lastAssistantText = normalized.assistantText;
+    if (
+      normalized.requestContextTokens !== undefined &&
+      normalized.requestContextTokens !== this.lastContextTokens
+    ) {
+      this.lastContextTokens = normalized.requestContextTokens;
+      recordContextState(this.options.taskFilePath, normalized.requestContextTokens, this.model);
+    }
     this.transcript.push(...normalized.transcriptEntries);
     for (const event of normalized.events) this.emit(event);
     trackErrorFromJson(json, this.errorTracker);

package/src/providers/claude-session-events.ts

@@ -60,6 +60,11 @@ export type NormalizedClaudeMessage = {
   contextWindowSize?: number;
   cost?: CostData;
   assistantText?: string;
+  /**
+   * Prompt size of the latest main-thread request: input + cache read + cache
+   * write tokens. Unset for subagent messages and messages without usage.
+   */
+  requestContextTokens?: number;
   isResult: boolean;
 };
 
@@ -150,6 +155,7 @@ export function normalizeClaudeMessage(
   let model: string | undefined;
   let contextWindowSize: number | undefined;
   let assistantText: string | undefined;
+  let requestContextTokens: number | undefined;
 
   if (json.type === "system" && json.subtype === "init" && json.session_id) {
     sessionId = json.session_id;
@@ -227,6 +233,12 @@ export function normalizeClaudeMessage(
         outputTokens: usage.output_tokens ?? 0,
         contextFormula: CONTEXT_FORMULA,
       });
+      if (!json.parent_tool_use_id) {
+        requestContextTokens =
+          (usage.input_tokens ?? 0) +
+          (usage.cache_read_input_tokens ?? 0) +
+          (usage.cache_creation_input_tokens ?? 0);
+      }
     }
   }
 
@@ -247,6 +259,7 @@ export function normalizeClaudeMessage(
     contextWindowSize,
     cost,
     assistantText,
+    requestContextTokens,
     isResult: json.type === "result",
   };
 }