@ziggs-ai/agent-sdk 0.10.0 → 0.10.1

package/dist/server/ConnectionPool.d.ts

@@ -1,17 +1,3 @@
-/**
- * ConnectionPool — multi-agent fleet manager.
- *
- * Holds N `AgentHostOptions` configs but only constructs/wakes an
- * `AgentHost` (one WS connection) when needed. Idle hosts are slept after
- * `idleTimeoutMs`. At most `maxActive` hosts are connected at a time; LRU
- * eviction drops the oldest if the cap is reached. With `startControl`, a
- * separate "launcher" socket receives backend-driven wake hints so the pool
- * spins up the right host on demand.
- *
- * This is how a single Node process serves a fleet of agents without
- * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
- */
-import { type InboxOperatorAgentEntry, type StartAgentOptions } from '@ziggs-ai/api-client';
 import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
 interface ConnectionManagerMeta {
     domain?: string;
@@ -24,44 +10,27 @@ interface QueryFilter {
     expertise?: string[];
     tags?: string[];
 }
-export interface PoolOptions {
-    maxActive?: number;
-    idleTimeoutMs?: number;
-    /**
-     * Gate on the operator-poll lazy start (ZIG-910): return false to leave an
-     * actionable agent's host down this pass. Explicit startAgent()s are not gated.
-     */
-    shouldLazyStart?: (entry: InboxOperatorAgentEntry) => boolean;
-}
 export interface SendToOptions {
     timeoutMs?: number;
 }
-export interface ControlOptions {
-    wsUrl?: string;
-    operatorKey?: string;
-}
 export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
     private readonly responseListeners;
-    constructor({ maxActive, idleTimeoutMs, shouldLazyStart }?: PoolOptions);
     /**
-     * Register N agent configs. Each will be lazily started (a fresh
-     * `AgentHost` constructed + connected) the first time it's referenced.
+     * Register N agent configs. Nothing connects until `connectAll()`; a config
+     * registered and never connected is an agent nobody hosts, which is the
+     * failure this pool exists to make impossible.
      */
     register(configs: AgentHostOptions[], metaArr?: ConnectionManagerMeta[]): void;
-    /**
-     * Start (or return) an agent's host. `pinned` keeps it up for the process's
-     * lifetime — no idle sweep, last to be evicted; use it for hosts the operator
-     * named rather than ones work happened to reach.
-     */
-    startAgent(agentId: string, opts?: StartAgentOptions): Promise<AgentHost>;
-    /** Agents kept up explicitly (launcher `preStart`), not by demand. */
-    listPinned(): string[];
+    /** Connect every registered agent. Reports the ones that could not come up. */
+    connectAll(): Promise<void>;
+    /** The host for one agent, connecting it if it somehow is not up yet. */
+    startAgent(agentId: string): Promise<AgentHost>;
     sleep(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
     /**
-     * Start the named agent, deliver a message, and wait for its first outbound
+     * Deliver a message to the named agent and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.
      *
      * The effectTap injected in `register` drains a per-agent listener queue;
@@ -70,28 +39,17 @@ export declare class ConnectionPool {
      */
     requestFrom(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<string>;
     /**
-     * Start the named agent and deliver one wire frame to it. Returns once the
-     * host has finished processing.
+     * Deliver one wire frame to the named agent. Returns once the host has
+     * finished processing.
      *
      * Note: does not return the agent's response. For request/response
      * semantics use `requestFrom`.
      */
     sendTo(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<null>;
-    /**
-     * Start the fleet lazy-start loop (delivery law, phase 4): the manager
-     * long-polls `GET /inbox/operator` with this operator key and starts the host
-     * for any owned agent whose slice has actionable content. Each started host
-     * then consumes via its own per-agent inbox loop — this is ordinary lazy
-     * process management, not a pushed signal. `wsUrl` is accepted for
-     * back-compat but unused (the poll is HTTP).
-     */
-    startControl({ operatorKey }?: ControlOptions): void;
-    stopControl(): void;
     query(filter: QueryFilter): string[];
     list(): string[];
     listActive(): string[];
     get size(): number;
-    get maxActive(): number;
     getMeta(id: string): ConnectionManagerMeta | undefined;
 }
 export {};

package/dist/server/ConnectionPool.js

@@ -1,30 +1,30 @@
 /**
- * ConnectionPool — multi-agent fleet manager.
+ * ConnectionPool — the agents this launcher process hosts.
  *
- * Holds N `AgentHostOptions` configs but only constructs/wakes an
- * `AgentHost` (one WS connection) when needed. Idle hosts are slept after
- * `idleTimeoutMs`. At most `maxActive` hosts are connected at a time; LRU
- * eviction drops the oldest if the cap is reached. With `startControl`, a
- * separate "launcher" socket receives backend-driven wake hints so the pool
- * spins up the right host on demand.
+ * Holds N `AgentHostOptions` configs and connects every one of them at boot
+ * (ZIG-1108). Each host long-polls its own inbox for the life of the process —
+ * there is no agent socket. There is no subset, no cap and no lifecycle policy:
+ * a write releasing that poll is the only signal anything needs.
  *
- * This is how a single Node process serves a fleet of agents without
- * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
+ * What this replaced: a launcher that registered 1000+ configs and connected
+ * ~50, deciding which by long-polling `GET /inbox/operator` for a fleet-wide
+ * sweep, sleeping quiet hosts on an idle timer, evicting past `maxActive` by
+ * LRU, and exempting operator-named agents with a `pinned` flag. Whether an
+ * agent was alive came down to a Terraform string, and nothing noticed when the
+ * answer was "none of them".
  */
 import { ConnectionManager } from '@ziggs-ai/api-client';
 import { AgentHost } from '../AgentHost.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 export class ConnectionPool {
-    manager;
+    manager = new ConnectionManager();
     configs = new Map();
     // Listeners enqueued by requestFrom — drained on outbound send-message effects.
     responseListeners = new Map();
-    constructor({ maxActive = 50, idleTimeoutMs = 60_000, shouldLazyStart } = {}) {
-        this.manager = new ConnectionManager({ maxActive, idleTimeoutMs, shouldLazyStart });
-    }
     /**
-     * Register N agent configs. Each will be lazily started (a fresh
-     * `AgentHost` constructed + connected) the first time it's referenced.
+     * Register N agent configs. Nothing connects until `connectAll()`; a config
+     * registered and never connected is an agent nobody hosts, which is the
+     * failure this pool exists to make impossible.
      */
     register(configs, metaArr = []) {
         const metaByAgentId = new Map();
@@ -46,14 +46,7 @@ export class ConnectionPool {
                 const pool = this;
                 const host = new AgentHost({
                     ...cfg,
-                    // Inbox activity and in-flight effects both reset the idle timer:
-                    // previously only pool.sendTo() touched it, so a host woken by its
-                    // own inbox loop was torn down every idleTimeoutMs (default 60s)
-                    // regardless of the work it was doing — losing lane ctx, Claude
-                    // session ids, and armed timers each time.
-                    onActivity: () => pool.manager.touch(agentId),
                     effectTap(effect, response) {
-                        pool.manager.touch(agentId);
                         if (effect.kind === 'send-message') {
                             const listeners = pool.responseListeners.get(agentId);
                             if (listeners?.length)
@@ -63,25 +56,21 @@ export class ConnectionPool {
                     },
                 });
                 await host.connectAsync();
-                runtimeLog.debug('ConnectionPool', `started "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`);
+                runtimeLog.debug('ConnectionPool', `connected "${agentId}"`);
                 return host;
             }, async (host) => {
                 host.disconnect();
-                runtimeLog.debug('ConnectionPool', `slept "${agentId}"`);
+                runtimeLog.debug('ConnectionPool', `disconnected "${agentId}"`);
             }, metaByAgentId.get(agentId));
         }
     }
-    /**
-     * Start (or return) an agent's host. `pinned` keeps it up for the process's
-     * lifetime — no idle sweep, last to be evicted; use it for hosts the operator
-     * named rather than ones work happened to reach.
-     */
-    async startAgent(agentId, opts = {}) {
-        return await this.manager.startAgent(agentId, opts);
+    /** Connect every registered agent. Reports the ones that could not come up. */
+    async connectAll() {
+        return this.manager.connectAll();
     }
-    /** Agents kept up explicitly (launcher `preStart`), not by demand. */
-    listPinned() {
-        return this.manager.listPinned();
+    /** The host for one agent, connecting it if it somehow is not up yet. */
+    async startAgent(agentId) {
+        return await this.manager.startAgent(agentId);
     }
     async sleep(agentId) {
         return this.manager.sleep(agentId);
@@ -90,7 +79,7 @@ export class ConnectionPool {
         return this.manager.sleepAll();
     }
     /**
-     * Start the named agent, deliver a message, and wait for its first outbound
+     * Deliver a message to the named agent and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.
      *
      * The effectTap injected in `register` drains a per-agent listener queue;
@@ -139,8 +128,8 @@ export class ConnectionPool {
         });
     }
     /**
-     * Start the named agent and deliver one wire frame to it. Returns once the
-     * host has finished processing.
+     * Deliver one wire frame to the named agent. Returns once the host has
+     * finished processing.
      *
      * Note: does not return the agent's response. For request/response
      * semantics use `requestFrom`.
@@ -149,31 +138,11 @@ export class ConnectionPool {
         const host = await this.startAgent(agentId);
         const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`sendTo timeout for "${agentId}" after ${timeoutMs}ms`)), timeoutMs));
         await Promise.race([host.handleMessage(text, metadata), timeoutPromise]);
-        this.manager.touch(agentId);
         return null;
     }
-    /**
-     * Start the fleet lazy-start loop (delivery law, phase 4): the manager
-     * long-polls `GET /inbox/operator` with this operator key and starts the host
-     * for any owned agent whose slice has actionable content. Each started host
-     * then consumes via its own per-agent inbox loop — this is ordinary lazy
-     * process management, not a pushed signal. `wsUrl` is accepted for
-     * back-compat but unused (the poll is HTTP).
-     */
-    startControl({ operatorKey } = {}) {
-        if (!operatorKey) {
-            runtimeLog.warn('ConnectionPool', 'startControl: operatorKey is required — skipping');
-            return;
-        }
-        this.manager.start(operatorKey);
-    }
-    stopControl() {
-        void this.manager.stop();
-    }
     query(filter) { return this.manager.query(filter); }
     list() { return this.manager.list(); }
     listActive() { return this.manager.listActive(); }
     get size() { return this.manager.size; }
-    get maxActive() { return this.manager.maxActive; }
     getMeta(id) { return this.manager.getMeta(id); }
 }

package/dist/server/EventQueue.d.ts

@@ -7,6 +7,12 @@ export interface EventQueueOptions {
  * batch dispatch. The runtime sees at most one in-flight processEvent call
  * per laneKey at a time; multiple events arriving while busy are merged
  * into a single { type: 'batch', events: [...] } frame on the next pass.
+ *
+ * ZIG-1191: `enqueue` REJECTS when the dispatch failed. It used to log the error
+ * and resolve, which made every caller — including the inbox loop, whose next
+ * statement is the ack — unable to tell a handled event from a lost one. A
+ * caller that has nothing to do with a failure should say so with `.catch()`;
+ * the one holding a delivery must not have that decision made for it.
  */
 export declare class EventQueue {
     private _processEvent;

package/dist/server/EventQueue.js

@@ -4,6 +4,12 @@ import { runtimeLog } from '../shared/runtimeLog.js';
  * batch dispatch. The runtime sees at most one in-flight processEvent call
  * per laneKey at a time; multiple events arriving while busy are merged
  * into a single { type: 'batch', events: [...] } frame on the next pass.
+ *
+ * ZIG-1191: `enqueue` REJECTS when the dispatch failed. It used to log the error
+ * and resolve, which made every caller — including the inbox loop, whose next
+ * statement is the ack — unable to tell a handled event from a lost one. A
+ * caller that has nothing to do with a failure should say so with `.catch()`;
+ * the one holding a delivery must not have that decision made for it.
  */
 export class EventQueue {
     _processEvent;
@@ -28,9 +34,12 @@ export class EventQueue {
             state = { events: [], processing: false };
             this._state.set(laneKey, state);
         }
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
             this._metrics.enqueued += 1;
-            state.events.push({ event, resolve });
+            state.events.push({
+                event,
+                settle: (err) => (err === undefined ? resolve() : reject(err)),
+            });
             this._trimQueueIfNeeded(state, laneKey);
             this._processIfNeeded(laneKey);
         });
@@ -49,21 +58,25 @@ export class EventQueue {
         while (state.events.length > 0) {
             const batch = state.events.splice(0, state.events.length);
             const events = batch.map(e => e.event);
-            const resolvers = batch.map(e => e.resolve);
+            const settlers = batch.map(e => e.settle);
             const coalesced = events.length === 1
                 ? events[0]
                 : { type: 'batch', events };
+            // Coalescing makes the batch the unit of success: the lane ran one tick
+            // for all of it, so a failure belongs to every event that was merged in.
+            let failure;
             try {
                 await this._processEvent(coalesced, laneKey);
             }
             catch (error) {
+                failure = error ?? new Error('processEvent failed');
                 this._metrics.errors += 1;
                 runtimeLog.error('EventQueue', `processEvent error for laneKey=${laneKey}: ${error?.message || error}`);
             }
             this._metrics.processedBatches += 1;
             this._metrics.processedEvents += events.length;
-            for (const r of resolvers)
-                r();
+            for (const settle of settlers)
+                settle(failure);
         }
         state.processing = false;
     }
@@ -71,7 +84,9 @@ export class EventQueue {
         while (state.events.length > this._maxQueueLengthPerLane) {
             const dropped = state.events.shift();
             this._metrics.dropped += 1;
-            dropped?.resolve();
+            // A dropped event was never handled, so its caller hears about it — the
+            // inbox loop holds the ack instead of acking work that fell off the queue.
+            dropped?.settle(new Error(`EventQueue dropped an event on laneKey=${laneKey} (queue over ${this._maxQueueLengthPerLane})`));
             runtimeLog.warn('EventQueue', `dropped oldest event laneKey=${laneKey} max=${this._maxQueueLengthPerLane}`);
         }
     }

package/dist/server/SeenMessages.d.ts

@@ -10,4 +10,11 @@ export declare class SeenMessages {
     constructor(maxSize?: number);
     has(messageId: string | null | undefined): boolean;
     mark(messageId: string | null | undefined): void;
+    /**
+     * Forget a mark, so the next delivery of the same id is processed rather than
+     * skipped. ZIG-1191: marking happens BEFORE the work, to hold the door against
+     * a concurrent duplicate — which means a failure has to take the mark back, or
+     * the redelivery that a held ack buys is silently dropped as a duplicate.
+     */
+    unmark(messageId: string | null | undefined): void;
 }

package/dist/server/SeenMessages.js

@@ -28,4 +28,19 @@ export class SeenMessages {
                 this.seen.delete(oldest);
         }
     }
+    /**
+     * Forget a mark, so the next delivery of the same id is processed rather than
+     * skipped. ZIG-1191: marking happens BEFORE the work, to hold the door against
+     * a concurrent duplicate — which means a failure has to take the mark back, or
+     * the redelivery that a held ack buys is silently dropped as a duplicate.
+     */
+    unmark(messageId) {
+        if (!messageId || typeof messageId !== 'string')
+            return;
+        if (!this.seen.delete(messageId))
+            return;
+        const at = this.order.indexOf(messageId);
+        if (at !== -1)
+            this.order.splice(at, 1);
+    }
 }

package/dist/server/ZiggsEffectHandler.d.ts

@@ -67,6 +67,7 @@ export declare function executeToolWithSideEffects(deps: Pick<ZiggsEffectDeps, '
 }>, roster: {
     agents: unknown[];
     users: unknown[];
+    agreements?: unknown[];
 }): Promise<ToolCallResult>;
 /**
  * Build a single shared EffectHandler. The handler is stateful — it caches

package/dist/server/ZiggsEffectHandler.js

@@ -109,7 +109,10 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     const toolT0 = Date.now();
     const args = effect.args || {};
     const argsPreview = previewToolArgs(args);
-    await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
+    // ZIG-1120 #6 — breadcrumbs are best-effort. Awaiting them bracketed every
+    // tool call; a slow/wedged artifacts backend stalled the whole wake. Match
+    // ClaudeSdkAgent thought writes (fire-and-forget).
+    void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
         state: 'started',
         tool: effect.name,
         ...(argsPreview ? { args: argsPreview } : {}),
@@ -142,6 +145,9 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             eff,
             agents: roster.agents,
             users: roster.users,
+            // ZIG-1120 #8 — session snapshot already has agreements; protocolRunner
+            // used to re-fetch them over HTTP on every spawn/subcontract.
+            agreements: roster.agreements ?? [],
             senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
             senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
             onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
@@ -153,7 +159,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         // One clip per tool call: this is a full JSON.stringify of the untruncated
         // result, and the artifact body and the idempotency key want the same string.
         const clipped = clipForOperationArtifact(result);
-        await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
+        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
             state: 'completed',
             tool: effect.name,
             result: clipped,
@@ -171,7 +177,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     catch (error) {
         const errMsg = error?.message ?? String(error);
         runtimeLog.warn('ZiggsEffectHandler', `tool-call "${effect.name}" failed: ${errMsg}`);
-        await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
+        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
@@ -277,14 +283,15 @@ export function createZiggsEffectHandler(deps) {
                 return { text, usage };
             }
             case 'tool-call': {
-                // Roster comes from the cached snapshot (populated by read-context). Both
-                // cognitions land here — the FSM via runTurn's executeTool, the Claude
-                // Agent SDK via the toolManagerToSdkMcp bridge — so tool side effects are
-                // emitted exactly once, in one place (ZIG-775).
+                // Roster + agreements come from the cached snapshot (populated by
+                // read-context). Both cognitions land here — the FSM via runTurn's
+                // executeTool, the Claude Agent SDK via the toolManagerToSdkMcp bridge —
+                // so tool side effects are emitted exactly once, in one place (ZIG-775).
                 const cached = cacheGet(effect.sessionId);
                 return executeToolWithSideEffects(deps, handler, effect, {
                     agents: cached?.agents || [],
                     users: cached?.users || [],
+                    agreements: cached?.agreements || [],
                 });
             }
             case 'send-message': {

package/dist/server/inboxLoop.d.ts

@@ -1,4 +1,4 @@
-import { type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
+import { type InboxQuestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
 import { SeenMessages } from './SeenMessages.js';
 /**
  * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
@@ -26,6 +26,12 @@ export interface InboxLoopDeps {
      * for it (chat-less agreement, self-assigned task).
      */
     onTask?: (task: InboxTaskRef) => Promise<void>;
+    /**
+     * A marketplace quest doorbell (ZIG-1185). The host MUST triage with a plain
+     * string compare and return without an LLM wake on miss — otherwise every
+     * public quest burns a full Claude turn per published supplier.
+     */
+    onQuest?: (quest: InboxQuestRef) => Promise<void>;
     label?: string;
 }
 export interface InboxPassResult {
@@ -35,10 +41,17 @@ export interface InboxPassResult {
     resourceEvents: number;
     /** Assigned open tasks delivered this pass (ZIG-973). */
     tasksDelivered: number;
+    /** Quest refs triaged this pass (ZIG-1185) — includes misses that only ack. */
+    questsTriaged: number;
     /** True when the watermark advanced this pass. */
     acked: boolean;
     /** True when there was more mail than one envelope carries. */
     truncated: boolean;
+    /**
+     * Handovers into the host that failed this pass (ZIG-1191). Non-zero means the
+     * watermark was deliberately held, so the same window arrives again.
+     */
+    failures: number;
 }
 /**
  * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
@@ -46,7 +59,9 @@ export interface InboxPassResult {
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number): Promise<InboxPassResult>;
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, opts?: {
+    forceAck?: boolean;
+}): Promise<InboxPassResult>;
 export interface InboxLoopHandle {
     /** Stop the loop after the current pass; resolves when it has fully exited. */
     stop(): Promise<void>;