@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/next-step.js

@@ -0,0 +1,214 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { keyRefusalAtLastSync } from '../../memory/project/sync-status.js';
+import { join } from 'node:path';
+import { ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { DRIVE_RECORD_SUFFIX } from '../../memory/project/dir/reticle-dir.js';
+import { callingAttachId } from '../../hooks/coding-agents.js';
+/**
+ * The one thing the agent should do next, on the result of the call it just made.
+ *
+ * Every client reads tool results; few read a briefing twice, and none keep a skill in mind across a
+ * long session. So what an agent must not forget (record what the user asked, hand the tab back,
+ * notice when its runs are not reaching the platform) is said where
+ * the agent is already looking, one short line, on the moment it applies. It is placed first in the
+ * result, because a model that truncates a long result keeps its beginning.
+ *
+ * The daemon syncs runs itself, whichever agent drove them; nothing here asks an agent to push.
+ * It only says when the sync needs a person (a refusal, a failure, a project never connected).
+ */
+/** How long a declared request counts as "the current task". Matches the run store's window. */
+const REQUEST_FRESH_MS = 6 * 60 * 60 * 1000;
+/** A reminder that is not about a verdict is repeated at most this often, per project. */
+const QUIET_CALLS = 10;
+/**
+ * How often the agent is asked to record the request before the other lines get their turn. In
+ * every recorded run the agent ignored it, and because it always won, no agent was ever told its
+ * runs were not reaching the platform.
+ */
+const DECLARE_ASKS = 2;
+/** A run file this much newer than the last push, and this old, was not sent. */
+const UNSENT_AFTER_MS = 2 * 60 * 1000;
+export const NextText = {
+    DECLARE: 'Record what the user asked, once per task, verbatim: reticle_run { tool: "reticle_intent", args: { action: "declare", request: "<their words>" } }. It travels with every run.',
+    SYNC_PROBLEM: (why) => `Runs are not reaching the platform (${why}). reticle_run { tool: "reticle_project", args: { push: true } } retries and reports why.`,
+    FINISH_LINKED: 'Done driving? reticle_session { action: "yield" } hands the tab back; this run syncs to the platform on its own.',
+    FINISH: 'Done driving? reticle_session { action: "yield" } hands the tab back.',
+    /**
+     * The evidence of this app is landing outside any project, so nothing will send it. A second
+     * checkout's runs and flows went to `~/.reticle/unmatched/<id>` and the agent was told nothing.
+     */
+    UNMATCHED: (root, contenders, serving) => {
+        const app = serving === undefined ? "This app's" : `The app served from ${serving}: its`;
+        const lead = `${app} runs and flows are going to ${root}, not your project, so they will not reach the dashboard: `;
+        if (0 === contenders.length) {
+            return `${lead}no folder on this machine declares its project. Run \`reticle init\` in the app's folder.`;
+        }
+        return (`${lead}${String(contenders.length)} folders claim its project id (${contenders.join(', ')}). ` +
+            'Serve the app from the checkout that owns the id, or give this one its own id with ' +
+            "`reticle init` in it — that rewrites its committed .reticle.json, so keep the change on this checkout's branch.");
+    },
+    REPLAY: (flows) => `This app has ${String(flows)} saved flow(s). Replay them before driving anything by hand: reticle_verify { action: "flows" } re-verifies them with no model.`,
+};
+/**
+ * Keyed by the agent session AND the folder: what is "said once" is said once to each agent. The
+ * daemon outlives agent sessions, and keyed by folder alone a fresh session in a second checkout
+ * was diverted into ~/.reticle/unmatched with nothing said, because an earlier one had been told.
+ */
+const roots = new Map();
+/** Tests only. */
+export function resetNextStep() {
+    roots.clear();
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return 'object' === typeof parsed && null !== parsed
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Declared within the window, read from the file's own stamp (or its age when it has none). */
+function requestDeclared(root, now) {
+    const path = join(root, ReticleDir.REQUEST_FILE);
+    if (!existsSync(path))
+        return false;
+    const at = readJson(path)?.['at'];
+    const when = 'number' === typeof at ? at : statSync(path).mtimeMs;
+    return now - when < REQUEST_FRESH_MS;
+}
+/**
+ * Run files THIS agent session wrote (at or after `since`) after the last push, and old enough that a
+ * sync cycle should have sent them. Another session's are not this one's to be told about.
+ */
+function unsentRuns(root, lastPushAt, now, since) {
+    try {
+        const dir = join(root, ReticleDir.RUNS_SUBDIR);
+        return readdirSync(dir).filter((name) => {
+            // A drive's own record is not a run and never syncs.
+            if (name.endsWith(DRIVE_RECORD_SUFFIX))
+                return false;
+            const at = statSync(join(dir, name)).mtimeMs;
+            return at >= since && at > lastPushAt + UNSENT_AFTER_MS && now - at > UNSENT_AFTER_MS;
+        }).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Whether this agent session wrote a run or a flow here since it began. */
+function wroteSince(root, since) {
+    for (const sub of [ReticleDir.RUNS_SUBDIR, ReticleDir.FLOWS_SUBDIR]) {
+        try {
+            const dir = join(root, sub);
+            if (readdirSync(dir).some((name) => statSync(join(dir, name)).mtimeMs >= since))
+                return true;
+        }
+        catch {
+            /* nothing written there */
+        }
+    }
+    return false;
+}
+/**
+ * Why sync needs a person, from the sync's own bookkeeping; undefined when it is fine.
+ *
+ * Runs that were written and never sent count too. A project the sync loop never looked at has no
+ * error and no refusal, which is how a whole day of runs stayed on one machine with every check
+ * reporting fine.
+ */
+function syncProblem(root, now, since) {
+    const state = readJson(join(root, ReticleDir.CLOUD_STATE_FILE));
+    const pushed = state?.['lastPushAt'];
+    const unsent = unsentRuns(root, 'number' === typeof pushed ? pushed : 0, now, since);
+    if (0 < unsent)
+        return `${String(unsent)} run(s) written here were never sent`;
+    if (state === undefined)
+        return undefined;
+    const error = state['lastError'];
+    // A refused key read as the platform's "valid API key required" to a member removed from the
+    // workspace, whose key was set: it was refused, which is what they have to act on — and it holds
+    // back this session's work too, so it is said whoever wrote what.
+    const refusal = keyRefusalAtLastSync(root);
+    if (refusal !== undefined)
+        return refusal;
+    // Anything else the project's sync reports is said to a session whose own work it holds back: a
+    // flow another session saved was named on every result of one that had written nothing.
+    if (!wroteSince(root, since))
+        return undefined;
+    if ('string' === typeof error && 0 < error.length)
+        return error.slice(0, 120);
+    const refused = state['refusedRuns'];
+    const count = 'object' === typeof refused && null !== refused ? Object.keys(refused).length : 0;
+    return 0 < count ? `${String(count)} run(s) refused` : undefined;
+}
+/** Saved flow files under `flows/`, one level of project folders deep. */
+function savedFlows(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).reduce((n, entry) => n +
+            (entry.isDirectory()
+                ? readdirSync(join(dir, entry.name)).filter((f) => f.endsWith('.json')).length
+                : entry.name.endsWith('.json')
+                    ? 1
+                    : 0), 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/** The line, or undefined when there is nothing the agent should be told right now. */
+export function nextStep(input) {
+    const { root } = input;
+    if (root === undefined)
+        return undefined;
+    const key = `${callingAttachId() ?? ''}\u0000${root}`;
+    const state = roots.get(key) ?? {
+        calls: 0,
+        lastQuietAt: Number.NEGATIVE_INFINITY,
+        declareAsks: 0,
+        replayTold: false,
+        since: input.now,
+    };
+    roots.set(key, state);
+    state.calls += 1;
+    const linked = existsSync(join(root, ReticleDir.CLOUD_LINK_FILE));
+    // A key in the environment syncs too, so its runs not arriving is just as much a problem.
+    const sends = linked || 0 < (process.env[ReticleEnv.API_KEY] ?? '').length;
+    const quietDue = state.calls - state.lastQuietAt >= QUIET_CALLS;
+    // Before anything else, once per folder: everything else said here assumes the work is landing
+    // in the project.
+    const unmatched = input.unmatched;
+    if (unmatched !== undefined && unmatched.root !== state.unmatchedTold) {
+        state.unmatchedTold = unmatched.root;
+        return NextText.UNMATCHED(unmatched.root, unmatched.contenders, unmatched.serving);
+    }
+    // Measured on a whole-app drive: an agent re-drove everything by hand while saved flows sat
+    // unreplayed, though the skill says to replay first. Said on the first call, where it is in time.
+    if (!state.replayTold && !input.tool.endsWith('verify')) {
+        state.replayTold = true;
+        const saved = savedFlows(join(root, ReticleDir.FLOWS_SUBDIR));
+        if (0 < saved)
+            return NextText.REPLAY(saved);
+    }
+    const problem = sends ? syncProblem(root, input.now, state.since) : undefined;
+    if (problem !== undefined && problem !== state.problemTold && (input.verdict || quietDue)) {
+        state.lastQuietAt = state.calls;
+        state.problemTold = problem;
+        return NextText.SYNC_PROBLEM(problem);
+    }
+    // Not on the declare call itself, which is the answer to this line.
+    if (!input.tool.endsWith('intent') &&
+        state.declareAsks < DECLARE_ASKS &&
+        !requestDeclared(root, input.now) &&
+        (input.verdict || quietDue)) {
+        state.lastQuietAt = state.calls;
+        state.declareAsks += 1;
+        return NextText.DECLARE;
+    }
+    if (!input.verdict)
+        return undefined;
+    // How to connect is the agent nudge's to say, once per session (`platform-moment.ts`).
+    return sends ? NextText.FINISH_LINKED : NextText.FINISH;
+}

package/dist/surface/tools/observe-tools.js

@@ -2,6 +2,7 @@
  * Observe / wait / assert tools — reticle_observe, reticle_wait_for, reticle_assert, reticle_network,
  * reticle_console, reticle_animations. Split out of tools.ts; assembled back via...OBSERVE_TOOLS.
  */
+import { checkWords, runIdOfCall } from '../../judgement/runs/drive-run.js';
 import { noteEmptyRead } from './gaps/observed-nothing.js';
 import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
@@ -159,8 +160,11 @@ export const OBSERVE_TOOLS = [
             // Output budget: cap to the most recent N (no silent caps — droppedOldest is surfaced in cost).
             const { events: budgeted, droppedOldest } = applyEventBudget(filtered, asNumber(args['max_events']) ?? DEFAULT_OBSERVE_EVENT_LIMIT);
             const report = buildReactionReport(budgeted, windowMs);
-            // Run over the FILTERED-but-unbudgeted window: a contradiction must not vanish because the
-            // timeline was capped for tokens. Detection is cheap; the events are already in hand.
+            // Run over the WHOLE window: neither unfiltered nor unbudgeted is a display choice. A contradiction
+            // must not vanish because the timeline was capped for tokens, and it must not APPEAR because a
+            // filter removed its counter-evidence: `filters: ["route"]` dropped the DOM events proving a
+            // destination rendered, and the call reported `route-rendered-nothing` the unfiltered call did
+            // not (#1359). Detection is cheap; the events are already in hand.
             // The act that opened this window is not in `args` — observe is a separate call — so its action
             // and in-target mutation count are read back off the session. Without them the "this click did
             // nothing" check is unreachable on the ordinary act-then-observe flow, which is most of them.
@@ -169,7 +173,7 @@ export const OBSERVE_TOOLS = [
             // never asked about.
             const actCursor = session.lastAct.cursor();
             const judgingTheAct = actCursor !== undefined && actCursor >= since;
-            const contradictions = findContradictions(filtered, {
+            const contradictions = findContradictions(events, {
                 currentDocumentId: session.currentDocumentId,
                 currentEditEpoch: session.currentEditEpoch,
                 appOrigin: session.url,
@@ -208,6 +212,12 @@ export const OBSERVE_TOOLS = [
                 .number()
                 .optional()
                 .describe('Present when this call stopped at the per-call limit before the predicate was seen. Call again with timeout_ms set to this, the same predicate and the same since, to keep waiting.'),
+            verified: z
+                .string()
+                .optional()
+                .describe('THE field to gate on, graded as reticle_assert grades it: "yes" | "no" | "unknown".'),
+            verifiedReason: z.string().optional().describe('The deciding clause, as one code.'),
+            because: z.string().optional().describe('One sentence naming the deciding evidence.'),
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
@@ -258,7 +268,7 @@ export const OBSERVE_TOOLS = [
             if (bodyRefusal !== undefined)
                 throw new Error(bodyRefusal);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            let since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
+            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             // See the note on the assert handler below: a wait cut off by a full-document navigation is
             // followed to the document that took over, rather than graded as a lost observation there.
             const predicateStarted = session.elapsed();
@@ -270,20 +280,37 @@ export const OBSERVE_TOOLS = [
                 predicateStarted,
                 reevaluate: (next, budget) => waitForPredicate(next, predicate, budget, 0),
             });
-            if (followed.followed)
-                since = 0;
             session = followed.session;
             const verdict = followed.verdict;
+            // Stopped at the per-call limit before the predicate was seen: "not yet", which is not a "no".
+            // Grading it read as a failure of the app while the caller is told to keep waiting (#1119).
+            const resume = resumeAfter(requestedMs, waitBudget, verdict);
+            if (resume !== undefined && !verdict.pass) {
+                return withControl(session, {
+                    ...annotateStarvedFailure(session, verdict),
+                    ...(followed.followed ? { sessionId: session.id } : {}),
+                    resume_ms: resume,
+                    ...healthEnvelope(session),
+                    ...bufferEnvelope(session),
+                });
+            }
+            // The verdict, graded as `reticle_assert` grades it. This is `reticle_assert { action: "wait" }`,
+            // and it answered `pass` with no `verified` — the one field an agent is told to gate on — while
+            // `action: "now"` carried it. Not journaled: a wait settles the page; the proof is the assert.
+            const { decision } = await assertVerdict(session, predicate, verdict.pass, verdict.evidence, followed.followed ? 0 : since, verdict.inconclusive, verdict.observationLost);
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
             // and the buffer envelope, so a verdict reached over an evicted window says so.
             return withControl(session, {
+                verified: decision['verified'],
+                verifiedReason: decision['verifiedReason'],
+                because: decision['because'],
                 // #537's starved-wait note wraps the verdict (it RETURNS the verdict), so it stands where
                 // `...verdict` did. The source line is #533's `assertionSource`, which superseded
                 // `lastActSourceOnFailure` — an assert used to be blamed on the previous act's file:line.
                 ...annotateStarvedFailure(session, verdict),
                 ...assertionSource(session, predicate, verdict),
                 ...(followed.followed ? { sessionId: session.id } : {}),
-                ...((resume) => (resume === undefined ? {} : { resume_ms: resume }))(resumeAfter(requestedMs, waitBudget, verdict)),
+                ...(resume === undefined ? {} : { resume_ms: resume }),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });
@@ -316,6 +343,10 @@ export const OBSERVE_TOOLS = [
             ...sessionIdShape,
         },
         outputSchema: {
+            // Returned on every graded answer and undeclared, so a schema-strict client dropped the one
+            // field an agent is told to gate on (#1119).
+            verified: z.string().optional().describe('THE field to gate on: "yes" | "no" | "unknown".'),
+            verifiedReason: z.string().optional().describe('The deciding clause, as one code.'),
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
@@ -433,6 +464,8 @@ export const OBSERVE_TOOLS = [
                     verdictId: inlineVerdictId(ReticleTool.ASSERT, deps.now()),
                     grade: gradeOfPredicate(predicate),
                     at: deps.now(),
+                    // The run this check lands in, so the platform links proof and run by id, not by time.
+                    runId: runIdOfCall(session.id),
                 }, 
                 /*
                  * An assertion has no element of its own — it observes, it does not act. The file it names
@@ -446,13 +479,16 @@ export const OBSERVE_TOOLS = [
             // in the response lives only in the agent's context window, which is the copy a compaction
             // destroys — see runs/run-context.ts. Recorded WITHOUT an attribution window: this tool drives
             // nothing, so no event it observed was caused by it.
-            session.recordAction(ReticleTool.ASSERT, asRecord(args), verdictEffect);
+            session.recordAction(ReticleTool.ASSERT, asRecord(args), {
+                ...verdictEffect,
+                ...checkWords(verdict),
+            });
             // A passing check over the default window (since the last act) is proof of that act, so it
             // joins that step in the recording — otherwise "act, then assert" saves a bare click. An
             // explicit `since` may reach back past the last step, where replay would not find it. The
             // store itself refuses when a navigation came after that step: see RecordingStore.markNavigated.
             if (Verified.YES === decision['verified'] && args['since'] === undefined) {
-                captureAssertion(deps.recordings, predicate);
+                captureAssertion(deps.recordings, predicate, session.id);
             }
             return withControl(session, {
                 ...decision,

package/dist/surface/tools/platform-moment.d.ts

@@ -0,0 +1,72 @@
+import { AgentNudgeKind } from '@reticlehq/core';
+import { type InstrumentedTab } from '../../portal/session/recorded-gaps.js';
+import type { ToolDeps } from './tool-kit.js';
+/** Verified runs kept only on this machine before the platform is worth a sentence. */
+export declare const LOCAL_RUNS_MOMENT = 5;
+/** A `.reticle` this large is history worth keeping somewhere other than one laptop. */
+export declare const LARGE_RETICLE_BYTES: number;
+export declare const CONNECT = "`npx @reticlehq/server connect`";
+export declare function takePlatformMoment(deps: Pick<ToolDeps, 'fs' | 'linkedCloud'> & {
+    now?: () => number;
+}, raw: Record<string, unknown>, 
+/** The `.reticle` of the project the verdict was about — the session's, not the daemon's. */
+rootOf: () => string): Promise<string | undefined>;
+/** Tests only. */
+export declare function resetPlatformMoments(): void;
+/**
+ * Hand-driven actions before the agent is told to hand journeys to the Harness. One: with the
+ * Harness switched on, the person has said they want journeys driven by it, so the agent hears it on
+ * its first hand-driven step rather than after eight.
+ */
+export declare const LONG_JOURNEY_ACTS = 1;
+export declare const NudgeText: {
+    readonly CONNECT: string;
+    readonly closeGaps: (reason: string) => string;
+    readonly switchOn: (percent: number) => string;
+    readonly explore: () => string;
+};
+export interface NudgeInput {
+    /** The agent's connection: a session. Absent means not an agent's own call, and nothing is said. */
+    session: string | undefined;
+    /** The project the call was about. */
+    root: string | undefined;
+    tool: string;
+    /** Whether this result carries a verdict. */
+    verdict: boolean;
+    /** Whether this result failed: an error, a refusal, or a verdict that came back no. */
+    failed: boolean;
+    /** Whether the project is linked to the platform. Read only when a kind needs it. */
+    linked: () => Promise<boolean>;
+    /** The driven tab's Harness gate, when one is resolved. */
+    gate: {
+        percent: number;
+        unlocked: boolean;
+        reason?: string;
+    } | undefined;
+    /** Whether the Harness is switched on, when the platform has said. Read only when needed. */
+    harnessOn: () => boolean | undefined;
+    /** Whether this call drives the page by hand. */
+    acted: boolean;
+}
+/** Tests only. */
+export declare function resetNudges(): void;
+/** The advisory for this result, and its kind, or undefined. Never throws. */
+export declare function takeNudge(input: NudgeInput): Promise<{
+    kind: AgentNudgeKind;
+    text: string;
+} | undefined>;
+/** A result that failed: thrown or returned as an error, refused, or a verdict that said no. */
+export declare function resultFailed(raw: Record<string, unknown>, isError: boolean): boolean;
+/**
+ * The advisory for one agent call, wired to this daemon: the tab's gate, the project's link and the
+ * Harness switch as the platform last said it. Counted when shown. Never throws.
+ */
+export declare function agentNudge(input: {
+    deps: Pick<ToolDeps, 'attachId' | 'linkedCloud'>;
+    tool: string;
+    raw: Record<string, unknown>;
+    isError: boolean;
+    tab: InstrumentedTab | undefined;
+    root: string | undefined;
+    harnessOn: () => boolean | undefined;
+}): Promise<string | undefined>;