@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/local-model-runtime.js

@@ -1,15 +1,24 @@
+import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { ROLE_ENUM } from "./shared.js";
 import { resolveWorkspaceRoot } from "./helpers.js";
 import { ALL_EXECUTION_ENGINES } from "./helpers/constants.js";
 import { executeAceInternalTool } from "./ace-internal-tools.js";
-import { ModelBridge } from "./model-bridge.js";
+import { isMutationIntent, ModelBridge, verifyCompletionArtifacts } from "./model-bridge.js";
+import { readBridgeTrace } from "./bridge-trace.js";
+import { reflectDeterministic } from "./experience-reflector.js";
+import { curate } from "./playbook-curator.js";
+import { PlaybookRepository } from "./store/repositories/playbook-repository.js";
+import { appendStatusEventSafe } from "./status-events.js";
 import { OllamaClient } from "./tui/ollama.js";
 import { OpenAICompatibleClient, diagnoseChatRuntimeConfig, } from "./tui/openai-compatible.js";
 import { discoverProviderContext } from "./tui/provider-discovery.js";
 import { defaultToolScopeForPolicy, defaultTurnsForPolicy, resolveLocalModelExecutionPolicy, } from "./local-model-policy.js";
 import { HermesSubprocessExecutor, } from "./hermes/session-manager.js";
 import { resolveHermesLaunchProfile, } from "./hermes/launch-profile.js";
+import { buildFilteredToolCatalog } from "./runtime-tool-specs.js";
+import { withLocalModelRuntimeRepository, } from "./store/repositories/local-model-runtime-repository.js";
+import { storeExistsSync } from "./store/store-snapshot.js";
 export function parseExecutionEngine(input) {
     if (!input)
         return undefined;
@@ -151,8 +160,40 @@ export async function runLocalModelTask(options) {
         requested_model_class: options.modelClass,
     });
     const maxTurns = options.maxTurns ?? defaultTurnsForPolicy(role, policy);
-    const toolScope = options.toolScope ?? defaultToolScopeForPolicy(role, policy);
+    const requestedToolScope = options.toolScope ?? defaultToolScopeForPolicy(role, policy);
+    const filteredToolCatalog = buildFilteredToolCatalog(policy.model_class, requestedToolScope, {
+        mutation_lane: policy.mutation_lane,
+    });
+    const filteredToolScope = filteredToolCatalog.entries.map((entry) => entry.name);
+    const toolScope = filteredToolScope.length > 0 ? filteredToolScope : requestedToolScope;
     if (runtime.executionEngine === "hermes_local") {
+        if (toolScope.length === 0) {
+            throw new Error("hermes_local requires a non-empty tool scope (reason_code=hermes_empty_tool_scope)");
+        }
+        const capabilitySnapshotId = randomUUID();
+        if (storeExistsSync(runtime.workspaceRoot)) {
+            await withLocalModelRuntimeRepository(runtime.workspaceRoot, async (repo) => {
+                await repo.saveCapabilitySnapshot({
+                    snapshot_id: capabilitySnapshotId,
+                    session_id: `hermes-local-${capabilitySnapshotId}`,
+                    turn_number: 1,
+                    captured_at: Date.now(),
+                    model_class: policy.model_class,
+                    allowed_tools: toolScope,
+                    unavailable_tools: filteredToolCatalog.unavailable_tools,
+                    tool_cost_class: filteredToolCatalog.tool_cost_class,
+                });
+                await repo.appendTransitionRecord({
+                    session_id: `hermes-local-${capabilitySnapshotId}`,
+                    subject_kind: "capability",
+                    subject_id: `hermes_local/${capabilitySnapshotId}`,
+                    from: "unscoped",
+                    to: `model_class:${policy.model_class}`,
+                    reason: "Capability snapshot captured for Hermes-local turn (surface_kind=hermes_local)",
+                    evidence_refs: [capabilitySnapshotId],
+                });
+            });
+        }
         const launchProfile = options.hermesLaunchProfile ?? resolveHermesLaunchProfile({ workspaceRoot: runtime.workspaceRoot });
         const hermesExecutor = options.hermesExecutor ??
             new HermesSubprocessExecutor({
@@ -165,6 +206,24 @@ export async function runLocalModelTask(options) {
             policy,
             toolScope,
             maxTurns,
+            timeoutMs: options.timeoutMs,
+        });
+        hermes.result = await verifyCompletionArtifacts(hermes.result, {
+            task: options.task,
+            role,
+            workspace: runtime.workspaceRoot,
+            touchedPaths: hermes.metadata.touched_paths ?? [],
+            expectedArtifacts: options.expectedArtifacts,
+            requiredEvidenceRefs: options.requiredEvidenceRefs,
+            forceCompletionVerification: (role === "coders" || role === "builder") &&
+                isMutationIntent(options.task),
+        });
+        await reflectRunIntoPlaybook({
+            workspaceRoot: runtime.workspaceRoot,
+            result: hermes.result,
+            role,
+            model: runtime.model,
+            modelClass: policy.model_class,
         });
         return {
             runtime,
@@ -183,8 +242,16 @@ export async function runLocalModelTask(options) {
         maxTurns,
         provider: runtime.provider,
         model: runtime.model,
+        modelClass: policy.model_class,
         toolScope,
     });
+    await reflectRunIntoPlaybook({
+        workspaceRoot: runtime.workspaceRoot,
+        result,
+        role,
+        model: runtime.model,
+        modelClass: policy.model_class,
+    });
     return {
         runtime,
         role,
@@ -193,5 +260,66 @@ export async function runLocalModelTask(options) {
         result,
     };
 }
+async function reflectRunIntoPlaybook(input) {
+    if (process.env.ACE_PLAYBOOK_REFLECT === "0" || process.env.ACE_PLAYBOOK_REFLECT === "false") {
+        return;
+    }
+    try {
+        const trace = readBridgeTrace(input.workspaceRoot, input.result.bridge_id);
+        const repo = new PlaybookRepository(input.workspaceRoot);
+        const ops = reflectDeterministic({
+            trace,
+            result: input.result,
+            role: input.role,
+            model: input.model,
+            modelClass: input.modelClass,
+        });
+        if (ops.length > 0) {
+            await curate(repo, ops);
+        }
+        const attributionOps = buildImplicitAttributionOps(repo, input.result);
+        if (attributionOps.length > 0) {
+            await curate(repo, attributionOps);
+        }
+    }
+    catch (error) {
+        await appendStatusEventSafe({
+            source_module: "capability-build",
+            event_type: "PLAYBOOK_REFLECT_FAILED",
+            status: "fail",
+            summary: `Playbook reflection failed: ${error instanceof Error ? error.message : String(error)}`,
+            payload: {
+                bridge_id: input.result.bridge_id,
+                role: input.role,
+                model_class: input.modelClass,
+            },
+        }).catch(() => undefined);
+    }
+}
+function buildImplicitAttributionOps(repo, result) {
+    const injected = result.injected_bullets ?? [];
+    if (injected.length === 0)
+        return [];
+    if ((result.used_bullets ?? []).length > 0) {
+        const injectedSet = new Set(injected);
+        return [...new Set(result.used_bullets ?? [])]
+            .filter((bullet_id) => injectedSet.has(bullet_id))
+            .map((bullet_id) => ({ type: "TAG", bullet_id, tag: "helpful" }));
+    }
+    const completedWithEvidence = result.status === "completed" &&
+        ((result.evidence_refs ?? []).length > 0 || (result.tool_calls ?? []).some((tool) => tool.ok));
+    if (completedWithEvidence) {
+        return injected.map((bullet_id) => ({ type: "TAG", bullet_id, tag: "helpful" }));
+    }
+    if (result.status === "blocked" && result.reason_code) {
+        return injected.flatMap((bullet_id) => {
+            const bullet = repo.getBullet(bullet_id);
+            return bullet?.scope.reason_code === result.reason_code
+                ? [{ type: "TAG", bullet_id, tag: "harmful" }]
+                : [];
+        });
+    }
+    return [];
+}
 export { resolveLocalModelExecutionPolicy, resolveLocalModelClass } from "./local-model-policy.js";
 //# sourceMappingURL=local-model-runtime.js.map

package/dist/measured-classing.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Measured model classing (E10 / D8).
+ *
+ * Name-regex classing misfires (gpt-oss→frontier, qwen2.5-coder→small). The
+ * question ACE actually cares about is "can this model hold the envelope
+ * contract?" — which is directly measurable with a one-shot canary probe at
+ * `ace connect`/`doctor`: ask for a fixed envelope and score compliance. This
+ * module compiles a {json_compliance, measured_ctx, param_count_b} measurement
+ * into a class, persists it per (provider, model), and lets the policy consult
+ * measurements first and the regex only as a fallback.
+ *
+ * The probe's model call is injected, so scoring/classing/persistence are all
+ * unit-testable without a live model.
+ */
+import type { RuntimeModelClass } from "./runtime-profile.js";
+/** Fixed canary: the smallest possible well-formed envelope request. */
+export declare const CANARY_PROMPT: string;
+export interface CapabilityMeasurement {
+    provider: string;
+    model: string;
+    /** 0..1 — how well the model emitted the requested envelope. */
+    json_compliance: number;
+    /** Measured/declared context window in tokens, if probed. */
+    measured_ctx?: number;
+    /** Parameter count in billions, if probed from provider metadata. */
+    param_count_b?: number;
+    measured_at: string;
+}
+/**
+ * Score a raw model output against the canary contract. Full credit for a
+ * clean parse of the exact envelope; partial credit for a JSON object with the
+ * right status field embedded in prose (the parser tolerates leading text);
+ * zero for no recoverable JSON.
+ */
+export declare function scoreCanaryCompliance(raw: string): number;
+/**
+ * Compile a measurement into a class. Compliance dominates: a model that cannot
+ * hold the envelope is `small_local` regardless of its parameter count (that is
+ * the whole point — measured behavior over metadata). Otherwise parameter count
+ * decides, with the context window as a tie-break toward `mid`.
+ */
+export declare function classFromMeasurement(m: Pick<CapabilityMeasurement, "json_compliance" | "measured_ctx" | "param_count_b">): RuntimeModelClass | undefined;
+export interface ProbeCanaryInput {
+    provider: string;
+    model: string;
+    /** Injected model call: returns the raw text the model produced for a prompt. */
+    call: (prompt: string) => Promise<string>;
+    measured_ctx?: number;
+    param_count_b?: number;
+}
+/** Run the canary probe and produce a measurement (does not persist). */
+export declare function probeModelCanary(input: ProbeCanaryInput): Promise<CapabilityMeasurement>;
+export declare function saveMeasurement(workspaceRoot: string, measurement: CapabilityMeasurement): void;
+export declare function getMeasurement(workspaceRoot: string, provider: string, model: string): CapabilityMeasurement | undefined;
+/**
+ * Class for a (provider, model), consulting a persisted measurement first and
+ * the name regex only as a fallback. This is the E10 entry point callers use
+ * instead of `resolveLocalModelClass` directly when a workspace is available.
+ */
+export declare function resolveClassMeasuredFirst(input: {
+    provider: string;
+    model: string;
+    workspaceRoot: string;
+    requested_model_class?: RuntimeModelClass;
+}): Promise<RuntimeModelClass>;
+//# sourceMappingURL=measured-classing.d.ts.map

package/dist/measured-classing.js

@@ -0,0 +1,165 @@
+/**
+ * Measured model classing (E10 / D8).
+ *
+ * Name-regex classing misfires (gpt-oss→frontier, qwen2.5-coder→small). The
+ * question ACE actually cares about is "can this model hold the envelope
+ * contract?" — which is directly measurable with a one-shot canary probe at
+ * `ace connect`/`doctor`: ask for a fixed envelope and score compliance. This
+ * module compiles a {json_compliance, measured_ctx, param_count_b} measurement
+ * into a class, persists it per (provider, model), and lets the policy consult
+ * measurements first and the regex only as a fallback.
+ *
+ * The probe's model call is injected, so scoring/classing/persistence are all
+ * unit-testable without a live model.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+/** Fixed canary: the smallest possible well-formed envelope request. */
+export const CANARY_PROMPT = 'Respond with exactly one JSON object and nothing else: ' +
+    '{"status":"message","thinking":"ok","message":"canary"}';
+/**
+ * Score a raw model output against the canary contract. Full credit for a
+ * clean parse of the exact envelope; partial credit for a JSON object with the
+ * right status field embedded in prose (the parser tolerates leading text);
+ * zero for no recoverable JSON.
+ */
+export function scoreCanaryCompliance(raw) {
+    const text = (raw ?? "").trim();
+    if (!text)
+        return 0;
+    // Exact-ish: the whole output is one JSON object with status:"message".
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && parsed.status === "message") {
+            return 1;
+        }
+        if (parsed && typeof parsed === "object" && typeof parsed.status === "string") {
+            return 0.75;
+        }
+    }
+    catch {
+        // fall through to brace-scan
+    }
+    // Tolerant: a JSON object is embedded in surrounding prose.
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+        try {
+            const parsed = JSON.parse(text.slice(start, end + 1));
+            if (parsed && typeof parsed === "object" && typeof parsed.status === "string") {
+                return 0.5;
+            }
+            return 0.3;
+        }
+        catch {
+            return 0.1;
+        }
+    }
+    return 0;
+}
+/**
+ * Compile a measurement into a class. Compliance dominates: a model that cannot
+ * hold the envelope is `small_local` regardless of its parameter count (that is
+ * the whole point — measured behavior over metadata). Otherwise parameter count
+ * decides, with the context window as a tie-break toward `mid`.
+ */
+export function classFromMeasurement(m) {
+    const compliance = clamp01(m.json_compliance);
+    // Below half-compliance the model cannot be trusted with the tool envelope.
+    if (compliance < 0.5)
+        return "small_local";
+    const params = m.param_count_b;
+    if (typeof params === "number" && Number.isFinite(params) && params > 0) {
+        if (params >= 30 && compliance >= 0.8)
+            return "frontier";
+        if (params >= 13)
+            return "frontier";
+        if (params >= 7)
+            return "mid";
+        return "small_local";
+    }
+    // No parameter metadata: fall back on compliance + context.
+    if (compliance >= 0.9 && (m.measured_ctx ?? 0) >= 32_768)
+        return "frontier";
+    if (compliance >= 0.75)
+        return "mid";
+    return "small_local";
+}
+/** Run the canary probe and produce a measurement (does not persist). */
+export async function probeModelCanary(input) {
+    let raw = "";
+    try {
+        raw = await input.call(CANARY_PROMPT);
+    }
+    catch {
+        raw = "";
+    }
+    return {
+        provider: input.provider,
+        model: input.model,
+        json_compliance: scoreCanaryCompliance(raw),
+        measured_ctx: input.measured_ctx,
+        param_count_b: input.param_count_b,
+        measured_at: new Date().toISOString(),
+    };
+}
+function measurementPath(workspaceRoot) {
+    return join(workspaceRoot, "agent-state", "model-measurements.json");
+}
+function measurementKey(provider, model) {
+    return `${provider.trim().toLowerCase()}::${model.trim().toLowerCase()}`;
+}
+function readMeasurementFile(workspaceRoot) {
+    const path = measurementPath(workspaceRoot);
+    if (!existsSync(path))
+        return { version: 1, updated_at: new Date().toISOString(), measurements: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version === 1 && Array.isArray(parsed.measurements))
+            return parsed;
+    }
+    catch {
+        // fall through to default
+    }
+    return { version: 1, updated_at: new Date().toISOString(), measurements: [] };
+}
+export function saveMeasurement(workspaceRoot, measurement) {
+    const dir = join(workspaceRoot, "agent-state");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const file = readMeasurementFile(workspaceRoot);
+    const key = measurementKey(measurement.provider, measurement.model);
+    const next = file.measurements.filter((m) => measurementKey(m.provider, m.model) !== key);
+    next.push(measurement);
+    const path = measurementPath(workspaceRoot);
+    const tmp = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ version: 1, updated_at: new Date().toISOString(), measurements: next }, null, 2));
+    renameSync(tmp, path);
+}
+export function getMeasurement(workspaceRoot, provider, model) {
+    const key = measurementKey(provider, model);
+    return readMeasurementFile(workspaceRoot).measurements.find((m) => measurementKey(m.provider, m.model) === key);
+}
+/**
+ * Class for a (provider, model), consulting a persisted measurement first and
+ * the name regex only as a fallback. This is the E10 entry point callers use
+ * instead of `resolveLocalModelClass` directly when a workspace is available.
+ */
+export async function resolveClassMeasuredFirst(input) {
+    const { resolveLocalModelClass } = await import("./local-model-policy.js");
+    const measurement = getMeasurement(input.workspaceRoot, input.provider, input.model);
+    const measured = measurement ? classFromMeasurement(measurement) : undefined;
+    return resolveLocalModelClass({
+        provider: input.provider,
+        model: input.model,
+        requested_model_class: input.requested_model_class,
+        measured_model_class: measured,
+    });
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+//# sourceMappingURL=measured-classing.js.map

package/dist/model-bridge.d.ts

@@ -10,6 +10,12 @@ export interface BridgeToolResult {
     ok: boolean;
     summary: string;
     isError: boolean;
+    /** Set when a tool fails for a classified reason (e.g. "tool_timeout"). */
+    reason_code?: string;
+}
+export interface BridgeUsageTotals {
+    prompt_tokens: number;
+    completion_tokens: number;
 }
 export interface BridgeProgressEvent {
     kind: "model_chunk" | "tool_start" | "tool_finish" | "process_post" | "output" | "thinking";
@@ -26,11 +32,16 @@ export interface BridgeResult {
     child_results: BridgeResult[];
     evidence_refs?: string[];
     reason_code?: string;
+    usage_totals?: BridgeUsageTotals;
+    injected_bullets?: string[];
+    used_bullets?: string[];
 }
 export interface ModelBridgeClients {
     ollama: Pick<OllamaClient, "chat" | "abort">;
     openai: Pick<OpenAICompatibleClient, "chat" | "abort">;
 }
+/** Keep completion-evidence policy identical across direct and Hermes execution. */
+export declare function isMutationIntent(task: string): boolean;
 export interface ModelBridgeRunOptions {
     task: string;
     role: string;
@@ -40,11 +51,13 @@ export interface ModelBridgeRunOptions {
     maxTurns: number;
     provider: string;
     model: string;
+    modelClass?: string;
     toolScope?: string[];
     expectedArtifacts?: {
         path: string;
         required?: boolean;
     }[];
+    requiredEvidenceRefs?: string[];
     parentBridge?: string;
     onToolCall?: (tool: string, args: Record<string, unknown>) => void;
     onToolResult?: (tool: string, result: BridgeToolResult) => void;
@@ -52,6 +65,38 @@ export interface ModelBridgeRunOptions {
     onThinking?: (text: string) => void;
     onProgress?: (event: BridgeProgressEvent) => void;
 }
+/**
+ * JSON Schema for the ACE response envelope. Passed as `format` (Ollama ≥ 0.5) or
+ * `response_format.json_schema` (OpenAI-compatible) to enable schema-constrained
+ * generation. Falls back to plain json-mode if the provider rejects it with a 400.
+ */
+export declare const ACE_ENVELOPE_JSON_SCHEMA: Record<string, unknown>;
+export declare function verifyCompletionArtifacts(result: BridgeResult, context: {
+    task: string;
+    role: string;
+    workspace: string;
+    touchedPaths: string[];
+    expectedArtifacts?: {
+        path: string;
+        required?: boolean;
+    }[];
+    requiredEvidenceRefs?: string[];
+    forceCompletionVerification?: boolean;
+}): Promise<BridgeResult>;
+/**
+ * Per-tool-call deadline (E12). A hung validation/test subprocess must never
+ * wedge a turn indefinitely — and under Promise.all one stuck call also holds
+ * every parallel sibling's feedback hostage. On timeout we resolve a classified
+ * `tool_timeout` failure that then feeds the WS-C doom-loop brake.
+ */
+export declare function executeToolWithDeadline(tool: string, args: Record<string, unknown>, sessionId: string, opts: {
+    workspace_path: string;
+}, deadlineMs: number, exec?: (tool: string, args: Record<string, unknown>, sessionId: string, opts: {
+    workspace_path: string;
+}) => Promise<unknown>): Promise<{
+    rawToolResult: unknown;
+    timedOut: boolean;
+}>;
 export declare class ModelBridge {
     private clients;
     private activeProviderClient;