@particle-academy/prism-harness 0.8.0 → 0.9.0

package/README.md

@@ -30,6 +30,58 @@ await session.lock(async (live) => {
 });
 ```
 
+## Named agents
+
+Select a stable agent id in trusted application code, using
+[a-z][a-z0-9_-]{0,63}. The existing calls without an agent retain their addresses.
+Each named agent has its own tools, providers, modes, session state, threads and
+default task list.
+
+```ts
+import { AgentRuntime, ModeRegistry, ToolRegistry } from '@particle-academy/prism-harness';
+
+const tools = new ToolRegistry(), modes = new ModeRegistry();
+tools.forAgent('support').register({ name: 'lookup', handle: () => 'found' }, 'app.support');
+modes.forAgent('support').register('reply', { tools: ['lookup'] }, 'app.support').setDefault('reply');
+const runtime = new AgentRuntime({ tools, modes,
+  client: async () => ({ text: 'done', finishReason: 'stop' }),
+}); // Replace the synthetic client when connecting a model.
+const session = harness.forAgent('support').for({ type: 'User', id: 7 }).session('case:42');
+const descriptors = await runtime.effectiveTools(session, 'reply');
+```
+
+Import ToolRegistry, ModeRegistry and AgentRuntime from this package. When the
+harness is constructed with runtime, its bound agent also exposes
+effectiveTools('reply', participant, scope). Descriptors contain name, owner and
+source and come from the model offer resolver. Inspection executes no handler,
+creates no session, thread or index entry and makes no model/provider request
+or logical state change. Reads may physically purge expired entries, exactly as
+an ordinary store read does. Explicit state writes during resolution refuse.
+
+For named agents, the mode list is the ceiling even when a caller supplies tool
+names. Legacy sessions retain caller-list selection by default; set
+`AgentRuntimeOptions.narrowRequestedTools` to `true` to apply the ceiling there.
+Named agents inherit no legacy authority. Builtins require explicit registration and
+mode selection. Named-agent duplicates are refused; use
+tools.forAgent('support').replace(replacement, 'app.support', 'app.support.v2')
+for an intentional replacement.
+
+Legacy registries retain duplicate overwrite and existing cross-kind precedence.
+Use `new ToolRegistry({ refuseDuplicates: true })` and
+`new ModeRegistry({ refuseDuplicates: true })` to refuse legacy duplicates.
+Named session addresses are immutable and validated; legacy participant/scope
+values retain their existing mutable behavior.
+
+AgentRuntime's agents map accepts provider/model, max_steps_ceiling,
+max_output_tokens_per_call and lock_ttl/lock_wait overrides. Unset scalars fall
+back to config; explicit null clears nullable defaults. Caps narrow the existing
+shared RunContext ledger and output budget. ToolAuthorizer's agents map supplies
+enabled/offer/call policy overrides, retaining invocation-time rechecks.
+PrismHarness's agents map separately supplies ttlSeconds, defaultScope and
+defaultTaskList. Typed ParticipantRef values require a ParticipantAdapters actor
+resolver; a child keeps the already-bound actor. Existing plain participants
+continue to work.
+
 ## Resolved, never held
 
 A server handles a request and moves on, so a session cannot be an object kept
@@ -334,21 +386,39 @@ badly.
 
 - **`MemorySessionStore`** — volatile, and says so. Right for the ephemeral slot
   in a test or a single-process tool. Its lock is real but process-local.
-- **`FileSessionStore`** — durable. Atomic writes (write-then-rename) and a
-  cross-process lock built on exclusive file creation, which is the one
-  primitive that is atomic on every filesystem worth supporting. Two workers on
-  one machine genuinely exclude each other; two machines over a network
-  filesystem do not, and no file lock can promise that — use a database there.
-
-  Its **lockfile format is shared with the PHP and Python ports**, because a
-  worker in any of the three may be pointed at one store directory: the expiry
-  in milliseconds, then a newline, written in a single write. The terminator is
-  load-bearing. Without it there is nothing to tell a complete expiry from the
-  first half of one, and every prefix of a timestamp is a smaller, *older*
-  timestamp — so a torn write reads as a lock that expired decades ago and gets
-  deleted out from under the worker holding it. Anything unterminated is treated
-  as held, bounded by the file's own age so a process that died mid-write cannot
-  wedge the key either.
+- **`FileSessionStore`** — durable. Payload writes remain atomic. Cross-process
+  local locks follow [decision 0022](https://github.com/Particle-Academy/prism-parity/blob/main/docs/decisions/0022-local-file-lock-ownership.md):
+  a complete nonce-bound owner directory is published atomically; TTL expiry
+  never proves that a live holder died. Recovery requires a matching established
+  native boot/PID realm and a proven dead or explicitly released owner. Local
+  filesystems on one host only; SMB/NFS are unsupported.
+
+  On Windows, the first file-lock operation makes one fixed, read-only metadata
+  query using the system Windows PowerShell and CIM module, with a fifteen-second
+  timeout. Established identities and detected container conditions are cached
+  for the process lifetime. Transient query failures are cached for sixty seconds,
+  then permit a new sample. With unknown identity a worker can acquire a free
+  lock and release its own owner record, but unknown owners and unknown probers
+  never authorize PID probes or recovery. A crashed unknown owner's lock stays
+  held for explicit operator inspection. `FileSessionStore.identityStatus()` is
+  an in-memory snapshot and performs no query or filesystem work. No runtime
+  compilation or extra dependency is used.
+
+  **BREAKING CHANGE: Stop all old workers before upgrading the file-lock
+  protocol.** Inspect and archive stale legacy timestamp lockfiles explicitly.
+  The library refuses them with `session_locked` and
+  `legacy_lock_requires_maintenance`, naming the canonical path and action
+  `stop_old_workers_then_inspect_and_archive`. On Windows, Node can replace a
+  legacy file created between preflight and rename; leaving old workers running
+  can break exclusion. No rolling upgrade is supported. The hard stop is a
+  correctness requirement in both ports.
+
+  A blocked Windows reader can delay release. The callback may already have
+  completed when release raises an error; the library does not replay it.
+  Pending cleanup is retried at the owning process's next file-lock operation.
+  The `file_lock_release_pending` warning includes only the key digest and nonce.
+  Read `store.pendingReleases()` for this directory's pending digest/nonce entries;
+  the snapshot's length is the count. Querying does not retry or write anything.
 
   **Threads are append-only logs** (`<digest>.jsonl` beside the payload file):
   one line per message, one write and an `fsync` per `record()`, so recording

package/dist/address-index.d.ts

@@ -0,0 +1,35 @@
+import { SessionAddress } from './address.js';
+import type { Participant } from './session.js';
+import type { JsonObject } from './json.js';
+import type { SessionStore } from './stores/session-store.js';
+export declare class AddressLimitExceeded extends Error {
+    readonly code = "address_limit_exceeded";
+    constructor();
+}
+export declare class IndexLockScopeUnsupported extends Error {
+    readonly code = "index_lock_scope_unsupported";
+    constructor();
+}
+export declare function storeLockRank(store: SessionStore): number;
+export declare class IndexRecoveryRequired extends Error {
+    readonly code = "index_recovery_required";
+    constructor();
+}
+export declare function addressLimit(value: number | null): number | null;
+export interface AddressIndexPage {
+    entries: JsonObject[];
+    next_cursor: number | null;
+}
+/** Fixed pages and a small commit head; no participant-wide value or ceiling. */
+export declare class StoreAddressIndex {
+    #private;
+    private readonly store;
+    private readonly maxAddressesPerParticipant;
+    static readonly PAGE_SIZE = 100;
+    constructor(store: SessionStore, maxAddressesPerParticipant?: number | null);
+    record(address: SessionAddress, slot: 'ephemeral' | 'durable', kind: 'state' | 'lock' | 'tasks' | 'thread', key: string): Promise<void>;
+    recover(participant: Participant | null): Promise<void>;
+    page(participant: Participant | null, cursor?: number, limit?: number): Promise<AddressIndexPage>;
+}
+/** Preserve append-log capabilities and existing transcript bytes while indexing writes. */
+export declare function indexedStore(inner: SessionStore, index: StoreAddressIndex, address: SessionAddress, slot: 'ephemeral' | 'durable', kind?: 'state' | 'tasks' | 'thread'): SessionStore;

package/dist/address-index.js

@@ -0,0 +1,170 @@
+var _a;
+import { createHash } from 'node:crypto';
+import { isJsonObject } from './json.js';
+import { supportsAppendLog } from './stores/session-store.js';
+import { HarnessError } from './errors.js';
+export class AddressLimitExceeded extends Error {
+    code = 'address_limit_exceeded';
+    constructor() { super('The configured max_addresses_per_participant limit was reached; no resource was written.'); this.name = 'AddressLimitExceeded'; }
+}
+export class IndexLockScopeUnsupported extends Error {
+    code = 'index_lock_scope_unsupported';
+    constructor() { super('Indexed namespaces require declared sharing and lock scopes, with the lock covering the sharing scope.'); this.name = 'IndexLockScopeUnsupported'; }
+}
+export function storeLockRank(store) {
+    const ranks = { process: 0, host: 1, distributed: 2 };
+    const sharing = store.sharingScope?.(), locking = store.lockScope?.();
+    if (!sharing || !locking || sharing === 'unsupported' || locking === 'unsupported'
+        || !Object.hasOwn(ranks, sharing) || !Object.hasOwn(ranks, locking) || ranks[locking] < ranks[sharing])
+        throw new IndexLockScopeUnsupported();
+    return ranks[locking];
+}
+export class IndexRecoveryRequired extends Error {
+    code = 'index_recovery_required';
+    constructor() { super('Recover the interrupted address append before reading a complete index or planning erasure.'); this.name = 'IndexRecoveryRequired'; }
+}
+export function addressLimit(value) {
+    if (value !== null && (!Number.isSafeInteger(value) || value < 1))
+        throw new TypeError('max_addresses_per_participant must be a positive integer or null.');
+    return value;
+}
+/** Fixed pages and a small commit head; no participant-wide value or ceiling. */
+export class StoreAddressIndex {
+    store;
+    maxAddressesPerParticipant;
+    static PAGE_SIZE = 100;
+    constructor(store, maxAddressesPerParticipant = null) {
+        this.store = store;
+        this.maxAddressesPerParticipant = maxAddressesPerParticipant;
+        if (store.durability() !== 'durable')
+            throw new HarnessError('unsafe_state_configuration', 'The address index requires a durable store.');
+        storeLockRank(store);
+        addressLimit(maxAddressesPerParticipant);
+    }
+    #root(type, id) {
+        return `harness-address-index:v1:${createHash('sha256').update(JSON.stringify([type, id])).digest('hex')}`;
+    }
+    #head(value) {
+        if (value === null)
+            return { version: 1, count: 0, pages: 0, pending: null };
+        if (value.version !== 1 || typeof value.count !== 'number' || !Number.isSafeInteger(value.count) || value.count < 0
+            || value.pages !== Math.ceil(value.count / _a.PAGE_SIZE)
+            || (value.pending !== null && !isJsonObject(value.pending)))
+            throw new Error('Invalid harness address index head.');
+        return value;
+    }
+    async #pageIds(root, number) {
+        const page = await this.store.get(`${root}:page:${number}`);
+        if (page === null)
+            return [];
+        if (page.version !== 1 || !Array.isArray(page.ids) || page.ids.length > _a.PAGE_SIZE
+            || page.ids.some(id => typeof id !== 'string' || /^[a-f0-9]{64}$/.exec(id)?.[0] !== id))
+            throw new Error('Invalid harness address index page.');
+        return page.ids;
+    }
+    async #recover(root, head) {
+        if (head.pending === null)
+            return head;
+        const pending = head.pending;
+        if (!isJsonObject(pending) || typeof pending.hash !== 'string' || /^[a-f0-9]{64}$/.exec(pending.hash)?.[0] !== pending.hash
+            || pending.position !== head.count || !isJsonObject(pending.entry) || pending.entry.position !== head.count)
+            throw new Error('Invalid harness address append journal.');
+        const number = Math.floor(head.count / _a.PAGE_SIZE), offset = head.count % _a.PAGE_SIZE;
+        const ids = await this.#pageIds(root, number);
+        if (ids.length === offset) {
+            ids.push(pending.hash);
+            await this.store.put(`${root}:page:${number}`, { version: 1, ids });
+        }
+        else if (ids.length !== offset + 1 || ids[offset] !== pending.hash)
+            throw new Error('Conflicting harness address append journal.');
+        await this.store.put(`${root}:entry:${pending.hash}`, pending.entry);
+        const committed = { version: 1, count: head.count + 1, pages: number + 1, pending: null };
+        // This is the visibility/commit point. Resource writes happen only after it.
+        await this.store.put(`${root}:head`, committed);
+        return committed;
+    }
+    async record(address, slot, kind, key) {
+        const root = this.#root(address.participantType, address.participantId);
+        await this.store.withLock(root, async () => {
+            const head = await this.#recover(root, this.#head(await this.store.get(`${root}:head`)));
+            const hash = address.indexKey();
+            const identity = { agent: address.agent, participant_type: address.participantType, participant_id: address.participantId, scope: address.scope };
+            const existing = await this.store.get(`${root}:entry:${hash}`);
+            if (existing !== null && (!isJsonObject(existing.address) || Object.entries(identity).some(([key, value]) => existing.address[key] !== value)
+                || typeof existing.position !== 'number' || !Number.isSafeInteger(existing.position) || existing.position < 0 || existing.position >= head.count
+                || !Array.isArray(existing.resources)))
+                throw new Error('Invalid harness address index entry.');
+            if (existing !== null) {
+                const position = existing.position, ids = await this.#pageIds(root, Math.floor(position / _a.PAGE_SIZE));
+                if (ids[position % _a.PAGE_SIZE] !== hash)
+                    throw new Error('Unlinked harness address index entry.');
+            }
+            const resources = isJsonObject(existing) && Array.isArray(existing.resources) ? [...existing.resources] : [];
+            const resource = { slot, kind, key };
+            if (resources.some(item => isJsonObject(item) && item.slot === slot && item.kind === kind && item.key === key))
+                return;
+            resources.push(resource);
+            const entry = { address: identity, resources, position: existing?.position ?? head.count };
+            if (existing !== null) {
+                await this.store.put(`${root}:entry:${hash}`, entry);
+                return;
+            }
+            if (this.maxAddressesPerParticipant !== null && head.count >= this.maxAddressesPerParticipant) {
+                throw new AddressLimitExceeded();
+            }
+            const prepared = { ...head, pending: { hash, position: head.count, entry } };
+            await this.store.put(`${root}:head`, prepared);
+            await this.#recover(root, prepared);
+        });
+    }
+    async recover(participant) {
+        const root = this.#root(participant?.type ?? null, participant === null ? null : String(participant.id));
+        await this.store.withLock(root, async () => { await this.#recover(root, this.#head(await this.store.get(`${root}:head`))); });
+    }
+    async page(participant, cursor = 0, limit = 100) {
+        if (!Number.isSafeInteger(cursor) || cursor < 0 || !Number.isInteger(limit) || limit < 1 || limit > 100)
+            throw new TypeError('Invalid address index page cursor or limit.');
+        const root = this.#root(participant?.type ?? null, participant === null ? null : String(participant.id));
+        const head = this.#head(await this.store.get(`${root}:head`)), end = Math.min(cursor + limit, head.count), entries = [];
+        if (head.pending !== null)
+            throw new IndexRecoveryRequired();
+        let pageNumber = -1, ids = [];
+        for (let position = cursor; position < end; position++) {
+            const number = Math.floor(position / _a.PAGE_SIZE);
+            if (number !== pageNumber) {
+                ids = await this.#pageIds(root, number);
+                pageNumber = number;
+            }
+            const hash = ids[position % _a.PAGE_SIZE];
+            if (hash === undefined)
+                throw new Error('Missing committed harness address page member.');
+            const entry = await this.store.get(`${root}:entry:${hash}`);
+            if (entry === null || entry.position !== position)
+                throw new Error('Missing committed harness address index entry.');
+            entries.push({ address_key: hash, ...entry });
+        }
+        return { entries, next_cursor: end < head.count ? end : null };
+    }
+}
+_a = StoreAddressIndex;
+/** Preserve append-log capabilities and existing transcript bytes while indexing writes. */
+export function indexedStore(inner, index, address, slot, kind = 'state') {
+    const wrapper = {
+        lockScope: () => inner.lockScope?.() ?? 'unsupported',
+        sharingScope: () => inner.sharingScope?.() ?? 'unsupported',
+        get: key => inner.get(key),
+        put: async (key, payload, ttl) => { await index.record(address, slot, kind, key); await inner.put(key, payload, ttl); },
+        forget: key => inner.forget(key),
+        durability: () => inner.durability(),
+        withLock: async (key, callback, ttl, wait) => { await index.record(address, slot, 'lock', key); return inner.withLock(key, callback, ttl, wait); },
+    };
+    if (supportsAppendLog(inner)) {
+        return Object.assign(wrapper, {
+            readLog: (key) => inner.readLog(key),
+            logLength: (key) => inner.logLength(key),
+            clearLog: (key) => inner.clearLog(key),
+            appendLog: async (key, entries) => { await index.record(address, slot, kind, key); await inner.appendLog(key, entries); },
+        });
+    }
+    return wrapper;
+}

package/dist/address.d.ts

@@ -0,0 +1,25 @@
+import type { Participant } from './session.js';
+export declare function validateAgent(agent: unknown): asserts agent is string | null;
+/** An explicit host-defined identity; its actor comes from a registered adapter. */
+export declare class ParticipantRef implements Participant {
+    readonly type: string;
+    readonly id: string;
+    constructor(type: string, id: string | number);
+}
+export declare class ParticipantAdapters {
+    #private;
+    register(type: string, actor: (participant: ParticipantRef) => object): void;
+    actor(participant: ParticipantRef, inheritedActor?: object): object;
+}
+/** Immutable address. Persona/display names are deliberately absent. */
+export declare class SessionAddress {
+    #private;
+    readonly scope: string;
+    readonly agent: string | null;
+    readonly participantType: string | null;
+    readonly participantId: string | null;
+    constructor(participant: Participant | null, scope: string, agent?: string | null);
+    sessionKey(): string;
+    threadKey(): string;
+    indexKey(): string;
+}

package/dist/address.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+export function validateAgent(agent) {
+    if (agent !== null && (typeof agent !== 'string' || /^[a-z][a-z0-9_-]{0,63}$/.exec(agent)?.[0] !== agent)) {
+        throw new TypeError('Harness namespace must be a configured lowercase identifier of 1–64 ASCII bytes.');
+    }
+}
+function utf8(value) {
+    return typeof value === 'string' && Buffer.from(value, 'utf8').toString('utf8') === value;
+}
+/** An explicit host-defined identity; its actor comes from a registered adapter. */
+export class ParticipantRef {
+    type;
+    id;
+    constructor(type, id) {
+        if (!utf8(type) || type.length === 0 || Buffer.byteLength(type) > 255
+            || (typeof id !== 'string' && (typeof id !== 'number' || !Number.isSafeInteger(id)))
+            || !utf8(String(id)) || String(id).length === 0 || Buffer.byteLength(String(id)) > 255) {
+            throw new TypeError('Participant references require non-empty UTF-8 type and id, at most 255 bytes each.');
+        }
+        this.type = type;
+        this.id = String(id);
+        Object.freeze(this);
+    }
+}
+export class ParticipantAdapters {
+    #actors = new Map();
+    register(type, actor) {
+        new ParticipantRef(type, 'validation');
+        if (this.#actors.has(type))
+            throw new Error('A participant adapter is already registered for this type.');
+        this.#actors.set(type, actor);
+    }
+    actor(participant, inheritedActor) {
+        const resolve = this.#actors.get(participant.type);
+        if (!resolve)
+            throw new Error('No participant actor adapter is registered for this type.');
+        const actor = inheritedActor ?? resolve(participant);
+        if (actor === null || typeof actor !== 'object')
+            throw new TypeError('Participant actor adapter must return an actor object.');
+        return actor;
+    }
+}
+/** Immutable address. Persona/display names are deliberately absent. */
+export class SessionAddress {
+    scope;
+    agent;
+    participantType;
+    participantId;
+    constructor(participant, scope, agent = null) {
+        this.scope = scope;
+        this.agent = agent;
+        validateAgent(agent);
+        if ((agent !== null || participant instanceof ParticipantRef) && (!utf8(scope) || (participant !== null && (!utf8(participant.type)
+            || (typeof participant.id !== 'string' && (typeof participant.id !== 'number' || !Number.isSafeInteger(participant.id)))
+            || !utf8(String(participant.id))))))
+            throw new TypeError('Harness addresses require valid UTF-8 and integer or string ids.');
+        this.participantType = participant?.type ?? null;
+        this.participantId = participant === null ? null : String(participant.id);
+        Object.freeze(this);
+    }
+    sessionKey() {
+        if (this.participantType === null || this.participantId === null)
+            throw new Error('A session requires a participant.');
+        if (this.agent === null)
+            return `session:${digest('sha1', this.participantType).slice(0, 12)}:${this.participantId}:${this.scope}`;
+        return `session:${this.#digest('prism-harness.session.v1')}`;
+    }
+    threadKey() {
+        if (this.agent !== null)
+            return this.#digest('prism-harness.thread.v1');
+        // PHP's legacy json_encode escapes Unicode, slashes and DEL. Keep its bytes.
+        const json = JSON.stringify([this.participantType, this.participantId, this.scope])
+            .replace(/\//g, '\\/').replace(/[\u007f-\uffff]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+        return digest('sha256', json);
+    }
+    indexKey() { return this.#digest('prism-harness.address.v1'); }
+    #digest(domain) {
+        return digest('sha256', JSON.stringify([domain, this.agent, this.participantType, this.participantId, this.scope]));
+    }
+}
+function digest(algorithm, value) {
+    return createHash(algorithm).update(value, 'utf8').digest('hex');
+}

package/dist/harness.d.ts

@@ -3,9 +3,25 @@ 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';
+import { ParticipantAdapters } from './address.js';
+import { StoreTaskSource } from './store-task-source.js';
+import { Thread } from './thread.js';
+import type { AgentRuntime, EffectiveTool } from './runtime.js';
+export interface AgentHarnessConfig {
+    ttlSeconds?: number | null;
+    defaultScope?: string;
+    defaultTaskList?: string;
+}
 export interface HarnessOptions extends Partial<StoreManagerOptions> {
+    agents?: Record<string, AgentHarnessConfig>;
+    defaultScope?: string;
+    defaultTaskList?: string;
+    runtime?: AgentRuntime;
     /** How long ephemeral state lives. Null keeps it until forgotten. */
     ttlSeconds?: number | null;
+    participantAdapters?: ParticipantAdapters;
+    /** Null (the default) leaves named address growth unlimited. */
+    maxAddressesPerParticipant?: number | null;
 }
 /**
  * The entry point: `harness.for(participant).session('support')`.
@@ -32,6 +48,12 @@ export declare class PrismHarness {
     constructor(options?: HarnessOptions);
     /** Bind to a participant. Returns a builder, because the scope comes next. */
     for(participant: Participant): PendingSession;
+    forAgent(agent: string | null): AgentHarness;
+    effectiveTools(agent: string | null, mode: string, participant: Participant, scope?: string): Promise<EffectiveTool[]>;
+    pending(participant: Participant, agent: string | null, actor?: object): PendingSession;
+    tasks(list?: string, agent?: string | null): StoreTaskSource;
+    sharedThread(scope: string, agent?: string | null): Thread;
+    findShared(scope: string, agent?: string | null): Promise<Thread | null>;
     ephemeralStore(): SessionStore;
     durableStore(): SessionStore;
 }
@@ -39,7 +61,13 @@ export declare class PendingSession {
     private readonly participant;
     private readonly stores;
     private readonly ttlSeconds;
-    constructor(participant: Participant, stores: SessionStoreManager, ttlSeconds: number | null);
+    private readonly agent;
+    private readonly actor?;
+    private readonly participants;
+    private readonly maxAddresses;
+    private readonly defaultScope;
+    constructor(participant: Participant, stores: SessionStoreManager, ttlSeconds: number | null, agent?: string | null, actor?: object | undefined, participants?: ParticipantAdapters, maxAddresses?: number | null, defaultScope?: string);
+    asActor(actor: object): PendingSession;
     /**
      * Resolve the session for a scope.
      *
@@ -47,5 +75,16 @@ export declare class PendingSession {
      * guard fire when a session is opened rather than at some later moment when
      * an approval needs saving.
      */
-    session(scope: string): Session;
+    session(scope?: string): Session;
+}
+/** A namespace-bound view, sharing stores without a mutable current-agent flag. */
+export declare class AgentHarness {
+    private readonly harness;
+    readonly agent: string | null;
+    constructor(harness: PrismHarness, agent: string | null);
+    for(participant: Participant): PendingSession;
+    effectiveTools(mode: string, participant: Participant, scope?: string): Promise<EffectiveTool[]>;
+    tasks(list?: string): StoreTaskSource;
+    sharedThread(scope: string): Thread;
+    findShared(scope: string): Promise<Thread | null>;
 }

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.');
+    }
+}