@particle-academy/prism-harness 0.8.0 → 0.9.1

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 && !this.#narrowRequestedTools) {
+                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);
@@ -279,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
@@ -398,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>;
 }

package/dist/session.js

@@ -1,4 +1,5 @@
-import { createHash } from 'node:crypto';
+import { ParticipantRef, SessionAddress } from './address.js';
+import { indexedStore, storeLockRank, StoreAddressIndex } from './address-index.js';
 import { isJsonObject } from './json.js';
 import { StoreTaskSource } from './store-task-source.js';
 import { Thread } from './thread.js';
@@ -18,18 +19,39 @@ import { Thread } from './thread.js';
  *  - the thread and stored capabilities are DURABLE.
  */
 export class Session {
+    address;
+    actor;
+    #addressIndex;
+    #rawDurable;
+    #rawEphemeral;
+    #lockStore;
     scope;
     participant;
     #ephemeral;
     #durable;
     #ttlSeconds;
     #cachedState = null;
+    #resolutionOnly = false;
+    #resolvedMode = null;
     constructor(options) {
-        this.participant = options.participant;
+        if (options.participant instanceof ParticipantRef && options.actor === undefined)
+            throw new Error('Typed participants require an explicit authorization actor.');
+        const strictIdentity = options.agent != null || options.participant instanceof ParticipantRef;
+        this.participant = options.participant instanceof ParticipantRef ? options.participant : (strictIdentity ? Object.freeze({ ...options.participant }) : options.participant);
+        this.address = new SessionAddress(this.participant, options.scope, options.agent ?? null);
+        this.actor = options.actor ?? this.participant;
+        const index = options.addressIndex ?? (this.address.agent !== null || options.participant instanceof ParticipantRef
+            ? new StoreAddressIndex(options.durable, options.maxAddressesPerParticipant ?? null) : undefined);
+        this.#addressIndex = index;
+        this.#rawDurable = options.durable;
+        this.#rawEphemeral = options.ephemeral;
         this.scope = options.scope;
-        this.#ephemeral = options.ephemeral;
-        this.#durable = options.durable;
+        this.#ephemeral = index ? indexedStore(options.ephemeral, index, this.address, 'ephemeral') : options.ephemeral;
+        this.#durable = index ? indexedStore(options.durable, index, this.address, 'durable') : options.durable;
+        this.#lockStore = index && storeLockRank(options.durable) > storeLockRank(options.ephemeral) ? this.#durable : this.#ephemeral;
         this.#ttlSeconds = options.ttlSeconds ?? null;
+        for (const key of strictIdentity ? ['address', 'actor', 'participant', 'scope'] : ['address', 'actor'])
+            Object.defineProperty(this, key, { writable: false, configurable: false });
     }
     /**
      * The address this session is resolved by.
@@ -45,11 +67,14 @@ export class Session {
      * ONE store and resolve the same session.
      */
     key() {
-        const digest = createHash('sha1').update(this.participant.type).digest('hex').slice(0, 12);
-        return `session:${digest}:${String(this.participant.id)}:${this.scope}`;
+        return this.address.agent === null && !(this.participant instanceof ParticipantRef)
+            ? new SessionAddress(this.participant, this.scope).sessionKey() : this.address.sessionKey();
     }
+    get agent() { return this.address.agent; }
     // -- ephemeral half --------------------------------------------------------
     async mode() {
+        if (this.#resolvedMode !== null)
+            return this.#resolvedMode;
         return this.#readString('mode');
     }
     async usingMode(mode) {
@@ -69,10 +94,11 @@ export class Session {
     }
     async state() {
         this.#cachedState ??= (await this.#ephemeral.get(this.#ephemeralKey())) ?? {};
-        return this.#cachedState;
+        return this.#resolutionOnly ? structuredClone(this.#cachedState) : this.#cachedState;
     }
     /** Drop the ephemeral half. THE CONVERSATION IS UNTOUCHED. */
     async forget() {
+        this.#assertWritable();
         await this.#ephemeral.forget(this.#ephemeralKey());
         this.#cachedState = null;
         return this;
@@ -80,7 +106,13 @@ export class Session {
     // -- durable half ----------------------------------------------------------
     /** The stored conversation this session is bound to. */
     thread() {
-        return new Thread(this.#durable, `${this.key()}:thread`);
+        this.#assertWritable();
+        const store = this.#addressIndex ? indexedStore(this.#rawDurable, this.#addressIndex, this.address, 'durable', 'thread') : this.#durable;
+        return new Thread(store, `${this.key()}:thread`);
+    }
+    async findThread() {
+        const thread = this.thread();
+        return await thread.exists() ? thread : null;
     }
     /**
      * The agent task list this session is bound to.
@@ -93,13 +125,15 @@ export class Session {
      * against a store as safe as one reached through here.
      */
     tasks(options = {}) {
-        return new StoreTaskSource(this.#durable, `${this.key()}:tasks`, options);
+        this.#assertWritable();
+        const store = this.#addressIndex ? indexedStore(this.#rawDurable, this.#addressIndex, this.address, 'durable', 'tasks') : this.#durable;
+        return new StoreTaskSource(store, `${this.key()}:tasks`, options);
     }
     async capability(name) {
         const stored = (await this.#durable.get(this.#durableKey())) ?? {};
         const capabilities = isJsonObject(stored.capabilities) ? stored.capabilities : {};
         const capability = capabilities[name];
-        return isJsonObject(capability) ? capability : null;
+        return isJsonObject(capability) ? (this.#resolutionOnly ? structuredClone(capability) : capability) : null;
     }
     async usingCapability(name, state) {
         return this.#writeCapabilities((capabilities) => ({ ...capabilities, [name]: state }));
@@ -149,7 +183,8 @@ export class Session {
      * run inside this, not outside it.
      */
     async lock(callback, ttlSeconds = 10, waitSeconds = 5) {
-        return this.#ephemeral.withLock(this.key(), async () => {
+        this.#assertWritable();
+        return this.#lockStore.withLock(this.key(), async () => {
             // Re-read inside the lock. State written by whoever held it before us
             // is otherwise invisible to this instance, and acting on a stale read
             // is the thing the lock exists to prevent.
@@ -164,17 +199,37 @@ export class Session {
     #durableKey() {
         return `${this.key()}:durable`;
     }
+    /** Refuse explicit logical mutations; ordinary get() retains expired-entry cleanup. */
+    async resolveReadOnly(mode, resolve) {
+        const view = new Session({ participant: this.participant, scope: this.scope, agent: this.agent, actor: this.actor,
+            ephemeral: this.#rawEphemeral, durable: this.#rawDurable, addressIndex: this.#addressIndex, ttlSeconds: this.#ttlSeconds });
+        view.#resolutionOnly = true;
+        view.#resolvedMode = mode;
+        try {
+            return await resolve(view);
+        }
+        finally {
+            view.#resolutionOnly = false;
+            view.#cachedState = null;
+        }
+    }
+    #assertWritable() {
+        if (this.#resolutionOnly)
+            throw new Error('Harness tool resolution is read-only.');
+    }
     async #readString(key) {
         const value = (await this.state())[key];
         return typeof value === 'string' ? value : null;
     }
     async #write(key, value) {
+        this.#assertWritable();
         const state = { ...(await this.state()), [key]: value };
         await this.#ephemeral.put(this.#ephemeralKey(), state, this.#ttlSeconds);
         this.#cachedState = state;
         return this;
     }
     async #writeCapabilities(mutate) {
+        this.#assertWritable();
         const stored = (await this.#durable.get(this.#durableKey())) ?? {};
         const capabilities = isJsonObject(stored.capabilities) ? stored.capabilities : {};
         await this.#durable.put(this.#durableKey(), { ...stored, capabilities: mutate(capabilities) });

package/dist/stores/file-lock-identity.d.ts

@@ -0,0 +1,20 @@
+export interface LockIdentity {
+    readonly platform: 'linux' | 'darwin' | 'win32';
+    readonly boot_id: string;
+    readonly pid_namespace: string | null;
+}
+export interface FileLockIdentityStatus {
+    readonly sampled: boolean;
+    readonly recovery_available: boolean;
+    readonly definitive: boolean;
+    readonly retry_after_ms: number | null;
+    readonly sample_duration_ms: number;
+    readonly code: 'file_lock_identity_unavailable' | null;
+}
+/** Process metadata snapshot only; never runs a query or performs I/O. */
+export declare function fileLockIdentityStatus(): FileLockIdentityStatus;
+/** Definitive metadata is permanent; transient failure is sampled at most once per minute. */
+export declare function nativeLockIdentity(): LockIdentity | null;
+export declare function sameLockIdentity(owner: LockIdentity, local: LockIdentity): boolean;
+/** Read-only signal-zero probe. Permission errors and reused live PIDs remain held. */
+export declare function lockPidIsDead(pid: number): boolean;