@reticlehq/server 3.5.0 → 3.7.0

package/dist/hooks/driven-by.js

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { outwardActionsAsked } from '@reticlehq/core';
+/**
+ * Which Harness drive the current tool call belongs to, carried across every await under it.
+ *
+ * The Harness dispatches through the same tools an agent calls, so nothing in a tool's arguments can
+ * say who called it, and adding a field to every tool's schema would advertise it to every agent.
+ * The context is set once around each Harness call and read where the journal writes the action.
+ */
+const current = new AsyncLocalStorage();
+export function runDrivenBy(by, fn, 
+/** What the PERSON asked for, in their own words: the only text that allows an outward action. */
+asked) {
+    return current.run(by, () => (asked === undefined ? fn() : askedStore.run(asked, fn)));
+}
+/** The person's own request for the Harness drive running now, when they made one. */
+const askedStore = new AsyncLocalStorage();
+/** The Harness drive this call is part of, or undefined when the connected agent made it. */
+export function currentDrivenBy() {
+    return current.getStore();
+}
+/**
+ * Bind a callback to the Harness drive running NOW, so it is still the Harness's when it fires later.
+ *
+ * A wait re-checks its predicate from a page-event listener and a timer, outside the awaited chain,
+ * where this context does not reach. Those re-checks went to the page untagged and the HUD filed the
+ * Harness's own "Finding…" rows in the Agent Log. Returns `fn` unchanged outside a drive.
+ */
+export function bindDrivenBy(fn) {
+    const by = current.getStore();
+    if (by === undefined)
+        return fn;
+    return (...args) => {
+        current.run(by, () => fn(...args));
+    };
+}
+/** Set while a SAVED flow replays: its steps were asked for by whoever recorded them. */
+const savedFlow = new AsyncLocalStorage();
+/** Replay a saved flow: its outward steps are the journey, not a model's choice. */
+export function runSavedFlow(fn) {
+    return savedFlow.run(true, fn);
+}
+/**
+ * The outward actions (invite, send, delete, pay…) this call may take, or undefined when it is not
+ * gated: an agent's call, or a saved flow's step. A Harness call a model or a planner chose may take
+ * only what its journey asks for in so many words — the Harness pressed Invite in a customer's
+ * workspace when its journey said "she does not send an invite".
+ */
+export function harnessOutwardAllowed() {
+    const by = current.getStore();
+    if (by === undefined || true === savedFlow.getStore())
+        return undefined;
+    // The person's words, never a planner's: a plan the platform invented ("press Invite") is not a
+    // request anybody made.
+    return outwardActionsAsked(askedStore.getStore() ?? '');
+}

package/dist/hooks/hook-bus.d.ts

@@ -51,3 +51,7 @@ export declare function emitHook(payload: HookPayload): void;
 export declare function hookListenerCount(event: HookEventName): number;
 /** Drop every listener. Tests, and a daemon tearing down its own wiring. */
 export declare function resetHooks(): void;
+/** Register "write what is pending now". Returns the unregister. */
+export declare function onPendingWrites(flush: () => Promise<void>): () => void;
+/** Write everything held back, now. */
+export declare function flushPendingWrites(): Promise<void>;

package/dist/hooks/hook-bus.js

@@ -104,3 +104,21 @@ export function resetHooks() {
     everyEvent.clear();
     reported.clear();
 }
+/**
+ * Writes held back on a timer, which a push must see through before it sends anything.
+ *
+ * A drive's run is written a few seconds after its last verdict, so a burst is folded once. A push
+ * asked for straight after a drive (`session end`, then `reticle_project { push: true }`) found no
+ * run to send and answered "0 of 0"; the run landed seconds later. A pure sink, like the rest of
+ * `hooks/`: the writer registers, the pusher flushes, neither imports the other.
+ */
+const flushers = new Set();
+/** Register "write what is pending now". Returns the unregister. */
+export function onPendingWrites(flush) {
+    flushers.add(flush);
+    return () => flushers.delete(flush);
+}
+/** Write everything held back, now. */
+export async function flushPendingWrites() {
+    await Promise.all([...flushers].map((flush) => flush()));
+}

package/dist/hooks/hook-commands.js

@@ -21,7 +21,7 @@
  * broken gets a log line; their verdicts keep working.
  */
 import { spawn } from 'node:child_process';
-import { readFileSync, statSync } from 'node:fs';
+import { closeSync, fstatSync, openSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { HOOK_EVENT_NAMES, HookConfigSchema } from '@reticlehq/core/hooks';
 import { ReticleDir } from '@reticlehq/core';
@@ -65,18 +65,29 @@ let cached;
  */
 export function readHookConfig(reticleRoot) {
     const path = join(reticleRoot, ReticleDir.HOOKS_FILE);
-    let mtime;
+    // Open once, then stat and read the SAME descriptor: the mtime the cache keys on is the mtime of
+    // the bytes read, not of whatever the path pointed at a moment earlier.
+    let fd;
     try {
-        mtime = statSync(path).mtimeMs;
+        fd = openSync(path, 'r');
     }
     catch {
         cached = undefined;
         return {};
     }
+    try {
+        return readOpenHookConfig(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readOpenHookConfig(fd) {
+    const mtime = fstatSync(fd).mtimeMs;
     if (cached !== undefined && cached.at === mtime)
         return cached.config;
     try {
-        const parsed = HookConfigSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+        const parsed = HookConfigSchema.safeParse(JSON.parse(readFileSync(fd, 'utf8')));
         if (!parsed.success) {
             reportOnce(`config:${String(mtime)}`, `${ReticleDir.HOOKS_FILE} is not a map of event→command`);
             cached = { at: mtime, config: {} };

package/dist/hooks/tool-log.d.ts

@@ -0,0 +1,9 @@
+export declare function toolLogPath(): string | undefined;
+export declare function logToolCall(path: string, entry: {
+    tool: string;
+    args: unknown;
+    at: number;
+    ms: number;
+    result?: unknown;
+    error?: string;
+}): void;

package/dist/hooks/tool-log.js

@@ -0,0 +1,29 @@
+import { appendFileSync } from 'node:fs';
+import { currentDrivenBy } from './driven-by.js';
+/**
+ * Every tool call, its arguments and what it answered, appended to a file a person names.
+ *
+ * Off unless `RETICLE_TOOL_LOG` is set. It exists to put two drives side by side (an agent's and
+ * the Harness's) and read what each one asked and was told; `drivenBy` says which was which. Local
+ * only: nothing here leaves the machine.
+ */
+const TOOL_LOG_ENV = 'RETICLE_TOOL_LOG';
+/** A page snapshot can be large; past this a record keeps its head and says it was cut. */
+const MAX_RESULT_CHARS = 200_000;
+export function toolLogPath() {
+    const path = process.env[TOOL_LOG_ENV];
+    return path === undefined || 0 === path.trim().length ? undefined : path;
+}
+export function logToolCall(path, entry) {
+    try {
+        const text = JSON.stringify(entry.result ?? null);
+        const result = text.length > MAX_RESULT_CHARS
+            ? { truncated: text.slice(0, MAX_RESULT_CHARS) }
+            : entry.result;
+        const drivenBy = currentDrivenBy();
+        appendFileSync(path, `${JSON.stringify({ ...entry, result, ...(drivenBy === undefined ? {} : { drivenBy }) })}\n`);
+    }
+    catch {
+        /* a log that cannot be written never fails the call it describes */
+    }
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { StartOptions } from './start-options.js';
 export type { StartOptions } from './start-options.js';
 import { Bridge } from './portal/bridge/bridge.js';
 import type { RealInputProvider } from './portal/input/real-input.js';
+export { replayVerdictLine } from './language/flows/replay-from-hud.js';
 export { ReticleTool } from '@reticlehq/core';
 export { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
 export { Bridge } from './portal/bridge/bridge.js';
@@ -74,6 +75,7 @@ export interface RunningServer {
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './portal/bridge/bridge-security.js';
+/** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 export declare function start(options?: StartOptions): Promise<RunningServer>;
 /**
  * Start the Reticle bridge in daemon mode: a single HTTP server handles both the WebSocket