@particle-academy/prism-harness 0.7.0 → 0.9.0

package/dist/harness.js

@@ -1,6 +1,10 @@
 import { Session } from './session.js';
 import { MemorySessionStore } from './stores/memory-session-store.js';
 import { SessionStoreManager } from './stores/store-manager.js';
+import { ParticipantAdapters, ParticipantRef, SessionAddress, validateAgent } from './address.js';
+import { addressLimit, indexedStore, StoreAddressIndex } from './address-index.js';
+import { StoreTaskSource } from './store-task-source.js';
+import { Thread } from './thread.js';
 /**
  * The entry point: `harness.for(participant).session('support')`.
  *
@@ -24,8 +28,25 @@ import { SessionStoreManager } from './stores/store-manager.js';
 export class PrismHarness {
     #stores;
     #ttlSeconds;
+    #participants;
+    #maxAddresses;
+    #runtime;
+    #agents;
+    #defaultScope;
+    #defaultTaskList;
     constructor(options = {}) {
+        this.#runtime = options.runtime;
+        this.#defaultScope = options.defaultScope ?? 'default';
+        this.#defaultTaskList = options.defaultTaskList ?? 'default';
+        validateHarnessConfig({ defaultScope: this.#defaultScope, defaultTaskList: this.#defaultTaskList });
+        this.#agents = Object.fromEntries(Object.entries(options.agents ?? {}).map(([agent, config]) => {
+            validateAgent(agent);
+            validateHarnessConfig(config);
+            return [agent, { ...config }];
+        }));
         this.#ttlSeconds = options.ttlSeconds ?? null;
+        this.#participants = options.participantAdapters ?? new ParticipantAdapters();
+        this.#maxAddresses = addressLimit(options.maxAddressesPerParticipant ?? null);
         this.#stores = new SessionStoreManager({
             stores: options.stores,
             drivers: options.drivers ?? { default: () => new MemorySessionStore() },
@@ -33,7 +54,36 @@ export class PrismHarness {
     }
     /** Bind to a participant. Returns a builder, because the scope comes next. */
     for(participant) {
-        return new PendingSession(participant, this.#stores, this.#ttlSeconds);
+        return this.pending(participant, null);
+    }
+    forAgent(agent) {
+        validateAgent(agent);
+        return new AgentHarness(this, agent);
+    }
+    effectiveTools(agent, mode, participant, scope) {
+        if (!this.#runtime)
+            throw new Error('Tool inspection requires a configured Harness runtime.');
+        return this.#runtime.effectiveTools(this.pending(participant, agent).session(scope), mode);
+    }
+    pending(participant, agent, actor) {
+        validateAgent(agent);
+        const config = agent === null ? undefined : this.#agents[agent];
+        const ttl = config?.ttlSeconds === undefined ? this.#ttlSeconds : config.ttlSeconds;
+        return new PendingSession(participant, this.#stores, ttl, agent, actor, this.#participants, this.#maxAddresses, config?.defaultScope ?? this.#defaultScope);
+    }
+    tasks(list, agent = null) {
+        list ??= (agent === null ? undefined : this.#agents[agent]?.defaultTaskList) ?? this.#defaultTaskList;
+        const address = new SessionAddress(null, `task-list:${list}`, agent);
+        const durable = this.#stores.durable();
+        return new StoreTaskSource(agent === null ? durable : indexedStore(durable, new StoreAddressIndex(durable, this.#maxAddresses), address, 'durable', 'tasks'), agent === null ? `${list}:tasks` : `agent-list:${address.indexKey()}:tasks`);
+    }
+    sharedThread(scope, agent = null) {
+        const address = new SessionAddress(null, scope, agent), durable = this.#stores.durable();
+        return new Thread(agent === null ? durable : indexedStore(durable, new StoreAddressIndex(durable, this.#maxAddresses), address, 'durable', 'thread'), `thread:${address.threadKey()}`);
+    }
+    async findShared(scope, agent = null) {
+        const thread = this.sharedThread(scope, agent);
+        return await thread.exists() ? thread : null;
     }
     ephemeralStore() {
         return this.#stores.ephemeral();
@@ -46,10 +96,25 @@ export class PendingSession {
     participant;
     stores;
     ttlSeconds;
-    constructor(participant, stores, ttlSeconds) {
+    agent;
+    actor;
+    participants;
+    maxAddresses;
+    defaultScope;
+    constructor(participant, stores, ttlSeconds, agent = null, actor, participants = new ParticipantAdapters(), maxAddresses = null, defaultScope = 'default') {
         this.participant = participant;
         this.stores = stores;
         this.ttlSeconds = ttlSeconds;
+        this.agent = agent;
+        this.actor = actor;
+        this.participants = participants;
+        this.maxAddresses = maxAddresses;
+        this.defaultScope = defaultScope;
+    }
+    asActor(actor) {
+        if (this.participant instanceof ParticipantRef)
+            throw new Error('Typed participants require a registered actor adapter.');
+        return new PendingSession(this.participant, this.stores, this.ttlSeconds, this.agent, actor, this.participants, this.maxAddresses, this.defaultScope);
     }
     /**
      * Resolve the session for a scope.
@@ -58,13 +123,43 @@ export class PendingSession {
      * guard fire when a session is opened rather than at some later moment when
      * an approval needs saving.
      */
-    session(scope) {
+    session(scope = this.defaultScope) {
+        const actor = this.participant instanceof ParticipantRef ? this.participants.actor(this.participant, this.actor) : (this.actor ?? this.participant);
+        const durable = this.stores.durable();
         return new Session({
             participant: this.participant,
             scope,
             ephemeral: this.stores.ephemeral(),
-            durable: this.stores.durable(),
+            durable,
             ttlSeconds: this.ttlSeconds,
+            agent: this.agent,
+            actor,
+            addressIndex: this.agent !== null || this.participant instanceof ParticipantRef ? new StoreAddressIndex(durable, this.maxAddresses) : undefined,
         });
     }
 }
+/** A namespace-bound view, sharing stores without a mutable current-agent flag. */
+export class AgentHarness {
+    harness;
+    agent;
+    constructor(harness, agent) {
+        this.harness = harness;
+        this.agent = agent;
+        validateAgent(agent);
+        Object.defineProperty(this, 'agent', { writable: false, configurable: false });
+    }
+    for(participant) { return this.harness.pending(participant, this.agent); }
+    effectiveTools(mode, participant, scope) { return this.harness.effectiveTools(this.agent, mode, participant, scope); }
+    tasks(list) { return this.harness.tasks(list, this.agent); }
+    sharedThread(scope) { return this.harness.sharedThread(scope, this.agent); }
+    findShared(scope) { return this.harness.findShared(scope, this.agent); }
+}
+function validateHarnessConfig(config) {
+    if (config.ttlSeconds !== undefined && config.ttlSeconds !== null && (!Number.isSafeInteger(config.ttlSeconds) || config.ttlSeconds < 0))
+        throw new TypeError('Agent ephemeral TTL must be nonnegative whole seconds or null.');
+    for (const key of ['defaultScope', 'defaultTaskList']) {
+        const value = config[key];
+        if (value !== undefined && (typeof value !== 'string' || Buffer.from(value, 'utf8').toString('utf8') !== value || (key === 'defaultTaskList' && value.length === 0)))
+            throw new TypeError('Agent scope/list defaults must be valid strings.');
+    }
+}

package/dist/index.d.ts

@@ -2,23 +2,28 @@ 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 { AppendLogStore, Durability, SessionStore } from './stores/session-store.js';
+export type { AppendLogStore, Durability, LockScope, SessionStore } from './stores/session-store.js';
 export { isDurable, supportsAppendLog } from './stores/session-store.js';
 export { MemorySessionStore } from './stores/memory-session-store.js';
 export { FileSessionStore } from './stores/file-session-store.js';
+export type { PendingFileLockRelease } from './stores/file-owner-lock.js';
+export type { FileLockIdentityStatus } from './stores/file-lock-identity.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 { AgentHarness, PendingSession, PrismHarness } from './harness.js';
+export { ParticipantAdapters, ParticipantRef, SessionAddress } from './address.js';
+export { AddressLimitExceeded, IndexLockScopeUnsupported, IndexRecoveryRequired, StoreAddressIndex } from './address-index.js';
+export type { AddressIndexPage } from './address-index.js';
+export type { AgentHarnessConfig, 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 type { CallPolicy, HarnessTool, OfferPolicy, ToolAuthorizerOptions, ToolFactory, RegistryOptions, ToolProvider, } from './tools.js';
 export { HarnessEvents } from './events.js';
 export type { HarnessEvent, HarnessListener, RunFailed, RunFinished, RunStarted } from './events.js';
 export { diagnose } from './doctor.js';
@@ -26,7 +31,7 @@ export type { DoctorFinding, DoctorReport, DoctorSubjects } from './doctor.js';
 export { AgentRuntime, recordApproval } from './runtime.js';
 export { assistantRow, threadView, toolResultEntry, toolResultRow } from './thread-rows.js';
 export type { ApprovalDecisionEntry, ApprovalRequestEntry, AssistantRow, ToolCallInput, ToolCallRow, ToolResultEntry, ToolResultRow, } from './thread-rows.js';
-export type { AgentResponse, AgentRuntimeOptions, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, StructuredAgentResponse, } from './runtime.js';
+export type { AgentResponse, AgentRuntimeOptions, EffectiveTool, RuntimeConfig, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, StructuredAgentResponse, } from './runtime.js';
 export { schemaName, schemaProblems } from './structured.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';
@@ -38,4 +43,5 @@ export { SkillRegistry } from './skills.js';
 export { SubagentRunner } from './subagent-runner.js';
 export type { SubagentOutcome, SubagentResult } from './subagent-runner.js';
 export { admitAttachments } from './attachments.js';
+export { RegistrationCollision } from './registration.js';
 export type { Attachment, MediaLike } from './attachments.js';

package/dist/index.js

@@ -6,7 +6,9 @@ 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 { AgentHarness, PendingSession, PrismHarness } from './harness.js';
+export { ParticipantAdapters, ParticipantRef, SessionAddress } from './address.js';
+export { AddressLimitExceeded, IndexLockScopeUnsupported, IndexRecoveryRequired, StoreAddressIndex } from './address-index.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';
@@ -21,3 +23,4 @@ export { agentCompletionTool } from './task-tools.js';
 export { SkillRegistry } from './skills.js';
 export { SubagentRunner } from './subagent-runner.js';
 export { admitAttachments } from './attachments.js';
+export { RegistrationCollision } from './registration.js';

package/dist/modes.d.ts

@@ -11,6 +11,9 @@ export interface ModeConfig {
     provider_options?: Record<string, unknown>;
 }
 export interface ModeRegistryConfig {
+    refuseDuplicates?: boolean;
+    owner?: string;
+    agents?: Record<string, ModeRegistryConfig>;
     default?: string;
     modes?: Record<string, ModeConfig>;
 }
@@ -53,7 +56,13 @@ export declare class AgentMode {
 export declare class ModeRegistry {
     #private;
     private readonly config;
-    constructor(config?: ModeRegistryConfig);
+    private readonly agent;
+    private readonly root?;
+    constructor(config?: ModeRegistryConfig, agent?: string | null, root?: ModeRegistry | undefined);
+    forAgent(agent: string | null): ModeRegistry;
+    register(name: string, mode: ModeConfig, owner?: string): this;
+    replace(name: string, mode: ModeConfig, predecessorOwner: string, owner?: string): this;
+    setDefault(name: string): this;
     default(): string;
     /** Every mode name this application has configured. */
     names(): string[];

package/dist/modes.js

@@ -1,6 +1,8 @@
 import { HarnessError } from './errors.js';
 import { isJsonObject } from './json.js';
 import { subagentFromConfig } from './subagents.js';
+import { validateAgent } from './address.js';
+import { RegistrationCollision, registrationOwner } from './registration.js';
 /**
  * What a mode lets a run do.
  *
@@ -47,8 +49,58 @@ export class AgentMode {
 }
 export class ModeRegistry {
     config;
-    constructor(config = {}) {
+    agent;
+    root;
+    #agents = new Map();
+    #owners = new Map();
+    constructor(config = {}, agent = null, root) {
         this.config = config;
+        this.agent = agent;
+        this.root = root;
+        if (config.refuseDuplicates !== undefined && typeof config.refuseDuplicates !== 'boolean')
+            throw new TypeError('refuseDuplicates must be a boolean');
+        validateAgent(agent);
+        for (const name of Object.keys(config.modes ?? {}))
+            this.#owners.set(name, registrationOwner(config.owner, agent));
+        for (const key of ['config', 'agent', 'root'])
+            Object.defineProperty(this, key, { writable: false, configurable: false });
+    }
+    forAgent(agent) {
+        validateAgent(agent);
+        const root = this.root ?? this;
+        if (agent === null)
+            return root;
+        let view = root.#agents.get(agent);
+        if (!view) {
+            const configured = root.config.agents?.[agent] ?? {};
+            view = new ModeRegistry({ ...structuredClone(configured), refuseDuplicates: root.config.refuseDuplicates, default: configured.default ?? root.default() }, agent, root);
+            root.#agents.set(agent, view);
+        }
+        return view;
+    }
+    register(name, mode, owner) {
+        const label = registrationOwner(owner, this.agent), previous = this.#owners.get(name);
+        if ((this.agent !== null || this.config.refuseDuplicates === true) && previous !== undefined)
+            throw new RegistrationCollision(this.agent, name, previous, label);
+        this.#set(name, mode, label);
+        return this;
+    }
+    replace(name, mode, predecessorOwner, owner) {
+        const label = registrationOwner(owner, this.agent);
+        if (this.#owners.get(name) !== predecessorOwner)
+            throw new Error('Replacement must name the registered predecessor owner.');
+        this.#set(name, mode, label);
+        return this;
+    }
+    #set(name, mode, owner) {
+        this.config.modes ??= {};
+        this.config.modes[name] = structuredClone(mode);
+        this.#owners.set(name, owner);
+    }
+    setDefault(name) {
+        this.resolve(name);
+        this.config.default = name;
+        return this;
     }
     default() {
         const configured = this.config.default;

package/dist/registration.d.ts

@@ -0,0 +1,6 @@
+export declare class RegistrationCollision extends Error {
+    readonly code = "registration_collision";
+    constructor(agent: string | null, name: string, previous: string, incoming: string);
+}
+/** Diagnostic labels are host configuration, never permission grants. */
+export declare function registrationOwner(owner: string | undefined, agent: string | null): string;

package/dist/registration.js

@@ -0,0 +1,15 @@
+export class RegistrationCollision extends Error {
+    code = 'registration_collision';
+    constructor(agent, name, previous, incoming) {
+        super(`Harness registry collision: agent [${agent ?? 'legacy'}], name [${name}], owners [${previous}] and [${incoming}]. Use replace naming predecessor owner [${previous}].`);
+    }
+}
+/** Diagnostic labels are host configuration, never permission grants. */
+export function registrationOwner(owner, agent) {
+    const label = owner ?? (agent === null ? 'legacy' : undefined);
+    if (typeof label !== 'string' || label.length === 0 || Buffer.byteLength(label) > 128
+        || Buffer.from(label, 'utf8').toString('utf8') !== label || /[\u0000-\u001f\u007f]/.test(label)) {
+        throw new TypeError('A named registration requires a non-empty UTF-8 owner label of at most 128 bytes without control characters.');
+    }
+    return label;
+}

package/dist/runtime.d.ts

@@ -16,6 +16,8 @@ import type { HarnessTool, ToolAuthorizer, ToolRegistry } from './tools.js';
  * The reference couples these because Prism is already a dependency there.
  */
 export interface LlmRequest {
+    /** Optional ceiling the model client must pass to its provider request. */
+    maxOutputTokens?: number;
     systemPrompt: string;
     /** The conversation so far, serialized — oldest first. */
     messages: readonly JsonObject[];
@@ -108,15 +110,34 @@ export interface PendingApproval {
     arguments: JsonObject;
 }
 export interface AgentRuntimeOptions {
+    /** Legacy compatibility default. Named agents always enforce their mode ceiling. */
+    narrowRequestedTools?: boolean;
+    config?: RuntimeConfig;
+    agents?: Record<string, RuntimeConfig>;
     client: LlmClient;
     modes: ModeRegistry;
     tools: ToolRegistry;
     authorizer?: ToolAuthorizer;
     events?: HarnessEvents;
 }
+export interface RuntimeConfig {
+    provider?: string | null;
+    model?: string | null;
+    max_steps_ceiling?: number | null;
+    max_output_tokens_per_call?: number | null;
+    lock_ttl?: number;
+    lock_wait?: number;
+}
+export interface EffectiveTool {
+    name: string;
+    owner: string;
+    source: string;
+}
 export declare class AgentRuntime {
     #private;
     constructor(options: AgentRuntimeOptions);
+    /** Inspect the offer without a run/handler or logical mutation; reads may purge expired entries. */
+    effectiveTools(session: Session, modeName?: string): Promise<EffectiveTool[]>;
     /**
      * Run a turn.
      *
@@ -149,19 +170,4 @@ export declare class AgentRuntime {
      */
     sendStructured(session: Session, prompt: string, schema: Readonly<JsonObject>, toolNames?: readonly string[], context?: RunContext, additionalContent?: readonly unknown[]): Promise<StructuredAgentResponse>;
 }
-/**
- * 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.
- *
- * Nothing runs until the next `send()`, which acts on every decision recorded
- * by then and refuses any pending call still without one. With several pending,
- * record them all first.
- *
- * `approvalId` is `PendingApproval.id`, not the tool call id.
- */
 export declare function recordApproval(session: Session, approvalId: string, approved: boolean, reason?: string | null): Promise<void>;

package/dist/runtime.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { validateAgent } from './address.js';
 import { assistantRow, threadView, toolResultEntry, toolResultRow, } from './thread-rows.js';
 import { admitAttachments } from './attachments.js';
 import { HarnessError } from './errors.js';
@@ -32,12 +33,56 @@ export class AgentRuntime {
     #tools;
     #authorizer;
     #events;
+    #config;
+    #agents;
+    #narrowRequestedTools;
     constructor(options) {
+        if (options.narrowRequestedTools !== undefined && typeof options.narrowRequestedTools !== 'boolean')
+            throw new TypeError('narrowRequestedTools must be a boolean');
+        this.#narrowRequestedTools = options.narrowRequestedTools ?? false;
         this.#client = options.client;
         this.#modes = options.modes;
         this.#tools = options.tools;
         this.#authorizer = options.authorizer;
         this.#events = options.events;
+        this.#config = { ...options.config };
+        this.#agents = Object.fromEntries(Object.entries(options.agents ?? {}).map(([agent, config]) => {
+            validateAgent(agent);
+            validateRuntimeConfig(config);
+            return [agent, { ...config }];
+        }));
+        validateRuntimeConfig(this.#config);
+    }
+    #setting(session, key) {
+        const options = session.agent === null ? undefined : this.#agents[session.agent];
+        return options && Object.hasOwn(options, key) ? options[key] : this.#config[key];
+    }
+    #boundedRun(session, run) {
+        const steps = this.#setting(session, 'max_steps_ceiling'), output = this.#setting(session, 'max_output_tokens_per_call'), budget = run.budget;
+        if (steps == null && output == null)
+            return run;
+        return new RunContext(run.ledger, new RunBudget(steps == null ? budget.maxSteps : Math.min(budget.maxSteps, run.ledger.steps + steps), budget.maxCostUsd, budget.maxSeconds, output == null ? budget.maxOutputTokensPerCall : Math.min(budget.maxOutputTokensPerCall ?? output, output)), run.parentRunId, run.depth);
+    }
+    /** Inspect the offer without a run/handler or logical mutation; reads may purge expired entries. */
+    async effectiveTools(session, modeName) {
+        const mode = this.#modes.forAgent(session.agent).resolve(modeName ?? await session.mode());
+        return (await this.#offer(session, mode)).descriptors;
+    }
+    async #offer(session, mode, requested) {
+        return session.resolveReadOnly(mode.name, async (view) => {
+            const names = session.agent !== null || this.#narrowRequestedTools ? narrowedTools(mode.tools, requested) : (requested ?? mode.tools);
+            const detailed = await this.#tools.resolveDetailed(names, view);
+            const tools = new Map([...detailed].map(([name, entry]) => [name, entry.tool]));
+            if (view.agent !== null && tools.has('complete_task')) {
+                const authorizer = this.#authorizer?.forAgent(view.agent);
+                if (!authorizer?.enabled || !authorizer.hasCallPolicy())
+                    throw new HarnessError('unsafe_authorization_configuration', 'Named task completion requires enabled authorization and an explicit call policy.');
+            }
+            const offered = this.#authorizer ? await this.#authorizer.allowed(view, tools) : [...tools.values()];
+            const ownership = new Map([...detailed.values()].map(entry => [entry.tool.name, entry]));
+            const descriptors = offered.map(tool => ({ name: tool.name, owner: ownership.get(tool.name).owner, source: ownership.get(tool.name).source }));
+            return { tools: offered, descriptors };
+        });
     }
     /**
      * Run a turn.
@@ -80,11 +125,11 @@ export class AgentRuntime {
         // Refused before a run exists: a bad attachment is a mistake in the call,
         // and it should not cost a run, events or budget.
         const attachments = admitAttachments(prompt, additionalContent);
-        const mode = this.#modes.resolve(await session.mode());
-        const provider = (await session.provider()) ?? 'unknown';
-        const model = (await session.model()) ?? 'unknown';
+        const mode = this.#modes.forAgent(session.agent).resolve(await session.mode());
+        const provider = (await session.provider()) ?? this.#setting(session, 'provider') ?? 'unknown';
+        const model = (await session.model()) ?? this.#setting(session, 'model') ?? 'unknown';
         const runId = randomUUID();
-        const run = context ?? RunContext.root(runId, new RunBudget(mode.maxSteps));
+        const run = this.#boundedRun(session, 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, ` +
@@ -103,8 +148,13 @@ export class AgentRuntime {
             at: new Date().toISOString(),
         });
         try {
-            const resolved = await this.#tools.resolve(toolNames ?? mode.tools, session);
-            const offered = this.#authorizer ? await this.#authorizer.allowed(session, resolved) : [...resolved.values()];
+            let offered;
+            if (session.agent === null) {
+                const resolved = await this.#tools.resolve(toolNames ?? mode.tools, session);
+                offered = this.#authorizer ? await this.#authorizer.allowed(session, resolved) : [...resolved.values()];
+            }
+            else
+                offered = (await this.#offer(session, mode, toolNames)).tools;
             const called = [];
             // Decisions recorded since the run stopped are acted on FIRST, before a
             // new prompt is recorded, so the results land after the calls they answer
@@ -164,6 +214,7 @@ export class AgentRuntime {
                 provider,
                 model,
                 providerOptions: mode.providerOptions,
+                ...(run.budget.maxOutputTokensPerCall === null ? {} : { maxOutputTokens: run.budget.maxOutputTokensPerCall }),
                 ...(schema === undefined ? {} : { schema }),
             });
             run.ledger.recordSteps(1);
@@ -171,7 +222,8 @@ export class AgentRuntime {
             text = response.text;
             finishReason = response.finishReason;
             const toolCalls = response.toolCalls ?? [];
-            const gated = toolCalls.filter((call) => mode.needsApproval(call.name));
+            const failedFinish = finishReason === 'error' || finishReason === 'unknown' ? finishReason : null;
+            const gated = failedFinish === null ? toolCalls.filter((call) => mode.needsApproval(call.name)) : [];
             const requests = gated.map((call) => ({
                 approval_id: `apr_${randomUUID().replaceAll('-', '')}`,
                 tool_call_id: call.id,
@@ -184,6 +236,14 @@ export class AgentRuntime {
                 ? { ...(response.additionalContent ?? {}), structured: response.structured ?? null }
                 : response.additionalContent;
             await thread.record([assistantRow(response.text, toolCalls, metadata, requests)], runId);
+            if (failedFinish !== null) {
+                // Complete the transcript with refusals, never approval requests, so a
+                // later resume cannot dispatch calls from this failed response.
+                if (toolCalls.length > 0) {
+                    await thread.record([toolResultRow(toolCalls.map(call => toolResultEntry(call, `Not run: model step failed (${failedFinish}).`)))], runId);
+                }
+                throw HarnessError.modelStepFailed(failedFinish);
+            }
             if (toolCalls.length === 0) {
                 if (schema !== undefined) {
                     // Recorded first, then checked: the exchange happened either way, and
@@ -270,7 +330,7 @@ export class AgentRuntime {
                 }
             }
             await live.thread().record([toolResultRow([...work.results.values(), ...resolved], [...work.decisions.values()])], runId);
-        }, RESOLUTION_LOCK_SECONDS, RESOLUTION_WAIT_SECONDS);
+        }, this.#setting(session, 'lock_ttl') ?? RESOLUTION_LOCK_SECONDS, this.#setting(session, 'lock_wait') ?? RESOLUTION_WAIT_SECONDS);
     }
     /**
      * The gated calls of the last tool-calling turn that have no result yet, with
@@ -389,6 +449,33 @@ export class AgentRuntime {
  *
  * `approvalId` is `PendingApproval.id`, not the tool call id.
  */
+function validateRuntimeConfig(config) {
+    for (const key of ['provider', 'model']) {
+        const value = config[key];
+        if (value !== undefined && value !== null && (typeof value !== 'string' || value === ''))
+            throw new TypeError('Agent provider/model defaults must be nonempty strings or null.');
+    }
+    for (const key of ['max_steps_ceiling', 'max_output_tokens_per_call']) {
+        const value = config[key];
+        if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || value < 1))
+            throw new TypeError('Agent step/output ceilings must be positive integers or null.');
+    }
+    for (const key of ['lock_ttl', 'lock_wait']) {
+        const value = config[key];
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < (key === 'lock_ttl' ? 1 : 0)))
+            throw new TypeError('Agent lock settings must be whole seconds with positive TTL and nonnegative wait.');
+    }
+}
+function narrowedTools(ceiling, requested) {
+    if (requested === undefined || requested.includes('*'))
+        return ceiling;
+    if (ceiling.includes('*'))
+        return requested;
+    const refused = requested.find(name => !ceiling.includes(name));
+    if (refused !== undefined)
+        throw HarnessError.toolNotAvailable(refused, ceiling);
+    return requested;
+}
 export async function recordApproval(session, approvalId, approved, reason = null) {
     const run = await session.run();
     await session.thread().record([toolResultRow([], [{ approval_id: approvalId, approved, reason }])], run?.id ?? null);

package/dist/session.d.ts

@@ -1,3 +1,5 @@
+import { SessionAddress } from './address.js';
+import { StoreAddressIndex } from './address-index.js';
 import type { JsonObject } from './json.js';
 import type { SessionStore } from './stores/session-store.js';
 import { StoreTaskSource } from './store-task-source.js';
@@ -29,6 +31,10 @@ export interface SessionOptions {
     durable: SessionStore;
     /** How long ephemeral state lives. Null keeps it until forgotten. */
     ttlSeconds?: number | null;
+    agent?: string | null;
+    actor?: object;
+    addressIndex?: StoreAddressIndex;
+    maxAddressesPerParticipant?: number | null;
 }
 /**
  * One participant's live runtime, reconstructed per turn.
@@ -47,6 +53,8 @@ export interface SessionOptions {
  */
 export declare class Session {
     #private;
+    readonly address: SessionAddress;
+    readonly actor: object;
     readonly scope: string;
     readonly participant: Participant;
     constructor(options: SessionOptions);
@@ -64,6 +72,7 @@ export declare class Session {
      * ONE store and resolve the same session.
      */
     key(): string;
+    get agent(): string | null;
     mode(): Promise<string | null>;
     usingMode(mode: string): Promise<this>;
     model(): Promise<string | null>;
@@ -75,6 +84,7 @@ export declare class Session {
     forget(): Promise<this>;
     /** The stored conversation this session is bound to. */
     thread(): Thread;
+    findThread(): Promise<Thread | null>;
     /**
      * The agent task list this session is bound to.
      *
@@ -111,4 +121,6 @@ export declare class Session {
      * run inside this, not outside it.
      */
     lock<T>(callback: (session: this) => T | Promise<T>, ttlSeconds?: number, waitSeconds?: number): Promise<T>;
+    /** Refuse explicit logical mutations; ordinary get() retains expired-entry cleanup. */
+    resolveReadOnly<T>(mode: string, resolve: (session: Session) => T | Promise<T>): Promise<T>;
 }