ruicode 0.0.0-stage → 0.67.1

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+import type { components } from "./wire.ts";
+type Schemas = components["schemas"];
+type Reply = Schemas[Extract<keyof Schemas, `${string}Reply`>];
+type Answer<T> = T extends {
+    answer: infer A;
+} ? A : never;
+type Code<T> = T extends {
+    code: infer C extends string;
+} ? C : never;
+type Status<T> = T extends {
+    status: infer S extends string;
+} ? S : never;
+export type RequestAnswer = Answer<Reply>;
+export type RequestRejectionCode = Code<RequestAnswer>;
+/** HTTP ErrorReply deliberately accepts codes beyond the command rejection enums. */
+export type RequestErrorCode = RequestRejectionCode | Schemas["ErrorReply"]["code"];
+type RequestErrorType = Schemas["ErrorReply"]["type"] | Status<Extract<RequestAnswer, {
+    code: string;
+}>>;
+type StartErrorCode = Schemas["StartError"]["rui_start_error"]["code"];
+/** Rui rejected one request. `code` is the Host's rejection code; `message` preserves advisory detail when provided. */
+export declare class RuiRequestError extends Error {
+    readonly name = "RuiRequestError";
+    readonly code: RequestErrorCode;
+    /** The Host's error class, such as `invocation_error` or `busy`. */
+    readonly type: RequestErrorType;
+    constructor(type: RequestErrorType, code: RequestErrorCode, message?: string | null);
+}
+/** Rui refused to open. `code` is one of the refusal codes at open (D136). */
+export declare class RuiStartError extends Error {
+    readonly name = "RuiStartError";
+    readonly code: StartErrorCode;
+    constructor(code: StartErrorCode, message: string);
+}
+/** The Rui child process is gone, or was never ready. */
+export declare class RuiUnavailableError extends Error {
+    readonly name = "RuiUnavailableError";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,31 @@
+// The three error types a caller sees (D116). Request failures are
+// RuiRequestError, a refusal at open is RuiStartError, and a call that finds
+// no running Host is RuiUnavailableError.
+/** Rui rejected one request. `code` is the Host's rejection code; `message` preserves advisory detail when provided. */
+export class RuiRequestError extends Error {
+    name = "RuiRequestError";
+    code;
+    /** The Host's error class, such as `invocation_error` or `busy`. */
+    type;
+    constructor(type, code, message) {
+        super(message ?? `Rui rejected the request: ${code}`);
+        this.type = type;
+        this.code = code;
+    }
+}
+/** Rui refused to open. `code` is one of the refusal codes at open (D136). */
+export class RuiStartError extends Error {
+    name = "RuiStartError";
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** The Rui child process is gone, or was never ready. */
+export class RuiUnavailableError extends Error {
+    name = "RuiUnavailableError";
+    constructor(message, options) {
+        super(message, options);
+    }
+}

package/dist/feed.d.ts

@@ -0,0 +1,78 @@
+import type { Link } from "./sessions.ts";
+import type { components } from "./wire.ts";
+type Schemas = components["schemas"];
+type Row = Schemas["ActivityItem"];
+/** Every kind the Host's feed has, in its own order. */
+export declare const FEED_KINDS: readonly ["admission", "user", "assistant", "call", "tool_result", "hosted_call", "turn_ended", "stop", "sent", "send_failed", "received", "approval_requested", "session_changed", "compacted"];
+export type FeedKind = (typeof FEED_KINDS)[number];
+/** Entry text is inline up to this many bytes (D168). */
+export declare const INLINE_TEXT_BYTES: number;
+export interface ListActivityOptions {
+    /** The `cursor` of the last entry read. Left out, the feed starts at its beginning. */
+    after?: string;
+    /**
+     * Follows new entries, polling at 250 ms rising to 2 s only while busy.
+     * An empty idle/finished/failed/stopped page with nothing queued sleeps without a timer
+     * until send/update/decide/interrupt/stop succeeds through any handle for this Session
+     * on this Rui instance. Writes from another process to the same Store are not noticed
+     * while asleep. `signal` abort ends the iterator even while asleep.
+     */
+    follow?: boolean;
+    /** Only these kinds, by their wire names. Left out, every kind. */
+    kinds?: readonly FeedKind[];
+    /** Ends the iterator, even while it waits for new entries: a pending `next()` then resolves as done. */
+    signal?: AbortSignal;
+}
+/** Maps only the row's own keys; nested values retain their wire spelling (D128). */
+type CamelKey<Key extends string> = Key extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<CamelKey<Tail>>}` : Key;
+type CamelRow<Payload> = {
+    [Key in keyof Payload as Key extends "session" ? "sessionId" : Key extends string ? CamelKey<Key> : Key]: Payload[Key];
+};
+type EntryText = {
+    /** The row's text, when this kind carries it and it fits inline. */
+    text?: string;
+    /** Text exceeds 16 KiB: use `session.readContent(entry)`. */
+    truncated?: boolean;
+    /** The text's length in bytes, when this kind carries text. */
+    contentBytes?: string;
+};
+type EntryFromRow<R extends Row> = R extends Row ? {
+    [Kind in keyof R["value"]]: Omit<R, "value"> & {
+        kind: Kind;
+        cursor: string;
+    } & CamelRow<R["value"][Kind]> & ("content" extends keyof R["value"][Kind] ? EntryText : {});
+}[keyof R["value"]] : never;
+/** A discriminated wire-row union with top-level camelCase fields and an opaque continuation `cursor`.
+ * `session_changed` uses `reasoning_effort_refused` and inline `providerText` for a refused effort change.
+ */
+export type FeedEntry = EntryFromRow<Row>;
+/** An opaque cursor: after the row at this position and ordinal. */
+export declare function encodeCursor(position: string, ordinal: string): string;
+export declare function decodeCursor(cursor: string): {
+    position: string;
+    ordinal: string;
+};
+/** The whole text of an entry that has some, as UTF-8 bytes, however long (D134). */
+export declare function readContentBytes(link: Link, session: string, entry: {
+    position: string;
+    ordinal: string;
+}): Promise<Buffer>;
+/** The whole text of an entry as a string. A text past the JavaScript string limit (about 512 MiB) throws; use `readContentBytes`. */
+export declare function readContent(link: Link, session: string, entry: {
+    position: string;
+    ordinal: string;
+}): Promise<string>;
+export declare function listActivity(link: Link, session: string, options?: ListActivityOptions): AsyncGenerator<FeedEntry, void, undefined>;
+export interface SearchActivityOptions {
+    /** Resume before this search entry's cursor. */
+    before?: string;
+    kinds?: readonly FeedKind[];
+    limit?: number;
+    signal?: AbortSignal;
+}
+export type ActivitySearchEntry = Schemas["ActivitySearchReply"]["items"][number] & {
+    cursor: string;
+};
+/** Search public feed text newest first. Empty budget-limited pages still advance. */
+export declare function searchActivity(link: Link, session: string, query: string, options?: SearchActivityOptions): AsyncGenerator<ActivitySearchEntry, void, undefined>;
+export {};

package/dist/feed.js

@@ -0,0 +1,237 @@
+// The Session feed: `listActivity` is an async iterator over /v1/activity-page
+// (D9, D10, D117, A-D117, D134, D168). The Host sends rows with content
+// references only, and no cursor type. The client encodes the cursor from a
+// row's position and ordinal, and fills `text` from /v1/activity-content, so
+// the Host holds no reply buffer for either (D168).
+import { WIRE_VERSION } from "./transport.js";
+/** Every kind the Host's feed has, in its own order. */
+export const FEED_KINDS = [
+    "admission",
+    "user",
+    "assistant",
+    "call",
+    "tool_result",
+    "hosted_call",
+    "turn_ended",
+    "stop",
+    "sent",
+    "send_failed",
+    "received",
+    "approval_requested",
+    "session_changed",
+    "compacted",
+];
+// A kind the wire gains fails to compile here until the list has it.
+const complete = true;
+void complete;
+/** Entry text is inline up to this many bytes (D168). */
+export const INLINE_TEXT_BYTES = 16 * 1024;
+const PAGE_ROWS = 16;
+const FIRST_POLL_MS = 250;
+const MAX_POLL_MS = 2_000;
+/** The only endings whose `turn_ended` entry carries text (D168). */
+const ENDINGS_WITH_TEXT = new Set(["provider_refused", "failed"]);
+/** An opaque cursor: after the row at this position and ordinal. */
+export function encodeCursor(position, ordinal) {
+    return Buffer.from(`1:${position}:${ordinal}`).toString("base64url");
+}
+export function decodeCursor(cursor) {
+    const match = /^1:(0|[1-9][0-9]*):(0|[1-9][0-9]*)$/.exec(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (!match)
+        throw new RangeError("not a feed cursor");
+    return { position: match[1], ordinal: match[2] };
+}
+function camel(name) {
+    if (name === "session")
+        return "sessionId";
+    return name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function camelCase(row) {
+    return Object.fromEntries(Object.entries(row).map(([name, value]) => [camel(name), value]));
+}
+function isReference(value) {
+    return typeof value === "object" && value !== null && "bytes" in value && "sha256" in value;
+}
+/** Builds an entry from a row, without its text. Returns the content reference when text is to be read. */
+function entryOf(row) {
+    const [kind, payload] = Object.entries(row.value)[0];
+    const reference = isReference(payload.content) ? payload.content : undefined;
+    const wanted = kind !== "turn_ended" || ENDINGS_WITH_TEXT.has(String(payload.ending));
+    const entry = {
+        kind,
+        cursor: encodeCursor(row.position, row.ordinal),
+        position: row.position,
+        ordinal: row.ordinal,
+        at: row.at,
+        ...camelCase(payload),
+        ...(reference && wanted ? { contentBytes: reference.bytes } : {}),
+    }; // Object.entries erases the generated kind/payload correlation at this boundary.
+    return { entry, reference: reference && wanted ? reference : undefined };
+}
+function activityBody(store, session, request) {
+    return JSON.stringify({
+        version: WIRE_VERSION,
+        kind: "activity_page",
+        store,
+        session,
+        end: request.end,
+        position: request.position,
+        ordinal: request.ordinal,
+        direction: "forward",
+        kinds: [...request.kinds],
+        limit: String(PAGE_ROWS),
+        ...(request.since === null ? {} : { since: request.since }),
+    });
+}
+function contentBody(store, session, entry) {
+    return JSON.stringify({
+        version: WIRE_VERSION,
+        kind: "activity_content",
+        store,
+        session,
+        position: entry.position,
+        ordinal: entry.ordinal,
+    });
+}
+/** The Host stores up to a little under 1 GiB of text in one entry. */
+const MAX_CONTENT_BYTES = 1024 * 1024 * 1024;
+/** The whole text of an entry that has some, as UTF-8 bytes, however long (D134). */
+export function readContentBytes(link, session, entry) {
+    return link.exchange("/v1/activity-content", (store) => contentBody(store, session, entry), undefined, { max: MAX_CONTENT_BYTES });
+}
+/** The whole text of an entry as a string. A text past the JavaScript string limit (about 512 MiB) throws; use `readContentBytes`. */
+export async function readContent(link, session, entry) {
+    return (await readContentBytes(link, session, entry)).toString("utf8");
+}
+/** Waits `ms`, or less when `signal` aborts. */
+function pause(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+export async function* listActivity(link, session, options = {}) {
+    // The Host wants kinds in its own order, each once.
+    const kinds = options.kinds === undefined ? FEED_KINDS : FEED_KINDS.filter((kind) => options.kinds?.includes(kind));
+    let position = "0";
+    let ordinal = null;
+    if (options.after !== undefined) {
+        const cursor = decodeCursor(options.after);
+        position = cursor.position;
+        ordinal = cursor.ordinal;
+    }
+    let pinnedEnd = null;
+    let wait = FIRST_POLL_MS;
+    let since = null;
+    let idle = false;
+    const { signal } = options;
+    const watcher = options.follow ? link.activity?.watch(session) : undefined;
+    try {
+        while (!signal?.aborted) {
+            // Capture before I/O so a write racing an idle reply cannot be lost.
+            const revision = watcher?.revision ?? 0;
+            const page = JSON.parse((await link.exchange("/v1/activity-page", (store) => activityBody(store, session, { end: pinnedEnd, position, ordinal, kinds, since }))).toString("utf8"));
+            let receivedItems = false;
+            if (page.delta === "not_modified") {
+                since = page.since;
+            }
+            else {
+                for (const row of page.items) {
+                    // Cancellation is honoured before each entry, and again after any read that took time.
+                    if (signal?.aborted)
+                        return;
+                    const { entry, reference } = entryOf(row);
+                    if (reference && "content" in entry) {
+                        if (Number(reference.bytes) > INLINE_TEXT_BYTES) {
+                            entry.truncated = true;
+                        }
+                        else {
+                            const prefix = await link.exchange("/v1/activity-content", (store) => contentBody(store, session, row), undefined, { prefix: INLINE_TEXT_BYTES });
+                            entry.text = prefix.toString("utf8");
+                        }
+                    }
+                    if (signal?.aborted)
+                        return;
+                    yield entry;
+                    position = row.position;
+                    ordinal = row.ordinal;
+                }
+                if (page.more) {
+                    // A bounded read keeps the end the first page named; a following one asks again.
+                    pinnedEnd = options.follow ? null : page.end;
+                    // A Session token cannot stand in for rows not yet consumed.
+                    since = null;
+                    wait = FIRST_POLL_MS;
+                    continue;
+                }
+                if (!options.follow)
+                    return;
+                pinnedEnd = null;
+                // Exhausted: everything the filter matches up to the end has been read, so the next poll starts at the end
+                // rather than rescanning the rows between the last match and it.
+                position = page.end;
+                ordinal = null;
+                since = page.since;
+                idle = page.queued.count === "0" && dormant(page.work.state.kind);
+                receivedItems = page.items.length > 0;
+            }
+            if (receivedItems)
+                wait = FIRST_POLL_MS;
+            else if (idle) {
+                await (watcher ? watcher.wait(revision, signal) : untilAbort(signal));
+                wait = FIRST_POLL_MS;
+            }
+            else {
+                await pause(wait, signal);
+                wait = Math.min(wait * 2, MAX_POLL_MS);
+            }
+        }
+    }
+    finally {
+        watcher?.close();
+    }
+}
+function dormant(kind) {
+    return kind === "idle" || kind === "finished" || kind === "failed" || kind === "stopped";
+}
+/** A bare internal Link has no local writes to observe; cancellation still ends its idle wait. */
+function untilAbort(signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            resolve();
+        else
+            signal?.addEventListener("abort", () => resolve(), { once: true });
+    });
+}
+/** Search public feed text newest first. Empty budget-limited pages still advance. */
+export async function* searchActivity(link, session, query, options = {}) {
+    const bytes = Buffer.byteLength(query, "utf8");
+    if (bytes === 0 || bytes > 256 || Buffer.from(query, "utf8").toString("utf8") !== query)
+        throw new RangeError("query must be 1–256 UTF-8 bytes");
+    const limit = options.limit ?? PAGE_ROWS;
+    if (!Number.isInteger(limit) || limit < 1 || limit > PAGE_ROWS)
+        throw new RangeError("limit must be 1–16");
+    const kinds = options.kinds === undefined ? FEED_KINDS : FEED_KINDS.filter((kind) => options.kinds?.includes(kind));
+    let before = options.before === undefined ? null : decodeCursor(options.before);
+    while (!options.signal?.aborted) {
+        const page = JSON.parse((await link.exchange("/v1/activity-search", (store) => JSON.stringify({
+            version: WIRE_VERSION, kind: "activity_search", store, session, query, kinds: [...kinds],
+            before_position: before?.position ?? null, before_ordinal: before?.ordinal ?? null, limit: String(limit),
+        }))).toString("utf8"));
+        for (const item of page.items) {
+            if (options.signal?.aborted)
+                return;
+            yield { ...item, cursor: encodeCursor(item.position, item.ordinal) };
+        }
+        if (page.next === null)
+            return;
+        before = page.next;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Rui, type ConnectOptions, type ExitEvent, type McpServer } from "./client.ts";
+export { RuiRequestError, RuiStartError, RuiUnavailableError } from "./errors.ts";
+export { Session, Sessions, type AgentSpec, type ListSessionsOptions, type SessionArchiveState, type SessionArchiveResult, type SessionCreate, type ModelSummary, type SendOptions, type SessionSpec, type SessionSummary, type SessionStatus, type SessionUpdate, type WriteOptions, } from "./sessions.ts";
+export { FEED_KINDS, INLINE_TEXT_BYTES, type FeedEntry, type FeedKind, type ListActivityOptions, type SearchActivityOptions, type ActivitySearchEntry } from "./feed.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+// The package's public surface. Transport types stay internal (D19).
+export { Rui } from "./client.js";
+export { RuiRequestError, RuiStartError, RuiUnavailableError } from "./errors.js";
+export { Session, Sessions, } from "./sessions.js";
+export { FEED_KINDS, INLINE_TEXT_BYTES } from "./feed.js";

package/dist/notifications.d.ts

@@ -0,0 +1,17 @@
+export declare class SessionNotifications {
+    #private;
+    watch(session: string): WriteWatch;
+    /** Rejects and releases every active follower, including one still reading its page. */
+    fail(error: Error): void;
+    notify(session: string): void;
+}
+declare class WriteWatch {
+    #private;
+    revision: number;
+    constructor(release: () => void);
+    notify(): void;
+    wait(revision: number, signal: AbortSignal | undefined): Promise<void>;
+    fail(error: Error): void;
+    close(): void;
+}
+export {};

package/dist/notifications.js

@@ -0,0 +1,69 @@
+// Owned by one Rui instance. Only active followers occupy the per-Session map.
+export class SessionNotifications {
+    #sessions = new Map();
+    watch(session) {
+        let watches = this.#sessions.get(session);
+        if (!watches)
+            this.#sessions.set(session, (watches = new Set()));
+        const watch = new WriteWatch(() => {
+            if (watches.delete(watch) && watches.size === 0)
+                this.#sessions.delete(session);
+        });
+        watches.add(watch);
+        return watch;
+    }
+    /** Rejects and releases every active follower, including one still reading its page. */
+    fail(error) {
+        for (const watches of this.#sessions.values()) {
+            for (const watch of watches)
+                watch.fail(error);
+        }
+    }
+    notify(session) {
+        for (const watch of this.#sessions.get(session) ?? [])
+            watch.notify();
+    }
+}
+class WriteWatch {
+    revision = 0;
+    #release;
+    #wake;
+    #error;
+    constructor(release) {
+        this.#release = release;
+    }
+    notify() {
+        this.revision++;
+        this.#wake?.();
+    }
+    wait(revision, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted)
+                return resolve();
+            if (this.#error)
+                return reject(this.#error);
+            if (this.revision !== revision)
+                return resolve();
+            const done = (error) => {
+                signal?.removeEventListener("abort", abort);
+                this.#wake = undefined;
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const abort = () => done();
+            this.#wake = done;
+            signal?.addEventListener("abort", abort, { once: true });
+        });
+    }
+    fail(error) {
+        this.#error = error;
+        this.#wake?.(error);
+        this.close();
+    }
+    close() {
+        this.#wake?.();
+        this.#release();
+    }
+}

package/dist/sessions.d.ts

@@ -0,0 +1,160 @@
+import type { SessionNotifications } from "./notifications.ts";
+import { type ActivitySearchEntry, type SearchActivityOptions, type FeedEntry, type ListActivityOptions } from "./feed.ts";
+import { type ReplyLimits } from "./transport.ts";
+import type { components } from "./wire.ts";
+/** What a Session handle needs from the client. */
+export interface Link {
+    readonly activity?: SessionNotifications;
+    exchange(path: string, build: (store: string) => string, environment?: Buffer, limits?: ReplyLimits): Promise<Buffer>;
+}
+type Schemas = components["schemas"];
+/** The Session settings the Host takes today. */
+export interface AgentSpec {
+    /** The working directory for Bash. Required with `bash`, fixed for the Session's life. */
+    workspace?: string;
+    /** `openai` or `codex`. Fixed for the Session's life. */
+    provider?: NonNullable<Schemas["AgentSpec"]["provider"]>;
+    /** May change within the Session's fixed provider. */
+    model: string;
+    instructions?: string;
+    /** JSON output schema object; `null` clears it. */
+    outputSchema?: Record<string, unknown> | null;
+    /** Tool names the Host offers, such as `bash` and `web_search`. */
+    tools: readonly string[];
+    /** Tools loaded from the first model request. */
+    loadedTools?: readonly string[];
+    /** Tokens reserved for model output; null clears the override. */
+    outputReservation?: number | null;
+    permissionMode: "ask" | "bypass";
+    /** Reasoning effort. `null` sends none, so the provider uses its own; only for a model Rui does not list (D111). */
+    effort: Schemas["AgentSpec"]["effort"];
+    /** Compact the conversation at this many tokens. */
+    compactAt: number;
+    /** A name shown in lists. `null` clears it. */
+    label?: string | null;
+}
+/** The same agent spec accepted by creation and connect-time presets. */
+export type SessionSpec = AgentSpec;
+/** Creation needs a complete spec, or a named preset with explicit overrides. */
+export type SessionCreate = ((AgentSpec & {
+    preset?: never;
+}) | ({
+    preset: string;
+} & Partial<AgentSpec>)) & {
+    /** Create an attached child, inheriting provider, workspace and Bash environment. */
+    parent?: string;
+};
+/** The settings `update` may change: everything but the ones fixed at creation. */
+export type SessionUpdate = Partial<Pick<SessionSpec, "model" | "instructions" | "outputSchema" | "tools" | "permissionMode" | "effort" | "compactAt" | "label" | "loadedTools" | "outputReservation">>;
+export interface WriteOptions {
+    /** Required on `create` and `send`, built as `kind:driftId`. Other writes get a fresh UUIDv4 when it is left out (D123). */
+    idempotencyKey?: string;
+}
+export interface SendOptions {
+    idempotencyKey: string;
+    /** The environment Bash runs in. Defaults to empty: the caller's own never reaches Bash (D121). */
+    env?: Record<string, string>;
+}
+export type SessionArchiveState = CurrentReport["archive_state"];
+export interface ListSessionsOptions {
+    /** Defaults to active, including Sessions still settling an archive request. */
+    archive?: Schemas["ListSessionsRequest"]["archive"];
+}
+export interface SessionArchiveResult {
+    archived: boolean;
+    /** Accepted intent can remain pending until stopped work has really settled. */
+    completion: "pending" | "completed";
+}
+export interface SessionSummary {
+    id: string;
+    label: string | null;
+    /** The Session's work state, such as `idle`, `working` or `approval`. */
+    state: string;
+    archiveState: SessionArchiveState;
+    parent: string | null;
+}
+type CurrentReport = Extract<Schemas["InspectSessionReply"], {
+    profile: "current";
+    work: unknown;
+}>;
+/** Current Host facts. Decimal counts, times and IDs remain lossless strings. */
+export interface SessionStatus {
+    archiveState: SessionArchiveState;
+    state: CurrentReport["work"]["state"]["kind"];
+    since: CurrentReport["work"]["state"]["since"];
+    turn: CurrentReport["work"]["turn"];
+    operation: CurrentReport["work"]["operation"];
+    pendingMessages: CurrentReport["pending_messages"];
+    parent: CurrentReport["session"]["parent"];
+    label: CurrentReport["session"]["label"];
+    model: CurrentReport["session"]["model"];
+    effort: CurrentReport["session"]["reasoning_effort"];
+    tools: CurrentReport["session"]["tools"];
+    permissionMode: CurrentReport["session"]["permission_mode"];
+    latestOutcome: CurrentReport["work"]["latest_outcome"];
+}
+export interface ModelSummary {
+    provider: string;
+    id: string;
+    known: boolean;
+}
+/** One plain wire spec for configure and connect-time presets. */
+export declare function agentSpec(spec: Partial<SessionSpec>): Schemas["Configuration"];
+/** `NAME=VALUE\0` for each entry the Host would keep (D121): a name that is not empty, holds no `=` or NUL and does not start with `RUI_`, and a value without NUL. The rest are left out, because after encoding the Host could not tell where an entry ended. */
+export declare function environmentBytes(env: Record<string, string> | undefined): Buffer;
+export declare class Session {
+    #private;
+    readonly id: string;
+    constructor(link: Link, id: string);
+    /**
+     * The Session's feed, in order, as an async iterator (D9). Without `follow`
+     * it ends at the current end. With it, busy Sessions poll with backoff; idle Sessions
+     * wait for a local write on this Rui instance (not writes from another process).
+     * See `ListActivityOptions.follow`; `signal` abort also ends an idle wait.
+     */
+    listActivity(options?: ListActivityOptions): AsyncGenerator<FeedEntry, void, undefined>;
+    /** Search public feed text newest first, with bounded snippets. */
+    searchActivity(query: string, options?: SearchActivityOptions): AsyncGenerator<ActivitySearchEntry, void, undefined>;
+    /** The whole text of an entry (D134). Past about 512 MiB a string cannot hold it and this throws: use `readContentBytes`. */
+    readContent(entry: Pick<FeedEntry, "position" | "ordinal">): Promise<string>;
+    /** The whole text of an entry as UTF-8 bytes, up to the Host's limit of about 1 GiB. */
+    readContentBytes(entry: Pick<FeedEntry, "position" | "ordinal">): Promise<Buffer>;
+    /** A Current report's summary (D12). A separate ending is not reported. */
+    status(): Promise<SessionStatus>;
+    /** Sends a Message. The receipt is its admission number; the answer arrives in the feed (D8). */
+    send(text: string, options: SendOptions): Promise<{
+        messageId: string;
+    }>;
+    /** Changes settings. Omitted fields stay as they are. Resolves once the Host accepted the change (D7). */
+    update(fields: SessionUpdate, options?: WriteOptions): Promise<void>;
+    /** Stops the current and queued work. The Session stays usable (D14). */
+    stop(options?: WriteOptions): Promise<void>;
+    /** Stops work and archives after real settlement, using one durable intent. */
+    archive(options?: WriteOptions): Promise<SessionArchiveResult>;
+    /** Restores organization only. Previously stopped work is never resumed. */
+    unarchive(options?: WriteOptions): Promise<SessionArchiveResult>;
+    /**
+     * Cuts off the model call that is current now while the Session keeps going.
+     * It takes no key: each call names the work it sees at that moment, so a
+     * repeat is a new cut, not a replay. Resolves without effect when no model
+     * call is current, or when the call ended before the cut arrived (D167, D171).
+     */
+    interrupt(): Promise<void>;
+    /** Answers an approval. `requestId` is the Action id of the `approval_requested` entry (D15). */
+    decide(requestId: string, decision: "allow" | "deny", options?: WriteOptions): Promise<void>;
+}
+export declare class Sessions {
+    #private;
+    constructor(link: Link);
+    /** Creates a Session. The key is required: a repeat returns the same Session (D7, D17). */
+    create(spec: SessionCreate, options: {
+        idempotencyKey: string;
+    }): Promise<Session>;
+    /** Configured Sessions, newest first; archived Sessions are hidden by default. */
+    list(options?: ListSessionsOptions): Promise<SessionSummary[]>;
+}
+/** The models each provider offers (D128). */
+export declare function models(link: Link): Promise<ModelSummary[]>;
+/** Holds every new Turn while paused; running work continues (D199). */
+export declare function setPaused(link: Link, paused: boolean): Promise<void>;
+export {};