@voybio/ace-swarm 0.1.0

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

@@ -0,0 +1,68 @@
+import { type ArtifactSource } from "./helpers.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";
+export declare const RUNTIME_TOOL_SPEC_SCHEMA_NAME = "runtime-tool-spec-registry@1.0.0";
+type JsonSchemaScalar = string | number | boolean | null;
+export type RuntimeToolSchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+export interface RuntimeToolSchema {
+    type: RuntimeToolSchemaType;
+    description?: string;
+    enum?: JsonSchemaScalar[];
+    properties?: Record<string, RuntimeToolSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: RuntimeToolSchema;
+}
+export interface RuntimeToolExecutorConfig {
+    command: string;
+    cwd?: string;
+    timeout_ms?: number;
+    env?: Record<string, string>;
+}
+export interface RuntimeToolSpec {
+    name: string;
+    description: string;
+    input_schema: RuntimeToolSchema;
+    success_schema?: RuntimeToolSchema;
+    failure_schema?: RuntimeToolSchema;
+    executor: RuntimeToolExecutorConfig;
+}
+export interface RuntimeToolSpecRegistry {
+    version: 1;
+    updated_at: string;
+    tools: RuntimeToolSpec[];
+}
+export interface RuntimeToolSpecRegistryResult {
+    ok: boolean;
+    schema: typeof RUNTIME_TOOL_SPEC_SCHEMA_NAME;
+    path: string;
+    source: ArtifactSource;
+    registry?: RuntimeToolSpecRegistry;
+    errors?: string[];
+}
+export interface RuntimeToolExecutionContext {
+    session_id?: string;
+    workspace_path?: string;
+    turn_number?: number;
+}
+export interface RuntimeToolExecutionResult {
+    ok: boolean;
+    name: string;
+    summary: string;
+    request_path: string;
+    response_path: string;
+    exit_code?: number | null;
+    duration_ms?: number;
+    output?: unknown;
+    error?: unknown;
+    validation_errors?: 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 {};
+//# sourceMappingURL=runtime-tool-specs.d.ts.map

package/dist/runtime-tool-specs.js

@@ -0,0 +1,527 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, mkdtempSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { DEFAULTS_ROOT, resolveWorkspaceArtifactPath as resolveWorkspaceArtifactPathHelper, resolveWorkspaceRoot, } from "./helpers.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { runShellCommand } from "./runtime-command.js";
+import { readRuntimeProfile } from "./runtime-profile.js";
+import { validateRuntimeToolSpecRegistryPayload, } from "./schemas.js";
+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";
+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";
+const DEFAULT_RUNTIME_TOOL_SPEC_REGISTRY_PATH = resolve(DEFAULTS_ROOT, RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH);
+const runtimeToolResponseSchema = z
+    .object({
+    ok: z.boolean(),
+    summary: z.string().optional(),
+    output: z.unknown().optional(),
+    error: z.unknown().optional(),
+})
+    .strict();
+function defaultRegistry() {
+    return {
+        version: 1,
+        updated_at: "1970-01-01T00:00:00.000Z",
+        tools: [],
+    };
+}
+function normalizeSource(path) {
+    return path === DEFAULT_RUNTIME_TOOL_SPEC_REGISTRY_PATH || path.startsWith(DEFAULTS_ROOT)
+        ? "package-defaults"
+        : "workspace";
+}
+function configuredRegistryRelativePath() {
+    const configured = readRuntimeProfile().tools?.registry_path;
+    return typeof configured === "string" && configured.trim().length > 0
+        ? configured.trim()
+        : RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH;
+}
+function resolveRuntimeToolRegistryTarget(explicitPath) {
+    const relativePath = explicitPath?.trim() || configuredRegistryRelativePath();
+    const workspaceRoot = resolveWorkspaceRoot();
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    const operationalKey = !relativePath.startsWith("/")
+        ? operationalArtifactKey(relativePath)
+        : undefined;
+    const resolved = relativePath.startsWith("/")
+        ? resolve(relativePath)
+        : resolveWorkspaceArtifactPathHelper(relativePath, "read");
+    const defaultWorkspacePath = resolveWorkspaceArtifactPathHelper(RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH, "read");
+    if (existsSync(resolved)) {
+        return { path: resolved, source: normalizeSource(resolved), mode: "file" };
+    }
+    if (operationalKey && readStoreBlobSync(workspaceRoot, operationalKey)) {
+        return {
+            path: toVirtualStorePath(storePath, operationalKey),
+            source: "store",
+            mode: "store",
+            key: operationalKey,
+        };
+    }
+    const knowledgeKey = !relativePath.startsWith("/") && relativePath === RUNTIME_TOOL_SPEC_REGISTRY_REL_PATH
+        ? "knowledge/agent-state/runtime-tool-specs.json"
+        : undefined;
+    if (knowledgeKey && readStoreBlobSync(workspaceRoot, knowledgeKey)) {
+        return {
+            path: toVirtualStorePath(storePath, knowledgeKey),
+            source: "store",
+            mode: "store",
+            key: knowledgeKey,
+        };
+    }
+    if (resolved === defaultWorkspacePath) {
+        return {
+            path: DEFAULT_RUNTIME_TOOL_SPEC_REGISTRY_PATH,
+            source: "package-defaults",
+            mode: "file",
+        };
+    }
+    return { path: resolved, source: "workspace", mode: "file" };
+}
+function resolveWorkspaceArtifactPath(filePath) {
+    return resolveWorkspaceArtifactPathHelper(filePath, "write");
+}
+function buildTempToolPaths(callId) {
+    const tempDir = mkdtempSync(join(tmpdir(), `ace-runtime-tool-${callId}-`));
+    return {
+        tempDir,
+        requestPath: join(tempDir, "request.json"),
+        responsePath: join(tempDir, "response.json"),
+    };
+}
+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) {
+    const workspaceRoot = resolveWorkspaceRoot();
+    if (!storeExistsSync(workspaceRoot)) {
+        const requestPath = resolveWorkspaceArtifactPath(`.ace-runtime/tools/${callId}.request.json`);
+        const responsePath = resolveWorkspaceArtifactPath(`.ace-runtime/tools/${callId}.response.json`);
+        mkdirSync(dirname(requestPath), { recursive: true });
+        writeFileSync(requestPath, requestContent, "utf-8");
+        writeFileSync(responsePath, responseContent, "utf-8");
+        return { requestPath, responsePath };
+    }
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    await withStoreWriteQueue(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            await store.setBlob(runtimeToolArtifactKey(callId, "request"), requestContent);
+            await store.setBlob(runtimeToolArtifactKey(callId, "response"), responseContent);
+            await store.commit();
+        }
+        finally {
+            await store.close();
+        }
+    });
+    return {
+        requestPath: runtimeToolArtifactVirtualPath(callId, "request"),
+        responsePath: runtimeToolArtifactVirtualPath(callId, "response"),
+    };
+}
+function parseRuntimeToolRegistry(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Runtime tool registry contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const validation = validateRuntimeToolSpecRegistryPayload(parsed);
+    if (!validation.ok) {
+        throw new Error(`Runtime tool registry failed validation (${validation.schema}): ${validation.errors.join("; ")}`);
+    }
+    return parsed;
+}
+function ensureToolSpec(spec, name) {
+    if (spec)
+        return spec;
+    throw new Error(`Unknown runtime tool spec: ${name}`);
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function validateEnum(schema, value, path) {
+    if (!schema.enum || schema.enum.length === 0)
+        return [];
+    return schema.enum.some((entry) => Object.is(entry, value))
+        ? []
+        : [`${path}: value must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join(", ")}`];
+}
+function validateValueAgainstSchema(schema, value, path) {
+    const enumErrors = validateEnum(schema, value, path);
+    if (enumErrors.length > 0)
+        return enumErrors;
+    switch (schema.type) {
+        case "object": {
+            if (!isPlainObject(value))
+                return [`${path}: expected object`];
+            const errors = [];
+            const properties = schema.properties ?? {};
+            const required = new Set(schema.required ?? []);
+            for (const key of required) {
+                if (!Object.prototype.hasOwnProperty.call(value, key)) {
+                    errors.push(`${path}.${key}: required`);
+                }
+            }
+            for (const [key, childValue] of Object.entries(value)) {
+                const childSchema = properties[key];
+                if (!childSchema) {
+                    if (schema.additionalProperties === false) {
+                        errors.push(`${path}.${key}: additional properties are not allowed`);
+                    }
+                    continue;
+                }
+                errors.push(...validateValueAgainstSchema(childSchema, childValue, `${path}.${key}`));
+            }
+            return errors;
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                return [`${path}: expected array`];
+            if (!schema.items)
+                return [];
+            return value.flatMap((entry, index) => validateValueAgainstSchema(schema.items, entry, `${path}[${index}]`));
+        }
+        case "string":
+            return typeof value === "string" ? [] : [`${path}: expected string`];
+        case "number":
+            return typeof value === "number" && Number.isFinite(value)
+                ? []
+                : [`${path}: expected number`];
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value)
+                ? []
+                : [`${path}: expected integer`];
+        case "boolean":
+            return typeof value === "boolean" ? [] : [`${path}: expected boolean`];
+        case "null":
+            return value === null ? [] : [`${path}: expected null`];
+        default:
+            return [`${path}: unsupported schema type ${schema.type}`];
+    }
+}
+function emitRuntimeToolEvent(eventType, summary, payload) {
+    return appendStatusEventSafe({
+        source_module: "capability-framework",
+        event_type: eventType,
+        status: eventType === "RUNTIME_TOOL_EXECUTED" ? "done" : "fail",
+        summary,
+        payload,
+    }).then(() => undefined).catch(() => undefined);
+}
+export function validateRuntimeToolRegistryContent(raw) {
+    try {
+        parseRuntimeToolRegistry(raw);
+        return { ok: true, schema: RUNTIME_TOOL_SPEC_SCHEMA_NAME };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            schema: RUNTIME_TOOL_SPEC_SCHEMA_NAME,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+export function loadRuntimeToolRegistry(explicitPath) {
+    const target = resolveRuntimeToolRegistryTarget(explicitPath);
+    if (target.mode === "file" && !existsSync(target.path)) {
+        return {
+            ok: false,
+            schema: RUNTIME_TOOL_SPEC_SCHEMA_NAME,
+            path: target.path,
+            source: target.source,
+            errors: [`Runtime tool registry file not found: ${target.path}`],
+        };
+    }
+    const raw = target.mode === "store"
+        ? (target.key ? readStoreBlobSync(resolveWorkspaceRoot(), target.key) : undefined) ?? ""
+        : readFileSync(target.path, "utf-8");
+    try {
+        const registry = parseRuntimeToolRegistry(raw);
+        return {
+            ok: true,
+            schema: RUNTIME_TOOL_SPEC_SCHEMA_NAME,
+            path: target.path,
+            source: target.source,
+            registry,
+        };
+    }
+    catch (error) {
+        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)],
+        });
+        return {
+            ok: false,
+            schema: RUNTIME_TOOL_SPEC_SCHEMA_NAME,
+            path: target.path,
+            source: target.source,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+export function readRuntimeToolRegistry() {
+    const result = loadRuntimeToolRegistry();
+    if (result.ok && result.registry)
+        return result.registry;
+    if (result.source === "package-defaults")
+        return defaultRegistry();
+    throw new Error(result.errors?.join("; ") ?? "Runtime tool registry is unavailable.");
+}
+export function listRuntimeToolSpecs() {
+    return [...readRuntimeToolRegistry().tools].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function getRuntimeToolRegistryPath() {
+    return loadRuntimeToolRegistry().path;
+}
+export async function executeRuntimeTool(name, input, context = {}) {
+    const registry = readRuntimeToolRegistry();
+    const spec = ensureToolSpec(registry.tools.find((tool) => tool.name === name), name);
+    const inputErrors = validateValueAgainstSchema(spec.input_schema, input, "input");
+    const workspacePath = context.workspace_path && context.workspace_path.trim().length > 0
+        ? resolve(context.workspace_path)
+        : resolveWorkspaceRoot();
+    const callId = randomUUID();
+    const tempPaths = buildTempToolPaths(callId);
+    let requestPath = runtimeToolArtifactVirtualPath(callId, "request");
+    let responsePath = runtimeToolArtifactVirtualPath(callId, "response");
+    if (inputErrors.length > 0) {
+        const validationRequest = JSON.stringify({
+            tool: {
+                name: spec.name,
+                description: spec.description,
+            },
+            input,
+            session_id: context.session_id,
+            turn_number: context.turn_number,
+            workspace_path: workspacePath,
+            timestamp: new Date().toISOString(),
+        }, null, 2);
+        const validationResponse = JSON.stringify({
+            ok: false,
+            summary: `Input validation failed for runtime tool '${name}'`,
+            error: {
+                message: "Input validation failed",
+            },
+            validation_errors: inputErrors,
+        }, null, 2);
+        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, validationRequest, validationResponse));
+        rmSync(tempPaths.tempDir, { recursive: true, force: true });
+        const result = {
+            ok: false,
+            name,
+            summary: `Input validation failed for runtime tool '${name}'`,
+            request_path: requestPath,
+            response_path: responsePath,
+            error: {
+                message: "Input validation failed",
+            },
+            validation_errors: inputErrors,
+        };
+        await appendRunLedgerEntrySafe({
+            tool: "runtime-tool-specs",
+            category: "regression",
+            message: result.summary,
+            artifacts: [],
+            metadata: {
+                tool_name: name,
+                validation_errors: inputErrors,
+            },
+        }).catch(() => undefined);
+        await emitRuntimeToolEvent("RUNTIME_TOOL_FAILED", result.summary, {
+            tool_name: name,
+            validation_errors: inputErrors,
+            session_id: context.session_id,
+            turn_number: context.turn_number,
+        });
+        return result;
+    }
+    const payload = {
+        tool: {
+            name: spec.name,
+            description: spec.description,
+        },
+        input,
+        session_id: context.session_id,
+        turn_number: context.turn_number,
+        workspace_path: workspacePath,
+        timestamp: new Date().toISOString(),
+    };
+    const requestRaw = JSON.stringify(payload, null, 2);
+    writeFileSync(tempPaths.requestPath, requestRaw, "utf-8");
+    const cwdBase = spec.executor.cwd?.trim()
+        ? resolve(spec.executor.cwd.startsWith("/")
+            ? spec.executor.cwd
+            : resolve(workspacePath, spec.executor.cwd))
+        : 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,
+        },
+        timeout_ms: spec.executor.timeout_ms ?? 60_000,
+    });
+    let responseRaw;
+    if (existsSync(tempPaths.responsePath)) {
+        responseRaw = readFileSync(tempPaths.responsePath, "utf-8");
+    }
+    if (!responseRaw) {
+        const summary = `Runtime tool '${name}' did not produce a response payload`;
+        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, requestRaw, JSON.stringify({
+            ok: false,
+            summary,
+            error: {
+                message: summary,
+                stdout: shellResult.stdout,
+                stderr: shellResult.stderr,
+            },
+        }, null, 2)));
+        const result = {
+            ok: false,
+            name,
+            summary,
+            request_path: requestPath,
+            response_path: responsePath,
+            exit_code: shellResult.exit_code,
+            duration_ms: shellResult.duration_ms,
+            error: {
+                message: summary,
+                stdout: shellResult.stdout,
+                stderr: shellResult.stderr,
+            },
+        };
+        await appendRunLedgerEntrySafe({
+            tool: "runtime-tool-specs",
+            category: "regression",
+            message: summary,
+            artifacts: [requestPath],
+            metadata: {
+                tool_name: name,
+                exit_code: shellResult.exit_code,
+                timed_out: shellResult.timed_out,
+            },
+        }).catch(() => undefined);
+        await emitRuntimeToolEvent("RUNTIME_TOOL_FAILED", summary, {
+            tool_name: name,
+            exit_code: shellResult.exit_code,
+            timed_out: shellResult.timed_out,
+            session_id: context.session_id,
+            turn_number: context.turn_number,
+        });
+        rmSync(tempPaths.tempDir, { recursive: true, force: true });
+        return result;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(responseRaw);
+    }
+    catch (error) {
+        const summary = `Runtime tool '${name}' returned invalid JSON`;
+        ({ requestPath, responsePath } = await persistToolInvocationArtifacts(callId, requestRaw, responseRaw));
+        await emitRuntimeToolEvent("RUNTIME_TOOL_FAILED", summary, {
+            tool_name: name,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        rmSync(tempPaths.tempDir, { recursive: true, force: true });
+        return {
+            ok: false,
+            name,
+            summary,
+            request_path: requestPath,
+            response_path: responsePath,
+            exit_code: shellResult.exit_code,
+            duration_ms: shellResult.duration_ms,
+            error: {
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+    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));
+        rmSync(tempPaths.tempDir, { recursive: true, force: true });
+        return {
+            ok: false,
+            name,
+            summary,
+            request_path: requestPath,
+            response_path: responsePath,
+            exit_code: shellResult.exit_code,
+            duration_ms: shellResult.duration_ms,
+            error: {
+                message: envelope.error.issues.map((issue) => issue.message).join("; "),
+            },
+        };
+    }
+    const validationErrors = envelope.data.ok
+        ? spec.success_schema
+            ? validateValueAgainstSchema(spec.success_schema, envelope.data.output, "output")
+            : []
+        : spec.failure_schema
+            ? validateValueAgainstSchema(spec.failure_schema, envelope.data.error, "error")
+            : [];
+    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));
+    rmSync(tempPaths.tempDir, { recursive: true, force: true });
+    const result = {
+        ok: success,
+        name,
+        summary,
+        request_path: requestPath,
+        response_path: responsePath,
+        exit_code: shellResult.exit_code,
+        duration_ms: shellResult.duration_ms,
+        output: envelope.data.ok ? envelope.data.output : undefined,
+        error: envelope.data.ok ? undefined : envelope.data.error,
+        validation_errors: validationErrors.length > 0 ? validationErrors : undefined,
+    };
+    await appendRunLedgerEntrySafe({
+        tool: "runtime-tool-specs",
+        category: success ? "info" : "regression",
+        message: summary,
+        artifacts: [requestPath, responsePath],
+        metadata: {
+            tool_name: name,
+            exit_code: shellResult.exit_code,
+            duration_ms: shellResult.duration_ms,
+            timed_out: shellResult.timed_out,
+            session_id: context.session_id,
+            turn_number: context.turn_number,
+            validation_errors: validationErrors,
+        },
+    }).catch(() => undefined);
+    await emitRuntimeToolEvent(success ? "RUNTIME_TOOL_EXECUTED" : "RUNTIME_TOOL_FAILED", summary, {
+        tool_name: name,
+        request_path: requestPath,
+        response_path: responsePath,
+        exit_code: shellResult.exit_code,
+        timed_out: shellResult.timed_out,
+        session_id: context.session_id,
+        turn_number: context.turn_number,
+        validation_errors: validationErrors,
+    });
+    return result;
+}
+//# sourceMappingURL=runtime-tool-specs.js.map

package/dist/safe-edit.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Safe-edit module: copy → modify → validate → swap pattern.
+ * Prevents bricking by never leaving core files in a broken state.
+ */
+export interface SafeEditInput {
+    /** Workspace-relative path to edit. */
+    path: string;
+    /** New file content. */
+    content: string;
+    /** Shell command to validate the change (e.g., "npx tsc --noEmit"). */
+    validation_command?: string;
+    /** Shell command to run tests (e.g., "npm test"). */
+    test_command?: string;
+    /** Whether to keep a .ace-backup copy (default: true). */
+    backup?: boolean;
+}
+export interface SafeEditResult {
+    ok: boolean;
+    original_path: string;
+    staging_path: string;
+    backup_path?: string;
+    original_hash: string;
+    new_hash: string;
+    validation_passed?: boolean;
+    validation_output?: string;
+    test_passed?: boolean;
+    test_output?: string;
+    error?: string;
+    restored?: boolean;
+}
+export interface TestSuiteResult {
+    ok: boolean;
+    exit_code: number;
+    output: string;
+    command: string;
+    duration_ms: number;
+}
+export interface DiffResult {
+    has_diff: boolean;
+    original_lines: number;
+    new_lines: number;
+    added: number;
+    removed: number;
+    diff_summary: string;
+}
+export declare function safeEditFile(input: SafeEditInput): SafeEditResult;
+export declare function runTestSuite(command?: string): TestSuiteResult;
+export declare function diffContents(original: string, updated: string): DiffResult;
+export declare function diffFiles(pathA: string, pathB: string): DiffResult & {
+    error?: string;
+};
+//# sourceMappingURL=safe-edit.d.ts.map