@superdurable/dex-agents 0.3.0 → 0.5.0

package/dist/src/agent-context-compaction.d.ts

@@ -2,7 +2,7 @@ import type { AgentEventWriter, AgentFrameworkRunner, AgentTurnContext, Deferred
 import type { AgentMessage, AgentUsage, ContextSummary, SessionSettings } from "./agent-session-values.js";
 /**
  * When a session summarizes its earlier messages so the model input stays under the context window, passed
- * as {@link AgentSessionOptions.compaction} or as `AgentDefinition.compaction` for a Stepwise agent.
+ * as {@link AgentSessionOptions.compaction} or as `AgentDefinition.compaction` for a built-in loop agent.
  *
  * Before each model call, `RunModel` asks the runner for the size of the next model input. When it reaches
  * {@link triggerRatio} of {@link contextWindowTokens}, `RunModel` makes no model call and moves to

package/dist/src/agent-framework-runner.d.ts

@@ -1,6 +1,7 @@
+import type { AsyncContext, RetryPolicy } from "@superdurable/dex";
 import type { BuiltInTool } from "./agent-built-in-tools.js";
 import type { ContextSummaryRequest, ContextSummaryResult } from "./agent-context-compaction.js";
-import type { AgentMessage, AgentPlan, AgentToolCall, AgentToolCallRecord, AgentToolCallStatus, AgentUsage, ContextSummary, SessionSettings, FrameworkMessage, InteractionMode, QuestionAnswer, ToolEffect } from "./agent-session-values.js";
+import type { AgentImageReference, AgentMessage, AgentPlan, AgentToolCall, AgentToolCallRecord, AgentToolCallStatus, AgentUsage, ContextSummary, SessionSettings, FrameworkMessage, InteractionMode, QuestionAnswer, ToolEffect } from "./agent-session-values.js";
 /**
  * Per-tool override of the effect and approval defaults.
  *
@@ -134,11 +135,14 @@ export interface AgentTurnContext {
      */
     readonly messages: readonly AgentMessage[];
     /**
-     * Framework run state from this turn's previous {@link ToolCallsRequested} outcome, or `null` for
-     * the turn's first model call.
+     * Framework run state from this turn's previous {@link ToolCallsRequested} or {@link TurnContinued} outcome,
+     * or `null` for the turn's first model call.
      */
     readonly frameworkRunState: string | null;
-    /** Whether this model call continues the turn after tool calls, that is, `frameworkRunState` is set. */
+    /**
+     * Whether this model call continues the turn after tool calls or after a {@link TurnContinued} outcome, that
+     * is, `frameworkRunState` is set.
+     */
     readonly isResuming: boolean;
     /**
      * Tool call records of this turn, in deferral order; every record is final. Give the framework the
@@ -241,6 +245,15 @@ export interface DeferredToolCall {
      * the tool without listing it again. Omit it to store nothing.
      */
     readonly toolSourceReference?: string;
+    /**
+     * Whether the call is a write that runs in the model's order after the turn's earlier ordered calls.
+     * The session starts one ordered call at a time, raises its approval only when its turn comes, and
+     * records later ordered calls as skipped once one does not succeed. `read` calls ignore it. When
+     * omitted, the call runs in parallel with the turn's other calls. `ConnectorToolSource` sets it for
+     * connector writes.
+     * @since 0.4.0
+     */
+    readonly ordered?: boolean;
 }
 /**
  * Model and response of one model call, returned in {@link TurnCompleted} or {@link ToolCallsRequested}
@@ -297,6 +310,62 @@ export interface TurnCompleted {
     readonly usage: AgentUsage;
     /** Model and response of this model call, for the `chat` span. When omitted, the span is named `chat`. */
     readonly modelCallMetadata?: ModelCallMetadata;
+    /**
+     * Error text that ends the turn as failed instead of completed.
+     *
+     * When it is set, the session still stores {@link newMessages} and records {@link usage} in the same commit.
+     * It then sets the turn's `lastTurnError` to this text and writes a `turn_failed` event instead of
+     * `turn_completed`. No retry follows, so use it only for a deliberate stop that a retry would repeat, such as a
+     * limit the runner enforces. Throw instead for a failure that a retry may fix. Omit it, the default, to complete
+     * the turn. Snapshots and the UI stream show the text, so keep secrets out of it.
+     *
+     * @since 0.5.0
+     */
+    readonly turnError?: string;
+}
+/**
+ * Outcome of a model call that answered without tool calls, after which the turn continues with another model
+ * call.
+ *
+ * The session stores {@link newMessages}, records {@link usage}, keeps {@link frameworkRunState}, and moves to
+ * `RunModel` again, all in one commit, within the same turn. That next `RunModel` is its own Step, so a retry there
+ * repeats only its own model call. Its {@link AgentTurnContext.messages} include these messages. End them with a
+ * user message when the next request must end with one, as Anthropic models from Claude 4.6 on require. The
+ * built-in loop returns this outcome when `AgentDefinition.decideTurnContinuation` returns a continuation, with its
+ * message as the last of {@link newMessages}.
+ *
+ * A runner that returns it with messages must implement {@link AgentFrameworkRunner.buildUnfinishedTurnMessages},
+ * as for {@link ToolCallsRequested.newMessages}; the session fails the turn otherwise. A runner that never returns
+ * it needs no change.
+ *
+ * @example
+ * ```ts
+ * return {
+ *   kind: "turn_continued",
+ *   frameworkRunState: JSON.stringify({ model_calls: modelCalls + 1 }),
+ *   newMessages: [...previousToolResults, ...thisResponse, continuationUserMessage],
+ *   usage,
+ * };
+ * ```
+ * @since 0.5.0
+ */
+export interface TurnContinued {
+    /** Discriminator. */
+    readonly kind: "turn_continued";
+    /**
+     * Non-empty serialized framework state from which the next `RunModel` continues the turn. The session keeps it
+     * opaquely in `FrameworkRunState`, as it keeps {@link ToolCallsRequested.frameworkRunState}.
+     */
+    readonly frameworkRunState: string;
+    /**
+     * Messages of the turn to store now: the previous model response's unstored tool results, if any, this model
+     * response, and any user message for the next call. The next {@link AgentTurnContext.messages} include them.
+     */
+    readonly newMessages: readonly FrameworkMessage[];
+    /** Usage of this model call only. */
+    readonly usage: AgentUsage;
+    /** Model and response of this model call, for the `chat` span. When omitted, the span is named `chat`. */
+    readonly modelCallMetadata?: ModelCallMetadata;
 }
 /** Outcome of a model call that requested tool calls. */
 export interface ToolCallsRequested {
@@ -329,8 +398,12 @@ export interface ToolCallsRequested {
     /** Model and response of this model call, for the `chat` span. When omitted, the span is named `chat`. */
     readonly modelCallMetadata?: ModelCallMetadata;
 }
-/** Result of {@link AgentFrameworkRunner.runModelStep}. */
-export type AgentTurnOutcome = TurnCompleted | ToolCallsRequested;
+/**
+ * Result of {@link AgentFrameworkRunner.runModelStep}.
+ *
+ * Changed in 0.5.0: {@link TurnContinued} joined the union, so code that handles every kind handles it too.
+ */
+export type AgentTurnOutcome = TurnCompleted | ToolCallsRequested | TurnContinued;
 /** One tool call that a tool Step asks the runner to run. */
 export interface DeferredToolExecution {
     /** Flow ID, which is the session ID. */
@@ -387,11 +460,66 @@ export interface DeferredToolExecution {
      * @returns A Promise that resolves when the Worker accepted the heartbeat.
      */
     saveHeartbeatCheckpoint?(checkpoint: string): Promise<void>;
+    /**
+     * The tool Step's live context, absent when the caller has none, such as a unit test. It gives the Step
+     * execution ID, the attempt deadline, and heartbeats. Use it only during this call and never store it.
+     * Record heartbeats only through {@link heartbeat} and {@link saveHeartbeatCheckpoint}, because a bare
+     * `context.recordHeartbeat()` would drop the checkpoint. It is never part of stored state.
+     * `ConnectorToolSource` derives the connector Call ID from its Step execution ID.
+     * @since 0.4.0
+     */
+    readonly context?: AsyncContext;
 }
 /** Successful result of one deferred tool call. A result without `kind` is a `ToolExecutionResult`. */
 export interface ToolExecutionResult {
     /** Output text recorded on the call and shown to the model. */
     readonly output: string;
+    /**
+     * Size in bytes of the full output when {@link output} is a truncated copy; omit it when the output is
+     * whole. The session stores it as {@link AgentToolCall.truncatedOutputBytes}.
+     * @since 0.4.0
+     */
+    readonly truncatedOutputBytes?: number;
+    /**
+     * Images the tool returns with {@link output}, uploaded with `MediaStore.putImage` inside the call, at most
+     * `maxImagesPerMessage`. The session stores them as {@link AgentToolCall.images}; a reference that
+     * `validateImageReference` refuses fails the attempt. Upload before returning: a retried attempt uploads the same
+     * bytes to the same object. Omit it for none.
+     * @since 0.5.0
+     */
+    readonly images?: readonly AgentImageReference[];
+    /**
+     * Opaque text the runner keeps with the call's result for its own later model calls, such as the framework
+     * state that the tool changed. The session stores it as {@link AgentToolCall.runnerToolState} of the
+     * `succeeded` record, and `runModelStep` reads it from `AgentTurnContext.toolCalls`. The session never interprets
+     * it and never shows it to the model, in the browser snapshot from `agentSnapshotToJson`, or in trace attributes.
+     * Only the attempt that commits the result stores it, so a retried attempt never adds a second copy. Omit it to
+     * store nothing.
+     * @since 0.5.0
+     */
+    readonly runnerToolState?: string;
+}
+/**
+ * Timeout and retry policy of one tool call's Step, returned by
+ * {@link AgentFrameworkRunner.toolCallStepOptions}.
+ *
+ * The session applies it to the movement that starts the call's tool Step, and to no other Step. A
+ * `CallSingleAttemptTool` call takes only {@link executeMethodTimeout}; it still runs one attempt.
+ *
+ * @example
+ * ```ts
+ * const options: ToolCallStepOptions = {
+ *   executeMethodTimeout: 30_000,
+ *   executeRetry: { maximumAttempts: 3, totalDuration: 3_600_000 },
+ * };
+ * ```
+ * @since 0.4.0
+ */
+export interface ToolCallStepOptions {
+    /** Timeout of each attempt in milliseconds; omit it for the tool Step's default. */
+    readonly executeMethodTimeout?: number;
+    /** Retry policy of a `CallTool` call; omit it for the default of three attempts. */
+    readonly executeRetry?: RetryPolicy;
 }
 /**
  * Result of a deferred tool call that needs an answer from the user before it can take effect.
@@ -548,6 +676,33 @@ export interface ToolTaskCancellation {
 export type DeferredToolOutcome = ToolExecutionResult | ToolInputRequested | ToolTaskStarted;
 /** Result of {@link AgentFrameworkRunner.pollToolTask}. */
 export type ToolTaskPollOutcome = ToolExecutionResult | ToolInputRequested | ToolTaskPending;
+/**
+ * Tool failure whose effect may or may not have happened, thrown from
+ * {@link AgentFrameworkRunner.executeDeferredToolCall}.
+ *
+ * Throw it when the tool sent a write and cannot tell whether it took effect, such as a connector
+ * operation's `uncertain` branch. The session records `outcome_unknown` with this error's message as
+ * `error`, does not retry, and the model sees {@link outcomeUnknownToolResult}. A later ordered write of
+ * the turn is skipped.
+ *
+ * {@link AgentFrameworkRunner.pollToolTask} may throw it too, for a task that ended without a known
+ * outcome. The session then records `outcome_unknown` the same way and stops polling. Changed in 0.5.0:
+ * `pollToolTask` may throw it.
+ *
+ * @example
+ * ```ts
+ * throw new ToolOutcomeUnknownError("the provider timed out after receiving the refund");
+ * ```
+ * @since 0.4.0
+ */
+export declare class ToolOutcomeUnknownError extends Error {
+    /**
+     * Creates an unknown-outcome failure.
+     * @param message - Error text recorded on the call.
+     * @param options - Standard error options, such as `cause`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
 /**
  * Tool failure that the model should see, thrown from {@link AgentFrameworkRunner.executeDeferredToolCall}.
  *
@@ -629,12 +784,35 @@ export interface AgentFrameworkRunner<ToolOutcome extends DeferredToolOutcome =
      * @returns The framework message, with `role` `"user"`.
      */
     buildUserMessage(text: string): FrameworkMessage;
+    /**
+     * Converts a user message with images into the framework's user message. Optional.
+     *
+     * Implement it when the runner can show images to its model. `send_user_message` accepts images only for a runner
+     * with this method, and the session calls it instead of {@link buildUserMessage} for a message with images. Put
+     * the references, never the bytes, in `frameworkItem`; read the bytes with `loadImages` when the model call
+     * builds its input. The session sets the stored message's `images` itself. It must be synchronous,
+     * deterministic, and free of side effects.
+     *
+     * @example
+     * ```ts
+     * public buildUserMessageWithImages(text: string, images: readonly AgentImageReference[]): FrameworkMessage {
+     *   return { role: "user", text, toolCallId: null, toolName: null, toolArguments: null, toolOutput: null,
+     *     frameworkItem: JSON.stringify({ role: "user", content: text, images }) };
+     * }
+     * ```
+     * @param text - User message text, never blank.
+     * @param images - The message's images, at least one, each valid for `validateImageReference`.
+     * @returns The framework message, with `role` `"user"`.
+     * @since 0.5.0
+     */
+    buildUserMessageWithImages?(text: string, images: readonly AgentImageReference[]): FrameworkMessage;
     /**
      * Makes the turn's next model call, at most one.
      *
      * @param turn - Turn context; see {@link AgentTurnContext}.
-     * @returns {@link TurnCompleted} with every new message of the turn, or {@link ToolCallsRequested}
-     * with the framework run state and every tool call of the model response.
+     * @returns {@link TurnCompleted} with every new message of the turn, {@link ToolCallsRequested}
+     * with the framework run state and every tool call of the model response, or {@link TurnContinued} to make
+     * another model call within the same turn.
      * @throws Any error to retry the model call; after the last attempt the turn fails.
      */
     runModelStep(turn: AgentTurnContext): Promise<AgentTurnOutcome>;
@@ -671,8 +849,8 @@ export interface AgentFrameworkRunner<ToolOutcome extends DeferredToolOutcome =
      * Such a runner reads {@link AgentTurnContext.interactionMode} in every `runModelStep`. In a `planning`
      * turn it offers only the `write_todos` definition from {@link builtInToolDefinitions}. It may force
      * `write_todos` on the turn's first model call while the plan is not a draft yet, where the model accepts a
-     * forced tool choice; Stepwise does with `planningToolChoice: "required"`. In every
-     * turn it shows the plan with {@link buildPlanNote} as user text before the turn's messages. The Stepwise
+     * forced tool choice; the built-in loop does with `planningToolChoice: "required"`. In every
+     * turn it shows the plan with {@link buildPlanNote} as user text before the turn's messages. The built-in loop
      * runner implements it; a framework adapter that cannot change the tools it offers between turns leaves
      * plan mode off.
      */
@@ -701,6 +879,9 @@ export interface AgentFrameworkRunner<ToolOutcome extends DeferredToolOutcome =
      * the call's result.
      * @throws {ToolExecutionError} When the task failed in a way the model should see; the call is
      * recorded as `failed`.
+     * @throws {ToolOutcomeUnknownError} When the task ended and may or may not have taken effect; the call is
+     * recorded as `outcome_unknown` and not polled again. Changed in 0.5.0: this error is recorded instead of
+     * failing the poll attempt.
      * @throws Any other error to fail the poll attempt; after three attempts the record becomes `failed`
      * for a `read` call and `outcome_unknown` otherwise, because the task may still run.
      */
@@ -727,6 +908,25 @@ export interface AgentFrameworkRunner<ToolOutcome extends DeferredToolOutcome =
      * three times, then records the call `outcome_unknown` anyway, so the turn always ends.
      */
     cancelToolTask?(cancellation: ToolTaskCancellation): Promise<void>;
+    /**
+     * Returns the timeout and retry policy of one call's tool Step. Optional.
+     *
+     * Implement it when some tools need options other than the tool Steps' defaults, as the built-in loop runner
+     * does for a tool source that defines `toolCallStepOptions`. The session calls it whenever it starts a
+     * call's tool Step, including after an approval, so it must answer from the record alone. A method that
+     * throws leaves the defaults.
+     *
+     * @example
+     * ```ts
+     * public toolCallStepOptions(toolCall: AgentToolCall): ToolCallStepOptions | undefined {
+     *   return toolCall.toolName === "export_report" ? { executeMethodTimeout: 120_000 } : undefined;
+     * }
+     * ```
+     * @param toolCall - The record whose tool Step starts.
+     * @returns The options, or `undefined` for the defaults.
+     * @since 0.4.0
+     */
+    toolCallStepOptions?(toolCall: AgentToolCall): ToolCallStepOptions | undefined;
     /**
      * Estimates the size of the model input that the next {@link runModelStep} sends. Optional; one of the
      * three compaction methods that {@link AgentSessionOptions.compaction} requires.

package/dist/src/agent-framework-runner.js

@@ -29,6 +29,36 @@ export function resolveToolPolicy(toolName, toolPolicies, defaultToolEffect, fra
     const requiresApproval = policy?.requiresApproval ?? (effect === "non_idempotent_write" || effect === "unclassified");
     return { effect, requiresApproval };
 }
+/**
+ * Tool failure whose effect may or may not have happened, thrown from
+ * {@link AgentFrameworkRunner.executeDeferredToolCall}.
+ *
+ * Throw it when the tool sent a write and cannot tell whether it took effect, such as a connector
+ * operation's `uncertain` branch. The session records `outcome_unknown` with this error's message as
+ * `error`, does not retry, and the model sees {@link outcomeUnknownToolResult}. A later ordered write of
+ * the turn is skipped.
+ *
+ * {@link AgentFrameworkRunner.pollToolTask} may throw it too, for a task that ended without a known
+ * outcome. The session then records `outcome_unknown` the same way and stops polling. Changed in 0.5.0:
+ * `pollToolTask` may throw it.
+ *
+ * @example
+ * ```ts
+ * throw new ToolOutcomeUnknownError("the provider timed out after receiving the refund");
+ * ```
+ * @since 0.4.0
+ */
+export class ToolOutcomeUnknownError extends Error {
+    /**
+     * Creates an unknown-outcome failure.
+     * @param message - Error text recorded on the call.
+     * @param options - Standard error options, such as `cause`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ToolOutcomeUnknownError";
+    }
+}
 /**
  * Tool failure that the model should see, thrown from {@link AgentFrameworkRunner.executeDeferredToolCall}.
  *

package/dist/src/agent-framework-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-framework-runner.js","sourceRoot":"","sources":["../../src/agent-framework-runner.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAmD1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,YAAkD,EAClD,iBAA6B,EAC7B,eAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,eAAe,IAAI,iBAAiB,CAAC;IACtE,MAAM,gBAAgB,GACpB,MAAM,EAAE,gBAAgB,IAAI,CAAC,MAAM,KAAK,sBAAsB,IAAI,MAAM,KAAK,cAAc,CAAC,CAAC;IAC/F,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACtC,CAAC;AAogBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;;;;OAIG;IACH,YAAmB,OAAe,EAAE,OAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AA+ND;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAA+B;IAE/B,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,WAAW,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"agent-framework-runner.js","sourceRoot":"","sources":["../../src/agent-framework-runner.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAsD1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,YAAkD,EAClD,iBAA6B,EAC7B,eAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,eAAe,IAAI,iBAAiB,CAAC;IACtE,MAAM,gBAAgB,GACpB,MAAM,EAAE,gBAAgB,IAAI,CAAC,MAAM,KAAK,sBAAsB,IAAI,MAAM,KAAK,cAAc,CAAC,CAAC;IAC/F,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACtC,CAAC;AAqoBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;;;;OAIG;IACH,YAAmB,OAAe,EAAE,OAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;;;;OAIG;IACH,YAAmB,OAAe,EAAE,OAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AA4QD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAA+B;IAE/B,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,WAAW,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/agent-local-directory-media-store.d.ts

@@ -0,0 +1,111 @@
+import { type MediaStore } from "./agent-media.js";
+import type { AgentImageReference } from "./agent-session-values.js";
+/**
+ * Keeps image bytes in a local directory, one file per distinct image.
+ *
+ * Use it when every client and Worker of a session runs on one machine, such as a command-line tool in local mode;
+ * use `S3MediaStore` from `@superdurable/dex-agents/s3` when they run on different machines.
+ *
+ * The file of an image is `<root>/sha256/<sha256>`, and a reference's `uri` is `file://<root>/sha256/<sha256>`, where
+ * `<root>` is the absolute root with every UTF-8 byte other than ASCII letters, digits, `-`, `.`, `_`, `~`, and `/`
+ * written as `%XX` in uppercase hex. The root is made absolute as text: `.` and `..` segments and repeated or trailing
+ * `/` characters are resolved without reading the file system, symbolic links are not resolved, and Unicode is not
+ * normalized. A client and a Worker that pass the same root therefore build the same references, in every core.
+ *
+ * `putImage` copies the bytes into a temporary file in the same directory, syncs it, and renames it into place, so a
+ * reader never sees a partial image. An existing file with the same bytes is success, so retried and concurrent uploads
+ * of the same bytes leave one file; an existing file with other bytes is replaced. Directories the store creates get
+ * mode `0700` and image files mode `0600`, narrowed further by the process umask. When `putImage` writes the image, it
+ * syncs the file before the rename. Before every `putImage` returns, including when an identical file already exists
+ * and nothing is written, it syncs the `sha256` directory, the root, and the root's parent. It also syncs the parent of
+ * each directory it creates. Directories above the root's parent must already be durable: a concurrent creator of a
+ * deeper missing ancestor is out of scope.
+ *
+ * The store refuses a `sha256` directory or an image file that is a symbolic link or not a regular file, and an image
+ * file with more than one hard link, with `MediaStoreError`, on both upload and read. The root itself may be a symbolic
+ * link. Node.js has no `openat`, so this store opens files by path and checks before and after each operation: it
+ * checks the `sha256` directory with `lstat` and opens the file with `O_NOFOLLOW`, then confirms that the real path of
+ * the `sha256` directory is still the root's and that the path still names the opened or written file. A read that
+ * fails the check returns nothing, and a write that fails it removes the file it wrote when it can still find it. A
+ * process of the same user that can write the `0700` root can still race a directory swap between these checks; the
+ * Python core opens every path relative to an open directory and has no such window. `getImage` reads only
+ * references under this store's root, refuses a file whose size differs from the reference before reading it, reads at
+ * most one byte more than `sizeBytes`, and checks the bytes with `verifyImageBytes`. It needs a POSIX file system; on
+ * Windows the constructor throws.
+ *
+ * Session deletion does not delete files. A runner reads a session's images again whenever a model call replays them,
+ * so keep every file at least as long as any session that references it can still run a turn or replay its history. A
+ * missing file makes those turns fail with `MediaStoreError`.
+ *
+ * @example
+ * ```ts
+ * import { LocalDirectoryMediaStore } from "@superdurable/dex-agents";
+ *
+ * const store = new LocalDirectoryMediaStore("/var/lib/my-agent/media");
+ * const reference = await store.putImage(screenshotPng);
+ * // reference.uri === "file:///var/lib/my-agent/media/sha256/9f2c..."
+ * ```
+ * @since 0.5.0
+ */
+export declare class LocalDirectoryMediaStore implements MediaStore {
+    /** The absolute root directory, made absolute as text, without a trailing `/`. */
+    readonly root: string;
+    /** The location that every reference of this store starts with: `"file://<root>"`, with the root percent-encoded. */
+    readonly storeUri: string;
+    /**
+     * Creates a store; it touches no file until the first upload or read.
+     *
+     * @param root - Absolute path of the directory that holds the images, such as `"/var/lib/my-agent/media"`. The first
+     * upload creates it and any missing parent directory with mode `0700`.
+     * @throws {TypeError} When `root` is not absolute, is not well-formed Unicode, contains NUL, or is the file system
+     * root.
+     * @throws {RangeError} When `root` makes image URIs longer than `maxImageUriLength`.
+     * @throws {Error} On a system without POSIX file access, such as Windows.
+     */
+    constructor(root: string);
+    /**
+     * Returns the path of the file of the image with this SHA-256.
+     *
+     * @param sha256 - SHA-256 of the bytes as 64 lowercase hex digits.
+     * @returns `"<root>/sha256/<sha256>"`.
+     */
+    imagePath(sha256: string): string;
+    /**
+     * Stores one image unless the directory already has it, and returns its reference.
+     *
+     * @param data - PNG, JPEG, GIF, or WebP bytes, at most `maxImageBytes`.
+     * @returns The reference.
+     * @throws {ImageValidationError} When the bytes are not a valid image for `buildImageReference`. Nothing is written.
+     * @throws {MediaStoreError} When the `sha256` directory or the image's file is a symbolic link or not a directory or
+     * regular file, the image's file has more than one hard link, or the `sha256` directory changed during the write.
+     * @throws A Node.js system error (`NodeJS.ErrnoException`) when the file system refuses a write, such as for missing
+     * permissions or a full disk. Retrying is safe.
+     */
+    putImage(data: Uint8Array): Promise<AgentImageReference>;
+    /**
+     * Returns the bytes of one image in this store.
+     *
+     * @param reference - A reference under this store's root.
+     * @returns The exact bytes, checked with `verifyImageBytes`.
+     * @throws {ImageValidationError} When the reference's fields are invalid.
+     * @throws {MediaStoreError} When the reference is outside this store's root, the file is missing, is a symbolic link
+     * or not a regular file, has more than one hard link, moved during the read, or its bytes do not match.
+     * @throws A Node.js system error (`NodeJS.ErrnoException`) when the file system refuses the read for another reason.
+     */
+    getImage(reference: AgentImageReference): Promise<Uint8Array>;
+    private imageDirectory;
+    /** Creates the root and its missing parents with mode `0700`, syncing the parent of each. */
+    private makeRoot;
+    /** Throws `MediaStoreError` unless the `sha256` directory is a real directory, not a symbolic link. */
+    private requireImageDirectory;
+    /** Returns whether the image's file exists and holds exactly `data`. */
+    private hasImageFile;
+    /** Opens the reference's image file, refusing symbolic links, special files, hard links, and moved files. */
+    private openImageFile;
+    /** Returns the open file, or `undefined` when a rename replaced it after the open. */
+    private openImageFileOnce;
+    /** Returns whether the `sha256` directory is a real directory whose real path is the root's. */
+    private isImageDirectoryInStore;
+    private directoryChanged;
+    private replaceImageFile;
+}