@particle-academy/prism-harness 0.0.0

package/dist/modes.js

@@ -0,0 +1,109 @@
+import { HarnessError } from './errors.js';
+import { subagentFromConfig } from './subagents.js';
+/**
+ * What a mode lets a run do.
+ *
+ * A mode is the unit of authority here: the tools it may reach, the skills it
+ * loads, how many steps it gets, which nested agents it may call, and which of
+ * its tools need a human first.
+ */
+export class AgentMode {
+    name;
+    systemPrompt;
+    tools;
+    skills;
+    maxSteps;
+    subagents;
+    requiresApproval;
+    constructor(name, systemPrompt, tools, skills, maxSteps, 
+    /** Nested agents this mode may call, by name. */
+    subagents = {}, 
+    /** Tools that must not run until a human says so. */
+    requiresApproval = []) {
+        this.name = name;
+        this.systemPrompt = systemPrompt;
+        this.tools = tools;
+        this.skills = skills;
+        this.maxSteps = maxSteps;
+        this.subagents = subagents;
+        this.requiresApproval = requiresApproval;
+    }
+    /**
+     * Whether a named tool needs a human before it runs IN THIS MODE.
+     *
+     * Declared per mode rather than on the tool, because the same tool is not
+     * equally consequential everywhere: `execute_op` against a scratch project is
+     * routine and against production is not, and the tool cannot tell which it is
+     * in. `'*'` gates every tool the mode offers.
+     */
+    needsApproval(tool) {
+        return this.requiresApproval.includes('*') || this.requiresApproval.includes(tool);
+    }
+}
+export class ModeRegistry {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    default() {
+        const configured = this.config.default;
+        return typeof configured === 'string' && configured !== '' ? configured : 'chat';
+    }
+    /** Every mode name this application has configured. */
+    names() {
+        return Object.keys(this.config.modes ?? {});
+    }
+    /**
+     * Every mode, RESOLVED.
+     *
+     * Resolving them all is the point: `resolve()` validates as it goes, so a
+     * mode nobody has entered yet keeps its misconfiguration until the day
+     * somebody switches to it. This is what the doctor uses to find that on a
+     * Tuesday rather than in front of a user.
+     */
+    all() {
+        return Object.fromEntries(this.names().map((name) => [name, this.resolve(name)]));
+    }
+    resolve(name) {
+        const wanted = name ?? this.default();
+        const mode = this.config.modes?.[wanted];
+        if (mode === undefined) {
+            throw HarnessError.modeNotConfigured(wanted);
+        }
+        const prompt = mode.system_prompt ?? '';
+        const maxSteps = mode.max_steps ?? 8;
+        if (typeof prompt !== 'string' || !Number.isInteger(maxSteps) || maxSteps < 1) {
+            throw HarnessError.modeMalformed(wanted, 'system_prompt must be a string and max_steps a positive integer');
+        }
+        return new AgentMode(wanted, prompt, strings(mode.tools), strings(mode.skills), maxSteps, this.#subagentsFor(wanted, mode), strings(mode.requires_approval));
+    }
+    /**
+     * The nested agents a mode may call.
+     *
+     * DECLARED PER MODE, which is the point: a subagent is authority, and
+     * authority a run inherits by being nested is authority nobody granted. A
+     * mode that names no subagents cannot spawn one.
+     *
+     * A subagent's own mode must EXIST, and it is checked here rather than at
+     * call time so a typo surfaces when the parent mode is loaded instead of
+     * halfway through a run that has already spent budget.
+     */
+    #subagentsFor(name, mode) {
+        const declared = mode.subagents ?? {};
+        const subagents = {};
+        for (const [key, config] of Object.entries(declared)) {
+            if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+                throw HarnessError.modeMalformed(name, `subagent [${key}] is not an object`);
+            }
+            const subagent = subagentFromConfig(key, config);
+            if (this.config.modes?.[subagent.mode] === undefined) {
+                throw HarnessError.modeMalformed(name, `it declares subagent [${key}], whose mode [${subagent.mode}] is not configured`);
+            }
+            subagents[key] = subagent;
+        }
+        return subagents;
+    }
+}
+function strings(value) {
+    return (value ?? []).filter((entry) => typeof entry === 'string');
+}

package/dist/runtime.d.ts

@@ -0,0 +1,104 @@
+import type { JsonObject } from './json.js';
+import type { HarnessEvents } from './events.js';
+import type { ModeRegistry } from './modes.js';
+import type { Session } from './session.js';
+import { RunContext } from './subagents.js';
+import type { HarnessTool, ToolAuthorizer, ToolRegistry } from './tools.js';
+/**
+ * What the runtime needs from a model, and NOTHING MORE.
+ *
+ * An INTERFACE rather than a dependency on `prism-ts`. The loop below — steps,
+ * budgets, approvals, thread recording, events — is the part worth porting, and
+ * none of it needs to know how a request reaches a provider. Keeping the seam
+ * here also means this package stays at zero dependencies and a consumer can
+ * drive it with `prism-ts`, with their own client, or with a fake in a test.
+ *
+ * The reference couples these because Prism is already a dependency there.
+ */
+export interface LlmRequest {
+    systemPrompt: string;
+    /** The conversation so far, serialized — oldest first. */
+    messages: readonly JsonObject[];
+    tools: readonly HarnessTool[];
+    provider: string;
+    model: string;
+}
+export interface LlmToolCall {
+    id: string;
+    name: string;
+    arguments: JsonObject;
+}
+export interface LlmResponse {
+    text: string;
+    toolCalls?: readonly LlmToolCall[];
+    /** `stop`, `tool_calls`, `length`, … — the provider's own reason, passed through. */
+    finishReason: string;
+    /** Null when the provider does not report one. NOT zero — see `RunLedger.recordCost`. */
+    costUsd?: number | null;
+}
+export type LlmClient = (request: LlmRequest) => Promise<LlmResponse>;
+export interface AgentResponse {
+    runId: string;
+    text: string;
+    steps: number;
+    /** NAMES only, in call order. */
+    toolCalls: readonly string[];
+    finishReason: string;
+    /** Set when the run stopped because a tool needs a human. */
+    pendingApprovals: readonly PendingApproval[];
+    /** Set when the run stopped because the tree ran out of budget, or was cancelled. */
+    stoppedBecause: string | null;
+}
+export interface PendingApproval {
+    id: string;
+    tool: string;
+    arguments: JsonObject;
+}
+export interface AgentRuntimeOptions {
+    client: LlmClient;
+    modes: ModeRegistry;
+    tools: ToolRegistry;
+    authorizer?: ToolAuthorizer;
+    events?: HarnessEvents;
+}
+/**
+ * The loop: prompt in, turns out, everything recorded.
+ *
+ * Three properties matter more than the mechanics.
+ *
+ * **Every step is checked against the budget BEFORE it is taken**, not after.
+ * Checking afterwards means the step that broke the limit has already been
+ * paid for, which makes a budget a report rather than a control.
+ *
+ * **An approval stops the run and is written to the THREAD**, not held in
+ * memory. That is what makes it survive: the approval a person grants this
+ * morning is a durable row, so the worker that resumes tonight — a different
+ * process, possibly after a deploy — reads the same answer.
+ *
+ * **A tool that needs approval and has none DOES NOT RUN.** Failing closed is
+ * the only safe direction: an unanswered approval that executed anyway is
+ * exactly the outcome the whole mechanism exists to prevent.
+ */
+export declare class AgentRuntime {
+    #private;
+    constructor(options: AgentRuntimeOptions);
+    /**
+     * Run a turn.
+     *
+     * An EMPTY prompt is meaningful and not an error: it is how a run resumes
+     * after an approval, because the conversation already contains the request,
+     * the decision, and everything before them. A new prompt there would be a
+     * second instruction competing with the one the tool call came from.
+     */
+    send(session: Session, prompt: string, toolNames?: readonly string[], context?: RunContext): Promise<AgentResponse>;
+}
+/**
+ * Answer a pending approval, durably.
+ *
+ * The decision is RECORDED IN THE THREAD, not held anywhere else. Who may
+ * approve is the APPLICATION's decision, not this package's: the session is
+ * already scoped to a participant, so nobody can answer another participant's
+ * approval through it, but "this user may approve THIS action" is a question
+ * only the host can answer. Authorize before calling.
+ */
+export declare function recordApproval(session: Session, approvalId: string, approved: boolean, reason?: string | null): Promise<void>;

package/dist/runtime.js

@@ -0,0 +1,244 @@
+import { randomUUID } from 'node:crypto';
+import { HarnessError } from './errors.js';
+import { RunBudget, RunContext } from './subagents.js';
+/**
+ * The loop: prompt in, turns out, everything recorded.
+ *
+ * Three properties matter more than the mechanics.
+ *
+ * **Every step is checked against the budget BEFORE it is taken**, not after.
+ * Checking afterwards means the step that broke the limit has already been
+ * paid for, which makes a budget a report rather than a control.
+ *
+ * **An approval stops the run and is written to the THREAD**, not held in
+ * memory. That is what makes it survive: the approval a person grants this
+ * morning is a durable row, so the worker that resumes tonight — a different
+ * process, possibly after a deploy — reads the same answer.
+ *
+ * **A tool that needs approval and has none DOES NOT RUN.** Failing closed is
+ * the only safe direction: an unanswered approval that executed anyway is
+ * exactly the outcome the whole mechanism exists to prevent.
+ */
+export class AgentRuntime {
+    #client;
+    #modes;
+    #tools;
+    #authorizer;
+    #events;
+    constructor(options) {
+        this.#client = options.client;
+        this.#modes = options.modes;
+        this.#tools = options.tools;
+        this.#authorizer = options.authorizer;
+        this.#events = options.events;
+    }
+    /**
+     * Run a turn.
+     *
+     * An EMPTY prompt is meaningful and not an error: it is how a run resumes
+     * after an approval, because the conversation already contains the request,
+     * the decision, and everything before them. A new prompt there would be a
+     * second instruction competing with the one the tool call came from.
+     */
+    async send(session, prompt, toolNames, context) {
+        const mode = this.#modes.resolve(await session.mode());
+        const provider = (await session.provider()) ?? 'unknown';
+        const model = (await session.model()) ?? 'unknown';
+        const runId = randomUUID();
+        const run = context ?? RunContext.root(runId, new RunBudget(mode.maxSteps));
+        const thread = session.thread();
+        if (run.tooDeep()) {
+            throw HarnessError.runNotPermitted(`This run is nested ${run.depth} deep, at or past the ceiling. Nobody debugs a tree that deep, ` +
+                'and a configuration that produced one is a mistake worth reporting rather than executing.');
+        }
+        await session.beginRun(runId, mode.name, provider, model);
+        this.#events?.emit({
+            type: 'run.started',
+            runId,
+            sessionKey: session.key(),
+            mode: mode.name,
+            provider,
+            model,
+            rootRunId: run.rootRunId,
+            depth: run.depth,
+            at: new Date().toISOString(),
+        });
+        if (prompt !== '') {
+            await thread.record([{ type: 'user', content: prompt }], runId);
+        }
+        try {
+            return await this.#loop(session, mode, run, runId, provider, model, toolNames);
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error.message : String(error);
+            await session.failRun(runId, failure);
+            this.#events?.emit({
+                type: 'run.failed',
+                runId,
+                sessionKey: session.key(),
+                failure,
+                steps: run.ledger.steps,
+                at: new Date().toISOString(),
+            });
+            throw error;
+        }
+    }
+    async #loop(session, mode, run, runId, provider, model, toolNames) {
+        const thread = session.thread();
+        const resolved = await this.#tools.resolve(toolNames ?? mode.tools, session);
+        const offered = this.#authorizer
+            ? await this.#authorizer.allowed(session, resolved)
+            : [...resolved.values()];
+        const called = [];
+        let text = '';
+        let finishReason = 'stop';
+        for (;;) {
+            // BEFORE the step, never after. Checking afterwards means the step that
+            // broke the limit has already been paid for.
+            const exhausted = run.ledger.exhaustion(run.budget);
+            if (exhausted !== null) {
+                return await this.#finish(session, runId, called, 'budget_exhausted', text, run, exhausted);
+            }
+            const response = await this.#client({
+                systemPrompt: mode.systemPrompt,
+                messages: (await thread.messages()).map((entry) => entry.message),
+                tools: offered,
+                provider,
+                model,
+            });
+            run.ledger.recordSteps(1);
+            run.ledger.recordCost(response.costUsd ?? null);
+            text = response.text;
+            finishReason = response.finishReason;
+            const toolCalls = response.toolCalls ?? [];
+            await thread.record([
+                {
+                    type: 'assistant',
+                    content: response.text,
+                    tool_calls: toolCalls.map((call) => ({ id: call.id, name: call.name })),
+                },
+            ], runId);
+            if (toolCalls.length === 0) {
+                return await this.#finish(session, runId, called, finishReason, text, run, null);
+            }
+            const pending = await this.#pendingApprovals(session, mode, toolCalls);
+            if (pending.length > 0) {
+                // FAILS CLOSED. The run stops here and the request is already in the
+                // thread, so a different process can pick it up after a human answers.
+                await thread.record([{ type: 'tool_approval_request', approvals: pending }], runId);
+                return {
+                    runId,
+                    text,
+                    steps: run.ledger.steps,
+                    toolCalls: called,
+                    finishReason: 'awaiting_approval',
+                    pendingApprovals: pending,
+                    stoppedBecause: null,
+                };
+            }
+            for (const call of toolCalls) {
+                called.push(call.name);
+                await thread.record([await this.#invoke(offered, call)], runId);
+            }
+        }
+    }
+    /**
+     * Which of these calls needs a human, and has not had one.
+     *
+     * An approval already answered in the thread is NOT asked again — that is the
+     * whole point of recording it durably. An answered-and-denied approval is
+     * also not asked again; it is simply not executed.
+     */
+    async #pendingApprovals(session, mode, toolCalls) {
+        const gated = toolCalls.filter((call) => mode.needsApproval(call.name));
+        if (gated.length === 0)
+            return [];
+        const answered = await this.#answeredApprovals(session);
+        return gated
+            .filter((call) => !answered.has(call.id))
+            .map((call) => ({ id: call.id, tool: call.name, arguments: call.arguments }));
+    }
+    async #answeredApprovals(session) {
+        const answered = new Map();
+        for (const entry of await session.thread().messages()) {
+            if (entry.message.type !== 'tool_approval_response')
+                continue;
+            const id = entry.message.approval_id;
+            const approved = entry.message.approved;
+            if (typeof id === 'string')
+                answered.set(id, approved === true);
+        }
+        return answered;
+    }
+    async #invoke(offered, call) {
+        const tool = offered.find((candidate) => candidate.name === call.name);
+        if (tool === undefined) {
+            throw HarnessError.toolNotAvailable(call.name, offered.map((candidate) => candidate.name));
+        }
+        try {
+            const result = await tool.handle(call.arguments);
+            return {
+                type: 'tool_result',
+                tool_call_id: call.id,
+                name: call.name,
+                result: typeof result === 'string' ? result : JSON.stringify(result ?? null),
+            };
+        }
+        catch (error) {
+            // A failed tool is a RESULT, not a crashed run: the model can often
+            // recover, and losing the whole turn to one bad call is worse. A refused
+            // call is different and is left to propagate — see `authorizedTool`.
+            if (error instanceof HarnessError && error.code === 'call_not_authorized')
+                throw error;
+            return {
+                type: 'tool_result',
+                tool_call_id: call.id,
+                name: call.name,
+                result: `The tool failed: ${error instanceof Error ? error.message : String(error)}`,
+                failed: true,
+            };
+        }
+    }
+    async #finish(session, runId, called, finishReason, text, run, stoppedBecause) {
+        await session.completeRun(runId, finishReason, called);
+        this.#events?.emit({
+            type: 'run.finished',
+            runId,
+            sessionKey: session.key(),
+            finishReason,
+            toolCalls: called,
+            steps: run.ledger.steps,
+            costUsd: run.ledger.unmeteredRuns > 0 ? null : run.ledger.costUsd,
+            at: new Date().toISOString(),
+        });
+        return {
+            runId,
+            text,
+            steps: run.ledger.steps,
+            toolCalls: called,
+            finishReason,
+            pendingApprovals: [],
+            stoppedBecause,
+        };
+    }
+}
+/**
+ * Answer a pending approval, durably.
+ *
+ * The decision is RECORDED IN THE THREAD, not held anywhere else. Who may
+ * approve is the APPLICATION's decision, not this package's: the session is
+ * already scoped to a participant, so nobody can answer another participant's
+ * approval through it, but "this user may approve THIS action" is a question
+ * only the host can answer. Authorize before calling.
+ */
+export async function recordApproval(session, approvalId, approved, reason = null) {
+    const run = await session.run();
+    await session.thread().record([
+        {
+            type: 'tool_approval_response',
+            approval_id: approvalId,
+            approved,
+            reason,
+        },
+    ], run?.id ?? null);
+}

package/dist/session.d.ts

@@ -0,0 +1,114 @@
+import type { JsonObject } from './json.js';
+import type { SessionStore } from './stores/session-store.js';
+import { StoreTaskSource } from './store-task-source.js';
+import type { StoreTaskSourceOptions } from './store-task-source.js';
+import { Thread } from './thread.js';
+/**
+ * Who a session belongs to.
+ *
+ * A TYPE and an ID, not just an id: one application holds users and teams and
+ * bots, and `7` means a different participant in each. The reference gets the
+ * same pair from Eloquent's morph class and primary key.
+ */
+export interface Participant {
+    type: string;
+    id: string | number;
+}
+export interface RunState extends JsonObject {
+    id: string;
+    status: 'running' | 'completed' | 'failed';
+    mode?: string;
+    provider?: string;
+    model?: string;
+    started_at?: string;
+}
+export interface SessionOptions {
+    participant: Participant;
+    scope: string;
+    ephemeral: SessionStore;
+    durable: SessionStore;
+    /** How long ephemeral state lives. Null keeps it until forgotten. */
+    ttlSeconds?: number | null;
+}
+/**
+ * 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 declare class Session {
+    #private;
+    readonly scope: string;
+    readonly participant: Participant;
+    constructor(options: SessionOptions);
+    /**
+     * 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(): string;
+    mode(): Promise<string | null>;
+    usingMode(mode: string): Promise<this>;
+    model(): Promise<string | null>;
+    usingModel(model: string): Promise<this>;
+    provider(): Promise<string | null>;
+    usingProvider(provider: string): Promise<this>;
+    state(): Promise<JsonObject>;
+    /** Drop the ephemeral half. THE CONVERSATION IS UNTOUCHED. */
+    forget(): Promise<this>;
+    /** The stored conversation this session is bound to. */
+    thread(): 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?: StoreTaskSourceOptions): StoreTaskSource;
+    capability(name: string): Promise<JsonObject | null>;
+    usingCapability(name: string, state: JsonObject): Promise<this>;
+    forgetCapability(name: string): Promise<this>;
+    run(): Promise<RunState | null>;
+    beginRun(id: string, mode: string, provider: string, model: string): Promise<this>;
+    /**
+     * @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.
+     */
+    completeRun(id: string, finishReason: string, toolCalls?: readonly string[]): Promise<this>;
+    failRun(id: string, failure: string): Promise<this>;
+    /**
+     * 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.
+     */
+    lock<T>(callback: (session: this) => T | Promise<T>, ttlSeconds?: number, waitSeconds?: number): Promise<T>;
+}