@1kbirds/chidori 3.6.0 → 3.7.0

package/dist/agent.js

@@ -44,3 +44,31 @@ export function run(handler) {
     throw new Error("run() is only available inside the chidori runtime; this import is " +
         "replaced when an agent runs under chidori.");
 }
+/**
+ * Wrap a function into a {@link ToolHandle} by attaching its documented
+ * signature — a `name`, a `description`, and a JSON-schema for its
+ * `parameters`. That signature is all the model needs to call the function;
+ * the function itself is just code. No `tools/` directory, no registry —
+ * import (or define inline) the handle like any other value. `parameters`
+ * defaults to an empty object schema; `description` to `""`. Inside the
+ * runtime this import is replaced by the live implementation, exactly like
+ * `run` and `chidori`.
+ *
+ * ```ts
+ * import { chidori, run, defineTool } from "chidori:agent";
+ *
+ * const search = defineTool({
+ *   name: "search",
+ *   description: "Search the corpus.",
+ *   parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },
+ *   run: async ({ q }) => (await fetch(BASE + q)).json(),
+ * });
+ *
+ * run(async () => chidori.prompt("find chidori", { tools: [search], maxTurns: 6 }));
+ * ```
+ */
+export function defineTool(def) {
+    void def;
+    throw new Error("defineTool() is only available inside the chidori runtime; this import " +
+        "is replaced when an agent runs under chidori.");
+}

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * dependencies; uses the global `fetch` available in Node 18+ and browsers.
  */
 import type { SignalSender } from "./agent.js";
-export type { AgentFunction, AgentJson, CacheTtl, Chidori, CompactOptions, Context, Conversation, ConversationLoopOptions, ConversationOptions, ConversationTurn, DatePolicy, InputOptions, JsonObject, JsonSchema, LlmResponseJson, MapSetSnapshotPolicy, MemoryAction, ParallelOptions, PromptOptions, PromptStreamType, RandomPolicy, RetryOptions, RuntimePolicyConfig, Signal, SignalOptions, SignalSender, SignalTimeout, ToolDefinition, ToolFunction, TryCallResult, TypeScriptImportPolicy, WorkspaceEntry, WorkspaceFileStatus, WorkspaceHost, WorkspaceListOptions, WorkspaceWriteOptions, } from "./agent.js";
+export type { ActorHandle, ActorMessage, ActorOutcome, ActorOutcomeStatus, ActorRestartStrategy, Actors, ActorStatus, ActorStillRunning, AgentFunction, AgentJson, AgentOutput, AppData, BranchOptions, BranchOutcome, BranchStatus, BranchVariant, CacheTtl, Chidori, ChidoriUtil, CompactOptions, Context, Conversation, ConversationLoopOptions, ConversationOptions, ConversationTurn, DatePolicy, DetachedAgentHandle, DetachedAgentOutcome, DetachedAgents, DetachedAgentStatus, InputOptions, JoinActorOptions, JsonObject, JsonSchema, LlmResponseJson, LogFields, MapSetSnapshotPolicy, MemoryStore, ParallelOptions, PromptOptions, PromptStreamType, RandomPolicy, ReceiveOptions, RetryOptions, RuntimePolicyConfig, Signal, SignalOptions, SignalSender, SignalTimeout, SpawnActorOptions, SpawnAgentOptions, ToolDefinition, ToolFunction, TryCallResult, TypeScriptImportPolicy, WorkspaceEntry, WorkspaceFileStatus, WorkspaceHost, WorkspaceListOptions, WorkspaceWriteOptions, } from "./agent.js";
 export { chidori, run } from "./agent.js";
 /** JSON-serialisable value — what agents produce as output and accept as input. */
 export type Json = null | boolean | number | string | Json[] | {
@@ -168,7 +168,7 @@ export declare class Session {
     pendingSignalName: string | null;
     /**
      * The full awaited name set when paused on a signal listen point: `[name]`
-     * for `chidori.signal(name)`, the listen set for `chidori.signalAny(names)`.
+     * for `chidori.signal(name)`, the listen set for the fan-in `chidori.signal(names)`.
      * Empty for non-signal states.
      */
     pendingSignalNames: string[];
@@ -178,6 +178,18 @@ export declare class Session {
      * when it passes. `null` when the pause has no timeout.
      */
     pendingSignalDeadline: string | null;
+    /**
+     * The artifact under review for an `input()` pause created with
+     * `{ details }` (a draft, a diff) — surface it so a human never approves
+     * blind. `null` when the pause carries no details.
+     */
+    pendingDetails: string | null;
+    /**
+     * The durable run directory id (`.chidori/runs/<run_id>`) this session
+     * journals into. Deliberately distinct from the session id: `chidori
+     * resume <agent.ts> <run_id>` and `chidori trace <run_id>` take THIS id.
+     */
+    runId: string | null;
     constructor(id: string, status: SessionStatus, input: Json, output?: Json | null, error?: string | null, callLog?: CallRecord[], pendingPrompt?: string | null, client?: AgentClient | null, snapshotManifest?: SnapshotManifest | null, 
     /**
      * When the run is `paused` at a `chidori.signal(name)` listen point, the
@@ -187,7 +199,7 @@ export declare class Session {
     pendingSignalName?: string | null, 
     /**
      * The full awaited name set when paused on a signal listen point: `[name]`
-     * for `chidori.signal(name)`, the listen set for `chidori.signalAny(names)`.
+     * for `chidori.signal(name)`, the listen set for the fan-in `chidori.signal(names)`.
      * Empty for non-signal states.
      */
     pendingSignalNames?: string[], 
@@ -196,7 +208,19 @@ export declare class Session {
      * `timeoutMs`; the server resolves the pause with the timeout sentinel
      * when it passes. `null` when the pause has no timeout.
      */
-    pendingSignalDeadline?: string | null);
+    pendingSignalDeadline?: string | null, 
+    /**
+     * The artifact under review for an `input()` pause created with
+     * `{ details }` (a draft, a diff) — surface it so a human never approves
+     * blind. `null` when the pause carries no details.
+     */
+    pendingDetails?: string | null, 
+    /**
+     * The durable run directory id (`.chidori/runs/<run_id>`) this session
+     * journals into. Deliberately distinct from the session id: `chidori
+     * resume <agent.ts> <run_id>` and `chidori trace <run_id>` take THIS id.
+     */
+    runId?: string | null);
     get ok(): boolean;
     /**
      * Fetch the full call log from the server (if not already loaded) and
@@ -230,7 +254,7 @@ export type StreamEvent = {
     error?: string | null;
 } | {
     /**
-     * The streamed run paused at a `signal()` / `signalAny()` listen point
+     * The streamed run paused at a `signal()` listen point
      * and stays live: the worker keeps supervising, and a delivered signal
      * (or the `timeoutMs` deadline) resumes it in-process — further events
      * follow on the same stream. Deliver with `client.signal`.
@@ -249,6 +273,86 @@ export type StreamEvent = {
     output?: Json;
     error?: string;
 };
+/** Base class for every error the SDK throws. `catch (e) { if (e instanceof
+ * AgentClientError) ... }` covers HTTP failures, timeouts, and connection
+ * errors alike. */
+export declare class AgentClientError extends Error {
+}
+/**
+ * A non-2xx HTTP response. Carries the parsed `status` so callers can
+ * distinguish the server's documented semantics — e.g. for `client.signal`:
+ * 400 (empty name), 404 (unknown session), 409 (terminal run) — instead of
+ * string-matching the message.
+ */
+export declare class HttpError extends AgentClientError {
+    /** HTTP method of the failed request. */
+    readonly method: string;
+    /** Request path relative to the base URL. */
+    readonly path: string;
+    /** HTTP status code (400, 404, 409, 500, ...). */
+    readonly status: number;
+    /** Raw response body text (may be empty). */
+    readonly body: string;
+    /** The server's `error` field, when the body was `{ "error": ... }`. */
+    readonly detail: string | null;
+    constructor(
+    /** HTTP method of the failed request. */
+    method: string, 
+    /** Request path relative to the base URL. */
+    path: string, 
+    /** HTTP status code (400, 404, 409, 500, ...). */
+    status: number, 
+    /** Raw response body text (may be empty). */
+    body: string, 
+    /** The server's `error` field, when the body was `{ "error": ... }`. */
+    detail?: string | null);
+    static fromResponse(method: string, path: string, resp: Response): Promise<HttpError>;
+}
+/** The request exceeded the client's `timeoutMs` without completing. */
+export declare class TimeoutError extends AgentClientError {
+    readonly method: string;
+    readonly path: string;
+    readonly timeoutMs: number;
+    constructor(method: string, path: string, timeoutMs: number);
+}
+/** The request never produced an HTTP response (refused, reset, DNS, ...). */
+export declare class ConnectionError extends AgentClientError {
+    readonly method: string;
+    readonly path: string;
+    constructor(method: string, path: string, cause: unknown);
+}
+export interface AgentClientOptions {
+    /**
+     * Bearer token for a server running with `CHIDORI_API_KEY` set (the
+     * production posture — see docs/deployment.md). Sent as
+     * `Authorization: Bearer <apiKey>` on every request, including `stream()`.
+     * Omit against an unauthenticated loopback server.
+     */
+    apiKey?: string;
+    /**
+     * Extra headers merged into every request (after `apiKey`, so an explicit
+     * `Authorization` entry here wins). Escape hatch for proxies and custom
+     * auth schemes the `apiKey` option doesn't cover.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Per-request timeout in milliseconds; `0` disables it. Defaults to
+     * 300 000 (5 minutes) — generous because `run()` executes the whole agent
+     * before responding, but finite so a hung server surfaces as a
+     * `TimeoutError` instead of blocking forever. For `stream()` the timeout
+     * covers connection establishment only, never an open event stream.
+     */
+    timeoutMs?: number;
+    /**
+     * How many times to retry **idempotent GET requests** after a connection
+     * error, timeout, or retryable status (429/502/503/504). Defaults to 2.
+     * POST requests are never retried — `run`/`resume`/`signal` are not
+     * idempotent, and a blind retry could execute an agent twice.
+     */
+    retries?: number;
+    /** Base delay between retries in milliseconds, doubling per attempt (default 250). */
+    retryDelayMs?: number;
+}
 /**
  * HTTP client for an `chidori serve` instance.
  *
@@ -260,10 +364,19 @@ export type StreamEvent = {
  * const cp = await session.checkpoint();
  * const replayed = await client.replay(cp);  // zero LLM calls
  * ```
+ *
+ * Failures throw typed errors (all extending {@link AgentClientError}):
+ * {@link HttpError} with a `.status` for non-2xx responses,
+ * {@link TimeoutError} after `timeoutMs`, {@link ConnectionError} when no
+ * response arrived at all.
  */
 export declare class AgentClient {
     readonly baseUrl: string;
-    constructor(baseUrl?: string);
+    readonly timeoutMs: number;
+    readonly retries: number;
+    readonly retryDelayMs: number;
+    private readonly baseHeaders;
+    constructor(baseUrl?: string, options?: AgentClientOptions);
     health(): Promise<Json>;
     /**
      * Create a new session and run the agent with the given input.
@@ -323,10 +436,21 @@ export declare class AgentClient {
      * events (`prompt_start`, `prompt_delta`, `prompt_end`), then a final
      * `done` event. Prompt events include `prompt_type` so UIs can filter
      * progress streams separately from final-answer streams.
+     *
+     * `options.policyProfile` mirrors `run()`: a built-in profile layered on
+     * the server policy with stricter-wins semantics for this session.
      */
-    stream(input: Json): AsyncGenerator<StreamEvent, void, void>;
+    stream(input: Json, options?: {
+        policyProfile?: PolicyProfile;
+    }): AsyncGenerator<StreamEvent, void, void>;
     private sessionFrom;
     private getJSON;
     private postJSON;
     private postJSONWithStatus;
+    /**
+     * One HTTP exchange with timeout and (for idempotent requests) retries.
+     * Resolves with a 2xx `Response`; throws {@link HttpError},
+     * {@link TimeoutError}, or {@link ConnectionError} otherwise.
+     */
+    private request;
 }

package/dist/index.js

@@ -59,6 +59,8 @@ export class Session {
     pendingSignalName;
     pendingSignalNames;
     pendingSignalDeadline;
+    pendingDetails;
+    runId;
     constructor(id, status, input, output = null, error = null, callLog = [], pendingPrompt = null, client = null, snapshotManifest = null, 
     /**
      * When the run is `paused` at a `chidori.signal(name)` listen point, the
@@ -68,7 +70,7 @@ export class Session {
     pendingSignalName = null, 
     /**
      * The full awaited name set when paused on a signal listen point: `[name]`
-     * for `chidori.signal(name)`, the listen set for `chidori.signalAny(names)`.
+     * for `chidori.signal(name)`, the listen set for the fan-in `chidori.signal(names)`.
      * Empty for non-signal states.
      */
     pendingSignalNames = [], 
@@ -77,7 +79,19 @@ export class Session {
      * `timeoutMs`; the server resolves the pause with the timeout sentinel
      * when it passes. `null` when the pause has no timeout.
      */
-    pendingSignalDeadline = null) {
+    pendingSignalDeadline = null, 
+    /**
+     * The artifact under review for an `input()` pause created with
+     * `{ details }` (a draft, a diff) — surface it so a human never approves
+     * blind. `null` when the pause carries no details.
+     */
+    pendingDetails = null, 
+    /**
+     * The durable run directory id (`.chidori/runs/<run_id>`) this session
+     * journals into. Deliberately distinct from the session id: `chidori
+     * resume <agent.ts> <run_id>` and `chidori trace <run_id>` take THIS id.
+     */
+    runId = null) {
         this.id = id;
         this.status = status;
         this.input = input;
@@ -90,6 +104,8 @@ export class Session {
         this.pendingSignalName = pendingSignalName;
         this.pendingSignalNames = pendingSignalNames;
         this.pendingSignalDeadline = pendingSignalDeadline;
+        this.pendingDetails = pendingDetails;
+        this.runId = runId;
     }
     get ok() {
         return this.status === "completed";
@@ -115,6 +131,84 @@ export class Session {
         return this.client.replay(cp);
     }
 }
+/** Base class for every error the SDK throws. `catch (e) { if (e instanceof
+ * AgentClientError) ... }` covers HTTP failures, timeouts, and connection
+ * errors alike. */
+export class AgentClientError extends Error {
+}
+/**
+ * A non-2xx HTTP response. Carries the parsed `status` so callers can
+ * distinguish the server's documented semantics — e.g. for `client.signal`:
+ * 400 (empty name), 404 (unknown session), 409 (terminal run) — instead of
+ * string-matching the message.
+ */
+export class HttpError extends AgentClientError {
+    method;
+    path;
+    status;
+    body;
+    detail;
+    constructor(
+    /** HTTP method of the failed request. */
+    method, 
+    /** Request path relative to the base URL. */
+    path, 
+    /** HTTP status code (400, 404, 409, 500, ...). */
+    status, 
+    /** Raw response body text (may be empty). */
+    body, 
+    /** The server's `error` field, when the body was `{ "error": ... }`. */
+    detail = null) {
+        super(`${method} ${path} failed: HTTP ${status}${detail || body ? `: ${detail ?? body}` : ""}`);
+        this.method = method;
+        this.path = path;
+        this.status = status;
+        this.body = body;
+        this.detail = detail;
+        this.name = "HttpError";
+    }
+    static async fromResponse(method, path, resp) {
+        const body = await resp.text().catch(() => "");
+        let detail = null;
+        try {
+            const parsed = JSON.parse(body);
+            if (typeof parsed.error === "string")
+                detail = parsed.error;
+        }
+        catch {
+            // not JSON — leave detail null
+        }
+        return new HttpError(method, path, resp.status, body, detail);
+    }
+}
+/** The request exceeded the client's `timeoutMs` without completing. */
+export class TimeoutError extends AgentClientError {
+    method;
+    path;
+    timeoutMs;
+    constructor(method, path, timeoutMs) {
+        super(`${method} ${path} timed out after ${timeoutMs}ms`);
+        this.method = method;
+        this.path = path;
+        this.timeoutMs = timeoutMs;
+        this.name = "TimeoutError";
+    }
+}
+/** The request never produced an HTTP response (refused, reset, DNS, ...). */
+export class ConnectionError extends AgentClientError {
+    method;
+    path;
+    constructor(method, path, cause) {
+        super(`${method} ${path} failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+            cause,
+        });
+        this.method = method;
+        this.path = path;
+        this.name = "ConnectionError";
+    }
+}
+/** Response statuses worth retrying on idempotent requests. */
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
 /**
  * HTTP client for an `chidori serve` instance.
  *
@@ -126,11 +220,27 @@ export class Session {
  * const cp = await session.checkpoint();
  * const replayed = await client.replay(cp);  // zero LLM calls
  * ```
+ *
+ * Failures throw typed errors (all extending {@link AgentClientError}):
+ * {@link HttpError} with a `.status` for non-2xx responses,
+ * {@link TimeoutError} after `timeoutMs`, {@link ConnectionError} when no
+ * response arrived at all.
  */
 export class AgentClient {
     baseUrl;
-    constructor(baseUrl = "http://localhost:8080") {
+    timeoutMs;
+    retries;
+    retryDelayMs;
+    baseHeaders;
+    constructor(baseUrl = "http://localhost:8080", options = {}) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? 300_000;
+        this.retries = options.retries ?? 2;
+        this.retryDelayMs = options.retryDelayMs ?? 250;
+        this.baseHeaders = {
+            ...(options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {}),
+            ...(options.headers ?? {}),
+        };
     }
     async health() {
         return (await this.getJSON("/health"));
@@ -224,15 +334,44 @@ export class AgentClient {
      * events (`prompt_start`, `prompt_delta`, `prompt_end`), then a final
      * `done` event. Prompt events include `prompt_type` so UIs can filter
      * progress streams separately from final-answer streams.
+     *
+     * `options.policyProfile` mirrors `run()`: a built-in profile layered on
+     * the server policy with stricter-wins semantics for this session.
      */
-    async *stream(input) {
-        const resp = await fetch(`${this.baseUrl}/sessions/stream`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json", Accept: "text/event-stream" },
-            body: JSON.stringify({ input }),
-        });
+    async *stream(input, options) {
+        // The timeout covers connection establishment (until response headers
+        // arrive), not the open event stream — a healthy run may stream for a
+        // long time between events.
+        const controller = new AbortController();
+        const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : null;
+        const body = { input };
+        if (options?.policyProfile) {
+            body.policy_profile = options.policyProfile;
+        }
+        let resp;
+        try {
+            resp = await fetch(`${this.baseUrl}/sessions/stream`, {
+                method: "POST",
+                headers: {
+                    ...this.baseHeaders,
+                    "Content-Type": "application/json",
+                    Accept: "text/event-stream",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw controller.signal.aborted
+                ? new TimeoutError("POST", "/sessions/stream", this.timeoutMs)
+                : new ConnectionError("POST", "/sessions/stream", err);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
         if (!resp.ok || !resp.body) {
-            throw new Error(`stream request failed: ${resp.status}`);
+            throw await HttpError.fromResponse("POST", "/sessions/stream", resp);
         }
         // Minimal SSE parser — just enough for the events our server emits.
         const reader = resp.body.getReader();
@@ -255,31 +394,75 @@ export class AgentClient {
     }
     // -- internals ----------------------------------------------------------
     sessionFrom(data, input) {
-        return new Session(data.id, data.status ?? "failed", input, data.output ?? null, data.error ?? null, data.call_log ?? [], data.pending_prompt ?? null, this, data.snapshot_manifest ?? null, data.pending_signal_name ?? null, data.pending_signal_names ?? [], data.pending_signal_deadline ?? null);
+        return new Session(data.id, data.status ?? "failed", input, data.output ?? null, data.error ?? null, data.call_log ?? [], data.pending_prompt ?? null, this, data.snapshot_manifest ?? null, data.pending_signal_name ?? null, data.pending_signal_names ?? [], data.pending_signal_deadline ?? null, data.pending_details ?? null, data.run_id ?? null);
     }
     async getJSON(path) {
-        const resp = await fetch(this.baseUrl + path);
-        if (!resp.ok)
-            throw await httpError(resp);
+        // GETs are idempotent: retry connection failures, timeouts, and
+        // retryable statuses with exponential backoff.
+        const resp = await this.request("GET", path, undefined, this.retries);
         return await resp.json();
     }
     async postJSON(path, body) {
         return (await this.postJSONWithStatus(path, body)).data;
     }
     async postJSONWithStatus(path, body) {
-        const resp = await fetch(this.baseUrl + path, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(body),
-        });
-        if (!resp.ok)
-            throw await httpError(resp);
+        // POSTs are never retried: run/resume/signal are not idempotent.
+        const resp = await this.request("POST", path, body, 0);
         return { status: resp.status, data: (await resp.json()) };
     }
+    /**
+     * One HTTP exchange with timeout and (for idempotent requests) retries.
+     * Resolves with a 2xx `Response`; throws {@link HttpError},
+     * {@link TimeoutError}, or {@link ConnectionError} otherwise.
+     */
+    async request(method, path, body, retries) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            if (attempt > 0) {
+                await sleep(this.retryDelayMs * 2 ** (attempt - 1));
+            }
+            const controller = new AbortController();
+            const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : null;
+            try {
+                let resp;
+                try {
+                    resp = await fetch(this.baseUrl + path, {
+                        method,
+                        signal: controller.signal,
+                        headers: body !== undefined
+                            ? { ...this.baseHeaders, "Content-Type": "application/json" }
+                            : this.baseHeaders,
+                        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                    });
+                }
+                catch (err) {
+                    throw controller.signal.aborted
+                        ? new TimeoutError(method, path, this.timeoutMs)
+                        : new ConnectionError(method, path, err);
+                }
+                if (!resp.ok)
+                    throw await HttpError.fromResponse(method, path, resp);
+                return resp;
+            }
+            catch (err) {
+                const retryable = err instanceof TimeoutError ||
+                    err instanceof ConnectionError ||
+                    (err instanceof HttpError && RETRYABLE_STATUS.has(err.status));
+                if (!retryable || attempt === retries)
+                    throw err;
+                lastError = err;
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        }
+        // Unreachable: the loop either returns or throws on the last attempt.
+        throw lastError ?? new ConnectionError(method, path, "retries exhausted");
+    }
 }
-async function httpError(resp) {
-    const text = await resp.text().catch(() => "");
-    return new Error(`HTTP ${resp.status}: ${text}`);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function parseSseFrame(frame) {
     let event = "message";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1kbirds/chidori",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "TypeScript SDK for the Chidori agent framework — HTTP client plus agent authoring types.",
   "keywords": ["ai", "agents", "typescript", "llm", "replay"],
   "publishConfig": { "access": "public" },
@@ -27,6 +27,7 @@
   "files": ["dist", "src", "README.md"],
   "scripts": {
     "build": "tsc",
+    "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
     "pretest": "tsc",
     "test": "node --test test/*.test.mjs"