linkshell-cli 0.9.0 → 0.10.1

package/dist/host/src/drivers/codex/desktop-ipc.js

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// The Codex desktop app and its IDE extension keep the threads they run in
+// app-servers of their own, which take no other clients. What they do share
+// is a message bus between their windows, on a socket in Codex's home: a
+// window that doesn't run a thread asks the one that does to act on it
+// ("thread-follower-…" requests). That is the only way to stop a turn the
+// desktop app is running without stopping the app.
+//
+// The bus is the app's own, not a published interface: each method carries a
+// version the receiver checks, and a request it doesn't recognise is refused.
+// So everything here is one question with a yes or a no; a no is reported as
+// "can't be stopped from here", never retried in another shape.
+/** Where the desktop app's bus listens (the first Codex window to start serves it). */
+export function desktopBusSocket(env = process.env) {
+    return join(env.CODEX_HOME || join(homedir(), ".codex"), "ipc", "ipc.sock");
+}
+/** The version of the interrupt request the installed apps accept: with the turn it is meant for, or (older) without. */
+const INTERRUPT_VERSION = { withTurn: 4, anyTurn: 3 };
+function frame(message) {
+    const body = Buffer.from(JSON.stringify(message), "utf8");
+    const head = Buffer.alloc(4);
+    head.writeUInt32LE(body.length, 0);
+    return Buffer.concat([head, body]);
+}
+/**
+ * Asks whichever Codex window runs `threadId` to stop its turn, as its own
+ * Stop button does. Resolves when that window says it has; rejects when no
+ * window runs the thread, none answers in time, or the app isn't there.
+ */
+export async function interruptThroughDesktop(socketPath, threadId, turnId, timeoutMs = 12_000) {
+    if (!existsSync(socketPath))
+        throw new Error("the Codex desktop app isn't running");
+    const socket = connect(socketPath);
+    try {
+        await new Promise((resolve, reject) => {
+            socket.once("connect", resolve);
+            socket.once("error", reject);
+        });
+        const bus = busClient(socket, timeoutMs);
+        const registered = await bus.request("initialize", { clientType: "linkshell" }, 0);
+        bus.clientId = String(registered.clientId ?? "");
+        await bus.request("thread-follower-interrupt-turn", { conversationId: threadId, mode: "user-stop", ...(turnId ? { expectedTurnId: turnId } : {}) }, turnId ? INTERRUPT_VERSION.withTurn : INTERRUPT_VERSION.anyTurn);
+    }
+    finally {
+        socket.destroy();
+    }
+}
+/** One connection to the bus: length-prefixed JSON, requests answered by `requestId`. */
+function busClient(socket, timeoutMs) {
+    const pending = new Map();
+    let buffered = Buffer.alloc(0);
+    const failAll = (error) => {
+        for (const waiting of pending.values())
+            waiting.reject(error);
+        pending.clear();
+    };
+    socket.on("data", (chunk) => {
+        buffered = Buffer.concat([buffered, chunk]);
+        while (buffered.length >= 4) {
+            const length = buffered.readUInt32LE(0);
+            if (buffered.length < 4 + length)
+                return;
+            let message;
+            try {
+                message = JSON.parse(buffered.subarray(4, 4 + length).toString("utf8"));
+            }
+            catch {
+                failAll(new Error("the Codex desktop app sent something unreadable"));
+                socket.destroy();
+                return;
+            }
+            buffered = buffered.subarray(4 + length);
+            if (message.type === "response") {
+                const waiting = pending.get(String(message.requestId));
+                if (!waiting)
+                    continue;
+                pending.delete(String(message.requestId));
+                if (message.resultType === "success")
+                    waiting.resolve(message.result);
+                else
+                    waiting.reject(new Error(String(message.error ?? "refused")));
+            }
+            else if (message.type === "client-discovery-request") {
+                // The bus asks every client whether it runs the thread a request is about. Left
+                // unanswered, the asker waits ten seconds for this client; it never does.
+                socket.write(frame({ type: "client-discovery-response", requestId: message.requestId, response: { canHandle: false } }));
+            }
+            else if (message.type === "request") {
+                socket.write(frame({ type: "response", requestId: message.requestId, resultType: "error", error: "no-handler-for-request" }));
+            }
+        }
+    });
+    socket.on("close", () => failAll(new Error("the Codex desktop app closed the connection")));
+    socket.on("error", () => { });
+    const client = {
+        clientId: "initializing-client",
+        request(method, params, version) {
+            const requestId = randomUUID();
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(requestId);
+                    reject(new Error("timeout"));
+                }, timeoutMs);
+                pending.set(requestId, {
+                    resolve: (result) => {
+                        clearTimeout(timer);
+                        resolve(result);
+                    },
+                    reject: (error) => {
+                        clearTimeout(timer);
+                        reject(error);
+                    },
+                });
+                socket.write(frame({ type: "request", requestId, sourceClientId: client.clientId, version, method, params, timeoutMs }));
+            });
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=desktop-ipc.js.map

package/dist/host/src/drivers/codex/desktop-ipc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-ipc.js","sourceRoot":"","sources":["../../../../../../host/src/drivers/codex/desktop-ipc.ts"],"names":[],"mappings":"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"}

package/dist/host/src/drivers/codex/driver.d.ts

@@ -8,10 +8,31 @@ export interface CodexDriverOptions {
     hostVersion: string;
     /** Delay before restarting a crashed app-server; doubles up to 30s. */
     restartDelayMs?: number;
+    /**
+     * Codex's own background server, joined for the threads that live in it
+     * (default: where the installed Codex keeps it). `false`: never.
+     */
+    sharedSocketPath?: string | false;
+    /**
+     * The bus the Codex desktop app's windows share, through which it is asked
+     * to stop a turn it runs (default: where the installed Codex keeps it). `false`: never.
+     */
+    desktopBusPath?: string | false;
+    /** How often a thread that can only be read is looked at again. */
+    observeIntervalMs?: number;
+    /** How long a thread no device has open, and that isn't working, stays joined. */
+    releaseDelayMs?: number;
 }
 /**
  * Codex, tier multi_client: LinkShell and the desktop TUI (`codex --remote`)
  * are both clients of one app-server, so every thread is live on both sides.
+ *
+ * Codex lets one process have a thread loaded at a time. A thread loaded in
+ * Codex's own background server (a plain `codex` in a terminal) is joined
+ * there, as one more client. A thread in a process that takes no other
+ * clients (the desktop app, an IDE extension) is read from disk as that
+ * process writes it; a message for it goes into Codex's own queue, which that
+ * process starts when it is idle; and its turn is stopped by asking the app.
  */
 export declare class CodexDriver implements AgentDriver {
     private readonly options;
@@ -52,12 +73,35 @@ export declare class CodexDriver implements AgentDriver {
     private restartTimer?;
     private restartDelay;
     private stopped;
+    private shared?;
+    /** Threads loaded in Codex's background server: announced by it, or joined there. */
+    private readonly inShared;
+    private readonly observed;
+    private readonly takingUp;
+    /** Messages in Codex's own queue for threads another process holds: it starts them when it is idle or its turn ends. */
+    private readonly waiting;
+    /** Notifications for a thread being joined, held until its history has been read. */
+    private readonly joining;
+    /** Threads a device has open. */
+    private readonly watching;
+    /** Threads another client of this host's app-server opened (`linkshell codex`): followed for as long as the host runs. */
+    private readonly kept;
+    /** Threads started here that have had no turn: nothing on disk yet to come back to. */
+    private readonly fresh;
+    private readonly releases;
+    /** What was last announced per thread (settings, commands): a thread joined again says it only if it changed. */
+    private readonly announced;
+    private readonly observeIntervalMs;
+    private readonly releaseDelayMs;
+    private readonly sharedSocketPath?;
+    private readonly desktopBusPath?;
     constructor(options: CodexDriverOptions);
     status(): DriverStatus;
     start(host: DriverHost): Promise<DriverStatus>;
     authStatus(): Promise<AgentAuth>;
     stop(): Promise<void>;
     listSessions(limit: number): Promise<DiscoveredSession[]>;
+    private stateElsewhere;
     /** Codex's own fork: a new thread with this one's turns, all or through `lastTurnId`, in `cwd`. */
     fork(nativeId: string, options: ForkOptions): Promise<DiscoveredSession>;
     createSession(options: {
@@ -65,10 +109,67 @@ export declare class CodexDriver implements AgentDriver {
         model?: string;
     }): Promise<DiscoveredSession>;
     attach(nativeId: string): Promise<HistoryItem[]>;
+    /**
+     * Subscribes to a thread where it can be driven: this host's app-server, or
+     * Codex's background server when the thread is loaded there. What the
+     * server sends from then on is held until `goLive`.
+     */
+    private subscribe;
+    /** thread/resume where the thread can be loaded: here, or in Codex's background server if it is loaded there. */
+    private resume;
+    /** Says where the joined thread stands, then lets through what arrived while it was being read. */
+    private goLive;
+    /** Reads the thread from disk, and keeps reading while a device has it open. */
+    private observe;
+    /** Reports what the other process has finished since the last look. An item still being written isn't on disk. */
+    private refresh;
+    private report;
+    private stopObserving;
+    /**
+     * Before writing to a thread that could only be read: joins it if whoever
+     * had it has let go, with what they wrote since the last look. Still held,
+     * it stays as it is.
+     */
+    private takeUp;
+    /**
+     * Leaves a message in Codex's own queue for a thread another process holds.
+     * That process starts it when it is idle, or right after the turn it is running.
+     */
+    private enqueue;
+    /** What waits in Codex's queue for the thread, as the session's queue on the devices. */
+    private syncWaiting;
+    private setWaiting;
+    unqueue(nativeId: string, clientMessageId: string): boolean;
+    /** A queued message can't be put into the turn another Codex is running: that turn is stopped, and the queue goes on. */
+    sendQueuedNow(nativeId: string): Promise<void>;
+    /**
+     * Stops the turn a Codex that can't be joined is running. Only its own app
+     * can: it is asked over the bus its windows share.
+     */
+    private stopElsewhere;
+    /**
+     * What a message for a thread held elsewhere is refused with. The apps show
+     * a failed message without its reason, so the reason goes into the session too.
+     */
+    private refused;
+    /** Says, when it becomes so and when it is over, that the session is in a Codex this host can't join. */
+    private reportHeld;
+    /** Whether a device has the session open. */
+    watched(nativeId: string, open: boolean): void;
+    private cancelRelease;
+    /**
+     * A thread stays loaded, and closed to every other Codex program, for as
+     * long as this host is subscribed to it. One that no device has open and
+     * that isn't working is let go after a while, so the desktop app or a
+     * `codex` in a terminal can open it; opening it on a device joins it again.
+     */
+    private considerRelease;
+    private release;
+    private hasApprovals;
     /** Nests each sub-agent's own history right after the call that spawned it. */
     private withSubAgents;
     detach(nativeId: string): Promise<void>;
-    prompt(nativeId: string, content: ContentBlock[], clientMessageId: string): Promise<"started" | "steered">;
+    prompt(nativeId: string, content: ContentBlock[], clientMessageId: string): Promise<"started" | "steered" | "queued">;
     /**
      * `/compact`, `/review`, `/init` and `/<skill>`: what the TUI does for them,
      * through the app-server. Anything else is an ordinary message.
@@ -79,6 +180,7 @@ export declare class CodexDriver implements AgentDriver {
     setConfig(nativeId: string, optionId: string, value: string): Promise<void>;
     private loadModels;
     private announceConfig;
+    private isNews;
     private loadSkills;
     /** What `/` offers on a device: the commands above, then the skills this project can use. */
     private announceCommands;
@@ -88,7 +190,7 @@ export declare class CodexDriver implements AgentDriver {
     cancel(nativeId: string): Promise<void>;
     respondPermission(nativeId: string, requestId: string, optionId: string): Promise<void>;
     answerQuestion(nativeId: string, requestId: string, answers: QuestionAnswer[]): Promise<void>;
-    desktopLaunch(args: string[], nativeId?: string): LaunchSpec;
+    desktopLaunch(args: string[], nativeId?: string): Promise<LaunchSpec>;
     private boot;
     /** Follows every thread already live in the app-server (e.g. opened in the TUI). */
     private reattachLoaded;
@@ -107,4 +209,11 @@ export declare class CodexDriver implements AgentDriver {
     private onServerRequest;
     private rememberTitle;
     private rpc;
+    /** A request about a thread, to the server it is loaded in. */
+    private rpcFor;
+    /** Connects to Codex's background server, if it is running. */
+    private connectShared;
+    /** Codex's background server went away (stopped, or restarted by its updater): the threads joined there are joined again wherever they are now. */
+    private onSharedDown;
+    private abandonApprovals;
 }