@reticlehq/server 3.4.0 → 3.6.0

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

@@ -7,13 +7,17 @@
  * 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 HarnessResult, type HarnessToolset, type ModelDriver, type ToolOutcome } from '../../features/harness/harness.js';
+import { type GoalCheck } from '../../features/harness/goals.js';
 export interface ExploreOptions {
     /** Who to be, or what to accomplish. Appended to the standing instruction. */
     focus?: string;
+    /** Texts the drive must leave on the page. Default: whatever `focus` quoted. See goals.ts. */
+    goals?: readonly string[];
     /** 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. */
@@ -51,6 +55,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 +70,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,6 +83,8 @@ 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[];
 }
 /**
  * Why the harness is unavailable, phrased as the way to make it available.
@@ -82,10 +94,6 @@ export interface ExploreResult {
  * 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.
  *
@@ -106,7 +114,10 @@ export declare const MSG_NO_OPENAI_KEY: string;
  * 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. */
+/**
+ * Can this machine reach the Harness? Only through the platform: a linked project or a platform
+ * key. Whether the workspace is entitled is the platform's answer, asked when the drive starts.
+ */
 export declare function harnessAvailable(env: Record<string, string | undefined>): boolean;
 /**
  * Read the step ceiling out of the environment.
@@ -125,6 +136,29 @@ export declare function maxStepsFromEnv(env: Record<string, string | undefined>)
  * 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>;
+/** 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) => void;
+/** What this project's memory says must hold, in its own words. Nothing recorded is none. */
+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.
  *
@@ -161,18 +195,66 @@ export declare const MSG_HARNESS_DISABLED: string;
 /**
  * The other reason a drive can be refused, and it is NOT the same reason.
  *
- * 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.
+ * A drive through the platform spends Reticle's model budget, bounded by the workspace's monthly
+ * Harness credits. The platform answers this only when something other than the switch stops it.
  */
 export declare const MSG_HARNESS_UNCLAIMED: string;
+/** The platform could not be asked, and the drive would spend Reticle's budget without its yes. */
+export declare const MSG_HARNESS_UNCONFIRMED: string;
+/**
+ * The reason this drive must not start, or `undefined` to go ahead.
+ *
+ * A drive on somebody's OWN model key never waits on the platform beyond the off switch: their key,
+ * their spend. A drive through the platform proxy bills Reticle, and that one needs a confirmed yes
+ * — enabled, entitled, and a model ready. It used to fail open: `fetchPlatformConfig` answers
+ * `undefined` on a network error, a non-2xx, a body that does not parse, or a two-second timeout,
+ * and all four read as "carry on", so a slow second on a settings endpoint let an unentitled
+ * workspace drive on Reticle's budget. Now the same silence refuses with a message that says to
+ * retry or bring a key. Fields an older platform omits still default to yes inside
+ * `fetchPlatformConfig`; only an answer that never arrived is a no.
+ */
+export declare function refusedByPlatform(env: Record<string, string | undefined>, options: ExploreOptions): Promise<string | undefined>;
+/**
+ * Close and save whatever recording the drive left open.
+ *
+ * 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.
+ */
 /**
- * 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): string;
+export declare function bankOpenRecording(toolset: HarnessToolset, drive: HarnessResult, persona: string | undefined): Promise<void>;
 /** 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): {
+    driver: ModelDriver;
+    name: string;
+};