oh-my-knowledge 0.52.3 → 0.54.0

package/dist/executors/core/http.js

@@ -0,0 +1,19 @@
+export async function readJsonResponse(response) {
+    const rawBody = await response.text();
+    if (!rawBody.trim())
+        return { data: null, rawBody };
+    try {
+        return { data: JSON.parse(rawBody), rawBody };
+    }
+    catch {
+        return { data: null, rawBody };
+    }
+}
+export function responseBodyPreview(rawBody, maxLength = 500) {
+    const normalized = rawBody.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return '';
+    return normalized.length > maxLength
+        ? `${normalized.slice(0, maxLength)}...`
+        : normalized;
+}

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

@@ -0,0 +1,2 @@
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+export declare const MAX_BUFFER: number;

package/dist/executors/core/limits.js

@@ -0,0 +1,2 @@
+export const DEFAULT_TIMEOUT_MS = 600_000;
+export const MAX_BUFFER = 10 * 1024 * 1024;

package/dist/executors/core/optional-dependencies.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutableExecutorName } from './registry.js';
+export interface OptionalExecutorDependency {
+    readonly packageName: string;
+    readonly installSpec: string;
+}
+export declare function getOptionalExecutorDependency(executorName: ExecutableExecutorName): OptionalExecutorDependency | undefined;
+export declare function assertOptionalExecutorDependency(executorName: ExecutableExecutorName, available?: (packageName: string) => boolean): void;

package/dist/executors/core/optional-dependencies.js

@@ -0,0 +1,35 @@
+const OPTIONAL_EXECUTOR_DEPENDENCIES = {
+    'claude-sdk': {
+        packageName: '@anthropic-ai/claude-agent-sdk',
+        installSpec: '@anthropic-ai/claude-agent-sdk@^0.3.143',
+    },
+    'codex-sdk': {
+        packageName: '@openai/codex-sdk',
+        installSpec: '@openai/codex-sdk@^0.149.0',
+    },
+};
+export function getOptionalExecutorDependency(executorName) {
+    return OPTIONAL_EXECUTOR_DEPENDENCIES[executorName];
+}
+function packageAvailable(packageName) {
+    try {
+        // Use ESM resolution because @openai/codex-sdk only exposes an `import`
+        // condition; createRequire().resolve() reports ERR_PACKAGE_PATH_NOT_EXPORTED
+        // even when that optional peer is correctly installed.
+        import.meta.resolve(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assertOptionalExecutorDependency(executorName, available = packageAvailable) {
+    const dependency = getOptionalExecutorDependency(executorName);
+    if (!dependency || available(dependency.packageName))
+        return;
+    throw new Error([
+        `执行器「${executorName}」需要可选依赖「${dependency.packageName}」，但当前 OMK 安装作用域中未找到。`,
+        `本地安装：npm install ${dependency.installSpec}`,
+        `全局安装：npm install -g ${dependency.installSpec}`,
+    ].join('\n'));
+}

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;