@fastagent-sh/fastagent 0.24.3 → 0.25.0

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

@@ -0,0 +1,77 @@
+/**
+ * What an agent's author writes (architecture.md §3): `defineAgent()` in `fastagent.config.ts`, `needs()` around the
+ * code that reads a secret, and `defineSchedule()` in `src/schedules/`. Each returns what it was given, typed; the
+ * assembly (open.ts) reads them back.
+ */
+import type { ModelThinkingLevel, Provider } from "@earendil-works/pi-ai";
+import type { Extension } from "@earendil-works/pi-durable";
+import type { ScheduleConfig } from "../../schedule/schedule.ts";
+export interface AgentConfig {
+    /** Default: `package.json`'s name. */
+    name?: string;
+    description?: string;
+    /** `"provider/modelId"`: what a session that names none answers with; a deployment may override it. */
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    /** Third-party capabilities, installed after `src/extensions/`. */
+    extensions?: readonly (Extension | Needs<Extension>)[];
+    /** Model providers beyond pi-ai's built-ins (a self-hosted endpoint, a gateway); a built-in's id replaces it. */
+    providers?: readonly (Provider | Needs<Provider>)[];
+    http?: {
+        /** The port a serve listens on, for its channels' webhooks and its health check. */
+        port?: number;
+        /**
+         * Whether a serve answers the Agent API under `/v1` with a key (default true): `dev`, `start`, and every deployment,
+         * which `deploy` gives a key. `false` keeps it to its channels and schedules, whatever key its environment holds.
+         */
+        api?: boolean;
+    };
+    /** How the agent is deployed, where a host needs to be told. */
+    deploy?: {
+        agentcore?: {
+            idleTimeoutSeconds?: number;
+        };
+    };
+}
+/** @public */
+export declare function defineAgent(config: AgentConfig): AgentConfig;
+/** One secret a piece of code reads: by name, or with what it is for and whether the code runs without it. */
+/** @public */
+export type SecretSpec = string | {
+    name: string;
+    description?: string;
+    optional?: boolean;
+};
+type NameOf<S> = S extends string ? S : S extends {
+    name: infer N extends string;
+} ? N : never;
+type IsOptional<S> = S extends {
+    optional: true;
+} ? true : false;
+/** The values a `needs` hands its code: a required secret is a string, an optional one may be absent. */
+/** @public */
+export type SecretValues<S extends readonly SecretSpec[]> = {
+    [K in S[number] as IsOptional<K> extends true ? never : NameOf<K>]: string;
+} & {
+    [K in S[number] as IsOptional<K> extends true ? NameOf<K> : never]?: string;
+};
+/** Code that needs secrets, built once their values are known: the declaration cannot drift from the read. */
+export interface Needs<T> {
+    readonly kind: "fastagent.needs";
+    readonly secrets: readonly {
+        name: string;
+        description?: string;
+        optional: boolean;
+    }[];
+    build(values: Record<string, string | undefined>): T;
+}
+/** @public */
+export declare function needs<const S extends readonly SecretSpec[], T>(secrets: S, build: (values: SecretValues<S>) => T): Needs<T>;
+export declare function isNeeds(value: unknown): value is Needs<unknown>;
+/** What `src/schedules/<name>.ts` default-exports. */
+export interface DefinedSchedule extends ScheduleConfig {
+    readonly kind: "fastagent.schedule";
+}
+/** @public */
+export declare function defineSchedule(config: ScheduleConfig): DefinedSchedule;
+export {};

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

@@ -0,0 +1,28 @@
+import { isEnvName } from "../../declared-secrets.js";
+/** @public */
+export function defineAgent(config) {
+    return config;
+}
+/** @public */
+export function needs(secrets, build) {
+    const declared = secrets.map((spec) => typeof spec === "string"
+        ? { name: spec, optional: false }
+        : {
+            name: spec.name,
+            optional: spec.optional === true,
+            ...(spec.description === undefined ? {} : { description: spec.description }),
+        });
+    for (const { name } of declared) {
+        // Written verbatim into env files and deploy artifacts, where a malformed name breaks somewhere far away.
+        if (!isEnvName(name))
+            throw new Error(`needs: ${JSON.stringify(name)} is not an environment variable name`);
+    }
+    return { kind: "fastagent.needs", secrets: declared, build: (values) => build(values) };
+}
+export function isNeeds(value) {
+    return value?.kind === "fastagent.needs";
+}
+/** @public */
+export function defineSchedule(config) {
+    return { kind: "fastagent.schedule", ...config };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * pi-durable's entries as the Agent API publishes them (SPEC.md §3): the conversation's messages, its tool results
+ * and its compactions. The harness's own entries (`pi.system`, resets, FastAgent's bookkeeping) are not published.
+ */
+import type { AssistantMessage, ImageContent, Usage as PiUsage } from "@earendil-works/pi-ai";
+import type { EntryRecord } from "@earendil-works/pi-durable";
+import type { Entry, Tokens } from "../../agent-api.ts";
+import type { Ids } from "./ids.ts";
+/** A message as it was taken: the model saw the record's content, a Caller sees what it sent (`sent`). */
+export declare const USER_ENTRY = "fastagent.user";
+/** A write that only places the queued inputs a run that did not answer left waiting (release.ts). */
+export declare const RELEASE_ENTRY = "fastagent.release";
+export type UserEntryData = {
+    requestId: string;
+    /** The first text part as sent, when a command expanded it for the model. */
+    sent?: string;
+};
+export declare function isPublished(record: EntryRecord): boolean;
+/** The request id a `fastagent.user` entry was submitted with: how the message it names is found. */
+export declare function requestIdOf(record: EntryRecord): string | undefined;
+/** `messageId`: the message a user entry names, when it names one. */
+export declare function publishEntry(record: EntryRecord, ids: Ids, messageId: number | undefined): Entry;
+export declare function replyText(message: Pick<AssistantMessage, "content">): string;
+/** The model's reasoning as a Caller may show it: a redacted block's placeholder is not reasoning. */
+export declare function thinkingOf(message: Pick<AssistantMessage, "content">): string | undefined;
+export declare function hasToolCalls(message: AssistantMessage): boolean;
+export declare function usageOf(usage: Pick<PiUsage, "input" | "output" | "cacheRead" | "cacheWrite" | "cost">): Tokens;
+export declare function parseImageRef(ref: string): {
+    entryId: string;
+    index: number;
+} | undefined;
+export declare function imageAt(record: EntryRecord, index: number): ImageContent | undefined;

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

@@ -0,0 +1,126 @@
+/** A message as it was taken: the model saw the record's content, a Caller sees what it sent (`sent`). */
+export const USER_ENTRY = "fastagent.user";
+/** A write that only places the queued inputs a run that did not answer left waiting (release.ts). */
+export const RELEASE_ENTRY = "fastagent.release";
+const PUBLISHED = new Set([USER_ENTRY, "pi.user", "pi.assistant", "pi.tool-result", "pi.compaction"]);
+export function isPublished(record) {
+    return PUBLISHED.has(record.kind) && record.model?.[0] !== undefined;
+}
+/** The request id a `fastagent.user` entry was submitted with: how the message it names is found. */
+export function requestIdOf(record) {
+    return record.kind === USER_ENTRY ? record.data.requestId : undefined;
+}
+/** `messageId`: the message a user entry names, when it names one. */
+export function publishEntry(record, ids, messageId) {
+    const model = record.model?.[0];
+    const ref = (index) => imageRef(ids.encode(record.id), index);
+    return {
+        id: ids.encode(record.id),
+        timestamp: model.timestamp,
+        ...published(record, model, ref, ids, messageId),
+    };
+}
+function published(record, model, ref, ids, messageId) {
+    switch (model.role) {
+        case "user": {
+            if (record.kind === "pi.compaction")
+                return { kind: "compaction", data: { summary: textOf(model.content) } };
+            const content = contentParts(model.content, ref);
+            const sent = record.kind === USER_ENTRY ? record.data.sent : undefined;
+            const first = content[0];
+            if (sent !== undefined && first?.type === "text")
+                content[0] = { type: "text", text: sent };
+            return {
+                kind: "user",
+                data: { content: content, ...(messageId === undefined ? {} : { messageId: ids.encode(messageId) }) },
+            };
+        }
+        case "assistant":
+            return { kind: "assistant", data: assistantData(model) };
+        case "toolResult":
+            return {
+                kind: "tool_result",
+                data: {
+                    toolCallId: model.toolCallId,
+                    toolName: model.toolName,
+                    isError: model.isError,
+                    content: contentParts(model.content, ref),
+                },
+            };
+        default:
+            throw new Error(`entry ${record.id} of kind ${record.kind} holds a ${model.role} message`);
+    }
+}
+function assistantData(message) {
+    const toolCalls = message.content.flatMap((block) => block.type === "toolCall" ? [{ id: block.id, name: block.name, args: block.arguments }] : []);
+    const thinking = thinkingOf(message);
+    const stop = STOPS[message.stopReason];
+    return {
+        text: replyText(message),
+        ...(thinking === undefined ? {} : { thinking }),
+        ...(toolCalls.length > 0 ? { toolCalls } : {}),
+        ...(stop === undefined ? {} : { stop }),
+        ...(stop === undefined || message.errorMessage === undefined ? {} : { error: message.errorMessage }),
+        usage: { ...usageOf(message.usage) },
+    };
+}
+/** How a reply stopped, when it did not stop as an answer or a tool call does. */
+const STOPS = {
+    length: "max_tokens",
+    error: "failed",
+    aborted: "aborted",
+};
+export function replyText(message) {
+    return message.content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("");
+}
+/** The model's reasoning as a Caller may show it: a redacted block's placeholder is not reasoning. */
+export function thinkingOf(message) {
+    const text = message.content
+        .flatMap((block) => (block.type === "thinking" && block.redacted !== true ? [block.thinking] : []))
+        .join("");
+    return text === "" ? undefined : text;
+}
+export function hasToolCalls(message) {
+    return message.content.some((block) => block.type === "toolCall");
+}
+export function usageOf(usage) {
+    return {
+        inputTokens: usage.input,
+        outputTokens: usage.output,
+        cacheReadTokens: usage.cacheRead,
+        cacheWriteTokens: usage.cacheWrite,
+        cost: usage.cost.total,
+    };
+}
+function textOf(content) {
+    return typeof content === "string"
+        ? content
+        : content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
+}
+function contentParts(content, ref) {
+    if (typeof content === "string")
+        return [{ type: "text", text: content }];
+    return content.map((part, index) => part.type === "text"
+        ? { type: "text", text: part.text }
+        : { type: "image", mimeType: part.mimeType, ref: ref(index) });
+}
+/** A ref names the entry and the part of its content that holds the image: images live inline in the entry. */
+function imageRef(entryId, index) {
+    return `${entryId}:${index}`;
+}
+export function parseImageRef(ref) {
+    const at = ref.lastIndexOf(":");
+    const index = ref.slice(at + 1);
+    if (at <= 0 || !/^(0|[1-9][0-9]{0,5})$/.test(index))
+        return undefined;
+    return { entryId: ref.slice(0, at), index: Number(index) };
+}
+export function imageAt(record, index) {
+    const model = record.model?.[0];
+    if (!isPublished(record) || (model?.role !== "user" && model?.role !== "toolResult"))
+        return undefined;
+    if (typeof model.content === "string")
+        return undefined;
+    const part = model.content[index];
+    return part?.type === "image" ? part : undefined;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * `sessions.events` (SPEC.md §6.1) over pi-durable's event stream of one conversation: the entries asked for, a
+ * `state` snapshot, then what each commit adds. pi-durable captures its snapshot and the registration for later
+ * commits atomically, so the replay ends at the snapshot's newest entry and the live part starts after it.
+ */
+import type { Context } from "@earendil-works/chord/context";
+import { type Harness } from "@earendil-works/pi-durable";
+import * as Stream from "effect/Stream";
+import { AgentError, type SessionEvent } from "../../agent-api.ts";
+import type { Ids } from "./ids.ts";
+import type { Reads } from "./reads.ts";
+export interface EventsOptions {
+    harness: Harness;
+    reads: Reads;
+    ids: Ids;
+    context: Context;
+    failureOf: (error: unknown) => AgentError;
+    /** The retry budget a `retrying` reports. */
+    maxRetries: number;
+}
+/**
+ * The session's events after the entry `after` names (`"start"`: every entry; absent: none). An unknown session or
+ * entry, and a storage that fails before the snapshot, fail the stream; a failure after it is a `stream_error`.
+ */
+export declare function sessionEvents({ harness, reads, ids, context, failureOf, maxRetries }: EventsOptions, sessionId: string, afterEntry: string | undefined): Stream.Stream<SessionEvent, AgentError>;

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

@@ -0,0 +1,238 @@
+import { watchEvents, } from "@earendil-works/pi-durable";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import { AgentError, agentError, errorData } from "../../agent-api.js";
+import { port, portError } from "../../effect-port.js";
+import { isPublished, replyText, thinkingOf } from "./entries.js";
+import { hasEnded, isInput, sessionOf } from "./messages.js";
+/**
+ * The session's events after the entry `after` names (`"start"`: every entry; absent: none). An unknown session or
+ * entry, and a storage that fails before the snapshot, fail the stream; a failure after it is a `stream_error`.
+ */
+export function sessionEvents({ harness, reads, ids, context, failureOf, maxRetries }, sessionId, afterEntry) {
+    return Stream.unwrap(Effect.gen(function* () {
+        const conversation = yield* reads.conversation(sessionId);
+        if (conversation === undefined)
+            return yield* agentError("not_found", `No session ${sessionId}`);
+        let after;
+        if (afterEntry === "start")
+            after = 0;
+        else if (afterEntry !== undefined) {
+            const entry = yield* reads.visibleEntry(conversation, afterEntry);
+            if (entry === undefined) {
+                return yield* agentError("not_found", `No entry ${afterEntry} in session ${sessionId}`);
+            }
+            after = entry.id;
+        }
+        const batches = yield* Effect.acquireRelease(Queue.bounded(1), Queue.shutdown);
+        const watch = yield* Effect.acquireRelease(port(() => watchEvents(harness, conversation.id, context)), (stream) => Effect.promise(() => stream.stop()));
+        // Taking one batch at a time keeps pi-durable's own bound on what a slow Caller leaves undelivered.
+        watch.start((events) => Effect.runPromiseExit(Queue.offer(batches, { events })).then(() => undefined));
+        void watch.closed.then((end) => Effect.runPromiseExit(Queue.offer(batches, { end })));
+        const { snapshot } = watch;
+        const newest = snapshot.entries.reduce((max, entry) => (max === undefined || entry.id > max ? entry.id : max), undefined);
+        const live = liveTranslator(reads, maxRetries, snapshot);
+        const replay = after === undefined || newest === undefined || after >= newest
+            ? Stream.empty
+            : replayed(reads, conversation, after, newest);
+        const present = Stream.succeed({
+            type: "state",
+            session: sessionOf(ids.encode(conversation.id), snapshot, snapshot.usage, snapshot.agent),
+        });
+        const events = Stream.fromQueue(batches).pipe(Stream.mapEffect((batch) => "end" in batch ? Effect.succeed([ended(batch.end)]) : live.translate(batch.events)), Stream.flattenIterable);
+        return Stream.concat(Stream.concat(replay, present), events).pipe(Stream.catchCause((cause) => Stream.succeed(streamError(failureOf(portError(cause))))), Stream.takeUntil((event) => event.type === "stream_error"));
+    }).pipe(Effect.catchCause((cause) => {
+        const error = portError(cause);
+        return Effect.fail(error instanceof AgentError ? error : failureOf(error));
+    })));
+}
+const streamError = (error) => ({ type: "stream_error", error: errorData(error) });
+function ended(end) {
+    switch (end.reason) {
+        case "session_failed":
+            return streamError(agentError("unavailable", `The agent's storage failed: ${String(end.error)}`));
+        case "listener_error":
+            return streamError(agentError("internal", `Following the session failed: ${end.error.message}`));
+        default:
+            return streamError(agentError("unavailable", `The agent stopped serving this session (${end.reason})`));
+    }
+}
+function replayed(reads, conversation, after, through) {
+    return reads
+        .publishedPages(conversation, {
+        order: "ascending",
+        minEntryId: (after + 1),
+        maxEntryId: through,
+    })
+        .pipe(Stream.mapEffect(reads.publish), Stream.flattenIterable, Stream.map(entryEvent));
+}
+const entryEvent = (entry) => ({ type: "entry", entry });
+/**
+ * What one commit's events add for a Caller: the reply's deltas, the tool calls that start and their status lines,
+ * retries, the published entries, and a `done` for each message that ended, before the next message's entry.
+ */
+function liveTranslator(reads, maxRetries, snapshot) {
+    let reply = [...(snapshot.generation?.message?.content ?? [])];
+    let shown = { text: replyText({ content: reply }), thinking: thinkingOf({ content: reply }) ?? "" };
+    const outputs = new Map(snapshot.tools.map((slot) => [slot.callId, slot.output ?? ""]));
+    const lines = new Map();
+    const outer = new Map(snapshot.nestedTools.map((slot) => [slot.callId, slot.parentCallId]));
+    const outermost = (callId) => {
+        const parent = outer.get(callId);
+        return parent === undefined ? callId : outermost(parent);
+    };
+    const restart = () => {
+        reply = [];
+        shown = { text: "", thinking: "" };
+    };
+    const deltas = () => {
+        const now = { text: replyText({ content: reply }), thinking: thinkingOf({ content: reply }) ?? "" };
+        const added = (channel) => now[channel].length > shown[channel].length && now[channel].startsWith(shown[channel])
+            ? [{ type: "delta", channel, text: now[channel].slice(shown[channel].length) }]
+            : [];
+        const events = [...added("thinking"), ...added("text")];
+        shown = now;
+        return events;
+    };
+    const apply = (changes) => {
+        for (const change of changes) {
+            switch (change.type) {
+                case "message":
+                    reply = [...change.message.content];
+                    break;
+                case "text_start":
+                case "thinking_start":
+                case "toolcall_start":
+                case "block":
+                    reply[change.contentIndex] = change.block;
+                    break;
+                case "text_delta": {
+                    const block = reply[change.contentIndex];
+                    if (block?.type === "text")
+                        reply[change.contentIndex] = { ...block, text: block.text + change.delta };
+                    break;
+                }
+                case "thinking_delta": {
+                    const block = reply[change.contentIndex];
+                    if (block?.type === "thinking") {
+                        reply[change.contentIndex] = { ...block, thinking: block.thinking + change.delta };
+                    }
+                    break;
+                }
+                case "toolcall_delta":
+                    break;
+            }
+        }
+    };
+    const progress = (toolCallId, text) => {
+        if (text === undefined || lines.get(toolCallId) === text)
+            return [];
+        lines.set(toolCallId, text);
+        return [{ type: "tool_progress", toolCallId, text }];
+    };
+    return {
+        translate: (events) => Effect.gen(function* () {
+            const before = [];
+            const entries = [];
+            const settled = [];
+            for (const [index, event] of events.entries()) {
+                switch (event.type) {
+                    case "snapshot":
+                        return [
+                            streamError(agentError("unavailable", "This stream fell behind the session; continue after its last entry")),
+                        ];
+                    case "message_start":
+                        // An entry's own start comes right before its end; any other is a new reply being written.
+                        if (events[index + 1]?.type !== "message_end" && event.message.role === "assistant") {
+                            reply = [...event.message.content];
+                            shown = { text: "", thinking: "" };
+                            before.push(...deltas());
+                        }
+                        break;
+                    case "message_update":
+                        apply(event.changes);
+                        before.push(...deltas());
+                        break;
+                    case "message_end":
+                    case "entry_appended":
+                        entries.push(event.entry);
+                        if (event.entry.model?.[0]?.role === "assistant")
+                            restart();
+                        break;
+                    case "tool_execution_start":
+                        if (event.parentToolCallId === undefined) {
+                            before.push({
+                                type: "tool_started",
+                                toolCallId: event.toolCallId,
+                                name: event.toolName,
+                                args: event.args,
+                            });
+                        }
+                        else {
+                            outer.set(event.toolCallId, event.parentToolCallId);
+                            before.push(...progress(outermost(event.toolCallId), callLine(event.toolName, event.args)));
+                        }
+                        break;
+                    case "tool_execution_update": {
+                        if (event.parentToolCallId !== undefined || event.output === undefined)
+                            break;
+                        const output = event.output;
+                        const current = outputs.get(event.toolCallId) ?? "";
+                        const next = "set" in output ? output.set : current.slice(output.trimStart ?? 0) + (output.append ?? "");
+                        outputs.set(event.toolCallId, next);
+                        before.push(...progress(event.toolCallId, lastLine(next)));
+                        break;
+                    }
+                    case "auto_retry_start":
+                        restart();
+                        before.push({
+                            type: "retrying",
+                            attempt: event.attempt,
+                            maxAttempts: maxRetries,
+                            delayMs: Math.max(0, event.at - Date.now()),
+                            reason: event.errorMessage,
+                        });
+                        break;
+                    case "tool_execution_end":
+                        outputs.delete(event.toolCallId);
+                        lines.delete(event.toolCallId);
+                        outer.delete(event.toolCallId);
+                        break;
+                    case "submission":
+                        if (isInput(event.record) && hasEnded(event.record))
+                            settled.push(event.record);
+                        break;
+                }
+            }
+            const published = yield* reads.publish(entries.filter(isPublished));
+            const dones = yield* Effect.forEach(settled, (record) => reads.message(record, entries));
+            // pi-durable places the next queued message in the commit that ends a run: its message's `done` goes first.
+            const next = published.findIndex((entry) => entry.kind === "user");
+            const at = next === -1 ? published.length : next;
+            return [
+                ...before,
+                ...published.slice(0, at).map(entryEvent),
+                ...dones.map((message) => ({ type: "done", message })),
+                ...published.slice(at).map(entryEvent),
+            ];
+        }),
+    };
+}
+/** The last line with text, a running tool's status. pi-durable's output already has no control characters. */
+function lastLine(text) {
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim();
+        if (line)
+            return line;
+    }
+    return undefined;
+}
+/** A nested call as its caller's status: the tool and its first plain argument, on one line (`weather London`). */
+function callLine(name, args) {
+    const first = args !== null && typeof args === "object" && !Array.isArray(args)
+        ? Object.values(args).find((value) => typeof value === "string" || typeof value === "number")
+        : undefined;
+    return first === undefined ? name : `${name} ${String(first).replace(/\s+/g, " ").trim()}`.trim();
+}

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

@@ -0,0 +1,16 @@
+import type { Context } from "@earendil-works/chord/context";
+import { type Harness, type ToolExecutionApi } from "@earendil-works/pi-durable";
+export interface Ids {
+    encode(id: number): string;
+    /** The pi-durable id `text` names in this storage, or undefined for any other text. */
+    decode(text: string): number | undefined;
+    /** A position among this storage's ids as a cursor, which no id reads as. */
+    encodeCursor(position: number): string;
+    decodeCursor(text: string): number | undefined;
+}
+export declare function storageIds(harness: Harness, context: Context): Promise<Ids>;
+/**
+ * The session id of the conversation a tool runs in, as the Agent hands it out, or undefined when that conversation is
+ * not a session (a subagent's): from the storage the tool runs on.
+ */
+export declare function sessionIdOf(api: Pick<ToolExecutionApi, "conversationId" | "snapshot" | "commit">, context: Context): Promise<string | undefined>;

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

@@ -0,0 +1,55 @@
+/**
+ * The ids the Agent hands out: the storage's incarnation, then pi-durable's id. pi-durable counts ids per storage and a
+ * new storage counts from the start again, so an id kept from a storage that is gone must not name what the new one
+ * gives the same number (architecture.md §2). An encoding, not a lookup: nothing is stored per id.
+ */
+import { randomBytes } from "node:crypto";
+import { defineDoc } from "@earendil-works/pi-durable";
+import { isSession } from "./sessions.js";
+const StorageDoc = defineDoc({
+    kind: "fastagent.storage",
+    version: 1,
+    scope: "session",
+    initial: () => ({ incarnation: "" }),
+});
+export async function storageIds(harness, context) {
+    const incarnation = await harness.commit(async (tx) => {
+        const doc = await tx.doc(StorageDoc);
+        if (doc.incarnation === "")
+            doc.incarnation = randomBytes(8).toString("base64url");
+        return doc.incarnation;
+    }, context);
+    return idsOf(incarnation);
+}
+/**
+ * The session id of the conversation a tool runs in, as the Agent hands it out, or undefined when that conversation is
+ * not a session (a subagent's): from the storage the tool runs on.
+ */
+export async function sessionIdOf(api, context) {
+    const record = await api.commit((tx) => tx.conversation(api.conversationId), context);
+    if (record === undefined || !isSession(record))
+        return undefined;
+    const incarnation = (await api.snapshot(StorageDoc, context))?.incarnation;
+    if (!incarnation)
+        throw new Error("this storage has no incarnation: the Agent did not open it");
+    return idsOf(incarnation).encode(api.conversationId);
+}
+function idsOf(incarnation) {
+    const prefix = `${incarnation}.`;
+    const cursorPrefix = `${incarnation}~`;
+    return {
+        encode: (id) => `${prefix}${id}`,
+        decode: (text) => numberAfter(prefix, text),
+        encodeCursor: (position) => `${cursorPrefix}${position}`,
+        decodeCursor: (text) => numberAfter(cursorPrefix, text),
+    };
+}
+function numberAfter(prefix, text) {
+    if (!text.startsWith(prefix))
+        return undefined;
+    const digits = text.slice(prefix.length);
+    if (!/^[1-9][0-9]{0,15}$/.test(digits))
+        return undefined;
+    const id = Number(digits);
+    return Number.isSafeInteger(id) ? id : undefined;
+}

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

@@ -0,0 +1,41 @@
+import type { AgentState, EntryRecord, SubmissionRecord } from "@earendil-works/pi-durable";
+import { type Message, type Session, type Usage } from "../../agent-api.ts";
+import { usageOf } from "./entries.ts";
+import type { Ids } from "./ids.ts";
+export type InputRecord = Extract<SubmissionRecord, {
+    type: "input";
+}>;
+export type EndedRecord = Extract<InputRecord, {
+    status: "done" | "unanswered";
+}>;
+/** Every message is submitted with a request id, so its entry can name it: the Caller's key, or one of our own. */
+export declare function requestIdFor(idempotencyKey: string | undefined): string;
+export declare function isInput(record: SubmissionRecord | undefined): record is InputRecord;
+export declare function hasEnded(record: InputRecord): record is EndedRecord;
+/** What a conversation's `pi.inbox`, `pi.usage` and `pi.live` say, as the documents and an event snapshot hold them. */
+export interface InboxView {
+    readonly items: readonly {
+        readonly id: number;
+        readonly mode: string;
+    }[];
+}
+export interface UsageView {
+    readonly models: Readonly<Record<string, Parameters<typeof usageOf>[0]>>;
+    readonly tools: Readonly<Record<string, Parameters<typeof usageOf>[0]>>;
+}
+export interface LiveView {
+    readonly run?: {
+        readonly inputs: readonly number[];
+    };
+    readonly generation?: {
+        readonly message?: unknown;
+    };
+}
+/** The queued inputs in the order they will be taken: steers before follow-ups, each in arrival order. */
+export declare function queuedInputs(inbox: InboxView | undefined): number[];
+/** A message as the API has it. An ended one needs its answer entry: the entry pi-durable settled it with. */
+export declare function messageOf(record: InputRecord, ids: Ids, answer?: EntryRecord): Message;
+/** The session as it is now, from its documents as one commit or one event snapshot holds them. */
+export declare function sessionOf(id: string, live: LiveView | undefined, usage: UsageView | undefined, agent: Pick<AgentState, "model" | "thinkingLevel" | "instructions" | "tools"> | undefined): Session;
+/** What a conversation's `pi.usage`, or the instance's total, says it spent. */
+export declare function usageOfState(usage: UsageView | undefined): Usage;