@martinloop/mcp 0.7.0 → 0.8.0

package/dist/vendor/core/swarm/lifecycle.d.ts

@@ -0,0 +1,72 @@
+import { SWARM_SCHEMA_VERSION, type SwarmBudgetLedger, type SwarmCleanupRecord, type SwarmEvent, type SwarmRunRecord } from "../../contracts/index.js";
+import type { SwarmWorkspaceManager, SwarmWorkspaceRuntimeHandle } from "./workspaces.js";
+export interface SwarmChildProcessClosure {
+    readonly state: "closed" | "failed";
+    readonly completedAt: string;
+    readonly errorCode?: string;
+}
+export interface SwarmLifecycleTerminalEvidence {
+    readonly schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    readonly swarmId: string;
+    readonly agentId: string;
+    readonly childRunId: string;
+    readonly taskId: string;
+    readonly workspaceId: string;
+    readonly leaseId: string;
+    readonly processCloseState: "closed" | "failed";
+    readonly leaseState: "settled" | "overspent" | "released" | "failed";
+    readonly reason: "cancelled" | "child_terminal_failure";
+    readonly recordedAt: string;
+    readonly errorCode?: string;
+}
+export interface SwarmLifecyclePreCleanupEvidence {
+    readonly terminal: SwarmLifecycleTerminalEvidence;
+    readonly childEvent: SwarmEvent;
+    readonly budgetLedger: SwarmBudgetLedger;
+    readonly cleanupIntent: {
+        readonly workspaceId: string;
+        readonly workspaceKind: "child";
+        readonly force: true;
+    };
+}
+export interface SwarmChildLifecycleEvidenceWriter {
+    persistBeforeCleanup(evidence: SwarmLifecyclePreCleanupEvidence): Promise<void>;
+}
+export interface SwarmLifecycleEvidenceStore {
+    persistCleanupEvidence(cleanup: SwarmCleanupRecord): Promise<void>;
+    persistTerminalRecord(record: SwarmRunRecord): Promise<void>;
+}
+export interface ActiveSwarmChildRegistration {
+    readonly swarmId: string;
+    readonly agentId: string;
+    readonly childRunId: string;
+    readonly taskId: string;
+    readonly leaseId: string;
+    readonly workspace: SwarmWorkspaceRuntimeHandle;
+    readonly abortController: AbortController;
+    readonly processClosed: Promise<SwarmChildProcessClosure>;
+    readonly evidenceWriter: SwarmChildLifecycleEvidenceWriter;
+}
+export interface SwarmLifecycleControllerInput {
+    readonly record: SwarmRunRecord;
+    readonly workspaceManager: SwarmWorkspaceManager;
+    readonly evidenceStore: SwarmLifecycleEvidenceStore;
+    readonly now?: () => string;
+    readonly createCleanupId?: () => string;
+}
+export interface SwarmLifecycleCancellationResult {
+    readonly acceptingWork: false;
+    readonly state: "stopped" | "needs_review";
+    readonly record: SwarmRunRecord;
+    readonly terminalEvidence: readonly SwarmLifecycleTerminalEvidence[];
+    readonly cleanupEvidence: readonly SwarmCleanupRecord[];
+    readonly unresolvedChildRunIds: readonly string[];
+}
+export interface SwarmLifecycleController {
+    readonly swarmId: string;
+    assertAcceptingWork(): void;
+    registerActiveChild(registration: ActiveSwarmChildRegistration): void;
+    cancel(reason: "cancelled" | "child_terminal_failure"): Promise<SwarmLifecycleCancellationResult>;
+}
+/** Internal parent capability. This module is intentionally absent from Core root exports. */
+export declare function createSwarmLifecycleController(input: SwarmLifecycleControllerInput): SwarmLifecycleController;

package/dist/vendor/core/swarm/lifecycle.js

@@ -0,0 +1,252 @@
+import { SWARM_SCHEMA_VERSION } from "../../contracts/index.js";
+import { releaseSwarmBudgetLease } from "./scheduler.js";
+const controllerAuthority = new WeakMap();
+/** Internal parent capability. This module is intentionally absent from Core root exports. */
+export function createSwarmLifecycleController(input) {
+    const state = {
+        acceptingWork: true,
+        record: cloneRecord(input.record),
+        registrations: new Map(),
+        input
+    };
+    const controller = Object.freeze({
+        swarmId: state.record.swarmId,
+        assertAcceptingWork() {
+            if (!authority(controller).acceptingWork)
+                throw new Error("Swarm is no longer accepting scheduling or admission work.");
+        },
+        registerActiveChild(registration) {
+            const current = authority(controller);
+            if (!current.acceptingWork)
+                throw new Error("Cannot register a child after swarm cancellation begins.");
+            assertRegistration(current, registration);
+            current.registrations.set(registration.childRunId, registration);
+        },
+        cancel(reason) {
+            const current = authority(controller);
+            current.acceptingWork = false;
+            current.cancellation ??= cancelRegisteredChildren(current, reason);
+            return current.cancellation;
+        }
+    });
+    controllerAuthority.set(controller, state);
+    return controller;
+}
+async function cancelRegisteredChildren(state, reason) {
+    const now = state.input.now ?? (() => new Date().toISOString());
+    const registrations = [...state.registrations.values()];
+    // cancel() closes the scheduling/admission gate synchronously before abort.
+    for (const registration of registrations)
+        registration.abortController.abort(reason);
+    // The shared process supervisor owns bounded grace and escalation. Never race
+    // its closure promise with a second timeout that could leave descendants live.
+    const closures = await Promise.all(registrations.map(async (registration) => ({
+        registration,
+        closure: await registration.processClosed.catch(() => ({
+            state: "failed",
+            completedAt: now(),
+            errorCode: "PROCESS_CLOSE_FAILED"
+        }))
+    })));
+    let ledger = cloneLedger(state.record.budgetLedger);
+    const terminalEvidence = [];
+    const childEvents = [];
+    const persisted = new Set();
+    const unresolved = new Set();
+    // Persist pre-cleanup evidence for every registration before any removal.
+    for (const { registration, closure } of closures) {
+        const lease = ledger.leases.find((candidate) => candidate.leaseId === registration.leaseId);
+        let leaseState = "failed";
+        if (lease && lease.agentId === registration.agentId && lease.taskId === registration.taskId) {
+            if (lease.status === "reserved") {
+                const released = releaseSwarmBudgetLease(ledger, lease.leaseId);
+                if (released.ok) {
+                    ledger = released.ledger;
+                    leaseState = "released";
+                }
+            }
+            else {
+                leaseState = lease.status;
+            }
+        }
+        if (leaseState === "failed" || closure.state !== "closed")
+            unresolved.add(registration.childRunId);
+        const terminal = Object.freeze({
+            schemaVersion: SWARM_SCHEMA_VERSION,
+            swarmId: state.record.swarmId,
+            agentId: registration.agentId,
+            childRunId: registration.childRunId,
+            taskId: registration.taskId,
+            workspaceId: registration.workspace.record.workspaceId,
+            leaseId: registration.leaseId,
+            processCloseState: closure.state,
+            leaseState,
+            reason,
+            recordedAt: now(),
+            ...(closure.errorCode ? { errorCode: closure.errorCode } : {})
+        });
+        const childEvent = Object.freeze({
+            type: closure.state === "closed" ? "CHILD_STOPPED" : "CHILD_NEEDS_REVIEW",
+            swarmId: state.record.swarmId,
+            timestamp: terminal.recordedAt,
+            parentPolicyVersion: state.record.parentContract.policyVersion,
+            taskId: registration.taskId,
+            agentId: registration.agentId,
+            childRunId: registration.childRunId,
+            payload: Object.freeze({ reason, processCloseState: closure.state, leaseState })
+        });
+        terminalEvidence.push(terminal);
+        childEvents.push(childEvent);
+        try {
+            await registration.evidenceWriter.persistBeforeCleanup({
+                terminal,
+                childEvent,
+                budgetLedger: cloneLedger(ledger),
+                cleanupIntent: {
+                    workspaceId: registration.workspace.record.workspaceId,
+                    workspaceKind: "child",
+                    force: true
+                }
+            });
+            persisted.add(registration.childRunId);
+        }
+        catch {
+            unresolved.add(registration.childRunId);
+        }
+    }
+    const cleanupEvidence = [];
+    for (const { registration, closure } of closures) {
+        if (closure.state !== "closed" || !persisted.has(registration.childRunId))
+            continue;
+        let cleanup;
+        try {
+            cleanup = await state.input.workspaceManager.removeWorkspace(registration.workspace, {
+                evidencePersisted: true,
+                processTreeClosed: true,
+                force: true
+            });
+        }
+        catch (error) {
+            cleanup = failedCleanupRecord(state, registration, error, now, state.input.createCleanupId);
+        }
+        cleanupEvidence.push(cleanup);
+        if (cleanup.state !== "completed")
+            unresolved.add(registration.childRunId);
+        try {
+            await state.input.evidenceStore.persistCleanupEvidence(cleanup);
+        }
+        catch {
+            unresolved.add(registration.childRunId);
+        }
+    }
+    const completedAt = now();
+    let record = buildTerminalRecord(state.record, closures, childEvents, ledger, unresolved, reason, completedAt);
+    try {
+        await state.input.evidenceStore.persistTerminalRecord(record);
+    }
+    catch {
+        unresolved.add("parent-record");
+        record = buildTerminalRecord(state.record, closures, childEvents, ledger, unresolved, reason, completedAt);
+    }
+    const finalState = unresolved.size === 0 ? "stopped" : "needs_review";
+    state.record = record;
+    return Object.freeze({
+        acceptingWork: false,
+        state: finalState,
+        record,
+        terminalEvidence: Object.freeze(terminalEvidence),
+        cleanupEvidence: Object.freeze(cleanupEvidence),
+        unresolvedChildRunIds: Object.freeze([...unresolved].sort())
+    });
+}
+function buildTerminalRecord(record, closures, childEvents, ledger, unresolved, reason, completedAt) {
+    const terminalState = unresolved.size === 0 ? "stopped" : "needs_review";
+    const unresolvedChildRunIds = [...unresolved].sort();
+    const terminalEvent = Object.freeze({
+        type: terminalState === "stopped" ? "SWARM_STOPPED" : "SWARM_NEEDS_REVIEW",
+        swarmId: record.swarmId,
+        timestamp: completedAt,
+        parentPolicyVersion: record.parentContract.policyVersion,
+        payload: Object.freeze({ reason, unresolvedChildRunIds })
+    });
+    return cloneRecord({
+        ...record,
+        budgetLedger: ledger,
+        agents: record.agents.map((agent) => {
+            const registration = closures.find(({ registration: candidate }) => candidate.agentId === agent.agentId)?.registration;
+            return registration
+                ? { ...agent, status: unresolved.has(registration.childRunId) ? "needs_review" : "stopped" }
+                : { ...agent };
+        }),
+        tasks: record.tasks.map((task) => {
+            const registration = closures.find(({ registration: candidate }) => candidate.taskId === task.taskId)?.registration;
+            return registration
+                ? { ...task, status: unresolved.has(registration.childRunId) ? "needs_review" : "stopped" }
+                : { ...task };
+        }),
+        outcome: {
+            state: terminalState,
+            reason: terminalState === "stopped"
+                ? "Parent cancellation completed after process closure and evidence-safe cleanup."
+                : unresolved.has("parent-record")
+                    ? "Terminal parent evidence could not be persisted."
+                    : "Parent cancellation retained unresolved process, evidence, lease, or cleanup state."
+        },
+        events: [...record.events, ...childEvents, terminalEvent],
+        updatedAt: completedAt
+    });
+}
+function authority(controller) {
+    const state = controllerAuthority.get(controller);
+    if (!state)
+        throw new Error("Unknown swarm lifecycle authority.");
+    return state;
+}
+function assertRegistration(state, registration) {
+    const agent = state.record.agents.find((candidate) => candidate.agentId === registration.agentId);
+    const task = state.record.tasks.find((candidate) => candidate.taskId === registration.taskId);
+    const lease = state.record.budgetLedger.leases.find((candidate) => candidate.leaseId === registration.leaseId);
+    if (registration.swarmId !== state.record.swarmId
+        || registration.workspace.record.kind !== "child"
+        || registration.workspace.record.swarmId !== state.record.swarmId
+        || registration.workspace.record.childRunId !== registration.childRunId
+        || registration.workspace.record.agentId !== registration.agentId
+        || !registration.workspace.record.taskIds.includes(registration.taskId)
+        || agent?.childRunId !== registration.childRunId
+        || !agent.contract.taskIds.includes(registration.taskId)
+        || task?.assignedAgentId !== registration.agentId
+        || lease?.agentId !== registration.agentId
+        || lease.taskId !== registration.taskId
+        || state.registrations.has(registration.childRunId))
+        throw new Error("Active swarm child registration is duplicate or authority-mismatched.");
+}
+function failedCleanupRecord(state, registration, error, now, createCleanupId) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code ?? "WORKSPACE_REMOVE_FAILED")
+        : "WORKSPACE_REMOVE_FAILED";
+    return Object.freeze({
+        schemaVersion: SWARM_SCHEMA_VERSION,
+        cleanupId: createCleanupId?.() ?? `cleanup-failed-${registration.workspace.record.workspaceId}`,
+        swarmId: state.record.swarmId,
+        workspaceId: registration.workspace.record.workspaceId,
+        workspaceKind: "child",
+        evidencePersisted: true,
+        processCloseState: "closed",
+        removalState: "failed",
+        state: code === "EPERM" || code === "EBUSY" ? "cleanup_pending" : "failed",
+        attemptedAt: now(),
+        errorCode: code
+    });
+}
+function cloneLedger(ledger) {
+    return {
+        ...ledger,
+        leases: ledger.leases.map((lease) => ({
+            ...lease,
+            ...(lease.actualUsage ? { actualUsage: { ...lease.actualUsage } } : {})
+        }))
+    };
+}
+function cloneRecord(record) {
+    return JSON.parse(JSON.stringify(record));
+}

package/dist/vendor/core/swarm/live-runtime.d.ts

@@ -0,0 +1,78 @@
+import { type SwarmAgentRecord, type SwarmEvent, type SwarmLiveEngineProfile, type SwarmLivePlan, type SwarmOutcome, type SwarmRunRecord, type SwarmTaskNode } from "../../contracts/index.js";
+import { type MartinAdapter } from "../index.js";
+export { readSwarmReceiptProjection, verifySwarmReceiptProjection, type SwarmReceiptProjection, } from "./receipt-projection.js";
+import { type CaptureSwarmCandidateInput, type CaptureSwarmCandidateResult, type SwarmCandidateArtifactWriter, type SwarmProcessClosureEvidence } from "./candidates.js";
+import { type ParentSwarmPipelineEvidenceStore, type PersistedSwarmChildCompletionEvidence, type RunParentSwarmPipelineInput, type RunParentSwarmPipelineResult } from "./index.js";
+import type { SwarmChildLifecycleEvidenceWriter, SwarmLifecycleEvidenceStore } from "./lifecycle.js";
+import { type SwarmLiveStore } from "./live-store.js";
+import type { SwarmVerifierExecutor } from "./verification.js";
+import { type SwarmWorkspaceManager, type SwarmWorkspaceRuntimeHandle } from "./workspaces.js";
+export interface SwarmChildAdapterFactoryInput {
+    readonly engine: SwarmLiveEngineProfile;
+    readonly task: SwarmTaskNode;
+    readonly agent: SwarmAgentRecord;
+    readonly childRunId: string;
+    readonly workspace: SwarmWorkspaceRuntimeHandle;
+    readonly budget: SwarmAgentRecord["contract"]["budget"];
+}
+export interface SwarmChildAdapterHandle {
+    readonly adapter: MartinAdapter;
+    /** Required for write tasks and must exactly match the Git-observed delta. */
+    readonly declaredPaths: readonly string[];
+}
+export type SwarmChildAdapterFactory = (input: SwarmChildAdapterFactoryInput) => MartinAdapter | SwarmChildAdapterHandle;
+export interface SwarmLiveRuntimeEvidenceStore extends ParentSwarmPipelineEvidenceStore, SwarmCandidateArtifactWriter, SwarmLifecycleEvidenceStore, SwarmChildLifecycleEvidenceWriter {
+    persistProcessClosure(evidence: SwarmProcessClosureEvidence): Promise<void>;
+    persistChildCompletion(evidence: PersistedSwarmChildCompletionEvidence): Promise<void>;
+}
+export interface RunLiveSwarmInput {
+    readonly plan: SwarmLivePlan;
+    readonly liveStore: SwarmLiveStore;
+    readonly workspaceManager: SwarmWorkspaceManager;
+    readonly evidenceStore: SwarmLiveRuntimeEvidenceStore;
+    readonly adapterFactory: SwarmChildAdapterFactory;
+    readonly verifierExecutor: SwarmVerifierExecutor;
+    readonly runsRoot: string;
+    signal?: AbortSignal;
+    readonly now?: () => string;
+    readonly createId?: (prefix: string) => string;
+    readonly nowMs?: () => number;
+}
+export interface RunLiveSwarmResult {
+    readonly record: SwarmRunRecord;
+    readonly outcome: SwarmOutcome;
+    readonly candidateIds: readonly string[];
+    readonly parent?: RunParentSwarmPipelineResult;
+}
+/** Checks in-process Core authority; structurally forged CLI/test objects cannot pass. */
+export declare function isAuthoritativeLiveSwarmVerified(result: RunLiveSwarmResult): boolean;
+export interface RunProductionLiveSwarmInput {
+    readonly plan: SwarmLivePlan;
+    readonly canonicalRoot: string;
+    readonly ownedRoot: string;
+    readonly storeRoot: string;
+    readonly runsRoot: string;
+    readonly workspaceIsolationMode?: "worktree" | "independent_clone";
+    readonly adapterFactory: SwarmChildAdapterFactory;
+    readonly verifierExecutor: SwarmVerifierExecutor;
+    signal?: AbortSignal;
+}
+interface LiveRuntimeDependencies {
+    captureCandidate(input: CaptureSwarmCandidateInput): Promise<CaptureSwarmCandidateResult>;
+    inventoryCandidatePaths(workspacePath: string): Promise<string[]>;
+    parentPipeline(input: RunParentSwarmPipelineInput): Promise<RunParentSwarmPipelineResult>;
+    sealTerminal?(result: RunLiveSwarmResult): Promise<void>;
+}
+/** Public high-level live entrypoint. Raw lifecycle and finalization authority stay internal. */
+export declare function runLiveSwarm(input: RunLiveSwarmInput): Promise<RunLiveSwarmResult>;
+/**
+ * Production composition boundary for CLI/operator callers. It accepts only
+ * validated operator paths plus narrow child/verifier executors. Raw store,
+ * worktree, evidence, lifecycle, and parent-finalization authority remain
+ * inside Core and are never exported from the package root.
+ */
+export declare function runProductionLiveSwarm(input: RunProductionLiveSwarmInput): Promise<RunLiveSwarmResult>;
+/** Internal test seam; intentionally not re-exported from the Core package root. */
+export declare function runLiveSwarmWithDependencies(input: RunLiveSwarmInput, dependencies: LiveRuntimeDependencies): Promise<RunLiveSwarmResult>;
+/** Internal production identity seam; intentionally not exported from the Core root. */
+export declare function sameCanonicalSwarmEvent(left: SwarmEvent, right: SwarmEvent): boolean;