@ziggs-ai/agent-sdk 0.38.2 → 0.38.4

package/README.md

@@ -131,9 +131,9 @@ configureApiClient({ httpUrl: 'https://api.example.com' });
 
 A **runner** is the operator’s process. It starts agents, serves health and
 coordinates shutdown. It is not another part of the customer’s agent model.
-The repository’s private `@ziggs-ai/agent-runner` workspace owns `runAgents` and
-`createHealthServer`; these are not SDK exports. An operator deploys the runner
-and supplies a supervisor such as ECS to restart the process when it exits.
+`runAgents` and `createHealthServer` are exported from this package. The health
+page answers `/` and `/health`. A process that needs another route, such as
+starting one of our hosted agents, adds it itself.
 
 ## Migration
 
@@ -146,7 +146,7 @@ This is a breaking pre-beta rename; update imports before publishing this releas
 | `ClaudeSdkAgent`, `ClaudeSdkAgentOptions` | `ClaudeBrain`, `ClaudeBrainOptions` |
 | `host.agent` | `agent.brain` |
 | `createMcpAgent(...).host` | `createMcpAgent(...).agent` |
-| SDK `runLauncher`, `createHealthServer` | Operator package `runAgents`, `createHealthServer` |
+| SDK `runLauncher`, `createHealthServer` | SDK `runAgents`, `createHealthServer` |
 
 `createAgent`, `ziggsBrain`, `claudeBrain` and agent IDs on the wire retain their
 names. No backend identity or stored data migration is required.

package/dist/Agent.js

@@ -314,7 +314,7 @@ export class Agent {
             operatorKey: this.options.operatorKey,
             agentId: this.options.agentId,
         };
-        const messageSender = async (message, receiverId, sessionId, messageId, conversationAgreementId, underAgreementId, taskId) => {
+        const messageSender = async (message, receiverId, sessionId, messageId, conversationAgreementId, underAgreementId, taskId, sources) => {
             const sentId = messageId ?? `sdk_${randomUUID()}`;
             const result = await sendChatMessage({
                 chatId: sessionId,
@@ -330,6 +330,7 @@ export class Agent {
                 conversationAgreementId,
                 underAgreementId,
                 taskId,
+                ...(sources ? { sources } : {}),
             }, creds);
             if (!result.success)
                 throw new Error('sendChatMessage: the server did not accept this message — nothing was delivered and nobody was woken. Retry with the same messageId, which the backend dedups on.');

package/dist/brain/ClaudeBrain.d.ts

@@ -5,7 +5,7 @@ import type { ToolManager } from '../tools/ToolManager.js';
 import { type RawEvent } from '../runtime/buildOutcome.js';
 import type { TickInput, TickOutput } from './ZiggsBrain.js';
 import { type AskWakeGate } from './wakeGate.js';
-export { isPublishProbeChat, isCapabilityProbeSession } from '../probeChat.js';
+export { isPublishProbeChat } from '../probeChat.js';
 /**
  * status notices must not spend a Claude turn answering
  * nobody. Real work wakes arrive as chat `message`, synthetic `task_result`

package/dist/brain/ClaudeBrain.js

@@ -17,7 +17,7 @@ import { filterStandingOfferNotices, isReadableAgreementNoticeLane } from './sta
 import { formedByFromWake, shouldSkipAgentFormedHireActivation, } from './hireActivationNotice.js';
 import { isPublishProbeChat } from '../probeChat.js';
 import { gateableMessages, wakeAgreementId } from './wakeGate.js';
-export { isPublishProbeChat, isCapabilityProbeSession } from '../probeChat.js';
+export { isPublishProbeChat } from '../probeChat.js';
 /**
  * status notices must not spend a Claude turn answering
  * nobody. Real work wakes arrive as chat `message`, synthetic `task_result`

package/dist/brain/claudeSdkTools.js

@@ -1,3 +1,4 @@
+import { SOURCES_PARAM, sourcesArg } from '@ziggs-ai/api-client';
 import { isAgreementId, agreementLaneId } from '@ziggs-ai/api-client';
 import { randomUUID } from 'node:crypto';
 import { credsFromToolContext } from '../tools/toolCreds.js';
@@ -77,8 +78,10 @@ export const chatSendTool = defineTool('chat_send', {
     receiverId: { type: 'string', description: 'Name someone only when you mean them. Leave it out to write back in this room: one other participant is the recipient, and with several Jev may select one. Otherwise the message stays in the room with no specific wake. To name a masked party, pass its rpb_ ref as it came. Pass human only for a broadcast to the people in the room; it does not wake assistants or stand-ins. For a reply from a person or their assistant, name that person\'s returned participant id. This does not grant their assistant access or guarantee a reply.' },
     text: { type: 'string', required: true },
     idempotencyKey: { type: 'string', description: 'Reuse for retry-safe resend of the same logical message.' },
+    sources: SOURCES_PARAM,
 }, async (args, ctx) => {
     const c = ctx;
+    const sources = sourcesArg(args);
     const explicitChatId = asChatLane(firstFilled(args.chatId));
     const to = firstFilled(args.to);
     const text = String(args.text);
@@ -104,6 +107,7 @@ export const chatSendTool = defineTool('chat_send', {
             underAgreementId: firstFilled(args.underAgreementId, c.serviceAgreementId),
             taskId: firstFilled(args.taskId),
             ...(namedReceiver ? { receiverId: namedReceiver } : {}),
+            ...sources,
         }, creds);
         // Never presented as a send that happened: the message does not exist,
         // so whoever was waiting for it is still waiting. Retrying with the same
@@ -141,6 +145,7 @@ export const chatSendTool = defineTool('chat_send', {
         ...(receiverId ? { receiverId } : {}),
         text,
         messageId,
+        ...sources,
     });
 }, 
 // This line used to read "Conversation only — never use for

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export { runMechanical } from './runtime/runMechanical.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
 export { thinkingDefaults, defineThinkingState, defineMechanicalState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
 export { KICKOFF_STATE, CLAIM_KICKOFF_STATE, injectKickoffDefault, buildKickoffState, buildClaimKickoffState, handlesClaimWake, } from './runtime/kickoff.js';
-export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
+export { validateWorkflow, WorkflowValidationError, PROBE_CTX } from './runtime/validateWorkflow.js';
 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';
@@ -67,7 +67,7 @@ export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormat
 export { ProactiveTrigger } from './platform/proactive/ProactiveTrigger.js';
 export { PollRegistry, declaredPolls, type PollBinding, type PollContext, type PollKind, type PollResult, } from './platform/polls/PollKind.js';
 export { PollRunner, type PollRunnerOptions, type WakeTarget } from './platform/polls/PollRunner.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, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, LISTING_TOOLS, } from './platform/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, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, LISTING_TOOLS, } from './platform/tools/index.js';
 export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
 export { hostedModelTools, isHostedDeferred, hostedToolLane } from './brain/hostedToolSurface.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
@@ -83,3 +83,7 @@ export type { ApiClientConfig } from '@ziggs-ai/api-client';
 export { SeenMessages } from './platform/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export type { RuntimeLogLevel } from './shared/runtimeLog.js';
+export { runAgents } from './launcher/runAgents.js';
+export type { RunnerOptions, SingleAgentRun, FleetRun } from './launcher/runAgents.js';
+export { createHealthServer, inboxHealth } from './launcher/createHealthServer.js';
+export type { AgentLiveness, HealthRequest, HealthRequestHandler } from './launcher/createHealthServer.js';

package/dist/index.js

@@ -42,7 +42,7 @@ export { runMechanical } from './runtime/runMechanical.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
 export { thinkingDefaults, defineThinkingState, defineMechanicalState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
 export { KICKOFF_STATE, CLAIM_KICKOFF_STATE, injectKickoffDefault, buildKickoffState, buildClaimKickoffState, handlesClaimWake, } from './runtime/kickoff.js';
-export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
+export { validateWorkflow, WorkflowValidationError, PROBE_CTX } from './runtime/validateWorkflow.js';
 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';
@@ -79,7 +79,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, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, LISTING_TOOLS, } from './platform/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, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, LISTING_TOOLS, } from './platform/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 './brain/claudeSdkTools.js';
@@ -96,3 +96,5 @@ export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl,
 configureApiClient, } from '@ziggs-ai/api-client';
 export { SeenMessages } from './platform/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export { runAgents } from './launcher/runAgents.js';
+export { createHealthServer, inboxHealth } from './launcher/createHealthServer.js';

package/dist/launcher/createHealthServer.d.ts

@@ -0,0 +1,50 @@
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { Agent } from '../Agent.js';
+import type { ConnectionPool } from '../platform/ConnectionPool.js';
+/** What one agent reports about its own inbox reading. */
+export type AgentLiveness = ReturnType<Agent['inboxLiveness']>;
+/**
+ * The health verdict. A process is alive when its agents are still reading,
+ * so the answer is derived from the inbox loop rather than from the fact that
+ * this HTTP server replied — a wedged process replies happily while none of
+ * its agents read anything.
+ *
+ * The restart decision reads `lastAttemptAt`, not `lastPassAt`. When the
+ * backend is down every pass fails while the loops are perfectly healthy, and
+ * restarting the fleet would fix nothing and lose in-flight turns. Read
+ * staleness is still reported per agent, for the store and for monitoring.
+ */
+export declare function inboxHealth(rows: AgentLiveness[], now?: number, staleMs?: number): {
+    ok: boolean;
+    reason?: string;
+    staleMs: number;
+    watching: number;
+    oldestAttemptAgeMs: number | null;
+    oldestPassAgeMs: number | null;
+    agents: (AgentLiveness & {
+        passAgeMs: number | null;
+        attemptAgeMs: number | null;
+    })[];
+};
+export type HealthRequest = {
+    req: IncomingMessage;
+    res: ServerResponse;
+    pool?: ConnectionPool;
+};
+/**
+ * A route the embedding process adds. Return true once the response is sent.
+ * The health page itself only answers `/` and `/health`.
+ */
+export type HealthRequestHandler = (call: HealthRequest) => Promise<boolean>;
+export declare function createHealthServer({ port, label, pool, liveness, onRequest, }?: {
+    port?: number;
+    label?: string;
+    pool?: ConnectionPool;
+    /**
+     * Every agent this process is responsible for. Omit only when there is
+     * nothing to watch: without it `/health` can say no more than "this server
+     * replied", which is the answer this route exists to stop giving.
+     */
+    liveness?: () => AgentLiveness[];
+    onRequest?: HealthRequestHandler;
+}): Server;

package/dist/launcher/createHealthServer.js

@@ -0,0 +1,68 @@
+import { createServer } from 'node:http';
+import { runtimeLog } from '../shared/runtimeLog.js';
+/**
+ * How long an agent's inbox loop may go without turning before this process is
+ * called unhealthy. An idle loop completes a pass every `DEFAULT_WAIT_SECONDS`
+ * (110s), so this is three missed cycles plus slack: long enough that a slow
+ * server or a long turn never flaps, short enough that a wedged process is
+ * replaced within minutes.
+ */
+const STALE_MS = Number(process.env.FLEET_INBOX_STALE_MS) || 360_000;
+function age(now, at) {
+    return at === null ? null : now - at;
+}
+/**
+ * The health verdict. A process is alive when its agents are still reading,
+ * so the answer is derived from the inbox loop rather than from the fact that
+ * this HTTP server replied — a wedged process replies happily while none of
+ * its agents read anything.
+ *
+ * The restart decision reads `lastAttemptAt`, not `lastPassAt`. When the
+ * backend is down every pass fails while the loops are perfectly healthy, and
+ * restarting the fleet would fix nothing and lose in-flight turns. Read
+ * staleness is still reported per agent, for the store and for monitoring.
+ */
+export function inboxHealth(rows, now = Date.now(), staleMs = STALE_MS) {
+    const agents = rows.map((r) => ({
+        ...r,
+        passAgeMs: age(now, r.lastPassAt),
+        attemptAgeMs: age(now, r.lastAttemptAt),
+    }));
+    // Only agents that are supposed to be polling can be stale. A connected
+    // agent with the inbox loop off (lab and eval paths) has nothing to report,
+    // and an agent that was deliberately stopped is not this process failing.
+    const watched = agents.filter((r) => r.pollingInbox && r.connected);
+    const turning = watched.filter((r) => r.attemptAgeMs !== null && r.attemptAgeMs <= staleMs);
+    const ages = watched.map((r) => r.attemptAgeMs).filter((n) => n !== null);
+    const passAges = watched.map((r) => r.passAgeMs).filter((n) => n !== null);
+    const ok = watched.length === 0 || turning.length > 0;
+    return {
+        ok,
+        ...(ok ? {} : { reason: `no inbox pass attempted by any of ${watched.length} agent(s) within ${staleMs}ms` }),
+        staleMs,
+        watching: watched.length,
+        oldestAttemptAgeMs: ages.length ? Math.max(...ages) : null,
+        oldestPassAgeMs: passAges.length ? Math.max(...passAges) : null,
+        agents,
+    };
+}
+export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents', pool, liveness, onRequest, } = {}) {
+    const server = createServer(async (req, res) => {
+        if (await onRequest?.({ req, res, pool }))
+            return;
+        const url = req.url ?? '/';
+        if (url === '/health' || url === '/') {
+            const report = inboxHealth(liveness?.() ?? []);
+            if (!report.ok) {
+                runtimeLog.warn(label, `health: ${report.reason}`);
+            }
+            res.writeHead(report.ok ? 200 : 503, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(report));
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    server.listen(port, () => runtimeLog.info(label, `health server on port ${port}`));
+    return server;
+}

package/dist/launcher/runAgents.d.ts

@@ -0,0 +1,32 @@
+import { type Agent, type AgentOptions } from '../Agent.js';
+import { ConnectionPool } from '../platform/ConnectionPool.js';
+import { type HealthRequestHandler } from './createHealthServer.js';
+import type { Server } from 'node:http';
+/** Process concerns only. Every Agent owns its inbox and external polls. */
+export interface RunnerOptions {
+    operatorKey?: string;
+    label?: string;
+    port?: number | string;
+    healthServer?: boolean;
+    /** Disable when the embedding process owns its signal handlers. */
+    handleSignals?: boolean;
+    drainTimeoutMs?: number;
+    onShutdown?: () => Promise<void>;
+    agentMeta?: Record<string, unknown>[];
+    primary?: AgentOptions | ((pool: ConnectionPool) => AgentOptions);
+    /** A route this process adds. The health page itself only answers `/` and `/health`. */
+    onRequest?: HealthRequestHandler;
+}
+export interface SingleAgentRun {
+    agent: Agent;
+    healthServer?: Server;
+    shutdown(): Promise<void>;
+}
+export interface FleetRun {
+    pool: ConnectionPool;
+    primary: Agent | null;
+    healthServer?: Server;
+    shutdown(): Promise<void>;
+}
+export declare function runAgents(config: AgentOptions, options?: RunnerOptions): Promise<SingleAgentRun>;
+export declare function runAgents(configs: AgentOptions[], options?: RunnerOptions): Promise<FleetRun>;

package/dist/launcher/runAgents.js

@@ -0,0 +1,119 @@
+import { createAgent } from '../Agent.js';
+import { ConnectionPool } from '../platform/ConnectionPool.js';
+import { boundKeyFleetWarning } from '../shared/operatorKeyClaims.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { createHealthServer } from './createHealthServer.js';
+const DRAIN_TIMEOUT_MS = Number(process.env.FLEET_DRAIN_TIMEOUT_MS) || 90_000;
+function shutdownHandler(stop, server, options) {
+    let pending;
+    const shutdown = () => {
+        if (!pending) {
+            process.off('SIGTERM', signal);
+            process.off('SIGINT', signal);
+            pending = (async () => {
+                try {
+                    await stop();
+                    await options.onShutdown?.();
+                }
+                finally {
+                    if (server)
+                        await new Promise((resolve) => server.close(() => resolve()));
+                }
+            })();
+        }
+        return pending;
+    };
+    const signal = () => {
+        runtimeLog.info(options.label || 'runner', 'Shutting down');
+        void shutdown().then(() => process.exit(0), (err) => {
+            runtimeLog.error(options.label || 'runner', `Shutdown failed: ${err.message}`);
+            process.exit(1);
+        });
+    };
+    if (options.handleSignals !== false) {
+        process.on('SIGTERM', signal);
+        process.on('SIGINT', signal);
+    }
+    return shutdown;
+}
+async function healthServer(options, liveness, pool) {
+    if (options.healthServer === false)
+        return undefined;
+    const server = createHealthServer({
+        port: Number(options.port ?? process.env.PORT ?? 8080),
+        label: options.label || 'runner',
+        pool,
+        liveness,
+        onRequest: options.onRequest,
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.once('listening', () => { server.off('error', reject); resolve(); });
+    });
+    return server;
+}
+export async function runAgents(configOrConfigs, options = {}) {
+    const effectiveKey = options.operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+    const decorate = (config) => effectiveKey && !config.operatorKey ? { ...config, operatorKey: effectiveKey } : config;
+    const drainTimeout = options.drainTimeoutMs ?? DRAIN_TIMEOUT_MS;
+    if (!Array.isArray(configOrConfigs)) {
+        const agent = createAgent(decorate(configOrConfigs));
+        let server;
+        // One budget for stopping intake and finishing in-flight work: the inbox
+        // pass gets up to the whole of it to acknowledge, the queue what is left.
+        const stop = async () => {
+            const deadline = Date.now() + drainTimeout;
+            await agent.disconnect(drainTimeout);
+            await agent.drain(Math.max(0, deadline - Date.now()));
+        };
+        try {
+            await agent.connectAsync();
+            server = await healthServer(options, () => [agent.inboxLiveness()]);
+        }
+        catch (err) {
+            await stop();
+            throw err;
+        }
+        const shutdown = shutdownHandler(stop, server, options);
+        return { agent, healthServer: server, shutdown };
+    }
+    const pool = new ConnectionPool();
+    const configs = configOrConfigs.map(decorate);
+    pool.register(configs, options.agentMeta);
+    const primaryConfig = typeof options.primary === 'function' ? options.primary(pool) : options.primary;
+    let primary = null;
+    let server;
+    // Same single budget as the one-agent path, shared by the pool and the primary.
+    const stop = async () => {
+        const deadline = Date.now() + drainTimeout;
+        await Promise.all([primary?.disconnect(drainTimeout), pool.shutdown(drainTimeout)]);
+        await primary?.drain(Math.max(0, deadline - Date.now()));
+    };
+    try {
+        if (primaryConfig)
+            primary = createAgent(decorate(primaryConfig));
+        const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? primary?.options.operatorKey;
+        if (controlKey) {
+            const warning = boundKeyFleetWarning(controlKey, pool.size + (primary ? 1 : 0));
+            if (warning)
+                runtimeLog.warn(options.label || 'runner', warning);
+        }
+        await primary?.connectAsync();
+        await pool.connectAll();
+        const connected = pool.listActive().length;
+        if (configs.length > 0 && connected === 0) {
+            throw new Error(`0/${configs.length} agents started; process must restart`);
+        }
+        if (connected !== pool.size || pool.size !== configs.length) {
+            runtimeLog.warn(options.label || 'runner', `Only ${connected}/${configs.length} agents started — hosting the ones that came up`);
+        }
+        server = await healthServer(options, () => [...(primary ? [primary.inboxLiveness()] : []), ...pool.liveness()], pool);
+        runtimeLog.info(options.label || 'runner', `Ready — ${connected}/${pool.size} agents started`);
+    }
+    catch (err) {
+        await stop();
+        throw err;
+    }
+    const shutdown = shutdownHandler(stop, server, options);
+    return { pool, primary, healthServer: server, shutdown };
+}

package/dist/platform/ZiggsEffectHandler.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '@ziggs-ai/api-client';
 /**
  * Ziggs-flavored EffectHandler.
  *
@@ -36,7 +37,7 @@ export interface ZiggsEffectDeps {
     contextReadClient: ContextReadClient;
     taskService: TaskService;
     agreementService: AgreementService;
-    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string, conversationAgreementId?: string, underAgreementId?: string, taskId?: string) => Promise<unknown>;
+    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string, conversationAgreementId?: string, underAgreementId?: string, taskId?: string, sources?: WriteSource[]) => 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/platform/ZiggsEffectHandler.js

@@ -318,7 +318,7 @@ export function createZiggsEffectHandler(deps) {
                 });
             }
             case 'send-message': {
-                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId, effect.underAgreementId, effect.taskId);
+                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId, effect.underAgreementId, effect.taskId, effect.sources);
                 outbox.track(effect.sessionId, { text: effect.text, receiverId: effect.receiverId });
                 // Carry the send's own report back to whoever asked for the send. A
                 // sender that cannot see where its message went cannot tell a delivered

package/dist/platform/tasks/TaskService.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '@ziggs-ai/api-client';
 import { type Task, type TaskState } from '@ziggs-ai/api-client';
 import type { CountTasksFilters, CreateTaskData } from '@ziggs-ai/api-client';
 export declare class TaskService {
@@ -9,7 +10,7 @@ export declare class TaskService {
     getActiveTasksForChat(chatId: string): Promise<Task[]>;
     getSubtasks(parentTaskId: string): Promise<Task[]>;
     spawnUnderAgreement(agreementId: string, taskData: Omit<CreateTaskData, 'agreementId'>): Promise<Task>;
-    updateState(taskId: string, state: TaskState, result?: unknown, idempotencyKey?: string): Promise<{
+    updateState(taskId: string, state: TaskState, result?: unknown, idempotencyKey?: string, sources?: WriteSource[]): Promise<{
         ok: true;
         taskId: string;
         state: string;
@@ -46,7 +47,7 @@ export declare class TaskService {
     updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown, waitingOn?: {
         kind: 'user' | 'agent';
         id: string;
-    } | null): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
+    } | null, sources?: WriteSource[]): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
     cancel(taskId: string): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
     report(taskId: string, message?: string): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
     setSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;

package/dist/platform/tasks/TaskService.js

@@ -60,11 +60,12 @@ export class TaskService {
             throw error;
         }
     }
-    async updateState(taskId, state, result, idempotencyKey) {
+    async updateState(taskId, state, result, idempotencyKey, sources) {
         try {
             const data = {
                 ...(result !== undefined ? { result: safeJsonStringify(result) } : {}),
                 ...(idempotencyKey ? { idempotencyKey } : {}),
+                ...(sources ? { sources } : {}),
             };
             const updated = await updateTaskState(taskId, state, data, this.creds);
             runtimeLog.info('TaskService', `Task state: ${taskId} → ${state}`);
@@ -97,9 +98,9 @@ export class TaskService {
             throw error;
         }
     }
-    async updatePlanStep(taskId, stepId, status, result, waitingOn) {
+    async updatePlanStep(taskId, stepId, status, result, waitingOn, sources) {
         try {
-            const updated = await updateTaskPlanStep(taskId, stepId, status, result, this.creds, waitingOn);
+            const updated = await updateTaskPlanStep(taskId, stepId, status, result, this.creds, waitingOn, sources);
             runtimeLog.info('TaskService', `Task plan step: ${taskId}/${stepId} → ${status}`);
             return updated;
         }

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

@@ -21,7 +21,7 @@ export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discover
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
 export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+export { CONTEXT_TOOLS, contextReadTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
 export { TASK_TOOLS, listTasksTool, cancelTaskTool } from './tier2/taskTools.js';
 export { PLAN_TOOLS, taskReplacePlanTool } from './tier2/planTools.js';

package/dist/platform/tools/index.js

@@ -23,7 +23,7 @@ export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discover
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
 export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+export { CONTEXT_TOOLS, contextReadTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 // 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';

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

@@ -45,6 +45,12 @@ function normalizePlanInPlace(payload) {
         ? 'before_execution'
         : 'with_proposal';
 }
+/** The `sources` a protocol call carried, when it carried a list. */
+function sourcesOf(payload) {
+    return Array.isArray(payload.sources)
+        ? { sources: payload.sources }
+        : {};
+}
 export async function dispatchProtocolOp(services, payload, chatId, _agents = [], actingAgentId = null, writeKeys = null, 
 /** #8 — prefer the cached session snapshot over a fresh HTTP read. */
 cachedAgreements) {
@@ -93,6 +99,7 @@ cachedAgreements) {
                 lifecycle: payload.lifecycle,
                 maxExecutions: payload.maxExecutions,
                 description: payload.description,
+                ...sourcesOf(payload),
             });
         case 'agreement-check-proposal':
             if (!payload.agreementId)
@@ -182,6 +189,7 @@ cachedAgreements) {
                 ...(payload.checkBack && typeof payload.checkBack === 'object'
                     ? { checkBack: payload.checkBack }
                     : {}),
+                ...sourcesOf(payload),
                 // Wake-derived idempotency key (delivery law): a crash-replay re-issuing
                 // this spawn resolves to the already-created task server-side instead of
                 // creating a duplicate. Keyed on what is actually written (the resolved
@@ -204,7 +212,7 @@ cachedAgreements) {
             const state = normalizeState(terminalRaw);
             // Wake-derived idempotency key: a crash-replay re-issuing this transition
             // no-ops server-side instead of erroring on the already-terminal task.
-            return taskService.updateState(payload.taskId, state, payload.result, writeKeys?.taskStateKey(payload.taskId, state));
+            return taskService.updateState(payload.taskId, state, payload.result, writeKeys?.taskStateKey(payload.taskId, state), sourcesOf(payload).sources);
         }
         case 'task-update-plan-step': {
             if (!payload.taskId)
@@ -225,7 +233,7 @@ cachedAgreements) {
             // a stepId that isn't in the plan — the backend 400s on both. That must never
             // hard-fail the tool → fail the task → wake-loop. Make it best-effort.
             try {
-                return await taskService.updatePlanStep(payload.taskId, payload.stepId, payload.status, payload.result, waitingOn);
+                return await taskService.updatePlanStep(payload.taskId, payload.stepId, payload.status, payload.result, waitingOn, sourcesOf(payload).sources);
             }
             catch {
                 return { ok: false, skipped: 'plan-step-not-updatable', stepId: payload.stepId };
@@ -286,6 +294,7 @@ async function proposeAgreement(services, payload, chatId, writeKeys = null) {
         billing,
         ...(payload.conversationAllowance !== undefined ? { conversationAllowance: payload.conversationAllowance } : {}),
         agreementDescription: payload.agreementDescription,
+        ...sourcesOf(payload),
         parentAgreementId: payload.parentAgreementId,
         engagementKind,
         idempotencyKey,

package/dist/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, agreementClaimCapability, agreementSubcontractCapability, } from '@ziggs-ai/api-client';
+import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, agreementClaimCapability, agreementSubcontractCapability, SOURCES_PARAM, } 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'];
@@ -60,21 +60,22 @@ function handlerFor(toolName) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. 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', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, 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) and no providerId posts a REQUEST any agent may claim. A person or the deploy publishes a standing listing; this agent does not. 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 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', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, 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', sources: SOURCES_PARAM }, 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) and no providerId posts a REQUEST any agent may claim. A person or the deploy publishes a standing listing; this agent does not. 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', agreementSubcontractCapability.params, handlerFor('agreement_subcontract'), { description: agreementSubcontractCapability.descriptions.sdk, 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', 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.
-    state: { type: 'string', required: true, enum: ['completed', 'failed', 'cancelled'] },
+    state: { type: 'string', required: true, enum: ['completed', 'failed'] },
     // Same object contract as MCP ({ summary, status, links, … }).
     result: {
         type: 'object',
         description: 'Outcome payload (summary, status, links, …). This is what the next agent reads when it picks the work up from its own inbox.',
     },
-}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Set the result here as an object ({ summary, status, links }): a task the parties opted into is closed by this call, whatever else you also sent them. Pass state (not status). This closes the task and not the engagement: a standing hire stays active for the next task, ending one is agreement_fulfill. The reply reports what actually happened — what was stored, who the completion was queued for (queued, not read), what per-task metering did — so report those and no more; a completed task is not by itself a paid one.' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, 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.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
+    sources: SOURCES_PARAM,
+}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state, completed or failed, and record the result. To cancel a task use task_cancel. Set the result here as an object ({ summary, status, links }): a task the parties opted into is closed by this call, whatever else you also sent them. Pass state (not status). This closes the task and not the engagement: a standing hire stays active for the next task, ending one is agreement_fulfill. The reply reports what actually happened — what was stored, who the completion was queued for (queued, not read), what per-task metering did — so report those and no more; a completed task is not by itself a paid one.' });
+export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, 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.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, description: 'string', sources: SOURCES_PARAM }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
 export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_get'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
 export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked and it cannot be reopened. Linked chats remain independent rooms governed by their own grants. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
@@ -92,6 +93,7 @@ export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', {
         description: 'Step progress. Required with stepId.',
     },
     result: 'string',
+    sources: SOURCES_PARAM,
     // Both fields are required, but the required list cannot be declared here:
     // defineTool reads a sibling `required` as the flag that makes waitingOn
     // itself mandatory. The backend enforces the pair; the description says so.
@@ -108,7 +110,7 @@ export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', {
         description: "Who this task now waits on, because you just asked them: { kind: 'user' | 'agent', id } — both fields required. Send it when you ask — with the step you are ticking, or on its own when the ask is all that happened. Your person then sees the task as waiting on them rather than as running, which is the difference between a job that looks stalled and one that is waiting for an answer. It clears itself: any later progress that does not restate it, and any terminal state, drops it.",
     },
 }, handlerFor('task_update_plan_step'), { description: "Update the status of a single step within a task's plan, and say who you are waiting on when you have just asked somebody. A task with no plan can still carry the waiting-on on its own." });
-export const taskCreateTool = defineTool('task_create', { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'Prior-step output artifact handles, for structured input links.' }, plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean', dueAt: dueAtParam, checkBack: checkBackParam }, handlerFor('task_create'), { description: 'Create a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open. For work that means chasing an answer out of somebody, set dueAt and checkBack so the holder knows when to stop and how often it may remind.' });
+export const taskCreateTool = defineTool('task_create', { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'Prior-step output artifact handles, for structured input links.' }, plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean', dueAt: dueAtParam, checkBack: checkBackParam, sources: SOURCES_PARAM }, handlerFor('task_create'), { description: 'Create a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open. For work that means chasing an answer out of somebody, set dueAt and checkBack so the holder knows when to stop and how often it may remind.' });
 export const PROTOCOL_TOOLS = [
     agreementProposeTool, agreementSubcontractTool,
     agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool,

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

@@ -3,7 +3,6 @@ export declare const contextReadTool: ToolDefinition;
 export declare const openTool: ToolDefinition;
 export declare const accessExplainTool: ToolDefinition;
 export declare const accessRequestTool: ToolDefinition;
-export declare const contextRequestTool: ToolDefinition;
 export declare const contextDelegateTool: ToolDefinition;
 export declare const contextExpandReachTool: ToolDefinition;
 export declare const contextDiscoverGrantableTool: ToolDefinition;

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

@@ -1,4 +1,4 @@
-import { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextRequestCapability, accessRequestCapability, } from '@ziggs-ai/api-client';
+import { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, accessRequestCapability, } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
 // context grant tools ride the same api-client
 // clients as ziggs-mcp; the whole definition (schema + handler) is now shared
@@ -7,7 +7,6 @@ export const contextReadTool = toolFromCapability(contextReadCapability);
 export const openTool = toolFromCapability(openCapability);
 export const accessExplainTool = toolFromCapability(accessExplainCapability);
 export const accessRequestTool = toolFromCapability(accessRequestCapability);
-export const contextRequestTool = toolFromCapability(contextRequestCapability);
 export const contextDelegateTool = toolFromCapability(contextDelegateCapability);
 export const contextExpandReachTool = toolFromCapability(contextExpandReachCapability);
 export const contextDiscoverGrantableTool = toolFromCapability(contextDiscoverGrantableCapability);

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

@@ -1,4 +1,4 @@
-import { replaceTaskPlan } from '@ziggs-ai/api-client';
+import { replaceTaskPlan, SOURCES_PARAM, } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
 import { credsFromToolContext } from '../../../tools/toolCreds.js';
 /**
@@ -44,6 +44,7 @@ export const taskReplacePlanTool = defineTool('task_replace_plan', {
                     type: 'object',
                     description: 'What this step produced, as an object — e.g. { "agreementId": "agr_…" } for an approval you requested, or { "artifactId": "art_…" } for a pack you recorded. Stored with the step and read back by task_list.',
                 },
+                sources: SOURCES_PARAM,
             },
             required: ['description'],
         },

package/dist/probeChat.d.ts

@@ -1,12 +1,10 @@
 /**
  * One classifier for store-publish probe rooms.
  *
- * The runner mints `probe_<agentId>_<ts>`. An id prefix must not buy
- * capability evidence or a canned brain reply; it only names the room so
- * inbox pin and wake order can find it. Capability vs liveness is decided
- * by the store sync, not by this prefix.
+ * The runner mints `probe_<agentId>_<ts>`. That prefix skips the wake gate
+ * and the wake-rate breaker, so a store publish still hears a model reply.
+ * It does not write a canned answer, and it is not capability evidence.
+ * Capability versus liveness is decided by the store sync.
  */
 export declare const PROBE_CHAT_ID_PREFIX = "probe_";
 export declare function isPublishProbeChat(chatId: string | undefined | null): boolean;
-/** @deprecated use {@link isPublishProbeChat} — same classifier, old name. */
-export declare const isCapabilityProbeSession: typeof isPublishProbeChat;

package/dist/probeChat.js

@@ -1,14 +1,12 @@
 /**
  * One classifier for store-publish probe rooms.
  *
- * The runner mints `probe_<agentId>_<ts>`. An id prefix must not buy
- * capability evidence or a canned brain reply; it only names the room so
- * inbox pin and wake order can find it. Capability vs liveness is decided
- * by the store sync, not by this prefix.
+ * The runner mints `probe_<agentId>_<ts>`. That prefix skips the wake gate
+ * and the wake-rate breaker, so a store publish still hears a model reply.
+ * It does not write a canned answer, and it is not capability evidence.
+ * Capability versus liveness is decided by the store sync.
  */
 export const PROBE_CHAT_ID_PREFIX = 'probe_';
 export function isPublishProbeChat(chatId) {
     return typeof chatId === 'string' && chatId.startsWith(PROBE_CHAT_ID_PREFIX);
 }
-/** @deprecated use {@link isPublishProbeChat} — same classifier, old name. */
-export const isCapabilityProbeSession = isPublishProbeChat;

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '@ziggs-ai/api-client';
 /**
  * Foundation types for the agent SDK workflow runtime.
  *
@@ -519,6 +520,7 @@ export type Effect = {
     conversationAgreementId?: string;
     underAgreementId?: string;
     taskId?: string;
+    sources?: WriteSource[];
 } | {
     kind: 'record-event';
     sessionId: string;

package/dist/types.js

@@ -1,7 +1 @@
-/**
- * Foundation types for the agent SDK workflow runtime.
- *
- * One outcome vocabulary, one ctx shape, one transition signature.
- * Every state — parked or thinking — re-enters with exactly one Outcome.
- */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.38.2",
+  "version": "0.38.4",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.4",
+    "@ziggs-ai/api-client": "0.37.6",
     "@ziggs-ai/contracts": "^0.23.3",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",