@neutrome/lilsdk-ts 0.1.2 → 0.2.0

package/src/primitives/index.ts

@@ -0,0 +1,120 @@
+import {
+  cloneInstruction,
+  type Instruction,
+  type Program,
+} from "@neutrome/lil-engine";
+
+export function indexOf(program: Program, needle: Instruction): number {
+  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 {
+  const i = indexOf(program, needle);
+  return i >= 0 ? cloneInstruction(program.code[i]!) : undefined;
+}
+
+export function walk(
+  program: Program,
+  callback: (instruction: Instruction, index: number, program: Program) => void,
+): void {
+  program.code.forEach((instruction, index) => callback(instruction, index, program));
+}
+
+export function map(
+  program: Program,
+  callback: (instruction: Instruction, index: number, program: Program) => Instruction,
+): Program {
+  return {
+    code: program.code.map((instruction, index) =>
+      cloneInstruction(callback(instruction, index, program))
+    ),
+    buffers: cloneBuffers(program.buffers),
+  };
+}
+
+export function filter(
+  program: Program,
+  callback: (instruction: Instruction, index: number, program: Program) => boolean,
+): Program {
+  return {
+    code: program.code
+      .filter((instruction, index) => callback(instruction, index, program))
+      .map(cloneInstruction),
+    buffers: cloneBuffers(program.buffers),
+  };
+}
+
+export function reduce<T>(
+  program: Program,
+  callback: (accumulator: T, instruction: Instruction, index: number, program: Program) => T,
+  initialValue: T,
+): T {
+  let accumulator = initialValue;
+  program.code.forEach((instruction, index) => {
+    accumulator = callback(accumulator, instruction, index, program);
+  });
+  return accumulator;
+}
+
+export function all(
+  program: Program,
+  callback: (instruction: Instruction, index: number, program: Program) => boolean,
+): boolean {
+  for (const [index, instruction] of program.code.entries()) {
+    if (!callback(instruction, index, program)) return false;
+  }
+  return true;
+}
+
+export function any(
+  program: Program,
+  callback: (instruction: Instruction, index: number, program: Program) => boolean,
+): boolean {
+  for (const [index, instruction] of program.code.entries()) {
+    if (callback(instruction, index, program)) return true;
+  }
+  return false;
+}
+
+function instructionEquals(left: Instruction, right: Instruction): boolean {
+  if (left.opcode !== right.opcode || left.value.kind !== right.value.kind) {
+    return false;
+  }
+
+  switch (left.value.kind) {
+    case "none":
+      return true;
+    case "string":
+    case "float":
+    case "int":
+    case "ref":
+      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);
+    case "key_string":
+      return (
+        right.value.kind === "key_string" &&
+        left.value.key === right.value.key &&
+        left.value.value === right.value.value
+      );
+    case "key_json":
+      return (
+        right.value.kind === "key_json" &&
+        left.value.key === right.value.key &&
+        bytesEqual(left.value.value, right.value.value)
+      );
+  }
+}
+
+function bytesEqual(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.byteLength !== right.byteLength) return false;
+  return left.every((value, index) => value === right[index]);
+}
+
+function cloneBuffers(buffers: Uint8Array[]): Uint8Array[] {
+  return buffers.map((buffer) => buffer.slice());
+}

package/src/stream/index.ts

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

package/src/synthetic/index.ts

@@ -0,0 +1,151 @@
+import {
+  appendInstructions,
+  createProgram,
+  insertAfter,
+  insertBefore,
+  messages,
+  Opcode,
+  setModel,
+  toolDefinitions,
+  type Instruction,
+  type Opcode as OpcodeValue,
+  type Program,
+} from "@neutrome/lil-engine";
+
+const encoder = new TextEncoder();
+
+export type TextMessageRole = "system" | "user" | "assistant";
+
+export type ToolInteraction = {
+  callId: string;
+  name: string;
+  args?: unknown;
+  result: unknown;
+};
+
+export function makeRequest(model: string): Program {
+  return setModel(createProgram(), model);
+}
+
+export function makeResponse(model: string): Program {
+  return setModel(createProgram(), model);
+}
+
+export function makeMessage(role: TextMessageRole, text: string): Program {
+  return createProgram({ code: buildMessage(role, text) });
+}
+
+export function prependSystemPrompt(program: Program, text: string): Program {
+  const systemMessage = buildMessage("system", text);
+  const spans = messages(program);
+  if (spans.length === 0) {
+    return appendInstructions(program, systemMessage);
+  }
+  return insertBefore(program, spans[0]!.start, systemMessage);
+}
+
+export function appendUserMessage(program: Program, text: string): Program {
+  return appendInstructions(program, buildMessage("user", text));
+}
+
+export function appendAssistantMessage(program: Program, text: string): Program {
+  return appendInstructions(program, buildMessage("assistant", text));
+}
+
+export function makeToolCall(
+  name: string,
+  args: unknown = {},
+  callId: string = crypto.randomUUID(),
+): Program {
+  return createProgram({
+    code: [
+      { opcode: Opcode.MSG_START, value: { kind: "none" } },
+      { 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_END, value: { kind: "none" } },
+      { opcode: Opcode.MSG_END, value: { kind: "none" } },
+    ],
+  });
+}
+
+export function makeToolResponse(callId: string, result: unknown): Program {
+  return createProgram({ code: buildToolResponse(callId, result) });
+}
+
+export function appendToolInteraction(
+  program: Program,
+  interaction: ToolInteraction,
+): Program {
+  return appendInstructions(program, [
+    ...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" } },
+    { opcode: roleOpcode(role), value: { kind: "none" } },
+    { opcode: Opcode.TXT_CHUNK, value: { kind: "string", value: text } },
+    { opcode: Opcode.MSG_END, value: { kind: "none" } },
+  ];
+}
+
+function buildToolResponse(callId: string, result: unknown): Instruction[] {
+  return [
+    { 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_END, value: { kind: "none" } },
+    { opcode: Opcode.MSG_END, value: { kind: "none" } },
+  ];
+}
+
+function roleOpcode(role: TextMessageRole): OpcodeValue {
+  switch (role) {
+    case "system":
+      return Opcode.ROLE_SYS;
+    case "user":
+      return Opcode.ROLE_USR;
+    case "assistant":
+      return Opcode.ROLE_AST;
+  }
+}
+
+function encodeJson(value: unknown): Uint8Array {
+  return encoder.encode(JSON.stringify(value));
+}
+
+function stringifyResult(result: unknown): string {
+  return typeof result === "string" ? result : JSON.stringify(result);
+}

package/src/tools.ts

@@ -0,0 +1,357 @@
+import {
+  callData,
+  createProgram,
+  isStreaming,
+  Opcode,
+  setStreaming,
+  type Instruction,
+  type Program,
+} from "@neutrome/lil-engine";
+import {
+  addTool,
+  appendToolInteraction,
+  prependSystemPrompt,
+} from "./synthetic/index.ts";
+import {
+  createSdkEvent,
+  type ExecutionTarget,
+  type Executor,
+  type ExecutorContext,
+  type Tool,
+} from "./types.ts";
+
+export type WithToolsOptions = {
+  maxIterations?: number;
+};
+
+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 result = await tool.execute(parsed, ctx);
+        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,
+            lilText: buildToolTrace(call, result),
+          },
+        }));
+        return { ...call, result };
+      }),
+    );
+  };
+}
+
+type ToolDeltaAcc = { index: number; id: string; name: string; args: string };
+
+function collectToolDeltasFromChunk(
+  chunk: Program,
+  acc: Map<number, ToolDeltaAcc>,
+) {
+  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 : "",
+        });
+      }
+    }
+  }
+}
+
+function filterChunkForClient(
+  chunk: Program,
+  connectedNames: Set<string>,
+  toolAcc: Map<number, ToolDeltaAcc>,
+  isIntermediate: boolean,
+): Program | null {
+  const kept: Instruction[] = [];
+
+  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);
+        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> {
+  const connectedNames = new Set(toolMap.keys());
+  let current = augmentRequest(request);
+  let yieldedStart = false;
+
+  for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+    const toolAcc = new Map<number, ToolDeltaAcc>();
+    const isIntermediate = true; // assume intermediate; we'll yield end markers later if final
+
+    for await (const chunk of invokeStream(current)) {
+      collectToolDeltasFromChunk(chunk, toolAcc);
+
+      const filtered = filterChunkForClient(chunk, connectedNames, toolAcc, 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 connected = calls.filter((c) => toolMap.has(c.name));
+    const outer = calls.filter((c) => !toolMap.has(c.name));
+
+    if (connected.length === 0 || outer.length > 0) {
+      // 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" } });
+      } 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
+    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;
+  }
+
+  // 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 withTools(
+  tools: Tool[],
+  target: ExecutionTarget,
+  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 ctx.invoke(current, { target });
+        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;
+      }
+
+      return ctx.invoke(current, { target });
+    },
+
+    async *stream(request, ctx) {
+      yield* streamToolLoop(
+        toolMap,
+        maxIterations,
+        augmentRequest,
+        executeConnectedCalls,
+        request,
+        ctx,
+        (req) => ctx.invokeStream(req, { target }),
+      );
+    },
+  };
+}
+
+/**
+ * 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,
+          });
+        }
+
+        if (outer.length > 0) return response;
+        current = next;
+      }
+
+      return inner.execute(current, ctx);
+    },
+
+    async *stream(request, ctx) {
+      yield* streamToolLoop(
+        toolMap,
+        maxIterations,
+        augmentRequest,
+        executeConnectedCalls,
+        request,
+        ctx,
+        (req) => inner.stream(req, ctx),
+      );
+    },
+  };
+}
+
+function parseToolArgs(args: string): unknown {
+  try {
+    return JSON.parse(args || "{}");
+  } catch {
+    return {};
+  }
+}