@nathapp/nax-agent 0.91.7 → 0.91.8-canary.1

package/dist/memory/operations.js

@@ -0,0 +1,440 @@
+/**
+ * The memory operations: what an agent's intent becomes once the store agrees to
+ * keep it.
+ *
+ * `saveMemoryNote` is the write path, and the only place a `MemoryNoteWrite`
+ * becomes a `MemoryNote`. Validation comes first and everything else after it:
+ * `validateMemoryNoteWrite` owns what may be stored (`validate.ts` — the field
+ * limits and the secret scan), so a refusal is thrown as `MEMORY_WRITE_REFUSED`
+ * with that reason as its message and nothing on disk is touched. This file adds
+ * no rule of its own; it only decides what to do with the answer.
+ *
+ * A write that passes is staged in the mirror before any provider is asked, and the
+ * staging is what outlives a provider that cannot take it: a provider that does not
+ * answer, and a push that fails or times out, leave the note exactly where it is and
+ * put the request — under the id the note was staged with — on the outbox, so a later
+ * sync delivers what this session already remembers. Only a permanent refusal is
+ * undone: the note under the key is read before staging (`previous`) and written back
+ * — or removed, when there was none — because a refusal is the one answer that will
+ * never change. After acceptance there is no rollback either: the provider holds the
+ * note, so a mirror write that then fails leaves the staged note in place and reports
+ * the bookkeeping failure. See `refusal.ts` for what a refusal does to the queue and
+ * the mirror, and why each step stands on its own.
+ *
+ * The note is minted with its own UUID — which is also the request's client id, so the save
+ * and the write that delivers it are named by one id — starts `active` under `direct` and
+ * `pending` under `proposal`, and is stamped with the caller's clock. The provider is probed
+ * and pushed through their deadlines as `raceTimeout` races, and its answer, never the
+ * caller's guess, decides the note's final id and status.
+ *
+ * A key the outbox already holds a queued write for is not pushed at all: the new one joins
+ * the queue behind it, so the provider receives them in the order the agent made them. That
+ * order is only meaningful if two saves of the key cannot both decide it, so a mirror's saves
+ * run one after another — in this process (`orderedByMirrorLocks`) and across processes (the
+ * store's lock files, project and user alike). A contending save waits for the holder to
+ * release (`waitForTurn`) before it stages or queues, so a holder paused before enqueueing
+ * still keeps the earlier sequence; an entry for the key alone is not permission to proceed,
+ * because it may predate the current holder. Only a save fenced by a sync known to this
+ * process queues without staging — it leaves the mirror and index to that sync — and every
+ * save that stages refreshes the index, so the next session reads the note whether or not this
+ * session could deliver it.
+ *
+ * `forgetMemoryNote` is the other half, and it only retires a note the mirror holds: an absent
+ * slug is a refusal. It declares its queue entry *before* touching the note, so the intent is
+ * durable first; under `direct` the note then goes, kept aside for a refusal to put back, and
+ * under `proposal` it stays, with the marker coming from the outbox alone.
+ *
+ * `approveMemoryNote` is the transition a proposal waits for: a pending note is rewritten in force
+ * under the caller's clock and the index is regenerated from the mirror, a note already in force is
+ * returned as it stands, and a note that is history — or one this mirror does not hold — is the
+ * same `MEMORY_NOTE_NOT_FOUND` refusal a forget of it would be. It asks no provider and writes
+ * nothing to the queue, but it still writes the mirror, so it takes the same ordering and the same
+ * locks a save takes. It reads the held-forget set only to keep the index's marker, and approves
+ * no queued forget: the entry stays the outbox's.
+ */
+import { randomUUID } from "node:crypto";
+import { getLogger } from "#src/infra/agent-logger";
+import { NaxError } from "#src/infra/nax-error";
+import { refreshMemoryIndex } from "./index-render.js";
+import { clockOf, mirrorSyncInFlight, orderedByMirrorLocks, withMirrorLock, } from "./mirror-lock.js";
+import { isMemoryPushRejected } from "./note.js";
+import { createMemoryOutbox } from "./outbox.js";
+import { discardRefused, restoreForgotten, restoreNote } from "./refusal.js";
+import { GLOBAL_MEMORY_TIMERS, providerAnswers, raceTimeout } from "./support.js";
+import { MEMORY_OP_TIMEOUT_MS, memoryNoteKey, } from "./types.js";
+import { forgetReasonRefusal, validateMemoryNoteWrite } from "./validate.js";
+const ERROR_STAGE = "memory";
+/** The status a write starts in: a proposal is not in force until it is approved. */
+const STATUS_BY_MODE = {
+    direct: "active",
+    proposal: "pending",
+};
+/** The status a forget rests in with no provider answer: retired, or still awaiting approval. */
+const FORGET_STATUS_BY_MODE = {
+    direct: "deleted",
+    proposal: "pending",
+};
+/** The refusal a rejected write is thrown as: the validator's reason as the message, its field as context. */
+function writeRefused(refusal) {
+    return new NaxError(refusal.reason, "MEMORY_WRITE_REFUSED", { stage: ERROR_STAGE, field: refusal.field });
+}
+/** The note a write becomes: a fresh id, the mode's starting status and the caller's clock. */
+function stagedNote(input) {
+    const { write } = input;
+    return {
+        id: randomUUID(),
+        slug: write.slug,
+        type: write.type,
+        scope: write.scope,
+        description: write.description,
+        source: input.source,
+        updatedAt: clockOf(input)().toISOString(),
+        status: STATUS_BY_MODE[input.writeMode],
+        body: write.body,
+    };
+}
+/** The request one staged note is pushed as: the note's own id keys the write. */
+function saveRequest(note, writeMode) {
+    return { kind: "save", clientId: note.id, scope: note.scope, slug: note.slug, writeMode, note };
+}
+/**
+ * The post-acceptance half: record what the provider made of the note.
+ *
+ * Only the provider's id and status are taken from the answer — the note's own
+ * source and timestamp are the caller's, and the delivery says what became of the
+ * write, not when it was made. This runs after the provider has accepted the
+ * write, so a failure here leaves the staged note in place: the mirror keeps the
+ * note the provider holds, and the bookkeeping failure reaches the caller. Rolling
+ * back instead would hand the mirror a note the provider no longer agrees with.
+ */
+async function recordDelivered(input, note, pushed) {
+    await input.store.writeNote({ ...note, id: pushed.id, status: pushed.status });
+}
+/**
+ * Regenerate the indexes from what the store now holds, so the next session reads this write.
+ *
+ * The queue is read for the notes whose forget is still waiting: that marker is the outbox
+ * speaking, and an index rendered without it would report a retire that is still in flight as
+ * though it had never been asked for.
+ */
+async function refreshIndex(input) {
+    await refreshMemoryIndex(input.store, { heldForgets: await input.outbox.heldKeys("forget") });
+}
+/** The undelivered answer: the write is on the queue, not delivered. */
+function queued(note) {
+    return { slug: note.slug, status: note.status, delivered: false };
+}
+/**
+ * Queue a write this save could not deliver and rebuild the index from what the mirror holds:
+ * the staged note is what the mirror keeps, so the next session has to see it — whether this
+ * save staged it or it was already there when this one joined the queue behind another.
+ */
+async function queueUnderLock(input, note, request) {
+    await input.outbox.enqueue(request);
+    await refreshIndex(input);
+    return queued(note);
+}
+/**
+ * The answer for a write that is already on the queue and whose staged note the mirror
+ * keeps: the entry is what makes it durable, so the index is the only thing left to rebuild.
+ */
+async function queuedEntryResult(input, note) {
+    await refreshIndex(input);
+    return queued(note);
+}
+/**
+ * Queue a write another writer's mirror could not take: the entry is the only thing this
+ * save writes.
+ *
+ * The index is not rebuilt here on purpose: rendering it from a mirror its owner is still
+ * changing could publish their half-written state over the view this save refused to touch,
+ * and the owner's own refresh (or the sync that delivers this entry) is the one that counts.
+ * The request keeps the id the note was minted with, so the note, the entry and the write a
+ * later sync sends share one client id and a replay is recognisable.
+ */
+async function queueFenced(input, note, request) {
+    await input.outbox.enqueue(request);
+    return queued(note);
+}
+/**
+ * Stage the note in the mirror and declare the write on the queue, while holding the lock.
+ *
+ * The note under the key is read first, because a permanent refusal has to be able to put it
+ * back. A key the outbox already holds a queued write for is not taken any further: this
+ * write joins the queue behind the one already waiting, and the order the agent wrote them
+ * in survives. Otherwise the note is staged and its request goes on the queue *before* the
+ * provider is asked. The lock covers both declaration and delivery, so a contending
+ * save cannot take an earlier sequence even if this holder is paused before enqueueing.
+ * A delivery that succeeds takes the entry back off again.
+ */
+async function deliverLocked(input) {
+    const note = stagedNote(input);
+    const request = saveRequest(note, input.writeMode);
+    const previous = await input.store.readNote(input.write.scope, input.write.slug);
+    await input.store.writeNote(note);
+    if ((await input.outbox.heldKeys()).has(memoryNoteKey(note.scope, note.slug))) {
+        return await queueUnderLock(input, note, request);
+    }
+    await input.outbox.enqueue(request);
+    return await handOver(input, note, previous);
+}
+/**
+ * Ask the provider for the note the queue already carries, and take the entry back on success.
+ *
+ * Anything short of an acceptance leaves the entry where it is and reports the save as
+ * undelivered; the staged note stays too, because the local write is the newer fact and is
+ * exactly what the queue will deliver.
+ *
+ * `MEMORY_PUSH_REJECTED` is the provider saying it will never take this write, so queueing it
+ * would only repeat the refusal: the entry comes back off, the mirror is put back the way it
+ * was, and the provider's error reaches the caller. Only the provider's answer changes the
+ * note's id and status, and only after it has taken the write — the delivered arm is the one
+ * arm that cannot be undone.
+ */
+async function handOver(input, note, previous) {
+    const timers = input.timers ?? GLOBAL_MEMORY_TIMERS;
+    if (!(await providerAnswers(input.provider, timers)))
+        return await queuedEntryResult(input, note);
+    let answer;
+    try {
+        answer = await raceTimeout(input.provider.push(saveRequest(note, input.writeMode)), MEMORY_OP_TIMEOUT_MS, timers);
+    }
+    catch (error) {
+        if (!isMemoryPushRejected(error))
+            return await queuedEntryResult(input, note);
+        await discardRefused(input, note.id);
+        await restoreNote(input, note.scope, note.slug, previous);
+        throw error;
+    }
+    await input.outbox.remove(note.id);
+    await recordDelivered(input, note, answer);
+    await refreshIndex(input);
+    return { slug: note.slug, status: answer.status, delivered: true };
+}
+/**
+ * Store one note and deliver it to the provider, or queue it for the next sync.
+ *
+ * The validator decides first, so a refusal leaves the store exactly as it found it.
+ * Everything after it runs in the mirror's own order — one save at a time in this process
+ * (`orderedByMirrorLocks`) and one writer at a time across processes (the store's locks) —
+ * because the "is this key already queued?" answer, the note staged in the mirror and the
+ * entry the queue takes are one decision: interleaved, they deliver in the wrong order or
+ * leave the mirror on the older note.
+ */
+export async function saveMemoryNote(input) {
+    const refusal = validateMemoryNoteWrite(input.write, input.source);
+    if (refusal !== null)
+        throw writeRefused(refusal);
+    return await orderedByMirrorLocks(input.store, () => commitSave(input));
+}
+/**
+ * The ordered half of a save: take the mirror's lock, and stage and declare under it.
+ *
+ * A mirror another writer owns is not this save's to change, and nothing is lost by
+ * leaving it alone: the note goes on the outbox under its own client id, and the sync that
+ * does own the mirror delivers it in sequence. Staging into a mirror someone else is
+ * draining or pulling would be the very interleaving the lock is there to prevent.
+ *
+ * A sync in this process is the one owner that needs no wait: it queues no save of its own,
+ * so this write can join the queue immediately. Any other owner has to release the lock
+ * before this save stages or declares (`waitForTurn`), preserving sequence allocation even
+ * when the holder is paused before enqueueing.
+ */
+async function commitSave(input) {
+    if (mirrorSyncInFlight(input.store))
+        return await queueWithoutMirror(input);
+    return await withMirrorLock(input, () => deliverLocked(input));
+}
+/**
+ * The answer when another writer owns the mirror: the write is queued and the mirror is
+ * left alone.
+ *
+ * Nothing is staged, so no index is rebuilt either — the mirror still holds what its owner
+ * put there, and this note reaches it when a sync delivers the entry. The queue is the one
+ * part of the mirror any writer may add to: an entry is a whole file written atomically,
+ * named by its sequence and client id.
+ */
+async function queueWithoutMirror(input) {
+    const note = stagedNote(input);
+    return await queueFenced(input, note, saveRequest(note, input.writeMode));
+}
+/** The refusal a note this mirror does not hold — or one that is history — is thrown as. */
+function noteNotFound(input) {
+    return new NaxError(`memory note "${memoryNoteKey(input.scope, input.slug)}" is not in this mirror`, "MEMORY_NOTE_NOT_FOUND", { stage: ERROR_STAGE, scope: input.scope, slug: input.slug });
+}
+/** The request one forget is pushed as: its own UUID keys the write, and the reason rides along. */
+function forgetRequest(input) {
+    const { scope, slug, writeMode, reason } = input;
+    return { kind: "forget", clientId: randomUUID(), scope, slug, writeMode, reason };
+}
+/** Queue a forget this operation could not deliver, and rebuild the index so its marker shows. */
+async function queuedForget(input) {
+    await refreshIndex(input);
+    return { slug: input.slug, status: FORGET_STATUS_BY_MODE[input.writeMode], delivered: false };
+}
+/**
+ * The ordered half of a forget: join a sync that owns the mirror, or take the lock and decide
+ * under it. Nothing is read from the mirror before the lock is held, so what a forget retires
+ * and what the queue is asked about are both the mirror's current answer rather than a stale one.
+ */
+async function commitForget(input) {
+    const request = forgetRequest(input);
+    if (mirrorSyncInFlight(input.store))
+        return await queueFencedForget(input, request);
+    return await withMirrorLock(input, () => forgetLocked(input, request));
+}
+/**
+ * The answer while a sync of this process owns the mirror: the request is queued, and the
+ * mirror is only read.
+ *
+ * The note is still required — a forget of a slug the mirror does not hold is refused rather
+ * than queued — but nothing is deleted and no index is rendered: an index built from a mirror
+ * the sync is halfway through changing would publish its half-written state, and the sync's own
+ * refresh is the one that counts.
+ */
+async function queueFencedForget(input, request) {
+    if ((await input.store.readNote(input.scope, input.slug)) === null)
+        throw noteNotFound(input);
+    await input.outbox.enqueue(request);
+    return { slug: input.slug, status: FORGET_STATUS_BY_MODE[input.writeMode], delivered: false };
+}
+/**
+ * Retire the note and deliver the request, while the mirror's lock is held.
+ *
+ * The intent is declared on the queue *before* the note it names is touched. Under `direct`
+ * this method deletes that note, and a delete no durable request records is a retire the
+ * provider never hears about — the next pull restores the note and the agent's decision is
+ * silently undone. Writing the entry first costs one file write and makes every later failure
+ * recoverable: a failed delete leaves the entry to be replayed, a transient push failure
+ * leaves it queued, and only a permanent refusal takes it back off (with the note put back,
+ * under `direct`, because a refusal will never change).
+ */
+async function forgetLocked(input, request) {
+    const previous = await input.store.readNote(input.scope, input.slug);
+    if (previous === null)
+        throw noteNotFound(input);
+    // Read before the entry goes on: the one this call is about to add cannot be "earlier work".
+    const waiting = (await input.outbox.heldKeys()).has(memoryNoteKey(input.scope, input.slug));
+    await input.outbox.enqueue(request);
+    if (input.writeMode === "direct")
+        await input.store.deleteNote(input.scope, input.slug);
+    if (waiting)
+        return await queuedForget(input);
+    return await handOverForget(input, previous, request);
+}
+/**
+ * Ask the provider to forget the note this operation already queued.
+ *
+ * Anything short of an acceptance leaves the entry where it is: the entry is what makes the
+ * retire durable, not this attempt. Acceptance and a permanent refusal both take it back off
+ * — retrying a refusal would repeat it — and the refusal puts the note back under `direct`.
+ */
+async function handOverForget(input, previous, request) {
+    const timers = input.timers ?? GLOBAL_MEMORY_TIMERS;
+    if (!(await providerAnswers(input.provider, timers)))
+        return await queuedForget(input);
+    let answer;
+    try {
+        answer = await raceTimeout(input.provider.push(request), MEMORY_OP_TIMEOUT_MS, timers);
+    }
+    catch (error) {
+        if (!isMemoryPushRejected(error))
+            return await queuedForget(input);
+        // The refusal is the caller's answer; the entry and the note are put back regardless of
+        // whether removing it works, so a refused forget never leaves the note deleted.
+        await discardRefused(input, request.clientId);
+        if (input.writeMode === "direct")
+            await restoreForgotten(input, previous);
+        throw error;
+    }
+    await input.outbox.remove(request.clientId);
+    await refreshIndex(input);
+    return { slug: input.slug, status: answer.status, delivered: true };
+}
+/**
+ * Forget one note: retire it in the mirror and tell the provider, or queue the request.
+ *
+ * The reason is checked first, before the lock and before anything is written: a justification
+ * that is empty, carries a line break or runs past `MEMORY_FORGET_REASON_MAX_CHARS` is refused
+ * as `MEMORY_WRITE_REFUSED`, so no such text reaches the request the provider is pushed or the
+ * entry a queued forget leaves in the mirror's outbox.
+ *
+ * A mirror another writer owns is not this forget's to change, so it is coordinated exactly as
+ * a save is: this process's chain (`orderedByStore`) orders the forgets and saves of one mirror,
+ * and the store's lock file orders them across processes. Without the lock a forget could delete
+ * a note while another process's save restored or overwrote it, and the queue's order would
+ * describe writes that never happened in that order. A permanent refusal is the one answer
+ * undone, under `direct`, and it is rethrown; an absent slug is never queued.
+ */
+export async function forgetMemoryNote(input) {
+    const refusal = forgetReasonRefusal(input.reason);
+    if (refusal !== null)
+        throw writeRefused(refusal);
+    return await orderedByMirrorLocks(input.store, () => commitForget(input));
+}
+/** The statuses an approval may not bring into force: a note that is already history. */
+const RETIRED_STATUSES = new Set(["superseded", "rejected", "deleted"]);
+/** The note one approval rewrites: the same note, in force, stamped with the caller's clock. */
+function inForce(note, now) {
+    return { ...note, status: "active", updatedAt: now().toISOString() };
+}
+/** The mirror's own queue, as an approval reads it: where the index's forget markers live. */
+function mirrorOutbox(store) {
+    return createMemoryOutbox({ dir: store.paths.outboxDir });
+}
+/**
+ * The mirror's lock as this approval takes it: the caller's seam where it gave one, and the
+ * process defaults — including the logger slot — where it did not.
+ */
+function lockInputOf(input) {
+    return {
+        store: input.store,
+        logger: input.logger ?? getLogger(),
+        now: input.now,
+        timers: input.timers,
+        isAlive: input.isAlive,
+    };
+}
+/**
+ * The locked half of an approval: read, decide and rewrite while no other writer of this
+ * mirror can change the note in between.
+ *
+ * The read and the write have to be one decision — that is the whole reason this takes the
+ * lock at all — so a note another writer replaced while this waited is the note that gets
+ * approved, never the copy this operation would otherwise have read before the wait.
+ */
+async function approveLocked(input) {
+    const note = await input.store.readNote(input.scope, input.slug);
+    if (note === null || RETIRED_STATUSES.has(note.status))
+        throw noteNotFound(input);
+    if (note.status === "active")
+        return note;
+    const approved = inForce(note, clockOf(input));
+    await input.store.writeNote(approved);
+    await refreshIndex({ store: input.store, outbox: mirrorOutbox(input.store) });
+    return approved;
+}
+/**
+ * Put one pending note in force in this mirror.
+ *
+ * Only the note the mirror holds is consulted, so approval is a local transition rather than an
+ * authorization step: it asks no provider and writes nothing to the queue, and a forget waiting
+ * on that queue is still waiting afterwards. What it does read from the queue is the set of
+ * notes whose forget is queued, because the index it regenerates carries that marker and an
+ * index rendered without it would report a still-pending retire as though it had never been
+ * asked for.
+ *
+ * The read and the rewrite are one decision, so they run under the same ordering and the same
+ * lock file a save and a forget use: this is a writer of the mirror, and what it approves must
+ * be the note the mirror holds now rather than a copy read before another writer's newer one
+ * landed. Waiting is the right answer here, unlike a save's — an approval has no queue to put
+ * its write on, so it has to be the writer when it reads.
+ *
+ * A note already in force is returned exactly as it stands — approving it again is not a
+ * rewrite, so its `updatedAt` still says when it was made active. A note that is history is not
+ * a note waiting for approval, and neither is one this mirror does not hold: both are
+ * `MEMORY_NOTE_NOT_FOUND`, because there is nothing to approve.
+ */
+export async function approveMemoryNote(input) {
+    return await orderedByMirrorLocks(input.store, () => withMirrorLock(lockInputOf(input), () => approveLocked(input)));
+}

package/dist/memory/outbox.d.ts

@@ -0,0 +1,35 @@
+import type { MemoryWriteRequest } from "./provider-types.ts";
+/** The write the caller hands over: it owns the content, the outbox may own the id. */
+type OutboxRequest = Omit<MemoryWriteRequest, "clientId"> & {
+    clientId?: string;
+};
+/** One queued write as the outbox holds it: the request plus where it sits in the order. */
+export type MemoryOutboxEntry = MemoryWriteRequest & {
+    readonly seq: number;
+    readonly enqueuedAt: string;
+    readonly state: "queued" | "rejected";
+    /** The rejection reason once rejected; the request's own reason until then. */
+    readonly reason?: string;
+    /** A reason the request itself carried (a forget's justification), kept across a rejection. */
+    readonly requestReason?: string;
+};
+/** The durable queue of unacknowledged writes. */
+export interface MemoryOutbox {
+    /**
+     * Take one write, stamped with its sequence. A request the queue cannot carry is refused
+     * before any file is written: `MEMORY_WRITE_REFUSED` for a reason past
+     * `MEMORY_FORGET_REASON_MAX_CHARS` (or empty, or spanning lines) and
+     * `MEMORY_CLIENT_ID_INVALID` for an id that is not one.
+     */
+    enqueue(request: OutboxRequest): Promise<MemoryOutboxEntry>;
+    list(): Promise<MemoryOutboxEntry[]>;
+    listInvalid(): Promise<string[]>;
+    remove(clientId: string): Promise<void>;
+    markRejected(clientId: string, reason: string): Promise<void>;
+    heldKeys(kind?: "save" | "forget"): Promise<ReadonlySet<string>>;
+}
+export declare function createMemoryOutbox(input: {
+    readonly dir: string;
+    readonly now?: () => Date;
+}): MemoryOutbox;
+export {};