@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/harnesses/pi-durable/registry.d.ts

@@ -0,0 +1,18 @@
+export declare const REGISTRY_KINDS: readonly ["tools", "extensions", "channels", "schedules"];
+type RegistryKind = (typeof REGISTRY_KINDS)[number];
+/** One module of the definition: where it is, and what it default-exports. */
+interface RegisteredModule {
+    /** Relative to the agent directory, as the author opens it: `src/tools/weather.ts`. */
+    file: string;
+    /** The file's name without its extension: a schedule's name. */
+    name: string;
+    value: unknown;
+}
+export type Registry = Record<RegistryKind, readonly RegisteredModule[]>;
+export declare const GENERATED_DIR = ".fastagent";
+export declare const REGISTRY_FILE = "registry.ts";
+/** The registry's source: one default import per module, grouped by directory. */
+export declare function registrySource(dir: string): Promise<string>;
+/** Write `.fastagent/registry.ts` for the agent in `dir`, and return its path. */
+export declare function generateRegistry(dir: string): Promise<string>;
+export {};

package/dist/harnesses/pi-durable/registry.js

@@ -0,0 +1,56 @@
+/**
+ * The generated registry (architecture.md §3): `.fastagent/registry.ts`, plain imports of every module in `src/tools/`,
+ * `src/extensions/`, `src/channels/` and `src/schedules/`, so nothing is imported by hand, types flow and a bundler can
+ * follow it. Each module default-exports one thing; a file directly in the directory is a module, and anything else a
+ * module imports (a helper) lives outside these directories. Generated from the files, never edited.
+ */
+import { readdir } from "node:fs/promises";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { join } from "node:path";
+export const REGISTRY_KINDS = ["tools", "extensions", "channels", "schedules"];
+export const GENERATED_DIR = ".fastagent";
+export const REGISTRY_FILE = "registry.ts";
+const MODULE = /^([^.][^/]*)\.(ts|mts|js|mjs)$/;
+const NOT_A_MODULE = /\.(d|test|spec)\.[a-z]+$/;
+/** The module files of one directory of `src/`, sorted so the registry is the same wherever it is generated. */
+async function modulesIn(dir, kind) {
+    let names;
+    try {
+        names = await readdir(join(dir, "src", kind));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return names.sort().flatMap((entry) => {
+        const match = MODULE.exec(entry);
+        return match === null || NOT_A_MODULE.test(entry)
+            ? []
+            : [{ file: `src/${kind}/${entry}`, name: match[1] }];
+    });
+}
+/** The registry's source: one default import per module, grouped by directory. */
+export async function registrySource(dir) {
+    const lines = ["// Generated by fastagent from src/: do not edit.", ""];
+    const groups = [];
+    let index = 0;
+    for (const kind of REGISTRY_KINDS) {
+        const entries = [];
+        for (const { file, name } of await modulesIn(dir, kind)) {
+            const local = `m${index++}`;
+            lines.push(`import ${local} from ${JSON.stringify(`../${file}`)};`);
+            entries.push(`  { file: ${JSON.stringify(file)}, name: ${JSON.stringify(name)}, value: ${local} },`);
+        }
+        groups.push(`export const ${kind} = [\n${entries.join("\n")}${entries.length > 0 ? "\n" : ""}];`);
+    }
+    return `${lines.join("\n")}${index > 0 ? "\n" : ""}\n${groups.join("\n\n")}\n`;
+}
+/** Write `.fastagent/registry.ts` for the agent in `dir`, and return its path. */
+export async function generateRegistry(dir) {
+    const path = join(dir, GENERATED_DIR, REGISTRY_FILE);
+    // Every command that reads the definition writes it, `dev`'s worker importing it meanwhile: a reader must see a whole
+    // file, and two writers write the same bytes.
+    writeFileAtomic(path, await registrySource(dir), undefined, true);
+    return path;
+}

package/dist/harnesses/pi-durable/release.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Temporary: pi-durable 1.3.0 leaves a conversation's queued messages waiting after a run that did not answer (a model
+ * failure, an abort, a message sent while an aborted run was still ending) until another submission places them, while
+ * the Agent API takes them whatever the message before them ended with (SPEC.md §5.3). A write of FastAgent's own
+ * kind places them. Remove once pi-durable ships `afterFailedRun` and it covers aborts too.
+ */
+import type { Context } from "@earendil-works/chord/context";
+import { type Harness } from "@earendil-works/pi-durable";
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import { type PortFailure } from "../../effect-port.ts";
+/** Release every conversation that waits now, and each one a run that did not answer leaves waiting, until the scope closes. */
+export declare const releaseWaitingQueues: (harness: Harness, context: Context) => Effect.Effect<void, PortFailure, Scope.Scope>;

package/dist/harnesses/pi-durable/release.js

@@ -0,0 +1,40 @@
+import { InboxDoc, LiveDoc } from "@earendil-works/pi-durable";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import { port, portError } from "../../effect-port.js";
+import { log } from "../../log.js";
+import { RELEASE_ENTRY } from "./entries.js";
+import { queuedInputs } from "./messages.js";
+/** Release every conversation that waits now, and each one a run that did not answer leaves waiting, until the scope closes. */
+export const releaseWaitingQueues = (harness, context) => Effect.gen(function* () {
+    const waiting = yield* Queue.unbounded();
+    const unsubscribe = harness.subscribeCommits(({ changes }) => {
+        for (const change of changes) {
+            const record = change.type === "submission" ? change.value : undefined;
+            if (record?.type === "input" && record.status === "unanswered") {
+                Queue.offerUnsafe(waiting, record.conversationId);
+            }
+        }
+    });
+    yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
+    yield* Queue.take(waiting).pipe(Effect.flatMap((conversationId) => release(harness, conversationId, context).pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`[fastagent] could not take the messages waiting in conversation ${conversationId}: ${String(portError(cause))}`))))), Effect.forever, Effect.forkScoped);
+    const inspection = yield* port(() => harness.inspect(context));
+    for (const record of inspection.submissions) {
+        if (record.type === "input" && record.status === "queued")
+            Queue.offerUnsafe(waiting, record.conversationId);
+    }
+});
+function release(harness, conversationId, context) {
+    return Effect.gen(function* () {
+        const live = yield* port(() => harness.snapshot(LiveDoc, conversationId, context));
+        if (live?.run !== undefined)
+            return;
+        const inbox = yield* port(() => harness.snapshot(InboxDoc, conversationId, context));
+        if (queuedInputs(inbox).length === 0)
+            return;
+        const conversation = yield* port(() => harness.conversation(conversationId, context));
+        if (conversation === undefined)
+            return;
+        yield* port(() => conversation.submit({ type: "write", entry: { kind: RELEASE_ENTRY, edits: [] } }, context));
+    });
+}

package/dist/harnesses/pi-durable/serve.d.ts

@@ -0,0 +1,80 @@
+import type { CredentialStore, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { type Harness } from "@earendil-works/pi-durable";
+import type { CredentialSourceOptions } from "../models/credentials.ts";
+import { type ModelEnvironment } from "../models/environment.ts";
+import { type ResolvedContent } from "../../content/resolve.ts";
+import type { Agent } from "../../agent-api.ts";
+import { type Service } from "../../service.ts";
+import type { DurableAgent, Unfinished } from "./agent.ts";
+import { type AgentDefinition, type BuiltDefinition } from "./open.ts";
+import { type StorageLocking } from "./storage.ts";
+export interface OpenServingOptions extends CredentialSourceOptions {
+    /** What a deployment sets over the definition's defaults (a flag, `FASTAGENT_MODEL`). */
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    /**
+     * Where the Agent keeps its sessions. Default `{ instance: "posix" }`: the instance's `agent.sqlite`, which one process
+     * holds at a time (storage.ts), with `wake` and `unwake`, since a serve's clock fires the wake-ups they keep. The other
+     * two never meet the storage a serve of the same directory holds, and have no `wake`, since no clock fires for them:
+     * `{ file }` is a database of the caller's own, held the same way (`holders`, when given, names in the refusal of a
+     * second opener what else opens it), and `"memory"` keeps nothing.
+     */
+    storage?: ServingStorage;
+    /** What becomes of the messages an earlier process left unfinished in the storage. Default `"resume"`. */
+    unfinished?: Unfinished;
+}
+type ServingStorage = {
+    instance: StorageLocking;
+} | {
+    file: string;
+    holders?: string;
+} | "memory";
+export interface OpenedServing {
+    agent: DurableAgent;
+    definition: AgentDefinition;
+    code: BuiltDefinition;
+    models: ModelEnvironment;
+    /** What the agent works on and knows, resolved for this instance. */
+    content: readonly ResolvedContent[];
+    agentDir: string;
+    /** Where the instance's state is: its storage, its channels' and schedules' state, its wake-ups. */
+    stateRoot: string;
+    /** The definition's channels and schedules, as `serveAgent` serves them: `serveAgent(opened)`. */
+    channels: BuiltDefinition["channels"];
+    schedules: BuiltDefinition["schedules"];
+}
+/**
+ * Run `work` holding the instance's storage, so no serve of the instance runs meanwhile: how a command changes the
+ * instance's state outside a serve without losing a write to a serve's own.
+ */
+export declare function holdingInstance<T>(stateRoot: string, work: () => T): Promise<T>;
+export declare function openServing(directory: string, options?: OpenServingOptions): Promise<OpenedServing>;
+/** An agent opened in this process (SPEC.md §8): the Agent API, and how it is served and operated. */
+export interface LocalAgent extends Agent {
+    /**
+     * Channels, schedules and wake-ups, `/health`, and the Agent API under `/v1` when `apiKeys` holds a key: a Fetch
+     * handler, or a server of its own (`listen`).
+     */
+    serve(options?: ServeAgentOptions): Promise<Service>;
+    /** pi-durable's own API, for operating the agent. */
+    readonly harness: Harness;
+    /** Close what `serve` started, then release the instance's storage. */
+    close(): Promise<void>;
+}
+export interface ServeAgentOptions {
+    /** The keys a Caller of the Agent API may present (SPEC.md §9.1). */
+    apiKeys?: readonly string[];
+}
+export interface OpenAgentOptions {
+    /** `"provider/modelId"`, over the definition's: what a session that names none answers with. */
+    model?: string;
+    /** Where provider credentials are kept, instead of the agent's own `.secrets/auth.json` over the machine's. */
+    credentials?: CredentialStore;
+}
+/**
+ * Open the agent directory `dir` the way `dev` and `start` do before they serve: its definition, its code built with
+ * the secrets it declares, its environment, its content and the instance's storage, which one process holds at a time.
+ * Nothing reaches the agent until `serve`.
+ */
+export declare function openAgent(dir: string, options?: OpenAgentOptions): Promise<LocalAgent>;
+export {};

package/dist/harnesses/pi-durable/serve.js

@@ -0,0 +1,156 @@
+/**
+ * An agent package opened: its definition prepared (the registry generated, the secrets manifest written), its code
+ * built with its secrets, its model environment, its storage, and the Agent over them. `openAgent` is how an app opens
+ * one (SPEC.md §8); `dev`, `start`, AgentCore, `invoke` and `schedules run` open it through `openServing`, which
+ * also takes where the Agent keeps its sessions and what becomes of an earlier process's messages.
+ */
+import { join } from "node:path";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { MemoryStorage } from "@earendil-works/pi-durable";
+import { modelEnvironment } from "../models/environment.js";
+import { loadContent } from "../../content/file.js";
+import { absentNotice, cloneContent, contentAbsentHere, resolveContent, } from "../../content/resolve.js";
+import { enterEnvironment } from "../../environment/mise.js";
+import { log } from "../../log.js";
+import { resolveStateRoot } from "../../paths.js";
+import { serveAgent } from "../../service.js";
+import { buildDefinition, assembleAgent, prepareDefinition, } from "./open.js";
+import { openLockedStorage } from "./storage.js";
+/** Who opens the instance's storage, for the refusal of a second opener. */
+const INSTANCE_HOLDERS = "another `fastagent dev`, `start` or `schedules` command of this agent (or of another agent with the same state root)";
+/**
+ * The content, once per process, before the agent opens: the locations are fixed until a restart, what is in them is
+ * read per message. This process runs the agent, so a repository with no checkout here is cloned, or its clone brought
+ * up to date in place where git can do so without touching the agent's work, first; then resolved again as what is now
+ * on disk.
+ */
+async function contentForThisRun(dir) {
+    const declaration = loadContent(dir);
+    for (const entry of resolveContent(dir, declaration)) {
+        if (entry.kind !== "github" || !entry.clone)
+            continue;
+        const done = await cloneContent(entry);
+        if (done.outcome === "kept") {
+            log.warn(`[fastagent] content "${entry.name}": the clone in ${entry.location} is kept as it is, ${done.reason}`);
+        }
+        else {
+            const said = { cloned: "cloned", updated: "brought up to date", current: "already up to date" }[done.outcome];
+            log.info(`[fastagent] github ${entry.repo}${entry.ref ? ` at ${entry.ref}` : ""}: ${said} in ${entry.location}`);
+        }
+    }
+    for (const absent of contentAbsentHere(declaration))
+        log.warn(`[fastagent] content ${absentNotice(absent)}`);
+    return resolveContent(dir, declaration);
+}
+/** The instance's database, under its state root. */
+const instanceStorageFile = (stateRoot) => join(stateRoot, "agent.sqlite");
+/**
+ * Run `work` holding the instance's storage, so no serve of the instance runs meanwhile: how a command changes the
+ * instance's state outside a serve without losing a write to a serve's own.
+ */
+export async function holdingInstance(stateRoot, work) {
+    const storage = await openLockedStorage(instanceStorageFile(stateRoot), "posix", INSTANCE_HOLDERS);
+    try {
+        return work();
+    }
+    finally {
+        await storage.close(BACKGROUND_CONTEXT);
+    }
+}
+function openStorage(stateRoot, storage) {
+    if (storage === "memory")
+        return new MemoryStorage();
+    if ("file" in storage)
+        return openLockedStorage(storage.file, "posix", storage.holders);
+    return openLockedStorage(instanceStorageFile(stateRoot), storage.instance, INSTANCE_HOLDERS);
+}
+export async function openServing(directory, options = {}) {
+    const definition = await prepareDefinition(directory);
+    const { dir } = definition;
+    const code = buildDefinition(definition);
+    // The commands the agent runs, as `context.json`'s environment declares them, before anything can run one.
+    await enterEnvironment(dir);
+    const content = await contentForThisRun(dir);
+    const models = await modelEnvironment(dir, {
+        ...(options.authPath === undefined ? {} : { authPath: options.authPath }),
+        ...(options.credentialStore === undefined ? {} : { credentialStore: options.credentialStore }),
+    }, code.providers);
+    const stateRoot = resolveStateRoot(dir);
+    const chosen = options.storage ?? { instance: "posix" };
+    const storage = await openStorage(stateRoot, chosen);
+    const agent = await assembleAgent(definition, {
+        storage,
+        code,
+        content,
+        models: models.models,
+        ...(models.catalogProblem === undefined ? {} : { catalogProblem: models.catalogProblem }),
+        ...(typeof chosen === "object" && "instance" in chosen ? { stateRoot } : {}),
+        ...(options.model === undefined ? {} : { model: options.model }),
+        ...(options.thinkingLevel === undefined ? {} : { thinkingLevel: options.thinkingLevel }),
+        ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
+    }).catch(async (error) => {
+        // An Agent that did not open does not own the storage, and its lock would refuse this process's next attempt.
+        await storage.close(BACKGROUND_CONTEXT);
+        throw error;
+    });
+    return {
+        agent,
+        definition,
+        code,
+        models,
+        content,
+        agentDir: dir,
+        stateRoot,
+        channels: code.channels,
+        schedules: code.schedules,
+    };
+}
+/**
+ * Open the agent directory `dir` the way `dev` and `start` do before they serve: its definition, its code built with
+ * the secrets it declares, its environment, its content and the instance's storage, which one process holds at a time.
+ * Nothing reaches the agent until `serve`.
+ */
+export async function openAgent(dir, options = {}) {
+    const opened = await openServing(dir, {
+        ...(options.model === undefined ? {} : { model: options.model }),
+        ...(options.credentials === undefined ? {} : { credentialStore: options.credentials }),
+    });
+    const { agent } = opened;
+    let served;
+    let closing;
+    return {
+        info: agent.info,
+        usage: agent.usage,
+        sessions: agent.sessions,
+        messages: agent.messages,
+        harness: agent.harness,
+        serve(serveOptions = {}) {
+            // Its storage is let go, or about to be: a service now would run channels and schedules nobody closes.
+            if (closing !== undefined)
+                return Promise.reject(new Error("this agent is closed"));
+            if (served !== undefined)
+                return Promise.reject(new Error("this agent is already served"));
+            const serving = serveAgent(opened, serveOptions);
+            served = serving;
+            // A serve that failed to start rolled itself back, so the agent may be served again.
+            serving.catch(() => {
+                if (served === serving)
+                    served = undefined;
+            });
+            return serving;
+        },
+        close() {
+            closing ??= (async () => {
+                // A serve that never started has nothing to close; its failure reached the caller of `serve`.
+                const service = await served?.catch(() => undefined);
+                const failures = [];
+                await service?.close().catch((error) => failures.push(error));
+                await agent.close().catch((error) => failures.push(error));
+                if (failures.length > 0) {
+                    throw failures.length === 1 ? failures[0] : new AggregateError(failures, "the agent did not close cleanly");
+                }
+            })();
+            return closing;
+        },
+    };
+}

package/dist/harnesses/pi-durable/sessions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which conversations are sessions, and each one's latest activity (SPEC.md §4), kept in memory as a cache of the
+ * storage: read once when the Agent opens, then moved forward by every commit, so `sessions.list` orders without
+ * reading the storage and every operation asks the same question `sessions.list` answers.
+ *
+ * pi-durable mints every record's id from one counter that grows across reopen (`Storage.mintId`), so a session's
+ * latest activity is the newest of its own ids: its creation, its newest message, its newest entry. No clock is
+ * needed. A conversation a task owns (a subagent's) is the harness's own work, not a session.
+ */
+import type { Context } from "@earendil-works/chord/context";
+import type { ConversationId, ConversationRecord, Harness, Storage } from "@earendil-works/pi-durable";
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import { type PortFailure } from "../../effect-port.ts";
+export declare const isSession: (record: ConversationRecord) => boolean;
+interface SessionActivity {
+    conversationId: ConversationId;
+    activity: number;
+}
+export interface Sessions {
+    has(id: ConversationId): boolean;
+    /** Most recently active first. */
+    byActivity(): SessionActivity[];
+}
+/** The cache, following commits until the scope closes. */
+export declare const trackSessions: (harness: Harness, storage: Storage, context: Context) => Effect.Effect<Sessions, PortFailure, Scope.Scope>;
+export {};

package/dist/harnesses/pi-durable/sessions.js

@@ -0,0 +1,47 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { port } from "../../effect-port.js";
+const SCAN_PAGE = 500;
+export const isSession = (record) => record.owner === undefined;
+const conversations = (storage, context) => Stream.paginate(undefined, (cursor) => port(() => storage.scanConversations({}, SCAN_PAGE, cursor, context)).pipe(Effect.map((page) => [[page.items], Option.fromUndefinedOr(page.next)]))).pipe(Stream.flattenIterable);
+/** What the storage holds before the cache follows commits: the newest entry an existing session wrote, and message. */
+const storedActivity = (storage, context, conversation) => Effect.all([
+    port(() => storage.scanEntries({ conversationId: conversation.id, order: "descending" }, 1, undefined, context)),
+    port(() => storage.scanSubmissions({ conversationId: conversation.id, order: "descending" }, 1, undefined, context)),
+], { concurrency: "unbounded" }).pipe(
+// An entry a fork shares is older than the fork, so the fork-aware entry scan cannot overstate it.
+Effect.map(([entries, submissions]) => Math.max(conversation.id, entries.items[0]?.id ?? 0, submissions.items[0]?.id ?? 0)));
+/** The cache, following commits until the scope closes. */
+export const trackSessions = (harness, storage, context) => Effect.gen(function* () {
+    const sessions = new Set();
+    const newest = new Map();
+    const touch = (id, value) => {
+        if (value > (newest.get(id) ?? 0))
+            newest.set(id, value);
+    };
+    // Subscribed before the scan, so a commit while it reads is not lost: either reports the newest id, and the
+    // larger stands. A change's conversation may be created in the same commit, so membership is not checked here.
+    yield* Effect.acquireRelease(Effect.sync(() => harness.subscribeCommits(({ changes }) => {
+        for (const change of changes) {
+            if (change.type === "conversation") {
+                if (isSession(change.value))
+                    sessions.add(change.value.id);
+                touch(change.value.id, change.value.id);
+            }
+            else if (change.type === "entry" || change.type === "submission") {
+                touch(change.value.conversationId, change.value.id);
+            }
+        }
+    })), (unsubscribe) => Effect.sync(unsubscribe));
+    yield* conversations(storage, context).pipe(Stream.filter(isSession), Stream.runForEach((conversation) => storedActivity(storage, context, conversation).pipe(Effect.tap((activity) => Effect.sync(() => {
+        sessions.add(conversation.id);
+        touch(conversation.id, activity);
+    })))));
+    return {
+        has: (id) => sessions.has(id),
+        byActivity: () => [...sessions]
+            .map((conversationId) => ({ conversationId, activity: newest.get(conversationId) ?? conversationId }))
+            .sort((a, b) => b.activity - a.activity),
+    };
+});

package/dist/harnesses/pi-durable/storage.d.ts

@@ -0,0 +1,4 @@
+import type { Storage } from "@earendil-works/pi-durable";
+export type StorageLocking = "posix" | "leased-dotfile";
+/** Open the database at `path`, or refuse, naming `holders` (what else opens it) when given. */
+export declare function openLockedStorage(path: string, locking: StorageLocking, holders?: string): Promise<Storage>;

package/dist/harnesses/pi-durable/storage.js

@@ -0,0 +1,49 @@
+/**
+ * A storage only one process opens: the instance's SQLite database, held by the one process that owns the instance
+ * (architecture.md §4.3), and `fastagent invoke`'s own. pi-durable does no cross-process locking of its own, and in
+ * WAL mode SQLite lets a second process open and write the same file, which would resume and run the same messages
+ * twice. So the database is opened in EXCLUSIVE locking mode: the first access takes the file's lock and keeps it
+ * until the process closes it or dies, and a second opener is refused. Locally that is SQLite's own POSIX lock. On a
+ * file system where those fail (AgentCore's session storage), the database locks by a `<path>.lock` directory
+ * instead, which outlives a stopped microVM: the process that holds the deployment's lease knows such a lock is a dead
+ * process's, removes it, and says so.
+ */
+import { existsSync, mkdirSync, rmdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { NodeSqliteDatabase } from "@earendil-works/pi-durable/storage/sqlite/node";
+import { SqliteStorage } from "@earendil-works/pi-durable/storage/sqlite";
+import { log } from "../../log.js";
+/** How long an opener waits for a lock: long enough for a restart's old process to finish closing. */
+const BUSY_TIMEOUT_MS = 5_000;
+const SQLITE_BUSY = 5;
+/** Open the database at `path`, or refuse, naming `holders` (what else opens it) when given. */
+export async function openLockedStorage(path, locking, holders) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (locking === "leased-dotfile")
+        breakStaleLock(`${path}.lock`);
+    const location = locking === "posix" ? path : `file:${path}?vfs=unix-dotfile`;
+    const database = new DatabaseSync(location, { timeout: BUSY_TIMEOUT_MS });
+    const adapter = new NodeSqliteDatabase(database);
+    try {
+        // In this order: an exclusive lock keeps WAL's index in this process's memory, so no shared memory is needed.
+        await adapter.exec("PRAGMA locking_mode = EXCLUSIVE");
+        await adapter.exec("PRAGMA journal_mode = WAL");
+        await adapter.exec("PRAGMA synchronous = NORMAL");
+        return await SqliteStorage.open(adapter);
+    }
+    catch (error) {
+        // The connection only: the adapter's close checkpoints first, which a refused opener cannot do.
+        database.close();
+        if (error.errcode !== SQLITE_BUSY)
+            throw error;
+        const who = holders === undefined ? "" : `: ${holders} is running`;
+        throw new Error(`the storage ${path} is held by another process${who}. Stop that one first`, { cause: error });
+    }
+}
+function breakStaleLock(lock) {
+    if (!existsSync(lock))
+        return;
+    rmdirSync(lock);
+    log.warn(`[fastagent] removed ${lock}: a process that held the storage stopped without releasing it`);
+}

package/dist/harnesses/pi-durable/stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `messages.stream` (SPEC.md §6.2): send a message and deliver it as it is written, over the Agent's own reads.
+ * The session is watched before the message is sent, so nothing it writes afterwards is missed; a send whose key the
+ * session has seen delivers that message from wherever it is.
+ */
+import { type Entry, type Message, type MessageStreamEvent, type Page, type SendRequest, type SessionEvent } from "../../agent-api.ts";
+export interface StreamSource {
+    events(sessionId: string, after?: string): AsyncIterable<SessionEvent>;
+    /** A send, and whether its key had already been sent: the message is then delivered from where it is. */
+    admit(request: SendRequest): Promise<{
+        message: Message;
+        replayed: boolean;
+    }>;
+    get(sessionId: string, messageId: string): Promise<Message>;
+    entry(sessionId: string, entryId: string): Promise<Entry>;
+    entries(sessionId: string, options: {
+        after: string;
+    }): Promise<Page<Entry>>;
+}
+export declare function messageStream(source: StreamSource, request: SendRequest, signal: AbortSignal | undefined): AsyncIterable<MessageStreamEvent>;