@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/store/write-coordinator.js

@@ -0,0 +1,386 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { getWorkspaceStorePath } from "./store-snapshot.js";
+import { withStoreWriteQueue } from "./write-queue.js";
+const DEFAULT_WAIT_MS = 15_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_LEASE_TTL_MS = 30_000;
+const DEFAULT_STALE_GRACE_MS = 1_000;
+export class StoreWriteLeaseBusyError extends Error {
+    storePath;
+    lockPath;
+    waitedMs;
+    currentHolder;
+    constructor(input) {
+        super(input.currentHolder
+            ? `Store write lease busy at ${input.storePath}; held by pid=${input.currentHolder.pid} hostname=${input.currentHolder.hostname}`
+            : `Store write lease busy at ${input.storePath}; no lease metadata available`);
+        this.name = "StoreWriteLeaseBusyError";
+        this.storePath = input.storePath;
+        this.lockPath = input.lockPath;
+        this.waitedMs = input.waitedMs;
+        this.currentHolder = input.currentHolder;
+    }
+}
+export class StoreSyncWriteBlockedByAsyncLeaseError extends Error {
+    code = "STORE_SYNC_WRITE_BLOCKED_BY_ASYNC_LEASE";
+    storePath;
+    currentAsyncOperationLabels;
+    constructor(input) {
+        super(`Sync store write blocked for ${input.storePath}; async ownership is already active in this process. Use safeWriteAsync() / appendStatusEventSafe() / createWorkspaceSessionAsync() instead.`);
+        this.name = "StoreSyncWriteBlockedByAsyncLeaseError";
+        this.storePath = input.storePath;
+        this.currentAsyncOperationLabels = input.currentAsyncOperationLabels;
+    }
+}
+const asyncStoreOwnerships = new Map();
+function leaseDirPath(storePath) {
+    return `${storePath}.write.lock`;
+}
+function leaseMetadataPath(lockPath) {
+    return join(lockPath, "lease.json");
+}
+function getOperationLabel(options) {
+    return options.operation_label?.trim() || undefined;
+}
+function emitLifecycleEvent(options, event) {
+    if (options.emit_lifecycle_events === false)
+        return;
+    const sink = options.lifecycle_sink;
+    if (!sink)
+        return;
+    try {
+        sink({
+            ...event,
+            hostname: hostname(),
+            pid: process.pid,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch {
+        // Lifecycle sinks are observability only; they must not affect lease behavior.
+    }
+}
+function registerAsyncStoreOwnership(storePath, operationLabel) {
+    const current = asyncStoreOwnerships.get(storePath);
+    if (!current) {
+        asyncStoreOwnerships.set(storePath, {
+            count: 1,
+            operationLabels: operationLabel ? [operationLabel] : [],
+        });
+        return;
+    }
+    current.count += 1;
+    if (operationLabel) {
+        current.operationLabels.push(operationLabel);
+    }
+}
+function releaseAsyncStoreOwnership(storePath, operationLabel) {
+    const current = asyncStoreOwnerships.get(storePath);
+    if (!current)
+        return;
+    current.count = Math.max(0, current.count - 1);
+    if (operationLabel) {
+        const index = current.operationLabels.lastIndexOf(operationLabel);
+        if (index >= 0) {
+            current.operationLabels.splice(index, 1);
+        }
+    }
+    if (current.count === 0) {
+        asyncStoreOwnerships.delete(storePath);
+    }
+}
+function getAsyncStoreOwnership(storePath) {
+    const current = asyncStoreOwnerships.get(storePath);
+    if (!current)
+        return undefined;
+    return {
+        count: current.count,
+        operationLabels: [...current.operationLabels],
+    };
+}
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    const shared = new SharedArrayBuffer(4);
+    const view = new Int32Array(shared);
+    Atomics.wait(view, 0, 0, ms);
+}
+function sleepAsync(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeLeaseRecord(record) {
+    if (!record)
+        return undefined;
+    if (typeof record.token !== "string" ||
+        typeof record.storePath !== "string" ||
+        typeof record.lockPath !== "string" ||
+        typeof record.metadataPath !== "string" ||
+        typeof record.pid !== "number" ||
+        typeof record.hostname !== "string" ||
+        typeof record.acquiredAt !== "string" ||
+        typeof record.expiresAt !== "string" ||
+        typeof record.ttlMs !== "number" ||
+        typeof record.waitedMs !== "number") {
+        return undefined;
+    }
+    return {
+        token: record.token,
+        storePath: record.storePath,
+        lockPath: record.lockPath,
+        metadataPath: record.metadataPath,
+        pid: record.pid,
+        hostname: record.hostname,
+        agentId: typeof record.agentId === "string" ? record.agentId : undefined,
+        operationLabel: typeof record.operationLabel === "string" ? record.operationLabel : undefined,
+        acquiredAt: record.acquiredAt,
+        expiresAt: record.expiresAt,
+        ttlMs: record.ttlMs,
+        waitedMs: record.waitedMs,
+    };
+}
+function readLeaseRecord(lockPath) {
+    const metadataPath = leaseMetadataPath(lockPath);
+    if (!existsSync(metadataPath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(metadataPath, "utf-8"));
+        return normalizeLeaseRecord(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaseIsStale(lease, staleGraceMs) {
+    const expiresAt = Date.parse(lease.expiresAt);
+    if (!Number.isFinite(expiresAt))
+        return true;
+    return Date.now() > expiresAt + staleGraceMs;
+}
+function canRecoverStaleLease(lease, staleGraceMs) {
+    if (!leaseIsStale(lease, staleGraceMs))
+        return false;
+    if (lease.hostname !== hostname())
+        return false;
+    try {
+        process.kill(lease.pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "ESRCH";
+    }
+}
+function createLeaseRecord(storePath, lockPath, options, waitedMs) {
+    const ttlMs = options.lease_ttl_ms ?? DEFAULT_LEASE_TTL_MS;
+    const acquiredAtMs = Date.now();
+    const acquiredAt = new Date(acquiredAtMs).toISOString();
+    return {
+        token: randomUUID(),
+        storePath,
+        lockPath,
+        metadataPath: leaseMetadataPath(lockPath),
+        pid: process.pid,
+        hostname: hostname(),
+        agentId: options.agent_id,
+        operationLabel: options.operation_label,
+        acquiredAt,
+        expiresAt: new Date(acquiredAtMs + ttlMs).toISOString(),
+        ttlMs,
+        waitedMs,
+    };
+}
+function tryAcquireLeaseSync(storePath, lockPath, options, waitedMs) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    mkdirSync(lockPath, { recursive: false });
+    const lease = createLeaseRecord(storePath, lockPath, options, waitedMs);
+    writeFileSync(lease.metadataPath, JSON.stringify({ kind: "store_write_lease", ...lease }, null, 2), "utf-8");
+    return lease;
+}
+async function tryAcquireLeaseAsync(storePath, lockPath, options, waitedMs) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    mkdirSync(lockPath, { recursive: false });
+    const lease = createLeaseRecord(storePath, lockPath, options, waitedMs);
+    writeFileSync(lease.metadataPath, JSON.stringify({ kind: "store_write_lease", ...lease }, null, 2), "utf-8");
+    return lease;
+}
+function releaseLease(lease) {
+    const current = readLeaseRecord(lease.lockPath);
+    if (!current) {
+        rmSync(lease.lockPath, { recursive: true, force: true });
+        return;
+    }
+    if (current.token !== lease.token) {
+        throw new Error(`Store write lease token mismatch while releasing ${lease.storePath}; refusing to remove a different holder's lock`);
+    }
+    rmSync(lease.lockPath, { recursive: true, force: true });
+}
+async function acquireLeaseAsync(storePath, options) {
+    const lockPath = leaseDirPath(storePath);
+    const waitMs = options.wait_ms ?? DEFAULT_WAIT_MS;
+    const pollIntervalMs = options.poll_interval_ms ?? DEFAULT_POLL_INTERVAL_MS;
+    const staleGraceMs = options.stale_grace_ms ?? DEFAULT_STALE_GRACE_MS;
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= waitMs) {
+        try {
+            return await tryAcquireLeaseAsync(storePath, lockPath, options, Date.now() - startedAt);
+        }
+        catch (error) {
+            const isBusy = error instanceof Error &&
+                "code" in error &&
+                error.code === "EEXIST";
+            if (!isBusy)
+                throw error;
+            const current = readLeaseRecord(lockPath);
+            if (current && canRecoverStaleLease(current, staleGraceMs)) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            await sleepAsync(Math.min(pollIntervalMs, waitMs));
+        }
+    }
+    const currentHolder = readLeaseRecord(lockPath);
+    emitLifecycleEvent(options, {
+        event: "store-write-blocked",
+        storePath,
+        operationLabel: getOperationLabel(options),
+        waitedMs: Date.now() - startedAt,
+        currentHolder,
+        asyncOwnership: getAsyncStoreOwnership(storePath),
+    });
+    throw new StoreWriteLeaseBusyError({
+        storePath,
+        lockPath,
+        waitedMs: Date.now() - startedAt,
+        currentHolder,
+    });
+}
+function acquireLeaseSync(storePath, options) {
+    const lockPath = leaseDirPath(storePath);
+    const waitMs = options.wait_ms ?? DEFAULT_WAIT_MS;
+    const pollIntervalMs = options.poll_interval_ms ?? DEFAULT_POLL_INTERVAL_MS;
+    const staleGraceMs = options.stale_grace_ms ?? DEFAULT_STALE_GRACE_MS;
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= waitMs) {
+        try {
+            return tryAcquireLeaseSync(storePath, lockPath, options, Date.now() - startedAt);
+        }
+        catch (error) {
+            const isBusy = error instanceof Error &&
+                "code" in error &&
+                error.code === "EEXIST";
+            if (!isBusy)
+                throw error;
+            const current = readLeaseRecord(lockPath);
+            if (current && canRecoverStaleLease(current, staleGraceMs)) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            sleepSync(Math.min(pollIntervalMs, waitMs));
+        }
+    }
+    const currentHolder = readLeaseRecord(lockPath);
+    emitLifecycleEvent(options, {
+        event: "store-write-blocked",
+        storePath,
+        operationLabel: getOperationLabel(options),
+        waitedMs: Date.now() - startedAt,
+        currentHolder,
+        asyncOwnership: getAsyncStoreOwnership(storePath),
+    });
+    throw new StoreWriteLeaseBusyError({
+        storePath,
+        lockPath,
+        waitedMs: Date.now() - startedAt,
+        currentHolder,
+    });
+}
+export async function withStoreWriteCoordinator(storePath, fn, options = {}) {
+    const operationLabel = getOperationLabel(options);
+    registerAsyncStoreOwnership(storePath, operationLabel);
+    emitLifecycleEvent(options, {
+        event: "store-write-requested",
+        storePath,
+        operationLabel,
+        asyncOwnership: getAsyncStoreOwnership(storePath),
+    });
+    try {
+        return await withStoreWriteQueue(storePath, async () => {
+            emitLifecycleEvent(options, {
+                event: "store-write-accepted",
+                storePath,
+                operationLabel,
+                asyncOwnership: getAsyncStoreOwnership(storePath),
+            });
+            const lease = await acquireLeaseAsync(storePath, options);
+            emitLifecycleEvent(options, {
+                event: "store-write-started",
+                storePath,
+                operationLabel,
+                waitedMs: lease.waitedMs,
+                currentHolder: lease,
+                asyncOwnership: getAsyncStoreOwnership(storePath),
+            });
+            try {
+                const result = await fn();
+                emitLifecycleEvent(options, {
+                    event: "store-write-committed",
+                    storePath,
+                    operationLabel,
+                    waitedMs: lease.waitedMs,
+                    currentHolder: lease,
+                    asyncOwnership: getAsyncStoreOwnership(storePath),
+                });
+                return result;
+            }
+            catch (error) {
+                emitLifecycleEvent(options, {
+                    event: "store-write-failed",
+                    storePath,
+                    operationLabel,
+                    waitedMs: lease.waitedMs,
+                    currentHolder: lease,
+                    error: error instanceof Error ? error.message : String(error),
+                    asyncOwnership: getAsyncStoreOwnership(storePath),
+                });
+                throw error;
+            }
+            finally {
+                releaseLease(lease);
+            }
+        });
+    }
+    finally {
+        releaseAsyncStoreOwnership(storePath, operationLabel);
+    }
+}
+export function withStoreWriteCoordinatorSync(storePath, fn, options = {}) {
+    const operationLabel = getOperationLabel(options);
+    const asyncOwnership = getAsyncStoreOwnership(storePath);
+    if (asyncOwnership && asyncOwnership.count > 0) {
+        emitLifecycleEvent(options, {
+            event: "store-write-blocked",
+            storePath,
+            operationLabel,
+            asyncOwnership,
+        });
+        throw new StoreSyncWriteBlockedByAsyncLeaseError({
+            storePath,
+            currentAsyncOperationLabels: asyncOwnership.operationLabels.length > 0
+                ? asyncOwnership.operationLabels
+                : ["unknown async store writer"],
+        });
+    }
+    const lease = acquireLeaseSync(storePath, options);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLease(lease);
+    }
+}
+export function resolveStoreWriteLeasePath(workspaceRoot) {
+    return `${getWorkspaceStorePath(workspaceRoot)}.write.lock`;
+}
+//# sourceMappingURL=write-coordinator.js.map

package/dist/todo-state.js

@@ -5,7 +5,7 @@ import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { TodoRepository } from "./store/repositories/todo-repository.js";
 import { getWorkspaceStorePath, readStoreJsonSync, storeExistsSync } from "./store/store-snapshot.js";
 import { operationalArtifactVirtualPath } from "./store/store-artifacts.js";
-import { withStoreWriteQueue } from "./store/write-queue.js";
+import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 import { isReadError, slugify } from "./shared.js";
 const TODO_MARKDOWN_REL = `${ACE_TASKS_ROOT_REL}/todo.md`;
 const TODO_STATE_REL = "agent-state/todo-state.json";
@@ -263,7 +263,7 @@ async function mirrorTodoStateToStore(root, state) {
     const storePath = getWorkspaceStorePath(root);
     if (!existsSync(storePath))
         return;
-    await withStoreWriteQueue(storePath, async () => {
+    await withStoreWriteCoordinator(storePath, async () => {
         const store = await openStore(storePath);
         try {
             const nextIds = state.order.filter((id) => Boolean(state.nodes[id]));
@@ -294,14 +294,14 @@ async function mirrorTodoStateToStore(root, state) {
         finally {
             await store.close();
         }
-    });
+    }, { operation_label: "syncTodoStateSafe" });
 }
 async function writeStateStoreBacked(root, state) {
     const storePath = getWorkspaceStorePath(root);
     if (!existsSync(storePath)) {
         return writeState(state);
     }
-    return withStoreWriteQueue(storePath, async () => {
+    return withStoreWriteCoordinator(storePath, async () => {
         const store = await openStore(storePath);
         try {
             const repo = new TodoRepository(store);
@@ -324,7 +324,7 @@ async function writeStateStoreBacked(root, state) {
         finally {
             await store.close();
         }
-    });
+    }, { operation_label: "syncTodoStateSafe" });
 }
 function scheduleTodoMirror(root, state) {
     const snapshot = JSON.parse(JSON.stringify(state));

package/dist/tools-agent.d.ts

@@ -2,6 +2,26 @@
  * Agent, skill, kernel, and task-pack tool registrations.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BridgeResult } from "./model-bridge.js";
+import { proposePlan as proposePlanImpl, validatePlan as validatePlanImpl, loadAcceptanceTraceContract as loadAcceptanceTraceContractImpl } from "./plan-proposal.js";
+import { type TaskPlan, type TaskStep } from "./orchestrator-supervisor.js";
 export type { TaskPlan, TaskStep } from "./orchestrator-supervisor.js";
+export declare function formatStepTaskForBridge(step: Pick<TaskStep, "task" | "upstream_outputs">): string;
+type IntentVerificationOutcome = "ok" | "revisit_step" | "replan_required";
+type IntentDriftReasonCode = "contract_missing" | "contract_invalid" | "bridge_output_malformed_json" | "role_drift_ui_off_topic" | "coder_artifact_stub" | "qa_rewrote_artifact" | "artifact_mismatch" | "forbidden_pattern" | "required_evidence_missing";
+interface IntentVerificationResult {
+    outcome: IntentVerificationOutcome;
+    reason: string;
+    reason_code?: IntentDriftReasonCode;
+    uncovered_clauses?: string[];
+}
+export { loadAcceptanceTraceContractImpl as loadAcceptanceTraceContract };
+export { proposePlanImpl as proposePlan, validatePlanImpl as validatePlan };
+export declare function verifyIntentAgainstContract(input: {
+    plan: TaskPlan;
+    step: TaskStep;
+    result: BridgeResult;
+    intent_contract: unknown;
+}): IntentVerificationResult;
 export declare function registerAgentTools(server: McpServer): void;
 //# sourceMappingURL=tools-agent.d.ts.map