iris-chatbot 0.2.4

package/template/src/lib/tooling/tools/system.ts

@@ -0,0 +1,142 @@
+import { ensureMacOS } from "../safety";
+import { runCommandSafe } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type SetVolumeInput = {
+  level?: number;
+};
+
+type OpenUrlInput = {
+  url?: string;
+};
+
+const APPLESCRIPT_TIMEOUT_MS = 20_000;
+
+function asObject(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object") {
+    throw new Error("Tool input must be an object.");
+  }
+  return input as Record<string, unknown>;
+}
+
+function asNumber(input: unknown, field: string): number {
+  if (typeof input !== "number" || !Number.isFinite(input)) {
+    throw new Error(`Missing required numeric field: ${field}`);
+  }
+  return input;
+}
+
+function asString(input: unknown, field: string): string {
+  if (typeof input !== "string" || !input.trim()) {
+    throw new Error(`Missing required string field: ${field}`);
+  }
+  return input.trim();
+}
+
+function assertHttpUrl(input: string): string {
+  const url = new URL(input);
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("Only http/https URLs are supported.");
+  }
+  return url.toString();
+}
+
+async function runAppleScript(script: string, args: string[] = [], signal?: AbortSignal) {
+  const { stdout } = await runCommandSafe({
+    command: "osascript",
+    args: ["-e", script, ...args],
+    signal,
+    timeoutMs: APPLESCRIPT_TIMEOUT_MS,
+  });
+  return stdout;
+}
+
+async function runSystemSetVolume(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("System automation");
+  const payload = asObject(input) as SetVolumeInput;
+  const level = Math.max(0, Math.min(100, Math.round(asNumber(payload.level, "level"))));
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: "system_set_volume", level };
+  }
+  await runAppleScript(`set volume output volume ${level}`, [], context.signal);
+  return { level };
+}
+
+async function runSystemGetStatus(_: unknown, context: ToolExecutionContext) {
+  ensureMacOS("System automation");
+  const volumeText = await runAppleScript("output volume of (get volume settings)", [], context.signal);
+  const app = await runAppleScript('tell application "System Events" to get name of first process whose frontmost is true', [], context.signal);
+  const timeText = await runAppleScript("return (current date) as text", [], context.signal);
+
+  let battery: string | null = null;
+  try {
+    const { stdout } = await runCommandSafe({
+      command: "pmset",
+      args: ["-g", "batt"],
+      signal: context.signal,
+      timeoutMs: 2_000,
+    });
+    battery = stdout;
+  } catch {
+    battery = null;
+  }
+
+  return {
+    volume: Number(volumeText) || null,
+    frontmostApp: app || null,
+    time: timeText || null,
+    battery,
+  };
+}
+
+async function runSystemOpenUrl(input: unknown, context: ToolExecutionContext) {
+  const payload = asObject(input) as OpenUrlInput;
+  const url = assertHttpUrl(asString(payload.url, "url"));
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: "system_open_url", url };
+  }
+  await runCommandSafe({
+    command: "open",
+    args: [url],
+    signal: context.signal,
+  });
+  return { opened: true, url };
+}
+
+export const systemTools: ToolDefinition[] = [
+  {
+    name: "system_set_volume",
+    description: "Set macOS system output volume level.",
+    inputSchema: {
+      type: "object",
+      required: ["level"],
+      properties: {
+        level: { type: "number" },
+      },
+      additionalProperties: false,
+    },
+    risk: "system",
+    execute: runSystemSetVolume,
+  },
+  {
+    name: "system_get_status",
+    description: "Get basic system status: volume, active app, time, battery.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    risk: "read",
+    execute: runSystemGetStatus,
+  },
+  {
+    name: "system_open_url",
+    description: "Open an HTTP/HTTPS URL in the default browser.",
+    inputSchema: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    risk: "system",
+    execute: runSystemOpenUrl,
+  },
+];

package/template/src/lib/tooling/tools/web.ts

@@ -0,0 +1,212 @@
+import { runCommandSafe, withRetry } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type WebSearchInput = {
+  query?: string;
+  maxResults?: number;
+  recency?: "day" | "week" | "month" | "any";
+};
+
+type WebOpenInput = {
+  url?: string;
+  mode?: "browser" | "extract";
+  maxChars?: number;
+};
+
+const SEARCH_CACHE_TTL_MS = 60_000;
+const searchCache = new Map<
+  string,
+  {
+    createdAt: number;
+    results: Array<{ title: string; url: string; snippet: string; source: string; rank: number }>;
+  }
+>();
+
+function asObject(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object") {
+    throw new Error("Tool input must be an object.");
+  }
+  return input as Record<string, unknown>;
+}
+
+function asString(input: unknown, field: string): string {
+  if (typeof input !== "string" || !input.trim()) {
+    throw new Error(`Missing required string field: ${field}`);
+  }
+  return input.trim();
+}
+
+function asWebUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error("Invalid URL.");
+  }
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("Only http/https URLs are supported.");
+  }
+  return url.toString();
+}
+
+function stripHtml(value: string): string {
+  return value
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function parseDuckDuckGoResults(html: string, maxResults: number) {
+  const results: Array<{ title: string; url: string; snippet: string; source: string; rank: number }> = [];
+  const regex =
+    /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(html)) && results.length < maxResults) {
+    const href = match[1]?.trim();
+    const title = stripHtml(match[2] ?? "");
+    const snippet = stripHtml(match[3] ?? "");
+    if (!href || !title) {
+      continue;
+    }
+    results.push({
+      title,
+      url: href,
+      snippet,
+      source: "duckduckgo",
+      rank: results.length + 1,
+    });
+  }
+  return results;
+}
+
+async function runWebSearch(input: unknown, context: ToolExecutionContext) {
+  const payload = asObject(input) as WebSearchInput;
+  const query = asString(payload.query, "query");
+  const maxResults =
+    typeof payload.maxResults === "number" && Number.isFinite(payload.maxResults)
+      ? Math.max(1, Math.min(10, Math.floor(payload.maxResults)))
+      : 5;
+  const recency = payload.recency ?? "any";
+  const cacheKey = `${query}::${recency}::${maxResults}`;
+  const cached = searchCache.get(cacheKey);
+  if (cached && Date.now() - cached.createdAt <= SEARCH_CACHE_TTL_MS) {
+    return {
+      query,
+      recency,
+      count: cached.results.length,
+      results: cached.results,
+      cached: true,
+    };
+  }
+
+  const q = recency === "any" ? query : `${query} ${recency}`;
+  const target = `https://duckduckgo.com/html/?q=${encodeURIComponent(q)}`;
+
+  const html = await withRetry({
+    operation: async () => {
+      const response = await fetch(target, { signal: context.signal });
+      if (!response.ok) {
+        throw new Error(`Search request failed with ${response.status}`);
+      }
+      return response.text();
+    },
+  });
+
+  const results = parseDuckDuckGoResults(await html, maxResults);
+  if (results.length === 0) {
+    return {
+      query,
+      recency,
+      count: 0,
+      results: [],
+      message: "No results parsed from current backend.",
+    };
+  }
+  searchCache.set(cacheKey, {
+    createdAt: Date.now(),
+    results,
+  });
+  return {
+    query,
+    recency,
+    count: results.length,
+    results,
+  };
+}
+
+async function runWebOpen(input: unknown, context: ToolExecutionContext) {
+  const payload = asObject(input) as WebOpenInput;
+  const url = asWebUrl(asString(payload.url, "url"));
+  const mode = payload.mode === "browser" ? "browser" : "extract";
+  const maxChars =
+    typeof payload.maxChars === "number" && Number.isFinite(payload.maxChars)
+      ? Math.max(200, Math.min(20_000, Math.floor(payload.maxChars)))
+      : 6_000;
+
+  if (mode === "browser") {
+    await runCommandSafe({
+      command: "open",
+      args: [url],
+      signal: context.signal,
+    });
+    return { opened: true, mode, url };
+  }
+
+  const html = await withRetry({
+    operation: async () => {
+      const response = await fetch(url, { signal: context.signal });
+      if (!response.ok) {
+        throw new Error(`Open request failed with ${response.status}`);
+      }
+      return response.text();
+    },
+  });
+
+  const text = stripHtml(await html).slice(0, maxChars);
+  return {
+    mode,
+    url,
+    extractedChars: text.length,
+    text,
+  };
+}
+
+export const webTools: ToolDefinition[] = [
+  {
+    name: "web_search",
+    description: "Search the web for a query and return top results.",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: {
+        query: { type: "string" },
+        maxResults: { type: "number" },
+        recency: { type: "string", enum: ["day", "week", "month", "any"] },
+      },
+      additionalProperties: false,
+    },
+    risk: "external",
+    execute: runWebSearch,
+  },
+  {
+    name: "web_open",
+    description: "Open a URL in browser or fetch/extract readable text.",
+    inputSchema: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: { type: "string" },
+        mode: { type: "string", enum: ["browser", "extract"] },
+        maxChars: { type: "number" },
+      },
+      additionalProperties: false,
+    },
+    risk: "external",
+    execute: runWebOpen,
+  },
+];

package/template/src/lib/tooling/tools/workflow.ts

@@ -0,0 +1,218 @@
+import { normalizeToolError, withRetry } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type WorkflowStep = {
+  id?: string;
+  tool?: string;
+  input?: Record<string, unknown>;
+  dependsOn?: string[];
+  continueOnError?: boolean;
+};
+
+type WorkflowInput = {
+  steps?: WorkflowStep[];
+  maxParallel?: number;
+};
+
+function asObject(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object") {
+    throw new Error("Tool input must be an object.");
+  }
+  return input as Record<string, unknown>;
+}
+
+function validateSteps(steps: WorkflowStep[]): Required<WorkflowStep>[] {
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw new Error("Missing required array field: steps");
+  }
+
+  const ids = new Set<string>();
+  return steps.map((step, index) => {
+    const id = typeof step.id === "string" && step.id.trim() ? step.id.trim() : `step_${index + 1}`;
+    const tool = typeof step.tool === "string" && step.tool.trim() ? step.tool.trim() : "";
+    if (!tool) {
+      throw new Error(`Missing required string field: steps[${index}].tool`);
+    }
+    if (ids.has(id)) {
+      throw new Error(`Duplicate workflow step id: ${id}`);
+    }
+    ids.add(id);
+
+    return {
+      id,
+      tool,
+      input: step.input ?? {},
+      dependsOn: Array.isArray(step.dependsOn) ? step.dependsOn : [],
+      continueOnError: step.continueOnError === true,
+    };
+  });
+}
+
+export function createWorkflowTool(getTools: () => ToolDefinition[]): ToolDefinition {
+  return {
+    name: "workflow_run",
+    description: "Run a multi-step tool workflow with dependencies.",
+    inputSchema: {
+      type: "object",
+      required: ["steps"],
+      properties: {
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["id", "tool"],
+            properties: {
+              id: { type: "string" },
+              tool: { type: "string" },
+              input: { type: "object" },
+              dependsOn: { type: "array", items: { type: "string" } },
+              continueOnError: { type: "boolean" },
+            },
+            additionalProperties: false,
+          },
+        },
+        maxParallel: { type: "number" },
+      },
+      additionalProperties: false,
+    },
+    risk: "write",
+    async execute(input: unknown, context: ToolExecutionContext) {
+      const payload = asObject(input) as WorkflowInput;
+      const steps = validateSteps(payload.steps ?? []);
+      const maxParallel =
+        typeof payload.maxParallel === "number" && Number.isFinite(payload.maxParallel)
+          ? Math.max(1, Math.min(5, Math.floor(payload.maxParallel)))
+          : 3;
+
+      const tools = getTools();
+      const byId = new Map(steps.map((step) => [step.id, step]));
+      for (const step of steps) {
+        for (const depId of step.dependsOn) {
+          if (!byId.has(depId)) {
+            throw new Error(`Unknown dependency ${depId} for step ${step.id}`);
+          }
+          if (depId === step.id) {
+            throw new Error(`Step ${step.id} cannot depend on itself.`);
+          }
+        }
+      }
+
+      const results: Array<{
+        id: string;
+        tool: string;
+        ok: boolean;
+        output?: unknown;
+        error?: string;
+        retryable?: boolean;
+        durationMs: number;
+      }> = [];
+      const done = new Set<string>();
+      const failed = new Set<string>();
+      const running = new Set<string>();
+
+      const canRun = (step: Required<WorkflowStep>) =>
+        step.dependsOn.every((dep) => done.has(dep));
+
+      while (done.size + failed.size < steps.length) {
+        const runnable = steps.filter(
+          (step) =>
+            !done.has(step.id) &&
+            !failed.has(step.id) &&
+            !running.has(step.id) &&
+            canRun(step),
+        );
+
+        if (runnable.length === 0 && running.size === 0) {
+          const blocked = steps
+            .filter((step) => !done.has(step.id) && !failed.has(step.id))
+            .map((step) => step.id);
+          for (const stepId of blocked) {
+            failed.add(stepId);
+            results.push({
+              id: stepId,
+              tool: byId.get(stepId)?.tool ?? "unknown",
+              ok: false,
+              error: "Blocked by failed dependency.",
+              durationMs: 0,
+            });
+          }
+          break;
+        }
+
+        const batch = runnable.slice(0, Math.max(0, maxParallel - running.size));
+        await Promise.all(
+          batch.map(async (step) => {
+            running.add(step.id);
+            const startedAt = Date.now();
+            const tool = tools.find((candidate) => candidate.name === step.tool);
+            if (!tool || tool.name === "workflow_run") {
+              failed.add(step.id);
+              running.delete(step.id);
+              results.push({
+                id: step.id,
+                tool: step.tool,
+                ok: false,
+                error: tool ? "Nested workflow_run is not allowed." : `Unknown tool: ${step.tool}`,
+                durationMs: Date.now() - startedAt,
+              });
+              return;
+            }
+
+            try {
+              const output = await withRetry({
+                operation: async () => tool.execute(step.input, context),
+                maxRetries: 2,
+              });
+              done.add(step.id);
+              results.push({
+                id: step.id,
+                tool: step.tool,
+                ok: true,
+                output,
+                durationMs: Date.now() - startedAt,
+              });
+            } catch (error) {
+              const normalized = normalizeToolError(error);
+              failed.add(step.id);
+              results.push({
+                id: step.id,
+                tool: step.tool,
+                ok: false,
+                error: normalized.message,
+                retryable: normalized.retryable,
+                durationMs: Date.now() - startedAt,
+              });
+              if (!step.continueOnError) {
+                for (const downstream of steps.filter((candidate) =>
+                  candidate.dependsOn.includes(step.id),
+                )) {
+                  if (!done.has(downstream.id) && !failed.has(downstream.id)) {
+                    failed.add(downstream.id);
+                    results.push({
+                      id: downstream.id,
+                      tool: downstream.tool,
+                      ok: false,
+                      error: `Skipped because dependency ${step.id} failed.`,
+                      durationMs: 0,
+                    });
+                  }
+                }
+              }
+            } finally {
+              running.delete(step.id);
+            }
+          }),
+        );
+      }
+
+      const successCount = results.filter((result) => result.ok).length;
+      const failCount = results.length - successCount;
+      return {
+        steps: results,
+        summary: failCount === 0
+          ? `Workflow completed: ${successCount}/${results.length} steps succeeded.`
+          : `Workflow finished with partial failures: ${successCount} succeeded, ${failCount} failed.`,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,27 @@
+import type { LocalToolsSettings } from "../types";
+
+export type ToolRisk =
+  | "read"
+  | "write"
+  | "destructive"
+  | "app"
+  | "external"
+  | "system";
+
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  risk: ToolRisk;
+  execute: (input: unknown, context: ToolExecutionContext) => Promise<unknown>;
+};
+
+export type ToolExecutionContext = {
+  localTools: LocalToolsSettings;
+  signal?: AbortSignal;
+};
+
+export type ToolExecutionResult = {
+  ok: boolean;
+  output: unknown;
+};