@ziggs-ai/agent-sdk 0.10.0 → 0.10.2

package/dist/tasks/protocolRegistry.d.ts

@@ -1,3 +1,23 @@
+/**
+ * The protocol verbs and the state operation each one performs.
+ *
+ * This is the single place the set is written down (ZIG-1110). It used to be
+ * restated: the tool definitions passed their operation string to `handlerFor`
+ * by hand, and this table listed them again. `agreement_fulfill` was in the
+ * first list and not the second, so it dispatched fine but
+ * `isProtocolToolName` said no — and at every consumer (applyEffects,
+ * routingLabels, buildOutcome) the verb that ends an engagement permanently
+ * degraded to an unlabelled plain tool-result whose outcome never reached
+ * context.
+ *
+ * A protocol tool now takes its handler from this table BY TOOL NAME, and a
+ * name that is absent throws while the module is loading. Adding a verb in one
+ * place can no longer half-register it: the tool cannot be constructed at all
+ * until it appears here.
+ *
+ * This module deliberately imports nothing. It is read from the context and
+ * runtime paths, which must not pull in the server tool chain.
+ */
 export declare const PROTOCOL_TOOL_TO_OPERATION: Readonly<{
     readonly agreement_propose: "agreement-propose";
     readonly agreement_subcontract: "agreement-subcontract";
@@ -6,6 +26,7 @@ export declare const PROTOCOL_TOOL_TO_OPERATION: Readonly<{
     readonly agreement_counter: "agreement-counter-proposal";
     readonly agreement_get: "agreement-check-proposal";
     readonly agreement_revoke: "agreement-revoke";
+    readonly agreement_fulfill: "agreement-fulfill";
     readonly task_create: "task-spawn";
     readonly task_set_result: "task-update";
     readonly task_update_plan_step: "task-update-plan-step";
@@ -15,3 +36,9 @@ export type ProtocolOperation = (typeof PROTOCOL_TOOL_TO_OPERATION)[ProtocolTool
 export declare const PROTOCOL_TOOL_NAMES: readonly ProtocolToolName[];
 export declare function mapProtocolToolToOperation(toolName: string): ProtocolOperation | null;
 export declare function isProtocolToolName(toolName: string): toolName is ProtocolToolName;
+/**
+ * The operation a protocol tool performs, or a throw. Called at module load by
+ * the tool definitions, so a verb defined without a registry entry takes the
+ * import down instead of shipping half-registered.
+ */
+export declare function requireProtocolOperation(toolName: string): ProtocolOperation;

package/dist/tasks/protocolRegistry.js

@@ -1,3 +1,23 @@
+/**
+ * The protocol verbs and the state operation each one performs.
+ *
+ * This is the single place the set is written down (ZIG-1110). It used to be
+ * restated: the tool definitions passed their operation string to `handlerFor`
+ * by hand, and this table listed them again. `agreement_fulfill` was in the
+ * first list and not the second, so it dispatched fine but
+ * `isProtocolToolName` said no — and at every consumer (applyEffects,
+ * routingLabels, buildOutcome) the verb that ends an engagement permanently
+ * degraded to an unlabelled plain tool-result whose outcome never reached
+ * context.
+ *
+ * A protocol tool now takes its handler from this table BY TOOL NAME, and a
+ * name that is absent throws while the module is loading. Adding a verb in one
+ * place can no longer half-register it: the tool cannot be constructed at all
+ * until it appears here.
+ *
+ * This module deliberately imports nothing. It is read from the context and
+ * runtime paths, which must not pull in the server tool chain.
+ */
 export const PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
     agreement_propose: 'agreement-propose',
     agreement_subcontract: 'agreement-subcontract',
@@ -6,6 +26,7 @@ export const PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
     agreement_counter: 'agreement-counter-proposal',
     agreement_get: 'agreement-check-proposal',
     agreement_revoke: 'agreement-revoke',
+    agreement_fulfill: 'agreement-fulfill',
     task_create: 'task-spawn',
     task_set_result: 'task-update',
     task_update_plan_step: 'task-update-plan-step',
@@ -19,3 +40,18 @@ export function mapProtocolToolToOperation(toolName) {
 export function isProtocolToolName(toolName) {
     return mapProtocolToolToOperation(toolName) != null;
 }
+/**
+ * The operation a protocol tool performs, or a throw. Called at module load by
+ * the tool definitions, so a verb defined without a registry entry takes the
+ * import down instead of shipping half-registered.
+ */
+export function requireProtocolOperation(toolName) {
+    const operation = mapProtocolToolToOperation(toolName);
+    if (!operation) {
+        throw new Error(`Unknown protocol tool "${toolName}": add it to PROTOCOL_TOOL_TO_OPERATION ` +
+            '(agent-sdk/src/tasks/protocolRegistry.ts). Every consumer of the protocol ' +
+            'set reads that table — a tool missing from it dispatches but is never ' +
+            'recognised as protocol, so its result never reaches context.');
+    }
+    return operation;
+}

package/dist/types.d.ts

@@ -187,15 +187,6 @@ export interface Ctx {
     /** Focus agreement — sync'd with tasks[activeTaskId] when a task is focused. */
     activeAgreementId: string | null;
     pendingProposalAgreementId: string | null;
-    /**
-     * @deprecated ZIG-1057 — unused mirrors; always `{}` / `[]` after bootstrap.
-     * Read via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`.
-     */
-    pendingSubtasks: Record<string, PendingSubtask>;
-    /** @deprecated ZIG-1057 — see `pendingSubtasks`. */
-    collectedResults: CollectedSubtaskResult[];
-    /** @deprecated ZIG-1057 — see `pendingSubtasks`. */
-    delegatedAgreementIds: string[];
     toolResults: ToolResultEntry[];
     lastOutcome: Outcome;
     /** Claude Agent SDK session id for resume across ticks (claude-sdk cognition only). */
@@ -206,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;
@@ -378,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;
     /**
@@ -472,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.0",
+  "version": "0.10.2",
   "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.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.9.0",
+    "@ziggs-ai/api-client": "^0.9.1",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",

package/dist/server/staleBacklogGate.d.ts

@@ -1,57 +0,0 @@
-/**
- * Launcher startup backlog policy (ZIG-910).
- *
- * "Work waits" has no statute of limitations on the backend — the inbox never
- * expires anything. But when a fleet comes up after a dark period, replaying
- * every weeks-old actionable slice means a mass of LLM turns on stale work at
- * real token cost. The consumer chooses what to pick up: this gate keeps the
- * operator-poll lazy start from resurrecting agents whose newest actionable
- * item is older than a cutoff. Skips are never silent — one loud aggregated
- * summary line announces what was left down and how to opt back in.
- *
- * Env:
- *   FLEET_REPLAY_MAX_AGE  cutoff, e.g. "3d" | "12h" | "30m" | bare number =
- *                         days (default "3d")
- *   FLEET_REPLAY_STALE=1  replay everything (disable the gate)
- *
- * Scope is the launcher only. The backend inbox is untouched, explicit
- * `pool.startAgent()` / preStart are untouched, and an agent with ANY fresh item
- * starts normally (its own inbox loop then drains the stale backlog too).
- */
-import type { InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
-export declare const DEFAULT_REPLAY_MAX_AGE_MS: number;
-export interface ReplayPolicy {
-    /** Skip slices whose newest actionable item is older than this. */
-    maxAgeMs: number;
-    /** FLEET_REPLAY_STALE=1 — replay everything, gate disabled. */
-    replayAll: boolean;
-}
-/**
- * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
- * granularity). Returns null on garbage so the caller can warn and fall back.
- */
-export declare function parseReplayMaxAge(raw: string): number | null;
-export declare function resolveReplayPolicy(env?: NodeJS.ProcessEnv): ReplayPolicy;
-/**
- * Newest actionable instant for an agent, from its operator-sweep entry.
- *
- * The sweep hands this over directly now — it is the agent's delivery
- * watermark — where this used to fold together the max timestamp across every
- * channel of a whole envelope. An agent surfaced only for open work carries no
- * delivery instant: age is unprovable, so it is treated as fresh and started.
- * Stale-skipping a half-finished task would strand it.
- */
-export declare function newestActionableAt(entry: InboxOperatorAgentEntry): number | null;
-export declare function formatAge(ms: number): string;
-export interface StaleBacklogGateOptions extends ReplayPolicy {
-    label?: string;
-    now?: () => number;
-    log?: (line: string) => void;
-}
-/**
- * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
- * resurface in every envelope (reading never acks), so announcements are
- * per-agent-once: each poll pass that skips agents not yet announced emits one
- * aggregated warn line covering them.
- */
-export declare function createStaleBacklogGate({ maxAgeMs, replayAll, label, now, log, }: StaleBacklogGateOptions): (entry: InboxOperatorAgentEntry) => boolean;

package/dist/server/staleBacklogGate.js

@@ -1,100 +0,0 @@
-import { runtimeLog } from '../shared/runtimeLog.js';
-export const DEFAULT_REPLAY_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1000;
-/**
- * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
- * granularity). Returns null on garbage so the caller can warn and fall back.
- */
-export function parseReplayMaxAge(raw) {
-    const m = /^\s*(\d+(?:\.\d+)?)\s*([dhms]?)\s*$/i.exec(raw);
-    if (!m)
-        return null;
-    const value = Number(m[1]);
-    if (!Number.isFinite(value) || value <= 0)
-        return null;
-    const unitMs = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1_000 }[(m[2] || 'd').toLowerCase()];
-    return value * unitMs;
-}
-export function resolveReplayPolicy(env = process.env) {
-    const replayAll = env.FLEET_REPLAY_STALE === '1' || env.FLEET_REPLAY_STALE === 'true';
-    const raw = env.FLEET_REPLAY_MAX_AGE?.trim();
-    let maxAgeMs = DEFAULT_REPLAY_MAX_AGE_MS;
-    if (raw) {
-        const parsed = parseReplayMaxAge(raw);
-        if (parsed == null) {
-            runtimeLog.warn('staleBacklogGate', `FLEET_REPLAY_MAX_AGE="${raw}" is not a duration (use e.g. "3d", "12h", "30m") — using default ${formatAge(DEFAULT_REPLAY_MAX_AGE_MS)}`);
-        }
-        else {
-            maxAgeMs = parsed;
-        }
-    }
-    return { maxAgeMs, replayAll };
-}
-/**
- * Newest actionable instant for an agent, from its operator-sweep entry.
- *
- * The sweep hands this over directly now — it is the agent's delivery
- * watermark — where this used to fold together the max timestamp across every
- * channel of a whole envelope. An agent surfaced only for open work carries no
- * delivery instant: age is unprovable, so it is treated as fresh and started.
- * Stale-skipping a half-finished task would strand it.
- */
-export function newestActionableAt(entry) {
-    if (!entry.deliveredUpTo)
-        return null;
-    const t = Date.parse(entry.deliveredUpTo);
-    return Number.isNaN(t) ? null : t;
-}
-export function formatAge(ms) {
-    if (ms >= 86_400_000)
-        return `${trimNum(ms / 86_400_000)}d`;
-    if (ms >= 3_600_000)
-        return `${trimNum(ms / 3_600_000)}h`;
-    if (ms >= 60_000)
-        return `${trimNum(ms / 60_000)}m`;
-    return `${trimNum(ms / 1_000)}s`;
-}
-function trimNum(n) {
-    return Number(n.toFixed(1)).toString();
-}
-/**
- * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
- * resurface in every envelope (reading never acks), so announcements are
- * per-agent-once: each poll pass that skips agents not yet announced emits one
- * aggregated warn line covering them.
- */
-export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher', now = Date.now, log, }) {
-    const emit = log ?? ((line) => runtimeLog.warn(label, line));
-    const announced = new Set();
-    let pendingAgents = [];
-    let flushScheduled = false;
-    // One envelope's entries are gated synchronously; a microtask-deferred
-    // flush turns a whole boot flood into a single summary line.
-    const flush = () => {
-        flushScheduled = false;
-        if (pendingAgents.length === 0)
-            return;
-        const preview = pendingAgents.slice(0, 5).join(', ');
-        const more = pendingAgents.length > 5 ? `, +${pendingAgents.length - 5} more` : '';
-        emit(`startup backlog policy: skipped ${pendingAgents.length} agent(s) whose newest mail is older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
-        pendingAgents = [];
-    };
-    return (entry) => {
-        if (replayAll)
-            return true;
-        // Open work always starts, however old: the task is unfinished, not stale.
-        if (entry.hasOpenTasks)
-            return true;
-        const newest = newestActionableAt(entry);
-        if (newest == null || now() - newest <= maxAgeMs)
-            return true;
-        if (!announced.has(entry.agentId)) {
-            announced.add(entry.agentId);
-            pendingAgents.push(entry.agentId);
-            if (!flushScheduled) {
-                flushScheduled = true;
-                queueMicrotask(flush);
-            }
-        }
-        return false;
-    };
-}