@wrenautomation/raven 0.1.1 → 0.2.0

package/README.md

@@ -21,8 +21,9 @@ learns. Raven never loops; the runner takes the edge.
 ## CLI
 
 Needs Node 24+. The model is a command that reads the prompt on stdin and prints the answer.
-Default `claude -p`, so Claude Code is the model in any terminal; `RAVEN_MODEL` or `--model`
-changes it; `--no-model` plans from your own queries only.
+Default `claude -p --output-format json`, so Claude Code is the model in any terminal and its
+envelope gives the cost per call; `RAVEN_MODEL` or `--model` changes it (plain text out is fine);
+`--no-model` plans from your own queries only.
 
 ```sh
 npm i @wrenautomation/raven
@@ -38,7 +39,10 @@ npx raven plans web > plans/web.json
 ```ts
 import { plan, triage, review, type Model } from "@wrenautomation/raven";
 
-const model: Model = { id: "claude-sonnet-5-5", ask: (prompt, shape) => yourClient.json(prompt, shape) };
+const model: Model = {
+  id: "claude-sonnet-5-5",
+  ask: async (prompt, shape) => ({ value: await yourClient.json(prompt, shape), usage: { usd: 0.01 } }),
+};
 const p = await plan({ ask: { text, kind: "web", known }, model, proposals: [byHand] });
 const reads = await triage(hits, p, model);
 const edge = await review(round, model);

package/dist/app/cli.js

@@ -15,7 +15,7 @@ import { defaultPlanFile, PLAN_KINDS } from "../plans/index.js";
 import { review } from "../review.js";
 import { triage } from "../triage.js";
 import { AskKind, HitView, Plan, PlanFile, Round, YieldRow, z } from "../types.js";
-const DEFAULT_MODEL = "claude -p";
+const DEFAULT_MODEL = "claude -p --output-format json";
 const readJson = (path, shape) => shape.parse(JSON.parse(readFileSync(path, "utf8")));
 const print = (x) => console.log(JSON.stringify(x, null, 2));
 const more = (v, prev) => [...prev, v];

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { commandModel, fill, type Model, parseAnswer, scriptedModel } from "./model.js";
+export { type Answer, commandModel, fill, type Model, parseAnswer, readOutput, scriptedModel, type Usage, } from "./model.js";
 export { mergeProposals, type PlanInput, plan, propose, proposePrompt } from "./plan.js";
 export { defaultPlanFile, PLAN_KINDS } from "./plans/index.js";
 export { renderHits, renderYield } from "./render.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { commandModel, fill, parseAnswer, scriptedModel } from "./model.js";
+export { commandModel, fill, parseAnswer, readOutput, scriptedModel, } from "./model.js";
 export { mergeProposals, plan, propose, proposePrompt } from "./plan.js";
 export { defaultPlanFile, PLAN_KINDS } from "./plans/index.js";
 export { renderHits, renderYield } from "./render.js";

package/dist/model.d.ts

@@ -1,19 +1,36 @@
 import type { ZodType } from "zod";
+/** What one model call cost, as far as the model says. All optional: a shell command may say nothing. */
+export interface Usage {
+    /** Tokens in and out. */
+    input?: number;
+    output?: number;
+    usd?: number;
+}
+/** A parsed answer and what it cost: the ledger keeps both. */
+export interface Answer<T> {
+    value: T;
+    usage?: Usage;
+}
 export interface Model {
     /** What goes in `by` on the records this model writes. */
     id: string;
-    ask<T>(prompt: string, shape: ZodType<T>): Promise<T>;
+    ask<T>(prompt: string, shape: ZodType<T>): Promise<Answer<T>>;
 }
 /** `{name}` marks filled in one pass; a `{word}` with no value stays as text. */
 export declare const fill: (template: string, values: Readonly<Record<string, string>>) => string;
 /**
- * The first JSON object in a model's text, parsed into the shape. Fences and prose around
- * it are dropped. Throws with the model's text when nothing parses.
+ * The first JSON object of the shape in a model's text, found by brace balance: fences, prose
+ * and stray braces around it are passed over. Throws with the model's text when nothing parses.
  */
 export declare function parseAnswer<T>(text: string, shape: ZodType<T>): T;
+/** A command's stdout as an answer: the envelope's text and usage when it printed one, else the text. */
+export declare function readOutput(stdout: string): {
+    text: string;
+    usage?: Usage;
+};
 /**
- * A model that is a shell command: the prompt on stdin, the answer on stdout. `claude -p`
- * makes Claude Code the planner's model from any terminal.
+ * A model that is a shell command: the prompt on stdin, the answer on stdout. When stdout is
+ * Claude Code's JSON envelope (`claude -p --output-format json`) the usage comes with it.
  */
 export declare function commandModel(command: string, id?: string): Model;
 /** A model that answers from a fixed list, in order: tests and dry runs. */

package/dist/model.js

@@ -1,33 +1,77 @@
 /**
  * The model seam. Raven never picks a model: a caller hands in one `Model`, a function from a
- * prompt and an answer shape to a parsed answer, and its id goes on every record it writes. In
- * a terminal the model is a command that reads the prompt on stdin and prints the answer
- * (`claude -p` by default); in wren it wraps the LLM client.
+ * prompt and an answer shape to a parsed answer with what it cost, and its id goes on every
+ * record it writes. In a terminal the model is a command that reads the prompt on stdin and
+ * prints the answer (`claude -p --output-format json` by default); in wren it wraps the LLM
+ * client.
  */
 import { spawn } from "node:child_process";
 /** `{name}` marks filled in one pass; a `{word}` with no value stays as text. */
 export const fill = (template, values) => template.replace(/\{(\w+)\}/g, (mark, name) => values[name] ?? mark);
+/** Every balanced `{...}` in a text, by start position: an outer object comes before its inner ones. */
+function* objects(text) {
+    for (let start = text.indexOf("{"); start >= 0; start = text.indexOf("{", start + 1)) {
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = start; i < text.length; i++) {
+            const c = text[i];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (c === "\\")
+                    escaped = true;
+                else if (c === '"')
+                    inString = false;
+            }
+            else if (c === '"')
+                inString = true;
+            else if (c === "{")
+                depth++;
+            else if (c === "}" && --depth === 0) {
+                yield text.slice(start, i + 1);
+                break;
+            }
+        }
+    }
+}
 /**
- * The first JSON object in a model's text, parsed into the shape. Fences and prose around
- * it are dropped. Throws with the model's text when nothing parses.
+ * The first JSON object of the shape in a model's text, found by brace balance: fences, prose
+ * and stray braces around it are passed over. Throws with the model's text when nothing parses.
  */
 export function parseAnswer(text, shape) {
-    const start = text.indexOf("{");
-    if (start >= 0) {
-        for (let end = text.lastIndexOf("}"); end > start; end = text.lastIndexOf("}", end - 1)) {
-            try {
-                const out = shape.safeParse(JSON.parse(text.slice(start, end + 1)));
-                if (out.success)
-                    return out.data;
-            }
-            catch { }
+    for (const candidate of objects(text)) {
+        try {
+            const out = shape.safeParse(JSON.parse(candidate));
+            if (out.success)
+                return out.data;
         }
+        catch { }
     }
     throw new Error(`no answer of the expected shape in: ${text.slice(0, 400)}`);
 }
+const isEnvelope = (x) => typeof x === "object" && x !== null && typeof x.result === "string";
+/** A command's stdout as an answer: the envelope's text and usage when it printed one, else the text. */
+export function readOutput(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (isEnvelope(parsed)) {
+            const usage = {};
+            if (parsed.usage?.input_tokens !== undefined)
+                usage.input = parsed.usage.input_tokens;
+            if (parsed.usage?.output_tokens !== undefined)
+                usage.output = parsed.usage.output_tokens;
+            if (parsed.total_cost_usd !== undefined)
+                usage.usd = parsed.total_cost_usd;
+            return { text: parsed.result, usage };
+        }
+    }
+    catch { }
+    return { text: stdout };
+}
 /**
- * A model that is a shell command: the prompt on stdin, the answer on stdout. `claude -p`
- * makes Claude Code the planner's model from any terminal.
+ * A model that is a shell command: the prompt on stdin, the answer on stdout. When stdout is
+ * Claude Code's JSON envelope (`claude -p --output-format json`) the usage comes with it.
  */
 export function commandModel(command, id = command) {
     return {
@@ -38,11 +82,12 @@ export function commandModel(command, id = command) {
             child.stdout.on("data", (b) => out.push(b));
             child.on("error", reject);
             child.on("close", (code) => {
-                const text = Buffer.concat(out).toString("utf8");
+                const stdout = Buffer.concat(out).toString("utf8");
                 if (code !== 0)
-                    return reject(new Error(`${command} exited ${code}: ${text.slice(0, 400)}`));
+                    return reject(new Error(`${command} exited ${code}: ${stdout.slice(0, 400)}`));
                 try {
-                    resolve(parseAnswer(text, shape));
+                    const { text, usage } = readOutput(stdout);
+                    resolve({ value: parseAnswer(text, shape), ...(usage ? { usage } : {}) });
                 }
                 catch (e) {
                     reject(e);
@@ -61,7 +106,7 @@ export function scriptedModel(answers, id = "scripted") {
             const a = answers[i++];
             if (a === undefined)
                 throw new Error(`scripted model has no answer ${i}`);
-            return shape.parse(a);
+            return { value: shape.parse(a) };
         },
     };
 }

package/dist/plan.js

@@ -22,7 +22,7 @@ export function proposePrompt(ask, planFile, yieldRows, now) {
 }
 /** The model's proposal for an ask under a plan file. */
 export async function propose(ask, planFile, model, yieldRows = [], now = new Date()) {
-    const out = await model.ask(proposePrompt(ask, planFile, yieldRows, now), ProposalAnswer);
+    const { value: out } = await model.ask(proposePrompt(ask, planFile, yieldRows, now), ProposalAnswer);
     return {
         from: "ai",
         by: model.id,

package/dist/plans/index.js

@@ -9,7 +9,7 @@ const SHAPE_HITS = `Return ONLY a JSON object, no prose, exactly this shape:
 {"hits": [{"url": "...", "read": true, "why": "..."}]}`;
 const SHAPE_EDGE = `Return ONLY a JSON object, no prose, exactly this shape:
 {"next": "stop", "why": "..."}
-where "next" is "stop", "again" (a new round from plan) or "back" (rerun one step of this round, named in "to": "plan", "fetch", "read" or "extract").`;
+where "next" is "stop", "again" (a new round from plan) or "back" (rerun one step of this round, named in "to": "plan", "fetch", "triage", "read" or "extract").`;
 const CONTEXT = `Ask: {ask}
 Known already (look past these):
 {known}

package/dist/review.js

@@ -35,7 +35,7 @@ export async function review(round, model, options = {}) {
         };
     }
     const planFile = options.planFile ?? defaultPlanFile(round.ask.kind);
-    const out = await model.ask(reviewPrompt(round, planFile), EdgeAnswer);
+    const { value: out } = await model.ask(reviewPrompt(round, planFile), EdgeAnswer);
     const edge = { next: out.next, why: out.why, from: "ai", by: model.id };
     if (out.next === "back")
         edge.to = out.to ?? "fetch";

package/dist/triage.d.ts

@@ -4,12 +4,12 @@
  * caps it; a hit the model did not name is a skip, written down as one.
  */
 import { type Model } from "./model.js";
-import { type HitView, type Plan, type PlanFile, type Triage, type YieldRow } from "./types.js";
+import { HitView, type HitViewIn, type Plan, type PlanFile, type Triage, type YieldRow } from "./types.js";
 /** One hit per url, sources merged, order of first sight. */
-export declare function dedupeHits(hits: readonly HitView[]): HitView[];
+export declare function dedupeHits(hits: readonly HitViewIn[]): HitView[];
 export declare function triagePrompt(hits: readonly HitView[], plan: Plan, planFile: PlanFile, yieldRows: readonly YieldRow[]): string;
 /** Read or skip per hit, with why. Reads over the plan's budget flip to skips, in the model's order. */
-export declare function triage(hits: readonly HitView[], plan: Plan, model: Model, options?: {
+export declare function triage(hits: readonly HitViewIn[], plan: Plan, model: Model, options?: {
     planFile?: PlanFile;
     yieldRows?: readonly YieldRow[];
 }): Promise<Triage[]>;

package/dist/triage.js

@@ -6,14 +6,14 @@
 import { fill } from "./model.js";
 import { defaultPlanFile } from "./plans/index.js";
 import { lines, renderHits, renderYield } from "./render.js";
-import { z } from "./types.js";
+import { HitView, z, } from "./types.js";
 const TriageAnswer = z.object({
     hits: z.array(z.object({ url: z.string(), read: z.boolean(), why: z.string() })),
 });
 /** One hit per url, sources merged, order of first sight. */
 export function dedupeHits(hits) {
     const byUrl = new Map();
-    for (const h of hits) {
+    for (const h of hits.map((x) => HitView.parse(x))) {
         const url = h.url.trim();
         const have = byUrl.get(url);
         if (!have) {
@@ -46,7 +46,7 @@ export async function triage(hits, plan, model, options = {}) {
     if (!unique.length)
         return [];
     const planFile = options.planFile ?? defaultPlanFile(plan.ask.kind);
-    const out = await model.ask(triagePrompt(unique, plan, planFile, options.yieldRows ?? []), TriageAnswer);
+    const { value: out } = await model.ask(triagePrompt(unique, plan, planFile, options.yieldRows ?? []), TriageAnswer);
     const said = new Map(out.hits.map((h) => [h.url.trim(), h]));
     let reads = 0;
     return unique.map((h) => {

package/dist/types.d.ts

@@ -195,6 +195,8 @@ export declare const HitView: z.ZodObject<{
     sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type HitView = z.infer<typeof HitView>;
+/** A hit as a caller may pass it: `sources` optional. */
+export type HitViewIn = z.input<typeof HitView>;
 export declare const Triage: z.ZodObject<{
     url: z.ZodString;
     read: z.ZodBoolean;
@@ -235,6 +237,7 @@ export declare const Round: z.ZodObject<{
 }, z.core.$strip>;
 export type Round = z.infer<typeof Round>;
 export declare const Step: z.ZodEnum<{
+    triage: "triage";
     read: "read";
     plan: "plan";
     fetch: "fetch";
@@ -249,6 +252,7 @@ export declare const Edge: z.ZodObject<{
         back: "back";
     }>;
     to: z.ZodOptional<z.ZodEnum<{
+        triage: "triage";
         read: "read";
         plan: "plan";
         fetch: "fetch";

package/dist/types.js

@@ -121,7 +121,7 @@ export const Round = z.object({
     /** What went wrong or ran out, one line each. */
     notes: z.array(z.string()).default([]),
 });
-export const Step = z.enum(["plan", "fetch", "read", "extract"]);
+export const Step = z.enum(["plan", "fetch", "triage", "read", "extract"]);
 /** The edge out of a round. `again` is a new round from `plan`; `back` reruns one step of this round. */
 export const Edge = z.object({
     next: z.enum(["stop", "again", "back"]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrenautomation/raven",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Ask in, plan out. The planner of Wren's research engine: typed queries with who proposed them and why, proposals merged into one plan under a plan file per ask kind, read-or-skip on hits, and the edge to take after a round. Pure functions and prompts; the model is injected.",
   "license": "PolyForm-Shield-1.0.0",
   "repository": {