@particle-academy/prism-harness 0.0.0

package/dist/task-tools.js

@@ -0,0 +1,136 @@
+import { HarnessError } from './errors.js';
+import { authorizedTool } from './tools.js';
+import { isTerminalState } from './tasks.js';
+/**
+ * A tool that lets the AGENT close its own task. OFF UNLESS A CONSUMER BUILDS IT.
+ *
+ * ## Why this is not the default
+ *
+ * If the model can set its own task to `done`, then "run until the goal is met"
+ * silently becomes "run until it decides it is met", and a run that has stalled
+ * ends by declaring victory. That is the same failure `prism-human-plus`
+ * addresses by reserving confirmation for the human, and the same reason the
+ * default here is off in all three languages. A port that ships it on has
+ * changed an observable decision, not a default.
+ *
+ * By default `release()` is called by the APPLICATION, from evidence. Nothing
+ * in this package registers this tool, and a `StoreTaskSource` on its own gives
+ * an agent no route to a terminal state.
+ *
+ * ## Why the authorizer is checked
+ *
+ * Through the EXISTING `ToolAuthorizer` -- no new permission mechanism, because
+ * a second mechanism is a second place to grant something by accident.
+ *
+ * A disabled authorizer is refused rather than tolerated. `ToolAuthorizer`
+ * defaults to off, and off means every registered tool is offered to every run
+ * and every call is allowed; a consumer who wires this tool up against one has
+ * granted the agent completion authority while believing a control is in place.
+ * Same argument, and the same error code, as a policy that is defined and never
+ * consulted.
+ *
+ * The returned factory produces a tool wrapped by `authorizedTool`, so the call
+ * policy is asked again AT CALL TIME with the arguments -- an offer-time check
+ * alone can say "may complete tasks" and never "only this task, only once the
+ * tests pass".
+ */
+export function agentCompletionTool(options) {
+    const name = options.name ?? 'complete_task';
+    if (!options.authorizer.enabled) {
+        throw HarnessError.completionToolWithoutAuthorizer(name);
+    }
+    const { source, task, worker, authorizer } = options;
+    const tool = {
+        name,
+        description: `Record the outcome of the task [${task.id()}] as either "done" or "failed". Only call this ` +
+            'when the work is actually finished; "failed" is a legitimate answer and is not a worse one.',
+        async handle(args) {
+            const given = args.outcome;
+            // REQUIRED and VALIDATED. `outcome` is the one value the MODEL supplies
+            // and it decides a terminal state, so mapping anything else onto `done`
+            // -- `"complete"`, `"DONE"`, `null`, or nothing at all -- would let a
+            // malformed call produce the more privileged result: an agent declaring
+            // victory by typo.
+            //
+            // ABSENT is refused too, and that is a ruling rather than an obvious
+            // reading. The argument for allowing it is real: calling a tool named
+            // `complete_task` looks like the declaration by itself. The reference
+            // settled it the other way, and the same code covers both, so a model
+            // that omitted the argument is told to say which outcome it means rather
+            // than having one chosen for it.
+            if (given !== 'done' && given !== 'failed') {
+                throw HarnessError.taskOutcomeInvalid(name, given);
+            }
+            const outcome = given;
+            // CHECKED HERE TOO, and this is not belt-and-braces.
+            //
+            // `StoreTaskSource.release()` refuses a worker that is not the holder, so
+            // against that source this block changes nothing -- deleting it is
+            // invisible, and the mutation SURVIVES. That is precisely the argument
+            // for it: an interface cannot make an implementation check anything, and
+            // `release(task, worker, outcome)` reads to a third party like "find it
+            // and set the state", which is what they will write. This tool is the
+            // thing a MODEL can call, so it does not get to assume the source behind
+            // it is the careful one. A fixture source with no guard at all is in the
+            // suite for exactly this, because nothing else would notice.
+            const current = await source.find(task.id());
+            if (current === null) {
+                throw HarnessError.taskNotFound(task.id());
+            }
+            if (isTerminalState(current.state())) {
+                throw HarnessError.taskAlreadyTerminal(task.id(), current.state());
+            }
+            if (current.state() !== 'claimed') {
+                throw HarnessError.taskLeaseNotHeld(task.id(), worker, 'nothing is holding it');
+            }
+            // ONE comparison, and it must be `!==` against the worker rather than a
+            // hunt for a mismatch. The three ways this is not the worker's task --
+            // somebody else holds it, nobody holds it, or the holder CANNOT BE
+            // ESTABLISHED -- all have to land on refusal, and the third is the one
+            // that is easy to get wrong.
+            //
+            // `AgentTask` is `id`, `instruction`, `state` and nothing else, so a
+            // conforming source may legally return a task from which no holder can be
+            // read. The first version here treated that as "no mismatch, therefore
+            // allowed", which is READING SILENCE AS PERMISSION -- the same mistake as
+            // inferring `done` from an absent outcome, asked about a different field
+            // and one level down. An unknowable holder resolves to a sentinel that
+            // matches no worker, so it refuses.
+            if (holderOf(current) !== worker) {
+                throw HarnessError.taskLeaseNotHeld(task.id(), worker, 'it is not held by this worker');
+            }
+            await source.release(task, worker, outcome);
+            return { id: task.id(), state: outcome };
+        },
+    };
+    return (session) => authorizedTool(tool, session, authorizer);
+}
+/**
+ * A holder that MATCHES NO WORKER, for a task whose holder cannot be read.
+ *
+ * A symbol rather than a string, so no worker id can ever equal it -- not the
+ * empty string, not `'unknown'`, not whatever a consumer happens to name a
+ * worker. "Impossible to collide with" is the entire job.
+ */
+const UNKNOWABLE_HOLDER = Symbol('the holder could not be established');
+/**
+ * Who holds this task -- or the sentinel, when that cannot be established.
+ *
+ * `AgentTaskSource.find()` returns an `AgentTask`: three methods, no lease.
+ * That is deliberate, because a consumer adapting an existing table may have
+ * nowhere to put an owner, and it means a perfectly conforming source can hand
+ * back a task from which no holder is readable. `LeasedAgentTask` adds the
+ * lease, and everything this package produces is one.
+ *
+ * The unreadable case resolves to a sentinel rather than to `undefined`,
+ * because `undefined` invites the caller to skip the comparison -- which is
+ * what the first version of this did, and skipping the comparison is granting
+ * the permission.
+ */
+function holderOf(task) {
+    const candidate = task;
+    if (typeof candidate.claimedBy !== 'function') {
+        return UNKNOWABLE_HOLDER;
+    }
+    return candidate.claimedBy();
+}

package/dist/tasks.d.ts

@@ -0,0 +1,257 @@
+import type { JsonObject } from './json.js';
+/**
+ * What remains to be done, and how far along it is.
+ *
+ * FOUR STATES, and no others. This is identity, not spelling: a port that adds
+ * a fifth (`cancelled`, `retrying`, `skipped`) has changed what a stored record
+ * can say, and a consumer reading a list written by another language would meet
+ * a value it cannot map.
+ *
+ * The transitions are equally pinned:
+ *
+ * ```text
+ *         claim()                    release(done)
+ *   todo ---------> claimed -------------------------> done
+ *    ^                 |            release(failed)
+ *    |                 +-------------------------------> failed
+ *    |                 |
+ *    +-----------------+
+ *       lease expires
+ * ```
+ *
+ * Note what is NOT there. An expired lease goes back to `todo`, never to
+ * `failed` -- a worker dying is not the task failing, and conflating the two
+ * burns a retry that never ran. And nothing leaves `done` or `failed`: a
+ * `failed` task is re-queued by the APPLICATION, because automatic retry needs
+ * backoff and attempt counts, and that is the scheduler this must not become.
+ */
+export type TaskState = 'todo' | 'claimed' | 'done' | 'failed';
+/** Every state, in the order the machine visits them. */
+export declare const TASK_STATES: readonly TaskState[];
+/**
+ * What `release()` records. Both are TERMINAL.
+ *
+ * Deliberately not a boolean. "Did it work" reads the same for a task that
+ * failed and a task that was never attempted, and those two are what this
+ * design exists to keep apart.
+ */
+export type TaskOutcome = Extract<TaskState, 'done' | 'failed'>;
+/**
+ * How long a claim holds by default: FIVE MINUTES.
+ *
+ * Long enough for a model call plus tool work, short enough that a crashed
+ * worker does not wedge the list for an hour. The number matters less than it
+ * being the same number in all three languages, which is why it is a named
+ * constant rather than a literal at the call site.
+ */
+export declare const DEFAULT_LEASE_SECONDS = 300;
+/**
+ * One unit of work.
+ *
+ * METHODS, not properties, and that is not decoration. An adapter over a
+ * consumer's own record has to read through to the live row -- a value
+ * snapshotted at construction would still report `claimed` after another
+ * worker's lease expired underneath it.
+ */
+export interface AgentTask {
+    /** Stable and unique WITHIN ITS SOURCE. Not globally unique. */
+    id(): string;
+    /** What the model is asked to do. */
+    instruction(): string;
+    state(): TaskState;
+}
+/**
+ * Where tasks come from.
+ *
+ * Four methods, and the first is the reason the interface exists.
+ *
+ * `claim()` is ONE call. "Read the next task" followed by "mark it mine" is two
+ * round trips with a window between them, and two workers arriving in that
+ * window both get the same task. An implementation must take the next available
+ * task and record the claim as a single atomic operation -- not for
+ * convenience, but because a source that cannot is not an implementation of
+ * this contract.
+ */
+export interface AgentTaskSource {
+    /**
+     * Atomically take the next available task, or null when there is none.
+     *
+     * Tasks come back in INSERTION ORDER unless the source defines otherwise. A
+     * source may expose an explicit position; it must not reorder implicitly.
+     * Nothing errors when ordering changes -- the agent simply does the work in a
+     * different sequence and produces a different result, which is the hardest
+     * kind of divergence to notice.
+     */
+    claim(worker: string, leaseSeconds?: number): Promise<AgentTask | null>;
+    /**
+     * Record what happened, as the worker that is HOLDING the task.
+     *
+     * Called by the APPLICATION, from evidence -- not by the agent. See
+     * `agentCompletionTool` for the opt-in that changes that, and why it is off
+     * until a consumer turns it on.
+     *
+     * The `worker` argument is not in the spec's three-method sketch and is here
+     * on purpose. Without it, a completion tool handed a source can close ANY
+     * task in the list, including one another worker is midway through -- and the
+     * whole reason completion authority is gated is that an agent closing work it
+     * did not do is the failure being designed against. A release by anyone but
+     * the holder is refused.
+     */
+    release(task: AgentTask, worker: string, outcome: TaskOutcome): Promise<void>;
+    /**
+     * How many tasks remain claimable.
+     *
+     * A COUNT, not a listing. It exists to terminate the loop and a count is
+     * enough for that; a listing invites the source to materialise every task on
+     * every pass, and a consumer that wants one already has its own query.
+     */
+    pending(): Promise<number>;
+    /**
+     * The task with this id, as it stands now, or null.
+     *
+     * On the contract because `release()` takes a TASK and every external caller
+     * holds only an ID. A tool call carries `{"id": "t-1"}`; an HTTP route has
+     * `/tasks/t-1`; a worker resuming after a restart has whatever it wrote down.
+     * Without this the contract could be driven only by code that still had the
+     * object `claim()` returned, which is the one caller that does not need it.
+     *
+     * A FRESH read, with any expired lease already applied -- so a task whose
+     * lease ran out reports `todo` here even if the store has not been rewritten
+     * yet.
+     */
+    find(id: string): Promise<AgentTask | null>;
+}
+/**
+ * The stored shape of a task. THE KEYS ARE THE CONTRACT.
+ *
+ * `claimed_by` and `claimed_until` are `| null` and NOT optional, and that
+ * distinction is why this type is spelled out rather than inferred. TypeScript
+ * has both `null` and `undefined` where PHP has one absent value; an optional
+ * property holding `undefined` is DROPPED by `JSON.stringify`; and a dropped
+ * key is different bytes -- an observable decision under prism-parity decision
+ * 0002, not a formatting detail.
+ *
+ * `claimed_until` is an integer Unix timestamp rather than a formatted date,
+ * because date formatting is exactly where three languages produce three
+ * strings from one instant.
+ */
+export interface AgentTaskRecord {
+    claimed_by: string | null;
+    claimed_until: number | null;
+    id: string;
+    instruction: string;
+    state: TaskState;
+}
+/**
+ * A task that also exposes its lease.
+ *
+ * Kept apart from `AgentTask` because the three-method contract is what an
+ * adapter over an existing table must satisfy, and such a table may have
+ * nowhere to put an owner and an expiry. Everything this package produces
+ * satisfies both.
+ */
+export interface LeasedAgentTask extends AgentTask {
+    /** Present-and-null when unclaimed. */
+    claimedBy(): string | null;
+    /** Integer Unix timestamp; present-and-null when unclaimed. */
+    claimedUntil(): number | null;
+    toRecord(): AgentTaskRecord;
+}
+/**
+ * The five attributes a consumer's own record has to expose.
+ *
+ * Camel-cased because this is the in-language shape; `AgentTaskRecord` is the
+ * stored one, and the two are converted rather than conflated. Only the stored
+ * one is pinned across languages.
+ */
+export interface AgentTaskAttributes {
+    id: string;
+    instruction: string;
+    state: TaskState;
+    /** PRESENT-AND-NULL when unclaimed. Never `undefined`; see `AgentTaskRecord`. */
+    claimedBy: string | null;
+    claimedUntil: number | null;
+}
+export declare function isTaskState(value: unknown): value is TaskState;
+/** `done` and `failed`. Nothing leaves either. */
+export declare function isTerminalState(state: TaskState): boolean;
+/**
+ * Canonical JSON for one task record.
+ *
+ * ```json
+ * {"claimed_by":null,"claimed_until":null,"id":"t-1","instruction":"...","state":"todo"}
+ * ```
+ *
+ * Keys SORTED -- which for these five is also the order above, so one task has
+ * one byte sequence rather than two.
+ *
+ * `undefined` is coerced to `null` instead of being handed to `JSON.stringify`,
+ * which would silently drop the key. That coercion is a backstop for values
+ * arriving from a store or an untyped consumer; the types above already make it
+ * unreachable from typed code, and a test asserts both halves rather than
+ * trusting the type.
+ *
+ * No whitespace, no escaped slashes, no escaped non-ASCII: JavaScript's
+ * `JSON.stringify` already produces all three where PHP's and Python's defaults
+ * do not. See prism-parity decision 0005.
+ */
+export declare function canonicalTaskJson(record: AgentTaskRecord): string;
+/**
+ * Rebuild a record from whatever a store handed back.
+ *
+ * A missing or `undefined` claim field becomes `null`, so there is exactly one
+ * representation of "unclaimed" once a row has been through here. A missing id,
+ * instruction or state is a CORRUPT row rather than a defaultable one, and is
+ * refused -- defaulting a missing state to `todo` would hand a half-finished
+ * task back out as if it had never been attempted.
+ */
+export declare function taskRecordFrom(value: JsonObject | Record<string, unknown>): AgentTaskRecord;
+export declare function recordToAttributes(record: AgentTaskRecord): AgentTaskAttributes;
+/**
+ * The stored record for a set of attributes.
+ *
+ * `?? null` on both claim fields is the load-bearing line in this file. An
+ * untyped consumer handing over `undefined` would otherwise produce a record
+ * whose keys vanish at serialisation time.
+ */
+export declare function attributesToRecord(attributes: AgentTaskAttributes): AgentTaskRecord;
+/**
+ * A consumer's own record, as an `AgentTask`.
+ *
+ * This is the idiomatic equivalent of the reference's trait on an Eloquent
+ * model, and the reason it looks nothing like a trait is decision 0002. PHP
+ * needs a trait because a trait is how PHP shares behaviour into someone else's
+ * class. TypeScript's conformance is STRUCTURAL: a consumer whose record
+ * already carries the five attributes needs no inheritance at all, so the
+ * natural spelling is a function that wraps one. Contorting the language to
+ * imitate a trait would change the spelling and nothing observable.
+ *
+ * The attributes object is read at CALL TIME rather than copied, so a live
+ * record another worker's claim changed underneath reports the new state.
+ */
+export declare function asAgentTask(attributes: AgentTaskAttributes): LeasedAgentTask;
+/**
+ * What the mixin needs from the class it is mixed into.
+ *
+ * ONE accessor rather than five fields, because a mixin cannot define a method
+ * called `id()` on a class that already has an `id` property -- the instance
+ * property shadows the prototype method and the method is never reached. That
+ * is a real constraint of the language, not a preference, and it is the reason
+ * the mixin asks for a mapping function instead of the attributes directly. A
+ * consumer maps their own column names here, exactly as a PHP trait would need
+ * them mapped.
+ */
+export interface AgentTaskAttributeSource {
+    taskAttributes(): AgentTaskAttributes;
+}
+type Constructor<T> = new (...args: any[]) => T;
+/**
+ * The mixin: `class Todo extends withAgentTask(Row) {}`.
+ *
+ * Same behaviour as `asAgentTask`, reached the way a consumer who wants the
+ * methods ON their model reaches it. Both exist because TypeScript has two
+ * natural spellings of "share this behaviour into someone else's class" and
+ * neither is more correct than the other.
+ */
+export declare function withAgentTask<TBase extends Constructor<AgentTaskAttributeSource>>(Base: TBase): TBase & Constructor<LeasedAgentTask>;
+export {};

package/dist/tasks.js

@@ -0,0 +1,162 @@
+import { HarnessError } from './errors.js';
+/** Every state, in the order the machine visits them. */
+export const TASK_STATES = ['todo', 'claimed', 'done', 'failed'];
+/**
+ * How long a claim holds by default: FIVE MINUTES.
+ *
+ * Long enough for a model call plus tool work, short enough that a crashed
+ * worker does not wedge the list for an hour. The number matters less than it
+ * being the same number in all three languages, which is why it is a named
+ * constant rather than a literal at the call site.
+ */
+export const DEFAULT_LEASE_SECONDS = 300;
+export function isTaskState(value) {
+    return typeof value === 'string' && TASK_STATES.includes(value);
+}
+/** `done` and `failed`. Nothing leaves either. */
+export function isTerminalState(state) {
+    return state === 'done' || state === 'failed';
+}
+/**
+ * Canonical JSON for one task record.
+ *
+ * ```json
+ * {"claimed_by":null,"claimed_until":null,"id":"t-1","instruction":"...","state":"todo"}
+ * ```
+ *
+ * Keys SORTED -- which for these five is also the order above, so one task has
+ * one byte sequence rather than two.
+ *
+ * `undefined` is coerced to `null` instead of being handed to `JSON.stringify`,
+ * which would silently drop the key. That coercion is a backstop for values
+ * arriving from a store or an untyped consumer; the types above already make it
+ * unreachable from typed code, and a test asserts both halves rather than
+ * trusting the type.
+ *
+ * No whitespace, no escaped slashes, no escaped non-ASCII: JavaScript's
+ * `JSON.stringify` already produces all three where PHP's and Python's defaults
+ * do not. See prism-parity decision 0005.
+ */
+export function canonicalTaskJson(record) {
+    const loose = record;
+    const ordered = {};
+    for (const key of Object.keys(loose).sort()) {
+        const value = loose[key];
+        ordered[key] = value === undefined ? null : value;
+    }
+    return JSON.stringify(ordered);
+}
+/**
+ * Rebuild a record from whatever a store handed back.
+ *
+ * A missing or `undefined` claim field becomes `null`, so there is exactly one
+ * representation of "unclaimed" once a row has been through here. A missing id,
+ * instruction or state is a CORRUPT row rather than a defaultable one, and is
+ * refused -- defaulting a missing state to `todo` would hand a half-finished
+ * task back out as if it had never been attempted.
+ */
+export function taskRecordFrom(value) {
+    const loose = value;
+    const id = loose.id;
+    const instruction = loose.instruction;
+    const state = loose.state;
+    if (typeof id !== 'string' || id === '') {
+        throw HarnessError.unmappableContent('a stored task record has no id');
+    }
+    if (typeof instruction !== 'string') {
+        throw HarnessError.unmappableContent(`the stored task [${id}] has no instruction`);
+    }
+    if (!isTaskState(state)) {
+        throw HarnessError.unmappableContent(`the stored task [${id}] has the state [${String(state)}], which is not one of ${TASK_STATES.join(', ')}`);
+    }
+    const claimedBy = loose.claimed_by;
+    const claimedUntil = loose.claimed_until;
+    return {
+        claimed_by: typeof claimedBy === 'string' ? claimedBy : null,
+        claimed_until: typeof claimedUntil === 'number' ? Math.trunc(claimedUntil) : null,
+        id,
+        instruction,
+        state,
+    };
+}
+export function recordToAttributes(record) {
+    return {
+        id: record.id,
+        instruction: record.instruction,
+        state: record.state,
+        claimedBy: record.claimed_by,
+        claimedUntil: record.claimed_until,
+    };
+}
+/**
+ * The stored record for a set of attributes.
+ *
+ * `?? null` on both claim fields is the load-bearing line in this file. An
+ * untyped consumer handing over `undefined` would otherwise produce a record
+ * whose keys vanish at serialisation time.
+ */
+export function attributesToRecord(attributes) {
+    const until = attributes.claimedUntil;
+    return {
+        claimed_by: attributes.claimedBy ?? null,
+        claimed_until: until === null || until === undefined ? null : Math.trunc(until),
+        id: attributes.id,
+        instruction: attributes.instruction,
+        state: attributes.state,
+    };
+}
+/**
+ * A consumer's own record, as an `AgentTask`.
+ *
+ * This is the idiomatic equivalent of the reference's trait on an Eloquent
+ * model, and the reason it looks nothing like a trait is decision 0002. PHP
+ * needs a trait because a trait is how PHP shares behaviour into someone else's
+ * class. TypeScript's conformance is STRUCTURAL: a consumer whose record
+ * already carries the five attributes needs no inheritance at all, so the
+ * natural spelling is a function that wraps one. Contorting the language to
+ * imitate a trait would change the spelling and nothing observable.
+ *
+ * The attributes object is read at CALL TIME rather than copied, so a live
+ * record another worker's claim changed underneath reports the new state.
+ */
+export function asAgentTask(attributes) {
+    return {
+        id: () => attributes.id,
+        instruction: () => attributes.instruction,
+        state: () => attributes.state,
+        claimedBy: () => attributes.claimedBy ?? null,
+        claimedUntil: () => attributes.claimedUntil ?? null,
+        toRecord: () => attributesToRecord(attributes),
+    };
+}
+/**
+ * The mixin: `class Todo extends withAgentTask(Row) {}`.
+ *
+ * Same behaviour as `asAgentTask`, reached the way a consumer who wants the
+ * methods ON their model reaches it. Both exist because TypeScript has two
+ * natural spellings of "share this behaviour into someone else's class" and
+ * neither is more correct than the other.
+ */
+export function withAgentTask(Base) {
+    class AgentTaskRow extends Base {
+        id() {
+            return this.taskAttributes().id;
+        }
+        instruction() {
+            return this.taskAttributes().instruction;
+        }
+        state() {
+            return this.taskAttributes().state;
+        }
+        claimedBy() {
+            return this.taskAttributes().claimedBy ?? null;
+        }
+        claimedUntil() {
+            return this.taskAttributes().claimedUntil ?? null;
+        }
+        toRecord() {
+            return attributesToRecord(this.taskAttributes());
+        }
+    }
+    return AgentTaskRow;
+}

package/dist/thread.d.ts

@@ -0,0 +1,49 @@
+import type { JsonObject } from './json.js';
+import type { SessionStore } from './stores/session-store.js';
+export interface ThreadMessage {
+    /** Position in the conversation, from 1. Assigned by the thread, never by the caller. */
+    position: number;
+    /** The serialized message — whatever `prism-ts`'s `messageFromObject` can rebuild. */
+    message: JsonObject;
+    /** The run that produced it, when there was one. */
+    runId: string | null;
+    recordedAt: string;
+}
+/**
+ * The stored conversation a session is bound to.
+ *
+ * DURABLE by construction: it lives in the durable slot, so it is the one thing
+ * here a flushed cache cannot take away. The PHP reference keeps it as Eloquent
+ * rows for the same reason.
+ *
+ * ## Position is assigned inside a lock
+ *
+ * `record()` takes the lock before reading the current length. Two turns
+ * landing concurrently would otherwise both read position 4 and both write
+ * position 5, and the conversation would silently lose a message — the same
+ * race the reference tracks as prism-harness#2. Doing the read and the write
+ * inside one lock is the fix, not a retry afterwards.
+ */
+export declare class Thread {
+    #private;
+    private readonly store;
+    private readonly key;
+    constructor(store: SessionStore, key: string);
+    messages(): Promise<ThreadMessage[]>;
+    /** How many messages the thread holds. */
+    count(): Promise<number>;
+    /**
+     * Append messages, in order, and return them with their assigned positions.
+     *
+     * Read-and-write inside ONE lock. See the class docblock.
+     */
+    record(messages: readonly JsonObject[], runId?: string | null): Promise<ThreadMessage[]>;
+    /**
+     * Forget the conversation.
+     *
+     * Deliberately separate from `Session.forget()`, which drops only the
+     * ephemeral half. Losing a thread is not a cache miss and must never be a
+     * side effect of clearing session state.
+     */
+    clear(): Promise<void>;
+}