tubeless 0.3.0 → 0.3.1

package/README.md

@@ -94,7 +94,7 @@ flags after `--`. Record runs with `--store` or `--trace`, then inspect them wit
 - Start with a [typed import](./examples/typed-import.ts) or add
   [dry runs and write gates](./examples/publish-with-gates.ts) to a publishing job.
 - Build workflows with [child pipelines](./examples/child-pipeline.ts) and [fan-out](./examples/fan-out-progress.ts).
-- Run bounded model decisions, default filesystem/shell tools, custom tools, and subagents with [in-process agents](./docs/agents.md).
+- Run bounded model decisions, workspace tools, custom tools, and subagents with [agents](./docs/agents.md), optional durable checkpoints, and local or remote execution environments.
 - Optional: the [peloton example](./examples/peloton.ts) is a cycling-themed kitchen sink for the live TUI.
 
 The [recipe index](./docs/recipes.md) covers validation, retries, tracing, testing,

package/dist/agent/agent-identity.d.ts

@@ -0,0 +1,2 @@
+export declare function markAgent(pipeline: object): void;
+export declare function isAgent(pipeline: object): boolean;

package/dist/agent/agent-identity.js

@@ -0,0 +1,8 @@
+const agents = new WeakSet();
+export function markAgent(pipeline) {
+    agents.add(pipeline);
+}
+export function isAgent(pipeline) {
+    return agents.has(pipeline);
+}
+//# sourceMappingURL=agent-identity.js.map

package/dist/agent/agent-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-identity.js","sourceRoot":"","sources":["../../src/agent/agent-identity.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,IAAI,OAAO,EAAU,CAAC;AACrC,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACvB,CAAC;AACD,MAAM,UAAU,OAAO,CAAC,QAAgB;IACtC,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC","sourcesContent":["const agents = new WeakSet<object>();\nexport function markAgent(pipeline: object): void {\n  agents.add(pipeline);\n}\nexport function isAgent(pipeline: object): boolean {\n  return agents.has(pipeline);\n}\n"]}

package/dist/agent/agent-state.d.ts

@@ -1,6 +1,7 @@
 import type { StandardSchemaV1 } from "../core/pipeline-types.js";
 import type { AgentState } from "./agent-types.js";
 export declare function agentError(code: string, message: string, cause?: unknown): Error;
+export declare function limit(name: string, bound: number, consumed: number, requested: number, scope: string): never;
 export declare function ownState<T>(state: T): AgentState<T>;
 export declare function checkSchema(schema: StandardSchemaV1, label: string): void;
 export declare function jsonDescriptor(schema: StandardSchemaV1, explicit: Readonly<Record<string, unknown>> | undefined, label: string): Readonly<Record<string, unknown>>;

package/dist/agent/agent-state.js

@@ -2,6 +2,9 @@ import { createHash } from "node:crypto";
 export function agentError(code, message, cause) {
     return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });
 }
+export function limit(name, bound, consumed, requested, scope) {
+    throw agentError("TUBELESS_AGENT_LIMIT_REACHED", `Agent ${name}=${bound} exceeded (consumed=${consumed}, requested=${requested}, scope=${scope})`);
+}
 /** Copy plain data into owned, frozen snapshots; repeated references are copied, cycles fail. */
 function copy(value, ancestors, json) {
     if (value === null || typeof value === "string" || typeof value === "boolean")

package/dist/agent/agent-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-state.js","sourceRoot":"","sources":["../../src/agent/agent-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { StandardSchemaV1 } from \"../core/pipeline-types.js\";\nimport type { AgentState } from \"./agent-types.js\";\n\nexport function agentError(code: string, message: string, cause?: unknown): Error {\n  return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });\n}\n\n/** Copy plain data into owned, frozen snapshots; repeated references are copied, cycles fail. */\nfunction copy(value: unknown, ancestors: Set<object>, json: boolean): unknown {\n  if (value === null || typeof value === \"string\" || typeof value === \"boolean\") return value;\n  if (value === undefined && !json) return value;\n  if (typeof value === \"number\" && Number.isFinite(value)) return value;\n  if (typeof value !== \"object\" || value === null) throw new Error(\"Expected finite plain data\");\n  if (ancestors.has(value)) throw new Error(\"Cyclic data is not supported\");\n  if (\n    !Array.isArray(value) &&\n    Object.getPrototypeOf(value) !== Object.prototype &&\n    Object.getPrototypeOf(value) !== null\n  ) {\n    throw new Error(\"Expected an array or plain record\");\n  }\n  ancestors.add(value);\n  const result: Record<string, unknown> | unknown[] = Array.isArray(value)\n    ? new Array(value.length)\n    : {};\n  const keys = Reflect.ownKeys(value);\n  if (json) keys.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0));\n  for (const key of keys) {\n    if (Array.isArray(value) && key === \"length\") continue;\n    const property = Object.getOwnPropertyDescriptor(value, key)!;\n    if (typeof key !== \"string\" || !(\"value\" in property) || !property.enumerable) {\n      throw new Error(\"State and descriptors require enumerable data properties\");\n    }\n    Object.defineProperty(result, key, {\n      value: copy(property.value, ancestors, json),\n      enumerable: true,\n    });\n  }\n  ancestors.delete(value);\n  return Object.freeze(result);\n}\n\nexport function ownState<T>(state: T): AgentState<T> {\n  try {\n    // SAFETY: copying retains every plain-data value and only adds deep readonly ownership.\n    return copy(state, new Set(), false) as AgentState<T>;\n  } catch (cause) {\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_STATE\",\n      \"Agent state must contain finite primitives, arrays, and plain records\",\n      cause\n    );\n  }\n}\n\nexport function checkSchema(schema: StandardSchemaV1, label: string): void {\n  if (schema?.[\"~standard\"]?.version !== 1 || typeof schema[\"~standard\"].validate !== \"function\") {\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      `${label} requires a Standard Schema validator`\n    );\n  }\n}\n\nexport function jsonDescriptor(\n  schema: StandardSchemaV1,\n  explicit: Readonly<Record<string, unknown>> | undefined,\n  label: string\n): Readonly<Record<string, unknown>> {\n  checkSchema(schema, label);\n  try {\n    const descriptor =\n      explicit ?? schema[\"~standard\"].jsonSchema?.input({ target: \"draft-2020-12\" });\n    if (descriptor === null || typeof descriptor !== \"object\" || Array.isArray(descriptor))\n      throw new Error(\"Missing JSON Schema object\");\n    // SAFETY: the object guard and plain JSON copy validate the descriptor's representation.\n    return copy(descriptor, new Set(), true) as Readonly<Record<string, unknown>>;\n  } catch (cause) {\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      `${label} requires a JSON Schema input descriptor or explicit fallback`,\n      cause\n    );\n  }\n}\n\nexport function descriptorFingerprint(descriptor: Readonly<Record<string, unknown>>): string {\n  return `sha256:${createHash(\"sha256\").update(JSON.stringify(descriptor)).digest(\"hex\")}`;\n}\n\nexport function checkDescription(description: string): void {\n  if (typeof description !== \"string\" || !description.trim() || description.length > 4096)\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      \"Tool description must be nonblank and at most 4096 characters\"\n    );\n}\n"]}
+{"version":3,"file":"agent-state.js","sourceRoot":"","sources":["../../src/agent/agent-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { StandardSchemaV1 } from \"../core/pipeline-types.js\";\nimport type { AgentState } from \"./agent-types.js\";\n\nexport function agentError(code: string, message: string, cause?: unknown): Error {\n  return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });\n}\n\nexport function limit(\n  name: string,\n  bound: number,\n  consumed: number,\n  requested: number,\n  scope: string\n): never {\n  throw agentError(\n    \"TUBELESS_AGENT_LIMIT_REACHED\",\n    `Agent ${name}=${bound} exceeded (consumed=${consumed}, requested=${requested}, scope=${scope})`\n  );\n}\n\n/** Copy plain data into owned, frozen snapshots; repeated references are copied, cycles fail. */\nfunction copy(value: unknown, ancestors: Set<object>, json: boolean): unknown {\n  if (value === null || typeof value === \"string\" || typeof value === \"boolean\") return value;\n  if (value === undefined && !json) return value;\n  if (typeof value === \"number\" && Number.isFinite(value)) return value;\n  if (typeof value !== \"object\" || value === null) throw new Error(\"Expected finite plain data\");\n  if (ancestors.has(value)) throw new Error(\"Cyclic data is not supported\");\n  if (\n    !Array.isArray(value) &&\n    Object.getPrototypeOf(value) !== Object.prototype &&\n    Object.getPrototypeOf(value) !== null\n  ) {\n    throw new Error(\"Expected an array or plain record\");\n  }\n  ancestors.add(value);\n  const result: Record<string, unknown> | unknown[] = Array.isArray(value)\n    ? new Array(value.length)\n    : {};\n  const keys = Reflect.ownKeys(value);\n  if (json) keys.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0));\n  for (const key of keys) {\n    if (Array.isArray(value) && key === \"length\") continue;\n    const property = Object.getOwnPropertyDescriptor(value, key)!;\n    if (typeof key !== \"string\" || !(\"value\" in property) || !property.enumerable) {\n      throw new Error(\"State and descriptors require enumerable data properties\");\n    }\n    Object.defineProperty(result, key, {\n      value: copy(property.value, ancestors, json),\n      enumerable: true,\n    });\n  }\n  ancestors.delete(value);\n  return Object.freeze(result);\n}\n\nexport function ownState<T>(state: T): AgentState<T> {\n  try {\n    // SAFETY: copying retains every plain-data value and only adds deep readonly ownership.\n    return copy(state, new Set(), false) as AgentState<T>;\n  } catch (cause) {\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_STATE\",\n      \"Agent state must contain finite primitives, arrays, and plain records\",\n      cause\n    );\n  }\n}\n\nexport function checkSchema(schema: StandardSchemaV1, label: string): void {\n  if (schema?.[\"~standard\"]?.version !== 1 || typeof schema[\"~standard\"].validate !== \"function\") {\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      `${label} requires a Standard Schema validator`\n    );\n  }\n}\n\nexport function jsonDescriptor(\n  schema: StandardSchemaV1,\n  explicit: Readonly<Record<string, unknown>> | undefined,\n  label: string\n): Readonly<Record<string, unknown>> {\n  checkSchema(schema, label);\n  try {\n    const descriptor =\n      explicit ?? schema[\"~standard\"].jsonSchema?.input({ target: \"draft-2020-12\" });\n    if (descriptor === null || typeof descriptor !== \"object\" || Array.isArray(descriptor))\n      throw new Error(\"Missing JSON Schema object\");\n    // SAFETY: the object guard and plain JSON copy validate the descriptor's representation.\n    return copy(descriptor, new Set(), true) as Readonly<Record<string, unknown>>;\n  } catch (cause) {\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      `${label} requires a JSON Schema input descriptor or explicit fallback`,\n      cause\n    );\n  }\n}\n\nexport function descriptorFingerprint(descriptor: Readonly<Record<string, unknown>>): string {\n  return `sha256:${createHash(\"sha256\").update(JSON.stringify(descriptor)).digest(\"hex\")}`;\n}\n\nexport function checkDescription(description: string): void {\n  if (typeof description !== \"string\" || !description.trim() || description.length > 4096)\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      \"Tool description must be nonblank and at most 4096 characters\"\n    );\n}\n"]}

package/dist/agent/agent-types.d.ts

@@ -1,5 +1,6 @@
 import type { PipelineStepContext, StandardSchemaV1 } from "../core/pipeline-types.js";
 import type { AgentEnvironment, AgentEnvironmentProvider } from "./environment.js";
+import type { AgentDurability, AgentExecutionIdentity } from "./checkpoint-types.js";
 import type { DefaultAgentTools } from "./default-tools.js";
 export type Awaitable<T> = T | Promise<T>;
 export type Input<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"];
@@ -70,10 +71,12 @@ export interface AgentLimits {
 /** Step services and the workspace capability available to a registered tool. */
 export interface AgentToolContext extends PipelineStepContext<{}> {
     readonly environment: AgentEnvironment;
+    readonly execution?: AgentExecutionIdentity;
 }
 /** Model-facing descriptors and ordinary step services, without executable tools. */
 export interface AgentDecisionContext<Options extends object> extends PipelineStepContext<Options> {
     readonly environment: AgentEnvironment;
+    readonly execution?: AgentExecutionIdentity;
     readonly turn: number;
     readonly stateVersion: number;
     readonly capabilities: readonly {
@@ -87,6 +90,7 @@ export interface AgentDefinition<Id extends string, Options extends StandardSche
     readonly id: Id;
     readonly name?: string;
     readonly description?: string;
+    /** Semantic revision; required when this agent uses or inherits durable recovery. */
     readonly implementationVersion?: string;
     readonly inputSchema: Options;
     readonly resultSchema: Result;
@@ -96,6 +100,8 @@ export interface AgentDefinition<Id extends string, Options extends StandardSche
     readonly limits?: AgentLimits;
     /** Workspace capabilities; descendants inherit them unless explicitly replaced. */
     readonly environment?: AgentEnvironmentProvider;
+    /** Acknowledged recovery checkpoints; requires an explicit implementationVersion. */
+    readonly durability?: AgentDurability<Output<Options>>;
     initialState(options: Output<Options>): State;
     decide(state: AgentState<NoInfer<State>>, context: AgentDecisionContext<Output<Options>>): Awaitable<unknown>;
     reduce?(state: AgentState<NoInfer<State>>, outcomes: readonly AgentOutcome<Registry>[]): NoInfer<State>;

package/dist/agent/agent-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../../src/agent/agent-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { PipelineStepContext, StandardSchemaV1 } from \"../core/pipeline-types.js\";\nimport type { AgentEnvironment, AgentEnvironmentProvider } from \"./environment.js\";\nimport type { DefaultAgentTools } from \"./default-tools.js\";\n\nexport type Awaitable<T> = T | Promise<T>;\nexport type Input<S extends StandardSchemaV1> = NonNullable<S[\"~standard\"][\"types\"]>[\"input\"];\nexport type Output<S extends StandardSchemaV1> = NonNullable<S[\"~standard\"][\"types\"]>[\"output\"];\n/** Deeply read-only view of the owned plain-data state supplied to agent callbacks. */\nexport type AgentState<T> = { readonly [K in keyof T]: AgentState<T[K]> };\ndeclare const capabilityTypes: unique symbol;\n\n/** Opaque capability created by defineTool or pipelineTool; model decisions contain data only. */\nexport interface AgentTool<Arguments, Result> {\n  readonly [capabilityTypes]: { readonly input: Arguments; readonly output: Result };\n}\n\nexport type Tools = Readonly<Record<string, AgentTool<unknown, unknown>>>;\ntype RegisteredTools<Custom extends Tools> = Omit<DefaultAgentTools, keyof Custom> & Custom;\n\ntype ToolCall<Registry extends Tools> = {\n  [Name in keyof Registry & string]: {\n    readonly id: string;\n    readonly tool: Name;\n    readonly input: Registry[Name][typeof capabilityTypes][\"input\"];\n  };\n}[keyof Registry & string];\n\n/** One built-in or custom call with raw model arguments; custom names replace defaults. */\nexport type AgentCall<Registry extends Tools = {}> = ToolCall<RegisteredTools<Registry>>;\n\ntype ToolOutcome<Registry extends Tools> = {\n  [Name in keyof Registry & string]: {\n    readonly id: string;\n    readonly tool: Name;\n  } & (\n    | {\n        readonly ok: true;\n        readonly value: Registry[Name][typeof capabilityTypes][\"output\"];\n      }\n    | { readonly ok: false; readonly error: { readonly code: string; readonly message: string } }\n  );\n}[keyof Registry & string];\n\n/** Input-order result or deliberately recoverable handler failure, including default tools. */\nexport type AgentOutcome<Registry extends Tools = {}> = ToolOutcome<RegisteredTools<Registry>>;\n\n/** A nonempty batch of independent calls, or the raw input to the final-result schema. */\nexport type AgentDecision<Registry extends Tools, Result> =\n  | {\n      readonly kind: \"continue\";\n      readonly calls: readonly [AgentCall<Registry>, ...AgentCall<Registry>[]];\n      readonly result?: never;\n    }\n  | { readonly kind: \"finish\"; readonly result: Result; readonly calls?: never };\n\n/** Finite limits for this agent and its descendants; child limits may only tighten them. */\nexport interface AgentLimits {\n  /** Decision callbacks, including finish. Defaults to 20. */\n  readonly maxTurns?: number;\n  /** Admitted subtree calls, including calls stopped before dispatch. Defaults to 100. */\n  readonly maxCalls?: number;\n  /** Subtree decision callback admissions. Defaults to 100; provider retries are application-owned. */\n  readonly maxDecisions?: number;\n  /** Pipeline-tool delegation edges below this agent. Defaults to 4; zero allows leaf tools only. */\n  readonly maxDepth?: number;\n  /** Active decision callbacks and leaf handlers across the subtree. Defaults to 1. */\n  readonly maxConcurrency?: number;\n}\n\n/** Step services and the workspace capability available to a registered tool. */\nexport interface AgentToolContext extends PipelineStepContext<{}> {\n  readonly environment: AgentEnvironment;\n}\n\n/** Model-facing descriptors and ordinary step services, without executable tools. */\nexport interface AgentDecisionContext<Options extends object> extends PipelineStepContext<Options> {\n  readonly environment: AgentEnvironment;\n  readonly turn: number;\n  readonly stateVersion: number;\n  readonly capabilities: readonly {\n    readonly name: string;\n    readonly description: string;\n    readonly inputJsonSchema: Readonly<Record<string, unknown>>;\n  }[];\n  readonly resultJsonSchema: Readonly<Record<string, unknown>>;\n}\n\nexport interface AgentDefinition<\n  Id extends string,\n  Options extends StandardSchemaV1<object, object>,\n  Result extends StandardSchemaV1,\n  State,\n  Registry extends Tools,\n> {\n  readonly id: Id;\n  readonly name?: string;\n  readonly description?: string;\n  readonly implementationVersion?: string;\n  readonly inputSchema: Options;\n  readonly resultSchema: Result;\n  readonly resultJsonSchema?: Readonly<Record<string, unknown>>;\n  /** Extend the standard tools; a custom tool with the same name replaces that default. */\n  readonly tools?: Registry;\n  readonly limits?: AgentLimits;\n  /** Workspace capabilities; descendants inherit them unless explicitly replaced. */\n  readonly environment?: AgentEnvironmentProvider;\n  initialState(options: Output<Options>): State;\n  decide(\n    state: AgentState<NoInfer<State>>,\n    context: AgentDecisionContext<Output<Options>>\n  ): Awaitable<unknown>;\n  reduce?(\n    state: AgentState<NoInfer<State>>,\n    outcomes: readonly AgentOutcome<Registry>[]\n  ): NoInfer<State>;\n  dryRun?(\n    state: AgentState<NoInfer<State>>,\n    context: AgentDecisionContext<Output<Options>>\n  ): Awaitable<unknown>;\n}\n"]}
+{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../../src/agent/agent-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { PipelineStepContext, StandardSchemaV1 } from \"../core/pipeline-types.js\";\nimport type { AgentEnvironment, AgentEnvironmentProvider } from \"./environment.js\";\nimport type { AgentDurability, AgentExecutionIdentity } from \"./checkpoint-types.js\";\nimport type { DefaultAgentTools } from \"./default-tools.js\";\n\nexport type Awaitable<T> = T | Promise<T>;\nexport type Input<S extends StandardSchemaV1> = NonNullable<S[\"~standard\"][\"types\"]>[\"input\"];\nexport type Output<S extends StandardSchemaV1> = NonNullable<S[\"~standard\"][\"types\"]>[\"output\"];\n/** Deeply read-only view of the owned plain-data state supplied to agent callbacks. */\nexport type AgentState<T> = { readonly [K in keyof T]: AgentState<T[K]> };\ndeclare const capabilityTypes: unique symbol;\n\n/** Opaque capability created by defineTool or pipelineTool; model decisions contain data only. */\nexport interface AgentTool<Arguments, Result> {\n  readonly [capabilityTypes]: { readonly input: Arguments; readonly output: Result };\n}\n\nexport type Tools = Readonly<Record<string, AgentTool<unknown, unknown>>>;\ntype RegisteredTools<Custom extends Tools> = Omit<DefaultAgentTools, keyof Custom> & Custom;\n\ntype ToolCall<Registry extends Tools> = {\n  [Name in keyof Registry & string]: {\n    readonly id: string;\n    readonly tool: Name;\n    readonly input: Registry[Name][typeof capabilityTypes][\"input\"];\n  };\n}[keyof Registry & string];\n\n/** One built-in or custom call with raw model arguments; custom names replace defaults. */\nexport type AgentCall<Registry extends Tools = {}> = ToolCall<RegisteredTools<Registry>>;\n\ntype ToolOutcome<Registry extends Tools> = {\n  [Name in keyof Registry & string]: {\n    readonly id: string;\n    readonly tool: Name;\n  } & (\n    | {\n        readonly ok: true;\n        readonly value: Registry[Name][typeof capabilityTypes][\"output\"];\n      }\n    | { readonly ok: false; readonly error: { readonly code: string; readonly message: string } }\n  );\n}[keyof Registry & string];\n\n/** Input-order result or deliberately recoverable handler failure, including default tools. */\nexport type AgentOutcome<Registry extends Tools = {}> = ToolOutcome<RegisteredTools<Registry>>;\n\n/** A nonempty batch of independent calls, or the raw input to the final-result schema. */\nexport type AgentDecision<Registry extends Tools, Result> =\n  | {\n      readonly kind: \"continue\";\n      readonly calls: readonly [AgentCall<Registry>, ...AgentCall<Registry>[]];\n      readonly result?: never;\n    }\n  | { readonly kind: \"finish\"; readonly result: Result; readonly calls?: never };\n\n/** Finite limits for this agent and its descendants; child limits may only tighten them. */\nexport interface AgentLimits {\n  /** Decision callbacks, including finish. Defaults to 20. */\n  readonly maxTurns?: number;\n  /** Admitted subtree calls, including calls stopped before dispatch. Defaults to 100. */\n  readonly maxCalls?: number;\n  /** Subtree decision callback admissions. Defaults to 100; provider retries are application-owned. */\n  readonly maxDecisions?: number;\n  /** Pipeline-tool delegation edges below this agent. Defaults to 4; zero allows leaf tools only. */\n  readonly maxDepth?: number;\n  /** Active decision callbacks and leaf handlers across the subtree. Defaults to 1. */\n  readonly maxConcurrency?: number;\n}\n\n/** Step services and the workspace capability available to a registered tool. */\nexport interface AgentToolContext extends PipelineStepContext<{}> {\n  readonly environment: AgentEnvironment;\n  readonly execution?: AgentExecutionIdentity;\n}\n\n/** Model-facing descriptors and ordinary step services, without executable tools. */\nexport interface AgentDecisionContext<Options extends object> extends PipelineStepContext<Options> {\n  readonly environment: AgentEnvironment;\n  readonly execution?: AgentExecutionIdentity;\n  readonly turn: number;\n  readonly stateVersion: number;\n  readonly capabilities: readonly {\n    readonly name: string;\n    readonly description: string;\n    readonly inputJsonSchema: Readonly<Record<string, unknown>>;\n  }[];\n  readonly resultJsonSchema: Readonly<Record<string, unknown>>;\n}\n\nexport interface AgentDefinition<\n  Id extends string,\n  Options extends StandardSchemaV1<object, object>,\n  Result extends StandardSchemaV1,\n  State,\n  Registry extends Tools,\n> {\n  readonly id: Id;\n  readonly name?: string;\n  readonly description?: string;\n  /** Semantic revision; required when this agent uses or inherits durable recovery. */\n  readonly implementationVersion?: string;\n  readonly inputSchema: Options;\n  readonly resultSchema: Result;\n  readonly resultJsonSchema?: Readonly<Record<string, unknown>>;\n  /** Extend the standard tools; a custom tool with the same name replaces that default. */\n  readonly tools?: Registry;\n  readonly limits?: AgentLimits;\n  /** Workspace capabilities; descendants inherit them unless explicitly replaced. */\n  readonly environment?: AgentEnvironmentProvider;\n  /** Acknowledged recovery checkpoints; requires an explicit implementationVersion. */\n  readonly durability?: AgentDurability<Output<Options>>;\n  initialState(options: Output<Options>): State;\n  decide(\n    state: AgentState<NoInfer<State>>,\n    context: AgentDecisionContext<Output<Options>>\n  ): Awaitable<unknown>;\n  reduce?(\n    state: AgentState<NoInfer<State>>,\n    outcomes: readonly AgentOutcome<Registry>[]\n  ): NoInfer<State>;\n  dryRun?(\n    state: AgentState<NoInfer<State>>,\n    context: AgentDecisionContext<Output<Options>>\n  ): Awaitable<unknown>;\n}\n"]}

package/dist/agent/agent.d.ts

@@ -5,6 +5,9 @@ export { defineTool, ToolError } from "./tools.js";
 export type { DefaultAgentTools } from "./default-tools.js";
 export type { AgentCall, AgentDecision, AgentDecisionContext, AgentLimits, AgentOutcome, AgentState, AgentTool, AgentToolContext, } from "./agent-types.js";
 export type { AgentEnvironment, AgentEnvironmentContext, AgentEnvironmentProvider, AgentProjectInstruction, } from "./environment.js";
+export { createMemoryAgentCheckpointStore } from "./memory-checkpoint-store.js";
+export { plainAgentCheckpointCodec } from "./checkpoint-codec.js";
+export type { AgentCheckpointLease, AgentCheckpointStore, AgentCheckpointCodec, AgentDurability, AgentExecutionIdentity, } from "./checkpoint-types.js";
 export { defineModelAgent } from "./model-agent.js";
 export type { AgentModel, AgentModelRequest, AgentModelResponse } from "./model-types.js";
 /** Build a bounded in-process agent as an ordinary pipeline with one target, agent. */

package/dist/agent/agent.js

@@ -2,6 +2,8 @@ import { agentError } from "./agent-state.js";
 import { compileAgent } from "./compile-agent.js";
 export { pipelineTool } from "./pipeline-tool.js";
 export { defineTool, ToolError } from "./tools.js";
+export { createMemoryAgentCheckpointStore } from "./memory-checkpoint-store.js";
+export { plainAgentCheckpointCodec } from "./checkpoint-codec.js";
 export { defineModelAgent } from "./model-agent.js";
 /** Build a bounded in-process agent as an ordinary pipeline with one target, agent. */
 export function defineAgent(definition) {

package/dist/agent/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAoBnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAMzB,UAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IACtC,IAAI,OAAO,MAAM,KAAK,UAAU,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,UAAU,CAAC;QACxF,MAAM,UAAU,CACd,mCAAmC,EACnC,iDAAiD,CAClD,CAAC;IACJ,OAAO,YAAY,CAAuC;QACxD,GAAG,UAAU;QACb,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;QACrF,MAAM,EACJ,MAAM,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;KAC5F,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { StandardSchemaV1 } from \"../core/pipeline-types.js\";\nimport type { AgentDefinition, Tools } from \"./agent-types.js\";\nimport { agentError } from \"./agent-state.js\";\nimport { compileAgent } from \"./compile-agent.js\";\n\nexport { pipelineTool } from \"./pipeline-tool.js\";\nexport { defineTool, ToolError } from \"./tools.js\";\nexport type { DefaultAgentTools } from \"./default-tools.js\";\nexport type {\n  AgentCall,\n  AgentDecision,\n  AgentDecisionContext,\n  AgentLimits,\n  AgentOutcome,\n  AgentState,\n  AgentTool,\n  AgentToolContext,\n} from \"./agent-types.js\";\n\nexport type {\n  AgentEnvironment,\n  AgentEnvironmentContext,\n  AgentEnvironmentProvider,\n  AgentProjectInstruction,\n} from \"./environment.js\";\n\nexport { defineModelAgent } from \"./model-agent.js\";\nexport type { AgentModel, AgentModelRequest, AgentModelResponse } from \"./model-types.js\";\n\n/** Build a bounded in-process agent as an ordinary pipeline with one target, agent. */\nexport function defineAgent<\n  const Id extends string,\n  const Options extends StandardSchemaV1<object, object>,\n  const Result extends StandardSchemaV1,\n  State,\n  const Registry extends Tools = {},\n>(definition: AgentDefinition<Id, Options, Result, State, Registry>) {\n  const { decide, dryRun } = definition;\n  if (typeof decide !== \"function\" || (dryRun !== undefined && typeof dryRun !== \"function\"))\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      \"Agent requires callable decide/dryRun callbacks\"\n    );\n  return compileAgent<Id, Options, Result, State, Registry>({\n    ...definition,\n    decide: async (state, context) => ({ decision: await decide(state, context), state }),\n    dryRun:\n      dryRun && (async (state, context) => ({ decision: await dryRun(state, context), state })),\n  });\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAoBnD,OAAO,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AASlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAMzB,UAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IACtC,IAAI,OAAO,MAAM,KAAK,UAAU,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,UAAU,CAAC;QACxF,MAAM,UAAU,CACd,mCAAmC,EACnC,iDAAiD,CAClD,CAAC;IACJ,OAAO,YAAY,CAAuC;QACxD,GAAG,UAAU;QACb,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;QACrF,MAAM,EACJ,MAAM,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;KAC5F,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { StandardSchemaV1 } from \"../core/pipeline-types.js\";\nimport type { AgentDefinition, Tools } from \"./agent-types.js\";\nimport { agentError } from \"./agent-state.js\";\nimport { compileAgent } from \"./compile-agent.js\";\n\nexport { pipelineTool } from \"./pipeline-tool.js\";\nexport { defineTool, ToolError } from \"./tools.js\";\nexport type { DefaultAgentTools } from \"./default-tools.js\";\nexport type {\n  AgentCall,\n  AgentDecision,\n  AgentDecisionContext,\n  AgentLimits,\n  AgentOutcome,\n  AgentState,\n  AgentTool,\n  AgentToolContext,\n} from \"./agent-types.js\";\n\nexport type {\n  AgentEnvironment,\n  AgentEnvironmentContext,\n  AgentEnvironmentProvider,\n  AgentProjectInstruction,\n} from \"./environment.js\";\n\nexport { createMemoryAgentCheckpointStore } from \"./memory-checkpoint-store.js\";\nexport { plainAgentCheckpointCodec } from \"./checkpoint-codec.js\";\nexport type {\n  AgentCheckpointLease,\n  AgentCheckpointStore,\n  AgentCheckpointCodec,\n  AgentDurability,\n  AgentExecutionIdentity,\n} from \"./checkpoint-types.js\";\n\nexport { defineModelAgent } from \"./model-agent.js\";\nexport type { AgentModel, AgentModelRequest, AgentModelResponse } from \"./model-types.js\";\n\n/** Build a bounded in-process agent as an ordinary pipeline with one target, agent. */\nexport function defineAgent<\n  const Id extends string,\n  const Options extends StandardSchemaV1<object, object>,\n  const Result extends StandardSchemaV1,\n  State,\n  const Registry extends Tools = {},\n>(definition: AgentDefinition<Id, Options, Result, State, Registry>) {\n  const { decide, dryRun } = definition;\n  if (typeof decide !== \"function\" || (dryRun !== undefined && typeof dryRun !== \"function\"))\n    throw agentError(\n      \"TUBELESS_AGENT_INVALID_DEFINITION\",\n      \"Agent requires callable decide/dryRun callbacks\"\n    );\n  return compileAgent<Id, Options, Result, State, Registry>({\n    ...definition,\n    decide: async (state, context) => ({ decision: await decide(state, context), state }),\n    dryRun:\n      dryRun && (async (state, context) => ({ decision: await dryRun(state, context), state })),\n  });\n}\n"]}

package/dist/agent/checkpoint-calls.d.ts

@@ -0,0 +1,8 @@
+import type { SavedCall } from "./checkpoint-format.js";
+import type { PreparedCall } from "./decision.js";
+import type { AgentExecutionScope } from "./execution-scope.js";
+import type { CompiledTool } from "./tools.js";
+import type { PipelineStepContext } from "../core/pipeline-types.js";
+export declare function saveCalls(calls: readonly PreparedCall[]): SavedCall[];
+/** Reconstruct privately prepared invocations after the owning definition has matched. */
+export declare function restoreCalls(saved: readonly SavedCall[], registry: ReadonlyMap<string, CompiledTool>, scope: AgentExecutionScope, turn: number, context: PipelineStepContext<object>): PreparedCall[];

package/dist/agent/checkpoint-calls.js

@@ -0,0 +1,46 @@
+import { PreparedOptions } from "../core/prepared-options.js";
+import { agentError } from "./agent-state.js";
+export function saveCalls(calls) {
+    return calls.map((call) => {
+        const receipt = {
+            id: call.id,
+            tool: call.tool.name,
+            replay: call.tool.replay,
+            status: "pending",
+        };
+        return call.kind === "handler"
+            ? { ...receipt, kind: "handler", input: call.input }
+            : {
+                ...receipt,
+                kind: "pipeline",
+                input: call.options,
+                validatedOptions: call.preparedOptions.read(call.tool.pipeline.optionsSchema, call.options),
+            };
+    });
+}
+/** Reconstruct privately prepared invocations after the owning definition has matched. */
+export function restoreCalls(saved, registry, scope, turn, context) {
+    return saved.map((call) => {
+        const tool = registry.get(call.tool);
+        if (!tool || tool.kind !== call.kind)
+            throw agentError("TUBELESS_AGENT_CHECKPOINT_MISMATCH", `Saved tool ${call.tool} differs`);
+        const plan = tool.pipeline.plan({ dryRun: context.dryRun, cache: context.cachePolicy });
+        if (!plan.ok)
+            throw agentError("TUBELESS_AGENT_CHECKPOINT_MISMATCH", `Saved tool ${call.tool} has an invalid plan`);
+        if (tool.kind === "handler" && call.kind === "handler")
+            return { kind: "handler", id: call.id, tool, input: call.input, plan };
+        if (tool.kind !== "pipeline" || call.kind !== "pipeline")
+            throw new Error("Saved pipeline call differs from its tool");
+        const options = call.input;
+        return {
+            kind: "pipeline",
+            id: call.id,
+            tool,
+            options,
+            preparedOptions: PreparedOptions.restore(tool.pipeline.optionsSchema, options, call.validatedOptions),
+            scope: scope.delegate(turn, call.id),
+            plan,
+        };
+    });
+}
+//# sourceMappingURL=checkpoint-calls.js.map

package/dist/agent/checkpoint-calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-calls.js","sourceRoot":"","sources":["../../src/agent/checkpoint-calls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAO9C,MAAM,UAAU,SAAS,CAAC,KAA8B;IACtD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAa,EAAE;QACnC,MAAM,OAAO,GAAG;YACd,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;YACpB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;YACxB,MAAM,EAAE,SAAkB;SAC3B,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS;YAC5B,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;YACpD,CAAC,CAAC;gBACE,GAAG,OAAO;gBACV,IAAI,EAAE,UAAU;gBAChB,KAAK,EAAE,IAAI,CAAC,OAAO;gBACnB,gBAAgB,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CACzC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,EAChC,IAAI,CAAC,OAAO,CACb;aACF,CAAC;IACR,CAAC,CAAC,CAAC;AACL,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAC1B,KAA2B,EAC3B,QAA2C,EAC3C,KAA0B,EAC1B,IAAY,EACZ,OAAoC;IAEpC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;YAClC,MAAM,UAAU,CAAC,oCAAoC,EAAE,cAAc,IAAI,CAAC,IAAI,UAAU,CAAC,CAAC;QAC5F,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACxF,IAAI,CAAC,IAAI,CAAC,EAAE;YACV,MAAM,UAAU,CACd,oCAAoC,EACpC,cAAc,IAAI,CAAC,IAAI,sBAAsB,CAC9C,CAAC;QACJ,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YACpD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;QACzE,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YACtD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI;YACJ,OAAO;YACP,eAAe,EAAE,eAAe,CAAC,OAAO,CACtC,IAAI,CAAC,QAAQ,CAAC,aAAa,EAC3B,OAAO,EACP,IAAI,CAAC,gBAAgB,CACtB;YACD,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YACpC,IAAI;SACL,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { PreparedOptions } from \"../core/prepared-options.js\";\nimport { agentError } from \"./agent-state.js\";\nimport type { SavedCall } from \"./checkpoint-format.js\";\nimport type { PreparedCall } from \"./decision.js\";\nimport type { AgentExecutionScope } from \"./execution-scope.js\";\nimport type { CompiledTool } from \"./tools.js\";\nimport type { PipelineStepContext } from \"../core/pipeline-types.js\";\n\nexport function saveCalls(calls: readonly PreparedCall[]): SavedCall[] {\n  return calls.map((call): SavedCall => {\n    const receipt = {\n      id: call.id,\n      tool: call.tool.name,\n      replay: call.tool.replay,\n      status: \"pending\" as const,\n    };\n    return call.kind === \"handler\"\n      ? { ...receipt, kind: \"handler\", input: call.input }\n      : {\n          ...receipt,\n          kind: \"pipeline\",\n          input: call.options,\n          validatedOptions: call.preparedOptions.read(\n            call.tool.pipeline.optionsSchema,\n            call.options\n          ),\n        };\n  });\n}\n\n/** Reconstruct privately prepared invocations after the owning definition has matched. */\nexport function restoreCalls(\n  saved: readonly SavedCall[],\n  registry: ReadonlyMap<string, CompiledTool>,\n  scope: AgentExecutionScope,\n  turn: number,\n  context: PipelineStepContext<object>\n): PreparedCall[] {\n  return saved.map((call) => {\n    const tool = registry.get(call.tool);\n    if (!tool || tool.kind !== call.kind)\n      throw agentError(\"TUBELESS_AGENT_CHECKPOINT_MISMATCH\", `Saved tool ${call.tool} differs`);\n    const plan = tool.pipeline.plan({ dryRun: context.dryRun, cache: context.cachePolicy });\n    if (!plan.ok)\n      throw agentError(\n        \"TUBELESS_AGENT_CHECKPOINT_MISMATCH\",\n        `Saved tool ${call.tool} has an invalid plan`\n      );\n    if (tool.kind === \"handler\" && call.kind === \"handler\")\n      return { kind: \"handler\", id: call.id, tool, input: call.input, plan };\n    if (tool.kind !== \"pipeline\" || call.kind !== \"pipeline\")\n      throw new Error(\"Saved pipeline call differs from its tool\");\n    const options = call.input;\n    return {\n      kind: \"pipeline\",\n      id: call.id,\n      tool,\n      options,\n      preparedOptions: PreparedOptions.restore(\n        tool.pipeline.optionsSchema,\n        options,\n        call.validatedOptions\n      ),\n      scope: scope.delegate(turn, call.id),\n      plan,\n    };\n  });\n}\n"]}

package/dist/agent/checkpoint-codec.d.ts

@@ -0,0 +1,3 @@
+import type { AgentCheckpointCodec } from "./checkpoint-types.js";
+/** Lossless, tagged JSON codec for finite plain data; preserves undefined and sparse arrays. */
+export declare const plainAgentCheckpointCodec: AgentCheckpointCodec;

package/dist/agent/checkpoint-codec.js

@@ -0,0 +1,108 @@
+import { agentError } from "./agent-state.js";
+function encode(value, ancestors) {
+    if (value === undefined)
+        return ["undefined"];
+    if (value === null)
+        return ["null"];
+    if (typeof value === "string")
+        return ["string", value];
+    if (typeof value === "boolean")
+        return ["boolean", value];
+    if (typeof value === "number" && Number.isFinite(value))
+        return ["number", Object.is(value, -0) ? "-0" : String(value)];
+    if (typeof value !== "object" || ancestors.has(value))
+        throw new Error("Expected acyclic finite plain data");
+    const array = Array.isArray(value);
+    if (array && Object.getPrototypeOf(value) !== Array.prototype)
+        throw new Error("Expected a plain array; supply a lossless codec for array subclasses");
+    if (!array &&
+        Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null)
+        throw new Error("Expected an array or plain record; supply a lossless codec for other values");
+    ancestors.add(value);
+    const properties = [];
+    for (const key of Reflect.ownKeys(value).sort((a, b) => String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)) {
+        if (array && key === "length")
+            continue;
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== "string" || !("value" in property) || !property.enumerable)
+            throw new Error("Expected enumerable data properties");
+        properties.push([key, encode(property.value, ancestors)]);
+    }
+    ancestors.delete(value);
+    return array
+        ? ["array", value.length, properties]
+        : [Object.getPrototypeOf(value) === null ? "null-record" : "record", properties];
+}
+function decode(value) {
+    if (!Array.isArray(value))
+        throw new Error("Invalid checkpoint value");
+    const [tag, payload, properties] = value;
+    if (tag === "undefined" && value.length === 1)
+        return undefined;
+    if (tag === "null" && value.length === 1)
+        return null;
+    if (tag === "string" && value.length === 2 && typeof payload === "string")
+        return payload;
+    if (tag === "boolean" && value.length === 2 && typeof payload === "boolean")
+        return payload;
+    if (tag === "number" &&
+        value.length === 2 &&
+        typeof payload === "string" &&
+        Number.isFinite(Number(payload)) &&
+        (payload === "-0" || String(Number(payload)) === payload))
+        return Number(payload);
+    const array = tag === "array" &&
+        value.length === 3 &&
+        Number.isSafeInteger(payload) &&
+        payload >= 0 &&
+        payload <= 0xffff_ffff;
+    const entries = array
+        ? properties
+        : (tag === "record" || tag === "null-record") && value.length === 2
+            ? payload
+            : undefined;
+    if (!Array.isArray(entries))
+        throw new Error("Invalid checkpoint properties");
+    const result = array
+        ? new Array(payload)
+        : tag === "null-record"
+            ? Object.create(null)
+            : {};
+    for (const entry of entries) {
+        if (!Array.isArray(entry) ||
+            entry.length !== 2 ||
+            typeof entry[0] !== "string" ||
+            Object.hasOwn(result, entry[0]))
+            throw new Error("Invalid or duplicate checkpoint property");
+        Object.defineProperty(result, entry[0], {
+            value: decode(entry[1]),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    if (array && result.length !== payload)
+        throw new Error("Invalid checkpoint array length");
+    return result;
+}
+/** Lossless, tagged JSON codec for finite plain data; preserves undefined and sparse arrays. */
+export const plainAgentCheckpointCodec = Object.freeze({
+    encode: (value) => {
+        try {
+            return JSON.stringify(encode(value, new Set()));
+        }
+        catch (cause) {
+            throw agentError("TUBELESS_AGENT_CHECKPOINT_CODEC", "Cannot encode agent checkpoint losslessly", cause);
+        }
+    },
+    decode: (checkpoint) => {
+        try {
+            return decode(JSON.parse(checkpoint));
+        }
+        catch (cause) {
+            throw agentError("TUBELESS_AGENT_CHECKPOINT_CODEC", "Invalid encoded agent checkpoint", cause);
+        }
+    },
+});
+//# sourceMappingURL=checkpoint-codec.js.map

package/dist/agent/checkpoint-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-codec.js","sourceRoot":"","sources":["../../src/agent/checkpoint-codec.ts"],"names":[],"mappings":"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","sourcesContent":["import { agentError } from \"./agent-state.js\";\nimport type { AgentCheckpointCodec } from \"./checkpoint-types.js\";\n\ntype Encoded =\n  | [\"undefined\"]\n  | [\"null\"]\n  | [\"string\", string]\n  | [\"boolean\", boolean]\n  | [\"number\", string]\n  | [\"array\", number, [string, Encoded][]]\n  | [\"record\" | \"null-record\", [string, Encoded][]];\n\nfunction encode(value: unknown, ancestors: Set<object>): Encoded {\n  if (value === undefined) return [\"undefined\"];\n  if (value === null) return [\"null\"];\n  if (typeof value === \"string\") return [\"string\", value];\n  if (typeof value === \"boolean\") return [\"boolean\", value];\n  if (typeof value === \"number\" && Number.isFinite(value))\n    return [\"number\", Object.is(value, -0) ? \"-0\" : String(value)];\n  if (typeof value !== \"object\" || ancestors.has(value))\n    throw new Error(\"Expected acyclic finite plain data\");\n  const array = Array.isArray(value);\n  if (array && Object.getPrototypeOf(value) !== Array.prototype)\n    throw new Error(\"Expected a plain array; supply a lossless codec for array subclasses\");\n  if (\n    !array &&\n    Object.getPrototypeOf(value) !== Object.prototype &&\n    Object.getPrototypeOf(value) !== null\n  )\n    throw new Error(\"Expected an array or plain record; supply a lossless codec for other values\");\n  ancestors.add(value);\n  const properties: [string, Encoded][] = [];\n  for (const key of Reflect.ownKeys(value).sort((a, b) =>\n    String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0\n  )) {\n    if (array && key === \"length\") continue;\n    const property = Object.getOwnPropertyDescriptor(value, key)!;\n    if (typeof key !== \"string\" || !(\"value\" in property) || !property.enumerable)\n      throw new Error(\"Expected enumerable data properties\");\n    properties.push([key, encode(property.value, ancestors)]);\n  }\n  ancestors.delete(value);\n  return array\n    ? [\"array\", value.length, properties]\n    : [Object.getPrototypeOf(value) === null ? \"null-record\" : \"record\", properties];\n}\n\nfunction decode(value: unknown): unknown {\n  if (!Array.isArray(value)) throw new Error(\"Invalid checkpoint value\");\n  const [tag, payload, properties] = value;\n  if (tag === \"undefined\" && value.length === 1) return undefined;\n  if (tag === \"null\" && value.length === 1) return null;\n  if (tag === \"string\" && value.length === 2 && typeof payload === \"string\") return payload;\n  if (tag === \"boolean\" && value.length === 2 && typeof payload === \"boolean\") return payload;\n  if (\n    tag === \"number\" &&\n    value.length === 2 &&\n    typeof payload === \"string\" &&\n    Number.isFinite(Number(payload)) &&\n    (payload === \"-0\" || String(Number(payload)) === payload)\n  )\n    return Number(payload);\n  const array =\n    tag === \"array\" &&\n    value.length === 3 &&\n    Number.isSafeInteger(payload) &&\n    payload >= 0 &&\n    payload <= 0xffff_ffff;\n  const entries = array\n    ? properties\n    : (tag === \"record\" || tag === \"null-record\") && value.length === 2\n      ? payload\n      : undefined;\n  if (!Array.isArray(entries)) throw new Error(\"Invalid checkpoint properties\");\n  const result: unknown[] | Record<string, unknown> = array\n    ? new Array(payload)\n    : tag === \"null-record\"\n      ? Object.create(null)\n      : {};\n  for (const entry of entries) {\n    if (\n      !Array.isArray(entry) ||\n      entry.length !== 2 ||\n      typeof entry[0] !== \"string\" ||\n      Object.hasOwn(result, entry[0])\n    )\n      throw new Error(\"Invalid or duplicate checkpoint property\");\n    Object.defineProperty(result, entry[0], {\n      value: decode(entry[1]),\n      enumerable: true,\n      writable: true,\n      configurable: true,\n    });\n  }\n  if (array && (result as unknown[]).length !== payload)\n    throw new Error(\"Invalid checkpoint array length\");\n  return result;\n}\n\n/** Lossless, tagged JSON codec for finite plain data; preserves undefined and sparse arrays. */\nexport const plainAgentCheckpointCodec: AgentCheckpointCodec = Object.freeze({\n  encode: (value: unknown) => {\n    try {\n      return JSON.stringify(encode(value, new Set()));\n    } catch (cause) {\n      throw agentError(\n        \"TUBELESS_AGENT_CHECKPOINT_CODEC\",\n        \"Cannot encode agent checkpoint losslessly\",\n        cause\n      );\n    }\n  },\n  decode: (checkpoint: string) => {\n    try {\n      return decode(JSON.parse(checkpoint));\n    } catch (cause) {\n      throw agentError(\n        \"TUBELESS_AGENT_CHECKPOINT_CODEC\",\n        \"Invalid encoded agent checkpoint\",\n        cause\n      );\n    }\n  },\n});\n"]}

package/dist/agent/checkpoint-format.d.ts

@@ -0,0 +1,80 @@
+import type { AgentLimits, AgentOutcome, Tools } from "./agent-types.js";
+export interface StoredBudget {
+    depth: number;
+    limits: Required<AgentLimits>;
+    maxCalls: number;
+    maxDecisions: number;
+}
+export type CallOutcome = AgentOutcome<Tools>;
+export type SavedCall = {
+    id: string;
+    tool: string;
+    replay: "safe" | "unsafe";
+} & ({
+    kind: "handler";
+    input: unknown;
+    validatedOptions?: never;
+} | {
+    kind: "pipeline";
+    input: object;
+    validatedOptions: object;
+}) & ({
+    status: "pending" | "running";
+    outcome?: never;
+} | {
+    status: "completed";
+    outcome: CallOutcome;
+});
+export interface SavedDecision {
+    state: unknown;
+    calls: SavedCall[];
+    admitted: boolean;
+}
+interface AgentSnapshot {
+    metadata: {
+        definition: string;
+        implementationVersion?: string;
+        options: object;
+        environment: string;
+        cwd: string;
+        cache: "use" | "recompute" | "bypass";
+    };
+    execution: {
+        state: unknown;
+        turn: number;
+        stateVersion: number;
+        calls: number;
+    };
+}
+export type SavedAgent = AgentSnapshot & ({
+    phase: "decide";
+    decision?: never;
+    result?: never;
+    failure?: never;
+} | {
+    phase: "calls";
+    decision: SavedDecision;
+    result?: never;
+    failure?: never;
+} | {
+    phase: "completed";
+    result: unknown;
+    decision?: never;
+    failure?: never;
+} | {
+    phase: "failed";
+    failure: {
+        code: string;
+        message: string;
+    };
+    decision?: never;
+    result?: never;
+});
+export interface Checkpoint {
+    version: 1;
+    agents: Record<string, SavedAgent>;
+    budgets: Record<string, StoredBudget>;
+}
+/** Validate receipts and counters before treating decoded storage as prepared work. */
+export declare function checkedCheckpoint(value: unknown): Checkpoint;
+export {};

package/dist/agent/checkpoint-format.js

@@ -0,0 +1,116 @@
+function record(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+function natural(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function options(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function failure(value) {
+    return record(value) && typeof value.code === "string" && typeof value.message === "string";
+}
+function checkCall(call, admitted, ids) {
+    if (!record(call) ||
+        typeof call.id !== "string" ||
+        !call.id.trim() ||
+        call.id.length > 256 ||
+        ids.has(call.id) ||
+        typeof call.tool !== "string" ||
+        !/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(call.tool) ||
+        !["handler", "pipeline"].includes(String(call.kind)) ||
+        !["safe", "unsafe"].includes(String(call.replay)) ||
+        !["pending", "running", "completed"].includes(String(call.status)) ||
+        !Object.hasOwn(call, "input"))
+        throw new Error("Invalid saved call");
+    ids.add(call.id);
+    if (call.kind === "pipeline" && (!options(call.input) || !options(call.validatedOptions)))
+        throw new Error("Invalid saved pipeline options");
+    if (!admitted && call.status !== "pending")
+        throw new Error("Unadmitted call has started");
+    if (call.status === "completed") {
+        const outcome = call.outcome;
+        if (!record(outcome) ||
+            outcome.id !== call.id ||
+            outcome.tool !== call.tool ||
+            typeof outcome.ok !== "boolean" ||
+            (outcome.ok ? !Object.hasOwn(outcome, "value") : !failure(outcome.error)))
+            throw new Error("Invalid saved call outcome");
+    }
+}
+function checkAgent(agent) {
+    if (!record(agent) || !record(agent.metadata) || !record(agent.execution))
+        throw new Error("Invalid saved agent");
+    const { metadata, execution } = agent;
+    if (typeof metadata.definition !== "string" ||
+        typeof metadata.environment !== "string" ||
+        typeof metadata.cwd !== "string" ||
+        !options(metadata.options) ||
+        (metadata.implementationVersion !== undefined &&
+            typeof metadata.implementationVersion !== "string") ||
+        !["use", "recompute", "bypass"].includes(String(metadata.cache)))
+        throw new Error("Invalid saved agent metadata");
+    if (!Object.hasOwn(execution, "state") ||
+        !natural(execution.turn) ||
+        execution.turn < 1 ||
+        !natural(execution.stateVersion) ||
+        !natural(execution.calls) ||
+        !["decide", "calls", "completed", "failed"].includes(String(agent.phase)))
+        throw new Error("Invalid saved agent execution");
+    if (agent.phase === "completed" && !Object.hasOwn(agent, "result"))
+        throw new Error("Missing saved agent result");
+    if (agent.phase === "failed" && !failure(agent.failure))
+        throw new Error("Invalid saved agent failure");
+    if (agent.phase === "calls") {
+        const decision = agent.decision;
+        if (!record(decision) ||
+            !Object.hasOwn(decision, "state") ||
+            !Array.isArray(decision.calls) ||
+            decision.calls.length === 0 ||
+            typeof decision.admitted !== "boolean")
+            throw new Error("Invalid saved call batch");
+        const ids = new Set();
+        for (const call of decision.calls)
+            checkCall(call, decision.admitted, ids);
+    }
+}
+function checkBudget(budget) {
+    if (!record(budget) ||
+        !natural(budget.depth) ||
+        !natural(budget.maxCalls) ||
+        !natural(budget.maxDecisions) ||
+        !record(budget.limits))
+        throw new Error("Invalid saved agent budget");
+    for (const name of [
+        "maxTurns",
+        "maxCalls",
+        "maxDecisions",
+        "maxDepth",
+        "maxConcurrency",
+    ]) {
+        const bound = budget.limits[name];
+        if (!natural(bound) || (!["maxCalls", "maxDepth"].includes(name) && bound === 0))
+            throw new Error("Invalid saved agent limits");
+    }
+    if (budget.maxCalls > Number(budget.limits.maxCalls) ||
+        budget.maxDecisions > Number(budget.limits.maxDecisions))
+        throw new Error("Saved agent budget exceeds its limits");
+}
+/** Validate receipts and counters before treating decoded storage as prepared work. */
+export function checkedCheckpoint(value) {
+    if (!record(value) || value.version !== 1 || !record(value.agents) || !record(value.budgets))
+        throw new Error("Invalid agent checkpoint envelope");
+    for (const [key, agent] of Object.entries(value.agents)) {
+        checkAgent(agent);
+        if (!Object.hasOwn(value.budgets, key))
+            throw new Error("Missing saved agent budget");
+    }
+    for (const budget of Object.values(value.budgets))
+        checkBudget(budget);
+    // SAFETY: metadata, execution counters, call receipts and budget contracts were checked above.
+    return value;
+}
+//# sourceMappingURL=checkpoint-format.js.map