lark-remote 0.5.3 → 0.5.5

package/dist/runner/dsh/daemon.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Global DSH Web Host lifecycle.
+ *
+ * One machine runs one DSH per `DSH_HOME`. lark-remote reuses an existing
+ * process, or starts `dsh web` detached when none is running. The child is
+ * deliberately independent: lark-remote exiting must not stop the shared DSH.
+ *
+ * Authentication is separate. DSH's `/api` and `/api/remote.mux` require a
+ * signed browser cookie; lark-remote mints a v1 cookie from the durable
+ * `client-connection/browser-session` secret in `$DSH_HOME/.credentials.yaml`,
+ * so a DSH restart never needs a copied launch token.
+ */
+/** Configuration providers are read on every resolve so `/config` hot edits land. */
+export interface DshDaemonOptions {
+    readonly host: () => string | undefined;
+    readonly dshHome?: () => string | undefined;
+    readonly dshCommand?: () => string | undefined;
+    readonly manageProcess?: () => boolean;
+    readonly startTimeoutMs?: () => number | undefined;
+}
+export type DshDaemonErrorCode = 'stopped' | 'start-lock' | 'spawn' | 'start-timeout';
+/** User-facing daemon failure; the bridge renders `message` in the chat card. */
+export declare class DshDaemonError extends Error {
+    readonly code: DshDaemonErrorCode;
+    constructor(code: DshDaemonErrorCode, message: string, options?: ErrorOptions);
+}
+interface SpawnedDaemon {
+    failure(): Error | undefined;
+    exited(): boolean;
+}
+/** Resolve the same Harness home DSH resolves: configured, env, then ~/.dsh. */
+export declare function resolveDshHome(configured?: string, env?: NodeJS.ProcessEnv): string;
+/** True only for the loopback HTTP address this process may start and probe. */
+export declare function isLoopbackHttpUrl(value: string): boolean;
+/**
+ * Build `dsh web` arguments for one managed base URL.
+ *
+ * `--host` takes one concrete IP literal, so `localhost` becomes 127.0.0.1.
+ * The port is always explicit: a managed DSH must be reachable at the address
+ * lark-remote probes, and `--port 0` would make rediscovery impossible.
+ */
+export declare function dshDaemonArgs(baseUrl: string): string[];
+/**
+ * One process-wide DSH resolver shared by the DSH runner and startup warmup.
+ * Concurrent callers share one in-flight start.
+ */
+export declare class DshDaemon {
+    private readonly options;
+    private inFlight;
+    constructor(options: DshDaemonOptions);
+    /** The configured base URL, always without a trailing slash. */
+    baseUrl(): string;
+    /** The configured Harness home, used for the start lock and DSH log. */
+    home(): string;
+    /** The detached DSH stderr log for start diagnostics. */
+    logFile(): string;
+    dshCommand(): string;
+    /**
+     * Return a reachable DSH base URL, starting it when needed.
+     *
+     * A successful probe always wins. Only a genuinely unreachable loopback
+     * address is started, so a DSH already running on the configured port is
+     * never duplicated.
+     */
+    ensure(): Promise<string>;
+    private resolve;
+    private withStartLock;
+    private lockIsStale;
+    private waitUntilReady;
+    protected startTimeoutMs(): number;
+    protected manageProcess(): boolean;
+    /**
+     * Probe the API prefix, not `/`: a listening server whose plugin tree has
+     * not mounted yet answers 404 there, while a ready DSH answers 401 before
+     * dispatch. Any other status still proves the listener is alive.
+     */
+    protected probe(baseUrl: string): Promise<boolean>;
+    /**
+     * Start one detached DSH. stdout is discarded because it carries the
+     * tokenized startup URL; stderr goes to a 0600 log for failure diagnosis.
+     */
+    protected spawnDaemon(baseUrl: string): SpawnedDaemon;
+    protected sleep(ms: number): Promise<void>;
+}
+export {};

package/dist/runner/dsh/daemon.js

@@ -0,0 +1,272 @@
+/**
+ * Global DSH Web Host lifecycle.
+ *
+ * One machine runs one DSH per `DSH_HOME`. lark-remote reuses an existing
+ * process, or starts `dsh web` detached when none is running. The child is
+ * deliberately independent: lark-remote exiting must not stop the shared DSH.
+ *
+ * Authentication is separate. DSH's `/api` and `/api/remote.mux` require a
+ * signed browser cookie; lark-remote mints a v1 cookie from the durable
+ * `client-connection/browser-session` secret in `$DSH_HOME/.credentials.yaml`,
+ * so a DSH restart never needs a copied launch token.
+ */
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_DSH_HOST } from '../../config/index.js';
+import { mergeProcessEnv, spawnProcess } from '../../platform/spawn.js';
+const DEFAULT_START_TIMEOUT_MS = 30_000;
+const READY_POLL_MS = 100;
+/** User-facing daemon failure; the bridge renders `message` in the chat card. */
+export class DshDaemonError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'DshDaemonError';
+        this.code = code;
+    }
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}
+/** Resolve the same Harness home DSH resolves: configured, env, then ~/.dsh. */
+export function resolveDshHome(configured, env = process.env) {
+    const value = configured?.trim() || env.DSH_HOME?.trim();
+    return path.resolve(value && value.length > 0 ? value : path.join(os.homedir(), '.dsh'));
+}
+/** True only for the loopback HTTP address this process may start and probe. */
+export function isLoopbackHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:')
+            return false;
+        return (url.hostname === '127.0.0.1' ||
+            url.hostname === 'localhost' ||
+            url.hostname === '[::1]' ||
+            url.hostname === '::1');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build `dsh web` arguments for one managed base URL.
+ *
+ * `--host` takes one concrete IP literal, so `localhost` becomes 127.0.0.1.
+ * The port is always explicit: a managed DSH must be reachable at the address
+ * lark-remote probes, and `--port 0` would make rediscovery impossible.
+ */
+export function dshDaemonArgs(baseUrl) {
+    const url = new URL(baseUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    const host = hostname === 'localhost' ? '127.0.0.1' : hostname;
+    return ['web', '--host', host, '--port', url.port || '3080', '--no-open'];
+}
+/**
+ * One process-wide DSH resolver shared by the DSH runner and startup warmup.
+ * Concurrent callers share one in-flight start.
+ */
+export class DshDaemon {
+    options;
+    inFlight;
+    constructor(options) {
+        this.options = options;
+    }
+    /** The configured base URL, always without a trailing slash. */
+    baseUrl() {
+        return stripTrailingSlash(this.options.host()?.trim() || DEFAULT_DSH_HOST);
+    }
+    /** The configured Harness home, used for the start lock and DSH log. */
+    home() {
+        return resolveDshHome(this.options.dshHome?.());
+    }
+    /** The detached DSH stderr log for start diagnostics. */
+    logFile() {
+        return path.join(this.home(), 'lark-remote', 'dsh-web.log');
+    }
+    dshCommand() {
+        return this.options.dshCommand?.()?.trim() || 'dsh';
+    }
+    /**
+     * Return a reachable DSH base URL, starting it when needed.
+     *
+     * A successful probe always wins. Only a genuinely unreachable loopback
+     * address is started, so a DSH already running on the configured port is
+     * never duplicated.
+     */
+    async ensure() {
+        const baseUrl = this.baseUrl();
+        if (await this.probe(baseUrl))
+            return baseUrl;
+        if (this.inFlight === undefined) {
+            const pending = this.resolve(baseUrl);
+            this.inFlight = pending;
+            pending
+                .finally(() => {
+                if (this.inFlight === pending)
+                    this.inFlight = undefined;
+            })
+                .catch(() => {
+                // The racing caller observes the same failure.
+            });
+        }
+        return this.inFlight;
+    }
+    async resolve(baseUrl) {
+        if (!isLoopbackHttpUrl(baseUrl) || !this.manageProcess()) {
+            throw new DshDaemonError('stopped', `DSH 未运行（${baseUrl}），且当前配置不会由 lark-remote 启动它。` +
+                `请先启动：\n  ${this.dshCommand()} web --port ${portOf(baseUrl)} --no-open`);
+        }
+        return this.withStartLock(baseUrl, async () => {
+            if (await this.probe(baseUrl))
+                return baseUrl;
+            let spawned;
+            try {
+                spawned = this.spawnDaemon(baseUrl);
+            }
+            catch (error) {
+                throw new DshDaemonError('spawn', `DSH 启动失败：${error.message}\n日志：${this.logFile()}`, { cause: error });
+            }
+            if (await this.waitUntilReady(baseUrl, this.startTimeoutMs(), spawned))
+                return baseUrl;
+            const failure = spawned.failure();
+            if (failure !== undefined) {
+                throw new DshDaemonError('spawn', `DSH 启动失败：${failure.message}\n日志：${this.logFile()}`, { cause: failure });
+            }
+            if (spawned.exited()) {
+                throw new DshDaemonError('spawn', `DSH 启动进程提前退出（端口可能被其他进程占用），${baseUrl} 未就绪。\n` +
+                    `日志：${this.logFile()}`);
+            }
+            throw new DshDaemonError('start-timeout', `DSH 启动超时（${String(this.startTimeoutMs())}ms），${baseUrl} 仍不可达。\n` +
+                `日志：${this.logFile()}`);
+        });
+    }
+    async withStartLock(baseUrl, run) {
+        const lockDir = path.join(this.home(), 'lark-remote', 'start.lock');
+        await fsp.mkdir(path.dirname(lockDir), { recursive: true, mode: 0o700 });
+        await fsp.chmod(path.dirname(lockDir), 0o700).catch(() => { });
+        const deadline = Date.now() + this.startTimeoutMs();
+        while (true) {
+            if (await this.probe(baseUrl))
+                return baseUrl;
+            try {
+                await fsp.mkdir(lockDir, { mode: 0o700 });
+                break;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                if (await this.lockIsStale(lockDir)) {
+                    await fsp.rm(lockDir, { recursive: true, force: true });
+                    continue;
+                }
+                if (Date.now() >= deadline) {
+                    throw new DshDaemonError('start-lock', `等待其他 lark-remote 启动 DSH 超时。锁文件：${lockDir}`);
+                }
+                await this.sleep(READY_POLL_MS);
+            }
+        }
+        try {
+            return await run();
+        }
+        finally {
+            await fsp.rm(lockDir, { recursive: true, force: true });
+        }
+    }
+    async lockIsStale(lockDir) {
+        try {
+            const stats = await fsp.stat(lockDir);
+            return Date.now() - stats.mtimeMs > this.startTimeoutMs() * 2;
+        }
+        catch {
+            return false;
+        }
+    }
+    async waitUntilReady(baseUrl, timeoutMs, spawned) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (await this.probe(baseUrl))
+                return true;
+            if (spawned.failure() !== undefined || spawned.exited())
+                return false;
+            await this.sleep(READY_POLL_MS);
+        }
+        return this.probe(baseUrl);
+    }
+    startTimeoutMs() {
+        const configured = this.options.startTimeoutMs?.();
+        return configured !== undefined && configured > 0 ? configured : DEFAULT_START_TIMEOUT_MS;
+    }
+    manageProcess() {
+        return this.options.manageProcess?.() ?? true;
+    }
+    /**
+     * Probe the API prefix, not `/`: a listening server whose plugin tree has
+     * not mounted yet answers 404 there, while a ready DSH answers 401 before
+     * dispatch. Any other status still proves the listener is alive.
+     */
+    async probe(baseUrl) {
+        try {
+            const response = await fetch(`${baseUrl}/api/`, {
+                method: 'GET',
+                redirect: 'manual',
+                signal: AbortSignal.timeout(1_500),
+            });
+            return response.status !== 404;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Start one detached DSH. stdout is discarded because it carries the
+     * tokenized startup URL; stderr goes to a 0600 log for failure diagnosis.
+     */
+    spawnDaemon(baseUrl) {
+        const home = this.home();
+        const log = this.logFile();
+        fs.mkdirSync(path.dirname(log), { recursive: true, mode: 0o700 });
+        try {
+            fs.chmodSync(path.dirname(log), 0o700);
+        }
+        catch {
+            // Non-POSIX filesystems keep their native ACLs.
+        }
+        const fd = fs.openSync(log, 'a', 0o600);
+        try {
+            fs.chmodSync(log, 0o600);
+        }
+        catch {
+            // Non-POSIX filesystems keep their native ACLs.
+        }
+        let failure;
+        let exited = false;
+        try {
+            const child = spawnProcess(this.dshCommand(), dshDaemonArgs(baseUrl), {
+                detached: true,
+                stdio: ['ignore', 'ignore', fd],
+                cwd: home,
+                env: mergeProcessEnv(process.env, { DSH_HOME: home }),
+            });
+            child.once('error', (error) => {
+                failure = error;
+            });
+            child.once('exit', () => {
+                exited = true;
+            });
+            child.unref();
+            return { failure: () => failure, exited: () => exited };
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    async sleep(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+function portOf(baseUrl) {
+    return new URL(baseUrl).port || '3080';
+}
+//# sourceMappingURL=daemon.js.map

package/dist/runner/dsh/merge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Merge independent async iterables into one consumer stream.
+ *
+ * DSH delivers a turn over `session/follow` and approvals over `$events`.
+ * Both must feed one runner loop without assuming which transport emits first.
+ * Source failures are rethrown to the consumer; normal source completion does
+ * not end the merged stream until every source has completed.
+ */
+export declare function mergeAsync<T>(sources: readonly AsyncIterable<T>[]): AsyncGenerator<T>;

package/dist/runner/dsh/merge.js

@@ -0,0 +1,51 @@
+/**
+ * Merge independent async iterables into one consumer stream.
+ *
+ * DSH delivers a turn over `session/follow` and approvals over `$events`.
+ * Both must feed one runner loop without assuming which transport emits first.
+ * Source failures are rethrown to the consumer; normal source completion does
+ * not end the merged stream until every source has completed.
+ */
+export async function* mergeAsync(sources) {
+    const queue = [];
+    const waiters = [];
+    let completed = 0;
+    let failure;
+    let hasFailure = false;
+    const wake = () => {
+        for (const resolve of waiters.splice(0))
+            resolve();
+    };
+    for (const source of sources) {
+        void (async () => {
+            try {
+                for await (const item of source) {
+                    queue.push(item);
+                    wake();
+                }
+            }
+            catch (err) {
+                if (!hasFailure) {
+                    hasFailure = true;
+                    failure = err;
+                }
+            }
+            finally {
+                completed += 1;
+                wake();
+            }
+        })();
+    }
+    while (true) {
+        if (hasFailure)
+            throw failure;
+        if (queue.length > 0) {
+            yield queue.shift();
+            continue;
+        }
+        if (completed >= sources.length)
+            return;
+        await new Promise((resolve) => waiters.push(resolve));
+    }
+}
+//# sourceMappingURL=merge.js.map

package/dist/runner/dsh/runner.d.ts

@@ -2,26 +2,39 @@
  * DshRunner — workspace-lifetime runner bridging to the DSH Web Host
  * (DeepSeek Harness) over plain HTTP. No local subprocess is spawned.
  *
- * Flow per run: session.create(cwd) (when no sessionId) → synthetic system/init
- * (DSH has no init event) → open per-session mux subscription → session.prompt
- * (mode:'queue') → consume subscription until turn/end → result event.
+ * Flow per run: session/create(cwd) (when no sessionId) → model/permission
+ * alignment → synthetic system/init (DSH has no init event) → session/prompt
+ * (mode:'queue') → consume `session/follow` + `$events` until turn/end.
  *
- * stop() → session.cancel + abort the mux subscription. killOrphan /
- * registerExitHandlers are no-ops (no local process). approval/requested is
- * surfaced as a WARN log + an assistant text prompt pointing to the DSH Web UI
- * (never silently parked — the turn stays live until the user resolves it in
- * the UI or the turn is cancelled/times out).
+ * stop() → session/cancel + abort the mux subscription. killOrphan /
+ * registerExitHandlers are no-ops (no local process). DSH approvals are
+ * two-channel: durable `approval/asked` / `approval/decided` drive the Feishu
+ * card, while the answerable `$events` waterfall supplies eventId/clientId.
+ * If `$events` is unavailable, the runner falls back to the Web UI prompt.
  */
 import type { AgentEvent, AgentSessionReader, AgentStatusInfo, SpawnOptions } from '../types.js';
 import type { AgentRunner } from '../types.js';
 import { DshClient, type WebSocketFactory } from './client.js';
+import type { DshDaemon } from './daemon.js';
 export interface DshRunnerOptions {
     kind: 'dsh';
     sessionReader: AgentSessionReader;
+    /** Global DSH process manager; omitted in tests that drive a fake server. */
+    daemon?: DshDaemon;
     /** DSH Web Host base URL, e.g. http://127.0.0.1:3080. */
     host?: string;
+    /** Configured DSH home; selects `.credentials.yaml` when credentialsFile is unset. */
+    dshHome?: string;
+    /** Optional `dsh web` launch token (or its startup URL). */
+    token?: string;
+    /** DSH credentials file with the durable browser-session signing secret. */
+    credentialsFile?: string;
     /** Session preset（agentPreset）固定于 session 创建时；undefined = 服务端默认。 */
     agentPreset?: string;
+    /** 权限预设（沙箱 + 审批策略）；undefined = 不干预。 */
+    permissionPreset?: string;
+    /** Provider route id (e.g. deepseek-official / anthropic); undefined = legacy default. */
+    provider?: string;
     /** Display model name. */
     model?: string;
     /** 推理强度（off/low/high/max）；undefined = 服务端默认。 */
@@ -30,29 +43,99 @@ export interface DshRunnerOptions {
     fetchImpl?: typeof fetch;
     /** Injectable WebSocket factory (defaults to global WebSocket). */
     webSocketImpl?: WebSocketFactory;
+    /** Unary request timeout in ms (default 60s); 0 disables. */
+    requestTimeoutMs?: number;
 }
 export declare class DshRunner implements AgentRunner {
     readonly kind: "dsh";
+    /**
+     * Session identity lives in the DSH Web Host (server-side), not in a local
+     * process, so a finished run is still addressable — the same property the
+     * bridge uses before recording a run as compactable. Without it the Compact
+     * button renders (capability is declared) but every click answers
+     * 「该任务已结束或不属于当前会话」.
+     */
+    readonly lifetime: "workspace";
     readonly sessionReader: AgentSessionReader;
     readonly client: DshClient;
     /** 用户配置的模型 ID（run 前 selectModel 对齐用）；undefined = 服务端默认。 */
     private readonly configuredModel;
+    /** 用户配置的 provider route；undefined = 兼容旧配置，按 deepseek-official 处理。 */
+    private readonly configuredProvider;
     private readonly agentPreset;
+    private configuredPermissionPreset;
     private readonly reasoningEffort;
     private activeAbort;
     private activeSessionId;
     private running;
+    private readonly daemon;
     /**
      * 已对齐模型的 session 集合：同一 session 二次 run 不再重发 selectModel
-     * （session.selectModel 会写服务端全局默认，每次 run 都写是写放大）。
-     * configuredModel 在实例生命周期内不变（/config 改模型会 clearRunners
-     * 重建实例 + 换新 sessionId），故「每 session 对齐一次」足以覆盖配置变化。
+     * （session/selectModel 会写服务端全局默认，每次 run 都写是写放大）。
+     * configuredModel / configuredProvider 在实例生命周期内不变（/config 改动
+     * 会 clearRunners 重建实例），故「每 session 对齐一次」足以覆盖配置变化。
      */
     private readonly alignedSessions;
+    /** 已对齐权限预设的 session；同一 session 只执行一次 `/permission`。 */
+    private readonly permissionAlignedSessions;
+    /** `$events` approval waterfall state for the current run. */
+    private readonly approvalTracker;
+    /** callId → tool call, used to render the command in the approval card. */
+    private readonly toolCalls;
+    /** False after `$events` is unavailable; approval/asked then falls back to text. */
+    private approvalChannelAvailable;
     constructor(opts: DshRunnerOptions);
     get isRunning(): boolean;
     getStatusInfo(): AgentStatusInfo;
+    /**
+     * Resolve the configured provider/model pair.
+     *
+     * A model-only config keeps the legacy `deepseek-official` route, so
+     * existing configs behave exactly as before. A provider-only config asks
+     * the live catalog for that provider's default (or first) model.
+     */
+    private resolveModelSelection;
     run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Consume one turn from both transports. `session/follow` owns transcript
+     * events; `$events` owns the answerable approval waterfall. The merged
+     * stream keeps either transport from starving the other.
+     */
+    private runTurn;
+    /** Apply the configured permission preset once per session, before prompt. */
+    private alignPermissionPreset;
+    /** Hot-update the configured preset; the next run aligns it. */
+    updateApprovalMode(settings: {
+        permissionPreset?: string;
+    }): Promise<void>;
+    /**
+     * Answer one DSH approval. `accept` / `decline` are the only user decisions
+     * exposed by the DSH Web UI; `cancel` stops the turn through session/cancel.
+     */
+    respondApproval(requestId: number | string, response: unknown): Promise<void>;
+    private buildApprovalRequested;
+    private approvalResolved;
+    private approvalFallbackText;
+    /**
+     * Compact the session through DSH's `/compact` command.
+     *
+     * Commands are a separate RPC from turns (`commands/execute`, idle-only), so
+     * this never prompts the model and never waits for a `turn/end`: the RPC
+     * itself settles when the compaction finishes, which is why the unary budget
+     * is disabled here (stop + the idle watchdog bound it instead). DSH reports
+     * expected refusals (busy / nothing to compact / summary failure) as
+     * `kind:'error'` values rather than RPC errors — those must become an error
+     * result, not a success card.
+     */
+    runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Resolve with the promise's value, or `undefined` as soon as `signal` aborts.
+     * The underlying promise keeps running (its own timeout still applies) — the
+     * caller decides what to do with a late settlement.
+     */
+    private awaitOrAbort;
+    /** Send session/cancel with a short bound; never throws (cleanup path). */
+    private cancelSessionQuietly;
     stop(_opts?: {
         immediate?: boolean;
     }): Promise<void>;