@ziggs-ai/agent-sdk 0.10.8 → 0.11.1

package/dist/agent/claudeCognition.d.ts

@@ -52,7 +52,7 @@ export declare function resolveClaudeModel(preferred?: string, servicesModel?: s
  * fixed here; callers only supply the per-wake variables (prompt, model, tools,
  * turn budget, resume). Returns `Options` so it drops straight into `query()`.
  *
- * ZIG-788 — prompt caching. The system prompt is handed over as blocks with a
+ * prompt caching. The system prompt is handed over as blocks with a
  * trailing `SYSTEM_PROMPT_DYNAMIC_BOUNDARY`: everything before the marker is
  * eligible for cross-session caching, and there is nothing after it because
  * nothing in this prompt varies per wake. Every per-wake input — the event, the
@@ -75,7 +75,7 @@ export declare function claudeQueryOptions(params: ClaudeQueryOptionsParams): Op
  * Concatenate the text blocks of a completed Claude assistant turn. Tool-use,
  * thinking, and other block kinds are skipped — only the model's user-facing
  * prose is returned (empty string for a pure tool-use turn). This is what a
- * Claude-brain wake records as a `thought` per turn (ZIG-787), the same way
+ * Claude-brain wake records as a `thought` per turn, the same way
  * the FSM's `emitThought` surfaces the model's reasoning.
  */
 export declare function extractAssistantText(message: SDKAssistantMessage): string;
@@ -86,7 +86,7 @@ export declare function summarizeContext(snap: Record<string, unknown> | null |
  * Claude-brain turn. The agent's standing instructions come from its system
  * prompt (protocol + role); this is just "here's what woke you, go handle it."
  *
- * ZIG-880: EventQueue coalesces events that arrive while the lane is busy into
+ * EventQueue coalesces events that arrive while the lane is busy into
  * a `{type:'batch', events:[...]}` frame. The FSM path unwraps those
  * (PromptBuilder), but this path used to render just "Event type: batch" —
  * every payload inside (including task results) was invisible to the model,

package/dist/agent/claudeCognition.js

@@ -32,7 +32,7 @@ export function resolveClaudeModel(preferred, servicesModel) {
  * fixed here; callers only supply the per-wake variables (prompt, model, tools,
  * turn budget, resume). Returns `Options` so it drops straight into `query()`.
  *
- * ZIG-788 — prompt caching. The system prompt is handed over as blocks with a
+ * prompt caching. The system prompt is handed over as blocks with a
  * trailing `SYSTEM_PROMPT_DYNAMIC_BOUNDARY`: everything before the marker is
  * eligible for cross-session caching, and there is nothing after it because
  * nothing in this prompt varies per wake. Every per-wake input — the event, the
@@ -76,7 +76,7 @@ export function claudeQueryOptions(params) {
  * Concatenate the text blocks of a completed Claude assistant turn. Tool-use,
  * thinking, and other block kinds are skipped — only the model's user-facing
  * prose is returned (empty string for a pure tool-use turn). This is what a
- * Claude-brain wake records as a `thought` per turn (ZIG-787), the same way
+ * Claude-brain wake records as a `thought` per turn, the same way
  * the FSM's `emitThought` surfaces the model's reasoning.
  */
 export function extractAssistantText(message) {
@@ -104,7 +104,7 @@ export function summarizeContext(snap) {
 function renderEventLines(event, lines) {
     if (event?.type)
         lines.push(`Event type: ${event.type}`);
-    // ZIG-1035 / ZIG-1052: notifications are not counterparty speech.
+    // notifications are not counterparty speech.
     // agreement_lifecycle is a work signal (hire approval) — label it as such.
     if (event?.text) {
         const label = event.type === 'agreement_lifecycle'
@@ -122,7 +122,7 @@ function renderEventLines(event, lines) {
         (event.operation === 'proposal_approved' || event.operation === 'proposal_approved_execute')) {
         lines.push('Work signal: proposal approved. If you proposed this agreement, spawn the first task (task_create) under it now. If you are the hired provider, begin fulfilling per the agreement — do not ignore this wake.');
     }
-    // ZIG-1278 — store claim wakes as resource_changed (no chat, reason
+    // store claim wakes as resource_changed (no chat, reason
     // proposal_approved). Distinct from the lifecycle hire path above: open the
     // buyer chat first, then greet and serve terms.
     if (event?.type === 'resource_changed') {
@@ -155,7 +155,7 @@ function renderEventLines(event, lines) {
     if (typeof event?.agreementId === 'string' && event.agreementId) {
         lines.push(`Agreement: ${event.agreementId}`);
     }
-    // ZIG-832: surface the task/agreement this event carries. Without it the brain
+    // surface the task/agreement this event carries. Without it the brain
     // can't tell WHICH task to update/complete (workers otherwise stall asking for
     // their own taskId) and can't see whether the referenced step already ran or
     // failed — which makes an orchestrator re-spawn duplicate delegations.
@@ -167,7 +167,7 @@ function renderEventLines(event, lines) {
             lines.push(`Agreement: ${result.agreementId}`);
         if (typeof result.state === 'string')
             lines.push(`Task state: ${result.state}`);
-        // ZIG-860: surface the task's RESULT payload too. Completion notifies now
+        // surface the task's RESULT payload too. Completion notifies now
         // pin it (backend), and an orchestrator consuming a worker's output has no
         // task-read tool — without this line the step outcome never reaches the
         // model and a chained pipeline stalls right after its first task.
@@ -183,7 +183,7 @@ function renderEventLines(event, lines) {
  * Claude-brain turn. The agent's standing instructions come from its system
  * prompt (protocol + role); this is just "here's what woke you, go handle it."
  *
- * ZIG-880: EventQueue coalesces events that arrive while the lane is busy into
+ * EventQueue coalesces events that arrive while the lane is busy into
  * a `{type:'batch', events:[...]}` frame. The FSM path unwraps those
  * (PromptBuilder), but this path used to render just "Event type: batch" —
  * every payload inside (including task results) was invisible to the model,

package/dist/agent/claudeSdkTools.d.ts

@@ -6,12 +6,12 @@ export interface ClaudeSdkToolContext extends Record<string, unknown> {
     chatId?: string | null;
     sessionId?: string | null;
     eff?: EffectHandler;
-    /** Human/agent whose message woke the agent — forwarded to the shared tool executor (ZIG-775). */
+    /** Human/agent whose message woke the agent — forwarded to the shared tool executor. */
     senderId?: string;
     senderType?: string;
-    /** Agreement this wake acts under (ZIG-831) — lets a delegated per-user MCP call resolve the originating end-user. */
+    /** Agreement this wake acts under — lets a delegated per-user MCP call resolve the originating end-user. */
     onBehalfOfAgreementId?: string;
-    /** Per-wake id grouping this tick's tool calls in telemetry (ZIG-775). Random — never use for idempotency. */
+    /** Per-wake id grouping this tick's tool calls in telemetry. Random — never use for idempotency. */
     runId?: string;
     /** Replay-stable write keys for this wake — write tools derive idempotency keys from here, never from the LLM. */
     writeKeys?: DeliveryWriteKeys;

package/dist/agent/claudeSdkTools.js

@@ -3,7 +3,7 @@ import { listTasks } from '@ziggs-ai/api-client';
 import { defineTool } from '../tools/defineTool.js';
 import { listGrantsTool } from '../server/tools/tier2/grantsTools.js';
 import { CHAT_TOOLS } from '../server/tools/tier2/chatTools.js';
-// ZIG-860: default message-history cap. An uncapped snapshot returns the whole
+// default message-history cap. An uncapped snapshot returns the whole
 // chat — in a delegation chat that accumulates notification rows, every wake's
 // snapshot ballooned (observed 35–47k input tokens/wake, ~205k/run). 12 recent
 // messages cover "what woke me and what was just said"; the model can pass a
@@ -12,7 +12,7 @@ const DEFAULT_SNAPSHOT_MAX_MESSAGES = 12;
 /**
  * First usable string among the candidates, treating blank as absent.
  *
- * ZIG-1081: a model that does not know a value fills the field with `""` rather
+ * a model that does not know a value fills the field with `""` rather
  * than omitting it — the schema shows `chatId`, the agent has no way to know it,
  * so it sends an empty string. Plain `??` let that blank win over the lane
  * default, and the very next line rejected it as missing. Every wake opened with
@@ -25,16 +25,33 @@ function firstFilled(...candidates) {
     }
     return undefined;
 }
+/**
+ * Accept the agreement id an agent was woken on where a chat id is wanted.
+ *
+ * An agent woken on an agreement reaches for its context with the only id that
+ * wake gave it — the agreement's. That is not a chat id, so the snapshot came
+ * back empty: no history, no agreements, the agent itself as the only participant,
+ * and a bare `chatMissing`. Observed on the FIRST wake of every two-agent run,
+ * and once it sent the provider off to chat instead of to its own task.
+ *
+ * An agreement's implicit notification chat is `agrn-<agreementId>` — the lane
+ * the backend itself routes agreement traffic through — so the id the agent has
+ * does name a readable room, one prefix away. Mapping it is the difference
+ * between a wasted turn and an answer.
+ */
+function asChatLane(id) {
+    return id?.startsWith('agr_') ? `agrn-${id}` : id;
+}
 // Named distinctly from ziggs-mcp's per-type `ziggs_context_read`: this is the
 // one-shot aggregate snapshot (grant-fenced server-side), not a cursored read.
 export const contextSnapshotTool = defineTool('context_snapshot', {
-    chatId: { type: 'string', description: 'Omit this to snapshot the chat you were woken in — that is the usual case, and you do not need to know its id. Only pass a chatId to snapshot a DIFFERENT chat.' },
+    chatId: { type: 'string', description: 'Omit this to snapshot the chat you were woken in — that is the usual case, and you do not need to know its id. Only pass a chatId to snapshot a DIFFERENT chat. An agreement id is accepted too, and reads that agreement\'s lane.' },
     maxMessages: { type: 'number', description: `Message history cap (default ${DEFAULT_SNAPSHOT_MAX_MESSAGES}). Pass a larger value when you need deeper history.` },
 }, async (args, ctx) => {
     const c = ctx;
     if (!c.eff)
         throw new Error('context_snapshot requires eff in tool context');
-    const sessionId = firstFilled(args.chatId, c.chatId, c.sessionId);
+    const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
     if (!sessionId) {
         throw new Error('context_snapshot: this wake carries no chat to snapshot. Call it with no arguments ' +
             'to read the chat you were woken in; if this wake is on an agreement lane with no ' +
@@ -57,7 +74,9 @@ export const chatSendTool = defineTool('chat_send', {
     const c = ctx;
     if (!c.eff)
         throw new Error('chat_send requires eff in tool context');
-    const sessionId = firstFilled(args.chatId, c.chatId, c.sessionId);
+    // Same agreement-id-where-a-chat-id-goes slip as context_snapshot, and the
+    // same mapping: an agreement's traffic lane is `agrn-<agreementId>`.
+    const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
     if (!sessionId) {
         throw new Error('chat_send: this wake carries no chat to send in. Call it with no chatId to reply in ' +
             'the chat you were woken in, or pass the chatId of the chat you mean.');
@@ -69,9 +88,9 @@ export const chatSendTool = defineTool('chat_send', {
     const receiverId = firstFilled(args.receiverId, c.senderId);
     if (!receiverId)
         throw new Error('chat_send: receiverId is required (this wake has no sender to default to)');
-    // Default to the wake's content-derived key (ZIG-1045): a crash-replay that
+    // Default to the wake's content-derived key: a crash-replay that
     // re-sends the same text re-derives the same messageId and the backend drops
-    // the duplicate (ZIG-718); a re-think with different text gets a new key
+    // the duplicate; a re-think with different text gets a new key
     // instead of colliding on a per-wake ordinal. An explicit LLM idempotencyKey
     // still wins (retry-safe resend of the same logical message across wakes);
     // random only when the wake has no durable identity.
@@ -89,14 +108,14 @@ export const chatSendTool = defineTool('chat_send', {
 }, { description: 'Send a user-visible chat message. Conversation only — never use for finished-work reporting.' });
 // Inbox read/ack are deliberately NOT here: the host owns the pull/ack cycle
 // (its per-agent inbox long-poll loop). A brain-side ack would race the host's,
-// and a per-turn inbox poll fed the tool-operation echo loop (ZIG-759).
+// and a per-turn inbox poll fed the tool-operation echo loop.
 //
-// grant_list IS here (ZIG-893): the hosted agent must always be able to answer
-// "what grants of mine do you hold?" across every rail — the 2026-07-20 incident
-// was a hosted agent with no grant-read tool telling its principal that lookup
-// doesn't exist. It reads operatorKey/agentId straight off the tool context.
+// grant_list IS here: the hosted agent must always be able to answer
+// "what grants of mine do you hold?" across every rail. Without the tool an
+// agent tells its principal the lookup does not exist. It reads
+// operatorKey/agentId straight off the tool context.
 //
-// task_list IS here (ZIG-977): MCP delegates have ziggs_task_list; the hosted
+// task_list IS here: MCP delegates have ziggs_task_list; the hosted
 // Claude surface previously had no way to enumerate its own open tasks (reads
 // were prompt-injected only). Same GET /tasks scope as the MCP tool.
 export const listTasksTool = defineTool('task_list', {
@@ -121,7 +140,7 @@ export const listTasksTool = defineTool('task_list', {
     if (!c.agentId)
         throw new Error('task_list: agentId missing from tool context');
     const assignedTo = args.assignedToMe ? c.agentId : args.assignedTo;
-    // ZIG-1092: the lane fences this to the engagement's tasks. Without it the
+    // the lane fences this to the engagement's tasks. Without it the
     // list is every task the agent's key can reach, across all its customers.
     const laneId = c.chatId || c.sessionId || undefined;
     return listTasks({
@@ -142,7 +161,7 @@ export const CLAUDE_SDK_TOOLS = [
     chatSendTool,
     listGrantsTool,
     listTasksTool,
-    // ZIG-1278 — store-claim providers must open the buyer chat from the default
+    // store-claim providers must open the buyer chat from the default
     // Claude surface (chat_open was tier-2 / email-agent opt-in only).
     ...CHAT_TOOLS,
 ];

package/dist/agent/hostedAgentConnection.d.ts

@@ -1,6 +1,6 @@
 /**
  * Hosted fleet agents connect via api-client (AgentHost), never inbound ziggs-mcp.
- * @see ZIG-781
+ * @see
  */
 export type McpServerSpec = {
     type?: string;

package/dist/agent/hostedAgentConnection.js

@@ -1,6 +1,6 @@
 /**
  * Hosted fleet agents connect via api-client (AgentHost), never inbound ziggs-mcp.
- * @see ZIG-781
+ * @see
  */
 export function looksLikeInboundZiggsMcp(command, args = []) {
     const joined = `${command} ${args.join(' ')}`;

package/dist/agent/toolManagerToSdkMcp.d.ts

@@ -3,7 +3,7 @@ import type { ToolDefinition } from '../tools/defineTool.js';
 import type { ClaudeSdkToolContext } from './claudeSdkTools.js';
 /**
  * Map Ziggs `ToolDefinition`s to Claude Agent SDK MCP tools. Each handler routes
- * execution through `eff({ kind: 'tool-call' })` — the shared executor (ZIG-775).
+ * execution through `eff({ kind: 'tool-call' })` — the shared executor.
  */
 export declare function buildSdkToolDefs(toolDefs: ToolDefinition[], getContext: () => ClaudeSdkToolContext): Array<SdkMcpToolDefinition>;
 export declare function buildZiggsSdkMcpServer(toolDefs: ToolDefinition[], getContext: () => ClaudeSdkToolContext, options?: {

package/dist/agent/toolManagerToSdkMcp.js

@@ -54,7 +54,7 @@ function parametersToZodShape(parameters) {
     return shape;
 }
 /**
- * ZIG-1215 — the Claude brain's args are validated here, before `eff` hands
+ * the Claude brain's args are validated here, before `eff` hands
  * them to the shared executor, so a plain shape means an unknown param is
  * stripped at this layer and ToolManager's own check never sees it. Closing
  * the object is what makes the rejection reach the brain: the call fails with
@@ -82,7 +82,7 @@ function toCallToolError(err) {
 }
 /**
  * Map Ziggs `ToolDefinition`s to Claude Agent SDK MCP tools. Each handler routes
- * execution through `eff({ kind: 'tool-call' })` — the shared executor (ZIG-775).
+ * execution through `eff({ kind: 'tool-call' })` — the shared executor.
  */
 export function buildSdkToolDefs(toolDefs, getContext) {
     return toolDefs.map((def) => {

package/dist/context/applyEffects.js

@@ -21,7 +21,7 @@ function applyTaskOperationResultToContext(updates, operation, result) {
         }
     }
     if (operation === 'task-update') {
-        // `state` only — ZIG-1057 cut `status` from the wire (ZIG-1128).
+        // `state` only cut `status` from the wire.
         const state = (task?.['state'] || r['state']);
         if (state === 'completed')
             updates['taskCompleted'] = true;

package/dist/defineAgent.js

@@ -3,6 +3,8 @@ import { injectKickoffDefault } from './runtime/kickoff.js';
 import { injectTaskIntakeDefault } from './runtime/taskIntake.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 import { DEFAULT_MODEL } from './AgentHost.js';
+import { normalizeNeeds, toolsForNeeds } from './tools/needs.js';
+import { toolName } from './tools/defineTool.js';
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
  * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
@@ -35,7 +37,7 @@ export function defineAgent(input) {
     const workflow = injectTaskIntakeDefault(injectKickoffDefault({
         id: input.agentId,
         // The workflow description is the agent's role text, which PromptBuilder
-        // renders into <self>. ZIG-1080 split that from the store-facing
+        // renders into <self>. split that from the store-facing
         // `description`: prefer the prompt when the author supplied one.
         description: input.systemPrompt || input.description,
         initial: input.initial,
@@ -44,10 +46,34 @@ export function defineAgent(input) {
     const { warnings } = validateWorkflow(workflow);
     for (const w of warnings)
         runtimeLog.warn('defineAgent', w);
-    const tools = [
+    // Tools the DECLARATION produces, not the author. An agent that says
+    // it needs a connection gets the tools to see and use one, so the prompt and
+    // the toolset cannot describe different worlds. Author tools come last and win
+    // on name, so hand-listing a derived tool is a no-op rather than a duplicate.
+    const needs = normalizeNeeds(input.needs);
+    const tools = [];
+    const positionByName = new Map();
+    for (const tool of [
+        ...toolsForNeeds(needs),
         ...(Array.isArray(input.tools) ? input.tools : []),
         ...(Array.isArray(input.services?.tools) ? input.services.tools : []),
-    ];
+    ]) {
+        const name = toolName(tool);
+        // A nameless entry cannot be deduped — keep it and let ToolManager reject
+        // it the way it always has, rather than silently dropping it here.
+        if (!name) {
+            tools.push(tool);
+            continue;
+        }
+        const at = positionByName.get(name);
+        if (at === undefined) {
+            positionByName.set(name, tools.length);
+            tools.push(tool);
+        }
+        else {
+            tools[at] = tool;
+        }
+    }
     // Model resolution, most-specific-first: a per-agent pin, then the
     // fleet-wide `LLM_MODEL` lever, then the single `DEFAULT_MODEL` fallback (the
     // ONE place the default lives — see AgentHost). The id also picks the provider
@@ -68,7 +94,7 @@ export function defineAgent(input) {
         tools,
         model,
         workflow,
-        // ZIG-1288: declaration is the source — receiving dynamic proposals is an
+        // declaration is the source — receiving dynamic proposals is an
         // explicit opt-in, and the default is claim-only (false). Derivation no
         // longer decides; it validates: an explicit opt-in whose workflow wires no
         // agreement_respond action is a declared door that cannot open.
@@ -76,6 +102,9 @@ export function defineAgent(input) {
         ...(input.services ? { services: input.services } : {}),
         ...(taskTools !== undefined ? { taskTools } : {}),
         ...rest,
+        // After `rest`, so the config carries the NORMALIZED needs — AgentHost
+        // enforces these at task start and should not have to re-parse the raw field.
+        ...(needs.length ? { needs } : {}),
     };
     return Object.freeze(config);
 }

package/dist/formatters/HistoryFormatter.js

@@ -24,7 +24,7 @@ export class HistoryFormatter {
             const label = labelTypes ? '[CHAT] ' : '';
             return `${label}${this.formatMessage(entry, agentId, timePrefix)}`;
         }
-        // ZIG-1035: notices are not counterparty turns — no "from → to:" speech framing.
+        // notices are not counterparty turns — no "from → to:" speech framing.
         if (entryType === 'notification') {
             const label = labelTypes ? '[NOTICE] ' : '';
             return `${label}${timePrefix}[notice] ${entry['text'] || ''}`;
@@ -126,7 +126,7 @@ export class HistoryFormatter {
             return 'System';
         if (id === agentId)
             return 'You';
-        // ZIG-1137: prefer presentation face when the wire masks the principal.
+        // prefer presentation face when the wire masks the principal.
         const presentation = participant['presentation'];
         const faceName = (typeof presentation?.['name'] === 'string' && presentation['name']) ||
             (typeof presentation?.['persona']?.['name'] === 'string'

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export type { CognitionKind } from './agent/ClaudeSdkAgent.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';
-export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
+export type { SessionResolver, AgentHostOptions, WakeRecord } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 export type { ZiggsEffectDeps } from './server/ZiggsEffectHandler.js';
 export { EventQueue } from './server/EventQueue.js';
@@ -52,13 +52,15 @@ export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
 export { recordReport } from './tools/recordReport.js';
 export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
+export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
+export type { AgentNeed, ConnectionNeed } from './tools/needs.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';
 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, 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, 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 { 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

@@ -48,16 +48,19 @@ export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
 export { recordReport } from './tools/recordReport.js';
+// An agent declares the access it cannot work without, and the declaration
+// produces the tools for it.
+export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';
 export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
 export { PollRegistry, declaredPolls, } from './server/polls/PollKind.js';
 export { PollRunner } from './server/polls/PollRunner.js';
-// ZIG-894 — the hand-rolled ZiggsPayClient / ZiggsConnectClient were deleted;
+// the hand-rolled ZiggsPayClient / ZiggsConnectClient were deleted;
 // payment and connection tools now use @ziggs-ai/api-client's PaymentsClient /
 // ConnectionsClient, the same clients ziggs-mcp uses.
-// ZIG-869 — the hand-rolled ZiggsContextClient was deleted; context tools now
+// the hand-rolled ZiggsContextClient was deleted; context tools now
 // use the same @ziggs-ai/api-client clients as ziggs-mcp (GrantsClient /
 // ContextGrantsClient / ContextReadClient). Grant/reach types live there.
 // All agent tool bundles live under server/tools/ (tier1 = protocol grammar,
@@ -66,8 +69,8 @@ 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, 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';
-// The always-on toolset for the hosted Claude cognition (ZIG-903 parity guard
+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';
+// 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';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
@@ -77,7 +80,7 @@ export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
 export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, 
-// ZIG-1204 — self-hosted / non-default backend: consumers of agent-sdk alone
+// self-hosted / non-default backend: consumers of agent-sdk alone
 // must be able to point the shared HTTP client without a direct api-client dep.
 configureApiClient, } from '@ziggs-ai/api-client';
 export { SeenMessages } from './server/SeenMessages.js';

package/dist/ingress/normalizeIncoming.d.ts

@@ -12,7 +12,7 @@ export interface NormalizedEvent {
         messageId?: string;
         timestamp: number;
         /**
-         * `notification` = lifecycle / status notice (ZIG-1035). Not counterparty
+         * `notification` = lifecycle / status notice. Not counterparty
          * speech; Claude parks without a model turn. Terminal task notices still
          * use `task_result` so orchestrators see completions.
          */

package/dist/ingress/normalizeIncoming.js

@@ -33,7 +33,7 @@ function wireAgreementId(metadata) {
  * Self-hire / fully-consented create activates before the chat fan-out lands.
  * The wire still says `proposal_created`, but the embedded agreement is already
  * `active` / proposal `approved`. That is the hire work signal (same as
- * `proposal_approved_execute`) — Claude must not park it as a notice (ZIG-1052).
+ * `proposal_approved_execute`) — Claude must not park it as a notice.
  */
 function isAlreadyActivatedProposalCreated(metadata) {
     if (wireOperation(metadata) !== 'proposal_created')
@@ -46,13 +46,13 @@ function isAlreadyActivatedProposalCreated(metadata) {
     return status === 'active' || proposalStatus === 'approved';
 }
 /**
- * ZIG-1078 — a `proposal_created` notification addressed to a party whose
+ * a `proposal_created` notification addressed to a party whose
  * approval is PENDING is a consent REQUEST, not a status notice. The backend
  * fans `proposal_created` out specifically to the pending approvers
- * (ZIG-244), and parking it meant the hand-off provider (ZIG-1059) — or any
+ *, and parking it meant the hand-off provider — or any
  * agent whose consent a proposal awaits — was alerted and then never looked:
  * the approval sat pending until a human nudged the chat. Same technique as
- * isAlreadyActivatedProposalCreated (ZIG-1052): reclassify by what the
+ * isAlreadyActivatedProposalCreated: reclassify by what the
  * embedded agreement SAYS rather than adding a new wake word.
  */
 function isPendingApprovalRequestNotification(metadata) {
@@ -90,7 +90,7 @@ function isTerminalTaskState(state) {
  * compatibility but no longer gates anything.
  */
 export function normalizeIncomingEvent({ text, metadata = {} }) {
-    // ZIG-936: classifier data lives under `service` on the inbox-pull wire;
+    // classifier data lives under `service` on the inbox-pull wire;
     // fall back to top-level for hand-built (direct-injection) metadata.
     const taskData = (metadata.service?.task ?? metadata.task) || null;
     const chatId = normalizeChatId(metadata);
@@ -124,7 +124,7 @@ export function normalizeIncomingEvent({ text, metadata = {} }) {
         };
     }
     if (isTaskRelated(metadata, taskData)) {
-        // ZIG-1035: active/spawn chat notices are not work — real assignment arrives
+        // active/spawn chat notices are not work — real assignment arrives
         // on the task channel (`tasksAwaitingMe` → wakeTaskAssignment). Keep terminal
         // task notices as `task_result` so orchestrators still see completions.
         if (entryType === 'notification' && !isTerminalTaskState(taskData?.state)) {
@@ -144,7 +144,7 @@ export function normalizeIncomingEvent({ text, metadata = {} }) {
             event: { ...base, type: 'task_result', result: taskData, text },
         };
     }
-    // ZIG-1035: residual lifecycle notices (proposal_created, agreement active, …)
+    // residual lifecycle notices (proposal_created, agreement active, …)
     // must not fall through as counterparty `message` speech.
     if (entryType === 'notification') {
         const operation = metadata.service?.operation ?? metadata.operation;

package/dist/pricing/fleetDefaults.d.ts

@@ -1,5 +1,5 @@
 /**
- * ZIG-368 — default paid pricing for Ziggs-operated (first-party) agents.
+ * default paid pricing for Ziggs-operated (first-party) agents.
  * Prices are in wallet cents (1 ZIG = 100 cents).
  */
 import { type FleetPricingTier } from './fleetTierByAgentId.gen.js';
@@ -22,7 +22,7 @@ export interface ProtocolPricingPayload {
     [key: string]: unknown;
 }
 /**
- * Apply ZIG-368 defaults when `price` is omitted (null/undefined).
+ * Apply defaults when `price` is omitted (null/undefined).
  * Explicit `price: 0` is kept (free-on-purpose).
  */
 export declare function applyFleetAgreementPricing(operation: 'agreement-propose' | 'agreement-subcontract', payload: ProtocolPricingPayload, actingAgentId: string): ProtocolPricingPayload;
@@ -36,7 +36,7 @@ export declare function applyFleetAgreementPricing(operation: 'agreement-propose
  */
 export declare function applyFleetCounterPricing<T extends ProtocolPricingPayload>(payload: T, actingAgentId: string): T;
 /**
- * Infer fleet actor when tool context omits agentId (ZIG-368 safety net).
+ * Infer fleet actor when tool context omits agentId (safety net).
  */
 export declare function inferFleetPricingActorId(payload: ProtocolPricingPayload): string | null;
 /** Apply fleet defaults with optional acting agent (falls back to payload inference). */

package/dist/pricing/fleetDefaults.js

@@ -1,5 +1,5 @@
 /**
- * ZIG-368 — default paid pricing for Ziggs-operated (first-party) agents.
+ * default paid pricing for Ziggs-operated (first-party) agents.
  * Prices are in wallet cents (1 ZIG = 100 cents).
  */
 import { FLEET_TIER_BY_AGENT_ID } from './fleetTierByAgentId.gen.js';
@@ -54,7 +54,7 @@ export function resolveDefaultPriceCentsForExecutor(executorId, description) {
     return tierPriceCents(tier);
 }
 /**
- * Apply ZIG-368 defaults when `price` is omitted (null/undefined).
+ * Apply defaults when `price` is omitted (null/undefined).
  * Explicit `price: 0` is kept (free-on-purpose).
  */
 export function applyFleetAgreementPricing(operation, payload, actingAgentId) {
@@ -122,7 +122,7 @@ export function applyFleetCounterPricing(payload, actingAgentId) {
     return { ...payload, price: cents };
 }
 /**
- * Infer fleet actor when tool context omits agentId (ZIG-368 safety net).
+ * Infer fleet actor when tool context omits agentId (safety net).
  */
 export function inferFleetPricingActorId(payload) {
     const executor = payload.executorId != null ? String(payload.executorId) : '';

package/dist/pricing/fleetEvalFree.d.ts

@@ -1,5 +1,5 @@
 /**
- * ZIG-395 — eval/harness free pricing via env flag (no SANDBOX id-shape regex).
+ * eval/harness free pricing via env flag (no SANDBOX id-shape regex).
  */
 /** Capability-probe + test harness agents (agents/test/). */
 export declare const EVAL_HARNESS_AGENT_IDS: Set<string>;

package/dist/pricing/fleetEvalFree.js

@@ -1,5 +1,5 @@
 /**
- * ZIG-395 — eval/harness free pricing via env flag (no SANDBOX id-shape regex).
+ * eval/harness free pricing via env flag (no SANDBOX id-shape regex).
  */
 /** Capability-probe + test harness agents (agents/test/). */
 export const EVAL_HARNESS_AGENT_IDS = new Set([

package/dist/pricing/fleetFreeTierA.gen.d.ts

@@ -1,6 +1,6 @@
 /**
  * AUTO-GENERATED by scripts/build-fleet-tier-map.mjs — do not edit by hand.
- * ZIG-368: Tier A trivial public lookups (free when price omitted).
+ * Tier A trivial public lookups (free when price omitted).
  */
 export declare const FREE_TIER_A_AGENT_IDS: Set<string>;
 export declare const FREE_TIER_A_COUNT = 4;

package/dist/pricing/fleetFreeTierA.gen.js

@@ -1,6 +1,6 @@
 /**
  * AUTO-GENERATED by scripts/build-fleet-tier-map.mjs — do not edit by hand.
- * ZIG-368: Tier A trivial public lookups (free when price omitted).
+ * Tier A trivial public lookups (free when price omitted).
  */
 export const FREE_TIER_A_AGENT_IDS = new Set([
     "site-health-checker",

package/dist/pricing/fleetTierByAgentId.gen.d.ts

@@ -1,7 +1,7 @@
 /**
  * AUTO-GENERATED by scripts/build-fleet-tier-map.mjs — do not edit by hand.
- * ZIG-368: agent-sdk local default pricing (backend uses agent.pricingTier — ZIG-395).
+ * Local default pricing; the server resolves an agent's own pricing tier.
  */
 export type FleetPricingTier = 'A' | 'B' | 'C' | 'D';
 export declare const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier>;
-export declare const FLEET_TIER_MAP_SIZE = 765;
+export declare const FLEET_TIER_MAP_SIZE = 772;