@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/gap-novelty.js

@@ -20,6 +20,7 @@
  *
  * Scoped per session id, because a new session is a new agent that has been told nothing.
  */
+import { recordGaps } from '../../portal/session/recorded-gaps.js';
 /** The fields worth repeating. Everything else on a gap is the remedy, said once. */
 const FACT_KEYS = ['kind', 'ref', 'source'];
 /** Sessions that have already been given the full text, by gap kind. */
@@ -30,9 +31,15 @@ const toldBySession = new Map();
  * Returns a NEW array and never mutates its input — the same gap objects travel into telemetry and
  * into the persisted capsule, and trimming those would lose the remedy where it is read cold.
  */
-export function withGapNovelty(sessionId, gaps) {
+export function withGapNovelty(sessionId, gaps, 
+/** When the verdict was taken: stamps the gaps recorded for the app's coverage. */
+now = Date.now()) {
     if (0 === gaps.length)
         return [];
+    // Before the trim, while each gap still carries its remedy: the app's coverage and the platform
+    // report read the full gap, and this is the one place every verdict's gaps pass through.
+    if (sessionId !== undefined)
+        recordGaps(sessionId, gaps, now);
     // No session id means no memory to check against, so nothing can be a repeat. Sending the full
     // text is the safe direction: a reader who has seen it skims, a reader who has not is stuck.
     if (sessionId === undefined)

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

@@ -7,13 +7,29 @@
  * nothing grades) but the flows that now exist on disk, because every future run replays those
  * deterministically with no model in the loop at all.
  */
+import { type FlowFile } from '@reticlehq/core';
 import type { ToolDeps } from './tool-kit.js';
 import { type HarnessPlan } from './harness-plan.js';
-import { type ConfigFetch } from '../../features/harness/platform-config.js';
-import { type HarnessResult, type ModelDriver, type ToolOutcome } from '../../features/harness/harness.js';
+import type { ConfigFetch } from '../../features/harness/platform-config.js';
+import type { JourneyResult } from '../../features/harness/platform/script.js';
+import { type HarnessOptions, type HarnessResult, type HarnessToolset, type ModelDriver, type ToolOutcome } from '../../features/harness/harness.js';
+import { type GoalCheck } from '../../features/harness/goals.js';
+import type { RunDisparity } from '@reticlehq/core';
+import type { HarnessMap } from '@reticlehq/core/artifacts';
+export { MSG_HARNESS_DISABLED, MSG_HARNESS_UNCLAIMED, MSG_HARNESS_UNCONFIRMED, } from '../../features/harness/platform/refusal.js';
+export { MSG_GATE_PROMPT_LEAD, MSG_NO_HARNESS_KEY, coverageRefusal, firstLine, harnessAvailable, harnessLockRefusal, refusedByPlatform, withLinkedCredential, } from './harness-gate.js';
 export interface ExploreOptions {
     /** Who to be, or what to accomplish. Appended to the standing instruction. */
     focus?: string;
+    /**
+     * A person started this run (Run plan from the dashboard) and acknowledged the saved flows' own
+     * destructive steps: a planned replay may take them. Never a step the model decides.
+     */
+    confirmDangerous?: boolean;
+    /** Texts the drive must leave on the page. Default: whatever `focus` quoted. See goals.ts. */
+    goals?: readonly string[];
+    /** The outcome the journey must end in, as a reticle_assert predicate. See `checkExpect`. */
+    expect?: Record<string, unknown>;
     /** Pinned tab, when the app has more than one connected. */
     sessionId?: string;
     /** Hard ceiling on model turns. Bounds cost, not value — the drive is usable however it ends. */
@@ -44,6 +60,14 @@ export interface ExploreOptions {
      * supposed to cover the OFF switch was asserting on a path where the platform is never asked.
      */
     configFetch?: ConfigFetch;
+    /** The drive's harness id, minted by the caller so its run id is known before the drive starts. */
+    harnessId?: string;
+    /** A plan the platform saved (`hp_…`): run it as it stands, instead of asking for a new one. */
+    planId?: string;
+    /** Asked between turns: whoever started the drive asked it to stop. */
+    stopped?: () => boolean;
+    /** Asked between turns: what whoever started the drive said to it since. */
+    inbox?: () => readonly string[];
 }
 export interface ExploreResult {
     drive: HarnessResult;
@@ -51,6 +75,8 @@ export interface ExploreResult {
     plan: HarnessPlan;
     /** Flows that exist now and did not before — the part of a drive that is worth paying for twice. */
     savedFlows: readonly string[];
+    /** Of the saved and rewritten flows, the ones with no step that checks anything. */
+    unverifiedFlows: readonly string[];
     /**
      * Flows that already existed and were written again by this drive.
      *
@@ -64,6 +90,10 @@ export interface ExploreResult {
      * journeys under the same names — so this is the ordinary case, not the corner one.
      */
     rewroteFlows: readonly string[];
+    /** One verdict per goal, checked by the harness after the drive rather than taken on its word. */
+    goals: readonly GoalCheck[];
+    /** The persona plan and how each persona ended, when the platform proposed the personas. */
+    planLines?: readonly string[];
     /**
      * Which driver actually drove.
      *
@@ -73,41 +103,19 @@ export interface ExploreResult {
      * comparison. `custom` is an injected driver, which is neither of ours to name.
      */
     driverName: string;
+    /** The run this drive syncs as (`harness-<id>`), so a caller can find it on the platform. */
+    runIds?: readonly string[];
+    /** The run's page on the dashboard, when the project is linked. */
+    runUrl?: string;
+    /** How each journey of a platform plan ended, worst lane first. Absent for an unplanned drive. */
+    journeys?: readonly JourneyResult[];
+    /** The platform plan this run drove, which the dashboard keeps, edits and runs again. */
+    planId?: string;
+    /** That plan's page on the dashboard. */
+    planUrl?: string;
+    /** Each goal the session's coding agent also judged, and how the two verdicts compare. */
+    disparity?: readonly RunDisparity[];
 }
-/**
- * Why the harness is unavailable, phrased as the way to make it available.
- *
- * A missing key is a configuration fact, not a fault, and the sentence a user reads has to tell them
- * the one thing to do about it. Named here because both the CLI and the honest no-flows refusal
- * print it, and two copies of this sentence would drift.
- */
-export declare const MSG_NO_HARNESS_KEY: string;
-/** Asked for Jev specifically and it is not configured. Distinct from having no model at all. */
-export declare const MSG_NO_JEV_KEY: string;
-/** Asked for OpenAI specifically and it is not configured. Never substituted, same as Jev. */
-export declare const MSG_NO_OPENAI_KEY: string;
-/**
- * The environment, plus the credential this machine already has.
- *
- * `reticle link` mints a project-scoped key and files it in `~/.reticle/credentials.json`; the CLI
- * has read it from there for as long as it has existed. The harness did not, and read only
- * `process.env` — so somebody who had signed in, linked their project and been told they were
- * connected still got "no model configured to drive the app", and the only way out was to find the
- * key in the console and export it by hand. Five manual steps to reach a feature they had already
- * finished setting up.
- *
- * Resolved into the env rather than threaded through four call sites: the drivers and the
- * preference lookup all read an env record, and giving them a completed one leaves each of them
- * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
- * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
- * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
- *
- * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
- * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.
- */
-export declare function withLinkedCredential(deps: ToolDeps, env: Record<string, string | undefined>): Promise<Record<string, string | undefined>>;
-/** Is there a model the harness can drive with? A read, because "not configured" is not a failure. */
-export declare function harnessAvailable(env: Record<string, string | undefined>): boolean;
 /**
  * Read the step ceiling out of the environment.
  *
@@ -124,7 +132,31 @@ export declare function maxStepsFromEnv(env: Record<string, string | undefined>)
  * that says it saved a flow and did not is the same false green as an app that says it saved a
  * record and did not — and this product does not get to make that mistake about its own work.
  */
-export declare function exploreApp(deps: ToolDeps, env: Record<string, string | undefined>, options?: ExploreOptions): Promise<ExploreResult>;
+export declare function exploreApp(deps: ToolDeps, given: Record<string, string | undefined>, asked?: ExploreOptions): Promise<ExploreResult>;
+/** The stop and the words of whoever started the drive, for `runHarness`. */
+export declare function steering(options: ExploreOptions): Pick<HarnessOptions, 'stopped' | 'inbox'>;
+/** A line in the HUD's Agent Log for the person watching; nobody watching is not an error. */
+export declare function narrator(deps: ToolDeps, options: ExploreOptions): (text: string, summary?: boolean) => void;
+export declare function productRules(deps: ToolDeps, sessionId?: string): Promise<string[]>;
+/** `deps` whose flow store is the session's own project, where the drive's saves land. */
+export declare function withProjectFlows(deps: ToolDeps, sessionId?: string): ToolDeps;
+/**
+ * Write the persona onto every flow the drive saved or rewrote without an intent.
+ *
+ * Whichever driver saved it, and in whatever words: the cheap driver's own teardown saved its flow
+ * with no intent at all, so a replay could never say which journey it was meant to prove. A flow
+ * that already carries an intent keeps it. Best effort: a flow that cannot be read or rewritten is
+ * still a saved flow.
+ */
+export declare function recordPersona(deps: ToolDeps, names: readonly string[], persona: string): Promise<void>;
+/**
+ * The saved flows with no step that asserts a consequence.
+ *
+ * Such a flow replays as "verified nothing": it clicks through the journey and would pass with the
+ * feature broken. Named so the drive's report does not count it as evidence. A flow that cannot be
+ * read is left out rather than guessed at.
+ */
+export declare function flowsThatCheckNothing(deps: ToolDeps, names: readonly string[]): Promise<readonly string[]>;
 /**
  * What a drive actually left behind, split into flows that are NEW and flows it wrote over.
  *
@@ -147,32 +179,61 @@ export declare function reconcileFlows(before: ReadonlySet<string>, after: reado
     rewroteFlows: readonly string[];
 };
 /**
- * What a person said about autonomous driving on the platform, honoured here.
- *
- * The switch existed, persisted and round-tripped, and the daemon read it and threw it away — so
- * turning the harness OFF changed a value in a database and nothing else. A control that does not
- * control anything is worse than no control: somebody turns it off, watches Reticle drive their app
- * anyway, and now correctly distrusts every other switch in the product.
- *
- * Absent means ON. The platform's own default is on, and a machine that cannot reach the platform —
- * offline, CI, no link — must not silently lose a feature it was never told to stop using.
+ * Why a drive must not be replayed into a verdict, or undefined when it may. A drive the platform
+ * cut off (credits gone: 402 needs_card) had saved one partial flow, and replaying it printed PASS
+ * with no word about the credits. The one test both CLI explore paths answer through.
  */
-export declare const MSG_HARNESS_DISABLED: string;
+export declare function cutOffReason(drive: {
+    stopReason?: unknown;
+    error?: unknown;
+}): string | undefined;
+/** The Agent Log's last line for a drive the platform cut off: its reason, and that it proved nothing. */
+export declare const msgDriveCutOff: (error: string | undefined) => string;
 /**
- * The other reason a drive can be refused, and it is NOT the same reason.
+ * Close and save whatever recording the drive left open.
  *
- * A drive through the platform spends Reticle's model budget. That is free for three months and
- * included on a paid plan, and outside both it is somebody else's money being spent on nothing. The
- * message says which of the two it is and what to do, because "the harness is off" told to a person
- * who never turned anything off is a support ticket rather than an answer.
+ * The driver reserves turns for its own teardown, which covers the ordinary ending. It does NOT
+ * cover a drive that broke, or one whose model went quiet, or one cut off by a budget the caller
+ * shortened — and in every one of those the app really was driven and the record of it is thrown
+ * away. Measured before this existed: a 24-step journey through a real dashboard, saved nothing.
+ *
+ * Failures are swallowed on purpose. This is a last chance, not a checkpoint: if the recording was
+ * already closed the stop is refused and there is nothing to do, and a drive must not fail at the
+ * finish line because the thing it was trying to rescue did not need rescuing.
  */
-export declare const MSG_HARNESS_UNCLAIMED: string;
 /**
- * A stored preference, kept only if this build can actually honour it.
+ * What a banked recording says it was for: the persona the caller named, when there was one.
  *
- * Exported because it is the whole of the asymmetry with the per-call argument, and the asymmetry
- * is the part somebody will later think is a bug.
+ * It used to be "Autonomous drive of X, banked after the run ended" whatever the caller asked for,
+ * so a replay could never say which journey the flow was meant to prove.
  */
-export declare function knownDriver(provider: string | undefined): string | undefined;
+export declare function bankedIntent(persona: string | undefined, open: string, 
+/** The journey the drive was for, when no persona was named. */
+journey?: string): string;
+export declare function bankOpenRecording(toolset: HarnessToolset, drive: HarnessResult, persona: string | undefined, journey?: string): Promise<ToolOutcome[]>;
 /** The recording started and never stopped, if there is one. Exported because it is the decision. */
 export declare function openRecordingName(toolCalls: readonly ToolOutcome[]): string | undefined;
+/**
+ * Read the project's own record of what it does and what is proved about it.
+ *
+ * No browser, no model, no source. A failure here is "nothing is recorded yet", which is the
+ * ordinary state of a new project and not a reason to refuse to drive — so it answers an empty
+ * plan rather than throwing.
+ */
+export declare function readFlows(deps: ToolDeps): Promise<FlowFile[]>;
+export declare function readPlan(deps: ToolDeps, sessionId?: string): Promise<HarnessPlan>;
+export declare function pinned(options: ExploreOptions): {
+    sessionId?: string;
+};
+/**
+ * The driver: the platform's Harness, which decides every step on its side while this machine
+ * executes. There is no other: the decisions, the models and the planning run only on the platform.
+ */
+export declare function buildDriver(env: Record<string, string | undefined>, maxSteps: number, plan: HarnessPlan, requested?: string, persona?: string, 
+/** A goal driven with no persona: it names the drive's flows as a persona would. */
+journey?: string, 
+/** The survey of the app, which the platform's engine looks goals up in. */
+siteMap?: HarnessMap): {
+    driver: ModelDriver;
+    name: string;
+};