@ziggs-ai/agent-sdk 0.4.1 → 0.6.0

package/dist/server/inboxLoop.js

@@ -1,4 +1,4 @@
-import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, } from '@ziggs-ai/api-client';
+import { ContextReadClient, InboxClient, } from '@ziggs-ai/api-client';
 import { runtimeLog } from '../shared/runtimeLog.js';
 const READ_PAGE = 100;
 function log(label, msg) {
@@ -7,67 +7,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 +75,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 +156,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,18 +183,25 @@ 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) {

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/tier1/protocolTools.js

@@ -19,14 +19,14 @@ function handlerFor(operation) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals, forbidden on broadcasts (the claiming agent fills the open side). Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT. Naming any other third party requires that party to have a matching published offer. The payer is always derived as the non-providing side.' }, price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-propose'), { description: 'Propose a contract to a user, agent, or as an open broadcast. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay"). Required on direct proposals; omit it only for a broadcast — proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org). engagementKind defaults to service.', isAgreementCreation: true });
+export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals, forbidden on broadcasts (the claiming agent fills the open side). Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT. Naming any other third party requires that party to have a matching published offer. The payer is always derived as the non-providing side.' }, price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', 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', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-propose'), { description: 'Propose a contract to a user, agent, or as an open broadcast. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay"). Required on direct proposals; omit it only for a broadcast — proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org). 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 }, parentTaskId: 'string', payerId: 'string', price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, 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 agreement proposal.' });
 export const taskUpdateTool = defineTool('task_update', { taskId: { type: 'string', required: true }, status: { type: 'string', required: true, enum: ['completed', 'failed', 'cancelled'] }, result: 'string' }, handlerFor('task-update'), { description: 'Transition a task to completed, failed, or cancelled. Include a result string for completed tasks.' });
 export const agreementCounterProposalTool = defineTool('agreement_counter_proposal', { agreementId: { type: 'string', required: true }, price: 'number', agreementDescription: 'string', expiresAt: 'string', lifecycle: 'string', maxExecutions: 'number', description: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-counter-proposal'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_check_proposal.' });
 export const agreementCheckProposalTool = defineTool('agreement_check_proposal', { 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: 'Mark an agreement you provide as fulfilled (complete) once its work is delivered — closes the engagement so it no longer reads as in-progress. Use on your hire after the final deliverable is done and delivered to the human.' });
+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_update (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.' });
 export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', { taskId: { type: 'string', required: true }, stepId: { type: 'string', required: true }, status: { type: 'string', required: true }, result: 'string' }, handlerFor('task-update-plan-step'), { description: "Update the status of a single step within a task's plan." });
 export const taskSpawnTool = defineTool('task_spawn', { 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: 'string', requireMidWorkPlanAck: 'boolean' }, handlerFor('task-spawn'), { description: 'Spawn 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 = [

package/dist/server/tools/tier2/artifactTools.d.ts

@@ -1,3 +1,3 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const recordArtifactTool: ToolDefinition;
 export declare const ARTIFACT_TOOLS: ToolDefinition[];

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

@@ -1,82 +1,7 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { ArtifactsClient } from '@ziggs-ai/api-client';
-/**
- * ZIG-899 — deliberate artifact recording on the SDK surface, same base name
- * as ziggs-mcp's ziggs_record_artifact. Until now artifacts were written only
- * as a host-side effect (recordReport / record-event); the model could not
- * decide "this is a deliverable, record it" — which is exactly what the
- * delegate protocol tells agents to do for heavy results. Rides
- * ArtifactsClient.writeStrict (fail loudly, return the artifactId) — the same
- * wire call as the MCP tool.
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-/**
- * ZIG-560 teaching carried over from the MCP tool: name the result slot on the
- * success path so an agent finds the right move unaided — reworded to the SDK
- * task grammar (task_update carries the terminal result on this surface).
- */
-function reportingHint(contentType, taskId) {
-    if (contentType === 'result') {
-        return taskId
-            ? 'Recorded as a task-bound result artifact. Close the task by setting its terminal result with task_update.'
-            : 'Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with task_update.';
-    }
-    return 'Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with task_update — chat messages are conversation only.';
-}
-export const recordArtifactTool = defineTool('record_artifact', {
-    text: { type: 'string', required: true, description: 'Artifact body' },
-    visibility: {
-        type: 'string',
-        required: true,
-        enum: ['chat', 'agent-private'],
-        description: 'chat = visible to scope parties; agent-private = your eyes only',
-    },
-    chatId: { type: 'string', description: 'Target chat (xor agreementId)' },
-    agreementId: { type: 'string', description: 'Target agreement (xor chatId)' },
-    taskId: {
-        type: 'string',
-        description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
-    },
-    content_type: { type: 'string', description: 'Default text; use result for a finished deliverable' },
-}, async (args, ctx) => {
-    const chatId = args['chatId'];
-    const agreementId = args['agreementId'];
-    if ((chatId && agreementId) || (!chatId && !agreementId)) {
-        throw new Error('Pass exactly one of chatId or agreementId');
-    }
-    const visibility = args['visibility'];
-    if (visibility !== 'chat' && visibility !== 'agent-private') {
-        throw new Error('visibility must be chat or agent-private');
-    }
-    const contentType = args['content_type'];
-    const taskId = args['taskId'];
-    const { operatorKey, agentId } = creds(ctx);
-    const { artifactId } = await new ArtifactsClient(operatorKey, agentId).writeStrict({
-        text: args['text'],
-        visibility,
-        chatId,
-        agreementId,
-        taskId,
-        content_type: contentType,
-    });
-    return {
-        ok: true,
-        artifactId,
-        visibility,
-        chatId,
-        agreementId,
-        taskId,
-        reportingHint: reportingHint(contentType, taskId),
-    };
-}, {
-    description: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
-});
-export const ARTIFACT_TOOLS = [recordArtifactTool];
+import { ARTIFACT_CAPABILITIES, recordArtifactCapability } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-899 / ZIG-956 — deliberate artifact recording, defined once in
+// api-client's shared capability layer (including the ZIG-560 result-slot
+// teaching, worded per surface task grammar).
+export const recordArtifactTool = toolFromCapability(recordArtifactCapability);
+export const ARTIFACT_TOOLS = toolsFromCapabilities(ARTIFACT_CAPABILITIES);

package/dist/server/tools/tier2/chatTools.d.ts

@@ -1,3 +1,3 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const openConversationTool: ToolDefinition;
 export declare const CHAT_TOOLS: ToolDefinition[];

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

@@ -1,37 +1,7 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { openConversation } from '@ziggs-ai/api-client';
-/**
- * ZIG-900 — the decided chat surface for hosted agents: open_conversation
- * only, same base name as MCP's ziggs_open_conversation. There is deliberately
- * NO chat-listing tool on the SDK: agents read context only via held grants
- * (ZIG-425) and chat membership auto-mints a chat grant (ZIG-428/426), so
- * "what chats can I see" is already answered by list_grants scopeKind=chat —
- * adding a lister would duplicate a context-family read (ZIG-626 rule).
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-export const openConversationTool = defineTool('open_conversation', {
-    participantId: {
-        type: 'string',
-        required: true,
-        description: 'User or agent id to converse with (from agent_search — do not guess ids)',
-    },
-}, async (args, ctx) => {
-    if (!args['participantId'])
-        throw new Error('participantId is required');
-    const { chatId } = await openConversation(args['participantId'], creds(ctx));
-    return {
-        chatId,
-        note: 'Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in list_grants scopeKind=chat for context reads.',
-    };
-}, {
-    description: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — request_link (if you have its agent id) or create_link_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use list_grants scopeKind=chat.',
-});
-export const CHAT_TOOLS = [openConversationTool];
+import { CHAT_CAPABILITIES, openConversationCapability } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-900 / ZIG-956 — open_conversation only (chat listing stays a
+// context-rail read, ZIG-626 rule); defined once in api-client's shared
+// capability layer.
+export const openConversationTool = toolFromCapability(openConversationCapability);
+export const CHAT_TOOLS = toolsFromCapabilities(CHAT_CAPABILITIES);

package/dist/server/tools/tier2/connectionTools.d.ts

@@ -1,5 +1,5 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const connectionProxyTool: ToolDefinition;
-export declare const connectionListGrantsTool: ToolDefinition;
 export declare const requestConnectionTool: ToolDefinition;
+export declare const connectionListGrantsTool: ToolDefinition;
 export declare const CONNECTION_TOOLS: ToolDefinition[];