agentic-engineering-harness 0.14.2 → 0.15.1

package/dist/releases/release-1791270099283-18794-a3ada60d/runtime/operationResources.d.ts

@@ -0,0 +1,317 @@
+import { recordPaseoTrace } from "../paseo/trace.js";
+import { runShell } from "../utils/process.js";
+import { type OperationStatus } from "../operations/state.js";
+export declare const operationResourceKinds: readonly ["paseo-workspace", "paseo-agent", "provider-session", "managed-process", "staging-root"];
+export type OperationResourceKindV1 = (typeof operationResourceKinds)[number];
+export declare const operationResourceStates: readonly ["OWNED", "ARCHIVED", "RELEASED", "TERMINATED", "REMOVED"];
+export type OperationResourceStateV1 = (typeof operationResourceStates)[number];
+export declare const operationResourceClassifications: readonly ["LIVE_OWNED", "TERMINAL_ORPHAN", "UNKNOWN_OR_UNOWNED"];
+export type OperationResourceClassificationV1 = (typeof operationResourceClassifications)[number];
+export declare const operationResourceReclaimPolicies: readonly ["ARCHIVE_ON_TERMINAL", "STOP_ON_TERMINAL", "TERMINATE_ON_TERMINAL", "REMOVE_ON_TERMINAL", "RETAIN_SHARED"];
+export type OperationResourceReclaimPolicyV1 = (typeof operationResourceReclaimPolicies)[number];
+/** Durable ownership entry. Identity and operation binding are the only authority. */
+export interface OperationResourceV1 {
+    version: 1;
+    resourceId: string;
+    kind: OperationResourceKindV1;
+    identity: string;
+    operationId: string;
+    reclaim: OperationResourceReclaimPolicyV1;
+    path?: string;
+    label?: string;
+    owner: {
+        candidateDigest?: string;
+        operationExecutionRevision?: number;
+        controllerEpoch?: number;
+        participantId?: string;
+        participantGeneration?: string;
+        supervisorAgentId?: string;
+        leaseId?: string;
+        source: "controller-registration" | "operation-record" | "provider-lease" | "managed-process-handle";
+    };
+    createdAt: string;
+    state: OperationResourceStateV1;
+    releasedAt?: string;
+    releaseEvidence?: Record<string, unknown>;
+}
+export interface OperationResourceRegistryV1 {
+    version: 1;
+    operationId: string;
+    updatedAt: string;
+    resources: OperationResourceV1[];
+}
+export interface OperationResourcePolicyV1 {
+    maxOwnedResourcesPerOperation: number;
+    maxConcurrentProviderSessionsPerOperation: number;
+}
+export declare const DEFAULT_OPERATION_RESOURCE_POLICY: OperationResourcePolicyV1;
+/**
+ * Provider backpressure QUEUE helpers (Unit 3).
+ *
+ * MECHANISM: DETERMINISTIC for classification; bounded polling for waits.
+ * `assertProviderSessionCapacity` keeps its throwing fail-closed contract.
+ * `checkProviderSessionBackpressure` is the pure QUEUE classifier; waits are
+ * bounded (`PROVIDER_BACKPRESSURE_MAX_WAIT_MS_V1`) and always count against
+ * the caller's existing deadline (never extend caps; exhausted waits are
+ * terminal). Telemetry attributes follow existing `recordEvent` conventions
+ * (bounded counter/gauge observation, never a gate).
+ */
+export declare const PROVIDER_BACKPRESSURE_MAX_WAIT_MS_V1 = 30000;
+export declare const PROVIDER_BACKPRESSURE_POLL_MS_V1 = 50;
+export declare const PROVIDER_BACKPRESSURE_EVENT_V1 = "harness.provider.backpressure";
+export type ProviderSessionBackpressureV1 = {
+    allowed: true;
+    active: number;
+    ceiling: number;
+} | {
+    allowed: false;
+    disposition: "QUEUE";
+    active: number;
+    ceiling: number;
+    retryAfterMs: number;
+};
+export interface ProviderBackpressureTelemetryV1 {
+    operationId: string;
+    active: number;
+    ceiling: number;
+    queued: number;
+    retryAfterMs: number;
+    disposition: "QUEUE" | "PROCEED";
+}
+export interface OperationResourceReconcileDeps {
+    run?: typeof runShell;
+    inspectAgent?: (root: string, agentId: string) => Promise<{
+        status?: string;
+        workspaceId?: string;
+    } | undefined>;
+    archiveAgent?: (root: string, agentId: string) => Promise<void>;
+    archiveWorkspace?: (root: string, workspaceId: string) => Promise<void>;
+    terminateProcess?: (pid: number) => Promise<void>;
+    removeStagingRoot?: (target: string) => Promise<void>;
+    /** Durable label-bound ownership discovery (`aeh.operation` is minted only by this product). */
+    listOwnedAgents?: (root: string, operationId: string) => Promise<Array<{
+        id?: string;
+        workspaceId?: string;
+    }>>;
+    trace?: typeof recordPaseoTrace;
+    now?: () => Date;
+}
+export interface OperationResourceDispositionV1 {
+    resourceId: string;
+    kind: OperationResourceKindV1;
+    identity: string;
+    classification: OperationResourceClassificationV1;
+    reclaim: OperationResourceReclaimPolicyV1;
+    action: "preserve" | "archive" | "stop+archive" | "terminate" | "remove" | "already-reconciled" | "none";
+    outcome: "preserved-live" | "preserved-unowned" | "preserved-shared" | "reconciled" | "already-reconciled" | "failed";
+    alreadyReconciled: boolean;
+    error?: string;
+}
+export interface OperationResourceReconciliationReceiptV1 {
+    version: 1;
+    kind: "operation-resource-reconciliation";
+    operationId: string;
+    operationStatus: OperationStatus;
+    operationTerminal: boolean;
+    candidateDigest?: string;
+    operationExecutionRevision?: number;
+    controllerEpoch?: number;
+    reconciledAt: string;
+    classification: {
+        liveOwned: number;
+        terminalOrphans: number;
+        unknownOrUnowned: number;
+    };
+    dispositions: OperationResourceDispositionV1[];
+    terminalOrphansRemaining: number;
+    cleanupComplete: boolean;
+    errors: string[];
+}
+export interface OperationResourceSweepResultV1 {
+    version: 1;
+    sweptAt: string;
+    operationsScanned: number;
+    terminalOperationsReconciled: number;
+    terminalOperationsCurrent: number;
+    liveOperationsPreserved: number;
+    failures: Array<{
+        operationId: string;
+        error: string;
+    }>;
+}
+export declare function operationResourcePolicy(config: {
+    orchestration?: unknown;
+} | undefined): OperationResourcePolicyV1;
+export declare function operationResourceRegistryFile(root: string, operationId: string): string;
+export declare function operationResourceReceiptFile(root: string, operationId: string): string;
+export declare function operationResourceId(operationId: string, kind: OperationResourceKindV1, identity: string): string;
+/**
+ * Register one durably owned resource for the current operation. Registration is
+ * idempotent by (kind, identity) and refuses to exceed the configured generic
+ * per-operation resource ceiling (typed `RESOURCE_CEILING_EXHAUSTED`).
+ */
+export declare function registerOperationResource(root: string, operationId: string, input: {
+    kind: OperationResourceKindV1;
+    identity: string;
+    reclaim?: OperationResourceReclaimPolicyV1;
+    path?: string;
+    label?: string;
+    owner?: Partial<OperationResourceV1["owner"]>;
+}, options?: {
+    policy?: OperationResourcePolicyV1;
+    now?: () => Date;
+}): Promise<OperationResourceV1>;
+export declare function listOperationResources(root: string, operationId: string): Promise<OperationResourceV1[]>;
+/** Mark a registered resource released after the owner removed/released it in-line (idempotent). */
+export declare function markOperationResourceReleased(root: string, operationId: string, resourceId: string, evidence: Record<string, unknown>, options?: {
+    now?: () => Date;
+}): Promise<void>;
+export declare function readOperationResourceReceipt(root: string, operationId: string): Promise<OperationResourceReconciliationReceiptV1 | undefined>;
+/**
+ * Reconcile the durable resources of one operation.
+ *
+ * Only a durably terminal operation may release resources. A live/non-terminal
+ * operation is classified LIVE_OWNED and preserved; a resource without exact
+ * durable ownership proof is classified UNKNOWN_OR_UNOWNED and preserved. The
+ * same call on already released resources is a no-op that reports
+ * `alreadyReconciled` instead of failing.
+ */
+export declare function reconcileOperationResources(root: string, operationId: string, deps?: OperationResourceReconcileDeps): Promise<OperationResourceReconciliationReceiptV1>;
+/**
+ * Deterministic recovery sweep: reconcile every durably terminal operation in
+ * this control root with an incomplete resource receipt, and preserve every
+ * non-terminal operation without touching its resources.
+ */
+export declare function reconcileTerminalOperationResources(root: string, deps?: OperationResourceReconcileDeps): Promise<OperationResourceSweepResultV1>;
+/** Capacity check for concurrent provider sessions of one operation (policy-driven, generic). */
+export declare function assertProviderSessionCapacity(root: string, operationId: string, ceiling?: number): Promise<void>;
+/**
+ * Pure QUEUE classifier for provider session capacity. Returns QUEUE (not
+ * throw) when `active` meets or exceeds `ceiling`; callers honor the bounded
+ * WAIT against their existing deadline and treat exhaustion as terminal.
+ */
+export declare function checkProviderSessionBackpressure(active: number, ceiling?: number): ProviderSessionBackpressureV1;
+/** DETERMINISTIC classifier: true when the error is provider capacity/lease backpressure (QUEUE, not FAIL). */
+export declare function isProviderCapacityError(error: unknown): boolean;
+/**
+ * Bounded QUEUE wait for provider session capacity. Polls the durable lease
+ * snapshot without widening any ceiling; the total wait never exceeds
+ * `min(maxWaitMs, deadlineAtMs - now)` and an exhausted budget returns
+ * `acquired: false` (terminal, fail-closed). Injectable clock/sleep/snapshot
+ * keeps fixtures scripted with no network.
+ *
+ * MECHANISM: DETERMINISTIC. Never mints fresh time: when `deadlineAtMs` is
+ * undefined (no existing wave/operation deadline can be established) the wait
+ * does a single immediate check only (no sleep, no fresh 30s budget). Allowed
+ * headroom proceeds immediately (no wait needed); saturation returns terminal
+ * `acquired: false` with zero waits. Unreadable durability BLOCKS (terminal
+ * false, never passes as clear with active=0).
+ */
+export declare function waitForProviderSessionCapacity(root: string, operationId: string, options?: {
+    ceiling?: number;
+    deadlineAtMs?: number;
+    maxWaitMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    countActive?: () => Promise<number> | number;
+}): Promise<{
+    acquired: boolean;
+    waitedMs: number;
+    active: number;
+    ceiling: number;
+}>;
+/**
+ * Durable atomic wave-slot acquire-or-queue (Luna F2+F3, fail-closed).
+ *
+ * MECHANISM: DETERMINISTIC + file-locked transact (atomic w.r.t. shared store).
+ * ATOMICITY NOTE: `RuntimeSupervisorV1.acquire/tryAcquireProviderLease` is
+ * synchronous and therefore atomic within one process, but it is NOT atomic
+ * w.r.t. the shared durable snapshot file across waves/operations/processes
+ * (each wave used a fresh in-memory supervisor, blind by construction). The
+ * previous `checkDurableWaveSlotConflict` was read-only check-then-proceed
+ * (TOCTOU): two racers could both read empty and both proceed. It is deleted.
+ * This primitive is the REAL atomic lease path: one root-scoped `.lock` file
+ * serializes reload→check→write so concurrent callers never both proceed.
+ * The same `findConflictingProviderLeases` predicate as `tryAcquireProviderLease`
+ * is evaluated inside the lock; ACQUIRED persists the new lease atomically,
+ * QUEUED persists nothing.
+ *
+ * Fail-closed: missing file means no leases yet (empty snapshot, may ACQUIRE);
+ * corrupt/unreadable/invalid snapshot never proceeds (QUEUED-terminal, no write,
+ * no wait when retryAfter is 0). Missing/empty identity throws (never ACQUIRE).
+ * No fresh time: `remainingBudgetMs` undefined means single immediate attempt
+ * only (no sleep, no fresh 30s); defined budget bounds total WAIT via
+ * `min(retryAfter, remaining)`; exhaustion is terminal QUEUED (caller FAILs).
+ * Deterministic clocks via `nowMs`/`sleepMs`; observation-only telemetry via
+ * existing `recordEvent` conventions (callers emit, never gate on it).
+ */
+export interface DurableWaveSlotInputV1 {
+    provider: string;
+    projectId: string;
+    canonicalRoot: string;
+    workspaceId: string;
+    ownerId: string;
+    mode?: "read" | "write";
+    ttlMs?: number;
+}
+export interface DurableWaveSlotAcquiredV1 {
+    acquired: true;
+    leaseId: string;
+    retryAfterMs: number;
+    queueDepth: number;
+    scope: "shared-durable";
+}
+export interface DurableWaveSlotQueuedV1 {
+    acquired: false;
+    retryAfterMs: number;
+    queueDepth: number;
+    scope: "shared-durable";
+    reason: string;
+}
+export type DurableWaveSlotResultV1 = DurableWaveSlotAcquiredV1 | DurableWaveSlotQueuedV1;
+/**
+ * Single atomic attempt (lock → reload → check → write): lock wait honors the
+ * caller's remaining budget (`min(10s requested, remaining)`; exhausted or
+ * undefined → single immediate attempt, no wait, terminal on contention).
+ * Returns ACQUIRED with durable leaseId (persisted) or QUEUED (persisted nothing).
+ * Unreadable/invalid durability returns QUEUED-terminal (BLOCKED, retryAfter 0).
+ */
+export declare function tryAcquireDurableWaveSlotAtomic(snapshotRoot: string, input: DurableWaveSlotInputV1, options?: {
+    nowMs?: () => number;
+    leaseTtlMs?: number;
+    remainingBudgetMs?: number;
+    sleepMs?: (ms: number) => Promise<void>;
+}): Promise<DurableWaveSlotResultV1>;
+/**
+ * Atomic release (lock → reload → delete → write). Idempotent: missing lease
+ * returns silently. Owner mismatch throws fail-closed (caller treats as FAIL,
+ * best-effort in wave finally blocks).
+ */
+export declare function releaseDurableWaveSlot(snapshotRoot: string, leaseId: string, ownerId: string, options?: {
+    nowMs?: () => number;
+    remainingBudgetMs?: number;
+    sleepMs?: (ms: number) => Promise<void>;
+}): Promise<void>;
+/**
+ * Bounded atomic acquire-or-wait-or-fail (production wave path).
+ * Single immediate attempt when `remainingBudgetMs` is undefined or <=0 (never
+ * mints fresh 30s); otherwise single bounded WAIT (`min(retryAfter, remaining)`)
+ * then one atomic re-attempt; exhaustion on second QUEUED is terminal (caller
+ * FAILs). Single-retry bound keeps waits deterministic with pinned clocks
+ * (tests pin `nowMs`/`sleepMs` with no clock advance; infinite polling would
+ * hang). Unreadable (retryAfter 0) never sleeps.
+ */
+export declare function acquireDurableWaveSlotOrQueue(snapshotRoot: string, input: DurableWaveSlotInputV1, options?: {
+    remainingBudgetMs?: number;
+    sleepMs?: (ms: number) => Promise<void>;
+    nowMs?: () => number;
+    leaseTtlMs?: number;
+}): Promise<DurableWaveSlotResultV1>;
+/**
+ * Bounded backpressure telemetry attributes for existing `recordEvent`
+ * conventions (counter: queued/active observations; gauge: ceiling). Refs-only,
+ * never provider content; observation only, never a gate.
+ */
+export declare function providerBackpressureAttributes(signal: ProviderBackpressureTelemetryV1): Record<string, unknown>;
+export declare function loadResourcePolicy(root: string): Promise<OperationResourcePolicyV1>;