@ziggs-ai/agent-sdk 0.38.1 → 0.38.3

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

@@ -1,3 +1,4 @@
+import { SERVER_EVENTS } from '@ziggs-ai/contracts';
 import { withAgreementContext } from './runtime/agreementContext.js';
 import { agreementLaneId, agreementIdFromLane, isContextAccessRequest } from '@ziggs-ai/api-client';
 import { createDeclaredPollRunner } from './platform/polls/declaredPollRunner.js';
@@ -556,7 +557,7 @@ export class Agent {
                 : undefined);
         const actorId = typeof event.actorId === 'string' && event.actorId ? event.actorId : undefined;
         return this.eventQueue.enqueue({
-            type: 'resource_changed',
+            type: SERVER_EVENTS.resourceChanged,
             resource: event,
             chatId: event.chatId,
             taskId: event.taskId,

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/claudeCognition.d.ts

@@ -1,16 +1,3 @@
-/**
- * Shared Claude-Agent-SDK cognition pieces.
- *
- * Everything a Claude-brain agent needs to turn a Ziggs wake into a `query()`
- * call, EXCEPT the loop itself. `ClaudeBrain` owns the loop (drive `query()`,
- * collect metrics); this module owns the periphery so it lives in one place and
- * is unit-testable without spinning up the SDK.
- *
- * The lockdown option set (`tools: []`, `strictMcpConfig`, `settingSources: []`,
- * bypass permissions, no local settings) is a security boundary, not a default —
- * it MUST be applied on every Claude-brain wake. Centralizing it here means a
- * caller cannot silently drift from it.
- */
 import { type Options, type SDKAssistantMessage } from '@anthropic-ai/claude-agent-sdk';
 import type { RawEvent } from '../runtime/buildOutcome.js';
 export interface ClaudeQueryOptionsParams {

package/dist/brain/claudeCognition.js

@@ -11,6 +11,7 @@
  * it MUST be applied on every Claude-brain wake. Centralizing it here means a
  * caller cannot silently drift from it.
  */
+import { SERVER_EVENTS } from '@ziggs-ai/contracts';
 import { SYSTEM_PROMPT_DYNAMIC_BOUNDARY, } from '@anthropic-ai/claude-agent-sdk';
 import { decisionWords } from '@ziggs-ai/api-client';
 import { getBatchEvents } from '../context/batch.js';
@@ -215,7 +216,7 @@ function renderEventLines(event, lines, now) {
     // 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') {
+    if (event?.type === SERVER_EVENTS.resourceChanged) {
         const resource = (event.resource ?? event);
         const reason = (typeof resource.reason === 'string' && resource.reason) ||
             (typeof event.reason === 'string' && event.reason) ||

package/dist/brain/hireActivationNotice.js

@@ -7,6 +7,7 @@
  * manifest opts in. A hire a person formed (store claim) still wakes
  * so the provider can open the room and greet.
  */
+import { SERVER_EVENTS } from '@ziggs-ai/contracts';
 const ACTIVATION_LIFECYCLE_OPS = new Set([
     'proposal_approved',
     'proposal_approved_execute',
@@ -62,7 +63,7 @@ export function isHireActivationNotice(event) {
     if (type === 'agreement_lifecycle' && operation && ACTIVATION_LIFECYCLE_OPS.has(operation)) {
         return true;
     }
-    if (type !== 'resource_changed')
+    if (type !== SERVER_EVENTS.resourceChanged)
         return false;
     const resource = asRecord(ev.resource) ?? ev;
     const reason = typeof resource.reason === 'string' ? resource.reason : undefined;

package/dist/brain/standingOfferNotice.js

@@ -1,3 +1,4 @@
+import { SERVER_EVENTS } from '@ziggs-ai/contracts';
 import { isAgreementId, isBroadcastTarget } from '@ziggs-ai/api-client';
 import { getBatchEvents } from '../context/batch.js';
 function record(value) {
@@ -46,7 +47,7 @@ export async function filterStandingOfferNotices(event, agentId, readAgreement)
         const resource = record(item?.resource);
         const reason = resource?.reason ?? item?.reason;
         const id = agreementEventId(item);
-        if (item?.type === 'resource_changed' && resource?.kind === 'agreement' &&
+        if (item?.type === SERVER_EVENTS.resourceChanged && resource?.kind === 'agreement' &&
             (reason === 'approval:approved' || reason === 'proposal_approved') && id) {
             // Inconclusive reads preserve the wake. An unavailable read must not eat
             // a legitimate customer hire or the answer to an agent's own request.

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/inboxLoop.js

@@ -314,9 +314,6 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
             handledSoFar.add(request.agreementId);
         }
     }
-    if (envelope.truncatedRequests) {
-        warn(label, `inbox truncatedRequests=${envelope.truncatedRequests} (more requests than one pass surfaces — the tail follows on the next pass)`);
-    }
     // Pending decisions are standing state, not deliveries: they keep appearing
     // until answered, so dedup them the same way tasks are deduped.
     for (const proposal of envelope.proposalsAwaitingMe) {

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

@@ -1,3 +1,4 @@
+import { AGREEMENT_TERMINAL_STATES } from '@ziggs-ai/contracts';
 import { isBroadcastTarget, partyActorIds, presentClaimResult, } from '@ziggs-ai/api-client';
 // the link-summary rule lives in AgreementClient, at the point the
 // document is parsed. Every verb here inherits it through the client instead of
@@ -300,7 +301,7 @@ async function proposeAgreement(services, payload, chatId, writeKeys = null) {
 // party — instead of under that worker's sub-agreement, which the backend
 // rejects with 400 "assignee is not a party". Both are made deterministic here
 // using the chat's existing agreements.
-const TERMINAL_STATUS = new Set(['fulfilled', 'cancelled', 'refunded', 'rejected']);
+const TERMINAL_STATUS = new Set(AGREEMENT_TERMINAL_STATES);
 async function agreementsInChat(services, chatId, cachedAgreements) {
     if (!chatId)
         return [];

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

@@ -67,13 +67,13 @@ export const agreementClaimTool = defineTool('agreement_claim', agreementClaimCa
 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.' });
+}, 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' }, 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.' });

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/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/runtime/buildOutcome.js

@@ -1,3 +1,4 @@
+import { SERVER_EVENTS } from '@ziggs-ai/contracts';
 import { isProtocolToolName, mapProtocolToolToOperation } from '../tasks/protocolRegistry.js';
 import { getBatchEvents, isTaskResultRelevantToAgent } from '../context/batch.js';
 import { bookForDelegation, ensureTaskBook, findBookHoldingPending, removeTaskBook, } from './taskBookkeeping.js';
@@ -108,7 +109,7 @@ function singleEventToOutcome(ev, ownAgentId) {
         }
         return { kind: 'subtask-finished', status: 'completed', task, result };
     }
-    if (ev.type === 'resource_changed') {
+    if (ev.type === SERVER_EVENTS.resourceChanged) {
         const resource = (ev.resource ?? ev);
         const reason = resource.reason;
         if (resource.kind === 'agreement' &&

package/dist/shared/types.d.ts

@@ -1,3 +1,6 @@
+import { ContentTypes, type ContentType } from '@ziggs-ai/api-client';
+export { ContentTypes, type ContentType };
+/** Entry kinds. `task_history` is a legacy alias the wire still accepts. */
 export declare const EntryTypes: {
     readonly MESSAGE: "message";
     readonly NOTIFICATION: "notification";
@@ -5,15 +8,6 @@ export declare const EntryTypes: {
     readonly TASK_HISTORY: "task_history";
 };
 export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
-export declare const ContentTypes: {
-    readonly TEXT: "text";
-    readonly OPERATION: "operation";
-    readonly CONTEXT: "context";
-    readonly RESULT: "result";
-    readonly TASK_UPDATE: "task_update";
-    readonly THOUGHT: "thought";
-};
-export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
 export declare const ContextProperties: {
     readonly HISTORY: "history";
     readonly AGREEMENTS: "agreements";

package/dist/shared/types.js

@@ -1,20 +1,12 @@
-// Inlined from `@ziggs-ai/api-client` so the pure SDK doesn't depend on the
-// Ziggs HTTP client. Both client and server agree on these string constants
-// because the protocol is the same — they're just two views of one schema.
+import { ContentTypes } from '@ziggs-ai/api-client';
+export { ContentTypes };
+/** Entry kinds. `task_history` is a legacy alias the wire still accepts. */
 export const EntryTypes = {
     MESSAGE: 'message',
     NOTIFICATION: 'notification',
     ARTIFACT: 'artifact',
     TASK_HISTORY: 'task_history',
 };
-export const ContentTypes = {
-    TEXT: 'text',
-    OPERATION: 'operation',
-    CONTEXT: 'context',
-    RESULT: 'result',
-    TASK_UPDATE: 'task_update',
-    THOUGHT: 'thought',
-};
 export const ContextProperties = {
     HISTORY: 'history',
     AGREEMENTS: 'agreements',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.38.1",
+  "version": "0.38.3",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,8 @@
     "@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.1",
+    "@ziggs-ai/api-client": "0.37.5",
+    "@ziggs-ai/contracts": "^0.23.3",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",