@ziggs-ai/agent-sdk 0.9.0 → 0.10.1

package/dist/server/tools/tier2/connectionTools.js

@@ -7,7 +7,13 @@ import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
 // allowance in the parity table).
 export const connectionProxyTool = toolFromCapability(connectionProxyCapability);
 export const requestConnectionTool = toolFromCapability(requestConnectionCapability);
-export const connectionListGrantsTool = defineTool('connection_list_grants', { connectionId: { type: 'string', required: true } }, async (args, ctx) => {
+export const connectionListGrantsTool = defineTool('connection_list_grants', {
+    connectionId: {
+        type: 'string',
+        required: true,
+        description: 'The stored connection to list grants for.',
+    },
+}, async (args, ctx) => {
     if (!args['connectionId'])
         throw new Error('connectionId is required');
     const operatorKey = ctx?.['operatorKey'];
@@ -28,6 +34,11 @@ export const connectionListGrantsTool = defineTool('connection_list_grants', { c
             wrapped.body = err.body;
         throw wrapped;
     }
+}, {
+    // ZIG-1128: this shipped with no description at all — the model was handed a
+    // name and a parameter and left to guess what the tool was for. Found by the
+    // new SDK tool-text guard.
+    description: "List the grants issued to this agent on one stored connection. Returns the grantId that connection_proxy needs. Use it when you have a connectionId but not the grantId — grant_list (scopeKind=connection) is the wider read across every connection.",
 });
 export const CONNECTION_TOOLS = [
     connectionProxyTool,

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/tools/capabilityAdapter.js

@@ -10,12 +10,23 @@ export function toolFromCapability(cap) {
     return defineTool(cap.names.sdk, cap.params, async (args, ctx) => {
         const operatorKey = ctx?.['operatorKey'];
         const agentId = ctx?.['agentId'];
+        // ZIG-1092 — the lane was already threaded to this exact point by
+        // ZIG-775's shared executor (`chatId: effect.sessionId` in
+        // executeToolWithSideEffects); it just was not used to narrow anything.
+        // Reading it here makes the fence brain-agnostic by construction: the
+        // Claude brain and the FSM brain both arrive through this adapter.
+        const laneId = ctx?.['chatId'] ||
+            ctx?.['sessionId'];
         if (!operatorKey)
             throw new Error('operatorKey missing from tool context');
         if (cap.needsAgentId && !agentId)
             throw new Error('agentId missing from tool context');
         const env = {
-            creds: { operatorKey, ...(agentId ? { agentId } : {}) },
+            creds: {
+                operatorKey,
+                ...(agentId ? { agentId } : {}),
+                ...(laneId ? { laneId } : {}),
+            },
             // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the
             // shared clients default to HTTP_URL (api-client convention) otherwise.
             baseUrl: process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined,

package/dist/tools/recordReport.js

@@ -12,10 +12,14 @@ export async function recordReport(input) {
     const { creds, taskId, report, chatId, agreementId, deliverable } = input;
     // ZIG-1037: no container needed. The deliverable is bound to its task, which
     // is what makes it retrievable as `via=task:<taskId>` and readable by the
-    // task's parties — a chat or agreement was never what made that work. Both
-    // containers at once IS still a mistake (only one takes effect), so resolve it
-    // here the way artifact_record does rather than letting the client throw
-    // at the last step of a finished task.
+    // task's parties — a chat or agreement was never what made that work.
+    //
+    // ZIG-1075: the agreement still wins here, and this is now the ONE place that
+    // resolves rather than refuses — deliberately, because the caller is not a
+    // model choosing arguments. `recordReport` is handed both ids by the runtime
+    // (the task's agreement and the chat it is running in), so there is no
+    // mistake to surface and nobody to retry: refusing would fail a finished
+    // task's delivery over a pair of ids it did not choose.
     const scope = agreementId ? { agreementId } : chatId ? { chatId } : {};
     // Deliverable FIRST, then close the task.
     //

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). */
@@ -385,8 +376,15 @@ export interface RecordedEntry {
 export interface WakeWriteKeys {
     /** 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;
-    /** Key for the next artifact write of this wake. Draws a per-wake ordinal — call exactly once per write, at the call site. */
-    artifactKey(): string | undefined;
+    /**
+     * Key for an artifact write of this wake. Pass the artifact's content so the
+     * key is derived from it (ZIG-1045 semantics): a wake writing several
+     * artifacts gets several keys, and a redelivered wake that re-writes the same
+     * content reuses its key instead of colliding on an ordinal slot and being
+     * discarded. Omitting content falls back to a per-wake ordinal — call exactly
+     * once per write in that case.
+     */
+    artifactKey(content?: unknown): string | undefined;
     /** Key for a task state transition. Derived from (taskId, state), so it is stable regardless of tool-call order within the wake. */
     taskStateKey(taskId: string, state: string): string | undefined;
     /**
@@ -512,7 +510,19 @@ export interface ServicesConfig {
 }
 export interface DefineAgentInput {
     agentId: string;
+    /**
+     * Human-facing one-liner: what this agent does, for a buyer reading the store
+     * row. NOT the system prompt — a claude-sdk agent puts its prompt in
+     * `systemPrompt` (ZIG-1080: every claude-sdk agent used to pass its prompt
+     * here, and `deriveAgentRecord` published it straight to the store).
+     */
     description: string;
+    /**
+     * Claude-brain only: the agent's system prompt (its `## Your role` block).
+     * Falls back to `description` when absent, which is what every FSM agent
+     * relies on. Never surfaced in the store.
+     */
+    systemPrompt?: string;
     specialization?: string;
     initial: string;
     states: Record<string, State>;
@@ -534,7 +544,10 @@ export interface AgentConfig {
     anthropicKey: string | undefined;
     operatorKey?: string;
     agentId: string;
+    /** Store-facing one-liner. See DefineAgentInput.description. */
     description: string;
+    /** Claude-brain system prompt; falls back to `description`. */
+    systemPrompt?: string;
     specialization?: string;
     tools: unknown[];
     model: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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.8.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;
-    };
-}