@trycua/cua 0.2.0

package/dist/spaces/events.js

@@ -0,0 +1,182 @@
+/**
+ * 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.
+ */
+/**
+ * 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 class TranscriptAdapter {
+    consumed = '';
+    seq = 0;
+    /** Feed the newest transcript tail; get back only the newly observed events. */
+    ingest(tail, now = () => new Date()) {
+        const events = [];
+        const fresh = this.diff(tail, events, now);
+        if (fresh === '')
+            return events;
+        this.consumed = tail;
+        for (const event of this.extract(fresh, now))
+            events.push(event);
+        return events;
+    }
+    /** Reset for a new turn that restarts the session (codex `resume` does this). */
+    reset() {
+        this.consumed = '';
+    }
+    diff(tail, events, now) {
+        if (this.consumed === '')
+            return tail;
+        if (tail === this.consumed)
+            return '';
+        if (tail.startsWith(this.consumed))
+            return tail.slice(this.consumed.length);
+        // The window scrolled. Find the longest suffix of `consumed` that prefixes
+        // `tail`; everything after it is new.
+        const max = Math.min(this.consumed.length, tail.length);
+        for (let overlap = max; overlap > 0; overlap--) {
+            if (tail.startsWith(this.consumed.slice(this.consumed.length - overlap))) {
+                return tail.slice(overlap);
+            }
+        }
+        events.push(this.make({
+            kind: 'error',
+            message: 'transcript scrolled past the polled window; output between the last poll and this one was lost',
+        }, now));
+        return tail;
+    }
+    *extract(fresh, now) {
+        const text = fresh.trim();
+        if (text !== '')
+            yield this.make({ kind: 'text', text }, now);
+        for (const url of matchAll(fresh, URL_PATTERN)) {
+            yield this.make({ kind: 'link', url: trimTrailingPunctuation(url) }, now);
+        }
+        for (const path of matchAll(fresh, PATH_PATTERN)) {
+            const clean = trimTrailingPunctuation(path);
+            if (IMAGE_SUFFIX.test(clean)) {
+                yield this.make({ kind: 'image', mimeType: mimeForPath(clean), path: clean }, now);
+            }
+            else {
+                yield this.make({ kind: 'file', path: clean }, now);
+            }
+        }
+        const approval = detectApproval(fresh);
+        if (approval) {
+            yield this.make({ kind: 'approval_request', prompt: approval.prompt, options: approval.options }, now);
+        }
+    }
+    make(partial, now) {
+        return {
+            ...partial,
+            seq: this.seq++,
+            observedAt: now().toISOString(),
+            derived: true,
+        };
+    }
+}
+// -- derivation heuristics, deliberately conservative -----------------------
+const URL_PATTERN = /\bhttps?:\/\/[^\s<>"')\]]+/g;
+/** Absolute POSIX paths only, with a file extension. A bare `/root` is a
+ *  directory mention, not a produced artefact, and is not reported. */
+const PATH_PATTERN = /(?<![\w:/])\/(?:[\w.@+-]+\/)+[\w.@+-]+\.[A-Za-z0-9]{1,8}\b/g;
+const IMAGE_SUFFIX = /\.(png|jpe?g|gif|webp|bmp|svg)$/i;
+function mimeForPath(path) {
+    const suffix = path.toLowerCase().split('.').pop() ?? '';
+    if (suffix === 'jpg' || suffix === 'jpeg')
+        return 'image/jpeg';
+    if (suffix === 'svg')
+        return 'image/svg+xml';
+    if (suffix === 'gif')
+        return 'image/gif';
+    if (suffix === 'webp')
+        return 'image/webp';
+    if (suffix === 'bmp')
+        return 'image/bmp';
+    return 'image/png';
+}
+function matchAll(text, pattern) {
+    const out = [];
+    const seen = new Set();
+    for (const match of text.matchAll(pattern)) {
+        const value = match[0];
+        if (!seen.has(value)) {
+            seen.add(value);
+            out.push(value);
+        }
+    }
+    return out;
+}
+function trimTrailingPunctuation(value) {
+    return value.replace(/[).,;:'"\]]+$/, '');
+}
+/**
+ * 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 function detectApproval(fresh) {
+    const lines = fresh.split(/\r?\n/);
+    let lastIndex = lines.length - 1;
+    while (lastIndex >= 0 && (lines[lastIndex] ?? '').trim() === '')
+        lastIndex--;
+    if (lastIndex < 0)
+        return null;
+    const tail = (lines[lastIndex] ?? '').trim();
+    const yesNo = tail.match(/(.*?)\s*[[(]\s*(y(?:es)?)\s*\/\s*(n(?:o)?)\s*[\])]\s*[?:]?\s*$/i);
+    if (yesNo) {
+        return {
+            prompt: (yesNo[1] ?? '').trim() || tail,
+            options: [yesNo[2] ?? 'y', yesNo[3] ?? 'n'],
+        };
+    }
+    // A numbered menu: collect contiguous "1) …" / "2. …" lines above the prompt.
+    const options = [];
+    let cursor = lastIndex;
+    const promptLooksLikeQuestion = /[?:]\s*$/.test(tail) || /^[>❯]/.test(tail);
+    if (!promptLooksLikeQuestion)
+        return null;
+    cursor--;
+    while (cursor >= 0) {
+        const candidate = (lines[cursor] ?? '').trim();
+        const numbered = candidate.match(/^(\d+)\s*[).]\s+(.*)$/);
+        if (!numbered)
+            break;
+        options.unshift(numbered[2] ?? '');
+        cursor--;
+    }
+    if (options.length < 2)
+        return null;
+    return { prompt: tail, options };
+}

package/dist/spaces/groups.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `@trycua/cua/spaces/groups`: group chats, one human and two to six Bots in
+ * one thread. No native library, no Node imports.
+ *
+ * A group chat is a fan-out over the members' own agent threads in the one
+ * shared Space plus a merged, attributed transcript; it is not a new kind of
+ * agent. The harness gives a Bot no way to know who else is in the room, so
+ * every message is framed with the room ({@link frameGroupMessage}).
+ * Delivery is per member and partial success is normal: a Bot mid-turn
+ * refuses, and the refusal lands in the transcript as a marked line.
+ *
+ * ```ts
+ * import { GroupChatStore } from "@trycua/cua/spaces/groups"
+ *
+ * const groups = new GroupChatStore(messenger)          // deliver / latestReply / isWorking / displayName
+ * const chat = groups.create("Launch", ["ada", "bo"])   // throws outside 2..6
+ * await groups.send("Where are we?", chat.id)
+ * await groups.collectReplies(chat.id)                  // poll; never duplicates a line
+ * ```
+ */
+/** The product bound: a group of one is a thread; every message fans out to every member. */
+export declare const GROUP_MIN_BOTS = 2;
+export declare const GROUP_MAX_BOTS = 6;
+export type GroupChatErrorCode = "tooFewBots" | "tooManyBots" | "full" | "atFloor" | "alreadyAMember" | "notAMember" | "unknownChat";
+/** A membership rule was broken. The message says which number. */
+export declare class GroupChatError extends Error {
+    readonly code: GroupChatErrorCode;
+    constructor(code: GroupChatErrorCode, message: string);
+    static tooFewBots(have: number): GroupChatError;
+    static tooManyBots(have: number): GroupChatError;
+    static full(): GroupChatError;
+    static atFloor(): GroupChatError;
+    static alreadyAMember(id: string): GroupChatError;
+    static notAMember(id: string): GroupChatError;
+    static unknownChat(id: string): GroupChatError;
+}
+/** Who said a line: the human, a Bot, or the group itself (joins, leaves, refusals). */
+export type GroupSpeaker = {
+    kind: "human";
+} | {
+    kind: "bot";
+    botID: string;
+} | {
+    kind: "system";
+};
+export interface GroupMessage {
+    id: string;
+    speaker: GroupSpeaker;
+    text: string;
+    at: string;
+    /** This line records a message that did not reach its Bot. */
+    undelivered: boolean;
+    reaction?: string;
+}
+/** The result of fanning one message out to one member. */
+export interface GroupDelivery {
+    botID: string;
+    accepted: boolean;
+    reason: string;
+}
+/** How a group reaches its Bots. `deliver` never throws: a refusal is a result. */
+export interface GroupMessenger {
+    deliver(text: string, botID: string): Promise<GroupDelivery>;
+    /** The Bot's most recent utterance, or `undefined`. */
+    latestReply(botID: string): Promise<string | undefined>;
+    /** Whether the Bot is producing output right now (the typing row). */
+    isWorking(botID: string): boolean;
+    displayName(botID: string): string;
+}
+/** Whether a Create button should be enabled for `members`. */
+export declare function canCreateGroup(members: readonly string[]): boolean;
+/** A group chat. The 2..6 bound holds for every instance: construction and membership changes throw. */
+export declare class GroupChat {
+    readonly id: string;
+    title: string;
+    readonly createdAt: string;
+    messages: GroupMessage[];
+    private members;
+    constructor(title: string, members: readonly string[], options?: {
+        id?: string;
+        createdAt?: Date;
+    });
+    /** Bot ids in join order. The human is implicit. */
+    get memberIDs(): readonly string[];
+    get isFull(): boolean;
+    get isAtFloor(): boolean;
+    /** `4 of 6 bots`. */
+    get membershipLabel(): string;
+    get remainingSeats(): number;
+    add(botID: string): void;
+    remove(botID: string): void;
+}
+/**
+ * The framing each member receives: the room, then the human's words on the
+ * last line (so an agent that reads the last line still sees them).
+ */
+export declare function frameGroupMessage(text: string, botID: string, chat: GroupChat, name: (botID: string) => string): string;
+/** Group chats: membership, fan-out, and the merged transcript. */
+export declare class GroupChatStore {
+    private messenger?;
+    chats: GroupChat[];
+    /** The last membership complaint, cleared on the next success. */
+    lastError: string | undefined;
+    /** Bots producing output right now, per chat. */
+    readonly working: Map<string, Set<string>>;
+    /** chat -> bot -> the last reply already folded in, so a re-poll cannot duplicate it. */
+    private readonly consumed;
+    private readonly listeners;
+    constructor(messenger?: GroupMessenger | undefined);
+    attach(messenger: GroupMessenger): void;
+    subscribe(fn: () => void): () => void;
+    private changed;
+    chat(id: string): GroupChat | undefined;
+    displayName(botID: string): string;
+    private require;
+    private line;
+    create(title: string, members: readonly string[]): GroupChat;
+    delete(id: string): void;
+    add(botID: string, chatID: string): void;
+    remove(botID: string, chatID: string): void;
+    private mutate;
+    /** Sends one message to every member; returns each member's delivery. */
+    send(text: string, chatID: string): Promise<GroupDelivery[]>;
+    /** Folds what members said since the last poll into the transcript, attributed. */
+    collectReplies(chatID: string): Promise<GroupMessage[]>;
+    /** Attaches a reaction to the last line. */
+    react(emoji: string, chatID: string): void;
+    refreshWorking(chatID: string): void;
+    workingBots(chatID: string): string[];
+}

package/dist/spaces/groups.js

@@ -0,0 +1,275 @@
+/**
+ * `@trycua/cua/spaces/groups`: group chats, one human and two to six Bots in
+ * one thread. No native library, no Node imports.
+ *
+ * A group chat is a fan-out over the members' own agent threads in the one
+ * shared Space plus a merged, attributed transcript; it is not a new kind of
+ * agent. The harness gives a Bot no way to know who else is in the room, so
+ * every message is framed with the room ({@link frameGroupMessage}).
+ * Delivery is per member and partial success is normal: a Bot mid-turn
+ * refuses, and the refusal lands in the transcript as a marked line.
+ *
+ * ```ts
+ * import { GroupChatStore } from "@trycua/cua/spaces/groups"
+ *
+ * const groups = new GroupChatStore(messenger)          // deliver / latestReply / isWorking / displayName
+ * const chat = groups.create("Launch", ["ada", "bo"])   // throws outside 2..6
+ * await groups.send("Where are we?", chat.id)
+ * await groups.collectReplies(chat.id)                  // poll; never duplicates a line
+ * ```
+ */
+/** The product bound: a group of one is a thread; every message fans out to every member. */
+export const GROUP_MIN_BOTS = 2;
+export const GROUP_MAX_BOTS = 6;
+/** A membership rule was broken. The message says which number. */
+export class GroupChatError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GroupChatError";
+    }
+    static tooFewBots(have) {
+        return new GroupChatError("tooFewBots", `A group chat needs at least ${GROUP_MIN_BOTS} bots; ${have} selected.`);
+    }
+    static tooManyBots(have) {
+        return new GroupChatError("tooManyBots", `A group chat holds at most ${GROUP_MAX_BOTS} bots; ${have} selected.`);
+    }
+    static full() {
+        return new GroupChatError("full", `This group is full: ${GROUP_MAX_BOTS} bots is the limit. Remove one to add another.`);
+    }
+    static atFloor() {
+        return new GroupChatError("atFloor", `A group chat needs at least ${GROUP_MIN_BOTS} bots. Add one before removing this one.`);
+    }
+    static alreadyAMember(id) {
+        return new GroupChatError("alreadyAMember", `${id} is already in this group.`);
+    }
+    static notAMember(id) {
+        return new GroupChatError("notAMember", `${id} is not in this group.`);
+    }
+    static unknownChat(id) {
+        return new GroupChatError("unknownChat", `No such group chat: ${id}`);
+    }
+}
+function newId() {
+    return globalThis.crypto.randomUUID().toUpperCase();
+}
+function dedupe(ids) {
+    const out = [];
+    for (const id of ids)
+        if (!out.includes(id))
+            out.push(id);
+    return out;
+}
+/** Whether a Create button should be enabled for `members`. */
+export function canCreateGroup(members) {
+    const n = new Set(members).size;
+    return n >= GROUP_MIN_BOTS && n <= GROUP_MAX_BOTS;
+}
+/** A group chat. The 2..6 bound holds for every instance: construction and membership changes throw. */
+export class GroupChat {
+    id;
+    title;
+    createdAt;
+    messages = [];
+    members;
+    constructor(title, members, options = {}) {
+        const d = dedupe(members);
+        if (d.length < GROUP_MIN_BOTS)
+            throw GroupChatError.tooFewBots(d.length);
+        if (d.length > GROUP_MAX_BOTS)
+            throw GroupChatError.tooManyBots(d.length);
+        this.id = options.id ?? newId();
+        this.title = title;
+        this.createdAt = (options.createdAt ?? new Date()).toISOString();
+        this.members = d;
+    }
+    /** Bot ids in join order. The human is implicit. */
+    get memberIDs() {
+        return this.members;
+    }
+    get isFull() {
+        return this.members.length >= GROUP_MAX_BOTS;
+    }
+    get isAtFloor() {
+        return this.members.length <= GROUP_MIN_BOTS;
+    }
+    /** `4 of 6 bots`. */
+    get membershipLabel() {
+        return `${this.members.length} of ${GROUP_MAX_BOTS} bots`;
+    }
+    get remainingSeats() {
+        return Math.max(0, GROUP_MAX_BOTS - this.members.length);
+    }
+    add(botID) {
+        if (this.members.includes(botID))
+            throw GroupChatError.alreadyAMember(botID);
+        if (this.isFull)
+            throw GroupChatError.full();
+        this.members.push(botID);
+    }
+    remove(botID) {
+        if (!this.members.includes(botID))
+            throw GroupChatError.notAMember(botID);
+        if (this.isAtFloor)
+            throw GroupChatError.atFloor();
+        this.members = this.members.filter((m) => m !== botID);
+    }
+}
+/**
+ * The framing each member receives: the room, then the human's words on the
+ * last line (so an agent that reads the last line still sees them).
+ */
+export function frameGroupMessage(text, botID, chat, name) {
+    const others = chat.memberIDs
+        .filter((m) => m !== botID)
+        .map(name)
+        .join(", ");
+    return `[group:${chat.title}] You are in a group chat with the user and ${others}. Answer for your own area only and keep it to a few lines.\n${text}`;
+}
+/** Group chats: membership, fan-out, and the merged transcript. */
+export class GroupChatStore {
+    messenger;
+    chats = [];
+    /** The last membership complaint, cleared on the next success. */
+    lastError;
+    /** Bots producing output right now, per chat. */
+    working = new Map();
+    /** chat -> bot -> the last reply already folded in, so a re-poll cannot duplicate it. */
+    consumed = new Map();
+    listeners = new Set();
+    constructor(messenger) {
+        this.messenger = messenger;
+    }
+    attach(messenger) {
+        this.messenger = messenger;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    changed() {
+        for (const l of this.listeners)
+            l();
+    }
+    chat(id) {
+        return this.chats.find((c) => c.id === id);
+    }
+    displayName(botID) {
+        return this.messenger?.displayName(botID) ?? botID;
+    }
+    require(id) {
+        const c = this.chat(id);
+        if (!c)
+            throw GroupChatError.unknownChat(id);
+        return c;
+    }
+    line(chat, speaker, text, undelivered = false) {
+        chat.messages.push({ id: newId(), speaker, text, at: new Date().toISOString(), undelivered });
+    }
+    create(title, members) {
+        const chat = new GroupChat(title, members);
+        this.chats.push(chat);
+        this.lastError = undefined;
+        this.changed();
+        return chat;
+    }
+    delete(id) {
+        this.chats = this.chats.filter((c) => c.id !== id);
+        this.consumed.delete(id);
+        this.working.delete(id);
+        this.changed();
+    }
+    add(botID, chatID) {
+        this.mutate(chatID, (c) => c.add(botID), (c) => `${this.displayName(botID)} joined, ${c.membershipLabel}.`);
+    }
+    remove(botID, chatID) {
+        this.mutate(chatID, (c) => c.remove(botID), (c) => `${this.displayName(botID)} left, ${c.membershipLabel}.`);
+    }
+    mutate(chatID, op, announce) {
+        const chat = this.require(chatID);
+        try {
+            op(chat);
+            this.line(chat, { kind: "system" }, announce(chat));
+            this.lastError = undefined;
+        }
+        catch (e) {
+            const text = e instanceof Error ? e.message : String(e);
+            this.lastError = text;
+            this.line(chat, { kind: "system" }, text, true);
+            this.changed();
+            throw e;
+        }
+        this.changed();
+    }
+    /** Sends one message to every member; returns each member's delivery. */
+    async send(text, chatID) {
+        const chat = this.chat(chatID);
+        if (!chat)
+            return [];
+        this.line(chat, { kind: "human" }, text);
+        this.changed();
+        const out = [];
+        for (const botID of chat.memberIDs) {
+            const framed = frameGroupMessage(text, botID, chat, (id) => this.displayName(id));
+            let d;
+            if (!this.messenger)
+                d = { botID, accepted: false, reason: "not connected to a Space" };
+            else {
+                try {
+                    d = await this.messenger.deliver(framed, botID);
+                }
+                catch (e) {
+                    d = { botID, accepted: false, reason: e instanceof Error ? e.message : String(e) };
+                }
+            }
+            out.push(d);
+            if (!d.accepted)
+                this.line(chat, { kind: "bot", botID }, `Did not receive that message: ${d.reason}`, true);
+        }
+        this.refreshWorking(chatID);
+        this.changed();
+        return out;
+    }
+    /** Folds what members said since the last poll into the transcript, attributed. */
+    async collectReplies(chatID) {
+        const chat = this.chat(chatID);
+        if (!chat || !this.messenger)
+            return [];
+        const added = [];
+        for (const botID of chat.memberIDs) {
+            const reply = (await this.messenger.latestReply(botID))?.trim();
+            if (!reply)
+                continue;
+            const seen = this.consumed.get(chatID) ?? new Map();
+            if (seen.get(botID) === reply)
+                continue;
+            seen.set(botID, reply);
+            this.consumed.set(chatID, seen);
+            this.line(chat, { kind: "bot", botID }, reply);
+            added.push(chat.messages[chat.messages.length - 1]);
+        }
+        this.refreshWorking(chatID);
+        if (added.length)
+            this.changed();
+        return added;
+    }
+    /** Attaches a reaction to the last line. */
+    react(emoji, chatID) {
+        const last = this.chat(chatID)?.messages.at(-1);
+        if (!last)
+            return;
+        last.reaction = emoji;
+        this.changed();
+    }
+    refreshWorking(chatID) {
+        const chat = this.chat(chatID);
+        if (!chat || !this.messenger)
+            return;
+        const m = this.messenger;
+        this.working.set(chatID, new Set(chat.memberIDs.filter((b) => m.isWorking(b))));
+    }
+    workingBots(chatID) {
+        return [...(this.working.get(chatID) ?? [])].sort();
+    }
+}

package/dist/spaces/host.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `@trycua/cua/spaces/host` — the host presentation adapter. **Explicitly unstable.**
+ *
+ * This is the one thing the SDK itself cannot do: put a Space on
+ * the *operator's own Mac desktop* — pinned as picture-in-picture, opened in a
+ * viewer window, or a single Space window streamed back bidirectionally over
+ * rcdp.
+ *
+ * It talks to the loopback control server inside the Cua Spaces desktop app,
+ * discovered through `$CUA_HOME/spaces-control.json` (default `~/.cua`; `{port, token}`). That means
+ * all of the following, and you should assume all of it will change:
+ *
+ *  - it only works on the machine where the app is running, as the user who
+ *    owns that home directory;
+ *  - the port is ephemeral and the token is regenerated on every app launch;
+ *  - a Local Space's rcdp token rotates on every rcdpd restart, so a token read
+ *    once and cached will start failing — `streamWindow` takes a fresh one;
+ *  - the control server resolves `local:<vm>` ids only. `pin` and `openViewer`
+ *    with any other id are rejected by the app with HTTP 400, and this adapter
+ *    says so rather than reporting success.
+ *
+ * Every method throws `host_unavailable` when the app is not running. None of
+ * them degrades to a silent no-op — a `forget_rcdp_token` with zero callers is
+ * exactly the kind of thing this codebase has shipped before.
+ */
+export interface ControlEndpoint {
+    port: number;
+    token: string;
+}
+export interface HostPresentationOptions {
+    /** Override the discovery file. Mostly for tests. */
+    controlFile?: string;
+    /** Inject a fetch (tests, or a different agent). */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/** `$CUA_HOME` when set and non-empty, else `~/.cua` (the Rust core's rule). */
+export declare function cuaHome(home: string, env?: Record<string, string | undefined>): string;
+/** Read `{port, token}` from the app's control file. */
+export declare function readControlEndpoint(controlFile?: string): Promise<ControlEndpoint>;
+export declare class HostPresentation {
+    private readonly options;
+    constructor(options?: HostPresentationOptions);
+    /** Pin a Local Space as picture-in-picture on this Mac's desktop. */
+    pin(spaceId: string): Promise<void>;
+    unpin(spaceId: string): Promise<void>;
+    /** Open the full viewer window for a Local Space. */
+    openViewer(spaceId: string): Promise<void>;
+    /**
+     * Stream one window of a Local Space back to a bidirectional window here.
+     *
+     * `rcdpToken` must be read fresh: a Local Space's rcdp token rotates on every
+     * rcdpd restart, so a cached one silently stops working.
+     *
+     * `replica: true` opens an *additional* stream for the same target rather
+     * than focusing the existing one. Note the real limit: only one page per app
+     * can hardware-decode H.264, so a second concurrent stream falls back to an
+     * uncompressed codec and is visibly heavier.
+     */
+    streamWindow(input: {
+        spaceId: string;
+        windowId: string;
+        rcdpToken: string;
+        appName?: string;
+        title?: string;
+        replica?: boolean;
+    }): Promise<void>;
+    /** Is the desktop app reachable right now? */
+    available(): Promise<boolean>;
+    private assertLocal;
+    private post;
+}