@ziggs-ai/agent-sdk 0.10.8 → 0.11.1

package/CHANGELOG.md

@@ -4,10 +4,10 @@
 
 ### Removed (breaking)
 
-- Removed exports `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge`. The launcher rewrite deleted the wake machinery these gated: every agent stays connected and the write signals it, so there is no backlog to age out and nothing to replay-gate (ZIG-993). Pinned to 0.4.x and importing any of the four? Delete the call — the behaviour it bought is now unconditional. There is no replacement API.
+- Removed exports `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge`. The launcher rewrite deleted the wake machinery these gated: every agent stays connected and the write signals it, so there is no backlog to age out and nothing to replay-gate. Pinned to 0.4.x and importing any of the four? Delete the call — the behaviour it bought is now unconditional. There is no replacement API.
 - `FLEET_REPLAY_MAX_AGE` is no longer read; the replay window it set no longer exists. Nothing in this repo sets it, but it can come out of any deployment env that does.
-- `Ctx` no longer carries `pendingSubtasks`, `collectedResults`, or `delegatedAgreementIds`. ZIG-977 moved the real bookkeeping into `Ctx.tasks` (keyed by taskId) and ZIG-1057 stopped syncing these mirrors, but they stayed on the interface as required-and-always-empty — so a workflow guard reading one saw empty forever and silently checked nothing. Read via `allPendingSubtasks(ctx)` / `allCollectedResults(ctx)` / `allDelegatedAgreementIds(ctx)`. Sessions persisted before `tasks` existed are still migrated on restore.
-- `WireResult.status` removed. ZIG-1057 cut `status` from the wire in favour of `state`; four readers kept a `|| r.status` tail, which would have absorbed a backend regression instead of failing on it. Task state resolves as `task?.state || r.state`.
+- `Ctx` no longer carries `pendingSubtasks`, `collectedResults`, or `delegatedAgreementIds`. The real bookkeeping moved into `Ctx.tasks` (keyed by taskId) and these mirrors stopped syncing, but they stayed on the interface as required-and-always-empty — so a workflow guard reading one saw empty forever and silently checked nothing. Read via `allPendingSubtasks(ctx)` / `allCollectedResults(ctx)` / `allDelegatedAgreementIds(ctx)`. Sessions persisted before `tasks` existed are still migrated on restore.
+- `WireResult.status` removed. The wire carries `state` only; the `|| r.status` fallback tails were removed so a backend regression fails loudly instead of being absorbed. Task state resolves as `task?.state || r.state`.
 
 ### Added
 
@@ -18,16 +18,16 @@
 - Attention gate: only the addressed agent spends a turn. A message addressed elsewhere in a shared room no longer wakes every participant.
 - No turn on a lane whose agreement has ended, and none on the echo of a task that already reported — both previously cost a turn and produced nothing.
 - Persona wire shapes are understood on inbound frames.
-- A wake declares its lane so the backend can fence reach (ZIG-1092).
-- A proposal awaiting the agent's own consent counts as actionable rather than a notice to park (ZIG-1078).
-- Artifact idempotency keys are derived from content (ZIG-1083).
-- Blank tool arguments fall back to the wake's lane (ZIG-1081).
+- A wake declares its lane so the backend can fence reach.
+- A proposal awaiting the agent's own consent counts as actionable rather than a notice to park.
+- Artifact idempotency keys are derived from content.
+- Blank tool arguments fall back to the wake's lane.
 
 ## 0.9.0 — 2026-07-30
 
 ### Changed (breaking)
 
-- `task-update` / `task_set_result` accept `state` only — legacy `status` alias removed (ZIG-1057).
+- `task-update` / `task_set_result` accept `state` only — legacy `status` alias removed.
 - Removed export `syncAggregateTaskViews`; read pending/collected/delegated via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`. Ctx aggregate mirrors stay empty.
 
 ## 0.4.0 — 2026-07-23
@@ -38,8 +38,8 @@
 
 ### Changed (breaking)
 
-- Removed legacy socket-frame aliases; wire frames use canonical names only (ZIG-913, ZIG-915).
-- Delivery-law: classify inbound messages from the `service` wire shape (ZIG-936).
+- Removed legacy socket-frame aliases; wire frames use canonical names only.
+- Delivery-law: classify inbound messages from the `service` wire shape.
 - Bumped `@ziggs-ai/api-client` to `^0.3.0`.
 
 ## 0.3.0 — 2026-07-22
@@ -50,7 +50,7 @@
 
 ## 0.2.0 — 2026-07-16
 
-### Added (ZIG-784)
+### Added
 
 - Public brain selection API: `ziggsBrain()`, `claudeBrain()`, and `Brain` interface (`tick()`).
 - `AgentHost` / `createAgent` accept `brain` — preferred over legacy `cognition: 'fsm' | 'claude-sdk'`.

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
@@ -41,13 +42,13 @@ export declare const DEFAULT_MODEL = "claude-haiku-4-5";
  */
 export type SessionResolver = (normalized: NormalizedEvent, ownAgentId: string) => string | null;
 /**
- * ZIG-975: one lane key per unit of work, derived the same way as inbox wakes.
+ * one lane key per unit of work, derived the same way as inbox wakes.
  *
  * Inbox deliveries key on `chatId` (DEFAULT_SESSION_RESOLVER). Bootstrap used to
  * prefer bare `agreementId`, which opened a second lane for the same task and
  * made the snapshot read treat the agreement id as a chat (`chatMissing: true`,
  * empty context). Prefer the origin chat when present; otherwise the agreement's
- * notification chat (`agrn-<agreementId>`), which is always linked after ZIG-966.
+ * notification chat (`agrn-<agreementId>`), which is always linked after.
  */
 export declare function laneSessionIdForTask(task: {
     originChatId?: string | null;
@@ -72,16 +73,22 @@ export interface AgentHostOptions {
     name?: string | null;
     /** Store-facing one-liner. See DefineAgentInput.description. */
     description?: string;
-    /** Claude-brain system prompt (ZIG-1080); falls back to `description`. */
+    /** Claude-brain system prompt; falls back to `description`. */
     systemPrompt?: string;
     specialization?: string | null;
     /**
-     * ZIG-1185 — strings compared exactly against a quest's `match` field.
+     * strings compared exactly against a quest's `match` field.
      * Miss → ack with zero LLM. Match → normal wake. `specialization` is also
      * checked when set.
      */
     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`.
@@ -96,7 +103,7 @@ export interface AgentHostOptions {
     /** Max agentic turns per Claude SDK wake. Default 30. */
     claudeMaxTurns?: number;
     /**
-     * ZIG-860: claude-sdk agents resume their transcript across wakes by default,
+     * claude-sdk agents resume their transcript across wakes by default,
      * so per-wake input grows monotonically on a long lane. When true, each wake
      * starts a fresh Claude session — the protocol is backend-authoritative (the
      * brain re-reads via context_snapshot / the wake event), so the
@@ -125,14 +132,14 @@ export interface AgentHostOptions {
     sessionStore?: SessionStore;
     /** Observability tap: called after every effect with the effect and its response. */
     effectTap?: (effect: import('./types.js').Effect, response: unknown) => void;
-    /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
+    /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape. */
     transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
     /**
      * Usage/cost tap: called once per settled tick with the tick's authoritative
      * token usage (result.metrics). This is the SINGLE source of truth for
      * usage/cost across every cognition — the FSM (llm-call + streamed reply +
      * tool-internal LLM) and the Claude brain (incl. cache tokens) both funnel
-     * their spend here (ZIG-813). effectTap / tool generations are structural
+     * their spend here. effectTap / tool generations are structural
      * tracing only and must NOT also carry billable usage, or cost double-counts.
      */
     metricsTap?: (info: {
@@ -142,14 +149,47 @@ export interface AgentHostOptions {
         cognition: string;
         metrics: import('./agent/Agent.js').TickOutput['metrics'];
     }) => void;
-    /** Production monitoring ingest (ZIG-360). Default on; set false to disable. */
+    /**
+     * 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;
     /**
-     * Pull inbox on every WS connect/reconnect (ZIG-454). Default true.
+     * Pull inbox on every WS connect/reconnect. Default true.
      * Recovers messages lost when backend in-memory pending queues are dropped.
      */
     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
@@ -167,7 +207,7 @@ export declare function warnOnShadowedPlatformTools(platformTools: ToolDefinitio
  * a transport (Ziggs WebSocket), and the lane router (per-session FIFO queue
  * + in-memory session state).
  *
- *   transport (WS)  →  handleMessage  →  agent.tick(... , eff)  →  ...
+ *   transport (WS)  →  handleMessage  →  agent.tick(.. , eff)  →  ..
  */
 export declare class AgentHost {
     options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
@@ -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;
@@ -208,7 +250,7 @@ export declare class AgentHost {
     /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
     handleMessage(text: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
-     * ZIG-1144 part 3 — an agreement lane outlives the agreement.
+     * part 3 — an agreement lane outlives the agreement.
      *
      * A lane named `agrn-<agreementId>` keeps its Claude session for the whole
      * engagement, so a trailing event after the deal ends pays for all of it: on
@@ -226,11 +268,11 @@ export declare class AgentHost {
      */
     private laneAgreementIsTerminal;
     /**
-     * ZIG-1153 — the trailing turn on work that is already reported.
+     * the trailing turn on work that is already reported.
      *
      * A lane session carries the whole engagement, so the LAST wake is the most
      * expensive one: on prod, the frame that followed a completed elicitation cost
-     * **158,733 tokens** with the session's input at 366,417 before ZIG-816 reset
+     * **158,733 tokens** with the session's input at 366,417 before reset
      * it, and produced nothing — the spec had been written and the task closed one
      * frame earlier.
      *
@@ -245,18 +287,56 @@ 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;
     connectAsync(_timeout?: number): Promise<this>;
     /**
-     * ZIG-1185 — plain string compare against {@link AgentHostOptions.questMatchTags}
+     * plain string compare against {@link AgentHostOptions.questMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
     private triageQuestDelivery;
     private _bootstrapAssignedActiveTasks;
-    /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
+    /** replay task-assigned for an existing active task (demo recovery). */
     wakeTaskAssignment(taskId: string): Promise<void>;
     disconnect(): void;
     /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */