@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/ace-server-instructions.js

@@ -57,6 +57,8 @@ const MUTATION_PREFIXES = [
     "update_",
     "write_",
 ];
+const DIGEST_CACHE_TTL_MS = 60_000;
+const digestCache = new Map();
 function readIfPresent(filePath) {
     if (!existsSync(filePath))
         return undefined;
@@ -188,6 +190,15 @@ export function buildAceDigest(workspaceRoot) {
     ].filter((value) => Boolean(value));
     return parts.length > 0 ? parts.join(" | ") : "ACE state detected; load recall_context for task and status.";
 }
+function buildAceDigestCached(workspaceRoot) {
+    const now = Date.now();
+    const cached = digestCache.get(workspaceRoot);
+    if (cached && cached.expiresAt > now)
+        return cached.value;
+    const value = buildAceDigest(workspaceRoot);
+    digestCache.set(workspaceRoot, { value, expiresAt: now + DIGEST_CACHE_TTL_MS });
+    return value;
+}
 export function buildServerInstructions(workspaceRoot) {
     const coreFiles = listExistingCoreFiles(workspaceRoot);
     const stateDirs = listExistingStateDirs(workspaceRoot);
@@ -224,13 +235,14 @@ export function buildHostInstructionText(host, workspaceRoot) {
         "Full instructions, skills, task packs, and runtime state live in ACE artifacts and should be accessed through the ACE MCP server.",
         "",
         "Session start protocol:",
-        "1. Call `recall_context` to load task, scope, and status from ACE state.",
+        "1. Call `recall_context` to load task, scope, and status through the ACE MCP server.",
         "2. Call `route_task` and `get_agent_instructions` before choosing a role.",
         "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
+        "4. Read/write task state through MCP tools (`recall_context`, `read_workspace_file`, `write_workspace_file`, lifecycle append tools); do not create files under `agent-state/` directly.",
         "",
         "Ground truth:",
-        "- `agent-state/*` is the visible runtime state surface for this workspace.",
-        "- `agent-state/ace-state.ace` is the canonical store path; legacy nested store layouts are compatibility fallback only.",
+        "- ACE MCP tools are the authoritative interface for task state and lifecycle updates.",
+        "- `agent-state/ace-state.ace` is the canonical store path; visible `agent-state/*` files are compatibility projections or sweep inputs.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
         "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
         "",
@@ -241,26 +253,26 @@ export function buildBootstrapNudge(workspaceRoot) {
     const coreFiles = listExistingCoreFiles(workspaceRoot);
     return [
         "ACE bootstrap hint: call `recall_context` before significant work so task and scope come from file-backed state.",
-        `ACE digest: ${buildAceDigest(workspaceRoot)}.`,
+        `ACE digest: ${buildAceDigestCached(workspaceRoot)}.`,
         coreFiles.length > 0 ? `Current core files: ${coreFiles.join(", ")}.` : undefined,
     ]
         .filter((value) => Boolean(value))
         .join(" ");
 }
 export function buildBootstrapGuidance(workspaceRoot, toolName) {
-    return `ACE context loaded via \`${toolName}\`. Current digest: ${buildAceDigest(workspaceRoot)}.`;
+    return `ACE context loaded via \`${toolName}\`. Current digest: ${buildAceDigestCached(workspaceRoot)}.`;
 }
 export function buildMutationGuidance(workspaceRoot, toolName) {
     const evidencePath = displayWorkspacePath(workspaceRoot, "agent-state/EVIDENCE_LOG.md");
     return [
-        `ACE digest after \`${toolName}\`: ${buildAceDigest(workspaceRoot)}.`,
+        `ACE digest after \`${toolName}\`: ${buildAceDigestCached(workspaceRoot)}.`,
         `If this changed code or state, reconcile \`${evidencePath}\`, run \`execute_gates\` when appropriate, and use structured handoffs/process posts for delegated follow-up.`,
     ].join(" ");
 }
 export function buildRefreshGuidance(workspaceRoot, toolName) {
     return [
         `ACE snapshot refresh completed via \`${toolName}\`.`,
-        `Current digest: ${buildAceDigest(workspaceRoot)}.`,
+        `Current digest: ${buildAceDigestCached(workspaceRoot)}.`,
     ].join(" ");
 }
 function isBootstrapTool(toolName) {
@@ -298,6 +310,8 @@ function isCallToolResult(value) {
 }
 export function installAceToolGovernance(server, workspaceRoot) {
     const bootstrappedSessions = new Set();
+    const bootstrapNudgeCounts = new Map();
+    const mutationGuidanceState = new Map();
     const wrapToolCallback = (toolName, callback) => async (...args) => {
         const extra = args.at(-1);
         const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
@@ -311,7 +325,11 @@ export function installAceToolGovernance(server, workspaceRoot) {
         }
         let next = rawResult;
         if (sessionId && !bootstrappedSessions.has(sessionId) && !isBootstrapTool(toolName)) {
-            next = appendTextContent(next, buildBootstrapNudge(workspaceRoot));
+            const callCount = (bootstrapNudgeCounts.get(sessionId) ?? 0) + 1;
+            bootstrapNudgeCounts.set(sessionId, callCount);
+            if (callCount === 1 || callCount % 10 === 0) {
+                next = appendTextContent(next, buildBootstrapNudge(workspaceRoot));
+            }
         }
         if (isBootstrapTool(toolName)) {
             next = appendTextContent(next, buildBootstrapGuidance(workspaceRoot, toolName));
@@ -320,7 +338,16 @@ export function installAceToolGovernance(server, workspaceRoot) {
             next = appendTextContent(next, buildRefreshGuidance(workspaceRoot, toolName));
         }
         else if (isMutationTool(toolName)) {
-            next = appendTextContent(next, buildMutationGuidance(workspaceRoot, toolName));
+            const mutationKey = sessionId ?? "__global__";
+            const currentDigest = buildAceDigestCached(workspaceRoot);
+            const state = mutationGuidanceState.get(mutationKey) ?? { count: 0 };
+            state.count += 1;
+            const shouldAppend = state.lastDigest === undefined || state.lastDigest !== currentDigest || state.count % 10 === 0;
+            state.lastDigest = currentDigest;
+            mutationGuidanceState.set(mutationKey, state);
+            if (shouldAppend) {
+                next = appendTextContent(next, buildMutationGuidance(workspaceRoot, toolName));
+            }
         }
         return next;
     };

package/dist/astgrep-index.d.ts

@@ -10,11 +10,17 @@ interface AstGrepMatch {
             line?: number;
             column?: number;
         };
+        byteOffset?: {
+            start?: number;
+            end?: number;
+        };
     };
-    metaVariables?: Record<string, unknown>;
+    metaVariables?: unknown;
     kind?: string;
     nodeKind?: string;
+    replacement?: string;
 }
+export declare function flattenMetaVariables(raw: unknown): Record<string, string>;
 export interface AstgrepMatch {
     file: string;
     line: number;

package/dist/astgrep-index.js

@@ -4,6 +4,57 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { appendStatusEventSafe } from "./status-events.js";
 import { safeRead, safeWrite, WORKSPACE_ROOT, wsPath } from "./helpers.js";
+function textFromMetaValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object") {
+        const text = value.text;
+        if (typeof text === "string")
+            return text;
+    }
+    return undefined;
+}
+const META_SINGLE_BUCKETS = ["single", "transformed"];
+const META_MULTI_BUCKETS = ["multi"];
+export function flattenMetaVariables(raw) {
+    const out = {};
+    if (!raw || typeof raw !== "object")
+        return out;
+    const root = raw;
+    for (const bucketKey of META_SINGLE_BUCKETS) {
+        const bucket = root[bucketKey];
+        if (bucket && typeof bucket === "object") {
+            for (const [name, value] of Object.entries(bucket)) {
+                const text = textFromMetaValue(value);
+                if (typeof text === "string" && text.length > 0)
+                    out[name] = text;
+            }
+        }
+    }
+    for (const bucketKey of META_MULTI_BUCKETS) {
+        const bucket = root[bucketKey];
+        if (bucket && typeof bucket === "object") {
+            for (const [name, value] of Object.entries(bucket)) {
+                if (!Array.isArray(value))
+                    continue;
+                const texts = value
+                    .map(textFromMetaValue)
+                    .filter((text) => typeof text === "string" && text.length > 0);
+                if (texts.length > 0)
+                    out[name] = texts.join("");
+            }
+        }
+    }
+    const reserved = new Set([...META_SINGLE_BUCKETS, ...META_MULTI_BUCKETS]);
+    for (const [name, value] of Object.entries(root)) {
+        if (reserved.has(name) || out[name] !== undefined)
+            continue;
+        const text = textFromMetaValue(value);
+        if (typeof text === "string" && text.length > 0)
+            out[name] = text;
+    }
+    return out;
+}
 export function runAstgrepQuery(pattern, lang, roots, _contextLines) {
     const cmd = detectAstgrepCommand();
     const raw = runAstgrep(cmd, pattern, lang, roots);
@@ -32,15 +83,8 @@ function nodeKindForMatch(match) {
     return undefined;
 }
 function captureMapForMatch(match) {
-    if (!match.metaVariables)
-        return undefined;
-    const captures = Object.entries(match.metaVariables).reduce((acc, [key]) => {
-        const text = extractMetaVarText(match, key);
-        if (typeof text === "string" && text.length > 0)
-            acc[key] = text;
-        return acc;
-    }, {});
-    return Object.keys(captures).length > 0 ? captures : undefined;
+    const flat = flattenMetaVariables(match.metaVariables);
+    return Object.keys(flat).length > 0 ? flat : undefined;
 }
 function computeMatchId(input) {
     const encoded = [
@@ -59,12 +103,8 @@ function computeMatchId(input) {
 function matchUsesSymbolHint(match, symbolHint) {
     if ((match.text ?? "").includes(symbolHint))
         return true;
-    if (!match.metaVariables)
-        return false;
-    return Object.keys(match.metaVariables).some((key) => {
-        const text = extractMetaVarText(match, key);
-        return typeof text === "string" && text.includes(symbolHint);
-    });
+    const flat = flattenMetaVariables(match.metaVariables);
+    return Object.values(flat).some((text) => text.includes(symbolHint));
 }
 export function locateAstgrepMatches(input) {
     const scope = resolveScope(input.scope ?? "src");
@@ -109,6 +149,14 @@ export function locateAstgrepMatches(input) {
                 line: match.range.end?.line ?? 0,
                 column: match.range.end?.column ?? 0,
             },
+            ...(match.range.byteOffset
+                ? {
+                    byteOffset: {
+                        start: match.range.byteOffset.start ?? 0,
+                        end: match.range.byteOffset.end ?? 0,
+                    },
+                }
+                : {}),
         };
         return [{
                 match_id: computeMatchId({
@@ -270,27 +318,6 @@ function runAstgrep(astgrepCmd, pattern, lang, paths) {
         return [];
     return parseAstgrepOutput(res.stdout);
 }
-function extractMetaVarText(match, key) {
-    const raw = match.metaVariables?.[key];
-    if (!raw)
-        return undefined;
-    if (typeof raw === "string")
-        return raw;
-    if (raw && typeof raw === "object" && "text" in raw && typeof raw.text === "string") {
-        return raw.text;
-    }
-    if (Array.isArray(raw)) {
-        const first = raw[0];
-        if (typeof first === "string")
-            return first;
-        if (first && typeof first === "object" && "text" in first) {
-            const text = first.text;
-            if (typeof text === "string")
-                return text;
-        }
-    }
-    return undefined;
-}
 function uniqueSorted(values, limit) {
     return [...new Set(values.filter(Boolean))].sort((a, b) => a.localeCompare(b)).slice(0, limit);
 }
@@ -357,13 +384,13 @@ export async function refreshAstgrepIndex(input = {}) {
     const pyTestMatches = runAstgrep(astgrepCmd, "def test_$NAME($$$ARGS):", "python", pyRoots);
     const handoffRefMatches = runAstgrep(astgrepCmd, '$X(\"SWARM_HANDOFF.$Y\")', "ts", tsRoots);
     const exportedFunctions = uniqueSorted(exportedFnMatches
-        .map((m) => extractMetaVarText(m, "NAME"))
+        .map((m) => flattenMetaVariables(m.metaVariables).NAME)
         .filter((v) => Boolean(v)), 40);
     const exportedClasses = uniqueSorted(exportedClassMatches
-        .map((m) => extractMetaVarText(m, "NAME"))
+        .map((m) => flattenMetaVariables(m.metaVariables).NAME)
         .filter((v) => Boolean(v)), 30);
     const asyncFunctions = uniqueSorted(asyncFnMatches
-        .map((m) => extractMetaVarText(m, "NAME"))
+        .map((m) => flattenMetaVariables(m.metaVariables).NAME)
         .filter((v) => Boolean(v)), 40);
     // Fallback symbol extraction when AST match shapes differ across language versions.
     const tsFiles = codeFiles.filter((file) => /\.(ts|tsx|js)$/i.test(file));

package/dist/bridge-trace.d.ts

@@ -0,0 +1,17 @@
+import type { BridgeUsageTotals } from "./model-bridge.js";
+export interface BridgeTraceLine {
+    turn: number;
+    envelope_status: string;
+    parse_repairs: number;
+    drift_repairs: number;
+    tool_calls: Array<{
+        tool: string;
+        ok: boolean;
+        reason_code?: string;
+    }>;
+    usage?: BridgeUsageTotals;
+    compressed?: boolean;
+}
+export declare function bridgeTracePath(workspaceRoot: string, runId: string): string;
+export declare function readBridgeTrace(workspaceRoot: string, runId: string): BridgeTraceLine[];
+//# sourceMappingURL=bridge-trace.d.ts.map

package/dist/bridge-trace.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export function bridgeTracePath(workspaceRoot, runId) {
+    const safeRunId = runId.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    return resolve(workspaceRoot, "agent-state", "bridge-traces", `${safeRunId}.ndjson`);
+}
+export function readBridgeTrace(workspaceRoot, runId) {
+    const path = bridgeTracePath(workspaceRoot, runId);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+//# sourceMappingURL=bridge-trace.js.map

package/dist/cli.d.ts

@@ -1,3 +1,11 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Positional arguments, with value-taking flags and their values removed.
+ * A bare `.filter(a => !a.startsWith("--"))` drops the flag but keeps its value,
+ * which silently folds `--budget-hours 2` into a goal objective. Supports both
+ * `--flag value` and `--flag=value`, plus `--` as an end-of-flags separator.
+ */
+export declare function positionalArgs(args: readonly string[], valueFlags: ReadonlySet<string>): string[];
+export declare const GOAL_VALUE_FLAGS: ReadonlySet<string>;
+export declare const PLAYBOOK_ADD_VALUE_FLAGS: ReadonlySet<string>;
 //# sourceMappingURL=cli.d.ts.map