@obversa/runtime 0.1.0 → 0.2.0

package/dist/core/judge.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A judge: a seat that answers typed questions about a piece of work and the
+ * rounds spent on it so far, in place of a plain review-round count. Used on
+ * a `workflow()` stage's `refine` and on a `dag()`'s `maxKickbacks`, between
+ * a review's verdict and the send-back.
+ *
+ * The default question set and the routing rule below make a loop that was
+ * first hand-wired as dag nodes into a runtime primitive.
+ */
+import type { FeedbackActionSeverity, FeedbackFinding, Judge, JudgeAnswer, JudgeQuestions, JobContext } from './types.js';
+export type { Judge, JudgeAnswer, JudgeQuestion, JudgeQuestions } from './types.js';
+/**
+ * The default question set: does the work hold for this use case, are the
+ * latest findings worth doing, is another round worth it, and why stop. A
+ * caller's own set replaces this wholesale (e.g. for a use case this
+ * wording doesn't fit); `what` names the thing being judged in the wording.
+ */
+export declare function stopQuestions(what?: string): JudgeQuestions;
+/**
+ * A judge for `refine` or `maxKickbacks`: `seat` runs with workspace mode
+ * none (it reads no file itself; everything it needs rides in the prompt),
+ * `cap` is the hard backstop on rounds regardless of what the judge says,
+ * and `questions` defaults to `stopQuestions()`.
+ */
+export declare function judge(seat: Judge['seat'], opts: {
+    cap: number;
+    questions?: JudgeQuestions;
+}): Judge;
+export declare function isJudge(value: unknown): value is Judge;
+/** A finding tagged block, by any reviewer, in this round's findings. */
+export declare function hasBlockFinding(findings: readonly FeedbackFinding[] | undefined): boolean;
+/** Every finding, counted by severity, the judge reads numbers, not a list to recount itself. */
+export declare function countBySeverity(findings: readonly FeedbackFinding[]): Record<FeedbackActionSeverity, number>;
+/** One round of the work the judge is watching converge. */
+export interface JudgeRound {
+    readonly round: number;
+    readonly findings: readonly FeedbackFinding[];
+    readonly counts: Readonly<Record<FeedbackActionSeverity, number>>;
+    /** Lines added or removed since the previous round, when the target is a file. */
+    readonly changedLines?: number;
+}
+/** What the judge sees. `cap` rides along so it can reason about how much room is left. */
+export interface JudgeState {
+    readonly useCase?: string;
+    /** The file being refined, relative to the workspace, when there is one. */
+    readonly file?: string;
+    /** That file's current content, when there is one. */
+    readonly draft?: string;
+    readonly latestFindings: readonly FeedbackFinding[];
+    readonly rounds: readonly JudgeRound[];
+    readonly round: number;
+    readonly cap: number;
+}
+export interface JudgeDecision {
+    /** Send the work back for another round. */
+    readonly again: boolean;
+    /** Always names the judge, so a kickback or a stop is traceable to it. */
+    readonly reason: string;
+}
+/**
+ * Route on the judge's answers. The chosen `stop_reason` is read first: in
+ * use it moves with the rounds while the probability answers stay flat, so it
+ * is the answer that discriminates. A clear yes or no from `holds`,
+ * `worth_doing` or `worth_another_round` is the fallback when the choice does
+ * not parse. Neither the cap nor a block finding is checked
+ * here: the caller enforces the cap itself (a loop's own `maxReviewRestarts`,
+ * or a dag's own kickback budget), and a block finding never reaches this
+ * function, it always goes back without asking the judge.
+ */
+export declare function judgeDecision(answers: Readonly<Record<string, JudgeAnswer>>): JudgeDecision;
+/**
+ * Ask the judge, and record its answer. Runs `cfg.seat` as a workspace-mode-
+ * none agent turn over `state` and `cfg.questions`, parses the reply as the
+ * judge engine's own `{ [question]: JudgeAnswer }` shape, and emits
+ * `refine:judge` so a person reading the record sees what it answered and
+ * why. A reply that fails to parse becomes an empty answers object ,
+ * `judgeDecision` reads that as `stop_reason: 'unknown'`, which is not a
+ * chosen stop, so the caller's own cap is what ends the rounds.
+ */
+export declare function askJudge(cfg: Judge, state: JudgeState, ctx: JobContext, path: readonly string[]): Promise<{
+    answers: Readonly<Record<string, JudgeAnswer>>;
+    decision: JudgeDecision;
+}>;

package/dist/core/types.d.ts

@@ -15,7 +15,7 @@
  * the primitive is the loop, not a pipeline.
  */
 import type { Engine, EngineRef, UsageReceipt } from '../engines/engine.js';
-import type { Memory } from '@obversa/api';
+import type { Memory, TeamSeat } from '@obversa/api';
 import type { LoopError } from './errors.js';
 import type { EnvHandle, Environment } from '../env/environment.js';
 import type { JsonValue, RunBrief } from '../graph/value.js';
@@ -371,7 +371,50 @@ export interface DagNode {
      */
     acceptsKickbackTo?: string[];
 }
-export type KickbackBudget = number | Readonly<Record<string, number>>;
+/**
+ * One question put to a judge, in the judge engine's own shape: `noul` asks
+ * for a probability, `choice` asks for one of the named criteria, `score`
+ * asks for a 0..1 rating per named criterion. `instructions` is what the
+ * judge reads; `criteria` are the standards it answers against.
+ */
+export type JudgeQuestion = {
+    readonly type: 'noul';
+    readonly instructions: string;
+    readonly criteria: {
+        readonly true: string;
+        readonly false: string;
+    };
+} | {
+    readonly type: 'choice';
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<string, string>>;
+} | {
+    readonly type: 'score';
+    readonly instructions: string;
+    readonly criteria: readonly string[];
+};
+export type JudgeQuestions = Readonly<Record<string, JudgeQuestion>>;
+/** One answer, in whichever of these fields its question type fills. */
+export interface JudgeAnswer {
+    readonly noul?: number;
+    readonly probability?: number;
+    readonly choice?: string;
+    readonly probabilities?: Readonly<Record<string, number>>;
+}
+/**
+ * A judge, in place of a plain round count, on a `workflow()` stage's
+ * `refine` or a `dag()`'s `maxKickbacks`: a seat that answers typed
+ * questions about the work and the rounds so far, between a review's
+ * verdict and the send-back. `cap` is the hard backstop, reached or not,
+ * it always stops the rounds. Built with `judge()`, never by hand.
+ */
+export interface Judge {
+    readonly kind: 'judge';
+    readonly seat: TeamSeat;
+    readonly cap: number;
+    readonly questions: JudgeQuestions;
+}
+export type KickbackBudget = number | Readonly<Record<string, number | Judge>>;
 export interface DagConfig {
     name: string;
     /** Node name → a `DagNode`, or a bare `Job` (shorthand for no deps/gates). */
@@ -626,6 +669,8 @@ export type LoopEvent = {
     path: string[];
     name: string;
     phase: 'use' | 'result';
+    /** The file, command, URL or pattern the tool acted on, when known. */
+    target?: string;
 } | {
     kind: 'engine:usage';
     ts: number;
@@ -634,6 +679,12 @@ export type LoopEvent = {
     usage: UsageReceipt;
     role?: 'writer' | 'reviewer';
     stage?: string;
+} | {
+    kind: 'refine:judge';
+    ts: number;
+    path: string[];
+    answers: Readonly<Record<string, JudgeAnswer>>;
+    reason: string;
 } | {
     kind: 'log';
     ts: number;

package/dist/runtime/monitor.d.ts

@@ -58,13 +58,16 @@ export interface MonitorState {
         decisionText: string;
         input: JsonValue;
     }>;
+    /**
+     * The record, already in the one line `formatEvent` would print for it: the
+     * console and this page must never disagree about what an event says, so
+     * neither keeps its own partial fields to re-render from. An event with
+     * nothing worth telling a person (thinking with no text yet) contributes no
+     * line at all, rather than a row that says only its own kind.
+     */
     events: Array<{
-        kind: string;
         ts: number;
-        path: string[];
-        node?: string;
-        label?: string;
-        summary?: string;
+        line: string;
     }>;
 }
 export interface StartedMonitor {

package/dist/runtime/render-record.d.ts

@@ -0,0 +1,68 @@
+import type { LoopEvent } from '../core/types.js';
+export interface RecordLine {
+    readonly kind: string;
+    readonly text: string;
+}
+export interface RecordEngineCall {
+    readonly model: string;
+    readonly inputTokens: number | null;
+    readonly outputTokens: number | null;
+}
+export interface RecordToolUse {
+    readonly name: string;
+    readonly count: number;
+    readonly targets: readonly string[];
+}
+export interface RecordKickback {
+    readonly from: string;
+    readonly to: string;
+    readonly reason: string;
+    readonly count: number;
+    readonly limit: number;
+    readonly accepted: boolean;
+    readonly note?: string;
+}
+export interface RecordOutcome {
+    readonly status: string;
+    readonly summary?: string;
+}
+export interface RecordNodeRun {
+    readonly attempt: number;
+    readonly startedAt: number | null;
+    readonly endedAt: number | null;
+    readonly outcome: RecordOutcome | null;
+    readonly kickback: RecordKickback | null;
+    readonly engineCalls: readonly RecordEngineCall[];
+    readonly tools: readonly RecordToolUse[];
+    readonly lines: readonly RecordLine[];
+}
+export interface RecordNodeSummary {
+    readonly node: string;
+    readonly runs: readonly RecordNodeRun[];
+}
+export interface RecordUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadInputTokens: number;
+    readonly unmeasuredCalls: number;
+}
+export interface RecordSummary {
+    readonly name: string | null;
+    readonly startedAt: number | null;
+    readonly endedAt: number | null;
+    readonly outcome: RecordOutcome | null;
+    readonly usage: RecordUsage;
+    readonly monitor: string | null;
+    readonly nodes: readonly RecordNodeSummary[];
+    readonly lines: readonly RecordLine[];
+}
+export interface RenderRecordOptions {
+    readonly lineWidth?: number;
+}
+export declare function summarizeRecord(events: readonly LoopEvent[]): RecordSummary;
+export declare function formatDuration(ms: number): string;
+export declare function renderRecord(events: readonly LoopEvent[], options?: RenderRecordOptions): string;
+export declare function readRecordFile(path: string): {
+    events: LoopEvent[];
+    unreadable: number;
+};

package/dist/workflow-support.js

@@ -1,4 +1,4 @@
-export { INVALID_TEAM_DECISION, assertDistinctSeats, outcomeFromAgentText, panelReviewers, requireNoFiles, requireNonEmptyFiles, seatIdentity, teamAgent } from './chunk-DV5P4QLI.js';
+export { INVALID_TEAM_DECISION, assertDistinctSeats, outcomeFromAgentText, panelReviewers, requireNoFiles, requireNonEmptyFiles, seatIdentity, teamAgent } from './chunk-ZXVFWRW5.js';
 import './chunk-NIBHM5I5.js';
 import './chunk-5GLEABOU.js';
 //# sourceMappingURL=workflow-support.js.map

package/dist/workflow.d.ts

@@ -1,5 +1,5 @@
 import { type TeamSeat } from '@obversa/api';
-import type { Job, Outcome, ConditionInput } from './core/types.js';
+import type { Job, Judge, Outcome, ConditionInput } from './core/types.js';
 export interface BriefSource {
     readonly brief: string;
     readonly files?: readonly string[];
@@ -17,7 +17,13 @@ export interface WorkflowStageBase {
     readonly optional?: boolean;
     readonly needs?: string | readonly string[];
     readonly sendsBackTo?: string;
-    readonly retry?: number;
+    /**
+     * How many more rounds a reviewed stage or a kickback target gets: a plain
+     * count, or `judge(seat, { cap, questions })` to let a seat decide between
+     * a review's verdict and the send-back, with `cap` as the hard backstop
+     * that stops it regardless of what the judge says.
+     */
+    readonly refine?: number | Judge;
     /** An interrupted attempt may run again without a person's reconciliation. */
     readonly retrySafe?: boolean;
 }

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@obversa/runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Model how your team really works. Durable agent workflows, reviews that send work back, no database needed.",
   "license": "MIT",
   "author": "Jonny Neill <jonnyneill@hotmail.com>",
   "type": "module",
   "main": "./dist/api.js",
+  "bin": {
+    "obversa-record": "./dist/bin/record.js"
+  },
   "types": "./dist/api.d.ts",
   "exports": {
     ".": {
@@ -48,16 +51,16 @@
   "dependencies": {
     "p-limit": "^7.3.0",
     "toposort": "^2.0.2",
-    "@obversa/core": "0.1.0"
+    "@obversa/core": "0.2.0"
   },
   "peerDependencies": {
-    "@obversa/api": "0.1.0"
+    "@obversa/api": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "22.12.0",
     "@types/toposort": "^2.0.7",
     "execa": "^9.6.1",
-    "@obversa/api": "0.1.0"
+    "@obversa/api": "0.2.0"
   },
   "keywords": [
     "agent",