@obversa/runtime 0.2.0 → 0.2.1

package/dist/core/interaction.d.ts

@@ -0,0 +1,26 @@
+import { type JsonObject, type JsonValue } from '../graph/value.js';
+import type { InteractionBinding, InteractionResponse, Job, JobContext, Outcome } from './types.js';
+export type { InteractionBinding, InteractionResponse } from './types.js';
+/** Keep declared job identity separate from an engine's mutable call state. */
+export declare function interactionDeclaration<T extends Function>(job: T, declaration: unknown): T;
+export declare function interactionIdentity(value: unknown): string;
+export declare function jsonSnapshot(value: unknown): JsonObject;
+/** Save only JSON outcome fields; runtime Error objects are not continuation data. */
+export declare function outcomeSnapshot(outcome: Outcome): JsonObject;
+export declare function savedInteraction(ctx: JobContext, path: readonly string[], identity: string): JsonObject | undefined;
+export declare function hasSavedInteraction(ctx: JobContext, path: readonly string[]): boolean;
+export declare function checkpointInteraction(ctx: JobContext, path: readonly string[], identity: string, data: JsonObject | null): void;
+export declare function interactionResponse(value: unknown): InteractionResponse;
+export declare const DEFAULT_INTERACTION: InteractionBinding;
+export declare function requestInteraction(binding: InteractionBinding, question: string, input: JsonObject, ctx: JobContext, humanApproval?: boolean): Promise<{
+    response: InteractionResponse;
+} | {
+    paused: Outcome;
+}>;
+export interface HumanReviewOptions {
+    readonly question: string;
+    readonly input: JsonValue | ((ctx: JobContext) => JsonValue | Promise<JsonValue>);
+    readonly interaction: InteractionBinding;
+}
+/** A person's explicit approval is the only passing result of this review. */
+export declare function humanReview(name: string, options: HumanReviewOptions): Job;

package/dist/core/job.d.ts

@@ -5,6 +5,7 @@
  * an HTTP API, or any framework — swap the engine and the same job runs.
  */
 import type { Outcome, Job, JobContext, ProofArtifact } from './types.js';
+import { type InteractionBinding } from './interaction.js';
 /** Shared state key holding every engine answer the run recorded so far.
  * Written by the runtime beside each engine:usage event; read by workflow
  * layers that must compare what answered against what was declared. */
@@ -26,6 +27,8 @@ import { type LoopErrorCode } from './errors.js';
 import { type AgentDef } from './agent.js';
 import { kickback, revisionRequest } from './feedback.js';
 export interface AgentJobConfig {
+    /** Opt in to requesting a rich interaction and continuing this same model. */
+    readonly interaction?: InteractionBinding;
     /** Tag this job's engine answers with the review side and stage they
      * belong to, so a workflow layer can compare recorded sides without
      * inferring them from paths. Untagged answers are outside such gates. */

package/dist/core/judge.d.ts

@@ -7,6 +7,8 @@
  * 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 InteractionBinding, type InteractionResponse } from './interaction.js';
+import type { Outcome } from './types.js';
 import type { FeedbackActionSeverity, FeedbackFinding, Judge, JudgeAnswer, JudgeQuestions, JobContext } from './types.js';
 export type { Judge, JudgeAnswer, JudgeQuestion, JudgeQuestions } from './types.js';
 /**
@@ -25,6 +27,7 @@ export declare function stopQuestions(what?: string): JudgeQuestions;
 export declare function judge(seat: Judge['seat'], opts: {
     cap: number;
     questions?: JudgeQuestions;
+    interaction?: InteractionBinding;
 }): Judge;
 export declare function isJudge(value: unknown): value is Judge;
 /** A finding tagged block, by any reviewer, in this round's findings. */
@@ -41,6 +44,7 @@ export interface JudgeRound {
 }
 /** What the judge sees. `cap` rides along so it can reason about how much room is left. */
 export interface JudgeState {
+    readonly productFeedback?: readonly InteractionResponse[];
     readonly useCase?: string;
     /** The file being refined, relative to the workspace, when there is one. */
     readonly file?: string;
@@ -56,6 +60,15 @@ export interface JudgeDecision {
     readonly again: boolean;
     /** Always names the judge, so a kickback or a stop is traceable to it. */
     readonly reason: string;
+    /**
+     * What a stop means, when `again` is false. `ship`: the work holds as it
+     * is, so it stands as a pass carrying the judge's reason. `fail`: another
+     * round will not fix it, so the run stops there and the requesting side's
+     * own failure stands. `product_decision` asks a person, then returns the
+     * feedback to this judge without advancing the review round. Absent when
+     * `again` is true.
+     */
+    readonly stop?: 'ship' | 'fail' | 'product_decision';
 }
 /**
  * Route on the judge's answers. The chosen `stop_reason` is read first: in
@@ -66,6 +79,17 @@ export interface JudgeDecision {
  * 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.
+ *
+ * `product_decision` pauses for rich feedback and another judgment of the
+ * same work. For a terminal stop, `holds` and `over_polishing` say the work
+ * is good enough as it stands, so it ships as a pass; other stops, including
+ * `not_converging` and any choice a custom question set invents of its own,
+ * says the run should not ship silently, so it stops there and the
+ * requesting side's failure stands. The same split applies to the
+ * probability fallback: a clear `holds` or a clear "not worth doing" ships
+ * the work; an unclear "another round is not worth it" fails instead of
+ * shipping, since its own criteria already blend polish with a stall and
+ * cannot tell the two apart.
  */
 export declare function judgeDecision(answers: Readonly<Record<string, JudgeAnswer>>): JudgeDecision;
 /**
@@ -81,3 +105,15 @@ export declare function askJudge(cfg: Judge, state: JudgeState, ctx: JobContext,
     answers: Readonly<Record<string, JudgeAnswer>>;
     decision: JudgeDecision;
 }>;
+/** Resume only the deliberate product question; every returned answer goes back to this judge. */
+export declare function consultJudge(cfg: Judge, initialState: JudgeState, ctx: JobContext, path: readonly string[], options: {
+    readonly identity: string;
+    readonly pending: boolean;
+    readonly save: (state: JudgeState) => void;
+}): Promise<{
+    state: JudgeState;
+    decision: JudgeDecision;
+} | {
+    state: JudgeState;
+    paused: Outcome;
+}>;

package/dist/core/types.d.ts

@@ -18,9 +18,20 @@ import type { Engine, EngineRef, UsageReceipt } from '../engines/engine.js';
 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';
+import type { JsonObject, JsonValue, RunBrief } from '../graph/value.js';
 import type { CallbackEvent, ClaimResult, ReleaseResult, SubmitResult } from '../callback/client.js';
 import type { CallbackRequest } from '../callback/gate.js';
+export type InteractionResponse = JsonObject & {
+    readonly feedback: JsonValue;
+    readonly prompt: string;
+    readonly decision?: 'approved' | 'changes-requested';
+};
+export interface InteractionBinding {
+    readonly id: string;
+    readonly responseSchema: JsonObject;
+    /** Return no answer when the page is cancelled, interrupted or times out. */
+    readonly answer?: (request: CallbackRequest, signal: AbortSignal) => Promise<InteractionResponse | undefined>;
+}
 /**
  * The client a run's questions go through: the in-memory `CallbackClient`,
  * or the stored client (`createStoredCallbackClient`) whose questions survive
@@ -79,6 +90,26 @@ export interface Outcome {
      */
     revision?: RevisionRequest;
 }
+export type RecordedStage = {
+    readonly kind: 'interrupted';
+    readonly startLine: number;
+} | {
+    readonly kind: 'completed';
+    readonly outcome: Outcome;
+};
+export interface ResumedStageRecords {
+    readonly interactions: ReadonlyMap<string, {
+        identity: string;
+        workspace: string;
+        data: JsonObject;
+    }>;
+    readonly anchors: ReadonlyMap<string, {
+        readonly identity: string;
+        readonly workspace: string;
+        readonly recordId: string;
+    }>;
+    readonly stages: ReadonlyMap<string, RecordedStage>;
+}
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /**
  * Where a job's code lives: a working directory and (when it is a git repo) the
@@ -413,6 +444,7 @@ export interface Judge {
     readonly seat: TeamSeat;
     readonly cap: number;
     readonly questions: JudgeQuestions;
+    readonly interaction?: InteractionBinding;
 }
 export type KickbackBudget = number | Readonly<Record<string, number | Judge>>;
 export interface DagConfig {
@@ -685,6 +717,13 @@ export type LoopEvent = {
     path: string[];
     answers: Readonly<Record<string, JudgeAnswer>>;
     reason: string;
+} | {
+    kind: 'interaction:checkpoint';
+    ts: number;
+    path: string[];
+    identity: string;
+    workspace: string;
+    data: import('../graph/value.js').JsonObject | null;
 } | {
     kind: 'log';
     ts: number;

package/dist/runtime/persist.d.ts

@@ -1,31 +1,18 @@
+import type { UsageReceipt } from '../engines/engine.js';
 import type { RecordedEngineUsage } from '../core/job.js';
-import type { LoopEvent, Outcome } from '../core/types.js';
+import type { LoopEvent, ResumedStageRecords } from '../core/types.js';
+export type { RecordedStage, ResumedStageRecords } from '../core/types.js';
 interface RecorderOptions {
     thin?: boolean;
     /** Append to the existing record instead of truncating it. */
     resume?: boolean;
 }
-export type RecordedStage = {
-    readonly kind: 'interrupted';
-    readonly startLine: number;
-} | {
-    readonly kind: 'completed';
-    readonly outcome: Outcome;
-};
-export interface ResumedStageRecords {
-    readonly anchors: ReadonlyMap<string, {
-        readonly identity: string;
-        readonly workspace: string;
-        readonly recordId: string;
-    }>;
-    readonly stages: ReadonlyMap<string, RecordedStage>;
-}
 /** Read the latest stage state and the engine answers recorded for each stage.
  * A missing record has no stage state, so resume starts fresh. */
 export declare function readResumeRecord(path: string): {
+    readonly receipts: readonly UsageReceipt[];
     readonly outcomes: ResumedStageRecords;
     readonly usage: ReadonlyMap<string, readonly RecordedEngineUsage[]>;
 };
 /** Append every durable event as one JSON line. */
 export declare function makeRecorder(path: string, options?: RecorderOptions): (event: LoopEvent) => void;
-export {};

package/dist/workflow-support.js

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

package/dist/workflow.d.ts

@@ -1,5 +1,6 @@
 import { type TeamSeat } from '@obversa/api';
 import type { Job, Judge, Outcome, ConditionInput } from './core/types.js';
+import { type InteractionBinding } from './core/interaction.js';
 export interface BriefSource {
     readonly brief: string;
     readonly files?: readonly string[];
@@ -7,6 +8,7 @@ export interface BriefSource {
 export interface PersonRole {
     readonly kind: 'person';
     readonly question: string;
+    readonly interaction?: InteractionBinding;
 }
 export type WorkflowRole = TeamSeat | readonly TeamSeat[] | PersonRole;
 export interface WorkflowStageBase {
@@ -33,22 +35,32 @@ export type WorkflowStage = WorkflowStageBase & {} & ({
     readonly run?: never;
     readonly panel?: never;
     readonly input?: never;
+    readonly fn?: never;
 } | {
     readonly run: string | readonly string[];
     readonly agent?: never;
     readonly panel?: never;
     readonly input?: never;
+    readonly fn?: never;
 } | {
     readonly panel: string;
     readonly agree?: number;
     readonly agent?: never;
     readonly run?: never;
     readonly input?: never;
+    readonly fn?: never;
 } | {
     readonly input: string;
     readonly agent?: never;
     readonly run?: never;
     readonly panel?: never;
+    readonly fn?: never;
+} | {
+    readonly fn: Job;
+    readonly agent?: never;
+    readonly run?: never;
+    readonly panel?: never;
+    readonly input?: never;
 });
 export interface NamedStage {
     readonly name: string;
@@ -74,6 +86,8 @@ export interface WorkflowConfig {
     };
 }
 export declare function briefFromFile(path: string | URL): BriefSource;
-export declare function person(question: string): PersonRole;
+export declare function person(question: string, options?: {
+    interaction?: InteractionBinding;
+}): PersonRole;
 export declare function stage(name: string, config: WorkflowStage): NamedStage;
 export declare function workflow(name: string, config: WorkflowConfig): Job;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obversa/runtime",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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>",
@@ -51,16 +51,16 @@
   "dependencies": {
     "p-limit": "^7.3.0",
     "toposort": "^2.0.2",
-    "@obversa/core": "0.2.0"
+    "@obversa/core": "0.2.1"
   },
   "peerDependencies": {
-    "@obversa/api": "0.2.0"
+    "@obversa/api": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "22.12.0",
     "@types/toposort": "^2.0.7",
     "execa": "^9.6.1",
-    "@obversa/api": "0.2.0"
+    "@obversa/api": "0.2.1"
   },
   "keywords": [
     "agent",