@particle-academy/prism-harness 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# Prism Harness for TypeScript
+
+Durable agent sessions — threads, session state and store drivers. The
+TypeScript port of [`particle-academy/prism-harness`](https://github.com/Particle-Academy/prism-harness).
+
+Zero runtime dependencies. Node 20+.
+
+This package is private while coordinated parity work is in progress.
+
+```ts
+import { FileSessionStore, MemorySessionStore, PrismHarness } from '@particle-academy/prism-harness';
+
+const harness = new PrismHarness({
+  drivers: {
+    memory: () => new MemorySessionStore(),
+    files: () => new FileSessionStore('./storage/harness'),
+  },
+  stores: { ephemeral: 'memory', durable: 'files' },
+});
+
+const session = harness.for({ type: 'User', id: 7 }).session('support');
+
+await session.usingMode('plan').then((s) => s.usingModel('claude-sonnet-4-5'));
+
+await session.lock(async (live) => {
+  // whatever must not happen twice
+  await live.beginRun('run-1', 'plan', 'anthropic', 'claude-sonnet-4-5');
+});
+```
+
+## Resolved, never held
+
+A server handles a request and moves on, so a session cannot be an object kept
+in memory the way a single-process agent's is. Every call rebuilds one from a
+store, which is what makes a fresh worker see the same mode, model and
+conversation as the request that set them.
+
+## The two halves
+
+State is split into named slots, because the halves have genuinely different
+requirements:
+
+| Slot | Holds | Losing it means |
+|---|---|---|
+| `ephemeral` | active mode, selected model, run bookkeeping | falls back to a default |
+| `durable` | threads, stored capabilities, agent task lists | work is gone |
+
+**A store that reports itself volatile is REFUSED for the durable slot**, at the
+moment a session is opened. That is the guard the package exists for: a cache is
+disposable by definition, and the durable slot holds approvals a human has not
+answered yet. Accepting it and finding out later is exactly the failure this
+package was written to avoid.
+
+Construct a `PrismHarness` with no drivers and it works — and then refuses
+durable state, loudly, with a message that names the fix. That is deliberate. A
+package that silently accepted an in-memory durable store would pass every test
+on one process and lose a half-executed action the first time it ran on two.
+
+## The same address as PHP
+
+`Session.key()` is byte for byte what the reference builds: `session:` plus the
+sha1 of the participant type truncated to 12, the participant id, and the scope.
+Matching exactly is what lets a PHP app and a TypeScript agent **share one store
+and resolve the same session**. A different digest would give two conversations
+that look identical and never meet.
+
+## Threads
+
+`record()` assigns positions inside the store lock, reading the current length
+and writing the new messages as one operation. Two turns landing concurrently
+would otherwise both read position 4 and both write position 5, silently losing
+a message — the race the reference tracks as prism-harness#2.
+
+## Agent task lists
+
+An agent given a goal has to keep working across many requests. It needs a list
+of what remains, and that list has to survive the request, the worker, a crash
+and a deploy.
+
+```ts
+const tasks = session.tasks();
+
+await tasks.addMany(['read the issue', 'write the patch', 'run the gates']);
+
+const task = await tasks.claim('worker-1');   // ONE atomic call
+
+if (task !== null) {
+  // …do the work…
+  await tasks.release(task, 'worker-1', 'done');
+}
+
+await tasks.pending();   // a COUNT, which is what a loop needs to stop
+```
+
+There is **no task model, no schema and no migration**. Two contracts and
+adapters: `AgentTaskSource` is where tasks come from — `claim`, `release`,
+`pending`, `find` — and `AgentTask` is one unit of work. `find()` is on the
+contract because `release()` takes a task while every external caller holds
+only an id: a tool call carries `{"id": "t-1"}` and an HTTP route has
+`/tasks/t-1`.
+
+`StoreTaskSource` is the default, backed by the durable slot; a consumer with an
+existing table wraps their own record with `asAgentTask()` or mixes
+`withAgentTask()` into their class. Both satisfy one contract.
+
+Four states — `todo`, `claimed`, `done`, `failed` — and the transitions are
+pinned across all three languages:
+
+| | |
+|---|---|
+| `claim()` is one call | Read-then-mark is two operations with a window between them, and two workers arriving in that window get the same task. |
+| A claim carries an owner AND an expiry | Five minutes by default. An expired claim returns the task to **`todo`**, never to `failed`: a worker dying is not the task failing, and conflating them burns a retry that never ran. |
+| `claimed` is written before the work begins | So "started and died" is distinguishable from "never started". |
+| `done` and `failed` are terminal | Re-releasing one is an error, not a silent no-op. |
+| A worker may extend its own lease | Only while it still holds it, and bounded by the RUN. `RunLedger.exhaustion()` refuses outright — cancelled, out of steps, out of money or out of time — and `remainingSeconds()` bounds what is granted. There is no second timeout to set, or to forget to set. The new expiry is `now + granted` even when that shortens the lease: the grant is what the run can still afford. |
+| A lease must be whole positive seconds | Zero or less is refused rather than clamped, and a fraction is refused rather than truncated — both are a value quietly becoming a different value, and `claimed_until` is an integer timestamp so a fractional lease could never have been honoured anyway. The check is `Number.isInteger`, which also refuses `NaN`, the infinities, and the string a JSON config would have delivered past the type annotation. |
+| `release()` names the worker | Not in the spec's sketch, and added because without it a completion tool can close any task in the list — including one another worker is midway through. A release by anyone but the holder is refused, and the refusal does not say who the holder is. |
+
+**A volatile store is refused**, the same way the durable slot is. A
+half-finished task list that vanishes on a deploy is indistinguishable from a
+finished one.
+
+**An empty worker id or task id is refused, and nothing is trimmed first.**
+`trim`, `strip` and `String.prototype.trim` each strip a different set of
+codepoints, so trimming would have three ports disagreeing about whether the
+same id is blank. A single space is a legal id. That is the `prism-human-plus`
+G-36 lesson applied before it costs anything.
+
+**An agent cannot mark its own task complete.** `release()` is the
+application's call, made from evidence. A consumer who wants the agent to close
+its own tasks builds `agentCompletionTool()` and authorizes it through the
+existing `ToolAuthorizer` — which must be enabled, because an authorizer that is
+off allows every call and would grant the authority while reading as a control.
+If the model can declare its own work done, "run until the goal is met" becomes
+"run until it decides it is met", and a run that has stalled ends by declaring
+victory.
+
+That tool **requires an explicit `outcome`** of `done` or `failed`. Anything
+else — `"complete"`, `null`, or a missing argument — is refused rather than
+guessed at, because `outcome` is the one value the model supplies and it decides
+a terminal state. Guessing would let a malformed call produce the more
+privileged result.
+
+It also **checks the holder itself** rather than trusting the source to. It is
+typed to the `AgentTaskSource` contract, and an interface cannot make an
+implementation check anything — `release(task, worker, outcome)` reads like
+"find it and set the state", which is what a third party will write. A task
+whose holder cannot be established at all is refused too: `AgentTask` is three
+methods, so a conforming source may expose no holder, and reading that silence
+as permission is the same mistake as inferring `done` from a missing outcome.
+
+Stopping is the existing `RunBudget` — cost, turns and wall-clock. Dependency
+ordering is not here: drive [`fancy-flow`](https://github.com/Particle-Academy/fancy-flow)
+for that. A task list that grows a scheduler has rebuilt a workflow engine
+badly.
+
+## Drivers
+
+- **`MemorySessionStore`** — volatile, and says so. Right for the ephemeral slot
+  in a test or a single-process tool. Its lock is real but process-local.
+- **`FileSessionStore`** — durable. Atomic writes (write-then-rename) and a
+  cross-process lock built on exclusive file creation, which is the one
+  primitive that is atomic on every filesystem worth supporting. Two workers on
+  one machine genuinely exclude each other; two machines over a network
+  filesystem do not, and no file lock can promise that — use a database there.
+
+  Its **lockfile format is shared with the PHP and Python ports**, because a
+  worker in any of the three may be pointed at one store directory: the expiry
+  in milliseconds, then a newline, written in a single write. The terminator is
+  load-bearing. Without it there is nothing to tell a complete expiry from the
+  first half of one, and every prefix of a timestamp is a smaller, *older*
+  timestamp — so a torn write reads as a lock that expired decades ago and gets
+  deleted out from under the worker holding it. Anything unterminated is treated
+  as held, bounded by the file's own age so a process that died mid-write cannot
+  wedge the key either.
+
+Implement `SessionStore` for anything else. Declare your own `durability()`:
+only you know whether your Redis is persistent or a disposable cache, and that
+declaration is an assertion about your infrastructure, not a preference.

package/dist/doctor.d.ts

@@ -0,0 +1,35 @@
+import type { ModeRegistry } from './modes.js';
+import type { SessionStoreManager } from './stores/store-manager.js';
+import type { ToolRegistry } from './tools.js';
+import type { ToolAuthorizer } from './tools.js';
+export interface DoctorFinding {
+    check: string;
+    ok: boolean;
+    detail: string;
+}
+export interface DoctorReport {
+    findings: readonly DoctorFinding[];
+    problems: number;
+    ok: boolean;
+    summary(): string;
+}
+export interface DoctorSubjects {
+    modes?: ModeRegistry;
+    tools?: ToolRegistry;
+    stores?: SessionStoreManager;
+    authorizer?: ToolAuthorizer;
+}
+/**
+ * Check the harness configuration BEFORE a run does it for you.
+ *
+ * Every check here corresponds to a failure this package already refuses at
+ * runtime. Those refusals are correct and they are also LATE: a mode nobody has
+ * entered yet keeps its broken subagent reference until someone switches to it,
+ * and the first person to find out is a user mid-conversation.
+ *
+ * So this resolves EVERY mode rather than the default one, and reports what a
+ * run would have thrown. A CLI is left to the consumer — this returns the
+ * report as data, which is also what makes it testable and what lets a health
+ * endpoint serve it.
+ */
+export declare function diagnose(subjects: DoctorSubjects): DoctorReport;

package/dist/doctor.js

@@ -0,0 +1,110 @@
+/**
+ * Check the harness configuration BEFORE a run does it for you.
+ *
+ * Every check here corresponds to a failure this package already refuses at
+ * runtime. Those refusals are correct and they are also LATE: a mode nobody has
+ * entered yet keeps its broken subagent reference until someone switches to it,
+ * and the first person to find out is a user mid-conversation.
+ *
+ * So this resolves EVERY mode rather than the default one, and reports what a
+ * run would have thrown. A CLI is left to the consumer — this returns the
+ * report as data, which is also what makes it testable and what lets a health
+ * endpoint serve it.
+ */
+export function diagnose(subjects) {
+    const findings = [];
+    if (subjects.stores !== undefined) {
+        findings.push(checkStores(subjects.stores));
+    }
+    if (subjects.authorizer !== undefined) {
+        findings.push({
+            check: 'authorizer',
+            ok: true,
+            detail: subjects.authorizer.enabled
+                ? 'enabled — tools are filtered per run and per call'
+                : 'DISABLED — every registered tool is offered to every run',
+        });
+    }
+    if (subjects.modes !== undefined) {
+        findings.push(...checkModes(subjects.modes, subjects.tools));
+    }
+    const problems = findings.filter((finding) => !finding.ok).length;
+    return {
+        findings,
+        problems,
+        ok: problems === 0,
+        summary() {
+            const lines = findings.map((finding) => `  ${finding.ok ? 'ok  ' : 'FAIL'} ${finding.check}: ${finding.detail}`);
+            lines.unshift(problems === 0
+                ? 'Harness configuration is consistent.'
+                : `${problems} problem(s) found in the harness configuration.`);
+            return lines.join('\n');
+        },
+    };
+}
+function checkStores(stores) {
+    try {
+        const durable = stores.durable();
+        stores.ephemeral();
+        return { check: 'stores', ok: true, detail: `durable slot is ${durable.durability()}` };
+    }
+    catch (error) {
+        return { check: 'stores', ok: false, detail: message(error) };
+    }
+}
+/**
+ * Resolve EVERY mode, and check the tools each one names.
+ *
+ * A mode listing a tool the registry cannot produce fails only when a run
+ * reaches for it — which is to say, in front of whoever is talking to the
+ * agent. Checked here against the registry's static names; a tool that only a
+ * provider can supply needs a session, so its absence is reported as unknown
+ * rather than missing.
+ */
+function checkModes(modes, tools) {
+    const findings = [];
+    const names = modes.names();
+    if (names.length === 0) {
+        return [{ check: 'modes', ok: false, detail: 'no modes are configured' }];
+    }
+    const known = new Set(tools?.names() ?? []);
+    for (const name of names) {
+        try {
+            const mode = modes.resolve(name);
+            const detail = [
+                `${mode.tools.length} tool(s)`,
+                `${mode.maxSteps} step(s)`,
+                `${Object.keys(mode.subagents).length} subagent(s)`,
+            ];
+            if (mode.requiresApproval.length > 0) {
+                detail.push(`approval: ${mode.requiresApproval.join(', ')}`);
+            }
+            const missing = tools === undefined || mode.tools.includes('*')
+                ? []
+                : mode.tools.filter((tool) => !known.has(tool));
+            findings.push(missing.length > 0
+                ? {
+                    check: `mode:${name}`,
+                    ok: false,
+                    detail: `names ${missing.length} tool(s) the registry cannot produce: ${missing.join(', ')}`,
+                }
+                : { check: `mode:${name}`, ok: true, detail: detail.join(', ') });
+        }
+        catch (error) {
+            findings.push({ check: `mode:${name}`, ok: false, detail: message(error) });
+        }
+    }
+    // The default has to resolve, or every session that does not name a mode
+    // fails — and that is the ordinary path, not an edge.
+    try {
+        modes.resolve(null);
+        findings.push({ check: 'default mode', ok: true, detail: modes.default() });
+    }
+    catch (error) {
+        findings.push({ check: 'default mode', ok: false, detail: message(error) });
+    }
+    return findings;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/errors.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Failures carry a stable CODE.
+ *
+ * The PHP reference identifies a failure by its exception class and an English
+ * sentence. A class name does not survive a port and a sentence is not a
+ * contract, so the code is what a consumer branches on here: treat
+ * `HarnessError.code` as stable and `HarnessError.message` as free to change in
+ * any release. Same decision, and the same reasoning, as `prism-ts`.
+ */
+export type HarnessErrorCode = 
+/** A lock on a session key could not be acquired before the wait expired. */
+'session_locked'
+/** A store that reports itself volatile was configured for durable state. */
+ | 'unsafe_state_configuration'
+/** A store slot names a driver nothing is registered under. */
+ | 'unknown_store_driver'
+/** A tool was asked for that this session cannot reach. */
+ | 'tool_not_available'
+/** A run was refused — by budget, by depth, or by a cancelled ledger. */
+ | 'run_not_permitted'
+/** A stored payload could not be mapped back into a value object. */
+ | 'unmappable_content'
+/** A session was asked to do something that needs a runtime it does not have. */
+ | 'no_agent_runtime'
+/** A mode was asked for that the application has not configured. */
+ | 'mode_not_configured'
+/** A configured mode is malformed, or names something that does not exist. */
+ | 'mode_malformed'
+/** A tool policy is defined but the authorizer that would consult it is off. */
+ | 'unsafe_authorization_configuration'
+/** A tool call was refused by the call-time policy. */
+ | 'call_not_authorized'
+/** A skill file was asked for that would resolve outside its own skill. */
+ | 'skill_path_refused'
+/** A task was added under an id the source already holds. */
+ | 'duplicate_task_id'
+/** A worker id or a task id was the empty string. */
+ | 'task_identifier_blank'
+/** A lease or extension that was not a whole positive number of seconds. */
+ | 'task_lease_invalid'
+/** A task id was named that its source does not hold. */
+ | 'task_not_found'
+/** A task that is already `done` or `failed` was released again. */
+ | 'task_already_terminal'
+/**
+ * A worker acted on a task it is not holding.
+ *
+ * ONE code for every shape of "not yours": nobody holds it, someone else
+ * does, or your own lease has expired. Decision 0020 would rather see those
+ * split, and the first draft here did split them -- but decision 0004 pins
+ * codes ACROSS LANGUAGES, and the Python port settled on one. A consumer
+ * branching on a code that exists in one port and not another is worse than a
+ * coarse code that means the same thing everywhere. The sentence still says
+ * which case it was.
+ */
+ | 'task_lease_not_held'
+/**
+ * A completion tool was called with an outcome that is not `done` or `failed`.
+ *
+ * NOT in the set the Python port settled, and raised rather than dropped --
+ * see `taskOutcomeInvalid` for why coercing instead is a security defect.
+ */
+ | 'task_outcome_invalid';
+export interface HarnessErrorOptions {
+    cause?: unknown;
+}
+export declare class HarnessError extends Error {
+    readonly code: HarnessErrorCode;
+    constructor(code: HarnessErrorCode, message: string, options?: HarnessErrorOptions);
+    static sessionLocked(key: string, waitSeconds: number): HarnessError;
+    /**
+     * The guard this package exists for.
+     *
+     * A cache is disposable by definition, and the durable slot holds pending
+     * tool approvals — a half-executed action waiting on a human. Losing one is a
+     * correctness failure, not a cache miss, so a store that reports itself
+     * volatile is refused here rather than accepted and discovered later.
+     */
+    static volatileDurableStore(slot: string, driver: string): HarnessError;
+    static unknownStoreDriver(slot: string, driver: string): HarnessError;
+    static toolNotAvailable(name: string, available: readonly string[]): HarnessError;
+    static runNotPermitted(reason: string): HarnessError;
+    static unmappableContent(description: string, options?: HarnessErrorOptions): HarnessError;
+    static modeNotConfigured(name: string): HarnessError;
+    static modeMalformed(name: string, detail: string): HarnessError;
+    /**
+     * Both at once is the one configuration not to leave in place.
+     *
+     * A defined policy that is never consulted looks like a control to every
+     * reader and is not one -- every registered tool is offered to every run
+     * while the code says otherwise.
+     */
+    static policyDefinedButDisabled(): HarnessError;
+    /**
+     * Thrown rather than returned as a tool result.
+     *
+     * A refusal handed back as a result reads to the model as a failure it might
+     * retry differently, and a denied action being retried is the opposite of
+     * what a guard is for.
+     */
+    static callNotAuthorized(tool: string): HarnessError;
+    /**
+     * A skill name or path that would leave the skill directory.
+     *
+     * Refused rather than sanitised. Silently rewriting a traversal to something
+     * safe teaches a caller — or a model — that the request was fine.
+     */
+    static skillPathRefused(detail: string): HarnessError;
+    /**
+     * A task list pointed at a store whose contents can vanish.
+     *
+     * The SAME code as `volatileDurableStore`, deliberately. It is the same
+     * misconfiguration reaching the same conclusion, and a consumer branching on
+     * "durable state was pointed somewhere it cannot live" should not have to
+     * know which feature noticed. Prose is free per prism-parity decision 0004;
+     * the code is not.
+     *
+     * A half-finished task list that vanishes on a deploy is indistinguishable
+     * from a finished one, which is why this refuses at construction rather than
+     * degrading to a default.
+     */
+    static volatileTaskSource(): HarnessError;
+    /**
+     * A lease that is not a whole positive number of seconds. REFUSED, not adjusted.
+     *
+     * Both halves were learned the hard way. Zero or less was CLAMPED to one
+     * second at first, because a clamp fails closed; a positive fraction was then
+     * still TRUNCATED. Both are a value quietly becoming a different value, and
+     * this repository has already shipped a configuration that did exactly that
+     * and stayed green throughout. A caller asking for a zero-second or
+     * fractional lease has a bug, and the useful thing to hand back is the bug.
+     *
+     * Takes `unknown` rather than `number` deliberately: the value that reaches
+     * this is whatever actually arrived, including a string out of a JSON config
+     * that the type annotation never saw.
+     */
+    static taskLeaseInvalid(seconds: unknown): HarnessError;
+    static taskNotFound(id: string): HarnessError;
+    static duplicateTaskId(id: string): HarnessError;
+    /**
+     * An empty identifier, compared against `""` EXACTLY.
+     *
+     * DELIBERATELY NOT TRIMMED, in any of the three languages. PHP's `trim`,
+     * JavaScript's `String.prototype.trim` and Python's `str.strip` each strip a
+     * different set of codepoints, so trimming here would produce three different
+     * answers for the same input -- which is precisely how `prism-human-plus`
+     * G-36 happened. A worker id of one space is accepted, and that is the
+     * correct behaviour rather than an oversight.
+     */
+    static taskIdentifierBlank(what: string): HarnessError;
+    /**
+     * An error, never a silent no-op.
+     *
+     * A second `release()` means two things believe they own the outcome of one
+     * task, and swallowing it leaves whichever wrote last as the answer with
+     * nothing recording that they disagreed.
+     */
+    static taskAlreadyTerminal(id: string, state: string): HarnessError;
+    /**
+     * "You are not holding this" -- and NOT WHO IS.
+     *
+     * The holder is deliberately left out of the sentence. This error can be
+     * raised inside a tool call, and a tool's failure comes back to the model as
+     * readable text: naming the other worker would hand an agent the identity of
+     * a peer it has no business knowing, from a refusal. The caller that needs to
+     * know who holds a task can ask the source.
+     *
+     * Covers three situations -- nobody holds it, someone else does, and your own
+     * lease expired -- because all three have the same answer: claim it again.
+     */
+    static taskLeaseNotHeld(id: string, worker: string, detail: string): HarnessError;
+    /**
+     * An outcome that is not `done` or `failed` was named.
+     *
+     * REFUSED, not coerced. The outcome decides a TERMINAL state; mapping
+     * `"complete"`, `"DONE"`, `null` or a MISSING argument onto `done` would mean
+     * a malformed call produces the MORE privileged result -- an agent declaring
+     * victory by typo. Failing closed here costs a retry with a valid value.
+     *
+     * Absent is covered by the same code deliberately. The argument for treating
+     * it as `done` is real -- calling a tool named `complete_task` looks like the
+     * declaration by itself -- and the reference settled against it.
+     *
+     * `where` names the door that refused rather than always a tool, because
+     * there are two: the completion tool a model can call, and
+     * `StoreTaskSource.release()`, which is reachable from any untyped caller.
+     */
+    static taskOutcomeInvalid(where: string, given: unknown): HarnessError;
+    /**
+     * A self-completion tool built against an authorizer that is switched off.
+     *
+     * The same code, and the same argument, as `policyDefinedButDisabled`: a
+     * control that is never consulted reads as a control to every reader and is
+     * not one. An agent closing its own tasks is exactly the authority that must
+     * not be granted by accident.
+     */
+    static completionToolWithoutAuthorizer(name: string): HarnessError;
+    static noAgentRuntime(action: string): HarnessError;
+}