minimal-agent 0.10.0 → 0.12.0

package/src/entry.compiled.tsx

@@ -0,0 +1,20 @@
+/**
+ * ============================================================
+ *  src/entry.compiled.tsx —— 绿色版（bun --compile 单文件）专属入口
+ * ------------------------------------------------------------
+ *  仅供 `bun build src/entry.compiled.tsx --compile ...` 使用。
+ *
+ *  与 npm bin / `bun run dev` 的区别：那两条路径入口都是 `src/main.tsx`，
+ *  **永不**经过本文件。本文件只比 main 多做一件事——先 import 内置插件注册表
+ *  （把 rich 插件执行器静态打进 exe），再加载主程序。
+ *
+ *  顺序保证：import 是同步求值，`builtinRegistry` 的副作用（注册）先于
+ *  `main`（其文件末尾 `main().catch()` 自调用启动 app）执行；等到用户敲
+ *  `/workflow` 命令分发时，注册表已就绪。
+ *
+ *  本文件被 tsconfig.json `exclude`，故不进 npm 发布物；`.npmignore` 另有兜底。
+ * ============================================================
+ */
+
+import './plugins/builtinRegistry.js';
+import './main.js';

package/src/harness/claimValidation.js

@@ -0,0 +1,9 @@
+/** Conservative deterministic check: only strong positive verification claims are inspected. */
+export function validateFinalClaims(assistantText, evidence) {
+    const claimsVerification = /(?:我)?已(?:运行|执行|完成).{0,20}(?:测试|typecheck|构建)|(?:测试|typecheck|构建).{0,12}(?:已全部通过|全部通过|成功完成)/i.test(assistantText);
+    const hasVerification = evidence.entries.some((entry) => entry.kind === 'verification' && entry.ok);
+    const warnings = claimsVerification && !hasVerification
+        ? ['最终回答包含已验证声明，但本轮证据台账没有成功的验证工具记录；该声明按未验证处理。']
+        : [];
+    return { verified: warnings.length === 0, warnings };
+}

package/src/harness/claimValidation.ts

@@ -0,0 +1,22 @@
+import type { RunEvidenceLedger } from '../types.js';
+
+export interface FinalClaimValidation {
+  verified: boolean;
+  warnings: string[];
+}
+
+/** Conservative deterministic check: only strong positive verification claims are inspected. */
+export function validateFinalClaims(
+  assistantText: string,
+  evidence: RunEvidenceLedger,
+): FinalClaimValidation {
+  const claimsVerification = /(?:我)?已(?:运行|执行|完成).{0,20}(?:测试|typecheck|构建)|(?:测试|typecheck|构建).{0,12}(?:已全部通过|全部通过|成功完成)/i.test(
+    assistantText,
+  );
+  const hasVerification = evidence.entries.some((entry) =>
+    entry.kind === 'verification' && entry.ok);
+  const warnings = claimsVerification && !hasVerification
+    ? ['最终回答包含已验证声明，但本轮证据台账没有成功的验证工具记录；该声明按未验证处理。']
+    : [];
+  return { verified: warnings.length === 0, warnings };
+}

package/src/harness/evidenceLedger.js

@@ -0,0 +1,92 @@
+import { createHash } from 'node:crypto';
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+function safeUrl(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function maxVerification(values) {
+    if (values.includes('failed'))
+        return 'failed';
+    if (values.includes('not_run'))
+        return 'not_run';
+    return values.length > 0 ? 'passed' : undefined;
+}
+export class EvidenceLedger {
+    #entries = [];
+    #toolCalls = 0;
+    #failedToolCalls = 0;
+    record(toolName, argsJson, result) {
+        this.#toolCalls += 1;
+        if (!result.ok)
+            this.#failedToolCalls += 1;
+        const base = {
+            toolName,
+            callHash: digest(`${toolName}\0${argsJson}`),
+            ok: result.ok,
+            resultHash: digest(result.ok ? result.content : result.error),
+            kind: 'tool',
+        };
+        const metadata = result.metadata;
+        if (metadata?.kind === 'process_execution') {
+            const verificationCommand = metadata.commandKind !== 'other';
+            const terminal = metadata.status === 'completed' || metadata.status === 'failed';
+            this.#entries.push({
+                ...base,
+                kind: verificationCommand && terminal ? 'verification' : 'tool',
+                ...(verificationCommand && terminal
+                    ? { verification: metadata.status === 'completed' && metadata.exitCode === 0 ? 'passed' : 'failed' }
+                    : {}),
+            });
+            return;
+        }
+        if (metadata?.kind === 'file_activity') {
+            this.#entries.push({
+                ...base,
+                kind: metadata.files.some((file) => file.purpose === 'deliverable') ? 'delivery' : 'file',
+                paths: metadata.files.map((file) => file.relativePath),
+                verification: maxVerification(metadata.files.map((file) => file.verification)),
+            });
+            return;
+        }
+        if (metadata?.kind === 'result_manifest') {
+            this.#entries.push({
+                ...base,
+                kind: 'delivery',
+                paths: metadata.manifest.files.map((file) => file.relativePath),
+                urls: metadata.manifest.links
+                    ?.map((link) => safeUrl(link.url))
+                    .filter((url) => Boolean(url)),
+                verification: maxVerification(metadata.manifest.files.map((file) => file.verification)),
+            });
+            return;
+        }
+        if (toolName === 'WebFetch') {
+            let url;
+            try {
+                url = safeUrl(JSON.parse(argsJson).url);
+            }
+            catch { /* invalid args are already represented by ok=false */ }
+            this.#entries.push({ ...base, kind: 'web', ...(url ? { urls: [url] } : {}) });
+            return;
+        }
+        this.#entries.push(base);
+    }
+    snapshot() {
+        return {
+            toolCalls: this.#toolCalls,
+            failedToolCalls: this.#failedToolCalls,
+            entries: this.#entries.map((entry) => ({ ...entry })),
+        };
+    }
+}

package/src/harness/evidenceLedger.ts

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import type {
+  FileVerification,
+  RunEvidenceEntry,
+  RunEvidenceLedger,
+  ToolResult,
+} from '../types.js';
+
+function digest(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+
+function safeUrl(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return undefined;
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return undefined;
+  }
+}
+
+function maxVerification(values: FileVerification[]): FileVerification | undefined {
+  if (values.includes('failed')) return 'failed';
+  if (values.includes('not_run')) return 'not_run';
+  return values.length > 0 ? 'passed' : undefined;
+}
+
+export class EvidenceLedger {
+  readonly #entries: RunEvidenceEntry[] = [];
+  #toolCalls = 0;
+  #failedToolCalls = 0;
+
+  record(toolName: string, argsJson: string, result: ToolResult): void {
+    this.#toolCalls += 1;
+    if (!result.ok) this.#failedToolCalls += 1;
+    const base: RunEvidenceEntry = {
+      toolName,
+      callHash: digest(`${toolName}\0${argsJson}`),
+      ok: result.ok,
+      resultHash: digest(result.ok ? result.content : result.error),
+      kind: 'tool',
+    };
+
+    const metadata = result.metadata;
+    if (metadata?.kind === 'process_execution') {
+      const verificationCommand = metadata.commandKind !== 'other';
+      const terminal = metadata.status === 'completed' || metadata.status === 'failed';
+      this.#entries.push({
+        ...base,
+        kind: verificationCommand && terminal ? 'verification' : 'tool',
+        ...(verificationCommand && terminal
+          ? { verification: metadata.status === 'completed' && metadata.exitCode === 0 ? 'passed' : 'failed' }
+          : {}),
+      });
+      return;
+    }
+    if (metadata?.kind === 'file_activity') {
+      this.#entries.push({
+        ...base,
+        kind: metadata.files.some((file) => file.purpose === 'deliverable') ? 'delivery' : 'file',
+        paths: metadata.files.map((file) => file.relativePath),
+        verification: maxVerification(metadata.files.map((file) => file.verification)),
+      });
+      return;
+    }
+    if (metadata?.kind === 'result_manifest') {
+      this.#entries.push({
+        ...base,
+        kind: 'delivery',
+        paths: metadata.manifest.files.map((file) => file.relativePath),
+        urls: metadata.manifest.links
+          ?.map((link) => safeUrl(link.url))
+          .filter((url): url is string => Boolean(url)),
+        verification: maxVerification(metadata.manifest.files.map((file) => file.verification)),
+      });
+      return;
+    }
+    if (toolName === 'WebFetch') {
+      let url: string | undefined;
+      try { url = safeUrl(JSON.parse(argsJson).url); } catch { /* invalid args are already represented by ok=false */ }
+      this.#entries.push({ ...base, kind: 'web', ...(url ? { urls: [url] } : {}) });
+      return;
+    }
+    this.#entries.push(base);
+  }
+
+  snapshot(): RunEvidenceLedger {
+    return {
+      toolCalls: this.#toolCalls,
+      failedToolCalls: this.#failedToolCalls,
+      entries: this.#entries.map((entry) => ({ ...entry })),
+    };
+  }
+}

package/src/harness/stallGuard.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Run-local deterministic guard. It never persists arguments or result text. */
+export class StallGuard {
+    #lastFailure = '';
+    #lastFailureCall = '';
+    #failureCount = 0;
+    #lastBatch = '';
+    #batchCount = 0;
+    shouldReject(call) {
+        return (this.#failureCount >= 2 &&
+            this.#lastFailureCall ===
+                hash(`${call.function.name}\0${call.function.arguments}`));
+    }
+    observe(calls, results, assistantText) {
+        for (let index = 0; index < calls.length; index += 1) {
+            const call = calls[index];
+            const result = results[index];
+            if (result.ok) {
+                this.#lastFailure = '';
+                this.#lastFailureCall = '';
+                this.#failureCount = 0;
+                continue;
+            }
+            const callSignature = hash(`${call.function.name}\0${call.function.arguments}`);
+            const signature = hash(`${callSignature}\0${result.error}`);
+            if (signature === this.#lastFailure)
+                this.#failureCount += 1;
+            else {
+                this.#lastFailure = signature;
+                this.#lastFailureCall = callSignature;
+                this.#failureCount = 1;
+            }
+            if (this.#failureCount >= 3) {
+                return {
+                    stalled: true,
+                    reason: 'repeated_failure',
+                    signature: signature.slice(0, 16),
+                };
+            }
+        }
+        const batch = hash(calls
+            .map((call, index) => {
+            const result = results[index];
+            return `${call.function.name}\0${call.function.arguments}\0${result.ok ? result.content : result.error}`;
+        })
+            .join('\x01'));
+        if (assistantText.trim().length === 0 && batch === this.#lastBatch)
+            this.#batchCount += 1;
+        else {
+            this.#lastBatch = batch;
+            this.#batchCount = assistantText.trim().length === 0 ? 1 : 0;
+        }
+        return this.#batchCount >= 3
+            ? { stalled: true, reason: 'no_progress', signature: batch.slice(0, 16) }
+            : { stalled: false };
+    }
+}

package/src/harness/stallGuard.ts

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import type { ToolCall, ToolResult } from '../types.js';
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export interface StallObservation {
+  stalled: boolean;
+  reason?: 'repeated_failure' | 'no_progress';
+  signature?: string;
+}
+
+/** Run-local deterministic guard. It never persists arguments or result text. */
+export class StallGuard {
+  #lastFailure = '';
+  #lastFailureCall = '';
+  #failureCount = 0;
+  #lastBatch = '';
+  #batchCount = 0;
+
+  shouldReject(call: ToolCall): boolean {
+    return (
+      this.#failureCount >= 2 &&
+      this.#lastFailureCall ===
+        hash(`${call.function.name}\0${call.function.arguments}`)
+    );
+  }
+
+  observe(
+    calls: readonly ToolCall[],
+    results: readonly ToolResult[],
+    assistantText: string,
+  ): StallObservation {
+    for (let index = 0; index < calls.length; index += 1) {
+      const call = calls[index]!;
+      const result = results[index]!;
+      if (result.ok) {
+        this.#lastFailure = '';
+        this.#lastFailureCall = '';
+        this.#failureCount = 0;
+        continue;
+      }
+      const callSignature = hash(
+        `${call.function.name}\0${call.function.arguments}`,
+      );
+      const signature = hash(`${callSignature}\0${result.error}`);
+      if (signature === this.#lastFailure) this.#failureCount += 1;
+      else {
+        this.#lastFailure = signature;
+        this.#lastFailureCall = callSignature;
+        this.#failureCount = 1;
+      }
+      if (this.#failureCount >= 3) {
+        return {
+          stalled: true,
+          reason: 'repeated_failure',
+          signature: signature.slice(0, 16),
+        };
+      }
+    }
+
+    const batch = hash(
+      calls
+        .map((call, index) => {
+          const result = results[index]!;
+          return `${call.function.name}\0${call.function.arguments}\0${result.ok ? result.content : result.error}`;
+        })
+        .join('\x01'),
+    );
+    if (assistantText.trim().length === 0 && batch === this.#lastBatch)
+      this.#batchCount += 1;
+    else {
+      this.#lastBatch = batch;
+      this.#batchCount = assistantText.trim().length === 0 ? 1 : 0;
+    }
+    return this.#batchCount >= 3
+      ? { stalled: true, reason: 'no_progress', signature: batch.slice(0, 16) }
+      : { stalled: false };
+  }
+}

package/src/humanIntervention.js

@@ -0,0 +1,129 @@
+import { randomUUID } from 'node:crypto';
+function interventionKey(identity) {
+    return `${identity.ownerId}\u0000${identity.conversationKey}\u0000${identity.runId}`;
+}
+function sameIdentity(pending, credential) {
+    return pending.id === credential.id
+        && pending.resumeToken === credential.resumeToken
+        && pending.ownerId === credential.ownerId
+        && pending.conversationKey === credential.conversationKey
+        && pending.runId === credential.runId;
+}
+/**
+ * Process-local coordination for sensitive handoffs. It deliberately stores no
+ * secret input: only a sanitized reason and the run identity cross this boundary.
+ */
+export class HumanInterventionCoordinator {
+    active = new Map();
+    byId = new Map();
+    listeners = new Set();
+    request(input) {
+        const key = interventionKey(input);
+        const current = this.active.get(key);
+        if (current)
+            return current.pending;
+        const requestedAt = Date.now();
+        const pending = {
+            ...input,
+            id: randomUUID(),
+            resumeToken: randomUUID(),
+            requestedAt,
+        };
+        const entry = { pending, waiters: new Set() };
+        if (pending.expiresAt !== undefined) {
+            const delay = Math.max(0, pending.expiresAt - requestedAt);
+            entry.expiryTimer = setTimeout(() => {
+                this.resolveEntry(entry, 'expired');
+            }, delay);
+            entry.expiryTimer.unref?.();
+        }
+        this.active.set(key, entry);
+        this.byId.set(pending.id, entry);
+        this.emit({ type: 'started', intervention: pending });
+        return pending;
+    }
+    get(identity) {
+        return this.active.get(interventionKey(identity))?.pending;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    wait(id, signal) {
+        const entry = this.byId.get(id);
+        if (!entry)
+            return Promise.reject(new Error('人工介入请求不存在或已结束'));
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const waiter = {
+                resolve: (resolution) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    waiter.cleanup();
+                    resolve(resolution);
+                },
+                reject: (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    waiter.cleanup();
+                    reject(error);
+                },
+                cleanup: () => signal?.removeEventListener('abort', onAbort),
+            };
+            const onAbort = () => {
+                entry.waiters.delete(waiter);
+                waiter.reject(new DOMException('aborted', 'AbortError'));
+            };
+            entry.waiters.add(waiter);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    resume(credential) {
+        return this.resolveCredential(credential, 'resumed');
+    }
+    cancel(credential) {
+        return this.resolveCredential(credential, 'cancelled');
+    }
+    abort(identity) {
+        const entry = this.active.get(interventionKey(identity));
+        if (!entry)
+            return false;
+        this.resolveEntry(entry, 'aborted');
+        return true;
+    }
+    resolveCredential(credential, status) {
+        const entry = this.byId.get(credential.id);
+        if (!entry || !sameIdentity(entry.pending, credential))
+            return false;
+        this.resolveEntry(entry, status);
+        return true;
+    }
+    resolveEntry(entry, status) {
+        const key = interventionKey(entry.pending);
+        if (this.active.get(key) !== entry || this.byId.get(entry.pending.id) !== entry)
+            return;
+        this.active.delete(key);
+        this.byId.delete(entry.pending.id);
+        if (entry.expiryTimer)
+            clearTimeout(entry.expiryTimer);
+        const resolvedAt = Date.now();
+        const resolution = {
+            status,
+            intervention: entry.pending,
+            resolvedAt,
+            waitedMs: Math.max(0, resolvedAt - entry.pending.requestedAt),
+        };
+        for (const waiter of [...entry.waiters])
+            waiter.resolve(resolution);
+        entry.waiters.clear();
+        this.emit({ type: 'resolved', resolution });
+    }
+    emit(event) {
+        for (const listener of this.listeners)
+            listener(event);
+    }
+}