shennian 0.2.6 → 0.2.7

package/dist/src/agents/command-spec.d.ts

@@ -0,0 +1,36 @@
+import { type ChildProcess, type SpawnOptions, type SpawnSyncOptions } from 'node:child_process';
+import type { BuiltinAgentType } from '@shennian/wire';
+export type CommandSpec = {
+    command: string;
+    args: string[];
+    display: string;
+};
+export type ResolvedCommandKind = 'native' | 'cmd-shim' | 'wsl-bridge';
+export type ResolvedCommandSpec = CommandSpec & {
+    kind: ResolvedCommandKind;
+    path: string;
+};
+type LaunchSpec = {
+    command: string;
+    args: string[];
+    cwd?: string;
+};
+export declare function resetCommandSpecCache(): void;
+export declare function getProcessPlatform(): NodeJS.Platform;
+export declare function windowsPathToWsl(input: string): string | undefined;
+export declare function commandExists(command: string): boolean;
+export declare function resolveBuiltinCommand(type: BuiltinAgentType): ResolvedCommandSpec | null;
+export declare function buildLaunchSpec(spec: ResolvedCommandSpec, runtimeArgs: string[], cwd?: string): LaunchSpec;
+export declare function spawnResolvedCommand(spec: ResolvedCommandSpec, runtimeArgs: string[], options?: Omit<SpawnOptions, 'cwd'> & {
+    cwd?: string;
+}): ChildProcess;
+export declare function spawnResolvedCommandSync(spec: ResolvedCommandSpec, runtimeArgs: string[], options?: Omit<SpawnSyncOptions, 'cwd'> & {
+    cwd?: string;
+}): import("child_process").SpawnSyncReturns<string | NonSharedBuffer>;
+export declare function parseCommandString(command: string): string[];
+export declare function buildCommandStringLaunchSpec(commandString: string, runtimeArgs: string[], cwd?: string): LaunchSpec;
+export declare function spawnCommandString(commandString: string, runtimeArgs: string[], options?: Omit<SpawnOptions, 'cwd'> & {
+    cwd?: string;
+}): ChildProcess;
+export declare function getCommandVersion(spec: ResolvedCommandSpec, flag?: string): string | undefined;
+export {};

package/dist/src/agents/command-spec.js

@@ -0,0 +1,303 @@
+// @arch docs/architecture/cli/windows-agent-launch.md
+// @test src/__tests__/command-spec.test.ts
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+const BUILTIN_COMMANDS = {
+    claude: [
+        { command: 'claude', args: [], display: 'claude' },
+    ],
+    codex: [
+        { command: 'codex', args: [], display: 'codex' },
+    ],
+    gemini: [
+        { command: 'gemini', args: [], display: 'gemini' },
+    ],
+    cursor: [
+        { command: 'agent', args: [], display: 'agent' },
+        { command: 'cursor', args: ['agent'], display: 'cursor agent' },
+    ],
+    openclaw: [
+        { command: 'openclaw', args: [], display: 'openclaw' },
+    ],
+    pi: [
+        { command: 'shennian', args: [], display: 'shennian' },
+    ],
+};
+const availabilityCache = new Map();
+const resolvedCache = new Map();
+const pathLookupCache = new Map();
+const wslAvailabilityCache = new Map();
+export function resetCommandSpecCache() {
+    availabilityCache.clear();
+    resolvedCache.clear();
+    pathLookupCache.clear();
+    wslAvailabilityCache.clear();
+}
+export function getProcessPlatform() {
+    return process.platform;
+}
+function splitLines(text) {
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function lookupCommandPaths(command) {
+    if (pathLookupCache.has(command)) {
+        return pathLookupCache.get(command) ?? [];
+    }
+    const lookup = getProcessPlatform() === 'win32' ? 'where' : 'which';
+    const result = spawnSync(lookup, [command], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 3000,
+    });
+    const paths = result.status === 0 ? splitLines(result.stdout ?? '') : [];
+    pathLookupCache.set(command, paths);
+    return paths;
+}
+function getWindowsShellPath() {
+    return process.env.ComSpec || 'cmd.exe';
+}
+function isWindowsNativeBinary(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === '.exe' || ext === '.com';
+}
+function isWindowsCmdShim(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === '.cmd' || ext === '.bat';
+}
+function quoteCmdArg(text) {
+    return `"${text.replace(/"/g, '""')}"`;
+}
+function quotePosixArg(text) {
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+export function windowsPathToWsl(input) {
+    if (!input)
+        return undefined;
+    const normalized = input.replace(/\//g, '\\');
+    const driveMatch = normalized.match(/^([A-Za-z]):\\(.*)$/);
+    if (driveMatch) {
+        const [, drive, rest] = driveMatch;
+        const suffix = rest.replace(/\\/g, '/');
+        return `/mnt/${drive.toLowerCase()}/${suffix}`;
+    }
+    if (normalized.startsWith('\\\\wsl$\\')) {
+        const remainder = normalized.replace(/^\\\\wsl\$\\[^\\]+\\?/, '');
+        return `/${remainder.replace(/\\/g, '/')}`;
+    }
+    if (input.startsWith('/'))
+        return input;
+    return undefined;
+}
+function resolveArbitraryWindowsCommand(command) {
+    const normalized = command.trim();
+    if (!normalized) {
+        throw new Error('Command string is empty');
+    }
+    const hasExplicitPath = /[\\/]/.test(normalized) || /^[A-Za-z]:/.test(normalized);
+    if (hasExplicitPath) {
+        if (isWindowsCmdShim(normalized))
+            return { kind: 'cmd-shim', path: normalized };
+        return { kind: 'direct', path: normalized };
+    }
+    const paths = lookupCommandPaths(normalized);
+    const native = paths.find(isWindowsNativeBinary);
+    if (native)
+        return { kind: 'direct', path: native };
+    const shim = paths.find(isWindowsCmdShim);
+    if (shim)
+        return { kind: 'cmd-shim', path: shim };
+    return { kind: 'direct', path: normalized };
+}
+function canUseWslBridge(command) {
+    if (wslAvailabilityCache.has(command)) {
+        return wslAvailabilityCache.get(command) ?? false;
+    }
+    const wslPath = lookupCommandPaths('wsl.exe')[0] ?? lookupCommandPaths('wsl')[0];
+    if (!wslPath) {
+        wslAvailabilityCache.set(command, false);
+        return false;
+    }
+    const result = spawnSync(wslPath, ['-e', 'sh', '-lc', `command -v ${quotePosixArg(command)} >/dev/null 2>&1`], {
+        stdio: 'ignore',
+        timeout: 5000,
+    });
+    const ok = result.status === 0;
+    wslAvailabilityCache.set(command, ok);
+    return ok;
+}
+export function commandExists(command) {
+    if (availabilityCache.has(command)) {
+        return availabilityCache.get(command) ?? false;
+    }
+    const exists = lookupCommandPaths(command).length > 0 || (getProcessPlatform() === 'win32' && canUseWslBridge(command));
+    availabilityCache.set(command, exists);
+    return exists;
+}
+function resolveWindowsBuiltinCommand(candidate) {
+    const paths = lookupCommandPaths(candidate.command);
+    const native = paths.find(isWindowsNativeBinary);
+    if (native) {
+        return { ...candidate, kind: 'native', path: native };
+    }
+    const shim = paths.find(isWindowsCmdShim);
+    if (shim) {
+        return { ...candidate, kind: 'cmd-shim', path: shim };
+    }
+    if (canUseWslBridge(candidate.command)) {
+        const wslPath = lookupCommandPaths('wsl.exe')[0] ?? lookupCommandPaths('wsl')[0];
+        if (wslPath) {
+            return { ...candidate, kind: 'wsl-bridge', path: wslPath };
+        }
+    }
+    return null;
+}
+export function resolveBuiltinCommand(type) {
+    if (resolvedCache.has(type)) {
+        return resolvedCache.get(type) ?? null;
+    }
+    const resolved = BUILTIN_COMMANDS[type]
+        .map((candidate) => {
+        if (getProcessPlatform() === 'win32') {
+            return resolveWindowsBuiltinCommand(candidate);
+        }
+        const commandPath = lookupCommandPaths(candidate.command)[0];
+        return commandPath ? { ...candidate, kind: 'native', path: commandPath } : null;
+    })
+        .find(Boolean) ?? null;
+    resolvedCache.set(type, resolved);
+    return resolved;
+}
+export function buildLaunchSpec(spec, runtimeArgs, cwd) {
+    if (spec.kind === 'native') {
+        return {
+            command: spec.path,
+            args: [...spec.args, ...runtimeArgs],
+            cwd,
+        };
+    }
+    if (spec.kind === 'cmd-shim') {
+        const commandLine = [spec.path, ...spec.args, ...runtimeArgs].map(quoteCmdArg).join(' ');
+        return {
+            command: getWindowsShellPath(),
+            args: ['/d', '/s', '/c', `"${commandLine}"`],
+            cwd,
+        };
+    }
+    const wslCwd = cwd ? windowsPathToWsl(cwd) : undefined;
+    if (cwd && !wslCwd) {
+        throw new Error(`Cannot map Windows path to WSL workDir: ${cwd}`);
+    }
+    const shellCommand = [
+        wslCwd ? `cd ${quotePosixArg(wslCwd)}` : '',
+        `exec ${[spec.command, ...spec.args, ...runtimeArgs].map(quotePosixArg).join(' ')}`,
+    ].filter(Boolean).join(' && ');
+    return {
+        command: spec.path,
+        args: ['-e', 'sh', '-lc', shellCommand],
+        cwd: undefined,
+    };
+}
+export function spawnResolvedCommand(spec, runtimeArgs, options = {}) {
+    const launch = buildLaunchSpec(spec, runtimeArgs, options.cwd);
+    return spawn(launch.command, launch.args, {
+        ...options,
+        cwd: launch.cwd,
+        ...(getProcessPlatform() === 'win32' && spec.kind === 'cmd-shim'
+            ? { windowsVerbatimArguments: true }
+            : {}),
+    });
+}
+export function spawnResolvedCommandSync(spec, runtimeArgs, options = {}) {
+    const launch = buildLaunchSpec(spec, runtimeArgs, options.cwd);
+    return spawnSync(launch.command, launch.args, {
+        ...options,
+        cwd: launch.cwd,
+        ...(getProcessPlatform() === 'win32' && spec.kind === 'cmd-shim'
+            ? { windowsVerbatimArguments: true }
+            : {}),
+    });
+}
+export function parseCommandString(command) {
+    const args = [];
+    let current = '';
+    let inSingle = false;
+    let inDouble = false;
+    for (const ch of command) {
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (ch === ' ' && !inSingle && !inDouble) {
+            if (current) {
+                args.push(current);
+                current = '';
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current)
+        args.push(current);
+    return args;
+}
+export function buildCommandStringLaunchSpec(commandString, runtimeArgs, cwd) {
+    const parts = parseCommandString(commandString);
+    const bin = parts[0];
+    if (!bin) {
+        throw new Error('Command string is empty');
+    }
+    const baseArgs = parts.slice(1);
+    if (getProcessPlatform() !== 'win32') {
+        return {
+            command: bin,
+            args: [...baseArgs, ...runtimeArgs],
+            cwd,
+        };
+    }
+    const invocation = resolveArbitraryWindowsCommand(bin);
+    if (invocation.kind === 'cmd-shim') {
+        return {
+            command: getWindowsShellPath(),
+            args: ['/d', '/s', '/c', `"${[invocation.path, ...baseArgs, ...runtimeArgs].map(quoteCmdArg).join(' ')}"`],
+            cwd,
+        };
+    }
+    return {
+        command: invocation.path,
+        args: [...baseArgs, ...runtimeArgs],
+        cwd,
+    };
+}
+export function spawnCommandString(commandString, runtimeArgs, options = {}) {
+    const launch = buildCommandStringLaunchSpec(commandString, runtimeArgs, options.cwd);
+    const parts = parseCommandString(commandString);
+    const invocation = getProcessPlatform() === 'win32' && parts[0]
+        ? resolveArbitraryWindowsCommand(parts[0])
+        : null;
+    return spawn(launch.command, launch.args, {
+        ...options,
+        cwd: launch.cwd,
+        ...(getProcessPlatform() === 'win32' && invocation?.kind === 'cmd-shim'
+            ? { windowsVerbatimArguments: true }
+            : {}),
+    });
+}
+export function getCommandVersion(spec, flag = '--version') {
+    const result = spawnResolvedCommandSync(spec, [flag], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5000,
+    });
+    if (result.status !== 0)
+        return undefined;
+    const text = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    const match = text.match(/\d+\.\d+[\w.-]*/);
+    return match?.[0];
+}

package/dist/src/agents/cursor.d.ts

@@ -0,0 +1,22 @@
+import { AgentAdapter } from './adapter.js';
+export declare class CursorAdapter extends AgentAdapter {
+    readonly type: "cursor";
+    private process;
+    private chatId;
+    private workDir;
+    private seq;
+    private runId;
+    private emittedText;
+    start(_sessionId: string, workDir: string, agentSessionId?: string | null): Promise<void>;
+    send(text: string, modelId?: string): Promise<void>;
+    resume(agentSessionId: string): Promise<void>;
+    stop(): Promise<void>;
+    private spawnAndParse;
+    private handleStreamEvent;
+    private emitEvent;
+    private killProcess;
+    private resetRunState;
+    private isLiveAssistantDelta;
+    private emitTextDelta;
+    private emitFinalResultDelta;
+}

package/dist/src/agents/cursor.js

@@ -0,0 +1,248 @@
+// @arch docs/architecture/cli/agent-adapters.md
+// @test src/__tests__/cursor-adapter.test.ts
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+import { AgentAdapter, registerAgent } from './adapter.js';
+import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+export class CursorAdapter extends AgentAdapter {
+    type = 'cursor';
+    process = null;
+    chatId = null;
+    workDir = null;
+    seq = 0;
+    runId = '';
+    emittedText = '';
+    async start(_sessionId, workDir, agentSessionId) {
+        this.workDir = workDir;
+        this.seq = 0;
+        if (agentSessionId)
+            this.chatId = agentSessionId;
+    }
+    async send(text, modelId) {
+        await this.killProcess();
+        this.runId = randomUUID();
+        this.resetRunState();
+        const args = [
+            '-p', text,
+            '--output-format', 'stream-json',
+            '--stream-partial-output',
+            '--trust',
+        ];
+        if (modelId) {
+            args.push('--model', modelId);
+        }
+        if (this.chatId) {
+            args.push('--continue');
+        }
+        this.spawnAndParse(args);
+    }
+    async resume(agentSessionId) {
+        await this.killProcess();
+        this.chatId = agentSessionId;
+        this.runId = randomUUID();
+        this.resetRunState();
+        this.spawnAndParse([
+            '--resume', agentSessionId,
+            '--output-format', 'stream-json',
+            '--stream-partial-output',
+            '--trust',
+        ]);
+    }
+    async stop() {
+        await this.killProcess();
+    }
+    spawnAndParse(args) {
+        const spec = resolveBuiltinCommand('cursor');
+        if (!spec) {
+            this.emit('error', new Error('Cursor Agent CLI not found. Expected "agent" or "cursor agent".'));
+            return;
+        }
+        const proc = spawnResolvedCommand(spec, args, {
+            cwd: this.workDir ?? undefined,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env },
+        });
+        this.process = proc;
+        const rl = createInterface({ input: proc.stdout });
+        rl.on('line', (line) => {
+            if (!line.trim())
+                return;
+            try {
+                const obj = JSON.parse(line);
+                this.handleStreamEvent(obj);
+            }
+            catch {
+                // 非 JSON 行当作纯文本 delta
+                this.emitEvent({ state: 'delta', text: line });
+            }
+        });
+        let stderrBuf = '';
+        proc.stderr?.on('data', (chunk) => {
+            stderrBuf += chunk.toString();
+        });
+        proc.on('close', (code) => {
+            if (this.process !== proc)
+                return;
+            this.process = null;
+            if (code !== 0 && code !== null) {
+                const msg = stderrBuf.trim() || `cursor agent exited with code ${code}`;
+                this.emitEvent({ state: 'error', message: msg });
+            }
+        });
+        proc.on('error', (err) => {
+            if (this.process !== proc)
+                return;
+            this.process = null;
+            if (err.code === 'ENOENT') {
+                this.emit('error', new Error('Command "cursor" not found. Is Cursor CLI installed?'));
+            }
+            else {
+                this.emit('error', err);
+            }
+        });
+    }
+    handleStreamEvent(obj) {
+        if (obj.session_id && !this.chatId) {
+            this.chatId = obj.session_id;
+        }
+        if (obj.chat_id && !this.chatId) {
+            this.chatId = obj.chat_id;
+        }
+        const eventType = obj.type ?? obj.event;
+        switch (eventType) {
+            case 'system': {
+                // init event — session_id already captured above
+                break;
+            }
+            case 'assistant': {
+                // Cursor's --stream-partial-output currently emits duplicate buffered
+                // flushes. Only timestamped assistant events without model_call_id are
+                // safe to treat as live deltas; use result.result as the terminal
+                // canonical text.
+                if (obj.message?.content) {
+                    if (!this.isLiveAssistantDelta(obj))
+                        break;
+                    for (const block of obj.message.content) {
+                        if (block.type === 'text' && block.text) {
+                            this.emitTextDelta(block.text);
+                        }
+                        else if (block.type === 'thinking' && block.thinking) {
+                            this.emitEvent({ state: 'delta', text: block.thinking, thinking: true });
+                        }
+                        else if (block.type === 'tool_use') {
+                            this.emitEvent({ state: 'tool-call', name: block.name, args: block.input });
+                        }
+                    }
+                    break;
+                }
+                // Legacy flat
+                if (obj.delta ?? obj.text) {
+                    this.emitEvent({ state: 'delta', text: (obj.delta ?? obj.text) });
+                }
+                break;
+            }
+            case 'user': break; // echo of user message
+            case 'result': {
+                if (obj.subtype === 'success' || !obj.is_error) {
+                    this.emitFinalResultDelta(obj.result);
+                    const u = obj.usage;
+                    this.emitEvent({
+                        state: 'final',
+                        agentSessionId: this.chatId ?? undefined,
+                        usage: u
+                            ? {
+                                inputTokens: u.inputTokens ?? u.input_tokens ?? 0,
+                                outputTokens: u.outputTokens ?? u.output_tokens ?? 0,
+                            }
+                            : undefined,
+                    });
+                }
+                else {
+                    this.emitEvent({
+                        state: 'error',
+                        message: obj.result ?? obj.error ?? 'unknown error',
+                    });
+                }
+                break;
+            }
+            case 'error': {
+                this.emitEvent({
+                    state: 'error',
+                    message: obj.error ?? 'unknown error',
+                });
+                break;
+            }
+            // Legacy event types
+            case 'text':
+            case 'delta':
+            case 'content': {
+                const text = obj.delta ?? obj.text;
+                if (text)
+                    this.emitEvent({ state: 'delta', text });
+                break;
+            }
+            case 'done': {
+                this.emitEvent({ state: 'final', agentSessionId: this.chatId ?? undefined });
+                break;
+            }
+            default: {
+                if (obj.done) {
+                    this.emitEvent({ state: 'final', agentSessionId: this.chatId ?? undefined });
+                }
+                else if (obj.delta ?? obj.text) {
+                    this.emitEvent({ state: 'delta', text: (obj.delta ?? obj.text) });
+                }
+            }
+        }
+    }
+    emitEvent(partial) {
+        const event = {
+            ...partial,
+            runId: this.runId,
+            seq: this.seq++,
+        };
+        this.emit('agentEvent', event);
+    }
+    async killProcess() {
+        const proc = this.process;
+        if (!proc)
+            return;
+        this.process = null;
+        proc.kill('SIGTERM');
+        await new Promise((resolve) => {
+            proc.on('close', resolve);
+            setTimeout(() => {
+                proc.kill('SIGKILL');
+                resolve();
+            }, 3000);
+        });
+    }
+    resetRunState() {
+        this.seq = 0;
+        this.emittedText = '';
+    }
+    isLiveAssistantDelta(obj) {
+        return obj.timestamp_ms != null && !obj.model_call_id;
+    }
+    emitTextDelta(text) {
+        if (!text)
+            return;
+        this.emittedText += text;
+        this.emitEvent({ state: 'delta', text });
+    }
+    emitFinalResultDelta(result) {
+        if (!result)
+            return;
+        if (!this.emittedText) {
+            this.emitTextDelta(result);
+            return;
+        }
+        if (!result.startsWith(this.emittedText))
+            return;
+        const tail = result.slice(this.emittedText.length);
+        if (tail) {
+            this.emitTextDelta(tail);
+        }
+    }
+}
+registerAgent('cursor', () => new CursorAdapter());

package/dist/src/agents/custom.d.ts

@@ -0,0 +1,30 @@
+import { AgentAdapter } from './adapter.js';
+import type { CustomAgentType } from '@shennian/wire';
+import type { CustomAgentEntry } from '../config/index.js';
+export declare class CustomAgentAdapter extends AgentAdapter {
+    readonly type: CustomAgentType;
+    private command;
+    private mode;
+    private proactive;
+    private sessionId;
+    private agentSessionId;
+    private workDir;
+    private runId;
+    private seq;
+    private stdioProcess;
+    private spawnProcess;
+    constructor(name: string, entry: CustomAgentEntry);
+    start(sessionId: string, workDir: string, agentSessionId?: string | null): Promise<void>;
+    send(text: string, modelId?: string): Promise<void>;
+    resume(agentSessionId: string): Promise<void>;
+    stop(): Promise<void>;
+    private runSpawn;
+    private killSpawnProcess;
+    private startStdioProcess;
+    private sendStdio;
+    private stopStdioProcess;
+    private attachOutputHandlers;
+    private handleProtocolEvent;
+    private emitEvent;
+}
+export declare function registerCustomAgent(name: string, entry: CustomAgentEntry): void;