@ziggs-ai/agent-sdk 0.11.0 → 0.11.1

package/README.md

@@ -91,7 +91,7 @@ The public **`Brain`** interface is `tick(TickInput): Promise<TickOutput>`. Buil
 2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, etc., and **`createAgent(config)`** (returns an **`AgentHost`**).
 3. **`connect()`** to go live; the SDK long-polls the HTTP inbox and routes deliveries into **`handleMessage`**.
 
-Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
+Worked examples and the full build path: https://ziggsai.com/docs
 
 Point the shared HTTP client at a non-default backend (self-hosted / local) before constructing hosts — no direct `@ziggs-ai/api-client` dependency needed:
 

package/dist/AgentHost.d.ts

@@ -1,5 +1,5 @@
 import type { AgentConfig, Ctx, Workflow } from './types.js';
-import { Agent } from './agent/Agent.js';
+import { Agent, type TickOutput } from './agent/Agent.js';
 import { ClaudeSdkAgent, type CognitionKind } from './agent/ClaudeSdkAgent.js';
 import { type BrainSelection } from './brain/index.js';
 export type { CognitionKind };
@@ -25,6 +25,7 @@ export interface SessionStore {
 import { ToolManager } from './tools/ToolManager.js';
 import type { ToolDefinition } from './tools/defineTool.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+import { type AgentNeed } from './tools/needs.js';
 /**
  * The single fleet-wide default model — the one place the fallback lives.
  * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
@@ -82,6 +83,12 @@ export interface AgentHostOptions {
      */
     questMatchTags?: string[];
     tools?: ToolDefinition[];
+    /**
+     * Access this agent cannot work without. Enforced at task start:
+     * a task arriving with no live grant behind a declared need is failed with the
+     * missing access named, before the tick spends anything.
+     */
+    needs?: AgentNeed[];
     taskTools?: 'all' | 'none' | string[];
     /**
      * Brain selection — preferred over legacy `cognition`.
@@ -142,6 +149,17 @@ export interface AgentHostOptions {
         cognition: string;
         metrics: import('./agent/Agent.js').TickOutput['metrics'];
     }) => void;
+    /**
+     * Called with everything a wake consists of, immediately before the brain
+     * runs. Pair it with {@link AgentHost.replayWake} to re-run that exact wake
+     * later against edited agent source — the difference between iterating on a
+     * prompt in seconds and standing a whole world back up to see one turn.
+     *
+     * Emitted for every wake, including ones the brain then declines to spend an
+     * LLM call on, because "why did nothing happen?" is the question a recording
+     * most often has to answer.
+     */
+    wakeTap?: (record: WakeRecord) => void;
     /** Production monitoring ingest. Default on; set false to disable. */
     telemetryIngest?: boolean;
     /**
@@ -150,6 +168,28 @@ export interface AgentHostOptions {
      */
     inboxCatchUp?: boolean;
 }
+/**
+ * One wake, as the brain received it.
+ *
+ * These four fields ARE the tick's input (`agent.tick({ event, ctx, state,
+ * identity })`) — everything else a tick touches is rebuilt from the agent's own
+ * config. So a record is replayable on its own, and a replay that behaves
+ * differently differs because the agent changed, not because the input drifted.
+ *
+ * Plain JSON on purpose: a record is meant to survive being written to a file
+ * and read back by another process.
+ */
+export interface WakeRecord {
+    agentId: string;
+    sessionId: string;
+    laneKey: string;
+    /** The event frame that woke the agent. */
+    event: unknown;
+    /** FSM context carried into the tick — undefined on a cold lane. */
+    ctx?: unknown;
+    /** FSM state the lane was parked in — undefined on a cold lane. */
+    state?: string;
+}
 /**
  * ToolManager is a Map keyed by tool name, so the last registration silently
  * wins. An agent's own tools register last — which means an `extraTools` entry
@@ -189,6 +229,8 @@ export declare class AgentHost {
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     private inboxLoop;
     private inboxLoopEnabled;
+    /** Short-lived grant-provider cache for the declared-needs gate. */
+    private grantProviderCache;
     constructor(options?: AgentHostOptions);
     private _validate;
     private _setup;
@@ -245,7 +287,45 @@ export declare class AgentHost {
      * still gets its turn, because that is an agent with something left to say.
      */
     private isSettledTaskEcho;
+    /** Providers of this agent's live connection grants. Its own seam, so the gate below is testable without a backend. */
+    private _listGrantProviders;
+    /**
+     * Short TTL on purpose: the gate runs on every wake, and a claim produces
+     * several in seconds — but hire comes before grant, so a grant arriving
+     * mid-engagement has to take effect without a restart.
+     */
+    private _grantProvidersCached;
+    /**
+     * Refuse work this agent has no way to do, before it costs a turn.
+     * Returns true when work was refused and the tick must not run.
+     *
+     * Enforced at wake for an agent holding assigned work, not at hire: hire comes
+     * first and the grant second, so a hire-time gate would refuse every honest
+     * one. Not limited to the task frame either — a store claim wakes the agent on
+     * the agreement first, and a task-only gate let the model take that turn and
+     * reason its own way to "I have no grant" (measured on linear-janitor: 8 calls,
+     * 114,025 tokens, for what one HTTP call answers).
+     *
+     * It fails the task rather than skipping quietly, which would leave it active
+     * with nothing working it — the same invisible stall from the buyer's side.
+     */
+    private _refuseIfNeedsUnmet;
     private _processEvent;
+    /**
+     * Re-run one recorded wake against THIS host's agent, and nothing else.
+     *
+     * The dev loop for a prompt: record a wake off a live run, edit the agent, and
+     * see what it does differently in seconds instead of standing a world back up
+     * for one turn. The brain, tools and effect handler are the real ones, so the
+     * turn is real — its tool calls hit the backend this host is pointed at, which
+     * is why it belongs against a disposable world and not a shared one.
+     *
+     * Deliberately NOT routed through `_processEvent`: everything that method does
+     * around the tick is lane bookkeeping — session state, liveness timers, session
+     * persistence, ack decisions, failure re-arm — and a replay has no lane to keep.
+     * Borrowing that path would make a dev tool able to disturb a live one.
+     */
+    replayWake(record: WakeRecord): Promise<TickOutput>;
     /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
     private _armIfTimedParked;
     private _resolveOwnAgentId;

package/dist/AgentHost.js

@@ -16,7 +16,8 @@ import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
 import { marketplaceViewTool } from './server/tools/tier2/marketplaceTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
-import { ArtifactsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
+import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
+import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 import { TaskService } from './server/tasks/TaskService.js';
 import { AgreementService } from './server/agreements/AgreementService.js';
 import { runInboxLoop } from './server/inboxLoop.js';
@@ -177,6 +178,8 @@ export class AgentHost {
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     inboxLoop = null;
     inboxLoopEnabled;
+    /** Short-lived grant-provider cache for the declared-needs gate. */
+    grantProviderCache = null;
     constructor(options = {}) {
         const resolved = applyBrainToHostOptions(options);
         this.options = {
@@ -190,6 +193,11 @@ export class AgentHost {
             systemPrompt: resolved.systemPrompt,
             specialization: resolved.specialization ?? null,
             tools: resolved.tools || [],
+            // Copied deliberately: this object is an allow-list, so a field left out
+            // here is silently dropped between the manifest and the runtime. That is
+            // exactly how `respondsToProposals` reached the store as null for 133
+            // agents — the declaration existed and nothing carried it.
+            needs: resolved.needs,
             taskTools: resolved.taskTools,
             states: resolved.states,
             initial: resolved.initial,
@@ -200,6 +208,7 @@ export class AgentHost {
             effectTap: resolved.effectTap,
             transitionTap: resolved.transitionTap,
             metricsTap: resolved.metricsTap,
+            wakeTap: resolved.wakeTap,
             inboxCatchUp: resolved.inboxCatchUp,
             brain: resolved.brain,
             cognition: resolved.cognition ?? 'fsm',
@@ -209,9 +218,9 @@ export class AgentHost {
         this.inboxLoopEnabled = options.inboxCatchUp !== false;
         this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
         // A Claude-brain wake legitimately runs long (multi-turn query, prose
-        // deliverables) — 120s watchdogged real spec-writing wakes mid-flight,
-        // which then redelivered and re-ran (dogfood, 2026-07-26). FSM
-        // turns stay on the tight default.
+        // deliverables). At 120s the watchdog cuts real spec-writing wakes
+        // mid-flight, which then redeliver and re-run. FSM turns stay on the tight
+        // default.
         this.tickTimeoutMs =
             options.tickTimeoutMs ??
                 (isClaudeCognition(options.cognition)
@@ -518,6 +527,90 @@ export class AgentHost {
         const reported = result.result;
         return reported !== undefined && reported !== null && reported !== '';
     }
+    /** Providers of this agent's live connection grants. Its own seam, so the gate below is testable without a backend. */
+    async _listGrantProviders(operatorKey, agentId) {
+        const groups = await new ConnectionsClient(operatorKey, agentId).listForHolder();
+        return groups.filter((g) => (g.grants ?? []).length > 0).map((g) => g.provider);
+    }
+    /**
+     * Short TTL on purpose: the gate runs on every wake, and a claim produces
+     * several in seconds — but hire comes before grant, so a grant arriving
+     * mid-engagement has to take effect without a restart.
+     */
+    async _grantProvidersCached(operatorKey, agentId) {
+        const now = Date.now();
+        if (this.grantProviderCache && now - this.grantProviderCache.at < 30_000) {
+            return this.grantProviderCache.providers;
+        }
+        const providers = await this._listGrantProviders(operatorKey, agentId);
+        this.grantProviderCache = { at: now, providers };
+        return providers;
+    }
+    /**
+     * Refuse work this agent has no way to do, before it costs a turn.
+     * Returns true when work was refused and the tick must not run.
+     *
+     * Enforced at wake for an agent holding assigned work, not at hire: hire comes
+     * first and the grant second, so a hire-time gate would refuse every honest
+     * one. Not limited to the task frame either — a store claim wakes the agent on
+     * the agreement first, and a task-only gate let the model take that turn and
+     * reason its own way to "I have no grant" (measured on linear-janitor: 8 calls,
+     * 114,025 tokens, for what one HTTP call answers).
+     *
+     * It fails the task rather than skipping quietly, which would leave it active
+     * with nothing working it — the same invisible stall from the buyer's side.
+     */
+    async _refuseIfNeedsUnmet(_event, _laneKey) {
+        const needs = normalizeNeeds(this.options.needs);
+        if (!needs.length)
+            return false;
+        const operatorKey = this.options.operatorKey;
+        const agentId = this.options.agentId;
+        if (!operatorKey || !agentId || !this.taskService)
+            return false;
+        let providers;
+        try {
+            providers = await this._grantProvidersCached(operatorKey, agentId);
+        }
+        catch (err) {
+            // A grants read that failed is not proof the grant is missing, and failing
+            // the task on our own outage would be worse than letting the agent try.
+            runtimeLog.warn(this.options.name || 'agent', `needs check skipped: ${err?.message ?? err}`);
+            return false;
+        }
+        const unmet = unmetNeeds(needs, providers);
+        if (!unmet.length)
+            return false;
+        // Only work already on this agent's plate is refused. A wake with no assigned
+        // task is someone talking to it — an agent that cannot reach Linear can still
+        // say so in a sentence, and muting it would be a worse silence.
+        let assigned;
+        try {
+            assigned = await this.taskService.getActiveTasksForAgent(agentId);
+        }
+        catch (err) {
+            runtimeLog.warn(this.options.name || 'agent', `needs check could not read assigned work: ${err?.message ?? err}`);
+            return false;
+        }
+        const mine = assigned.filter((t) => t.taskId && (!t.assigneeId || t.assigneeId === agentId));
+        if (!mine.length)
+            return false;
+        const message = unmetNeedsMessage(unmet);
+        for (const task of mine) {
+            const taskId = String(task.taskId);
+            runtimeLog.warn(this.options.name || 'agent', `refusing task ${taskId} — ${message}`);
+            try {
+                await this.taskService.updateState(taskId, 'failed', {
+                    summary: message,
+                    status: 'failed',
+                });
+            }
+            catch (err) {
+                runtimeLog.warn(this.options.name || 'agent', `could not fail task ${taskId} after refusing it: ${err?.message ?? err}`);
+            }
+        }
+        return true;
+    }
     async _processEvent(event, laneKey) {
         const session = this.sessions.get(laneKey);
         if (!session?.sessionId)
@@ -530,6 +623,10 @@ export class AgentHost {
             runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its task already reported a result`);
             return;
         }
+        // Before the tick spends anything: work this agent declared it cannot do
+        // without access it does not hold.
+        if (await this._refuseIfNeedsUnmet(event, laneKey))
+            return;
         // Stale timer frames (superseded epoch) are dropped BEFORE touching the
         // live timer — a pure-stale frame must not reset a freshly armed countdown.
         const frame = this.stateTimers.stripStale(event, laneKey);
@@ -557,6 +654,24 @@ export class AgentHost {
             sessionId: session.sessionId,
             laneKey,
         };
+        // Recorded here rather than after the tick: this is the last point where the
+        // input is still exactly what the brain will see, and a wake that goes on to
+        // throw is the one most worth replaying.
+        if (this.options.wakeTap) {
+            try {
+                this.options.wakeTap({
+                    agentId: identity.agentId,
+                    sessionId: identity.sessionId,
+                    laneKey,
+                    event: frame,
+                    ctx: session.ctx,
+                    state: session.state,
+                });
+            }
+            catch (err) {
+                runtimeLog.warn('AgentHost', `wakeTap failed: ${err?.message || err}`);
+            }
+        }
         // The watchdog timer must be cleared once the tick settles — leaving it
         // armed pinned one live 2-minute timer per tick (and kept short-lived
         // processes/tests alive until it fired).
@@ -644,6 +759,71 @@ export class AgentHost {
             clearTimeout(tickWatchdog);
         }
     }
+    /**
+     * Re-run one recorded wake against THIS host's agent, and nothing else.
+     *
+     * The dev loop for a prompt: record a wake off a live run, edit the agent, and
+     * see what it does differently in seconds instead of standing a world back up
+     * for one turn. The brain, tools and effect handler are the real ones, so the
+     * turn is real — its tool calls hit the backend this host is pointed at, which
+     * is why it belongs against a disposable world and not a shared one.
+     *
+     * Deliberately NOT routed through `_processEvent`: everything that method does
+     * around the tick is lane bookkeeping — session state, liveness timers, session
+     * persistence, ack decisions, failure re-arm — and a replay has no lane to keep.
+     * Borrowing that path would make a dev tool able to disturb a live one.
+     */
+    async replayWake(record) {
+        if (!record?.sessionId)
+            throw new Error('replayWake: record.sessionId is required');
+        const identity = {
+            agentId: record.agentId || this.options.agentId,
+            sessionId: record.sessionId,
+            laneKey: record.laneKey || record.sessionId,
+        };
+        // Same watchdog as a live wake, for the same reason: an unaborted Claude
+        // query outlives the promise that abandoned it and keeps spending.
+        const abort = new AbortController();
+        let watchdog;
+        try {
+            const result = await Promise.race([
+                this.agent.tick({
+                    event: record.event,
+                    ctx: record.ctx,
+                    state: record.state,
+                    identity,
+                    eff: this.eff,
+                    memory: this.memory,
+                    transitionTap: this.options.transitionTap,
+                    signal: abort.signal,
+                }),
+                new Promise((_, reject) => {
+                    watchdog = setTimeout(() => {
+                        abort.abort(new Error('tick timeout'));
+                        reject(new Error('tick timeout'));
+                    }, this.tickTimeoutMs);
+                }),
+            ]);
+            if (this.options.metricsTap && result.metrics) {
+                try {
+                    this.options.metricsTap({
+                        agentId: identity.agentId,
+                        sessionId: identity.sessionId,
+                        model: this.options.model ?? 'unknown',
+                        cognition: this.options.cognition ?? 'fsm',
+                        metrics: result.metrics,
+                    });
+                }
+                catch (err) {
+                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                }
+            }
+            return result;
+        }
+        finally {
+            clearTimeout(watchdog);
+        }
+    }
     /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
     _armIfTimedParked(laneKey, stateName) {
         if (!stateName)

package/dist/adapters/McpAdapter.js

@@ -56,12 +56,11 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     if (!agentId) {
         throw new Error('ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)');
     }
-    // ZIG-1104: explicit overrides still win, but the LAST resort is
-    // `getBackendUrl()` — the resolution every other SDK call uses — not
-    // `localhost:3000`. The fleet task sets neither BACKEND_URL nor
-    // ZIGGS_BACKEND_URL (it sets HTTP_URL), so the old chain silently pointed every
-    // gateway call at localhost inside the container: the requests never reached the
-    // backend at all, and the agent reported the server as unreachable.
+    // Explicit overrides still win, but the LAST resort is `getBackendUrl()` —
+    // the resolution every other SDK call uses — not `localhost:3000`. A deployment
+    // that sets none of BACKEND_URL / ZIGGS_BACKEND_URL would otherwise have every
+    // gateway call silently point at localhost inside its own container: the
+    // requests never reach the backend, and the agent reports it as unreachable.
     const baseUrl = (config.baseUrl ||
         process.env.ZIGGS_BACKEND_URL ||
         process.env.BACKEND_URL ||
@@ -85,12 +84,11 @@ export function resolvePerUserGatewayTarget(config, agentId, userId, onBehalfOfA
     if (!operatorKey) {
         throw new Error('ziggs-per-user MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
     }
-    // ZIG-1104: explicit overrides still win, but the LAST resort is
-    // `getBackendUrl()` — the resolution every other SDK call uses — not
-    // `localhost:3000`. The fleet task sets neither BACKEND_URL nor
-    // ZIGGS_BACKEND_URL (it sets HTTP_URL), so the old chain silently pointed every
-    // gateway call at localhost inside the container: the requests never reached the
-    // backend at all, and the agent reported the server as unreachable.
+    // Explicit overrides still win, but the LAST resort is `getBackendUrl()` —
+    // the resolution every other SDK call uses — not `localhost:3000`. A deployment
+    // that sets none of BACKEND_URL / ZIGGS_BACKEND_URL would otherwise have every
+    // gateway call silently point at localhost inside its own container: the
+    // requests never reach the backend, and the agent reports it as unreachable.
     const baseUrl = (config.baseUrl ||
         process.env.ZIGGS_BACKEND_URL ||
         process.env.BACKEND_URL ||

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -52,6 +52,15 @@ export interface ClaudeSdkAgentOptions {
  * that is all the CLI gives us — no code, no typed error — so keep it narrow
  * enough that a different failure never claims the retry.
  */
+/**
+ * "I ran out of turns", as Claude Code reports it.
+ *
+ * Turn exhaustion is not a crash: the wake did real work and stopped at a cap
+ * we set. It arrives as a thrown error result with no code and no type, so the
+ * message is all there is to match on — kept narrow so no other failure claims
+ * the handling.
+ */
+export declare function isMaxTurnsError(err: unknown): boolean;
 export declare function isMissingSessionError(err: unknown): boolean;
 /**
  * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`