@ziggs-ai/agent-sdk 0.10.8 → 0.11.0

package/CHANGELOG.md

@@ -4,10 +4,10 @@
 
 ### Removed (breaking)
 
-- Removed exports `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge`. The launcher rewrite deleted the wake machinery these gated: every agent stays connected and the write signals it, so there is no backlog to age out and nothing to replay-gate (ZIG-993). Pinned to 0.4.x and importing any of the four? Delete the call — the behaviour it bought is now unconditional. There is no replacement API.
+- Removed exports `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge`. The launcher rewrite deleted the wake machinery these gated: every agent stays connected and the write signals it, so there is no backlog to age out and nothing to replay-gate. Pinned to 0.4.x and importing any of the four? Delete the call — the behaviour it bought is now unconditional. There is no replacement API.
 - `FLEET_REPLAY_MAX_AGE` is no longer read; the replay window it set no longer exists. Nothing in this repo sets it, but it can come out of any deployment env that does.
-- `Ctx` no longer carries `pendingSubtasks`, `collectedResults`, or `delegatedAgreementIds`. ZIG-977 moved the real bookkeeping into `Ctx.tasks` (keyed by taskId) and ZIG-1057 stopped syncing these mirrors, but they stayed on the interface as required-and-always-empty — so a workflow guard reading one saw empty forever and silently checked nothing. Read via `allPendingSubtasks(ctx)` / `allCollectedResults(ctx)` / `allDelegatedAgreementIds(ctx)`. Sessions persisted before `tasks` existed are still migrated on restore.
-- `WireResult.status` removed. ZIG-1057 cut `status` from the wire in favour of `state`; four readers kept a `|| r.status` tail, which would have absorbed a backend regression instead of failing on it. Task state resolves as `task?.state || r.state`.
+- `Ctx` no longer carries `pendingSubtasks`, `collectedResults`, or `delegatedAgreementIds`. The real bookkeeping moved into `Ctx.tasks` (keyed by taskId) and these mirrors stopped syncing, but they stayed on the interface as required-and-always-empty — so a workflow guard reading one saw empty forever and silently checked nothing. Read via `allPendingSubtasks(ctx)` / `allCollectedResults(ctx)` / `allDelegatedAgreementIds(ctx)`. Sessions persisted before `tasks` existed are still migrated on restore.
+- `WireResult.status` removed. The wire carries `state` only; the `|| r.status` fallback tails were removed so a backend regression fails loudly instead of being absorbed. Task state resolves as `task?.state || r.state`.
 
 ### Added
 
@@ -18,16 +18,16 @@
 - Attention gate: only the addressed agent spends a turn. A message addressed elsewhere in a shared room no longer wakes every participant.
 - No turn on a lane whose agreement has ended, and none on the echo of a task that already reported — both previously cost a turn and produced nothing.
 - Persona wire shapes are understood on inbound frames.
-- A wake declares its lane so the backend can fence reach (ZIG-1092).
-- A proposal awaiting the agent's own consent counts as actionable rather than a notice to park (ZIG-1078).
-- Artifact idempotency keys are derived from content (ZIG-1083).
-- Blank tool arguments fall back to the wake's lane (ZIG-1081).
+- A wake declares its lane so the backend can fence reach.
+- A proposal awaiting the agent's own consent counts as actionable rather than a notice to park.
+- Artifact idempotency keys are derived from content.
+- Blank tool arguments fall back to the wake's lane.
 
 ## 0.9.0 — 2026-07-30
 
 ### Changed (breaking)
 
-- `task-update` / `task_set_result` accept `state` only — legacy `status` alias removed (ZIG-1057).
+- `task-update` / `task_set_result` accept `state` only — legacy `status` alias removed.
 - Removed export `syncAggregateTaskViews`; read pending/collected/delegated via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`. Ctx aggregate mirrors stay empty.
 
 ## 0.4.0 — 2026-07-23
@@ -38,8 +38,8 @@
 
 ### Changed (breaking)
 
-- Removed legacy socket-frame aliases; wire frames use canonical names only (ZIG-913, ZIG-915).
-- Delivery-law: classify inbound messages from the `service` wire shape (ZIG-936).
+- Removed legacy socket-frame aliases; wire frames use canonical names only.
+- Delivery-law: classify inbound messages from the `service` wire shape.
 - Bumped `@ziggs-ai/api-client` to `^0.3.0`.
 
 ## 0.3.0 — 2026-07-22
@@ -50,7 +50,7 @@
 
 ## 0.2.0 — 2026-07-16
 
-### Added (ZIG-784)
+### Added
 
 - Public brain selection API: `ziggsBrain()`, `claudeBrain()`, and `Brain` interface (`tick()`).
 - `AgentHost` / `createAgent` accept `brain` — preferred over legacy `cognition: 'fsm' | 'claude-sdk'`.

package/dist/AgentHost.d.ts

@@ -41,13 +41,13 @@ export declare const DEFAULT_MODEL = "claude-haiku-4-5";
  */
 export type SessionResolver = (normalized: NormalizedEvent, ownAgentId: string) => string | null;
 /**
- * ZIG-975: one lane key per unit of work, derived the same way as inbox wakes.
+ * one lane key per unit of work, derived the same way as inbox wakes.
  *
  * Inbox deliveries key on `chatId` (DEFAULT_SESSION_RESOLVER). Bootstrap used to
  * prefer bare `agreementId`, which opened a second lane for the same task and
  * made the snapshot read treat the agreement id as a chat (`chatMissing: true`,
  * empty context). Prefer the origin chat when present; otherwise the agreement's
- * notification chat (`agrn-<agreementId>`), which is always linked after ZIG-966.
+ * notification chat (`agrn-<agreementId>`), which is always linked after.
  */
 export declare function laneSessionIdForTask(task: {
     originChatId?: string | null;
@@ -72,11 +72,11 @@ export interface AgentHostOptions {
     name?: string | null;
     /** Store-facing one-liner. See DefineAgentInput.description. */
     description?: string;
-    /** Claude-brain system prompt (ZIG-1080); falls back to `description`. */
+    /** Claude-brain system prompt; falls back to `description`. */
     systemPrompt?: string;
     specialization?: string | null;
     /**
-     * ZIG-1185 — strings compared exactly against a quest's `match` field.
+     * strings compared exactly against a quest's `match` field.
      * Miss → ack with zero LLM. Match → normal wake. `specialization` is also
      * checked when set.
      */
@@ -96,7 +96,7 @@ export interface AgentHostOptions {
     /** Max agentic turns per Claude SDK wake. Default 30. */
     claudeMaxTurns?: number;
     /**
-     * ZIG-860: claude-sdk agents resume their transcript across wakes by default,
+     * claude-sdk agents resume their transcript across wakes by default,
      * so per-wake input grows monotonically on a long lane. When true, each wake
      * starts a fresh Claude session — the protocol is backend-authoritative (the
      * brain re-reads via context_snapshot / the wake event), so the
@@ -125,14 +125,14 @@ export interface AgentHostOptions {
     sessionStore?: SessionStore;
     /** Observability tap: called after every effect with the effect and its response. */
     effectTap?: (effect: import('./types.js').Effect, response: unknown) => void;
-    /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
+    /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape. */
     transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
     /**
      * Usage/cost tap: called once per settled tick with the tick's authoritative
      * token usage (result.metrics). This is the SINGLE source of truth for
      * usage/cost across every cognition — the FSM (llm-call + streamed reply +
      * tool-internal LLM) and the Claude brain (incl. cache tokens) both funnel
-     * their spend here (ZIG-813). effectTap / tool generations are structural
+     * their spend here. effectTap / tool generations are structural
      * tracing only and must NOT also carry billable usage, or cost double-counts.
      */
     metricsTap?: (info: {
@@ -142,10 +142,10 @@ export interface AgentHostOptions {
         cognition: string;
         metrics: import('./agent/Agent.js').TickOutput['metrics'];
     }) => void;
-    /** Production monitoring ingest (ZIG-360). Default on; set false to disable. */
+    /** Production monitoring ingest. Default on; set false to disable. */
     telemetryIngest?: boolean;
     /**
-     * Pull inbox on every WS connect/reconnect (ZIG-454). Default true.
+     * Pull inbox on every WS connect/reconnect. Default true.
      * Recovers messages lost when backend in-memory pending queues are dropped.
      */
     inboxCatchUp?: boolean;
@@ -167,7 +167,7 @@ export declare function warnOnShadowedPlatformTools(platformTools: ToolDefinitio
  * a transport (Ziggs WebSocket), and the lane router (per-session FIFO queue
  * + in-memory session state).
  *
- *   transport (WS)  →  handleMessage  →  agent.tick(... , eff)  →  ...
+ *   transport (WS)  →  handleMessage  →  agent.tick(.. , eff)  →  ..
  */
 export declare class AgentHost {
     options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
@@ -208,7 +208,7 @@ export declare class AgentHost {
     /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
     handleMessage(text: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
-     * ZIG-1144 part 3 — an agreement lane outlives the agreement.
+     * part 3 — an agreement lane outlives the agreement.
      *
      * A lane named `agrn-<agreementId>` keeps its Claude session for the whole
      * engagement, so a trailing event after the deal ends pays for all of it: on
@@ -226,11 +226,11 @@ export declare class AgentHost {
      */
     private laneAgreementIsTerminal;
     /**
-     * ZIG-1153 — the trailing turn on work that is already reported.
+     * the trailing turn on work that is already reported.
      *
      * A lane session carries the whole engagement, so the LAST wake is the most
      * expensive one: on prod, the frame that followed a completed elicitation cost
-     * **158,733 tokens** with the session's input at 366,417 before ZIG-816 reset
+     * **158,733 tokens** with the session's input at 366,417 before reset
      * it, and produced nothing — the spec had been written and the task closed one
      * frame earlier.
      *
@@ -251,12 +251,12 @@ export declare class AgentHost {
     private _resolveOwnAgentId;
     connectAsync(_timeout?: number): Promise<this>;
     /**
-     * ZIG-1185 — plain string compare against {@link AgentHostOptions.questMatchTags}
+     * plain string compare against {@link AgentHostOptions.questMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
     private triageQuestDelivery;
     private _bootstrapAssignedActiveTasks;
-    /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
+    /** replay task-assigned for an existing active task (demo recovery). */
     wakeTaskAssignment(taskId: string): Promise<void>;
     disconnect(): void;
     /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */

package/dist/AgentHost.js

@@ -40,13 +40,13 @@ async function loadConnectionPool() {
 }
 const DEFAULT_SESSION_RESOLVER = (normalized) => normalized.chatId;
 /**
- * ZIG-975: one lane key per unit of work, derived the same way as inbox wakes.
+ * one lane key per unit of work, derived the same way as inbox wakes.
  *
  * Inbox deliveries key on `chatId` (DEFAULT_SESSION_RESOLVER). Bootstrap used to
  * prefer bare `agreementId`, which opened a second lane for the same task and
  * made the snapshot read treat the agreement id as a chat (`chatMissing: true`,
  * empty context). Prefer the origin chat when present; otherwise the agreement's
- * notification chat (`agrn-<agreementId>`), which is always linked after ZIG-966.
+ * notification chat (`agrn-<agreementId>`), which is always linked after.
  */
 export function laneSessionIdForTask(task) {
     if (typeof task.originChatId === 'string' && task.originChatId) {
@@ -69,13 +69,13 @@ function createToolManager(options) {
         taskTools = PROTOCOL_TOOLS; // 'all' or undefined
     const claudeSdkTools = isClaudeCognition(options.cognition) ? CLAUDE_SDK_TOOLS : [];
     const ownTools = Array.isArray(userTools) ? userTools : [];
-    // ZIG-1280 — browse rides wherever claim rides. Posted-first engagements
+    // browse rides wherever claim rides. Posted-first engagements
     // START at marketplace_view (find the listing), so an agent that can
     // agreement_claim but cannot browse holds a default pathway it cannot begin.
     // Both directions: shedding claim (taskTools array without it) sheds browse.
     const canClaim = taskTools.some((t) => t.schema.function.name === 'agreement_claim');
     const browseTools = canClaim ? [marketplaceViewTool] : [];
-    // ZIG-1278 — chat_open is always-on so claim/provider kickoff (FSM) and the
+    // chat_open is always-on so claim/provider kickoff (FSM) and the
     // Claude always-on set can open the buyer chat after a store claim. CHAT_TOOLS
     // is also folded into CLAUDE_SDK_TOOLS; Map registration makes duplicates a no-op.
     const platformTools = [...taskTools, ...CHAT_TOOLS, ...browseTools, ...claudeSdkTools];
@@ -128,7 +128,7 @@ function createBackendServices(options) {
     const agentId = options.agentId;
     const artifactsClient = new ArtifactsClient(operatorKey, agentId);
     const contextReadClient = new ContextReadClient(operatorKey, agentId);
-    // ZIG-1080: the role text is the prompt when the author split the two; the
+    // the role text is the prompt when the author split the two; the
     // store-facing `description` is only the fallback for agents that never did.
     const promptBuilder = new PromptBuilder({
         description: options.systemPrompt || options.description,
@@ -153,7 +153,7 @@ function createBackendServices(options) {
  * a transport (Ziggs WebSocket), and the lane router (per-session FIFO queue
  * + in-memory session state).
  *
- *   transport (WS)  →  handleMessage  →  agent.tick(... , eff)  →  ...
+ *   transport (WS)  →  handleMessage  →  agent.tick(.. , eff)  →  ..
  */
 export class AgentHost {
     options;
@@ -210,7 +210,7 @@ export class AgentHost {
         this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
         // A Claude-brain wake legitimately runs long (multi-turn query, prose
         // deliverables) — 120s watchdogged real spec-writing wakes mid-flight,
-        // which then redelivered and re-ran (ZIG-924 dogfood, 2026-07-26). FSM
+        // which then redelivered and re-ran (dogfood, 2026-07-26). FSM
         // turns stay on the tight default.
         this.tickTimeoutMs =
             options.tickTimeoutMs ??
@@ -319,7 +319,7 @@ export class AgentHost {
                 agentId: this.options.agentId,
                 // No taskService/agreementService: Claude-brain tools execute through
                 // eff({ kind: 'tool-call' }) → the shared executor, which sources those
-                // services from the effect handler's deps like the FSM path (ZIG-775).
+                // services from the effect handler's deps like the FSM path.
                 maxTurns: this.options.claudeMaxTurns,
                 statelessPerWake: this.options.claudeStatelessPerWake,
             })
@@ -331,7 +331,7 @@ export class AgentHost {
         this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
         // A timer frame is not a delivery: there is no watermark waiting on it and
         // nothing to redeliver, so its failure is logged and dropped here rather
-        // than left as an unhandled rejection (ZIG-1191 made enqueue reject).
+        // than left as an unhandled rejection (made enqueue reject).
         this.stateTimers = new StateTimers((ev, laneKey) => {
             void this.eventQueue.enqueue(ev, laneKey).catch((err) => {
                 runtimeLog.warn('AgentHost', `state-timer frame failed laneKey=${laneKey}: ${err?.message || err}`);
@@ -366,7 +366,7 @@ export class AgentHost {
             event: { type: 'message', timestamp: Date.now(), text: '' },
         };
         let sessionId = this.sessionResolver(fakeNormalized, ownAgentId);
-        // ZIG-1278 — store claims deliver agreement wakes with no chatId. Do not
+        // store claims deliver agreement wakes with no chatId. Do not
         // drop them; lane by agreement the same way task bootstrap does
         // (`agrn-<agreementId>`), never a bare agreement id.
         if (!sessionId) {
@@ -415,7 +415,7 @@ export class AgentHost {
         }
         let enrichedText = typeof text === 'string' ? text : '';
         if (!enrichedText.trim()) {
-            // ZIG-936: agreement rides under `service` on the inbox-pull wire; fall
+            // agreement rides under `service` on the inbox-pull wire; fall
             // back to top-level for hand-built metadata.
             const svc = metadata.service;
             const agreement = (svc?.agreement ?? metadata.agreement);
@@ -441,7 +441,7 @@ export class AgentHost {
         // routes the event onto its lane. No live-path watermark ack — there is no
         // separate live/push channel to reconcile against anymore.
         //
-        // ZIG-1191: a failure un-marks the messageId. The mark above is what stops
+        // a failure un-marks the messageId. The mark above is what stops
         // the same message being processed twice; leaving it set on a failed wake
         // would make the redelivery this rejection buys us a no-op.
         try {
@@ -454,7 +454,7 @@ export class AgentHost {
         }
     }
     /**
-     * ZIG-1144 part 3 — an agreement lane outlives the agreement.
+     * part 3 — an agreement lane outlives the agreement.
      *
      * A lane named `agrn-<agreementId>` keeps its Claude session for the whole
      * engagement, so a trailing event after the deal ends pays for all of it: on
@@ -486,11 +486,11 @@ export class AgentHost {
         }
     }
     /**
-     * ZIG-1153 — the trailing turn on work that is already reported.
+     * the trailing turn on work that is already reported.
      *
      * A lane session carries the whole engagement, so the LAST wake is the most
      * expensive one: on prod, the frame that followed a completed elicitation cost
-     * **158,733 tokens** with the session's input at 366,417 before ZIG-816 reset
+     * **158,733 tokens** with the session's input at 366,417 before reset
      * it, and produced nothing — the spec had been written and the task closed one
      * frame earlier.
      *
@@ -589,7 +589,7 @@ export class AgentHost {
                 runtimeLog.info('AgentHost', `wake agent=${identity.agentId} lane=${laneKey} llmCalls=${m.llmCalls} ` +
                     `tokens_in=${m.tokens.input} tokens_out=${m.tokens.output} total=${m.tokens.total}`);
             }
-            // Single source of truth for usage/cost (ZIG-813): emit the tick's
+            // Single source of truth for usage/cost: emit the tick's
             // authoritative token metrics once, for every cognition. Never let an
             // observability failure break the tick.
             if (this.options.metricsTap && result.metrics) {
@@ -624,7 +624,7 @@ export class AgentHost {
             // again unless a real event happens to arrive.
             this._armIfTimedParked(laneKey, session.state ?? this.agent.workflow.initial);
             // Best-effort: also notify the user so the conversation isn't silently
-            // stuck (ZIG-607). Complements the timer re-arm above — that recovers a
+            // stuck. Complements the timer re-arm above — that recovers a
             // parked lane; this tells a waiting human.
             const ev = event;
             const senderType = String(ev?.senderType ?? '').toUpperCase();
@@ -632,7 +632,7 @@ export class AgentHost {
             if (senderId && senderType === 'USER') {
                 this.eff({ kind: 'send-message', sessionId: session.sessionId, receiverId: senderId, text: 'Something went wrong. Please try again.' }).catch(() => { });
             }
-            // ZIG-1191: and then say so. Everything above is recovery for the lane —
+            // and then say so. Everything above is recovery for the lane —
             // it does not mean the event was handled, and the caller is about to
             // decide whether the delivery that carried it can be acked. Swallowing
             // here is what turned a failed wake into a lost one: two hand-off publish
@@ -682,7 +682,7 @@ export class AgentHost {
                 onResourceEvent: (event) => {
                     return this.handleResourceEvent(event);
                 },
-                // ZIG-973: work delivered by the inbox's task channel, not by a chat
+                // work delivered by the inbox's task channel, not by a chat
                 // row — this is what reaches a task under a chat-less agreement or one
                 // the agent assigned to itself.
                 onTask: async (task) => {
@@ -693,7 +693,7 @@ export class AgentHost {
                         runtimeLog.warn(this.options.name || 'agent', `inbox task ${task.taskId} could not be woken: ${err.message}`);
                     }
                 },
-                // ZIG-1185: exact-match triage in code — miss acks with 0 tokens.
+                // exact-match triage in code — miss acks with 0 tokens.
                 onQuest: async (quest) => {
                     await this.triageQuestDelivery(quest);
                 },
@@ -702,7 +702,7 @@ export class AgentHost {
         return this;
     }
     /**
-     * ZIG-1185 — plain string compare against {@link AgentHostOptions.questMatchTags}
+     * plain string compare against {@link AgentHostOptions.questMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
     async triageQuestDelivery(quest) {
@@ -768,7 +768,7 @@ export class AgentHost {
             }, laneKey);
         }
     }
-    /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
+    /** replay task-assigned for an existing active task (demo recovery). */
     async wakeTaskAssignment(taskId) {
         const agentId = this.options.agentId;
         if (!agentId || !this.taskService) {

package/dist/adapters/AnthropicAdapter.js

@@ -94,7 +94,7 @@ export class AnthropicAdapter {
         const final = await stream.finalMessage();
         const u = final.usage;
         // Fold cache read/creation into prompt tokens so the streamed reply is not
-        // undercounted (cache traffic was the bulk of the ZIG-759 drain).
+        // undercounted (cache traffic was the bulk of the drain).
         const usage = u
             ? {
                 prompt_tokens: (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0),

package/dist/adapters/McpAdapter.d.ts

@@ -38,7 +38,7 @@ export type McpTransportConfig = {
     agentId?: string;
 } | {
     /**
-     * Per-user brokered connection (ZIG-771): the agent holds NO
+     * Per-user brokered connection: the agent holds NO
      * connectionId/grantId. It speaks StreamableHTTP to
      * `/connections/mcp/relay` and asserts the invoking end-user via
      * `x-on-behalf-of-user`; the gateway resolves that user's own connection
@@ -57,13 +57,13 @@ export type McpTransportConfig = {
      * The MCP server URL this agent fronts. Not used for gateway calls (the
      * gateway derives the server from the resolved connection), but needed to
      * open a connection request when the invoking user hasn't connected yet
-     * (ZIG-771). Without it, a NO_USER_CONNECTION surfaces as an error rather
+     *. Without it, a NO_USER_CONNECTION surfaces as an error rather
      * than an auto-created consent prompt.
      */
     serverUrl?: string;
 };
 /**
- * Typed failure from the Ziggs MCP gateway (ZIG-702). `code` is the stable
+ * Typed failure from the Ziggs MCP gateway. `code` is the stable
  * machine-readable reason — e.g. `GRANT_REVOKED`, `GRANT_EXPIRED`,
  * `GRANT_HOLDER_MISMATCH`, `GRANT_CONNECTION_MISMATCH` — so agent code can
  * branch ("revoked → tell the user and stop retrying" vs "network blip →
@@ -89,7 +89,7 @@ export declare function resolveZiggsGatewayTarget(config: Extract<McpTransportCo
     headers: Record<string, string>;
 };
 /**
- * Resolve the per-user gateway URL + headers (ZIG-771). No connectionId/grantId —
+ * Resolve the per-user gateway URL + headers. No connectionId/grantId —
  * the gateway resolves the invoking user's own connection + grant from
  * `x-on-behalf-of-user` + the impersonated agent.
  */
@@ -109,9 +109,9 @@ export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' |
     /**
      * Max tools to bind to the LLM per turn. LLM providers cap the `tools` array
      * (OpenAI: 128); an MCP server exposing more (e.g. PostHog: 146) makes every
-     * turn fail with `400 ... array too long`. When the server's tool count
+     * turn fail with `400 .. array too long`. When the server's tool count
      * exceeds this budget the list is truncated (and logged). Defaults to 128.
-     * See ZIG-759; Phase 2 will replace truncation with query-aware selection.
+     * See; Phase 2 will replace truncation with query-aware selection.
      */
     maxTools?: number;
     /**
@@ -120,12 +120,12 @@ export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' |
      * MCP server (e.g. PostHog's 146 tools) be narrowed to the handful this agent
      * actually needs — cutting per-turn cost and stopping the model from thrashing
      * across (or never binding) the tool it should call. Empty/undefined = bind
-     * all (unchanged behavior). ZIG-759 Phase 2 = name-based selection.
+     * all (unchanged behavior). Phase 2 = name-based selection.
      */
     allowedTools?: string[];
     /**
      * Pre-discovered MCP tool schemas. REQUIRED for `type: 'ziggs-per-user'`
-     * (ZIG-771) — there is no boot connection to call `tools/list` on, so the
+     * — there is no boot connection to call `tools/list` on, so the
      * schema is baked at provision time and passed here. Ignored for the other
      * transports, which discover tools live at boot.
      */
@@ -138,7 +138,7 @@ export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' |
 /**
  * How many MCP tools may be bound to the LLM, given the provider cap and the
  * number of extra (non-MCP) tools the agent also carries. Always >= 1 so a
- * pathological config still binds something rather than nothing. ZIG-759.
+ * pathological config still binds something rather than nothing.
  */
 export declare function mcpToolBudget(maxTools: number, extraToolCount: number): number;
 export interface McpAgentHandle {
@@ -158,7 +158,7 @@ export declare function buildTransport(config: McpTransportConfig, defaults?: {
  * that full block rides every turn. Keep the lead — what the tool does + how to
  * call it — and drop the embedded reference; agents fetch detail via dedicated
  * schema/help tools at call time. Tunable; big enough to preserve real guidance.
- * ZIG-759.
+ *.
  */
 export declare const MAX_TOOL_DESC_CHARS = 2000;
 /** Truncate one description at a sentence/newline boundary near the cap. */

package/dist/adapters/McpAdapter.js

@@ -1,11 +1,11 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ConnectionsClient } from '@ziggs-ai/api-client';
+import { ConnectionsClient, getBackendUrl } from '@ziggs-ai/api-client';
 import { AgentHost } from '../AgentHost.js';
 import { thinkingDefaults } from '../runtime/defaults.js';
 /**
- * Typed failure from the Ziggs MCP gateway (ZIG-702). `code` is the stable
+ * Typed failure from the Ziggs MCP gateway. `code` is the stable
  * machine-readable reason — e.g. `GRANT_REVOKED`, `GRANT_EXPIRED`,
  * `GRANT_HOLDER_MISMATCH`, `GRANT_CONNECTION_MISMATCH` — so agent code can
  * branch ("revoked → tell the user and stop retrying" vs "network blip →
@@ -56,10 +56,16 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     if (!agentId) {
         throw new Error('ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)');
     }
+    // ZIG-1104: explicit overrides still win, but the LAST resort is
+    // `getBackendUrl()` — the resolution every other SDK call uses — not
+    // `localhost:3000`. The fleet task sets neither BACKEND_URL nor
+    // ZIGGS_BACKEND_URL (it sets HTTP_URL), so the old chain silently pointed every
+    // gateway call at localhost inside the container: the requests never reached the
+    // backend at all, and the agent reported the server as unreachable.
     const baseUrl = (config.baseUrl ||
-        process.env.BACKEND_URL ||
         process.env.ZIGGS_BACKEND_URL ||
-        'http://localhost:3000').replace(/\/$/, '');
+        process.env.BACKEND_URL ||
+        getBackendUrl()).replace(/\/$/, '');
     return {
         url: new URL(`${baseUrl}/connections/${encodeURIComponent(config.connectionId)}/mcp`),
         headers: {
@@ -70,7 +76,7 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     };
 }
 /**
- * Resolve the per-user gateway URL + headers (ZIG-771). No connectionId/grantId —
+ * Resolve the per-user gateway URL + headers. No connectionId/grantId —
  * the gateway resolves the invoking user's own connection + grant from
  * `x-on-behalf-of-user` + the impersonated agent.
  */
@@ -79,17 +85,23 @@ export function resolvePerUserGatewayTarget(config, agentId, userId, onBehalfOfA
     if (!operatorKey) {
         throw new Error('ziggs-per-user MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
     }
+    // ZIG-1104: explicit overrides still win, but the LAST resort is
+    // `getBackendUrl()` — the resolution every other SDK call uses — not
+    // `localhost:3000`. The fleet task sets neither BACKEND_URL nor
+    // ZIGGS_BACKEND_URL (it sets HTTP_URL), so the old chain silently pointed every
+    // gateway call at localhost inside the container: the requests never reached the
+    // backend at all, and the agent reported the server as unreachable.
     const baseUrl = (config.baseUrl ||
-        process.env.BACKEND_URL ||
         process.env.ZIGGS_BACKEND_URL ||
-        'http://localhost:3000').replace(/\/$/, '');
+        process.env.BACKEND_URL ||
+        getBackendUrl()).replace(/\/$/, '');
     return {
         url: new URL(`${baseUrl}/connections/mcp/relay`),
         headers: {
             authorization: `Bearer ${operatorKey}`,
             'x-agent-id': agentId,
             'x-on-behalf-of-user': userId,
-            // ZIG-831: when this call runs under a delegation, userId is the delegating
+            // when this call runs under a delegation, userId is the delegating
             // agent (senderId), not the end-user who owns the connection. The gateway
             // uses this agreement to resolve the delegation root's user.
             ...(onBehalfOfAgreementId ? { 'x-on-behalf-of-agreement': onBehalfOfAgreementId } : {}),
@@ -103,7 +115,7 @@ const CONTROL_TOOL_RESERVE = 4;
 /**
  * How many MCP tools may be bound to the LLM, given the provider cap and the
  * number of extra (non-MCP) tools the agent also carries. Always >= 1 so a
- * pathological config still binds something rather than nothing. ZIG-759.
+ * pathological config still binds something rather than nothing.
  */
 export function mcpToolBudget(maxTools, extraToolCount) {
     return Math.max(1, maxTools - CONTROL_TOOL_RESERVE - extraToolCount);
@@ -218,7 +230,7 @@ function buildDefaultWorkflow(description, mcpTools) {
  * that full block rides every turn. Keep the lead — what the tool does + how to
  * call it — and drop the embedded reference; agents fetch detail via dedicated
  * schema/help tools at call time. Tunable; big enough to preserve real guidance.
- * ZIG-759.
+ *.
  */
 export const MAX_TOOL_DESC_CHARS = 2000;
 /** Truncate one description at a sentence/newline boundary near the cap. */
@@ -230,7 +242,7 @@ export function trimDescription(desc) {
     const head = boundary > MAX_TOOL_DESC_CHARS * 0.6 ? slice.slice(0, boundary + 1) : slice;
     return `${head.trimEnd()} […description truncated; use the server's schema/help tools for full detail]`;
 }
-/** Trim oversized descriptions across the tool set (cost control, ZIG-759). */
+/** Trim oversized descriptions across the tool set (cost control). */
 function trimToolDescriptions(tools, agentId) {
     let trimmedCount = 0;
     let savedChars = 0;
@@ -243,14 +255,14 @@ function trimToolDescriptions(tools, agentId) {
         return { ...t, description: nextDesc };
     });
     if (trimmedCount > 0) {
-        console.warn(`[McpAdapter] ${agentId}: trimmed ${trimmedCount} oversized tool description(s) to ${MAX_TOOL_DESC_CHARS} chars, saving ~${Math.round(savedChars / 4 / 1000)}K tokens/turn. (ZIG-759)`);
+        console.warn(`[McpAdapter] ${agentId}: trimmed ${trimmedCount} oversized tool description(s) to ${MAX_TOOL_DESC_CHARS} chars, saving ~${Math.round(savedChars / 4 / 1000)}K tokens/turn.`);
     }
     return out;
 }
 /**
  * Keep only tools whose name matches one of the allowlist substrings
  * (case-insensitive). No allowlist → pass through unchanged. Applied before the
- * maxTools cap so a targeted agent binds exactly the tools it needs. ZIG-759.
+ * maxTools cap so a targeted agent binds exactly the tools it needs.
  */
 function filterToolsByAllowlist(tools, allowedTools, agentId) {
     if (!allowedTools || allowedTools.length === 0)
@@ -263,7 +275,7 @@ function filterToolsByAllowlist(tools, allowedTools, agentId) {
 /**
  * Cap the tool set bound to the LLM at the provider limit (OpenAI 128) —
  * truncate and log rather than crash — and trim oversized descriptions so the
- * bound schema doesn't ship a manual every turn. ZIG-759 Phase 1. Shared by the
+ * bound schema doesn't ship a manual every turn. Phase 1. Shared by the
  * boot-time (single-client) and per-user paths. When `allowedTools` is set the
  * server's tools are narrowed by name first, so the cap rarely bites.
  */
@@ -273,7 +285,7 @@ function capTools(tools, agentId, maxTools, extraToolCount, allowedTools) {
     const budget = mcpToolBudget(maxTools, extraToolCount);
     if (trimmed.length <= budget)
         return trimmed;
-    console.warn(`[McpAdapter] ${agentId}: MCP server exposes ${trimmed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${budget}, dropping ${trimmed.length - budget}. (ZIG-759 Phase 2 will select per query.)`);
+    console.warn(`[McpAdapter] ${agentId}: MCP server exposes ${trimmed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${budget}, dropping ${trimmed.length - budget}.`);
     return trimmed.slice(0, budget);
 }
 /**
@@ -311,7 +323,7 @@ function capTools(tools, agentId, maxTools, extraToolCount, allowedTools) {
  */
 export async function createMcpAgent(options) {
     const { transport: transportConfig, extraTools = [], workflow, maxTools = DEFAULT_MAX_TOOLS, allowedTools, toolSchema, ...hostOptions } = options;
-    // ── Per-user path (ZIG-771): no boot connection; one MCP client per invoking
+    // ── Per-user path: no boot connection; one MCP client per invoking
     // user, each carrying that user's on-behalf-of header for an isolated session.
     if (transportConfig.type === 'ziggs-per-user') {
         const agentId = transportConfig.agentId || hostOptions.agentId;
@@ -351,12 +363,12 @@ export async function createMcpAgent(options) {
         // When the invoking user hasn't connected this server, open a connection
         // request targeting THEM (X-On-Behalf-Of-User) so the consent prompt lands
         // in their inbox. The backend dedups pending requests, so retrying every
-        // turn is safe. ZIG-771.
+        // turn is safe.
         const backendBase = (transportConfig.baseUrl ||
             process.env.BACKEND_URL ||
             process.env.ZIGGS_BACKEND_URL ||
             'http://localhost:3000').replace(/\/$/, '');
-        // App URL for the user-facing connect link (ZIG-790): api.ziggsai.com → ziggsai.com.
+        // App URL for the user-facing connect link: api.ziggsai.com → ziggsai.com.
         const appUrl = backendBase.includes('localhost')
             ? 'http://localhost:1234'
             : backendBase.replace(/\/\/api\./, '//');
@@ -364,7 +376,7 @@ export async function createMcpAgent(options) {
             ? new URL(transportConfig.serverUrl).host
             : 'the external service';
         // Open a connection request for this user; returns its id so the caller can
-        // deep-link the user straight to it on the Connections page (ZIG-790).
+        // deep-link the user straight to it on the Connections page.
         const triggerConnectionRequest = async (userId) => {
             if (!transportConfig.serverUrl)
                 return null;
@@ -390,11 +402,11 @@ export async function createMcpAgent(options) {
             if (!userId) {
                 throw new Error('per-user MCP tool call requires an invoking user (context.senderId is missing)');
             }
-            // ZIG-831: for a delegated wake, senderId is the delegating agent, not the
+            // for a delegated wake, senderId is the delegating agent, not the
             // connection-owning end-user; pass the agreement so the gateway resolves
             // the delegation root's user.
             const onBehalfOfAgreementId = typeof context.onBehalfOfAgreementId === 'string' ? context.onBehalfOfAgreementId : undefined;
-            // ZIG-832 (B): per-user resolution is intermittently flaky even when the
+            // (B): per-user resolution is intermittently flaky even when the
             // connection is valid and resolvable — the same on-behalf call fails with
             // NO_USER_CONNECTION on one wake and succeeds on the next. clientFor never
             // caches a failed connect, so each attempt re-resolves from scratch. Retry

package/dist/adapters/OpenAIAdapter.js

@@ -137,7 +137,7 @@ export class OpenAIAdapter {
             stream: true,
             // Without this, a streamed completion never returns a usage block — the
             // streamed reply (often the largest output) would bill tokens that are
-            // counted nowhere (ZIG-813). The usage arrives on a final chunk whose
+            // counted nowhere. The usage arrives on a final chunk whose
             // `choices` is empty.
             stream_options: { include_usage: true },
             max_completion_tokens: maxCompletionTokensForModel(this.model),