@neutrome/lilsdk 0.3.5

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");
+}

package/src/tools.ts

@@ -0,0 +1,279 @@
+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 {
+  buildCallExecutor,
+  buildToolAugmenter,
+  parseToolArguments,
+  type ToolCall,
+  type ToolExecution,
+} from "./tools-support.ts";
+
+export { ToolArgumentsError } from "./tools-support.ts";
+
+export type WithToolsOptions = {
+  maxIterations?: number;
+};
+
+const DEFAULT_MAX_ITERATIONS = 10;
+
+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) {
+    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,
+  isIntermediate: boolean,
+): Program | null {
+  const kept: Instruction[] = [];
+
+  for (const instr of chunk.code) {
+    switch (instr.opcode) {
+      case Opcode.STREAM_TOOL_DELTA:
+        // Tool ownership can be revealed by a later fragment, so defer all deltas.
+        break;
+      case Opcode.RESP_DONE:
+        if (isIntermediate) continue;
+        kept.push(instr);
+        break;
+      case Opcode.STREAM_END:
+        if (isIntermediate) continue;
+        kept.push(instr);
+        break;
+      default:
+        kept.push(instr);
+        break;
+    }
+  }
+
+  if (kept.length === 0) return null;
+  return createProgram({ code: kept });
+}
+
+async function* streamToolLoop(
+  toolMap: Map<string, Tool>,
+  maxIterations: number,
+  augmentRequest: (r: Program) => Program,
+  executeConnectedCalls: ReturnType<typeof buildCallExecutor>,
+  request: Program,
+  ctx: ExecutorContext,
+  invokeStream: (req: Program) => AsyncIterable<Program>,
+): AsyncGenerator<Program> {
+  let state = createToolLoopState(augmentRequest(request));
+  let yieldedStart = false;
+
+  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(state.request)) {
+      toolDeltas.push(...collectToolDeltasFromChunk(chunk, toolAcc));
+
+      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
+        ) {
+          continue;
+        }
+        yield filtered;
+        if (filtered.code.some((i) => i.opcode === Opcode.STREAM_START)) {
+          yieldedStart = true;
+        }
+      }
+    }
+
+    // Convert accumulated tool deltas to call data
+    const calls = [...toolAcc.values()]
+      .filter((t) => t.name)
+      .map((t) => ({ id: t.id, name: t.name, args: t.args }));
+
+    const decision = decideToolLoop(calls, toolMap);
+
+    if (decision.kind !== "continue") {
+      // Final iteration — emit suppressed end markers
+      const endInstructions: Instruction[] = [];
+      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.STREAM_END,
+        value: { kind: "none" },
+      });
+      yield createProgram({ code: endInstructions });
+      return;
+    }
+
+    // Execute connected tools and loop
+    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" } },
+    ],
+  });
+}
+
+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 = buildToolAugmenter(tools);
+  const executeConnectedCalls = buildCallExecutor(toolMap);
+
+  return {
+    async execute(request, ctx) {
+      const augmented = augmentRequest(request);
+      let state = createToolLoopState(
+        isStreaming(augmented) ? setStreaming(augmented, false) : augmented,
+      );
+
+      while (canRunToolLoop(state, maxIterations)) {
+        const response = await inner.execute(state.request, ctx);
+        const calls = callData(response);
+        const decision = decideToolLoop(calls, toolMap);
+        if (decision.kind !== "continue") return response;
+
+        state = await advanceToolLoopState(
+          state,
+          decision.calls,
+          ctx,
+          executeConnectedCalls,
+        );
+      }
+
+      return inner.execute(state.request, ctx);
+    },
+
+    async *stream(request, ctx) {
+      yield* streamToolLoop(
+        toolMap,
+        maxIterations,
+        augmentRequest,
+        executeConnectedCalls,
+        request,
+        ctx,
+        (req) => inner.stream(req, ctx),
+      );
+    },
+  };
+}
+
+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 };
+}
+
+function createToolLoopState(request: Program): ToolLoopState {
+  return { request, iteration: 0 };
+}
+
+function canRunToolLoop(state: ToolLoopState, maxIterations: number): boolean {
+  return state.iteration < maxIterations;
+}
+
+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,
+  );
+}
+
+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

@@ -0,0 +1,101 @@
+import type { Program } from "@neutrome/lil-engine";
+
+export type TransformCapability =
+  | "read_messages"
+  | "write_messages"
+  | "write_config"
+  | "write_tools"
+  | "drop_content"
+  | "provider_extension";
+
+export type ExecutionTarget =
+  | {
+      kind: "provider";
+      provider?: string;
+      model: string;
+      transforms?: string[];
+    }
+  | {
+      kind: "executor";
+      executorId: string;
+      alias: string;
+      transforms?: string[];
+    };
+
+export type ExecutionEvent = {
+  kind: string;
+  requestId: string;
+  executionId: string;
+  timestamp: string;
+  parentExecutionId?: string;
+  target?: { kind: "provider" | "executor"; id: string };
+  errorKind?: string;
+  data?: Record<string, unknown>;
+};
+
+export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
+  timestamp?: string;
+};
+
+export type InvokeOptions = {
+  target?: ExecutionTarget;
+  requestId?: string;
+  executionId?: string;
+  parentExecutionId?: string;
+};
+
+export type TransformContext = {
+  invoke(request: Program, options?: InvokeOptions): Promise<Program>;
+  invokeStream(
+    request: Program,
+    options?: InvokeOptions,
+  ): AsyncIterable<Program>;
+  observe(event: ExecutionEvent): void;
+  signal: AbortSignal;
+};
+
+export type ProgramTransform = {
+  name: string;
+  capabilities: TransformCapability[];
+  apply(program: Program, ctx: TransformContext): Program | Promise<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: ExecutionEvent): 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 createExecutionEvent(
+  input: ExecutionEventInput,
+): ExecutionEvent {
+  return {
+    ...input,
+    timestamp: input.timestamp ?? new Date().toISOString(),
+  };
+}