@ziggs-ai/agent-sdk 0.15.0 → 0.17.0

package/dist/{server → platform}/tools/index.d.ts

@@ -23,6 +23,7 @@ export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 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 { TASK_TOOLS, listTasksTool } from './tier2/taskTools.js';
 export { LINK_TOOLS, linkProposeTool, linkListTool, } from './tier2/linkTools.js';
 export { INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, } from './tier2/introductionTools.js';
 export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';

package/dist/{server → platform}/tools/index.js

@@ -27,6 +27,7 @@ export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReach
 // one grant lister across every rail (retires context_discover +
 // payment_list_grants). Always-available on the hosted agent — see CLAUDE_SDK_TOOLS.
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
+export { TASK_TOOLS, listTasksTool } from './tier2/taskTools.js';
 // links (agreements with engagementKind 'link') — cross-org reach.
 ///1022: the rail is two tools; propose/claim/revoke ride the
 // agreement grammar.

package/dist/{server → platform}/tools/tier1/protocolRunner.js

@@ -1,4 +1,4 @@
-import { isBroadcastTarget, partyActorIds, } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, partyActorIds, presentClaimResult, } from '@ziggs-ai/api-client';
 import { applyFleetCounterPricing, applyFleetPricingForProtocol, } from '../../../pricing/fleetDefaults.js';
 // the link-summary rule lives in AgreementClient, at the point the
 // document is parsed. Every verb here inherits it through the client instead of
@@ -71,11 +71,16 @@ cachedAgreements) {
             // claim; it does not re-parent the row, which stays in the publisher's
             // tree.
             const declaredMandate = payload.mandateAgreementId;
-            return await agreementService.claim(payload.agreementId, {
+            const { agreement, kind } = await agreementService.claim(payload.agreementId, {
                 ...(typeof declaredMandate === 'string' && declaredMandate
                     ? { mandateAgreementId: declaredMandate }
                     : {}),
             });
+            return presentClaimResult(agreement, kind, {
+                creds: { operatorKey: 'sdk', agentId: actorId ?? 'agent' },
+                surface: 'sdk',
+                webUrl: process.env.ZIGGS_WEB_URL,
+            });
         }
         case 'agreement-counter-proposal':
             if (!payload.agreementId)
@@ -221,38 +226,16 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
         throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To create a task under an existing agreement, use `task_create` instead.');
-    const isBroadcast = isBroadcastTarget(payload.proposedTo);
     // a link proposal is an agreement with engagementKind 'link' —
     // no chat, no money; the target owner approves. Folds the old request_link.
+    // The shared propose grammar no longer has a link arm (link_propose owns it).
     if (payload.engagementKind === 'link') {
-        if (isBroadcast) {
+        if (isBroadcastTarget(payload.proposedTo)) {
             throw new Error('A broadcast link is an invite — use link_propose with no target instead; it returns a share link.');
         }
         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) {
-        // 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 request — the claiming agent fills the open side).');
-    }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
-    const { operation: _op, ...fields } = priced;
     // Wake-derived idempotency key (delivery law): a crash-replay re-issuing this
     // propose resolves to the already-created agreement server-side instead of
     // minting a duplicate proposal. Keyed on what the proposal writes, so
@@ -263,7 +246,30 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         description: payload.description,
         parentAgreementId: payload.parentAgreementId,
     });
-    return services.agreementService.propose({ ...fields, chatId, idempotencyKey });
+    const engagementKind = priced.engagementKind === 'hire' || priced.engagementKind === 'service'
+        ? priced.engagementKind
+        : undefined;
+    const billing = priced['billing'] === 'per_task' || priced['billing'] === 'total'
+        ? priced['billing']
+        : undefined;
+    const { agreement, shape } = await services.agreementService.proposeUnified({
+        proposedTo: priced.proposedTo ?? payload.proposedTo,
+        chatId: chatId ?? undefined,
+        description: String(priced.description ?? payload.description),
+        providerId: priced.providerId,
+        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,
+        billing,
+        agreementDescription: priced.agreementDescription,
+        parentAgreementId: priced.parentAgreementId,
+        engagementKind,
+        idempotencyKey,
+    });
+    // Keep the agreement fields at the top level (the shape agents already
+    // read) and add the discriminant the shared flow returns.
+    return { ...agreement, shape };
 }
 // ── deterministic sub-agreement resolution ─────────────────────────
 // The orchestrator delegates one task per worker, but the LLM inconsistently

package/dist/{server → platform}/tools/tier1/protocolTools.js

@@ -1,7 +1,7 @@
 import { defineTool } from '../../../tools/defineTool.js';
 import { requireProtocolOperation } from '../../../tasks/protocolRegistry.js';
 import { dispatchProtocolOp } from './protocolRunner.js';
-import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, } from '@ziggs-ai/api-client';
+import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, agreementClaimCapability, } from '@ziggs-ai/api-client';
 /** keep these enums in lockstep with MCP ziggs_agreement_* / ziggs_task_create. */
 const LIFECYCLE_ENUM = ['open', 'time-bound', 'count-bound'];
 const PLAN_REVIEW_TIMING_ENUM = ['with_proposal', 'before_execution'];
@@ -46,12 +46,7 @@ function handlerFor(toolName) {
 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. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, 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. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. 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 REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose: it takes an email or an agent id, or neither for a share link. 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: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, 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 (requests, 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 (request / offer / link invite id)' },
-    // The job this claim is part of. Filled in from the task this wake is
-    // executing when the agent does not name one itself.
-    mandateAgreementId: { type: 'string', description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.' },
-}, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (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 requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.' });
+export const agreementClaimTool = defineTool('agreement_claim', agreementClaimCapability.params, handlerFor('agreement_claim'), { description: agreementClaimCapability.descriptions.sdk });
 export const taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
     // same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.

package/dist/{server → platform}/tools/tier2/mcpConnectionTools.js

@@ -2,7 +2,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { ConnectionsClient } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
-import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
+import { resolveZiggsGatewayTarget } from '../../../mcp/createMcpAgent.js';
 /**
  * Calling a tool on a connected MCP server, one shot.
  *
@@ -15,7 +15,7 @@ import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
  *
  * The gateway (`POST /connections/:id/mcp`) has always been the right door and is
  * already in production; what was missing was a tool that walks through it. The
- * transport, headers and MCP handshake are the same ones `McpAdapter`'s `ziggs`
+ * transport, headers and MCP handshake are the same ones `createMcpAgent`'s `ziggs`
  * transport uses — reused rather than re-derived, so a change to the gateway
  * contract lands in one place.
  *
@@ -66,7 +66,10 @@ async function withClient(ctx, connectionId, grantId, run) {
         grantId,
         operatorKey: ctx['operatorKey'],
         agentId: ctx['agentId'],
-    }, { agentId: ctx['agentId'] });
+    }, {
+        agentId: ctx['agentId'],
+        laneId: ctx['laneId'],
+    });
     const transport = new StreamableHTTPClientTransport(target.url, {
         requestInit: { headers: target.headers },
     });

package/dist/platform/tools/tier2/taskTools.d.ts

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

package/dist/platform/tools/tier2/taskTools.js

@@ -0,0 +1,6 @@
+import { listTasksCapability, TASK_CAPABILITIES } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// GET /tasks, defined once in api-client. MCP ziggs_task_list and this
+// hosted-Claude tool used to re-declare the same filters.
+export const listTasksTool = toolFromCapability(listTasksCapability);
+export const TASK_TOOLS = toolsFromCapabilities(TASK_CAPABILITIES);

package/dist/runtime/bootstrapCtx.d.ts

@@ -3,7 +3,7 @@ import type { Ctx, Identity } from '../types.js';
  * The one place a per-lane `Ctx` is constructed.
  *
  * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
- * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * and the Claude Agent SDK brain (`ClaudeBrain.tick`). Before this, each
  * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
  * and they had already drifted (the "default them ONCE here" comment in
  * AgentMachine no longer held). Keep it here so the shape lives in a single spot.

package/dist/runtime/bootstrapCtx.js

@@ -3,7 +3,7 @@ import { migrateLegacyTaskFields } from './taskBookkeeping.js';
  * The one place a per-lane `Ctx` is constructed.
  *
  * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
- * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * and the Claude Agent SDK brain (`ClaudeBrain.tick`). Before this, each
  * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
  * and they had already drifted (the "default them ONCE here" comment in
  * AgentMachine no longer held). Keep it here so the shape lives in a single spot.

package/dist/runtime/buildOutcome.d.ts

@@ -36,14 +36,6 @@ export interface EmittedEvent {
     senderId?: string;
     [key: string]: unknown;
 }
-/**
- * A chat message whose stated receiver is a DIFFERENT party. `receiverId` is
- * the sender's addressing decision, carried on every wire frame; the
- * human-broadcast sentinel counts as "elsewhere" for an agent (a broadcast is
- * addressed to the room's humans). A frame with NO receiver keeps the turn —
- * we cannot know it is not ours, and skipping on absence would deafen agents
- * to malformed or legacy frames.
- */
 export declare function isMessageAddressedElsewhere(ev: RawEvent | null | undefined, ownAgentId: string | null | undefined): boolean;
 /**
  * Converts a raw incoming event into the single Outcome that re-enters the

package/dist/runtime/buildOutcome.js

@@ -9,12 +9,26 @@ import { bookForDelegation, ensureTaskBook, findBookHoldingPending, removeTaskBo
  * we cannot know it is not ours, and skipping on absence would deafen agents
  * to malformed or legacy frames.
  */
+function isSyntheticOrgReceiver(id) {
+    if (/^([a-z0-9][a-z0-9-]*)\1@ziggs\.local$/i.test(id))
+        return true;
+    const sep = id.indexOf(':::');
+    if (sep > 0)
+        return /@ziggs\.local$/i.test(id.slice(sep + 3));
+    return false;
+}
 export function isMessageAddressedElsewhere(ev, ownAgentId) {
-    return Boolean(ev &&
-        ev.type === 'message' &&
-        ownAgentId &&
-        ev.receiverId &&
-        ev.receiverId !== ownAgentId);
+    if (!ev || ev.type !== 'message' || !ownAgentId || !ev.receiverId) {
+        return false;
+    }
+    if (ev.receiverId === ownAgentId)
+        return false;
+    // Fleet synthetic users are not a party that will answer. A hire room
+    // born with the org ghost as the other face used to address the human's
+    // message there, and the agent skipped the turn — claimed, acked, silence.
+    if (isSyntheticOrgReceiver(String(ev.receiverId)))
+        return false;
+    return true;
 }
 // ── outcomeFromEvent: incoming wire event → Outcome ──────────────────────────
 /**
@@ -148,7 +162,7 @@ function singleEventToOutcome(ev, ownAgentId) {
         return null;
     }
     if (ev.type === 'state-timeout') {
-        // Synthetic frame from AgentHost's StateTimers — host-constructed, fields always present.
+        // Synthetic frame from Agent's StateTimers — host-constructed, fields always present.
         return { kind: 'state-timeout', state: ev.state, waitedMs: ev.waitedMs };
     }
     // Only real inbound chat messages should drive the FSM. Backend bookkeeping

package/dist/runtime/kickoff.js

@@ -185,7 +185,7 @@ export function buildClaimKickoffState(initial) {
                 prompt: {
                     when: 'There is not yet a real chat with the buyer (common on store claims).',
                     instruction: 'Open or reuse a chat with the buyer who claimed the listing.',
-                    format: '{"participantId": "<buyer actorId / Sender from the event>"}',
+                    format: '{"participantId": "<buyer actorId / Sender from the event>", "agreementId": "<the claimed agreement id>"}',
                 },
                 tool: 'chat_open',
                 produces: (result) => {

package/dist/runtime/runTurn.d.ts

@@ -15,7 +15,7 @@ interface RunTurnInput {
     toolManager: ToolManager;
     promptBuilder: PromptBuilder;
     /**
-     * Agent-private long-term memory, threaded from AgentHost. Currently
+     * Agent-private long-term memory, threaded from Agent. Currently
      * surfaced into `eff` as part of the tool-call effect payload so tools
      * can read/write notes; the prompt builder doesn't consume it yet.
      */

package/dist/runtime/runTurn.js

@@ -1,7 +1,9 @@
+import { isAgreementId } from '@ziggs-ai/api-client';
 import { outcomeFromActionResult } from './buildOutcome.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { safeParseJSON } from '../utils/jsonExtractor.js';
 import { withDeclaredMandate } from './mandateDeclaration.js';
+import { resolveOnBehalfAgreementId, } from '../brain/onBehalfAgreement.js';
 const MAX_TOOL_LOOP_ITERS = 20;
 const MAX_MSG_CHARS = 3500;
 /**
@@ -117,9 +119,7 @@ export async function runTurn(input) {
     // only. a bare agreement id as sessionId is a mis-keyed lane —
     // loud-log the empty snapshot rather than staying silent.
     if (ctxObj.chatMissing) {
-        const looksLikeBareAgreement = typeof sessionId === 'string' &&
-            sessionId.startsWith('agr_') &&
-            !sessionId.startsWith('agrn-');
+        const looksLikeBareAgreement = isAgreementId(sessionId);
         if (looksLikeBareAgreement) {
             runtimeLog.warn('runTurn', `chatMissing on non-chat sessionId=${sessionId} (state=${stateId}) — ` +
                 `lane was keyed by agreementId instead of the agreement's origin/notification chat; ` +
@@ -265,7 +265,9 @@ export async function runTurn(input) {
                 // not. The runtime knows; the model would have to be told.
                 args = withDeclaredMandate(args, toolName, toolManager, ctx.activeAgreementId);
                 const decision = { action: matchingAction, tool: toolName, args };
-                const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
+                const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, incomingEvent, addToolUsage, ctx.identity.agentId, Array.isArray(ctxObj.agreements)
+                    ? ctxObj.agreements
+                    : null);
                 toolCallResults.push({ tc, matchingAction, result, args, actionDef });
             }
             let hasTerminal = false;
@@ -418,7 +420,9 @@ export async function runTurn(input) {
             try {
                 // effWithTrace, not eff: JSON-path tool calls must carry runId/stateId
                 // and the wake's write keys exactly like tool-loop calls do.
-                result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
+                result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, incomingEvent, addToolUsage, ctx.identity.agentId, Array.isArray(ctxObj.agreements)
+                    ? ctxObj.agreements
+                    : null);
             }
             catch (err) {
                 // Only outbound sends can throw out of executeDecision — executeTool
@@ -642,17 +646,18 @@ function findActionForTool(toolName, allowedActionNames, actions) {
     }
     return null;
 }
-async function executeDecision(decision, actionDef, eff, sessionId, memory, incomingEvent = null, onUsage) {
+async function executeDecision(decision, actionDef, eff, sessionId, memory, incomingEvent = null, onUsage, agentId = null, agreements = null) {
     const boundTool = actionDef?.tool || null;
     if (boundTool) {
         decision.tool = boundTool;
-        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage, agentId, agreements);
     }
     if (decision.action === '_genericDiscoveryTool' && decision.tool) {
-        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage, agentId, agreements);
+    }
+    if (decision.tool) {
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage, agentId, agreements);
     }
-    if (decision.tool)
-        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
     if (decision.messages && Array.isArray(decision.messages) && decision.messages.length > 0) {
         return await executeSendMessages(decision, eff, sessionId);
     }
@@ -775,7 +780,7 @@ async function executeSendMessages(decision, eff, sessionId) {
  * dependencies (taskService, agreementService, agents list, etc.), and
  * wrapping the call in telemetry / operation-record entries if it wants.
  */
-async function executeTool(decision, eff, sessionId, memory, incomingEvent = null, onUsage) {
+async function executeTool(decision, eff, sessionId, memory, incomingEvent = null, onUsage, agentId = null, agreements = null) {
     const { tool, args } = decision;
     if (!tool)
         return null;
@@ -788,13 +793,8 @@ async function executeTool(decision, eff, sessionId, memory, incomingEvent = nul
             memory,
             senderId: incomingEvent?.senderId != null ? String(incomingEvent.senderId) : undefined,
             senderType: incomingEvent?.senderType != null ? String(incomingEvent.senderType) : undefined,
-            // the subcontract agreement this wake is under (task events carry
-            // it under `result.agreementId`) so a delegated per-user MCP call can
-            // resolve the originating end-user, not the delegating agent (senderId).
-            onBehalfOfAgreementId: (() => {
-                const aid = incomingEvent?.result?.agreementId;
-                return typeof aid === 'string' && aid ? aid : undefined;
-            })(),
+            // Never bind on-behalf to a sub the agent only pays for.
+            onBehalfOfAgreementId: resolveOnBehalfAgreementId(incomingEvent ?? undefined, agreements, agentId, sessionId),
         });
         if (r.usage)
             onUsage?.(r.usage);

package/dist/runtime/validateWorkflow.js

@@ -94,7 +94,7 @@ export function validateWorkflow(workflow) {
                 errors.push(`thinking state "${name}" requires at least one action`);
             }
             if (state.timeoutMs !== undefined) {
-                errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by AgentHost tickTimeoutMs)`);
+                errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by Agent tickTimeoutMs)`);
             }
         }
         if (state.kind === 'mechanical') {

package/dist/runtime/wakeOutcome.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Every claimed wake must leave a recorded outcome.
+ *
+ * Claim + ack with no externally visible effect used to exist: the host
+ * consumed the delivery, the agent stayed silent, and metering had no row.
+ * A wake ends in exactly one of: a reply, task progress, or an explicit
+ * no-op with a reason.
+ */
+export type WakeOutcomeKind = 'replied' | 'task-progress' | 'no-op';
+export interface WakeOutcome {
+    kind: WakeOutcomeKind;
+    reason?: string;
+}
+export declare function classifyWakeOutcome(input: {
+    skippedReason?: string;
+    lastOutcomeKind?: string | null;
+    llmCalls: number;
+    sentMessage?: boolean;
+    taskWrite?: boolean;
+}): WakeOutcome;
+export declare function buildWakeOutcomePayload(input: {
+    agentId: string;
+    sessionId: string;
+    laneKey: string;
+    outcome: WakeOutcome;
+    llmCalls?: number;
+}): Record<string, unknown>;

package/dist/runtime/wakeOutcome.js

@@ -0,0 +1,43 @@
+/**
+ * Every claimed wake must leave a recorded outcome.
+ *
+ * Claim + ack with no externally visible effect used to exist: the host
+ * consumed the delivery, the agent stayed silent, and metering had no row.
+ * A wake ends in exactly one of: a reply, task progress, or an explicit
+ * no-op with a reason.
+ */
+export function classifyWakeOutcome(input) {
+    if (input.skippedReason) {
+        return { kind: 'no-op', reason: input.skippedReason };
+    }
+    if (input.sentMessage || input.lastOutcomeKind === 'message-sent') {
+        return { kind: 'replied' };
+    }
+    if (input.taskWrite ||
+        input.lastOutcomeKind === 'task-delegated' ||
+        input.lastOutcomeKind === 'task-completed' ||
+        input.lastOutcomeKind === 'task-progress') {
+        return { kind: 'task-progress' };
+    }
+    if (input.llmCalls > 0) {
+        return { kind: 'no-op', reason: 'llm_no_visible_effect' };
+    }
+    return { kind: 'no-op', reason: 'no_llm' };
+}
+export function buildWakeOutcomePayload(input) {
+    return {
+        source: 'agent',
+        chatId: input.sessionId,
+        sessionId: input.sessionId,
+        execution: {
+            llmCallsTotal: input.llmCalls ?? 0,
+        },
+        meta: {
+            effect: 'wake-outcome',
+            kind: input.outcome.kind,
+            ...(input.outcome.reason ? { reason: input.outcome.reason } : {}),
+            laneKey: input.laneKey,
+            agentId: input.agentId,
+        },
+    };
+}

package/dist/skills/parseSkill.d.ts

@@ -61,9 +61,14 @@ export declare function skillHash(files: SkillFile[]): string;
 export declare function parseSkill(files: SkillFile[], opts?: {
     maxChars?: number;
 }): ParsedSkill;
+/** Catalog name for a reference path (`references/tone.md` → `tone`). */
+export declare function skillReferenceName(path: string): string;
+/** First prose line of a reference, for the on-prompt catalog. */
+export declare function skillReferenceOneLine(content: string): string;
 /**
- * Assemble the skill's role prompt: body first, then each reference under its
- * own header.
+ * Assemble the skill's role prompt: the body, then a catalog of references.
+ * Full reference text is fetched with `skill_read_reference` — it does not
+ * ride every turn.
  *
  * This is only the ROLE block. The Ziggs protocol is prepended separately, by
  * the one place that builds a Claude-brain system prompt — a skill is never in a

package/dist/skills/parseSkill.js

@@ -8,7 +8,7 @@
  * with the agent's full authority, so "instructions-only" has to be a structural
  * property of what we accept, not a convention authors are trusted to follow.
  *
- * This module is deliberately free of AgentHost / LLM / MCP imports so it stays
+ * This module is deliberately free of Agent / LLM / MCP imports so it stays
  * unit-testable standalone (same rule as scripts/lib/mcp-provision.ts).
  */
 import { createHash } from 'node:crypto';
@@ -124,9 +124,24 @@ export function parseSkill(files, opts = {}) {
     }
     return { name: name, description: description, body, references, hash: skillHash(files) };
 }
+/** Catalog name for a reference path (`references/tone.md` → `tone`). */
+export function skillReferenceName(path) {
+    return path.replace(/^references\//, '').replace(/\.md$/, '');
+}
+/** First prose line of a reference, for the on-prompt catalog. */
+export function skillReferenceOneLine(content) {
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        return trimmed.length > 160 ? `${trimmed.slice(0, 157)}…` : trimmed;
+    }
+    return '(empty)';
+}
 /**
- * Assemble the skill's role prompt: body first, then each reference under its
- * own header.
+ * Assemble the skill's role prompt: the body, then a catalog of references.
+ * Full reference text is fetched with `skill_read_reference` — it does not
+ * ride every turn.
  *
  * This is only the ROLE block. The Ziggs protocol is prepended separately, by
  * the one place that builds a Claude-brain system prompt — a skill is never in a
@@ -134,8 +149,10 @@ export function parseSkill(files, opts = {}) {
  */
 export function skillRolePrompt(skill) {
     const parts = [skill.body];
-    for (const ref of skill.references) {
-        parts.push(`## Reference: ${ref.path.replace(/^references\//, '').replace(/\.md$/, '')}`, ref.content);
+    if (skill.references.length > 0) {
+        parts.push('## Skill references', 'These files are not in this prompt. Call skill_read_reference with the name when you need one. Do not invent their contents.', skill.references
+            .map((ref) => `- ${skillReferenceName(ref.path)}: ${skillReferenceOneLine(ref.content)}`)
+            .join('\n'));
     }
     return parts.join('\n\n');
 }

package/dist/skills/skillReadReference.d.ts

@@ -0,0 +1,6 @@
+import { type ParsedSkill } from './parseSkill.js';
+/**
+ * Fetch one skill reference by catalog name. The role prompt lists names and
+ * one line each; this is how the rest of the file is loaded.
+ */
+export declare function skillReadReferenceTool(skill: ParsedSkill): import("../tools/defineTool.js").ToolDefinition;

package/dist/skills/skillReadReference.js

@@ -0,0 +1,27 @@
+import { defineTool } from '../tools/defineTool.js';
+import { skillReferenceName, } from './parseSkill.js';
+/**
+ * Fetch one skill reference by catalog name. The role prompt lists names and
+ * one line each; this is how the rest of the file is loaded.
+ */
+export function skillReadReferenceTool(skill) {
+    const byName = new Map(skill.references.map((ref) => [skillReferenceName(ref.path), ref]));
+    return defineTool('skill_read_reference', {
+        name: {
+            type: 'string',
+            required: true,
+            description: 'Reference name from the skill catalog (filename without .md)',
+        },
+    }, async (args) => {
+        const name = String(args['name'] ?? '').trim();
+        const ref = byName.get(name);
+        if (!ref) {
+            const available = [...byName.keys()];
+            throw new Error(`unknown skill reference "${name}". Available: ${available.join(', ') || '(none)'}`);
+        }
+        return { name, path: ref.path, content: ref.content };
+    }, {
+        description: 'Read one skill reference by name. The catalog of names is in your role prompt.',
+        isGenericFallback: true,
+    });
+}

package/dist/tools/needs.js

@@ -11,8 +11,8 @@
  * Scope is agents built on this SDK.
  */
 import { toolName } from './defineTool.js';
-import { connectionListGrantsTool, connectionProxyTool } from '../server/tools/tier2/connectionTools.js';
-import { MCP_CONNECTION_TOOLS } from '../server/tools/tier2/mcpConnectionTools.js';
+import { connectionListGrantsTool, connectionProxyTool } from '../platform/tools/tier2/connectionTools.js';
+import { MCP_CONNECTION_TOOLS } from '../platform/tools/tier2/mcpConnectionTools.js';
 /**
  * A remote MCP server is stored as `provider: 'mcp'` and goes through the
  * gateway. `connection_proxy` resolves a NAMED connector and refuses it with

package/dist/tools/recordReport.d.ts

@@ -38,6 +38,11 @@ export interface RecordReportResult {
  * When `deliverable` is provided, also writes a task-bound result artifact
  * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
  *
+ * One deliverable per task: the idempotency key is `task-result:<taskId>`.
+ * A retry after a partial failure reuses that row (intentional). A later
+ * revision of the same task still returns the original artifact — change the
+ * key if you mean a new deliverable; do not change this helper's key.
+ *
  * Implements the B1 convention (Agents/REPORTING.md).
  */
 export declare function recordReport(input: RecordReportInput): Promise<RecordReportResult>;

package/dist/tools/recordReport.js

@@ -6,6 +6,11 @@ import { ArtifactsClient, updateTaskState, } from '@ziggs-ai/api-client';
  * When `deliverable` is provided, also writes a task-bound result artifact
  * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
  *
+ * One deliverable per task: the idempotency key is `task-result:<taskId>`.
+ * A retry after a partial failure reuses that row (intentional). A later
+ * revision of the same task still returns the original artifact — change the
+ * key if you mean a new deliverable; do not change this helper's key.
+ *
  * Implements the B1 convention (Agents/REPORTING.md).
  */
 export async function recordReport(input) {

package/dist/tools/toolCreds.d.ts

@@ -3,7 +3,7 @@
  *
  * A custom tool builds `{ operatorKey, agentId }` by hand and stops there, so
  * every call it makes runs on the narrowest reach fence there is: the agent's
- * own org. `AgentHost` already threads the wake's lane into the tool context
+ * own org. `Agent` already threads the wake's lane into the tool context
  * (as `chatId` / `sessionId`, which is what the capability adapter reads), and
  * the backend's fence is "own org ∪ the orgs of the parties to this lane" — so
  * a tool that does not pass it loses reach it is entitled to, and loses it

package/dist/tools/toolCreds.js

@@ -3,7 +3,7 @@
  *
  * A custom tool builds `{ operatorKey, agentId }` by hand and stops there, so
  * every call it makes runs on the narrowest reach fence there is: the agent's
- * own org. `AgentHost` already threads the wake's lane into the tool context
+ * own org. `Agent` already threads the wake's lane into the tool context
  * (as `chatId` / `sessionId`, which is what the capability adapter reads), and
  * the backend's fence is "own org ∪ the orgs of the parties to this lane" — so
  * a tool that does not pass it loses reach it is entitled to, and loses it