@anvia/durable 0.0.0-bootstrap.0 → 0.1.1

package/dist/types-CBjKEKQ7.d.ts

@@ -0,0 +1,396 @@
+import { AgentInteractionRequest } from '@anvia/core/agent/interactions';
+import { JsonValue, Usage, Message } from '@anvia/core/completion';
+import { z } from 'zod';
+import { Agent, AgentInput, AgentOutcome } from '@anvia/core/agent';
+
+type DurableMetrics = {
+    observedAt: string;
+    runs: Record<string, number>;
+    tasks: Record<string, number>;
+    oldestPendingAgeMs: number;
+    operations: number;
+    events: number;
+    databaseBytes: number;
+};
+
+type DurableLimits = {
+    maxPendingRuns: number;
+    maxPendingTasks: number;
+    maxPayloadBytes: number;
+    maxOperations: number;
+};
+
+type DurableTask = {
+    id: string;
+    agentId: string;
+    prompt: string;
+    dependsOn?: readonly string[];
+};
+type DurableGraphSubmission = {
+    sessionId: string;
+    requestId: string;
+    /** A static directed acyclic graph, limited to 100 tasks. */
+    tasks: readonly DurableTask[];
+};
+type DurableGraphRecord = {
+    id: string;
+    submission: DurableGraphSubmission;
+    createdAt: string;
+    cancelled: boolean;
+    /** IDs are persisted atomically with the child runs. */
+    runIds: Record<string, string>;
+};
+type DurableTaskWait = {
+    type: "dependencies" | "dependency_failed";
+    taskIds: string[];
+} | {
+    type: "capacity";
+} | {
+    type: "interaction";
+    interactionId: string;
+} | {
+    type: "retry";
+    until: string;
+} | {
+    type: "recovery";
+    operationId?: string;
+};
+type DurableGraphNode = {
+    id: string;
+    agentId: string;
+    runId: string;
+    status: DurableRunStatus;
+    wait?: DurableTaskWait;
+    output?: JsonValue;
+    interaction?: AgentInteractionRequest;
+    error?: string;
+};
+type DurableGraphSnapshot = {
+    id: string;
+    sessionId: string;
+    requestId: string;
+    createdAt: string;
+    status: "running" | "waiting" | "blocked" | "completed" | "cancelled";
+    nodes: DurableGraphNode[];
+    edges: {
+        source: string;
+        target: string;
+    }[];
+    cursor: number;
+};
+type DurableGraphEvent = DurableEvent & {
+    graphId: string;
+    taskId: string;
+};
+type DurableGraphListOptions = {
+    sessionId?: string | undefined;
+    after?: number | undefined;
+    limit?: number | undefined;
+};
+type DurableGraphPage = {
+    graphs: {
+        id: string;
+        sessionId: string;
+        requestId: string;
+        createdAt: string;
+    }[];
+    nextCursor?: number;
+};
+
+type TaskOutcome<R = JsonValue> = {
+    status: "completed";
+    output: R;
+} | {
+    status: "failed" | "cancelled";
+    error: string;
+};
+type TaskWait = {
+    type: "children";
+    ids: string[];
+    policy: "allSettled" | "failFast";
+} | {
+    type: "timer";
+    until: string;
+} | {
+    type: "agent";
+    runId: string;
+    status: DurableRunStatus;
+} | {
+    type: "signal";
+    name: string;
+};
+type TaskTransition<S, R> = {
+    status: "pending";
+    checkpoint: S;
+} | {
+    status: "waiting";
+    checkpoint: S;
+    wait: TaskWait;
+} | TaskOutcome<R>;
+type TaskContext<I, S> = {
+    readonly id: string;
+    readonly input: I;
+    readonly checkpoint: S;
+    readonly signal: AbortSignal;
+    /** The key is unique for this parent's lifetime. Replay returns the same child. */
+    spawn<CI, CS, CR>(key: string, task: TaskDefinition<CI, CS, CR>, input: CI): string;
+    spawnAgent(key: string, input: {
+        agentId: string;
+        prompt: string;
+    }): string;
+    children(): TaskRecord[];
+    signalValue(name: string): JsonValue | undefined;
+    /** Effects default to manual reconciliation after an uncertain interruption. */
+    effect<T extends JsonValue>(key: string, input: JsonValue, execute: (operationId: string, signal: AbortSignal) => Promise<T>, recovery?: ToolRecovery): Promise<T>;
+};
+type TaskDefinition<I, S, R> = {
+    readonly name: string;
+    readonly version: number;
+    readonly input: z.ZodType<I>;
+    readonly checkpoint: z.ZodType<S>;
+    readonly output: z.ZodType<R>;
+    readonly initial: (input: I) => S;
+    /** Re-entered from the last committed checkpoint; external effects belong in effect(). */
+    readonly run: (context: TaskContext<I, S>) => Promise<TaskTransition<S, R>>;
+    readonly migrate?: (input: JsonValue, checkpoint: JsonValue, fromVersion: number) => {
+        input: I;
+        checkpoint: S;
+    };
+};
+type DefinedTask<I, S, R> = TaskDefinition<I, S, R> & {
+    readonly registration: RegisteredTask;
+};
+/** Type-erased at registration; schemas enforce every persisted boundary. */
+type RegisteredTask = {
+    readonly name: string;
+    readonly version: number;
+    parseInput(value: unknown): JsonValue;
+    parseCheckpoint(value: unknown): JsonValue;
+    parseOutput(value: unknown): JsonValue;
+    initial(input: JsonValue): JsonValue;
+    run(context: TaskContext<JsonValue, JsonValue>): Promise<TaskTransition<JsonValue, JsonValue>>;
+    migrate?: (input: JsonValue, checkpoint: JsonValue, version: number) => {
+        input: JsonValue;
+        checkpoint: JsonValue;
+    };
+};
+type TaskRecord = {
+    id: string;
+    rootId: string;
+    parentId?: string;
+    agentRunId?: string;
+    depth: number;
+    sessionId: string;
+    key: string;
+    name: string;
+    version: number;
+    submissionVersion: number;
+    /** Original input for deduplication, even after migration. */
+    submissionInput: JsonValue;
+    input: JsonValue;
+    checkpoint: JsonValue;
+    status: "pending" | "running" | "waiting" | "completing" | "cancelling" | "completed" | "failed" | "cancelled" | "needs_attention";
+    wait?: TaskWait;
+    outcome?: TaskOutcome;
+    error?: string;
+    blockedOperation?: string;
+    signals: Record<string, {
+        requestId: string;
+        value: JsonValue;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+};
+type TaskListOptions = {
+    sessionId?: string | undefined;
+    after?: number | undefined;
+    limit?: number | undefined;
+};
+type TaskPage = {
+    tasks: TaskRecord[];
+    nextCursor?: number;
+};
+type TaskGraphSnapshot = {
+    rootId: string;
+    nodes: TaskRecord[];
+    edges: {
+        source: string;
+        target: string;
+        type: "owns" | "waits";
+    }[];
+    cursor: number;
+};
+type TaskEvent = {
+    rootId: string;
+    sequence: number;
+    taskId: string;
+    createdAt: string;
+    type: "submitted" | "status";
+    data: JsonValue;
+};
+interface TaskTransaction {
+    getTask(id: string): TaskRecord | undefined;
+    findTask(sessionId: string, parentId: string | undefined, key: string): TaskRecord | undefined;
+    putTask(task: TaskRecord): void;
+    taskChildren(id: string): TaskRecord[];
+    taskTree(rootId: string): TaskRecord[];
+}
+
+type ToolRecovery = "safe" | "idempotent" | "manual";
+/** Opt-in retries for core completion-attempt errors, including validation and observers. */
+type DurableModelRetry = {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+};
+type DurableAgentRegistration = {
+    agent: Agent<unknown>;
+    /** Bump whenever code, model, tools, schemas, or instructions change incompatibly. */
+    version: string;
+    /** Unlisted tools require reconciliation if interrupted after their intent was committed. */
+    toolRecovery?: Readonly<Record<string, ToolRecovery>>;
+    modelRetry?: DurableModelRetry;
+};
+type DurableRunStatus = "queued" | "retry_wait" | "pending" | "running" | "waiting" | "needs_attention" | "completed" | "failed" | "cancelled";
+type DurableSubmission = {
+    agentId: string;
+    sessionId: string;
+    requestId: string;
+    prompt: string;
+};
+type DurableRunRecord = DurableSubmission & {
+    id: string;
+    version: string;
+    status: DurableRunStatus;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    graphId?: string;
+    taskId?: string;
+    dependencies?: string[];
+    epoch: number;
+    input: AgentInput;
+    modelTurns: number;
+    maxModelTurns: number;
+    usage: Usage;
+    /** Canonical history before this submission, retained across interaction continuations. */
+    history: Message[];
+    outcome?: AgentOutcome<unknown>;
+    error?: string;
+    blockedOperation?: string;
+    modelRetry?: DurableModelRetry;
+    nextAttemptAt?: string;
+    responses: Record<string, JsonValue>;
+};
+type DurableOperation = {
+    key: string;
+    kind: "model" | "tool" | "effect";
+    input: JsonValue;
+    status: "started" | "completed";
+    recovery: ToolRecovery;
+    result?: JsonValue | undefined;
+    /** Persisted before each completion attempt, including interrupted attempts; reset by explicit retry(). */
+    attempts?: number | undefined;
+};
+type DurableListOptions = {
+    sessionId?: string | undefined;
+    agentId?: string | undefined;
+    status?: DurableRunStatus | undefined;
+    /** Exclusive insertion cursor, unrelated to progress-event cursors. */
+    after?: number | undefined;
+    limit?: number | undefined;
+};
+type DurableRunSummary = Pick<DurableRunRecord, "id" | "agentId" | "sessionId" | "requestId" | "status" | "createdAt" | "updatedAt" | "error" | "blockedOperation" | "nextAttemptAt">;
+type DurableRunPage = {
+    runs: DurableRunSummary[];
+    nextCursor?: number;
+};
+type DurableSubmitOptions = {
+    /** Queue behind unfinished work in the session instead of rejecting the submission. */
+    enqueue?: boolean;
+};
+type DurableEvent = {
+    sequence: number;
+    runId: string;
+    createdAt: string;
+    type: "submitted" | "status" | "model_started" | "model_completed" | "tool_started" | "tool_completed";
+    data: JsonValue;
+};
+type DurableSnapshot = {
+    run: DurableRunRecord;
+    /** Committed operation state, including results produced before the run finishes. */
+    operations: DurableOperation[];
+    /** Global commit cursor; pass to stream({ after: cursor }) after rendering this snapshot. */
+    cursor: number;
+};
+/** Synchronous, atomic transaction. Never perform external work inside its callback. */
+interface DurableTransaction extends TaskTransaction {
+    pendingCounts(): {
+        runs: number;
+        tasks: number;
+    };
+    operationCount(id: string): number;
+    getGraph(id: string): DurableGraphRecord | undefined;
+    findGraphRequest(sessionId: string, requestId: string): DurableGraphRecord | undefined;
+    putGraph(graph: DurableGraphRecord): void;
+    getRun(id: string): DurableRunRecord | undefined;
+    findRequest(sessionId: string, requestId: string): DurableRunRecord | undefined;
+    activeRun(sessionId: string): DurableRunRecord | undefined;
+    latestCompleted(sessionId: string): DurableRunRecord | undefined;
+    hasLaterStartedRun(id: string): boolean;
+    putRun(run: DurableRunRecord): void;
+    getOperation(runId: string, key: string): DurableOperation | undefined;
+    operations(runId: string): DurableOperation[];
+    putOperation(runId: string, operation: DurableOperation): void;
+    appendEvent(runId: string, type: DurableEvent["type"], data: JsonValue): void;
+    cursor(): number;
+}
+/** A store is exclusively owned by one open runtime. All returned values must be detached copies. */
+interface DurableStore {
+    metrics(): DurableMetrics;
+    listTasks(options: TaskListOptions): TaskPage;
+    scheduleTasks(excluded: readonly string[], limit: number): string[];
+    unsettledTaskRoots(after: number): {
+        ids: string[];
+        cursor?: number;
+    };
+    taskEvents(rootId: string, after: number, limit: number): DurableEvent[];
+    acquire(): void;
+    close(): void;
+    transaction<T>(callback: (tx: DurableTransaction) => T): T;
+    listGraphs(options: DurableGraphListOptions): DurableGraphPage;
+    graphEvents(graphId: string, after: number, limit: number): DurableEvent[];
+    list(options: DurableListOptions): DurableRunPage;
+    /** Oldest eligible unfinished run per session, excluding executions still settling. */
+    schedule(now: string, limit: number, excludedSessions: readonly string[]): {
+        ids: string[];
+        nextAttemptAt?: string;
+    };
+    events(runId: string, after: number, limit: number): DurableEvent[];
+}
+type DurableRuntimeOptions = {
+    store: DurableStore;
+    limits?: Partial<DurableLimits>;
+    /** Called once after a fatal storage/scheduler failure; never includes task payloads automatically. */
+    onFatalError?: (error: unknown) => void;
+    agents?: readonly DurableAgentRegistration[];
+    tasks?: readonly {
+        readonly registration: RegisteredTask;
+    }[];
+    /** Independent capacity for custom task phases. Waiting phases release their slot. */
+    maxConcurrentTasks?: number;
+    /** Maximum simultaneous executions across sessions. Defaults to 4. */
+    maxConcurrentRuns?: number;
+};
+/** Lightweight owner metadata for application authorization. */
+type DurableRunScope = {
+    runId: string;
+    agentId: string;
+    sessionId: string;
+    graphId?: string;
+    taskId?: string;
+    rootTaskId?: string;
+    taskName?: string;
+};
+
+export type { DurableRunRecord as A, DurableRunStatus as B, DurableRunSummary as C, DurableSnapshot as D, DurableTask as E, DurableTaskWait as F, DurableTransaction as G, TaskContext as H, TaskOutcome as I, TaskTransaction as J, TaskTransition as K, TaskWait as L, ToolRecovery as M, RegisteredTask as R, TaskRecord as T, DurableEvent as a, DurableGraphSnapshot as b, DurableGraphEvent as c, DurableStore as d, DurableAgentRegistration as e, DurableOperation as f, TaskGraphSnapshot as g, TaskEvent as h, DurableRuntimeOptions as i, DefinedTask as j, DurableRunScope as k, TaskListOptions as l, TaskPage as m, DurableSubmission as n, DurableSubmitOptions as o, DurableGraphSubmission as p, DurableGraphListOptions as q, DurableGraphPage as r, DurableListOptions as s, DurableRunPage as t, DurableMetrics as u, TaskDefinition as v, DurableGraphNode as w, DurableGraphRecord as x, DurableLimits as y, DurableModelRetry as z };

package/package.json

@@ -1,17 +1,61 @@
 {
   "name": "@anvia/durable",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Bootstrap placeholder for configuring Anvia durable trusted publishing. Not a usable runtime.",
+  "version": "0.1.1",
+  "description": "Durable agent execution with persisted model and tool checkpoints for Anvia.",
+  "author": "anvia",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/anvia-hq/anvia",
     "directory": "packages/durable"
   },
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
-}
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "import": "./dist/sqlite.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./maintenance": {
+      "types": "./dist/maintenance.d.ts",
+      "import": "./dist/maintenance.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.6.5",
+    "@anvia/core": "1.7.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.6.5",
+    "@anvia/core": "^1.7.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/sqlite.ts src/protocol.ts src/maintenance.ts --format esm --dts --sourcemap --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}