@neutrome/lilsdk-ts 0.2.5 → 0.3.1

package/src/tools.ts

@@ -1,24 +1,25 @@
 import {
   callData,
   createProgram,
+  decodeStreamToolDelta,
   isStreaming,
   Opcode,
   setStreaming,
   type Instruction,
   type Program,
+  type StreamToolDelta,
 } from "@neutrome/lil-engine";
+import { appendToolInteraction } from "./synthetic/index.ts";
+import { type Executor, type ExecutorContext, type Tool } from "./types.ts";
 import {
-  addTool,
-  appendToolInteraction,
-  prependSystemPrompt,
-} from "./synthetic/index.ts";
-import {
-  createSdkEvent,
-  type ExecutionTarget,
-  type Executor,
-  type ExecutorContext,
-  type Tool,
-} from "./types.ts";
+  buildCallExecutor,
+  buildToolAugmenter,
+  parseToolArguments,
+  type ToolCall,
+  type ToolExecution,
+} from "./tools-support.ts";
+
+export { ToolArgumentsError } from "./tools-support.ts";
 
 export type WithToolsOptions = {
   maxIterations?: number;
@@ -26,108 +27,34 @@ export type WithToolsOptions = {
 
 const DEFAULT_MAX_ITERATIONS = 10;
 
-function buildAugmenter(tools: Tool[]) {
-  const encoder = new TextEncoder();
-  const fragments = tools
-    .map((t) => t.systemPromptFragment)
-    .filter((f): f is string => !!f);
-
-  return function augmentRequest(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;
-  };
-}
-
-function buildToolTrace(call: { id: string; name: string; args: string }, 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");
-}
-
-function buildCallExecutor(toolMap: Map<string, Tool>) {
-  return function executeConnectedCalls(
-    calls: Array<{ id: string; name: string; args: string }>,
-    ctx: ExecutorContext,
-  ): Promise<Array<{ id: string; name: string; args: string; result: string }>> {
-    return Promise.all(
-      calls.map(async (call) => {
-        const tool = toolMap.get(call.name)!;
-        let parsed: Record<string, unknown>;
-        try {
-          parsed = JSON.parse(call.args);
-        } catch {
-          parsed = {};
-        }
-        const startedMs = Date.now();
-        const startedAt = new Date(startedMs).toISOString();
-        const result = await tool.execute(parsed, ctx);
-        const finishedMs = Date.now();
-        ctx.observe(createSdkEvent({
-          kind: "tool.executed",
-          requestId: ctx.requestId,
-          executionId: `tool_${call.id || crypto.randomUUID()}`,
-          parentExecutionId: ctx.executionId,
-          data: {
-            toolName: call.name,
-            toolCallId: call.id,
-            startedAt,
-            finishedAt: new Date(finishedMs).toISOString(),
-            durationMs: finishedMs - startedMs,
-            lilText: buildToolTrace(call, result),
-          },
-        }));
-        return { ...call, result };
-      }),
-    );
-  };
-}
-
 type ToolDeltaAcc = { index: number; id: string; name: string; args: string };
+type DecodedToolDelta = { instruction: Instruction; delta: StreamToolDelta };
 
 function collectToolDeltasFromChunk(
   chunk: Program,
   acc: Map<number, ToolDeltaAcc>,
-) {
+): DecodedToolDelta[] {
+  const deltas: DecodedToolDelta[] = [];
   for (const instr of chunk.code) {
-    if (instr.opcode === Opcode.STREAM_TOOL_DELTA && instr.value.kind === "json") {
-      const parsed = JSON.parse(new TextDecoder().decode(instr.value.value)) as Record<string, unknown>;
-      const index = typeof parsed.index === "number" ? parsed.index : 0;
-      const existing = acc.get(index);
-      if (existing) {
-        if (typeof parsed.arguments === "string") existing.args += parsed.arguments;
-      } else {
-        acc.set(index, {
-          index,
-          id: typeof parsed.id === "string" ? parsed.id : "",
-          name: typeof parsed.name === "string" ? parsed.name : "",
-          args: typeof parsed.arguments === "string" ? parsed.arguments : "",
-        });
-      }
-    }
+    const delta = decodeStreamToolDelta(instr);
+    if (!delta) continue;
+    deltas.push({ instruction: instr, delta });
+    const current = acc.get(delta.index) ?? {
+      index: delta.index,
+      id: "",
+      name: "",
+      args: "",
+    };
+    if (delta.id) current.id = delta.id;
+    if (delta.name) current.name = delta.name;
+    if (delta.arguments) current.args += delta.arguments;
+    acc.set(delta.index, current);
   }
+  return deltas;
 }
 
 function filterChunkForClient(
   chunk: Program,
-  connectedNames: Set<string>,
-  toolAcc: Map<number, ToolDeltaAcc>,
   isIntermediate: boolean,
 ): Program | null {
   const kept: Instruction[] = [];
@@ -135,16 +62,7 @@ function filterChunkForClient(
   for (const instr of chunk.code) {
     switch (instr.opcode) {
       case Opcode.STREAM_TOOL_DELTA:
-        // Suppress connected tool deltas; pass through outer ones
-        if (instr.value.kind === "json") {
-          const parsed = JSON.parse(new TextDecoder().decode(instr.value.value)) as Record<string, unknown>;
-          const index = typeof parsed.index === "number" ? parsed.index : 0;
-          const tool = toolAcc.get(index);
-          if (tool && connectedNames.has(tool.name)) {
-            continue;
-          }
-        }
-        kept.push(instr);
+        // Tool ownership can be revealed by a later fragment, so defer all deltas.
         break;
       case Opcode.RESP_DONE:
         if (isIntermediate) continue;
@@ -173,21 +91,25 @@ async function* streamToolLoop(
   ctx: ExecutorContext,
   invokeStream: (req: Program) => AsyncIterable<Program>,
 ): AsyncGenerator<Program> {
-  const connectedNames = new Set(toolMap.keys());
-  let current = augmentRequest(request);
+  let state = createToolLoopState(augmentRequest(request));
   let yieldedStart = false;
 
-  for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+  while (canRunToolLoop(state, maxIterations)) {
     const toolAcc = new Map<number, ToolDeltaAcc>();
+    const toolDeltas: DecodedToolDelta[] = [];
     const isIntermediate = true; // assume intermediate; we'll yield end markers later if final
 
-    for await (const chunk of invokeStream(current)) {
-      collectToolDeltasFromChunk(chunk, toolAcc);
+    for await (const chunk of invokeStream(state.request)) {
+      toolDeltas.push(...collectToolDeltasFromChunk(chunk, toolAcc));
 
-      const filtered = filterChunkForClient(chunk, connectedNames, toolAcc, isIntermediate);
+      const filtered = filterChunkForClient(chunk, isIntermediate);
       if (filtered) {
         // Skip STREAM_START on iterations after the first (client already got it)
-        if (yieldedStart && filtered.code.length === 1 && filtered.code[0]!.opcode === Opcode.STREAM_START) {
+        if (
+          yieldedStart &&
+          filtered.code.length === 1 &&
+          filtered.code[0]?.opcode === Opcode.STREAM_START
+        ) {
           continue;
         }
         yield filtered;
@@ -202,82 +124,88 @@ async function* streamToolLoop(
       .filter((t) => t.name)
       .map((t) => ({ id: t.id, name: t.name, args: t.args }));
 
-    const connected = calls.filter((c) => toolMap.has(c.name));
-    const outer = calls.filter((c) => !toolMap.has(c.name));
+    const decision = decideToolLoop(calls, toolMap);
 
-    if (connected.length === 0 || outer.length > 0) {
+    if (decision.kind !== "continue") {
       // Final iteration — emit suppressed end markers
       const endInstructions: Instruction[] = [];
-      if (calls.length > 0 && outer.length > 0) {
-        endInstructions.push({ opcode: Opcode.RESP_DONE, value: { kind: "string", value: "tool_calls" } });
+      if (decision.kind === "external") {
+        const outerNames = new Set(decision.calls.map((call) => call.name));
+        const outerDeltas = toolDeltas
+          .filter(({ delta }) => {
+            const call = toolAcc.get(delta.index);
+            return call !== undefined && outerNames.has(call.name);
+          })
+          .map(({ instruction }) => instruction);
+        if (outerDeltas.length > 0) yield createProgram({ code: outerDeltas });
+        endInstructions.push({
+          opcode: Opcode.RESP_DONE,
+          value: { kind: "string", value: "tool_calls" },
+        });
       } else if (calls.length === 0) {
-        endInstructions.push({ opcode: Opcode.RESP_DONE, value: { kind: "string", value: "stop" } });
+        endInstructions.push({
+          opcode: Opcode.RESP_DONE,
+          value: { kind: "string", value: "stop" },
+        });
       }
-      endInstructions.push({ opcode: Opcode.STREAM_END, value: { kind: "none" } });
+      endInstructions.push({
+        opcode: Opcode.STREAM_END,
+        value: { kind: "none" },
+      });
       yield createProgram({ code: endInstructions });
       return;
     }
 
     // Execute connected tools and loop
-    const results = await executeConnectedCalls(connected, ctx);
-    let next = current;
-    for (const r of results) {
-      next = appendToolInteraction(next, {
-        callId: r.id,
-        name: r.name,
-        args: parseToolArgs(r.args),
-        result: r.result,
-      });
-    }
-    current = next;
+    state = await advanceToolLoopState(
+      state,
+      decision.calls,
+      ctx,
+      executeConnectedCalls,
+    );
   }
 
   // Max iterations reached — emit end
-  yield createProgram({ code: [
-    { opcode: Opcode.RESP_DONE, value: { kind: "string", value: "stop" } },
-    { opcode: Opcode.STREAM_END, value: { kind: "none" } },
-  ] });
+  yield createProgram({
+    code: [
+      { opcode: Opcode.RESP_DONE, value: { kind: "string", value: "stop" } },
+      { opcode: Opcode.STREAM_END, value: { kind: "none" } },
+    ],
+  });
 }
 
-export function withTools(
+export function connectTools(
   tools: Tool[],
-  target: ExecutionTarget,
+  inner: Executor,
   options: WithToolsOptions = {},
 ): Executor {
   const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
   const toolMap = new Map(tools.map((t) => [t.name, t]));
-  const augmentRequest = buildAugmenter(tools);
+  const augmentRequest = buildToolAugmenter(tools);
   const executeConnectedCalls = buildCallExecutor(toolMap);
 
   return {
     async execute(request, ctx) {
       const augmented = augmentRequest(request);
-      let current = isStreaming(augmented) ? setStreaming(augmented, false) : augmented;
+      let state = createToolLoopState(
+        isStreaming(augmented) ? setStreaming(augmented, false) : augmented,
+      );
 
-      for (let iteration = 0; iteration < maxIterations; iteration += 1) {
-        const response = await ctx.invoke(current, { target });
+      while (canRunToolLoop(state, maxIterations)) {
+        const response = await inner.execute(state.request, ctx);
         const calls = callData(response);
-        const connected = calls.filter((c) => toolMap.has(c.name));
-        const outer = calls.filter((c) => !toolMap.has(c.name));
-
-        if (connected.length === 0) return response;
-
-        const results = await executeConnectedCalls(connected, ctx);
-        let next = current;
-        for (const r of results) {
-          next = appendToolInteraction(next, {
-            callId: r.id,
-            name: r.name,
-            args: parseToolArgs(r.args),
-            result: r.result,
-          });
-        }
-
-        if (outer.length > 0) return response;
-        current = next;
+        const decision = decideToolLoop(calls, toolMap);
+        if (decision.kind !== "continue") return response;
+
+        state = await advanceToolLoopState(
+          state,
+          decision.calls,
+          ctx,
+          executeConnectedCalls,
+        );
       }
 
-      return ctx.invoke(current, { target });
+      return inner.execute(state.request, ctx);
     },
 
     async *stream(request, ctx) {
@@ -288,76 +216,64 @@ export function withTools(
         executeConnectedCalls,
         request,
         ctx,
-        (req) => ctx.invokeStream(req, { target }),
+        (req) => inner.stream(req, ctx),
       );
     },
   };
 }
 
-/**
- * Wraps an existing executor with connected tools. The inner executor is called
- * with augmented requests (tool definitions + system fragments injected), and
- * any tool calls it returns are automatically resolved in a loop.
- */
-export function connectTools(
-  tools: Tool[],
-  inner: Executor,
-  options: WithToolsOptions = {},
-): Executor {
-  const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
-  const toolMap = new Map(tools.map((t) => [t.name, t]));
-  const augmentRequest = buildAugmenter(tools);
-  const executeConnectedCalls = buildCallExecutor(toolMap);
-
-  return {
-    async execute(request, ctx) {
-      const augmented = augmentRequest(request);
-      let current = isStreaming(augmented) ? setStreaming(augmented, false) : augmented;
-
-      for (let iteration = 0; iteration < maxIterations; iteration += 1) {
-        const response = await inner.execute(current, ctx);
-        const calls = callData(response);
-        const connected = calls.filter((c) => toolMap.has(c.name));
-        const outer = calls.filter((c) => !toolMap.has(c.name));
-
-        if (connected.length === 0) return response;
-
-        const results = await executeConnectedCalls(connected, ctx);
-        let next = current;
-        for (const r of results) {
-          next = appendToolInteraction(next, {
-            callId: r.id,
-            name: r.name,
-            args: parseToolArgs(r.args),
-            result: r.result,
-          });
-        }
+type ToolLoopState = { request: Program; iteration: number };
+type ToolLoopDecision =
+  | { kind: "complete" }
+  | { kind: "external"; calls: ToolCall[] }
+  | { kind: "continue"; calls: ToolCall[] };
+
+function decideToolLoop(
+  calls: ToolCall[],
+  toolMap: ReadonlyMap<string, Tool>,
+): ToolLoopDecision {
+  const connected: ToolCall[] = [];
+  const outer: ToolCall[] = [];
+  for (const call of calls) {
+    (toolMap.has(call.name) ? connected : outer).push(call);
+  }
+  if (outer.length > 0) return { kind: "external", calls: outer };
+  if (connected.length === 0) return { kind: "complete" };
+  return { kind: "continue", calls: connected };
+}
 
-        if (outer.length > 0) return response;
-        current = next;
-      }
+function createToolLoopState(request: Program): ToolLoopState {
+  return { request, iteration: 0 };
+}
 
-      return inner.execute(current, ctx);
-    },
+function canRunToolLoop(state: ToolLoopState, maxIterations: number): boolean {
+  return state.iteration < maxIterations;
+}
 
-    async *stream(request, ctx) {
-      yield* streamToolLoop(
-        toolMap,
-        maxIterations,
-        augmentRequest,
-        executeConnectedCalls,
-        request,
-        ctx,
-        (req) => inner.stream(req, ctx),
-      );
-    },
-  };
+function appendToolResults(
+  request: Program,
+  results: readonly ToolExecution[],
+): Program {
+  return results.reduce(
+    (next, result) =>
+      appendToolInteraction(next, {
+        callId: result.id,
+        name: result.name,
+        args: parseToolArguments(result.name, result.args),
+        result: result.result,
+      }),
+    request,
+  );
 }
 
-function parseToolArgs(args: string): unknown {
-  try {
-    return JSON.parse(args || "{}");
-  } catch {
-    return {};
-  }
+async function advanceToolLoopState(
+  state: ToolLoopState,
+  calls: readonly ToolCall[],
+  ctx: ExecutorContext,
+  executeCalls: ReturnType<typeof buildCallExecutor>,
+): Promise<ToolLoopState> {
+  return {
+    request: appendToolResults(state.request, await executeCalls(calls, ctx)),
+    iteration: state.iteration + 1,
+  };
 }

package/src/types.ts

@@ -22,7 +22,7 @@ export type ExecutionTarget =
       transforms?: string[];
     };
 
-export type SdkEvent = {
+export type ExecutionEvent = {
   kind: string;
   requestId: string;
   executionId: string;
@@ -33,7 +33,7 @@ export type SdkEvent = {
   data?: Record<string, unknown>;
 };
 
-export type SdkEventInput = Omit<SdkEvent, "timestamp"> & {
+export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
   timestamp?: string;
 };
 
@@ -46,8 +46,11 @@ export type InvokeOptions = {
 
 export type TransformContext = {
   invoke(request: Program, options?: InvokeOptions): Promise<Program>;
-  invokeStream(request: Program, options?: InvokeOptions): AsyncIterable<Program>;
-  observe(event: SdkEvent): void;
+  invokeStream(
+    request: Program,
+    options?: InvokeOptions,
+  ): AsyncIterable<Program>;
+  observe(event: ExecutionEvent): void;
   signal: AbortSignal;
 };
 
@@ -62,8 +65,11 @@ export type ExecutorContext = {
   executionId: string;
   parentExecutionId?: string;
   invoke(request: Program, options?: InvokeOptions): Promise<Program>;
-  invokeStream(request: Program, options?: InvokeOptions): AsyncIterable<Program>;
-  observe(event: SdkEvent): void;
+  invokeStream(
+    request: Program,
+    options?: InvokeOptions,
+  ): AsyncIterable<Program>;
+  observe(event: ExecutionEvent): void;
   signal: AbortSignal;
 };
 
@@ -85,7 +91,9 @@ export type OutputSink = {
   close(): void | Promise<void>;
 };
 
-export function createSdkEvent(input: SdkEventInput): SdkEvent {
+export function createExecutionEvent(
+  input: ExecutionEventInput,
+): ExecutionEvent {
   return {
     ...input,
     timestamp: input.timestamp ?? new Date().toISOString(),