@ziggs-ai/agent-sdk 0.10.0 → 0.10.2

package/dist/server/polls/PollRunner.js

@@ -0,0 +1,138 @@
+/**
+ * PollRunner — executes declared polls for a whole fleet, outside any host.
+ *
+ * Every host already long-polls its own Ziggs inbox; this applies the same wake
+ * discipline to the sources Ziggs cannot see — mailboxes, feeds, whatever a
+ * PollKind can ask. It runs in the launcher rather than inside any AgentHost
+ * because none of it belongs to a host's message loop: a poll is per
+ * (agent, binding) and carries its own interval, backoff and backpressure.
+ *
+ * One loop per (agent, binding), and each loop AWAITS its own wake before
+ * scheduling the next tick. That is the whole backpressure story: while an
+ * agent is still dealing with what it was woken for, its next poll has not
+ * happened yet, so it cannot be woken twice for the same thing. No in-flight
+ * bookkeeping, no dedup table — the source is authoritative and a poll that
+ * has not run yet cannot report anything stale.
+ *
+ * A failing source backs off exponentially and recovers on the first success.
+ * Without it a source that is down is hit at full rate indefinitely, which is
+ * how you get rate-limited by the thing you were trying to read.
+ */
+import { runtimeLog } from '../../shared/runtimeLog.js';
+import { declaredPolls } from './PollKind.js';
+export class PollRunner {
+    pool;
+    operatorKey;
+    label;
+    maxBackoffMs;
+    wakeTimeoutMs;
+    loops = [];
+    running = false;
+    constructor({ pool, registry, agents, operatorKey, defaultIntervalMs = 60_000, maxBackoffMs = 15 * 60_000, wakeTimeoutMs = Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000), label = 'PollRunner', }) {
+        this.pool = pool;
+        this.operatorKey = operatorKey;
+        this.label = label;
+        this.maxBackoffMs = maxBackoffMs;
+        this.wakeTimeoutMs = wakeTimeoutMs;
+        for (const config of agents) {
+            const agentId = config['agentId'];
+            if (typeof agentId !== 'string' || !agentId)
+                continue;
+            for (const binding of declaredPolls(config)) {
+                const kind = registry.get(binding.kind);
+                if (!kind) {
+                    // Loud, and does not stop the fleet: an agent declaring a kind nobody
+                    // registered would otherwise sit there looking healthy and never wake.
+                    runtimeLog.warn(label, `${agentId} declares unknown poll kind "${binding.kind}" — it will never be woken by it (registered: ${registry.ids.join(', ') || 'none'})`);
+                    continue;
+                }
+                if (!binding.chatId) {
+                    // Refused at startup rather than dropped per-wake: without a lane the
+                    // host's session resolver returns null and the wake disappears with
+                    // only a debug line, which looks exactly like "the source is quiet".
+                    runtimeLog.warn(label, `${agentId} declares poll "${binding.kind}" without a chatId — refusing to register it, because every wake would be silently dropped`);
+                    continue;
+                }
+                this.loops.push({
+                    agentId,
+                    binding,
+                    kind,
+                    intervalMs: kind.intervalMs ?? defaultIntervalMs,
+                    chatId: binding.chatId,
+                    timer: null,
+                    failures: 0,
+                });
+            }
+        }
+    }
+    get size() {
+        return this.loops.length;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        if (!this.loops.length)
+            return;
+        for (const loop of this.loops)
+            this.schedule(loop, 0);
+        runtimeLog.info(this.label, `started — ${this.loops.length} poll(s): ${this.loops.map((l) => `${l.agentId}:${l.kind.id}`).join(', ')}`);
+    }
+    stop() {
+        this.running = false;
+        for (const loop of this.loops) {
+            if (loop.timer)
+                clearTimeout(loop.timer);
+            loop.timer = null;
+        }
+        runtimeLog.info(this.label, 'stopped');
+    }
+    schedule(loop, delayMs = this.nextDelay(loop)) {
+        if (!this.running)
+            return;
+        loop.timer = setTimeout(() => void this.tick(loop), delayMs);
+    }
+    /** Interval while healthy; doubling up to the ceiling while failing. */
+    nextDelay(loop) {
+        if (loop.failures === 0)
+            return loop.intervalMs;
+        return Math.min(loop.intervalMs * 2 ** loop.failures, this.maxBackoffMs);
+    }
+    async tick(loop) {
+        if (!this.running)
+            return;
+        let result;
+        try {
+            result = await loop.kind.poll(loop.binding, {
+                agentId: loop.agentId,
+                ...(this.operatorKey ? { operatorKey: this.operatorKey } : {}),
+            });
+            loop.failures = 0;
+        }
+        catch (err) {
+            loop.failures += 1;
+            runtimeLog.error(this.label, `${loop.agentId}:${loop.kind.id} source failed (${loop.failures}x, next in ${this.nextDelay(loop)}ms): ${err.message}`);
+            this.schedule(loop);
+            return;
+        }
+        if (result?.actionable) {
+            const hint = result.hint ?? `New work from ${loop.kind.id}. Check it.`;
+            try {
+                // Awaited on purpose — see the header. The next tick waits for the
+                // agent to finish, which is what stops a double wake. chatId is what
+                // makes the wake resolve to a lane at all, and wakeTimeoutMs has to
+                // outlast a real multi-turn wake or the await stops meaning anything.
+                await this.pool.sendTo(loop.agentId, hint, { chatId: loop.chatId, pollKind: loop.kind.id }, { timeoutMs: this.wakeTimeoutMs });
+                runtimeLog.info(this.label, `woke ${loop.agentId} for ${loop.kind.id}`);
+            }
+            catch (err) {
+                // Reported separately from a source failure: the source is fine, the
+                // agent is not. Still backs off, because hammering a wedged agent helps
+                // nobody.
+                loop.failures += 1;
+                runtimeLog.error(this.label, `${loop.agentId} wake failed (${loop.failures}x, next in ${this.nextDelay(loop)}ms): ${err.message}`);
+            }
+        }
+        this.schedule(loop);
+    }
+}

package/dist/server/questMatch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ZIG-1185 — exact-match triage for marketplace quests.
+ * Empty match never hits (token-safe default). Comparison is exact after trim.
+ */
+export declare function questExactMatch(match: string, tags: ReadonlyArray<string | null | undefined>): boolean;

package/dist/server/questMatch.js

@@ -0,0 +1,14 @@
+/**
+ * ZIG-1185 — exact-match triage for marketplace quests.
+ * Empty match never hits (token-safe default). Comparison is exact after trim.
+ */
+export function questExactMatch(match, tags) {
+    const needle = typeof match === 'string' ? match.trim() : '';
+    if (!needle)
+        return false;
+    for (const t of tags) {
+        if (typeof t === 'string' && t.trim() === needle)
+            return true;
+    }
+    return false;
+}

package/dist/server/runLauncher.d.ts

@@ -15,14 +15,8 @@ interface SingleOptions {
     onShutdown?: () => Promise<void>;
 }
 interface FleetOptions extends SingleOptions {
-    wsUrl?: string;
     agentMeta?: Record<string, unknown>[];
     primary?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
-    preStart?: string[];
-    poolOptions?: {
-        maxActive?: number;
-        idleTimeoutMs?: number;
-    };
 }
 export declare function runLauncher(configOrConfigs: AgentConfig | AgentConfig[], opts?: FleetOptions): Promise<unknown>;
 export {};

package/dist/server/runLauncher.js

@@ -1,9 +1,39 @@
 import { ConnectionPool } from './ConnectionPool.js';
 import { AgentHost } from '../AgentHost.js';
 import { createHealthServer } from './createHealthServer.js';
-import { createStaleBacklogGate, resolveReplayPolicy } from './staleBacklogGate.js';
 import { boundKeyFleetWarning } from '../shared/operatorKeyClaims.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
+import { PollRegistry } from './polls/PollKind.js';
+import { PollRunner } from './polls/PollRunner.js';
+/**
+ * Collect the poll kinds the agents themselves ship and start a runner for
+ * whatever they declared. This lives in the launcher, not in a caller's
+ * bootstrap file: an agent that declares `polls` and gets no runner sees no
+ * error and simply never wakes, which is indistinguishable from a quiet source.
+ * Every launcher path therefore executes polls, or refuses loudly.
+ */
+function startDeclaredPolls(configs, pool, { operatorKey, label }) {
+    const registry = new PollRegistry();
+    for (const cfg of configs) {
+        for (const kind of (cfg.pollKinds ?? [])) {
+            // Two agents may legitimately share a source; first registration wins and
+            // a duplicate id is not an error worth killing a fleet launch over.
+            if (!registry.get(kind.id))
+                registry.register(kind);
+        }
+    }
+    const runner = new PollRunner({
+        pool,
+        registry,
+        agents: configs,
+        label: `${label}-polls`,
+        ...(operatorKey ? { operatorKey } : {}),
+    });
+    if (runner.size === 0)
+        return null;
+    runner.start();
+    return runner;
+}
 export async function runLauncher(configOrConfigs, opts = {}) {
     if (Array.isArray(configOrConfigs))
         return runFleet(configOrConfigs, opts);
@@ -21,8 +51,11 @@ async function runSingle(config, { operatorKey, label = 'agent', port = process.
         runtimeLog.warn(label, `Agent failed to connect at startup: ${err.message} — will retry`);
     }
     const server = healthServer ? createHealthServer({ port: Number(port), label }) : null;
+    // One agent, so the "pool" is just this host.
+    const pollRunner = startDeclaredPolls([decorated], { sendTo: (_agentId, text, metadata) => agent.handleMessage(text, metadata ?? {}) }, { label, ...(effectiveKey ? { operatorKey: effectiveKey } : {}) });
     process.on('SIGTERM', async () => {
         runtimeLog.info(label, 'SIGTERM — shutting down');
+        pollRunner?.stop();
         agent.disconnect();
         await agent.drain(30_000);
         try {
@@ -36,14 +69,8 @@ async function runSingle(config, { operatorKey, label = 'agent', port = process.
     });
     return { agent, healthServer: server ?? undefined };
 }
-async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, preStart = [], poolOptions, onShutdown, } = {}) {
-    // ZIG-910: don't resurrect stale backlogs at bootstrap. Env-driven default
-    // (FLEET_REPLAY_MAX_AGE / FLEET_REPLAY_STALE); an explicit
-    // poolOptions.shouldLazyStart wins.
-    const pool = new ConnectionPool({
-        shouldLazyStart: createStaleBacklogGate({ ...resolveReplayPolicy(), label }),
-        ...poolOptions,
-    });
+async function runFleet(configs, { operatorKey, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, onShutdown, } = {}) {
+    const pool = new ConnectionPool();
     const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
     const decoratedConfigs = effectiveKey
         ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
@@ -63,10 +90,6 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
         const boundWarning = boundKeyFleetWarning(controlKey, pool.size);
         if (boundWarning)
             runtimeLog.warn(label, boundWarning);
-        pool.startControl({ wsUrl, operatorKey: controlKey });
-    }
-    else {
-        runtimeLog.warn(label, 'No operatorKey provided — skipping fleet inbox poll (no agents will be lazily started)');
     }
     let primary = null;
     if (resolvedPrimaryConfig) {
@@ -76,26 +99,30 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
             runtimeLog.info(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" connected`);
         }
         catch (err) {
-            // Backend may not be ready yet — socket.io reconnects automatically.
-            // Don't crash the process; the primary agent will be live once it reconnects.
+            // Backend may not be ready yet — the inbox long-poll loop retries on
+            // the next pass. Don't crash the process.
             runtimeLog.warn(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" failed to connect at startup: ${err.message} — will retry`);
         }
     }
-    if (preStart.length > 0) {
-        // Pinned: these agents are up because the operator named them
-        // (WAKE_AGENTS), not because work arrived, so the idle sweep must not
-        // retire them. It used to: an empty long-poll isn't "activity", so a quiet
-        // pre-started agent was torn down after idleTimeoutMs and only lazy start
-        // could bring it back — which at fleet size it cannot (ZIG-965 tail).
-        await Promise.all(preStart.map(id => pool.startAgent(id, { pinned: true })
-            .then(() => runtimeLog.debug(label, `Pre-started "${id}" (pinned)`))
-            .catch(err => runtimeLog.warn(label, `Could not pre-start "${id}": ${err.message}`))));
+    // Every registered agent connects (ZIG-1108). There is no roster to consult
+    // and no reason to defer: an agent this launcher was handed is an agent it
+    // hosts, and each host's own inbox long-poll is the only wake signal needed.
+    await pool.connectAll();
+    const connected = pool.listActive().length;
+    if (connected < pool.size) {
+        // Say it loudly and with the number. A launcher that silently hosts fewer
+        // agents than it was given is exactly how three published, hireable agents
+        // ran with no host and nothing noticed (ZIG-1107).
+        runtimeLog.warn(label, `Only ${connected}/${pool.size} agent(s) connected — the rest are registered but unhosted`);
     }
-    runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected` +
-        (pool.listPinned().length ? ` (${pool.listPinned().length} pinned)` : ''));
+    runtimeLog.info(label, `Ready — ${connected}/${pool.size} agent(s) connected`);
+    const pollRunner = startDeclaredPolls(decoratedConfigs, pool, {
+        label,
+        ...(effectiveKey ? { operatorKey: effectiveKey } : {}),
+    });
     process.on('SIGTERM', async () => {
         runtimeLog.info(label, 'SIGTERM — shutting down');
-        pool.stopControl();
+        pollRunner?.stop();
         primary?.disconnect?.();
         await primary?.drain?.(30_000);
         await pool.disconnectAll();

package/dist/server/tools/tier1/protocolRunner.d.ts

@@ -1,6 +1,6 @@
 import type { AgreementService } from '../../agreements/AgreementService.js';
 import type { TaskService } from '../../tasks/TaskService.js';
-import type { WakeWriteKeys } from '../../../types.js';
+import type { DeliveryWriteKeys } from '../../../types.js';
 import { type ContextReadClient } from '@ziggs-ai/api-client';
 interface Services {
     agreementService: AgreementService;
@@ -36,5 +36,7 @@ interface ProtocolPayload {
     })[];
     [key: string]: unknown;
 }
-export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null, wakeKeys?: WakeWriteKeys | null): Promise<unknown>;
+export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null, writeKeys?: DeliveryWriteKeys | null, 
+/** ZIG-1120 #8 — prefer the cached session snapshot over a fresh HTTP read. */
+cachedAgreements?: unknown[]): Promise<unknown>;
 export {};

package/dist/server/tools/tier1/protocolRunner.js

@@ -1,17 +1,9 @@
-import { isBroadcastTarget, linkSummary, } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, } from '@ziggs-ai/api-client';
 import { applyFleetCounterPricing, applyFleetPricingForProtocol, } from '../../../pricing/fleetDefaults.js';
-/**
- * ZIG-957 — same summary shape as MCP link mutations / link_* tools.
- * Raw Mongo money/approvals noise must not reach the LLM on a trust link.
- */
-function shapeAgreementResult(agreement) {
-    if (!agreement)
-        return agreement;
-    return agreement.engagementKind === 'link' ? linkSummary(agreement) : agreement;
-}
-function shapeRevokeResult(result) {
-    return { ...result, agreement: shapeAgreementResult(result.agreement) };
-}
+// ZIG-1111: the link-summary rule lives in AgreementClient, at the point the
+// document is parsed. Every verb here inherits it through the client instead of
+// each one restating `engagementKind === 'link' ? linkSummary(a) : a` — which is
+// how counter, fulfill and subcontract came to return the raw document.
 // Map legacy task-state aliases onto the canonical set.
 function normalizeState(state) {
     if (state === 'done')
@@ -53,7 +45,9 @@ function normalizePlanInPlace(payload) {
         ? 'before_execution'
         : 'with_proposal';
 }
-export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, wakeKeys = null) {
+export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, writeKeys = null, 
+/** ZIG-1120 #8 — prefer the cached session snapshot over a fresh HTTP read. */
+cachedAgreements) {
     if (!payload?.operation)
         return null;
     const { operation } = payload;
@@ -61,22 +55,18 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
     const actorId = actingAgentId?.trim() || null;
     switch (operation) {
         case 'agreement-propose':
-            return proposeAgreement(services, payload, chatId, agents, actorId, wakeKeys);
+            return proposeAgreement(services, payload, chatId, agents, actorId, writeKeys);
         case 'agreement-subcontract':
-            return subcontractAgreement(services, payload, chatId, agents, actorId, wakeKeys);
+            return subcontractAgreement(services, payload, chatId, agents, actorId, writeKeys, cachedAgreements);
         case 'agreement-respond':
             if (!payload.agreementId || !payload.action)
                 return null;
-            return shapeAgreementResult(await agreementService.respond(payload.agreementId, payload.action));
+            return agreementService.respond(payload.agreementId, payload.action);
         case 'agreement-claim': {
             // ZIG-1021: the one claim verb — quest, standing offer, or link invite.
             if (!payload.agreementId)
                 throw new Error('agreement-claim requires `agreementId`');
-            const claimed = await agreementService.claim(payload.agreementId);
-            return {
-                ...claimed,
-                agreement: shapeAgreementResult(claimed.agreement),
-            };
+            return await agreementService.claim(payload.agreementId);
         }
         case 'agreement-counter-proposal':
             if (!payload.agreementId)
@@ -101,16 +91,16 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
         case 'agreement-revoke':
             if (!payload.agreementId)
                 return null;
-            return shapeRevokeResult(await agreementService.revoke(payload.agreementId));
+            return await agreementService.revoke(payload.agreementId);
         case 'agreement-fulfill':
             if (!payload.agreementId)
                 return null;
-            return shapeRevokeResult(await agreementService.fulfill(payload.agreementId));
+            return await agreementService.fulfill(payload.agreementId);
         case 'task-spawn': {
             if (!payload.agreementId || !payload.description)
                 return null;
             let spawnAgreementId = payload.agreementId;
-            const ags = await agreementsInChat(services, chatId);
+            const ags = await agreementsInChat(services, chatId, cachedAgreements);
             // b2 (ZIG-832): if the assignee is not a party on the cited agreement,
             // redirect the spawn to the ACTIVE sub-agreement (same root) where the
             // assignee IS the provider — the orchestrator often cites the top-level
@@ -177,7 +167,7 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
                 // creating a duplicate. Keyed on what is actually written (the resolved
                 // agreement, not the LLM-cited one), so multiple spawns in one wake stay
                 // distinct.
-                idempotencyKey: wakeKeys?.taskSpawnKey({
+                idempotencyKey: writeKeys?.taskSpawnKey({
                     agreementId: spawnAgreementId,
                     description: payload.description,
                     assigneeId: payload.assigneeId,
@@ -194,7 +184,7 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
             const state = normalizeState(terminalRaw);
             // Wake-derived idempotency key: a crash-replay re-issuing this transition
             // no-ops server-side instead of erroring on the already-terminal task.
-            return taskService.updateState(payload.taskId, state, payload.result, wakeKeys?.taskStateKey(payload.taskId, state));
+            return taskService.updateState(payload.taskId, state, payload.result, writeKeys?.taskStateKey(payload.taskId, state));
         }
         case 'task-update-plan-step':
             if (!payload.taskId)
@@ -217,7 +207,7 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
             throw new Error(`Unknown protocol operation: ${operation}`);
     }
 }
-async function proposeAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
+async function proposeAgreement(services, payload, chatId, _agents, actingAgentId, writeKeys = null) {
     if (!payload.description)
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
@@ -229,7 +219,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         if (isBroadcast) {
             throw new Error('A broadcast link is an invite — use link_create_invite instead; propose links to one agent id.');
         }
-        return shapeAgreementResult(await services.agreementService.requestLink(payload.proposedTo, payload.description));
+        return services.agreementService.requestLink(payload.proposedTo, payload.description);
     }
     if (!isBroadcast && !payload.providerId) {
         throw new Error('agreement-propose requires `providerId` — name who does the work: your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient).');
@@ -258,7 +248,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     // propose resolves to the already-created agreement server-side instead of
     // minting a duplicate proposal. Keyed on what the proposal writes, so
     // multiple proposals in one wake stay distinct.
-    const idempotencyKey = wakeKeys?.agreementProposeKey({
+    const idempotencyKey = writeKeys?.agreementProposeKey({
         proposedTo: payload.proposedTo,
         providerId: payload.providerId,
         description: payload.description,
@@ -274,9 +264,15 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
 // rejects with 400 "assignee is not a party". Both are made deterministic here
 // using the chat's existing agreements.
 const TERMINAL_STATUS = new Set(['fulfilled', 'cancelled', 'refunded', 'rejected']);
-async function agreementsInChat(services, chatId) {
+async function agreementsInChat(services, chatId, cachedAgreements) {
     if (!chatId)
         return [];
+    // ZIG-1120 #8 — createZiggsEffectHandler already cached the session snapshot;
+    // prefer that over another GET /context/snapshot just for the agreements array.
+    // Empty array is a real answer ("none in this chat") — do not re-fetch.
+    if (cachedAgreements !== undefined) {
+        return Array.isArray(cachedAgreements) ? cachedAgreements : [];
+    }
     try {
         const snap = await services.contextReadClient.snapshot(chatId, { maxMessages: 1 });
         const ags = snap.agreements;
@@ -305,7 +301,7 @@ function agActive(a) {
 function agIsActiveStatus(a) {
     return String(a.status ?? '') === 'active';
 }
-async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
+async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, writeKeys = null, cachedAgreements) {
     if (!payload.description || !payload.executorId)
         return null;
     // b1 (ZIG-832): idempotent subcontract — if a non-terminal sub-agreement for
@@ -313,7 +309,7 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
     // creating a duplicate (which bloats the chain and blocks the fulfill cascade).
     if (chatId) {
         const parent = payload.parentAgreementId;
-        const existing = (await agreementsInChat(services, chatId)).find((a) => agActive(a) && agIsProvider(a, payload.executorId) &&
+        const existing = (await agreementsInChat(services, chatId, cachedAgreements)).find((a) => agActive(a) && agIsProvider(a, payload.executorId) &&
             (!parent || a.parentAgreementId === parent || a.rootAgreementId === parent));
         if (existing?.agreementId)
             return existing;
@@ -365,7 +361,7 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
     // the b1 reuse check above (e.g. no chatId, or the sub not yet visible in the
     // snapshot) resolves to the already-created sub-agreement server-side instead
     // of minting a duplicate.
-    const idempotencyKey = wakeKeys?.agreementSubcontractKey({
+    const idempotencyKey = writeKeys?.agreementSubcontractKey({
         executorId: payload.executorId,
         description: payload.description,
         parentAgreementId: payload.parentAgreementId ?? '',

package/dist/server/tools/tier1/protocolTools.js

@@ -1,4 +1,5 @@
 import { defineTool } from '../../../tools/defineTool.js';
+import { requireProtocolOperation } from '../../../tasks/protocolRegistry.js';
 import { dispatchProtocolOp } from './protocolRunner.js';
 /** ZIG-957 — keep these enums in lockstep with MCP ziggs_agreement_* / ziggs_task_create. */
 const LIFECYCLE_ENUM = ['open', 'time-bound', 'count-bound'];
@@ -13,7 +14,16 @@ const planReviewTimingParam = {
     enum: [...PLAN_REVIEW_TIMING_ENUM],
     description: 'When the buyer reviews the plan: with_proposal | before_execution',
 };
-function handlerFor(operation) {
+/**
+ * The handler for a protocol verb, looked up by tool name in the registry
+ * (ZIG-1110). Keying off the tool name rather than restating the operation is
+ * what makes half-registration impossible: a verb missing from
+ * PROTOCOL_TOOL_TO_OPERATION throws here, while this module loads, instead of
+ * dispatching correctly and then being unrecognised as protocol at every
+ * consumer that decides whether its result reaches context.
+ */
+function handlerFor(toolName) {
+    const operation = requireProtocolOperation(toolName);
     return async (args, ctx) => {
         const c = ctx;
         if (!c.taskService)
@@ -26,16 +36,16 @@ function handlerFor(operation) {
             taskService: c.taskService,
             agreementService: c.agreementService,
             contextReadClient: c.contextReadClient,
-        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null, c.wakeKeys ?? null);
+        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null, c.writeKeys ?? null, Array.isArray(c.agreements) ? c.agreements : undefined);
         if (result == null)
             throw new Error(`Operation ${operation} returned no result`);
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service', 'link'], description: "Contract type. Defaults to service. 'link' proposes a bilateral trust link (no work, no money)." }, parentAgreementId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals. Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT (any other third party needs a matching published offer). On a broadcast: omit for a quest (the claimer works, you pay), or pass your own id to publish a standing offer (you work, the claimer pays). The payer is always derived as the non-providing side.' }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement-propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a QUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). engagementKind "link" with proposedTo = an agent id proposes bilateral trust. engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
-export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement-subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
-export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement-respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
-export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (quest / offer / link invite id)' } }, handlerFor('agreement-claim'), { description: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.' });
+export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service', 'link'], description: "Contract type. Defaults to service. 'link' proposes a bilateral trust link (no work, no money)." }, parentAgreementId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals. Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT (any other third party needs a matching published offer). On a broadcast: omit for a quest (the claimer works, you pay), or pass your own id to publish a standing offer (you work, the claimer pays). The payer is always derived as the non-providing side.' }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a QUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). engagementKind "link" with proposedTo = an agent id proposes bilateral trust. engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
+export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement_subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
+export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
+export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (quest / offer / link invite id)' } }, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.' });
 export const taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
     // ZIG-957: same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
@@ -45,11 +55,11 @@ export const taskSetResultTool = defineTool('task_set_result', {
         type: 'object',
         description: 'Outcome payload (summary, status, links, …). Finished work is the task result — never a chat message.',
     },
-}, handlerFor('task-update'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Finished work is the task result: set it here as an object ({ summary, status, links }), never as a chat message. Pass state (not status).' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement-counter-proposal'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
-export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-check-proposal'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
-export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
-export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
+}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Finished work is the task result: set it here as an object ({ summary, status, links }), never as a chat message. Pass state (not status).' });
+export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
+export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_get'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
+export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
+export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
 // `status` names its four values here because nothing else does: the backend is
 // the only place the vocabulary was written down, and it now rejects anything
 // outside it. Every reader (the chat step badge, the SDK's own plan formatter)
@@ -64,8 +74,8 @@ export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', {
         enum: ['pending', 'in_progress', 'completed', 'skipped'],
     },
     result: 'string',
-}, handlerFor('task-update-plan-step'), { description: "Update the status of a single step within a task's plan." });
-export const taskCreateTool = defineTool('task_create', { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'ZIG-734: prior-step output artifact handles for structured input links.' }, plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean' }, handlerFor('task-spawn'), { description: 'Create a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' });
+}, handlerFor('task_update_plan_step'), { description: "Update the status of a single step within a task's plan." });
+export const taskCreateTool = defineTool('task_create', { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'Prior-step output artifact handles, for structured input links.' }, plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean' }, handlerFor('task_create'), { description: 'Create a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' });
 export const PROTOCOL_TOOLS = [
     agreementProposeTool, agreementSubcontractTool,
     agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool,

package/dist/server/tools/tier2/connectionTools.js

@@ -7,7 +7,13 @@ import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
 // allowance in the parity table).
 export const connectionProxyTool = toolFromCapability(connectionProxyCapability);
 export const requestConnectionTool = toolFromCapability(requestConnectionCapability);
-export const connectionListGrantsTool = defineTool('connection_list_grants', { connectionId: { type: 'string', required: true } }, async (args, ctx) => {
+export const connectionListGrantsTool = defineTool('connection_list_grants', {
+    connectionId: {
+        type: 'string',
+        required: true,
+        description: 'The stored connection to list grants for.',
+    },
+}, async (args, ctx) => {
     if (!args['connectionId'])
         throw new Error('connectionId is required');
     const operatorKey = ctx?.['operatorKey'];
@@ -28,6 +34,11 @@ export const connectionListGrantsTool = defineTool('connection_list_grants', { c
             wrapped.body = err.body;
         throw wrapped;
     }
+}, {
+    // ZIG-1128: this shipped with no description at all — the model was handed a
+    // name and a parameter and left to guess what the tool was for. Found by the
+    // new SDK tool-text guard.
+    description: "List the grants issued to this agent on one stored connection. Returns the grantId that connection_proxy needs. Use it when you have a connectionId but not the grantId — grant_list (scopeKind=connection) is the wider read across every connection.",
 });
 export const CONNECTION_TOOLS = [
     connectionProxyTool,