cbrowser 20.1.0 → 20.1.2

package/dist/cognitive/index.d.ts

@@ -3,6 +3,25 @@
  * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
  * Learn more at https://cbrowser.ai - MIT License
  */
+/**
+ * Cognitive Journey API Module
+ *
+ * Provides cognitive user simulation with two modes:
+ *
+ * ## Mode 1: Claude Code Session (Recommended when inside Claude Code)
+ * When running via MCP inside Claude Code, use the step-by-step tools:
+ * - `cognitive_journey_init` - Initialize journey with persona
+ * - `cognitive_journey_update_state` - Track cognitive state after each action
+ * No API key needed - Claude Code itself is the reasoning engine.
+ *
+ * ## Mode 2: Standalone (API Key Required)
+ * When running standalone (CLI, CI/CD, scripts), uses Anthropic API directly:
+ * - `npx cbrowser cognitive-journey --persona X --start URL --goal "..."
+ * Requires: `npx cbrowser config set-api-key YOUR_KEY`
+ *
+ * @module cognitive
+ */
+import Anthropic from "@anthropic-ai/sdk";
 import { type AutoCaptureSetting } from "../recording/auto-capture.js";
 import type { CognitiveState, CognitiveJourneyResult, CognitiveTraits } from "../types.js";
 import type { DecisionProvider } from "./journey-trace.js";
@@ -39,6 +58,8 @@ export declare function isCognitiveAvailable(): boolean;
 export interface CognitiveJourneyOptions {
     /** Persona name or description */
     persona: string;
+    /** A label for this run (the CLI's first word). Names its trace and capture files and is returned on the result. */
+    name?: string;
     /** Goal statement for the journey */
     goal: string;
     /** Starting URL */
@@ -177,6 +198,8 @@ export interface CognitiveStep {
      * not anything the model said.
      */
     replyReadable: boolean;
+    /** Why the reply could not be read, when replyReadable is false. */
+    replyProblem?: string;
     state: CognitiveState;
     /** Step-aligned screenshot. Captured only on initial page load + scroll>100. */
     screenshotPath?: string;
@@ -193,6 +216,25 @@ export interface CognitiveStep {
     url?: string;
 }
 export declare function runCognitiveJourney(options: CognitiveJourneyOptions): Promise<CognitiveJourneyResult>;
+/**
+ * The live per-step decision: one messages.create call, its text blocks read
+ * together, and one more ask for the JSON alone when the reply does not hold
+ * a JSON object. describeLastReply says why the last reply was unreadable.
+ * Exported for tests, which pass a fake client.
+ */
+export declare function createLiveDecisionProvider(anthropic: Pick<Anthropic, "messages"> | null, model: string): DecisionProvider;
+/** A journey or persona name as a file-name part: letters, digits, - and _ only. */
+export declare function journeySlug(name: string): string;
+/**
+ * The JSON object in a model reply, or why there is none. Tried in order: the
+ * reply with any code fences removed, each balanced {...} in it (string-aware,
+ * so a reply with prose after its JSON still reads), then the old greedy
+ * first-"{"-to-last-"}" match; the first that parses to an object wins.
+ */
+export declare function readReplyJson(reply: string): {
+    value?: Record<string, unknown>;
+    problem?: string;
+};
 export { createInitialEmotionalState, createEmotionalConfig, applyEmotionalTrigger, decayEmotions, calculateAbandonmentModifier, calculateExplorationTendency, calculateDecisionSpeedModifier, describeEmotionalState, shouldConsiderAbandonment, } from "./emotions.js";
 export { GoalDecomposer } from "./goal-decomposer.js";
 export type { ParsedGoal, GoalPlan, SubGoal, Strategy, PlannedAction, GoalResult, ExecutionOptions, } from "./goal-types.js";

package/dist/cognitive/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cognitive/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,OAAO,EAA8D,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAMnI,OAAO,KAAK,EACV,cAAc,EAEd,sBAAsB,EAItB,eAAe,EAKhB,MAAM,aAAa,CAAC;AA4BrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAW3D;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAalD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAkBvD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAa5C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAG5C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAO7C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAkiBD,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,YAAY,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1E,CAAC;IACF,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,WAAW,EAAE;YAAE,QAAQ,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QAC7E,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,iBAAiB,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QACzF,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF;;;;;OAKG;IACH,eAAe,CAAC,EAAE;QAChB,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,cAAc,CAAC;IACtB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAqBD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAm8CjC;AAgwBD,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,4BAA4B,EAC5B,4BAA4B,EAC5B,8BAA8B,EAC9B,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,aAAa,EACb,UAAU,EACV,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cognitive/index.ts"],"names":[],"mappings":"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"}

package/dist/cognitive/index.js

@@ -693,25 +693,16 @@ export async function runCognitiveJourney(options) {
     // Decision-provider seam (v18.68.0): the per-step LLM call sits behind a
     // DecisionProvider so a recorded trace (or an injected fake) can stand in
     // for the live API. The default path is the same anthropic.messages.create
-    // call as before — params and text extraction unchanged. The post-journey
+    // call as before, reading every text block (20.1.2). The post-journey
     // goal evaluation goes through the same provider (FINAL_EVAL_STEP), so a
     // replay reproduces the recorded verdict with no model call.
-    const liveLLMProvider = {
-        decide: async (ctx) => {
-            if (!anthropic)
-                throw new Error("Anthropic API key not configured.");
-            const response = await anthropic.messages.create({
-                model,
-                max_tokens: 2000,
-                ...(ctx.systemPrompt ? { system: ctx.systemPrompt } : {}),
-                messages: ctx.messages.map((m) => ({ role: m.role, content: m.content })),
-            });
-            return response.content[0].type === "text" ? response.content[0].text : "";
-        },
-    };
+    const liveLLMProvider = createLiveDecisionProvider(anthropic, model);
     const decisionProvider = options.decisionProvider ??
         (options.replayTrace ? new TraceReplayProvider(options.replayTrace) : liveLLMProvider);
-    const traceWriter = options.trace ? new JourneyTraceWriter() : null;
+    const nameSlug = options.name ? journeySlug(options.name) : undefined;
+    const traceWriter = options.trace
+        ? new JourneyTraceWriter(nameSlug ? { journeyId: `journey-${nameSlug}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}` } : undefined)
+        : null;
     // Get or create persona
     const existingPersona = getPersona(options.persona);
     let personaObj;
@@ -990,7 +981,7 @@ export async function runCognitiveJourney(options) {
     // Auto-capture (v18.70.0): recording starts once the journey's start URL is
     // loaded, so frame 0 is the page the persona actually opens on, and stops
     // just before the browser closes. Capture never fails the journey.
-    const captureSession = await startAutoCapture(await browser.getPage(), options.capture, `journey-${options.persona.replace(/[^a-zA-Z0-9-_]+/g, "-").toLowerCase()}-${Date.now()}`);
+    const captureSession = await startAutoCapture(await browser.getPage(), options.capture, `journey-${nameSlug ?? journeySlug(options.persona)}-${Date.now()}`);
     // Apply geolocation at runtime as well (ensures permission is granted after context exists)
     if (effectiveLocation.geolocation) {
         await browser.setGeolocationRuntime(effectiveLocation.geolocation);
@@ -1326,6 +1317,9 @@ Right now it's ${temporalState.description}.`;
         // action); say so rather than let it pass as an "evaluate" step.
         const parsed = parseCognitiveResponse(assistantMessage);
         const replyReadable = Object.keys(parsed).length > 0;
+        const replyProblem = replyReadable
+            ? undefined
+            : decisionProvider.describeLastReply?.() ?? readReplyJson(assistantMessage).problem;
         // Capture URL BEFORE we apply any action. We use the previous URL +
         // the post-action URL to gate goal progress on real evidence — Claude's
         // self-reported progress is taken as a *signal*, but only allowed to
@@ -1549,6 +1543,7 @@ Right now it's ${temporalState.description}.`;
             pageTitle: pageTitle,
             phase: parsed.phase || "evaluate",
             replyReadable,
+            ...(replyProblem ? { replyProblem } : {}),
             action: parsed.action || null,
             actionTarget: parsed.actionTarget || null,
             focusedElement: parsed.focusedElement || null,
@@ -1586,6 +1581,7 @@ Right now it's ${temporalState.description}.`;
                 action: parsed.action,
                 actionTarget: parsed.actionTarget || undefined,
                 replyReadable,
+                ...(replyProblem ? { replyProblem } : {}),
                 state: { ...state },
                 screenshotPath,
                 attentionHeatmapBase64,
@@ -1926,7 +1922,7 @@ Answer with JSON:
                 });
             }
             try {
-                const evalJson = JSON.parse(evalText.replace(/```json?\n?/g, '').replace(/```/g, '').trim());
+                const evalJson = (readReplyJson(evalText).value ?? {});
                 if (evalJson.achieved) {
                     goalAchieved = true;
                     goalEvidence = `[FINAL EVAL] ${evalJson.evidence || finalPageText.substring(0, 200)}`;
@@ -1960,6 +1956,7 @@ Answer with JSON:
         : state.confusionLevel;
     // Build result
     return {
+        ...(options.name ? { name: options.name } : {}),
         persona: personaObj.name,
         goal: options.goal,
         goalAchieved,
@@ -2230,18 +2227,118 @@ STRATEGY:
 
 Respond in JSON format.`;
 }
+/**
+ * The live per-step decision: one messages.create call, its text blocks read
+ * together, and one more ask for the JSON alone when the reply does not hold
+ * a JSON object. describeLastReply says why the last reply was unreadable.
+ * Exported for tests, which pass a fake client.
+ */
+export function createLiveDecisionProvider(anthropic, model) {
+    // Why the last live reply could not be read; the step reports it as
+    // replyProblem. Undefined after a readable reply.
+    let lastLiveProblem;
+    return {
+        decide: async (ctx) => {
+            if (!anthropic)
+                throw new Error("Anthropic API key not configured.");
+            const ask = (messages, maxTokens = 2000) => anthropic.messages.create({
+                model,
+                max_tokens: maxTokens,
+                ...(ctx.systemPrompt ? { system: ctx.systemPrompt } : {}),
+                messages: messages.map((m) => ({ role: m.role, content: m.content })),
+            });
+            const textOf = (r) => r.content.map((b) => (b.type === "text" ? b.text : "")).join("");
+            const whyUnreadable = (r, text) => text.trim()
+                ? readReplyJson(text).problem
+                : `the model returned no text (stop_reason ${r.stop_reason ?? "none"}; content blocks: ${r.content.map((b) => b.type).join(", ") || "none"})`;
+            lastLiveProblem = undefined;
+            const first = await ask(ctx.messages);
+            const firstText = textOf(first);
+            if (readReplyJson(firstText).value)
+                return firstText;
+            // Asked once more, for the JSON alone. Inside the provider, so a trace
+            // records one decision per step and still replays.
+            // Thinking counts against max_tokens, so a reply cut off there may hold
+            // no text at all; the second ask gets room for both.
+            const firstProblem = whyUnreadable(first, firstText);
+            const retry = await ask([
+                ...ctx.messages,
+                { role: "assistant", content: firstText.trim() || "(no text)" },
+                { role: "user", content: "Your reply could not be read as the JSON object the response format asks for. Reply again with only that JSON object, nothing before or after it." },
+            ], first.stop_reason === "max_tokens" ? 8000 : 2000);
+            const retryText = textOf(retry);
+            if (readReplyJson(retryText).value)
+                return retryText;
+            lastLiveProblem = `${firstProblem}; asked once more, and ${whyUnreadable(retry, retryText)}`;
+            return retryText;
+        },
+        describeLastReply: () => lastLiveProblem,
+    };
+}
+/** A journey or persona name as a file-name part: letters, digits, - and _ only. */
+export function journeySlug(name) {
+    return name.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "journey";
+}
 function parseCognitiveResponse(response) {
-    try {
-        // Extract JSON from response (may have markdown code blocks)
-        const jsonMatch = response.match(/\{[\s\S]*\}/);
-        if (jsonMatch) {
-            return JSON.parse(jsonMatch[0]);
+    return (readReplyJson(response).value ?? {});
+}
+/**
+ * The JSON object in a model reply, or why there is none. Tried in order: the
+ * reply with any code fences removed, each balanced {...} in it (string-aware,
+ * so a reply with prose after its JSON still reads), then the old greedy
+ * first-"{"-to-last-"}" match; the first that parses to an object wins.
+ */
+export function readReplyJson(reply) {
+    const text = reply.trim();
+    if (!text)
+        return { problem: "the model returned no text" };
+    const unfenced = text.replace(/```(?:json)?/gi, "").trim();
+    const candidates = [unfenced];
+    for (let i = 0; i < unfenced.length; i++) {
+        if (unfenced[i] !== "{")
+            continue;
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let j = i; j < unfenced.length; j++) {
+            const c = unfenced[j];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (c === "\\")
+                    escaped = true;
+                else if (c === '"')
+                    inString = false;
+                continue;
+            }
+            if (c === '"')
+                inString = true;
+            else if (c === "{")
+                depth++;
+            else if (c === "}" && --depth === 0) {
+                candidates.push(unfenced.slice(i, j + 1));
+                i = j;
+                break;
+            }
         }
     }
-    catch {
-        // Parsing failed
+    const greedy = unfenced.match(/\{[\s\S]*\}/);
+    if (greedy)
+        candidates.push(greedy[0]);
+    let firstError = "";
+    for (const candidate of candidates) {
+        try {
+            const value = JSON.parse(candidate);
+            if (value && typeof value === "object" && !Array.isArray(value))
+                return { value };
+        }
+        catch (e) {
+            if (!firstError)
+                firstError = e.message;
+        }
     }
-    return {};
+    const start = text.slice(0, 80).replace(/\s+/g, " ");
+    return { problem: `the reply was not a JSON object (${firstError || "no {...} in it"}); it began: ${start}${text.length > 80 ? "..." : ""}` };
 }
 function checkAbandonmentTriggers(state, thresholds) {
     if (state.patienceRemaining < thresholds.patienceMin) {