@ziggs-ai/agent-sdk 0.10.1 → 0.10.2

package/README.md

@@ -93,6 +93,14 @@ The public **`Brain`** interface is `tick(TickInput): Promise<TickOutput>`. Buil
 
 Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
 
+Point the shared HTTP client at a non-default backend (self-hosted / local) before constructing hosts — no direct `@ziggs-ai/api-client` dependency needed:
+
+```ts
+import { configureApiClient, createAgent } from '@ziggs-ai/agent-sdk';
+
+configureApiClient({ httpUrl: 'https://api.example.com' });
+```
+
 ---
 
 ## Main exports (entry: `src/index.js`)
@@ -105,7 +113,7 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
   - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *not* passed in the user `tools:` array. Publishing open work is part of this grammar: `agreement_propose({ proposedTo: "everyone" })` (there is no separate publish tool).
   - **Tier 2 — capability bundles (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
-- **Re-exported** from `@ziggs-ai/api-client`: `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly. The WebSocket client was removed — delivery is HTTP inbox long-poll; read/ack via `InboxClient` from `@ziggs-ai/api-client`.)
+- **Re-exported** from `@ziggs-ai/api-client`: `configureApiClient`, type `ApiClientConfig`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly. The WebSocket client was removed — delivery is HTTP inbox long-poll; read/ack via `InboxClient` from `@ziggs-ai/api-client`.)
 
 Package export: `"."` → `dist/index.js` (see `package.json`; `npm run build` before publish or monorepo tests).
 

package/dist/agent/Agent.js

@@ -1,5 +1,5 @@
 import { AgentMachine } from '../runtime/AgentMachine.js';
-import { createWakeWriteKeys } from '../runtime/wakeWriteKeys.js';
+import { createDeliveryWriteKeys } from '../runtime/deliveryWriteKeys.js';
 import { runTurn } from '../runtime/runTurn.js';
 import { PromptBuilder } from '../runtime/PromptBuilder.js';
 /**
@@ -46,7 +46,7 @@ export class Agent {
             transitionTap,
             // One key stream per wake, shared by every state this tick runs through —
             // per-state streams would restart the ordinal and collide across states.
-            wakeKeys: createWakeWriteKeys(identity.laneKey, event),
+            writeKeys: createDeliveryWriteKeys(identity.laneKey, event),
         });
         // `send` awaits the recursive _step until the machine settles at a
         // parked state (or stops). When it returns, we have the final state.

package/dist/agent/ClaudeSdkAgent.js

@@ -2,7 +2,7 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 import { isMessageAddressedElsewhere, outcomeFromEvent } from '../runtime/buildOutcome.js';
 import { getBatchEvents } from '../context/batch.js';
 import { bootstrapCtx } from '../runtime/bootstrapCtx.js';
-import { createWakeWriteKeys } from '../runtime/wakeWriteKeys.js';
+import { createDeliveryWriteKeys } from '../runtime/deliveryWriteKeys.js';
 import { CLAUDE_SDK_PROTOCOL } from './claudeSdkProtocol.js';
 import { buildZiggsSdkMcpServer } from './toolManagerToSdkMcp.js';
 import { claudeQueryOptions, buildClaudeEventPrompt, summarizeContext, extractAssistantText, } from './claudeCognition.js';
@@ -222,11 +222,11 @@ export class ClaudeSdkAgent {
         const nextCtx = bootstrapCtx(identity, ctx);
         nextCtx.lastOutcome = outcomeFromEvent(rawEvent ?? null, identity.agentId);
         const now = Date.now();
-        const recentWakes = (nextCtx.recentWakes ?? []).filter((t) => now - t < WAKE_WINDOW_MS);
-        if (recentWakes.length >= MAX_WAKES_PER_WINDOW) {
-            runtimeLog.warn('ClaudeSdkAgent', `wake-rate breaker tripped: ${recentWakes.length} wakes in ${WAKE_WINDOW_MS / 60_000}min ` +
+        const recentDeliveries = (nextCtx.recentDeliveries ?? []).filter((t) => now - t < WAKE_WINDOW_MS);
+        if (recentDeliveries.length >= MAX_WAKES_PER_WINDOW) {
+            runtimeLog.warn('ClaudeSdkAgent', `wake-rate breaker tripped: ${recentDeliveries.length} wakes in ${WAKE_WINDOW_MS / 60_000}min ` +
                 `session=${identity.sessionId} agent=${this.agentId} — skipping LLM for this wake`);
-            nextCtx.recentWakes = recentWakes;
+            nextCtx.recentDeliveries = recentDeliveries;
             return {
                 ctx: nextCtx,
                 state: state ?? DEFAULT_STATE,
@@ -235,7 +235,7 @@ export class ClaudeSdkAgent {
                 metrics: { llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } },
             };
         }
-        nextCtx.recentWakes = [...recentWakes, now];
+        nextCtx.recentDeliveries = [...recentDeliveries, now];
         if (isNoticeOnlyWake(rawEvent, identity.agentId)) {
             runtimeLog.info('ClaudeSdkAgent', `notice-only wake — skipping LLM session=${identity.sessionId} agent=${this.agentId} ` +
                 `type=${rawEvent?.type ?? 'unknown'}`);
@@ -296,12 +296,14 @@ export class ClaudeSdkAgent {
             this.rolePrompt,
             this.specialization ? `Specialization: ${this.specialization}` : '',
         ].filter(Boolean).join('\n');
-        const systemPrompt = `${CLAUDE_SDK_PROTOCOL}\n\n${roleBlock}`;
+        // Two blocks, not one string: the shared protocol first so its cache prefix
+        // is reachable by every hosted agent, this agent's role second (ZIG-788).
+        const systemPrompt = [CLAUDE_SDK_PROTOCOL, roleBlock];
         const runId = crypto.randomUUID();
         // Replay-stable write keys for this wake (runId is random and can't serve):
         // a crash-replay of the same event derives the same keys, so the backend
         // drops the duplicate artifacts / no-ops the repeated task transitions.
-        const wakeKeys = createWakeWriteKeys(identity.laneKey, rawEvent);
+        const writeKeys = createDeliveryWriteKeys(identity.laneKey, rawEvent);
         const toolContext = {
             operatorKey: this.operatorKey,
             agentId: this.agentId,
@@ -316,7 +318,7 @@ export class ClaudeSdkAgent {
             // not just task_result events — see resolveOnBehalfAgreementId.
             onBehalfOfAgreementId: resolveOnBehalfAgreementId(rawEvent, contextSnap, this.agentId, identity.sessionId),
             runId,
-            wakeKeys,
+            writeKeys,
         };
         this.toolContextHolder.current = toolContext;
         if (!this.sdkMcpServer) {
@@ -394,7 +396,7 @@ export class ClaudeSdkAgent {
                         if (text) {
                             // Ordinal drawn synchronously so the fire-and-forget below can't
                             // reorder key assignment against other writes of this wake.
-                            const idempotencyKey = wakeKeys.artifactKey({ kind: 'thought', text });
+                            const idempotencyKey = writeKeys.artifactKey({ kind: 'thought', text });
                             void eff({ kind: 'record-event', sessionId: identity.sessionId, entry: { kind: 'thought', text }, idempotencyKey })
                                 .catch((err) => runtimeLog.warn('ClaudeSdkAgent', `record thought failed session=${identity.sessionId}: ${err.message}`));
                         }

package/dist/agent/claudeCognition.d.ts

@@ -11,11 +11,15 @@
  * it MUST be applied on every Claude-brain wake. Centralizing it here means a
  * caller cannot silently drift from it.
  */
-import type { Options, SDKAssistantMessage } from '@anthropic-ai/claude-agent-sdk';
+import { type Options, type SDKAssistantMessage } from '@anthropic-ai/claude-agent-sdk';
 import type { RawEvent } from '../runtime/buildOutcome.js';
 export interface ClaudeQueryOptionsParams {
-    /** Protocol + role system prompt. */
-    systemPrompt: string;
+    /**
+     * The system prompt in cache-ordered blocks: the shared protocol first, then
+     * this agent's role. Both are stable across wakes — see
+     * {@link claudeQueryOptions} for why that matters.
+     */
+    systemPrompt: string[];
     /** Claude model id for the brain. */
     model: string;
     /** In-process MCP servers exposing the agent's tools (e.g. `{ ziggs }`). */
@@ -47,6 +51,24 @@ export declare function resolveClaudeModel(preferred?: string, servicesModel?: s
  * Build the `query()` options for a Claude-brain wake. The lockdown fields are
  * fixed here; callers only supply the per-wake variables (prompt, model, tools,
  * turn budget, resume). Returns `Options` so it drops straight into `query()`.
+ *
+ * ZIG-788 — prompt caching. The system prompt is handed over as blocks with a
+ * trailing `SYSTEM_PROMPT_DYNAMIC_BOUNDARY`: everything before the marker is
+ * eligible for cross-session caching, and there is nothing after it because
+ * nothing in this prompt varies per wake. Every per-wake input — the event, the
+ * context digest — is in the user prompt (`buildClaudeEventPrompt`), which sits
+ * after the cached prefix and cannot invalidate it.
+ *
+ * Cross-SESSION is the point, not cross-turn: `statelessPerWake` starts a fresh
+ * transcript on every wake, so without this the identical prefix was re-read at
+ * full price on each one.
+ *
+ * Caching is a prefix match, so block ORDER decides how far the hit reaches:
+ * the protocol block is byte-identical for every hosted agent and goes first,
+ * the role block is per-agent and goes second. An agent whose combined prompt
+ * lands under the model's minimum cacheable prefix (~1k tokens on Sonnet, more
+ * on Haiku) simply writes no entry — that is a silent no-op, not an error, so
+ * read `cacheRead`/`cacheCreation` in the wake metrics rather than assuming.
  */
 export declare function claudeQueryOptions(params: ClaudeQueryOptionsParams): Options;
 /**

package/dist/agent/claudeCognition.js

@@ -1,3 +1,17 @@
+/**
+ * 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. `ClaudeSdkAgent` 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 { SYSTEM_PROMPT_DYNAMIC_BOUNDARY, } from '@anthropic-ai/claude-agent-sdk';
 import { getBatchEvents } from '../context/batch.js';
 const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6';
 /**
@@ -17,10 +31,28 @@ export function resolveClaudeModel(preferred, servicesModel) {
  * Build the `query()` options for a Claude-brain wake. The lockdown fields are
  * fixed here; callers only supply the per-wake variables (prompt, model, tools,
  * turn budget, resume). Returns `Options` so it drops straight into `query()`.
+ *
+ * ZIG-788 — prompt caching. The system prompt is handed over as blocks with a
+ * trailing `SYSTEM_PROMPT_DYNAMIC_BOUNDARY`: everything before the marker is
+ * eligible for cross-session caching, and there is nothing after it because
+ * nothing in this prompt varies per wake. Every per-wake input — the event, the
+ * context digest — is in the user prompt (`buildClaudeEventPrompt`), which sits
+ * after the cached prefix and cannot invalidate it.
+ *
+ * Cross-SESSION is the point, not cross-turn: `statelessPerWake` starts a fresh
+ * transcript on every wake, so without this the identical prefix was re-read at
+ * full price on each one.
+ *
+ * Caching is a prefix match, so block ORDER decides how far the hit reaches:
+ * the protocol block is byte-identical for every hosted agent and goes first,
+ * the role block is per-agent and goes second. An agent whose combined prompt
+ * lands under the model's minimum cacheable prefix (~1k tokens on Sonnet, more
+ * on Haiku) simply writes no entry — that is a silent no-op, not an error, so
+ * read `cacheRead`/`cacheCreation` in the wake metrics rather than assuming.
  */
 export function claudeQueryOptions(params) {
     return {
-        systemPrompt: params.systemPrompt,
+        systemPrompt: [...params.systemPrompt, SYSTEM_PROMPT_DYNAMIC_BOUNDARY],
         model: params.model,
         mcpServers: params.mcpServers,
         // The agent's ONLY capabilities are its MCP tools — no built-in file/bash/web

package/dist/agent/claudeSdkTools.d.ts

@@ -1,5 +1,5 @@
 import { type ToolDefinition } from '../tools/defineTool.js';
-import type { EffectHandler, WakeWriteKeys } from '../types.js';
+import type { EffectHandler, DeliveryWriteKeys } from '../types.js';
 export interface ClaudeSdkToolContext extends Record<string, unknown> {
     operatorKey: string;
     agentId: string;
@@ -14,7 +14,7 @@ export interface ClaudeSdkToolContext extends Record<string, unknown> {
     /** Per-wake id grouping this tick's tool calls in telemetry (ZIG-775). Random — never use for idempotency. */
     runId?: string;
     /** Replay-stable write keys for this wake — write tools derive idempotency keys from here, never from the LLM. */
-    wakeKeys?: WakeWriteKeys;
+    writeKeys?: DeliveryWriteKeys;
 }
 export declare const contextSnapshotTool: ToolDefinition;
 export declare const chatSendTool: ToolDefinition;

package/dist/agent/claudeSdkTools.js

@@ -77,7 +77,7 @@ export const chatSendTool = defineTool('chat_send', {
     const text = String(args.text);
     const messageId = args.idempotencyKey
         ? `sdk_idem_${String(args.idempotencyKey)}`
-        : c.wakeKeys?.messageKey({ text, sessionId, receiverId }) ?? `sdk_${randomUUID()}`;
+        : c.writeKeys?.messageKey({ text, sessionId, receiverId }) ?? `sdk_${randomUUID()}`;
     return c.eff({
         kind: 'send-message',
         sessionId,

package/dist/agent/toolManagerToSdkMcp.js

@@ -100,7 +100,7 @@ export function buildSdkToolDefs(toolDefs, getContext) {
                         senderType: ctx.senderType,
                         onBehalfOfAgreementId: ctx.onBehalfOfAgreementId,
                         runId: ctx.runId,
-                        wakeKeys: ctx.wakeKeys,
+                        writeKeys: ctx.writeKeys,
                     });
                     if (r.ok)
                         return toCallToolResult(r.result);

package/dist/index.d.ts

@@ -35,8 +35,8 @@ export { validateWorkflow, WorkflowValidationError } from './runtime/validateWor
 export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './runtime/taskBookkeeping.js';
-export { createWakeWriteKeys } from './runtime/wakeWriteKeys.js';
-export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, PendingSubtask, CollectedSubtaskResult, TaskBookkeeping, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, WakeWriteKeys, } from './types.js';
+export { createDeliveryWriteKeys } from './runtime/deliveryWriteKeys.js';
+export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, PendingSubtask, CollectedSubtaskResult, TaskBookkeeping, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, DeliveryWriteKeys, } from './types.js';
 export { default } from './AgentHost.js';
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
@@ -66,7 +66,8 @@ export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
-export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, } from '@ziggs-ai/api-client';
+export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, configureApiClient, } from '@ziggs-ai/api-client';
+export type { ApiClientConfig } from '@ziggs-ai/api-client';
 export { SeenMessages } from './server/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export type { RuntimeLogLevel } from './shared/runtimeLog.js';

package/dist/index.js

@@ -29,7 +29,7 @@ export { validateWorkflow, WorkflowValidationError } from './runtime/validateWor
 export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './runtime/taskBookkeeping.js';
-export { createWakeWriteKeys } from './runtime/wakeWriteKeys.js';
+export { createDeliveryWriteKeys } from './runtime/deliveryWriteKeys.js';
 export { default } from './AgentHost.js';
 // ── Supporting modules ──────────────────────────────────────────────────────
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
@@ -71,6 +71,9 @@ export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
-export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, } from '@ziggs-ai/api-client';
+export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, 
+// ZIG-1204 — self-hosted / non-default backend: consumers of agent-sdk alone
+// must be able to point the shared HTTP client without a direct api-client dep.
+configureApiClient, } from '@ziggs-ai/api-client';
 export { SeenMessages } from './server/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/ingress/normalizeIncoming.d.ts

@@ -7,7 +7,7 @@ export interface NormalizedEvent {
         /**
          * Backend per-delivery id of the chat row this event came from. The one
          * field of the event that is identical on live push and on catch-up
-         * redelivery, so it anchors the wake's idempotency keys (wakeWriteKeys).
+         * redelivery, so it anchors the wake's idempotency keys (deliveryWriteKeys).
          */
         messageId?: string;
         timestamp: number;
@@ -92,7 +92,7 @@ interface NormalizeArgs {
  * what is fenced to this agent, so there is no client-side "is this for me"
  * relevance gate — this function decides SHAPE (message vs task_result vs
  * agreement_lifecycle vs notification) and the fields the FSM / SessionResolver /
- * wakeWriteKeys depend on, nothing more. `ownAgentId` is accepted for call-site
+ * deliveryWriteKeys depend on, nothing more. `ownAgentId` is accepted for call-site
  * compatibility but no longer gates anything.
  */
 export declare function normalizeIncomingEvent({ text, metadata }: NormalizeArgs): NormalizedEvent;

package/dist/ingress/normalizeIncoming.js

@@ -86,7 +86,7 @@ function isTerminalTaskState(state) {
  * what is fenced to this agent, so there is no client-side "is this for me"
  * relevance gate — this function decides SHAPE (message vs task_result vs
  * agreement_lifecycle vs notification) and the fields the FSM / SessionResolver /
- * wakeWriteKeys depend on, nothing more. `ownAgentId` is accepted for call-site
+ * deliveryWriteKeys depend on, nothing more. `ownAgentId` is accepted for call-site
  * compatibility but no longer gates anything.
  */
 export function normalizeIncomingEvent({ text, metadata = {} }) {

package/dist/runtime/AgentMachine.d.ts

@@ -1,4 +1,4 @@
-import type { Ctx, Outcome, Workflow, Identity, EffectHandler, WakeWriteKeys } from '../types.js';
+import type { Ctx, Outcome, Workflow, Identity, EffectHandler, DeliveryWriteKeys } from '../types.js';
 import { type RawEvent } from './buildOutcome.js';
 import type { runTurn as RunTurnFn } from './runTurn.js';
 import { PromptBuilder } from './PromptBuilder.js';
@@ -60,7 +60,7 @@ interface MachineOptions {
     /** Runaway-loop backstop: max thinking turns without human input before parking. Default 100. */
     maxTurnsWithoutUserInput?: number;
     /** This wake's replay-stable write keys — one stream shared by every turn of the tick. */
-    wakeKeys?: WakeWriteKeys;
+    writeKeys?: DeliveryWriteKeys;
 }
 interface IncomingFrame {
     event?: RawEvent;
@@ -86,7 +86,7 @@ export declare class AgentMachine {
     toolManager: ToolManager;
     promptBuilder: PromptBuilder;
     memory?: MemoryStore;
-    wakeKeys?: WakeWriteKeys;
+    writeKeys?: DeliveryWriteKeys;
     state: string;
     status: 'active' | 'stopped';
     ctx: Ctx;
@@ -114,7 +114,7 @@ export declare class AgentMachine {
         output: number;
     };
     get stateTimeoutUnhandled(): boolean;
-    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, wakeKeys }: MachineOptions);
+    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, writeKeys }: MachineOptions);
     getSnapshot(): MachineSnapshot;
     /** Parked = currently in a parked state and not executing a turn. */
     get isParked(): boolean;

package/dist/runtime/AgentMachine.js

@@ -30,7 +30,7 @@ export class AgentMachine {
     toolManager;
     promptBuilder;
     memory;
-    wakeKeys;
+    writeKeys;
     state;
     status = 'active';
     ctx;
@@ -50,14 +50,14 @@ export class AgentMachine {
     get llmCalls() { return this._llmCalls; }
     get tokens() { return this._tokens; }
     get stateTimeoutUnhandled() { return this._stateTimeoutUnhandled; }
-    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, wakeKeys }) {
+    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, writeKeys }) {
         this.workflow = workflow;
         this.executionCore = executionCore;
         this.eff = eff;
         this.toolManager = toolManager;
         this.promptBuilder = promptBuilder;
         this.memory = memory;
-        this.wakeKeys = wakeKeys;
+        this.writeKeys = writeKeys;
         this._transitionTap = transitionTap;
         this._maxTurnsWithoutUserInput = maxTurnsWithoutUserInput ?? DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT;
         this.state = input.state || workflow.initial;
@@ -202,7 +202,7 @@ export class AgentMachine {
                     eff: this.eff,
                     memory: this.memory,
                     incomingEvent: this._lastIncomingEvent,
-                    wakeKeys: this.wakeKeys,
+                    writeKeys: this.writeKeys,
                 });
                 this.ctx.toolResults = toolResults;
                 this._llmCalls += llmCalls;
@@ -296,7 +296,7 @@ export class AgentMachine {
                 promptBuilder: this.promptBuilder,
                 memory: this.memory,
                 definition: this.workflow,
-                wakeKeys: this.wakeKeys,
+                writeKeys: this.writeKeys,
             });
             this.ctx.toolResults = toolResults;
             this._llmCalls += llmCalls;
@@ -365,7 +365,7 @@ export class AgentMachine {
                 sessionId,
                 receiverId: userId,
                 text,
-                messageId: this.wakeKeys?.messageKey({ text, sessionId, receiverId: userId }),
+                messageId: this.writeKeys?.messageKey({ text, sessionId, receiverId: userId }),
             });
         }
         catch { /* best-effort */ }

package/dist/runtime/{wakeWriteKeys.d.ts → deliveryWriteKeys.d.ts}

@@ -1,4 +1,4 @@
-import type { WakeWriteKeys } from '../types.js';
+import type { DeliveryWriteKeys } from '../types.js';
 /**
  * Build the per-wake key derivation. Call once per tick with the lane and the
  * raw triggering event, then thread the instance to every write of the wake.
@@ -24,4 +24,4 @@ import type { WakeWriteKeys } from '../types.js';
  *   as task spawns; the backend dedups on (creator, key) so a replayed
  *   propose/subcontract resolves to the original agreement.
  */
-export declare function createWakeWriteKeys(laneKey: string, event: unknown): WakeWriteKeys;
+export declare function createDeliveryWriteKeys(laneKey: string, event: unknown): DeliveryWriteKeys;

package/dist/runtime/{wakeWriteKeys.js → deliveryWriteKeys.js}

@@ -93,7 +93,7 @@ function sha(input) {
  *   as task spawns; the backend dedups on (creator, key) so a replayed
  *   propose/subcontract resolves to the original agreement.
  */
-export function createWakeWriteKeys(laneKey, event) {
+export function createDeliveryWriteKeys(laneKey, event) {
     const identity = eventIdentity(event);
     const wakeHash = identity === null ? null : sha(`${laneKey}\n${identity}`).slice(0, 40);
     let ordinal = 0;

package/dist/runtime/runMechanical.d.ts

@@ -1,4 +1,4 @@
-import type { Ctx, EffectHandler, MechanicalState, Outcome, ToolResultEntry, WakeWriteKeys } from '../types.js';
+import type { Ctx, EffectHandler, MechanicalState, Outcome, ToolResultEntry, DeliveryWriteKeys } from '../types.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 import { type RawEvent } from './buildOutcome.js';
 export interface RunMechanicalResult {
@@ -23,5 +23,5 @@ export declare function runMechanical(input: {
     memory?: MemoryStore;
     incomingEvent: RawEvent | null;
     /** This wake's replay-stable write keys (shared across every turn of the tick — see AgentMachine). */
-    wakeKeys?: WakeWriteKeys;
+    writeKeys?: DeliveryWriteKeys;
 }): Promise<RunMechanicalResult>;

package/dist/runtime/runMechanical.js

@@ -5,12 +5,12 @@ import { runtimeLog } from '../shared/runtimeLog.js';
  * Used by dumb coordinators whose only job is a fixed tool call on task-assigned.
  */
 export async function runMechanical(input) {
-    const { stateId, state, ctx, eff, memory, incomingEvent, wakeKeys } = input;
+    const { stateId, state, ctx, eff, memory, incomingEvent, writeKeys } = input;
     const sessionId = ctx.identity.sessionId;
     const runId = crypto.randomUUID();
     const effWithTrace = (effect) => {
         if (effect.kind === 'tool-call') {
-            return eff({ ...effect, runId, stateId, wakeKeys });
+            return eff({ ...effect, runId, stateId, writeKeys });
         }
         return eff(effect);
     };

package/dist/runtime/runTurn.d.ts

@@ -1,4 +1,4 @@
-import type { Action, Ctx, Outcome, ToolResultEntry, EffectHandler, WakeWriteKeys } from '../types.js';
+import type { Action, Ctx, Outcome, ToolResultEntry, EffectHandler, DeliveryWriteKeys } from '../types.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 import { type RawEvent } from './buildOutcome.js';
 import { PromptBuilder } from './PromptBuilder.js';
@@ -33,7 +33,7 @@ interface RunTurnInput {
      */
     streamRespondActions?: boolean;
     /** This wake's replay-stable write keys (shared across every turn of the tick — see AgentMachine). */
-    wakeKeys?: WakeWriteKeys;
+    writeKeys?: DeliveryWriteKeys;
 }
 interface RunTurnResult {
     outcome: Outcome;

package/dist/runtime/runTurn.js

@@ -45,7 +45,7 @@ function isGenericFallbackTool(name, toolManager) {
  * call and (optionally) wrapping it in telemetry / dedup / retries.
  */
 export async function runTurn(input) {
-    const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition, wakeKeys } = input;
+    const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition, writeKeys } = input;
     // Default on (ZIG-838); ENABLE_LLM_STREAMING=false is the deployment
     // kill-switch. Any other value (unset, 'true', …) streams.
     const streamRespondActions = input.streamRespondActions ?? process.env.ENABLE_LLM_STREAMING !== 'false';
@@ -62,13 +62,13 @@ export async function runTurn(input) {
             return eff({ ...effect, runId, stateId });
         }
         if (effect.kind === 'tool-call') {
-            return eff({ ...effect, runId, stateId, wakeKeys });
+            return eff({ ...effect, runId, stateId, writeKeys });
         }
         if (effect.kind === 'send-message' && !effect.messageId) {
             const send = effect;
             return eff({
                 ...effect,
-                messageId: wakeKeys?.messageKey({
+                messageId: writeKeys?.messageKey({
                     text: send.text,
                     sessionId: send.sessionId,
                     receiverId: send.receiverId,
@@ -84,7 +84,7 @@ export async function runTurn(input) {
         if (s.length === 0)
             return;
         try {
-            await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s }, idempotencyKey: wakeKeys?.artifactKey({ kind: 'thought', text: s }) });
+            await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s }, idempotencyKey: writeKeys?.artifactKey({ kind: 'thought', text: s }) });
         }
         catch (err) {
             runtimeLog.warn('runTurn', `record-event:thought failed: ${err.message}`);
@@ -380,7 +380,7 @@ export async function runTurn(input) {
                     }
                     const safeText = truncateMsg(replyText);
                     persistMessageId =
-                        wakeKeys?.messageKey({
+                        writeKeys?.messageKey({
                             text: safeText,
                             sessionId,
                             receiverId: decision.receiverId,

package/dist/server/ConnectionPool.d.ts

@@ -27,7 +27,7 @@ export declare class ConnectionPool {
     connectAll(): Promise<void>;
     /** The host for one agent, connecting it if it somehow is not up yet. */
     startAgent(agentId: string): Promise<AgentHost>;
-    sleep(agentId: string): Promise<void>;
+    stopAgent(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
     /**
      * Deliver a message to the named agent and wait for its first outbound

package/dist/server/ConnectionPool.js

@@ -72,11 +72,11 @@ export class ConnectionPool {
     async startAgent(agentId) {
         return await this.manager.startAgent(agentId);
     }
-    async sleep(agentId) {
-        return this.manager.sleep(agentId);
+    async stopAgent(agentId) {
+        return this.manager.stopAgent(agentId);
     }
     async disconnectAll() {
-        return this.manager.sleepAll();
+        return this.manager.stopAll();
     }
     /**
      * Deliver a message to the named agent and wait for its first outbound

package/dist/server/ZiggsEffectHandler.js

@@ -116,7 +116,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         state: 'started',
         tool: effect.name,
         ...(argsPreview ? { args: argsPreview } : {}),
-    }, effect.wakeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }));
+    }, effect.writeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }));
     try {
         const lastUser = roster.users.find((u) => u.userId || u.id);
         // Accumulate token usage from any nested LLM call the tool makes (llmTool),
@@ -152,7 +152,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
             onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
             memory: effect.memory,
-            wakeKeys: effect.wakeKeys,
+            writeKeys: effect.writeKeys,
             reportUsage,
             turnScratch: {},
         });
@@ -163,7 +163,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'completed',
             tool: effect.name,
             result: clipped,
-        }, effect.wakeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }));
+        }, effect.writeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }));
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -181,7 +181,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
-        }, effect.wakeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }));
+        }, effect.writeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }));
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,

package/dist/server/createHealthServer.js

@@ -19,7 +19,7 @@ function readJsonBody(req) {
 export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents', pool, } = {}) {
     const server = createServer(async (req, res) => {
         const url = req.url ?? '/';
-        const startMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
+        const startMatch = url.match(/^\/fleet-start\/([^/?]+)/);
         if (req.method === 'POST' && startMatch && pool) {
             const agentId = decodeURIComponent(startMatch[1]);
             try {

package/dist/server/tools/tier1/protocolRunner.d.ts

@@ -1,6 +1,6 @@
 import type { AgreementService } from '../../agreements/AgreementService.js';
 import type { TaskService } from '../../tasks/TaskService.js';
-import type { WakeWriteKeys } from '../../../types.js';
+import type { DeliveryWriteKeys } from '../../../types.js';
 import { type ContextReadClient } from '@ziggs-ai/api-client';
 interface Services {
     agreementService: AgreementService;
@@ -36,7 +36,7 @@ interface ProtocolPayload {
     })[];
     [key: string]: unknown;
 }
-export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null, wakeKeys?: WakeWriteKeys | null, 
+export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null, writeKeys?: DeliveryWriteKeys | null, 
 /** ZIG-1120 #8 — prefer the cached session snapshot over a fresh HTTP read. */
 cachedAgreements?: unknown[]): Promise<unknown>;
 export {};

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

@@ -45,7 +45,7 @@ function normalizePlanInPlace(payload) {
         ? 'before_execution'
         : 'with_proposal';
 }
-export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, wakeKeys = null, 
+export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, writeKeys = null, 
 /** ZIG-1120 #8 — prefer the cached session snapshot over a fresh HTTP read. */
 cachedAgreements) {
     if (!payload?.operation)
@@ -55,9 +55,9 @@ cachedAgreements) {
     const actorId = actingAgentId?.trim() || null;
     switch (operation) {
         case 'agreement-propose':
-            return proposeAgreement(services, payload, chatId, agents, actorId, wakeKeys);
+            return proposeAgreement(services, payload, chatId, agents, actorId, writeKeys);
         case 'agreement-subcontract':
-            return subcontractAgreement(services, payload, chatId, agents, actorId, wakeKeys, cachedAgreements);
+            return subcontractAgreement(services, payload, chatId, agents, actorId, writeKeys, cachedAgreements);
         case 'agreement-respond':
             if (!payload.agreementId || !payload.action)
                 return null;
@@ -167,7 +167,7 @@ cachedAgreements) {
                 // creating a duplicate. Keyed on what is actually written (the resolved
                 // agreement, not the LLM-cited one), so multiple spawns in one wake stay
                 // distinct.
-                idempotencyKey: wakeKeys?.taskSpawnKey({
+                idempotencyKey: writeKeys?.taskSpawnKey({
                     agreementId: spawnAgreementId,
                     description: payload.description,
                     assigneeId: payload.assigneeId,
@@ -184,7 +184,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, wakeKeys?.taskStateKey(payload.taskId, state));
+            return taskService.updateState(payload.taskId, state, payload.result, writeKeys?.taskStateKey(payload.taskId, state));
         }
         case 'task-update-plan-step':
             if (!payload.taskId)
@@ -207,7 +207,7 @@ cachedAgreements) {
             throw new Error(`Unknown protocol operation: ${operation}`);
     }
 }
-async function proposeAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
+async function proposeAgreement(services, payload, chatId, _agents, actingAgentId, writeKeys = null) {
     if (!payload.description)
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
@@ -248,7 +248,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     // propose resolves to the already-created agreement server-side instead of
     // minting a duplicate proposal. Keyed on what the proposal writes, so
     // multiple proposals in one wake stay distinct.
-    const idempotencyKey = wakeKeys?.agreementProposeKey({
+    const idempotencyKey = writeKeys?.agreementProposeKey({
         proposedTo: payload.proposedTo,
         providerId: payload.providerId,
         description: payload.description,
@@ -301,7 +301,7 @@ function agActive(a) {
 function agIsActiveStatus(a) {
     return String(a.status ?? '') === 'active';
 }
-async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null, cachedAgreements) {
+async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, writeKeys = null, cachedAgreements) {
     if (!payload.description || !payload.executorId)
         return null;
     // b1 (ZIG-832): idempotent subcontract — if a non-terminal sub-agreement for
@@ -361,7 +361,7 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
     // the b1 reuse check above (e.g. no chatId, or the sub not yet visible in the
     // snapshot) resolves to the already-created sub-agreement server-side instead
     // of minting a duplicate.
-    const idempotencyKey = wakeKeys?.agreementSubcontractKey({
+    const idempotencyKey = writeKeys?.agreementSubcontractKey({
         executorId: payload.executorId,
         description: payload.description,
         parentAgreementId: payload.parentAgreementId ?? '',

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

@@ -36,7 +36,7 @@ function handlerFor(toolName) {
             taskService: c.taskService,
             agreementService: c.agreementService,
             contextReadClient: c.contextReadClient,
-        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null, c.wakeKeys ?? null, Array.isArray(c.agreements) ? c.agreements : undefined);
+        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null, c.writeKeys ?? null, Array.isArray(c.agreements) ? c.agreements : undefined);
         if (result == null)
             throw new Error(`Operation ${operation} returned no result`);
         return result;

package/dist/types.d.ts

@@ -197,7 +197,7 @@ export interface Ctx {
      * traffic could drive it, the brain skips the LLM instead of burning the
      * fleet key on a wake storm.
      */
-    recentWakes?: number[];
+    recentDeliveries?: number[];
 }
 export interface PromptDef {
     role?: string;
@@ -369,11 +369,11 @@ export interface RecordedEntry {
 /**
  * Deterministic idempotency keys for one wake's writes (delivery law, item 2).
  * Created once per tick from (laneKey, triggering event) — see
- * `createWakeWriteKeys` — and threaded to every artifact / task-state write the
+ * `createDeliveryWriteKeys` — and threaded to every artifact / task-state write the
  * wake performs, so a crash-replay of the same wake reproduces the same keys
  * and the backend drops the duplicates. Never LLM-supplied, never random.
  */
-export interface WakeWriteKeys {
+export interface DeliveryWriteKeys {
     /** Stable id of this wake, or null when its trigger has no durable delivery identity (timer/synthetic frames) — null means writes go keyless, as before. */
     readonly wakeKey: string | null;
     /**
@@ -463,7 +463,7 @@ export type Effect = {
     /** FSM state name (ZIG-440). */
     stateId?: string;
     /** Replay-stable write keys for this wake — write-capable tools derive their idempotency key from here, never from the LLM. */
-    wakeKeys?: WakeWriteKeys;
+    writeKeys?: DeliveryWriteKeys;
 } | {
     kind: 'send-message';
     sessionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",