@hoplogic/hopjit 0.1.0

package/dist/provider-types.d.ts

@@ -0,0 +1,134 @@
+import type { SpecAST, ExecutableStepType } from './ast-types.js';
+import type { EngineSnapshot } from './runtime-types.js';
+/** PersistenceProvider：引擎状态快照存取接口——引擎经此持久化/恢复执行状态，支撑复用/独立双模式驱动。见 [[shared-providers#^anc-provider-persistence-iface]] */
+export interface PersistenceProvider {
+    init(instanceId: string, spec: SpecAST): void;
+    saveSnapshot(snapshot: EngineSnapshot): void;
+    loadSnapshot(): EngineSnapshot;
+    exists(): boolean;
+    getWorkZone(): string;
+}
+/** ToolProvider：工具能力接口——引擎经此调用宿主注入的工具（execute 执行、list 列举）。见 [[shared-providers#^anc-provider-tool]] */
+export interface ToolProvider {
+    execute(tool_name: string, tool_args: Record<string, unknown>): Promise<ToolResult>;
+    list(): ToolDef[];
+}
+/** ToolResult：工具执行结果——承载返回值、内容类型（text/json）与成功标志。见 [[shared-providers#^anc-provider-tool]] */
+export interface ToolResult {
+    result: string | Record<string, unknown>;
+    content_type?: 'text' | 'json';
+    success: boolean;
+}
+/** ToolDef：工具定义——声明名称、描述、input_schema 及 requires_commit 副作用级别（用于 act 步骤拦截）。见 [[shared-providers#^anc-provider-tool]] */
+export interface ToolDef {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    requires_commit: boolean;
+}
+/** KnowledgeProvider：知识检索接口——引擎经此按 query 检索宿主知识片段供 prompt 注入。见 [[shared-providers#^anc-provider-knowledge]] */
+export interface KnowledgeProvider {
+    retrieve(query: string, max_results: number): Promise<KnowledgeFragment[]>;
+}
+/** KnowledgeFragment：知识片段——检索返回的单条结果，含来源 id、内容与相关度。见 [[shared-providers#^anc-provider-knowledge]] */
+export interface KnowledgeFragment {
+    source_id: string;
+    content: string;
+    relevance: 'high' | 'medium' | 'low';
+}
+/** IdentityProvider：身份凭证接口——为外部服务调用提供凭证（get_credential/list_services），v1 仅定义形状未实装。见 [[shared-providers#^anc-provider-identity]] */
+export interface IdentityProvider {
+    get_credential(service_id: string): Promise<Credential | null>;
+    list_services(): ServiceEntry[];
+}
+/** Credential：外部服务凭证——含类型（api_key/ak_sk/bearer_token/oauth）与键值对。见 [[shared-providers#^anc-provider-identity]] */
+export interface Credential {
+    type: 'api_key' | 'ak_sk' | 'bearer_token' | 'oauth';
+    values: Record<string, string>;
+}
+/** ServiceEntry：可用服务条目——list_services 返回的单项，含 service_id 与描述。见 [[shared-providers#^anc-provider-identity]] */
+export interface ServiceEntry {
+    service_id: string;
+    description: string;
+}
+export interface SpecProvider {
+    resolve(spec_id: string): Promise<SpecSource | null>;
+    list?(): SpecEntry[];
+}
+/** SpecSource：被调子 spec 源——resolve 返回的 HopSpec markdown 全文及可选版本（引擎只透传/审计）。见 [[shared-providers#^anc-provider-spec]] */
+export interface SpecSource {
+    spec_id: string;
+    source: string;
+    version?: string;
+}
+/** SpecEntry：可用 spec 条目——可选 list() 返回的单项，含 spec_id 与描述。见 [[shared-providers#^anc-provider-spec]] */
+export interface SpecEntry {
+    spec_id: string;
+    description: string;
+}
+/** ModelEngine：多模型路由配置——由 IdentityLayer 持有，定义默认服务/模型及按步骤类型的路由规则。见 [[shared-providers#^anc-config-model-engine]] */
+export interface ModelEngine {
+    default_service_id: string;
+    default_model: string;
+    routing_rules?: ModelRoute[];
+}
+/** ModelRoute：单条模型路由规则——按 step_type 匹配到目标 service_id 与 model。见 [[shared-providers#^anc-config-model-engine]] */
+export interface ModelRoute {
+    match: {
+        step_type?: ExecutableStepType;
+    };
+    service_id: string;
+    model: string;
+}
+/** HostConfig：宿主环境配置——实例化时由宿主注入，贯穿执行生命周期，聚合 workspace/sandbox/三件套 Provider/模型与资源上限。见 [[shared-providers#^anc-config-host]] */
+export interface HostConfig {
+    workspace_dir: string;
+    sandbox: SandboxConfig;
+    tool_provider?: ToolProvider;
+    knowledge_provider?: KnowledgeProvider;
+    identity_provider?: IdentityProvider;
+    spec_provider?: SpecProvider;
+    api_key: string;
+    base_url?: string;
+    model?: string;
+    model_engine?: ModelEngine;
+    resource_limits?: ResourceLimits;
+}
+/** SandboxConfig：沙箱配置——定义 act 步骤能安全触及的资源边界（文件/网络/运行时/数据库四类）。见 [[shared-providers#^anc-config-sandbox]] */
+export interface SandboxConfig {
+    filesystem: FilesystemSandbox;
+    network: NetworkSandbox;
+    runtime: RuntimeSandbox;
+    database?: DatabaseSandbox;
+}
+/** FilesystemSandbox：文件系统沙箱——声明工作区根目录与读取访问控制（allowed/denied/confirm_required）。见 [[shared-providers#^anc-config-sandbox]] */
+export interface FilesystemSandbox {
+    workspace_dir: string;
+    read_access: {
+        allowed: string[];
+        denied: string[];
+        confirm_required: string[];
+    };
+}
+/** NetworkSandbox：网络沙箱——声明可信域名白名单，约束 act 步骤可访问的网络主机。见 [[shared-providers#^anc-config-sandbox]] */
+export interface NetworkSandbox {
+    trusted_hosts: string[];
+}
+/** RuntimeSandbox：运行时沙箱——声明可用运行时白名单（如 python/node/uv/pdf/ocr）。见 [[shared-providers#^anc-config-sandbox]] */
+export interface RuntimeSandbox {
+    available: string[];
+}
+/** DatabaseSandbox：数据库沙箱——区分临时库（act 可读写、可重建）与只读库（act 只查、写需 commit）。见 [[shared-providers#^anc-config-sandbox]] */
+export interface DatabaseSandbox {
+    temp_databases: string[];
+    readonly_databases?: string[];
+}
+/** ResourceLimits：资源上限——定义单步执行的 token 预算、工具调用上限、replan/并发/超时等约束。见 [[shared-providers#^anc-config-resource-limits]] */
+export interface ResourceLimits {
+    max_tool_iterations: number;
+    max_context_tokens: number;
+    max_output_tokens: number;
+    max_replan_attempts: number;
+    max_concurrent_workers?: number;
+    timeout_seconds?: number;
+}

package/dist/provider-types.js

@@ -0,0 +1,3 @@
+// @module: shared-providers ^anc-struct-shared-providers — 宿主契约：Provider 三件套 + HostConfig/Sandbox/ResourceLimits/ModelEngine。
+// 拆自原 types.ts（见 design/spec-ast.md ^anc-struct-spec-ast 拆分表）。Provider 接口定位见 shared-types.md。
+export {};

package/dist/runtime-types.d.ts

@@ -0,0 +1,84 @@
+import type { SpecAST, OutputDecl, ResponseOption, StepSummary } from './ast-types.js';
+import type { SandboxConfig } from './provider-types.js';
+export interface ExecEvent {
+    at: string;
+    step_id: string;
+    event: string;
+    detail?: string;
+}
+/** 步骤失败的结构化分类——`lack_of_info`（缺信息，driver 可补充知识或上传父层）或 `error`（一般错误，走 retry/adaptive）。见 [[exec-engine#^anc-struct-exec-engine-exports]] */
+export type FailKind = 'lack_of_info' | 'error';
+/** 单个步骤的失败记录——人类可读原因加失败分类，按 step_id 存入 state.json 供 get_failure_reason 跨进程直读。见 [[exec-engine#^anc-exec-state-persistence]] */
+export interface StepFailRecord {
+    reason: string;
+    fail_kind: FailKind;
+}
+/** subtask 一次重试尝试的档案——尝试轮次、失败原因与已试步骤摘要，供 adaptive replan 与 L2c 带反馈重跑消费。见 [[shared-types#^anc-type-auxiliary]] */
+export interface RetryRecord {
+    attempt: number;
+    failure_reason: string;
+    steps_tried: StepSummary[];
+}
+/** PromptAssembler 组装后的六层执行上下文——任务契约、知识注入、进度摘要、输入、指令与输出约束，随 StepReady 交给 driver。见 [[exec-engine#^anc-exec-prompt-assembly]] */
+export interface AssembledContext {
+    task_context: string;
+    knowledge_context?: string;
+    doc_ref_context?: string;
+    progress_summary: string;
+    iteration_history?: string;
+    retry_feedback?: string;
+    inputs: Record<string, unknown>;
+    instruction: string;
+    output_schema: OutputDecl[];
+}
+/** HITL 暂停快照——confirm/commit/waiting_human 触发时打包的执行上下文（呈现数据、回复项、变量快照），写入 checkpoint.json 供 resume 恢复。见 [[exec-engine#^anc-exec-crash-recovery]] */
+export interface Checkpoint {
+    step_id: string;
+    pause_reason: string;
+    presented_data: unknown;
+    response_options?: ResponseOption[];
+    variables_snapshot: Record<string, unknown>;
+    timestamp: string;
+}
+export interface StateFile {
+    format_version: 1;
+    step_states: Record<string, string>;
+    retry_counters: Record<string, number>;
+    loop_counters: Record<string, number>;
+    retry_history?: Record<string, RetryRecord[]>;
+    step_fail_reasons?: Record<string, StepFailRecord>;
+    exec_events?: ExecEvent[];
+    log_dir?: string;
+    hoplog_run_dir?: string;
+    adaptive_needed_subtask?: string;
+    can_fanout?: boolean;
+    context_mode?: 'full' | 'minimal';
+    subtree_root?: string;
+    dispatched?: Record<string, string[]>;
+    spec_path?: string;
+    cli_abs_path?: string;
+    max_concurrent?: number;
+    host_context?: {
+        workspace_dir: string;
+        sandbox: SandboxConfig;
+    };
+}
+/** 单个作用域的持久化数据——父 scope id（root 为 null）+ 本层变量。见 [[exec-engine#^anc-exec-vars-scope-persist]] */
+export interface ScopeData {
+    parent: string | null;
+    variables: Record<string, unknown>;
+}
+/** vars.json 的持久化结构，先于 state.json 原子写入。见 [[exec-engine#^anc-exec-vars-scope-persist]]
+ * - v2（当前）：`scopes` 落盘完整 scope 树（scopeId → {parent, variables}），跨进程 scope 隔离保真。
+ * - v1（旧）：`variables` 扁平字典（无 scope 前缀），读时全塞 root 向后兼容。 */
+export interface VarsFile {
+    format_version: 1 | 2;
+    variables?: Record<string, unknown>;
+    scopes?: Record<string, ScopeData>;
+}
+/** 引擎完整快照——spec AST、状态文件与变量文件三合一，PersistenceProvider save/load 的载荷单元。见 [[shared-providers#^anc-provider-persistence-iface]] */
+export interface EngineSnapshot {
+    spec: SpecAST;
+    state: StateFile;
+    vars: VarsFile;
+}

package/dist/runtime-types.js

@@ -0,0 +1,4 @@
+// @module: exec-engine ^anc-struct-exec-engine
+// 引擎内部运行时类型——随实现演进（非对外稳定面）：事件流/快照/状态文件/组装上下文。
+// 拆自原 types.ts（见 design/spec-ast.md ^anc-struct-spec-ast 拆分表）。
+export {};

package/dist/tools.d.ts

@@ -0,0 +1,16 @@
+import type { ToolProvider, ToolDef, ToolResult, HostConfig, SandboxConfig } from './provider-types.js';
+export declare function resolveWorkspacePath(workspaceDir: string, filePath: string): string;
+export declare function validateReadAccess(sandbox: SandboxConfig, resolvedPath: string): void;
+export declare function readSandboxedFile(workspaceDir: string, sandbox: SandboxConfig, filePath: string): string;
+/** ToolProvider 契约的默认实现：无宿主注入时提供 Read/Write 两个受控工具（均 requires_commit=false，不含 bash），执行受 SandboxConfig 约束。见 [[tools#^anc-struct-tools]] */
+export declare class DefaultToolProvider implements ToolProvider {
+    private workspaceDir;
+    private sandbox;
+    constructor(hostConfig: HostConfig);
+    list(): ToolDef[];
+    execute(tool_name: string, tool_args: Record<string, unknown>): Promise<ToolResult>;
+    private executeRead;
+    private executeWrite;
+    private resolvePath;
+    private validateFileAccess;
+}

package/dist/tools.js

@@ -0,0 +1,141 @@
+// @module: tools ^anc-struct-tools
+import { readFileSync, writeFileSync, realpathSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+function resolveReal(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+// 解析 workspace 相对路径（禁绝对路径 / `..`）。复用于 DefaultToolProvider 与 doc-ref。
+// @a: anc-exec-tool-permission
+export function resolveWorkspacePath(workspaceDir, filePath) {
+    if (isAbsolute(filePath)) {
+        throw new Error(`Absolute paths are forbidden: ${filePath}`);
+    }
+    if (filePath.includes('..')) {
+        throw new Error(`Path traversal (..) is forbidden: ${filePath}`);
+    }
+    return resolve(workspaceDir, filePath);
+}
+// 路径是否匹配某模式（子串命中 或 realpath 前缀命中）。denied/confirm_required 共用同一判据。
+// 注：includes 子串匹配偏宽（会跨路径段命中），属已登记的收紧候选（见 code-quality 报告 tools P2），
+// 此处只抽重复、不改判据（沙箱行为不变）。
+function pathMatches(realPath, pattern) {
+    return realPath.includes(pattern) || realPath.startsWith(resolveReal(pattern));
+}
+// 校验读权限（denied / confirm_required / workspace 内 / allowed 链）。
+// 抽自 DefaultToolProvider.validateFileAccess 的 read 分支，供 doc-ref 复用。
+// @a: anc-exec-tool-permission
+export function validateReadAccess(sandbox, resolvedPath) {
+    const realPath = resolveReal(resolvedPath);
+    const fs = sandbox.filesystem;
+    const wsDir = resolveReal(resolve(fs.workspace_dir));
+    for (const denied of fs.read_access.denied) {
+        if (pathMatches(realPath, denied)) {
+            throw new Error(`Read denied: ${realPath} matches denied pattern "${denied}"`);
+        }
+    }
+    for (const confirmReq of fs.read_access.confirm_required) {
+        if (pathMatches(realPath, confirmReq)) {
+            throw new Error(`Read requires confirm: ${realPath} (act steps cannot confirm)`);
+        }
+    }
+    if (realPath.startsWith(wsDir))
+        return;
+    for (const allowed of fs.read_access.allowed) {
+        const allowedReal = resolveReal(resolve(allowed));
+        if (realPath.startsWith(allowedReal))
+            return;
+    }
+    throw new Error(`Read outside allowed paths: ${realPath}`);
+}
+// 读取一个受沙箱约束的 workspace 文件（解析路径 + 校验读权限 + 读取）。
+// doc-ref 解析直接复用此入口，与 act 步骤的 read 工具同一套权限。
+// @a: anc-exec-doc-ref-resolve
+export function readSandboxedFile(workspaceDir, sandbox, filePath) {
+    const resolved = resolveWorkspacePath(workspaceDir, filePath);
+    validateReadAccess(sandbox, resolved);
+    return readFileSync(resolved, 'utf-8');
+}
+const READ_TOOL = {
+    name: 'read',
+    description: 'Read a file and return its contents.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to the file to read' },
+        },
+        required: ['path'],
+    },
+    requires_commit: false,
+};
+const WRITE_TOOL = {
+    name: 'write',
+    description: 'Write content to a file.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to the file to write' },
+            content: { type: 'string', description: 'Content to write' },
+        },
+        required: ['path', 'content'],
+    },
+    requires_commit: false,
+};
+/** ToolProvider 契约的默认实现：无宿主注入时提供 Read/Write 两个受控工具（均 requires_commit=false，不含 bash），执行受 SandboxConfig 约束。见 [[tools#^anc-struct-tools]] */
+export class DefaultToolProvider {
+    workspaceDir;
+    sandbox;
+    constructor(hostConfig) {
+        this.workspaceDir = resolveReal(hostConfig.workspace_dir);
+        this.sandbox = hostConfig.sandbox;
+    }
+    list() {
+        return [READ_TOOL, WRITE_TOOL];
+    }
+    async execute(tool_name, tool_args) {
+        try {
+            switch (tool_name) {
+                case 'read': return this.executeRead(tool_args.path);
+                case 'write': return this.executeWrite(tool_args.path, tool_args.content);
+                default: return { result: `Unknown tool: ${tool_name}`, success: false, content_type: 'text' };
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { result: msg, success: false, content_type: 'text' };
+        }
+    }
+    executeRead(filePath) {
+        const resolved = this.resolvePath(filePath);
+        this.validateFileAccess(resolved, 'read');
+        const content = readFileSync(resolved, 'utf-8');
+        return { result: content, success: true, content_type: 'text' };
+    }
+    executeWrite(filePath, content) {
+        const resolved = this.resolvePath(filePath);
+        this.validateFileAccess(resolved, 'write');
+        writeFileSync(resolved, content, 'utf-8');
+        return { result: `Written ${content.length} bytes to ${filePath}`, success: true, content_type: 'text' };
+    }
+    resolvePath(filePath) {
+        return resolveWorkspacePath(this.workspaceDir, filePath);
+    }
+    validateFileAccess(resolvedPath, operation) {
+        if (operation === 'write') {
+            const realPath = resolveReal(resolvedPath);
+            const wsDir = resolveReal(resolve(this.sandbox.filesystem.workspace_dir));
+            if (!realPath.startsWith(wsDir)) {
+                throw new Error(`Write outside workspace sandbox: ${realPath}`);
+            }
+            if (realPath.includes('.hopstate')) {
+                throw new Error('Write to .hopstate/ is forbidden');
+            }
+            return;
+        }
+        validateReadAccess(this.sandbox, resolvedPath);
+    }
+}

package/dist/validator.d.ts

@@ -0,0 +1,23 @@
+import type { SpecAST, OutputDecl } from './ast-types.js';
+import type { ValidationError } from './errors.js';
+import type { SandboxConfig } from './provider-types.js';
+export interface DocRefCheckCtx {
+    workspace_dir: string;
+    sandbox: SandboxConfig;
+}
+/** Spec 校验入口——对 SpecAST 执行结构/控制流/变量/特殊步骤共 37 条规则，返回违规列表（放行前闸门）。见 [[spec-parser#^anc-rule-all]]。 */
+export declare function validateSpec(ast: SpecAST, docRefCtx?: DocRefCheckCtx): ValidationError[];
+export interface SchemaMismatch {
+    field: string;
+    declared_type: string;
+    actual: string;
+    reason: string;
+}
+/**
+ * 校验一组输出值是否匹配步骤的 +→ 声明（OutputDecl[]）。
+ * 返回不匹配项列表（空数组 = 全部通过）。
+ * @a: anc-exec-output-schema-check
+ */
+export declare function validateOutputValues(decls: OutputDecl[] | undefined, outputs: Record<string, unknown>): SchemaMismatch[];
+/** 把不匹配项格式化为 SCHEMA_MISMATCH 的 message（供算子级重试构造反馈）。 */
+export declare function formatSchemaMismatch(mismatches: SchemaMismatch[]): string;