@desplega.ai/agent-swarm 2.5.2 → 2.5.4

package/src/http/idempotency-key.ts

@@ -0,0 +1,117 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  findAcceptedWorkflowOperation,
+  type WorkflowIdempotencyClaim,
+} from "../be/db/workflow-idempotency";
+import { getRequestAuth } from "../utils/request-auth-context";
+import { jsonError } from "./utils";
+
+/** Visible ASCII, at most 255 characters: room for a UUID, a ULID or a client's own scheme. */
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{1,255}$/;
+
+/** Set on a response answered from an earlier accepted request. */
+export const IDEMPOTENT_REPLAYED_HEADER = "Idempotent-Replayed";
+
+/** OpenAPI declaration of the optional `Idempotency-Key` request header. */
+export const idempotencyKeyHeader = (accepted: string) =>
+  z.object({
+    "Idempotency-Key": z
+      .string()
+      .regex(IDEMPOTENCY_KEY_PATTERN)
+      .optional()
+      .describe(
+        "Optional client-generated key, 1-255 visible ASCII characters (a UUID works). " +
+          `The first request the server accepts under a key ${accepted}; a retry with the same key ` +
+          "and an equivalent body gets that request's status and body back (with " +
+          `\`${IDEMPOTENT_REPLAYED_HEADER}: true\`) and changes nothing. The key is scoped to the ` +
+          "caller's identity and this operation; it is not a credential. The same key with a " +
+          "different body is a 409. A request rejected before it is accepted (validation, auth, " +
+          "not found, disabled) does not use up the key. Accepted keys do not expire.",
+      ),
+  });
+
+/** A request that sent a usable `Idempotency-Key`. */
+export interface IdempotencyKeyRequest {
+  /** Stable identity of the authenticated caller, never a credential value. */
+  principal: string;
+  key: string;
+}
+
+/**
+ * The caller identity a key is scoped to. A user or session token names its
+ * user or agent; rotating the token keeps the scope. Requests on the swarm API
+ * key are the operator, or the agent named by X-Agent-ID: every worker shares
+ * that key, so this keeps their keys apart (it is not an access boundary; the
+ * swarm key may act as any agent). A guest page session has no identity.
+ */
+function idempotencyPrincipal(req: IncomingMessage, myAgentId: string | undefined): string | null {
+  const auth = getRequestAuth(req);
+  switch (auth?.kind) {
+    case "user":
+      return `user:${auth.userId}`;
+    case "agent":
+      return `agent:${auth.agentId}`;
+    case "controller":
+      return `controller:${auth.controllerId}`;
+    case "guest":
+      return null;
+    default:
+      return myAgentId ? `agent:${myAgentId}` : "operator";
+  }
+}
+
+/**
+ * Read the `Idempotency-Key` header. Undefined when none was sent; null when
+ * it is malformed or the caller has no identity to scope it to, after writing
+ * the 400.
+ */
+export function readIdempotencyKey(
+  req: IncomingMessage,
+  res: ServerResponse,
+  myAgentId: string | undefined,
+): IdempotencyKeyRequest | null | undefined {
+  const raw = req.headers["idempotency-key"];
+  if (raw === undefined) return undefined;
+  const key = Array.isArray(raw) ? raw.join(", ") : raw;
+  if (!IDEMPOTENCY_KEY_PATTERN.test(key)) {
+    jsonError(res, "Idempotency-Key must be 1-255 visible ASCII characters", 400);
+    return null;
+  }
+  const principal = idempotencyPrincipal(req, myAgentId);
+  if (!principal) {
+    jsonError(res, "Idempotency-Key needs an identified caller", 400);
+    return null;
+  }
+  return { principal, key };
+}
+
+/**
+ * Answer from the operation already accepted under this claim's scope, if
+ * any. Returns false, writing nothing, when there is none. Otherwise writes a
+ * 409 when the stored request differs, a 410 when its workflow was deleted,
+ * or hands the stored body to `send` with the replay header set, and returns
+ * true. Runs after authentication and before any check that may have changed
+ * since the original request.
+ */
+export async function replayAcceptedOperation(
+  res: ServerResponse,
+  claim: WorkflowIdempotencyClaim,
+  send: (body: unknown) => void,
+): Promise<boolean> {
+  const accepted = await findAcceptedWorkflowOperation(claim);
+  if (!accepted) return false;
+  if (accepted.fingerprint !== claim.fingerprint) {
+    jsonError(res, "Idempotency-Key was already used for a different request", 409);
+  } else if (accepted.resourceDeletedAt !== null) {
+    jsonError(
+      res,
+      "The workflow this Idempotency-Key created or triggered was deleted; send a new key to start over",
+      410,
+    );
+  } else {
+    res.setHeader(IDEMPOTENT_REPLAYED_HEADER, "true");
+    send(accepted.body);
+  }
+  return true;
+}

package/src/http/sessions.ts

@@ -502,7 +502,22 @@ const SessionHideSourceSchema = z
       .filter(Boolean),
   )
   .describe(
-    "Comma-separated root sources to leave out (the sessions v2 source filter), e.g. `slack,chat`.",
+    "Comma-separated root sources to leave out, e.g. `slack,chat`. Older sessions v2 clients send this; `showSource` replaces it.",
+  );
+
+const SessionShowSourceSchema = z
+  .string()
+  // The same cap as the `showSource` body field of `POST /api/session-triage`.
+  .refine((value) => value.split(",").length <= 32, "showSource takes at most 32 sources.")
+  .optional()
+  .transform((value) =>
+    value
+      ?.split(",")
+      .map((source) => source.trim())
+      .filter(Boolean),
+  )
+  .describe(
+    "Comma-separated root sources to keep (the sessions v2 source filter), e.g. `ui,slack`. Present and empty keeps none; omit to keep every source.",
   );
 
 const listSessions = route({
@@ -568,6 +583,8 @@ const listSessions = route({
     show: SessionShowSchema,
     /** Root sources to leave out. Must match the tree's `hideSource`. */
     hideSource: SessionHideSourceSchema,
+    /** Root sources to keep. Must match the tree's `showSource`. */
+    showSource: SessionShowSourceSchema,
   }),
   responses: {
     200: {
@@ -590,7 +607,11 @@ const sessionTree = route({
   pattern: ["api", "session-tree"],
   summary: "Get session groups and triage counts",
   tags: ["Sessions"],
-  query: z.object({ show: SessionShowSchema, hideSource: SessionHideSourceSchema }),
+  query: z.object({
+    show: SessionShowSchema,
+    hideSource: SessionHideSourceSchema,
+    showSource: SessionShowSourceSchema,
+  }),
   responses: {
     200: { description: "Visible groups and section counts", schema: SessionTreeResponseSchema },
     401: { description: "Unauthorized" },
@@ -615,6 +636,8 @@ const triageSessionListRoute = route({
       groupKey: SessionKeyFilterSchema.optional(),
       show: SessionShowSchema,
       hideSource: z.array(z.string().min(1)).max(32).optional(),
+      /** Root sources to keep; an empty array keeps none. */
+      showSource: z.array(z.string().min(1)).max(32).optional(),
     })
     .refine((body) => [body.triage, body.noGroup, body.groupKey].filter(Boolean).length === 1, {
       message: "Name exactly one list: triage, noGroup, or groupKey",
@@ -941,6 +964,7 @@ export async function handleSessions(
     const filterOpts = {
       source: sources,
       hideSource: parsed.query.hideSource,
+      showSource: parsed.query.showSource,
       q: parsed.query.q,
       requestedByUserId: parsed.query.requestedByUserId,
       contextKeyPrefix: parsed.query.contextKeyPrefix,
@@ -994,6 +1018,7 @@ export async function handleSessions(
       await getSessionTree(actor, undefined, {
         mine: parsed.query.show !== "all",
         hideSource: parsed.query.hideSource,
+        showSource: parsed.query.showSource,
       }),
     );
     return true;

package/src/http/workflows.ts

@@ -5,6 +5,7 @@ import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
   createWorkflow,
   deleteWorkflow,
+  getDbClient,
   getWorkflow,
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
@@ -15,6 +16,13 @@ import {
   type updateWorkflow,
   withFavoriteFlags,
 } from "../be/db";
+import {
+  assertWorkflowIdempotencyKeyUnused,
+  IdempotencyKeyTakenError,
+  recordAcceptedWorkflowOperation,
+  type WorkflowIdempotencyClaim,
+  workflowRequestFingerprint,
+} from "../be/db/workflow-idempotency";
 import { getWorkflowRunParent } from "../be/db/workflow-runs";
 import {
   AssetKeySchema,
@@ -46,6 +54,11 @@ import { cancelWorkflowRun, retryFailedRun } from "../workflows/resume";
 import { handleWebhookTrigger, WebhookError } from "../workflows/triggers";
 import { snapshotAndUpdateWorkflow } from "../workflows/version";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
+import {
+  idempotencyKeyHeader,
+  readIdempotencyKey,
+  replayAcceptedOperation,
+} from "./idempotency-key";
 import { route } from "./route-def";
 import { jsonError, parseBody, triggerSchemaErrorResponse } from "./utils";
 
@@ -142,6 +155,7 @@ const createWorkflowRoute = route({
   pattern: ["api", "workflows"],
   summary: "Create a new workflow",
   tags: ["Workflows"],
+  headers: idempotencyKeyHeader("creates one workflow"),
   body: z.object({
     name: z.string().min(1),
     key: AssetKeySchema.optional(),
@@ -159,7 +173,9 @@ const createWorkflowRoute = route({
   }),
   responses: {
     201: { description: "Workflow created", schema: WorkflowSaveResponseSchema },
-    400: { description: "Invalid definition" },
+    400: { description: "Invalid definition, or a malformed Idempotency-Key" },
+    409: { description: "Idempotency-Key was already used for a different request" },
+    410: { description: "The workflow created under this Idempotency-Key was deleted" },
   },
 });
 
@@ -272,16 +288,21 @@ const triggerWorkflowRoute = route({
   path: "/api/workflows/{id}/trigger",
   pattern: ["api", "workflows", null, "trigger"],
   summary: "Trigger a workflow execution",
+  description:
+    "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  headers: idempotencyKeyHeader("starts one run"),
   responses: {
     201: {
       description: "Workflow run started (or skipped if cooldown active)",
       schema: z.object({ runId: z.string(), skipped: z.boolean() }),
     },
-    400: { description: "Workflow is disabled" },
+    400: { description: "Workflow is disabled, or a malformed Idempotency-Key" },
     401: { description: "Unauthorized" },
     404: { description: "Workflow not found" },
+    409: { description: "Idempotency-Key was already used for a different request" },
+    410: { description: "The workflow triggered under this Idempotency-Key was deleted" },
   },
 });
 
@@ -574,8 +595,21 @@ export async function handleWorkflows(
   }
 
   if (createWorkflowRoute.match(req.method, pathSegments)) {
+    const idempotency = readIdempotencyKey(req, res, myAgentId);
+    if (idempotency === null) return true;
     const parsed = await createWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    const claim: WorkflowIdempotencyClaim | undefined = idempotency && {
+      ...idempotency,
+      operation: "workflow.create",
+      targetId: "",
+      fingerprint: workflowRequestFingerprint("workflow.create", parsed.body),
+    };
+    const replayCreate = (body: unknown) =>
+      createWorkflowRoute.respond(res, 201, body as z.input<typeof WorkflowSaveResponseSchema>);
+    // Before validation: a retry gets the original result even if the same
+    // definition would no longer validate.
+    if (claim && (await replayAcceptedOperation(res, claim, replayCreate))) return true;
 
     // Validate definition structure
     const validation = validateDefinition(parsed.body.definition, getExecutorRegistry());
@@ -603,27 +637,55 @@ export async function handleWorkflows(
       throw error;
     }
 
-    const workflow = await createWorkflow(
-      {
-        key,
-        name: parsed.body.name,
-        description: parsed.body.description,
-        definition: parsed.body.definition,
-        triggers: parsed.body.triggers,
-        cooldown: parsed.body.cooldown,
-        input: parsed.body.input,
-        triggerSchema: parsed.body.triggerSchema,
-        params: parsed.body.params,
-        requiredParams: parsed.body.requiredParams,
-        requires: parsed.body.requires,
-        dir: parsed.body.dir,
-        vcsRepo: parsed.body.vcsRepo,
-        createdByAgentId: myAgentId ?? undefined,
-        createdBy: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
-      },
-      "api",
-    );
-    createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
+    const data: Parameters<typeof createWorkflow>[0] = {
+      key,
+      name: parsed.body.name,
+      description: parsed.body.description,
+      definition: parsed.body.definition,
+      triggers: parsed.body.triggers,
+      cooldown: parsed.body.cooldown,
+      input: parsed.body.input,
+      triggerSchema: parsed.body.triggerSchema,
+      params: parsed.body.params,
+      requiredParams: parsed.body.requiredParams,
+      requires: parsed.body.requires,
+      dir: parsed.body.dir,
+      vcsRepo: parsed.body.vcsRepo,
+      createdByAgentId: myAgentId ?? undefined,
+      createdBy: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+    };
+    if (!claim) {
+      const workflow = await createWorkflow(data, "api");
+      createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
+      return true;
+    }
+
+    // Warnings are computed before the transaction (a readiness check may
+    // call out) and stored with the workflow, so a retry gets this snapshot,
+    // not the workflow as it is by then.
+    const warnings = await workflowSaveWarnings(parsed.body.definition, getExecutorRegistry());
+    let saved: z.input<typeof WorkflowSaveResponseSchema>;
+    try {
+      saved = await getDbClient().transaction(async () => {
+        // Before the insert: a concurrent winner's workflow holds the same name.
+        await assertWorkflowIdempotencyKeyUnused(claim);
+        const workflow = await createWorkflow(data, "api");
+        const body = warnings.length > 0 ? { ...workflow, warnings } : workflow;
+        await recordAcceptedWorkflowOperation(claim, {
+          workflowId: workflow.id,
+          status: 201,
+          body,
+        });
+        return body;
+      });
+    } catch (err) {
+      // A concurrent request with this key committed first; nothing of this one did.
+      if (err instanceof IdempotencyKeyTakenError) {
+        if (await replayAcceptedOperation(res, claim, replayCreate)) return true;
+      }
+      throw err;
+    }
+    createWorkflowRoute.respond(res, 201, saved);
     return true;
   }
 
@@ -858,8 +920,26 @@ export async function handleWorkflows(
   }
 
   if (triggerWorkflowRoute.match(req.method, pathSegments)) {
+    const idempotency = readIdempotencyKey(req, res, myAgentId);
+    if (idempotency === null) return true;
     const parsed = await triggerWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    let claim: WorkflowIdempotencyClaim | undefined;
+    let keyedBody: Record<string, unknown> | undefined;
+    const replayTrigger = (body: unknown) =>
+      triggerWorkflowRoute.respond(res, 201, body as { runId: string; skipped: boolean });
+    if (idempotency) {
+      keyedBody = await parseBody<Record<string, unknown>>(req);
+      claim = {
+        ...idempotency,
+        operation: "workflow.trigger",
+        targetId: parsed.params.id,
+        fingerprint: workflowRequestFingerprint("workflow.trigger", keyedBody),
+      };
+      // Before the enabled, cooldown, readiness and trigger-schema checks: an
+      // accepted trigger replays even after the workflow changed.
+      if (await replayAcceptedOperation(res, claim, replayTrigger)) return true;
+    }
     const workflow = await getWorkflow(parsed.params.id);
     if (!workflow) {
       res.writeHead(404);
@@ -870,20 +950,45 @@ export async function handleWorkflows(
       jsonError(res, "Workflow is disabled", 400);
       return true;
     }
-    const body = await parseBody<Record<string, unknown>>(req);
+    // Not `??`: a JSON `null` body is a parsed body too, and reading the
+    // already-ended stream again would wait forever.
+    const body = idempotency ? keyedBody : await parseBody<Record<string, unknown>>(req);
     let runId: string;
+    let accepted: { runId: string; skipped: boolean } | undefined;
     try {
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
         triggerType: "api",
         requestedByUserId: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+        // Recorded in the run's own transaction, before the walk starts.
+        accept: claim
+          ? async (run) => {
+              const response = { runId: run.runId, skipped: run.skipped };
+              await recordAcceptedWorkflowOperation(claim, {
+                workflowId: workflow.id,
+                runId: run.runId,
+                status: 201,
+                body: response,
+              });
+              accepted = response;
+            }
+          : undefined,
       });
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
         triggerSchemaErrorResponse(res, err.message, err.validationErrors);
         return true;
       }
+      // A concurrent request with this key committed its run first; this one
+      // created none and walks nothing.
+      if (claim && err instanceof IdempotencyKeyTakenError) {
+        if (await replayAcceptedOperation(res, claim, replayTrigger)) return true;
+      }
       throw err;
     }
+    if (accepted) {
+      triggerWorkflowRoute.respond(res, 201, accepted);
+      return true;
+    }
 
     // Check if skipped due to cooldown
     const run = await getWorkflowRun(runId);

package/src/integrations/chat-sdk/inbound.ts

@@ -188,9 +188,10 @@ export async function handleChatInbound(
   }
 
   if (text || attachments.length > 0) {
-    // Subscribed-thread messages may be dropped by the router at flush time;
-    // they get typing and a reaction once a task exists (see flushChatThread).
-    const acknowledge = kind !== "subscribed";
+    // An unaddressed subscribed-thread message may be dropped by the router at
+    // flush time; it gets typing and a reaction once a task exists (see
+    // flushChatThread). A mention, reply to the bot, or DM is acknowledged now.
+    const acknowledge = kind !== "subscribed" || isDirectMessage || mentioned || facts.replyToBot;
     bufferChatMessage(thread.id, {
       messageId: message.id,
       channelId: thread.channelId,
@@ -580,7 +581,7 @@ export async function flushChatThread(
   if (created > 0) {
     await rememberChatThreadRequester(threadId, requester.userId);
     await subscribe(thread);
-    // Subscribed-thread messages start typing only here, once a task exists.
+    // Unaddressed subscribed-thread messages start typing only here, once a task exists.
     startTypingKeepalive(adapter, threadId);
     await clearChatMessageReactions(
       adapter,

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/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.1792728062-g40cf3f";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1792844927-g360c96";
 
 /** 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();
   }