@hoplogic/hopjit 0.1.0

package/dist/persistence.d.ts

@@ -0,0 +1,60 @@
+import type { SpecAST } from './ast-types.js';
+import type { PersistenceProvider } from './provider-types.js';
+import type { StateFile, VarsFile, EngineSnapshot } from './runtime-types.js';
+/** 原子写文件：先写 `.tmp` 再 rename 覆盖，避免崩溃中途留下半截状态文件。见 design ^anc-exec-crash-recovery */
+export declare function writeAtomic(filePath: string, data: string): void;
+/** 确保实例状态目录 `<stateDir>/<instanceId>/` 存在（0700 权限）并返回其路径。见 design ^anc-exec-state-persistence */
+export declare function ensureStateDir(stateDir: string, instanceId: string): string;
+/** fan-out 时把某 child 的 params_for_child（内部真值，不 deflate）落盘到其 subinstance 目录
+ * `<parentDir>/parallel/<childId>/params.json`，供 worker init 按 cid 回填 itemVar。
+ * 见 design/parallel-execution.md ^anc-exec-parallel-foreach-worker。 // @a: anc-exec-parallel-foreach-worker */
+export declare function writeChildParams(parentDir: string, childId: string, params: Record<string, unknown>): void;
+/** worker init 按 cid 回读 `<workerInstanceDir>/params.json`（= 父引擎 fan-out 落盘的 child 真值）。
+ * 不存在返回 null（触发 MISSING_INPUT 硬报错）。worker 只读自己那份，不碰父/兄弟 vars。 // @a: anc-exec-parallel-foreach-worker */
+export declare function readChildParams(workerInstanceDir: string): Record<string, unknown> | null;
+/** 将执行状态快照原子写入实例目录下的 `state.json`。见 [[persistence#^anc-provider-persistence]] */
+export declare function writeState(dir: string, state: StateFile): void;
+/** 将变量快照原子写入实例目录下的 `vars.json`。见 [[persistence#^anc-provider-persistence]] */
+export declare function writeVars(dir: string, vars: VarsFile): void;
+/** 将运行时 AST 快照原子写入实例目录下的 `spec.json`（随 replan 演化需重写）。见 [[persistence#^anc-provider-persistence]] */
+export declare function writeSpec(dir: string, spec: object): void;
+/** 读取并校验实例目录下的 `state.json`（format_version + step_states 校验）。见 [[persistence#^anc-provider-persistence]] */
+export declare function readState(dir: string): StateFile;
+/** 读取并校验实例目录下的 `vars.json`（format_version 1|2 + variables/scopes 二者其一校验）。见 [[persistence#^anc-provider-persistence]] */
+export declare function readVars(dir: string): VarsFile;
+/** 把 VarsFile（v1 扁平 / v2 scope 树）摊平为 name→value 字典，供按名读取的 cli 场景（call 回填、for-each 列表长度、join merge）。
+ * v2 合并所有 scope 变量、非 root scope 覆盖 root（与旧 v1 toJSON 的合并序一致，无行为回退）。 */
+export declare function flattenVars(vars: VarsFile): Record<string, unknown>;
+/** 读取实例目录下的 `spec.json` 运行时 AST 快照。损坏时抛 CORRUPT_STATE_FILE（与 state/vars 同错误语义，
+ * 便于崩溃恢复定位）。SpecAST 无 format_version 字段，故不走 parseChecked。见 [[persistence#^anc-provider-persistence]] */
+export declare function readSpec(dir: string): object;
+/** 判断实例目录下是否已存在 `state.json`（cli 定位实例是否有状态）。见 [[persistence#^anc-provider-persistence]] */
+export declare function stateExists(dir: string): boolean;
+/**
+ * 复用模式持久化：快照 ↔ .hopstate/<instance_id>/ 文件。
+ * CLI 每个命令是独立进程，状态必须外置存活。
+ */
+export declare class FilePersistence implements PersistenceProvider {
+    private stateDir;
+    private instanceDir;
+    constructor(stateDir: string, isInstanceDir?: boolean);
+    init(instanceId: string, spec: SpecAST): void;
+    getWorkZone(): string;
+    saveSnapshot(snapshot: EngineSnapshot): void;
+    loadSnapshot(): EngineSnapshot;
+    exists(): boolean;
+    getInstanceDir(): string | null;
+}
+/**
+ * 独立模式持久化（默认）：进程内快照。
+ * Dispatcher 驱动完整生命周期，无需跨进程，状态保留在内存。
+ */
+export declare class MemoryPersistence implements PersistenceProvider {
+    private snapshot;
+    private spec;
+    init(_instanceId: string, spec: SpecAST): void;
+    saveSnapshot(snapshot: EngineSnapshot): void;
+    loadSnapshot(): EngineSnapshot;
+    exists(): boolean;
+    getWorkZone(): string;
+}

package/dist/persistence.js

@@ -0,0 +1,208 @@
+// @module: persistence ^anc-provider-persistence
+import { writeFileSync, renameSync, mkdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** 原子写文件：先写 `.tmp` 再 rename 覆盖，避免崩溃中途留下半截状态文件。见 design ^anc-exec-crash-recovery */
+export function writeAtomic(filePath, data) {
+    const tmp = filePath + '.tmp';
+    writeFileSync(tmp, data, { mode: 0o600 });
+    renameSync(tmp, filePath);
+}
+/** 确保实例状态目录 `<stateDir>/<instanceId>/` 存在（0700 权限）并返回其路径。见 design ^anc-exec-state-persistence */
+export function ensureStateDir(stateDir, instanceId) {
+    const dir = join(stateDir, instanceId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** fan-out 时把某 child 的 params_for_child（内部真值，不 deflate）落盘到其 subinstance 目录
+ * `<parentDir>/parallel/<childId>/params.json`，供 worker init 按 cid 回填 itemVar。
+ * 见 design/parallel-execution.md ^anc-exec-parallel-foreach-worker。 // @a: anc-exec-parallel-foreach-worker */
+export function writeChildParams(parentDir, childId, params) {
+    const dir = join(parentDir, 'parallel', childId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeAtomic(join(dir, 'params.json'), JSON.stringify(params, null, 2));
+}
+/** worker init 按 cid 回读 `<workerInstanceDir>/params.json`（= 父引擎 fan-out 落盘的 child 真值）。
+ * 不存在返回 null（触发 MISSING_INPUT 硬报错）。worker 只读自己那份，不碰父/兄弟 vars。 // @a: anc-exec-parallel-foreach-worker */
+export function readChildParams(workerInstanceDir) {
+    const filePath = join(workerInstanceDir, 'params.json');
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 将执行状态快照原子写入实例目录下的 `state.json`。见 [[persistence#^anc-provider-persistence]] */
+export function writeState(dir, state) {
+    writeAtomic(join(dir, 'state.json'), JSON.stringify(state, null, 2));
+}
+/** 将变量快照原子写入实例目录下的 `vars.json`。见 [[persistence#^anc-provider-persistence]] */
+export function writeVars(dir, vars) {
+    writeAtomic(join(dir, 'vars.json'), JSON.stringify(vars, null, 2));
+}
+/** 将运行时 AST 快照原子写入实例目录下的 `spec.json`（随 replan 演化需重写）。见 [[persistence#^anc-provider-persistence]] */
+export function writeSpec(dir, spec) {
+    writeAtomic(join(dir, 'spec.json'), JSON.stringify(spec, null, 2));
+}
+// 状态文件读取健壮性校验：format_version 必须 === 1 + 关键字段存在。
+// 不符抛 CORRUPT_STATE_FILE:<path>（明确定位），替代裸 JSON.parse + as 断言后续的晦涩 TypeError。
+// 见 design/exec-engine.md ^anc-exec-parallel-join-preconditions。// @a: anc-exec-parallel-join-preconditions
+// requiredKey 可传多个候选（任一存在即合格，用于 vars.json v1 `variables` / v2 `scopes` 二者其一）；
+// allowedVersions 缺省 [1]（state.json 恒 v1），vars.json 传 [1,2] 兼容旧扁平格式。
+function parseChecked(filePath, requiredKeys, allowedVersions = [1]) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (e) {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 不可读 (${e instanceof Error ? e.message : String(e)})`);
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 非合法 JSON`);
+    }
+    if (typeof obj !== 'object' || obj === null) {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 顶层非对象`);
+    }
+    const rec = obj;
+    if (typeof rec.format_version !== 'number' || !allowedVersions.includes(rec.format_version)) {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} format_version=${JSON.stringify(rec.format_version)}，期望 ${allowedVersions.join('|')}`);
+    }
+    const keys = Array.isArray(requiredKeys) ? requiredKeys : [requiredKeys];
+    if (!keys.some(k => typeof rec[k] === 'object' && rec[k] !== null)) {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 缺关键字段 "${keys.join('|')}"`);
+    }
+    return obj;
+}
+/** 读取并校验实例目录下的 `state.json`（format_version + step_states 校验）。见 [[persistence#^anc-provider-persistence]] */
+export function readState(dir) {
+    return parseChecked(join(dir, 'state.json'), 'step_states');
+}
+/** 读取并校验实例目录下的 `vars.json`（format_version 1|2 + variables/scopes 二者其一校验）。见 [[persistence#^anc-provider-persistence]] */
+export function readVars(dir) {
+    return parseChecked(join(dir, 'vars.json'), ['variables', 'scopes'], [1, 2]);
+}
+/** 把 VarsFile（v1 扁平 / v2 scope 树）摊平为 name→value 字典，供按名读取的 cli 场景（call 回填、for-each 列表长度、join merge）。
+ * v2 合并所有 scope 变量、非 root scope 覆盖 root（与旧 v1 toJSON 的合并序一致，无行为回退）。 */
+export function flattenVars(vars) {
+    if (vars.format_version === 2 && vars.scopes) {
+        const flat = { ...(vars.scopes.root?.variables ?? {}) };
+        for (const [scopeId, data] of Object.entries(vars.scopes)) {
+            if (scopeId === 'root')
+                continue;
+            Object.assign(flat, data.variables);
+        }
+        return flat;
+    }
+    return vars.variables ?? {};
+}
+/** 读取实例目录下的 `spec.json` 运行时 AST 快照。损坏时抛 CORRUPT_STATE_FILE（与 state/vars 同错误语义，
+ * 便于崩溃恢复定位）。SpecAST 无 format_version 字段，故不走 parseChecked。见 [[persistence#^anc-provider-persistence]] */
+export function readSpec(dir) {
+    const filePath = join(dir, 'spec.json');
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (e) {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 不可读 (${e instanceof Error ? e.message : String(e)})`);
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 非合法 JSON`);
+    }
+    if (typeof obj !== 'object' || obj === null) {
+        throw new Error(`CORRUPT_STATE_FILE: ${filePath} 顶层非对象`);
+    }
+    return obj;
+}
+/** 判断实例目录下是否已存在 `state.json`（cli 定位实例是否有状态）。见 [[persistence#^anc-provider-persistence]] */
+export function stateExists(dir) {
+    return existsSync(join(dir, 'state.json'));
+}
+/**
+ * 复用模式持久化：快照 ↔ .hopstate/<instance_id>/ 文件。
+ * CLI 每个命令是独立进程，状态必须外置存活。
+ */
+export class FilePersistence {
+    stateDir;
+    instanceDir = null;
+    // stateDir: 实例存储的根目录（.hopstate）。从已存在实例目录恢复时传 instanceDir + isInstanceDir=true。
+    constructor(stateDir, isInstanceDir = false) {
+        this.stateDir = stateDir;
+        if (isInstanceDir)
+            this.instanceDir = stateDir;
+    }
+    init(instanceId, spec) {
+        this.instanceDir = ensureStateDir(this.stateDir, instanceId);
+        writeSpec(this.instanceDir, spec);
+        // 创建 work_zone/ + work_zone/vars/(driver @file 临时文件 + deflate $file 指针存放)
+        // 见 design/exec-engine.md ^anc-exec-work-zone。// @a: anc-exec-work-zone
+        mkdirSync(join(this.instanceDir, 'work_zone', 'vars'), { recursive: true, mode: 0o700 });
+    }
+    // 返回 work_zone 工作区绝对路径,NextResponse 五形态都携带此路径。// @a: anc-exec-work-zone
+    getWorkZone() {
+        if (!this.instanceDir)
+            throw new Error('FilePersistence.getWorkZone before init');
+        return join(this.instanceDir, 'work_zone');
+    }
+    saveSnapshot(snapshot) {
+        if (!this.instanceDir)
+            throw new Error('FilePersistence.saveSnapshot before init');
+        writeVars(this.instanceDir, snapshot.vars);
+        writeState(this.instanceDir, snapshot.state);
+        // spec.json 是运行时 AST 快照,随 replan 演化必须重写——否则跨进程 load 丢失 replan
+        // 的新 children(此前真实 bug)。见 design/exec-engine.md ^anc-exec-state-persistence。
+        // v1 每次 saveSnapshot 都写(整树序列化,spec 通常不大;正确性优先、不漏写);
+        // v2 可优化为脏标记(仅 replan 改 AST 时写)。// @a: anc-exec-state-persistence
+        writeSpec(this.instanceDir, snapshot.spec);
+    }
+    loadSnapshot() {
+        if (!this.instanceDir)
+            throw new Error('FilePersistence.loadSnapshot before init');
+        return {
+            spec: readSpec(this.instanceDir),
+            vars: readVars(this.instanceDir),
+            state: readState(this.instanceDir),
+        };
+    }
+    exists() {
+        return this.instanceDir != null && stateExists(this.instanceDir);
+    }
+    getInstanceDir() {
+        return this.instanceDir;
+    }
+}
+/**
+ * 独立模式持久化（默认）：进程内快照。
+ * Dispatcher 驱动完整生命周期，无需跨进程，状态保留在内存。
+ */
+export class MemoryPersistence {
+    snapshot = null;
+    spec = null;
+    init(_instanceId, spec) {
+        this.spec = spec;
+    }
+    saveSnapshot(snapshot) {
+        this.snapshot = snapshot;
+    }
+    loadSnapshot() {
+        if (!this.snapshot)
+            throw new Error('MemoryPersistence.loadSnapshot before any saveSnapshot');
+        return this.snapshot;
+    }
+    exists() {
+        return this.snapshot != null;
+    }
+    // 独立模式不暴露 work_zone 给外部 driver(dispatcher 进程内直跑,无 @file 跨进程交换需求)。
+    // 返回空串使下游一致透传;若独立模式将来需要 work_zone,可改为 tmpdir 自建。// @a: anc-exec-work-zone
+    getWorkZone() { return ''; }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,130 @@
+import type { SpecAST, StepNode } from './ast-types.js';
+import type { KnowledgeProvider, KnowledgeFragment } from './provider-types.js';
+import type { AssembledContext, ExecEvent } from './runtime-types.js';
+import { type VariableStore, type StepStatus } from './ast-runtime.js';
+/** PromptAssembler↔engine 的收窄只读接口边界：engine 实现它，Assembler 据此实时取 Spec/步骤状态/变量/执行事件流组 6 层 context。见 [[prompt-assembler#^anc-struct-prompt-assembler]] */
+export interface EngineAccessor {
+    getSpec(): SpecAST | null;
+    getStepStates(): Map<string, StepStatus>;
+    getVariableStore(): VariableStore;
+    getExecEvents(): ExecEvent[];
+    getLoopCounters(): Map<string, number>;
+    getActiveRetryFeedback(stepId: string): {
+        attempt: number;
+        reason: string;
+    } | undefined;
+    getSubtreeRoot(): string | null;
+    getWorkZone(): string;
+    getContextMode(): 'full' | 'minimal';
+}
+/** 上下文组装组件：按步骤类型把引擎运行时状态组成 6 层 AssembledContext（L1-L6）并做 token 预算裁剪，自身不发 API。见 [[prompt-assembler#^anc-exec-prompt-assembly]] */
+export declare class PromptAssembler {
+    private engine;
+    private budget;
+    constructor(engine: EngineAccessor, hasKnowledgeProvider?: boolean);
+    assembleReasonContext(step: StepNode): AssembledContext;
+    assembleCheckContext(step: StepNode): AssembledContext;
+    assembleActContext(step: StepNode): AssembledContext;
+    assembleAdaptiveContext(subtaskId: string): AssembledContext;
+    reassembleAggressive(step: StepNode): AssembledContext;
+    private assembleContext;
+    private buildRetryFeedback;
+    /** 渲染骨架单节点（含容器 attr：loop max / subtask retry+adaptive / case condition）+ 递归 children。
+     * buildSpecSkeleton 与 buildSubtreeSkeleton 共用（原两处 render 逐字复制）。 */
+    private renderSkeletonNode;
+    private buildSpecSkeleton;
+    private buildSubtreeSkeleton;
+    private buildTaskContext;
+    private buildProgressSummary;
+    private buildFullDisplaySet;
+    private renderStepProgress;
+    private formatStepFull;
+    /** 把步骤输出格式化为 `name=值(截断) # desc` 列表——读 scope 变量、JSON.stringify、超长截断。
+     * formatStepFull / formatContainerOutputs 共用（原两处逐字复制）。 */
+    private formatOutputVals;
+    private formatContainerOutputs;
+    private findProducerSteps;
+    private getSiblingStepIds;
+    private buildIterationHistory;
+    private resolveInputs;
+    private buildInstruction;
+    private buildAdaptiveTaskContext;
+    private buildSubtaskProgress;
+    private applyBudgetTrimming;
+    private estimateContextTokens;
+    private estimateTokens;
+    private getAncestorChain;
+    private findNearestLoopAncestor;
+    private findStepById;
+}
+/**
+ * Extract @knowledge hints from text (constraints, instruction, etc.)
+ * Returns unique keywords/phrases declared via `@knowledge <term>`.
+ */
+export declare function extractKnowledgeHints(text: string): string[];
+/**
+ * Collects all @knowledge hints from spec constraints and a step's instruction.
+ */
+export declare function collectKnowledgeHints(spec: SpecAST, step: StepNode): {
+    specHints: string[];
+    stepHints: string[];
+};
+/** L2 知识检索的分来源结果（Spec @knowledge / 步骤 @knowledge / 补充检索），供组装时按优先级合并裁剪。见 [[prompt-assembler#^anc-exec-knowledge-retrieval]] */
+export interface KnowledgeRetrievalResult {
+    specKnowledge: KnowledgeFragment[];
+    stepKnowledge: KnowledgeFragment[];
+    supplementary: KnowledgeFragment[];
+    dynamic: KnowledgeFragment[];
+}
+export declare function retrieveKnowledge(provider: KnowledgeProvider, specHints: string[], stepHints: string[], supplementaryQuery?: string, dynamicQuery?: string): Promise<KnowledgeRetrievalResult>;
+/**
+ * Format knowledge retrieval results into the L2 knowledge_context string.
+ * Deduplicates by source_id and applies budget trimming.
+ */
+export declare function formatKnowledgeContext(result: KnowledgeRetrievalResult, triggerStepId?: string, budgetChars?: number): string;
+/**
+ * Inject L2 knowledge context into an assembled context.
+ * This is the main async entry point for the dispatcher to enrich context with knowledge.
+ *
+ * @param ctx - The assembled context (modified in place and returned)
+ * @param provider - KnowledgeProvider from HostConfig
+ * @param spec - The spec AST (for extracting constraints)
+ * @param step - The current step node (for extracting step-level hints)
+ * @param supplementaryQuery - Optional query from lack_of_info (passive path)
+ * @param triggerStepId - Step ID that triggered supplementary retrieval
+ * @returns The enriched AssembledContext
+ */
+export declare function injectKnowledgeContext(ctx: AssembledContext, provider: KnowledgeProvider, spec: SpecAST, step: StepNode, supplementaryQuery?: string, triggerStepId?: string): Promise<string[]>;
+/**
+ * 把 AssembledContext 格式化为完整自包含 prompt 文本。
+ * 包含：角色说明（让任何 LLM 拿到就能正确执行）+ 6 层结构化内容。
+ * 复用模式下记录到 hoplog llm.prompt（引擎交给 CC 推理的完整 context 渲染——CC 即 llm，
+ * 见 [[spec-observability#^anc-obs-mode-boundary]]）。独立模式的真实 API prompt 由 dispatcher
+ * 的 buildSystemPrompt+buildMessages 另行组装（结构不同：system + 多条 user message），
+ * 本函数不代表独立模式实际发送内容（独立模式 llm.prompt 记录属 v2）。
+ * 覆盖守护见 tests/prompt.test.ts（@v: anc-obs-debug-context）——新增 AssembledContext 字段须同步本函数。
+ */
+export declare function formatPromptText(ctx: AssembledContext, stepType?: string): string;
+/** formatParallelPromptText 的入参：组 parallel worker fan-out 派活 prompt 所需的目标/输出声明/parallel 步骤标识等字段。见 [[prompt-assembler#^anc-struct-prompt-assembler]] */
+export interface ParallelPromptParams {
+    goal: string;
+    outputs: string;
+    parallelStepId: string;
+    children: Array<{
+        child_step_id: string;
+        summary: string;
+        params_for_child: Record<string, unknown>;
+    }>;
+    maxConcurrent: number;
+    instanceId: string;
+    specPath: string;
+    cliPath: string;
+    parentLogDir: string;
+    stateDir: string;
+}
+/**
+ * 组装 parallel 容器的完整自包含 fan-out 指令文本。
+ * driver agent 拿到这段文本就能完成 fan-out→驱动→join 全流程。
+ */
+export declare function formatParallelPromptText(p: ParallelPromptParams): string;
+export declare function formatHumanContext(record: Record<string, unknown>, workZone: string): Record<string, unknown>;