@neutrome/lilsdk-ts 0.1.3 → 0.2.1

package/src/types.ts

@@ -1,29 +1,91 @@
 import type { Program } from "@neutrome/lil-engine";
-import type { ExecutionRuntime, InvokeOptions } from "@neutrome/lil-engine";
 
-export type ModelRuntime = Pick<ExecutionRuntime, "execute" | "stream">;
+export type TransformCapability =
+  | "read_messages"
+  | "write_messages"
+  | "write_config"
+  | "write_tools"
+  | "drop_content"
+  | "provider_extension";
 
-export type OutputSink = {
-  write(chunk: Program): void | Promise<void>;
-  close(): void | Promise<void>;
+export type ExecutionTarget =
+  | {
+      kind: "provider";
+      provider?: string;
+      model: string;
+      transforms?: string[];
+    }
+  | {
+      kind: "executor";
+      executorId: string;
+      alias: string;
+      transforms?: string[];
+    };
+
+export type SdkEvent = {
+  kind: string;
+  requestId: string;
+  executionId: string;
+  timestamp: string;
+  parentExecutionId?: string;
+  target?: { kind: "provider" | "executor"; id: string };
+  errorKind?: string;
+  data?: Record<string, unknown>;
+};
+
+export type SdkEventInput = Omit<SdkEvent, "timestamp"> & {
+  timestamp?: string;
 };
 
-export type ExecuteModelOptions = InvokeOptions;
+export type InvokeOptions = {
+  target?: ExecutionTarget;
+  requestId?: string;
+  executionId?: string;
+  parentExecutionId?: string;
+};
 
-export type StreamModelOptions = InvokeOptions & {
-  close?: boolean;
+export type TransformContext = {
+  observe(event: SdkEvent): void;
+  signal: AbortSignal;
 };
 
-export type ModelHandler = {
-  execute(
-    request: Program,
-    runtime: ModelRuntime,
-    options?: ExecuteModelOptions,
-  ): Promise<Program>;
-  stream(
-    request: Program,
-    runtime: ModelRuntime,
-    sink: OutputSink,
-    options?: StreamModelOptions,
-  ): Promise<void>;
+export type ProgramTransform = {
+  name: string;
+  capabilities: TransformCapability[];
+  apply(program: Program, ctx: TransformContext): Program;
 };
+
+export type ExecutorContext = {
+  requestId: string;
+  executionId: string;
+  parentExecutionId?: string;
+  invoke(request: Program, options?: InvokeOptions): Promise<Program>;
+  invokeStream(request: Program, options?: InvokeOptions): AsyncIterable<Program>;
+  observe(event: SdkEvent): void;
+  signal: AbortSignal;
+};
+
+export type Executor = {
+  execute(request: Program, ctx: ExecutorContext): Promise<Program>;
+  stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
+};
+
+export type Tool = {
+  name: string;
+  description: string;
+  schema: Record<string, unknown>;
+  systemPromptFragment?: string;
+  execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<string>;
+};
+
+export type OutputSink = {
+  write(chunk: Program): void | Promise<void>;
+  close(): void | Promise<void>;
+};
+
+export function createSdkEvent(input: SdkEventInput): SdkEvent {
+  return {
+    ...input,
+    timestamp: input.timestamp ?? new Date().toISOString(),
+  };
+}

package/test/lilsdk-ts.test.ts

@@ -1,32 +1,58 @@
 import {
-  appendAssistantMessage,
   contentText,
   emitChatCompletionsRequest,
   emitChatCompletionsStreamChunk,
   getModel,
-  isStreaming,
   parseChatCompletionsRequest,
   parseChatCompletionsStreamChunk,
-  prependSystemPrompt,
+  Opcode,
   type Program,
 } from "@neutrome/lil-engine";
 import { describe, expect, it } from "vitest";
+import { all, any, find, has, indexOf, map, reduce } from "../src/primitives/index.ts";
+import { appendAssistantMessage, appendToolInteraction } from "../src/synthetic/index.ts";
+import { observeExecutionStream, writeReasoning } from "../src/stream/index.ts";
+import { fallback, goal, retry } from "../src/loops/index.ts";
 import {
-  appendSyntheticToolExchange,
-  executeWithModel,
-  observeExecutionStream,
-  passthroughPrograms,
-  streamWithModel,
-  writeReasoning,
-  type ModelRuntime,
-  type OutputSink,
-} from "../src/index.ts";
+  appendInternalDraft,
+  createTwoPassExecutor,
+  invokeModel,
+  INTERNAL_DRAFT_TOOL_NAME,
+  streamModel,
+} from "../src/managed/twoPassExecutor.ts";
+import type {
+  Executor,
+  ExecutorContext,
+  OutputSink,
+} from "../src/types.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
 describe("@neutrome/lilsdk-ts", () => {
-  it("observes tool-call streams and supports passthrough", async () => {
+  it("provides clone-safe structural primitives", () => {
+    const needle = { opcode: Opcode.MSG_START, value: { kind: "none" as const } };
+    const program: Program = {
+      code: [
+        needle,
+        { opcode: Opcode.TXT_CHUNK, value: { kind: "string", value: "hello" } },
+      ],
+      buffers: [new Uint8Array([1, 2, 3])],
+    };
+
+    expect(indexOf(program, needle)).toBe(0);
+    expect(has(program, needle)).toBe(true);
+    expect(find(program, needle)).toEqual(needle);
+    expect(reduce(program, (count) => count + 1, 0)).toBe(2);
+    expect(all(program, (instruction) => instruction.opcode !== Opcode.MSG_END)).toBe(true);
+    expect(any(program, (instruction) => instruction.opcode === Opcode.TXT_CHUNK)).toBe(true);
+
+    const mapped = map(program, (instruction) => instruction);
+    mapped.buffers[0]![0] = 9;
+    expect(program.buffers[0]![0]).toBe(1);
+  });
+
+  it("observes tool-call streams", async () => {
     const observed = await observeExecutionStream((async function* () {
       yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
         id: "tool-stream",
@@ -63,88 +89,163 @@ describe("@neutrome/lilsdk-ts", () => {
       throw new Error("expected tool mode");
     }
 
-    const emitted: string[] = [];
-    const sink: OutputSink = {
-      write(chunk) {
-        emitted.push(decoder.decode(emitChatCompletionsStreamChunk(chunk)));
-      },
-      close() {
-        emitted.push("[DONE]");
-      },
-    };
+    const parsed = observed.chunks.map((chunk) =>
+      JSON.parse(decoder.decode(emitChatCompletionsStreamChunk(chunk)))
+    );
+    expect(parsed.some((chunk) => chunk.choices?.[0]?.delta?.tool_calls)).toBe(true);
+  });
+
+  it("appends internal drafts with fixed SDK metadata and empty args", () => {
+    const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
+      model: "virtual-model",
+      messages: [{ role: "user", content: "hello" }],
+    })));
 
-    await passthroughPrograms(observed.chunks, sink);
+    const updated = appendInternalDraft(request, "draft answer");
+    const emitted = JSON.parse(decoder.decode(emitChatCompletionsRequest(updated)));
 
-    expect(emitted.at(-1)).toBe("[DONE]");
-    const parsed = emitted.slice(0, -1).map((chunk) => JSON.parse(chunk));
-    expect(parsed.some((chunk) => chunk.choices?.[0]?.delta?.tool_calls)).toBe(true);
+    expect(emitted.messages[1].tool_calls[0].function.name).toBe(INTERNAL_DRAFT_TOOL_NAME);
+    expect(emitted.messages[1].tool_calls[0].function.arguments).toBe("{}");
+    expect(emitted.messages[2].content).toBe("draft answer");
   });
 
-  it("appends synthetic tool exchanges to a request program", () => {
+  it("appends generic synthetic tool interactions", () => {
     const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
       model: "virtual-model",
       messages: [{ role: "user", content: "hello" }],
     })));
 
-    const updated = appendSyntheticToolExchange(request, {
-      callId: "knowledge_0",
-      name: "knowledge",
-      args: "{\"question\":\"thinking\"}",
-      result: "draft answer",
+    const updated = appendToolInteraction(request, {
+      callId: "call_lookup",
+      name: "lookup",
+      args: { id: "42" },
+      result: { status: "active" },
     });
-
     const emitted = JSON.parse(decoder.decode(emitChatCompletionsRequest(updated)));
-    expect(emitted.messages).toHaveLength(3);
-    expect(emitted.messages[1].tool_calls[0].function.name).toBe("knowledge");
-    expect(emitted.messages[2].tool_call_id).toBe("knowledge_0");
-    expect(JSON.parse(decoder.decode(emitChatCompletionsRequest(request))).messages).toHaveLength(1);
+
+    expect(emitted.messages[1].tool_calls[0].function).toEqual({
+      name: "lookup",
+      arguments: "{\"id\":\"42\"}",
+    });
+    expect(emitted.messages[2]).toEqual({
+      role: "tool",
+      tool_call_id: "call_lookup",
+      content: "{\"status\":\"active\"}",
+    });
   });
 
-  it("supports chained model execution across multiple passes", async () => {
-    const calls: Array<{ model: string; streaming: boolean }> = [];
-    const runtime: ModelRuntime = {
-      async execute(request) {
-        calls.push({ model: getModel(request) ?? "", streaming: isStreaming(request) });
-        if (calls.length === 1) {
+  it("builds two-pass executors from model and prompt config", async () => {
+    const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
+      model: "virtual-model",
+      messages: [{ role: "user", content: "hello" }],
+    })));
+    const seen: Program[] = [];
+    const ctx = buildExecutorContext({
+      async invoke(program) {
+        seen.push(program);
+        if (seen.length === 1) {
           return appendAssistantMessage({ code: [], buffers: [] }, "draft answer");
         }
         return appendAssistantMessage({ code: [], buffers: [] }, "final answer");
       },
-      async *stream(): AsyncIterable<Program> {
+      async *invokeStream() {
         throw new Error("streaming path is not used in this test");
       },
-    };
+    });
+
+    const executor = createTwoPassExecutor({
+      draftModel: "smart-model",
+      finalModel: "base-model",
+      finalSystemPrompt: "system prompt",
+    });
 
+    const result = await executor.execute(request, ctx);
+
+    expect(seen.map((program) => getModel(program))).toEqual(["smart-model", "base-model"]);
+    expect(contentText(result)).toBe("final answer");
+
+    const finalRequest = JSON.parse(decoder.decode(emitChatCompletionsRequest(seen[1]!)));
+    expect(finalRequest.messages[0]).toEqual({ role: "system", content: "system prompt" });
+    expect(finalRequest.messages[2].tool_calls[0].function).toEqual({
+      name: INTERNAL_DRAFT_TOOL_NAME,
+      arguments: "{}",
+    });
+    expect(finalRequest.messages[3]).toEqual({
+      role: "tool",
+      tool_call_id: "knowledge_0",
+      content: "draft answer",
+    });
+  });
+
+  it("replaces draft system prompt and moves existing system prompt to first user message", async () => {
     const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
       model: "virtual-model",
-      messages: [{ role: "user", content: "hello" }],
+      messages: [
+        { role: "system", content: "original system" },
+        { role: "user", content: "hello" },
+      ],
     })));
-    const first = await executeWithModel(request, runtime, "smart-model");
-    const draft = contentText(first);
-
-    let secondRequest = appendSyntheticToolExchange(request, {
-      callId: "knowledge_0",
-      name: "knowledge",
-      args: "{\"question\":\"thinking\"}",
-      result: draft,
+    const seen: Program[] = [];
+    const ctx = buildExecutorContext({
+      async invoke(program) {
+        seen.push(program);
+        return appendAssistantMessage({ code: [], buffers: [] }, seen.length === 1 ? "draft" : "final");
+      },
+      async *invokeStream() {
+        throw new Error("streaming path is not used in this test");
+      },
     });
-    secondRequest = prependSystemPrompt(secondRequest, "system prompt");
 
-    const second = await executeWithModel(secondRequest, runtime, "base-model");
+    const executor = createTwoPassExecutor({
+      draftModel: "smart-model",
+      finalModel: "base-model",
+      draftSystemPrompt: "draft system",
+    });
 
-    expect(calls).toEqual([
-      { model: "smart-model", streaming: false },
-      { model: "base-model", streaming: false },
+    await executor.execute(request, ctx);
+
+    const draftRequest = JSON.parse(decoder.decode(emitChatCompletionsRequest(seen[0]!)));
+    expect(draftRequest.messages).toEqual([
+      { role: "system", content: "draft system" },
+      { role: "user", content: "original system" },
+      { role: "user", content: "hello" },
     ]);
-    expect(contentText(second)).toBe("final answer");
-    expect(getModel(request)).toBe("virtual-model");
   });
 
-  it("streams model output through a sink and writes reasoning helpers", async () => {
+  it("invokes and streams another model through executor context helpers", async () => {
+    const calls: Array<{ model: string; streaming: boolean }> = [];
+    const ctx = buildExecutorContext({
+      async invoke(program) {
+        calls.push({ model: getModel(program) ?? "", streaming: false });
+        return appendAssistantMessage({ code: [], buffers: [] }, "model answer");
+      },
+      async *invokeStream(program) {
+        calls.push({ model: getModel(program) ?? "", streaming: true });
+        yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
+          id: "stream-response",
+          model: "base-model",
+          choices: [{ index: 0, delta: { content: "hello" } }],
+        })));
+      },
+    });
+
     const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
       model: "virtual-model",
       messages: [{ role: "user", content: "hello" }],
     })));
+    const first = await invokeModel(ctx, request, "smart-model");
+    const chunks: Program[] = [];
+    for await (const chunk of streamModel(ctx, request, "base-model")) {
+      chunks.push(chunk);
+    }
+
+    expect(calls).toEqual([{ model: "smart-model", streaming: false }, { model: "base-model", streaming: true }]);
+    expect(contentText(first)).toBe("model answer");
+    expect(decoder.decode(emitChatCompletionsStreamChunk(chunks[0]!))).toContain("hello");
+    expect(getModel(request)).toBe("virtual-model");
+  });
+
+  it("writes reasoning helpers to a sink", async () => {
     const emitted: string[] = [];
     const sink: OutputSink = {
       write(chunk) {
@@ -155,31 +256,90 @@ describe("@neutrome/lilsdk-ts", () => {
       },
     };
 
-    const runtime: ModelRuntime = {
-      async execute() {
-        throw new Error("non-streaming path is not used in this test");
+    await writeReasoning(sink, "thinking");
+
+    expect(JSON.parse(emitted[0]!).choices[0].delta.reasoning_content).toBe("thinking");
+  });
+
+  it("retries executor failures", async () => {
+    let calls = 0;
+    const executor = retry(executorFromExecute(async () => {
+      calls += 1;
+      if (calls === 1) {
+        throw new Error("transient");
+      }
+      return appendAssistantMessage({ code: [], buffers: [] }, "ok");
+    }));
+
+    const result = await executor.execute({ code: [], buffers: [] }, buildExecutorContext());
+
+    expect(calls).toBe(2);
+    expect(contentText(result)).toBe("ok");
+  });
+
+  it("falls back to the next executor after failure", async () => {
+    const executor = fallback([
+      executorFromExecute(async () => {
+        throw new Error("primary failed");
+      }),
+      executorFromExecute(async () => appendAssistantMessage({ code: [], buffers: [] }, "fallback")),
+    ]);
+
+    const result = await executor.execute({ code: [], buffers: [] }, buildExecutorContext());
+
+    expect(contentText(result)).toBe("fallback");
+  });
+
+  it("runs goal loops until the review is satisfied", async () => {
+    let attempts = 0;
+    const executor = goal({
+      draft: executorFromExecute(async () => {
+        attempts += 1;
+        return appendAssistantMessage({ code: [], buffers: [] }, `answer ${attempts}`);
+      }),
+      review: executorFromExecute(async () =>
+        appendAssistantMessage({ code: [], buffers: [] }, attempts > 1 ? "pass" : "retry")
+      ),
+      satisfied(review) {
+        return contentText(review) === "pass";
       },
-      async *stream(program) {
-        expect(getModel(program)).toBe("base-model");
-        expect(isStreaming(program)).toBe(true);
-        yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
-          id: "stream-response",
-          model: "base-model",
-          choices: [{ index: 0, delta: { content: "hello" } }],
-        })));
-        yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
-          id: "stream-response",
-          model: "base-model",
-          choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
-        })));
+      refine(request) {
+        return request;
       },
-    };
+    });
 
-    await writeReasoning(sink, "thinking");
-    await streamWithModel(request, runtime, sink, "base-model");
+    const result = await executor.execute({ code: [], buffers: [] }, buildExecutorContext());
 
-    expect(emitted.at(-1)).toBe("[DONE]");
-    expect(JSON.parse(emitted[0]!).choices[0].delta.reasoning_content).toBe("thinking");
-    expect(JSON.parse(emitted[1]!).choices[0].delta.content).toBe("hello");
+    expect(attempts).toBe(2);
+    expect(contentText(result)).toBe("answer 2");
   });
 });
+
+function buildExecutorContext(
+  impl: Pick<ExecutorContext, "invoke" | "invokeStream"> = {
+    async invoke(program) {
+      return program;
+    },
+    async *invokeStream(program) {
+      yield program;
+    },
+  },
+): ExecutorContext {
+  return {
+    requestId: "req_test",
+    executionId: "exec_test",
+    invoke: impl.invoke,
+    invokeStream: impl.invokeStream,
+    observe: () => {},
+    signal: new AbortController().signal,
+  };
+}
+
+function executorFromExecute(execute: Executor["execute"]): Executor {
+  return {
+    execute,
+    async *stream(request, ctx) {
+      yield await execute(request, ctx);
+    },
+  };
+}