@neutrome/lilsdk-ts 0.3.3 → 0.3.5

package/README.md

@@ -19,7 +19,7 @@ This package owns:
 - `@neutrome/lilsdk-ts/synthetic`: request/message synthesis helpers such as `createModelProgram`, `makeMessage`, `makeToolCall`, `makeToolResponse`, and `appendToolInteraction`
 - `@neutrome/lilsdk-ts/tools`: `connectTools` tool-call loop
 - `@neutrome/lilsdk-ts/stream`: stream observation and output helpers
-- `@neutrome/lilsdk-ts/loops`: `retry`, `fallback`, and execute-only `runGoal` control-flow helpers
+- `@neutrome/lilsdk-ts/loops`: `retry`, `fallback`, and `createGoalExecutor` control-flow helpers
 - `@neutrome/lilsdk-ts/managed/twoPassExecutor`: `createTwoPassExecutor` and model invocation helpers
 - multi-pass authoring primitives used by virtual models
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/lilsdk-ts",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -13,7 +13,7 @@
     "./managed": "./src/managed/index.ts"
   },
   "dependencies": {
-    "@neutrome/lil-engine": "0.3.2"
+    "@neutrome/lil-engine": "0.3.4"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/loops/index.ts

@@ -1,5 +1,6 @@
-import type { Program } from "@neutrome/lil-engine";
+import { createProgram, deltaText, type Program } from "@neutrome/lil-engine";
 import type { Executor, ExecutorContext } from "../types.ts";
+import { appendAssistantMessage } from "../synthetic/index.ts";
 
 export type RetryOptions = {
   attempts?: number;
@@ -15,7 +16,7 @@ export type FallbackOptions = {
   onFallback?: (error: unknown, executorIndex: number) => void | Promise<void>;
 };
 
-export type GoalOptions = {
+export type GoalExecutorOptions = {
   draft: Executor;
   review: Executor;
   refine: (
@@ -28,8 +29,6 @@ export type GoalOptions = {
   maxIterations?: number;
 };
 
-export type ExecuteOnly = Pick<Executor, "execute">;
-
 export function retry(
   executor: Executor,
   options: RetryOptions = {},
@@ -127,33 +126,70 @@ export function fallback(
   };
 }
 
-export function runGoal(options: GoalOptions): ExecuteOnly {
+export function createGoalExecutor(options: GoalExecutorOptions): Executor {
   const maxIterations = positiveInteger(
     options.maxIterations ?? 3,
     "goal maxIterations",
   );
-  const executeGoal: Executor["execute"] = async (request, ctx) => {
-    let current = request;
-    let answer = request;
-
-    for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
-      answer = await options.draft.execute(current, childContext(ctx, attempt));
-      const review = await options.review.execute(
-        answer,
-        childContext(ctx, attempt),
-      );
-      if (await options.satisfied(review, attempt)) {
-        return answer;
-      }
-      if (attempt < maxIterations) {
-        current = await options.refine(current, answer, review, attempt);
+
+  return {
+    async execute(request, ctx) {
+      let current = request;
+      let answer = request;
+
+      for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
+        const attemptContext = childContext(ctx, attempt);
+        answer = await options.draft.execute(current, attemptContext);
+        const review = await options.review.execute(answer, attemptContext);
+        if (await options.satisfied(review, attempt)) return answer;
+        if (attempt < maxIterations) {
+          current = await options.refine(current, answer, review, attempt);
+        }
       }
-    }
 
-    return answer;
+      return answer;
+    },
+
+    async *stream(request, ctx) {
+      let current = request;
+      let answer = request;
+
+      for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
+        const attemptContext = childContext(ctx, attempt);
+        answer = yield* streamGoalStage(
+          options.draft.stream(current, attemptContext),
+          current,
+        );
+        const review = yield* streamGoalStage(
+          options.review.stream(answer, attemptContext),
+          answer,
+        );
+
+        if (await options.satisfied(review, attempt)) return;
+        if (attempt < maxIterations) {
+          current = await options.refine(current, answer, review, attempt);
+        }
+      }
+    },
   };
+}
+
+async function* streamGoalStage(
+  source: AsyncIterable<Program>,
+  fallback: Program,
+): AsyncGenerator<Program, Program> {
+  let final = fallback;
+  let transcript = "";
+
+  for await (const chunk of source) {
+    final = chunk;
+    transcript += deltaText(chunk);
+    yield chunk;
+  }
 
-  return { execute: executeGoal };
+  return transcript
+    ? appendAssistantMessage(createProgram(), transcript)
+    : final;
 }
 
 async function runRetry<T>(

package/test/lilsdk-ts.test.ts

@@ -22,8 +22,12 @@ import {
   appendAssistantMessage,
   appendToolInteraction,
 } from "../src/synthetic/index.ts";
-import { observeExecutionStream, writeReasoning } from "../src/stream/index.ts";
-import { fallback, retry, runGoal } from "../src/loops/index.ts";
+import {
+  observeExecutionStream,
+  streamTextResponse,
+  writeReasoning,
+} from "../src/stream/index.ts";
+import { createGoalExecutor, fallback, retry } from "../src/loops/index.ts";
 import {
   appendInternalDraft,
   createTwoPassExecutor,
@@ -513,9 +517,9 @@ describe("@neutrome/lilsdk-ts", () => {
     expect(fallbackCalls).toBe(0);
   });
 
-  it("runs execute-only goal loops until the review is satisfied", async () => {
+  it("runs goal loops until the review is satisfied", async () => {
     let attempts = 0;
-    const executor = runGoal({
+    const executor = createGoalExecutor({
       draft: executorFromExecute(async () => {
         attempts += 1;
         return appendAssistantMessage(
@@ -545,6 +549,74 @@ describe("@neutrome/lilsdk-ts", () => {
     expect(attempts).toBe(2);
     expect(contentText(result)).toBe("answer 2");
   });
+
+  it("streams draft and review passes through each goal iteration", async () => {
+    let attempts = 0;
+    const executor = createGoalExecutor({
+      draft: streamingExecutor(async function* () {
+        attempts += 1;
+        yield appendAssistantMessage(
+          { code: [], buffers: [] },
+          `answer ${attempts}`,
+        );
+      }),
+      review: streamingExecutor(async function* () {
+        yield appendAssistantMessage(
+          { code: [], buffers: [] },
+          attempts > 1 ? "pass" : "retry",
+        );
+      }),
+      satisfied(review) {
+        return contentText(review) === "pass";
+      },
+      refine(request) {
+        return request;
+      },
+    });
+
+    const chunks: Program[] = [];
+    for await (const chunk of executor.stream(
+      { code: [], buffers: [] },
+      buildExecutorContext(),
+    )) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks.map(contentText)).toEqual([
+      "answer 1",
+      "retry",
+      "answer 2",
+      "pass",
+    ]);
+  });
+
+  it("uses streamed text as the next goal stage's response", async () => {
+    let reviewedAnswer = "";
+    const executor = createGoalExecutor({
+      draft: streamingExecutor(async function* () {
+        yield* streamTextResponse("answer");
+      }),
+      review: streamingExecutor(async function* (request) {
+        reviewedAnswer = contentText(request);
+        yield* streamTextResponse("pass");
+      }),
+      satisfied(review) {
+        return contentText(review) === "pass";
+      },
+      refine(request) {
+        return request;
+      },
+    });
+
+    for await (const _chunk of executor.stream(
+      { code: [], buffers: [] },
+      buildExecutorContext(),
+    )) {
+      // Consume the entire goal stream.
+    }
+
+    expect(reviewedAnswer).toBe("answer");
+  });
 });
 
 function buildExecutorContext(