@wrenautomation/raven 0.2.0 → 0.2.2

package/README.md

@@ -12,7 +12,7 @@ Three calls, one record each:
 |---|---|---|
 | `plan` | an ask (text, kind, what is known), proposals from people or other models, yield rows from earlier runs | a `Plan`: typed queries, each with `why`, `from` (ai or human) and `by` (model id, plan file or person), the sources it may use, the budget, and a snapshot of what raven was given |
 | `triage` | hits as a source shows them for free (title, channel, length, date, snippet, which sources returned it) | read or skip per hit, with why; the read budget caps it |
-| `review` | what a round came to (counts, found lines, notes) | the edge: `stop`, `again` (a new round from plan) or `back` (rerun one step), with why |
+| `review` | what a round came to (counts, found lines, the extractor's verdict and gap per read, notes) | the edge: `stop`, `again` (a new round from plan) or `back` (rerun one step), with why |
 
 Ask kinds: `web`, `video`, `channel`, `person`, `site`. Each has a default plan file
 (prompts, sources, budget). Copy one, tune it, keep it beside your ledger: that is where a run
@@ -23,7 +23,8 @@ learns. Raven never loops; the runner takes the edge.
 Needs Node 24+. The model is a command that reads the prompt on stdin and prints the answer.
 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.
+`--no-model` plans from your own queries only. A command that says nothing for 3 minutes is
+killed and the call fails with why.
 
 ```sh
 npm i @wrenautomation/raven

package/dist/model.d.ts

@@ -31,7 +31,9 @@ export declare function readOutput(stdout: string): {
 /**
  * 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.
+ * A command that says nothing for `timeoutMs` (3 minutes) is killed and the ask fails with
+ * why, so a hung model never hangs the run.
  */
-export declare function commandModel(command: string, id?: string): Model;
+export declare function commandModel(command: string, id?: string, timeoutMs?: number): Model;
 /** A model that answers from a fixed list, in order: tests and dry runs. */
 export declare function scriptedModel(answers: unknown[], id?: string): Model;

package/dist/model.js

@@ -72,17 +72,30 @@ export function readOutput(stdout) {
 /**
  * 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.
+ * A command that says nothing for `timeoutMs` (3 minutes) is killed and the ask fails with
+ * why, so a hung model never hangs the run.
  */
-export function commandModel(command, id = command) {
+export function commandModel(command, id = command, timeoutMs = 180_000) {
     return {
         id,
         ask: (prompt, shape) => new Promise((resolve, reject) => {
             const child = spawn(command, { shell: true, stdio: ["pipe", "pipe", "inherit"] });
             const out = [];
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill();
+            }, timeoutMs);
             child.stdout.on("data", (b) => out.push(b));
-            child.on("error", reject);
+            child.on("error", (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
             child.on("close", (code) => {
+                clearTimeout(timer);
                 const stdout = Buffer.concat(out).toString("utf8");
+                if (timedOut)
+                    return reject(new Error(`${command}: no answer in ${Math.round(timeoutMs / 1000)}s`));
                 if (code !== 0)
                     return reject(new Error(`${command} exited ${code}: ${stdout.slice(0, 400)}`));
                 try {

package/dist/plans/index.js

@@ -25,7 +25,8 @@ ${SHAPE_EDGE}
 
 Rules:
 - "stop" when the found lines answer the ask, or when another round would likely add nothing.
-- "again" when the ask is still open and new queries could find more. Say what to look for next in "why".
+- "again" when the ask is still open and new queries could find more. The gaps say what is missing; say what to look for next in "why".
+- "again" too when the reads were mostly "thin" or "off": the queries found the wrong pages, so plan different ones.
 - "back" when one step of this round failed for a reason a rerun fixes (a source was down, reads timed out). Name the step in "to".
 - "why" is one short line a person reads to agree or not.
 
@@ -33,12 +34,14 @@ Ask: {ask}
 Round {round} of at most {rounds}. Hits {hits}, reads {reads}, findings proposed {proposed}, kept {kept}.
 Found:
 {found}
+Read (quality: rich, thin, off or empty; then the gap, what the ask still lacks):
+{verdicts}
 Notes:
 {notes}`;
 const web = {
     id: "raven/web",
     kind: "web",
-    version: 1,
+    version: 2,
     propose: `You plan web searches for one research ask.
 
 ${SHAPE_QUERIES}
@@ -69,7 +72,7 @@ Hits:
 const video = {
     id: "raven/video",
     kind: "video",
-    version: 1,
+    version: 2,
     propose: `You plan video searches for one research ask: talks, walkthroughs, interviews and reviews on YouTube and podcast feeds.
 
 ${SHAPE_QUERIES}
@@ -100,7 +103,7 @@ Hits:
 const channel = {
     id: "raven/channel",
     kind: "channel",
-    version: 1,
+    version: 2,
     propose: `You plan searches that find the people and channels worth following for one research ask: creators, newsletters, podcasts, forums.
 
 ${SHAPE_QUERIES}
@@ -129,7 +132,7 @@ Hits:
 const person = {
     id: "raven/person",
     kind: "person",
-    version: 1,
+    version: 2,
     propose: `You plan searches about one person or company for one research ask: what they do, what they said, what others say about them.
 
 ${SHAPE_QUERIES}
@@ -160,7 +163,7 @@ Hits:
 const site = {
     id: "raven/site",
     kind: "site",
-    version: 1,
+    version: 2,
     propose: `You plan searches inside one website for one research ask. Every query runs on {site} only.
 
 ${SHAPE_QUERIES}

package/dist/review.js

@@ -12,6 +12,7 @@ const EdgeAnswer = z.object({
     to: Step.optional(),
     why: z.string(),
 });
+const verdictLine = (v) => `${v.url}: ${v.quality}${v.gap ? `. ${v.gap}` : ""}`;
 export function reviewPrompt(round, planFile) {
     return fill(planFile.review, {
         ask: round.ask.text,
@@ -23,6 +24,7 @@ export function reviewPrompt(round, planFile) {
         kept: String(round.kept),
         found: lines(round.found),
         notes: lines(round.notes, "(none)"),
+        verdicts: lines(round.verdicts.map(verdictLine), "(none)"),
     });
 }
 export async function review(round, model, options = {}) {

package/dist/types.d.ts

@@ -208,7 +208,19 @@ export declare const Triage: z.ZodObject<{
     by: z.ZodString;
 }, z.core.$strip>;
 export type Triage = z.infer<typeof Triage>;
-/** What one round came to, as counts and notes. The runner fills it; raven reads it. */
+/** The extractor's word on one read document: how much of the ask it served, what is still missing. */
+export declare const Verdict: z.ZodObject<{
+    url: z.ZodString;
+    quality: z.ZodEnum<{
+        rich: "rich";
+        thin: "thin";
+        off: "off";
+        empty: "empty";
+    }>;
+    gap: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Verdict = z.infer<typeof Verdict>;
+/** What one round came to, as counts, verdicts and notes. The runner fills it; raven reads it. */
 export declare const Round: z.ZodObject<{
     ask: z.ZodObject<{
         text: z.ZodString;
@@ -234,6 +246,16 @@ export declare const Round: z.ZodObject<{
     kept: z.ZodNumber;
     found: z.ZodDefault<z.ZodArray<z.ZodString>>;
     notes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    verdicts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        quality: z.ZodEnum<{
+            rich: "rich";
+            thin: "thin";
+            off: "off";
+            empty: "empty";
+        }>;
+        gap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type Round = z.infer<typeof Round>;
 export declare const Step: z.ZodEnum<{

package/dist/types.js

@@ -107,7 +107,13 @@ export const Triage = z.object({
     from: From,
     by: z.string(),
 });
-/** What one round came to, as counts and notes. The runner fills it; raven reads it. */
+/** The extractor's word on one read document: how much of the ask it served, what is still missing. */
+export const Verdict = z.object({
+    url: z.string(),
+    quality: z.enum(["rich", "thin", "off", "empty"]),
+    gap: z.string().optional(),
+});
+/** What one round came to, as counts, verdicts and notes. The runner fills it; raven reads it. */
 export const Round = z.object({
     ask: Ask,
     round: z.number().int().positive(),
@@ -120,6 +126,8 @@ export const Round = z.object({
     found: z.array(z.string()).default([]),
     /** What went wrong or ran out, one line each. */
     notes: z.array(z.string()).default([]),
+    /** The extractor's verdict on each document read this round: the planner sees what the reads were worth. */
+    verdicts: z.array(Verdict).default([]),
 });
 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrenautomation/raven",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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": {