@ziggs-ai/agent-sdk 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.10.0 — unreleased
+
+### 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.
+- `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`.
+
+### Added
+
+- Declared polls: an agent names the external sources it depends on (`polls`, `pollKinds`) and never executes them. New exports `PollRunner`, `PollRegistry`, `declaredPolls`, and types `PollBinding`, `PollContext`, `PollKind`, `PollResult`, `PollRunnerOptions`, `WakeTarget`. `runLauncher` runs declared polls at fleet level — outside any `AgentHost`, because a host is evicted when idle and that is exactly when its source still needs watching.
+
+### Changed
+
+- 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).
+
 ## 0.9.0 — 2026-07-30
 
 ### Changed (breaking)

package/dist/AgentHost.d.ts

@@ -71,8 +71,17 @@ export interface AgentHostOptions {
     agentId?: string;
     name?: string | null;
     wsUrl?: string;
+    /** Store-facing one-liner. See DefineAgentInput.description. */
     description?: string;
+    /** Claude-brain system prompt (ZIG-1080); falls back to `description`. */
+    systemPrompt?: string;
     specialization?: string | null;
+    /**
+     * ZIG-1185 — strings compared exactly against a quest's `match` field.
+     * Miss → ack with zero LLM. Match → normal wake. `specialization` is also
+     * checked when set.
+     */
+    questMatchTags?: string[];
     tools?: ToolDefinition[];
     taskTools?: 'all' | 'none' | string[];
     /**
@@ -117,14 +126,6 @@ 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;
-    /**
-     * Liveness signal: called whenever the host receives or processes work (an
-     * inbox message or resource event delivered to a lane). Hosting pools use it
-     * to reset their idle-eviction timer — without it a host that is actively
-     * working (but never addressed via pool.sendTo) is torn down mid-stream at
-     * the idle timeout, discarding lane state, Claude session ids, and timers.
-     */
-    onActivity?: () => void;
     /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
     transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
     /**
@@ -195,11 +196,54 @@ export declare class AgentHost {
     handleResourceEvent(event: Record<string, unknown>): Promise<void>;
     /** 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.
+     *
+     * 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
+     * 2026-08-03 a cancelled hand-off woke its lane once for 92k tokens, and on
+     * 08-04 the same shape cost 147k with the session reaching 399,864 input tokens
+     * before it reset. Nothing was produced either time — the work had finished and
+     * the contract was gone.
+     *
+     * So a lane whose agreement is terminal does not get a turn. The event is still
+     * consumed (and acked by the inbox loop), the FSM is untouched, and a chat lane
+     * is never affected: only the agreement-scoped routing key is checked.
+     *
+     * Failing open is deliberate. If the lookup errors we run the turn — a missed
+     * suppression costs tokens, while a wrongly suppressed turn drops work.
+     */
+    private laneAgreementIsTerminal;
+    /**
+     * ZIG-1153 — 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
+     * it, and produced nothing — the spec had been written and the task closed one
+     * frame earlier.
+     *
+     * A task frame that carries a terminal state AND a result is an echo of work
+     * this agent has already finished: there is no decision left in it. Dropping it
+     * is not the same suppression as {@link laneAgreementIsTerminal}, which waits
+     * for the agreement to end — this fires while the engagement is still live,
+     * which is where the cost actually was.
+     *
+     * Deliberately narrow: only a `task_result` frame, only with a terminal state,
+     * and only when a result is attached. A completed task with no result recorded
+     * still gets its turn, because that is an agent with something left to say.
+     */
+    private isSettledTaskEcho;
     private _processEvent;
     /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
     private _armIfTimedParked;
     private _resolveOwnAgentId;
     connectAsync(_timeout?: number): Promise<this>;
+    /**
+     * ZIG-1185 — 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). */
     wakeTaskAssignment(taskId: string): Promise<void>;
@@ -214,10 +258,5 @@ export declare class AgentHost {
  * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
  */
 export declare function createAgent(options?: AgentHostOptions | AgentConfig): AgentHost;
-export declare function createAgentPool(configs: AgentHostOptions[] | AgentConfig[], opts?: {
-    poolOptions?: {
-        maxActive?: number;
-        idleTimeoutMs?: number;
-    };
-}): Promise<unknown>;
+export declare function createAgentPool(configs: AgentHostOptions[] | AgentConfig[]): Promise<unknown>;
 export default AgentHost;

package/dist/AgentHost.js

@@ -18,6 +18,7 @@ import { ArtifactsClient, ContextReadClient, TelemetryClient, sendChatMessage, }
 import { TaskService } from './server/tasks/TaskService.js';
 import { AgreementService } from './server/agreements/AgreementService.js';
 import { runInboxLoop } from './server/inboxLoop.js';
+import { questExactMatch } from './server/questMatch.js';
 import { SeenMessages } from './server/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 /**
@@ -90,7 +91,12 @@ function createBackendServices(options) {
     const agentId = options.agentId;
     const artifactsClient = new ArtifactsClient(operatorKey, agentId);
     const contextReadClient = new ContextReadClient(operatorKey, agentId);
-    const promptBuilder = new PromptBuilder({ description: options.description, specialization: options.specialization });
+    // ZIG-1080: 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,
+        specialization: options.specialization,
+    });
     const taskService = new TaskService(operatorKey, agentId);
     const agreementService = new AgreementService(operatorKey, agentId);
     const telemetryClient = new TelemetryClient(operatorKey, agentId);
@@ -145,6 +151,7 @@ export class AgentHost {
             name: resolved.name || null,
             wsUrl: resolved.wsUrl,
             description: resolved.description || 'A helpful assistant',
+            systemPrompt: resolved.systemPrompt,
             specialization: resolved.specialization ?? null,
             tools: resolved.tools || [],
             taskTools: resolved.taskTools,
@@ -268,6 +275,7 @@ export class AgentHost {
                 workflow,
                 toolManager: services.toolManager,
                 description: this.options.description,
+                systemPrompt: this.options.systemPrompt,
                 specialization: this.options.specialization,
                 model: resolveClaudeModel(this.options.model, this.options.services?.llm?.model),
                 anthropicKey: this.options.anthropicKey,
@@ -285,7 +293,14 @@ export class AgentHost {
                 promptBuilder: services.promptBuilder,
             });
         this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
-        this.stateTimers = new StateTimers((ev, laneKey) => { void this.eventQueue.enqueue(ev, 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).
+        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}`);
+            });
+        });
     }
     /**
      * Handler for a resource change (artifact created, task state transition,
@@ -364,12 +379,96 @@ export class AgentHost {
         // The inbox loop owns ack (act-before-ack, delivery law); the host only
         // routes the event onto its lane. No live-path watermark ack — there is no
         // separate live/push channel to reconcile against anymore.
-        return this.eventQueue.enqueue(normalized.event, laneKey);
+        //
+        // ZIG-1191: 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 {
+            await this.eventQueue.enqueue(normalized.event, laneKey);
+        }
+        catch (err) {
+            if (messageId)
+                this.seenMessages.unmark(messageId);
+            throw err;
+        }
+    }
+    /**
+     * ZIG-1144 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
+     * 2026-08-03 a cancelled hand-off woke its lane once for 92k tokens, and on
+     * 08-04 the same shape cost 147k with the session reaching 399,864 input tokens
+     * before it reset. Nothing was produced either time — the work had finished and
+     * the contract was gone.
+     *
+     * So a lane whose agreement is terminal does not get a turn. The event is still
+     * consumed (and acked by the inbox loop), the FSM is untouched, and a chat lane
+     * is never affected: only the agreement-scoped routing key is checked.
+     *
+     * Failing open is deliberate. If the lookup errors we run the turn — a missed
+     * suppression costs tokens, while a wrongly suppressed turn drops work.
+     */
+    async laneAgreementIsTerminal(sessionId) {
+        if (!sessionId.startsWith('agrn-'))
+            return false;
+        const agreementId = sessionId.slice('agrn-'.length);
+        if (!agreementId || !this.agreementService)
+            return false;
+        try {
+            const agreement = await this.agreementService.get(agreementId);
+            const status = String(agreement?.status ?? '');
+            return (status === 'cancelled' || status === 'refunded' || status === 'fulfilled');
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * ZIG-1153 — 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
+     * it, and produced nothing — the spec had been written and the task closed one
+     * frame earlier.
+     *
+     * A task frame that carries a terminal state AND a result is an echo of work
+     * this agent has already finished: there is no decision left in it. Dropping it
+     * is not the same suppression as {@link laneAgreementIsTerminal}, which waits
+     * for the agreement to end — this fires while the engagement is still live,
+     * which is where the cost actually was.
+     *
+     * Deliberately narrow: only a `task_result` frame, only with a terminal state,
+     * and only when a result is attached. A completed task with no result recorded
+     * still gets its turn, because that is an agent with something left to say.
+     */
+    isSettledTaskEcho(event) {
+        const frame = event;
+        if (frame?.type !== 'task_result')
+            return false;
+        const result = frame.result;
+        if (!result)
+            return false;
+        const state = String(result.state ?? '');
+        if (state !== 'completed' && state !== 'cancelled' && state !== 'failed') {
+            return false;
+        }
+        const reported = result.result;
+        return reported !== undefined && reported !== null && reported !== '';
     }
     async _processEvent(event, laneKey) {
         const session = this.sessions.get(laneKey);
         if (!session?.sessionId)
             return;
+        if (await this.laneAgreementIsTerminal(session.sessionId)) {
+            runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its agreement is terminal`);
+            return;
+        }
+        if (this.isSettledTaskEcho(event)) {
+            runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its task already reported a result`);
+            return;
+        }
         // Stale timer frames (superseded epoch) are dropped BEFORE touching the
         // live timer — a pure-stale frame must not reset a freshly armed countdown.
         const frame = this.stateTimers.stripStale(event, laneKey);
@@ -472,6 +571,13 @@ 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 —
+            // 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
+            // notifications were acked after failing, so nothing ever redelivered
+            // them and a claim stayed blocked on consent that no wake would give.
+            throw err;
         }
         finally {
             clearTimeout(tickWatchdog);
@@ -510,18 +616,15 @@ export class AgentHost {
                 seen: this.seenMessages,
                 label,
                 onMessage: (text, metadata) => {
-                    this.options.onActivity?.();
                     return this.handleMessage(text, metadata);
                 },
                 onResourceEvent: (event) => {
-                    this.options.onActivity?.();
                     return this.handleResourceEvent(event);
                 },
                 // ZIG-973: 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) => {
-                    this.options.onActivity?.();
                     try {
                         await this.wakeTaskAssignment(task.taskId);
                     }
@@ -529,10 +632,35 @@ 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.
+                onQuest: async (quest) => {
+                    await this.triageQuestDelivery(quest);
+                },
             });
         }
         return this;
     }
+    /**
+     * ZIG-1185 — plain string compare against {@link AgentHostOptions.questMatchTags}
+     * and `specialization`. No match → return (caller acks). Match → normal wake.
+     */
+    async triageQuestDelivery(quest) {
+        const tags = [
+            ...(this.options.questMatchTags ?? []),
+            ...(this.options.specialization ? [this.options.specialization] : []),
+        ];
+        if (!questExactMatch(quest.match, tags)) {
+            runtimeLog.debug(this.options.name || 'agent', `quest ${quest.agreementId}: no tag match for ${JSON.stringify(quest.match)} — ack without wake`);
+            return;
+        }
+        const needle = quest.match.trim();
+        const title = quest.title?.trim() || needle;
+        await this.handleMessage(`New marketplace quest matching your tags (${needle}): ${title}. Claim with agreement_claim if you will take it.`, {
+            messageId: `quest-wake:${quest.agreementId}:${quest.ts}`,
+            chatId: `marketplace:${quest.agreementId}`,
+            agreementId: quest.agreementId,
+        });
+    }
     async _bootstrapAssignedActiveTasks() {
         const agentId = this.options.agentId;
         if (!agentId || !this.taskService)
@@ -619,10 +747,11 @@ export class AgentHost {
 export function createAgent(options = {}) {
     return new AgentHost(options);
 }
-export async function createAgentPool(configs, opts = {}) {
+export async function createAgentPool(configs) {
     const ConnectionPool = await loadConnectionPool();
-    const pool = new ConnectionPool(opts.poolOptions);
+    const pool = new ConnectionPool();
     pool.register(configs);
+    await pool.connectAll();
     return pool;
 }
 export default AgentHost;

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -15,13 +15,21 @@ import type { TickInput, TickOutput } from './Agent.js';
  * `notification` only.
  *
  * Empty / missing batch → notice-only (do not burn a turn on a malformed wake).
+ *
+ * A message addressed to a DIFFERENT party is notice-only too (attention
+ * gate): the sender named who should act, and it wasn't this agent. The
+ * message still lands in chat history and arrives as context on the next
+ * real wake — skipped here is the LLM turn, not the information.
  */
-export declare function isNoticeOnlyWake(event: RawEvent | undefined): boolean;
+export declare function isNoticeOnlyWake(event: RawEvent | undefined, ownAgentId?: string | null): boolean;
 export type CognitionKind = 'fsm' | 'claude-sdk';
 export interface ClaudeSdkAgentOptions {
     workflow: Workflow;
     toolManager: ToolManager;
+    /** Store-facing one-liner. Used as the role block only when `systemPrompt` is absent. */
     description: string;
+    /** The agent's system prompt (ZIG-1080). Preferred over `description` for the role block. */
+    systemPrompt?: string;
     specialization?: string | null;
     model: string;
     anthropicKey: string;
@@ -35,6 +43,16 @@ export interface ClaudeSdkAgentOptions {
     /** Injectable for tests. Defaults to @anthropic-ai/claude-agent-sdk query(). */
     queryFn?: typeof query;
 }
+/**
+ * ZIG-1191 — "the transcript you asked me to resume is not here".
+ *
+ * Claude Code answers a `resume` of an unknown id with this, and it is the only
+ * failure that a fresh session reliably fixes: the id is valid-looking but its
+ * transcript lived on a container that is gone. Matched on the message because
+ * that is all the CLI gives us — no code, no typed error — so keep it narrow
+ * enough that a different failure never claims the retry.
+ */
+export declare function isMissingSessionError(err: unknown): boolean;
 /**
  * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`
  * side channel, same tool surface as the FSM `Agent` — the ONLY difference is
@@ -44,7 +62,7 @@ export interface ClaudeSdkAgentOptions {
 export declare class ClaudeSdkAgent {
     workflow: Workflow;
     toolManager: ToolManager;
-    private description;
+    private rolePrompt;
     private specialization;
     private model;
     private anthropicKey;
@@ -53,6 +71,13 @@ export declare class ClaudeSdkAgent {
     private maxTurns;
     private statelessPerWake;
     private queryFn;
+    /**
+     * ZIG-1120 #7 — tool set is fixed at host construction; rebuilding the
+     * in-process MCP server (+ zod schema tree) every wake was pure waste.
+     * A mutable holder supplies per-wake context without closing over `tick`.
+     */
+    private toolContextHolder;
+    private sdkMcpServer;
     constructor(opts: ClaudeSdkAgentOptions);
     tick({ event, ctx, state, identity, eff, signal }: TickInput): Promise<TickOutput>;
 }