@particle-academy/prism-harness 0.0.0

package/dist/stores/file-session-store.js

@@ -0,0 +1,284 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { mkdir, open, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isJsonObject } from '../json.js';
+import { HarnessError } from '../errors.js';
+/**
+ * State on disk, as one JSON file per key. DURABLE, and it says so.
+ *
+ * The default durable driver for a port with no database and no dependencies.
+ * A real deployment points the durable slot at a database instead; this exists
+ * so the package WORKS ON INSTALL rather than requiring infrastructure before
+ * the first session can be opened — the same reason the PHP reference defaults
+ * both slots to `database`.
+ *
+ * ## Two properties that matter more than speed
+ *
+ * **Writes are atomic.** A payload is written to a temporary file and renamed
+ * over the target, because `rename` is atomic on both POSIX and Windows. A
+ * partial write here is a corrupted thread, and a process killed mid-write is
+ * ordinary rather than exotic.
+ *
+ * **The lock is cross-process.** It is an exclusive-create lockfile (`wx`),
+ * which is the one primitive that is atomic on every filesystem worth
+ * supporting — unlike an "is it there?" check followed by a create, which has a
+ * window between the two. Two workers on one machine genuinely exclude each
+ * other. Two workers on different machines sharing a network filesystem do NOT
+ * reliably, and no file lock can promise that; use a database or Redis there.
+ */
+export class FileSessionStore {
+    #directory;
+    constructor(directory) {
+        this.#directory = directory;
+        mkdirSync(directory, { recursive: true });
+    }
+    durability() {
+        return 'durable';
+    }
+    async get(key) {
+        let raw;
+        try {
+            raw = await readFile(this.#pathFor(key), 'utf8');
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw error;
+        }
+        let document;
+        try {
+            document = JSON.parse(raw);
+        }
+        catch (error) {
+            throw HarnessError.unmappableContent(`the stored payload for [${key}] is not valid JSON`, {
+                cause: error,
+            });
+        }
+        if (!isJsonObject(document)) {
+            throw HarnessError.unmappableContent(`the stored payload for [${key}] is not an object`);
+        }
+        const expiresAt = document.expires_at;
+        if (typeof expiresAt === 'number' && expiresAt <= Date.now()) {
+            await this.forget(key);
+            return null;
+        }
+        return isJsonObject(document.payload) ? document.payload : null;
+    }
+    async put(key, payload, ttlSeconds = null) {
+        const target = this.#pathFor(key);
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        const document = JSON.stringify({
+            key,
+            payload,
+            expires_at: ttlSeconds === null ? null : Date.now() + ttlSeconds * 1000,
+        });
+        await mkdir(this.#directory, { recursive: true });
+        await writeFile(temporary, document, 'utf8');
+        try {
+            // Atomic on both POSIX and Windows. A reader either sees the whole old
+            // payload or the whole new one, never half of either.
+            await rename(temporary, target);
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
+    }
+    async forget(key) {
+        await rm(this.#pathFor(key), { force: true });
+    }
+    async withLock(key, callback, ttlSeconds = 10, waitSeconds = 5) {
+        const lockPath = `${this.#pathFor(key)}.lock`;
+        const deadline = Date.now() + waitSeconds * 1000;
+        for (;;) {
+            try {
+                // `wx` fails if the file exists. Exclusive CREATION is atomic; a
+                // check-then-create is not, and the window between the two is exactly
+                // where two workers both decide they hold the lock.
+                const handle = await open(lockPath, 'wx');
+                // ONE write, and the terminator goes in it. The newline is what lets a
+                // reader tell a complete stamp from a torn one, so it must never be a
+                // second write that could be the half that did not land. See
+                // `#expired`, and note the format is shared with the other two ports.
+                await handle.writeFile(stamp(Date.now() + ttlSeconds * 1000), 'utf8');
+                await handle.close();
+                try {
+                    return await callback();
+                }
+                finally {
+                    await this.#release(lockPath);
+                }
+            }
+            catch (error) {
+                if (!isHeld(error))
+                    throw error;
+                // A lock whose TTL has passed belonged to a process that died holding
+                // it. Left alone it would wedge the key forever, which is worse than
+                // the small race in reclaiming it — and the reclaim is itself a
+                // create-exclusive, so only one waiter can win.
+                if (await this.#expired(lockPath, ttlSeconds)) {
+                    await unlink(lockPath).catch(() => undefined);
+                    continue;
+                }
+                if (Date.now() >= deadline) {
+                    throw HarnessError.sessionLocked(key, waitSeconds);
+                }
+                await sleep(25);
+            }
+        }
+    }
+    /**
+     * Give the lock up, and NEVER leave it held on the way out.
+     *
+     * Deleting is the normal path, but on Windows it can fail: another waiter
+     * attempting to create the same path holds a transient handle, and the unlink
+     * then raises EPERM. Swallowing that — which is what this did first — LEAKS
+     * THE LOCK. The waiter then sees a lockfile whose TTL is still in the future,
+     * has no way to know its holder is gone, and blocks for the whole wait before
+     * failing. Not theoretical: `prism-harness-py` hit exactly this the first
+     * time two threads recorded a message concurrently, and this port had the
+     * same defect with no test that happened to reach it.
+     *
+     * So if the file cannot be removed, it is rewritten with an ALREADY-PAST
+     * expiry. Any waiter reclaims it on its next attempt, which is the same path
+     * a genuinely dead holder takes.
+     */
+    async #release(lockPath) {
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+            try {
+                await unlink(lockPath);
+                return;
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return;
+                await sleep(5);
+            }
+        }
+        // Nothing left to try but mark it dead. The TTL is the backstop, and it is
+        // why the lockfile carries one at all. TERMINATED like any other stamp: an
+        // unterminated `0` reads as a torn write, and a waiter would then sit on
+        // the mtime bound for a whole ttl instead of reclaiming it at once — the
+        // exact delay this path exists to avoid.
+        await writeFile(lockPath, stamp(0), 'utf8').catch(() => undefined);
+    }
+    /**
+     * Whether this lock belonged to a holder that is gone.
+     *
+     * ## An UNFINISHED stamp is HELD, not expired in 1970
+     *
+     * Taking the lock is an exclusive create and THEN a write of the expiry —
+     * two operations, with a moment in between where the file exists and is
+     * incomplete. There are two ways to read it in that moment and both used to
+     * steal the lock:
+     *
+     *  - **Empty.** `Number('')` is `0`, which is finite and certainly
+     *    `<= Date.now()`.
+     *  - **Torn.** A partial write leaves a PREFIX of the timestamp —
+     *    `17356899` where `1735689900000` was meant — and every prefix of a
+     *    number is a SMALLER number. It parses, it is finite, and it is decades
+     *    in the past. This one is worse than the empty case precisely because it
+     *    does not look broken.
+     *
+     * Either way a waiter concluded the holder was long dead, deleted the lock,
+     * and took one somebody was actively holding. Two callers, one key: the
+     * failure this lock exists to prevent, produced BY the mechanism meant to
+     * recover from a dead holder. The empty case surfaced as a flaky test — about
+     * one run in eight — which is how it survived; the torn case would not have
+     * surfaced at all.
+     *
+     * The fix is the TERMINATOR. A stamp is digits followed by a newline, written
+     * in one write, so anything else is an unfinished write rather than a small
+     * number. Unreadable then means WAIT — `session_locked` after the wait
+     * period, which is loud and recoverable — instead of deleting a live holder's
+     * lock. The format is shared with the PHP and Python ports, because a worker
+     * in any of the three may be pointed at the same store directory.
+     *
+     * ## …but only until it is older than the ttl
+     *
+     * Treating an empty lockfile as held forever would let a process that died
+     * inside that window wedge the key permanently, which is the worse failure
+     * of the two. The file's own mtime bounds it: the window is microseconds in a
+     * live process, so a file still empty a whole ttl later belonged to one that
+     * did not survive it. Nothing extra has to be written for that to work.
+     */
+    async #expired(lockPath, ttlSeconds) {
+        let raw;
+        try {
+            raw = await readFile(lockPath, 'utf8');
+        }
+        catch {
+            // Gone between the failed create and this read: treat it as not expired
+            // and let the next attempt take it cleanly.
+            return false;
+        }
+        // Digits AND a terminator, or this is not a finished stamp. Checked as a
+        // whole rather than by trying to parse and hoping a bad value fails to:
+        // the torn case parses perfectly and is the reason this check exists.
+        if (!STAMP.test(raw)) {
+            try {
+                const { mtimeMs } = await stat(lockPath);
+                return mtimeMs + ttlSeconds * 1000 <= Date.now();
+            }
+            catch {
+                return false;
+            }
+        }
+        const expiresAt = Number(raw.slice(0, -1));
+        return Number.isFinite(expiresAt) && expiresAt <= Date.now();
+    }
+    /**
+     * One file per key, named by a digest.
+     *
+     * A session key contains colons, which are legal on POSIX and not on Windows,
+     * and it is long enough to run into path ceilings once a scope is appended.
+     * The digest sidesteps both, and the key itself is stored INSIDE the file so
+     * the mapping stays inspectable.
+     */
+    #pathFor(key) {
+        return join(this.#directory, `${createHash('sha256').update(key).digest('hex').slice(0, 32)}.json`);
+    }
+}
+/**
+ * A finished lock stamp: digits, then a newline. NOTHING ELSE.
+ *
+ * The terminator is the only thing that distinguishes a complete timestamp from
+ * a torn one, because a prefix of a timestamp is a perfectly valid smaller
+ * timestamp. Shared with the PHP and Python ports — a worker in any of the
+ * three may be pointed at the same store directory, and one that does not
+ * emit the newline has its locks waited out rather than reclaimed everywhere
+ * else.
+ */
+const STAMP = /^\d+\n$/;
+function stamp(expiresAt) {
+    return `${String(Math.trunc(expiresAt))}\n`;
+}
+function isMissing(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+/**
+ * "The lock is already held" — under four different names.
+ *
+ * POSIX says EEXIST. WINDOWS DOES NOT, reliably: deleting a file that another
+ * handle still has open leaves it in a pending-delete state, and a create
+ * attempt against that returns EPERM, EACCES or EBUSY instead. That window is
+ * not rare — it is exactly the moment one caller releases the lock while the
+ * next is trying to take it, which is the common case under contention rather
+ * than an edge.
+ *
+ * Treating those as "held, retry" is also the safe direction to be wrong in: a
+ * genuine permission problem retries until the wait expires and then reports
+ * `session_locked`, which is a survivable failure. Treating them as "not held"
+ * would hand the same lock to two callers.
+ */
+function isHeld(error) {
+    const code = typeof error === 'object' && error !== null ? error.code : undefined;
+    return code === 'EEXIST' || code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}

package/dist/stores/memory-session-store.d.ts

@@ -0,0 +1,22 @@
+import type { JsonObject } from '../json.js';
+import type { Durability, SessionStore } from './session-store.js';
+/**
+ * State in this process's memory. VOLATILE, and it says so.
+ *
+ * The right home for the ephemeral slot in a test or a single-process tool, and
+ * REFUSED for the durable slot by the store manager — not as a technicality:
+ * the contents do not outlive the process, and the durable slot holds approvals
+ * a human has not answered yet.
+ *
+ * The lock is real but PROCESS-LOCAL. Two workers cannot see each other's
+ * locks, which is the whole reason a deployment uses something else; this
+ * serialises callers within one process and claims nothing beyond that.
+ */
+export declare class MemorySessionStore implements SessionStore {
+    #private;
+    durability(): Durability;
+    get(key: string): Promise<JsonObject | null>;
+    put(key: string, payload: JsonObject, ttlSeconds?: number | null): Promise<void>;
+    forget(key: string): Promise<void>;
+    withLock<T>(key: string, callback: () => T | Promise<T>, _ttlSeconds?: number, waitSeconds?: number): Promise<T>;
+}

package/dist/stores/memory-session-store.js

@@ -0,0 +1,97 @@
+import { clone } from '../json.js';
+import { HarnessError } from '../errors.js';
+/**
+ * State in this process's memory. VOLATILE, and it says so.
+ *
+ * The right home for the ephemeral slot in a test or a single-process tool, and
+ * REFUSED for the durable slot by the store manager — not as a technicality:
+ * the contents do not outlive the process, and the durable slot holds approvals
+ * a human has not answered yet.
+ *
+ * The lock is real but PROCESS-LOCAL. Two workers cannot see each other's
+ * locks, which is the whole reason a deployment uses something else; this
+ * serialises callers within one process and claims nothing beyond that.
+ */
+export class MemorySessionStore {
+    #entries = new Map();
+    /** Key → the promise chain currently serialising work on it. */
+    #locks = new Map();
+    durability() {
+        return 'volatile';
+    }
+    async get(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined) {
+            return null;
+        }
+        if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+            this.#entries.delete(key);
+            return null;
+        }
+        // A copy, so a caller mutating what it read cannot reach into the store.
+        return clone(entry.payload);
+    }
+    async put(key, payload, ttlSeconds = null) {
+        this.#entries.set(key, {
+            payload: clone(payload),
+            expiresAt: ttlSeconds === null ? null : Date.now() + ttlSeconds * 1000,
+        });
+    }
+    async forget(key) {
+        this.#entries.delete(key);
+    }
+    async withLock(key, callback, _ttlSeconds = 10, waitSeconds = 5) {
+        const previous = this.#locks.get(key) ?? Promise.resolve();
+        let release;
+        const held = new Promise((resolve) => {
+            release = resolve;
+        });
+        // CLAIMED SYNCHRONOUSLY, before the first `await`.
+        //
+        // Registering after awaiting is a check-then-act race: two callers arriving
+        // in the same tick both read an empty slot, both decide they hold the lock,
+        // and both run. That is the same shape as an `exists?`-then-`create` on the
+        // file driver, which is why that one uses exclusive creation instead — and
+        // it is not theoretical, it is what the serialisation test caught here.
+        //
+        // The chain resolves only once the previous holder has finished AND this
+        // one has released, so waiters queue in arrival order.
+        const chained = previous.then(() => held, () => held);
+        this.#locks.set(key, chained);
+        // The wait is bounded. A callback that never returns would otherwise hold
+        // every later caller forever, and "the lock timed out" is a far better
+        // failure than a request that hangs until something upstream gives up.
+        const acquired = await Promise.race([
+            previous.then(() => true, () => true),
+            sleep(waitSeconds * 1000).then(() => false),
+        ]);
+        if (!acquired) {
+            // Release before throwing, or everyone queued behind this caller waits on
+            // a lock that was never actually taken.
+            this.#releaseSlot(key, chained, release);
+            throw HarnessError.sessionLocked(key, waitSeconds);
+        }
+        try {
+            return await callback();
+        }
+        finally {
+            this.#releaseSlot(key, chained, release);
+        }
+    }
+    #releaseSlot(key, chained, release) {
+        release();
+        // Only clear the slot if nobody queued behind us. Deleting a slot another
+        // caller has already chained onto would let a third caller start while the
+        // second is still running.
+        if (this.#locks.get(key) === chained) {
+            this.#locks.delete(key);
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        // Do not hold the event loop open just to fail a lock later.
+        timer.unref?.();
+    });
+}

package/dist/stores/session-store.d.ts

@@ -0,0 +1,65 @@
+import type { JsonObject } from '../json.js';
+/**
+ * Whether a store's contents survive a deploy.
+ *
+ * This is the distinction the whole state layer turns on. An in-memory map or a
+ * Redis used as a cache is the natural home for live session state — and a
+ * cache is disposable by definition. Something has to say which of the two a
+ * configured store actually is, because the package cannot detect it and
+ * guessing wrong loses a half-executed agent action rather than a cheap value.
+ */
+export type Durability = 
+/**
+ * Contents may vanish at any time — a flush, an eviction, a deploy.
+ *
+ * Only safe for state whose loss degrades to a default: the active mode, the
+ * selected model, run bookkeeping. Ask again and you get a sensible answer.
+ */
+'volatile'
+/**
+ * Contents survive until deliberately removed.
+ *
+ * Required for anything whose loss is a correctness failure rather than an
+ * inconvenience — a pending tool approval is a half-executed action waiting
+ * on a human, and it has to outlive the request, the worker, and a deploy.
+ */
+ | 'durable';
+export declare function isDurable(durability: Durability): boolean;
+/**
+ * Where session state lives between turns.
+ *
+ * A server handles a request and moves on, so a session cannot be an object
+ * held in memory the way a single-process agent's is — it has to be
+ * reconstructed from a store every time. This is that store.
+ *
+ * Implementations declare their OWN durability rather than having it inferred.
+ * Only the application knows whether its Redis is persistent or a disposable
+ * cache, and the difference decides whether losing the contents is a shrug or a
+ * lost agent action.
+ */
+export interface SessionStore {
+    /** Null when nothing is stored. */
+    get(key: string): Promise<JsonObject | null>;
+    /** `ttlSeconds` of null keeps the payload until it is removed. */
+    put(key: string, payload: JsonObject, ttlSeconds?: number | null): Promise<void>;
+    forget(key: string): Promise<void>;
+    /**
+     * Run the callback while holding an EXCLUSIVE lock on the key.
+     *
+     * Two workers can resolve the same session at the same moment — a queued job
+     * finishing a run while the user sends another message is ordinary, not
+     * exotic. Whatever must not happen twice goes in here.
+     *
+     * Returns the callback's value. Throws `HarnessError` code `session_locked`
+     * if the lock cannot be acquired within `waitSeconds`, rather than running
+     * the callback anyway.
+     */
+    withLock<T>(key: string, callback: () => T | Promise<T>, ttlSeconds?: number, waitSeconds?: number): Promise<T>;
+    /**
+     * Whether this store's contents survive a deploy.
+     *
+     * Read by the manager when a slot is resolved: a store that reports itself
+     * volatile is refused for durable state instead of silently accepting it.
+     */
+    durability(): Durability;
+}

package/dist/stores/session-store.js

@@ -0,0 +1,3 @@
+export function isDurable(durability) {
+    return durability === 'durable';
+}

package/dist/stores/store-manager.d.ts

@@ -0,0 +1,32 @@
+import type { SessionStore } from './session-store.js';
+export declare const SLOT_EPHEMERAL = "ephemeral";
+export declare const SLOT_DURABLE = "durable";
+export type StoreFactory = () => SessionStore;
+export interface StoreManagerOptions {
+    /** Driver name per slot. Both default to whatever is registered as `default`. */
+    stores?: Partial<Record<'ephemeral' | 'durable', string>>;
+    /** Driver name → factory. Resolved lazily, and each driver is built at most once. */
+    drivers: Record<string, StoreFactory>;
+}
+/**
+ * Resolves the two state slots, and REFUSES a configuration that would lose work.
+ *
+ * State is split into two named slots rather than one store, because the halves
+ * have genuinely different requirements:
+ *
+ *  - `ephemeral` — active mode, selected model, run bookkeeping. Losing it
+ *    degrades to a default.
+ *  - `durable` — threads and pending tool approvals. Losing it is a correctness
+ *    failure, not a cache miss.
+ *
+ * The guard is the point of this class: a driver that reports itself volatile
+ * is refused for the durable slot AT RESOLVE TIME. Accepting it and finding out
+ * later is exactly the failure the package was written to avoid.
+ */
+export declare class SessionStoreManager {
+    #private;
+    constructor(options: StoreManagerOptions);
+    ephemeral(): SessionStore;
+    durable(): SessionStore;
+    slot(slot: string): SessionStore;
+}

package/dist/stores/store-manager.js

@@ -0,0 +1,57 @@
+import { HarnessError } from '../errors.js';
+import { isDurable } from './session-store.js';
+export const SLOT_EPHEMERAL = 'ephemeral';
+export const SLOT_DURABLE = 'durable';
+/**
+ * Resolves the two state slots, and REFUSES a configuration that would lose work.
+ *
+ * State is split into two named slots rather than one store, because the halves
+ * have genuinely different requirements:
+ *
+ *  - `ephemeral` — active mode, selected model, run bookkeeping. Losing it
+ *    degrades to a default.
+ *  - `durable` — threads and pending tool approvals. Losing it is a correctness
+ *    failure, not a cache miss.
+ *
+ * The guard is the point of this class: a driver that reports itself volatile
+ * is refused for the durable slot AT RESOLVE TIME. Accepting it and finding out
+ * later is exactly the failure the package was written to avoid.
+ */
+export class SessionStoreManager {
+    #drivers;
+    #slots;
+    #resolved = new Map();
+    constructor(options) {
+        this.#drivers = options.drivers;
+        this.#slots = {
+            [SLOT_EPHEMERAL]: options.stores?.ephemeral ?? 'default',
+            [SLOT_DURABLE]: options.stores?.durable ?? 'default',
+        };
+    }
+    ephemeral() {
+        return this.slot(SLOT_EPHEMERAL);
+    }
+    durable() {
+        return this.slot(SLOT_DURABLE);
+    }
+    slot(slot) {
+        const cached = this.#resolved.get(slot);
+        if (cached !== undefined)
+            return cached;
+        const name = this.#slots[slot] ?? 'default';
+        const factory = this.#drivers[name];
+        if (factory === undefined) {
+            throw HarnessError.unknownStoreDriver(slot, name);
+        }
+        const store = factory();
+        // Checked HERE rather than at construction, so it fires in the same place
+        // whether the store is configured up front, swapped in a test, or changed
+        // at runtime — and so a misconfiguration cannot lie dormant until the first
+        // approval needs saving.
+        if (slot === SLOT_DURABLE && !isDurable(store.durability())) {
+            throw HarnessError.volatileDurableStore(slot, name);
+        }
+        this.#resolved.set(slot, store);
+        return store;
+    }
+}

package/dist/subagent-runner.d.ts

@@ -0,0 +1,45 @@
+import type { PrismHarness } from './harness.js';
+import type { AgentRuntime } from './runtime.js';
+import type { Session } from './session.js';
+import { RunContext, type Subagent } from './subagents.js';
+import type { HarnessTool } from './tools.js';
+export type SubagentOutcome = 
+/** It ran and returned. */
+'completed'
+/** The tree had nothing left to spend. */
+ | 'exhausted'
+/** The tree was stopped. */
+ | 'cancelled'
+/** Refused before it began — depth, most often. */
+ | 'denied'
+/** It ran and threw. */
+ | 'failed';
+export interface SubagentResult {
+    subagent: string;
+    runId: string;
+    parentRunId: string;
+    outcome: SubagentOutcome;
+    text: string;
+    /** What to hand back to the model as the tool's result. */
+    toToolResult(): string;
+}
+/**
+ * Turns a declared `Subagent` into a TOOL the parent run can call.
+ *
+ * The parent is mid-run and holding its own session lock when this executes.
+ * Everything here is arranged so that fact stays harmless:
+ *
+ *  - the child resolves its OWN session address, so it takes a different lock;
+ *  - the child's authority comes from its declared mode, never the parent's;
+ *  - the child's budget is drawn from the tree's remaining allowance;
+ *  - EVERY way the child can end returns a framed result rather than throwing,
+ *    because the parent is a legitimate audience for "that did not work" and
+ *    tearing down the parent run would discard work it had already done.
+ */
+export declare class SubagentRunner {
+    private readonly harness;
+    private readonly runtime;
+    constructor(harness: PrismHarness, runtime: AgentRuntime);
+    tool(subagent: Subagent, parent: Session, context: RunContext, parentRunId: string): HarnessTool;
+    run(subagent: Subagent, parent: Session, context: RunContext, parentRunId: string, task: string): Promise<SubagentResult>;
+}