@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/agent-api.d.ts

@@ -0,0 +1,452 @@
+/**
+ * The Agent API (docs/SPEC.md) as Effect Schemas: its objects, what a Caller sends, its errors and its
+ * limits. Imports only `effect`: it is the layer that keeps the harness away from its Callers, and the HTTP binding is
+ * built from the same schemas, so the two bindings cannot describe different APIs.
+ */
+import * as Schema from "effect/Schema";
+export type Json = Schema.Json;
+export declare const ModelRef: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly modelId: Schema.String;
+}>;
+export type ModelRef = typeof ModelRef.Type;
+export declare const ThinkingLevel: Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>;
+export type ThinkingLevel = typeof ThinkingLevel.Type;
+declare const Tokens_base: Schema.Opaque<Tokens, Schema.Struct<{
+    readonly inputTokens: Schema.Number;
+    readonly outputTokens: Schema.Number;
+    readonly cacheReadTokens: Schema.optionalKey<Schema.Number>;
+    readonly cacheWriteTokens: Schema.optionalKey<Schema.Number>;
+    readonly cost: Schema.optionalKey<Schema.Number>;
+}>, {}> & Omit<Schema.Struct<{
+    readonly inputTokens: Schema.Number;
+    readonly outputTokens: Schema.Number;
+    readonly cacheReadTokens: Schema.optionalKey<Schema.Number>;
+    readonly cacheWriteTokens: Schema.optionalKey<Schema.Number>;
+    readonly cost: Schema.optionalKey<Schema.Number>;
+}>, keyof Schema.Top>;
+export declare class Tokens extends Tokens_base {
+}
+declare const Usage_base: Schema.Opaque<Usage, Schema.Struct<{
+    readonly models: Schema.$Record<Schema.String, typeof Tokens>;
+    readonly tools: Schema.$Record<Schema.String, typeof Tokens>;
+}>, {}> & Omit<Schema.Struct<{
+    readonly models: Schema.$Record<Schema.String, typeof Tokens>;
+    readonly tools: Schema.$Record<Schema.String, typeof Tokens>;
+}>, keyof Schema.Top>;
+/** Spend by `provider/model` for model calls, and by tool name for what tools reported (§3). */
+export declare class Usage extends Usage_base {
+}
+declare const AgentInfo_base: Schema.Opaque<AgentInfo, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+    /** What a message may start with as `/<name>` (§5.1). */
+    readonly commands: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+    }>>;
+    /** The tools a session may enable. */
+    readonly tools: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+    }>>;
+    /** The models a session may name: those whose provider has a credential here. */
+    readonly models: Schema.$Array<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+        readonly name: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly defaultModel: Schema.optionalKey<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>;
+}>, {}> & Omit<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.optionalKey<Schema.String>;
+    /** What a message may start with as `/<name>` (§5.1). */
+    readonly commands: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+    }>>;
+    /** The tools a session may enable. */
+    readonly tools: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.optionalKey<Schema.String>;
+    }>>;
+    /** The models a session may name: those whose provider has a credential here. */
+    readonly models: Schema.$Array<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+        readonly name: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly defaultModel: Schema.optionalKey<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>;
+}>, keyof Schema.Top>;
+export declare class AgentInfo extends AgentInfo_base {
+}
+export declare const ContentPart: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"text">;
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"image">;
+    readonly mimeType: Schema.String;
+    readonly data: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"image">;
+    readonly mimeType: Schema.String;
+    readonly ref: Schema.String;
+}>]>;
+export type ContentPart = typeof ContentPart.Type;
+/** The shape of an error as data: in a failed message, and in a `stream_error`. */
+export declare const AgentErrorData: Schema.Struct<{
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+    /** Whether the same request may succeed if sent again. */
+    readonly retryable: Schema.Boolean;
+    readonly details: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type AgentErrorData = typeof AgentErrorData.Type;
+declare const AgentError_base: Schema.Class<AgentError, Schema.Struct<{
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+    /** Whether the same request may succeed if sent again. */
+    readonly retryable: Schema.Boolean;
+    readonly details: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, import("effect/Cause").YieldableError>;
+/** What every operation rejects with (§7). */
+export declare class AgentError extends AgentError_base {
+}
+export declare const SessionStatus: Schema.Literals<readonly ["idle", "running"]>;
+export type SessionStatus = typeof SessionStatus.Type;
+declare const Session_base: Schema.Opaque<Session, Schema.Struct<{
+    readonly model: Schema.optional<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>> | Schema.optionalKey<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>;
+    readonly thinkingLevel: Schema.optional<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>> | Schema.optionalKey<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>>;
+    readonly instructions: Schema.optional<Schema.String> | Schema.optionalKey<Schema.String>;
+    readonly tools: Schema.optional<Schema.$Array<Schema.String>> | Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly id: Schema.String;
+    readonly status: Schema.Codec<"idle" | "running" | (string & {}), string, never, never>;
+    /** The agent's reply being written, as written so far: present only while one is. */
+    readonly reply: Schema.optionalKey<Schema.Struct<{
+        readonly text: Schema.String;
+        readonly thinking: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly usage: typeof Usage;
+}>, {}> & Omit<Schema.Struct<{
+    readonly model: Schema.optional<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>> | Schema.optionalKey<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>;
+    readonly thinkingLevel: Schema.optional<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>> | Schema.optionalKey<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>>;
+    readonly instructions: Schema.optional<Schema.String> | Schema.optionalKey<Schema.String>;
+    readonly tools: Schema.optional<Schema.$Array<Schema.String>> | Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly id: Schema.String;
+    readonly status: Schema.Codec<"idle" | "running" | (string & {}), string, never, never>;
+    /** The agent's reply being written, as written so far: present only while one is. */
+    readonly reply: Schema.optionalKey<Schema.Struct<{
+        readonly text: Schema.String;
+        readonly thinking: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly usage: typeof Usage;
+}>, keyof Schema.Top>;
+export declare class Session extends Session_base {
+}
+/** A message's statuses: `queued` and `running` until it ends, then one of the four ends, which are all its ends. */
+export declare const MessageStatus: Schema.Literals<readonly ["queued", "running", "completed", "incomplete", "failed", "canceled"]>;
+export type MessageStatus = typeof MessageStatus.Type;
+declare const Message_base: Schema.Opaque<Message, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly idempotencyKey: Schema.optionalKey<Schema.String>;
+    readonly status: Schema.Codec<"canceled" | "completed" | "failed" | "incomplete" | "queued" | "running" | (string & {}), string, never, never>;
+    /** Its `user` entry, once the agent took it. */
+    readonly entryId: Schema.optionalKey<Schema.String>;
+    /** The `assistant` entry the agent stopped on for it: when `completed`, and when `incomplete`. */
+    readonly answer: Schema.optionalKey<Schema.Struct<{
+        readonly entryId: Schema.String;
+        readonly text: Schema.String;
+    }>>;
+    /** Why it `failed`. */
+    readonly error: Schema.optionalKey<Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+        /** Whether the same request may succeed if sent again. */
+        readonly retryable: Schema.Boolean;
+        readonly details: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>;
+}>, {}> & Omit<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly idempotencyKey: Schema.optionalKey<Schema.String>;
+    readonly status: Schema.Codec<"canceled" | "completed" | "failed" | "incomplete" | "queued" | "running" | (string & {}), string, never, never>;
+    /** Its `user` entry, once the agent took it. */
+    readonly entryId: Schema.optionalKey<Schema.String>;
+    /** The `assistant` entry the agent stopped on for it: when `completed`, and when `incomplete`. */
+    readonly answer: Schema.optionalKey<Schema.Struct<{
+        readonly entryId: Schema.String;
+        readonly text: Schema.String;
+    }>>;
+    /** Why it `failed`. */
+    readonly error: Schema.optionalKey<Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+        /** Whether the same request may succeed if sent again. */
+        readonly retryable: Schema.Boolean;
+        readonly details: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>;
+}>, keyof Schema.Top>;
+export declare class Message extends Message_base {
+}
+/** Whether a message has ended: its ends are a closed set, so any other status, known or not, has not (§7.1). */
+export declare const hasEnded: (message: Pick<Message, "status">) => boolean;
+declare const Entry_base: Schema.Opaque<Entry, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly timestamp: Schema.Number;
+    readonly kind: Schema.String;
+    readonly data: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, {}> & Omit<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly timestamp: Schema.Number;
+    readonly kind: Schema.String;
+    readonly data: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, keyof Schema.Top>;
+/**
+ * One durable record of a session's history. Its `data` by `kind`:
+ * - `user`: `{ content: ContentPart[], messageId? }`
+ * - `assistant`: `{ text, thinking?, toolCalls?: { id, name, args }[], stop?: "max_tokens" | "failed" | "aborted",
+ *   error?, usage }`
+ * - `tool_result`: `{ toolCallId, toolName, isError, content: ContentPart[] }`
+ * - `compaction`: `{ summary }`
+ */
+export declare class Entry extends Entry_base {
+}
+export interface Page<T> {
+    data: T[];
+    next?: string;
+    prev?: string;
+}
+export declare const SessionEvent: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"entry">;
+    readonly entry: typeof Entry;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"state">;
+    readonly session: typeof Session;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"delta">;
+    readonly channel: Schema.Literals<readonly ["text", "thinking"]>;
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"tool_started">;
+    readonly toolCallId: Schema.String;
+    readonly name: Schema.String;
+    readonly args: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"tool_progress">;
+    readonly toolCallId: Schema.String;
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"retrying">;
+    readonly attempt: Schema.Number;
+    readonly maxAttempts: Schema.Number;
+    readonly delayMs: Schema.Number;
+    readonly reason: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"done">;
+    readonly message: typeof Message;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"stream_error">;
+    readonly error: Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+        /** Whether the same request may succeed if sent again. */
+        readonly retryable: Schema.Boolean;
+        readonly details: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>;
+}>]>;
+export type SessionEvent = typeof SessionEvent.Type;
+export declare const MessageStreamEvent: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"message">;
+    readonly message: typeof Message;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"entry">;
+    readonly entry: typeof Entry;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"state">;
+    readonly session: typeof Session;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"delta">;
+    readonly channel: Schema.Literals<readonly ["text", "thinking"]>;
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"tool_started">;
+    readonly toolCallId: Schema.String;
+    readonly name: Schema.String;
+    readonly args: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"tool_progress">;
+    readonly toolCallId: Schema.String;
+    readonly text: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"retrying">;
+    readonly attempt: Schema.Number;
+    readonly maxAttempts: Schema.Number;
+    readonly delayMs: Schema.Number;
+    readonly reason: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"done">;
+    readonly message: typeof Message;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"stream_error">;
+    readonly error: Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+        /** Whether the same request may succeed if sent again. */
+        readonly retryable: Schema.Boolean;
+        readonly details: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>;
+}>]>;
+export type MessageStreamEvent = typeof MessageStreamEvent.Type;
+export declare const SessionSettings: Schema.Struct<{
+    model: Schema.optional<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>> | Schema.optionalKey<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>;
+    thinkingLevel: Schema.optional<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>> | Schema.optionalKey<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>>;
+    /** Text added at the end of the agent's system prompt for this session. */
+    instructions: Schema.optional<Schema.String> | Schema.optionalKey<Schema.String>;
+    /** The tools the session enables, each among `info().tools`. */
+    tools: Schema.optional<Schema.$Array<Schema.String>> | Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export type SessionSettings = typeof SessionSettings.Type;
+export declare const CreateSessionOptions: Schema.Struct<{
+    readonly model: Schema.optional<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>> | Schema.optionalKey<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>;
+    readonly thinkingLevel: Schema.optional<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>> | Schema.optionalKey<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>>;
+    readonly instructions: Schema.optional<Schema.String> | Schema.optionalKey<Schema.String>;
+    readonly tools: Schema.optional<Schema.$Array<Schema.String>> | Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly forkFrom: Schema.optional<Schema.Struct<{
+        readonly sessionId: Schema.String;
+        readonly entryId: Schema.optional<Schema.String>;
+    }>>;
+}>;
+export type CreateSessionOptions = typeof CreateSessionOptions.Type;
+/** `null` clears a field back to the deployment's. */
+export declare const SessionChanges: Schema.Struct<{
+    readonly model: Schema.optional<Schema.NullOr<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly modelId: Schema.String;
+    }>>>;
+    readonly thinkingLevel: Schema.optional<Schema.NullOr<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>>>;
+    readonly instructions: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly tools: Schema.optional<Schema.NullOr<Schema.$Array<Schema.String>>>;
+}>;
+export type SessionChanges = typeof SessionChanges.Type;
+export declare const ListOptions: Schema.Struct<{
+    readonly limit: Schema.optional<Schema.Int>;
+    readonly after: Schema.optional<Schema.String>;
+}>;
+export type ListOptions = typeof ListOptions.Type;
+export declare const EntriesOptions: Schema.Struct<{
+    readonly after: Schema.optional<Schema.String>;
+    readonly before: Schema.optional<Schema.String>;
+    readonly limit: Schema.optional<Schema.Int>;
+}>;
+export type EntriesOptions = typeof EntriesOptions.Type;
+export declare const IdempotencyKey: Schema.String;
+export declare const SendRequest: Schema.Struct<{
+    readonly sessionId: Schema.String;
+    /** A string is one text part. */
+    readonly content: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"text">;
+        readonly text: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"image">;
+        readonly mimeType: Schema.String;
+        readonly data: Schema.String;
+    }>]>>]>;
+    /** The Caller's key for this message, unique within the session (§5.2). */
+    readonly idempotencyKey: Schema.optional<Schema.String>;
+    /** What the message is when the session is busy with another (§5.3). Default: "queue". */
+    readonly whenBusy: Schema.optional<Schema.Literals<readonly ["queue", "steer", "reject"]>>;
+}>;
+export type SendRequest = typeof SendRequest.Type;
+/** In seconds: how long a call waits for a message to end before it answers with the message as it is then. */
+export declare const Wait: Schema.Number;
+/** A message, by its id or by the key it was sent with. */
+export declare const MessageKey: Schema.Union<readonly [Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly messageId: Schema.String;
+}>, Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly idempotencyKey: Schema.String;
+}>]>;
+export type MessageKey = typeof MessageKey.Type;
+export declare const CompactOptions: Schema.Struct<{
+    readonly instructions: Schema.optional<Schema.String>;
+}>;
+export type CompactOptions = typeof CompactOptions.Type;
+export interface WaitOptions {
+    wait?: number;
+    signal?: AbortSignal;
+}
+export interface Agent {
+    info(): Promise<AgentInfo>;
+    usage(): Promise<Usage>;
+    sessions: {
+        create(options?: CreateSessionOptions): Promise<Session>;
+        get(sessionId: string): Promise<Session>;
+        list(options?: ListOptions): Promise<Page<Session>>;
+        update(sessionId: string, changes: SessionChanges): Promise<Session>;
+        entries(sessionId: string, options?: EntriesOptions): Promise<Page<Entry>>;
+        events(sessionId: string, options?: {
+            after?: string;
+            signal?: AbortSignal;
+        }): AsyncIterable<SessionEvent>;
+        cancel(sessionId: string): Promise<{
+            stopped: string[];
+        }>;
+        compact(sessionId: string, options?: CompactOptions): Promise<void>;
+        attachment(sessionId: string, ref: string): Promise<{
+            mimeType: string;
+            data: Uint8Array;
+        }>;
+    };
+    messages: {
+        send(request: SendRequest, options?: WaitOptions): Promise<Message>;
+        stream(request: SendRequest, options?: {
+            signal?: AbortSignal;
+        }): AsyncIterable<MessageStreamEvent>;
+        get(key: MessageKey, options?: WaitOptions): Promise<Message>;
+    };
+}
+export type ErrorCode = "invalid_request" | "unauthorized" | "not_found" | "busy" | "missing_model" | "missing_tool" | "auth_required" | "model_error" | "unconfirmed" | "unavailable" | "internal";
+export declare const LIMITS: {
+    readonly queuedPerSession: 20;
+    readonly inFlightPerProcess: 100;
+    readonly pageDefault: 100;
+    readonly pageBytes: number;
+    /** The longest one HTTP request waits for a message; `connectAgent` asks again until its Caller's `wait` is met. */
+    readonly httpWaitSeconds: 60;
+};
+export declare function agentError(code: ErrorCode, message: string, details?: Json): AgentError;
+/** An error as data, the way a message's `error` and a `stream_error` carry it. */
+export declare function errorData(error: AgentErrorData): AgentErrorData;
+export {};

package/dist/agent-api.js

@@ -0,0 +1,201 @@
+/**
+ * The Agent API (docs/SPEC.md) as Effect Schemas: its objects, what a Caller sends, its errors and its
+ * limits. Imports only `effect`: it is the layer that keeps the harness away from its Callers, and the HTTP binding is
+ * built from the same schemas, so the two bindings cannot describe different APIs.
+ */
+import * as Schema from "effect/Schema";
+export const ModelRef = Schema.Struct({ provider: Schema.String, modelId: Schema.String });
+export const ThinkingLevel = Schema.Literals(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+export class Tokens extends Schema.Opaque()(Schema.Struct({
+    inputTokens: Schema.Number,
+    outputTokens: Schema.Number,
+    cacheReadTokens: Schema.optionalKey(Schema.Number),
+    cacheWriteTokens: Schema.optionalKey(Schema.Number),
+    cost: Schema.optionalKey(Schema.Number),
+})) {
+}
+/** Spend by `provider/model` for model calls, and by tool name for what tools reported (§3). */
+export class Usage extends Schema.Opaque()(Schema.Struct({
+    models: Schema.Record(Schema.String, Tokens),
+    tools: Schema.Record(Schema.String, Tokens),
+})) {
+}
+const Named = Schema.Struct({ name: Schema.String, description: Schema.optionalKey(Schema.String) });
+export class AgentInfo extends Schema.Opaque()(Schema.Struct({
+    name: Schema.String,
+    description: Schema.optionalKey(Schema.String),
+    /** What a message may start with as `/<name>` (§5.1). */
+    commands: Schema.Array(Named),
+    /** The tools a session may enable. */
+    tools: Schema.Array(Named),
+    /** The models a session may name: those whose provider has a credential here. */
+    models: Schema.Array(Schema.Struct({ provider: Schema.String, modelId: Schema.String, name: Schema.optionalKey(Schema.String) })),
+    defaultModel: Schema.optionalKey(ModelRef),
+})) {
+}
+const TextPart = Schema.Struct({ type: Schema.Literal("text"), text: Schema.String });
+/** An image in a message carries its bytes, base64. */
+const ImagePart = Schema.Struct({ type: Schema.Literal("image"), mimeType: Schema.String, data: Schema.String });
+/** An image in an entry is a ref, read with `sessions.attachment`. */
+const ImageRef = Schema.Struct({ type: Schema.Literal("image"), mimeType: Schema.String, ref: Schema.String });
+export const ContentPart = Schema.Union([TextPart, ImagePart, ImageRef]);
+/** The shape of an error as data: in a failed message, and in a `stream_error`. */
+export const AgentErrorData = Schema.Struct({
+    code: Schema.String,
+    message: Schema.String,
+    /** Whether the same request may succeed if sent again. */
+    retryable: Schema.Boolean,
+    details: Schema.optionalKey(Schema.Json),
+});
+/** What every operation rejects with (§7). */
+export class AgentError extends Schema.Error("AgentError")(AgentErrorData) {
+}
+/**
+ * A session's settings. An object the Agent answers with leaves out what it does not name (`optionalKey`); what a Caller
+ * sends may also give a field as `undefined`, which is the same as leaving it out (`optional`), as a TypeScript Caller
+ * without `exactOptionalPropertyTypes` writes it.
+ */
+const settingsFields = (optional) => ({
+    model: optional(ModelRef),
+    thinkingLevel: optional(ThinkingLevel),
+    /** Text added at the end of the agent's system prompt for this session. */
+    instructions: optional(Schema.String),
+    /** The tools the session enables, each among `info().tools`. */
+    tools: optional(Schema.Array(Schema.String)),
+});
+/**
+ * A status as a field: the values this version defines, and any other, since a later version may add one and a Caller
+ * reads it the way §7.1 says (an unknown session status is busy, an unknown message status has not ended).
+ */
+const open = (known) => 
+// As a type, the known values and any string, so an editor still offers them (`string & {}` does not absorb them).
+Schema.Union([known, Schema.String]);
+export const SessionStatus = Schema.Literals(["idle", "running"]);
+export class Session extends Schema.Opaque()(Schema.Struct({
+    id: Schema.String,
+    status: open(SessionStatus),
+    ...settingsFields(Schema.optionalKey),
+    /** The agent's reply being written, as written so far: present only while one is. */
+    reply: Schema.optionalKey(Schema.Struct({ text: Schema.String, thinking: Schema.optionalKey(Schema.String) })),
+    usage: Usage,
+})) {
+}
+/** A message's statuses: `queued` and `running` until it ends, then one of the four ends, which are all its ends. */
+export const MessageStatus = Schema.Literals(["queued", "running", "completed", "incomplete", "failed", "canceled"]);
+export class Message extends Schema.Opaque()(Schema.Struct({
+    id: Schema.String,
+    sessionId: Schema.String,
+    idempotencyKey: Schema.optionalKey(Schema.String),
+    status: open(MessageStatus),
+    /** Its `user` entry, once the agent took it. */
+    entryId: Schema.optionalKey(Schema.String),
+    /** The `assistant` entry the agent stopped on for it: when `completed`, and when `incomplete`. */
+    answer: Schema.optionalKey(Schema.Struct({ entryId: Schema.String, text: Schema.String })),
+    /** Why it `failed`. */
+    error: Schema.optionalKey(AgentErrorData),
+})) {
+}
+const ENDS = new Set(["completed", "incomplete", "failed", "canceled"]);
+/** Whether a message has ended: its ends are a closed set, so any other status, known or not, has not (§7.1). */
+export const hasEnded = (message) => ENDS.has(message.status);
+/**
+ * One durable record of a session's history. Its `data` by `kind`:
+ * - `user`: `{ content: ContentPart[], messageId? }`
+ * - `assistant`: `{ text, thinking?, toolCalls?: { id, name, args }[], stop?: "max_tokens" | "failed" | "aborted",
+ *   error?, usage }`
+ * - `tool_result`: `{ toolCallId, toolName, isError, content: ContentPart[] }`
+ * - `compaction`: `{ summary }`
+ */
+export class Entry extends Schema.Opaque()(Schema.Struct({ id: Schema.String, timestamp: Schema.Number, kind: Schema.String, data: Schema.Json })) {
+}
+export const SessionEvent = Schema.Union([
+    Schema.Struct({ type: Schema.Literal("entry"), entry: Entry }),
+    Schema.Struct({ type: Schema.Literal("state"), session: Session }),
+    Schema.Struct({ type: Schema.Literal("delta"), channel: Schema.Literals(["text", "thinking"]), text: Schema.String }),
+    Schema.Struct({
+        type: Schema.Literal("tool_started"),
+        toolCallId: Schema.String,
+        name: Schema.String,
+        args: Schema.Json,
+    }),
+    Schema.Struct({ type: Schema.Literal("tool_progress"), toolCallId: Schema.String, text: Schema.String }),
+    Schema.Struct({
+        type: Schema.Literal("retrying"),
+        attempt: Schema.Number,
+        maxAttempts: Schema.Number,
+        delayMs: Schema.Number,
+        reason: Schema.String,
+    }),
+    Schema.Struct({ type: Schema.Literal("done"), message: Message }),
+    Schema.Struct({ type: Schema.Literal("stream_error"), error: AgentErrorData }),
+]);
+export const MessageStreamEvent = Schema.Union([
+    Schema.Struct({ type: Schema.Literal("message"), message: Message }),
+    ...SessionEvent.members,
+]);
+const Limit = (max) => Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: max }));
+const Seconds = Schema.Number.check(Schema.isGreaterThanOrEqualTo(0));
+export const SessionSettings = Schema.Struct(settingsFields(Schema.optional));
+export const CreateSessionOptions = Schema.Struct({
+    ...settingsFields(Schema.optional),
+    forkFrom: Schema.optional(Schema.Struct({ sessionId: Schema.String, entryId: Schema.optional(Schema.String) })),
+});
+/** `null` clears a field back to the deployment's. */
+export const SessionChanges = Schema.Struct({
+    model: Schema.optional(Schema.NullOr(ModelRef)),
+    thinkingLevel: Schema.optional(Schema.NullOr(ThinkingLevel)),
+    instructions: Schema.optional(Schema.NullOr(Schema.String)),
+    tools: Schema.optional(Schema.NullOr(Schema.Array(Schema.String))),
+});
+export const ListOptions = Schema.Struct({
+    limit: Schema.optional(Limit(500)),
+    after: Schema.optional(Schema.String),
+});
+export const EntriesOptions = Schema.Struct({
+    after: Schema.optional(Schema.String),
+    before: Schema.optional(Schema.String),
+    limit: Schema.optional(Limit(500)),
+});
+export const IdempotencyKey = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+export const SendRequest = Schema.Struct({
+    sessionId: Schema.String,
+    /** A string is one text part. */
+    content: Schema.Union([
+        Schema.String,
+        Schema.Array(Schema.Union([TextPart, ImagePart])).check(Schema.isMinLength(1)),
+    ]),
+    /** The Caller's key for this message, unique within the session (§5.2). */
+    idempotencyKey: Schema.optional(IdempotencyKey),
+    /** What the message is when the session is busy with another (§5.3). Default: "queue". */
+    whenBusy: Schema.optional(Schema.Literals(["queue", "steer", "reject"])),
+});
+/** In seconds: how long a call waits for a message to end before it answers with the message as it is then. */
+export const Wait = Seconds;
+/** A message, by its id or by the key it was sent with. */
+export const MessageKey = Schema.Union([
+    Schema.Struct({ sessionId: Schema.String, messageId: Schema.String }),
+    Schema.Struct({ sessionId: Schema.String, idempotencyKey: IdempotencyKey }),
+]);
+export const CompactOptions = Schema.Struct({ instructions: Schema.optional(Schema.String) });
+export const LIMITS = {
+    queuedPerSession: 20,
+    inFlightPerProcess: 100,
+    pageDefault: 100,
+    pageBytes: 4 << 20,
+    /** The longest one HTTP request waits for a message; `connectAgent` asks again until its Caller's `wait` is met. */
+    httpWaitSeconds: 60,
+};
+const RETRYABLE_CODES = new Set(["busy", "unavailable"]);
+export function agentError(code, message, details) {
+    return new AgentError({
+        code,
+        message,
+        retryable: RETRYABLE_CODES.has(code),
+        ...(details === undefined ? {} : { details }),
+    });
+}
+/** An error as data, the way a message's `error` and a `stream_error` carry it. */
+export function errorData(error) {
+    const { code, message, retryable, details } = error;
+    return { code, message, retryable, ...(details === undefined ? {} : { details }) };
+}

package/dist/answer-text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The text of the agent's replies in one message's stream, as a renderer shows it: the live deltas, and what an
+ * `assistant` entry says that no delta did. Deltas are live only (SPEC.md §6.1), so work that ended before its
+ * stream subscribed, or that the stream fell behind on, has its text in the entry alone.
+ */
+import type { SessionEvent } from "./agent-api.ts";
+/** Feed it a message's stream; it answers the text each event adds. */
+export declare function answerText(): (event: SessionEvent) => string;