@martinloop/mcp 0.7.1 → 0.8.0

package/dist/vendor/contracts/swarm.d.ts

@@ -0,0 +1,449 @@
+import type { ApprovalPolicy, FailureClass, LoopBudget, ReceiptIntegrityState, VerificationStep } from "./index.js";
+export declare const SWARM_SCHEMA_VERSION: "martin.swarm.v1";
+export declare const SWARM_EVENT_TYPES: readonly ["SWARM_CREATED", "SWARM_PLAN_CREATED", "SWARM_PLAN_APPROVED", "TASK_READY", "TASK_ASSIGNED", "CHILD_STARTED", "CHILD_PROGRESS", "CHILD_VERIFIER_STARTED", "CHILD_VERIFIED", "CHILD_STOPPED", "CHILD_NEEDS_REVIEW", "CHILD_PATCH_PROPOSED", "CHILD_PATCH_REJECTED", "CHILD_PATCH_ADMITTED", "ACTION_BLOCKED", "TASK_REASSIGNED", "DEPENDENCY_SATISFIED", "INTEGRATION_STARTED", "INTEGRATION_CONFLICT", "INTEGRATION_COMPLETED", "GLOBAL_VERIFIER_STARTED", "GLOBAL_VERIFIER_PASSED", "GLOBAL_VERIFIER_FAILED", "SWARM_CANCEL_REQUESTED", "SWARM_STOPPED", "SWARM_NEEDS_REVIEW", "SWARM_VERIFIED"];
+export type SwarmEventType = (typeof SWARM_EVENT_TYPES)[number];
+export declare const SWARM_ORCHESTRATION_STRATEGIES: readonly ["hierarchical_dag", "pipeline_dag", "parallel_dag", "hybrid"];
+export type SwarmOrchestrationStrategy = (typeof SWARM_ORCHESTRATION_STRATEGIES)[number];
+export type SwarmIntegrationStrategy = "parent_fan_in" | "serial_parent_merge";
+export type SwarmStopDisposition = "stop" | "needs_review";
+export type SwarmVerifierAuthority = "child_only" | "parent_global";
+export interface SwarmScope {
+    allowedPaths: string[];
+    deniedPaths: string[];
+}
+export interface SwarmPermissions {
+    networkDomains: string[];
+    commands: string[];
+}
+export interface SwarmStopPolicy {
+    budgetExhausted: SwarmStopDisposition;
+    blockingFailure: SwarmStopDisposition;
+    verifierFailure: SwarmStopDisposition;
+}
+export interface SwarmRecoveryPolicy {
+    maxReassignmentsPerTask: number;
+    dependencyWaiversAllowed: boolean;
+}
+export interface SwarmParentContract {
+    policyVersion: string;
+    objective: string;
+    definitionOfDone: string[];
+    budget: LoopBudget;
+    maxWallClockMs: number;
+    maxConcurrency: number;
+    scope: SwarmScope;
+    permissions: SwarmPermissions;
+    integrationStrategy: SwarmIntegrationStrategy;
+    globalVerifierStack: VerificationStep[];
+    stopPolicy: SwarmStopPolicy;
+    recoveryPolicy: SwarmRecoveryPolicy;
+    approvalPolicy: ApprovalPolicy;
+    orchestrationStrategy: SwarmOrchestrationStrategy;
+}
+export interface SwarmChildContract {
+    agentId: string;
+    taskIds: string[];
+    scope: SwarmScope;
+    budget: LoopBudget;
+    /** Optional explicit child ceiling, distinct from its initial fair-share reservation. */
+    hardMaxUsd?: number;
+    /** Optional explicit child ceiling, distinct from its initial fair-share reservation. */
+    hardMaxTokens?: number;
+    maxWallClockMs: number;
+    permissions: SwarmPermissions;
+    approvalPolicy: ApprovalPolicy;
+    verifierAuthority: SwarmVerifierAuthority;
+}
+export interface SwarmChildReceiptLink {
+    parentSwarmId: string;
+    agentId: string;
+    attemptId: string;
+    taskIds: string[];
+}
+export type SwarmTaskStatus = "queued" | "ready" | "running" | "accepted" | "rejected" | "stopped" | "needs_review";
+export interface SwarmTaskNode {
+    taskId: string;
+    title: string;
+    objective: string;
+    required: boolean;
+    dependsOn: string[];
+    assignedAgentId?: string;
+    status: SwarmTaskStatus;
+    mutationMode: "read_only" | "write";
+    writeScope: string[];
+}
+export interface SwarmDependencyWaiver {
+    taskId: string;
+    dependencyTaskId: string;
+    parentPolicyVersion: string;
+    approvedBy: string;
+    approvedAt: string;
+}
+export type SwarmAgentStatus = "queued" | "running" | "verified" | "stopped" | "needs_review";
+export interface SwarmAgentRecord {
+    agentId: string;
+    role: string;
+    status: SwarmAgentStatus;
+    childRunId?: string;
+    contract: SwarmChildContract;
+    failureClass?: FailureClass;
+}
+export type SwarmLeaseStatus = "reserved" | "settled" | "overspent" | "released";
+export interface SwarmBudgetUsage {
+    usd: number;
+    tokens: number;
+    provenance?: string;
+}
+export interface SwarmBudgetLease {
+    leaseId: string;
+    agentId: string;
+    taskId: string;
+    reservedUsd: number;
+    reservedTokens: number;
+    status: SwarmLeaseStatus;
+    actualUsage?: SwarmBudgetUsage;
+}
+export interface SwarmBudgetLedger {
+    capUsd: number;
+    capTokens?: number;
+    settledUsd: number;
+    settledTokens: number;
+    leases: SwarmBudgetLease[];
+}
+export interface SwarmConflictRecord {
+    conflictId: string;
+    taskIds: string[];
+    paths: string[];
+    state: "detected" | "resolved" | "blocking";
+    resolution?: string;
+    schemaVersion?: typeof SWARM_SCHEMA_VERSION;
+    candidateId?: string;
+    childRunId?: string;
+    agentId?: string;
+    preIntegrationTreeHash?: string;
+    recordedAt?: string;
+    diagnostic?: string;
+}
+export interface SwarmVerificationRecord {
+    verifierId: string;
+    scope: "child" | "parent_global";
+    state: "pending" | "passed" | "failed" | "unknown";
+    steps: VerificationStep[];
+    boundAt?: string;
+}
+export type SwarmWorkspaceKind = "child" | "integration" | "verifier";
+export type SwarmWorkspaceState = "created" | "active" | "closed" | "cleanup_pending" | "removed";
+interface SwarmWorkspaceRecordBase {
+    readonly schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    readonly workspaceId: string;
+    readonly swarmId: string;
+    readonly kind: SwarmWorkspaceKind;
+    readonly baselineCommit: string;
+    readonly state: SwarmWorkspaceState;
+    readonly createdAt: string;
+}
+export interface SwarmChildWorkspaceRecord extends SwarmWorkspaceRecordBase {
+    readonly kind: "child";
+    readonly childRunId: string;
+    readonly agentId: string;
+    readonly taskIds: readonly string[];
+}
+export interface SwarmIntegrationWorkspaceRecord extends SwarmWorkspaceRecordBase {
+    readonly kind: "integration";
+}
+export interface SwarmVerifierWorkspaceRecord extends SwarmWorkspaceRecordBase {
+    readonly kind: "verifier";
+}
+export type SwarmWorkspaceRecord = SwarmChildWorkspaceRecord | SwarmIntegrationWorkspaceRecord | SwarmVerifierWorkspaceRecord;
+export interface SwarmCandidate {
+    readonly schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    readonly candidateId: string;
+    readonly swarmId: string;
+    readonly workspaceId: string;
+    readonly childRunId: string;
+    readonly agentId: string;
+    readonly taskIds: readonly string[];
+    readonly baselineCommit: string;
+    readonly patchSha256: string;
+    readonly changedPaths: readonly string[];
+    readonly createdAt: string;
+}
+export type SwarmPatchAdmissionState = "admitted" | "rejected";
+export type SwarmPatchAdmissionReasonCode = "admitted" | "child_not_terminal" | "process_active" | "identity_mismatch" | "receipt_not_verified" | "receipt_scope_mismatch" | "stale_baseline" | "git_inventory_failed" | "invalid_concrete_path" | "unsafe_path" | "undeclared_path" | "path_not_allowed" | "path_denied" | "task_scope_violation" | "candidate_changed_during_capture" | "empty_candidate" | "patch_hash_mismatch" | "integration_precondition_failed" | "integration_conflict" | "integration_apply_failed" | "artifact_persistence_failed";
+export interface SwarmPatchAdmission {
+    readonly schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    readonly admissionId: string;
+    readonly candidateId: string;
+    readonly swarmId: string;
+    readonly workspaceId: string;
+    readonly childRunId: string;
+    readonly agentId: string;
+    readonly taskIds: readonly string[];
+    readonly baselineCommit: string;
+    readonly changedPaths: readonly string[];
+    readonly state: SwarmPatchAdmissionState;
+    readonly reasonCode: SwarmPatchAdmissionReasonCode;
+    readonly receiptIntegrity: ReceiptIntegrityState;
+    readonly decidedAt: string;
+    readonly preIntegrationTreeHash?: string;
+    readonly postIntegrationTreeHash?: string;
+    readonly diagnostic?: string;
+}
+export type SwarmGlobalVerificationCommandState = "pending" | "passed" | "failed" | "unknown";
+export type SwarmVerifierMutationState = "pending" | "clean" | "mutated" | "unknown";
+export interface SwarmVerifierSubprocessResult {
+    readonly command: string;
+    readonly launched: boolean;
+    readonly completed: boolean;
+    readonly timedOut: boolean;
+    readonly exitCode: number | null;
+    readonly signal?: string;
+    readonly startedAt: string;
+    readonly completedAt?: string;
+}
+export interface SwarmGlobalVerification {
+    readonly schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    readonly verificationId: string;
+    readonly swarmId: string;
+    readonly workspaceId: string;
+    readonly parentPolicyVersion: string;
+    readonly baselineCommit: string;
+    readonly integratedTreeHash: string;
+    readonly commands: readonly string[];
+    readonly commandState: SwarmGlobalVerificationCommandState;
+    readonly mutationState: SwarmVerifierMutationState;
+    readonly startedAt: string;
+    readonly completedAt?: string;
+    readonly subprocessResults: readonly SwarmVerifierSubprocessResult[];
+}
+export type SwarmProcessCloseState = "not_required" | "pending" | "closed" | "failed";
+export type SwarmWorkspaceRemovalState = "pending" | "removed" | "failed";
+export type SwarmCleanupState = "pending" | "completed" | "failed" | "cleanup_pending";
+export interface SwarmCleanupRecord {
+    readonly schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    readonly cleanupId: string;
+    readonly swarmId: string;
+    readonly workspaceId: string;
+    readonly workspaceKind: SwarmWorkspaceKind;
+    readonly ownedProcessId?: number;
+    readonly evidencePersisted: boolean;
+    readonly processCloseState: SwarmProcessCloseState;
+    readonly removalState: SwarmWorkspaceRemovalState;
+    readonly state: SwarmCleanupState;
+    readonly attemptedAt: string;
+    readonly completedAt?: string;
+    readonly errorCode?: string;
+}
+export type SwarmDemoReferentialBindingState = "passed" | "failed" | "unknown";
+export interface SwarmDeterministicDemoReceiptEvidence {
+    evidenceKind: "deterministic_demo";
+    swarmId: string;
+    agentId: string;
+    taskIds: string[];
+    childRunId: string;
+    referentialBinding: SwarmDemoReferentialBindingState;
+    signedIntegrity: "not_evaluated";
+}
+export type SwarmOutcomeState = "running" | "stopped" | "needs_review" | "verified";
+export interface SwarmOutcome {
+    state: SwarmOutcomeState;
+    reason: string;
+    verifiedAt?: string;
+}
+export interface SwarmEvent {
+    type: SwarmEventType;
+    swarmId: string;
+    timestamp: string;
+    parentPolicyVersion: string;
+    taskId?: string;
+    agentId?: string;
+    childRunId?: string;
+    payload: Record<string, unknown>;
+}
+export interface SwarmRunRecord {
+    schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    swarmId: string;
+    workspaceId: string;
+    projectId: string;
+    parentContract: SwarmParentContract;
+    tasks: SwarmTaskNode[];
+    agents: SwarmAgentRecord[];
+    dependencyWaivers: SwarmDependencyWaiver[];
+    budgetLedger: SwarmBudgetLedger;
+    conflicts: SwarmConflictRecord[];
+    verification: SwarmVerificationRecord[];
+    outcome: SwarmOutcome;
+    events: SwarmEvent[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SwarmRunDraft {
+    swarmId: string;
+    workspaceId: string;
+    projectId: string;
+    parentContract: SwarmParentContract;
+    tasks: SwarmTaskNode[];
+    agents: SwarmAgentRecord[];
+    dependencyWaivers?: SwarmDependencyWaiver[];
+    budgetLedger?: SwarmBudgetLedger;
+    conflicts?: SwarmConflictRecord[];
+    verification?: SwarmVerificationRecord[];
+    outcome?: SwarmOutcome;
+    events?: SwarmEvent[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+export declare const SWARM_LIVE_ENGINES: readonly ["claude", "codex", "gemini", "openai"];
+export type SwarmLiveEngine = (typeof SWARM_LIVE_ENGINES)[number];
+export interface SwarmLiveEngineProfile {
+    engine: SwarmLiveEngine;
+    model: string;
+}
+export interface SwarmLivePlanDraft {
+    planId: string;
+    swarmId: string;
+    workspaceId: string;
+    projectId: string;
+    baselineCommit: string;
+    parentContract: SwarmParentContract;
+    tasks: SwarmTaskNode[];
+    agents: SwarmAgentRecord[];
+    engine: SwarmLiveEngineProfile;
+    childMaxIterations: number;
+    createdAt: string;
+}
+export interface SwarmLivePlan extends SwarmLivePlanDraft {
+    schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    planHash: string;
+}
+export type SwarmLiveRevision = number;
+export interface SwarmLiveEvent {
+    schemaVersion: typeof SWARM_SCHEMA_VERSION;
+    sequence: number;
+    idempotencyKey: string;
+    type: SwarmEventType;
+    swarmId: string;
+    timestamp: string;
+    parentPolicyVersion: string;
+    planHash: string;
+    taskId?: string;
+    agentId?: string;
+    childRunId?: string;
+    failureClass?: FailureClass;
+    payload: Record<string, unknown>;
+}
+export declare const SWARM_PARENT_RECEIPT_SCHEMA_VERSION: "martin.swarm-receipt.v1";
+export interface SwarmReceiptBlockedAction {
+    eventId: string;
+    sequence: number;
+    agentId: string;
+    taskId: string;
+    attemptId: string;
+    action: string;
+    reason: string;
+    timestamp: string;
+}
+export interface SwarmReceiptReassignment {
+    eventId: string;
+    sequence: number;
+    taskId: string;
+    fromAgentId: string;
+    toAgentId: string;
+    fromAttemptId: string;
+    toAttemptId: string;
+    reason: string;
+    timestamp: string;
+}
+export interface SwarmParentReceipt {
+    schemaVersion: typeof SWARM_PARENT_RECEIPT_SCHEMA_VERSION;
+    receiptId: string;
+    receiptSha256: string;
+    swarmId: string;
+    planHash: string;
+    objective: string;
+    engine: SwarmLiveEngineProfile;
+    baselineCommit: string;
+    tasks: SwarmTaskNode[];
+    agents: SwarmAgentRecord[];
+    budget: LoopBudget;
+    budgetLedger: SwarmBudgetLedger;
+    childReceipts: Array<{
+        childRunId: string;
+        agentId: string;
+        attemptId: string;
+        taskIds: string[];
+        receiptIntegritySha256: string;
+    }>;
+    blockedActions: SwarmReceiptBlockedAction[];
+    reassignments: SwarmReceiptReassignment[];
+    events: SwarmLiveEvent[];
+    evidenceIndexSha256: string;
+    evidenceFiles: Array<{
+        kind: "operational" | "artifact";
+        path: string;
+        sha256: string;
+        bytes: number;
+    }>;
+    evidenceBindings: {
+        admissions: string[];
+        rejections: string[];
+        conflicts: string[];
+        integration: string[];
+        globalVerification: string[];
+        cleanup: string[];
+    };
+    integratedTreeHash?: string;
+    globalVerificationId?: string;
+    parentOutcome: Omit<SwarmOutcome, "state"> & {
+        state: Exclude<SwarmOutcomeState, "running">;
+    };
+    taskVerificationState: "passed" | "failed" | "unknown";
+    sealedAt: string;
+}
+export interface SwarmValidationError {
+    code: string;
+    path: string;
+    message: string;
+}
+export type SwarmValidationResult = {
+    ok: true;
+    errors: [];
+} | {
+    ok: false;
+    errors: SwarmValidationError[];
+};
+export type SwarmPathPatternResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type SwarmConcretePathResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateSwarmChildReceiptLink(value: unknown): SwarmValidationResult;
+export declare function createSwarmLivePlan(draft: SwarmLivePlanDraft): SwarmLivePlan;
+export declare function computeSwarmLivePlanHash(plan: SwarmLivePlan | (SwarmLivePlanDraft & {
+    schemaVersion?: typeof SWARM_SCHEMA_VERSION;
+})): string;
+export declare function validateSwarmLiveRevision(value: unknown): value is SwarmLiveRevision;
+export declare function validateSwarmLivePlan(plan: SwarmLivePlan): SwarmValidationResult;
+export declare function validateSwarmLiveEvent(event: SwarmLiveEvent, plan: SwarmLivePlan): SwarmValidationResult;
+export declare function validateSwarmConcretePath(value: string): SwarmConcretePathResult;
+export declare function swarmConcretePathMatchesPattern(concretePath: string, pattern: string): boolean;
+export declare function normalizeSwarmPathPattern(value: string): SwarmPathPatternResult;
+export declare function swarmPathPatternContains(parent: string, child: string): boolean;
+export declare function swarmPathPatternsOverlap(left: string, right: string): boolean;
+export declare function validateSwarmParentContract(parent: SwarmParentContract): SwarmValidationResult;
+export declare function validateSwarmDeterministicDemoReceiptEvidence(evidence: SwarmDeterministicDemoReceiptEvidence): SwarmValidationResult;
+export declare function validateSwarmChildContract(parent: SwarmParentContract, child: SwarmChildContract): SwarmValidationResult;
+export declare function createSwarmRunRecord(draft: SwarmRunDraft, options?: {
+    now?: string;
+}): SwarmRunRecord;
+export declare function validateSwarmRunRecord(record: SwarmRunRecord): SwarmValidationResult;
+export {};