@reticlehq/server 3.6.0 → 3.7.0

package/dist/features/visual/step-shots.js

@@ -0,0 +1,231 @@
+/**
+ * A screenshot after every step: every page-touching action, every assert, every replayed step.
+ *
+ * The agent gets a PATH, never the image: reading it is the agent's choice, and an image forced
+ * into every result would cost more than every other field together. The path is named the moment
+ * the step's outcome is decided and the file lands right after, so a capture never holds a verdict
+ * back. The capture itself STARTS before this returns, which is what makes it a picture of the
+ * moment the verdict was decided rather than of whatever the next call did.
+ *
+ * Two sources, best first. `browser` is a real screenshot of a page this daemon drives (a leased
+ * tab, or the CDP provider). `rendered` is the page drawn by the SDK in-page — approximate, and
+ * labelled so. Which one the result names is a prediction from what worked last on this tab; the
+ * run's own record (`shots.jsonl`) says what actually happened. When the last attempt produced
+ * nothing at all, the next one is awaited, so the agent is told `{ error }` instead of a path to a
+ * file that will never exist.
+ *
+ * ponytail: the desktop shell's own window capture is not a source here. It returns a device-pixel
+ * PNG, and the daemon ships no JPEG encoder to shrink it to the step format; an Electron renderer
+ * draws itself fine in-page. Add it when the shells can hand back a JPEG.
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { asRecord, ReticleCommand, ScreenshotSource, STEP_SCREENSHOT, ReticleTool, } from '@reticlehq/core';
+import { runIdOfCall } from '../../judgement/runs/drive-run.js';
+import { noteLanding } from '../../judgement/runs/artifact/run-store.js';
+import { isValidRunId, stepShotDir } from '../../memory/project/dir/reticle-dir.js';
+import { UPLOAD_TEXT_MAX } from '@reticlehq/core/artifacts';
+const JPEG_EXT = '.jpg';
+const TOOL_PREFIX = /^reticle_/;
+const SEQ_WIDTH = 4;
+/** A prior capture on this tab produced nothing — see the header. */
+const NOTHING = 'none';
+/** CDP's quality scale is 0–100. */
+const CDP_QUALITY = Math.round(STEP_SCREENSHOT.JPEG_QUALITY * 100);
+/** What worked last on each tab: the next result names that source. */
+const lastSource = new Map();
+/** The next sequence number per run directory, read from its record the first time. */
+const nextSeq = new Map();
+/**
+ * Width and height from a JPEG's frame header, or undefined when the bytes are not a JPEG.
+ * Read rather than trusted: the run record and the upload both state the size.
+ */
+export function jpegSize(bytes) {
+    if (bytes.length < 4 || 0xff !== bytes[0] || 0xd8 !== bytes[1])
+        return undefined;
+    let i = 2;
+    while (i + 9 < bytes.length) {
+        if (0xff !== bytes[i])
+            return undefined;
+        const marker = bytes[i + 1] ?? 0;
+        const length = ((bytes[i + 2] ?? 0) << 8) | (bytes[i + 3] ?? 0);
+        // The start-of-frame markers carry the size; 0xC4, 0xC8 and 0xCC share the range and are not frames.
+        if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+            const height = ((bytes[i + 5] ?? 0) << 8) | (bytes[i + 6] ?? 0);
+            const width = ((bytes[i + 7] ?? 0) << 8) | (bytes[i + 8] ?? 0);
+            return width > 0 && height > 0 ? { width, height } : undefined;
+        }
+        i += 2 + length;
+    }
+    return undefined;
+}
+/** A real screenshot of a page this daemon drives, or undefined when it drives none for this tab. */
+async function browserPixels(deps, session) {
+    const opts = { jpegQuality: CDP_QUALITY, cssScale: true };
+    const leased = await deps.pool?.screenshotLease(session.id, opts);
+    if (leased !== undefined)
+        return leased;
+    // Only a provider driving THIS tab: a launched provider photographs the one page it owns whatever
+    // url it is handed, which is how a screenshot of one tab was once filed under another (#1407).
+    if (true !== (await deps.realInput?.isAvailableFor(session.url)))
+        return undefined;
+    return deps.realInput?.screenshot?.(session.url, opts);
+}
+/** The page drawn by the SDK. The answer is base64 in chunks — see `ReticleCommand.RENDER`. */
+async function renderedPixels(session) {
+    const res = await session.command(ReticleCommand.RENDER, {});
+    if (!res.ok)
+        return res.error ?? 'the page did not answer';
+    const r = asRecord(res.result);
+    if (true !== r['ok'])
+        return 'string' === typeof r['reason'] ? r['reason'] : 'render failed';
+    const chunks = Array.isArray(r['chunks']) ? r['chunks'] : [];
+    return new Uint8Array(Buffer.from(chunks.filter((c) => 'string' === typeof c).join(''), 'base64'));
+}
+/** Best source first; the first that yields a readable JPEG wins. Never throws. */
+async function capture(deps, session) {
+    const reasons = [];
+    try {
+        const real = await browserPixels(deps, session);
+        const size = real === undefined ? undefined : jpegSize(real);
+        if (real !== undefined && size !== undefined)
+            return { bytes: real, source: ScreenshotSource.BROWSER, ...size };
+    }
+    catch (error) {
+        reasons.push(error instanceof Error ? error.message : String(error));
+    }
+    try {
+        const drawn = await renderedPixels(session);
+        if ('string' === typeof drawn)
+            reasons.push(`the page could not draw itself: ${drawn}`);
+        else {
+            const size = jpegSize(drawn);
+            if (size !== undefined)
+                return { bytes: drawn, source: ScreenshotSource.RENDERED, ...size };
+            reasons.push('the page drew something that is not a JPEG');
+        }
+    }
+    catch (error) {
+        reasons.push(error instanceof Error ? error.message : String(error));
+    }
+    return `no screenshot: ${reasons.join('; ')}`;
+}
+/** Which source this tab's next result names, or undefined when the last capture got nothing. */
+async function predict(deps, session) {
+    const last = lastSource.get(session.id);
+    if (NOTHING === last)
+        return undefined;
+    if (last !== undefined)
+        return last;
+    if (true === deps.pool?.leasedSessionIds().includes(session.id))
+        return ScreenshotSource.BROWSER;
+    const driven = deps.realInput?.screenshot !== undefined &&
+        true === (await deps.realInput.isAvailableFor(session.url));
+    return driven ? ScreenshotSource.BROWSER : ScreenshotSource.RENDERED;
+}
+/** Highest sequence number this run has used, from its record — files can outlive a restart. */
+async function allocate(fs, dir) {
+    let held = nextSeq.get(dir);
+    if (held === undefined) {
+        held = fs
+            .readFile(join(dir, STEP_SCREENSHOT.MANIFEST_FILE))
+            .then((text) => {
+            const seqs = text.split('\n').map((line) => {
+                try {
+                    const seq = asRecord(JSON.parse(line))['seq'];
+                    return 'number' === typeof seq ? seq : 0;
+                }
+                catch {
+                    return 0;
+                }
+            });
+            return { n: Math.max(0, ...seqs) };
+        })
+            .catch(() => ({ n: 0 }));
+        nextSeq.set(dir, held);
+    }
+    const counter = await held;
+    counter.n += 1;
+    return counter.n;
+}
+/**
+ * Photograph the tab a step just ran on. Returns the result field; never throws, because a
+ * screenshot is evidence about a step and must never be the reason the step's answer is lost.
+ *
+ * `step` names the flow step a replay was on, as `<flow>#<index>`, so the run can pin the picture
+ * to it; `verdict` says the call produced a verdict, so the run can pair the picture with its check.
+ */
+export async function takeStepShot(deps, sessionId, tool, opts = {}) {
+    try {
+        return await shoot(deps, deps.sessions.resolve(sessionId), tool, opts);
+    }
+    catch (error) {
+        return { error: `no screenshot: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+async function shoot(deps, session, tool, { step, verdict }) {
+    const root = session.artifactRoot ?? deps.reticleRoot;
+    // Read before anything is awaited: the action this call's verdict was recorded on.
+    const actionId = true === verdict ? session.lastActionId : undefined;
+    const runId = runIdOfCall(session.id);
+    if (!isValidRunId(runId))
+        return { error: `no screenshot: unusable run id ${runId}` };
+    const dir = stepShotDir(root, runId);
+    const seq = await allocate(deps.fs, dir);
+    if (seq > STEP_SCREENSHOT.MAX_PER_RUN) {
+        return {
+            error: `no screenshot: this run already holds ${String(STEP_SCREENSHOT.MAX_PER_RUN)}, the most one run keeps`,
+        };
+    }
+    // The first capture of a tab is one nothing has vouched for yet (the in-page renderer loads on
+    // first use): it is tried again once and waited for, so its answer is a path that landed or the
+    // reason. A first act was handed a path whose file never landed.
+    const fresh = !lastSource.has(session.id);
+    // Started before anything else is awaited: the picture is of THIS moment.
+    const taken = capture(deps, session).then((pixels) => fresh && 'string' === typeof pixels ? capture(deps, session) : pixels);
+    const predicted = fresh ? undefined : await predict(deps, session);
+    const file = `${String(seq).padStart(SEQ_WIDTH, '0')}-${tool.replace(TOOL_PREFIX, '')}${JPEG_EXT}`;
+    const path = join(dir, file);
+    const land = taken.then(async (pixels) => {
+        if ('string' === typeof pixels) {
+            lastSource.set(session.id, NOTHING);
+            return;
+        }
+        lastSource.set(session.id, pixels.source);
+        try {
+            await deps.fs.mkdir(dir);
+            await deps.fs.writeFileBytes(path, pixels.bytes);
+            const record = {
+                seq,
+                file,
+                tool,
+                ...(step === undefined ? {} : { step: step.slice(0, UPLOAD_TEXT_MAX) }),
+                ...(true === verdict ? { verdict } : {}),
+                ...(actionId === undefined ? {} : { actionId }),
+                source: pixels.source,
+                width: pixels.width,
+                height: pixels.height,
+                sha256: createHash('sha256').update(pixels.bytes).digest('hex'),
+            };
+            await deps.fs.appendFile(join(dir, STEP_SCREENSHOT.MANIFEST_FILE), `${JSON.stringify(record)}\n`);
+        }
+        catch {
+            // A disk that cannot take the file loses one picture, never the step.
+        }
+    });
+    noteLanding(dir, land);
+    if (predicted !== undefined)
+        return { path, source: predicted };
+    // Nothing worked last time: wait, and tell the truth either way.
+    const pixels = await taken;
+    await land;
+    return 'string' === typeof pixels ? { error: pixels } : { path, source: pixels.source };
+}
+/** The replay hook that gives every reported flow step its screenshot, filed as `<flow>#<step>`. */
+export function replayStepShooter(deps, sessionId) {
+    return async (result, flow) => {
+        result.screenshot = await takeStepShot(deps, sessionId, ReticleTool.REPLAY, {
+            step: `${flow}#${String(result.step)}`,
+        });
+    };
+}

package/dist/features/visual/visual-tools.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { AppRuntime, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
+import { AppRuntime, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, RETICLE_TAURI_INERT_MARKER, TAURI_INERT_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { ratioSchema } from '../../surface/tools/args/numeric-bounds.js';
-import { asNumber, asRecord, asString } from '@reticlehq/core';
+import { VISUAL_PIXEL_THRESHOLD, asNumber, asRecord, asString } from '@reticlehq/core';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
 /**
@@ -43,6 +43,12 @@ const noProvider = {
     reason: VisualReason.NO_PROVIDER,
     recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
 };
+/** The answer when no pixels came back: the shell's own recommendation over the web one. */
+function unavailable(reason, recommendation) {
+    if (recommendation !== undefined)
+        return { ok: false, reason, recommendation };
+    return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
+}
 function asBox(value) {
     const b = asRecord(asRecord(value)['box']);
     const x = asNumber(b['x']);
@@ -94,8 +100,11 @@ async function desktopCapture(deps, sessionId, fullPage) {
     if (r['ok'] !== true) {
         // The shell refused a full-page capture it cannot do. That is a different answer from "capture
         // broke", and the caller has to hear it — otherwise they read `fullPage` as honoured.
-        return r['reason'] === VisualReason.FULL_PAGE_UNSUPPORTED
-            ? { reason: VisualReason.FULL_PAGE_UNSUPPORTED }
+        if (r['reason'] === VisualReason.FULL_PAGE_UNSUPPORTED)
+            return { reason: VisualReason.FULL_PAGE_UNSUPPORTED };
+        // A Tauri release build with the capture compiled out: say that, never the web answer.
+        return true === asString(r['reason'])?.includes(RETICLE_TAURI_INERT_MARKER)
+            ? { reason: VisualReason.NO_PROVIDER, recommendation: TAURI_INERT_RECOMMENDATION }
             : {};
     }
     const path = asString(r['path']);
@@ -232,7 +241,7 @@ async function capture(deps, sessionId, args) {
     if (desktop.png !== undefined)
         return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
     if (desktop.reason !== undefined)
-        return { reason: desktop.reason };
+        return desktop;
     /*
      * A LEASED page is a real browser page, so the pixels were always there — the visual tools simply
      * had no route to them. Without this, `reticle_screenshot` answered "no provider" for every context
@@ -300,10 +309,9 @@ export const VISUAL_TOOLS = [
         },
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
-            const { png, reason, runtime } = await capture(deps, sessionId, args);
-            if (png === undefined) {
-                return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
-            }
+            const { png, reason, recommendation, runtime } = await capture(deps, sessionId, args);
+            if (png === undefined)
+                return unavailable(reason, recommendation);
             const name = asString(args['name']) ?? 'default';
             // Beside the app that was captured. The tool RETURNS this path to the agent, so a wrong root
             // is not only a stray PNG — it is a path the agent is told to look at in a tree that has
@@ -337,7 +345,7 @@ export const VISUAL_TOOLS = [
             maxRatio: ratioSchema.optional(),
             threshold: ratioSchema
                 .optional()
-                .describe('Pixel difference threshold (0–1). Default: 0.01.'),
+                .describe(`Pixel difference threshold (0–1). Default: ${String(VISUAL_PIXEL_THRESHOLD)}.`),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -360,10 +368,10 @@ export const VISUAL_TOOLS = [
             // not the desktop one. Comparing across renderers is a confident wrong diff in one direction
             // and a silently overwritten baseline in the other.
             const sessionId = asString(args['sessionId']);
-            const { png: current, reason, runtime } = await capture(deps, sessionId, args);
-            if (current === undefined) {
-                return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
-            }
+            const captured = await capture(deps, sessionId, args);
+            const { png: current, runtime } = captured;
+            if (current === undefined)
+                return unavailable(captured.reason, captured.recommendation);
             // A baseline from another runtime is not missing by accident — it is a different rendering, and
             // "no baseline for this one" is the honest answer.
             const baselineBytes = await store.readBaseline(baseline, runtime);

package/dist/hooks/client-directory.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingHttpHeaders } from 'node:http';
+/** The calling client's project directory, or undefined when this call did not name one. */
+export declare function callingClientDirectory(): string | undefined;
+export declare function runWithClientDirectory<T>(directory: string, fn: () => T): T;
+/**
+ * The absolute directory a client named, or undefined when the header is absent or not a path.
+ *
+ * Relative values are dropped rather than resolved against the daemon's cwd: that would quietly
+ * turn "the client's project" back into "wherever this process was started".
+ */
+export declare function clientDirectoryFromHeader(headers: IncomingHttpHeaders): string | undefined;
+/**
+ * The directory this peer may name, or undefined.
+ *
+ * A remote client can present the pairing token, so the header is honored only from loopback.
+ * Otherwise it could point `init` at a path it chose.
+ */
+export declare function clientDirectoryFromPeer(loopback: boolean, headers: IncomingHttpHeaders): string | undefined;

package/dist/hooks/client-directory.js

@@ -0,0 +1,57 @@
+/**
+ * Which project the MCP client that is calling right now is standing in.
+ *
+ * One daemon serves every project on the machine. `everConnected` and the first-run wiring used to
+ * read the directory the daemon was started in, so a second project's first `reticle_session` was
+ * answered with the first project's closed tab. The proxy knows its own cwd, which is the project
+ * the agent launched it from, and the HTTP door puts it on this context for the call.
+ *
+ * Same shape as `driven-by`: set around the request, read wherever the call is answered, gone when
+ * the call is. Absent means an in-process caller that has no separate project, and the daemon's own
+ * directory is still the answer.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { isAbsolute, resolve } from 'node:path';
+import { MCP_CLIENT_DIRECTORY_HEADER } from '@reticlehq/core';
+const current = new AsyncLocalStorage();
+/** The calling client's project directory, or undefined when this call did not name one. */
+export function callingClientDirectory() {
+    return current.getStore();
+}
+export function runWithClientDirectory(directory, fn) {
+    return current.run(resolve(directory), fn);
+}
+/**
+ * The absolute directory a client named, or undefined when the header is absent or not a path.
+ *
+ * Relative values are dropped rather than resolved against the daemon's cwd: that would quietly
+ * turn "the client's project" back into "wherever this process was started".
+ */
+export function clientDirectoryFromHeader(headers) {
+    const raw = headers[MCP_CLIENT_DIRECTORY_HEADER];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if ('string' !== typeof value)
+        return undefined;
+    // The proxy percent-encodes the path. A raw absolute path still decodes to itself.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isAbsolute(decoded))
+        return undefined;
+    return resolve(decoded);
+}
+/**
+ * The directory this peer may name, or undefined.
+ *
+ * A remote client can present the pairing token, so the header is honored only from loopback.
+ * Otherwise it could point `init` at a path it chose.
+ */
+export function clientDirectoryFromPeer(loopback, headers) {
+    if (!loopback)
+        return undefined;
+    return clientDirectoryFromHeader(headers);
+}

package/dist/hooks/coding-agents.d.ts

@@ -0,0 +1,34 @@
+import { AgentClient } from '@reticlehq/core/telemetry';
+export declare function agentLabel(name: string): string;
+/** The closed telemetry value for a client name: never the name itself, which is the client's text. */
+export declare function agentClientOf(name: string | undefined): AgentClient | undefined;
+/** An MCP connection finished its handshake as `name`. */
+export declare function noteAgentAttached(attachId: string, name: string): void;
+/** That connection closed. */
+export declare function noteAgentDetached(attachId: string): void;
+/** The friendly names of the agents attached now, each once. */
+export declare function connectedAgents(): string[];
+/** Hear an agent attach or leave. Returns the unsubscribe. */
+export declare function onAgentsChange(listener: () => void): () => void;
+/** Run a tool call as the agent on connection `attachId`, so what it reads is credited to it. */
+export declare function runAsAgent<T>(attachId: string | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * The agent the current call came from; else the only agent attached; else undefined. Two agents
+ * and no call to say which is unknown, never a guess.
+ */
+export declare function callingAgent(): string | undefined;
+/** The MCP connection the current call came over, or undefined outside one. */
+export declare function callingAttachId(): string | undefined;
+/**
+ * The client whose call this is, and nobody else: no fallback to the only agent attached. A run or
+ * a journaled action is credited by this — a dashboard Re-verify, which no agent made, was credited
+ * to `claude-code` because it was the client last connected.
+ */
+export declare function callerClientName(): string | undefined;
+/**
+ * The raw client name behind `callingAgent()` — the id a run is credited to, the same string
+ * `mcpClientIdentity()` reports, so one agent is one facet on the dashboard.
+ */
+export declare function callingClientName(): string | undefined;
+/** Tests only. */
+export declare function forgetAgents(): void;

package/dist/hooks/coding-agents.js

@@ -0,0 +1,117 @@
+/**
+ * Which coding agents are attached to this daemon, and which one the current tool call came from.
+ *
+ * Read from MCP `initialize` (`clientInfo.name`), the only honest source: see `client-identity.ts`.
+ * Kept per connection, so the HUD can say "Connected: Claude Code" and a note it sent can be marked
+ * as seen by the agent whose call actually took it. A pure sink, like the rest of `hooks/`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { AgentClient } from '@reticlehq/core/telemetry';
+/**
+ * Friendly names for the clients people know, matched as a lowercase substring of the name the
+ * client sent, and the closed telemetry value each one reports as. Ordered: `cursor-vscode` is
+ * Cursor, not VS Code. Anything else keeps its own name, and reports as `other`.
+ */
+const AGENT_LABELS = [
+    ['claude-code', 'Claude Code', AgentClient.CLAUDE_CODE],
+    ['claude-ai', 'Claude Desktop', AgentClient.CLAUDE_DESKTOP],
+    ['codex', 'Codex', AgentClient.CODEX],
+    ['cursor', 'Cursor', AgentClient.CURSOR],
+    ['gemini', 'Gemini CLI', AgentClient.GEMINI_CLI],
+    ['antigravity', 'Antigravity', AgentClient.ANTIGRAVITY],
+    ['windsurf', 'Windsurf', AgentClient.WINDSURF],
+    ['cline', 'Cline', AgentClient.CLINE],
+    ['opencode', 'OpenCode', AgentClient.OPENCODE],
+    ['zed', 'Zed', AgentClient.ZED],
+    ['visual studio code', 'VS Code', AgentClient.VSCODE],
+    ['vscode', 'VS Code', AgentClient.VSCODE],
+];
+const MAX_LABEL = 64;
+/** The name each connection's handshake sent, verbatim; labels are derived on read. */
+const byAttach = new Map();
+const listeners = new Set();
+const calling = new AsyncLocalStorage();
+function knownAgent(name) {
+    const lower = name.toLowerCase();
+    return AGENT_LABELS.find(([needle]) => lower.includes(needle));
+}
+export function agentLabel(name) {
+    return (knownAgent(name)?.[1] ?? name).slice(0, MAX_LABEL);
+}
+/** The closed telemetry value for a client name: never the name itself, which is the client's text. */
+export function agentClientOf(name) {
+    if (name === undefined || 0 === name.trim().length)
+        return undefined;
+    return knownAgent(name)?.[2] ?? AgentClient.OTHER;
+}
+/** An MCP connection finished its handshake as `name`. */
+export function noteAgentAttached(attachId, name) {
+    byAttach.set(attachId, name);
+    changed();
+}
+/** That connection closed. */
+export function noteAgentDetached(attachId) {
+    if (byAttach.delete(attachId))
+        changed();
+}
+/** The friendly names of the agents attached now, each once. */
+export function connectedAgents() {
+    return [...new Set([...byAttach.values()].map(agentLabel))];
+}
+/** Hear an agent attach or leave. Returns the unsubscribe. */
+export function onAgentsChange(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+/** Run a tool call as the agent on connection `attachId`, so what it reads is credited to it. */
+export function runAsAgent(attachId, fn) {
+    return attachId === undefined ? fn() : calling.run(attachId, fn);
+}
+/**
+ * The agent the current call came from; else the only agent attached; else undefined. Two agents
+ * and no call to say which is unknown, never a guess.
+ */
+export function callingAgent() {
+    const name = callingClientName();
+    return name === undefined ? undefined : agentLabel(name);
+}
+/** The MCP connection the current call came over, or undefined outside one. */
+export function callingAttachId() {
+    return calling.getStore();
+}
+/**
+ * The client whose call this is, and nobody else: no fallback to the only agent attached. A run or
+ * a journaled action is credited by this — a dashboard Re-verify, which no agent made, was credited
+ * to `claude-code` because it was the client last connected.
+ */
+export function callerClientName() {
+    const own = calling.getStore();
+    return own === undefined ? undefined : byAttach.get(own);
+}
+/**
+ * The raw client name behind `callingAgent()` — the id a run is credited to, the same string
+ * `mcpClientIdentity()` reports, so one agent is one facet on the dashboard.
+ */
+export function callingClientName() {
+    const own = calling.getStore();
+    const name = own === undefined ? undefined : byAttach.get(own);
+    if (name !== undefined)
+        return name;
+    const all = [...new Set(byAttach.values())];
+    return 1 === all.length ? all[0] : undefined;
+}
+/** Tests only. */
+export function forgetAgents() {
+    byAttach.clear();
+    listeners.clear();
+}
+function changed() {
+    for (const listener of listeners) {
+        try {
+            listener();
+        }
+        catch {
+            /* a listener never breaks the connection it listens to */
+        }
+    }
+}

package/dist/hooks/driven-by.d.ts

@@ -1,4 +1,23 @@
-import type { DrivenBy } from '@reticlehq/core';
-export declare function runDrivenBy<T>(by: DrivenBy, fn: () => Promise<T>): Promise<T>;
+import { type DrivenBy, type OutwardAction } from '@reticlehq/core';
+export declare function runDrivenBy<T>(by: DrivenBy, fn: () => Promise<T>, 
+/** What the PERSON asked for, in their own words: the only text that allows an outward action. */
+asked?: string): Promise<T>;
 /** The Harness drive this call is part of, or undefined when the connected agent made it. */
 export declare function currentDrivenBy(): DrivenBy | undefined;
+/**
+ * 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 declare function bindDrivenBy<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+/** Replay a saved flow: its outward steps are the journey, not a model's choice. */
+export declare function runSavedFlow<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function harnessOutwardAllowed(): OutwardAction[] | undefined;

package/dist/hooks/driven-by.js

@@ -1,4 +1,5 @@
 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.
  *
@@ -7,10 +8,49 @@ import { AsyncLocalStorage } from 'node:async_hooks';
  * 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) {
-    return current.run(by, fn);
+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()));
+}