@hoplogic/hopjit 0.1.0

package/dist/dispatcher.js

@@ -0,0 +1,692 @@
+// @module: step-dispatcher ^anc-struct-step-dispatcher
+import Anthropic from '@anthropic-ai/sdk';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { PromptAssembler, injectKnowledgeContext } from './prompt.js';
+import { DefaultToolProvider } from './tools.js';
+import { BodyInterpreter } from './act-body-interpreter.js';
+import { ErrorCode } from './errors.js';
+// 算子级重试：SCHEMA_MISMATCH 缺省重做次数（与 subtask retry 缺省值对齐）
+// 见 design/step-dispatcher.md ^anc-exec-operator-retry
+const SCHEMA_RETRY_MAX = 3;
+// API 输出 token 上限缺省值（env / resource_limits 都未指定时）。
+const DEFAULT_MAX_OUTPUT_TOKENS = 16384;
+/** 独立模式的驱动适配层：跑调度循环（init→next→execute→done）并直调 Anthropic API 完成单步推理与工具调用。见 [[step-dispatcher#^anc-struct-step-dispatcher]] */
+export class StepDispatcher {
+    engine;
+    hostConfig;
+    clients = new Map(); // @a: anc-exec-model-routing
+    defaultClient;
+    toolProvider;
+    cumulativeTokens = 0;
+    replanAttempts = new Map();
+    maxToolIterations;
+    tokenBudget;
+    timeoutSeconds;
+    pendingPause = null; // confirm/commit 暂停信号，executionLoop 读取后返回
+    constructor(engine, hostConfig, config = {}) {
+        this.engine = engine;
+        this.hostConfig = hostConfig;
+        const { apiKey, baseURL } = this.resolveCredential();
+        this.defaultClient = baseURL
+            ? new Anthropic({ apiKey, baseURL })
+            : new Anthropic({ apiKey });
+        this.clients.set('default', this.defaultClient);
+        this.toolProvider = hostConfig.tool_provider ?? new DefaultToolProvider(hostConfig);
+        this.maxToolIterations = config.maxToolIterations
+            ?? hostConfig.resource_limits?.max_tool_iterations ?? 20;
+        this.tokenBudget = config.tokenBudget;
+        this.timeoutSeconds = config.timeoutSeconds
+            ?? hostConfig.resource_limits?.timeout_seconds;
+    }
+    async runSpec() {
+        return this.executionLoop();
+    }
+    /**
+     * 同实例恢复：注入 caller 对 confirm 暂停步骤的决策，继续执行循环。 // @a: anc-exec-resume-semantics
+     * confirm 是唯一的暂停点（鉴权/决策环节）：answer 作为步骤输出注入 → completeStep（audit hitl_decision）。
+     * commit 不暂停（授权在前序完成），故 resume 不处理 commit。
+     */
+    async resume(stepId, answer) {
+        const node = this.findStepInSpec(stepId);
+        if (!node) {
+            throw new Error(`resume: step ${stepId} not found`);
+        }
+        if (node.step_type !== 'confirm' && node.step_type !== 'ask') {
+            throw new Error(`resume: step ${stepId} is ${node.step_type}, not a pausable step (only confirm/ask pause)`);
+        }
+        // confirm/ask answer 规范化统一在 engine.completeStep（^anc-exec-confirm-answer / ^anc-exec-hitl-presentation，
+        // 模式无关）。dispatcher 仅透传 answer，不自行判定，避免两模式逻辑分叉。审计由 completeStep 记录。
+        this.engine.completeStep(stepId, answer);
+        return this.executionLoop();
+    }
+    async resumeSpec() {
+        return this.executionLoop();
+    }
+    getCumulativeTokens() {
+        return this.cumulativeTokens;
+    }
+    async executionLoop() {
+        while (true) {
+            const next = this.engine.nextStep();
+            switch (next.status) {
+                case 'completed':
+                    return { status: 'completed', outputs: next.outputs, cumulative_tokens: this.cumulativeTokens };
+                case 'failed': {
+                    const f = next;
+                    return { status: 'failed', failure: { step_id: f.failed_step_id, reason: f.failure_reason }, cumulative_tokens: this.cumulativeTokens };
+                }
+                case 'paused':
+                    return { status: 'paused', pause: next, cumulative_tokens: this.cumulativeTokens };
+                case 'adaptive_needed':
+                    await this.handleAdaptive(next);
+                    break;
+                case 'step_ready':
+                    await this.handleStepReady(next);
+                    // confirm/commit 步骤暂停：步骤保持 running，返回暂停信号等待 caller 决策（CITL）
+                    if (this.pendingPause) {
+                        const pause = this.pendingPause;
+                        this.pendingPause = null;
+                        return { status: 'paused', pause, cumulative_tokens: this.cumulativeTokens };
+                    }
+                    break;
+            }
+        }
+    }
+    async handleStepReady(step) {
+        const hasNoneInputs = this.checkNoneInputs(step);
+        if (hasNoneInputs) {
+            this.engine.failStep(step.step_id, 'MISSING_INPUT: required input is None');
+            return;
+        }
+        // L2 Knowledge injection: enrich context if KnowledgeProvider is available
+        await this.injectKnowledge(step);
+        // 注：L2d doc-ref 解析已下沉到 engine.assembleBasicContext（两模式共享），
+        // 不在 dispatcher——见 design/step-dispatcher.md ^anc-exec-doc-ref-resolve（架构修正）
+        try {
+            let result = await this.executeStepWithTimeout(step);
+            if (result === 'paused')
+                return;
+            if (this.hasLackOfInfo(result) && this.hostConfig.knowledge_provider) {
+                const query = typeof result.lack_of_info === 'string' ? result.lack_of_info : step.summary;
+                const fragments = await this.hostConfig.knowledge_provider.retrieve(query, 5);
+                if (fragments.length > 0) {
+                    const supplementary = fragments.map(f => f.content).join('\n\n');
+                    step.context.knowledge_context = (step.context.knowledge_context ?? '')
+                        + `\n\n### 补充检索（由步骤 ${step.step_id} 的 lack_of_info 触发）\n${supplementary}`;
+                    const retryResult = await this.executeStepWithTimeout(step);
+                    if (retryResult === 'paused')
+                        return;
+                    if (this.hasLackOfInfo(retryResult)) {
+                        this.engine.failStep(step.step_id, `${query} (supplementary retrieval exhausted)`, 'lack_of_info');
+                        return;
+                    }
+                    result = retryResult;
+                }
+                else {
+                    this.engine.failStep(step.step_id, `${query} (no knowledge available)`, 'lack_of_info');
+                    return;
+                }
+            }
+            // 算子级重试：completeStep 校验输出 schema，不匹配则拼反馈重做（缺省 3 次），
+            // 耗尽 failStep（转入容器级 retry）。复用模式无此循环——done 直接返回 SCHEMA_MISMATCH
+            // 由 caller 重试。见 design/step-dispatcher.md ^anc-exec-operator-retry
+            // @a: anc-exec-operator-retry
+            // body 步骤跳过 SCHEMA_MISMATCH 重试：该重试是为 LLM「改 prompt 重做」设计的，body 不是
+            // LLM 且确定性——同 body 重跑产出一样的不匹配，重做无意义。schema 不匹配直接 failStep
+            // 转容器级 retry。（注：工具瞬时失败的重试归 ToolProvider 内部，与本层无关。）// @a: anc-exec-act-body-interp
+            const bodyNode = this.findStepInSpec(step.step_id);
+            const isBodyStep = !!bodyNode?.body;
+            const baseInstruction = step.context.instruction;
+            let attempt = 1;
+            while (true) {
+                const resp = this.engine.completeStep(step.step_id, result);
+                if (resp.code !== ErrorCode.SCHEMA_MISMATCH)
+                    break; // 通过或其他响应 → 交回主循环
+                if (isBodyStep || attempt >= SCHEMA_RETRY_MAX) {
+                    this.engine.failStep(step.step_id, isBodyStep
+                        ? `${resp.message}（act body 确定性，schema 不匹配不改 prompt 重做，转容器级 retry）`
+                        : `${resp.message} (after ${SCHEMA_RETRY_MAX} attempts)`);
+                    return;
+                }
+                attempt++;
+                // 把校验反馈拼回 instruction，重做该算子
+                step.context.instruction = `${baseInstruction}\n\n[上次输出未通过校验，请修正后重新输出]\n${resp.message}`;
+                const retry = await this.executeStepWithTimeout(step);
+                if (retry === 'paused')
+                    return;
+                result = retry;
+            }
+            step.context.instruction = baseInstruction;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.engine.failStep(step.step_id, reason);
+        }
+    }
+    async injectKnowledge(step) {
+        const provider = this.hostConfig.knowledge_provider;
+        if (!provider)
+            return;
+        const spec = this.engine.getSpec();
+        if (!spec)
+            return;
+        const stepNode = this.findStepInSpec(step.step_id);
+        if (!stepNode)
+            return;
+        try {
+            const sources = await injectKnowledgeContext(step.context, provider, spec, stepNode);
+            // knowledge 流控字段（info 级）：记录本步检索到的知识来源 // @a: anc-obs-step-mapping
+            if (sources.length > 0) {
+                const at = new Date().toISOString();
+                this.engine.getHopLog()?.recordStepMeta(step.step_id, {
+                    knowledge: sources.map(source_id => ({ source_id, at })),
+                });
+            }
+        }
+        catch (err) {
+            // 知识注入降级：provider 抛错 → L2 留空。不静默——记 stderr 诊断，
+            // 让排障能区分「provider 真没返回」与「provider 抛异常」。
+            const reason = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[knowledge-degraded] step ${step.step_id}: provider error, L2 empty — ${reason}\n`);
+        }
+    }
+    async handleAdaptive(resp) {
+        const subtaskId = resp.subtask_id;
+        const attempts = this.replanAttempts.get(subtaskId) ?? 0;
+        const maxReplanAttempts = this.hostConfig.resource_limits?.max_replan_attempts ?? 3;
+        if (attempts >= maxReplanAttempts) {
+            this.engine.failStep(subtaskId, `Replan circuit breaker: ${maxReplanAttempts} attempts exhausted`);
+            return;
+        }
+        const hasKnowledge = !!this.hostConfig.knowledge_provider;
+        const assembler = new PromptAssembler(this.engine, hasKnowledge);
+        const ctx = assembler.assembleAdaptiveContext(subtaskId);
+        const { request, client } = this.buildApiRequest(ctx, 'reason');
+        try {
+            const response = await this.callLlmWithRetry(request, client);
+            const newStepsMd = this.extractTextContent(response);
+            const replanResult = this.engine.submitReplan(subtaskId, newStepsMd);
+            if (replanResult.status === 'error') {
+                this.recordReplanFailure(subtaskId, attempts, maxReplanAttempts, `Replan failed after ${maxReplanAttempts} attempts`);
+            }
+            else {
+                this.replanAttempts.set(subtaskId, 0);
+            }
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.recordReplanFailure(subtaskId, attempts, maxReplanAttempts, `Replan API error after ${maxReplanAttempts} attempts: ${reason}`);
+        }
+    }
+    async executeStepWithTimeout(step) {
+        if (!this.timeoutSeconds) {
+            return this.executeStep(step);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutSeconds * 1000);
+        try {
+            const result = await Promise.race([
+                this.executeStep(step),
+                new Promise((_, reject) => {
+                    controller.signal.addEventListener('abort', () => reject(new Error(`STEP_TIMEOUT: exceeded ${this.timeoutSeconds}s`)));
+                }),
+            ]);
+            return result;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async executeStep(step) {
+        const stepType = step.step_type;
+        switch (stepType) {
+            case 'reason':
+            case 'check':
+                return this.executeReasonOrCheck(step);
+            case 'act':
+                return this.executeActBody(step, false);
+            case 'confirm':
+                return this.executeConfirm(step);
+            case 'commit':
+                return this.executeCommit(step);
+            case 'call':
+                throw new Error('call step recursive execution not implemented in v1');
+            default:
+                throw new Error(`Unknown executable step type: ${stepType}`);
+        }
+    }
+    async executeReasonOrCheck(step) {
+        const { request, client } = this.buildApiRequest(step.context, step.step_type, step);
+        let response;
+        try {
+            response = await this.callLlmWithRetry(request, client);
+        }
+        catch (err) {
+            if (this.isContextOverflow(err)) {
+                const hasKnowledge = !!this.hostConfig.knowledge_provider;
+                const assembler = new PromptAssembler(this.engine, hasKnowledge);
+                const stepNode = this.findStepInSpec(step.step_id);
+                if (stepNode) {
+                    const aggressiveCtx = assembler.reassembleAggressive(stepNode);
+                    const { request: retryRequest, client: retryClient } = this.buildApiRequest(aggressiveCtx, step.step_type, step);
+                    response = await this.callLlmWithRetry(retryRequest, retryClient);
+                }
+                else {
+                    throw err;
+                }
+            }
+            else {
+                throw err;
+            }
+        }
+        const hopLog = this.engine.getHopLog();
+        if (hopLog) {
+            // 独立模式执行内幕（LLM/tool）由 Dispatcher 写入 HopLog；复用模式归 caller 生态 // @a: anc-obs-mode-boundary
+            hopLog.recordStepMeta(step.step_id, {
+                llm: { model: request.model, input_tokens: response.usage?.input_tokens, output_tokens: response.usage?.output_tokens },
+                tokens_used: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0),
+            });
+        }
+        return this.parseStepOutput(response, step.context.output_schema);
+    }
+    // act 步骤中 LLM 仅能从预注册工具列表选择调用——无任意代码执行 // @a: anc-exec-sandbox-principle, anc-config-sandbox-step-mapping
+    async executeActWithTools(step, allowCommit = false) {
+        const tools = this.toolProvider.list().map(t => ({
+            name: t.name,
+            description: t.description,
+            input_schema: t.input_schema,
+        }));
+        let messages = this.buildMessages(step.context);
+        const systemPrompt = this.buildSystemPrompt(step.context);
+        const resolved = this.resolveModel('act', step);
+        const actClient = this.getClientForService(resolved.service_id);
+        const toolCallLog = [];
+        let iteration = 0;
+        while (iteration < this.maxToolIterations) {
+            this.checkBudget();
+            const response = await this.callLlmWithRetry({
+                model: resolved.model,
+                system: systemPrompt,
+                messages,
+                max_tokens: this.resolveMaxOutputTokens(),
+                temperature: 0,
+                tools,
+            }, actClient);
+            const hasToolUse = response.content.some(b => b.type === 'tool_use');
+            if (!hasToolUse) {
+                this.flushToolLog(step.step_id, toolCallLog);
+                return this.parseStepOutput(response, step.context.output_schema);
+            }
+            const assistantContent = response.content;
+            messages = [...messages, { role: 'assistant', content: assistantContent }];
+            const toolResults = [];
+            for (const block of assistantContent) {
+                if (block.type === 'tool_use') {
+                    // act 步骤拦截 requires_commit=true 的工具；commit 步骤是授权执行点，放行 // @a: anc-exec-requires-commit
+                    const toolDef = this.toolProvider.list().find(t => t.name === block.name);
+                    if (!allowCommit && toolDef?.requires_commit) {
+                        throw new Error('COMMIT_REQUIRED: tool "' + block.name + '" requires commit step');
+                    }
+                    const result = await this.toolProvider.execute(block.name, block.input);
+                    // tool 审计性字段，步骤完成时经 recordStepMeta 写入 // @a: anc-obs-audit
+                    toolCallLog.push({ name: block.name, result: result.success ? 'success' : 'failure', at: new Date().toISOString() });
+                    toolResults.push({
+                        type: 'tool_result',
+                        tool_use_id: block.id,
+                        content: result.success ? String(result.result) : `Error: ${result.result}`,
+                        is_error: !result.success,
+                    });
+                }
+            }
+            messages = [...messages, { role: 'user', content: toolResults }];
+            iteration++;
+        }
+        throw new Error('MAX_TOOL_ITERATIONS: exceeded tool use iteration limit');
+    }
+    executeConfirm(step) {
+        // confirm 暂停：构造 ExecutionPaused 信号，步骤保持 running 等待 caller 决策
+        const node = this.findStepInSpec(step.step_id);
+        const options = node?.response_options
+            ?? [
+                { value: 'approve', label: '批准' },
+                { value: 'reject', label: '拒绝' },
+            ];
+        this.pendingPause = {
+            status: 'paused',
+            instance_id: this.engine.getInstanceId(),
+            step_id: step.step_id,
+            pause_reason: node?.require_human ? 'waiting_human' : 'confirm',
+            presented_data: {
+                summary: step.summary,
+                instruction: step.context.instruction,
+                context: step.context.inputs,
+            },
+            response_options: options,
+            work_zone: '', // 独立模式不暴露 work_zone 给外部 driver, 见 anc-exec-work-zone
+        };
+        return 'paused';
+    }
+    // commit 直接执行不可逆操作——授权已在前序完成（环境预授权或前置 confirm），commit 本身不暂停鉴权
+    // 如同 git commit：能执行到此即已授权，直接执行写入。audit 记录执行内幕。 // @a: anc-step-commit
+    async executeCommit(step) {
+        const node = this.findStepInSpec(step.step_id);
+        const target = node?.irreversible_action ?? step.summary;
+        const hopLog = this.engine.getHopLog();
+        // commit 走 body 执行器（allowCommit=true 放行 requires_commit 工具）；无 body 回退 LLM 循环
+        const result = await this.executeActBody(step, true);
+        // commit_audit 审计性字段：记录不可逆操作执行 // @a: anc-obs-audit
+        // authorized_by='policy'：授权由前序流程（confirm 或环境策略）建立，非 commit 自身索取
+        if (hopLog) {
+            hopLog.recordStepMeta(step.step_id, {
+                commit_audit: { target, authorized_by: 'policy', result: 'success', at: new Date().toISOString() },
+            });
+        }
+        return result;
+    }
+    // act/commit 执行：有 hop_python body 走 BodyInterpreter（确定性、无 LLM）；
+    // 无 body 回退 executeActWithTools（LLM 循环，存量 spec 零回归）。 // @a: anc-exec-act-body-interp
+    async executeActBody(step, allowCommit) {
+        const node = this.findStepInSpec(step.step_id);
+        if (!node?.body) {
+            return this.executeActWithTools(step, allowCommit); // fallback
+        }
+        const toolCallLog = [];
+        const interp = new BodyInterpreter({
+            inputs: step.context.inputs,
+            toolProvider: this.toolProvider,
+            allowCommit,
+            toolCallLog,
+        });
+        const outputs = await interp.run(node.body, step.context.output_schema);
+        // tool 审计字段：步骤完成时写入 HopLog（与 executeActWithTools 一致）// @a: anc-obs-audit
+        this.flushToolLog(step.step_id, toolCallLog);
+        return outputs;
+    }
+    buildApiRequest(context, stepType, step) {
+        const system = this.buildSystemPrompt(context);
+        const messages = this.buildMessages(context);
+        const resolved = this.resolveModel(stepType, step);
+        const client = this.getClientForService(resolved.service_id);
+        const maxOutput = this.resolveMaxOutputTokens();
+        return {
+            request: {
+                model: resolved.model,
+                system,
+                messages,
+                max_tokens: maxOutput,
+                temperature: this.selectTemperature(stepType),
+            },
+            client,
+        };
+    }
+    buildSystemPrompt(context) {
+        const parts = [`Working directory: ${this.hostConfig.workspace_dir}\n\n${context.task_context}`];
+        if (context.knowledge_context)
+            parts.push(context.knowledge_context);
+        if (context.doc_ref_context)
+            parts.push(context.doc_ref_context); // L2d doc-ref // @a: anc-exec-doc-ref-injection
+        return parts.join('\n\n---\n\n');
+    }
+    buildMessages(context) {
+        const messages = [];
+        let progress = context.progress_summary;
+        if (context.iteration_history)
+            progress += '\n\n' + context.iteration_history;
+        if (progress.trim()) {
+            messages.push({ role: 'user', content: '[执行进度]\n' + progress });
+        }
+        const inputsText = this.formatInputs(context.inputs);
+        messages.push({ role: 'user', content: '[步骤输入]\n' + inputsText });
+        messages.push({ role: 'user', content: '[当前任务]\n' + context.instruction });
+        const schemaText = this.formatOutputSchema(context.output_schema);
+        messages.push({ role: 'user', content: '[输出要求]\n' + schemaText + '\n\n请严格按上述结构输出 YAML。' });
+        return messages;
+    }
+    formatInputs(inputs) {
+        const lines = [];
+        for (const [key, value] of Object.entries(inputs)) {
+            if (value === null || value === undefined) {
+                lines.push(`${key}: None`);
+            }
+            else if (typeof value === 'string') {
+                const display = value.length > 500 ? value.slice(0, 497) + '...' : value;
+                lines.push(`${key}: ${display}`);
+            }
+            else {
+                lines.push(`${key}: ${JSON.stringify(value)}`);
+            }
+        }
+        return lines.length > 0 ? lines.join('\n') : '(none)';
+    }
+    formatOutputSchema(schema) {
+        return schema.map(o => {
+            let line = `- ${o.name}: ${o.type}`;
+            if (o.description)
+                line += ` # ${o.description}`;
+            return line;
+        }).join('\n');
+    }
+    selectTemperature(stepType) {
+        switch (stepType) {
+            case 'reason': return 0.3;
+            case 'act': return 0;
+            case 'check': return 0;
+            case 'commit': return 0;
+            default: return 0.3;
+        }
+    }
+    async callLlmWithRetry(request, client) {
+        const maxRetries = 4;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const resp = await (client ?? this.defaultClient).messages.create(request);
+                this.cumulativeTokens += resp.usage.input_tokens + resp.usage.output_tokens;
+                this.checkBudget();
+                return resp;
+            }
+            catch (err) {
+                lastError = err;
+                if (this.isAuthFailure(err))
+                    throw err;
+                if (this.isContextOverflow(err))
+                    throw err;
+                const retriesForError = this.getMaxRetries(err);
+                if (attempt >= retriesForError)
+                    throw err;
+                const delay = 1000 * Math.pow(2, attempt) + Math.random() * 100;
+                await this.sleep(delay);
+            }
+        }
+        throw lastError;
+    }
+    getMaxRetries(err) {
+        if (this.isRateLimited(err))
+            return 4;
+        if (this.isServerError(err))
+            return 3;
+        if (this.isTimeout(err) || this.isNetworkError(err))
+            return 2;
+        return 0;
+    }
+    isRateLimited(err) {
+        return err instanceof Anthropic.RateLimitError;
+    }
+    isServerError(err) {
+        return err instanceof Anthropic.InternalServerError;
+    }
+    isTimeout(err) {
+        return err instanceof Anthropic.APIConnectionTimeoutError;
+    }
+    isNetworkError(err) {
+        return err instanceof Anthropic.APIConnectionError;
+    }
+    isAuthFailure(err) {
+        return err instanceof Anthropic.AuthenticationError;
+    }
+    isContextOverflow(err) {
+        if (err instanceof Anthropic.BadRequestError) {
+            // 收紧到 Anthropic 上下文超长的实际文案——旧判据裸命中 token/context 子串，
+            // 会把无关的鉴权类 'invalid token' BadRequest 误判为溢出、触发 reassembleAggressive。
+            const msg = (err.message ?? '').toLowerCase();
+            return msg.includes('prompt is too long')
+                || msg.includes('context_length')
+                || msg.includes('context length exceeded')
+                || msg.includes('maximum context')
+                || msg.includes('too many tokens')
+                || (msg.includes('too long') && msg.includes('token'));
+        }
+        return false;
+    }
+    checkBudget() {
+        if (this.tokenBudget && this.cumulativeTokens >= this.tokenBudget) {
+            throw new Error('BUDGET_EXCEEDED: token budget exhausted');
+        }
+    }
+    checkNoneInputs(step) {
+        const inputs = step.context.inputs;
+        return Object.values(inputs).some(v => v === null);
+    }
+    parseStepOutput(response, schema) {
+        const text = this.extractTextContent(response);
+        const outputs = {};
+        if (schema.length === 1) {
+            outputs[schema[0].name] = text.trim();
+            return outputs;
+        }
+        // Try YAML-like parsing: "key: value" per line
+        for (const decl of schema) {
+            const regex = new RegExp(`^${decl.name}:\\s*(.+)$`, 'm');
+            const match = text.match(regex);
+            if (match) {
+                outputs[decl.name] = match[1].trim();
+            }
+            else {
+                outputs[decl.name] = null;
+            }
+        }
+        return outputs;
+    }
+    extractTextContent(response) {
+        return response.content
+            .filter(b => b.type === 'text')
+            .map(b => b.text)
+            .join('\n');
+    }
+    findStepNode(steps, stepId) {
+        for (const s of steps) {
+            if (s.step_id === stepId)
+                return s;
+            if (s.children) {
+                const found = this.findStepNode(s.children, stepId);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    resolveCredential() {
+        const baseURL = process.env['ANTHROPIC_BASE_URL'] || this.hostConfig.base_url || undefined;
+        const authToken = process.env['ANTHROPIC_AUTH_TOKEN'];
+        if (authToken && authToken.trim()) {
+            return { apiKey: authToken, baseURL };
+        }
+        const envKey = process.env['ANTHROPIC_API_KEY']
+            ?? process.env['HOPSTEP_ANTHROPIC_API_KEY'];
+        if (envKey && envKey.trim())
+            return { apiKey: envKey, baseURL };
+        if (this.hostConfig.api_key && this.hostConfig.api_key.trim()) {
+            return { apiKey: this.hostConfig.api_key, baseURL };
+        }
+        const configPath = join(homedir(), '.hopstep', 'config.json');
+        if (existsSync(configPath)) {
+            const stat = statSync(configPath);
+            const mode = stat.mode & 0o777;
+            if (mode > 0o600) {
+                throw new Error(`~/.hopstep/config.json has insecure permissions (${mode.toString(8)}). Must be 0600 or less.`);
+            }
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            if (config.api_key && config.api_key.trim())
+                return { apiKey: config.api_key, baseURL };
+        }
+        throw new Error('No API key found. Set ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, or provide via HostConfig.');
+    }
+    resolveModel(stepType, step) {
+        if (step) {
+            const stepNode = this.findStepInSpec(step.step_id);
+            if (stepNode?.model_override)
+                return this.parseModelRef(stepNode.model_override);
+        }
+        const specConfig = this.engine.getSpec()?.header?.config;
+        if (specConfig?.model)
+            return this.parseModelRef(specConfig.model);
+        const me = this.hostConfig.model_engine;
+        if (me?.routing_rules) {
+            for (const rule of me.routing_rules) {
+                if (rule.match.step_type === stepType)
+                    return { service_id: rule.service_id, model: rule.model };
+            }
+        }
+        const envModel = process.env['ANTHROPIC_MODEL'];
+        if (envModel)
+            return { service_id: 'default', model: envModel };
+        if (me?.default_model)
+            return { service_id: me.default_service_id ?? 'default', model: me.default_model };
+        if (this.hostConfig.model)
+            return { service_id: 'default', model: this.hostConfig.model };
+        return { service_id: 'default', model: 'claude-sonnet-4-20250514' };
+    }
+    parseModelRef(ref) {
+        const slash = ref.indexOf('/');
+        if (slash > 0)
+            return { service_id: ref.slice(0, slash), model: ref.slice(slash + 1) };
+        return { service_id: 'default', model: ref };
+    }
+    findStepInSpec(stepId) {
+        const steps = this.engine.getSpec()?.steps;
+        if (!steps)
+            return null;
+        return this.findStepNode(steps, stepId);
+    }
+    /** 解析 API 输出 token 上限：env → resource_limits → 缺省。单点定义（原两处逐字复制）。
+     * 通用 env `HOPJIT_MAX_OUTPUT_TOKENS` 优先；`CLAUDE_CODE_MAX_OUTPUT_TOKENS` 保留作兼容（CC 宿主已设的不破坏）。 */
+    resolveMaxOutputTokens() {
+        return Number(process.env['HOPJIT_MAX_OUTPUT_TOKENS']
+            ?? process.env['CLAUDE_CODE_MAX_OUTPUT_TOKENS']
+            ?? this.hostConfig.resource_limits?.max_output_tokens ?? DEFAULT_MAX_OUTPUT_TOKENS);
+    }
+    /** replan 失败收尾：attempts+1 写回，达上限则 failStep。error 分支与 catch 分支共用。 */
+    recordReplanFailure(subtaskId, attempts, maxReplanAttempts, reasonText) {
+        this.replanAttempts.set(subtaskId, attempts + 1);
+        if (attempts + 1 >= maxReplanAttempts) {
+            this.engine.failStep(subtaskId, reasonText);
+        }
+    }
+    /** 步骤完成时把工具调用日志写入 HopLog（非空才写）。executeActWithTools / executeActBody 共用。 */
+    flushToolLog(stepId, toolCallLog) {
+        const hopLog = this.engine.getHopLog();
+        if (hopLog && toolCallLog.length > 0) {
+            hopLog.recordStepMeta(stepId, { tool: toolCallLog });
+        }
+    }
+    getClientForService(service_id) {
+        if (this.clients.has(service_id))
+            return this.clients.get(service_id);
+        const envKey = process.env[`${service_id.toUpperCase()}_API_KEY`];
+        const envUrl = process.env[`${service_id.toUpperCase()}_BASE_URL`];
+        if (envKey) {
+            const client = envUrl ? new Anthropic({ apiKey: envKey, baseURL: envUrl }) : new Anthropic({ apiKey: envKey });
+            this.clients.set(service_id, client);
+            return client;
+        }
+        return this.defaultClient;
+    }
+    hasLackOfInfo(result) {
+        return result.lack_of_info !== undefined && result.lack_of_info !== null;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}