@linkshell/host 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinkShell Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @linkshell/host
+
+The LinkShell v2 host daemon. It runs on your computer and owns what your devices control:
+agent sessions (Codex, Claude Code, Gemini, Copilot, Grok and other ACP agents), terminals,
+file and port previews. Devices reach it over the LAN or through a relay, end-to-end encrypted.
+
+Run it through the CLI: `npm install -g linkshell-cli`, then `linkshell host --daemon`.
+
+Requires Node.js 22.13 or newer.
+
+MIT License

package/dist/host/src/drivers/acp/connection.d.ts

@@ -0,0 +1,61 @@
+import { type RpcId } from "@linkshell/wire";
+/** The subset of ACP `initialize` results LinkShell reads. */
+export interface AcpAgentCapabilities {
+    loadSession?: boolean;
+    promptCapabilities?: {
+        image?: boolean;
+        audio?: boolean;
+        embeddedContext?: boolean;
+    };
+    sessionCapabilities?: {
+        list?: unknown;
+        resume?: unknown;
+        close?: unknown;
+        fork?: unknown;
+        delete?: unknown;
+    };
+    _meta?: Record<string, unknown>;
+}
+export interface AcpInitializeResult {
+    protocolVersion?: number;
+    agentCapabilities?: AcpAgentCapabilities;
+    agentInfo?: {
+        name?: string;
+        version?: string;
+    };
+    authMethods?: {
+        id: string;
+        name?: string;
+    }[];
+    _meta?: Record<string, unknown>;
+}
+export interface AcpConnectionOptions {
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    clientVersion: string;
+    onUpdate: (sessionId: string, update: unknown) => void;
+    /** Agent → client requests (session/request_permission, …). */
+    onRequest: (method: string, params: unknown, id: RpcId) => unknown;
+    onExit: (reason: string) => void;
+}
+/**
+ * One ACP agent subprocess: JSON-RPC 2.0 over newline-delimited stdio.
+ * A single process serves every session of that agent.
+ */
+export declare class AcpConnection {
+    private readonly options;
+    private child?;
+    private peer?;
+    private stopping;
+    private stderrTail;
+    initializeResult: AcpInitializeResult;
+    constructor(options: AcpConnectionOptions);
+    get capabilities(): AcpAgentCapabilities;
+    get alive(): boolean;
+    start(): Promise<AcpInitializeResult>;
+    request<T>(method: string, params: unknown, timeoutMs?: number): Promise<T>;
+    notify(method: string, params: unknown): void;
+    stop(): Promise<void>;
+}

package/dist/host/src/drivers/acp/connection.js

@@ -0,0 +1,121 @@
+import { spawn } from "node:child_process";
+import { RpcPeer } from "@linkshell/wire";
+/**
+ * One ACP agent subprocess: JSON-RPC 2.0 over newline-delimited stdio.
+ * A single process serves every session of that agent.
+ */
+export class AcpConnection {
+    options;
+    child;
+    peer;
+    stopping = false;
+    stderrTail = "";
+    initializeResult = {};
+    constructor(options) {
+        this.options = options;
+    }
+    get capabilities() {
+        return this.initializeResult.agentCapabilities ?? {};
+    }
+    get alive() {
+        return Boolean(this.child && this.child.exitCode === null && !this.peer?.isClosed);
+    }
+    async start() {
+        this.stopping = false;
+        const child = spawn(this.options.command, this.options.args, {
+            env: this.options.env,
+            cwd: this.options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        const peer = new RpcPeer({
+            send: (text) => {
+                if (child.stdin?.writable)
+                    child.stdin.write(`${text}\n`);
+            },
+            onNotification: (method, params) => {
+                if (method !== "session/update")
+                    return;
+                const payload = params;
+                if (typeof payload?.sessionId === "string")
+                    this.options.onUpdate(payload.sessionId, payload.update);
+            },
+            onRequest: (method, params, id) => this.options.onRequest(method, params, id),
+            requestTimeoutMs: 0,
+        });
+        this.peer = peer;
+        // stdout chunks can split a JSON line; only hand complete lines to the peer.
+        let pending = "";
+        child.stdout?.on("data", (chunk) => {
+            pending += chunk.toString("utf8");
+            const end = pending.lastIndexOf("\n");
+            if (end < 0)
+                return;
+            const complete = pending.slice(0, end);
+            pending = pending.slice(end + 1);
+            peer.receive(complete);
+        });
+        child.stderr?.on("data", (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-4000);
+        });
+        const exited = new Promise((_, reject) => {
+            child.once("exit", (code, signal) => {
+                const reason = `${this.options.command} exited (${signal ?? code})${this.stderrTail ? `: ${this.stderrTail.trim().split("\n").slice(-3).join(" | ")}` : ""}`;
+                peer.close(reason);
+                if (!this.stopping)
+                    this.options.onExit(reason);
+                reject(new Error(reason));
+            });
+            child.once("error", (error) => {
+                peer.close(error.message);
+                reject(error);
+            });
+        });
+        exited.catch(() => { });
+        this.initializeResult = await Promise.race([
+            peer.request("initialize", {
+                protocolVersion: 1,
+                // LinkShell doesn't serve files or terminals to the agent: agents use their own tools.
+                clientCapabilities: {
+                    fs: { readTextFile: false, writeTextFile: false },
+                    terminal: false,
+                    // Ask adapters that support it (Claude's) to stream sub-agents' own
+                    // messages and tool calls, each stamped with the spawning call.
+                    _meta: { "subagent-transcript": true },
+                },
+                clientInfo: { name: "linkshell", title: "LinkShell", version: this.options.clientVersion },
+            }, 30_000),
+            exited,
+        ]);
+        return this.initializeResult;
+    }
+    request(method, params, timeoutMs = 60_000) {
+        if (!this.peer)
+            return Promise.reject(new Error("agent is not running"));
+        return this.peer.request(method, params, timeoutMs);
+    }
+    notify(method, params) {
+        this.peer?.notify(method, params);
+    }
+    async stop() {
+        this.stopping = true;
+        const child = this.child;
+        this.child = undefined;
+        this.peer?.close("stopping");
+        if (!child || child.exitCode !== null)
+            return;
+        child.stdin?.end();
+        child.kill("SIGTERM");
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                resolve();
+            }, 3000);
+            child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/host/src/drivers/acp/connection.js.map

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

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

@@ -0,0 +1,110 @@
+import { type AgentAuth, type AgentCapabilities, type AgentTier, type ContentBlock, type SessionUpdate } from "@linkshell/wire";
+import type { AgentDriver, AttachContext, DiscoveredSession, DriverHost, DriverStatus, HistoryItem } from "../types.js";
+import { AcpConnection } from "./connection.js";
+import { AcpItemTracker, type SourcedConfigOption } from "./mapper.js";
+export interface AcpAgentSpec {
+    id: string;
+    label: string;
+    tier: AgentTier;
+    /** How to start the agent as an ACP server. */
+    command: string;
+    args: string[];
+    /** Detects the install; defaults to `<command> --version`. */
+    version?: {
+        command: string;
+        args: string[];
+    };
+    env?: Record<string, string>;
+    authStatus?: (env: NodeJS.ProcessEnv) => Promise<AgentAuth>;
+    /**
+     * Start the agent process with the host so its existing sessions show up
+     * (needs ACP session/list). Otherwise it starts on first use.
+     */
+    discover?: boolean;
+}
+interface PendingPrompt {
+    content: ContentBlock[];
+    clientMessageId: string;
+}
+export interface AcpSessionState {
+    cwd: string;
+    loaded: boolean;
+    tracker: AcpItemTracker;
+    config: SourcedConfigOption[];
+    /** Set while a session/load replays history. */
+    replaying?: SessionUpdate[];
+    turnActive: boolean;
+    /** session/prompt requests in flight; with steering, a turn spans several. */
+    inflight: number;
+    queue: PendingPrompt[];
+    permissions: Map<string, (outcome: unknown) => void>;
+}
+/** Turns agent failures into something a person can act on. */
+export declare function describeAgentError(label: string, message: string): {
+    message: string;
+    hint?: string;
+};
+/**
+ * A generic Agent Client Protocol driver: one agent subprocess serving every
+ * session. Tier "remote" by default — LinkShell drives the agent, the desktop
+ * uses LinkShell's own UI. Subclasses add desktop handoff.
+ */
+export declare class AcpDriver implements AgentDriver {
+    protected readonly spec: AcpAgentSpec;
+    protected readonly options: {
+        env?: NodeJS.ProcessEnv;
+        hostVersion: string;
+    };
+    readonly id: string;
+    readonly label: string;
+    readonly tier: AgentTier;
+    capabilities: AgentCapabilities;
+    protected host?: DriverHost;
+    protected connection?: AcpConnection;
+    protected current: DriverStatus;
+    protected readonly sessions: Map<string, AcpSessionState>;
+    private restartTimer?;
+    private restartDelay;
+    private stopped;
+    private nextPermissionId;
+    constructor(spec: AcpAgentSpec, options: {
+        env?: NodeJS.ProcessEnv;
+        hostVersion: string;
+    });
+    status(): DriverStatus;
+    protected get env(): NodeJS.ProcessEnv;
+    authStatus(): Promise<AgentAuth>;
+    start(host: DriverHost): Promise<DriverStatus>;
+    stop(): Promise<void>;
+    listSessions(limit: number): Promise<DiscoveredSession[]>;
+    createSession(options: {
+        cwd: string;
+        model?: string;
+    }): Promise<DiscoveredSession>;
+    attach(nativeId: string, context: AttachContext): Promise<HistoryItem[]>;
+    detach(nativeId: string): Promise<void>;
+    prompt(nativeId: string, content: ContentBlock[], clientMessageId: string): Promise<"started" | "steered" | "queued">;
+    cancel(nativeId: string): Promise<void>;
+    respondPermission(nativeId: string, requestId: string, optionId: string): Promise<void>;
+    setConfig(nativeId: string, optionId: string, value: string): Promise<void>;
+    protected detectVersion(): Promise<string | undefined>;
+    private booting?;
+    /** Starts the agent process once; concurrent callers share the attempt. */
+    protected ensureStarted(): Promise<void>;
+    protected boot(): Promise<void>;
+    private scheduleRestart;
+    private onExit;
+    protected stateFor(nativeId: string, cwd: string): AcpSessionState;
+    protected emitConfig(nativeId: string, state: AcpSessionState): void;
+    /** Feeds an update through the item tracker and on to the host. */
+    protected emit(nativeId: string, update: SessionUpdate): void;
+    protected closeMessage(nativeId: string): void;
+    protected onUpdate(sessionId: string, raw: unknown): void;
+    private onRequest;
+    private cancelPermissions;
+    private echoUserMessage;
+    protected startTurn(nativeId: string, state: AcpSessionState, content: ContentBlock[], clientMessageId: string): void;
+    private sendPrompt;
+    protected rpc<T = unknown>(method: string, params: unknown, timeoutMs?: number): Promise<T>;
+}
+export {};