@particle-academy/prism-harness 0.0.0

package/dist/errors.js

@@ -0,0 +1,201 @@
+export class HarnessError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.name = 'HarnessError';
+        this.code = code;
+    }
+    static sessionLocked(key, waitSeconds) {
+        return new HarnessError('session_locked', `Could not acquire the lock on session [${key}] within ${waitSeconds}s. ` +
+            'Another worker is holding it; the callback was NOT run.');
+    }
+    /**
+     * 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, driver) {
+        return new HarnessError('unsafe_state_configuration', `The [${slot}] slot is configured with the [${driver}] driver, which reports itself VOLATILE. ` +
+            'Durable state (threads, pending tool approvals) must survive a deploy. Either point this ' +
+            'slot at a durable driver, or — if this store really does persist — declare it durable when ' +
+            'you register it. That declaration is an assertion about your infrastructure, not a preference.');
+    }
+    static unknownStoreDriver(slot, driver) {
+        return new HarnessError('unknown_store_driver', `The [${slot}] slot names the driver [${driver}], which is not registered.`);
+    }
+    static toolNotAvailable(name, available) {
+        return new HarnessError('tool_not_available', `The tool [${name}] is not available to this session (has: ${available.join(', ') || 'none'}).`);
+    }
+    static runNotPermitted(reason) {
+        return new HarnessError('run_not_permitted', reason);
+    }
+    static unmappableContent(description, options = {}) {
+        return new HarnessError('unmappable_content', `Could not rebuild stored content: ${description}.`, options);
+    }
+    static modeNotConfigured(name) {
+        return new HarnessError('mode_not_configured', `Harness mode [${name}] is not configured.`);
+    }
+    static modeMalformed(name, detail) {
+        return new HarnessError('mode_malformed', `Harness mode [${name}] is malformed: ${detail}.`);
+    }
+    /**
+     * 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() {
+        return new HarnessError('unsafe_authorization_configuration', 'A tool authorization policy was supplied, but the authorizer is disabled, so that policy is ' +
+            'never consulted and every registered tool is offered to every run. Either enable the ' +
+            'authorizer, or remove the policy so nothing suggests tool access is being restricted.');
+    }
+    /**
+     * 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) {
+        return new HarnessError('call_not_authorized', `This call to [${tool}] was refused by the tool authorization policy.`);
+    }
+    /**
+     * 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) {
+        return new HarnessError('skill_path_refused', `Refused to read a skill file: ${detail}.`);
+    }
+    /**
+     * 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() {
+        return new HarnessError('unsafe_state_configuration', 'An agent task list was pointed at a store that reports itself VOLATILE. The list is durable ' +
+            'state: losing it is a correctness failure, because a half-finished list that vanishes on a ' +
+            'deploy looks exactly like a finished one. Point it at a durable store, or -- if this store ' +
+            'really does persist -- declare it durable when you register it. That declaration is an ' +
+            'assertion about your infrastructure, not a preference.');
+    }
+    /**
+     * 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) {
+        return new HarnessError('task_lease_invalid', `A lease of [${String(seconds)}] seconds was asked for. It must be a whole number of seconds, ` +
+            'at least one. A fraction cannot be honoured -- the expiry is an integer timestamp -- and a ' +
+            'lease that has already expired when it is granted hands the same task to a second worker.');
+    }
+    static taskNotFound(id) {
+        return new HarnessError('task_not_found', `No task with the id [${id}] is in this source.`);
+    }
+    static duplicateTaskId(id) {
+        return new HarnessError('duplicate_task_id', `A task with the id [${id}] is already in this source. Ids are unique within a source, and ` +
+            'reusing one would let two units of work share a claim.');
+    }
+    /**
+     * 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) {
+        return new HarnessError('task_identifier_blank', `The ${what} is the empty string. An identifier that is not an identifier would make one ` +
+            'claim indistinguishable from another.');
+    }
+    /**
+     * 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, state) {
+        return new HarnessError('task_already_terminal', `The task [${id}] is already [${state}], which is terminal. Re-releasing it is refused rather ` +
+            'than ignored: two callers believing they own one outcome is worth reporting.');
+    }
+    /**
+     * "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, worker, detail) {
+        return new HarnessError('task_lease_not_held', `The worker [${worker}] is not holding the task [${id}]: ${detail}. Claim it again rather ` +
+            'than acting on it.');
+    }
+    /**
+     * 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, given) {
+        return new HarnessError('task_outcome_invalid', `[${where}] was given the outcome [${String(given)}]. It must be exactly [done] ` +
+            'or [failed]; anything else is refused rather than guessed at, because guessing would let a ' +
+            'malformed argument close a task.');
+    }
+    /**
+     * 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) {
+        return new HarnessError('unsafe_authorization_configuration', `The tool [${name}] would let the agent mark its own task complete, but the ToolAuthorizer it ` +
+            'was given is disabled, so nothing would ever be asked whether that call may proceed. An ' +
+            'agent that can close its own tasks turns "run until the goal is met" into "run until it ' +
+            'decides it is met". Enable the authorizer and give it a call policy, or do not register ' +
+            'this tool.');
+    }
+    static noAgentRuntime(action) {
+        return new HarnessError('no_agent_runtime', `This session cannot ${action}: it was built without an agent runtime.`);
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,67 @@
+import type { JsonObject } from './json.js';
+/**
+ * What happened during a run, for anything that wants to watch.
+ *
+ * A plain discriminated union and a synchronous listener list rather than an
+ * event bus: this package has no framework to hang one off, and a consumer that
+ * wants queues or broadcasting already has somewhere better to put them. The
+ * point is that the harness EMITS at the right moments, not that it owns the
+ * delivery mechanism.
+ *
+ * NO PROMPTS, NO TOOL ARGUMENTS, and that boundary is the same one
+ * `Session.completeRun()` holds: tool NAMES are what an operator needs to audit
+ * a guardrail and are not PII, while arguments are — `prism-opentelemetry`
+ * already carries those behind an opt-in capture gate with a length cap, and
+ * emitting them here ungated would quietly undo that decision for anyone who
+ * installed both.
+ */
+export type HarnessEvent = RunStarted | RunFinished | RunFailed;
+export interface RunStarted {
+    type: 'run.started';
+    runId: string;
+    sessionKey: string;
+    mode: string;
+    provider: string;
+    model: string;
+    /** The root of the tree this run belongs to; equal to `runId` for a root run. */
+    rootRunId: string;
+    depth: number;
+    at: string;
+}
+export interface RunFinished {
+    type: 'run.finished';
+    runId: string;
+    sessionKey: string;
+    finishReason: string;
+    /** NAMES only, in call order. */
+    toolCalls: readonly string[];
+    steps: number;
+    costUsd: number | null;
+    at: string;
+}
+export interface RunFailed {
+    type: 'run.failed';
+    runId: string;
+    sessionKey: string;
+    /** Why it stopped: a budget reason, a cancellation, or a provider failure. */
+    failure: string;
+    steps: number;
+    at: string;
+}
+export type HarnessListener = (event: HarnessEvent) => void;
+export declare class HarnessEvents {
+    #private;
+    /** Returns an unsubscribe function, so a caller can stop listening. */
+    listen(listener: HarnessListener): () => void;
+    /**
+     * Deliver an event to every listener.
+     *
+     * A THROWING LISTENER MUST NOT BREAK THE RUN. Telemetry that takes down the
+     * thing it observes is worse than no telemetry, and a listener is by
+     * definition somebody else's code. Failures are collected and reported after
+     * every listener has had its turn.
+     */
+    emit(event: HarnessEvent): void;
+    /** For a consumer that wants to persist or forward the event as data. */
+    static toObject(event: HarnessEvent): JsonObject;
+}

package/dist/events.js

@@ -0,0 +1,40 @@
+export class HarnessEvents {
+    #listeners = [];
+    /** Returns an unsubscribe function, so a caller can stop listening. */
+    listen(listener) {
+        this.#listeners.push(listener);
+        return () => {
+            const index = this.#listeners.indexOf(listener);
+            if (index >= 0)
+                this.#listeners.splice(index, 1);
+        };
+    }
+    /**
+     * Deliver an event to every listener.
+     *
+     * A THROWING LISTENER MUST NOT BREAK THE RUN. Telemetry that takes down the
+     * thing it observes is worse than no telemetry, and a listener is by
+     * definition somebody else's code. Failures are collected and reported after
+     * every listener has had its turn.
+     */
+    emit(event) {
+        const failures = [];
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0 && typeof process !== 'undefined') {
+            for (const failure of failures) {
+                process.emitWarning(`A prism-harness event listener threw while handling [${event.type}]: ${String(failure)}`);
+            }
+        }
+    }
+    /** For a consumer that wants to persist or forward the event as data. */
+    static toObject(event) {
+        return { ...event };
+    }
+}

package/dist/harness.d.ts

@@ -0,0 +1,51 @@
+import type { Participant } from './session.js';
+import { Session } from './session.js';
+import type { SessionStore } from './stores/session-store.js';
+import type { StoreManagerOptions } from './stores/store-manager.js';
+import { SessionStoreManager } from './stores/store-manager.js';
+export interface HarnessOptions extends Partial<StoreManagerOptions> {
+    /** How long ephemeral state lives. Null keeps it until forgotten. */
+    ttlSeconds?: number | null;
+}
+/**
+ * The entry point: `harness.for(participant).session('support')`.
+ *
+ * Mirrors the reference's `PrismHarness::for($user)->session('support')`,
+ * including the two-step shape — the participant is chosen first and the scope
+ * second, because one participant holds several unrelated conversations and the
+ * pair is what addresses one of them.
+ *
+ * ## The default is deliberately NOT usable for durable state
+ *
+ * With no drivers configured, both slots resolve to an in-memory store, and the
+ * manager then REFUSES it for the durable slot — because it reports itself
+ * volatile and the durable slot holds approvals a human has not answered yet.
+ * Constructing a harness therefore works, and asking it for durable state
+ * fails loudly with a message that names the fix.
+ *
+ * That is not an oversight to be smoothed over. 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 was deployed on two.
+ */
+export declare class PrismHarness {
+    #private;
+    constructor(options?: HarnessOptions);
+    /** Bind to a participant. Returns a builder, because the scope comes next. */
+    for(participant: Participant): PendingSession;
+    ephemeralStore(): SessionStore;
+    durableStore(): SessionStore;
+}
+export declare class PendingSession {
+    private readonly participant;
+    private readonly stores;
+    private readonly ttlSeconds;
+    constructor(participant: Participant, stores: SessionStoreManager, ttlSeconds: number | null);
+    /**
+     * Resolve the session for a scope.
+     *
+     * The stores are resolved HERE, which is what makes the volatile-durable
+     * guard fire when a session is opened rather than at some later moment when
+     * an approval needs saving.
+     */
+    session(scope: string): Session;
+}

package/dist/harness.js

@@ -0,0 +1,70 @@
+import { Session } from './session.js';
+import { MemorySessionStore } from './stores/memory-session-store.js';
+import { SessionStoreManager } from './stores/store-manager.js';
+/**
+ * The entry point: `harness.for(participant).session('support')`.
+ *
+ * Mirrors the reference's `PrismHarness::for($user)->session('support')`,
+ * including the two-step shape — the participant is chosen first and the scope
+ * second, because one participant holds several unrelated conversations and the
+ * pair is what addresses one of them.
+ *
+ * ## The default is deliberately NOT usable for durable state
+ *
+ * With no drivers configured, both slots resolve to an in-memory store, and the
+ * manager then REFUSES it for the durable slot — because it reports itself
+ * volatile and the durable slot holds approvals a human has not answered yet.
+ * Constructing a harness therefore works, and asking it for durable state
+ * fails loudly with a message that names the fix.
+ *
+ * That is not an oversight to be smoothed over. 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 was deployed on two.
+ */
+export class PrismHarness {
+    #stores;
+    #ttlSeconds;
+    constructor(options = {}) {
+        this.#ttlSeconds = options.ttlSeconds ?? null;
+        this.#stores = new SessionStoreManager({
+            stores: options.stores,
+            drivers: options.drivers ?? { default: () => new MemorySessionStore() },
+        });
+    }
+    /** Bind to a participant. Returns a builder, because the scope comes next. */
+    for(participant) {
+        return new PendingSession(participant, this.#stores, this.#ttlSeconds);
+    }
+    ephemeralStore() {
+        return this.#stores.ephemeral();
+    }
+    durableStore() {
+        return this.#stores.durable();
+    }
+}
+export class PendingSession {
+    participant;
+    stores;
+    ttlSeconds;
+    constructor(participant, stores, ttlSeconds) {
+        this.participant = participant;
+        this.stores = stores;
+        this.ttlSeconds = ttlSeconds;
+    }
+    /**
+     * Resolve the session for a scope.
+     *
+     * The stores are resolved HERE, which is what makes the volatile-durable
+     * guard fire when a session is opened rather than at some later moment when
+     * an approval needs saving.
+     */
+    session(scope) {
+        return new Session({
+            participant: this.participant,
+            scope,
+            ephemeral: this.stores.ephemeral(),
+            durable: this.stores.durable(),
+            ttlSeconds: this.ttlSeconds,
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+export { HarnessError } from './errors.js';
+export type { HarnessErrorCode, HarnessErrorOptions } from './errors.js';
+export type { JsonObject, JsonValue } from './json.js';
+export { isJsonObject } from './json.js';
+export type { Durability, SessionStore } from './stores/session-store.js';
+export { isDurable } from './stores/session-store.js';
+export { MemorySessionStore } from './stores/memory-session-store.js';
+export { FileSessionStore } from './stores/file-session-store.js';
+export { SessionStoreManager, SLOT_DURABLE, SLOT_EPHEMERAL } from './stores/store-manager.js';
+export type { StoreFactory, StoreManagerOptions } from './stores/store-manager.js';
+export { Session } from './session.js';
+export type { Participant, RunState, SessionOptions } from './session.js';
+export { Thread } from './thread.js';
+export type { ThreadMessage } from './thread.js';
+export { PendingSession, PrismHarness } from './harness.js';
+export type { HarnessOptions } from './harness.js';
+export { AgentMode, ModeRegistry } from './modes.js';
+export type { ModeConfig, ModeRegistryConfig } from './modes.js';
+export { MAX_DEPTH, RunBudget, RunContext, RunLedger, Subagent, subagentFromConfig } from './subagents.js';
+export { ToolAuthorizer, ToolRegistry, authorizedTool } from './tools.js';
+export type { CallPolicy, HarnessTool, OfferPolicy, ToolAuthorizerOptions, ToolFactory, ToolProvider, } from './tools.js';
+export { HarnessEvents } from './events.js';
+export type { HarnessEvent, HarnessListener, RunFailed, RunFinished, RunStarted } from './events.js';
+export { diagnose } from './doctor.js';
+export type { DoctorFinding, DoctorReport, DoctorSubjects } from './doctor.js';
+export { AgentRuntime, recordApproval } from './runtime.js';
+export type { AgentResponse, AgentRuntimeOptions, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, } from './runtime.js';
+export { DEFAULT_LEASE_SECONDS, TASK_STATES, asAgentTask, attributesToRecord, canonicalTaskJson, isTaskState, isTerminalState, recordToAttributes, taskRecordFrom, withAgentTask, } from './tasks.js';
+export type { AgentTask, AgentTaskAttributeSource, AgentTaskAttributes, AgentTaskRecord, AgentTaskSource, LeasedAgentTask, TaskOutcome, TaskState, } from './tasks.js';
+export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';
+export type { Clock, StoreTaskSourceOptions } from './store-task-source.js';
+export { agentCompletionTool } from './task-tools.js';
+export type { CompletionToolOptions } from './task-tools.js';
+export { SkillRegistry } from './skills.js';
+export { SubagentRunner } from './subagent-runner.js';
+export type { SubagentOutcome, SubagentResult } from './subagent-runner.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+export { HarnessError } from './errors.js';
+export { isJsonObject } from './json.js';
+export { isDurable } from './stores/session-store.js';
+export { MemorySessionStore } from './stores/memory-session-store.js';
+export { FileSessionStore } from './stores/file-session-store.js';
+export { SessionStoreManager, SLOT_DURABLE, SLOT_EPHEMERAL } from './stores/store-manager.js';
+export { Session } from './session.js';
+export { Thread } from './thread.js';
+export { PendingSession, PrismHarness } from './harness.js';
+export { AgentMode, ModeRegistry } from './modes.js';
+export { MAX_DEPTH, RunBudget, RunContext, RunLedger, Subagent, subagentFromConfig } from './subagents.js';
+export { ToolAuthorizer, ToolRegistry, authorizedTool } from './tools.js';
+export { HarnessEvents } from './events.js';
+export { diagnose } from './doctor.js';
+export { AgentRuntime, recordApproval } from './runtime.js';
+export { DEFAULT_LEASE_SECONDS, TASK_STATES, asAgentTask, attributesToRecord, canonicalTaskJson, isTaskState, isTerminalState, recordToAttributes, taskRecordFrom, withAgentTask, } from './tasks.js';
+export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';
+export { agentCompletionTool } from './task-tools.js';
+export { SkillRegistry } from './skills.js';
+export { SubagentRunner } from './subagent-runner.js';

package/dist/json.d.ts

@@ -0,0 +1,15 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue | undefined;
+}
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/**
+ * A deep copy, by round trip.
+ *
+ * Stores hand payloads back to callers, and a caller that mutates what it was
+ * given would otherwise reach into the store's own state — which the in-memory
+ * driver makes trivially possible and every other driver makes impossible. A
+ * bug that only appears on one driver is the worst kind here, because the
+ * in-memory one is what tests run against.
+ */
+export declare function clone<T extends JsonValue | JsonObject>(value: T): T;

package/dist/json.js

@@ -0,0 +1,15 @@
+export function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * A deep copy, by round trip.
+ *
+ * Stores hand payloads back to callers, and a caller that mutates what it was
+ * given would otherwise reach into the store's own state — which the in-memory
+ * driver makes trivially possible and every other driver makes impossible. A
+ * bug that only appears on one driver is the worst kind here, because the
+ * in-memory one is what tests run against.
+ */
+export function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/modes.d.ts

@@ -0,0 +1,63 @@
+import type { Subagent } from './subagents.js';
+export interface ModeConfig {
+    system_prompt?: string;
+    tools?: readonly string[];
+    skills?: readonly string[];
+    max_steps?: number;
+    subagents?: Record<string, unknown>;
+    requires_approval?: readonly string[];
+}
+export interface ModeRegistryConfig {
+    default?: string;
+    modes?: Record<string, ModeConfig>;
+}
+/**
+ * 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 declare class AgentMode {
+    readonly name: string;
+    readonly systemPrompt: string;
+    readonly tools: readonly string[];
+    readonly skills: readonly string[];
+    readonly maxSteps: number;
+    /** Nested agents this mode may call, by name. */
+    readonly subagents: Readonly<Record<string, Subagent>>;
+    /** Tools that must not run until a human says so. */
+    readonly requiresApproval: readonly string[];
+    constructor(name: string, systemPrompt: string, tools: readonly string[], skills: readonly string[], maxSteps: number, 
+    /** Nested agents this mode may call, by name. */
+    subagents?: Readonly<Record<string, Subagent>>, 
+    /** Tools that must not run until a human says so. */
+    requiresApproval?: readonly string[]);
+    /**
+     * 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: string): boolean;
+}
+export declare class ModeRegistry {
+    #private;
+    private readonly config;
+    constructor(config?: ModeRegistryConfig);
+    default(): string;
+    /** Every mode name this application has configured. */
+    names(): string[];
+    /**
+     * 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(): Record<string, AgentMode>;
+    resolve(name?: string | null): AgentMode;
+}