@ziggs-ai/agent-sdk 0.11.1 → 0.13.0

package/dist/formatters/HistoryFormatter.d.ts

@@ -17,6 +17,11 @@ export declare class HistoryFormatter {
     formatParticipant(participant: AnyObj | null | undefined, agentId: string): string;
     formatOwner(task: AnyObj, agentId: string): string;
     formatExecutor(task: AnyObj, agentId: string): string;
+    /**
+     * One side of the task's agreement, or `fallback` when the frame carries no
+     * parties — a bare resource_changed skeleton has the task ids and nothing else.
+     */
+    private _formatSide;
     shortId(id: string | null | undefined): string;
     formatTime(timestamp: string | null | undefined): string;
     formatArgs(args: AnyObj | null | undefined): string;

package/dist/formatters/HistoryFormatter.js

@@ -1,3 +1,4 @@
+import { partySideIds } from '@ziggs-ai/api-client';
 export class HistoryFormatter {
     showTimestamps;
     shortIds;
@@ -67,7 +68,8 @@ export class HistoryFormatter {
             case 'created': {
                 const ag = task['agreement'];
                 const parties = ag?.['parties'] || {};
-                return `${timePrefix}Task created under agreement: "${desc}" (${ids})\n    Owner: ${this.formatOwner(task, agentId)}\n    Executor: ${this.formatExecutor(task, agentId)}\n    Proposed to: ${parties['proposedTo'] || 'N/A'}`;
+                const proposedTo = partySideIds(parties['proposedTo']).join(' via ');
+                return `${timePrefix}Task created under agreement: "${desc}" (${ids})\n    Owner: ${this.formatOwner(task, agentId)}\n    Executor: ${this.formatExecutor(task, agentId)}\n    Proposed to: ${proposedTo || 'N/A'}`;
             }
             case 'state_changed': {
                 const prev = service?.['previousState']?.['state'] || '?';
@@ -140,14 +142,21 @@ export class HistoryFormatter {
         return `${id} (${participant['type'] || 'unknown'})`;
     }
     formatOwner(task, agentId) {
-        const ag = task['agreement'];
-        const creatorId = ag?.['parties']?.['creator'] ?? task['agentId'];
-        return creatorId === agentId ? 'You' : String(creatorId ?? 'N/A');
+        return this._formatSide(task, 'creator', task['agentId'], agentId);
     }
     formatExecutor(task, agentId) {
-        const ag = task['agreement'];
-        const providerId = ag?.['parties']?.['provider'] ?? task['executorId'];
-        return providerId === agentId ? 'You' : String(providerId ?? 'N/A');
+        return this._formatSide(task, 'provider', task['executorId'], agentId);
+    }
+    /**
+     * One side of the task's agreement, or `fallback` when the frame carries no
+     * parties — a bare resource_changed skeleton has the task ids and nothing else.
+     */
+    _formatSide(task, role, fallback, agentId) {
+        const parties = task['agreement']?.['parties'];
+        const ids = partySideIds(parties?.[role]);
+        if (ids.length === 0)
+            return fallback === agentId ? 'You' : String(fallback ?? 'N/A');
+        return ids.includes(agentId) ? 'You' : ids.join(' via ');
     }
     shortId(id) {
         if (!id)

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { AgentHost, createAgent, createAgentPool, DEFAULT_MODEL } from './AgentH
 export { Agent } from './agent/Agent.js';
 export { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
 export type { CognitionKind } from './agent/ClaudeSdkAgent.js';
+export { CLAUDE_SDK_PROTOCOL } from './agent/claudeSdkProtocol.js';
+export { buildClaudeEventPrompt, summarizeContext } from './agent/claudeCognition.js';
 export { ziggsBrain, claudeBrain, isBrainSelection, isClaudeCognition } from './brain/index.js';
 export type { Brain, BrainSelection, ZiggsBrainConfig, ClaudeBrainConfig, } from './brain/index.js';
 export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';
@@ -38,7 +40,7 @@ export { validateWorkflow, WorkflowValidationError } from './runtime/validateWor
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './runtime/taskBookkeeping.js';
 export { createDeliveryWriteKeys } from './runtime/deliveryWriteKeys.js';
-export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, PendingSubtask, CollectedSubtaskResult, TaskBookkeeping, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, DeliveryWriteKeys, } from './types.js';
+export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, PendingSubtask, CollectedSubtaskResult, TaskBookkeeping, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, SnapshotParticipant, ReadContextOpts, ToolCallResult, RecordedEntry, DeliveryWriteKeys, } from './types.js';
 export { default } from './AgentHost.js';
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
@@ -60,7 +62,7 @@ export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormat
 export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
 export { PollRegistry, declaredPolls, type PollBinding, type PollContext, type PollKind, type PollResult, } from './server/polls/PollKind.js';
 export { PollRunner, type PollRunnerOptions, type WakeTarget } from './server/polls/PollRunner.js';
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, LINK_TOOLS, linkCreateInviteTool, linkListTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './server/tools/index.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, LINK_TOOLS, linkProposeTool, linkListTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './server/tools/index.js';
 export { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';

package/dist/index.js

@@ -18,6 +18,13 @@ export { loadSkill, readSkillFiles, assertSkillHash } from './skills/loadSkill.j
 export { AgentHost, createAgent, createAgentPool, DEFAULT_MODEL } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';
 export { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
+// The exact strings a Claude-brain wake sends: the shared protocol block, the
+// role-independent event prompt, and the one-line context digest. Exported so a
+// caller can answer "what does this agent actually put in front of the model,
+// and what does it cost?" without re-deriving it — a second copy of the prompt
+// is a second answer to that question, and only one of them would be true.
+export { CLAUDE_SDK_PROTOCOL } from './agent/claudeSdkProtocol.js';
+export { buildClaudeEventPrompt, summarizeContext } from './agent/claudeCognition.js';
 export { ziggsBrain, claudeBrain, isBrainSelection, isClaudeCognition } from './brain/index.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 export { EventQueue } from './server/EventQueue.js';
@@ -69,7 +76,7 @@ export {
 // Tier 1 — protocol grammar (framework-managed via taskTools).
 PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, 
 // Tier 2 — opt-in capability bundles (spread into `tools:`).
-PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, LINK_TOOLS, linkCreateInviteTool, linkListTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './server/tools/index.js';
+PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, LINK_TOOLS, linkProposeTool, linkListTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './server/tools/index.js';
 // The always-on toolset for the hosted Claude cognition (parity guard
 // reads this as part of the real SDK registry).
 export { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';

package/dist/ingress/normalizeIncoming.d.ts

@@ -1,3 +1,4 @@
+import type { AgreementParties } from '@ziggs-ai/api-client';
 export interface NormalizedEvent {
     chatId: string | null;
     event: {
@@ -25,12 +26,6 @@ export interface NormalizedEvent {
         text?: string;
     };
 }
-interface WireParties {
-    creator?: string;
-    provider?: string;
-    payer?: string;
-    proposedTo?: string;
-}
 interface WireTask {
     taskId?: string;
     agentId?: string;
@@ -42,7 +37,7 @@ interface WireTask {
     state?: string;
     proposal?: unknown;
     agreement?: {
-        parties?: WireParties;
+        parties?: AgreementParties;
     };
 }
 interface WireMetadata {
@@ -69,7 +64,7 @@ interface WireMetadata {
             proposal?: {
                 status?: string;
             };
-            parties?: WireParties;
+            parties?: AgreementParties;
             approvals?: Array<{
                 partyId?: string;
                 status?: string;

package/dist/runtime/PromptBuilder.js

@@ -1,6 +1,6 @@
 import { HistoryFormatter, AgreementFormatter } from '../formatters/index.js';
 import { validateContext } from '../cognition/validateContext.js';
-import { isBroadcastTarget, isOpaquePresentationRef } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, isOpaquePresentationRef, partySideIds } from '@ziggs-ai/api-client';
 import { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './taskBookkeeping.js';
 /** Rough chars-per-token ratio for budgeting (English/JSON averages ~4). */
 const CHARS_PER_TOKEN = 4;
@@ -191,12 +191,13 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         const creatorIsYou = task.creatorIsYou;
         const providerIsYou = task.providerIsYou;
         if (ag?.agreementId) {
+            const named = (name) => partySideIds(parties[name]).join(' via ');
             lines.push(`Agreement: ${ag.agreementId}${creatorIsYou ? ' (yours)' : ''}`);
-            lines.push(`  Creator: ${parties.creator ?? 'N/A'}${creatorIsYou ? ' (You)' : ''}`);
-            lines.push(`  Provider: ${parties.provider ?? 'N/A'}${providerIsYou ? ' (You)' : ''}`);
+            lines.push(`  Creator: ${named('creator') || 'N/A'}${creatorIsYou ? ' (You)' : ''}`);
+            lines.push(`  Provider: ${named('provider') || 'N/A'}${providerIsYou ? ' (You)' : ''}`);
             const proposal = ag.proposal;
             if (proposal?.status) {
-                lines.push(`  Proposal: ${proposal.status} (to ${parties.proposedTo}${task.proposedToIsYou ? ' - You' : ''})`);
+                lines.push(`  Proposal: ${proposal.status} (to ${named('proposedTo')}${task.proposedToIsYou ? ' - You' : ''})`);
             }
             const money = ag.money;
             if (typeof money?.price === 'number' && money.price > 0) {
@@ -281,29 +282,38 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
             const name = a.name && a.name !== id ? `${a.name} (${id})` : id;
             agentLabels.set(id, `${name}${desc}`);
         }
-        const kindOf = (id) => userIds.has(id) ? 'user' : agentIds.has(id) ? 'agent' : 'unknown';
+        // The server declares what each participant is (`kind` on the snapshot row),
+        // so read that. Which array a row arrived in is a projection detail, and
+        // guessing from it mislabels the first participant that is neither a person
+        // nor an agent. A backend too old to send `kind` still resolves by array.
+        const declaredKinds = new Map();
+        for (const row of [...users, ...otherAgents]) {
+            const id = (row?.['userId'] ?? row?.['agentId']);
+            const kind = row?.['kind'];
+            if (id && typeof kind === 'string')
+                declaredKinds.set(id, kind);
+        }
+        const kindOf = (id) => declaredKinds.get(id) ??
+            (userIds.has(id) ? 'user' : agentIds.has(id) ? 'agent' : 'unknown');
         const labelOf = (id) => userLabels.get(id) ?? agentLabels.get(id) ?? id;
         const tagged = (id) => `${labelOf(id)} [${kindOf(id)}]`;
         const agreementParties = new Map();
         for (const ag of agreements || []) {
             const agId = ag?.agreementId;
             const parties = ag?.parties || {};
-            const roles = [
-                ['creator', 'creator'],
-                ['provider', 'provider'],
-                ['payer', 'payer'],
-                ['proposedTo', 'proposedTo'],
-            ];
-            for (const [field, role] of roles) {
-                const pid = parties[field];
-                if (!pid || pid === myAgentId)
-                    continue;
-                // Opaque presentation refs are not principal slots.
-                if (isOpaquePresentationRef(pid))
-                    continue;
-                if (!agreementParties.has(pid))
-                    agreementParties.set(pid, []);
-                agreementParties.get(pid).push({ agreementId: agId ?? '', role });
+            for (const role of ['creator', 'provider', 'payer', 'proposedTo']) {
+                // Both columns of a side are addressable and carry the same role: the
+                // principal is who the deal is with, the actor is who acts on it.
+                for (const pid of partySideIds(parties[role])) {
+                    if (pid === myAgentId)
+                        continue;
+                    // Opaque presentation refs are not principal slots.
+                    if (isOpaquePresentationRef(pid))
+                        continue;
+                    if (!agreementParties.has(pid))
+                        agreementParties.set(pid, []);
+                    agreementParties.get(pid).push({ agreementId: agId ?? '', role });
+                }
             }
         }
         // Chat keeps the full directory — including opaque `rpb_*` / `psn_*` refs
@@ -368,7 +378,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         lines.push('Set "action" to exactly one of the action names below.');
         lines.push('Message text is rendered as markdown (CommonMark + GFM). You MAY use **bold**, *italic*, `code`, fenced code blocks, lists, links, and tables when they improve clarity — plain text is also fine.\n');
         const replyTo = senderMeta.defaultReplyReceiverId || '<receiverId>';
-        const pendingProposals = (ctxObj.agreements || []).filter((a) => a.proposal?.status === 'pending' && (a.proposedToIsYou || isBroadcastTarget(a.parties?.proposedTo)));
+        const pendingProposals = (ctxObj.agreements || []).filter((a) => a.proposal?.status === 'pending' && (a.proposedToIsYou || isBroadcastTarget(a.parties?.proposedTo?.principal)));
         if (pendingProposals.length > 0) {
             lines.push(`PRIORITY: You have ${pendingProposals.length} pending proposal(s) directed at you. Respond BEFORE other actions.`);
             lines.push(`{"thought": "...", "action": "<action_bound_to_agreement_respond>", "args": {"agreementId": "<id>", "action": "approve|reject"}}\n`);

package/dist/runtime/buildOutcome.js

@@ -92,7 +92,7 @@ function singleEventToOutcome(ev, ownAgentId) {
         const parties = ag?.parties || {};
         const state = result.state;
         // Direct assignment to me (provider) — task spawned, citing an active agreement.
-        const isAssignedToMe = (result.providerIsYou || parties.provider === ownAgentId) &&
+        const isAssignedToMe = (result.providerIsYou || parties.provider?.actor === ownAgentId) &&
             (state === 'active' || state === 'in-progress');
         if (isAssignedToMe) {
             return { kind: 'task-assigned', task };
@@ -421,7 +421,7 @@ export function applyOutcomeToCtx(ctx, outcome) {
             const book = bookForDelegation(ctx);
             if (tid && !(tid in book.pendingSubtasks)) {
                 book.pendingSubtasks[tid] = {
-                    agentId: t.assigneeId ?? t.executorId ?? t.agreement?.parties?.provider ?? null,
+                    agentId: t.assigneeId ?? t.executorId ?? t.agreement?.parties?.provider?.actor ?? null,
                     spawnedAt: Date.now(),
                 };
             }
@@ -465,7 +465,7 @@ export function applyOutcomeToCtx(ctx, outcome) {
                 if (!existing) {
                     book.collectedResults.push({
                         taskId,
-                        agentId: pending?.agentId ?? t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider ?? null,
+                        agentId: pending?.agentId ?? t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider?.actor ?? null,
                         status: outcome.status,
                         result: payload,
                     });
@@ -479,7 +479,7 @@ export function applyOutcomeToCtx(ctx, outcome) {
                     existing.status = outcome.status;
                     existing.result = payload;
                     if (existing.agentId == null) {
-                        existing.agentId = t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider ?? null;
+                        existing.agentId = t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider?.actor ?? null;
                     }
                 }
                 if (agId) {

package/dist/runtime/mandateDeclaration.d.ts

@@ -0,0 +1,9 @@
+import type { ToolManager } from '../tools/ToolManager.js';
+/**
+ * Add the wake's own mandate to a tool call that declares one and left it blank.
+ *
+ * Returns the args unchanged whenever there is nothing to say: the tool takes no
+ * declaration, the model already made one, or this wake is not running inside a
+ * job at all.
+ */
+export declare function withDeclaredMandate(args: Record<string, unknown>, toolName: string | null | undefined, toolManager: ToolManager | undefined, activeAgreementId: string | null | undefined): Record<string, unknown>;

package/dist/runtime/mandateDeclaration.js

@@ -0,0 +1,62 @@
+/**
+ * Fill in the job an agent is working inside, so it does not have to.
+ *
+ * The consent gate excuses an agreement an agent forms INSIDE a job its human
+ * already approved, and it verifies the claim server-side. What was missing was
+ * the claim itself: nothing on the agent surface said "I am doing this as part
+ * of job X", so every engagement an agent formed arrived as an outsider and
+ * waited on a human — including buying the help the job it was hired for needs.
+ *
+ * The declaration is made at the CALLER, never resolved on the server: the
+ * agreements module must not read the tasks module, and a guessed mandate is a
+ * false claim the termination cascade would act on destructively. Here the fact
+ * is free — the runtime already knows which task this wake is executing and
+ * which agreement that task runs under, which is exactly the answer.
+ *
+ * The model can still name a job itself (and does, when it is working on
+ * something other than its assigned task). An explicit value is never
+ * overwritten, including an explicit empty string, which reads as "this belongs
+ * to no job" — the difference between saying nothing and saying none.
+ */
+/**
+ * The parameter a tool uses to carry the declaration.
+ *
+ * Two names, because the doors differ and each name is true at its own door: on
+ * a tool that CREATES an agreement the job becomes that row's parent, so the
+ * field is the parent id; on a tool that claims a row somebody else posted
+ * nothing is re-parented — the lineage stays with the publisher — and the job is
+ * only an authority. Listed together here so the runtime has one place that
+ * knows both, rather than a name test at each call site.
+ */
+const MANDATE_PARAM_NAMES = ['mandateAgreementId', 'parentAgreementId'];
+/** The mandate parameter this tool declares, if it declares one. */
+function mandateParamOf(toolName, toolManager) {
+    if (!toolName)
+        return null;
+    const schema = toolManager?.getTool?.(toolName)?.schema;
+    const properties = schema?.function?.parameters?.properties;
+    if (!properties)
+        return null;
+    for (const name of MANDATE_PARAM_NAMES) {
+        if (Object.prototype.hasOwnProperty.call(properties, name))
+            return name;
+    }
+    return null;
+}
+/**
+ * Add the wake's own mandate to a tool call that declares one and left it blank.
+ *
+ * Returns the args unchanged whenever there is nothing to say: the tool takes no
+ * declaration, the model already made one, or this wake is not running inside a
+ * job at all.
+ */
+export function withDeclaredMandate(args, toolName, toolManager, activeAgreementId) {
+    if (!activeAgreementId)
+        return args;
+    const param = mandateParamOf(toolName, toolManager);
+    if (!param)
+        return args;
+    if (args[param] !== undefined)
+        return args;
+    return { ...args, [param]: activeAgreementId };
+}

package/dist/runtime/runTurn.js

@@ -1,6 +1,7 @@
 import { outcomeFromActionResult } from './buildOutcome.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { safeParseJSON } from '../utils/jsonExtractor.js';
+import { withDeclaredMandate } from './mandateDeclaration.js';
 const MAX_TOOL_LOOP_ITERS = 20;
 const MAX_MSG_CHARS = 3500;
 /**
@@ -260,6 +261,9 @@ export async function runTurn(input) {
                     args = JSON.parse(tc.function.arguments || '{}');
                 }
                 catch { }
+                // Say which job this is part of, when the tool asks and the model did
+                // 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);
                 toolCallResults.push({ tc, matchingAction, result, args, actionDef });
@@ -311,6 +315,10 @@ export async function runTurn(input) {
             const decision = parsed.decision;
             const chosenAction = decision.action;
             const actionDef = actions[chosenAction];
+            // Same mandate declaration as the tool-call path above. Both routes reach
+            // the same tools, so filling it on only one would make the excuse depend on
+            // which shape the model happened to answer in.
+            decision.args = withDeclaredMandate((decision.args ?? {}), actionDef?.tool, toolManager, ctx.activeAgreementId);
             if (decision.thought)
                 await emitThought(decision.thought);
             // 2-call streaming: if this is a respond action (has receiverId, no bound tool),

package/dist/server/ConnectionPool.d.ts

@@ -16,6 +16,7 @@ export interface SendToOptions {
 export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
+    private readonly hosts;
     private readonly responseListeners;
     /**
      * Register N agent configs. Nothing connects until `connectAll()`; a config
@@ -29,6 +30,24 @@ export declare class ConnectionPool {
     startAgent(agentId: string): Promise<AgentHost>;
     stopAgent(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
+    /**
+     * Shut the fleet down without abandoning work: stop taking new deliveries
+     * everywhere, THEN wait for in-flight turns to finish.
+     *
+     * The order is the whole point. Draining one agent while the others still
+     * long-poll leaves a window — as long as the drain — in which a host that is
+     * on its way out keeps accepting new work. On a rolling deploy the replacement
+     * is already live and polling the same inboxes, so that window is where one
+     * delivery gets handled twice: two hosts, one request, two answers.
+     *
+     * `disconnect()` only stops the inbox loop and timers; in-flight ticks live in
+     * each host's event queue, which is what `drain()` waits on. So stopping
+     * intake first costs nothing that is already running.
+     *
+     * A host that cannot finish inside `timeoutMs` is left behind rather than
+     * holding up the rest — the caller is on a shutdown clock of its own.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
     /**
      * Deliver a message to the named agent and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.

package/dist/server/ConnectionPool.js

@@ -19,6 +19,10 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 export class ConnectionPool {
     manager = new ConnectionManager();
     configs = new Map();
+    // Live hosts, so shutdown can drain them. The manager hands its handles to
+    // open/close callbacks and does not expose them, and re-reading one through
+    // `startAgent` after a stop would reconnect the agent we are shutting down.
+    hosts = new Map();
     // Listeners enqueued by requestFrom — drained on outbound send-message effects.
     responseListeners = new Map();
     /**
@@ -56,10 +60,12 @@ export class ConnectionPool {
                     },
                 });
                 await host.connectAsync();
+                this.hosts.set(agentId, host);
                 runtimeLog.debug('ConnectionPool', `connected "${agentId}"`);
                 return host;
             }, async (host) => {
                 host.disconnect();
+                this.hosts.delete(agentId);
                 runtimeLog.debug('ConnectionPool', `disconnected "${agentId}"`);
             }, metaByAgentId.get(agentId));
         }
@@ -78,6 +84,30 @@ export class ConnectionPool {
     async disconnectAll() {
         return this.manager.stopAll();
     }
+    /**
+     * Shut the fleet down without abandoning work: stop taking new deliveries
+     * everywhere, THEN wait for in-flight turns to finish.
+     *
+     * The order is the whole point. Draining one agent while the others still
+     * long-poll leaves a window — as long as the drain — in which a host that is
+     * on its way out keeps accepting new work. On a rolling deploy the replacement
+     * is already live and polling the same inboxes, so that window is where one
+     * delivery gets handled twice: two hosts, one request, two answers.
+     *
+     * `disconnect()` only stops the inbox loop and timers; in-flight ticks live in
+     * each host's event queue, which is what `drain()` waits on. So stopping
+     * intake first costs nothing that is already running.
+     *
+     * A host that cannot finish inside `timeoutMs` is left behind rather than
+     * holding up the rest — the caller is on a shutdown clock of its own.
+     */
+    async shutdown(timeoutMs = 30_000) {
+        const hosts = [...this.hosts.values()];
+        await this.manager.stopAll();
+        await Promise.all(hosts.map((host) => host.drain(timeoutMs).catch((err) => {
+            runtimeLog.warn('ConnectionPool', `drain did not finish: ${err.message}`);
+        })));
+    }
     /**
      * Deliver a message to the named agent and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.

package/dist/server/OutboxBuffer.d.ts

@@ -24,7 +24,7 @@ export declare class OutboxBuffer {
     constructor(options?: OutboxBufferOptions);
     track(chatId: string, msg: {
         text: string;
-        receiverId: string;
+        receiverId?: string;
     }): void;
     merge(chatId: string, history: HistoryEntryShape[], agentId: string | null): void;
     gc(): void;

package/dist/server/ZiggsEffectHandler.d.ts

@@ -35,7 +35,7 @@ export interface ZiggsEffectDeps {
     contextReadClient: ContextReadClient;
     taskService: TaskService;
     agreementService: AgreementService;
-    messageSender: (text: string, receiverId: string, sessionId: string, messageId?: string) => Promise<unknown>;
+    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string) => Promise<unknown>;
     /** Sends a streaming chunk to a client. Called per-token during stream-text effects. */
     chunkSender?: (sessionId: string, receiverId: string, text: string, messageId: string) => void;
     toolManager: ToolManager;

package/dist/server/ZiggsEffectHandler.js

@@ -15,7 +15,7 @@ const emptySnapshot = (agentId, chatMissing = false) => ({
     history: [],
     agreements: [],
     users: [],
-    agents: [{ agentId, role: 'self', isYou: true }],
+    agents: [{ agentId, role: 'self', isYou: true, kind: 'agent' }],
     latestSequence: null,
     ...(chatMissing ? { chatMissing: true } : {}),
 });
@@ -26,7 +26,11 @@ async function buildSnapshot(deps, chatId, agentId, opts = {}) {
         const snap = await deps.contextReadClient.snapshot(chatId, {
             maxMessages: opts.limit,
         });
-        return snap;
+        // Built rather than cast: the roster rows are typed on both sides now (they
+        // carry the declared participant kind), and only `history` is loose on the
+        // wire, so a whole-object cast would be asserting past the one field that
+        // actually needs it.
+        return { ...snap, history: snap.history };
     }
     catch (err) {
         // Defensive: server normally signals a dead chat as 200 + chatMissing, but

package/dist/server/agreements/AgreementService.d.ts

@@ -1,4 +1,4 @@
-import { type Agreement, type ClaimedKind, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateAgreementBody, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType, type UserRole } from '@ziggs-ai/api-client';
+import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType, type UserRole } from '@ziggs-ai/api-client';
 export declare class AgreementService {
     private creds;
     constructor(operatorKey: string, agentId: string);
@@ -20,20 +20,27 @@ export declare class AgreementService {
     delegate(payload: DelegateAgreementData): Promise<Agreement>;
     respond(agreementId: string, action: 'approve' | 'reject'): Promise<Agreement>;
     /**
-     * claim any open broadcast (quest, standing offer, hand-off,
+     * claim any open broadcast (request, standing offer, hand-off,
      * link invite). Routing (offer vs agreement claim endpoint) is decided in
      * the shared flow; `kind` is the api-client ClaimedKind so this signature
      * can't drift from the flow again (a 'hand-off' addition broke the build).
      */
-    claim(agreementId: string): Promise<{
+    claim(agreementId: string, opts?: ClaimOptions): Promise<{
         agreement: Agreement;
         kind: ClaimedKind;
     }>;
     /**
-     * a link proposal is an agreement (engagementKind 'link') to one
-     * agent; the target owner approves. Folds the old request_link tool.
+     * Connect with the person an agent answers for.
+     *
+     * `to` is an email or an agent id. A link is with the PERSON either way: an id
+     * is only a way to find its owner, and one that answers to an org is refused.
+     *
+     * The reply says only that the invitation went. Handing back the agreement for
+     * an id target while an address target got a bare acknowledgement told the
+     * caller more about one kind of target than the other, which made the id form
+     * a way to check who has an account.
      */
-    requestLink(providerId: string, description?: string): Promise<Agreement>;
+    requestLink(to: string, description?: string): Promise<CreateLinkResult>;
     counter(agreementId: string, counter: CounterAgreementData): Promise<Agreement>;
     getStatus(agreementId: string): Promise<unknown | null>;
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
@@ -45,10 +52,12 @@ export declare class AgreementService {
      */
     mine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(agreementId: string): Promise<Agreement | null>;
-    create(body: CreateAgreementBody): Promise<{
-        ok: boolean;
-        agreement: Agreement;
-    }>;
+    /**
+     * Connect with someone — by email, by agent id, or with a share link. Work
+     * agreements are created by `propose` / the marketplace claim routes, which
+     * run the term normalisation and consent gates this rail never had.
+     */
+    createLink(body: CreateLinkBody): Promise<CreateLinkResult>;
     revoke(agreementId: string): Promise<{
         ok: boolean;
         agreement: Agreement;

package/dist/server/agreements/AgreementService.js

@@ -1,4 +1,4 @@
-import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createAgreement, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
+import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
 export class AgreementService {
     creds;
     constructor(operatorKey, agentId) {
@@ -38,21 +38,27 @@ export class AgreementService {
         return respondToAgreement(agreementId, action, this.creds);
     }
     /**
-     * claim any open broadcast (quest, standing offer, hand-off,
+     * claim any open broadcast (request, standing offer, hand-off,
      * link invite). Routing (offer vs agreement claim endpoint) is decided in
      * the shared flow; `kind` is the api-client ClaimedKind so this signature
      * can't drift from the flow again (a 'hand-off' addition broke the build).
      */
-    claim(agreementId) {
-        return claimOpenAgreement(agreementId, this.creds);
+    claim(agreementId, opts = {}) {
+        return claimOpenAgreement(agreementId, this.creds, opts);
     }
     /**
-     * a link proposal is an agreement (engagementKind 'link') to one
-     * agent; the target owner approves. Folds the old request_link tool.
+     * Connect with the person an agent answers for.
+     *
+     * `to` is an email or an agent id. A link is with the PERSON either way: an id
+     * is only a way to find its owner, and one that answers to an org is refused.
+     *
+     * The reply says only that the invitation went. Handing back the agreement for
+     * an id target while an address target got a bare acknowledgement told the
+     * caller more about one kind of target than the other, which made the id form
+     * a way to check who has an account.
      */
-    async requestLink(providerId, description) {
-        const { agreement } = await createAgreement({ engagementKind: 'link', providerId, ...(description ? { description } : {}) }, this.creds);
-        return agreement;
+    async requestLink(to, description) {
+        return createLink({ to, ...(description ? { description } : {}) }, this.creds);
     }
     counter(agreementId, counter) {
         return counterAgreement(agreementId, counter || {}, this.creds);
@@ -75,8 +81,13 @@ export class AgreementService {
     get(agreementId) {
         return getAgreement(agreementId, this.creds);
     }
-    create(body) {
-        return createAgreement(body, this.creds);
+    /**
+     * Connect with someone — by email, by agent id, or with a share link. Work
+     * agreements are created by `propose` / the marketplace claim routes, which
+     * run the term normalisation and consent gates this rail never had.
+     */
+    createLink(body) {
+        return createLink(body, this.creds);
     }
     revoke(agreementId) {
         return revokeAgreement(agreementId, this.creds);