@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/harness-toolset.d.ts

@@ -7,6 +7,7 @@
  * is missing a tool and THAT is the bug. Every capability a harness run proves is one a user's own
  * agent can reach.
  */
+import { type DrivenBy } from '@reticlehq/core';
 import { type ToolDeps } from './tools.js';
 import type { HarnessToolset } from '../../features/harness/harness.js';
 export interface ReticleToolsetOptions {
@@ -14,6 +15,12 @@ export interface ReticleToolsetOptions {
     sessionId?: string;
     /** Restrict to these names. Defaults to the advertised surface plus the recording pair. */
     only?: readonly string[];
+    /** Stamped on every action this drive journals, so its verdicts fold into a run of their own. */
+    drivenBy?: DrivenBy;
+    /** The person's own request: the only text that lets the drive press an outward control. */
+    asked?: string;
+    /** The pinned session wins over any a call names: a remote caller never reaches another tab. */
+    locked?: boolean;
 }
 /**
  * Bind the live tool surface to a set of dependencies.
@@ -23,6 +30,12 @@ export interface ReticleToolsetOptions {
  * a harness run a measurement of the product rather than of a test harness.
  */
 export declare function reticleToolset(deps: ToolDeps, options?: ReticleToolsetOptions): HarnessToolset;
+/**
+ * A request the Harness declares must succeed (`ok: true`) unless its claim names a status. A net
+ * claim with no status is met by any answer, so a sign-in whose `POST /api/login` came back 401 was
+ * counted as a check that held. Applied to the top-level claim of a wait or an assert.
+ */
+export declare function requestMustSucceed(args: Record<string, unknown>): Record<string, unknown>;
 /**
  * Stamp the drive's own session onto a call.
  *
@@ -32,4 +45,12 @@ export declare function reticleToolset(deps: ToolDeps, options?: ReticleToolsetO
  * ids, and silently overwriting one would make a deliberate cross-tab call lie about which tab it
  * read.
  */
-export declare function pinSession(args: Record<string, unknown>, sessionId: string | undefined): Record<string, unknown>;
+export declare function pinSession(args: Record<string, unknown>, sessionId: string | undefined, locked?: boolean): Record<string, unknown>;
+/**
+ * A desktop app's backend is its IPC: a claim that the app writes to its backend means that call.
+ *
+ * Reported from a chat-requested drive of a Tauri app: the platform claimed a POST for Add, the app
+ * made the same write as `ipc://add_todo` (200), and the step was graded `no`. Only a MUTATING method
+ * is read this way; a read, an unbound request and every other kind keep their meaning.
+ */
+export declare function desktopBackendClaims(args: Record<string, unknown>): Record<string, unknown>;

package/dist/surface/tools/harness-toolset.js

@@ -9,11 +9,13 @@
  */
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { ReticleTool } from '@reticlehq/core';
+import { AppRuntime, ConsequenceKind, NetInitiator, PredicateKind, ReticleTool, } from '@reticlehq/core';
 import { TOOLS } from './tools.js';
 import { runTool } from './invoke-tool.js';
 import { TOOL_SURFACE, filterTools } from './tool-surface.js';
 import { withTimeout } from '../../features/harness/with-timeout.js';
+import { runDrivenBy } from '../../hooks/driven-by.js';
+import { noteDriveStep } from '../../features/harness/drive-runs.js';
 /**
  * The two tools the harness is given beyond the advertised surface.
  *
@@ -24,7 +26,7 @@ import { withTimeout } from '../../features/harness/with-timeout.js';
  * sometimes skip, which silently turns the cheap path off.
  */
 /**
- * Beyond the default surface, the three tools a drive cannot do its job without.
+ * Beyond the default surface, the tools a drive cannot do its job without.
  *
  * RECORD and FLOW_SAVE are how a drive keeps what it drove. FLOW_REPLAY is how it avoids driving
  * the same thing twice — it was absent, so a driver handed a plan full of already-recorded journeys
@@ -34,6 +36,9 @@ const HARNESS_EXTRA_TOOLS = [
     ReticleTool.RECORD,
     ReticleTool.FLOW_SAVE,
     ReticleTool.FLOW_REPLAY,
+    // A goal below the fold stayed `unknown` on a drive told to scroll to it: nothing it was offered
+    // could scroll. This one brings an element into view by the same query a find uses.
+    ReticleTool.SCROLL_TO,
 ];
 /**
  * The one deliberate subtraction.
@@ -43,6 +48,34 @@ const HARNESS_EXTRA_TOOLS = [
  * meant to protect.
  */
 const HARNESS_EXCLUDED = new Set([ReticleTool.FEEDBACK]);
+/**
+ * All a locked (remote) drive may run: reading and driving the one tab it was given, and keeping or
+ * replaying what it drove there. Nothing that lists other tabs, opens a browser, spends the local
+ * model, deletes saved work or sends a picture the person did not ask to send.
+ */
+const REMOTE_TOOLS = new Set([
+    ReticleTool.LOOK,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.NAVIGATE,
+    ReticleTool.REFRESH,
+    ReticleTool.ACT,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.OBSERVE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.WAIT_READY,
+    ReticleTool.SCROLL_TO,
+    ReticleTool.ASSERT,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.STATE,
+    ReticleTool.RECORD,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+    ReticleTool.RUN,
+]);
 /**
  * Parameters the model is never asked for, because the harness supplies them.
  *
@@ -93,7 +126,7 @@ function toHarnessTool(tool) {
  * a harness run a measurement of the product rather than of a test harness.
  */
 export function reticleToolset(deps, options = {}) {
-    const usable = TOOLS.filter((tool) => !HARNESS_EXCLUDED.has(tool.name));
+    const usable = TOOLS.filter((tool) => !HARNESS_EXCLUDED.has(tool.name) && (true !== options.locked || REMOTE_TOOLS.has(tool.name)));
     /**
      * Everything callable, whether or not it is advertised. `reticle_run` dispatches against this, so
      * trimming the ADVERTISED list never trims what a drive can reach.
@@ -115,11 +148,36 @@ export function reticleToolset(deps, options = {}) {
                 // list, and this is the same recovery the MCP surface gives an agent that does the same.
                 return { error: `unknown tool ${target ?? name}`, available: [...byName.keys()] };
             }
-            const scoped = pinSession(targetArgs, options.sessionId);
-            return withTimeout(runTool(tool, deps, scoped), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
+            const pinned = pinSession(options.drivenBy === undefined ? targetArgs : requestMustSucceed(targetArgs), options.sessionId, true === options.locked);
+            const scoped = isDesktopSession(deps, pinned['sessionId'])
+                ? desktopBackendClaims(pinned)
+                : pinned;
+            const drivenBy = options.drivenBy;
+            if (drivenBy !== undefined)
+                noteDriveStep(drivenBy.harness, tool.name);
+            return withTimeout(drivenBy === undefined
+                ? runTool(tool, deps, scoped)
+                : runDrivenBy(drivenBy, () => runTool(tool, deps, scoped), options.asked), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
         },
     };
 }
+/**
+ * A request the Harness declares must succeed (`ok: true`) unless its claim names a status. A net
+ * claim with no status is met by any answer, so a sign-in whose `POST /api/login` came back 401 was
+ * counted as a check that held. Applied to the top-level claim of a wait or an assert.
+ */
+export function requestMustSucceed(args) {
+    const out = { ...args };
+    for (const key of ['until', 'predicate']) {
+        const claim = args[key];
+        if ('object' !== typeof claim || null === claim)
+            continue;
+        const p = claim;
+        if (PredicateKind.NET === p['kind'] && undefined === p['status'] && undefined === p['ok'])
+            out[key] = { ...p, ok: true };
+    }
+    return out;
+}
 /**
  * Stamp the drive's own session onto a call.
  *
@@ -129,11 +187,47 @@ export function reticleToolset(deps, options = {}) {
  * ids, and silently overwriting one would make a deliberate cross-tab call lie about which tab it
  * read.
  */
-export function pinSession(args, sessionId) {
-    if (sessionId === undefined || 'sessionId' in args)
+export function pinSession(args, sessionId, locked = false) {
+    if (sessionId === undefined || (!locked && 'sessionId' in args))
         return args;
     return { ...args, sessionId };
 }
+/** The HTTP methods a "saves" or "updates" claim names: a write to the app's backend. */
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+function isDesktopSession(deps, sessionId) {
+    try {
+        const runtime = deps.sessions.resolve('string' === typeof sessionId ? sessionId : undefined).runtime;
+        return AppRuntime.ELECTRON === runtime || AppRuntime.TAURI === runtime;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A desktop app's backend is its IPC: a claim that the app writes to its backend means that call.
+ *
+ * Reported from a chat-requested drive of a Tauri app: the platform claimed a POST for Add, the app
+ * made the same write as `ipc://add_todo` (200), and the step was graded `no`. Only a MUTATING method
+ * is read this way; a read, an unbound request and every other kind keep their meaning.
+ */
+export function desktopBackendClaims(args) {
+    const rewrite = (value) => {
+        if (Array.isArray(value))
+            return value.map(rewrite);
+        if ('object' !== typeof value || null === value)
+            return value;
+        const record = value;
+        const method = record['method'];
+        const ipc = ConsequenceKind.NET === record['kind'] &&
+            'string' === typeof method &&
+            MUTATING_METHODS.has(method.toUpperCase());
+        return Object.fromEntries(Object.entries(record).map(([key, inner]) => [
+            key,
+            ipc && 'method' === key ? NetInitiator.IPC : rewrite(inner),
+        ]));
+    };
+    return rewrite(args);
+}
 function asName(value) {
     return 'string' === typeof value && value.length > 0 ? value : undefined;
 }

package/dist/surface/tools/human-notes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The notes a person sent from the HUD, handed to the agent on whatever Reticle call it makes next.
+ *
+ * Act tools already splice them (`withControl`); every other tool did not, so a note waited until
+ * the agent happened to drive the page or poll `messages`. Taken here, once, from the tab the call
+ * is about; a call that names no tab and cannot resolve one takes every tab's, since a note held
+ * back is a note the person believes was read.
+ */
+import type { Session } from '../../portal/session/session.js';
+import type { SessionManager } from '../../portal/session/session-manager.js';
+import type { SessionState } from '@reticlehq/core';
+export interface HumanNotes {
+    state: SessionState;
+    guidance: string[];
+}
+export declare function takeHumanNotes(sessions: SessionManager, sessionId: string | undefined, session: Session | undefined): HumanNotes | undefined;

package/dist/surface/tools/human-notes.js

@@ -0,0 +1,27 @@
+export function takeHumanNotes(sessions, sessionId, session) {
+    let target = session;
+    if (target === undefined) {
+        try {
+            target = sessions.resolve(sessionId);
+        }
+        catch {
+            target = undefined;
+        }
+    }
+    // ponytail: an unresolvable call takes every tab's notes; per-agent routing is the upgrade if two
+    // agents ever share one daemon on different apps and a note lands with the wrong one.
+    try {
+        const holding = (target === undefined ? (sessions.all?.() ?? []) : [target]).filter((tab) => 0 < tab.inboxSize());
+        const first = holding[0];
+        if (first === undefined)
+            return undefined;
+        return {
+            state: first.getState(),
+            guidance: holding.flatMap((tab) => tab.drainInbox().map((message) => message.text)),
+        };
+    }
+    catch {
+        // A courtesy on every call is never the reason a call fails; the notes stay queued.
+        return undefined;
+    }
+}

package/dist/surface/tools/invoke-tool.d.ts

@@ -1,4 +1,5 @@
-import type { ToolDef, ToolDeps } from './tool-kit.js';
+import { type NoticeFold } from './agent/notices.js';
+import type { ToolCall, ToolDef, ToolDeps } from './tool-kit.js';
 export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
 /**
  * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
@@ -7,4 +8,6 @@ export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
  * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
  */
 export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
-export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
+export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, given: Record<string, unknown>, call?: ToolCall): Promise<unknown>;
+/** Advisories that become once-per-session notice lines. See agent/notices.ts. */
+export declare const NOTICE_FOLD: NoticeFold;