jev-devtools 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,10 @@
 # Jev DevTools
 
-[![npm version 0.2.0](https://img.shields.io/badge/npm-v0.2.0-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.2.0)
+[![npm version 0.3.0](https://img.shields.io/badge/npm-v0.3.0-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.3.0)
 
 A React drawer and Node adapter for inspecting TypeSafe Jev requests with animated diagrams. Includes request history, context, questions, typed answers, transport attempts, and raw snapshots.
 
-**Experimental 0.1.x.** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
+**Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
 
 [Changelog and release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) — published versions and unreleased work.
 
@@ -44,7 +44,7 @@ To try unpublished local changes instead:
 npm ci
 npm run pack:devtools
 # From the consuming app:
-npm install /absolute/path/to/jev-devtools-0.2.0.tgz
+npm install /absolute/path/to/jev-devtools-0.3.0.tgz
 ```
 
 Mount once:
@@ -80,3 +80,47 @@ For Next.js App Router, use `getJevDevtools(appKey, optionsFactory)` from `/serv
 [Full integration guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md) · [Repository and playground](https://github.com/diegoag64/jev-devtools)
 
 MIT for project code. See bundled LICENSE and THIRD_PARTY_NOTICES.txt for original design attribution and TypeSafe branding.
+
+## Connected Jev flows
+
+New in **0.3.0**: define calls, conditions, parallel checks, and named outcomes with `jev-devtools/flow`. The drawer connects each request's complete diagram on one canvas. Condition cards show the incoming value and its requirement; optional titles and descriptions explain each step. Existing single-request integrations need no changes.
+
+On the server, reuse the instrumented `jev` client and `inspector` from the setup above:
+
+```ts
+import { defineJevFlow } from 'jev-devtools/flow';
+
+const review = defineJevFlow<{ message: string }>('review', (flow) => {
+  const decision = flow.jev('readiness', {
+    state: flow.input,
+    questions: { ready: { type: 'noul', instructions: 'Is this ready for review?' } },
+  }, { title: 'Assess readiness' });
+
+  return flow.branch('route', {
+    when: decision.answer('ready').noul.gte(0.9), // Your application's policy.
+    then: (path) => path.output('ready', { probability: decision.answer('ready').noul }, {
+      title: 'Ready for review', description: 'Return readiness to the application.',
+    }),
+    else: (path) => path.output('manual-review', undefined, { title: 'Needs manual review' }),
+  }, { title: 'Require at least 90% readiness' });
+});
+
+const result = await review.run({ message: 'Please review my ticket.' }, {
+  client: jev,
+  devtools: inspector,
+});
+// Handle result.outcome in your app. The flow does not execute business actions.
+```
+
+Define once in a Node module and run per request. Use `flow.parallel` for concurrent named lanes; downstream calls wait for every lane to succeed. Branches are terminal in their block. Runs are in-process, with bounded inspector history, SDK retries, and cancellation support; they are not durable workflows.
+
+[Full flow guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/flows.md) · [AI flow recipe](https://github.com/diegoag64/jev-devtools/blob/main/packages/jev-devtools/skills/setup-jev-devtools/references/flows.md)
+
+To have your coding agent add a flow after installation:
+
+```text
+Read node_modules/jev-devtools/skills/setup-jev-devtools/SKILL.md and references/flows.md.
+Build a flow for the scenario I describe using the shared server client/inspector.
+Preserve my routing policies, add clear step titles/descriptions, and verify with
+labeled samples before using live inference. Ask for any missing decision rules.
+```

package/lib/flow/index.d.ts

@@ -0,0 +1,82 @@
+import type { Questions, ResultFor, SystemOneRequest, TypeSafeClient } from "@typesafe-ai/sdk";
+import type { FlowDefinition, FlowDisplay, FlowRun } from "../src/flow-protocol.js";
+export type { FlowDisplay, FlowDefinition, FlowRun, FlowStep, } from "../src/flow-protocol.js";
+type Ast = {
+    op: "input";
+} | {
+    op: "ref";
+    id: string;
+} | {
+    op: "get";
+    from: Ast;
+    key: string;
+} | {
+    op: "literal";
+    value: unknown;
+} | {
+    op: "eq" | "lt" | "gte" | "all" | "any" | "not";
+    args: Ast[];
+};
+/** Inspectable expression, not an application callback. Use get() for input fields. */
+export declare class FlowExpression<T> {
+    readonly ast: Ast;
+    private readonly valueType;
+    constructor(ast: Ast, owner?: object);
+    get<K extends keyof T & (string | number)>(key: K): FlowExpression<T[K]>;
+    eq(value: T | FlowExpression<T>): FlowExpression<boolean>;
+    lt(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
+    gte(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
+}
+export declare const all: (...conditions: FlowExpression<boolean>[]) => FlowExpression<boolean>;
+export declare const any: (...conditions: FlowExpression<boolean>[]) => FlowExpression<boolean>;
+export declare const not: (condition: FlowExpression<boolean>) => FlowExpression<boolean>;
+export type FlowOutcome = {
+    outcome: string;
+    value?: unknown;
+};
+type AnswerRefs<Q extends Questions> = {
+    answer<K extends keyof Q & string>(name: K): {
+        [F in keyof ResultFor<Q[K]>]: FlowExpression<ResultFor<Q[K]>[F]>;
+    };
+};
+type Request<Q extends Questions> = Omit<SystemOneRequest<Q>, "state"> & {
+    state: unknown;
+};
+/** Observer contract used by createJevDevtools; execution never depends on successful recording. */
+export type FlowObserver = {
+    startFlow(definition: FlowDefinition, run: FlowRun): {
+        update(run: FlowRun): void;
+        request<T>(link: {
+            runId: string;
+            stepId: string;
+            executionId: string;
+        }, onTrace: (id: string) => void, callback: () => T): T;
+    } | undefined;
+};
+export type FlowRunOptions = {
+    client: Pick<TypeSafeClient, "systemOne">;
+    devtools?: FlowObserver;
+    signal?: AbortSignal;
+};
+export interface FlowBuilder<T> {
+    readonly input: FlowExpression<T>;
+    jev<const Q extends Questions>(id: string, request: Request<Q>, display?: FlowDisplay): AnswerRefs<Q>;
+    /** Terminal decision: each callback must return output() or another branch(). */
+    branch(id: string, paths: {
+        when: FlowExpression<boolean>;
+        then: (path: FlowBuilder<T>) => FlowExpression<FlowOutcome>;
+        else: (path: FlowBuilder<T>) => FlowExpression<FlowOutcome>;
+    }, display?: FlowDisplay): FlowExpression<FlowOutcome>;
+    parallel<const B extends Record<string, (lane: FlowBuilder<T>) => FlowExpression<unknown>>>(id: string, lanes: B, display?: FlowDisplay): {
+        [K in keyof B]: ReturnType<B[K]>;
+    };
+    output(name: string, value?: unknown, display?: FlowDisplay): FlowExpression<FlowOutcome>;
+}
+export declare function defineJevFlow<T>(name: string, build: (flow: FlowBuilder<T>) => FlowExpression<FlowOutcome>): {
+    definition: FlowDefinition;
+    run(data: T, options: FlowRunOptions): Promise<{
+        runId: string;
+        outcome: string;
+        value?: unknown;
+    }>;
+};