iris-chatbot 0.2.4

package/template/src/lib/tooling/providers/openai.ts

@@ -0,0 +1,267 @@
+import OpenAI from "openai";
+import type { ProviderToolSchema } from "../registry";
+import type {
+  CreateProviderSessionArgs,
+  ProviderCitationSource,
+  NormalizedToolCall,
+  ProviderStep,
+  ToolLoopMessage,
+  ToolProviderSession,
+} from "./types";
+
+type OpenAIResponseInputItem = OpenAI.Responses.ResponseInputItem;
+
+function mapMessages(messages: ToolLoopMessage[]): OpenAIResponseInputItem[] {
+  const mapped: OpenAIResponseInputItem[] = [];
+
+  for (const message of messages) {
+    if (message.role === "system") {
+      continue;
+    }
+
+    if (message.role === "tool") {
+      if (!message.toolCallId) {
+        continue;
+      }
+      mapped.push({
+        type: "function_call_output",
+        call_id: message.toolCallId,
+        output: message.content,
+      } as OpenAIResponseInputItem);
+      continue;
+    }
+
+    mapped.push({
+      type: "message",
+      role: message.role,
+      content: message.content,
+    } as OpenAIResponseInputItem);
+  }
+
+  return mapped;
+}
+
+function mapTools(tools: ProviderToolSchema[]): OpenAI.Responses.FunctionTool[] {
+  return tools.map((tool) => ({
+    type: "function" as const,
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.input_schema,
+    strict: false,
+  }));
+}
+
+function normalizeSource(
+  source: { url?: unknown; title?: unknown } | null | undefined,
+): ProviderCitationSource | null {
+  if (!source || typeof source.url !== "string") {
+    return null;
+  }
+  const url = source.url.trim();
+  if (!url) {
+    return null;
+  }
+  const title =
+    typeof source.title === "string" && source.title.trim()
+      ? source.title.trim()
+      : undefined;
+  return {
+    url,
+    title,
+  };
+}
+
+function addSource(
+  uniqueSources: Map<string, ProviderCitationSource>,
+  source: ProviderCitationSource | null,
+) {
+  if (!source) {
+    return;
+  }
+  const existing = uniqueSources.get(source.url);
+  if (!existing || (!existing.title && source.title)) {
+    uniqueSources.set(source.url, source);
+  }
+}
+
+export function extractCitationSourcesFromResponse(response: {
+  output?: unknown;
+}): ProviderCitationSource[] {
+  if (!Array.isArray(response.output)) {
+    return [];
+  }
+
+  const uniqueSources = new Map<string, ProviderCitationSource>();
+
+  for (const outputItem of response.output) {
+    if (!outputItem || typeof outputItem !== "object") {
+      continue;
+    }
+    const item = outputItem as {
+      type?: unknown;
+      action?: unknown;
+      content?: unknown;
+    };
+
+    if (item.type === "web_search_call" && item.action && typeof item.action === "object") {
+      const action = item.action as { type?: unknown; sources?: unknown };
+      if (action.type === "search" && Array.isArray(action.sources)) {
+        for (const source of action.sources) {
+          if (!source || typeof source !== "object") {
+            continue;
+          }
+          addSource(uniqueSources, normalizeSource(source as { url?: unknown; title?: unknown }));
+        }
+      }
+      continue;
+    }
+
+    if (item.type !== "message" || !Array.isArray(item.content)) {
+      continue;
+    }
+
+    for (const contentPart of item.content) {
+      if (!contentPart || typeof contentPart !== "object") {
+        continue;
+      }
+      const part = contentPart as { type?: unknown; annotations?: unknown };
+      if (part.type !== "output_text" || !Array.isArray(part.annotations)) {
+        continue;
+      }
+
+      for (const annotation of part.annotations) {
+        if (!annotation || typeof annotation !== "object") {
+          continue;
+        }
+        const urlCitation = annotation as {
+          type?: unknown;
+          url?: unknown;
+          title?: unknown;
+        };
+        if (urlCitation.type !== "url_citation") {
+          continue;
+        }
+        addSource(uniqueSources, normalizeSource(urlCitation));
+      }
+    }
+  }
+
+  return [...uniqueSources.values()];
+}
+
+function parseToolCalls(outputItems: unknown): NormalizedToolCall[] {
+  if (!Array.isArray(outputItems)) {
+    return [];
+  }
+
+  const calls: NormalizedToolCall[] = [];
+  for (const rawCall of outputItems) {
+    if (!rawCall || typeof rawCall !== "object") {
+      continue;
+    }
+
+    const call = rawCall as {
+      type?: unknown;
+      call_id?: unknown;
+      id?: unknown;
+      name?: unknown;
+      arguments?: unknown;
+    };
+
+    if (call.type !== "function_call") {
+      continue;
+    }
+
+    if (
+      typeof call.call_id !== "string" ||
+      typeof call.name !== "string"
+    ) {
+      continue;
+    }
+
+    let parsedInput: Record<string, unknown> = {};
+    const rawArguments = call.arguments;
+
+    if (typeof rawArguments === "string" && rawArguments.trim()) {
+      try {
+        const maybeObj = JSON.parse(rawArguments);
+        if (maybeObj && typeof maybeObj === "object") {
+          parsedInput = maybeObj as Record<string, unknown>;
+        }
+      } catch {
+        throw new Error(
+          `Model returned invalid JSON args for tool ${call.name}.`,
+        );
+      }
+    }
+
+    calls.push({
+      id: call.call_id,
+      name: call.name,
+      input: parsedInput,
+    });
+  }
+
+  return calls;
+}
+
+export function createOpenAISession(
+  args: CreateProviderSessionArgs & {
+    baseURL?: string;
+    defaultHeaders?: Record<string, string>;
+  },
+): ToolProviderSession {
+  const client = new OpenAI({
+    apiKey: args.apiKey,
+    baseURL: args.baseURL,
+    defaultHeaders: args.defaultHeaders,
+  });
+  const initialInput = mapMessages(args.messages);
+  const pendingInput: OpenAIResponseInputItem[] = [...initialInput];
+  const functionTools = mapTools(args.tools);
+  const webSearchTools: OpenAI.Responses.WebSearchTool[] = args.enableWebSources
+    ? [{ type: "web_search" }]
+    : [];
+  const tools: OpenAI.Responses.Tool[] = [...functionTools, ...webSearchTools];
+  const instructions = args.system?.trim() || undefined;
+  let previousResponseId: string | null = null;
+
+  return {
+    async step(signal?: AbortSignal): Promise<ProviderStep> {
+      const response = await client.responses.create({
+        model: args.model,
+        instructions,
+        input: [...pendingInput],
+        previous_response_id: previousResponseId,
+        tools: tools.length > 0 ? tools : undefined,
+        tool_choice: tools.length > 0 ? "auto" : undefined,
+        include: args.enableWebSources ? ["web_search_call.action.sources"] : undefined,
+      }, { signal });
+
+      previousResponseId = response.id;
+      pendingInput.length = 0;
+
+      if (response.error?.message) {
+        throw new Error(response.error.message);
+      }
+
+      const text = response.output_text || "";
+      const toolCalls = parseToolCalls((response as { output?: unknown }).output);
+      const sources = extractCitationSourcesFromResponse(response as { output?: unknown });
+
+      return {
+        text,
+        toolCalls,
+        sources,
+      };
+    },
+
+    addToolResult(params) {
+      pendingInput.push({
+        type: "function_call_output",
+        call_id: params.callId,
+        output: params.result,
+      });
+    },
+  };
+}

package/template/src/lib/tooling/providers/openai_compatible.ts

@@ -0,0 +1,16 @@
+import { createOpenAISession } from "./openai";
+import type { CreateProviderSessionArgs, ToolProviderSession } from "./types";
+
+export function createOpenAICompatibleSession(
+  args: CreateProviderSessionArgs & {
+    baseURL: string;
+    defaultHeaders?: Record<string, string>;
+  },
+): ToolProviderSession {
+  return createOpenAISession({
+    ...args,
+    baseURL: args.baseURL,
+    defaultHeaders: args.defaultHeaders,
+  });
+}
+

package/template/src/lib/tooling/providers/types.ts

@@ -0,0 +1,44 @@
+import type { ProviderToolSchema } from "../registry";
+
+export type ToolLoopMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  toolCallId?: string;
+  toolName?: string;
+};
+
+export type NormalizedToolCall = {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+};
+
+export type ProviderCitationSource = {
+  url: string;
+  title?: string;
+};
+
+export type ProviderStep = {
+  text: string;
+  toolCalls: NormalizedToolCall[];
+  sources?: ProviderCitationSource[];
+};
+
+export type CreateProviderSessionArgs = {
+  model: string;
+  apiKey: string;
+  system?: string;
+  messages: ToolLoopMessage[];
+  tools: ProviderToolSchema[];
+  enableWebSources?: boolean;
+};
+
+export type ToolProviderSession = {
+  step: (signal?: AbortSignal) => Promise<ProviderStep>;
+  addToolResult: (params: {
+    callId: string;
+    name: string;
+    result: string;
+    isError?: boolean;
+  }) => void;
+};

package/template/src/lib/tooling/registry.ts

@@ -0,0 +1,103 @@
+import type { LocalToolsSettings } from "../types";
+import type { ToolDefinition } from "./types";
+import { appTools } from "./tools/apps";
+import { appPlusTools } from "./tools/apps_plus";
+import { communicationTools } from "./tools/communication";
+import { fileTools } from "./tools/files";
+import { musicTools } from "./tools/music";
+import { notesTools } from "./tools/notes";
+import { notesPlusTools } from "./tools/notes_plus";
+import { numbersTools } from "./tools/numbers";
+import { scheduleTools } from "./tools/schedule";
+import { systemTools } from "./tools/system";
+import { webTools } from "./tools/web";
+import { createWorkflowTool } from "./tools/workflow";
+
+export type ProviderToolSchema = {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+};
+
+const MAX_SERIALIZED_TOOL_OUTPUT_CHARS = 12_000;
+
+export function createToolRegistry(localTools: LocalToolsSettings): ToolDefinition[] {
+  const tools: ToolDefinition[] = [...fileTools];
+
+  if (localTools.enableNotes) {
+    tools.push(...notesTools);
+    tools.push(...notesPlusTools);
+  }
+
+  if (localTools.enableApps) {
+    tools.push(...appTools);
+    tools.push(...appPlusTools);
+  }
+
+  if (localTools.enableNumbers) {
+    tools.push(...numbersTools);
+  }
+
+  if (localTools.enableWeb) {
+    tools.push(...webTools);
+  }
+
+  if (localTools.enableMusic) {
+    tools.push(...musicTools);
+  }
+
+  if (localTools.enableCalendar) {
+    tools.push(...scheduleTools);
+  }
+
+  if (localTools.enableMail) {
+    tools.push(...communicationTools);
+  }
+
+  if (localTools.enableSystem) {
+    tools.push(...systemTools);
+  }
+
+  if (localTools.enableWorkflow) {
+    const workflowTool = createWorkflowTool(() => tools);
+    tools.push(workflowTool);
+  }
+
+  return tools;
+}
+
+export function toProviderToolSchemas(tools: ToolDefinition[]): ProviderToolSchema[] {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema,
+  }));
+}
+
+export function findToolByName(
+  tools: ToolDefinition[],
+  name: string,
+): ToolDefinition | null {
+  return tools.find((tool) => tool.name === name) ?? null;
+}
+
+export function serializeToolOutput(output: unknown): string {
+  if (typeof output === "string") {
+    if (output.length <= MAX_SERIALIZED_TOOL_OUTPUT_CHARS) {
+      return output;
+    }
+    const remaining = output.length - MAX_SERIALIZED_TOOL_OUTPUT_CHARS;
+    return `${output.slice(0, MAX_SERIALIZED_TOOL_OUTPUT_CHARS)}\n...[truncated ${remaining} chars]`;
+  }
+
+  try {
+    const serialized = JSON.stringify(output, null, 2);
+    if (serialized.length <= MAX_SERIALIZED_TOOL_OUTPUT_CHARS) {
+      return serialized;
+    }
+    const remaining = serialized.length - MAX_SERIALIZED_TOOL_OUTPUT_CHARS;
+    return `${serialized.slice(0, MAX_SERIALIZED_TOOL_OUTPUT_CHARS)}\n...[truncated ${remaining} chars]`;
+  } catch {
+    return String(output);
+  }
+}

package/template/src/lib/tooling/runtime.ts

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+
+export type ToolErrorCode =
+  | "TIMEOUT"
+  | "VALIDATION"
+  | "PERMISSION"
+  | "NOT_FOUND"
+  | "TRANSIENT"
+  | "UNAVAILABLE";
+
+export type NormalizedToolError = {
+  code: ToolErrorCode;
+  message: string;
+  retryable: boolean;
+  details?: string;
+};
+
+type RunCommandSafeParams = {
+  command: string;
+  args: string[];
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  maxOutputChars?: number;
+};
+
+type RunCommandSafeResult = {
+  stdout: string;
+  stderr: string;
+};
+
+const idempotencyStore = new Map<string, unknown>();
+
+function trimOutput(value: string, maxOutputChars: number): string {
+  if (value.length <= maxOutputChars) {
+    return value;
+  }
+  const remaining = value.length - maxOutputChars;
+  return `${value.slice(0, maxOutputChars)}... (+${remaining} chars truncated)`;
+}
+
+export async function runCommandSafe(
+  params: RunCommandSafeParams,
+): Promise<RunCommandSafeResult> {
+  const timeoutMs = params.timeoutMs ?? 25_000;
+  const maxOutputChars = params.maxOutputChars ?? 12_000;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(params.command, params.args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      signal: params.signal,
+    });
+
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+
+    let forceKillTimer: NodeJS.Timeout | null = null;
+    const finalize = (action: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      if (forceKillTimer) {
+        clearTimeout(forceKillTimer);
+      }
+      action();
+    };
+
+    const timer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      child.kill("SIGTERM");
+      forceKillTimer = setTimeout(() => {
+        if (!settled) {
+          child.kill("SIGKILL");
+        }
+      }, 1_000);
+      finalize(() => reject(new Error(`Timed out after ${timeoutMs}ms`)));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      finalize(() => reject(error));
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        finalize(() => resolve({
+          stdout: trimOutput(stdout.trim(), maxOutputChars),
+          stderr: trimOutput(stderr.trim(), maxOutputChars),
+        }));
+        return;
+      }
+
+      finalize(() => reject(
+        new Error(
+          trimOutput(
+            stderr.trim() || `${params.command} exited with code ${code}`,
+            maxOutputChars,
+          ),
+        ),
+      ));
+    });
+  });
+}
+
+export function normalizeToolError(error: unknown): NormalizedToolError {
+  const message =
+    error instanceof Error ? error.message : "Unexpected tool runtime error.";
+  const lower = message.toLowerCase();
+
+  if (lower.includes("timed out") || lower.includes("timeout")) {
+    return { code: "TIMEOUT", message, retryable: true };
+  }
+  if (lower.includes("outside allowed roots") || lower.includes("blocked")) {
+    return { code: "PERMISSION", message, retryable: false };
+  }
+  if (
+    lower.includes("missing required") ||
+    lower.includes("must be") ||
+    lower.includes("invalid")
+  ) {
+    return { code: "VALIDATION", message, retryable: false };
+  }
+  if (lower.includes("not found") || lower.includes("no such file")) {
+    return { code: "NOT_FOUND", message, retryable: false };
+  }
+  if (
+    lower.includes("temporar") ||
+    lower.includes("econn") ||
+    lower.includes("enotfound")
+  ) {
+    return { code: "TRANSIENT", message, retryable: true };
+  }
+
+  return { code: "UNAVAILABLE", message, retryable: false };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withRetry<T>(params: {
+  operation: () => Promise<T>;
+  maxRetries?: number;
+  baseDelayMs?: number;
+}): Promise<T> {
+  const maxRetries = params.maxRetries ?? 2;
+  const baseDelayMs = params.baseDelayMs ?? 120;
+
+  let attempt = 0;
+  while (true) {
+    try {
+      return await params.operation();
+    } catch (error) {
+      const normalized = normalizeToolError(error);
+      if (!normalized.retryable || attempt >= maxRetries) {
+        throw error;
+      }
+      const jitter = Math.floor(Math.random() * 80);
+      const delay = baseDelayMs * 2 ** attempt + jitter;
+      attempt += 1;
+      await sleep(delay);
+    }
+  }
+}
+
+export async function withIdempotency<T>(params: {
+  key?: string;
+  operation: () => Promise<T>;
+}): Promise<T> {
+  if (!params.key) {
+    return params.operation();
+  }
+
+  if (idempotencyStore.has(params.key)) {
+    return idempotencyStore.get(params.key) as T;
+  }
+
+  const result = await params.operation();
+  idempotencyStore.set(params.key, result);
+  return result;
+}