@particle-academy/prism-harness 0.8.0 → 0.9.0

package/dist/stores/file-session-store.js

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
-import { mkdir, open, readFile, rename, rm, stat, truncate, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, rename, rm, stat, truncate, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isJsonObject } from '../json.js';
 import { HarnessError } from '../errors.js';
+import { withFileOwnerLock, pendingFileOwnerReleases } from './file-owner-lock.js';
+import { fileLockIdentityStatus } from './file-lock-identity.js';
 /**
  * State on disk, as one JSON file per key. DURABLE, and it says so.
  *
@@ -20,12 +22,10 @@ import { HarnessError } from '../errors.js';
  * partial write here is a corrupted thread, and a process killed mid-write is
  * ordinary rather than exotic.
  *
- * **The lock is cross-process.** It is an exclusive-create lockfile (`wx`),
- * which is the one primitive that is atomic on every filesystem worth
- * supporting — unlike an "is it there?" check followed by a create, which has a
- * window between the two. Two workers on one machine genuinely exclude each
- * other. Two workers on different machines sharing a network filesystem do NOT
- * reliably, and no file lock can promise that; use a database or Redis there.
+ * **The lock is cross-process.** Decision 0022 uses an atomically published
+ * owner directory. TTL never proves death. Local filesystems on one host only;
+ * SMB/NFS are unsupported. Stop all old workers before upgrading and inspect
+ * legacy timestamp lockfiles explicitly. Use a database or Redis across hosts.
  */
 export class FileSessionStore {
     #directory;
@@ -44,6 +44,11 @@ export class FileSessionStore {
     durability() {
         return 'durable';
     }
+    /** Local filesystem on one host; SMB/NFS sharing is unsupported. */
+    sharingScope() { return 'host'; }
+    lockScope() { return 'host'; }
+    /** Process discovery snapshot; this observer never starts metadata discovery. */
+    identityStatus() { return fileLockIdentityStatus(); }
     async get(key) {
         let raw;
         try {
@@ -221,144 +226,11 @@ export class FileSessionStore {
         }
     }
     async withLock(key, callback, ttlSeconds = 10, waitSeconds = 5) {
-        const lockPath = `${this.#pathFor(key)}.lock`;
-        const deadline = Date.now() + waitSeconds * 1000;
-        for (;;) {
-            try {
-                // `wx` fails if the file exists. Exclusive CREATION is atomic; a
-                // check-then-create is not, and the window between the two is exactly
-                // where two workers both decide they hold the lock.
-                const handle = await open(lockPath, 'wx');
-                // ONE write, and the terminator goes in it. The newline is what lets a
-                // reader tell a complete stamp from a torn one, so it must never be a
-                // second write that could be the half that did not land. See
-                // `#expired`, and note the format is shared with the other two ports.
-                await handle.writeFile(stamp(Date.now() + ttlSeconds * 1000), 'utf8');
-                await handle.close();
-                try {
-                    return await callback();
-                }
-                finally {
-                    await this.#release(lockPath);
-                }
-            }
-            catch (error) {
-                if (!isHeld(error))
-                    throw error;
-                // A lock whose TTL has passed belonged to a process that died holding
-                // it. Left alone it would wedge the key forever, which is worse than
-                // the small race in reclaiming it — and the reclaim is itself a
-                // create-exclusive, so only one waiter can win.
-                if (await this.#expired(lockPath, ttlSeconds)) {
-                    await unlink(lockPath).catch(() => undefined);
-                    continue;
-                }
-                if (Date.now() >= deadline) {
-                    throw HarnessError.sessionLocked(key, waitSeconds);
-                }
-                await sleep(25);
-            }
-        }
+        return withFileOwnerLock(this.#pathFor(key) + '.lock', key, callback, ttlSeconds, waitSeconds);
     }
-    /**
-     * Give the lock up, and NEVER leave it held on the way out.
-     *
-     * Deleting is the normal path, but on Windows it can fail: another waiter
-     * attempting to create the same path holds a transient handle, and the unlink
-     * then raises EPERM. Swallowing that — which is what this did first — LEAKS
-     * THE LOCK. The waiter then sees a lockfile whose TTL is still in the future,
-     * has no way to know its holder is gone, and blocks for the whole wait before
-     * failing. Not theoretical: `prism-harness-py` hit exactly this the first
-     * time two threads recorded a message concurrently, and this port had the
-     * same defect with no test that happened to reach it.
-     *
-     * So if the file cannot be removed, it is rewritten with an ALREADY-PAST
-     * expiry. Any waiter reclaims it on its next attempt, which is the same path
-     * a genuinely dead holder takes.
-     */
-    async #release(lockPath) {
-        for (let attempt = 0; attempt < 5; attempt += 1) {
-            try {
-                await unlink(lockPath);
-                return;
-            }
-            catch (error) {
-                if (isMissing(error))
-                    return;
-                await sleep(5);
-            }
-        }
-        // Nothing left to try but mark it dead. The TTL is the backstop, and it is
-        // why the lockfile carries one at all. TERMINATED like any other stamp: an
-        // unterminated `0` reads as a torn write, and a waiter would then sit on
-        // the mtime bound for a whole ttl instead of reclaiming it at once — the
-        // exact delay this path exists to avoid.
-        await writeFile(lockPath, stamp(0), 'utf8').catch(() => undefined);
-    }
-    /**
-     * Whether this lock belonged to a holder that is gone.
-     *
-     * ## An UNFINISHED stamp is HELD, not expired in 1970
-     *
-     * Taking the lock is an exclusive create and THEN a write of the expiry —
-     * two operations, with a moment in between where the file exists and is
-     * incomplete. There are two ways to read it in that moment and both used to
-     * steal the lock:
-     *
-     *  - **Empty.** `Number('')` is `0`, which is finite and certainly
-     *    `<= Date.now()`.
-     *  - **Torn.** A partial write leaves a PREFIX of the timestamp —
-     *    `17356899` where `1735689900000` was meant — and every prefix of a
-     *    number is a SMALLER number. It parses, it is finite, and it is decades
-     *    in the past. This one is worse than the empty case precisely because it
-     *    does not look broken.
-     *
-     * Either way a waiter concluded the holder was long dead, deleted the lock,
-     * and took one somebody was actively holding. Two callers, one key: the
-     * failure this lock exists to prevent, produced BY the mechanism meant to
-     * recover from a dead holder. The empty case surfaced as a flaky test — about
-     * one run in eight — which is how it survived; the torn case would not have
-     * surfaced at all.
-     *
-     * The fix is the TERMINATOR. A stamp is digits followed by a newline, written
-     * in one write, so anything else is an unfinished write rather than a small
-     * number. Unreadable then means WAIT — `session_locked` after the wait
-     * period, which is loud and recoverable — instead of deleting a live holder's
-     * lock. The format is shared with the PHP and Python ports, because a worker
-     * in any of the three may be pointed at the same store directory.
-     *
-     * ## …but only until it is older than the ttl
-     *
-     * Treating an empty lockfile as held forever would let a process that died
-     * inside that window wedge the key permanently, which is the worse failure
-     * of the two. The file's own mtime bounds it: the window is microseconds in a
-     * live process, so a file still empty a whole ttl later belonged to one that
-     * did not survive it. Nothing extra has to be written for that to work.
-     */
-    async #expired(lockPath, ttlSeconds) {
-        let raw;
-        try {
-            raw = await readFile(lockPath, 'utf8');
-        }
-        catch {
-            // Gone between the failed create and this read: treat it as not expired
-            // and let the next attempt take it cleanly.
-            return false;
-        }
-        // Digits AND a terminator, or this is not a finished stamp. Checked as a
-        // whole rather than by trying to parse and hoping a bad value fails to:
-        // the torn case parses perfectly and is the reason this check exists.
-        if (!STAMP.test(raw)) {
-            try {
-                const { mtimeMs } = await stat(lockPath);
-                return mtimeMs + ttlSeconds * 1000 <= Date.now();
-            }
-            catch {
-                return false;
-            }
-        }
-        const expiresAt = Number(raw.slice(0, -1));
-        return Number.isFinite(expiresAt) && expiresAt <= Date.now();
+    /** Pending release diagnostics for this directory; length is the pending count. */
+    pendingReleases() {
+        return pendingFileOwnerReleases(this.#directory);
     }
     /**
      * One file per key, named by a digest.
@@ -376,49 +248,10 @@ export class FileSessionStore {
         return join(this.#directory, `${digestOf(key)}.jsonl`);
     }
 }
-/**
- * A finished lock stamp: digits, then a newline. NOTHING ELSE.
- *
- * The terminator is the only thing that distinguishes a complete timestamp from
- * a torn one, because a prefix of a timestamp is a perfectly valid smaller
- * timestamp. Shared with the PHP and Python ports — a worker in any of the
- * three may be pointed at the same store directory, and one that does not
- * emit the newline has its locks waited out rather than reclaimed everywhere
- * else.
- */
-const STAMP = /^\d+\n$/;
 /** A key's file name. Colons are illegal on Windows and keys run long, so it is digested. */
 function digestOf(key) {
     return createHash('sha256').update(key).digest('hex').slice(0, 32);
 }
-function stamp(expiresAt) {
-    return `${String(Math.trunc(expiresAt))}\n`;
-}
 function isMissing(error) {
     return typeof error === 'object' && error !== null && error.code === 'ENOENT';
 }
-/**
- * "The lock is already held" — under four different names.
- *
- * POSIX says EEXIST. WINDOWS DOES NOT, reliably: deleting a file that another
- * handle still has open leaves it in a pending-delete state, and a create
- * attempt against that returns EPERM, EACCES or EBUSY instead. That window is
- * not rare — it is exactly the moment one caller releases the lock while the
- * next is trying to take it, which is the common case under contention rather
- * than an edge.
- *
- * Treating those as "held, retry" is also the safe direction to be wrong in: a
- * genuine permission problem retries until the wait expires and then reports
- * `session_locked`, which is a survivable failure. Treating them as "not held"
- * would hand the same lock to two callers.
- */
-function isHeld(error) {
-    const code = typeof error === 'object' && error !== null ? error.code : undefined;
-    return code === 'EEXIST' || code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
-}
-function sleep(ms) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        timer.unref?.();
-    });
-}

package/dist/stores/memory-session-store.d.ts

@@ -15,6 +15,8 @@ import type { Durability, SessionStore } from './session-store.js';
 export declare class MemorySessionStore implements SessionStore {
     #private;
     durability(): Durability;
+    sharingScope(): 'process';
+    lockScope(): 'process' | 'host' | 'distributed' | 'unsupported';
     get(key: string): Promise<JsonObject | null>;
     put(key: string, payload: JsonObject, ttlSeconds?: number | null): Promise<void>;
     forget(key: string): Promise<void>;

package/dist/stores/memory-session-store.js

@@ -19,6 +19,8 @@ export class MemorySessionStore {
     durability() {
         return 'volatile';
     }
+    sharingScope() { return 'process'; }
+    lockScope() { return 'process'; }
     async get(key) {
         const entry = this.#entries.get(key);
         if (entry === undefined) {

package/dist/stores/session-store.d.ts

@@ -25,6 +25,7 @@ export type Durability =
  */
  | 'durable';
 export declare function isDurable(durability: Durability): boolean;
+export type LockScope = 'process' | 'host' | 'distributed' | 'unsupported';
 /**
  * Where session state lives between turns.
  *
@@ -38,6 +39,9 @@ export declare function isDurable(durability: Durability): boolean;
  * lost agent action.
  */
 export interface SessionStore {
+    /** Required to opt into indexed namespaces; absent declarations are refused there. */
+    lockScope?(): LockScope;
+    sharingScope?(): LockScope;
     /** Null when nothing is stored. */
     get(key: string): Promise<JsonObject | null>;
     /** `ttlSeconds` of null keeps the payload until it is removed. */

package/dist/subagent-runner.js

@@ -1,4 +1,5 @@
 import { MAX_DEPTH } from './subagents.js';
+import { HarnessError } from './errors.js';
 /**
  * Turns a declared `Subagent` into a TOOL the parent run can call.
  *
@@ -24,6 +25,9 @@ export class SubagentRunner {
             name: subagent.name,
             description: subagent.description,
             handle: async (args) => {
+                if (parent.agent !== null && Object.keys(args).some(key => key !== 'task')) {
+                    throw HarnessError.runNotPermitted('Named subagent input may contain only task. Identity changes require an explicit host-owned delegation binding.');
+                }
                 const task = typeof args.task === 'string' ? args.task : '';
                 return (await this.run(subagent, parent, context, parentRunId, task)).toToolResult();
             },
@@ -47,12 +51,15 @@ export class SubagentRunner {
             return refused(subagent.name, runId, parentRunId, 'denied', `subagent nesting reached the maximum depth of ${MAX_DEPTH}`);
         }
         const child = this.harness
-            .for(parent.participant)
+            .pending(parent.participant, parent.agent, parent.actor)
             .session(subagent.scopeUnder(parent.scope));
         // The child's authority comes from ITS mode, not the parent's.
         await child.usingMode(subagent.mode);
-        await child.usingProvider((await parent.provider()) ?? 'unknown');
-        await child.usingModel((await parent.model()) ?? 'unknown');
+        const provider = await parent.provider(), model = await parent.model();
+        if (parent.agent === null || provider !== null)
+            await child.usingProvider(provider ?? 'unknown');
+        if (parent.agent === null || model !== null)
+            await child.usingModel(model ?? 'unknown');
         try {
             const response = await this.runtime.send(child, task, undefined, childContext);
             return {

package/dist/subagents.d.ts

@@ -25,7 +25,8 @@ export declare class RunBudget {
     readonly maxSteps: number;
     readonly maxCostUsd: number | null;
     readonly maxSeconds: number | null;
-    constructor(maxSteps: number, maxCostUsd?: number | null, maxSeconds?: number | null);
+    readonly maxOutputTokensPerCall: number | null;
+    constructor(maxSteps: number, maxCostUsd?: number | null, maxSeconds?: number | null, maxOutputTokensPerCall?: number | null);
     static fromConfig(config: Record<string, unknown>, defaultSteps?: number): RunBudget;
     /**
      * The budget a CHILD actually gets, as a TREE-ABSOLUTE ceiling.

package/dist/subagents.js

@@ -25,13 +25,20 @@ export class RunBudget {
     maxSteps;
     maxCostUsd;
     maxSeconds;
-    constructor(maxSteps, maxCostUsd = null, maxSeconds = null) {
+    maxOutputTokensPerCall;
+    constructor(maxSteps, maxCostUsd = null, maxSeconds = null, maxOutputTokensPerCall = null) {
         this.maxSteps = maxSteps;
         this.maxCostUsd = maxCostUsd;
         this.maxSeconds = maxSeconds;
+        this.maxOutputTokensPerCall = maxOutputTokensPerCall;
+        if (maxOutputTokensPerCall !== null && (!Number.isSafeInteger(maxOutputTokensPerCall) || maxOutputTokensPerCall < 1))
+            throw new TypeError('Output ceilings must be positive integers or null.');
     }
     static fromConfig(config, defaultSteps = 8) {
-        return new RunBudget(numberOr(config.max_steps, defaultSteps), numberOrNull(config.max_cost_usd), numberOrNull(config.max_seconds));
+        const output = config.max_output_tokens_per_call;
+        if (output !== undefined && output !== null && (typeof output !== 'number' || !Number.isSafeInteger(output) || output < 1))
+            throw new TypeError('Output ceilings must be positive integers or null.');
+        return new RunBudget(numberOr(config.max_steps, defaultSteps), numberOrNull(config.max_cost_usd), numberOrNull(config.max_seconds), output ?? null);
     }
     /**
      * The budget a CHILD actually gets, as a TREE-ABSOLUTE ceiling.
@@ -61,7 +68,7 @@ export class RunBudget {
      * should adopt.
      */
     nestedWithin(parent, ledger) {
-        return new RunBudget(Math.min(parent.maxSteps, ledger.steps + this.maxSteps), lesser(parent.maxCostUsd, this.maxCostUsd === null ? null : ledger.costUsd + this.maxCostUsd), lesser(parent.maxSeconds, this.maxSeconds === null ? null : Math.trunc(ledger.elapsedSeconds()) + this.maxSeconds));
+        return new RunBudget(Math.min(parent.maxSteps, ledger.steps + this.maxSteps), lesser(parent.maxCostUsd, this.maxCostUsd === null ? null : ledger.costUsd + this.maxCostUsd), lesser(parent.maxSeconds, this.maxSeconds === null ? null : Math.trunc(ledger.elapsedSeconds()) + this.maxSeconds), lesser(parent.maxOutputTokensPerCall, this.maxOutputTokensPerCall));
     }
 }
 /**

package/dist/task-tools.js

@@ -103,7 +103,12 @@ export function agentCompletionTool(options) {
             return { id: task.id(), state: outcome };
         },
     };
-    return (session) => authorizedTool(tool, session, authorizer);
+    return (session) => {
+        const scoped = session.agent === null ? authorizer : authorizer.forAgent(session.agent);
+        if (session.agent !== null && (!scoped.enabled || !scoped.hasCallPolicy()))
+            throw HarnessError.completionToolWithoutAuthorizer(name);
+        return authorizedTool(tool, session, scoped);
+    };
 }
 /**
  * A holder that MATCHES NO WORKER, for a task whose holder cannot be read.

package/dist/thread.d.ts

@@ -29,6 +29,8 @@ export declare class Thread {
     private readonly store;
     private readonly key;
     constructor(store: SessionStore, key: string);
+    /** Existence probe only: never starts a log, migrates data or acquires a lock. */
+    exists(): Promise<boolean>;
     messages(): Promise<ThreadMessage[]>;
     /** How many messages the thread holds. */
     count(): Promise<number>;

package/dist/thread.js

@@ -23,6 +23,12 @@ export class Thread {
         this.store = store;
         this.key = key;
     }
+    /** Existence probe only: never starts a log, migrates data or acquires a lock. */
+    async exists() {
+        if (supportsAppendLog(this.store) && await this.store.logLength(this.key) !== null)
+            return true;
+        return await this.store.get(this.key) !== null;
+    }
     async messages() {
         if (supportsAppendLog(this.store)) {
             const log = await this.store.readLog(this.key);

package/dist/tools.d.ts

@@ -23,12 +23,28 @@ export type ToolProvider = (session: Session) => Iterable<HarnessTool> | Promise
  * (`registerFactory`), and a set discovered at resolve time — an MCP server's
  * catalogue, say (`registerProvider`).
  */
+export interface ResolvedTool {
+    tool: HarnessTool;
+    owner: string;
+    source: 'static' | 'factory' | 'provider';
+}
+export interface RegistryOptions {
+    refuseDuplicates?: boolean;
+}
 export declare class ToolRegistry {
     #private;
-    register(tool: HarnessTool): this;
-    registerMany(tools: Iterable<HarnessTool>): this;
-    registerFactory(name: string, factory: ToolFactory): this;
-    registerProvider(provider: ToolProvider): this;
+    private readonly namespace;
+    private readonly root?;
+    constructor(options?: RegistryOptions | string | null, root?: ToolRegistry);
+    /** Immutable namespace views share registrations, never a current-agent flag. */
+    forAgent(agent: string | null): ToolRegistry;
+    register(tool: HarnessTool, owner?: string): this;
+    registerMany(tools: Iterable<HarnessTool>, owner?: string): this;
+    registerFactory(name: string, factory: ToolFactory, owner?: string): this;
+    registerProvider(provider: ToolProvider, owner?: string, name?: string): this;
+    replace(tool: HarnessTool, predecessorOwner: string, owner?: string): this;
+    replaceFactory(name: string, factory: ToolFactory, predecessorOwner: string, owner?: string): this;
+    replaceProvider(name: string, provider: ToolProvider, predecessorOwner: string, owner?: string): this;
     /** Every name this registry can produce without a session. */
     names(): string[];
     /**
@@ -40,12 +56,15 @@ export declare class ToolRegistry {
      * run wondering why the model never called it.
      */
     resolve(names: readonly string[], session?: Session): Promise<Map<string, HarnessTool>>;
+    /** The offer path and inspection path consume the same ownership result. */
+    resolveDetailed(names: readonly string[], session?: Session): Promise<Map<string, ResolvedTool>>;
 }
 /** Whether a tool may be OFFERED to a run. */
 export type OfferPolicy = (session: Session, tool: HarnessTool) => boolean | Promise<boolean>;
 /** Whether THIS call, with THESE arguments, may proceed. */
 export type CallPolicy = (session: Session, tool: HarnessTool, args: JsonObject) => boolean | Promise<boolean>;
 export interface ToolAuthorizerOptions {
+    agents?: Record<string, ToolAuthorizerOptions>;
     enabled?: boolean;
     offer?: OfferPolicy;
     call?: CallPolicy;
@@ -65,8 +84,12 @@ export interface ToolAuthorizerOptions {
  */
 export declare class ToolAuthorizer {
     #private;
+    private readonly namespace;
+    private readonly root?;
     readonly enabled: boolean;
-    constructor(options?: ToolAuthorizerOptions);
+    constructor(options?: ToolAuthorizerOptions, namespace?: string | null, root?: ToolAuthorizer | undefined);
+    forAgent(agent: string | null): ToolAuthorizer;
+    hasCallPolicy(): boolean;
     /** The tools a run may be offered, each wrapped so the call policy is asked again. */
     allowed(session: Session, tools: Map<string, HarnessTool>): Promise<HarnessTool[]>;
     /**