ruicode 0.0.0-stage → 0.69.0

package/dist/sessions.js

@@ -0,0 +1,279 @@
+// Sessions: create, list, status, send, update, stop, interrupt and decide, plus the
+// model list and Host pause (D7, D8, D14 to D17, D121, D123, D128, D167,
+// D171). Every call is one request to a Host route that exists today.
+import { randomUUID } from "node:crypto";
+import { RuiRequestError } from "./errors.js";
+import { listActivity, searchActivity, readContent, readContentBytes } from "./feed.js";
+import { WIRE_VERSION } from "./transport.js";
+/** One plain wire spec for configure and connect-time presets. */
+export function agentSpec(spec) {
+    return {
+        ...(spec.workspace === undefined ? {} : { workspace: spec.workspace }),
+        ...(spec.provider === undefined ? {} : { provider: spec.provider }),
+        ...(spec.model === undefined ? {} : { model: spec.model }),
+        ...(spec.instructions === undefined ? {} : { instructions: spec.instructions }),
+        ...(spec.tools === undefined ? {} : { tools: [...new Set(spec.tools)].sort() }),
+        ...(spec.loadedTools === undefined ? {} : { loadedTools: [...new Set(spec.loadedTools)].sort() }),
+        ...(spec.permissionMode === undefined ? {} : { permissionMode: spec.permissionMode }),
+        ...(spec.outputSchema === undefined ? {} : { outputSchema: spec.outputSchema }),
+        ...(spec.compactAt === undefined ? {} : { compactAt: spec.compactAt }),
+        ...(spec.outputReservation === undefined ? {} : { outputReservation: spec.outputReservation }),
+        ...(spec.effort === undefined ? {} : { effort: spec.effort }),
+        ...(spec.label === undefined ? {} : { label: spec.label }),
+    };
+}
+function configureBody(store, key, session, spec) {
+    return JSON.stringify({
+        version: WIRE_VERSION,
+        kind: "configure",
+        store,
+        key,
+        session,
+        configuration: { ...agentSpec(spec), ...(spec.parent === undefined ? {} : { parent: spec.parent }) },
+        ...(spec.preset === undefined ? {} : { preset: spec.preset }),
+    });
+}
+function key(options) {
+    return options?.idempotencyKey ?? randomUUID();
+}
+function parse(reply) {
+    return JSON.parse(reply.toString("utf8"));
+}
+/** Throws the Host's rejection or conflict; returns the accepted answer. */
+function accepted(answer) {
+    if (answer.status !== "accepted")
+        throw new RuiRequestError(answer.status, answer.code, "message" in answer ? answer.message : undefined);
+    return answer;
+}
+/** `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 function environmentBytes(env) {
+    const forwarded = Object.entries(env ?? {}).filter(([name, entry]) => name !== "" && !name.startsWith("RUI_") && !/[=\0]/.test(name) && !entry.includes("\0"));
+    return Buffer.from(forwarded.map(([name, entry]) => `${name}=${entry}\0`).join(""), "utf8");
+}
+export class Session {
+    #link;
+    id;
+    constructor(link, id) {
+        this.#link = link;
+        this.id = id;
+    }
+    /**
+     * 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) {
+        return listActivity(this.#link, this.id, options);
+    }
+    /** Search public feed text newest first, with bounded snippets. */
+    searchActivity(query, options) {
+        return searchActivity(this.#link, this.id, query, options);
+    }
+    /** The whole text of an entry (D134). Past about 512 MiB a string cannot hold it and this throws: use `readContentBytes`. */
+    readContent(entry) {
+        return readContent(this.#link, this.id, entry);
+    }
+    /** The whole text of an entry as UTF-8 bytes, up to the Host's limit of about 1 GiB. */
+    readContentBytes(entry) {
+        return readContentBytes(this.#link, this.id, entry);
+    }
+    /** A Current report's summary (D12). A separate ending is not reported. */
+    async status() {
+        const reply = parse(await this.#link.exchange("/v1/inspect-session", (store) => JSON.stringify({
+            version: WIRE_VERSION,
+            kind: "inspect_session",
+            store,
+            session: this.id,
+        })));
+        if (reply.session === null)
+            throw new RuiRequestError("invocation_error", "session_not_found");
+        return {
+            archiveState: reply.archive_state,
+            state: reply.work.state.kind,
+            since: reply.work.state.since,
+            turn: reply.work.turn,
+            operation: reply.work.operation,
+            pendingMessages: reply.pending_messages,
+            parent: reply.session.parent,
+            label: reply.session.label,
+            model: reply.session.model,
+            effort: reply.session.reasoning_effort,
+            tools: reply.session.tools,
+            permissionMode: reply.session.permission_mode,
+            latestOutcome: reply.work.latest_outcome,
+        };
+    }
+    /** Sends a Message. The receipt is its admission number; the answer arrives in the feed (D8). */
+    async send(text, options) {
+        const body = (store) => JSON.stringify({
+            version: WIRE_VERSION,
+            kind: "message",
+            store,
+            key: options.idempotencyKey,
+            session: this.id,
+            sender: null,
+            sender_handle: null,
+            text: { state: "value", value: text },
+        });
+        const reply = parse(await this.#link.exchange("/v1/message", body, environmentBytes(options.env)));
+        const messageId = accepted(reply.answer).admission;
+        this.#link.activity?.notify(this.id);
+        return { messageId };
+    }
+    /** Changes settings. Omitted fields stay as they are. Resolves once the Host accepted the change (D7). */
+    async update(fields, options) {
+        const idempotencyKey = key(options);
+        const reply = parse(await this.#link.exchange("/v1/configure", (store) => configureBody(store, idempotencyKey, this.id, fields)));
+        accepted(reply.answer);
+        this.#link.activity?.notify(this.id);
+    }
+    /** Stops the current and queued work. The Session stays usable (D14). */
+    async stop(options) {
+        const idempotencyKey = key(options);
+        const body = (store) => JSON.stringify({
+            version: WIRE_VERSION,
+            kind: "session_stop",
+            store,
+            key: idempotencyKey,
+            session: this.id,
+        });
+        accepted(parse(await this.#link.exchange("/v1/control/session-stop", body)).answer);
+        this.#link.activity?.notify(this.id);
+    }
+    /** Stops work and archives after real settlement, using one durable intent. */
+    archive(options) {
+        return this.#setArchived(true, options);
+    }
+    /** Restores organization only. Previously stopped work is never resumed. */
+    unarchive(options) {
+        return this.#setArchived(false, options);
+    }
+    async #setArchived(archived, options) {
+        const idempotencyKey = key(options);
+        const reply = parse(await this.#link.exchange("/v1/control/session-archive", (store) => JSON.stringify({
+            version: WIRE_VERSION,
+            kind: "session_archive",
+            store,
+            key: idempotencyKey,
+            session: this.id,
+            archived,
+        })));
+        const answer = accepted(reply.answer);
+        const completion = reply.completion.status;
+        if (completion === "unavailable")
+            throw new RuiRequestError("invocation_error", "invalid_response");
+        this.#link.activity?.notify(this.id);
+        return { archived: answer.archived, completion };
+    }
+    /**
+     * 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).
+     */
+    async interrupt() {
+        const status = await this.status();
+        const { turn, operation } = status;
+        if (turn === null || operation === null || !modelCallCurrent(status.state)) {
+            this.#link.activity?.notify(this.id);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        const body = (store) => JSON.stringify({
+            version: WIRE_VERSION,
+            kind: "model_interruption",
+            store,
+            key: idempotencyKey,
+            target: { session: this.id, turn, operation },
+        });
+        try {
+            accepted(parse(await this.#link.exchange("/v1/control/model-interruption", body)).answer);
+        }
+        catch (error) {
+            // The call ended before the cut reached it: nothing is left to cut.
+            const gone = error instanceof RuiRequestError && (error.code === "operation_resolved" || error.code === "target_mismatch");
+            if (!gone)
+                throw error;
+        }
+        this.#link.activity?.notify(this.id);
+    }
+    /** Answers an approval. `requestId` is the Action id of the `approval_requested` entry (D15). */
+    async decide(requestId, decision, options) {
+        const idempotencyKey = key(options);
+        const wire = decision === "allow" ? "allow_once" : "deny";
+        const body = (store) => JSON.stringify({
+            version: WIRE_VERSION,
+            kind: "permission_decision",
+            store,
+            key: idempotencyKey,
+            session: this.id,
+            action: requestId,
+            decision: wire,
+        });
+        accepted(parse(await this.#link.exchange("/v1/control/permission-decision", body)).answer);
+        this.#link.activity?.notify(this.id);
+    }
+}
+/** Work states in which a model call is the current thing. */
+function modelCallCurrent(kind) {
+    return kind === "working" || kind === "retrying" || kind === "pending";
+}
+export class Sessions {
+    #link;
+    constructor(link) {
+        this.#link = link;
+    }
+    /** Creates a Session. The key is required: a repeat returns the same Session (D7, D17). */
+    async create(spec, options) {
+        const reply = parse(await this.#link.exchange("/v1/configure", (store) => configureBody(store, options.idempotencyKey, "", spec)));
+        return new Session(this.#link, accepted(reply.answer).session);
+    }
+    /** Configured Sessions, newest first; archived Sessions are hidden by default. */
+    async list(options) {
+        const summaries = [];
+        let after = "0";
+        let ceiling = "0";
+        for (;;) {
+            const wireAfter = after;
+            const wireCeiling = ceiling;
+            const page = parse(await this.#link.exchange("/v1/list-sessions", (store) => JSON.stringify({
+                version: WIRE_VERSION,
+                kind: "list_sessions",
+                store,
+                workspace: null,
+                archive: options?.archive ?? "active",
+                after: wireAfter,
+                ceiling: wireCeiling,
+            })));
+            for (const row of page.sessions) {
+                summaries.push({ id: row.reference, label: row.label, state: row.work.state.kind, archiveState: row.archive_state, parent: row.parent });
+            }
+            if (page.next === null || !("after" in page.next))
+                return summaries.reverse();
+            after = page.next.after;
+            ceiling = page.next.ceiling;
+        }
+    }
+}
+/** The models each provider offers (D128). */
+export async function models(link) {
+    const reply = parse(await link.exchange("/v1/model-list", (store) => JSON.stringify({
+        version: WIRE_VERSION,
+        kind: "model_list",
+        store,
+    }), undefined, {
+        // A live provider list can take longer than the default response wait.
+        responseMs: 30_000,
+    }));
+    return reply.providers.flatMap((entry) => entry.models.map((model) => ({ provider: entry.provider, id: model.id, known: model.known })));
+}
+/** Holds every new Turn while paused; running work continues (D199). */
+export async function setPaused(link, paused) {
+    await link.exchange("/v1/control/host-pause", (store) => JSON.stringify({
+        version: WIRE_VERSION,
+        kind: "host_pause",
+        store,
+        paused,
+    }));
+}

package/dist/transport.d.ts

@@ -0,0 +1,27 @@
+/** The wire version openapi.json describes. A test keeps the two equal. */
+export declare const WIRE_VERSION = "13";
+export interface Post {
+    socketPath: string;
+    path: string;
+    /** The serialized request JSON. */
+    body: string;
+    /** The Host instance from host-info; a different instance refuses the call. */
+    instance?: string;
+    /** Client environment bytes sent ahead of the JSON (`/v1/message`). */
+    environment?: Buffer;
+    /** `prefix`: resolve with the first this-many bytes of a successful reply and drop the rest. `max`: the most a reply may hold; the default fits the Host's control replies. */
+    limits?: ReplyLimits;
+}
+export interface ReplyLimits {
+    prefix?: number;
+    max?: number;
+    /** The longest silence before the first reply byte, once the request is sent. Default 5 s. */
+    responseMs?: number;
+    /** The longest a transfer may make no byte of progress. Default 60 s. */
+    idleMs?: number;
+}
+/** A failure to reach the Host at all, as opposed to a refusal from it. */
+export declare class ConnectionError extends Error {
+    readonly name = "ConnectionError";
+}
+export declare function post(call: Post): Promise<Buffer>;

package/dist/transport.js

@@ -0,0 +1,87 @@
+// One POST over the Host's Unix socket. The Host speaks HTTP/1.1, answers
+// once and closes the connection. Nothing here is exported from the package
+// (D19).
+import { request } from "node:http";
+import { RuiRequestError } from "./errors.js";
+/** The wire version openapi.json describes. A test keeps the two equal. */
+export const WIRE_VERSION = "13";
+/** The largest reply body read. The Host's own replies stay far below it. */
+const MAX_REPLY_BYTES = 64 * 1024 * 1024;
+/** After the request is sent, the longest the Host may stay silent before its first reply byte. */
+const RESPONSE_WAIT_MS = 5_000;
+/** The longest a transfer, in either direction, may make no byte of progress. */
+const TRANSFER_IDLE_MS = 60_000;
+/** A failure to reach the Host at all, as opposed to a refusal from it. */
+export class ConnectionError extends Error {
+    name = "ConnectionError";
+}
+export function post(call) {
+    const json = Buffer.from(call.body);
+    const payload = call.environment ? Buffer.concat([call.environment, json]) : json;
+    const headers = {
+        "Content-Type": "application/json",
+        "Content-Length": String(payload.length),
+        "X-Rui-Wire-Version": WIRE_VERSION,
+    };
+    if (call.instance !== undefined)
+        headers["X-Rui-Host-Instance"] = call.instance;
+    if (call.environment !== undefined)
+        headers["X-Rui-Environment-Bytes"] = String(call.environment.length);
+    return new Promise((resolve, reject) => {
+        const outgoing = request({ socketPath: call.socketPath, path: call.path, method: "POST", headers, agent: false });
+        const idle = call.limits?.idleMs ?? TRANSFER_IDLE_MS;
+        outgoing.setTimeout(idle);
+        outgoing.on("timeout", () => outgoing.destroy(new Error("the Host made no progress in time")));
+        // Silence after the whole request went out gets the short budget; any byte of progress renews the long one.
+        outgoing.on("finish", () => outgoing.setTimeout(call.limits?.responseMs ?? RESPONSE_WAIT_MS));
+        outgoing.on("error", (error) => reject(new ConnectionError(error.message, { cause: error })));
+        outgoing.on("response", (incoming) => {
+            outgoing.setTimeout(idle);
+            const chunks = [];
+            let length = 0;
+            incoming.on("data", (chunk) => {
+                if (call.limits?.prefix !== undefined && incoming.statusCode === 200) {
+                    chunks.push(chunk);
+                    length += chunk.length;
+                    if (length >= (call.limits?.prefix ?? Infinity)) {
+                        incoming.destroy();
+                        resolve(Buffer.concat(chunks).subarray(0, call.limits?.prefix));
+                    }
+                    return;
+                }
+                length += chunk.length;
+                const max = call.limits?.max ?? MAX_REPLY_BYTES;
+                if (length > max) {
+                    incoming.destroy(new Error(`the reply exceeds ${max} bytes`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            incoming.on("error", (error) => reject(new ConnectionError(error.message, { cause: error })));
+            incoming.on("end", () => {
+                const reply = Buffer.concat(chunks);
+                if (incoming.statusCode === 200)
+                    return resolve(reply);
+                reject(refusal(incoming.statusCode, reply));
+            });
+        });
+        outgoing.end(payload);
+    });
+}
+function refusal(status, reply) {
+    let parsed;
+    try {
+        parsed = JSON.parse(reply.toString("utf8"));
+    }
+    catch {
+        // Fall through: a reply that is not an ErrorReply is reported by status.
+    }
+    if (parsed && typeof parsed.code === "string" && typeof parsed.type === "string") {
+        return new RuiRequestError(parsed.type, parsed.code);
+    }
+    // A reused key with different input answers 409 with the command's own envelope.
+    if (parsed?.answer && typeof parsed.answer.code === "string" && typeof parsed.answer.status === "string") {
+        return new RuiRequestError(parsed.answer.status, parsed.answer.code);
+    }
+    return new RuiRequestError("invocation_error", `http_${status ?? "unknown"}`);
+}