@neutrome/lilsdk-ts 0.2.5 → 0.3.1

package/README.md

@@ -5,7 +5,10 @@ High-level TypeScript SDK for transport-neutral model authoring on top of `@neut
 ```ts
 import { createTwoPassExecutor, type Executor } from "@neutrome/lilsdk-ts";
 import { retry } from "@neutrome/lilsdk-ts/loops";
-import { observeExecutionStream, writeReasoning } from "@neutrome/lilsdk-ts/stream";
+import {
+  observeExecutionStream,
+  writeReasoning,
+} from "@neutrome/lilsdk-ts/stream";
 import { connectTools } from "@neutrome/lilsdk-ts/tools";
 ```
 
@@ -13,10 +16,10 @@ This package owns:
 
 - executor and tool contracts
 - `@neutrome/lilsdk-ts/primitives`: structural program helpers such as `walk`, `map`, `reduce`, `has`, `find`, `indexOf`, `all`, and `any`
-- `@neutrome/lilsdk-ts/synthetic`: request/message/tool synthesis helpers such as `makeRequest`, `makeResponse`, `makeMessage`, `makeToolCall`, `makeToolResponse`, and `appendToolInteraction`
-- `@neutrome/lilsdk-ts/tools`: `connectTools` and `withTools` tool-call loops
+- `@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 `goal` executor control-flow helpers
+- `@neutrome/lilsdk-ts/loops`: `retry`, `fallback`, and execute-only `runGoal` 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.2.5",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -13,7 +13,7 @@
     "./managed": "./src/managed/index.ts"
   },
   "dependencies": {
-    "@neutrome/lil-engine": "0.2.1"
+    "@neutrome/lil-engine": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/index.ts

@@ -5,10 +5,10 @@ export type {
   InvokeOptions,
   OutputSink,
   ProgramTransform,
-  SdkEvent,
-  SdkEventInput,
+  ExecutionEvent,
+  ExecutionEventInput,
   Tool,
   TransformCapability,
   TransformContext,
-  createSdkEvent,
 } from "./types.ts";
+export { createExecutionEvent } from "./types.ts";

package/src/loops/index.ts

@@ -8,7 +8,10 @@ export type RetryOptions = {
 };
 
 export type FallbackOptions = {
-  shouldFallback?: (error: unknown, executorIndex: number) => boolean | Promise<boolean>;
+  shouldFallback?: (
+    error: unknown,
+    executorIndex: number,
+  ) => boolean | Promise<boolean>;
   onFallback?: (error: unknown, executorIndex: number) => void | Promise<void>;
 };
 
@@ -25,7 +28,12 @@ export type GoalOptions = {
   maxIterations?: number;
 };
 
-export function retry(executor: Executor, options: RetryOptions = {}): Executor {
+export type ExecuteOnly = Pick<Executor, "execute">;
+
+export function retry(
+  executor: Executor,
+  options: RetryOptions = {},
+): Executor {
   const attempts = positiveInteger(options.attempts ?? 2, "retry attempts");
 
   return {
@@ -41,12 +49,22 @@ export function retry(executor: Executor, options: RetryOptions = {}): Executor
       let lastError: unknown;
 
       for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        let emitted = false;
         try {
-          yield* executor.stream(request, childContext(ctx, attempt));
+          for await (const chunk of executor.stream(
+            request,
+            childContext(ctx, attempt),
+          )) {
+            emitted = true;
+            yield chunk;
+          }
           return;
         } catch (error) {
           lastError = error;
-          const canRetry = attempt < attempts && (await shouldContinue(error, attempt, options.shouldRetry));
+          if (emitted) throw error;
+          const canRetry =
+            attempt < attempts &&
+            (await shouldContinue(error, attempt, options.shouldRetry));
           if (!canRetry) {
             throw error;
           }
@@ -59,7 +77,10 @@ export function retry(executor: Executor, options: RetryOptions = {}): Executor
   };
 }
 
-export function fallback(executors: readonly Executor[], options: FallbackOptions = {}): Executor {
+export function fallback(
+  executors: readonly Executor[],
+  options: FallbackOptions = {},
+): Executor {
   if (executors.length === 0) {
     throw new Error("fallback requires at least one executor");
   }
@@ -67,7 +88,8 @@ export function fallback(executors: readonly Executor[], options: FallbackOption
   return {
     execute(request, ctx) {
       return runFallback(
-        (executor, index) => executor.execute(request, childContext(ctx, index + 1)),
+        (executor, index) =>
+          executor.execute(request, childContext(ctx, index + 1)),
         executors,
         options,
       );
@@ -77,11 +99,19 @@ export function fallback(executors: readonly Executor[], options: FallbackOption
       let lastError: unknown;
 
       for (const [index, executor] of executors.entries()) {
+        let emitted = false;
         try {
-          yield* executor.stream(request, childContext(ctx, index + 1));
+          for await (const chunk of executor.stream(
+            request,
+            childContext(ctx, index + 1),
+          )) {
+            emitted = true;
+            yield chunk;
+          }
           return;
         } catch (error) {
           lastError = error;
+          if (emitted) throw error;
           const canFallback =
             index < executors.length - 1 &&
             (await shouldContinue(error, index, options.shouldFallback));
@@ -97,15 +127,21 @@ export function fallback(executors: readonly Executor[], options: FallbackOption
   };
 }
 
-export function goal(options: GoalOptions): Executor {
-  const maxIterations = positiveInteger(options.maxIterations ?? 3, "goal maxIterations");
+export function runGoal(options: GoalOptions): ExecuteOnly {
+  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));
+      const review = await options.review.execute(
+        answer,
+        childContext(ctx, attempt),
+      );
       if (await options.satisfied(review, attempt)) {
         return answer;
       }
@@ -117,14 +153,7 @@ export function goal(options: GoalOptions): Executor {
     return answer;
   };
 
-  return {
-    execute: executeGoal,
-
-    async *stream(request, ctx) {
-      const result = await executeGoal(request, ctx);
-      yield result;
-    },
-  };
+  return { execute: executeGoal };
 }
 
 async function runRetry<T>(
@@ -139,7 +168,9 @@ async function runRetry<T>(
       return await operation(attempt);
     } catch (error) {
       lastError = error;
-      const canRetry = attempt < attempts && (await shouldContinue(error, attempt, options.shouldRetry));
+      const canRetry =
+        attempt < attempts &&
+        (await shouldContinue(error, attempt, options.shouldRetry));
       if (!canRetry) {
         throw error;
       }

package/src/managed/index.ts

@@ -1,4 +1,4 @@
-export { wrap, wrapNoAcl } from "./wrap.ts";
+export { createTargetExecutor } from "./target-executor.ts";
 
 export {
   appendInternalDraft,

package/src/managed/target-executor.ts

@@ -0,0 +1,12 @@
+import type { ExecutionTarget, Executor } from "../types.ts";
+
+export function createTargetExecutor(target: ExecutionTarget): Executor {
+  return {
+    execute(request, context) {
+      return context.invoke(request, { target });
+    },
+    stream(request, context) {
+      return context.invokeStream(request, { target });
+    },
+  };
+}

package/src/managed/twoPassExecutor.ts

@@ -79,7 +79,9 @@ export function appendInternalDraft(
   );
 }
 
-export function createTwoPassExecutor(options: TwoPassExecutorOptions): Executor {
+export function createTwoPassExecutor(
+  options: TwoPassExecutorOptions,
+): Executor {
   const reasoningIntro = options.reasoningIntro ?? "Let me think...\n\n";
   const reasoningSeparator = options.reasoningSeparator ?? "\n\n";
 
@@ -90,7 +92,11 @@ export function createTwoPassExecutor(options: TwoPassExecutorOptions): Executor
         return invokeModel(ctx, draftRequest, options.draftModel);
       }
 
-      const draftResponse = await invokeModel(ctx, draftRequest, options.draftModel);
+      const draftResponse = await invokeModel(
+        ctx,
+        draftRequest,
+        options.draftModel,
+      );
       if (callData(draftResponse).length > 0) {
         return draftResponse;
       }
@@ -124,7 +130,8 @@ export function createTwoPassExecutor(options: TwoPassExecutorOptions): Executor
           continue;
         }
 
-        const toolRequested = hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
+        const toolRequested =
+          hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
         if (toolRequested) {
           toolMode = true;
           yield chunk;
@@ -161,12 +168,17 @@ export function createTwoPassExecutor(options: TwoPassExecutorOptions): Executor
   };
 }
 
-function buildDraftRequest(options: TwoPassExecutorOptions, request: Program): Program {
+function buildDraftRequest(
+  options: TwoPassExecutorOptions,
+  request: Program,
+): Program {
   if (!options.draftSystemPrompt) {
     return request;
   }
 
-  const systemSpans = messages(request).filter((span) => span.role === "system");
+  const systemSpans = messages(request).filter(
+    (span) => span.role === "system",
+  );
   const previousSystemPrompt = systemSpans
     .map((span) => messageText(request, span).trim())
     .filter((text) => text.length > 0)
@@ -208,7 +220,7 @@ function buildFinalRequest(
 
 function normalizeDrafts(draft: InternalDraft): string[] {
   const drafts = Array.isArray(draft)
-    ? draft.map((item) => typeof item === "string" ? item : item.text)
+    ? draft.map((item) => (typeof item === "string" ? item : item.text))
     : [draft];
   return drafts.map((text) => text.trim()).filter((text) => text.length > 0);
 }

package/src/observe.ts

@@ -36,7 +36,8 @@ export async function observeExecutionStream(
 
   for await (const chunk of source) {
     const text = deltaText(chunk);
-    const toolRequested = hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
+    const toolRequested =
+      hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
 
     if (mode === "pending") {
       const clone = cloneProgram(chunk);

package/src/output.ts

@@ -8,7 +8,10 @@ import {
 } from "@neutrome/lil-engine";
 import type { OutputSink } from "./types.ts";
 
-export async function writeReasoning(sink: OutputSink, text: string): Promise<void> {
+export async function writeReasoning(
+  sink: OutputSink,
+  text: string,
+): Promise<void> {
   await sink.write(streamReasoningDelta(text));
 }
 
@@ -19,7 +22,10 @@ export function streamTextResponse(text: string): Program[] {
 export function streamReasoningDelta(text: string): Program {
   return createProgram({
     code: [
-      { opcode: Opcode.STREAM_THINK_DELTA, value: { kind: "string", value: text } },
+      {
+        opcode: Opcode.STREAM_THINK_DELTA,
+        value: { kind: "string", value: text },
+      },
     ],
   });
 }

package/src/primitives/index.ts

@@ -5,14 +5,19 @@ import {
 } from "@neutrome/lil-engine";
 
 export function indexOf(program: Program, needle: Instruction): number {
-  return program.code.findIndex((instruction) => instructionEquals(instruction, needle));
+  return program.code.findIndex((instruction) =>
+    instructionEquals(instruction, needle),
+  );
 }
 
 export function has(program: Program, needle: Instruction): boolean {
   return indexOf(program, needle) >= 0;
 }
 
-export function find(program: Program, needle: Instruction): Instruction | undefined {
+export function find(
+  program: Program,
+  needle: Instruction,
+): Instruction | undefined {
   const i = indexOf(program, needle);
   return i >= 0 ? cloneInstruction(program.code[i]!) : undefined;
 }
@@ -21,16 +26,22 @@ export function walk(
   program: Program,
   callback: (instruction: Instruction, index: number, program: Program) => void,
 ): void {
-  program.code.forEach((instruction, index) => callback(instruction, index, program));
+  program.code.forEach((instruction, index) =>
+    callback(instruction, index, program),
+  );
 }
 
 export function map(
   program: Program,
-  callback: (instruction: Instruction, index: number, program: Program) => Instruction,
+  callback: (
+    instruction: Instruction,
+    index: number,
+    program: Program,
+  ) => Instruction,
 ): Program {
   return {
     code: program.code.map((instruction, index) =>
-      cloneInstruction(callback(instruction, index, program))
+      cloneInstruction(callback(instruction, index, program)),
     ),
     buffers: cloneBuffers(program.buffers),
   };
@@ -38,7 +49,11 @@ export function map(
 
 export function filter(
   program: Program,
-  callback: (instruction: Instruction, index: number, program: Program) => boolean,
+  callback: (
+    instruction: Instruction,
+    index: number,
+    program: Program,
+  ) => boolean,
 ): Program {
   return {
     code: program.code
@@ -50,7 +65,12 @@ export function filter(
 
 export function reduce<T>(
   program: Program,
-  callback: (accumulator: T, instruction: Instruction, index: number, program: Program) => T,
+  callback: (
+    accumulator: T,
+    instruction: Instruction,
+    index: number,
+    program: Program,
+  ) => T,
   initialValue: T,
 ): T {
   let accumulator = initialValue;
@@ -62,7 +82,11 @@ export function reduce<T>(
 
 export function all(
   program: Program,
-  callback: (instruction: Instruction, index: number, program: Program) => boolean,
+  callback: (
+    instruction: Instruction,
+    index: number,
+    program: Program,
+  ) => boolean,
 ): boolean {
   for (const [index, instruction] of program.code.entries()) {
     if (!callback(instruction, index, program)) return false;
@@ -72,7 +96,11 @@ export function all(
 
 export function any(
   program: Program,
-  callback: (instruction: Instruction, index: number, program: Program) => boolean,
+  callback: (
+    instruction: Instruction,
+    index: number,
+    program: Program,
+  ) => boolean,
 ): boolean {
   for (const [index, instruction] of program.code.entries()) {
     if (callback(instruction, index, program)) return true;
@@ -92,9 +120,15 @@ function instructionEquals(left: Instruction, right: Instruction): boolean {
     case "float":
     case "int":
     case "ref":
-      return right.value.kind === left.value.kind && left.value.value === right.value.value;
+      return (
+        right.value.kind === left.value.kind &&
+        left.value.value === right.value.value
+      );
     case "json":
-      return right.value.kind === "json" && bytesEqual(left.value.value, right.value.value);
+      return (
+        right.value.kind === "json" &&
+        bytesEqual(left.value.value, right.value.value)
+      );
     case "key_string":
       return (
         right.value.kind === "key_string" &&

package/src/stream/index.ts

@@ -1,4 +1,8 @@
 export type { ObservedExecution, StreamObservationHooks } from "../observe.ts";
 
 export { observeExecutionStream } from "../observe.ts";
-export { streamReasoningDelta, streamTextResponse, writeReasoning } from "../output.ts";
+export {
+  streamReasoningDelta,
+  streamTextResponse,
+  writeReasoning,
+} from "../output.ts";

package/src/synthetic/index.ts

@@ -1,12 +1,11 @@
 import {
+  addTool,
   appendInstructions,
   createProgram,
-  insertAfter,
   insertBefore,
   messages,
   Opcode,
   setModel,
-  toolDefinitions,
   type Instruction,
   type Opcode as OpcodeValue,
   type Program,
@@ -23,11 +22,7 @@ export type ToolInteraction = {
   result: unknown;
 };
 
-export function makeRequest(model: string): Program {
-  return setModel(createProgram(), model);
-}
-
-export function makeResponse(model: string): Program {
+export function createModelProgram(model: string): Program {
   return setModel(createProgram(), model);
 }
 
@@ -41,14 +36,19 @@ export function prependSystemPrompt(program: Program, text: string): Program {
   if (spans.length === 0) {
     return appendInstructions(program, systemMessage);
   }
-  return insertBefore(program, spans[0]!.start, systemMessage);
+  const firstSpan = spans[0];
+  if (!firstSpan) return appendInstructions(program, systemMessage);
+  return insertBefore(program, firstSpan.start, systemMessage);
 }
 
 export function appendUserMessage(program: Program, text: string): Program {
   return appendInstructions(program, buildMessage("user", text));
 }
 
-export function appendAssistantMessage(program: Program, text: string): Program {
+export function appendAssistantMessage(
+  program: Program,
+  text: string,
+): Program {
   return appendInstructions(program, buildMessage("assistant", text));
 }
 
@@ -63,7 +63,10 @@ export function makeToolCall(
       { opcode: Opcode.ROLE_AST, value: { kind: "none" } },
       { opcode: Opcode.CALL_START, value: { kind: "string", value: callId } },
       { opcode: Opcode.CALL_NAME, value: { kind: "string", value: name } },
-      { opcode: Opcode.CALL_ARGS, value: { kind: "json", value: encodeJson(args) } },
+      {
+        opcode: Opcode.CALL_ARGS,
+        value: { kind: "json", value: encodeJson(args) },
+      },
       { opcode: Opcode.CALL_END, value: { kind: "none" } },
       { opcode: Opcode.MSG_END, value: { kind: "none" } },
     ],
@@ -79,38 +82,15 @@ export function appendToolInteraction(
   interaction: ToolInteraction,
 ): Program {
   return appendInstructions(program, [
-    ...makeToolCall(interaction.name, interaction.args ?? {}, interaction.callId).code,
+    ...makeToolCall(
+      interaction.name,
+      interaction.args ?? {},
+      interaction.callId,
+    ).code,
     ...buildToolResponse(interaction.callId, interaction.result),
   ]);
 }
 
-export function addTool(
-  program: Program,
-  name: string,
-  description: string,
-  schemaJson: Uint8Array,
-): Program {
-  const definition: Instruction[] = [
-    { opcode: Opcode.DEF_START, value: { kind: "none" } },
-    { opcode: Opcode.DEF_NAME, value: { kind: "string", value: name } },
-    { opcode: Opcode.DEF_DESC, value: { kind: "string", value: description } },
-    { opcode: Opcode.DEF_SCHEMA, value: { kind: "json", value: schemaJson.slice() } },
-    { opcode: Opcode.DEF_END, value: { kind: "none" } },
-  ];
-
-  const defs = toolDefinitions(program);
-  if (defs.length > 0) {
-    return insertAfter(program, defs.at(-1)!.end, definition);
-  }
-
-  const spans = messages(program);
-  if (spans.length > 0) {
-    return insertBefore(program, spans[0]!.start, definition);
-  }
-
-  return appendInstructions(program, definition);
-}
-
 function buildMessage(role: TextMessageRole, text: string): Instruction[] {
   return [
     { opcode: Opcode.MSG_START, value: { kind: "none" } },
@@ -125,7 +105,10 @@ function buildToolResponse(callId: string, result: unknown): Instruction[] {
     { opcode: Opcode.MSG_START, value: { kind: "none" } },
     { opcode: Opcode.ROLE_TOOL, value: { kind: "none" } },
     { opcode: Opcode.RESULT_START, value: { kind: "string", value: callId } },
-    { opcode: Opcode.RESULT_DATA, value: { kind: "string", value: stringifyResult(result) } },
+    {
+      opcode: Opcode.RESULT_DATA,
+      value: { kind: "string", value: stringifyResult(result) },
+    },
     { opcode: Opcode.RESULT_END, value: { kind: "none" } },
     { opcode: Opcode.MSG_END, value: { kind: "none" } },
   ];

package/src/tools-support.ts

@@ -0,0 +1,108 @@
+import { addTool, type Program } from "@neutrome/lil-engine";
+import { prependSystemPrompt } from "./synthetic/index.ts";
+import {
+  createExecutionEvent,
+  type ExecutorContext,
+  type Tool,
+} from "./types.ts";
+
+export type ToolCall = { id: string; name: string; args: string };
+export type ToolExecution = ToolCall & { result: string };
+
+export class ToolArgumentsError extends Error {
+  constructor(
+    readonly toolName: string,
+    readonly argumentsText: string,
+  ) {
+    super(`Tool "${toolName}" received invalid JSON object arguments`);
+    this.name = "ToolArgumentsError";
+  }
+}
+
+export function buildToolAugmenter(tools: readonly Tool[]) {
+  const encoder = new TextEncoder();
+  const fragments = tools
+    .map((tool) => tool.systemPromptFragment)
+    .filter((fragment): fragment is string => Boolean(fragment));
+
+  return (request: Program): Program => {
+    let augmented = request;
+    if (fragments.length > 0) {
+      augmented = prependSystemPrompt(augmented, fragments.join("\n\n"));
+    }
+    for (const tool of tools) {
+      augmented = addTool(
+        augmented,
+        tool.name,
+        tool.description,
+        encoder.encode(JSON.stringify(tool.schema)),
+      );
+    }
+    return augmented;
+  };
+}
+
+export function buildCallExecutor(toolMap: ReadonlyMap<string, Tool>) {
+  return async (
+    calls: readonly ToolCall[],
+    ctx: ExecutorContext,
+  ): Promise<ToolExecution[]> =>
+    Promise.all(
+      calls.map(async (call) => {
+        const tool = toolMap.get(call.name);
+        if (!tool) {
+          throw new Error(`No tool is registered for call "${call.name}"`);
+        }
+        const startedMs = Date.now();
+        const result = await tool.execute(
+          parseToolArguments(call.name, call.args),
+          ctx,
+        );
+        const finishedMs = Date.now();
+        ctx.observe(
+          createExecutionEvent({
+            kind: "tool.executed",
+            requestId: ctx.requestId,
+            executionId: `tool_${call.id || crypto.randomUUID()}`,
+            parentExecutionId: ctx.executionId,
+            data: {
+              toolName: call.name,
+              toolCallId: call.id,
+              startedAt: new Date(startedMs).toISOString(),
+              finishedAt: new Date(finishedMs).toISOString(),
+              durationMs: finishedMs - startedMs,
+              lilText: toolTrace(call, result),
+            },
+          }),
+        );
+        return { ...call, result };
+      }),
+    );
+}
+
+export function parseToolArguments(
+  toolName: string,
+  argumentsText: string,
+): Record<string, unknown> {
+  try {
+    const value: unknown = JSON.parse(argumentsText);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new ToolArgumentsError(toolName, argumentsText);
+    }
+    return value as Record<string, unknown>;
+  } catch {
+    throw new ToolArgumentsError(toolName, argumentsText);
+  }
+}
+
+function toolTrace(call: ToolCall, result: string): string {
+  return [
+    `CALL_START ${JSON.stringify(call.id)}`,
+    `CALL_NAME ${JSON.stringify(call.name)}`,
+    `CALL_ARGS ${call.args}`,
+    "CALL_END",
+    "RESULT_START",
+    `RESULT_DATA ${JSON.stringify(result)}`,
+    "RESULT_END",
+  ].join("\n");
+}