@ziggs-ai/agent-sdk 0.10.0 → 0.10.1

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

@@ -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, wakeKeys?: WakeWriteKeys | 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, wakeKeys = null, 
+/** ZIG-1120 #8 — prefer the cached session snapshot over a fresh HTTP read. */
+cachedAgreements) {
     if (!payload?.operation)
         return null;
     const { operation } = payload;
@@ -63,20 +57,16 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
         case 'agreement-propose':
             return proposeAgreement(services, payload, chatId, agents, actorId, wakeKeys);
         case 'agreement-subcontract':
-            return subcontractAgreement(services, payload, chatId, agents, actorId, wakeKeys);
+            return subcontractAgreement(services, payload, chatId, agents, actorId, wakeKeys, 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
@@ -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).');
@@ -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, wakeKeys = 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;

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.wakeKeys ?? 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,

package/dist/tasks/protocolRegistry.d.ts

@@ -1,3 +1,23 @@
+/**
+ * The protocol verbs and the state operation each one performs.
+ *
+ * This is the single place the set is written down (ZIG-1110). It used to be
+ * restated: the tool definitions passed their operation string to `handlerFor`
+ * by hand, and this table listed them again. `agreement_fulfill` was in the
+ * first list and not the second, so it dispatched fine but
+ * `isProtocolToolName` said no — and at every consumer (applyEffects,
+ * routingLabels, buildOutcome) the verb that ends an engagement permanently
+ * degraded to an unlabelled plain tool-result whose outcome never reached
+ * context.
+ *
+ * A protocol tool now takes its handler from this table BY TOOL NAME, and a
+ * name that is absent throws while the module is loading. Adding a verb in one
+ * place can no longer half-register it: the tool cannot be constructed at all
+ * until it appears here.
+ *
+ * This module deliberately imports nothing. It is read from the context and
+ * runtime paths, which must not pull in the server tool chain.
+ */
 export declare const PROTOCOL_TOOL_TO_OPERATION: Readonly<{
     readonly agreement_propose: "agreement-propose";
     readonly agreement_subcontract: "agreement-subcontract";
@@ -6,6 +26,7 @@ export declare const PROTOCOL_TOOL_TO_OPERATION: Readonly<{
     readonly agreement_counter: "agreement-counter-proposal";
     readonly agreement_get: "agreement-check-proposal";
     readonly agreement_revoke: "agreement-revoke";
+    readonly agreement_fulfill: "agreement-fulfill";
     readonly task_create: "task-spawn";
     readonly task_set_result: "task-update";
     readonly task_update_plan_step: "task-update-plan-step";
@@ -15,3 +36,9 @@ export type ProtocolOperation = (typeof PROTOCOL_TOOL_TO_OPERATION)[ProtocolTool
 export declare const PROTOCOL_TOOL_NAMES: readonly ProtocolToolName[];
 export declare function mapProtocolToolToOperation(toolName: string): ProtocolOperation | null;
 export declare function isProtocolToolName(toolName: string): toolName is ProtocolToolName;
+/**
+ * The operation a protocol tool performs, or a throw. Called at module load by
+ * the tool definitions, so a verb defined without a registry entry takes the
+ * import down instead of shipping half-registered.
+ */
+export declare function requireProtocolOperation(toolName: string): ProtocolOperation;

package/dist/tasks/protocolRegistry.js

@@ -1,3 +1,23 @@
+/**
+ * The protocol verbs and the state operation each one performs.
+ *
+ * This is the single place the set is written down (ZIG-1110). It used to be
+ * restated: the tool definitions passed their operation string to `handlerFor`
+ * by hand, and this table listed them again. `agreement_fulfill` was in the
+ * first list and not the second, so it dispatched fine but
+ * `isProtocolToolName` said no — and at every consumer (applyEffects,
+ * routingLabels, buildOutcome) the verb that ends an engagement permanently
+ * degraded to an unlabelled plain tool-result whose outcome never reached
+ * context.
+ *
+ * A protocol tool now takes its handler from this table BY TOOL NAME, and a
+ * name that is absent throws while the module is loading. Adding a verb in one
+ * place can no longer half-register it: the tool cannot be constructed at all
+ * until it appears here.
+ *
+ * This module deliberately imports nothing. It is read from the context and
+ * runtime paths, which must not pull in the server tool chain.
+ */
 export const PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
     agreement_propose: 'agreement-propose',
     agreement_subcontract: 'agreement-subcontract',
@@ -6,6 +26,7 @@ export const PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
     agreement_counter: 'agreement-counter-proposal',
     agreement_get: 'agreement-check-proposal',
     agreement_revoke: 'agreement-revoke',
+    agreement_fulfill: 'agreement-fulfill',
     task_create: 'task-spawn',
     task_set_result: 'task-update',
     task_update_plan_step: 'task-update-plan-step',
@@ -19,3 +40,18 @@ export function mapProtocolToolToOperation(toolName) {
 export function isProtocolToolName(toolName) {
     return mapProtocolToolToOperation(toolName) != null;
 }
+/**
+ * The operation a protocol tool performs, or a throw. Called at module load by
+ * the tool definitions, so a verb defined without a registry entry takes the
+ * import down instead of shipping half-registered.
+ */
+export function requireProtocolOperation(toolName) {
+    const operation = mapProtocolToolToOperation(toolName);
+    if (!operation) {
+        throw new Error(`Unknown protocol tool "${toolName}": add it to PROTOCOL_TOOL_TO_OPERATION ` +
+            '(agent-sdk/src/tasks/protocolRegistry.ts). Every consumer of the protocol ' +
+            'set reads that table — a tool missing from it dispatches but is never ' +
+            'recognised as protocol, so its result never reaches context.');
+    }
+    return operation;
+}

package/dist/types.d.ts

@@ -187,15 +187,6 @@ export interface Ctx {
     /** Focus agreement — sync'd with tasks[activeTaskId] when a task is focused. */
     activeAgreementId: string | null;
     pendingProposalAgreementId: string | null;
-    /**
-     * @deprecated ZIG-1057 — unused mirrors; always `{}` / `[]` after bootstrap.
-     * Read via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`.
-     */
-    pendingSubtasks: Record<string, PendingSubtask>;
-    /** @deprecated ZIG-1057 — see `pendingSubtasks`. */
-    collectedResults: CollectedSubtaskResult[];
-    /** @deprecated ZIG-1057 — see `pendingSubtasks`. */
-    delegatedAgreementIds: string[];
     toolResults: ToolResultEntry[];
     lastOutcome: Outcome;
     /** Claude Agent SDK session id for resume across ticks (claude-sdk cognition only). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.9.0",
+    "@ziggs-ai/api-client": "^0.9.1",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",

package/dist/server/staleBacklogGate.d.ts

@@ -1,57 +0,0 @@
-/**
- * Launcher startup backlog policy (ZIG-910).
- *
- * "Work waits" has no statute of limitations on the backend — the inbox never
- * expires anything. But when a fleet comes up after a dark period, replaying
- * every weeks-old actionable slice means a mass of LLM turns on stale work at
- * real token cost. The consumer chooses what to pick up: this gate keeps the
- * operator-poll lazy start from resurrecting agents whose newest actionable
- * item is older than a cutoff. Skips are never silent — one loud aggregated
- * summary line announces what was left down and how to opt back in.
- *
- * Env:
- *   FLEET_REPLAY_MAX_AGE  cutoff, e.g. "3d" | "12h" | "30m" | bare number =
- *                         days (default "3d")
- *   FLEET_REPLAY_STALE=1  replay everything (disable the gate)
- *
- * Scope is the launcher only. The backend inbox is untouched, explicit
- * `pool.startAgent()` / preStart are untouched, and an agent with ANY fresh item
- * starts normally (its own inbox loop then drains the stale backlog too).
- */
-import type { InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
-export declare const DEFAULT_REPLAY_MAX_AGE_MS: number;
-export interface ReplayPolicy {
-    /** Skip slices whose newest actionable item is older than this. */
-    maxAgeMs: number;
-    /** FLEET_REPLAY_STALE=1 — replay everything, gate disabled. */
-    replayAll: boolean;
-}
-/**
- * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
- * granularity). Returns null on garbage so the caller can warn and fall back.
- */
-export declare function parseReplayMaxAge(raw: string): number | null;
-export declare function resolveReplayPolicy(env?: NodeJS.ProcessEnv): ReplayPolicy;
-/**
- * Newest actionable instant for an agent, from its operator-sweep entry.
- *
- * The sweep hands this over directly now — it is the agent's delivery
- * watermark — where this used to fold together the max timestamp across every
- * channel of a whole envelope. An agent surfaced only for open work carries no
- * delivery instant: age is unprovable, so it is treated as fresh and started.
- * Stale-skipping a half-finished task would strand it.
- */
-export declare function newestActionableAt(entry: InboxOperatorAgentEntry): number | null;
-export declare function formatAge(ms: number): string;
-export interface StaleBacklogGateOptions extends ReplayPolicy {
-    label?: string;
-    now?: () => number;
-    log?: (line: string) => void;
-}
-/**
- * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
- * resurface in every envelope (reading never acks), so announcements are
- * per-agent-once: each poll pass that skips agents not yet announced emits one
- * aggregated warn line covering them.
- */
-export declare function createStaleBacklogGate({ maxAgeMs, replayAll, label, now, log, }: StaleBacklogGateOptions): (entry: InboxOperatorAgentEntry) => boolean;