@trycua/cua 0.2.0

package/dist/native/index.d.ts

@@ -0,0 +1,7 @@
+export * from './cua_sdk.js';
+import * as cua_sdk from './cua_sdk.js';
+export declare function uniffiInitAsync(): Promise<void>;
+declare const _default: {
+    cua_sdk: typeof cua_sdk;
+};
+export default _default;

package/dist/native/index.js

@@ -0,0 +1,12 @@
+// Generated by uniffi-bindgen-react-native — do not edit.
+export * from './cua_sdk.js';
+import * as cua_sdk from './cua_sdk.js';
+let initialized = false;
+if (!initialized) {
+    cua_sdk.default.initialize();
+    initialized = true;
+}
+export async function uniffiInitAsync() { }
+export default {
+    cua_sdk,
+};

package/dist/native/node-runtime.d.ts

@@ -0,0 +1,72 @@
+import { resolveLibPath } from "@ubjs/node/typescript/dist/resolve-lib.js";
+declare const _default: {
+    FfiType: {
+        UInt8: {
+            tag: string;
+        };
+        Int8: {
+            tag: string;
+        };
+        UInt16: {
+            tag: string;
+        };
+        Int16: {
+            tag: string;
+        };
+        UInt32: {
+            tag: string;
+        };
+        Int32: {
+            tag: string;
+        };
+        UInt64: {
+            tag: string;
+        };
+        Int64: {
+            tag: string;
+        };
+        Float32: {
+            tag: string;
+        };
+        Float64: {
+            tag: string;
+        };
+        Handle: {
+            tag: string;
+        };
+        RustBuffer: {
+            tag: string;
+        };
+        ForeignBytes: {
+            tag: string;
+        };
+        RustCallStatus: {
+            tag: string;
+        };
+        VoidPointer: {
+            tag: string;
+        };
+        Void: {
+            tag: string;
+        };
+        Callback: (name: string) => {
+            tag: string;
+            name: string;
+        };
+        Struct: (name: string) => {
+            tag: string;
+            name: string;
+        };
+        Reference: (inner: unknown) => {
+            tag: string;
+            inner: unknown;
+        };
+        MutReference: (inner: unknown) => {
+            tag: string;
+            inner: unknown;
+        };
+    };
+    resolveLibPath: typeof resolveLibPath;
+    UniffiNativeModule: unknown;
+};
+export default _default;

package/dist/native/node-runtime.js

@@ -0,0 +1,35 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { resolveLibPath } from "@ubjs/node/typescript/dist/resolve-lib.js";
+const FfiType = {
+    UInt8: { tag: "UInt8" },
+    Int8: { tag: "Int8" },
+    UInt16: { tag: "UInt16" },
+    Int16: { tag: "Int16" },
+    UInt32: { tag: "UInt32" },
+    Int32: { tag: "Int32" },
+    UInt64: { tag: "UInt64" },
+    Int64: { tag: "Int64" },
+    Float32: { tag: "Float32" },
+    Float64: { tag: "Float64" },
+    Handle: { tag: "Handle" },
+    RustBuffer: { tag: "RustBuffer" },
+    ForeignBytes: { tag: "ForeignBytes" },
+    RustCallStatus: { tag: "RustCallStatus" },
+    VoidPointer: { tag: "VoidPointer" },
+    Void: { tag: "Void" },
+    Callback: (name) => ({ tag: "Callback", name }),
+    Struct: (name) => ({ tag: "Struct", name }),
+    Reference: (inner) => ({ tag: "Reference", inner }),
+    MutReference: (inner) => ({ tag: "MutReference", inner }),
+};
+const sdkLibrary = resolveLibPath({
+    crateName: "cua_sdk",
+    callerUrl: import.meta.url,
+    npmPackageBase: "@trycua/cua-",
+    tripleStyle: "node",
+});
+const runtimePath = join(dirname(sdkLibrary), "cua_node_runtime.node");
+const require = createRequire(import.meta.url);
+const { UniffiNativeModule } = require(runtimePath);
+export default { FfiType, resolveLibPath, UniffiNativeModule };

package/dist/spaces/cursorArt.d.ts

@@ -0,0 +1,27 @@
+/** A presence cursor shape (the names of `cua.env.v1.CursorShape`). */
+export type CursorShapeName = "arrow" | "text" | "pointer" | "resize_ew" | "resize_ns" | "resize_nwse" | "resize_nesw" | "move" | "crosshair" | "wait" | "progress" | "not_allowed" | "grab" | "grabbing";
+/** Every shape, in wire order. */
+export declare const CURSOR_SHAPES: readonly CursorShapeName[];
+/** One shape's art: an SVG path (absolute M, L, C, Z; nonzero fill) and its hot spot. */
+export interface CursorArtShape {
+    hotspot: readonly [number, number];
+    d: string;
+}
+/** The shared presence cursor art: fill with the participant's color over the outline. */
+export declare const CURSOR_ART: {
+    canvas: number;
+    outline: {
+        color: string;
+        width: number;
+    };
+    shapes: Readonly<Record<CursorShapeName, CursorArtShape>>;
+};
+/** Whether `name` is a known shape. */
+export declare function isCursorShape(name: unknown): name is CursorShapeName;
+/** The art for `shape`; unknown names get the arrow. */
+export declare function cursorArt(shape: string): CursorArtShape;
+/**
+ * A standalone SVG of `shape` filled with `color`, `size` pixels square.
+ * The hot spot is at `cursorArt(shape).hotspot * size / CURSOR_ART.canvas`.
+ */
+export declare function cursorArtSvg(shape: string, color: string, size?: number): string;

package/dist/spaces/cursorArt.js

@@ -0,0 +1,59 @@
+// Generated by libs/cua/scripts/generate-presence-art.mjs from
+// libs/cua/crates/cua-spaces/assets/presence-cursors.json. Do not edit.
+/** Every shape, in wire order. */
+export const CURSOR_SHAPES = Object.freeze([
+    "arrow",
+    "text",
+    "pointer",
+    "resize_ew",
+    "resize_ns",
+    "resize_nwse",
+    "resize_nesw",
+    "move",
+    "crosshair",
+    "wait",
+    "progress",
+    "not_allowed",
+    "grab",
+    "grabbing",
+]);
+/** The shared presence cursor art: fill with the participant's color over the outline. */
+export const CURSOR_ART = Object.freeze({
+    canvas: 32,
+    outline: Object.freeze({ color: "#ffffff", width: 2.5 }),
+    shapes: Object.freeze({
+        arrow: { hotspot: [2, 2], d: "M2 2 L2 24.95 L8.21 19.01 L12.26 28.19 L16.04 26.57 L12.12 17.66 L20.09 17.66 Z" },
+        text: { hotspot: [16, 16], d: "M11 4 L21 4 L21 6.5 L17.25 6.5 L17.25 25.5 L21 25.5 L21 28 L11 28 L11 25.5 L14.75 25.5 L14.75 6.5 L11 6.5 Z" },
+        pointer: { hotspot: [13, 3], d: "M11 5 C11 2.3 15 2.3 15 5 L15 12.5 C15 11 18.5 11 18.5 12.8 C18.5 11.3 22 11.3 22 13.2 C22 11.8 25 11.8 25 13.8 L25 21 C25 25.5 22.5 28 18.5 28 L14.5 28 C11.5 28 10 26.5 8.5 24 L5.2 18.2 C4.3 16.6 6.4 15.2 7.7 16.4 L11 19.5 Z" },
+        resize_ew: { hotspot: [16, 16], d: "M4 16 L10 10 L10 14 L22 14 L22 10 L28 16 L22 22 L22 18 L10 18 L10 22 Z" },
+        resize_ns: { hotspot: [16, 16], d: "M16 4 L22 10 L18 10 L18 22 L22 22 L16 28 L10 22 L14 22 L14 10 L10 10 Z" },
+        resize_nwse: { hotspot: [16, 16], d: "M7.51 7.51 L16 7.51 L13.17 10.34 L21.66 18.83 L24.49 16 L24.49 24.49 L16 24.49 L18.83 21.66 L10.34 13.17 L7.51 16 Z" },
+        resize_nesw: { hotspot: [16, 16], d: "M7.51 24.49 L7.51 16 L10.34 18.83 L18.83 10.34 L16 7.51 L24.49 7.51 L24.49 16 L21.66 13.17 L13.17 21.66 L16 24.49 Z" },
+        move: { hotspot: [16, 16], d: "M16 3 L21 8 L17.5 8 L17.5 14.5 L24 14.5 L24 11 L29 16 L24 21 L24 17.5 L17.5 17.5 L17.5 24 L21 24 L16 29 L11 24 L14.5 24 L14.5 17.5 L8 17.5 L8 21 L3 16 L8 11 L8 14.5 L14.5 14.5 L14.5 8 L11 8 Z" },
+        crosshair: { hotspot: [16, 16], d: "M15 4 L17 4 L17 13 L15 13 Z M15 19 L17 19 L17 28 L15 28 Z M4 15 L13 15 L13 17 L4 17 Z M19 15 L28 15 L28 17 L19 17 Z" },
+        wait: { hotspot: [16, 16], d: "M16 5 C22.08 5 27 9.92 27 16 C27 22.08 22.08 27 16 27 C9.92 27 5 22.08 5 16 C5 9.92 9.92 5 16 5 Z M16 9.5 C12.41 9.5 9.5 12.41 9.5 16 C9.5 19.59 12.41 22.5 16 22.5 C19.59 22.5 22.5 19.59 22.5 16 C22.5 12.41 19.59 9.5 16 9.5 Z M16 16 L16 5 L27 16 Z" },
+        progress: { hotspot: [2, 2], d: "M2 2 L2 24.95 L8.21 19.01 L12.26 28.19 L16.04 26.57 L12.12 17.66 L20.09 17.66 Z M24 18 C27.31 18 30 20.69 30 24 C30 27.31 27.31 30 24 30 C20.69 30 18 27.31 18 24 C18 20.69 20.69 18 24 18 Z M24 20.5 C22.07 20.5 20.5 22.07 20.5 24 C20.5 25.93 22.07 27.5 24 27.5 C25.93 27.5 27.5 25.93 27.5 24 C27.5 22.07 25.93 20.5 24 20.5 Z" },
+        not_allowed: { hotspot: [16, 16], d: "M16 5 C22.08 5 27 9.92 27 16 C27 22.08 22.08 27 16 27 C9.92 27 5 22.08 5 16 C5 9.92 9.92 5 16 5 Z M16 8.5 C11.86 8.5 8.5 11.86 8.5 16 C8.5 20.14 11.86 23.5 16 23.5 C20.14 23.5 23.5 20.14 23.5 16 C23.5 11.86 20.14 8.5 16 8.5 Z M11.93 10.17 L21.83 20.07 L20.07 21.83 L10.17 11.93 Z" },
+        grab: { hotspot: [16, 16], d: "M8 12 C8 9.5 11.5 9.5 11.5 12 L11.5 9 C11.5 6.5 15 6.5 15 9 L15 8 C15 5.5 18.5 5.5 18.5 8 L18.5 9 C18.5 6.5 22 6.5 22 9 L22 13 C22 11 25 11 25 13 L25 20 C25 25 22 28 18 28 L14 28 C10.5 28 8 25.5 8 22 Z" },
+        grabbing: { hotspot: [16, 16], d: "M8 16 C8 13.5 11.5 13.5 11.5 15 C11.5 12.5 15 12.5 15 14.5 C15 12 18.5 12 18.5 14.5 C18.5 12.5 22 12.5 22 15 C22 13.5 25 13.5 25 16 L25 21 C25 25.5 22 28 18 28 L14 28 C10.5 28 8 25.5 8 22 Z" },
+    }),
+});
+/** Whether `name` is a known shape. */
+export function isCursorShape(name) {
+    return typeof name === "string" && Object.prototype.hasOwnProperty.call(CURSOR_ART.shapes, name);
+}
+/** The art for `shape`; unknown names get the arrow. */
+export function cursorArt(shape) {
+    return isCursorShape(shape) ? CURSOR_ART.shapes[shape] : CURSOR_ART.shapes.arrow;
+}
+/**
+ * A standalone SVG of `shape` filled with `color`, `size` pixels square.
+ * The hot spot is at `cursorArt(shape).hotspot * size / CURSOR_ART.canvas`.
+ */
+export function cursorArtSvg(shape, color, size = CURSOR_ART.canvas) {
+    const a = cursorArt(shape);
+    const c = CURSOR_ART.canvas;
+    const fill = /^#[0-9a-fA-F]{3,8}$/.test(color) ? color : "#3b82f6";
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${c} ${c}">` +
+        `<path d="${a.d}" fill="${fill}" stroke="${CURSOR_ART.outline.color}" stroke-width="${CURSOR_ART.outline.width}" stroke-linejoin="round" paint-order="stroke"/></svg>`);
+}

package/dist/spaces/errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Every failure in this SDK is an exception with a stable `code`.
+ *
+ * There is exactly one rule here and it is not negotiable: **no call in this
+ * SDK resolves successfully unless the remote side proved the effect
+ * happened.** Cua has shipped clicks that acked in 3ms and injected nothing,
+ * uploads that reported success for files that never landed, and a decoder
+ * that drained every chunk and emitted nothing. An SDK is where that class of
+ * bug becomes a third party's outage, so the primitives here verify and then
+ * throw rather than return an optimistic value.
+ */
+/** Stable, matchable error codes. Adding a code is a minor release; removing or
+ *  repurposing one is a breaking release. */
+export type SpacesErrorCode = 
+/** Credentials missing or rejected by the token endpoint. */
+'auth'
+/** Transport-level failure: DNS, connect, TLS, socket reset, timeout. */
+ | 'transport'
+/** The control plane answered, but with a non-success status. */
+ | 'http'
+/** The control plane answered with a body this SDK cannot interpret. */
+ | 'protocol'
+/** The caller passed something this SDK rejects before any I/O. */
+ | 'usage'
+/** A Space, thread or run id does not exist (or is no longer bound). */
+ | 'not_found'
+/** A bare name matches Spaces in more than one location; the message lists
+ * the ids to use (`local:<name>`, `cloud:<name>`). */
+ | 'ambiguous_sandbox'
+/** An operation timed out waiting for a remote state change. */
+ | 'timeout'
+/** A file transfer completed but could not be proved intact. */
+ | 'verification'
+/** A shared-Space operation was refused because isolation was not acknowledged. */
+ | 'isolation'
+/** A command ran inside the Space and exited non-zero. */
+ | 'space_command'
+/** The host presentation channel (Cua Spaces desktop app) is not reachable. */
+ | 'host_unavailable'
+/** The requested capability exists in the product but not on this path yet. */
+ | 'unsupported'
+/** The Space's spacesd reports a feature this call needs as unsupported. */
+ | 'capability_missing'
+/** A host-side prerequisite (app sessions, a local runtime) is missing. */
+ | 'host_capability_missing'
+/** The Space has no cua-spacesd. */
+ | 'spacesd_not_available'
+/** The teleport consent gate refused (or the approver declined). */
+ | 'teleport_refused';
+export interface SpacesErrorOptions {
+    cause?: unknown;
+    /** Free-form, already-redacted detail shown in the message. */
+    detail?: string;
+    /** HTTP status, when code is 'http'. */
+    status?: number;
+    /** Request target, for triage. Never carries credentials. */
+    target?: string;
+}
+/** Trim an untrusted body for an error message without hiding it entirely. */
+export declare function excerpt(body: string, max?: number): string;
+export declare class SpacesError extends Error {
+    readonly code: SpacesErrorCode;
+    readonly status: number | undefined;
+    readonly target: string | undefined;
+    readonly detail: string | undefined;
+    constructor(code: SpacesErrorCode, message: string, options?: SpacesErrorOptions);
+    static auth(message: string, options?: SpacesErrorOptions): SpacesError;
+    static usage(message: string, options?: SpacesErrorOptions): SpacesError;
+    static protocol(message: string, options?: SpacesErrorOptions): SpacesError;
+    static timeout(message: string, options?: SpacesErrorOptions): SpacesError;
+}
+/** Narrowing helper for consumers: `if (isSpacesError(e, 'verification')) …` */
+export declare function isSpacesError(value: unknown, code?: SpacesErrorCode): value is SpacesError;
+/**
+ * Wraps anything the native SDK threw as a {@link SpacesError} with a stable
+ * code (the `CuaError` variant stays reachable as `cause`). Already-wrapped
+ * errors pass through.
+ */
+export declare function toSpacesError(error: unknown): SpacesError;
+/** Runs `body`, rethrowing native errors as {@link SpacesError}. */
+export declare function wrapErrors<T>(body: () => Promise<T>): Promise<T>;

package/dist/spaces/errors.js

@@ -0,0 +1,102 @@
+/**
+ * Every failure in this SDK is an exception with a stable `code`.
+ *
+ * There is exactly one rule here and it is not negotiable: **no call in this
+ * SDK resolves successfully unless the remote side proved the effect
+ * happened.** Cua has shipped clicks that acked in 3ms and injected nothing,
+ * uploads that reported success for files that never landed, and a decoder
+ * that drained every chunk and emitted nothing. An SDK is where that class of
+ * bug becomes a third party's outage, so the primitives here verify and then
+ * throw rather than return an optimistic value.
+ */
+/** Trim an untrusted body for an error message without hiding it entirely. */
+export function excerpt(body, max = 400) {
+    const flat = body.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max)}… (${flat.length} bytes)`;
+}
+export class SpacesError extends Error {
+    code;
+    status;
+    target;
+    detail;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'SpacesError';
+        this.code = code;
+        this.status = options.status;
+        this.target = options.target;
+        this.detail = options.detail;
+    }
+    static auth(message, options) {
+        return new SpacesError('auth', message, options);
+    }
+    static usage(message, options) {
+        return new SpacesError('usage', message, options);
+    }
+    static protocol(message, options) {
+        return new SpacesError('protocol', message, options);
+    }
+    static timeout(message, options) {
+        return new SpacesError('timeout', message, options);
+    }
+}
+/** Narrowing helper for consumers: `if (isSpacesError(e, 'verification')) …` */
+export function isSpacesError(value, code) {
+    return value instanceof SpacesError && (code === undefined || value.code === code);
+}
+/** Maps a `CuaError` variant tag (from the native binding) to a code. */
+const CUA_TAGS = {
+    InvalidArgument: 'usage',
+    NotFound: 'not_found',
+    AmbiguousSandbox: 'ambiguous_sandbox',
+    ProviderNotConfigured: 'auth',
+    Unsupported: 'unsupported',
+    SpacesdNotAvailable: 'spacesd_not_available',
+    Timeout: 'timeout',
+    Fleet: 'http',
+    // Fleet's admission refused a size over the account's limits (Fleet's
+    // message names the limit): pick a smaller size.
+    FleetAdmissionDenied: 'usage',
+    // Out of Cua Cloud credit (the message names the billing page): add
+    // credit there, or run locally.
+    CloudCreditExhausted: 'usage',
+    Runtime: 'space_command',
+    Env: 'space_command',
+    Http: 'http',
+    Unauthenticated: 'auth',
+    PermissionDenied: 'auth',
+    Transport: 'transport',
+    // No `cua daemon` answers (start Cua, or run `cua daemon start`).
+    DaemonNotRunning: 'transport',
+    Closed: 'transport',
+    CapabilityMissing: 'capability_missing',
+    HostCapabilityMissing: 'host_capability_missing',
+    TeleportRefused: 'teleport_refused',
+    Internal: 'protocol',
+    // A pull, build or VM create would fill the disk (`cua cache prune`).
+    InsufficientDisk: 'space_command',
+    // A catalog image CI has not published yet (pass the ref explicitly).
+    ImageNotPublished: 'not_found',
+};
+/**
+ * Wraps anything the native SDK threw as a {@link SpacesError} with a stable
+ * code (the `CuaError` variant stays reachable as `cause`). Already-wrapped
+ * errors pass through.
+ */
+export function toSpacesError(error) {
+    if (error instanceof SpacesError)
+        return error;
+    const tag = error?.tag;
+    const code = typeof tag === 'string' ? CUA_TAGS[tag] : undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    return new SpacesError(code ?? 'protocol', message, { cause: error });
+}
+/** Runs `body`, rethrowing native errors as {@link SpacesError}. */
+export async function wrapErrors(body) {
+    try {
+        return await body();
+    }
+    catch (error) {
+        throw toSpacesError(error);
+    }
+}

package/dist/spaces/events.d.ts

@@ -0,0 +1,154 @@
+/**
+ * What an agent sends back.
+ *
+ * The honest situation, as of this release: the agent runtime inside a Space is
+ * a terminal. `agent_status` returns the tail of the run's output (the agent
+ * runs as a detached, tagged cua-spacesd process). There is no structured
+ * result channel yet — no file manifest, no image parts, no approval
+ * protocol. The supported agents are launched auto-approved and the sandbox is
+ * the safety boundary.
+ *
+ * So this module does two things and is careful about the difference:
+ *
+ *  1. It defines the *result model* a chat app with agent coworkers needs — text, files,
+ *     images, links, approval requests — as a stable discriminated union, so an
+ *     app can be written against it today and keep working when the runtime
+ *     starts emitting the real thing.
+ *  2. It derives what it can from the terminal transcript, and marks every
+ *     derived event `derived: true`. A consumer can therefore tell a fact
+ *     ("the agent emitted this file") from an inference ("a path-shaped string
+ *     appeared in the scrollback"). Nothing here pretends to be ground truth.
+ *
+ * When the agent runtime gains a structured channel (see `docs/`), the adapter
+ * gains a branch that emits the same events with `derived: false`. The union is
+ * the stable contract; the adapter is not.
+ */
+export type ThreadEventKind = 'text' | 'file' | 'image' | 'link' | 'approval_request' | 'state' | 'error';
+interface ThreadEventBase {
+    kind: ThreadEventKind;
+    /** Monotonic within a thread, assigned by the SDK. */
+    seq: number;
+    /** Wall clock at the moment the SDK observed it, not when the agent produced it. */
+    observedAt: string;
+    /**
+     * `true` when this event was inferred from unstructured terminal output
+     * rather than reported by the agent runtime. Always check it before treating
+     * an event as authoritative.
+     */
+    derived: boolean;
+}
+export interface TextEvent extends ThreadEventBase {
+    kind: 'text';
+    text: string;
+}
+/** A file the agent appears to have produced, by absolute path inside the Space.
+ *  Fetch it with `space.download(path, destDir)` — the SDK does not pre-fetch. */
+export interface FileEvent extends ThreadEventBase {
+    kind: 'file';
+    path: string;
+}
+/** An image the agent produced. `data` is base64; `path` is set instead when the
+ *  image is only known by its in-Space location. */
+export interface ImageEvent extends ThreadEventBase {
+    kind: 'image';
+    mimeType: string;
+    data?: string;
+    path?: string;
+}
+export interface LinkEvent extends ThreadEventBase {
+    kind: 'link';
+    url: string;
+}
+/**
+ * The agent is blocked on a human decision.
+ *
+ * No agent runtime in a Space emits this today (they run auto-approved). It is
+ * defined because an app that puts an agent in front of a user needs the shape,
+ * and because a derived detector can spot a REPL prompt that is waiting. Answer
+ * it with `thread.send(...)` — there is no separate approval RPC yet, and this
+ * SDK will not invent one that silently does nothing.
+ */
+export interface ApprovalRequestEvent extends ThreadEventBase {
+    kind: 'approval_request';
+    prompt: string;
+    /** Choices parsed from the prompt, when they were parseable. */
+    options: string[];
+}
+export interface StateEvent extends ThreadEventBase {
+    kind: 'state';
+    state: AgentStatus;
+    /** The ladder's reason for this status. */
+    reason: string;
+}
+export interface ErrorEvent extends ThreadEventBase {
+    kind: 'error';
+    message: string;
+}
+export type ThreadEvent = TextEvent | FileEvent | ImageEvent | LinkEvent | ApprovalRequestEvent | StateEvent | ErrorEvent;
+/**
+ * The agent status ladder — one closed vocabulary for every harness and every
+ * provider. A UI can rely on this being closed.
+ *
+ * `idle` and `finished` are deliberately different: both mean "no turn is
+ * running", but `idle` means the session can still be continued and `finished`
+ * means it cannot.
+ *
+ * `unknown` is a real, reachable state and is **not** a synonym for "done". A
+ * probe that could not run, an unreachable Space, and an interactive REPL whose
+ * working-vs-waiting we cannot tell apart all land here. Reporting any of them
+ * as `idle` is how a caller concludes an agent finished when the Space actually
+ * fell over — and `crashed` exists so a dead process that never recorded an
+ * exit status is never read as a clean finish.
+ */
+export type AgentStatus = 'running' | 'awaiting_input' | 'idle' | 'finished' | 'failed' | 'crashed' | 'unknown';
+/** Everything the SDK knows about a run's current moment. */
+export interface ThreadStatus {
+    runId: string;
+    status: AgentStatus;
+    /** Why the ladder landed there, in words. Always populated. */
+    reason: string;
+    /** A follow-up sent now starts the next turn: the server's published
+     *  rule (idle, or a crashed or failed run it restarts; not mid-turn). */
+    acceptsMessage: boolean;
+    /** The raw transcript tail exactly as the Space reported it. Always present,
+     *  because every derived event above is an interpretation of this. */
+    transcript: string;
+    /** The agent's terminal window on the Space desktop, when it was found.
+     *  `null` means "not found", which is not the same as "does not exist". */
+    desktopWindow: string | null;
+}
+/**
+ * Turns a growing transcript into events, without re-emitting what it already
+ * emitted.
+ *
+ * The runtime gives us a *tail*, not a stream, so the adapter tracks what it has
+ * consumed by content, not by offset: a tail that scrolled past our last known
+ * position is detected, and only the portion it can prove is new is emitted.
+ * When it cannot prove overlap at all — the tail
+ * scrolled entirely past — it emits the whole tail and an `error` event saying
+ * output was lost, rather than silently dropping it.
+ */
+export declare class TranscriptAdapter {
+    private consumed;
+    private seq;
+    /** Feed the newest transcript tail; get back only the newly observed events. */
+    ingest(tail: string, now?: () => Date): ThreadEvent[];
+    /** Reset for a new turn that restarts the session (codex `resume` does this). */
+    reset(): void;
+    private diff;
+    private extract;
+    private make;
+}
+/**
+ * Spot a terminal prompt that is waiting on a human.
+ *
+ * Only fires on a prompt at the very end of the fresh output — a question in
+ * the middle of the scrollback has already been answered. Recognizes the two
+ * common shapes: a `[y/N]`-style suffix and a numbered choice list followed by
+ * a prompt line.
+ */
+export declare function detectApproval(fresh: string): {
+    prompt: string;
+    options: string[];
+} | null;
+export {};