@hoplogic/hopjit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lenx Wei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# HopJIT
+
+**HopJIT** 是 HopSpec v3 的执行运行时——一套面向 LLM Agent 的结构化执行引擎。你用 HopSpec markdown 声明任务结构（步骤类型、数据流、循环/分支/并行、人机介入点），HopJIT 负责执行状态管理、变量存储、retry/adaptive 修复、None 传播等流控。
+
+两种驱动模式：
+
+- **复用模式（reuse）**：外层 LLM（如 Claude Code）当推理引擎，HopJIT 只做纯流控——**不需要 API key**。配套 `hopspec` skill 驱动。
+- **独立模式（standalone）**：HopJIT 内部 StepDispatcher 直调 LLM API 执行——需 `@anthropic-ai/sdk` + `ANTHROPIC_API_KEY`。
+
+## 包名、命令名、文件
+
+一句话理清三层：装 **包** `@hoplogic/hopjit` → 得到 **命令** `hopjit` → 它执行包内的 `dist/cli.js`。
+
+```bash
+# 全局 CLI
+npm install -g @hoplogic/hopjit
+
+# 或项目内
+npm install @hoplogic/hopjit
+
+# 开发期（克隆本仓库）
+npm install && npm run build && npm link
+```
+
+装好后 `hopjit --help` 可用（bin 命令名是 `hopjit`，与包名 scope 无关）。
+
+## CLI 用法
+
+```bash
+hopjit validate <spec.md>        # 校验 spec 合法性（放行前闸门，验证规则）
+hopjit list <dir>                # 列出目录下可执行 spec
+hopjit run <spec.md> [--params '<json>']   # 启动执行（复用模式由 skill 驱动，见下）
+hopjit status --state-dir <dir> [--instance <id>]   # 查执行进度
+hopjit resume --state-dir <dir> [--instance <id>]   # 从中断恢复
+hopjit install-skill [--dir <目标>] [--carrier cc|codex]   # 安装驱动 skill（见下）
+```
+
+其余子命令（`init` / `submit_and_fetch_next` / `join_parallel` / `fanout-plan` / `fanout-next` / `debug_step` / `vars`）由驱动层（skill / dispatcher）调用，一般不手动跑。
+
+**Quickstart**（校验你自己的 spec）：
+
+```bash
+hopjit validate my-spec.md
+```
+
+> spec 范本见项目仓库 `examples/`（未随 npm 包发布——多为引擎自测范本）。
+
+## 复用模式：安装驱动 skill
+
+复用模式下外层 LLM（Claude Code / Codex）通过 skill 驱动引擎。**一条命令安装**（自动把包内 `driver/` 源展开到正确布局，免手动 cp）：
+
+```bash
+# Claude Code（默认，装到 .claude/skills/）
+hopjit install-skill
+
+# Codex（装到指定目录，用 AGENTS.md 载体）
+hopjit install-skill --carrier codex --dir .
+
+# 覆盖已存在的（改过 skill 想重置时）
+hopjit install-skill --force
+```
+
+`install-skill` 展开的布局（CC）：
+
+```
+.claude/skills/
+├── hopspec/
+│   ├── SKILL.md          # 主 skill（源 driver/hopspec-skill.md 改名）
+│   └── references/       # 载体中立共享（cli-discovery / driver-subagent / …）
+└── hopskill-build/
+    ├── SKILL.md
+    └── references/
+```
+
+skill 启动时**自举探测** hopjit 位置（全局命令 → 项目 node_modules → 包内 dist → 开发期 fallback），无需硬编码路径——见 `references/cli-discovery.md`。
+
+之后在 Claude Code 里：
+
+```
+/hopspec run <spec.md>          # 驱动执行一个 spec
+/hopspec list [dir]             # 列出可执行 spec
+/hopskill-build                 # 把 prose skill 翻译成 hopskill
+```
+
+Codex 载体见 `driver/codex/AGENTS.md`——同构 CC，只换四处载体原语（触发 / 起 subagent / 问人 / act 工具）。
+
+## 依赖说明
+
+- **运行时依赖**：`commander`（CLI）+ `@anthropic-ai/sdk`（仅独立模式的 StepDispatcher 用；复用模式不触发）。
+- 复用模式（skill 驱动）**不需要 API key**——推理由外层 LLM 承担。
+
+## 文档
+
+- 项目仓库 `examples/` — 端到端 spec 范本（data-quality / doc-review / parallel-* / fact-check 等；未随 npm 包发布）。
+- HopSpec v3 语法与执行语义见项目概念层文档（HopSpec V3 核心规范 / 配套 HopJIT 运行时能力）。
+
+## License
+
+MIT

package/dist/act-body-interpreter.d.ts

@@ -0,0 +1,24 @@
+import type { ActBody, OutputDecl } from './ast-types.js';
+import type { ToolProvider } from './provider-types.js';
+/** BodyInterpreter 执行 hop_python body 所需的上下文（scope 初值输入、工具 provider、commit 放行开关、工具调用日志）。见 [[act-body#^anc-exec-act-body-interp]] */
+export interface BodyExecContext {
+    inputs: Record<string, unknown>;
+    toolProvider: ToolProvider;
+    allowCommit: boolean;
+    toolCallLog: Array<{
+        name: string;
+        result: 'success' | 'failure';
+        at: string;
+    }>;
+}
+/** 独立模式的 hop_python 解释器：按 ActBody AST 顺序求值执行、调白名单工具，执行期无 LLM/无推理。见 [[act-body#^anc-exec-act-body-interp]] */
+export declare class BodyInterpreter {
+    private ctx;
+    constructor(ctx: BodyExecContext);
+    run(body: ActBody, outputDecls: OutputDecl[]): Promise<Record<string, unknown>>;
+    private execStatements;
+    private execStatement;
+    private evalExpr;
+    private evalBinary;
+    private evalCall;
+}

package/dist/act-body-interpreter.js

@@ -0,0 +1,159 @@
+// @module: act-body ^anc-struct-act-body
+// act body 解释器（独立模式执行器）：按 ActBody AST 顺序执行——求值 + 调白名单工具，无 LLM。
+// 设计见 design/exec-engine.md ^anc-exec-act-body-interp；概念 ^anc-step-act-body-lang。
+// 替换 dispatcher.executeActWithTools 的 LLM tool-use 循环（执行期无推理）。
+// @a: anc-exec-act-body-interp
+import { ACT_BUILTINS } from './act-builtins.js';
+import { isTruthy } from './ast-runtime.js';
+/** 独立模式的 hop_python 解释器：按 ActBody AST 顺序求值执行、调白名单工具，执行期无 LLM/无推理。见 [[act-body#^anc-exec-act-body-interp]] */
+export class BodyInterpreter {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // 执行 body，返回 +→ 声明的输出值（从 scope 取声明名）
+    async run(body, outputDecls) {
+        const scope = new Map(Object.entries(this.ctx.inputs));
+        await this.execStatements(body.statements, scope);
+        const outputs = {};
+        for (const decl of outputDecls) {
+            if (scope.has(decl.name))
+                outputs[decl.name] = scope.get(decl.name);
+        }
+        return outputs;
+    }
+    async execStatements(stmts, scope) {
+        for (const stmt of stmts)
+            await this.execStatement(stmt, scope);
+    }
+    async execStatement(stmt, scope) {
+        if (stmt.type === 'assign') {
+            const a = stmt;
+            scope.set(a.target, await this.evalExpr(a.value, scope));
+        }
+        else if (stmt.type === 'call') {
+            await this.evalExpr(stmt.call, scope); // 副作用调用，丢弃返回值
+        }
+        else if (stmt.type === 'if') {
+            const ifs = stmt;
+            const cond = await this.evalExpr(ifs.condition, scope);
+            if (isTruthy(cond))
+                await this.execStatements(ifs.then_body, scope);
+            else if (ifs.else_body)
+                await this.execStatements(ifs.else_body, scope);
+        }
+    }
+    async evalExpr(expr, scope) {
+        switch (expr.type) {
+            case 'literal':
+                return expr.value;
+            case 'var':
+                if (!scope.has(expr.name))
+                    throw new Error(`act body 引用未定义变量 "${expr.name}"`);
+                return scope.get(expr.name);
+            case 'field': {
+                const obj = await this.evalExpr(expr.object, scope);
+                if (obj === null || obj === undefined) {
+                    throw new Error(`act body 在 null/undefined 上取字段 "${expr.field}"`);
+                }
+                return obj[expr.field];
+            }
+            case 'unary': {
+                const v = await this.evalExpr(expr.operand, scope);
+                if (expr.op === 'not')
+                    return !isTruthy(v);
+                return -toNumber(v); // '-'
+            }
+            case 'binary':
+                return this.evalBinary(expr.op, expr.left, expr.right, scope);
+            case 'call':
+                return this.evalCall(expr, scope);
+        }
+    }
+    async evalBinary(op, leftE, rightE, scope) {
+        // and/or 短路
+        if (op === 'and') {
+            const l = await this.evalExpr(leftE, scope);
+            if (!isTruthy(l))
+                return l;
+            return this.evalExpr(rightE, scope);
+        }
+        if (op === 'or') {
+            const l = await this.evalExpr(leftE, scope);
+            if (isTruthy(l))
+                return l;
+            return this.evalExpr(rightE, scope);
+        }
+        const l = await this.evalExpr(leftE, scope);
+        const r = await this.evalExpr(rightE, scope);
+        switch (op) {
+            case '+':
+                // 仿 JS：任一为字符串则拼接，否则数加
+                if (typeof l === 'string' || typeof r === 'string')
+                    return String(l) + String(r);
+                return toNumber(l) + toNumber(r);
+            case '-': return toNumber(l) - toNumber(r);
+            case '*': return toNumber(l) * toNumber(r);
+            case '/': return toNumber(l) / toNumber(r);
+            case '==': return looseEq(l, r);
+            case '!=': return !looseEq(l, r);
+            case '<': return toNumber(l) < toNumber(r);
+            case '>': return toNumber(l) > toNumber(r);
+            case '<=': return toNumber(l) <= toNumber(r);
+            case '>=': return toNumber(l) >= toNumber(r);
+            default: throw new Error(`act body 未知运算符 "${op}"`);
+        }
+    }
+    async evalCall(call, scope) {
+        // 内置函数：位置参数
+        const builtin = ACT_BUILTINS.get(call.callee);
+        if (builtin) {
+            const args = await Promise.all(call.args.map(a => this.evalExpr(a.value, scope)));
+            return builtin.fn(args);
+        }
+        // 否则视为 ToolProvider 工具：命名参数 → Record；先查 requires_commit 拦截
+        const toolDef = this.ctx.toolProvider.list().find(t => t.name === call.callee);
+        if (!toolDef) {
+            throw new Error(`TOOL_EXEC_ERROR: act body 调用未知工具/函数 "${call.callee}"（不在内置白名单也不在 ToolProvider 清单）`);
+        }
+        if (!this.ctx.allowCommit && toolDef.requires_commit) {
+            throw new Error(`COMMIT_REQUIRED: tool "${call.callee}" requires commit step`);
+        }
+        const argObj = {};
+        for (const a of call.args) {
+            if (!a.name)
+                throw new Error(`act body 工具 "${call.callee}" 调用须用命名参数（如 ${call.callee}(arg: value)）`);
+            argObj[a.name] = await this.evalExpr(a.value, scope);
+        }
+        const result = await this.ctx.toolProvider.execute(call.callee, argObj);
+        // 工具瞬时失败的重试归 ToolProvider 内部职责（execute 自己实现重试/超时）——
+        // 解释器只调一次拿结果，与工具命名空间同归宿主。失败即抛，转容器级 retry。
+        this.ctx.toolCallLog.push({
+            name: call.callee,
+            result: result.success ? 'success' : 'failure',
+            at: new Date().toISOString(),
+        });
+        if (!result.success) {
+            throw new Error(`TOOL_EXEC_ERROR: tool "${call.callee}" failed: ${String(result.result)}`);
+        }
+        return result.result;
+    }
+}
+function toNumber(v) {
+    const n = typeof v === 'number' ? v : Number(v);
+    if (Number.isNaN(n))
+        throw new Error(`act body 期望数字，实际: ${JSON.stringify(v)}`);
+    return n;
+}
+// 宽松相等：数字与数字字符串可比（"3" == 3），其余按 ===
+function looseEq(l, r) {
+    if (l === r)
+        return true;
+    if ((typeof l === 'number' || typeof r === 'number') && typeof l !== 'object' && typeof r !== 'object') {
+        const ln = Number(l);
+        const rn = Number(r);
+        if (!Number.isNaN(ln) && !Number.isNaN(rn))
+            return ln === rn;
+    }
+    return false;
+}

package/dist/act-body-parser.d.ts

@@ -0,0 +1,10 @@
+import type { ActBody } from './ast-types.js';
+import type { ParseError } from './errors.js';
+export declare function extractHopPythonFence(instructionLines: string[]): {
+    bodyLines: string[] | null;
+    bodyStartIndex: number;
+    narrative: string[];
+};
+export declare function parseActBody(bodyLines: string[], baseLine: number, errors: ParseError[]): ActBody | null;
+export declare function serializeActBody(body: ActBody): string;
+export declare function bodyHasToolCall(body: ActBody): boolean;