@particle-academy/prism-harness 0.0.0

package/dist/session.js

@@ -0,0 +1,198 @@
+import { createHash } from 'node:crypto';
+import { isJsonObject } from './json.js';
+import { StoreTaskSource } from './store-task-source.js';
+import { Thread } from './thread.js';
+/**
+ * One participant's live runtime, reconstructed per turn.
+ *
+ * RESOLVED, NEVER HELD. Nothing survives in memory between turns, so a fresh
+ * worker resolving the same address has to see the same active mode, the same
+ * model and the same conversation as whatever set them. Everything here reads
+ * through a store for that reason, rather than being a property that happens to
+ * be populated.
+ *
+ * State is split deliberately:
+ *
+ *  - mode, model, provider and run bookkeeping are EPHEMERAL. Lose them and the
+ *    next turn falls back to a default, which is a shrug.
+ *  - the thread and stored capabilities are DURABLE.
+ */
+export class Session {
+    scope;
+    participant;
+    #ephemeral;
+    #durable;
+    #ttlSeconds;
+    #cachedState = null;
+    constructor(options) {
+        this.participant = options.participant;
+        this.scope = options.scope;
+        this.#ephemeral = options.ephemeral;
+        this.#durable = options.durable;
+        this.#ttlSeconds = options.ttlSeconds ?? null;
+    }
+    /**
+     * The address this session is resolved by.
+     *
+     * Participant AND scope, because one participant holds several unrelated
+     * conversations at once and they must not collide.
+     *
+     * The type is HASHED rather than interpolated, and with sha1 truncated to 12
+     * characters — byte for byte what the PHP reference produces. A class name
+     * contains backslashes there, which make for awkward store keys and leak the
+     * application's namespace layout into something visible in tooling. Matching
+     * the reference exactly is what lets a PHP app and a TypeScript agent share
+     * ONE store and resolve the same session.
+     */
+    key() {
+        const digest = createHash('sha1').update(this.participant.type).digest('hex').slice(0, 12);
+        return `session:${digest}:${String(this.participant.id)}:${this.scope}`;
+    }
+    // -- ephemeral half --------------------------------------------------------
+    async mode() {
+        return this.#readString('mode');
+    }
+    async usingMode(mode) {
+        return this.#write('mode', mode);
+    }
+    async model() {
+        return this.#readString('model');
+    }
+    async usingModel(model) {
+        return this.#write('model', model);
+    }
+    async provider() {
+        return this.#readString('provider');
+    }
+    async usingProvider(provider) {
+        return this.#write('provider', provider);
+    }
+    async state() {
+        this.#cachedState ??= (await this.#ephemeral.get(this.#ephemeralKey())) ?? {};
+        return this.#cachedState;
+    }
+    /** Drop the ephemeral half. THE CONVERSATION IS UNTOUCHED. */
+    async forget() {
+        await this.#ephemeral.forget(this.#ephemeralKey());
+        this.#cachedState = null;
+        return this;
+    }
+    // -- durable half ----------------------------------------------------------
+    /** The stored conversation this session is bound to. */
+    thread() {
+        return new Thread(this.#durable, `${this.key()}:thread`);
+    }
+    /**
+     * The agent task list this session is bound to.
+     *
+     * The DURABLE half, alongside the thread, for the same reason: a
+     * half-finished task list that vanishes on a deploy is indistinguishable from
+     * a finished one. A volatile durable slot has already been refused by the
+     * store manager before this can be reached, and `StoreTaskSource` refuses one
+     * again on its own -- the second check is what makes a source built directly
+     * against a store as safe as one reached through here.
+     */
+    tasks(options = {}) {
+        return new StoreTaskSource(this.#durable, `${this.key()}:tasks`, options);
+    }
+    async capability(name) {
+        const stored = (await this.#durable.get(this.#durableKey())) ?? {};
+        const capabilities = isJsonObject(stored.capabilities) ? stored.capabilities : {};
+        const capability = capabilities[name];
+        return isJsonObject(capability) ? capability : null;
+    }
+    async usingCapability(name, state) {
+        return this.#writeCapabilities((capabilities) => ({ ...capabilities, [name]: state }));
+    }
+    async forgetCapability(name) {
+        return this.#writeCapabilities(({ [name]: _dropped, ...rest }) => rest);
+    }
+    // -- runs ------------------------------------------------------------------
+    async run() {
+        const run = (await this.state()).run;
+        return isJsonObject(run) && typeof run.id === 'string' ? run : null;
+    }
+    async beginRun(id, mode, provider, model) {
+        return this.#write('run', {
+            id,
+            status: 'running',
+            mode,
+            provider,
+            model,
+            started_at: new Date().toISOString(),
+        });
+    }
+    /**
+     * @param toolCalls the NAMES of the tools this run invoked, in order.
+     *
+     * NAMES ONLY, and that boundary is deliberate. "Which tools did this run
+     * reach for" is what an operator needs to audit a guardrail, and a tool name
+     * is not PII. ARGUMENTS are — `prism-opentelemetry` already carries them
+     * behind an opt-in capture gate with a length cap, and recording them a
+     * second time here, ungated, would quietly undo that decision for everyone
+     * who installed both.
+     */
+    async completeRun(id, finishReason, toolCalls = []) {
+        return this.#finishRun(id, 'completed', {
+            finish_reason: finishReason,
+            tool_calls: [...toolCalls],
+        });
+    }
+    async failRun(id, failure) {
+        return this.#finishRun(id, 'failed', { failure });
+    }
+    /**
+     * Run something that MUST NOT HAPPEN TWICE.
+     *
+     * Two workers can hold the same session at the same moment: a queued job
+     * finishing a run while the user sends another message is ordinary. Advance a
+     * run inside this, not outside it.
+     */
+    async lock(callback, ttlSeconds = 10, waitSeconds = 5) {
+        return this.#ephemeral.withLock(this.key(), async () => {
+            // Re-read inside the lock. State written by whoever held it before us
+            // is otherwise invisible to this instance, and acting on a stale read
+            // is the thing the lock exists to prevent.
+            this.#cachedState = null;
+            return callback(this);
+        }, ttlSeconds, waitSeconds);
+    }
+    // -- internals -------------------------------------------------------------
+    #ephemeralKey() {
+        return `${this.key()}:ephemeral`;
+    }
+    #durableKey() {
+        return `${this.key()}:durable`;
+    }
+    async #readString(key) {
+        const value = (await this.state())[key];
+        return typeof value === 'string' ? value : null;
+    }
+    async #write(key, value) {
+        const state = { ...(await this.state()), [key]: value };
+        await this.#ephemeral.put(this.#ephemeralKey(), state, this.#ttlSeconds);
+        this.#cachedState = state;
+        return this;
+    }
+    async #writeCapabilities(mutate) {
+        const stored = (await this.#durable.get(this.#durableKey())) ?? {};
+        const capabilities = isJsonObject(stored.capabilities) ? stored.capabilities : {};
+        await this.#durable.put(this.#durableKey(), { ...stored, capabilities: mutate(capabilities) });
+        return this;
+    }
+    async #finishRun(id, status, extra) {
+        const current = await this.run();
+        // A run that is not the one in flight does not overwrite it. A late worker
+        // reporting on a superseded run would otherwise mark the live one finished.
+        if (current !== null && current.id !== id) {
+            return this;
+        }
+        return this.#write('run', {
+            ...(current ?? { id }),
+            id,
+            status,
+            finished_at: new Date().toISOString(),
+            ...extra,
+        });
+    }
+}

package/dist/skills.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Skills a mode can load into its system prompt, read from disk.
+ *
+ * ## The read is GUARDED, and that is the whole of it
+ *
+ * A skill name and a path both arrive from configuration or, worse, from a
+ * model that was told it may fetch a referenced file. Reading either without
+ * checking is a path traversal with extra steps, and the file it would reach is
+ * on the machine running the agent.
+ *
+ * Three checks, in this order, each closing something the others do not:
+ *
+ *  1. the NAME matches a strict pattern — this is what stops `../` in the
+ *     name itself, before it is ever joined to anything;
+ *  2. the relative PATH is rejected lexically if it is absolute or contains a
+ *     `..` segment;
+ *  3. the resolved REAL path must still sit inside the skill's own real root,
+ *     which is what catches a symlink pointing out of it — the one thing the
+ *     first two checks cannot see.
+ *
+ * The third is not redundant. A lexically innocent `notes/link.md` that is a
+ * symlink to `/etc/passwd` passes both earlier checks.
+ */
+export declare class SkillRegistry {
+    #private;
+    constructor(root: string);
+    /**
+     * The system prompt with each named skill appended as a tagged section.
+     *
+     * Returns the prompt UNCHANGED when no skills are named, rather than
+     * appending an empty preamble that would tell the model skills are available
+     * when none are.
+     */
+    augmentPrompt(systemPrompt: string, names: readonly string[]): string;
+    /** Read one file from inside a skill. See the class docblock for the guard. */
+    read(name: string, path: string): string;
+}

package/dist/skills.js

@@ -0,0 +1,73 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { HarnessError } from './errors.js';
+const SKILL_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+const TRAVERSAL = /(^|\/)\.\.(\/|$)/;
+/**
+ * Skills a mode can load into its system prompt, read from disk.
+ *
+ * ## The read is GUARDED, and that is the whole of it
+ *
+ * A skill name and a path both arrive from configuration or, worse, from a
+ * model that was told it may fetch a referenced file. Reading either without
+ * checking is a path traversal with extra steps, and the file it would reach is
+ * on the machine running the agent.
+ *
+ * Three checks, in this order, each closing something the others do not:
+ *
+ *  1. the NAME matches a strict pattern — this is what stops `../` in the
+ *     name itself, before it is ever joined to anything;
+ *  2. the relative PATH is rejected lexically if it is absolute or contains a
+ *     `..` segment;
+ *  3. the resolved REAL path must still sit inside the skill's own real root,
+ *     which is what catches a symlink pointing out of it — the one thing the
+ *     first two checks cannot see.
+ *
+ * The third is not redundant. A lexically innocent `notes/link.md` that is a
+ * symlink to `/etc/passwd` passes both earlier checks.
+ */
+export class SkillRegistry {
+    #root;
+    constructor(root) {
+        this.#root = resolve(root);
+    }
+    /**
+     * The system prompt with each named skill appended as a tagged section.
+     *
+     * Returns the prompt UNCHANGED when no skills are named, rather than
+     * appending an empty preamble that would tell the model skills are available
+     * when none are.
+     */
+    augmentPrompt(systemPrompt, names) {
+        const sections = names.map((name) => `<skill name="${name}">\n${this.read(name, 'SKILL.md')}\n</skill>`);
+        if (sections.length === 0) {
+            return systemPrompt;
+        }
+        return `${systemPrompt}\n\nThe following Harness-owned skills are available. Follow their routing instructions and use skill_read for referenced files. Do not copy skill files into the project workspace.\n\n${sections.join('\n\n')}`.trim();
+    }
+    /** Read one file from inside a skill. See the class docblock for the guard. */
+    read(name, path) {
+        if (!SKILL_NAME.test(name)) {
+            throw HarnessError.skillPathRefused(`the skill name [${name}] is not a valid name`);
+        }
+        const relative = path.replaceAll('\\', '/').trim();
+        if (relative === '' || relative.startsWith('/') || TRAVERSAL.test(relative)) {
+            throw HarnessError.skillPathRefused(`[${path}] must stay inside the skill`);
+        }
+        let skillRoot;
+        let file;
+        try {
+            skillRoot = realpathSync.native(join(this.#root, name));
+            file = realpathSync.native(join(this.#root, name, ...relative.split('/')));
+        }
+        catch {
+            throw HarnessError.skillPathRefused(`[${name}/${relative}] was not found`);
+        }
+        // The check the lexical ones cannot make: a symlink inside the skill that
+        // points out of it is lexically innocent and resolves elsewhere.
+        if (!file.startsWith(skillRoot + sep) || !statSync(file).isFile()) {
+            throw HarnessError.skillPathRefused(`[${name}/${relative}] resolves outside the skill`);
+        }
+        return readFileSync(file, 'utf8');
+    }
+}

package/dist/store-task-source.d.ts

@@ -0,0 +1,169 @@
+import type { Durability, SessionStore } from './stores/session-store.js';
+import type { RunBudget, RunLedger } from './subagents.js';
+import type { AgentTask, AgentTaskRecord, AgentTaskSource, LeasedAgentTask, TaskOutcome, TaskState } from './tasks.js';
+/** Integer Unix seconds. Injectable so a lease can be expired in a test without waiting for one. */
+export type Clock = () => number;
+export interface StoreTaskSourceOptions {
+    /** Defaults to the system clock, truncated to whole seconds. */
+    now?: Clock;
+}
+/**
+ * A task whose state was read at a point in time.
+ *
+ * A SNAPSHOT, and it has to be: `AgentTask.state()` is synchronous, and the
+ * only honest way to make it live would be to hit the store, which cannot be
+ * done without returning a promise. Ask `StoreTaskSource.find()` for a fresh
+ * read; do not treat a task object held across an await as current.
+ */
+export declare class StoredAgentTask implements LeasedAgentTask {
+    #private;
+    constructor(record: AgentTaskRecord);
+    id(): string;
+    instruction(): string;
+    state(): TaskState;
+    claimedBy(): string | null;
+    claimedUntil(): number | null;
+    toRecord(): AgentTaskRecord;
+}
+/**
+ * The default task source: the list lives in the harness's own durable store.
+ *
+ * No schema, no migration, works on install. A consumer with an existing table
+ * adapts it instead (`asAgentTask` / `withAgentTask`); both satisfy one
+ * contract, and neither is the afterthought.
+ *
+ * ## Durable or nothing
+ *
+ * REFUSED AT CONSTRUCTION against a store that reports itself volatile. The
+ * package already draws this line for the durable slot and this inherits the
+ * rule rather than restating it: a half-finished task list that vanishes on a
+ * deploy is indistinguishable from a finished one, so losing it is a
+ * correctness failure and not a degradation to a default.
+ *
+ * ## The claim is one operation
+ *
+ * `claim()` does the whole read-expire-select-write inside ONE store lock.
+ * Reading the next task and then marking it taken is two operations with a
+ * window between them, and two workers arriving in that window both get the
+ * same task. That race is the reason this class exists, so the lock wraps
+ * everything rather than just the write.
+ *
+ * **The guarantee is the STORE'S, not this class's.** "Never the same task
+ * twice" holds exactly as far as `SessionStore.withLock` does:
+ * `MemorySessionStore`'s lock is process-local and `FileSessionStore`'s is one
+ * machine. Two workers on different machines over a network filesystem are not
+ * excluded by either, and no file lock can promise that -- point the durable
+ * slot at a database or Redis there. Saying so is the point: a claim that looks
+ * atomic and is not would hand the same expensive task to two agents.
+ *
+ * ## Size
+ *
+ * The whole list is one stored value, read and rewritten on every claim. That
+ * is right for the tens-of-tasks a bounded agent run produces and wrong for
+ * thousands: a consumer with a real backlog wants their own table and the
+ * application-model adapter, which is why that adapter is a first-class shape
+ * rather than an afterthought.
+ *
+ * ## Ordering
+ *
+ * Tasks are held in an array and `claim()` takes the first claimable one, so
+ * the order out is the order in. Nothing here sorts, prioritises or shuffles.
+ * Ordering is the divergence nothing reports: the agent just does the work in a
+ * different sequence and produces a different result.
+ */
+export declare class StoreTaskSource implements AgentTaskSource {
+    #private;
+    constructor(store: SessionStore, key: string, options?: StoreTaskSourceOptions);
+    /** What the underlying store says about itself. Always `durable` -- see the constructor. */
+    durability(): Durability;
+    /**
+     * Append a task, in `todo`.
+     *
+     * The id may be supplied -- a consumer seeding a list from their own domain
+     * keys wants their keys -- and is generated as `t-<n>` when it is not. A
+     * supplied id that is already in the list is REFUSED rather than merged: two
+     * units of work sharing an id would share a claim.
+     *
+     * An id of `""` is refused too, compared against the empty string EXACTLY.
+     * Nothing is trimmed first, in any of the three languages: `trim`, `strip`
+     * and `String.prototype.trim` each strip a different set of codepoints, so a
+     * trim here would give three different answers to the same input. A single
+     * space is a legal id, and that is the correct behaviour.
+     */
+    add(instruction: string, id?: string): Promise<StoredAgentTask>;
+    /** Append several tasks at once, in the order given, with generated ids. */
+    addMany(instructions: readonly string[]): Promise<StoredAgentTask[]>;
+    /**
+     * Take the next claimable task, atomically, or null when there is none.
+     *
+     * The claim is WRITTEN BEFORE this returns, which is the point: the caller
+     * cannot begin work until the store says the task is theirs, so a worker that
+     * dies mid-task leaves a `claimed` row with an expiry rather than a `todo`
+     * row that looks like it was never attempted.
+     */
+    claim(worker: string, leaseSeconds?: number): Promise<StoredAgentTask | null>;
+    /**
+     * Record what happened, as the worker HOLDING the task. Both outcomes are TERMINAL.
+     *
+     * Refuses a task that is already terminal rather than ignoring it: two
+     * callers believing they own one outcome is worth reporting, and the second
+     * write silently winning would leave nothing recording the disagreement.
+     *
+     * Refuses a task this worker is not holding -- nobody holding it, someone
+     * else holding it, or a lease that has since expired all reach the same
+     * refusal, because they have the same answer. The state machine has no edge
+     * from `todo` to `done`, and a lease that expired mid-flight has already put
+     * the task back where anyone can take it, so the worker that finally finished
+     * may no longer be the one whose result counts.
+     *
+     * And refuses an OUTCOME that is not one of the two, BEFORE anything else --
+     * see `assertOutcome`, and the ordering note there.
+     */
+    release(task: AgentTask, worker: string, outcome: TaskOutcome): Promise<void>;
+    /**
+     * How many tasks a `claim()` could still hand out.
+     *
+     * Counts `todo` AND any `claimed` task whose lease has run out, because an
+     * expired lease is claimable by anyone -- a loop that stopped while such a
+     * task sat there would stop with work left.
+     *
+     * Reads without taking the lock. A store `get` is a single atomic read of one
+     * key, so the count is consistent with some moment; taking the lock would
+     * make it consistent with a moment that has already passed by the time the
+     * caller reads it.
+     */
+    pending(): Promise<number>;
+    /** A fresh read of one task, with any expired lease already applied, or null. */
+    find(id: string): Promise<StoredAgentTask | null>;
+    /**
+     * Push this worker's lease out, and ONLY while it still holds it.
+     *
+     * Bounded by the RUN, which is the whole argument. Unbounded self-extension
+     * is how a wedged worker holds a task forever, and a second timeout invented
+     * here would be one limit spelled two ways across an ecosystem -- which is
+     * how a limit ends up set in the place that is not enforced. The `RunBudget`
+     * is already the stop condition, so extension stops when the run's own
+     * allowance does. Nothing new to enforce and nothing new to forget.
+     *
+     * TWO checks, not one. `exhaustion()` refuses outright -- cancelled, out of
+     * steps, out of money or out of time -- and `remainingSeconds()` then bounds
+     * how much is granted. Reading the spec's "remaining wall-clock budget"
+     * literally and checking only the second left a cancelled run able to keep
+     * extending; the reference settled it the other way.
+     *
+     * Granted seconds are `min(requested, remaining)`. A budget with no
+     * wall-clock cap (`maxSeconds` null) grants what was asked, matching
+     * `RunLedger.exhaustion()`, which also has nothing to enforce in that case.
+     *
+     * The new expiry is `now + granted` EVEN WHEN THAT SHORTENS the lease. A
+     * first draft here took the later of the two, on the reasoning that a call
+     * named "extend" should never take time away. That is the wrong reasoning:
+     * the granted figure is what the RUN can still afford, so keeping a longer
+     * lease would hold a task past the budget that is supposed to bound it, and
+     * it would also make the result depend on the order calls happened to arrive
+     * in. One rule, one answer.
+     *
+     * @returns the new expiry, an integer Unix timestamp.
+     */
+    extendLease(task: AgentTask, worker: string, seconds: number, ledger: RunLedger, budget: RunBudget): Promise<number>;
+}