@particle-academy/prism-harness 0.9.1 → 0.10.0

package/README.md

@@ -58,9 +58,17 @@ 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.
+The mode list is the ceiling for named and legacy sessions. Caller-supplied
+names narrow it; omitting names uses the mode's full list, and an empty list
+offers no tools. A requested `*` selects the mode's ceiling. Other names outside
+the ceiling fail before the model is called.
+
+Legacy callers that intentionally need the previous replacement behavior can
+set `AgentRuntimeOptions.allowLegacyToolListWidening` to `true`. This permits
+widening only in the legacy namespace; the configured authorizer still filters
+the offer and tool calls. Named agents always retain their ceiling. Remove an
+old explicit `narrowRequestedTools: false`: it now raises a migration error.
+Explicit `true` remains supported, and conflicts with the widening opt-out.
 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')
@@ -393,6 +401,13 @@ badly.
   native boot/PID realm and a proven dead or explicitly released owner. Local
   filesystems on one host only; SMB/NFS are unsupported.
 
+  State readers close their handles before decoding the document. On Windows,
+  replacement of a state file can fail while another process holds it open,
+  even with delete sharing. Permission failures retry for up to 750 ms. If the
+  reader stays open or access is permanently denied, the original native error
+  is raised and the temporary file is removed; the previous state stays intact.
+  Other errors and POSIX replacement do not retry. Callbacks are never replayed.
+
   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

package/dist/runtime.d.ts

@@ -110,8 +110,10 @@ export interface PendingApproval {
     arguments: JsonObject;
 }
 export interface AgentRuntimeOptions {
-    /** Legacy compatibility default. Named agents always enforce their mode ceiling. */
+    /** Explicit true retains strict behavior. Explicit false now requires migration to the widening opt-out. */
     narrowRequestedTools?: boolean;
+    /** Permit caller names to replace a LEGACY session's mode list. Named agents remain strict; authorizers still apply. */
+    allowLegacyToolListWidening?: boolean;
     config?: RuntimeConfig;
     agents?: Record<string, RuntimeConfig>;
     client: LlmClient;

package/dist/runtime.js

@@ -39,7 +39,13 @@ export class AgentRuntime {
     constructor(options) {
         if (options.narrowRequestedTools !== undefined && typeof options.narrowRequestedTools !== 'boolean')
             throw new TypeError('narrowRequestedTools must be a boolean');
-        this.#narrowRequestedTools = options.narrowRequestedTools ?? false;
+        if (options.allowLegacyToolListWidening !== undefined && typeof options.allowLegacyToolListWidening !== 'boolean')
+            throw new TypeError('allowLegacyToolListWidening must be a boolean');
+        if (options.narrowRequestedTools === false)
+            throw new TypeError('narrowRequestedTools: false is no longer supported. Remove it; use allowLegacyToolListWidening: true only to explicitly permit legacy tool-list widening.');
+        if (options.narrowRequestedTools === true && options.allowLegacyToolListWidening === true)
+            throw new TypeError('narrowRequestedTools: true conflicts with allowLegacyToolListWidening: true.');
+        this.#narrowRequestedTools = options.allowLegacyToolListWidening !== true;
         this.#client = options.client;
         this.#modes = options.modes;
         this.#tools = options.tools;

package/dist/stores/file-owner-lock.js

@@ -126,6 +126,9 @@ async function inspect(lockPath, local) {
             return 'held';
         if (!owner.released && !lockPidIsDead(owner.pid))
             return 'held';
+        // A proven stale owner's temporary file may still be open on Windows.
+        // Cleanup errors use inspection's held handling and the existing wait budget.
+        await cleanFileLockOwner(lockPath, owner, temporary);
     }
     catch (error) {
         if (code(error) === 'ENOENT')
@@ -134,7 +137,6 @@ async function inspect(lockPath, local) {
             return 'held';
         throw error;
     }
-    await cleanFileLockOwner(lockPath, owner, temporary);
     return 'retry';
 }
 async function release(progress) {

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

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
 import { mkdir, open, readFile, rename, rm, stat, truncate, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { isJsonObject } from '../json.js';
 import { HarnessError } from '../errors.js';
 import { withFileOwnerLock, pendingFileOwnerReleases } from './file-owner-lock.js';
@@ -52,6 +53,8 @@ export class FileSessionStore {
     async get(key) {
         let raw;
         try {
+            // Node's whole-file helper closes its own handle on both outcomes before
+            // resolving; JSON decoding and expiry housekeeping happen after it closes.
             raw = await readFile(this.#pathFor(key), 'utf8');
         }
         catch (error) {
@@ -91,7 +94,7 @@ export class FileSessionStore {
         try {
             // Atomic on both POSIX and Windows. A reader either sees the whole old
             // payload or the whole new one, never half of either.
-            await rename(temporary, target);
+            await replaceStateFile(temporary, target);
         }
         catch (error) {
             await rm(temporary, { force: true });
@@ -255,3 +258,36 @@ function digestOf(key) {
 function isMissing(error) {
     return typeof error === 'object' && error !== null && error.code === 'ENOENT';
 }
+/** An open Windows target can block replacement even with delete sharing. */
+async function replaceStateFile(temporary, target) {
+    try {
+        await rename(temporary, target);
+        return;
+    }
+    catch (original) {
+        if (process.platform !== 'win32' || !isReplacePermissionError(original))
+            throw original;
+        const deadline = performance.now() + 750;
+        while (true) {
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                throw original;
+            // This timer stays referenced: an awaited write must keep the process alive.
+            await delay(Math.min(10, remaining));
+            if (performance.now() >= deadline)
+                throw original;
+            try {
+                await rename(temporary, target);
+                return;
+            }
+            catch (error) {
+                if (!isReplacePermissionError(error))
+                    throw error;
+            }
+        }
+    }
+}
+function isReplacePermissionError(error) {
+    const code = typeof error === 'object' && error !== null ? error.code : undefined;
+    return code === 'EPERM' || code === 'EACCES';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,
@@ -25,7 +25,8 @@
   "devDependencies": {
     "@types/node": "^26.3.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11"
+    "vite": "^8.3.5",
+    "vitest": "^4.1.12"
   },
   "repository": {
     "type": "git",