oh-my-knowledge 0.52.3 → 0.53.0

package/dist/executors/core/registry.d.ts

@@ -0,0 +1,145 @@
+export type ExecutorVendor = 'anthropic' | 'openai' | 'unknown';
+export type ExecutorFamily = 'claude' | 'codex' | 'dsh' | 'anthropic-api' | 'openai-api';
+export type SampleMockSupport = 'native-hooks' | 'delegated-script' | 'unsupported';
+export interface ExecutorCapabilities {
+    sampleMocks: SampleMockSupport;
+}
+export type ExecutorFingerprintSpec = {
+    readonly strategy: 'path-cli';
+    readonly command: 'claude' | 'codex';
+} | {
+    readonly strategy: 'claude-sdk';
+} | {
+    readonly strategy: 'codex-sdk';
+} | {
+    readonly strategy: 'api';
+} | {
+    readonly strategy: 'dsh-host';
+};
+declare const EXECUTOR_DESCRIPTORS: readonly [{
+    readonly name: "claude";
+    readonly execution: "builtin";
+    readonly family: "claude";
+    readonly vendor: "anthropic";
+    readonly sampleMocks: "native-hooks";
+    readonly runtimeKind: "agent-cli";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "native";
+        readonly costUSD: "reported";
+        readonly trace: "native";
+        readonly skillIsolation: "full-no-partial";
+    };
+    readonly fingerprint: {
+        readonly strategy: "path-cli";
+        readonly command: "claude";
+    };
+}, {
+    readonly name: "claude-sdk";
+    readonly execution: "builtin";
+    readonly family: "claude";
+    readonly vendor: "anthropic";
+    readonly sampleMocks: "native-hooks";
+    readonly runtimeKind: "agent-sdk";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "native";
+        readonly costUSD: "reported";
+        readonly trace: "native";
+        readonly skillIsolation: "full";
+    };
+    readonly fingerprint: {
+        readonly strategy: "claude-sdk";
+    };
+}, {
+    readonly name: "codex";
+    readonly execution: "builtin";
+    readonly family: "codex";
+    readonly vendor: "openai";
+    readonly sampleMocks: "unsupported";
+    readonly runtimeKind: "agent-cli";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "prepended";
+        readonly costUSD: "not-reported";
+        readonly trace: "best-effort";
+        readonly skillIsolation: "cwd-only";
+    };
+    readonly fingerprint: {
+        readonly strategy: "path-cli";
+        readonly command: "codex";
+    };
+}, {
+    readonly name: "codex-sdk";
+    readonly execution: "builtin";
+    readonly family: "codex";
+    readonly vendor: "openai";
+    readonly sampleMocks: "unsupported";
+    readonly runtimeKind: "agent-sdk";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "prepended";
+        readonly costUSD: "not-reported";
+        readonly trace: "best-effort";
+        readonly skillIsolation: "cwd-only";
+    };
+    readonly fingerprint: {
+        readonly strategy: "codex-sdk";
+    };
+}, {
+    readonly name: "dsh-host";
+    readonly execution: "host-only";
+    readonly family: "dsh";
+    readonly vendor: "unknown";
+    readonly sampleMocks: "unsupported";
+    readonly runtimeKind: "agent-sdk";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "native";
+        readonly costUSD: "not-reported";
+        readonly trace: "native";
+        readonly skillIsolation: "full-no-partial";
+    };
+    readonly fingerprint: {
+        readonly strategy: "dsh-host";
+    };
+}, {
+    readonly name: "anthropic-api";
+    readonly execution: "builtin";
+    readonly family: "anthropic-api";
+    readonly vendor: "anthropic";
+    readonly sampleMocks: "unsupported";
+    readonly runtimeKind: "api";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "native";
+        readonly costUSD: "not-reported";
+        readonly trace: "none";
+        readonly skillIsolation: "none";
+    };
+    readonly fingerprint: {
+        readonly strategy: "api";
+    };
+}, {
+    readonly name: "openai-api";
+    readonly execution: "builtin";
+    readonly family: "openai-api";
+    readonly vendor: "openai";
+    readonly sampleMocks: "unsupported";
+    readonly runtimeKind: "api";
+    readonly runtimeCapabilities: {
+        readonly systemPrompt: "native";
+        readonly costUSD: "not-reported";
+        readonly trace: "none";
+        readonly skillIsolation: "none";
+    };
+    readonly fingerprint: {
+        readonly strategy: "api";
+    };
+}];
+export type RegisteredExecutorDescriptor = (typeof EXECUTOR_DESCRIPTORS)[number];
+export type RegisteredExecutorName = RegisteredExecutorDescriptor['name'];
+export type ExecutableExecutorName = Extract<RegisteredExecutorDescriptor, {
+    execution: 'builtin';
+}>['name'];
+export declare function executorDescriptors(): readonly RegisteredExecutorDescriptor[];
+export declare function getExecutorDescriptor(name: string): RegisteredExecutorDescriptor | undefined;
+export declare function isRegisteredExecutorName(name: string): name is RegisteredExecutorName;
+export declare function executorVendor(executor: string): ExecutorVendor;
+export declare function executorFamily(executor: string): ExecutorFamily | 'custom';
+export declare function executorNamesForFamily(family: ExecutorFamily): ReadonlySet<string>;
+export {};

package/dist/executors/core/registry.js

@@ -0,0 +1,127 @@
+const EXECUTOR_DESCRIPTORS = [
+    {
+        name: 'claude',
+        execution: 'builtin',
+        family: 'claude',
+        vendor: 'anthropic',
+        sampleMocks: 'native-hooks',
+        runtimeKind: 'agent-cli',
+        runtimeCapabilities: {
+            systemPrompt: 'native',
+            costUSD: 'reported',
+            trace: 'native',
+            skillIsolation: 'full-no-partial',
+        },
+        fingerprint: { strategy: 'path-cli', command: 'claude' },
+    },
+    {
+        name: 'claude-sdk',
+        execution: 'builtin',
+        family: 'claude',
+        vendor: 'anthropic',
+        sampleMocks: 'native-hooks',
+        runtimeKind: 'agent-sdk',
+        runtimeCapabilities: {
+            systemPrompt: 'native',
+            costUSD: 'reported',
+            trace: 'native',
+            skillIsolation: 'full',
+        },
+        fingerprint: { strategy: 'claude-sdk' },
+    },
+    {
+        name: 'codex',
+        execution: 'builtin',
+        family: 'codex',
+        vendor: 'openai',
+        sampleMocks: 'unsupported',
+        runtimeKind: 'agent-cli',
+        runtimeCapabilities: {
+            systemPrompt: 'prepended',
+            costUSD: 'not-reported',
+            trace: 'best-effort',
+            skillIsolation: 'cwd-only',
+        },
+        fingerprint: { strategy: 'path-cli', command: 'codex' },
+    },
+    {
+        name: 'codex-sdk',
+        execution: 'builtin',
+        family: 'codex',
+        vendor: 'openai',
+        sampleMocks: 'unsupported',
+        runtimeKind: 'agent-sdk',
+        runtimeCapabilities: {
+            systemPrompt: 'prepended',
+            costUSD: 'not-reported',
+            trace: 'best-effort',
+            skillIsolation: 'cwd-only',
+        },
+        fingerprint: { strategy: 'codex-sdk' },
+    },
+    {
+        name: 'dsh-host',
+        execution: 'host-only',
+        family: 'dsh',
+        vendor: 'unknown',
+        sampleMocks: 'unsupported',
+        runtimeKind: 'agent-sdk',
+        runtimeCapabilities: {
+            systemPrompt: 'native',
+            costUSD: 'not-reported',
+            trace: 'native',
+            skillIsolation: 'full-no-partial',
+        },
+        fingerprint: { strategy: 'dsh-host' },
+    },
+    {
+        name: 'anthropic-api',
+        execution: 'builtin',
+        family: 'anthropic-api',
+        vendor: 'anthropic',
+        sampleMocks: 'unsupported',
+        runtimeKind: 'api',
+        runtimeCapabilities: {
+            systemPrompt: 'native',
+            costUSD: 'not-reported',
+            trace: 'none',
+            skillIsolation: 'none',
+        },
+        fingerprint: { strategy: 'api' },
+    },
+    {
+        name: 'openai-api',
+        execution: 'builtin',
+        family: 'openai-api',
+        vendor: 'openai',
+        sampleMocks: 'unsupported',
+        runtimeKind: 'api',
+        runtimeCapabilities: {
+            systemPrompt: 'native',
+            costUSD: 'not-reported',
+            trace: 'none',
+            skillIsolation: 'none',
+        },
+        fingerprint: { strategy: 'api' },
+    },
+];
+export function executorDescriptors() {
+    return EXECUTOR_DESCRIPTORS;
+}
+export function getExecutorDescriptor(name) {
+    return EXECUTOR_DESCRIPTORS.find((descriptor) => descriptor.name === name);
+}
+export function isRegisteredExecutorName(name) {
+    return getExecutorDescriptor(name) !== undefined;
+}
+export function executorVendor(executor) {
+    return getExecutorDescriptor(executor)?.vendor ?? 'unknown';
+}
+export function executorFamily(executor) {
+    return getExecutorDescriptor(executor)?.family ?? 'custom';
+}
+export function executorNamesForFamily(family) {
+    return new Set(EXECUTOR_DESCRIPTORS
+        .filter((descriptor) => descriptor.family === family)
+        .map((descriptor) => descriptor.name));
+}

package/dist/executors/core/runtime-fingerprint.d.ts

@@ -0,0 +1,13 @@
+import type { ExecutorFn, ExecutorRuntimeFingerprint } from '../../types/index.js';
+export interface DshHostRuntimeIdentity {
+    provider?: string;
+    agentPreset?: string;
+    toolSchemas?: readonly unknown[];
+}
+export interface ExecutorRuntimeFingerprintOptions {
+    skillDir?: string | null;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function createDshHostRuntimeFingerprint(model: string, identity?: DshHostRuntimeIdentity): ExecutorRuntimeFingerprint;
+export declare function resolveExecutorRuntimeFingerprint(executorName: string, model: string, options?: ExecutorRuntimeFingerprintOptions, executor?: ExecutorFn): ExecutorRuntimeFingerprint;
+export declare function getExecutorRuntimeFingerprint(executorName: string, model: string, options?: ExecutorRuntimeFingerprintOptions): ExecutorRuntimeFingerprint;

package/dist/executors/{runtime-fingerprint.js → core/runtime-fingerprint.js}

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { delimiter, dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildExecEnv } from './shared.js';
-import { isScriptFileInterpreter, resolveScriptCommand, } from './script-command.js';
+import { buildExecEnv } from './runtime.js';
+import { isScriptFileInterpreter, resolveScriptCommand, } from '../script/command.js';
+import { getExecutorDescriptor } from './registry.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const requireFromHere = createRequire(import.meta.url);
 const RUNTIME_CACHE = new Map();
@@ -56,6 +57,50 @@ function findNearestPackageJson(fromPath) {
     }
     return null;
 }
+function readInvokingDshPackage() {
+    const invokedEntrypoint = process.argv[1];
+    if (!invokedEntrypoint || !isAbsolute(invokedEntrypoint)) {
+        return {
+            package: { name: '@deepseek-ai/dsh', error: 'DSH host entrypoint not found' },
+        };
+    }
+    let entrypoint = invokedEntrypoint;
+    try {
+        entrypoint = realpathSync(invokedEntrypoint);
+    }
+    catch {
+        // Keep the invoked path so the audit record still explains the lookup failure.
+    }
+    let dir = dirname(entrypoint);
+    for (let i = 0; i < 10; i++) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                if (pkg.name === '@deepseek-ai/dsh') {
+                    return {
+                        entrypoint,
+                        package: {
+                            name: pkg.name,
+                            ...(pkg.version ? { version: pkg.version } : {}),
+                        },
+                    };
+                }
+            }
+            catch {
+                // Keep walking: a parent package may still be the DSH CLI package.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return {
+        entrypoint,
+        package: { name: '@deepseek-ai/dsh', error: 'invoking @deepseek-ai/dsh package.json not found' },
+    };
+}
 function resolvePackageJson(packageName, from) {
     const req = from ? createRequire(from) : requireFromHere;
     try {
@@ -165,6 +210,7 @@ function withFingerprint(input) {
                 status: input.sdk.version ? 'ok' : input.sdk.error ? 'error' : 'missing',
             }
             : undefined,
+        ...(input.auditability ? { auditability: input.auditability } : {}),
         capabilities: input.capabilities,
     };
     return { ...input, fingerprint: hashString(canonicalStringify(stablePayload)) };
@@ -178,6 +224,32 @@ function runtime(executor, model, kind, capabilities, extra = {}) {
         ...extra,
     });
 }
+function ownPackage() {
+    const packageJson = findNearestPackageJson(fileURLToPath(import.meta.url));
+    if (!packageJson)
+        return { name: 'oh-my-knowledge', error: 'package.json not found' };
+    try {
+        const pkg = JSON.parse(readFileSync(packageJson, 'utf-8'));
+        return {
+            name: pkg.name ?? 'oh-my-knowledge',
+            ...(pkg.version ? { version: pkg.version } : {}),
+        };
+    }
+    catch (error) {
+        return {
+            name: 'oh-my-knowledge',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function dshCompositionHash(identity) {
+    return createHash('sha256').update(canonicalStringify({
+        adapter: 'omk-dsh-host-v1',
+        provider: identity.provider ?? null,
+        agentPreset: identity.agentPreset ?? null,
+        toolSchemas: identity.toolSchemas ?? null,
+    })).digest('hex');
+}
 function runtimeEnv(options) {
     return options?.env ?? buildExecEnv(options?.skillDir);
 }
@@ -245,48 +317,63 @@ function scriptRuntime(executorName, model, env) {
         },
     });
 }
+export function createDshHostRuntimeFingerprint(model, identity = {}) {
+    const descriptor = getExecutorDescriptor('dsh-host');
+    if (!descriptor || descriptor.name !== 'dsh-host') {
+        throw new Error('dsh-host executor descriptor is missing');
+    }
+    const host = readInvokingDshPackage();
+    return runtime(descriptor.name, model, descriptor.runtimeKind, descriptor.runtimeCapabilities, {
+        binary: {
+            name: '@deepseek-ai/dsh',
+            source: host.package.version ? 'path' : 'unknown',
+            ...(host.package.version ? { version: host.package.version } : {}),
+            ...(host.entrypoint ? { path: host.entrypoint } : {}),
+            contentHash: dshCompositionHash(identity),
+            package: host.package,
+            ...(host.package.error ? { error: host.package.error } : {}),
+        },
+        sdk: ownPackage(),
+        auditability: {
+            status: 'partial',
+            reasons: [
+                'DSH does not expose a canonical digest for every active plugin and policy; the fingerprint covers provider, agent preset, and effective tool schemas',
+            ],
+        },
+    });
+}
+export function resolveExecutorRuntimeFingerprint(executorName, model, options = {}, executor) {
+    return executor?.runtimeFingerprint?.(model, options)
+        ?? getExecutorRuntimeFingerprint(executorName, model, options);
+}
 export function getExecutorRuntimeFingerprint(executorName, model, options = {}) {
     const env = runtimeEnv(options);
-    if (![
-        'claude',
-        'claude-sdk',
-        'codex',
-        'codex-sdk',
-        'gemini',
-        'anthropic-api',
-        'openai-api',
-    ].includes(executorName)) {
+    const descriptor = getExecutorDescriptor(executorName);
+    if (!descriptor) {
         // Custom executors are local code. Re-read their referenced files so a
         // long-running Studio process cannot reuse stale outputs after the script
         // changes while the command line remains identical.
         return scriptRuntime(executorName, model, env);
     }
+    if (descriptor.fingerprint.strategy === 'dsh-host') {
+        return createDshHostRuntimeFingerprint(model);
+    }
     const pathHash = hashString(env.PATH || '');
     const cacheKey = `${executorName}\0${model}\0${pathHash}`;
     const cached = RUNTIME_CACHE.get(cacheKey);
     if (cached)
         return structuredClone(cached);
     let fp;
-    switch (executorName) {
-        case 'claude': {
-            fp = runtime(executorName, model, 'agent-cli', {
-                systemPrompt: 'native',
-                costUSD: 'reported',
-                trace: 'native',
-                skillIsolation: 'full-no-partial',
-            }, { binary: readPathBinary('claude', env) });
+    switch (descriptor.fingerprint.strategy) {
+        case 'path-cli': {
+            fp = runtime(descriptor.name, model, descriptor.runtimeKind, descriptor.runtimeCapabilities, { binary: readPathBinary(descriptor.fingerprint.command, env) });
             break;
         }
         case 'claude-sdk': {
             const sdkPackageJson = resolvePackageJson('@anthropic-ai/claude-agent-sdk');
             const sdk = readPackage('@anthropic-ai/claude-agent-sdk', sdkPackageJson ?? undefined);
             const claudeCodeVersion = readPackageField('@anthropic-ai/claude-agent-sdk', 'claudeCodeVersion', sdkPackageJson ?? undefined);
-            fp = runtime(executorName, model, 'agent-sdk', {
-                systemPrompt: 'native',
-                costUSD: 'reported',
-                trace: 'native',
-                skillIsolation: 'full',
-            }, {
+            fp = runtime(descriptor.name, model, descriptor.runtimeKind, descriptor.runtimeCapabilities, {
                 sdk,
                 binary: {
                     name: 'claude-code',
@@ -297,25 +384,11 @@ export function getExecutorRuntimeFingerprint(executorName, model, options = {})
             });
             break;
         }
-        case 'codex': {
-            fp = runtime(executorName, model, 'agent-cli', {
-                systemPrompt: 'prepended',
-                costUSD: 'not-reported',
-                trace: 'best-effort',
-                skillIsolation: 'cwd-only',
-            }, { binary: readPathBinary('codex', env) });
-            break;
-        }
         case 'codex-sdk': {
             const sdkPackageJson = resolvePackageJson('@openai/codex-sdk');
             const sdk = readPackage('@openai/codex-sdk', sdkPackageJson ?? undefined);
             const bundledCodex = readPackage('@openai/codex', sdkPackageJson ?? undefined);
-            fp = runtime(executorName, model, 'agent-sdk', {
-                systemPrompt: 'prepended',
-                costUSD: 'not-reported',
-                trace: 'best-effort',
-                skillIsolation: 'cwd-only',
-            }, {
+            fp = runtime(descriptor.name, model, descriptor.runtimeKind, descriptor.runtimeCapabilities, {
                 sdk,
                 binary: {
                     name: 'codex',
@@ -326,27 +399,14 @@ export function getExecutorRuntimeFingerprint(executorName, model, options = {})
             });
             break;
         }
-        case 'gemini': {
-            fp = runtime(executorName, model, 'agent-cli', {
-                systemPrompt: 'prepended',
-                costUSD: 'not-reported',
-                trace: 'none',
-                skillIsolation: 'none',
-            }, { binary: readPathBinary('gemini', env) });
+        case 'api': {
+            fp = runtime(descriptor.name, model, descriptor.runtimeKind, descriptor.runtimeCapabilities, { binary: { name: descriptor.name, source: 'none' } });
             break;
         }
-        case 'anthropic-api':
-        case 'openai-api': {
-            fp = runtime(executorName, model, 'api', {
-                systemPrompt: 'native',
-                costUSD: 'not-reported',
-                trace: 'none',
-                skillIsolation: 'none',
-            }, { binary: { name: executorName, source: 'none' } });
-            break;
+        default: {
+            const unreachable = descriptor.fingerprint;
+            throw new Error(`unreachable executor fingerprint strategy: ${JSON.stringify(unreachable)}`);
         }
-        default:
-            throw new Error(`unreachable executor runtime: ${executorName}`);
     }
     RUNTIME_CACHE.set(cacheKey, structuredClone(fp));
     return structuredClone(fp);

package/dist/executors/core/runtime.d.ts

@@ -0,0 +1,12 @@
+import type { ExecResult } from '../../types/index.js';
+export interface ExecutorErrorLike {
+    message?: string;
+    name?: string;
+    killed?: boolean;
+    stdout?: string;
+}
+export declare function asErrorLike(err: unknown): ExecutorErrorLike;
+export declare function errorMessage(err: unknown, fallback?: string): string;
+export declare function buildExecEnv(skillDir?: string | null): NodeJS.ProcessEnv;
+export declare function timeoutExecResult(timeoutMs: number, durationMs: number): ExecResult;
+export declare function interruptedExecResult(durationMs: number): ExecResult;

package/dist/executors/core/runtime.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+export function asErrorLike(err) {
+    return typeof err === 'object' && err !== null ? err : {};
+}
+export function errorMessage(err, fallback = 'unknown error') {
+    const details = asErrorLike(err);
+    return details.message || fallback;
+}
+export function buildExecEnv(skillDir) {
+    const proxyUrl = process.env.CCV_PROXY_URL || undefined;
+    const env = proxyUrl
+        ? { ...process.env, ANTHROPIC_BASE_URL: proxyUrl }
+        : { ...process.env };
+    if (skillDir) {
+        const nodeBin = join(skillDir, 'node_modules', '.bin');
+        if (existsSync(nodeBin)) {
+            env.PATH = `${nodeBin}${env.PATH ? delimiter + env.PATH : ''}`;
+        }
+    }
+    return env;
+}
+export function timeoutExecResult(timeoutMs, durationMs) {
+    return {
+        ok: false,
+        error: `execution timed out after ${timeoutMs / 1000}s`,
+        durationMs,
+        durationApiMs: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        tokenUsageReportedByExecutor: false,
+        costUSD: 0,
+        costReportedByExecutor: false,
+        output: null,
+        stopReason: 'timeout',
+        numTurns: 0,
+    };
+}
+// SIGINT-killed child（用户在 host 按 Ctrl+C，parent 收到 SIGINT 后广播 SIGTERM 给 children）
+// 跟 timeout-killed 区分：stopReason='interrupted'，跟 'timeout' / 'error' 都不一样，
+// caller / renderer 可以据此显示不同的语义（"用户中断" vs "超时" vs "执行错误"）。
+export function interruptedExecResult(durationMs) {
+    return {
+        ok: false,
+        error: 'execution interrupted (SIGINT)',
+        durationMs,
+        durationApiMs: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        tokenUsageReportedByExecutor: false,
+        costUSD: 0,
+        costReportedByExecutor: false,
+        output: null,
+        stopReason: 'interrupted',
+        numTurns: 0,
+    };
+}

package/dist/executors/core/subprocess.d.ts

@@ -0,0 +1,44 @@
+import { type ChildProcess } from 'node:child_process';
+/**
+ * Register an in-process runtime (for example an SDK-owned child) with the
+ * same SIGINT coordinator used by spawned executors.
+ */
+export declare function registerSigintSubscriber(subscriber: () => void): () => void;
+export declare function __resetSigintRegistryForTest(): void;
+export interface SpawnHelperResult {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    killedByTimeout: boolean;
+    killedBySignal: NodeJS.Signals | null;
+}
+export interface SpawnHelperError extends Error {
+    stdout?: string;
+    stderr?: string;
+    code?: number | null;
+    signal?: NodeJS.Signals | null;
+    killedByTimeout?: boolean;
+    killedBySignal?: NodeJS.Signals | null;
+}
+export interface SpawnHelperOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** kill child after this many ms; reject with killedByTimeout=true */
+    timeoutMs?: number;
+    /** per-stream stdout/stderr byte limit; reject when either stream exceeds it */
+    maxBuffer?: number;
+    /** external abort signal; abort() 走跟 SIGINT 同一 grace 路径 */
+    abortSignal?: AbortSignal;
+}
+/**
+ * spawn child + 注册到全局 SIGINT registry。返回 { child, done } 让 caller 自己
+ * 操作 stdin（写入 / 关闭），通过 done 等结果。
+ *
+ * 适用：claude / codex / script CLI 子进程。HTTP executor（*-api）用 fetch +
+ * AbortSignal.timeout，自带 abort，不走这个。claude-sdk in-process 也不走。
+ */
+export declare function spawnWithSigintPropagation(command: string, args: string[], options?: SpawnHelperOptions): {
+    child: ChildProcess;
+    done: Promise<SpawnHelperResult>;
+};