@reticlehq/server 2.11.0 → 2.13.0

package/dist/intent/intent-tools.js

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import { IntentStore } from './intent-store.js';
+import { IntentShardStore } from './intent-shard-store.js';
+import { IntentStatus } from './intent-shard.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * Declare what a change was SUPPOSED to make true, while somebody still knows.
+ *
+ * One tool with three actions rather than three tools, because the surface is capped and because an
+ * agent that has to discover three names to use one idea uses none of them.
+ *
+ * There is deliberately no `discharge` action. A verdict discharges an intent by satisfying its
+ * binding, and a discharge an agent has to remember to file would be the same forgetting problem
+ * this exists to solve, moved one layer up.
+ */
+const DECLARE = 'declare';
+const LIST = 'list';
+const BIND = 'bind';
+/* The sharded store's surface. Same tool, because a second tool name is a second thing to discover. */
+const INDEX = 'index';
+const SUBJECT = 'subject';
+const GET = 'get';
+const RECORD = 'record';
+const MIGRATE = 'migrate';
+export const INTENT_TOOLS = [
+    {
+        name: ReticleTool.INTENT,
+        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent.json, git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
+        example: {
+            action: DECLARE,
+            intents: [
+                { id: 'checkin', statement: 'clicking Send check-in makes the badge read "checked in"' },
+            ],
+        },
+        inputSchema: {
+            action: z.enum([DECLARE, LIST, BIND, INDEX, SUBJECT, GET, RECORD, MIGRATE]),
+            subject: z
+                .string()
+                .optional()
+                .describe('subject/record: what the intent is ABOUT — the shard it lives in.'),
+            statement: z.string().optional().describe('record only: what must be true, in prose.'),
+            why: z
+                .string()
+                .optional()
+                .describe('record only: WHY it must be true. The thing somebody says once and forgets.'),
+            source: z
+                .string()
+                .optional()
+                .describe('record only: where it came from — a person, a ticket, a conversation.'),
+            status: z
+                .enum([IntentStatus.PROPOSED, IntentStatus.AGREED, IntentStatus.PROVED, IntentStatus.STALE])
+                .optional()
+                .describe('record only: how settled it is. Defaults to proposed.'),
+            intents: z
+                .array(z.object({
+                id: z.string(),
+                statement: z.string(),
+                surface: z
+                    .object({
+                    route: z.string().optional(),
+                    flow: z.string().optional(),
+                    files: z.array(z.string()).optional(),
+                })
+                    .optional(),
+            }))
+                .optional()
+                .describe('declare only. Batchable — declare every intent for a feature in one call.'),
+            id: z.string().optional().describe('bind only: which intent the predicate proves.'),
+            binding: z
+                .unknown()
+                .optional()
+                .describe("bind only: the predicate that would prove it, in reticle_assert's shape."),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            intents: z
+                .array(z.unknown())
+                .optional()
+                .describe('The intents this call declared, or on `list` everything still open — each { id, statement, state, declaredAt, binding?, surface?, provenBy?, amended? }. `state` is declared (prose only), bound (a predicate exists), or proved (a verdict satisfied it).'),
+            bound: z.boolean().optional().describe('bind only: false when the id names no intent.'),
+            path: z.string().optional().describe('Where the ledger was written.'),
+            entries: z
+                .array(z.unknown())
+                .optional()
+                .describe('index only: one line per intent — { id, subject, statement (summarised), status }. The cheap read: enough to decide WHICH subject to open, without loading any of them.'),
+            records: z
+                .array(z.unknown())
+                .optional()
+                .describe('subject only: every full record for that subject.'),
+            record: z.unknown().optional().describe('get/record: the single full record, or null.'),
+            migrated: z
+                .number()
+                .optional()
+                .describe('migrate only: how many flat-file intents were folded into shards.'),
+            subjects: z
+                .array(z.string())
+                .optional()
+                .describe('migrate only: which subjects received them.'),
+        },
+        handler: async (deps, args) => {
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const store = new IntentStore(deps.fs, root, { now: deps.now });
+            const shards = new IntentShardStore(deps.fs, root, { now: deps.now });
+            const action = asString(args['action']);
+            if (INDEX === action)
+                return { entries: (await shards.index()).entries, path: root };
+            if (SUBJECT === action)
+                return { records: await shards.subject(asString(args['subject']) ?? ''), path: root };
+            if (GET === action)
+                return { record: await shards.get(asString(args['id']) ?? '') };
+            if (MIGRATE === action)
+                return { ...(await shards.migrate()), path: root };
+            if (RECORD === action) {
+                const written = await shards.record({
+                    id: asString(args['id']) ?? '',
+                    statement: asString(args['statement']) ?? '',
+                    subject: asString(args['subject']),
+                    why: asString(args['why']),
+                    source: asString(args['source']),
+                    status: asString(args['status']),
+                    binding: args['binding'],
+                });
+                return { record: written, path: root };
+            }
+            if (BIND === action) {
+                const id = asString(args['id']) ?? '';
+                return { bound: await store.bind(id, args['binding']) };
+            }
+            if (LIST === action) {
+                return { intents: await store.open() };
+            }
+            const raw = args['intents'];
+            const entries = Array.isArray(raw)
+                ? raw
+                : [];
+            const declared = await store.declare(entries);
+            return { intents: declared, path: root };
+        },
+    },
+];

package/dist/intent/open-intents.d.ts

@@ -0,0 +1,42 @@
+import type { Intent } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * What this project still owes — the ledger's undischarged intents, for a tool that has `deps` and a
+ * session id rather than a store.
+ *
+ * One helper rather than the same three-line construction at each site: the ROOT resolution is the
+ * part that must not drift. A caller that resolved the daemon's own directory while the declaring
+ * tool wrote to the project's would read an empty ledger and report that nothing was declared, which
+ * is a false accusation rather than an error.
+ */
+export declare function openSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;
+/**
+ * EVERY intent in the ledger, proved ones included — the denominator the open list is a subset of.
+ *
+ * Separate from `openSessionIntents` rather than a flag on it, because the two answer different
+ * questions: "what does this project still owe" drives a verdict's honesty, and "was anything ever
+ * declared" is what decides whether `reticle_intent` is used at all. Same root resolution, for the
+ * same reason it is shared above.
+ */
+export declare function allSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;
+/** What the ledger still owes once this verdict's own intent is discharged, and how old it is. */
+export interface IntentDebt {
+    openIntentCount: number;
+    /**
+     * Age of the OLDEST open intent, in ms. Absent when nothing is open.
+     *
+     * A count alone cannot tell "declared a minute ago and not proved yet" from "this project has
+     * owed eighteen things since last week", and only the first is actionable on the result being
+     * read. A number that is always large is one people learn to skip, which is how an honest gap
+     * gets filtered out along with the noise.
+     */
+    oldestOpenIntentAgeMs?: number;
+}
+/**
+ * The debt a verdict should report, MINUS the intent it is about to discharge.
+ *
+ * The discharge happens after the gaps are built, so counting the raw ledger would include the
+ * intent this very call proves — measured live: an inline intent was declared, asserted and proved
+ * by one verdict, and the result still said "1 declared intent(s) are still unproved".
+ */
+export declare function intentDebt(open: readonly Intent[], dischargedId: string | undefined, now: number): IntentDebt;

package/dist/intent/open-intents.js

@@ -0,0 +1,40 @@
+import { IntentStore } from './intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
+/**
+ * What this project still owes — the ledger's undischarged intents, for a tool that has `deps` and a
+ * session id rather than a store.
+ *
+ * One helper rather than the same three-line construction at each site: the ROOT resolution is the
+ * part that must not drift. A caller that resolved the daemon's own directory while the declaring
+ * tool wrote to the project's would read an empty ledger and report that nothing was declared, which
+ * is a false accusation rather than an error.
+ */
+export async function openSessionIntents(deps, sessionId) {
+    return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).open();
+}
+/**
+ * EVERY intent in the ledger, proved ones included — the denominator the open list is a subset of.
+ *
+ * Separate from `openSessionIntents` rather than a flag on it, because the two answer different
+ * questions: "what does this project still owe" drives a verdict's honesty, and "was anything ever
+ * declared" is what decides whether `reticle_intent` is used at all. Same root resolution, for the
+ * same reason it is shared above.
+ */
+export async function allSessionIntents(deps, sessionId) {
+    return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).read();
+}
+/**
+ * The debt a verdict should report, MINUS the intent it is about to discharge.
+ *
+ * The discharge happens after the gaps are built, so counting the raw ledger would include the
+ * intent this very call proves — measured live: an inline intent was declared, asserted and proved
+ * by one verdict, and the result still said "1 declared intent(s) are still unproved".
+ */
+export function intentDebt(open, dischargedId, now) {
+    const stillOpen = open.filter((i) => dischargedId === undefined || i.id !== dischargedId);
+    const oldest = stillOpen.reduce((min, i) => (min === undefined || i.declaredAt < min ? i.declaredAt : min), undefined);
+    return {
+        openIntentCount: stillOpen.length,
+        ...(oldest === undefined ? {} : { oldestOpenIntentAgeMs: now - oldest }),
+    };
+}

package/dist/journal/envelope.d.ts

@@ -8,7 +8,7 @@ import type { SegmentRollup } from './rollups.js';
  * (slower, more errors, more requests) — a segment doing less than expected is not a regression.
  */
 /** Online mean/variance/max for one metric (Welford's algorithm). Immutable: addStat returns a copy. */
-export interface MetricStats {
+interface MetricStats {
     count: number;
     mean: number;
     /** Sum of squared deviations (Welford M2); variance = m2/(count-1). */
@@ -22,7 +22,7 @@ export declare function stddev(stats: MetricStats): number;
 export declare function zScore(stats: MetricStats, x: number): number;
 /** The metrics an envelope tracks per route. */
 declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
-export type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
+type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
 export interface RouteEnvelope {
     route: string;
     /** Runs that contributed a sample — below MIN_ENVELOPE_SAMPLES the envelope is too green to judge. */
@@ -43,14 +43,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
         net: z.ZodObject<{
             count: z.ZodNumber;
@@ -59,14 +59,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
         netErrors: z.ZodObject<{
             count: z.ZodNumber;
@@ -75,14 +75,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
         consoleErrors: z.ZodObject<{
             count: z.ZodNumber;
@@ -91,64 +91,64 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
     }, "strip", z.ZodTypeAny, {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     }, {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     }>;
 }, "strip", z.ZodTypeAny, {
@@ -157,27 +157,27 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     stats: {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     };
 }, {
@@ -186,27 +186,27 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     stats: {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     };
 }>;

package/dist/journal/journal-recorder.d.ts

@@ -7,6 +7,11 @@ export interface JournalSink {
 /** Read side of the durable journal — the fall-through source when the ring buffer has evicted. */
 export interface JournalReader {
     readEvents(): Promise<ReticleEvent[]>;
+    /**
+     * The action ledger. Optional because a test double is a partial reader, and nothing that only
+     * needs events should be forced to grow a second method to satisfy the type.
+     */
+    readActions?(): Promise<JournalAction[]>;
 }
 interface JournalRecorderOptions {
     /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
@@ -32,6 +37,24 @@ export declare class JournalRecorder {
     beginAction(actionId: string, tool: string, args: Record<string, unknown>): void;
     /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
     finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId: string, tool: string, args: Record<string, unknown>, effect?: unknown): void;
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     flush(): Promise<void>;
 }

package/dist/journal/journal-recorder.js

@@ -65,6 +65,41 @@ export class JournalRecorder {
         this.#enqueueFlush();
         this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
     }
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId, tool, args, effect) {
+        const at = this.#now();
+        const action = {
+            v: JOURNAL_FILE_VERSION,
+            actionId,
+            tool,
+            args,
+            effect,
+            // No window was opened, so no event carries this id: `seqRange` is omitted rather than
+            // invented, because any range here would claim an attribution that never happened. `tRange` is
+            // required by the schema and the honest value is the instant the verdict was recorded — a span
+            // of zero, which is exactly how much time this action attributed events over.
+            tRange: { from: at, to: at },
+            at,
+        };
+        this.#enqueueFlush();
+        this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
+    }
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     async flush() {
         this.#enqueueFlush();

package/dist/license/license-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Find an enterprise licence key the customer actually placed, wherever they reasonably placed it.
+ *
+ * The daemon folded in `<cwd>/.env` and nothing else. It is spawned without an explicit `cwd`, so it
+ * inherits whatever directory the editor launched the MCP server from — in a monorepo that is the
+ * workspace root while the key sits in the app's own `.env`, and under some editors it is the user's
+ * home. The key was never read, `describeLicense` reported `missing`, and every event that customer
+ * produced said they had no licence, which is indistinguishable from a customer who has none.
+ *
+ * That is the worst shape a licensing bug can take. A key that fails LOUDLY gets reported by the
+ * customer within the hour. A key that silently fails to register leaves them believing they are
+ * licensed and us believing they are not, and neither side finds out.
+ *
+ * Two directions, because the field hits both: DOWN one level into app directories (the daemon
+ * starts at the workspace root) and UP to the project root (the editor starts inside the app).
+ *
+ * ONLY the licence key is ever taken out of a file found this way, and that restriction is the point
+ * rather than an optimisation. Bulk-importing a `.env` discovered by walking would let a directory
+ * the caller never named rebind the daemon's port, its telemetry gate or its allowed origins — a far
+ * worse bug than the one this fixes. `loadDotEnv` still owns the local file, where importing
+ * everything is what the caller asked for.
+ */
+/**
+ * The key, or undefined. Never throws, never mutates anything the caller did not ask it to.
+ *
+ * A key already present in `env` always wins: that is the operator stating it explicitly, and a file
+ * silently overriding it is the surprise `loadDotEnv` already refuses to cause.
+ */
+export declare function licenseKeyFromEnvFiles(startDir: string, env?: NodeJS.ProcessEnv): string | undefined;