@h-ai/runner 0.0.0-stage → 1.0.0-beta.24

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+import { Writable, Readable } from 'node:stream';
+
+declare const resources: z.ZodObject<{
+    cpu: z.ZodNumber;
+    memoryMiB: z.ZodNumber;
+    pids: z.ZodNumber;
+    scratchMiB: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * 容器资源限制；CPU 为核心数，内存和临时盘使用 MiB。
+ * @example
+ * ```ts
+ * import type { RunnerResources } from '@h-ai/runner'
+ * const resources: RunnerResources = { cpu: 1, memoryMiB: 256, pids: 32, scratchMiB: 64 }
+ * ```
+ */
+type RunnerResources = z.infer<typeof resources>;
+/**
+ * 已登记且固定镜像的执行环境。
+ * @example
+ * ```ts
+ * import type { RunnerEnvironment } from '@h-ai/runner'
+ * function resolveImage(environment: RunnerEnvironment) { return environment.image }
+ * ```
+ */
+type RunnerEnvironment = z.infer<typeof environment>;
+declare const environment: z.ZodObject<{
+    id: z.ZodString;
+    image: z.ZodString;
+    backend: z.ZodDefault<z.ZodLiteral<"container">>;
+    architecture: z.ZodOptional<z.ZodEnum<{
+        x64: "x64";
+        arm64: "arm64";
+    }>>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    resources: z.ZodObject<{
+        cpu: z.ZodNumber;
+        memoryMiB: z.ZodNumber;
+        pids: z.ZodNumber;
+        scratchMiB: z.ZodNumber;
+    }, z.core.$strict>;
+    networkPolicy: z.ZodDefault<z.ZodEnum<{
+        offline: "offline";
+        internal: "internal";
+    }>>;
+    network: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Runner 启动配置 Schema。执行节点 ID 在部署中保持唯一。
+ * @example
+ * ```ts
+ * import { RunnerConfigSchema } from '@h-ai/runner'
+ * const result = RunnerConfigSchema.safeParse({ nodeId: 'api', executor: false })
+ * ```
+ */
+declare const RunnerConfigSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    executor: z.ZodDefault<z.ZodBoolean>;
+    engine: z.ZodDefault<z.ZodEnum<{
+        podman: "podman";
+        docker: "docker";
+    }>>;
+    capacity: z.ZodDefault<z.ZodObject<{
+        cpu: z.ZodNumber;
+        memoryMiB: z.ZodNumber;
+        pids: z.ZodNumber;
+        scratchMiB: z.ZodNumber;
+    }, z.core.$strict>>;
+    toolCapacity: z.ZodDefault<z.ZodObject<{
+        cpu: z.ZodNumber;
+        memoryMiB: z.ZodNumber;
+        pids: z.ZodNumber;
+        scratchMiB: z.ZodNumber;
+    }, z.core.$strict>>;
+    toolMaxRunning: z.ZodDefault<z.ZodNumber>;
+    leaseMs: z.ZodDefault<z.ZodNumber>;
+    pollMs: z.ZodDefault<z.ZodNumber>;
+    maxRunning: z.ZodDefault<z.ZodNumber>;
+    maxRunningPerScope: z.ZodDefault<z.ZodNumber>;
+    maxControlRunning: z.ZodDefault<z.ZodNumber>;
+    maxQueued: z.ZodDefault<z.ZodNumber>;
+    maxEvents: z.ZodDefault<z.ZodNumber>;
+    closeTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    environments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        image: z.ZodString;
+        backend: z.ZodDefault<z.ZodLiteral<"container">>;
+        architecture: z.ZodOptional<z.ZodEnum<{
+            x64: "x64";
+            arm64: "arm64";
+        }>>;
+        capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        resources: z.ZodObject<{
+            cpu: z.ZodNumber;
+            memoryMiB: z.ZodNumber;
+            pids: z.ZodNumber;
+            scratchMiB: z.ZodNumber;
+        }, z.core.$strict>;
+        networkPolicy: z.ZodDefault<z.ZodEnum<{
+            offline: "offline";
+            internal: "internal";
+        }>>;
+        network: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/**
+ * 启动参数；默认执行角色，API 节点可单独关闭执行。
+ * @example
+ * ```ts
+ * import type { RunnerConfigInput } from '@h-ai/runner'
+ * const config: RunnerConfigInput = { nodeId: 'api-east', executor: false }
+ * ```
+ */
+type RunnerConfigInput = z.input<typeof RunnerConfigSchema>;
+/**
+ * 持久 JSON 字段的校验，包括有限数值。
+ * @example 模块内部上下文
+ * ```ts
+ * const value = json.safeParse({ message: 'ready' })
+ * ```
+ */
+declare const json: z.ZodJSONSchema;
+/**
+ * 持久提交及主体校验。
+ * @example 模块内部上下文
+ * ```ts
+ * const value = submitSchema.safeParse({ scope: { tenantId: 'work', userId: 'alice' }, kind: 'report', input: null })
+ * ```
+ */
+declare const submitSchema: z.ZodObject<{
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+    }, z.core.$strict>;
+    kind: z.ZodString;
+    input: z.ZodJSONSchema;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    environmentId: z.ZodOptional<z.ZodString>;
+    resources: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodOptional<z.ZodNumber>;
+        memoryMiB: z.ZodOptional<z.ZodNumber>;
+        pids: z.ZodOptional<z.ZodNumber>;
+        scratchMiB: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    nodeId: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodOptional<z.ZodString>;
+    capacityClass: z.ZodDefault<z.ZodEnum<{
+        default: "default";
+        tool: "tool";
+    }>>;
+    warmPool: z.ZodOptional<z.ZodLiteral<true>>;
+    concurrency: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        limit: z.ZodNumber;
+    }, z.core.$strict>>;
+    reuseKey: z.ZodOptional<z.ZodString>;
+    queueTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    runTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+
+/**
+ * 持久执行错误定义。业务处理失败另记录为执行终态。
+ * @example
+ * ```ts
+ * import { HaiRunnerError } from '@h-ai/runner'
+ * const key = HaiRunnerError.CONFLICT
+ * ```
+ */
+declare const HaiRunnerError: {
+    NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    ALREADY_INITIALIZED: _h_ai_core.HaiErrorDef;
+    INVALID: _h_ai_core.HaiErrorDef;
+    NOT_FOUND: _h_ai_core.HaiErrorDef;
+    CONFLICT: _h_ai_core.HaiErrorDef;
+    UNAVAILABLE: _h_ai_core.HaiErrorDef;
+    CAPACITY: _h_ai_core.HaiErrorDef;
+    LEASE_LOST: _h_ai_core.HaiErrorDef;
+    CLEANUP_UNCONFIRMED: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 可持久化的输入、事件和输出。
+ * @example
+ * ```ts
+ * import type { RunnerJson } from '@h-ai/runner'
+ * const event: RunnerJson = { step: 'ready', parts: [1, 2] }
+ * ```
+ */
+type RunnerJson = z.infer<typeof json>;
+/**
+ * 由可信应用确定的任务主体。
+ * @example
+ * ```ts
+ * import type { RunnerScope } from '@h-ai/runner'
+ * const scope: RunnerScope = { tenantId: 'engineering', userId: 'alice' }
+ * ```
+ */
+type RunnerScope = RunnerSubmit['scope'];
+/**
+ * 不含密钥或本机文件路径的持久提交参数。
+ * @example
+ * ```ts
+ * import type { RunnerSubmit } from '@h-ai/runner'
+ * const task: RunnerSubmit = { scope: { tenantId: 'team', userId: 'alice' }, kind: 'reports.v1', input: { page: 1 } }
+ * ```
+ */
+type RunnerSubmit = z.input<typeof submitSchema>;
+/**
+ * 当前执行者的启动代次；节点重启后代次会变化。
+ * @example
+ * ```ts
+ * import type { RunnerOwner } from '@h-ai/runner'
+ * function node(owner: RunnerOwner) { return owner.nodeId }
+ * ```
+ */
+interface RunnerOwner {
+    nodeId: string;
+    generation: string;
+}
+/**
+ * 跨实例可读取的执行状态和结果。
+ * @example
+ * ```ts
+ * import type { RunnerExecution } from '@h-ai/runner'
+ * function isDone(execution: RunnerExecution) { return execution.status === 'succeeded' }
+ * ```
+ */
+interface RunnerExecution {
+    id: string;
+    status: 'queued' | 'running' | 'cancelling' | 'cancelled' | 'succeeded' | 'failed' | 'unknown';
+    owner?: RunnerOwner;
+    environmentId?: string;
+    output?: RunnerJson;
+    failure?: 'queue-timeout' | 'run-timeout' | 'handler-failed' | 'owner-lost' | 'parent-ended' | 'cleanup-unconfirmed';
+    createdAt: number;
+    updatedAt: number;
+    /** 运维核验容器和本地暂存已清理的时间；未知业务副作用仍保留。 */
+    reconciledAt?: number;
+}
+/**
+ * 由可信管理入口取得的核验责任人及工单原因。
+ * @example
+ * ```ts
+ * import type { RunnerReconciliation } from '@h-ai/runner'
+ * const review: RunnerReconciliation = { operatorId: 'ops-1', reason: 'INC-47: verified engine cleanup' }
+ * ```
+ */
+interface RunnerReconciliation {
+    operatorId: string;
+    reason: string;
+}
+/**
+ * 已登记离线固定工具的集群预热目标及容量边界。
+ * @example
+ * ```ts
+ * import type { RunnerWarmPool } from '@h-ai/runner'
+ * const pool: RunnerWarmPool = { key: 'docs', kind: 'docs.v1', environmentId: 'docs', minReady: 1, maxRunning: 2, maxTotal: 3 }
+ * ```
+ */
+interface RunnerWarmPool {
+    key: string;
+    kind: string;
+    environmentId: string;
+    minReady: number;
+    maxRunning: number;
+    maxTotal: number;
+}
+/**
+ * 持久事件游标从 1 开始，按执行内递增。
+ * @example
+ * ```ts
+ * import type { RunnerEvent } from '@h-ai/runner'
+ * function nextCursor(event: RunnerEvent) { return event.sequence }
+ * ```
+ */
+interface RunnerEvent {
+    sequence: number;
+    data: RunnerJson;
+    createdAt: number;
+}
+/**
+ * 仅限可信已注册处理器调用。工作目录默认 /workspace，配置文件置于 /state。
+ * @example
+ * ```ts
+ * import type { RunnerLaunch } from '@h-ai/runner'
+ * const launch: RunnerLaunch = { command: 'cat', args: ['/state/manifest.json'], files: { 'manifest.json': '{}' } }
+ * ```
+ */
+interface RunnerLaunch {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    files?: Record<string, string>;
+    /** 规范 Base64 输入文件；提供空对象时也会分配 /input 与 /output。 */
+    inputs?: Record<string, string>;
+    cwd?: string;
+}
+/**
+ * 容器标准流与经过核验的停止操作。
+ * @example
+ * ```ts
+ * import type { RunnerProcess } from '@h-ai/runner'
+ * async function stop(process: RunnerProcess) { return process.close() }
+ * ```
+ */
+interface RunnerProcess {
+    stdin: Writable;
+    stdout: Readable;
+    stderr: Readable;
+    wait: () => Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    /** 从仍运行的工具容器读取一个受限普通文件，返回规范 Base64。 */
+    artifact: (name: string, maxBytes: number) => Promise<HaiResult<string>>;
+    close: () => Promise<HaiResult<void>>;
+}
+/**
+ * 处理器只在当前租约拥有者内执行，启动和事件都经过持久代次检查。
+ * @example
+ * ```ts
+ * import type { RunnerContext } from '@h-ai/runner'
+ * async function accepted(context: RunnerContext) { return context.emit({ id: context.id }) }
+ * ```
+ */
+interface RunnerContext {
+    id: string;
+    scope: RunnerScope;
+    owner: RunnerOwner;
+    parentId?: string;
+    signal: AbortSignal;
+    emit: (data: RunnerJson) => Promise<HaiResult<void>>;
+    start: (launch: RunnerLaunch) => Promise<HaiResult<RunnerProcess>>;
+}
+/**
+ * 可信服务器代码注册的处理器；输入需要由业务再次校验。
+ * @example
+ * ```ts
+ * import type { RunnerHandler } from '@h-ai/runner'
+ * const handler: RunnerHandler = async (input) => ({ echoed: input })
+ * ```
+ */
+type RunnerHandler = (input: RunnerJson, context: RunnerContext) => Promise<RunnerJson>;
+/**
+ * 注入 ACP 或工具服务的受管执行对象。
+ * @example
+ * ```ts
+ * import type { RunnerFunctions } from '@h-ai/runner'
+ * async function ready(instance: RunnerFunctions) { return instance.init({ nodeId: 'east' }) }
+ * ```
+ */
+interface RunnerFunctions {
+    /** 当前实例已启动并承担执行角色。 */
+    readonly isExecutor: boolean;
+    /** 启动前应先初始化 reldb。 */
+    init: (config: RunnerConfigInput) => Promise<HaiResult<void>>;
+    /** 停止领取，取消本节点执行并核验清理。 */
+    close: () => Promise<HaiResult<void>>;
+    /** 当前环境快照。 */
+    environment: (id: string) => HaiResult<RunnerEnvironment>;
+    /** 注册处理器并返回仅移除该处理器的回调。 */
+    register: (kind: string, handler: RunnerHandler) => HaiResult<() => void>;
+    /** 在 API 和执行节点登记同一部署快照。只在执行节点创建实例。 */
+    registerWarmPool: (pool: RunnerWarmPool) => HaiResult<() => void>;
+    /** 持久化接收，在可用节点领取。 */
+    submit: (request: RunnerSubmit) => Promise<HaiResult<RunnerExecution>>;
+    /** 按业务幂等键定位既有执行。 */
+    find: (scope: RunnerScope, kind: string, key: string) => Promise<HaiResult<RunnerExecution | undefined>>;
+    /** 根据可信主体读取任务。 */
+    get: (scope: RunnerScope, id: string) => Promise<HaiResult<RunnerExecution>>;
+    /** 持久记录取消请求。 */
+    cancel: (scope: RunnerScope, id: string) => Promise<HaiResult<RunnerExecution>>;
+    /** 原执行节点管理入口；核验环境已释放并审计，仍保留未知业务结果。 */
+    reconcileUnknown: (scope: RunnerScope, id: string, review: RunnerReconciliation) => Promise<HaiResult<RunnerExecution>>;
+    /** 分页读取保序事件。 */
+    events: (scope: RunnerScope, id: string, after?: number, limit?: number) => Promise<HaiResult<RunnerEvent[]>>;
+}
+
+/**
+ * 创建独立 runner，可在同一进程分别承接不同节点角色或用于隔离测试。
+ * @example
+ * ```ts
+ * import { reldb } from '@h-ai/reldb'
+ * import { createRunner } from '@h-ai/runner'
+ * const database = await reldb.init({ type: 'sqlite', database: ':memory:' })
+ * if (!database.success) throw new Error(database.error.message)
+ * const runner = createRunner()
+ * const initialized = await runner.init({ nodeId: 'tools' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * await runner.close()
+ * await reldb.close()
+ * ```
+ */
+declare function createRunner(): RunnerFunctions;
+/**
+ * 共享执行入口；应用负责初始化数据库、启动并在关闭前等待结果。
+ * @example
+ * ```ts
+ * import { runner } from '@h-ai/runner'
+ * const status = await runner.get({ tenantId: 'team', userId: 'alice' }, '0'.repeat(64))
+ * if (!status.success) throw new Error(status.error.message)
+ * ```
+ */
+declare const runner: RunnerFunctions;
+
+export { HaiRunnerError, RunnerConfigSchema, createRunner, runner };
+export type { RunnerConfigInput, RunnerContext, RunnerEnvironment, RunnerEvent, RunnerExecution, RunnerFunctions, RunnerHandler, RunnerJson, RunnerLaunch, RunnerOwner, RunnerProcess, RunnerReconciliation, RunnerResources, RunnerScope, RunnerSubmit, RunnerWarmPool };