iris-chatbot 0.2.4

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

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import type { ApprovalMode, LocalToolsSettings } from "../types";
+import type { ToolRisk } from "./types";
+
+const SYSTEM_DENY_PREFIXES = [
+  "/System",
+  "/Library",
+  "/private",
+  "/bin",
+  "/sbin",
+  "/usr",
+  "/etc",
+] as const;
+
+const SENSITIVE_SEGMENTS = [".ssh", ".aws", ".gnupg", ".config"];
+
+function isInside(root: string, target: string): boolean {
+  const rel = path.relative(root, target);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+export function expandUserPath(value: string): string {
+  if (!value) {
+    return value;
+  }
+  if (value === "~") {
+    return os.homedir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+export async function normalizeAllowedRoots(allowedRoots: string[]): Promise<string[]> {
+  const roots: string[] = [];
+  for (const rawRoot of allowedRoots) {
+    const expanded = expandUserPath(rawRoot).trim();
+    if (!expanded) {
+      continue;
+    }
+    const absolute = path.isAbsolute(expanded)
+      ? path.normalize(expanded)
+      : path.resolve(process.cwd(), expanded);
+
+    try {
+      roots.push(await fs.realpath(absolute));
+    } catch {
+      roots.push(absolute);
+    }
+  }
+  return [...new Set(roots)];
+}
+
+async function resolveExistingPath(candidate: string): Promise<string> {
+  const absolute = path.isAbsolute(candidate)
+    ? path.normalize(candidate)
+    : path.resolve(process.cwd(), candidate);
+  return fs.realpath(absolute);
+}
+
+async function resolveWriteTarget(candidate: string): Promise<string> {
+  const absolute = path.isAbsolute(candidate)
+    ? path.normalize(candidate)
+    : path.resolve(process.cwd(), candidate);
+
+  try {
+    return await fs.realpath(absolute);
+  } catch {
+    let cursor = path.dirname(absolute);
+    let suffix = path.basename(absolute);
+
+    while (true) {
+      try {
+        const ancestorReal = await fs.realpath(cursor);
+        return path.join(ancestorReal, suffix);
+      } catch {
+        const next = path.dirname(cursor);
+        if (next === cursor) {
+          throw new Error(`Unable to resolve write target path: ${absolute}`);
+        }
+        suffix = path.join(path.basename(cursor), suffix);
+        cursor = next;
+      }
+    }
+  }
+}
+
+function hasSensitiveSegment(target: string): boolean {
+  return SENSITIVE_SEGMENTS.some((segment) =>
+    target.split(path.sep).includes(segment),
+  );
+}
+
+function isDeniedBySystemPrefix(target: string): boolean {
+  return SYSTEM_DENY_PREFIXES.some(
+    (prefix) => target === prefix || target.startsWith(`${prefix}${path.sep}`),
+  );
+}
+
+export async function assertAllowedPath(params: {
+  candidate: string;
+  localTools: LocalToolsSettings;
+  mode: "read" | "write";
+}): Promise<string> {
+  const normalizedRoots = await normalizeAllowedRoots(params.localTools.allowedRoots);
+  if (normalizedRoots.length === 0) {
+    throw new Error("No allowed filesystem roots are configured.");
+  }
+
+  const resolved =
+    params.mode === "read"
+      ? await resolveExistingPath(expandUserPath(params.candidate))
+      : await resolveWriteTarget(expandUserPath(params.candidate));
+
+  const insideAllowed = normalizedRoots.some((root) => isInside(root, resolved));
+  if (!insideAllowed) {
+    throw new Error(`Path is outside allowed roots: ${resolved}`);
+  }
+
+  if (isDeniedBySystemPrefix(resolved)) {
+    throw new Error(`Path is blocked by system denylist: ${resolved}`);
+  }
+
+  if (hasSensitiveSegment(resolved)) {
+    throw new Error(`Path contains a blocked sensitive segment: ${resolved}`);
+  }
+
+  return resolved;
+}
+
+export function requiresApprovalForRisk(risk: ToolRisk, mode: ApprovalMode): boolean {
+  if (mode === "trusted_auto") {
+    return false;
+  }
+
+  if (mode === "always_confirm_writes") {
+    return risk !== "read";
+  }
+
+  return risk === "destructive";
+}
+
+export function requiresApprovalForSafetyProfile(
+  risk: ToolRisk,
+  profile: "strict" | "balanced" | "auto",
+): boolean {
+  if (profile === "strict") {
+    return risk !== "read";
+  }
+
+  if (profile === "balanced") {
+    return ["write", "destructive", "external", "system"].includes(risk);
+  }
+
+  return risk === "destructive" || risk === "external";
+}
+
+export function ensureMacOS(feature: string) {
+  if (process.platform !== "darwin") {
+    throw new Error(`${feature} is only available on macOS.`);
+  }
+}

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

@@ -0,0 +1,108 @@
+import { ensureMacOS } from "../safety";
+import { runCommandSafe } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type AppInput = {
+  appName?: string;
+};
+
+const APP_COMMAND_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 asString(input: unknown, field: string): string {
+  if (typeof input !== "string" || !input.trim()) {
+    throw new Error(`Missing required string field: ${field}`);
+  }
+  return input.trim();
+}
+
+async function runCommand(command: string, args: string[], signal?: AbortSignal): Promise<string> {
+  const { stdout } = await runCommandSafe({
+    command,
+    args,
+    signal,
+    timeoutMs: APP_COMMAND_TIMEOUT_MS,
+  });
+  return stdout;
+}
+
+async function runAppOpen(input: unknown, context: ToolExecutionContext) {
+  const payload = asObject(input) as AppInput;
+  const appName = asString(payload.appName, "appName");
+
+  ensureMacOS("App open automation");
+
+  if (context.localTools.dryRun) {
+    return {
+      dryRun: true,
+      action: "app_open",
+      appName,
+    };
+  }
+
+  await runCommand("open", ["-a", appName], context.signal);
+  return {
+    opened: true,
+    appName,
+  };
+}
+
+async function runAppFocus(input: unknown, context: ToolExecutionContext) {
+  const payload = asObject(input) as AppInput;
+  const appName = asString(payload.appName, "appName");
+
+  ensureMacOS("App focus automation");
+
+  if (context.localTools.dryRun) {
+    return {
+      dryRun: true,
+      action: "app_focus",
+      appName,
+    };
+  }
+
+  const script = `tell application ${JSON.stringify(appName)} to activate`;
+  await runCommand("osascript", ["-e", script], context.signal);
+
+  return {
+    focused: true,
+    appName,
+  };
+}
+
+export const appTools: ToolDefinition[] = [
+  {
+    name: "app_open",
+    description: "Open an installed macOS app by name.",
+    inputSchema: {
+      type: "object",
+      required: ["appName"],
+      properties: {
+        appName: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    risk: "app",
+    execute: runAppOpen,
+  },
+  {
+    name: "app_focus",
+    description: "Bring an app to the foreground.",
+    inputSchema: {
+      type: "object",
+      required: ["appName"],
+      properties: {
+        appName: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    risk: "app",
+    execute: runAppFocus,
+  },
+];

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

@@ -0,0 +1,153 @@
+import { ensureMacOS } from "../safety";
+import { runCommandSafe } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type AppNameInput = {
+  appName?: string;
+};
+
+type AppOpenResourceInput = {
+  appName?: string;
+  pathOrUrl?: string;
+};
+
+type AppWindowActionInput = {
+  appName?: string;
+  action?: "minimize" | "fullscreen" | "hide" | "unhide" | "close_front_window";
+};
+
+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();
+}
+
+async function runAppleScript(script: string, args: string[] = [], signal?: AbortSignal) {
+  const { stdout } = await runCommandSafe({
+    command: "osascript",
+    args: ["-e", script, ...args],
+    signal,
+  });
+  return stdout;
+}
+
+async function runAppQuit(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("App automation");
+  const payload = asObject(input) as AppNameInput;
+  const appName = asString(payload.appName, "appName");
+
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: "app_quit", appName };
+  }
+
+  await runAppleScript(`tell application ${JSON.stringify(appName)} to quit`, [], context.signal);
+  return { quit: true, appName };
+}
+
+async function runAppOpenResource(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("App automation");
+  const payload = asObject(input) as AppOpenResourceInput;
+  const pathOrUrl = asString(payload.pathOrUrl, "pathOrUrl");
+  const appName = typeof payload.appName === "string" ? payload.appName.trim() : "";
+
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: "app_open_resource", appName: appName || null, pathOrUrl };
+  }
+
+  const args = appName ? ["-a", appName, pathOrUrl] : [pathOrUrl];
+  await runCommandSafe({
+    command: "open",
+    args,
+    signal: context.signal,
+  });
+  return { opened: true, appName: appName || null, pathOrUrl };
+}
+
+async function runAppWindowAction(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("App automation");
+  const payload = asObject(input) as AppWindowActionInput;
+  const appName = asString(payload.appName, "appName");
+  const action = payload.action;
+  if (!action) {
+    throw new Error("Missing required string field: action");
+  }
+
+  if (context.localTools.dryRun) {
+    return { dryRun: true, action: "app_window_action", appName, windowAction: action };
+  }
+
+  const actionScript =
+    action === "hide"
+      ? "set visible to false"
+      : action === "unhide"
+        ? "set visible to true"
+        : action === "close_front_window"
+          ? 'if (count of windows) > 0 then close window 1'
+          : action === "minimize"
+            ? 'if (count of windows) > 0 then set miniaturized of window 1 to true'
+            : 'if (count of windows) > 0 then set value of attribute "AXFullScreen" of window 1 to true';
+
+  const script =
+    `tell application ${JSON.stringify(appName)}\n` +
+    "activate\n" +
+    `${actionScript}\n` +
+    "end tell";
+  await runAppleScript(script, [], context.signal);
+  return { appName, action };
+}
+
+export const appPlusTools: ToolDefinition[] = [
+  {
+    name: "app_quit",
+    description: "Quit an app by name.",
+    inputSchema: {
+      type: "object",
+      required: ["appName"],
+      properties: { appName: { type: "string" } },
+      additionalProperties: false,
+    },
+    risk: "app",
+    execute: runAppQuit,
+  },
+  {
+    name: "app_open_resource",
+    description: "Open a URL or file path, optionally with a specific app.",
+    inputSchema: {
+      type: "object",
+      required: ["pathOrUrl"],
+      properties: {
+        appName: { type: "string" },
+        pathOrUrl: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    risk: "app",
+    execute: runAppOpenResource,
+  },
+  {
+    name: "app_window_action",
+    description: "Perform a window action for an app.",
+    inputSchema: {
+      type: "object",
+      required: ["appName", "action"],
+      properties: {
+        appName: { type: "string" },
+        action: {
+          type: "string",
+          enum: ["minimize", "fullscreen", "hide", "unhide", "close_front_window"],
+        },
+      },
+      additionalProperties: false,
+    },
+    risk: "app",
+    execute: runAppWindowAction,
+  },
+];