@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/impact/impact-recorder.js

@@ -0,0 +1,160 @@
+import { Verified, } from '@reticlehq/core';
+import { estimateTokens } from '../../portal/session/output-budget.js';
+import { ImpactStore } from './impact-store.js';
+/**
+ * The daemon's impact recorders — ONE PER PROJECT ROOT.
+ *
+ * This was a single module-level store, and "the first root wins for the daemon's lifetime" was
+ * written down as if it were a design decision. It is only correct for a daemon that serves one
+ * project, and this daemon has never been that: `artifactRootFor` exists precisely because one
+ * daemon serves many, and nine modules already route their artifacts by the SESSION's project.
+ *
+ * Measured, not theorised: with a daemon rooted at repo A, two verdicts driven against app B landed
+ * in A's `impact.json` — B's own ledger never moved — and A's cloud link then carried them to a
+ * PRODUCTION dashboard belonging to a different account than B was linked to. The impact ledger is
+ * what the whole dashboard is computed from, so this was the one artifact whose misrouting was
+ * guaranteed to be visible and billed.
+ *
+ * Keyed by root path, so two projects driven through one daemon keep separate ledgers, and the
+ * daemon's own root remains the answer for anything that cannot name a project.
+ */
+/** One store per `.reticle` root. */
+const stores = new Map();
+/** The daemon's own root — used when a call cannot say which project it was for. */
+let defaultRoot;
+/** Held so a per-root store is built with the same clock and project name as the default. */
+let storeOpts = {};
+/** Get-or-create the store for one root. */
+function storeFor(root) {
+    const key = root ?? defaultRoot;
+    if (key === undefined || 0 === key.length)
+        return undefined;
+    let found = stores.get(key);
+    if (found === undefined) {
+        found = new ImpactStore({ ...storeOpts, reticleRoot: key });
+        stores.set(key, found);
+    }
+    return found;
+}
+/**
+ * Wire the DEFAULT root — the daemon's own. Idempotent; the first one wins.
+ *
+ * Still idempotent, and still first-wins, because the daemon's own root genuinely does not change
+ * while it runs. What changed is that this is no longer the ONLY root: a call that knows its
+ * project passes one, and this is the fallback for calls that do not.
+ */
+export function initImpact(opts) {
+    // No root, no record. Programmatic callers and test doubles build their own deps and are not
+    // obliged to carry one, and a courtesy counter must never be the reason a tool call throws.
+    if (opts.reticleRoot === undefined || 0 === opts.reticleRoot.length)
+        return storeFor(undefined);
+    if (defaultRoot === undefined) {
+        defaultRoot = opts.reticleRoot;
+        const { projectName, now, config } = opts;
+        storeOpts = {
+            ...(projectName === undefined ? {} : { projectName }),
+            ...(now === undefined ? {} : { now }),
+            ...(config === undefined ? {} : { config }),
+        };
+    }
+    return storeFor(opts.reticleRoot);
+}
+/** The live store for a root (default when omitted), if one has been initialised. */
+export function impactStore(root) {
+    return storeFor(root);
+}
+/** Test seam: drop the stores so a suite can start from a clean record. */
+export function resetImpactForTest() {
+    stores.clear();
+    defaultRoot = undefined;
+    storeOpts = {};
+}
+/**
+ * Record one delta against a project's ledger. Never throws: stats must not break a tool call.
+ *
+ * `root` is the `.reticle` directory this call's evidence belongs to. Omitted means "could not tell
+ * which project", which falls back to the daemon's own root — the old behaviour, kept for the paths
+ * that genuinely have no session to ask.
+ */
+export function recordImpact(delta, meta = {}, root) {
+    try {
+        storeFor(root)?.record(delta, meta);
+    }
+    catch {
+        // Counting is a courtesy to the user; failing to count is not worth failing their call over.
+    }
+}
+export function impactSnapshot(root) {
+    return storeFor(root)?.snapshot();
+}
+/**
+ * What one tool call did, as counters.
+ *
+ * Pure and exported so the shape is testable without a dispatch: given a result and a duration, it
+ * says what the record should gain. `verified` is the only field that can mint a verdict, which is
+ * the same rule the product states to agents - everything else moves or reads the app.
+ */
+export function deltaForToolResult(raw, durationMs, refused) {
+    const delta = {
+        calls: 1,
+        drivingMs: Math.max(0, Math.round(durationMs)),
+        tokensReturned: estimateTokens(JSON.stringify(raw) ?? ''),
+    };
+    if (refused) {
+        delta.refusals = 1;
+        return delta;
+    }
+    const verified = isRecord(raw) ? raw['verified'] : undefined;
+    if (verified === Verified.YES) {
+        delta.verdicts = 1;
+        delta.passed = 1;
+    }
+    else if (verified === Verified.NO) {
+        delta.verdicts = 1;
+        delta.failed = 1;
+    }
+    else if (verified === Verified.UNKNOWN) {
+        delta.verdicts = 1;
+        delta.unknown = 1;
+    }
+    return delta;
+}
+/**
+ * What one FAILED verdict was, in a line.
+ *
+ * Only a verified:"no" produces one. That is the same rule the counters follow and the same rule
+ * the product states to agents: an "unknown" is not a defect, it is Reticle admitting it could not
+ * tell — recording those here would fill the user's short list with the tool's own blind spots.
+ *
+ * Everything is read from the result the tool already returned, so this costs nothing extra and
+ * cannot disagree with the verdict it describes.
+ */
+export function defectForToolResult(raw, at) {
+    if (!isRecord(raw) || raw['verified'] !== Verified.NO)
+        return undefined;
+    const effect = isRecord(raw['effect']) ? raw['effect'] : undefined;
+    const verdict = isRecord(raw['verdict']) ? raw['verdict'] : undefined;
+    const named = text(effect?.['name']) ?? text(effect?.['testid']) ?? text(effect?.['component']);
+    const why = text(verdict?.['failureReason']) ?? text(raw['because']);
+    const defect = {
+        at,
+        // The control that was acted on, when the result names one — "Sign In did not sign in" is a
+        // sentence somebody can act on; "a verdict failed" is not.
+        title: named === undefined ? (why ?? 'a declared consequence did not hold') : named,
+    };
+    if (named !== undefined && why !== undefined)
+        defect.detail = why;
+    const source = text(raw['source']);
+    if (source !== undefined)
+        defect.source = source;
+    return defect;
+}
+function text(value) {
+    if ('string' !== typeof value)
+        return undefined;
+    const trimmed = value.trim();
+    return 0 === trimmed.length ? undefined : trimmed;
+}
+function isRecord(value) {
+    return 'object' === typeof value && null !== value;
+}

package/dist/memory/impact/impact-store.d.ts

@@ -0,0 +1,52 @@
+import { type OfferSource } from '../cloud/harness-offer.js';
+import type { ConfigSource } from '../cloud/harness-config.js';
+import { type ImpactCounts, type ImpactDefect, type AccountState, type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
+/** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
+export declare function readScope(path: string, now: number): ImpactScope;
+/** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
+export declare function isoDay(now: number): string;
+/**
+ * What a fold knows beyond the counters.
+ *
+ * `runMs` is a SESSION's lifetime, and it only ever feeds the "longest run" record. It is not a
+ * counter: adding it to a total would answer a question nobody asked, and the record used to be fed
+ * a single tool call's duration instead, which made the report's superlative a number of
+ * milliseconds that never grew past one click.
+ */
+export interface ImpactFoldMeta {
+    runMs?: number;
+    /**
+     * The defect this call caught, when it caught one. Carried beside the counters rather than in
+     * them because it is not a tally: `counts.failed` says how many, this says which.
+     */
+    defect?: ImpactDefect;
+}
+/** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
+export declare function applyDelta(scope: ImpactScope, delta: Partial<ImpactCounts>, now: number, meta?: ImpactFoldMeta): ImpactScope;
+/**
+ * The live impact record for one project.
+ *
+ * Holds both scopes in memory, folds deltas in synchronously (so a reader always sees the truth),
+ * and flushes to disk on a debounce.
+ */
+export declare class ImpactStore {
+    #private;
+    constructor(opts: {
+        reticleRoot: string;
+        projectName?: string;
+        now?: () => number;
+        /** Where `~/.reticle` lives. Defaults to the real home; overridden so the shared scope is testable. */
+        globalRoot?: string;
+        /** Reads whether this machine is signed in. Injected so the store stays testable and pure-ish. */
+        account?: () => AccountState;
+        /** Where the workspace stands with the free harness offer. Injected so no test touches a network. */
+        offer?: OfferSource;
+        config?: ConfigSource;
+    });
+    /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
+    onChange(fn: () => void): void;
+    record(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta): void;
+    snapshot(): ImpactSnapshot;
+    /** Write now (process exit, tests). */
+    flush(): void;
+}

package/dist/memory/impact/impact-store.js

@@ -0,0 +1,274 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { readAccountState } from '../cloud/account-state.js';
+import { harnessOfferSource } from '../cloud/harness-offer.js';
+import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_DEFECT_LIMIT, IMPACT_SCHEMA_VERSION, ImpactScopeSchema, addImpactCounts, emptyImpactCounts, emptyImpactRecords, estimateImpactSavings, } from '@reticlehq/core';
+/**
+ * Where Reticle keeps the record of what it has done for you.
+ *
+ * Two scopes, two files, both local and never uploaded: the project's own `.reticle/impact.json`,
+ * and a machine-wide `~/.reticle/impact.json` that answers "what has Reticle done for me overall"
+ * across every app you have instrumented.
+ *
+ * This is NOT telemetry. Telemetry answers our questions about the product and leaves the machine;
+ * this answers the user's question about their own work and never does.
+ */
+/** Writes are debounced: a verification loop is 50-200 calls, and each one is a counter bump. */
+const WRITE_DEBOUNCE_MS = 800;
+/** The project's cloud binding, written by `reticle link`. Absent for an unlinked project. */
+const CLOUD_LINK_FILE = 'cloud.json';
+/**
+ * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
+ * the global scope lives beside the daemon's own state in `~/.reticle`.
+ *
+ * `globalRoot` defaults to the home directory and exists to be overridden. Reaching for `homedir()`
+ * implicitly made the machine-wide scope untestable — the one scope with a concurrency bug in it —
+ * so the seam is the fix's precondition, not a test affordance.
+ */
+function impactPaths(reticleRoot, globalRoot) {
+    return {
+        project: join(reticleRoot, ReticleDir.IMPACT_FILE),
+        global: join(globalRoot, ReticleDir.ROOT, ReticleDir.IMPACT_FILE),
+    };
+}
+/**
+ * Where this project's dashboard lives, if `reticle link` recorded one.
+ *
+ * Read from the link file rather than derived from the API url, because the API origin and the
+ * console origin are different hosts in every deployment that is not a laptop. Synchronous and
+ * best-effort, like every other read in this file: a missing or malformed link file means no link
+ * in the HUD, never a failed tool call.
+ */
+function readDashboardUrl(reticleRoot) {
+    try {
+        const raw = JSON.parse(readFileSync(join(reticleRoot, CLOUD_LINK_FILE), 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const value = raw['dashboardUrl'];
+        return 'string' === typeof value && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function emptyScope(now) {
+    const counts = emptyImpactCounts();
+    return {
+        counts,
+        days: [],
+        records: emptyImpactRecords(),
+        savings: estimateImpactSavings(counts),
+        since: now,
+        defects: [],
+    };
+}
+/** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
+export function readScope(path, now) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const result = ImpactScopeSchema.safeParse(parsed);
+        return result.success ? result.data : emptyScope(now);
+    }
+    catch {
+        return emptyScope(now);
+    }
+}
+/**
+ * Write a scope atomically.
+ *
+ * tmp + rename, because two daemons can serve two apps in the same repo at once and a half-written
+ * counters file is one the next read discards - silently losing the whole history.
+ */
+function writeScope(path, scope) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, JSON.stringify(scope, null, 2), 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // A stats file that cannot be written must never break a tool call. The counters stay in
+        // memory and the next write attempt carries them.
+    }
+}
+/** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
+export function isoDay(now) {
+    const d = new Date(now);
+    const month = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${String(d.getFullYear())}-${month}-${day}`;
+}
+/** Whether `b` is the calendar day right after `a` - the streak rule. */
+function isNextDay(a, b) {
+    const prev = new Date(`${a}T00:00:00`);
+    const next = new Date(`${b}T00:00:00`);
+    return 1 === Math.round((next.getTime() - prev.getTime()) / 86_400_000);
+}
+/** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
+export function applyDelta(scope, delta, now, meta = {}) {
+    const today = isoDay(now);
+    const counts = addImpactCounts(scope.counts, delta);
+    const days = scope.days.slice();
+    const last = days[days.length - 1];
+    if (last !== undefined && last.date === today) {
+        days[days.length - 1] = { date: today, counts: addImpactCounts(last.counts, delta) };
+    }
+    else {
+        days.push({ date: today, counts: addImpactCounts(emptyImpactCounts(), delta) });
+    }
+    while (days.length > IMPACT_DAILY_BUCKETS)
+        days.shift();
+    const todayCounts = days[days.length - 1]?.counts ?? emptyImpactCounts();
+    const previousDay = days[days.length - 2];
+    const records = { ...scope.records };
+    records.bestVerdictDay = Math.max(records.bestVerdictDay, todayCounts.verdicts);
+    records.bestDefectDay = Math.max(records.bestDefectDay, todayCounts.failed);
+    if (last === undefined || last.date !== today) {
+        // A new day joins the streak only if it follows yesterday; otherwise it starts a new one.
+        records.streakDays =
+            previousDay !== undefined && isNextDay(previousDay.date, today) ? records.streakDays + 1 : 1;
+    }
+    else if (0 === records.streakDays) {
+        records.streakDays = 1;
+    }
+    records.bestStreakDays = Math.max(records.bestStreakDays, records.streakDays);
+    records.longestRunMs = Math.max(records.longestRunMs, meta.runMs ?? 0);
+    /*
+     * Newest first, capped. Prepending is what makes the HUD's short list the CURRENT breakage rather
+     * than the first ten things that ever broke — which, after a week, is a list about the past.
+     */
+    const defects = meta.defect === undefined
+        ? scope.defects
+        : [meta.defect, ...scope.defects].slice(0, IMPACT_DEFECT_LIMIT);
+    return {
+        counts,
+        days,
+        records,
+        savings: estimateImpactSavings(counts),
+        since: scope.since,
+        defects,
+    };
+}
+/**
+ * The live impact record for one project.
+ *
+ * Holds both scopes in memory, folds deltas in synchronously (so a reader always sees the truth),
+ * and flushes to disk on a debounce.
+ */
+export class ImpactStore {
+    #paths;
+    #now;
+    #projectName;
+    #dashboardUrl;
+    #project;
+    #global;
+    /**
+     * Deltas folded since the last machine-wide write, kept so the write can be a MERGE.
+     *
+     * The project scope has one writer and can be written wholesale. The machine-wide file is shared
+     * by every daemon on the box, so writing an in-memory copy taken at construction erases whatever a
+     * sibling wrote in between — which is what made the machine streak read LOWER than a single
+     * project's. Replaying these onto whatever is on disk at flush time is what makes the write additive.
+     */
+    #pendingGlobal = [];
+    #timer;
+    #onChange;
+    #account;
+    /** Where this workspace stands with the free harness offer. Cached; see harness-offer.ts. */
+    #offer;
+    #config;
+    constructor(opts) {
+        this.#paths = impactPaths(opts.reticleRoot, opts.globalRoot ?? homedir());
+        // Resolved per snapshot, not cached: a user who runs `reticle login` in another terminal must
+        // see the HUD change without restarting the daemon that is watching their app.
+        this.#account = opts.account ?? (() => readAccountState(homedir(), process.env));
+        this.#now = opts.now ?? (() => Date.now());
+        this.#projectName = opts.projectName;
+        this.#dashboardUrl = readDashboardUrl(opts.reticleRoot);
+        // The claim happens in the console, so the link this project was linked to IS the claim link —
+        // built here rather than in the HUD, which has no way to know where this project points.
+        this.#offer = opts.offer ?? harnessOfferSource(process.env, () => this.#dashboardUrl);
+        // No default: the loader lives in `features/harness` and this file may not reach for it.
+        // A store built without one simply reports no harness config, which the HUD renders as no row.
+        this.#config = opts.config ?? { read: () => undefined };
+        const now = this.#now();
+        this.#project = readScope(this.#paths.project, now);
+        this.#global = readScope(this.#paths.global, now);
+    }
+    /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
+    onChange(fn) {
+        this.#onChange = fn;
+    }
+    record(delta, meta = {}) {
+        const now = this.#now();
+        this.#project = applyDelta(this.#project, delta, now, meta);
+        // Folded in memory so a reader sees it immediately, AND buffered so the durable write can replay
+        // it onto a file a sibling may have moved on since. The in-memory copy is rebased at flush.
+        this.#global = applyDelta(this.#global, delta, now, meta);
+        this.#pendingGlobal.push({ delta, now, meta });
+        this.#scheduleFlush();
+        this.#onChange?.();
+    }
+    snapshot() {
+        const snap = {
+            schemaVersion: IMPACT_SCHEMA_VERSION,
+            project: this.#project,
+            global: this.#global,
+        };
+        if (this.#projectName !== undefined)
+            snap.projectName = this.#projectName;
+        if (this.#dashboardUrl !== undefined)
+            snap.dashboardUrl = this.#dashboardUrl;
+        snap.account = this.#account();
+        const offer = this.#offer.read();
+        // Absent means "we have not heard", which the HUD renders as nothing at all. Never defaulted to
+        // `{claimed:false}`: that would advertise the offer to everyone who is offline.
+        if (offer !== undefined)
+            snap.harnessOffer = offer;
+        // Absent stays absent: the HUD reads that as "we have not heard" and renders no control.
+        const cfg = this.#config.read();
+        if (cfg !== undefined)
+            snap.harnessConfig = cfg;
+        return snap;
+    }
+    /** Write now (process exit, tests). */
+    flush() {
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+        // One writer: the in-memory copy IS the truth.
+        writeScope(this.#paths.project, this.#project);
+        this.#flushGlobal();
+    }
+    /**
+     * Publish this store's contribution to the machine-wide scope WITHOUT discarding anyone else's.
+     *
+     * Re-reads what is on disk and replays only the deltas recorded since the last write, so a sibling
+     * daemon's day survives. The merged result is adopted in memory too, which is what keeps the HUD's
+     * "everything on this machine" honest rather than showing this process's private view forever.
+     *
+     * ponytail: read-modify-write, not locked. Two daemons flushing inside the same read→rename window
+     * can still drop one batch — far rarer than the every-second-flush loss this replaces, and it costs
+     * one debounce window rather than a whole history. Upgrade to a lock file (exclusive `wx` create
+     * plus a stale timeout) if the counters are ever load-bearing for anything but the HUD.
+     */
+    #flushGlobal() {
+        if (0 === this.#pendingGlobal.length)
+            return;
+        const merged = this.#pendingGlobal.reduce((scope, p) => applyDelta(scope, p.delta, p.now, p.meta), readScope(this.#paths.global, this.#now()));
+        writeScope(this.#paths.global, merged);
+        this.#global = merged;
+        this.#pendingGlobal = [];
+    }
+    #scheduleFlush() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.flush();
+        }, WRITE_DEBOUNCE_MS);
+        this.#timer.unref?.();
+    }
+}

package/dist/memory/intent/inline-intent.d.ts

@@ -0,0 +1,60 @@
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/** What `provenBy` records: which tool drew the verdict, and when. */
+export declare function inlineVerdictId(tool: string, at: number): string;
+/**
+ * The surface an inline intent was captured on, so the store can FILE it.
+ *
+ * Without one, almost everything a project knew landed in `unsorted`: `act_and_wait({ intent })`
+ * declared a statement and nothing else, so the subject ladder had no flow, no route and no explicit
+ * subject to work from. A coverage map that is one pile with six labels reads as a team that knows
+ * nothing, when the truth is that it knows a great deal and none of it is filed.
+ *
+ * The ROUTE is what makes this work at all, because it is always available: an agent asserting
+ * something is always somewhere. A flow name is better when there is one, and `subjectFor` already
+ * prefers it — this only has to supply both and let that ladder decide.
+ *
+ * Query and hash are dropped: `/issues?category=severe` and `/issues` are the same subject seen
+ * twice, and keeping the query would shard one area across every filter anybody used.
+ *
+ * Returns undefined rather than an empty object when there is nothing to record, so the result reads
+ * as a capture that looked for a location and found none.
+ */
+export declare function surfaceForInlineIntent(url: string | undefined, flow: string | undefined, 
+/** `file` or `file:line` for the element the verdict acted on, when it had one. */
+sourceLabel?: string): {
+    route?: string;
+    flow?: string;
+    files?: string[];
+} | undefined;
+/**
+ * Put an inline intent in the ledger and attach the predicate about to be evaluated. Returns the id
+ * the verdict may later discharge, or undefined when there was no intent to record.
+ *
+ * `intent` carries EITHER prose OR the id of an intent already in the ledger. One field rather than
+ * two because the surface is the scarce thing here, and the two cases are told apart by the ledger
+ * itself: a string that names an existing row is a reference, anything else is prose.
+ *
+ * A referenced intent is never re-declared, which would overwrite the agent's own words with an id,
+ * and its binding is left alone when it already has one — a predicate bound deliberately through
+ * `reticle_intent { action: "bind" }` is a stronger statement than whatever this one call asserts.
+ *
+ * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
+ * that fails to return because of one is a large problem.
+ */
+export declare function linkInlineIntent(deps: ToolDeps, sessionId: string | undefined, intent: string | undefined, 
+/** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
+binding: unknown): Promise<string | undefined>;
+/**
+ * Record that this verdict proved the intent. Call only for a verdict that actually proved something.
+ *
+ * The ledger's own rule does the rest: `dischargeIntent` refuses an intent with no binding, so an
+ * intent declared inline on a wait that asserted no consequence stays open and honest instead of
+ * collecting a proof nothing earned.
+ */
+export declare function dischargeInlineIntent(deps: ToolDeps, sessionId: string | undefined, id: string | undefined, proof: {
+    verdictId: string;
+    grade: string;
+    at: number;
+}, 
+/** `file:line` of the element this verdict acted on, when there was one. */
+sourceLabel?: string): Promise<void>;