minimal-agent 0.13.0 → 0.14.0

package/skills/workflow-creator/scripts/workflow-creator.test.mjs

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCAFFOLD = join(HERE, 'scaffold.mjs');
+const VALIDATE = join(HERE, 'validate.mjs');
+
+function run(script, args) {
+  return spawnSync(process.execPath, [script, ...args], {
+    encoding: 'utf8',
+  });
+}
+
+test('scaffold 默认只创建必需文件，可选目录必须显式请求', async (t) => {
+  const temp = await mkdtemp(join(tmpdir(), 'workflow-creator-'));
+  t.after(() => rm(temp, { recursive: true, force: true }));
+  const workflowsRoot = join(temp, 'workflows');
+
+  const minimal = run(SCAFFOLD, [
+    'minimal-case',
+    `--workflows-root=${workflowsRoot}`,
+  ]);
+  assert.equal(minimal.status, 0, minimal.stderr);
+  assert.deepEqual(
+    (await readdir(join(workflowsRoot, 'minimal-case'))).sort(),
+    ['README.md', 'workflow.mjs'],
+  );
+
+  const verdict = run(VALIDATE, [
+    join(workflowsRoot, 'minimal-case', 'workflow.mjs'),
+  ]);
+  assert.equal(verdict.status, 0, verdict.stderr);
+
+  const extended = run(SCAFFOLD, [
+    'extended-case',
+    '--with=scripts,prompts,assets',
+    `--workflows-root=${workflowsRoot}`,
+  ]);
+  assert.equal(extended.status, 0, extended.stderr);
+  assert.deepEqual(
+    (await readdir(join(workflowsRoot, 'extended-case'))).sort(),
+    ['README.md', 'assets', 'prompts', 'scripts', 'workflow.mjs'],
+  );
+  assert.match(
+    await readFile(
+      join(workflowsRoot, 'extended-case', 'scripts', 'README.md'),
+      'utf8',
+    ),
+    /\$\{workflowDir\}\/scripts/,
+  );
+});
+
+test('validator 拒绝不存在的配套文件引用', async (t) => {
+  const temp = await mkdtemp(join(tmpdir(), 'workflow-validator-'));
+  t.after(() => rm(temp, { recursive: true, force: true }));
+  const workflowDir = join(temp, 'workflows', 'broken-case');
+
+  const scaffold = run(SCAFFOLD, [
+    'broken-case',
+    `--workflows-root=${join(temp, 'workflows')}`,
+  ]);
+  assert.equal(scaffold.status, 0, scaffold.stderr);
+  await writeFile(
+    join(workflowDir, 'workflow.mjs'),
+    `export const meta = { description: 'broken reference', artifacts: [] }
+
+const prompt = await readText('prompts/missing.md')
+echo(prompt)
+`,
+    'utf8',
+  );
+
+  const verdict = run(VALIDATE, [join(workflowDir, 'workflow.mjs')]);
+  assert.equal(verdict.status, 1);
+  assert.match(verdict.stderr, /prompts\/missing\.md/);
+  assert.match(verdict.stderr, /不存在/);
+});

package/src/advisor/advisorCoordinator.js

@@ -0,0 +1,503 @@
+import crypto from 'node:crypto';
+/**
+ * 同一个检查点最多连续暂缓几次，超过就降级放行并留痕。
+ *
+ * 取 3 而不是 1：一次暂缓 + 一次咨询 + 一次记录决策是正常配合的节奏，
+ * 留出余量才不会误伤按流程走、只是多绕了一步的模型；取有限值而不是无限，
+ * 是因为唯一的替代上界是 maxTurns（200 轮），那不叫闸门叫卡死。
+ */
+const MAX_CONSECUTIVE_DEFERRALS = 3;
+const MAX_FREE_RECONCILIATIONS_PER_CHECKPOINT = 1;
+const WRITE_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'ApplyPatch', 'NotebookEdit']);
+const INVESTIGATION_TOOLS = new Set([
+    'Read',
+    'Glob',
+    'Grep',
+    'LSP',
+    'WebSearch',
+    'WebFetch',
+    'WebBrowser',
+    'TerminalCapture',
+    'RecallMemory',
+    'SearchConversations',
+]);
+function textContent(message) {
+    if (!message)
+        return '';
+    if (typeof message.content === 'string')
+        return message.content;
+    if (Array.isArray(message.content)) {
+        return message.content
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text)
+            .join('\n');
+    }
+    return '';
+}
+function toolNamesByCallId(history) {
+    const names = new Map();
+    for (const message of history) {
+        if (message.role !== 'assistant')
+            continue;
+        for (const call of message.tool_calls ?? [])
+            names.set(call.id, call.function.name);
+    }
+    return names;
+}
+function advisorMetadata(metadata) {
+    if (metadata?.kind === 'advisor_checkpoint' ||
+        metadata?.kind === 'advisor_consultation' ||
+        metadata?.kind === 'advisor_decision')
+        return metadata;
+    return undefined;
+}
+function versionsOf(metadata) {
+    return {
+        taskVersion: metadata.taskVersion,
+        workVersion: metadata.workVersion,
+        evidenceVersion: metadata.evidenceVersion,
+    };
+}
+function checkpointKey(checkpoint, versions) {
+    return `${versions.taskVersion}:${checkpoint}:${versions.workVersion}:${versions.evidenceVersion}`;
+}
+/**
+ * Run-local controller whose durable source of truth is Advisor metadata already
+ * stored on tool messages. It owns checkpoint de-duplication and versioning;
+ * provider calls remain in tools/advisor/advisor.ts.
+ */
+export class AdvisorCoordinator {
+    #history;
+    #currentRequest;
+    #advisorAvailable;
+    #completed = new Set();
+    #deferredOnce = new Set();
+    #deferCounts = new Map();
+    #successfulConsultationsByKey = new Map();
+    #softAlerts = new Set();
+    #taskVersion;
+    #taskCommitted = false;
+    #workVersion = 0;
+    #evidenceVersion = 0;
+    #investigationEvidence = 0;
+    #mutations = 0;
+    #verifications = 0;
+    #deliveryProduced = false;
+    #required;
+    #softCheckpoint;
+    #pending;
+    #lastDecision;
+    #reminders = [];
+    constructor(input) {
+        this.#history = input.history;
+        this.#currentRequest = input.currentRequest;
+        this.#advisorAvailable = input.advisorAvailable;
+        const names = toolNamesByCallId(input.history);
+        let maxTaskVersion = 0;
+        let maxWorkVersion = 0;
+        let maxEvidenceVersion = 0;
+        const decisions = new Set();
+        const successfulConsultations = [];
+        const currentRequestIndex = input.currentRequestMessageId
+            ? input.history.findIndex((message) => message.role === 'user' && message.id === input.currentRequestMessageId)
+            : -1;
+        for (let index = 0; index < input.history.length; index += 1) {
+            const message = input.history[index];
+            if (message.role !== 'tool')
+                continue;
+            const metadata = advisorMetadata(message.display_metadata);
+            if (metadata) {
+                maxTaskVersion = Math.max(maxTaskVersion, metadata.taskVersion);
+                maxWorkVersion = Math.max(maxWorkVersion, metadata.workVersion);
+                maxEvidenceVersion = Math.max(maxEvidenceVersion, metadata.evidenceVersion);
+                if (metadata.kind === 'advisor_decision') {
+                    decisions.add(metadata.consultationId);
+                    this.#completed.add(metadata.checkpointKey);
+                    this.#lastDecision = metadata;
+                }
+                else if (metadata.kind === 'advisor_consultation') {
+                    if (metadata.status === 'failed')
+                        this.#completed.add(metadata.checkpointKey);
+                    else {
+                        this.#successfulConsultationsByKey.set(metadata.checkpointKey, (this.#successfulConsultationsByKey.get(metadata.checkpointKey) ?? 0) + 1);
+                        successfulConsultations.push({ index, metadata });
+                    }
+                }
+            }
+            const toolName = names.get(message.tool_call_id);
+            const display = message.display_metadata;
+            if (display?.kind === 'file_activity') {
+                const mutationCount = display.files.filter((file) => ['created', 'modified', 'generated', 'deleted'].includes(file.activity)).length;
+                this.#workVersion += mutationCount;
+            }
+            const failed = message.content.startsWith('Error: ');
+            if (toolName &&
+                toolName !== 'Advisor' &&
+                toolName !== 'AdvisorDecision' &&
+                display?.kind !== 'advisor_checkpoint' &&
+                (!failed || display?.kind === 'process_execution')) {
+                this.#evidenceVersion += 1;
+            }
+        }
+        this.#workVersion = Math.max(this.#workVersion, maxWorkVersion);
+        this.#evidenceVersion = Math.max(this.#evidenceVersion, maxEvidenceVersion);
+        this.#taskVersion = maxTaskVersion + 1;
+        this.#pending = successfulConsultations
+            .filter(({ index }) => input.currentRequestMessageId === undefined
+            ? true
+            : currentRequestIndex >= 0 && index > currentRequestIndex)
+            .reverse()
+            .map(({ metadata }) => metadata)
+            .find((consultation) => !decisions.has(consultation.consultationId));
+    }
+    get versions() {
+        return {
+            taskVersion: this.#taskVersion,
+            workVersion: this.#workVersion,
+            evidenceVersion: this.#evidenceVersion,
+        };
+    }
+    get pendingConsultationId() {
+        return this.#pending?.consultationId;
+    }
+    get canReconcileConsultation() {
+        if (!this.#pending)
+            return false;
+        const successful = this.#successfulConsultationsByKey.get(this.#pending.checkpointKey) ?? 0;
+        return successful <= MAX_FREE_RECONCILIATIONS_PER_CHECKPOINT;
+    }
+    setAvailable(available) {
+        this.#advisorAvailable = available;
+    }
+    usageLine(used, max) {
+        const pending = this.#pending
+            ? `；顾问意见 #${this.#pending.consultationId.slice(-8)} 等待主 Agent 记录采纳决定`
+            : '';
+        return used === 0
+            ? `Advisor 动态：本回合尚未咨询顾问（可用 ${max} 次）${pending}。`
+            : `Advisor 动态：本回合已咨询 ${used}/${max} 次${pending}。`;
+    }
+    transientReminder() {
+        return this.#reminders.join('\n\n');
+    }
+    markTransientDelivered() {
+        this.#reminders = [];
+    }
+    beforeTool(call, semantics) {
+        if (!this.#advisorAvailable ||
+            call.function.name === 'Advisor' ||
+            call.function.name === 'AdvisorDecision') {
+            return { allow: true };
+        }
+        if (this.#pending && (semantics.mutatesWorkspace || semantics.highRisk)) {
+            return this.#deferPending('顾问意见已返回，但尚未调用 AdvisorDecision 记录主 Agent 的采纳判断。');
+        }
+        if (semantics.highRisk) {
+            return this.requestCheckpoint('high-risk', semantics.riskReason ?? '即将执行不可逆操作');
+        }
+        if (semantics.mutatesWorkspace) {
+            return this.requestCheckpoint('pre-execution', '即将进行本任务版本的首次实质写入');
+        }
+        return { allow: true };
+    }
+    requestCheckpoint(checkpoint, reason, options = {}) {
+        if (!this.#advisorAvailable)
+            return { allow: true };
+        this.#commitTask();
+        const key = checkpointKey(checkpoint, this.versions);
+        if (this.#completed.has(key))
+            return { allow: true };
+        if (options.oneShot && this.#deferredOnce.has(key)) {
+            this.#required = undefined;
+            this.#completed.add(key);
+            return { allow: true };
+        }
+        // ── 死锁上界：模型不配合时也必须让路 ──────────────────────────────
+        // 顾问**失败**这条路已有降级（finishConsultation 会 #completed.add），
+        // 但模型**不配合**（一直不调 Advisor/AdvisorDecision、只管重试写操作）此前无人管：
+        // high-risk 与 pre-execution 都不传 oneShot，同一个 key 会被反复 defer，
+        // 唯一的界是 maxTurns —— 而它刚从 50 涨到 200，用户看到的就是「agent 卡住不干活」。
+        // 本模块自己的原则是「不会死锁」，这里把那条原则补全到第二条路上。
+        const seen = (this.#deferCounts.get(key) ?? 0) + 1;
+        this.#deferCounts.set(key, seen);
+        if (seen > MAX_CONSECUTIVE_DEFERRALS) {
+            this.#required = undefined;
+            this.#completed.add(key);
+            // 绕过了本该经过的检查点就必须留痕：静默放行会让模型以为自己合规了。
+            const notice = `Advisor 检查点 ${checkpoint} 已连续暂缓 ${MAX_CONSECUTIVE_DEFERRALS} 次仍未完成咨询，本次降级放行。这一步没有第二意见背书，请自行加倍核实，并在汇报时如实说明。`;
+            if (!this.#reminders.includes(notice))
+                this.#reminders.push(notice);
+            return { allow: true };
+        }
+        this.#required = { checkpoint, key, reason };
+        this.#deferredOnce.add(key);
+        return this.#defer(checkpoint, reason, key);
+    }
+    notifyStalled(signature) {
+        if (!this.#advisorAvailable)
+            return;
+        this.#commitTask();
+        const key = `${checkpointKey('stalled', this.versions)}:${signature ?? 'unknown'}`;
+        if (this.#softAlerts.has(key))
+            return;
+        this.#softAlerts.add(key);
+        this.#softCheckpoint = {
+            checkpoint: 'stalled',
+            key: checkpointKey('stalled', this.versions),
+        };
+        this.#reminders.push('检测到连续同类失败或执行没有进展。继续重试前请优先调用 Advisor 获取第二意见；这是提醒，不阻止只读诊断或切换路径。');
+    }
+    shouldCheckDelivery() {
+        return (this.#mutations > 0 ||
+            this.#verifications > 0 ||
+            this.#deliveryProduced ||
+            this.#investigationEvidence >= 3);
+    }
+    beforeDelivery() {
+        if (this.#pending) {
+            const decision = this.#deferPending('提交最终结果前必须先用 AdvisorDecision 记录对当前顾问意见的判断。');
+            if (decision.deferred &&
+                !decision.deferred.ok &&
+                !this.#reminders.includes(decision.deferred.error)) {
+                this.#reminders.push(decision.deferred.error);
+            }
+            return decision;
+        }
+        if (!this.shouldCheckDelivery())
+            return { allow: true };
+        const decision = this.requestCheckpoint('pre-delivery', '当前回合已产生实质成果或证据，提交最终结论前进行一次第二意见复核', { oneShot: true });
+        if (decision.deferred &&
+            !decision.deferred.ok &&
+            !this.#reminders.includes(decision.deferred.error)) {
+            this.#reminders.push(decision.deferred.error);
+        }
+        return decision;
+    }
+    beginConsultation() {
+        this.#commitTask();
+        // #pending 存在 = 有一个检查点已经问过、还没被 AdvisorDecision 结清。
+        // 这种情况下的任何新咨询（模型主动复核、或 notifyStalled 又冒出一个软
+        // 检查点）都必须沿用它的身份，不能落到 #required/#softCheckpoint/默认
+        // pre-execution ——否则原始检查点的 checkpointKey 永远进不了 #completed，
+        // 重试会被误判成"没咨询过"再次拦下，而模型明明已经照工具说明书的要求
+        // 做了复核。这与 beforeTool 顶部"#pending 存在就先拦"的语义保持一致：
+        // 既然还有检查点没走完决策，新咨询理应服务于把它结清，而不是凭空开新身份。
+        const active = this.#pending
+            ? { checkpoint: this.#pending.checkpoint, key: this.#pending.checkpointKey }
+            : this.#required ??
+                this.#softCheckpoint ?? {
+                checkpoint: 'pre-execution',
+                key: checkpointKey('pre-execution', this.versions),
+            };
+        return {
+            kind: 'advisor_consultation',
+            consultationId: crypto.randomUUID(),
+            checkpoint: active.checkpoint,
+            checkpointKey: active.key,
+            status: 'completed',
+            ...this.versions,
+        };
+    }
+    finishConsultation(metadata, ok) {
+        const finished = {
+            ...metadata,
+            status: ok ? 'completed' : 'failed',
+        };
+        if (ok) {
+            this.#pending = finished;
+            this.#successfulConsultationsByKey.set(finished.checkpointKey, (this.#successfulConsultationsByKey.get(finished.checkpointKey) ?? 0) + 1);
+        }
+        else {
+            this.#completed.add(finished.checkpointKey);
+            if (this.#pending?.checkpointKey === finished.checkpointKey)
+                this.#pending = undefined;
+        }
+        this.#required = undefined;
+        this.#softCheckpoint = undefined;
+        return finished;
+    }
+    recordDecision(input) {
+        if (!this.#pending ||
+            this.#pending.consultationId !== input.consultationId) {
+            const expected = this.#pending?.consultationId;
+            return {
+                ok: false,
+                error: expected
+                    ? `顾问咨询 ID 不匹配：收到 ${input.consultationId}，当前待处理的完整 consultationId 是 ${expected}。请原样使用该完整 ID 重试一次 AdvisorDecision。`
+                    : `没有找到待处理的顾问咨询 ${input.consultationId}；不要继续重试 AdvisorDecision。`,
+                recovery: expected ? 'change-input' : 'none',
+            };
+        }
+        const metadata = {
+            kind: 'advisor_decision',
+            consultationId: input.consultationId,
+            checkpoint: this.#pending.checkpoint,
+            checkpointKey: this.#pending.checkpointKey,
+            decision: input.decision,
+            rationale: input.rationale,
+            acceptedPoints: input.acceptedPoints ?? [],
+            rejectedPoints: input.rejectedPoints ?? [],
+            verificationPlan: input.verificationPlan ?? [],
+            ...versionsOf(this.#pending),
+        };
+        this.#completed.add(metadata.checkpointKey);
+        this.#lastDecision = metadata;
+        this.#pending = undefined;
+        return {
+            ok: true,
+            content: `已记录顾问意见处理决定：${input.decision}。理由：${input.rationale}`,
+            metadata,
+        };
+    }
+    observeToolResult(call, result) {
+        if (!result.ok && result.disposition === 'deferred')
+            return;
+        if (result.metadata?.kind === 'advisor_consultation') {
+            if (result.metadata.status === 'completed')
+                this.#pending = result.metadata;
+            else {
+                this.#completed.add(result.metadata.checkpointKey);
+                if (this.#pending?.checkpointKey === result.metadata.checkpointKey)
+                    this.#pending = undefined;
+            }
+            return;
+        }
+        if (result.metadata?.kind === 'advisor_decision') {
+            this.#completed.add(result.metadata.checkpointKey);
+            this.#lastDecision = result.metadata;
+            this.#pending = undefined;
+            return;
+        }
+        const metadata = result.metadata;
+        const verificationResult = Boolean(metadata?.kind === 'process_execution' &&
+            metadata.commandKind !== 'other' &&
+            ['completed', 'failed'].includes(metadata.status));
+        if (verificationResult) {
+            this.#verifications += 1;
+            this.#evidenceVersion += 1;
+            if (!result.ok)
+                return;
+        }
+        if (!result.ok)
+            return;
+        if (metadata?.kind === 'file_activity') {
+            const mutations = metadata.files.filter((file) => ['created', 'modified', 'generated', 'deleted'].includes(file.activity)).length;
+            this.#mutations += mutations;
+            this.#workVersion += mutations;
+        }
+        if (metadata?.kind === 'result_manifest')
+            this.#deliveryProduced = true;
+        if (INVESTIGATION_TOOLS.has(call.function.name))
+            this.#investigationEvidence += 1;
+        if (call.function.name !== 'Advisor' &&
+            call.function.name !== 'AdvisorDecision' &&
+            !verificationResult) {
+            this.#evidenceVersion += 1;
+        }
+    }
+    contextPacket(note) {
+        const names = toolNamesByCallId(this.#history);
+        const changedFiles = new Set();
+        const evidence = [];
+        let previousAdvice;
+        let lastAdvisorIndex = -1;
+        for (let index = 0; index < this.#history.length; index += 1) {
+            const message = this.#history[index];
+            if (message.role !== 'tool')
+                continue;
+            const toolName = names.get(message.tool_call_id) ?? 'Tool';
+            if (message.display_metadata?.kind === 'file_activity') {
+                for (const file of message.display_metadata.files)
+                    changedFiles.add(file.relativePath);
+            }
+            if (message.display_metadata?.kind === 'process_execution') {
+                evidence.push(`${toolName}: ${message.display_metadata.commandKind}/${message.display_metadata.status}`);
+            }
+            else if (message.display_metadata?.kind === 'result_manifest') {
+                evidence.push(`${toolName}: 已生成 ${message.display_metadata.manifest.files.length} 个交付文件`);
+            }
+            else if (toolName !== 'Advisor' &&
+                toolName !== 'AdvisorDecision' &&
+                evidence.length < 12) {
+                evidence.push(`${toolName}: ${message.content.slice(0, 240)}`);
+            }
+            if (toolName === 'Advisor' &&
+                message.display_metadata?.kind === 'advisor_consultation' &&
+                message.display_metadata.status === 'completed') {
+                previousAdvice = message.content.slice(0, 4_000);
+                lastAdvisorIndex = index;
+            }
+        }
+        const actionsAfterPreviousAdvice = lastAdvisorIndex < 0
+            ? []
+            : this.#history
+                .slice(lastAdvisorIndex + 1)
+                .filter((message) => message.role === 'tool')
+                .map((message) => names.get(message.tool_call_id) ?? 'Tool')
+                .filter((name) => name !== 'AdvisorDecision');
+        const firstUser = this.#history.find((message) => message.role === 'user');
+        // 与 beginConsultation() 同一条修复：复核调用时顾问看到的 checkpoint 字段
+        // 不该被误标成 pre-execution ——它自己就是在评审那个还没结清的检查点。
+        const active = this.#pending
+            ? { checkpoint: this.#pending.checkpoint }
+            : this.#required ?? this.#softCheckpoint;
+        return {
+            objective: (textContent(firstUser) || this.#currentRequest).slice(0, 8_000),
+            currentRequest: this.#currentRequest.slice(0, 8_000),
+            checkpoint: active?.checkpoint ?? 'pre-execution',
+            versions: this.versions,
+            changedFiles: [...changedFiles],
+            evidence,
+            ...(previousAdvice ? { previousAdvice } : {}),
+            actionsAfterPreviousAdvice,
+            openQuestions: note ? [note] : [],
+        };
+    }
+    #commitTask() {
+        if (this.#taskCommitted)
+            return;
+        this.#taskCommitted = true;
+    }
+    #defer(checkpoint, reason, key) {
+        this.#commitTask();
+        const actualKey = key ?? checkpointKey(checkpoint, this.versions);
+        const metadata = {
+            kind: 'advisor_checkpoint',
+            checkpoint,
+            checkpointKey: actualKey,
+            status: 'required',
+            ...this.versions,
+        };
+        return {
+            allow: false,
+            deferred: {
+                ok: false,
+                disposition: 'deferred',
+                recovery: 'change-input',
+                sensitivity: 'public',
+                metadata,
+                error: `Advisor 检查点 ${checkpoint} 暂缓了这一步：${reason}\n请先调用 Advisor 获取第二意见；成功后调用 AdvisorDecision 记录采纳、部分采纳或拒绝及依据，然后重试原操作。若 Advisor 返回不可用/超时/配额不足，本检查点会降级放行，不要循环重试。`,
+            },
+        };
+    }
+    #deferPending(reason) {
+        const pending = this.#pending;
+        if (!pending)
+            return { allow: true };
+        const key = pending.checkpointKey;
+        const seen = (this.#deferCounts.get(key) ?? 0) + 1;
+        this.#deferCounts.set(key, seen);
+        if (seen > MAX_CONSECUTIVE_DEFERRALS) {
+            this.#completed.add(key);
+            this.#pending = undefined;
+            const notice = `Advisor 检查点 ${pending.checkpoint} 的咨询 ${pending.consultationId} 已连续等待 AdvisorDecision ${MAX_CONSECUTIVE_DEFERRALS} 次，本次降级结清并放行。这一步没有完整的顾问决策记录，请自行核实并在汇报时如实说明。`;
+            if (!this.#reminders.includes(notice))
+                this.#reminders.push(notice);
+            return { allow: true };
+        }
+        return this.#defer(pending.checkpoint, reason, key);
+    }
+}
+export function isWorkspaceMutationTool(name) {
+    return WRITE_TOOLS.has(name);
+}