@particle-academy/prism-harness 0.0.0

package/dist/thread.js

@@ -0,0 +1,88 @@
+import { isJsonObject } from './json.js';
+import { HarnessError } from './errors.js';
+/**
+ * The stored conversation a session is bound to.
+ *
+ * DURABLE by construction: it lives in the durable slot, so it is the one thing
+ * here a flushed cache cannot take away. The PHP reference keeps it as Eloquent
+ * rows for the same reason.
+ *
+ * ## Position is assigned inside a lock
+ *
+ * `record()` takes the lock before reading the current length. Two turns
+ * landing concurrently would otherwise both read position 4 and both write
+ * position 5, and the conversation would silently lose a message — the same
+ * race the reference tracks as prism-harness#2. Doing the read and the write
+ * inside one lock is the fix, not a retry afterwards.
+ */
+export class Thread {
+    store;
+    key;
+    constructor(store, key) {
+        this.store = store;
+        this.key = key;
+    }
+    async messages() {
+        const stored = await this.store.get(this.key);
+        if (stored === null)
+            return [];
+        const messages = stored.messages;
+        if (!Array.isArray(messages))
+            return [];
+        return messages.filter(isJsonObject).map((entry) => this.#toMessage(entry));
+    }
+    /** How many messages the thread holds. */
+    async count() {
+        return (await this.messages()).length;
+    }
+    /**
+     * Append messages, in order, and return them with their assigned positions.
+     *
+     * Read-and-write inside ONE lock. See the class docblock.
+     */
+    async record(messages, runId = null) {
+        if (messages.length === 0)
+            return [];
+        return this.store.withLock(this.key, async () => {
+            const stored = (await this.store.get(this.key)) ?? {};
+            const existing = Array.isArray(stored.messages) ? stored.messages.filter(isJsonObject) : [];
+            const recordedAt = new Date().toISOString();
+            const appended = messages.map((message, index) => ({
+                position: existing.length + index + 1,
+                message,
+                run_id: runId,
+                recorded_at: recordedAt,
+            }));
+            await this.store.put(this.key, {
+                ...stored,
+                messages: [...existing, ...appended],
+            });
+            return appended.map((entry) => this.#toMessage(entry));
+        });
+    }
+    /**
+     * Forget the conversation.
+     *
+     * Deliberately separate from `Session.forget()`, which drops only the
+     * ephemeral half. Losing a thread is not a cache miss and must never be a
+     * side effect of clearing session state.
+     */
+    async clear() {
+        await this.store.withLock(this.key, async () => {
+            const stored = (await this.store.get(this.key)) ?? {};
+            await this.store.put(this.key, { ...stored, messages: [] });
+        });
+    }
+    #toMessage(entry) {
+        const message = entry.message;
+        if (!isJsonObject(message)) {
+            throw HarnessError.unmappableContent(`a stored thread entry has no message object (position ${String(entry.position)})`);
+        }
+        return {
+            position: typeof entry.position === 'number' ? entry.position : 0,
+            message,
+            runId: typeof entry.run_id === 'string' ? entry.run_id : null,
+            recordedAt: typeof entry.recorded_at === 'string' ? entry.recorded_at : '',
+        };
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,89 @@
+import type { JsonObject } from './json.js';
+import type { Session } from './session.js';
+/**
+ * The shape this package needs from a tool.
+ *
+ * STRUCTURAL, not an import. `prism-ts`'s `Tool` satisfies it, and so does
+ * anything else with a name and a handler — which keeps this package at zero
+ * dependencies and lets a consumer bring their own tool type. The reference
+ * imports `Prism\Prism\Tool` directly because it is already a dependency there.
+ */
+export interface HarnessTool {
+    readonly name: string;
+    readonly description?: string;
+    handle(args: JsonObject): unknown | Promise<unknown>;
+}
+export type ToolFactory = (session: Session) => HarnessTool;
+export type ToolProvider = (session: Session) => Iterable<HarnessTool> | Promise<Iterable<HarnessTool>>;
+/**
+ * Which tools exist, and which a given run may be offered.
+ *
+ * Three ways in, because the three answer different questions: a tool that is
+ * always the same (`register`), one that needs the session to build
+ * (`registerFactory`), and a set discovered at resolve time — an MCP server's
+ * catalogue, say (`registerProvider`).
+ */
+export declare class ToolRegistry {
+    #private;
+    register(tool: HarnessTool): this;
+    registerMany(tools: Iterable<HarnessTool>): this;
+    registerFactory(name: string, factory: ToolFactory): this;
+    registerProvider(provider: ToolProvider): this;
+    /** Every name this registry can produce without a session. */
+    names(): string[];
+    /**
+     * Resolve the named tools for a session.
+     *
+     * `'*'` means every tool this registry can produce. A name that resolves to
+     * nothing is an ERROR rather than a silent omission: a mode that lists a tool
+     * it cannot get is a misconfiguration, and dropping it quietly would leave a
+     * run wondering why the model never called it.
+     */
+    resolve(names: readonly string[], session?: Session): Promise<Map<string, HarnessTool>>;
+}
+/** Whether a tool may be OFFERED to a run. */
+export type OfferPolicy = (session: Session, tool: HarnessTool) => boolean | Promise<boolean>;
+/** Whether THIS call, with THESE arguments, may proceed. */
+export type CallPolicy = (session: Session, tool: HarnessTool, args: JsonObject) => boolean | Promise<boolean>;
+export interface ToolAuthorizerOptions {
+    enabled?: boolean;
+    offer?: OfferPolicy;
+    call?: CallPolicy;
+}
+/**
+ * The two authorization questions, kept apart.
+ *
+ * Whether a tool may be OFFERED to a run, and whether THIS invocation of it —
+ * with these arguments, this many calls in — may proceed. At the moment the
+ * toolset is assembled the arguments do not exist yet, so an offer policy can
+ * say "may use delete_file" and never "only under /tmp".
+ *
+ * OFF BY DEFAULT, matching the reference. But a policy that is defined and
+ * never consulted is REFUSED at construction rather than tolerated: it looks
+ * like a control to every reader and is not one. That is the one configuration
+ * not to leave in place — both at once.
+ */
+export declare class ToolAuthorizer {
+    #private;
+    readonly enabled: boolean;
+    constructor(options?: ToolAuthorizerOptions);
+    /** The tools a run may be offered, each wrapped so the call policy is asked again. */
+    allowed(session: Session, tools: Map<string, HarnessTool>): Promise<HarnessTool[]>;
+    /**
+     * Whether this call may proceed.
+     *
+     * True when the authorizer is disabled, matching `allowed()` — the
+     * constructor has already refused the configuration where that silence would
+     * be mistaken for enforcement.
+     */
+    allowsCall(session: Session, tool: HarnessTool, args: JsonObject): Promise<boolean>;
+}
+/**
+ * A tool that asks the policy again, at call time, with the arguments.
+ *
+ * Refuses by THROWING rather than returning an error string: a refusal handed
+ * back as a tool 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.
+ */
+export declare function authorizedTool(tool: HarnessTool, session: Session, authorizer: ToolAuthorizer): HarnessTool;

package/dist/tools.js

@@ -0,0 +1,148 @@
+import { HarnessError } from './errors.js';
+/**
+ * Which tools exist, and which a given run may be offered.
+ *
+ * Three ways in, because the three answer different questions: a tool that is
+ * always the same (`register`), one that needs the session to build
+ * (`registerFactory`), and a set discovered at resolve time — an MCP server's
+ * catalogue, say (`registerProvider`).
+ */
+export class ToolRegistry {
+    #tools = new Map();
+    #factories = new Map();
+    #providers = [];
+    register(tool) {
+        this.#tools.set(tool.name, tool);
+        return this;
+    }
+    registerMany(tools) {
+        for (const tool of tools)
+            this.register(tool);
+        return this;
+    }
+    registerFactory(name, factory) {
+        this.#factories.set(name, factory);
+        return this;
+    }
+    registerProvider(provider) {
+        this.#providers.push(provider);
+        return this;
+    }
+    /** Every name this registry can produce without a session. */
+    names() {
+        return [...new Set([...this.#tools.keys(), ...this.#factories.keys()])].sort();
+    }
+    /**
+     * Resolve the named tools for a session.
+     *
+     * `'*'` means every tool this registry can produce. A name that resolves to
+     * nothing is an ERROR rather than a silent omission: a mode that lists a tool
+     * it cannot get is a misconfiguration, and dropping it quietly would leave a
+     * run wondering why the model never called it.
+     */
+    async resolve(names, session) {
+        const provided = new Map();
+        if (session !== undefined) {
+            for (const provider of this.#providers) {
+                for (const tool of await provider(session))
+                    provided.set(tool.name, tool);
+            }
+        }
+        const available = [
+            ...new Set([...this.#tools.keys(), ...this.#factories.keys(), ...provided.keys()]),
+        ];
+        const selected = names.includes('*') ? available : names;
+        const resolved = new Map();
+        for (const name of selected) {
+            const tool = this.#tools.get(name) ?? provided.get(name);
+            if (tool !== undefined) {
+                resolved.set(name, tool);
+                continue;
+            }
+            const factory = this.#factories.get(name);
+            if (factory === undefined) {
+                throw HarnessError.toolNotAvailable(name, available);
+            }
+            if (session === undefined) {
+                throw HarnessError.toolNotAvailable(`${name} (needs a session to build)`, available);
+            }
+            resolved.set(name, factory(session));
+        }
+        return resolved;
+    }
+}
+/**
+ * The two authorization questions, kept apart.
+ *
+ * Whether a tool may be OFFERED to a run, and whether THIS invocation of it —
+ * with these arguments, this many calls in — may proceed. At the moment the
+ * toolset is assembled the arguments do not exist yet, so an offer policy can
+ * say "may use delete_file" and never "only under /tmp".
+ *
+ * OFF BY DEFAULT, matching the reference. But a policy that is defined and
+ * never consulted is REFUSED at construction rather than tolerated: it looks
+ * like a control to every reader and is not one. That is the one configuration
+ * not to leave in place — both at once.
+ */
+export class ToolAuthorizer {
+    enabled;
+    #offer;
+    #call;
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? false;
+        this.#offer = options.offer;
+        this.#call = options.call;
+        if (!this.enabled && (options.offer !== undefined || options.call !== undefined)) {
+            throw HarnessError.policyDefinedButDisabled();
+        }
+    }
+    /** The tools a run may be offered, each wrapped so the call policy is asked again. */
+    async allowed(session, tools) {
+        if (!this.enabled) {
+            return [...tools.values()];
+        }
+        const allowed = [];
+        for (const tool of tools.values()) {
+            if (this.#offer === undefined || (await this.#offer(session, tool))) {
+                // Wrapped so the SAME policy is asked when the tool is actually called,
+                // with arguments. Offer-time filtering alone cannot bound how a tool is
+                // used, only whether it is present.
+                allowed.push(authorizedTool(tool, session, this));
+            }
+        }
+        return allowed;
+    }
+    /**
+     * Whether this call may proceed.
+     *
+     * True when the authorizer is disabled, matching `allowed()` — the
+     * constructor has already refused the configuration where that silence would
+     * be mistaken for enforcement.
+     */
+    async allowsCall(session, tool, args) {
+        if (!this.enabled || this.#call === undefined) {
+            return true;
+        }
+        return this.#call(session, tool, args);
+    }
+}
+/**
+ * A tool that asks the policy again, at call time, with the arguments.
+ *
+ * Refuses by THROWING rather than returning an error string: a refusal handed
+ * back as a tool 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.
+ */
+export function authorizedTool(tool, session, authorizer) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        async handle(args) {
+            if (!(await authorizer.allowsCall(session, tool, args))) {
+                throw HarnessError.callNotAuthorized(tool.name);
+            }
+            return tool.handle(args);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@particle-academy/prism-harness",
+  "version": "0.0.0",
+  "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Particle-Academy/prism-harness-ts.git"
+  }
+}