@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/runtime-profile.d.ts

@@ -8,6 +8,31 @@ export declare const DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH = "agent-state/runti
 export declare const DEFAULT_EXECUTOR_MAX_TURNS = 6;
 export declare const DEFAULT_EXECUTOR_TURN_TIMEOUT_MS = 300000;
 export declare const DEFAULT_VERICIFY_BRIDGE_REL_PATH = "agent-state/vericify/ace-bridge.json";
+export type RuntimeModelClass = "frontier" | "mid" | "small_local";
+export declare const DEFAULT_STALL_WINDOW_MS = 300000;
+export declare const DEFAULT_TURN_BUDGET_MS = 1800000;
+export declare const DEFAULT_MAX_STALL_RESTARTS = 3;
+export declare const DEFAULT_INITIAL_BACKOFF_MS = 5000;
+export declare const DEFAULT_MAX_RETRY_BACKOFF_MS = 300000;
+export interface ModelClassLivenessDefaults {
+    turn_budget_ms: number;
+    stall_window_ms: number;
+    max_stall_restarts: number;
+    initial_backoff_ms: number;
+    max_retry_backoff_ms: number;
+}
+export interface SurgicalReadBudgets {
+    small_local: number;
+    mid: number;
+    frontier: number | null;
+}
+export interface ResolvedSurgicalReadBudget {
+    model_class: RuntimeModelClass;
+    read_file_lines_max_lines: number | null;
+}
+export declare const DEFAULT_SURGICAL_READ_BUDGETS: SurgicalReadBudgets;
+export declare function getLivenessDefaults(modelClass?: RuntimeModelClass): ModelClassLivenessDefaults;
+export declare function resolveEffectiveSurgicalReadBudget(profile: RuntimeProfile | undefined, modelClass?: RuntimeModelClass): ResolvedSurgicalReadBudget;
 export declare const DEFAULT_VERICIFY_PROCESS_POST_LOG_REL_PATH = "agent-state/vericify/process-posts.json";
 declare const runtimeProfileSchema: z.ZodObject<{
     ace_runtime_version: z.ZodLiteral<"1.0.0">;
@@ -41,6 +66,11 @@ declare const runtimeProfileSchema: z.ZodObject<{
     }, z.core.$strict>;
     tools: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         registry_path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        surgical_read_budgets: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+            small_local: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            mid: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            frontier: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>>;
     autonomy: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         orchestrator_preflight: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -110,7 +140,9 @@ export declare function readRuntimeProfile(): RuntimeProfile;
 export declare function readRuntimePromptTemplate(): string;
 export declare function readRuntimeProfileState(): RuntimeProfileSnapshot;
 export declare function renderRuntimePrompt(templateContext: Record<string, unknown>): string;
+export declare function renderRuntimePromptFromSnapshot(snapshot: RuntimeProfileSnapshot, templateContext: Record<string, unknown>): string;
 export declare function getRuntimeProfilePath(): string;
 export declare function getRuntimeProfileSchemaPath(): string;
+export declare function getSurgicalReadBudget(modelClass: "frontier" | "mid" | "small_local" | undefined, profile?: RuntimeProfile): number | null;
 export {};
 //# sourceMappingURL=runtime-profile.d.ts.map

package/dist/runtime-profile.js

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 import { z } from "zod";
 import { DEFAULTS_ROOT, resolveWorkspaceArtifactPath, resolveWorkspaceRoot, } from "./helpers.js";
 import { getStoreStatSync, getWorkspaceStorePath, parseVirtualStorePath, readStoreBlobSync, readStoreBlobByPathSync, toVirtualStorePath, } from "./store/store-snapshot.js";
-import { appendStatusEvent } from "./status-events.js";
+import { appendStatusEventSafe } from "./status-events.js";
 import { DEFAULT_AUTONOMY_POLICY, DEFAULT_CONTINUITY_POLICY, } from "./ace-autonomy.js";
 export const RUNTIME_PROFILE_REL_PATH = "agent-state/ACE_WORKFLOW.md";
 export const RUNTIME_PROFILE_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json";
@@ -13,6 +13,57 @@ export const DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH = "agent-state/runtime-tool-
 export const DEFAULT_EXECUTOR_MAX_TURNS = 6;
 export const DEFAULT_EXECUTOR_TURN_TIMEOUT_MS = 300_000;
 export const DEFAULT_VERICIFY_BRIDGE_REL_PATH = "agent-state/vericify/ace-bridge.json";
+// Liveness defaults per model class
+export const DEFAULT_STALL_WINDOW_MS = 300_000; // 5 min — inter-progress cap
+export const DEFAULT_TURN_BUDGET_MS = 1_800_000; // 30 min — per-turn soft cap
+export const DEFAULT_MAX_STALL_RESTARTS = 3;
+export const DEFAULT_INITIAL_BACKOFF_MS = 5_000;
+export const DEFAULT_MAX_RETRY_BACKOFF_MS = 300_000;
+export const DEFAULT_SURGICAL_READ_BUDGETS = {
+    small_local: 200,
+    mid: 800,
+    frontier: null,
+};
+export function getLivenessDefaults(modelClass) {
+    switch (modelClass) {
+        case "small_local":
+            return {
+                turn_budget_ms: 3_600_000, // 60 min — slow models need generous cap
+                stall_window_ms: 180_000, // 3 min stall window
+                max_stall_restarts: 3,
+                initial_backoff_ms: 10_000,
+                max_retry_backoff_ms: 300_000,
+            };
+        case "mid":
+            return {
+                turn_budget_ms: 1_800_000, // 30 min
+                stall_window_ms: 300_000, // 5 min
+                max_stall_restarts: 3,
+                initial_backoff_ms: 5_000,
+                max_retry_backoff_ms: 180_000,
+            };
+        case "frontier":
+        default:
+            return {
+                turn_budget_ms: DEFAULT_TURN_BUDGET_MS,
+                stall_window_ms: DEFAULT_STALL_WINDOW_MS,
+                max_stall_restarts: DEFAULT_MAX_STALL_RESTARTS,
+                initial_backoff_ms: DEFAULT_INITIAL_BACKOFF_MS,
+                max_retry_backoff_ms: DEFAULT_MAX_RETRY_BACKOFF_MS,
+            };
+    }
+}
+function resolveSurgicalReadBudgetValue(budgets, modelClass) {
+    const resolved = budgets ?? DEFAULT_SURGICAL_READ_BUDGETS;
+    return resolved[modelClass] ?? null;
+}
+export function resolveEffectiveSurgicalReadBudget(profile, modelClass) {
+    const effectiveModelClass = modelClass ?? "frontier";
+    return {
+        model_class: effectiveModelClass,
+        read_file_lines_max_lines: resolveSurgicalReadBudgetValue(profile?.tools?.surgical_read_budgets, effectiveModelClass),
+    };
+}
 export const DEFAULT_VERICIFY_PROCESS_POST_LOG_REL_PATH = "agent-state/vericify/process-posts.json";
 const DEFAULT_RUNTIME_PROFILE_PATH = resolve(DEFAULTS_ROOT, RUNTIME_PROFILE_REL_PATH);
 const DEFAULT_RUNTIME_PROFILE_SCHEMA_PATH = resolve(DEFAULTS_ROOT, RUNTIME_PROFILE_SCHEMA_REL_PATH);
@@ -63,10 +114,22 @@ const runtimeProfileSchema = z
             .min(1)
             .optional()
             .default(DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH),
+        surgical_read_budgets: z
+            .object({
+            small_local: z.number().int().positive().optional().default(DEFAULT_SURGICAL_READ_BUDGETS.small_local),
+            mid: z.number().int().positive().optional().default(DEFAULT_SURGICAL_READ_BUDGETS.mid),
+            frontier: z.number().int().positive().nullable().optional().default(DEFAULT_SURGICAL_READ_BUDGETS.frontier),
+        })
+            .strict()
+            .optional()
+            .default(DEFAULT_SURGICAL_READ_BUDGETS),
     })
         .strict()
         .optional()
-        .default({ registry_path: DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH }),
+        .default({
+        registry_path: DEFAULT_RUNTIME_TOOL_REGISTRY_REL_PATH,
+        surgical_read_budgets: DEFAULT_SURGICAL_READ_BUDGETS,
+    }),
     autonomy: z
         .object({
         orchestrator_preflight: z.boolean().optional().default(true),
@@ -336,7 +399,7 @@ function parseRuntimeProfileContent(raw) {
 }
 function emitRuntimeProfileEvent(eventType, input) {
     try {
-        appendStatusEvent({
+        void appendStatusEventSafe({
             source_module: "capability-framework",
             event_type: eventType,
             status: eventType === "RUNTIME_PROFILE_INVALID" ? "fail" : "pass",
@@ -349,6 +412,8 @@ function emitRuntimeProfileEvent(eventType, input) {
                 signature: input.signature,
                 errors: input.errors,
             },
+        }).catch(() => {
+            // Runtime profile reads must not fail due to observability side effects.
         });
     }
     catch {
@@ -357,13 +422,16 @@ function emitRuntimeProfileEvent(eventType, input) {
 }
 function ensureLastGoodSnapshot() {
     const current = loadRuntimeProfile();
-    if (current.ok && lastGoodSnapshot)
-        return lastGoodSnapshot;
-    if (lastGoodSnapshot)
+    if (current.ok)
+        return current;
+    if (lastGoodSnapshot &&
+        lastGoodSnapshot.path === current.path &&
+        lastGoodSnapshot.source === current.source) {
         return lastGoodSnapshot;
+    }
     const packaged = loadRuntimeProfile(DEFAULT_RUNTIME_PROFILE_PATH);
-    if (packaged.ok && lastGoodSnapshot)
-        return lastGoodSnapshot;
+    if (packaged.ok)
+        return packaged;
     throw new Error(`Packaged ACE runtime profile is invalid: ${(packaged.ok ? [] : packaged.errors).join("; ")}`);
 }
 function resolveTemplatePath(context, path) {
@@ -511,14 +579,17 @@ export function readRuntimeProfileState() {
 }
 export function renderRuntimePrompt(templateContext) {
     const active = ensureLastGoodSnapshot();
+    return renderRuntimePromptFromSnapshot(active, templateContext);
+}
+export function renderRuntimePromptFromSnapshot(snapshot, templateContext) {
     const renderContext = {
-        ...active.profile,
-        runtime_profile_path: active.path,
-        runtime_profile_source: active.source,
-        prompt_template: active.prompt_template,
+        ...snapshot.profile,
+        runtime_profile_path: snapshot.path,
+        runtime_profile_source: snapshot.source,
+        prompt_template: snapshot.prompt_template,
         ...templateContext,
     };
-    return active.prompt_template.replace(/{{\s*([A-Za-z0-9_.-]+)\s*}}/g, (match, token) => {
+    return snapshot.prompt_template.replace(/{{\s*([A-Za-z0-9_.-]+)\s*}}/g, (match, token) => {
         const value = resolveTemplatePath(renderContext, token);
         return value === undefined ? match : stringifyTemplateValue(value);
     });
@@ -529,4 +600,9 @@ export function getRuntimeProfilePath() {
 export function getRuntimeProfileSchemaPath() {
     return DEFAULT_RUNTIME_PROFILE_SCHEMA_PATH;
 }
+export function getSurgicalReadBudget(modelClass, profile) {
+    const effectiveProfile = profile ?? readRuntimeProfile();
+    const budgets = effectiveProfile.tools?.surgical_read_budgets ?? DEFAULT_SURGICAL_READ_BUDGETS;
+    return budgets[modelClass ?? "frontier"] ?? null;
+}
 //# sourceMappingURL=runtime-profile.js.map

package/dist/runtime-tool-specs.d.ts

@@ -1,4 +1,6 @@
+import type { ToolCostClass } from "./store/repositories/local-model-runtime-repository.js";
 import { type ArtifactSource } from "./helpers.js";
+import { type RuntimeModelClass } from "./runtime-profile.js";
 import { type ValidationResult } from "./schemas.js";
 export declare const RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH = "agent-state/runtime-tool-specs.json";
 export declare const RUNTIME_TOOL_SPEC_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json";
@@ -20,6 +22,14 @@ export interface RuntimeToolExecutorConfig {
     timeout_ms?: number;
     env?: Record<string, string>;
 }
+export interface RuntimeToolMcpServerConfig {
+    transport: "stdio" | "http";
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+    tool_allowlist?: string[];
+}
 export interface RuntimeToolSpec {
     name: string;
     description: string;
@@ -27,6 +37,7 @@ export interface RuntimeToolSpec {
     success_schema?: RuntimeToolSchema;
     failure_schema?: RuntimeToolSchema;
     executor: RuntimeToolExecutorConfig;
+    mcp_server?: RuntimeToolMcpServerConfig;
 }
 export interface RuntimeToolSpecRegistry {
     version: 1;
@@ -58,11 +69,39 @@ export interface RuntimeToolExecutionResult {
     error?: unknown;
     validation_errors?: string[];
 }
+export declare function buildRuntimeToolEnvironment(input: {
+    base_env?: NodeJS.ProcessEnv;
+    spec_env?: Record<string, string>;
+    injected_env: Record<string, string>;
+}): NodeJS.ProcessEnv;
+export declare function persistRuntimeToolInvocationArtifacts(callId: string, requestContent: string, responseContent: string): Promise<{
+    requestPath: string;
+    responsePath: string;
+}>;
 export declare function validateRuntimeToolRegistryContent(raw: string): ValidationResult;
 export declare function loadRuntimeToolRegistry(explicitPath?: string): RuntimeToolSpecRegistryResult;
 export declare function readRuntimeToolRegistry(): RuntimeToolSpecRegistry;
 export declare function listRuntimeToolSpecs(): RuntimeToolSpec[];
 export declare function getRuntimeToolRegistryPath(): string;
 export declare function executeRuntimeTool(name: string, input: unknown, context?: RuntimeToolExecutionContext): Promise<RuntimeToolExecutionResult>;
+export type ModelClass = RuntimeModelClass;
+export declare const SMALL_LOCAL_PRIORITY_TOOL_NAMES: readonly ["outline_file", "astgrep_query", "astgrep_locate", "read_file_lines", "compile_structural_edit", "preview_structural_edit", "list_workspace", "recall_context", "validate_framework", "run_orchestrator"];
+export interface FilteredToolCatalogEntry {
+    name: string;
+    description: string;
+    input_schema: RuntimeToolSchema;
+    cost_class: ToolCostClass;
+}
+export interface FilteredToolCatalog {
+    entries: FilteredToolCatalogEntry[];
+    model_class: ModelClass;
+    unavailable_tools: {
+        name: string;
+        reason: string;
+        reason_code: string;
+    }[];
+    tool_cost_class: Record<string, ToolCostClass>;
+}
+export declare function buildFilteredToolCatalog(modelClass: ModelClass | undefined, allowedTools?: string[]): FilteredToolCatalog;
 export {};
 //# sourceMappingURL=runtime-tool-specs.d.ts.map

package/dist/runtime-tool-specs.js

@@ -12,7 +12,8 @@ import { appendStatusEventSafe } from "./status-events.js";
 import { openStore } from "./store/ace-packed-store.js";
 import { getWorkspaceStorePath, readStoreBlobSync, storeExistsSync, toVirtualStorePath, } from "./store/store-snapshot.js";
 import { operationalArtifactKey, } from "./store/store-artifacts.js";
-import { withStoreWriteQueue } from "./store/write-queue.js";
+import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
+import { parseJsonLikeText } from "./json-sanitizer.js";
 export const RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH = "agent-state/runtime-tool-specs.json";
 export const RUNTIME_TOOL_SPEC_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json";
 export const RUNTIME_TOOL_SPEC_SCHEMA_NAME = "runtime-tool-spec-registry@1.0.0";
@@ -96,13 +97,46 @@ function buildTempToolPaths(callId) {
         responsePath: join(tempDir, "response.json"),
     };
 }
+const SAFE_RUNTIME_ENV_KEYS = new Set([
+    "PATH",
+    "HOME",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "USER",
+    "LANG",
+    "LC_ALL",
+    "SHELL",
+    "NODE_PATH",
+]);
+function isSecretEnvKey(key) {
+    return /(SECRET|TOKEN|KEY|PASSWORD|PASS|CREDENTIAL|AUTH|COOKIE|SESSION)/i.test(key);
+}
+export function buildRuntimeToolEnvironment(input) {
+    const base = input.base_env ?? process.env;
+    const env = {};
+    for (const key of SAFE_RUNTIME_ENV_KEYS) {
+        const value = base[key];
+        if (typeof value === "string")
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(input.spec_env ?? {})) {
+        if (isSecretEnvKey(key))
+            continue;
+        env[key] = value;
+    }
+    for (const [key, value] of Object.entries(input.injected_env)) {
+        env[key] = value;
+    }
+    return env;
+}
 function runtimeToolArtifactKey(callId, kind) {
     return `state/runtime/tools/invocations/${callId}/${kind}.json`;
 }
 function runtimeToolArtifactVirtualPath(callId, kind) {
     return toVirtualStorePath(getWorkspaceStorePath(resolveWorkspaceRoot()), runtimeToolArtifactKey(callId, kind));
 }
-async function persistToolInvocationArtifacts(callId, requestContent, responseContent) {
+export async function persistRuntimeToolInvocationArtifacts(callId, requestContent, responseContent) {
     const workspaceRoot = resolveWorkspaceRoot();
     if (!storeExistsSync(workspaceRoot)) {
         const requestPath = resolveWorkspaceArtifactPath(`.ace-runtime/tools/${callId}.request.json`);
@@ -113,7 +147,7 @@ async function persistToolInvocationArtifacts(callId, requestContent, responseCo
         return { requestPath, responsePath };
     }
     const storePath = getWorkspaceStorePath(workspaceRoot);
-    await withStoreWriteQueue(storePath, async () => {
+    await withStoreWriteCoordinator(storePath, async () => {
         const store = await openStore(storePath);
         try {
             await store.setBlob(runtimeToolArtifactKey(callId, "request"), requestContent);
@@ -123,25 +157,25 @@ async function persistToolInvocationArtifacts(callId, requestContent, responseCo
         finally {
             await store.close();
         }
-    });
+    }, { operation_label: "persistToolInvocationArtifacts" });
     return {
         requestPath: runtimeToolArtifactVirtualPath(callId, "request"),
         responsePath: runtimeToolArtifactVirtualPath(callId, "response"),
     };
 }
 function parseRuntimeToolRegistry(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
+    const parsed = parseJsonLikeText(raw);
+    if (!parsed.ok) {
+        throw new Error(`Runtime tool registry contains invalid JSON: ${parsed.error}`);
     }
-    catch (error) {
-        throw new Error(`Runtime tool registry contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    if (parsed.sanitized.removed_control_bytes > 0) {
+        throw new Error(`Runtime tool registry contains control-byte corruption: control_bytes_removed=${parsed.sanitized.removed_control_bytes}`);
     }
-    const validation = validateRuntimeToolSpecRegistryPayload(parsed);
+    const validation = validateRuntimeToolSpecRegistryPayload(parsed.value);
     if (!validation.ok) {
         throw new Error(`Runtime tool registry failed validation (${validation.schema}): ${validation.errors.join("; ")}`);
     }
-    return parsed;
+    return parsed.value;
 }
 function ensureToolSpec(spec, name) {
     if (spec)
@@ -258,17 +292,20 @@ export function loadRuntimeToolRegistry(explicitPath) {
         };
     }
     catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const controlBytesRemoved = Number(errorMessage.match(/control_bytes_removed=(\d+)/)?.[1] ?? 0);
         void emitRuntimeToolEvent("RUNTIME_TOOL_REGISTRY_INVALID", `Runtime tool registry validation failed for ${target.path}`, {
             path: target.path,
             source: target.source,
-            errors: [error instanceof Error ? error.message : String(error)],
+            ...(controlBytesRemoved > 0 ? { control_bytes_removed: controlBytesRemoved } : {}),
+            errors: [errorMessage],
         });
         return {
             ok: false,
             schema: RUNTIME_TOOL_SPEC_SCHEMA_NAME,
             path: target.path,
             source: target.source,
-            errors: [error instanceof Error ? error.message : String(error)],
+            errors: [errorMessage],
         };
     }
 }
@@ -317,7 +354,7 @@ export async function executeRuntimeTool(name, input, context = {}) {
             },
             validation_errors: inputErrors,
         }, null, 2);
-        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, validationRequest, validationResponse));
+        ({ requestPath, responsePath } = await persistRuntimeToolInvocationArtifacts(callId, validationRequest, validationResponse));
         rmSync(tempPaths.tempDir, { recursive: true, force: true });
         const result = {
             ok: false,
@@ -368,16 +405,17 @@ export async function executeRuntimeTool(name, input, context = {}) {
         : workspacePath;
     const shellResult = await runShellCommand(spec.executor.command, {
         cwd: cwdBase,
-        env: {
-            ...process.env,
-            ...(spec.executor.env ?? {}),
-            ACE_RUNTIME_TOOL_NAME: spec.name,
-            ACE_RUNTIME_TOOL_REQUEST_FILE: tempPaths.requestPath,
-            ACE_RUNTIME_TOOL_RESPONSE_FILE: tempPaths.responsePath,
-            ACE_RUNTIME_SESSION_ID: context.session_id ?? "",
-            ACE_RUNTIME_TURN: context.turn_number ? String(context.turn_number) : "",
-            ACE_RUNTIME_WORKSPACE_PATH: workspacePath,
-        },
+        env: buildRuntimeToolEnvironment({
+            spec_env: spec.executor.env,
+            injected_env: {
+                ACE_RUNTIME_TOOL_NAME: spec.name,
+                ACE_RUNTIME_TOOL_REQUEST_FILE: tempPaths.requestPath,
+                ACE_RUNTIME_TOOL_RESPONSE_FILE: tempPaths.responsePath,
+                ACE_RUNTIME_SESSION_ID: context.session_id ?? "",
+                ACE_RUNTIME_TURN: context.turn_number ? String(context.turn_number) : "",
+                ACE_RUNTIME_WORKSPACE_PATH: workspacePath,
+            },
+        }),
         timeout_ms: spec.executor.timeout_ms ?? 60_000,
     });
     let responseRaw;
@@ -386,7 +424,7 @@ export async function executeRuntimeTool(name, input, context = {}) {
     }
     if (!responseRaw) {
         const summary = `Runtime tool '${name}' did not produce a response payload`;
-        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, requestRaw, JSON.stringify({
+        ({ requestPath, responsePath } = await persistRuntimeToolInvocationArtifacts(callId, requestRaw, JSON.stringify({
             ok: false,
             summary,
             error: {
@@ -436,7 +474,7 @@ export async function executeRuntimeTool(name, input, context = {}) {
     }
     catch (error) {
         const summary = `Runtime tool '${name}' returned invalid JSON`;
-        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, requestRaw, responseRaw));
+        ({ requestPath, responsePath } = await persistRuntimeToolInvocationArtifacts(callId, requestRaw, responseRaw));
         await emitRuntimeToolEvent("RUNTIME_TOOL_FAILED", summary, {
             tool_name: name,
             error: error instanceof Error ? error.message : String(error),
@@ -458,7 +496,7 @@ export async function executeRuntimeTool(name, input, context = {}) {
     const envelope = runtimeToolResponseSchema.safeParse(parsed);
     if (!envelope.success) {
         const summary = `Runtime tool '${name}' returned an invalid response envelope`;
-        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, requestRaw, responseRaw));
+        ({ requestPath, responsePath } = await persistRuntimeToolInvocationArtifacts(callId, requestRaw, responseRaw));
         rmSync(tempPaths.tempDir, { recursive: true, force: true });
         return {
             ok: false,
@@ -483,7 +521,7 @@ export async function executeRuntimeTool(name, input, context = {}) {
     const success = envelope.data.ok && validationErrors.length === 0;
     const summary = envelope.data.summary ??
         (success ? `Runtime tool '${name}' executed successfully` : `Runtime tool '${name}' failed`);
-    ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, requestRaw, responseRaw));
+    ({ requestPath, responsePath } = await persistRuntimeToolInvocationArtifacts(callId, requestRaw, responseRaw));
     rmSync(tempPaths.tempDir, { recursive: true, force: true });
     const result = {
         ok: success,
@@ -524,4 +562,82 @@ export async function executeRuntimeTool(name, input, context = {}) {
     });
     return result;
 }
+export const SMALL_LOCAL_PRIORITY_TOOL_NAMES = [
+    "outline_file",
+    "astgrep_query",
+    "astgrep_locate",
+    "read_file_lines",
+    "compile_structural_edit",
+    "preview_structural_edit",
+    "list_workspace",
+    "recall_context",
+    "validate_framework",
+    "run_orchestrator",
+];
+const HEAVY_TOOL_NAMES = new Set([
+    "read_workspace_file",
+    "write_workspace_file",
+    "safe_edit_file",
+    "astgrep_rewrite",
+]);
+function extractCostClass(tool) {
+    const desc = (tool.description ?? "").toLowerCase();
+    if (desc.includes("cost: cheap"))
+        return "cheap";
+    if (desc.includes("cost: moderate"))
+        return "moderate";
+    if (desc.includes("cost: heavy"))
+        return "heavy";
+    if (HEAVY_TOOL_NAMES.has(tool.name))
+        return "heavy";
+    if (["read_file_lines", "apply_patch", "diff_files"].includes(tool.name))
+        return "moderate";
+    return "cheap";
+}
+export function buildFilteredToolCatalog(modelClass, allowedTools) {
+    const allTools = listRuntimeToolSpecs();
+    const effectiveModelClass = modelClass ?? "frontier";
+    const allowed = allowedTools ? new Set(allowedTools) : null;
+    const unavailable = [];
+    let entries = [];
+    for (const tool of allTools) {
+        if (allowed !== null && !allowed.has(tool.name)) {
+            unavailable.push({
+                name: tool.name,
+                reason: "Not in allowed_tools for this session",
+                reason_code: "workspace_disabled",
+            });
+            continue;
+        }
+        const costClass = extractCostClass(tool);
+        let description = tool.description;
+        if (effectiveModelClass === "small_local" && costClass === "heavy") {
+            description = `[cost: heavy — prefer surgical alternatives] ${description}`;
+        }
+        entries.push({
+            name: tool.name,
+            description,
+            input_schema: tool.input_schema,
+            cost_class: costClass,
+        });
+    }
+    if (effectiveModelClass === "small_local" || effectiveModelClass === "mid") {
+        const priority = new Map(SMALL_LOCAL_PRIORITY_TOOL_NAMES.map((name, idx) => [name, idx]));
+        entries.sort((a, b) => {
+            const pa = priority.get(a.name) ?? 999;
+            const pb = priority.get(b.name) ?? 999;
+            return pa - pb;
+        });
+    }
+    const toolCostClass = {};
+    for (const e of entries) {
+        toolCostClass[e.name] = e.cost_class;
+    }
+    return {
+        entries,
+        model_class: effectiveModelClass,
+        unavailable_tools: unavailable,
+        tool_cost_class: toolCostClass,
+    };
+}
 //# sourceMappingURL=runtime-tool-specs.js.map

package/dist/safe-edit.d.ts

@@ -49,4 +49,11 @@ export declare function diffContents(original: string, updated: string): DiffRes
 export declare function diffFiles(pathA: string, pathB: string): DiffResult & {
     error?: string;
 };
+export interface ApplyPatchInput {
+    path: string;
+    patch: string;
+    validation_command?: string;
+    test_command?: string;
+}
+export declare function applyPatch(input: ApplyPatchInput): SafeEditResult;
 //# sourceMappingURL=safe-edit.d.ts.map