@ziggs-ai/agent-sdk 0.5.0 → 0.7.0

package/dist/server/inboxLoop.js

@@ -1,5 +1,6 @@
-import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, } from '@ziggs-ai/api-client';
+import { ContextReadClient, InboxClient, } from '@ziggs-ai/api-client';
 import { runtimeLog } from '../shared/runtimeLog.js';
+import { isRateLimited } from '@ziggs-ai/api-client';
 const READ_PAGE = 100;
 function log(label, msg) {
     runtimeLog.info(label, msg);
@@ -7,67 +8,61 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
-async function chatIdsForScope(scope, creds, grants) {
-    const { kind, id } = scope.scope;
-    switch (kind) {
-        case 'chat':
-            return [id];
-        case 'agreement': {
-            const links = (await getChatsForAgreement(id, creds));
-            return [...new Set(links.map((l) => l.chatId).filter(Boolean))];
-        }
-        case 'org': {
-            // All pages of live chat grants — an org-scope read must not miss chats
-            // hidden behind pagination (GET /grants defaults to one page).
-            const items = await grants.listAllGrants({
-                scopeKind: 'chat',
-                health: 'active',
-            });
-            return [...new Set(items.map((g) => g.scope.id))];
-        }
-        default:
-            return [];
-    }
-}
-async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
+/**
+ * Read the messages behind one chat's deliveries and hand them to the host.
+ *
+ * The envelope says which chat and how many, not the bodies — so this still
+ * reads through `/context/read`, where the agent's own grants fence what it is
+ * allowed to see. A delivery reference is an address, never an authorisation.
+ */
+async function deliverMessagesForChat(deps, news, earliestTs, reader) {
     let delivered = 0;
-    const label = deps.label ?? 'inboxLoop';
-    const expected = scope.newMessages;
-    let remaining = expected >= countCap ? Number.POSITIVE_INFINITY : expected;
-    for (const chatId of chatIds) {
-        if (remaining <= 0)
-            break;
-        let after = scope.since;
-        let pages = 0;
-        const maxPages = 20;
-        while (remaining > 0 && pages < maxPages) {
-            const limit = Math.min(READ_PAGE, remaining === Number.POSITIVE_INFINITY ? READ_PAGE : remaining);
-            const page = await reader.read('messages', {
-                via: `chat:${chatId}`,
+    let remaining = news.count;
+    // `after` is exclusive, so step back a millisecond to include the oldest
+    // delivery itself. Re-reading a neighbour that shares its timestamp is
+    // harmless — `seen` dedups by messageId.
+    let after = new Date(Date.parse(earliestTs) - 1).toISOString();
+    let pages = 0;
+    const maxPages = 20;
+    while (remaining > 0 && pages < maxPages) {
+        const limit = Math.min(READ_PAGE, remaining);
+        let page;
+        try {
+            page = await reader.read('messages', {
+                via: `chat:${news.chatId}`,
                 after,
                 direction: 'forward',
                 limit,
             });
-            for (const row of page.items) {
-                const messageId = String(row.messageId ?? '');
-                if (deps.seen.has(messageId))
-                    continue;
-                const text = typeof row.text === 'string' ? row.text : '';
-                if (!text.trim())
-                    continue;
-                await deps.onMessage(text, { ...row, chatId });
-                delivered++;
-                if (remaining !== Number.POSITIVE_INFINITY)
-                    remaining--;
-            }
-            if (!page.hasMore || !page.latestSequence)
-                break;
-            after = page.latestSequence;
-            pages++;
         }
-    }
-    if (delivered < expected && expected >= countCap) {
-        warn(label, `scope ${scope.scope.kind}:${scope.scope.id} may be incomplete (count cap)`);
+        catch (err) {
+            const status = err.status;
+            if (status !== 403 && status !== 404)
+                throw err;
+            // Addressed but not readable. Since the delivery log and the grants are
+            // now separate, the two can disagree — a grant revoked between the write
+            // and this read, or a chat since deleted. Skipping keeps the pass alive
+            // so the rest of the mail is delivered and the watermark still advances;
+            // failing here would wedge the agent on one unreadable item forever,
+            // re-woken by the same delivery on every pass.
+            warn(deps.label ?? 'inboxLoop', `chat ${news.chatId}: addressed but not readable (${status}) — skipping ${remaining} delivery/deliveries`);
+            return delivered;
+        }
+        for (const row of page.items) {
+            const messageId = String(row.messageId ?? '');
+            if (deps.seen.has(messageId))
+                continue;
+            const text = typeof row.text === 'string' ? row.text : '';
+            if (!text.trim())
+                continue;
+            await deps.onMessage(text, { ...row, chatId: news.chatId });
+            delivered++;
+            remaining--;
+        }
+        if (!page.hasMore || !page.latestSequence)
+            break;
+        after = page.latestSequence;
+        pages++;
     }
     return delivered;
 }
@@ -81,51 +76,77 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
     const label = deps.label ?? 'inboxLoop';
     const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
-    const grants = new GrantsClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const envelope = await inbox.getInbox(waitSeconds > 0 ? { waitSeconds } : {});
-    const countCap = envelope.countCap;
     let messagesDelivered = 0;
     let resourceEvents = 0;
-    const toAck = [];
-    if (envelope.truncatedScopes > 0) {
-        // Informational only — does NOT block acking the scopes returned below.
-        // truncatedScopes just means the caller's total reach exceeded the server's
-        // per-call scope cap; each returned scope is still an independently accurate,
-        // safe-to-ack unit of news. Never acking here would make a busy agent
-        // (reach > cap) re-deliver its whole backlog every pass forever.
-        warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} (reach exceeds per-call cap — examined scopes are still acked normally)`);
+    let tasksDelivered = 0;
+    if (envelope.deliveriesCapped) {
+        // Informational only — does NOT block acking what WAS handed over. The
+        // tail stays unacked and arrives on the next pass; never acking here would
+        // make a badly backed-up agent replay its whole backlog forever.
+        warn(label, 'inbox deliveriesCapped (more mail than one envelope carries — the tail follows on the next pass)');
     }
-    for (const scope of envelope.scopes) {
-        const chatIds = await chatIdsForScope(scope, deps.creds, grants);
-        if (!chatIds.length && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
-            warn(label, `no chat ids for scope ${scope.scope.kind}:${scope.scope.id} (${scope.newMessages} msgs)`);
-        }
-        if (scope.newMessages > 0 && chatIds.length) {
-            const n = await deliverMessagesForScope(deps, scope, chatIds, reader, countCap);
-            messagesDelivered += n;
-            log(label, `scope ${scope.scope.kind}:${scope.scope.id} delivered ${n} message(s)`);
-        }
-        if (scope.newArtifacts > 0) {
-            for (const chatId of chatIds) {
-                await deps.onResourceEvent({
-                    kind: 'artifact',
-                    ts: scope.latestAt ?? new Date().toISOString(),
-                    resourceId: chatId,
-                    chatId,
-                    change: 'created',
-                });
-                resourceEvents++;
-            }
-        }
-        if (scope.latestAt && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
-            toAck.push({
-                kind: scope.scope.kind,
-                id: scope.scope.id,
-                upTo: scope.latestAt,
-            });
+    // Oldest delivery per chat: where to start reading that chat's messages.
+    const earliestByChat = new Map();
+    for (const d of envelope.deliveries) {
+        if (!d.chatId)
+            continue;
+        const seen = earliestByChat.get(d.chatId);
+        if (!seen || d.ts < seen)
+            earliestByChat.set(d.chatId, d.ts);
+    }
+    for (const news of envelope.chats) {
+        const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
+        const n = await deliverMessagesForChat(deps, news, earliest, reader);
+        messagesDelivered += n;
+        if (n > 0)
+            log(label, `chat ${news.chatId} delivered ${n} message(s)`);
+    }
+    // Everything that is not chat text is handed over as a resource event, from
+    // the delivery itself — the reference already carries the ids the host needs,
+    // so nothing has to be re-derived to name what changed.
+    for (const d of envelope.deliveries) {
+        if (d.kind === 'message')
+            continue;
+        const key = `delivery:${d.kind}:${d.resourceId}:${d.ts}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
+        await deps.onResourceEvent({
+            kind: d.kind,
+            ts: d.ts,
+            resourceId: d.resourceId,
+            ...(d.chatId ? { chatId: d.chatId } : {}),
+            ...(d.agreementId ? { agreementId: d.agreementId } : {}),
+            ...(d.taskId ? { taskId: d.taskId } : {}),
+            change: 'created',
+        });
+        resourceEvents++;
+    }
+    // ZIG-973: the work channel. An open assigned task is redelivered on every
+    // pass until it closes (that IS the durable-wait contract), so dedup on
+    // taskId+updatedAt — a genuinely touched task wakes again, an untouched one
+    // doesn't storm the lane every long-poll.
+    for (const task of envelope.tasksAwaitingMe ?? []) {
+        const key = `task:${task.taskId}:${task.updatedAt ?? ''}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
+        if (deps.onTask) {
+            await deps.onTask(task);
+            tasksDelivered++;
         }
     }
+    if (envelope.truncatedTasks) {
+        warn(label, `inbox truncatedTasks=${envelope.truncatedTasks} (more assigned tasks than one pass surfaces — they appear as earlier ones close)`);
+    }
+    // Pending decisions are standing state, not deliveries: they keep appearing
+    // until answered, so dedup them the same way tasks are deduped.
     for (const proposal of envelope.proposalsAwaitingMe) {
+        const key = `proposal:${proposal.agreementId}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
         await deps.onResourceEvent({
             kind: 'agreement',
             ts: proposal.proposedAt ?? new Date().toISOString(),
@@ -136,18 +157,21 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
         });
         resourceEvents++;
     }
-    let acked = 0;
-    if (toAck.length) {
-        await inbox.ack(toAck);
-        acked = toAck.length;
-        log(label, `acked ${acked} scope(s)`);
+    // Act, then ack: everything above has been handed to the host, so the
+    // watermark may now move past it. A crash before this point redelivers.
+    let acked = false;
+    if (envelope.ackTo) {
+        await inbox.ack(envelope.ackTo);
+        acked = true;
+        log(label, `acked up to ${envelope.ackTo}`);
     }
     return {
-        scopes: envelope.scopes.length,
+        deliveries: envelope.deliveries.length,
         messagesDelivered,
         resourceEvents,
+        tasksDelivered,
         acked,
-        truncated: envelope.truncatedScopes > 0,
+        truncated: envelope.deliveriesCapped,
     };
 }
 const DEFAULT_WAIT_SECONDS = 25;
@@ -160,24 +184,43 @@ function sleep(ms) {
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
  * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
  * Errors retry with exponential backoff + jitter and never exit the loop —
- * there is nothing to resynchronize (the cursor is server-side), so recovery is
- * just the next iteration.
+ * there is nothing to resynchronize (the watermark is server-side), so recovery
+ * is just the next iteration.
+ *
+ * The FIRST pass is an immediate read. A held poll only answers to new mail, so
+ * a host that just started (or restarted after a crash) would otherwise sit
+ * waiting while the work it was already assigned — open tasks, pending
+ * decisions — went unseen until something unrelated arrived.
  */
 export function runInboxLoop(deps, opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
     let running = true;
     let consecutiveErrors = 0;
+    let first = true;
     const done = (async () => {
         while (running) {
             try {
-                await pollInboxOnce(deps, waitSeconds);
+                await pollInboxOnce(deps, first ? 0 : waitSeconds);
+                first = false;
                 consecutiveErrors = 0;
             }
             catch (err) {
                 if (!running)
                     break;
                 consecutiveErrors++;
+                // ZIG-1019: a 429 already told us how long to wait, and every refused
+                // call still counts against the cap — so the exponential ladder digs
+                // the hole deeper (1s, 2s, 4s… of pure refusals). Wait the server's
+                // number instead, and do not let a throttle inflate the ladder for the
+                // real errors that come after it.
+                const throttleMs = isRateLimited(err) ? (err.retryAfterMs ?? 30_000) : null;
+                if (throttleMs !== null) {
+                    consecutiveErrors = 0;
+                    warn(label, `inbox loop throttled: ${err?.message ?? err} — waiting ${Math.round(throttleMs)}ms as instructed`);
+                    await sleep(throttleMs);
+                    continue;
+                }
                 const backoff = Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
                 const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14); // deterministic-ish, no Math.random
                 warn(label, `inbox loop pass failed (#${consecutiveErrors}): ${err?.message ?? err} — retrying in ~${Math.round(jitter)}ms`);

package/dist/server/runLauncher.js

@@ -82,11 +82,17 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
         }
     }
     if (preStart.length > 0) {
-        await Promise.all(preStart.map(id => pool.startAgent(id)
-            .then(() => runtimeLog.debug(label, `Pre-started "${id}"`))
+        // 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}`))));
     }
-    runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
+    runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected` +
+        (pool.listPinned().length ? ` (${pool.listPinned().length} pinned)` : ''));
     process.on('SIGTERM', async () => {
         runtimeLog.info(label, 'SIGTERM — shutting down');
         pool.stopControl();

package/dist/server/staleBacklogGate.d.ts

@@ -18,7 +18,7 @@
  * `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 { InboxEnvelope, InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
+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. */
@@ -33,11 +33,15 @@ export interface ReplayPolicy {
 export declare function parseReplayMaxAge(raw: string): number | null;
 export declare function resolveReplayPolicy(env?: NodeJS.ProcessEnv): ReplayPolicy;
 /**
- * Newest actionable timestamp across an agent's slice: scope activity,
- * proposals, and connection/MCP requests. Null when nothing carries a
- * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ * 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(inbox: InboxEnvelope): number | null;
+export declare function newestActionableAt(entry: InboxOperatorAgentEntry): number | null;
 export declare function formatAge(ms: number): string;
 export interface StaleBacklogGateOptions extends ReplayPolicy {
     label?: string;

package/dist/server/staleBacklogGate.js

@@ -30,39 +30,19 @@ export function resolveReplayPolicy(env = process.env) {
     return { maxAgeMs, replayAll };
 }
 /**
- * Newest actionable timestamp across an agent's slice: scope activity,
- * proposals, and connection/MCP requests. Null when nothing carries a
- * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ * 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 function newestActionableAt(inbox) {
-    let newest = null;
-    const consider = (iso) => {
-        if (!iso)
-            return;
-        const t = Date.parse(iso);
-        if (!Number.isNaN(t) && (newest == null || t > newest))
-            newest = t;
-    };
-    for (const scope of inbox.scopes ?? [])
-        consider(scope.latestAt);
-    for (const p of inbox.proposalsAwaitingMe ?? [])
-        consider(p.proposedAt);
-    for (const r of inbox.connectionRequestsAwaitingMe ?? [])
-        consider(r.requestedAt);
-    for (const r of inbox.mcpServerRequestsAwaitingMe ?? [])
-        consider(r.requestedAt);
-    return newest;
-}
-/** Unread items in a slice, for the summary line. Counts are backend-capped. */
-function countItems(inbox) {
-    let items = 0;
-    for (const scope of inbox.scopes ?? []) {
-        items += (scope.newMessages ?? 0) + (scope.newArtifacts ?? 0);
-    }
-    items += (inbox.proposalsAwaitingMe ?? []).length;
-    items += (inbox.connectionRequestsAwaitingMe ?? []).length;
-    items += (inbox.mcpServerRequestsAwaitingMe ?? []).length;
-    return items;
+export function newestActionableAt(entry) {
+    if (!entry.deliveredUpTo)
+        return null;
+    const t = Date.parse(entry.deliveredUpTo);
+    return Number.isNaN(t) ? null : t;
 }
 export function formatAge(ms) {
     if (ms >= 86_400_000)
@@ -86,7 +66,6 @@ export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher'
     const emit = log ?? ((line) => runtimeLog.warn(label, line));
     const announced = new Set();
     let pendingAgents = [];
-    let pendingItems = 0;
     let flushScheduled = false;
     // One envelope's entries are gated synchronously; a microtask-deferred
     // flush turns a whole boot flood into a single summary line.
@@ -96,20 +75,21 @@ export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher'
             return;
         const preview = pendingAgents.slice(0, 5).join(', ');
         const more = pendingAgents.length > 5 ? `, +${pendingAgents.length - 5} more` : '';
-        emit(`startup backlog policy: skipped ${pendingItems} stale item(s) across ${pendingAgents.length} agent(s) older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
+        emit(`startup backlog policy: skipped ${pendingAgents.length} agent(s) whose newest mail is older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
         pendingAgents = [];
-        pendingItems = 0;
     };
     return (entry) => {
         if (replayAll)
             return true;
-        const newest = newestActionableAt(entry.inbox);
+        // Open work always starts, however old: the task is unfinished, not stale.
+        if (entry.hasOpenTasks)
+            return true;
+        const newest = newestActionableAt(entry);
         if (newest == null || now() - newest <= maxAgeMs)
             return true;
         if (!announced.has(entry.agentId)) {
             announced.add(entry.agentId);
             pendingAgents.push(entry.agentId);
-            pendingItems += countItems(entry.inbox);
             if (!flushScheduled) {
                 flushScheduled = true;
                 queueMicrotask(flush);

package/dist/server/tools/index.d.ts

@@ -15,7 +15,7 @@
  * its `tools:` array. Each tool reads operatorKey/agentId from tool context and
  * wraps a backend HTTP client — no per-agent plumbing.
  */
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, } from './tier1/protocolTools.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, } from './tier1/protocolTools.js';
 export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
@@ -23,6 +23,6 @@ export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForA
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
 export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
-export { LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, } from './tier2/linkTools.js';
+export { LINK_TOOLS, linkCreateInviteTool, linkListTool, } from './tier2/linkTools.js';
 export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
 export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

package/dist/server/tools/index.js

@@ -16,7 +16,7 @@
  * wraps a backend HTTP client — no per-agent plumbing.
  */
 // ── Tier 1: protocol grammar ────────────────────────────────────────────────
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, } from './tier1/protocolTools.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, } from './tier1/protocolTools.js';
 export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 // ── Tier 2: capability bundles ──────────────────────────────────────────────
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
@@ -28,9 +28,11 @@ export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReach
 // payment_list_grants). Always-available on the hosted agent — see CLAUDE_SDK_TOOLS.
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
 // ZIG-898: links (agreements with engagementKind 'link') — cross-org reach.
-export { LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, } from './tier2/linkTools.js';
+// ZIG-1021/1022: the rail is two tools; propose/claim/revoke ride the
+// agreement grammar.
+export { LINK_TOOLS, linkCreateInviteTool, linkListTool, } from './tier2/linkTools.js';
 // ZIG-899: deliberate artifact recording (the model decides "record this").
 export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
-// ZIG-900 decision: open_conversation only — chat listing stays a context-rail
-// read (list_grants scopeKind=chat), no duplicate lister (ZIG-626 rule).
+// ZIG-900 decision: chat_open only — chat listing stays a context-rail
+// read (grant_list scopeKind=chat), no duplicate lister (ZIG-626 rule).
 export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

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

@@ -30,7 +30,7 @@ interface ProtocolPayload {
     plan?: unknown;
     planReviewTiming?: string;
     requireMidWorkPlanAck?: boolean;
-    engagementKind?: 'hire' | 'service';
+    engagementKind?: 'hire' | 'service' | 'link';
     subtasks?: (string | {
         description?: string;
     })[];

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

@@ -50,6 +50,11 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
             if (!payload.agreementId || !payload.action)
                 return null;
             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`');
+            return agreementService.claim(payload.agreementId);
         case 'agreement-counter-proposal':
             if (!payload.agreementId)
                 return null;
@@ -192,13 +197,36 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     if (!payload.description)
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
-        throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To spawn a task under an existing agreement, use `task_spawn` instead.');
+        throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To create a task under an existing agreement, use `task_create` instead.');
     const isBroadcast = payload.proposedTo === 'everyone' || payload.proposedTo === 'org';
+    // ZIG-1022: a link proposal is an agreement with engagementKind 'link' —
+    // no chat, no money; the target owner approves. Folds the old request_link.
+    if (payload.engagementKind === 'link') {
+        if (isBroadcast) {
+            throw new Error('A broadcast link is an invite — use link_create_invite instead; propose links to one agent id.');
+        }
+        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).');
     }
     if (isBroadcast && payload.providerId) {
-        throw new Error('agreement-propose forbids `providerId` on a broadcast — the claiming agent fills the open side.');
+        // ZIG-1022: providerId = self on a broadcast publishes a STANDING OFFER
+        // (seller side open to any claimer). Any other providerId stays an error.
+        if (actingAgentId && payload.providerId === actingAgentId) {
+            const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
+            return services.agreementService.publishOffer({
+                description: String(priced.description ?? ''),
+                price: typeof priced.price === 'number' ? priced.price : undefined,
+                lifecycle: typeof priced.lifecycle === 'string' ? priced.lifecycle : undefined,
+                expiresAt: typeof priced.expiresAt === 'string' ? priced.expiresAt : undefined,
+                maxExecutions: typeof priced.maxExecutions === 'number' ? priced.maxExecutions : undefined,
+                engagementKind: priced.engagementKind === 'hire' ? 'hire' : priced.engagementKind === 'service' ? 'service' : undefined,
+                billing: priced['billing'] === 'per_task' ? 'per_task' : priced['billing'] === 'total' ? 'total' : undefined,
+                audience: payload.proposedTo === 'org' ? 'org' : 'everyone',
+            });
+        }
+        throw new Error('On a broadcast, providerId must be your own agent id (a standing offer) or omitted (a quest — the claiming agent fills the open side).');
     }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;

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

@@ -2,11 +2,12 @@ import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const agreementProposeTool: ToolDefinition;
 export declare const agreementSubcontractTool: ToolDefinition;
 export declare const agreementRespondTool: ToolDefinition;
-export declare const taskUpdateTool: ToolDefinition;
-export declare const agreementCounterProposalTool: ToolDefinition;
-export declare const agreementCheckProposalTool: ToolDefinition;
+export declare const agreementClaimTool: ToolDefinition;
+export declare const taskSetResultTool: ToolDefinition;
+export declare const agreementCounterTool: ToolDefinition;
+export declare const agreementGetTool: ToolDefinition;
 export declare const agreementRevokeTool: ToolDefinition;
 export declare const agreementFulfillTool: ToolDefinition;
 export declare const taskUpdatePlanStepTool: ToolDefinition;
-export declare const taskSpawnTool: ToolDefinition;
+export declare const taskCreateTool: ToolDefinition;
 export declare const PROTOCOL_TOOLS: ToolDefinition[];