jev-devtools 0.2.0 → 0.4.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.4.0](https://img.shields.io/badge/npm-v0.4.0-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.4.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.
+**0.4.0 — pending publication.** Use a packed checkout until publication is confirmed in the changelog. **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.
 
@@ -34,17 +34,17 @@ The [setup skill](https://github.com/diegoag64/jev-devtools/blob/main/packages/j
 Install from npm:
 
 ```sh
-npm install jev-devtools
+npm install jev-devtools @typesafe-ai/sdk
 ```
 
-To try unpublished local changes instead:
+To install this checkout before publication or try later local changes:
 
 ```sh
 # From the jev-devtools repository root:
 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.4.0.tgz
 ```
 
 Mount once:
@@ -73,10 +73,54 @@ app.use(inspector.middleware); // Mount at root, before fallback handlers.
 
 Only calls through that client are captured. The React component subscribes via same-origin SSE, receiving an initial snapshot followed by changed traces. Older client/server combinations remain compatible through full snapshots. Both sides default to disabled. API keys remain server-side. Browser code is SSR-safe. The drawer uses a Shadow DOM boundary and its own stylesheet so host page selectors cannot alter its internal layout. Existing stylesheet imports remain supported; no Tailwind or shadcn installation is required. Drag the Flow canvas to pan, scroll/pinch to zoom, or use Fit.
 
-History is bounded to 50 calls in memory by default. API routes and inspector endpoints must share an adapter instance; distributed processes and edge runtimes are not supported. Non-loopback use requires explicit authorization. Captures include bounded/redacted context and answers, not hidden model reasoning.
+History is bounded to 50 calls in memory by default. API routes and inspector endpoints must share an adapter instance; distributed processes and edge runtimes are not supported. Without `authorize`, the middleware accepts only loopback connections; Web Request handlers can't see the connection's address, so run those servers on `127.0.0.1`. Captures include bounded/redacted context and answers, not hidden model reasoning.
 
 For Next.js App Router, use `getJevDevtools(appKey, optionsFactory)` from `/server` to share an adapter across server reloads, expose `handleNodeRoute` through an optional catch-all Route Handler, and mount the root component in a client boundary. See the [Next.js guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/nextjs.md) and runnable example. No Next dependency is required by this package.
 
 [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 with `jev-devtools/flow`
+
+Define calls, conditions, parallel checks, and named outcomes with `jev-devtools/flow`. **0.4.0 adds** server function steps (`task`), runtime request factories, bounded collections (`map`), returning conditionals (`if`), stateful iteration (`loop`), and strict numeric `.gt()` comparisons. The drawer connects request diagrams, function results, selected paths, collection items, and loop iterations on one canvas. Existing single-request integrations remain supported.
+
+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. `flow.branch` is terminal in its block; use `flow.if` when selected values feed shared downstream work. Tasks execute application code on Node with JSON-compatible inputs/results; maps and loops have explicit bounds. Runs have SDK retries and cooperative cancellation, with bounded in-memory inspector history. They do not provide durable or distributed execution. Keep the 0.4.0 server and drawer together to inspect its new step kinds.
+
+[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,143 @@
+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" | "gt" | "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>;
+    gt(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> = {
+    /** All answers, including question names created by a runtime request factory. */
+    readonly answers: FlowExpression<{
+        [K in keyof Q]: ResultFor<Q[K]>;
+    }>;
+    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;
+};
+/** Resolve nested references before invoking a server callback. */
+export type Resolved<T> = T extends FlowExpression<infer V> ? V : T extends readonly unknown[] ? {
+    [K in keyof T]: Resolved<T[K]>;
+} : T extends object ? {
+    [K in keyof T]: Resolved<T[K]>;
+} : T;
+export type TaskContext = {
+    signal: AbortSignal;
+    runId: string;
+    stepId: string;
+    executionId: string;
+};
+export type FlowTask<I, O> = {
+    input: I;
+    run: (input: Resolved<I>, context: TaskContext) => O | Promise<O>;
+    timeoutMs?: number;
+};
+export type FlowRequestFactory<I, Q extends Questions> = {
+    input: I;
+    /** Synchronous construction only; the runner executes the SDK request. */
+    request: (input: Resolved<I>) => SystemOneRequest<Q>;
+};
+/** 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 declare class FlowLoopLimitError extends Error {
+    readonly name = "FlowLoopLimitError";
+    constructor();
+}
+export interface FlowBuilder<T> {
+    readonly input: FlowExpression<T>;
+    jev<const Q extends Questions>(id: string, request: Request<Q>, display?: FlowDisplay): AnswerRefs<Q>;
+    jev<I, const Q extends Questions>(id: string, request: FlowRequestFactory<I, Q>, display?: FlowDisplay): AnswerRefs<Q>;
+    task<I, O>(id: string, task: FlowTask<I, O>, display?: FlowDisplay): FlowExpression<Awaited<O>>;
+    /** Execute a reusable item program with bounded concurrency; return results in input order. */
+    map<I, C, O>(id: string, options: {
+        items: FlowExpression<readonly I[]> | readonly I[];
+        input: C;
+        concurrency?: number;
+        maxItems: number;
+    }, build: (item: FlowBuilder<{
+        item: I;
+        index: number;
+        context: Resolved<C>;
+    }>) => FlowExpression<O>, display?: FlowDisplay): FlowExpression<O[]>;
+    /** Pre-test loop with JSON state, explicit context and a required iteration limit. */
+    loop<S, C>(id: string, options: {
+        initial: S | FlowExpression<S>;
+        input: C;
+        while: (state: FlowExpression<NoInfer<S>>) => FlowExpression<boolean>;
+        maxIterations: number;
+    }, build: (iteration: FlowBuilder<{
+        state: S;
+        index: number;
+        context: Resolved<C>;
+    }>) => FlowExpression<NoInfer<S>>, display?: FlowDisplay): FlowExpression<S>;
+    /** Execute one value-returning path, then continue with its typed result. */
+    if<A, B>(id: string, paths: {
+        when: FlowExpression<boolean>;
+        then: (path: FlowBuilder<T>) => FlowExpression<A>;
+        else: (path: FlowBuilder<T>) => FlowExpression<B>;
+    }, display?: FlowDisplay): FlowExpression<A | B>;
+    /** 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;
+    }>;
+};