@obversa/runtime 0.1.0

package/dist/runtime/node-lifecycle.d.ts

@@ -0,0 +1,84 @@
+import type { Memory } from '@obversa/api';
+import { type AgentResultPart, type Engine, type EngineSelectionRecord, type EngineTransportFailure, type UsageReceipt } from '../engines/engine.js';
+import { type EngineFailureKind } from '../engines/failure.js';
+import { type JsonObject, type JsonValue } from '../graph/value.js';
+import type { AttemptIdentity } from './attempt.js';
+import type { GraphEngineIdentity } from '../graph/type.js';
+import { type AttemptBudgetPolicy, type TokenBudget } from './budget.js';
+import type { ResultContract } from './result-contract.js';
+import type { ExecutionTarget } from '../graph/plan.js';
+import { type NodeWorkspacePolicy } from './workspace-policy.js';
+import { type ActionDecision } from '@obversa/api';
+export { validateActionDecision, type ActionDecision, type AllowActionDecision, type WaitActionDecision, type DenyActionDecision } from '@obversa/api';
+export interface PreparedEngineLane {
+    readonly engine: Engine;
+    readonly selection: EngineSelectionRecord;
+    readonly hardTokenLimitEnforceable: boolean;
+    readonly target?: ExecutionTarget;
+}
+import { type NodeDataContext } from '@obversa/api';
+export { type NodeDataContext } from '@obversa/api';
+export interface ModelUnavailableFact {
+    readonly schemaVersion: 1;
+    readonly identity: AttemptIdentity;
+    readonly selection: EngineSelectionRecord;
+    readonly effective: EngineSelectionRecord;
+    readonly failure: EngineFailureKind;
+    readonly target?: ExecutionTarget;
+}
+export interface PreparedNodeAttempt {
+    readonly identity: AttemptIdentity;
+    readonly nodeId: string;
+    readonly input: JsonValue;
+    readonly memory: Memory | null;
+    readonly prompt: string | null;
+    readonly scratchDirectory: string;
+    readonly workspace: NodeWorkspacePolicy;
+    readonly trustedCaller: JsonObject;
+    readonly permissions: readonly string[];
+    readonly policy: AttemptBudgetPolicy;
+    readonly resultContract: ResultContract | null;
+    readonly engineRoute: readonly [PreparedEngineLane] | readonly [PreparedEngineLane, PreparedEngineLane] | null;
+    readonly declaredTargets?: readonly ExecutionTarget[];
+    readonly runData: ((context: NodeDataContext) => Promise<JsonValue>) | null;
+    readonly parseResult: ((part: AgentResultPart, parts: readonly AgentResultPart[]) => JsonValue) | null;
+    readonly tokenBudget: TokenBudget | null;
+    readonly recordModelUnavailable: (fact: ModelUnavailableFact) => Promise<void>;
+    readonly recordEngineAttempt?: (fact: Readonly<{
+        requested: GraphEngineIdentity;
+        effective: GraphEngineIdentity | null;
+    }>) => Promise<void>;
+    decideAction(): Promise<ActionDecision>;
+}
+export type NodeAttemptFailureCode = 'INVALID_ATTEMPT' | 'ABORTED' | 'INPUT_LIMIT' | 'ACTION_POLICY' | 'TOKEN_BUDGET' | 'TIMEOUT' | 'EFFECT_FAILED' | 'ENGINE_UNAVAILABLE' | 'MODEL_UNAVAILABLE_RECORD' | 'ENGINE_IDENTITY_UNRESOLVED' | 'RESULT_INVALID' | 'OUTPUT_LIMIT' | 'WORKSPACE_INSPECTION' | 'WORKSPACE_VIOLATION' | 'WORKSPACE_LIMIT';
+export interface NodeAttemptFailure extends JsonObject {
+    readonly code: NodeAttemptFailureCode;
+    readonly message: string;
+}
+export interface NodeAttemptRecord {
+    readonly schemaVersion: 1;
+    readonly identity: AttemptIdentity;
+    readonly status: 'completed' | 'failed' | 'paused' | 'denied';
+    readonly decision: ActionDecision | null;
+    readonly failure: NodeAttemptFailure | null;
+    readonly result: JsonValue | null;
+    readonly parts: readonly AgentResultPart[];
+    readonly usage: UsageReceipt;
+    readonly requestedEngine: EngineSelectionRecord | null;
+    readonly effectiveEngine: EngineSelectionRecord | null;
+    readonly unavailableModels: readonly EngineSelectionRecord[];
+    readonly transportFailure: EngineTransportFailure | null;
+    readonly inputBytes: number;
+    readonly outputBytes: number;
+    readonly changedPaths: readonly string[];
+    readonly foreignPaths: readonly string[];
+    readonly filesChanged: number;
+    readonly linesChanged: number;
+    readonly entryHead: string | null;
+    readonly exitHead: string | null;
+    readonly headChanged: boolean;
+    readonly trustedCaller: JsonObject;
+    readonly permissions: readonly string[];
+}
+export declare function validateScratchDirectory(value: string): Promise<string>;
+export declare function executeNodeAttempt(prepared: PreparedNodeAttempt, signal: AbortSignal): Promise<NodeAttemptRecord>;

package/dist/runtime/paths.d.ts

@@ -0,0 +1,2 @@
+/** Create one safe runtime-owned directory under the workspace. */
+export declare function ensureRunSubdir(workspaceDir: string, name: string): string;

package/dist/runtime/persist.d.ts

@@ -0,0 +1,31 @@
+import type { RecordedEngineUsage } from '../core/job.js';
+import type { LoopEvent, Outcome } from '../core/types.js';
+interface RecorderOptions {
+    thin?: boolean;
+    /** Append to the existing record instead of truncating it. */
+    resume?: boolean;
+}
+export type RecordedStage = {
+    readonly kind: 'interrupted';
+    readonly startLine: number;
+} | {
+    readonly kind: 'completed';
+    readonly outcome: Outcome;
+};
+export interface ResumedStageRecords {
+    readonly anchors: ReadonlyMap<string, {
+        readonly identity: string;
+        readonly workspace: string;
+        readonly recordId: string;
+    }>;
+    readonly stages: ReadonlyMap<string, RecordedStage>;
+}
+/** Read the latest stage state and the engine answers recorded for each stage.
+ * A missing record has no stage state, so resume starts fresh. */
+export declare function readResumeRecord(path: string): {
+    readonly outcomes: ResumedStageRecords;
+    readonly usage: ReadonlyMap<string, readonly RecordedEngineUsage[]>;
+};
+/** Append every durable event as one JSON line. */
+export declare function makeRecorder(path: string, options?: RecorderOptions): (event: LoopEvent) => void;
+export {};

package/dist/runtime/preflight-record.d.ts

@@ -0,0 +1,149 @@
+import { type ArtifactReference } from '../artifacts/store.js';
+import { type DomainEventEnvelope, type EventStreamRef, type StreamRevision } from '../events/envelope.js';
+import type { AgentResult, EngineFailureKind, EngineIncompleteResultEvidence, EngineSelectionRecord, UsageReceipt } from '../engines/engine.js';
+import type { ExecutionTarget } from '../graph/plan.js';
+import { type StorageErrorCode } from '../storage/error.js';
+import { type EngineExclusionKey } from './engine-availability.js';
+import { type RunStorageBinding } from './run-definition.js';
+import { type PreflightPauseResult } from '@obversa/api';
+export { type PreflightPauseResult, type PreflightFailureResult } from '@obversa/api';
+import type { RunPreflightState } from '@obversa/api';
+export type { RunPreflightState } from '@obversa/api';
+export type ProbeStartPayload = {
+    readonly laneId: string;
+    readonly target: ExecutionTarget;
+    readonly selection: EngineSelectionRecord;
+} & ({
+    readonly stage: 'static';
+    readonly contextNodeId: string | null;
+    readonly expectedSelection: EngineSelectionRecord | null;
+} | {
+    readonly stage: 'live';
+});
+export type ProbeEvidence = {
+    readonly kind: 'complete';
+    readonly result: Omit<AgentResult, 'raw'>;
+} | {
+    readonly kind: 'incomplete';
+    readonly result: Omit<EngineIncompleteResultEvidence, 'raw'>;
+};
+export interface ProbeEvidenceDocument {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly probeEventId: string;
+    readonly evidence: ProbeEvidence;
+}
+export interface ProbeDiagnosticDocument {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly probeEventId: string;
+    readonly detail: string;
+}
+type EvidenceReference = ArtifactReference<'preflight-evidence'>;
+type DiagnosticReference = ArtifactReference<'preflight-diagnostic'>;
+export type StaticOutcome = {
+    readonly kind: 'admitted';
+    readonly selection: EngineSelectionRecord;
+} | {
+    readonly kind: 'unsupported';
+} | {
+    readonly kind: 'failed';
+    readonly failure: EngineFailureKind;
+    readonly effective: EngineSelectionRecord | null;
+    readonly diagnostic: DiagnosticReference;
+} | {
+    readonly kind: 'interrupted';
+} | {
+    readonly kind: 'recording-failed';
+    readonly storageCode: StorageErrorCode;
+};
+export type LiveOutcome = {
+    readonly usage: UsageReceipt;
+    readonly effective: EngineSelectionRecord | null;
+} & ({
+    readonly kind: 'succeeded';
+    readonly evidence: EvidenceReference;
+    readonly diagnostic: DiagnosticReference;
+} | {
+    readonly kind: 'failed';
+    readonly failure: EngineFailureKind;
+    readonly evidence: EvidenceReference | null;
+    readonly diagnostic: DiagnosticReference;
+} | {
+    readonly kind: 'interrupted';
+    readonly evidence: null;
+    readonly diagnostic: null;
+} | {
+    readonly kind: 'recording-failed';
+    readonly storageCode: StorageErrorCode;
+    readonly evidence: null;
+    readonly diagnostic: null;
+});
+export type ProbeFinishPayload = {
+    readonly probeEventId: string;
+} & ({
+    readonly stage: 'static';
+    readonly outcome: StaticOutcome;
+} | {
+    readonly stage: 'live';
+    readonly outcome: LiveOutcome;
+});
+type PauseReason = 'engine-failure' | 'interrupted' | 'recording-failure';
+export interface PreflightPausedPayload {
+    readonly finishedProbeEventId: string;
+    readonly reason: PauseReason;
+}
+export interface PreflightResumedPayload {
+    readonly preflightEventId: string;
+}
+export interface PreflightFailedPayload {
+    readonly laneId: string;
+    readonly code: 'PREFLIGHT_FAILED';
+    readonly reason: 'no-admissible-target';
+}
+export interface ProbeModelUnavailableFact {
+    readonly schemaVersion: 1;
+    readonly source: {
+        readonly kind: 'preflight';
+        readonly probeEventId: string;
+        readonly laneId: string;
+    };
+    readonly target: ExecutionTarget;
+    readonly selection: EngineSelectionRecord;
+    readonly effective: EngineSelectionRecord;
+    readonly failure: EngineFailureKind;
+}
+export interface RecordedProbeStart {
+    readonly envelope: DomainEventEnvelope;
+    readonly payload: ProbeStartPayload;
+}
+export interface CompletedProbe {
+    readonly start: RecordedProbeStart;
+    readonly finish: DomainEventEnvelope;
+    readonly payload: ProbeFinishPayload;
+    readonly evidence: ProbeEvidence | null;
+}
+export interface ValidatedProbeFailure {
+    readonly envelope: DomainEventEnvelope;
+    readonly fact: ProbeModelUnavailableFact;
+    readonly exclusionKeys: readonly EngineExclusionKey[];
+}
+export interface LoadedRunPreflight {
+    readonly stream: EventStreamRef;
+    readonly revision: StreamRevision;
+    readonly events: readonly DomainEventEnvelope[];
+    readonly state: RunPreflightState;
+    readonly probes: readonly CompletedProbe[];
+    readonly openProbe: RecordedProbeStart | null;
+    readonly admissionCompletedAtRevision: StreamRevision | null;
+    readonly probeFailures: ReadonlyMap<string, ValidatedProbeFailure>;
+}
+/** Private package surface: the executor replays these captured envelopes. */
+export declare function loadRunPreflight(storage: RunStorageBinding, runId: string): Promise<LoadedRunPreflight>;
+/** Read admission state without calling engines, loading a host, or appending events. */
+export declare function readRunPreflight(storage: RunStorageBinding, runId: string): Promise<RunPreflightState>;
+/**
+ * The caller must own this run and verify worker cleanup before calling.
+ * Close one uncertain check using one expected-revision append; never retry.
+ */
+export declare function interruptRunPreflight(storage: RunStorageBinding, runId: string): Promise<PreflightPauseResult | null>;

package/dist/runtime/process-tree.d.ts

@@ -0,0 +1 @@
+export { capturePipeOwnerProbe, inspectAttemptMarkedProcesses, inspectOwnedProcessTree, inspectPipeHoldingProcesses, measureOwnedProcessMemory, parseWindowsProcessRows, readAttemptMarkerProcessIds, stopOwnedProcessTree, type OwnedProcessTreeRequest, type PipeOwnerProbe, type ProcessIdentity, type StopOwnedProcessTreeRequest, } from '@obversa/core/command';

package/dist/runtime/result-contract.d.ts

@@ -0,0 +1,4 @@
+import { type JsonValue } from '../graph/value.js';
+import type { ResultContract, ResultContractDefinition } from '@obversa/api';
+export { type ResultContractRecord, type ResultContract, type ResultContractDefinition } from '@obversa/api';
+export declare function defineResultContract<Schema extends JsonValue, Result extends JsonValue>(definition: ResultContractDefinition<Schema, Result>): ResultContract<Schema, Result>;

package/dist/runtime/result-parts.d.ts

@@ -0,0 +1 @@
+export { assistantResult, engineSelection, finalResultPart, finalResultText, reportedUsage, requireFinalResultText, validateAgentResult, validateIncompleteResultEvidence, } from '@obversa/api';

package/dist/runtime/run-definition.d.ts

@@ -0,0 +1,24 @@
+import { type CompiledGraphDefinition, type RunStorageBinding, type RunStartRecord } from '@obversa/api';
+import { type JsonObject, type RunBrief } from '../graph/value.js';
+import { type ResolvedPlanSnapshot } from '../graph/plan.js';
+export { validateRunDefinition, validateRunStartRecord, validateRunStoragePolicy, validateRunStorageRecord, type StorageProviderRecord, type SensitiveContentPolicy, type RunStoragePolicy, type RunStorageRecord, type RunDefinition, type RunStartedPayload, type NewRunStartedEvent, type RunStartRecord, type RunStorageBinding, } from '@obversa/api';
+export interface PersistRunDefinitionInput {
+    readonly runId: string;
+    readonly eventId: string;
+    readonly timestamp: string;
+    readonly graphDefinition: CompiledGraphDefinition;
+    readonly resolvedPlan: ResolvedPlanSnapshot;
+    readonly resolvedInputs: RunBrief;
+    readonly workspaceBinding: JsonObject | null;
+    readonly hostBinding: {
+        readonly bytes: Uint8Array;
+        readonly mediaType: string;
+    } | null;
+}
+export interface LoadedRunDefinition {
+    readonly record: RunStartRecord;
+    readonly resolvedPlan: ResolvedPlanSnapshot;
+    readonly hostBindingBytes: Uint8Array | null;
+}
+export declare function persistRunDefinition(binding: RunStorageBinding, input: PersistRunDefinitionInput): Promise<RunStartRecord>;
+export declare function loadRunDefinition(binding: RunStorageBinding, runId: string): Promise<LoadedRunDefinition>;

package/dist/runtime/run-event.d.ts

@@ -0,0 +1,9 @@
+import { type DomainEventEnvelope, type EventStreamRef, type NewDomainEvent } from '../events/envelope.js';
+import { type RunStorageBinding } from './run-definition.js';
+export interface LoadedRunEvents {
+    readonly stream: EventStreamRef;
+    readonly events: readonly DomainEventEnvelope[];
+}
+export type RunEventAppendCheck = (events: readonly DomainEventEnvelope[]) => 'append' | 'already-stored';
+export declare function readRunEvents(storage: RunStorageBinding, runId: string): Promise<LoadedRunEvents>;
+export declare function appendRunEvent(storage: RunStorageBinding, runId: string, event: NewDomainEvent, check?: RunEventAppendCheck): Promise<void>;

package/dist/runtime/runner.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The runner assembles a `JobContext` and executes a root `Job` (a loop, a dag,
+ * or any job). It owns the engine resolver, the abort controller, the shared
+ * state, and the stats collector. Hosts observe via `onEvent`.
+ */
+import type { Engine, EngineRef } from '../engines/engine.js';
+import { type StatsSnapshot } from '../core/stats.js';
+import { type CostReport, type PriceTable } from '../core/cost.js';
+import { type BudgetConfig } from '../core/budget.js';
+/** Run-owned keys holding the workflow state read from its record. */
+export declare const RESUME_STAGE_OUTCOMES = "obversa:resumed-stage-outcomes";
+export declare const RESUME_RECORDED_USAGE = "obversa:resumed-recorded-usage";
+import type { Environment } from '../env/environment.js';
+import type { Memory } from '@obversa/api';
+import { type RunMonitor } from './monitor.js';
+import { type RunBrief } from '../graph/value.js';
+import type { Job, LimitPolicy, LoopEvent, Outcome, UsageTotals, RunCallbacks } from '../core/types.js';
+/**
+ * Exit code for a `paused` run: EX_TEMPFAIL (sysexits.h). Distinct from `fail`
+ * (1) so a wrapper can tell "paused" from "failed".
+ */
+export declare const EXIT_PAUSED = 75;
+export interface RunOptions {
+    /** Default engine selected when a job or condition names none. */
+    readonly engine?: EngineRef;
+    /** Ready-made engines available to jobs and conditions by name. */
+    readonly engines?: Readonly<Record<string, Engine>>;
+    /** External abort signal. */
+    signal?: AbortSignal;
+    /** Root working directory the run operates in. Default: process.cwd(). */
+    cwd?: string;
+    /**
+     * Bring an environment up for the run (the root workspace) before the job and
+     * tear it down after, so the gate can test the running thing. You supply the
+     * adapter; the runtime owns only the interface. Per-team environments at the
+     * worktree boundary are a separate, later binding.
+     */
+    environment?: Environment;
+    onEvent?: (event: LoopEvent) => void;
+    /** Immutable run brief shared by every job. */
+    params?: RunBrief;
+    /** Seed the shared, mutable run state. */
+    state?: Record<string, unknown>;
+    /** Memory instance available to every job in the run. */
+    memory?: Memory;
+    /**
+     * The client the run's questions go through (`approval`). Default: a fresh
+     * in-memory client for this run, so a run without one forgets its questions
+     * when it ends. Pass a client to keep them: the in-memory one across runs
+     * in a process, the stored client (`createStoredCallbackClient`) across a
+     * process exit.
+     */
+    callbacks?: RunCallbacks;
+    /** Wait for an outside answer, or return paused (the default). */
+    onCallback?: 'wait' | 'exit';
+    /**
+     * Serve the run's own page on a free loopback port: the declared graph with
+     * each step's live state, the returns, the pending questions, the record
+     * tail. Off by default; on under `supervise` unless set to false. The
+     * address is one `monitor` event and one line in the record, never stdout.
+     */
+    monitor?: boolean;
+    /**
+     * Cap total tokens (input + output) for the run. A bare number is the limit;
+     * pass `{ limit, headroom?, soft? }` for headroom or warn-don't-refuse mode.
+     * Engine call sites refuse to spend past it (see `Budget`).
+     */
+    budget?: number | BudgetConfig;
+    /** Append every structured event as JSONL here, or auto-name one under `.obversa/records`. */
+    recordTo?: string | 'auto';
+    /**
+     * Resume from the record at `recordTo` instead of truncating it: stages
+     * whose completion is already recorded are skipped, interrupted stages
+     * re-run. Requires an explicit `recordTo` path; a missing record is a
+     * fresh run, not an error. Two processes resuming one record at once is
+     * out of scope.
+     */
+    resume?: boolean;
+    /**
+     * Register this run in the global registry (`~/.obversa/runs/<runId>`) and write
+     * its live state there, so another process can inspect it. Off by default;
+     * opt in to make a run observable from outside.
+     */
+    supervise?: boolean;
+    /**
+     * Assign the registry id instead of generating one, so an outside controller
+     * knows the id before the run registers.
+     * Must match the registry alphabet (`[a-z0-9][a-z0-9-]*`); only meaningful
+     * with `supervise` or `recordTo: 'auto'`.
+     */
+    runId?: string;
+    /**
+     * How a loop reacts to a rate limit / quota / token budget. Default `auto`:
+     * wait out a known reset within `maxWaitMs`, else pause (exit code 75).
+     * `wait` waits any known reset with no ceiling; `exit` never waits; `fail` is
+     * fatal
+     * behaviour.
+     */
+    onLimit?: LimitPolicy;
+    /** Ceiling on a single interruptible limit-wait, in ms. Default 300000. */
+    maxWaitMs?: number;
+    /**
+     * Price the run's measured token usage (`RunResult.cost`). Prices are
+     * caller-supplied — the library hardcodes none. `baselineModel` adds the
+     * reconstructed counterfactual: the same token stream at that model's rates.
+     */
+    cost?: {
+        prices: PriceTable;
+        baselineModel?: string;
+    };
+}
+export interface RunResult {
+    outcome: Outcome;
+    stats: StatsSnapshot;
+    /**
+     * What the whole run spent, in the shape `formatEvent` takes, so the totals
+     * a run reports can be handed straight back to the line formatter. The same
+     * numbers are in `stats`; this is the summary a person reads rather than the
+     * per-model record.
+     */
+    usage: UsageTotals;
+    /** Final token accounting, when a budget was set. */
+    budget?: {
+        limit: number;
+        spent: number;
+        remaining: number;
+    };
+    /** The registry id, when the run was supervised. */
+    runId?: string;
+    /** The run's page, when `monitor` was on: its address, and a way to close it. */
+    monitor?: RunMonitor;
+    /** The JSONL event record path, when recording was enabled. */
+    recordPath?: string;
+    /** The priced receipt, when `RunOptions.cost` was set. */
+    cost?: CostReport;
+}
+export declare function run(job: Job, options?: RunOptions): Promise<RunResult>;
+/** Process exit code mapped from a terminal outcome. */
+export declare function exitCodeFor(outcome: Outcome): number;

package/dist/runtime/supervisor.d.ts

@@ -0,0 +1,111 @@
+/** Filesystem-backed status for a run that another process can inspect. */
+import type { JobMeta, LoopEvent, Outcome, ProofRecord, UsageTotals } from '../core/types.js';
+export declare function runsHome(): string;
+export declare function newRunId(title: string): string;
+export interface CurrentWork {
+    kind: 'job' | 'dag-node';
+    path: string[];
+    label?: string;
+    node?: string;
+    startedAt: number;
+    timeoutMs?: number;
+    deadlineAt?: number;
+}
+export interface RunLive {
+    path: string[];
+    iteration: number;
+    current?: CurrentWork;
+    active?: Record<string, CurrentWork>;
+    lastGate?: {
+        which: string;
+        met: boolean;
+        confidence?: number;
+        reason: string;
+    };
+    lastOutcome?: {
+        status: string;
+        summary?: string;
+        late?: boolean;
+    };
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        /** What this run has been served from cache, the figure the line reports. */
+        cacheReadInputTokens: number;
+        /** What it paid to build that cache, kept separate on purpose. */
+        cacheCreationInputTokens: number;
+        calls: number;
+        unmeasuredCalls: number;
+    };
+}
+export interface RunStatus {
+    runId: string;
+    pid: number;
+    cwd: string;
+    title: string;
+    startedAt: number;
+    updatedAt: number;
+    endedAt?: number;
+    status: 'running' | Outcome['status'];
+    alive?: boolean;
+    shape?: JobMeta;
+    live: RunLive;
+    evidence?: {
+        count: number;
+        indexPath: string;
+        latest?: ProofRecord;
+    };
+}
+export interface Supervisor {
+    runId: string;
+    dir: string;
+    sink: (event: LoopEvent) => void;
+    finish: (outcome: Outcome) => void;
+}
+export declare function startSupervisor(input: {
+    runId: string;
+    cwd: string;
+    title: string;
+    shape?: JobMeta;
+}): Supervisor;
+export declare function isAlive(pid: number): boolean;
+export declare function readRunStatus(runId: string): RunStatus | undefined;
+export declare function listRuns(): RunStatus[];
+export declare function runEventsPath(runId: string): string;
+export declare function runEvidenceIndexPath(runId: string): string;
+export interface RunProgress {
+    runId: string;
+    status: RunStatus['status'];
+    alive?: boolean;
+    title: string;
+    stage: string;
+    iteration: number;
+    lastGate?: RunLive['lastGate'];
+    lastOutcome?: RunLive['lastOutcome'];
+    usage: RunLive['usage'];
+    current?: RunLive['current'] & {
+        elapsedMs: number;
+        remainingMs?: number;
+    };
+    evidence?: RunStatus['evidence'];
+    startedAt: number;
+    updatedAt: number;
+    blocker?: {
+        kind: 'gate-failing' | 'limit-pause' | 'error';
+        detail: string;
+    };
+    recent: string[];
+}
+export declare function readRunProgress(runId: string, options?: {
+    recent?: number;
+}): RunProgress | undefined;
+export declare function runningTotal(totals: UsageTotals): string;
+export declare function toLine(value: string): string;
+/**
+ * Format one event with optional totals the caller already holds.
+ *
+ * `StatsSnapshot` accumulates the totals and the monitor's live status tracks
+ * them, so nothing here remembers anything: the function stays one event in,
+ * one string out. Omitting the totals prints exactly what it printed before.
+ */
+export declare function formatEvent(event: LoopEvent, totals?: UsageTotals): string;

package/dist/runtime/team-rooms.d.ts

@@ -0,0 +1,13 @@
+import { type RunStorageBinding } from './run-definition.js';
+import type { StreamRevision } from '../events/envelope.js';
+export declare function projectTeamRooms(input: {
+    readonly storage: RunStorageBinding;
+    readonly runId: string;
+    readonly directory: string;
+}): Promise<{
+    readonly revision: StreamRevision;
+    readonly files: readonly {
+        readonly roomId: string;
+        readonly path: string;
+    }[];
+}>;

package/dist/runtime/workspace-policy.d.ts

@@ -0,0 +1,25 @@
+import { type GitWorkspaceSnapshot } from '../core/git.js';
+import { type JsonObject } from '../graph/value.js';
+import type { NodeWorkspacePolicy } from '@obversa/api';
+export { type WorkspaceMode, type NodeWorkspacePolicy } from '@obversa/api';
+export interface WorkspaceEntry {
+    readonly policy: NodeWorkspacePolicy;
+    readonly snapshot: GitWorkspaceSnapshot | null;
+}
+export interface WorkspaceAttemptEvidence extends JsonObject {
+    readonly entryHead: string | null;
+    readonly exitHead: string | null;
+    readonly headChanged: boolean;
+    readonly changedPaths: readonly string[];
+    readonly foreignPaths: readonly string[];
+    readonly filesChanged: number;
+    readonly linesChanged: number;
+}
+export type WorkspacePolicyErrorCode = 'INVALID_WORKSPACE_POLICY' | 'NOT_GIT_REPOSITORY' | 'GIT_INSPECTION_FAILED' | 'ABORTED';
+export declare class WorkspacePolicyError extends Error {
+    readonly code: WorkspacePolicyErrorCode;
+    constructor(code: WorkspacePolicyErrorCode, message: string);
+}
+export declare function validateWorkspacePolicy(value: NodeWorkspacePolicy): NodeWorkspacePolicy;
+export declare function captureWorkspaceEntry(value: NodeWorkspacePolicy, signal: AbortSignal): Promise<WorkspaceEntry>;
+export declare function inspectWorkspaceExit(value: NodeWorkspacePolicy, entry: WorkspaceEntry, signal: AbortSignal): Promise<WorkspaceAttemptEvidence>;

package/dist/storage/error.d.ts

@@ -0,0 +1 @@
+export { StorageError, type StorageErrorCode } from '@obversa/api';

package/dist/storage/id.d.ts

@@ -0,0 +1 @@
+export { validateStorageId } from '@obversa/api';

package/dist/storage/local.d.ts

@@ -0,0 +1,12 @@
+import { createLocalArtifactStore, type LocalArtifactStoreOptions } from '../artifacts/file-store.js';
+import { createLocalEventStore, type LocalEventStoreOptions } from '../events/jsonl-store.js';
+import { type RunStorageBinding, type RunStoragePolicy } from '../runtime/run-definition.js';
+export interface LocalRunStorageOptions {
+    readonly directory: string;
+    readonly namespace: string;
+    readonly policy: RunStoragePolicy;
+    readonly knownSecrets?: readonly string[];
+}
+export declare function createLocalRunStorage(options: LocalRunStorageOptions): RunStorageBinding;
+export { createLocalArtifactStore, createLocalEventStore, };
+export type { LocalArtifactStoreOptions, LocalEventStoreOptions, };