mioku-plugin-agent 0.1.0

package/tools/deliver.ts

@@ -0,0 +1,75 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AITool, Bot, MiokuContext } from "mioku";
+import type { FsPolicy } from "./perm";
+import { resolveWorkspacePath } from "./perm";
+import { sendImageSource, sendLocalFile } from "../core/attachment";
+
+interface DeliverToolDeps {
+  ctx: MiokuContext;
+  bot: Bot | undefined;
+  userId: number;
+  policy: FsPolicy;
+}
+
+export function createSendFileTool(deps: DeliverToolDeps): AITool {
+  return {
+    name: "send_file",
+    description:
+      "Send a local file to the user in the current private chat (documents, archives, generated artifacts).",
+    parameters: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "Local file path to send" },
+        name: { type: "string", description: "Optional display file name" },
+      },
+      required: ["file_path"],
+    },
+    handler: async (args) => {
+      const filePath = resolveWorkspacePath(deps.policy, String(args?.file_path ?? ""));
+      if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+        return { error: `File not found: ${filePath}` };
+      }
+      if (!deps.bot) return { error: "bot is not connected" };
+      const name = args?.name ? String(args.name) : path.basename(filePath);
+      await sendLocalFile(
+        deps.ctx,
+        deps.bot,
+        { type: "private", user_id: deps.userId },
+        filePath,
+        name,
+      );
+      return { success: true, file: filePath, name };
+    },
+  };
+}
+
+export function createSendImageTool(deps: DeliverToolDeps): AITool {
+  return {
+    name: "send_image",
+    description:
+      "Send a local image file to the user in the current private chat as a picture message.",
+    parameters: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "Local image path (png/jpg/webp/gif)" },
+      },
+      required: ["file_path"],
+    },
+    handler: async (args) => {
+      const filePath = resolveWorkspacePath(deps.policy, String(args?.file_path ?? ""));
+      if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+        return { error: `File not found: ${filePath}` };
+      }
+      if (!deps.bot) return { error: "bot is not connected" };
+      const sent = await sendImageSource(
+        deps.ctx,
+        deps.bot,
+        { type: "private", user_id: deps.userId },
+        filePath,
+      );
+      if (!sent) return { error: `Failed to send image: ${filePath}` };
+      return { success: true, file: filePath };
+    },
+  };
+}

package/tools/fs.ts

@@ -0,0 +1,296 @@
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import type { AITool } from "mioku";
+import type { FsPolicy } from "./perm";
+import { canWrite, permissionDenied, resolveWorkspacePath } from "./perm";
+
+const READ_DEFAULT_LIMIT = 500;
+const READ_MAX_LIMIT = 2000;
+const READ_MAX_BYTES = 256 * 1024;
+const READ_MAX_LINE = 2000;
+const LIST_MAX_RESULTS = 100;
+const GREP_MAX_MATCHES = 250;
+
+export interface FsToolDeps {
+  policy: FsPolicy;
+}
+
+function toTool(tool: AITool): AITool {
+  return tool;
+}
+
+function lineNumbered(lines: string[], offset: number): string {
+  return lines
+    .map((line, index) => {
+      const truncated =
+        line.length > READ_MAX_LINE
+          ? `${line.slice(0, READ_MAX_LINE)}… [line truncated]`
+          : line;
+      return `${String(offset + index).padStart(6)}\t${truncated}`;
+    })
+    .join("\n");
+}
+
+export function createReadTool(deps: FsToolDeps): AITool {
+  return toTool({
+    name: "read",
+    description:
+      "Read a UTF-8 text file and return numbered lines. Supports offset/limit windowing for large files.",
+    parameters: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "File path (absolute, or relative to the workspace)" },
+        offset: { type: "number", description: "1-based first line to return" },
+        limit: { type: "number", description: "Max lines to return (default 500, max 2000)" },
+      },
+      required: ["file_path"],
+    },
+    handler: async (args) => {
+      const filePath = resolveWorkspacePath(deps.policy, String(args?.file_path ?? ""));
+      let stat: fs.Stats;
+      try {
+        stat = await fsp.stat(filePath);
+      } catch {
+        return { error: `File not found: ${filePath}` };
+      }
+      if (!stat.isFile()) return { error: `Not a regular file: ${filePath}` };
+      const offset = Math.max(1, Math.floor(Number(args?.offset) || 1));
+      let limit = Math.floor(Number(args?.limit) || READ_DEFAULT_LIMIT);
+      limit = Math.min(Math.max(1, limit), READ_MAX_LIMIT);
+      const content = await fsp.readFile(filePath, "utf-8");
+      const allLines = content.split("\n");
+      const selected: string[] = [];
+      let bytes = 0;
+      let index = offset - 1;
+      while (index < allLines.length && selected.length < limit) {
+        const line = `${allLines[index]}\n`;
+        if (bytes + line.length > READ_MAX_BYTES) {
+          selected.push("[output truncated: byte limit reached]");
+          break;
+        }
+        selected.push(allLines[index]);
+        bytes += line.length;
+        index += 1;
+      }
+      return {
+        file: filePath,
+        totalLines: allLines.length,
+        offset,
+        content: lineNumbered(selected, offset),
+        hasMore: index < allLines.length,
+      };
+    },
+  });
+}
+
+export function createWriteTool(deps: FsToolDeps): AITool {
+  return toTool({
+    name: "write",
+    description:
+      "Create or completely overwrite a UTF-8 text file with the given content.",
+    parameters: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "File path" },
+        content: { type: "string", description: "Full file content to write" },
+      },
+      required: ["file_path", "content"],
+    },
+    handler: async (args) => {
+      const filePath = resolveWorkspacePath(deps.policy, String(args?.file_path ?? ""));
+      if (!canWrite(deps.policy, filePath)) {
+        return { error: permissionDenied(deps.policy, "write", filePath).message };
+      }
+      const content = String(args?.content ?? "");
+      await fsp.mkdir(path.dirname(filePath), { recursive: true });
+      await fsp.writeFile(filePath, content, "utf-8");
+      return { success: true, file: filePath, bytes: Buffer.byteLength(content) };
+    },
+  });
+}
+
+export function createEditTool(deps: FsToolDeps): AITool {
+  return toTool({
+    name: "edit",
+    description:
+      "Replace an exact literal string in an existing UTF-8 text file. old_string must appear exactly once unless replace_all is set.",
+    parameters: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "File path" },
+        old_string: { type: "string", description: "Exact text to replace" },
+        new_string: { type: "string", description: "Replacement text" },
+        replace_all: { type: "boolean", description: "Replace every occurrence" },
+      },
+      required: ["file_path", "old_string", "new_string"],
+    },
+    handler: async (args) => {
+      const filePath = resolveWorkspacePath(deps.policy, String(args?.file_path ?? ""));
+      if (!canWrite(deps.policy, filePath)) {
+        return { error: permissionDenied(deps.policy, "edit", filePath).message };
+      }
+      const oldString = String(args?.old_string ?? "");
+      const newString = String(args?.new_string ?? "");
+      if (!oldString) return { error: "old_string must be a non-empty string" };
+      let content: string;
+      try {
+        content = await fsp.readFile(filePath, "utf-8");
+      } catch {
+        return { error: `File not found: ${filePath}` };
+      }
+      const occurrences = content.split(oldString).length - 1;
+      if (occurrences === 0) return { error: "old_string not found in file" };
+      if (occurrences > 1 && !args?.replace_all) {
+        return {
+          error: `old_string appears ${occurrences} times. Provide more surrounding context or set replace_all=true.`,
+        };
+      }
+      const next =
+        occurrences > 1 && args?.replace_all
+          ? content.split(oldString).join(newString)
+          : content.replace(oldString, newString);
+      await fsp.writeFile(filePath, next, "utf-8");
+      return { success: true, file: filePath, replacements: occurrences > 1 && args?.replace_all ? occurrences : 1 };
+    },
+  });
+}
+
+function patternToRegExp(pattern: string): RegExp {
+  let source = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "*") {
+      if (pattern[i + 1] === "*") {
+        source += pattern[i + 2] === "/" ? "(?:.*/)?" : ".*";
+        if (pattern[i + 2] === "/") i += 2;
+        else i += 1;
+      } else {
+        source += "[^/]*";
+      }
+      continue;
+    }
+    if (char === "?") {
+      source += "[^/]";
+      continue;
+    }
+    source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`);
+}
+
+async function walkFiles(root: string, cap: number): Promise<string[]> {
+  const results: string[] = [];
+  const queue = [root];
+  while (queue.length > 0 && results.length < cap * 20) {
+    const current = queue.shift()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        queue.push(full);
+      } else if (entry.isFile()) {
+        results.push(full);
+        if (results.length >= cap * 20) break;
+      }
+    }
+  }
+  return results;
+}
+
+export function createGlobTool(deps: FsToolDeps): AITool {
+  return toTool({
+    name: "glob",
+    description:
+      "Find files whose paths match a glob pattern (supports ** and *). Searches the workspace by default.",
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Glob pattern, e.g. **/*.ts" },
+        path: { type: "string", description: "Directory to search (default: workspace root)" },
+      },
+      required: ["pattern"],
+    },
+    handler: async (args) => {
+      const pattern = String(args?.pattern ?? "");
+      if (!pattern) return { error: "pattern must be a non-empty string" };
+      const root = resolveWorkspacePath(deps.policy, String(args?.path ?? "") || deps.policy.workspaceRoot);
+      if (!fs.existsSync(root)) return { error: `Directory not found: ${root}` };
+      const regExp = patternToRegExp(pattern);
+      const files = await walkFiles(root, LIST_MAX_RESULTS);
+      const matched = files
+        .filter((file) => {
+          const rel = path.relative(root, file).split(path.sep).join("/");
+          return regExp.test(rel) || regExp.test(path.basename(file));
+        })
+        .slice(0, LIST_MAX_RESULTS);
+      return { root, count: matched.length, files: matched };
+    },
+  });
+}
+
+export function createGrepTool(deps: FsToolDeps): AITool {
+  return toTool({
+    name: "grep",
+    description:
+      "Search file contents with a regular expression. Returns matching lines with line numbers.",
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Regular expression" },
+        path: { type: "string", description: "File or directory to search (default: workspace root)" },
+        include: { type: "string", description: "Glob filter for file names, e.g. *.ts" },
+      },
+      required: ["pattern"],
+    },
+    handler: async (args) => {
+      const pattern = String(args?.pattern ?? "");
+      if (!pattern) return { error: "pattern must be a non-empty string" };
+      let regExp: RegExp;
+      try {
+        regExp = new RegExp(pattern);
+      } catch (err) {
+        return { error: `Invalid regex: ${err}` };
+      }
+      const target = resolveWorkspacePath(deps.policy, String(args?.path ?? "") || deps.policy.workspaceRoot);
+      const include = args?.include ? patternToRegExp(String(args.include)) : null;
+      const stat = fs.existsSync(target) ? fs.statSync(target) : null;
+      const files = stat?.isFile() ? [target] : await walkFiles(target, GREP_MAX_MATCHES);
+      const matches: Array<{ file: string; line: number; text: string }> = [];
+      for (const file of files) {
+        if (include && !include.test(path.basename(file))) continue;
+        let content: string;
+        try {
+          if (fs.statSync(file).size > 2 * 1024 * 1024) continue;
+          content = await fsp.readFile(file, "utf-8");
+        } catch {
+          continue;
+        }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          if (regExp.test(lines[i])) {
+            matches.push({
+              file,
+              line: i + 1,
+              text: lines[i].slice(0, 500),
+            });
+            if (matches.length >= GREP_MAX_MATCHES) break;
+          }
+        }
+        if (matches.length >= GREP_MAX_MATCHES) break;
+      }
+      return {
+        pattern,
+        count: matches.length,
+        truncated: matches.length >= GREP_MAX_MATCHES,
+        matches,
+      };
+    },
+  });
+}

package/tools/index.ts

@@ -0,0 +1,194 @@
+import type { AITool, Bot, SessionToolDefinition } from "mioku";
+import type { AgentHost } from "../types";
+import type { BashReporter } from "./bash";
+import type { FsToolDeps } from "./fs";
+import {
+  createEditTool,
+  createGlobTool,
+  createGrepTool,
+  createReadTool,
+  createWriteTool,
+} from "./fs";
+import { createBashTool } from "./bash";
+import { createSendFileTool, createSendImageTool } from "./deliver";
+import { createViewImageTool } from "./view-image";
+import { createWebFetchTool, createWebSearchTool } from "./web";
+import { createTodoTool } from "./todo";
+import {
+  isAutoReviewMode,
+  isQuietMode,
+  normalizePermissionLevel,
+  type FsPolicy,
+} from "./perm";
+import { describeImageFile } from "../core/media";
+import { assessCommandRisk } from "../core/risk";
+import type { TurnActivity } from "../core/activity";
+
+export interface TurnToolOptions {
+  userId: number;
+  bot: Bot | undefined;
+  runId: number;
+  reporter: BashReporter;
+  activity: TurnActivity;
+}
+
+function isToolError(result: unknown): boolean {
+  if (!result || typeof result !== "object") return false;
+  const record = result as Record<string, unknown>;
+  return Boolean(record.error) || record.success === false;
+}
+
+function wrapTool(
+  tool: AITool,
+  host: AgentHost,
+  runId: number,
+  activity: TurnActivity,
+): AITool {
+  const recording = host.getSettings().dataCollection.enabled && runId > 0;
+  const tracking = tool.name !== "bash";
+  if (!recording && !tracking) return tool;
+  return {
+    ...tool,
+    handler: async (args) => {
+      const startedAt = Date.now();
+      try {
+        const result = await tool.handler(args);
+        if (recording) {
+          host.db.recordToolCall(
+            runId,
+            tool.name,
+            args,
+            JSON.stringify(result ?? {}).length,
+            Date.now() - startedAt,
+            !isToolError(result),
+          );
+        }
+        if (tracking) {
+          activity.recordTool(
+            tool.name,
+            args ?? {},
+            result,
+            Date.now() - startedAt,
+          );
+        }
+        return result;
+      } catch (err) {
+        if (recording) {
+          host.db.recordToolCall(
+            runId,
+            tool.name,
+            args,
+            0,
+            Date.now() - startedAt,
+            false,
+            String(err),
+          );
+        }
+        if (tracking) {
+          activity.recordTool(
+            tool.name,
+            args ?? {},
+            { error: String(err) },
+            Date.now() - startedAt,
+          );
+        }
+        throw err;
+      }
+    },
+  };
+}
+
+export function buildTurnTools(
+  host: AgentHost,
+  options: TurnToolOptions,
+): { tools: SessionToolDefinition[]; webSearchState: { count: number } } {
+  const base = host.getBase();
+  const settings = host.getSettings();
+  const policy: FsPolicy = {
+    level: normalizePermissionLevel(base.permissionLevel),
+    workspaceRoot: host.workspaceRoot(options.userId),
+  };
+  const webSearchState = { count: 0 };
+  const resolved = host.resolveModel();
+
+  const fsDeps: FsToolDeps = { policy };
+
+  const tools: AITool[] = [
+    createReadTool(fsDeps),
+    createGlobTool(fsDeps),
+    createGrepTool(fsDeps),
+    createSendFileTool({
+      ctx: host.ctx,
+      bot: options.bot,
+      userId: options.userId,
+      policy,
+    }),
+    createSendImageTool({
+      ctx: host.ctx,
+      bot: options.bot,
+      userId: options.userId,
+      policy,
+    }),
+  ];
+
+  if (policy.level !== "read-only") {
+    tools.push(createWriteTool(fsDeps), createEditTool(fsDeps));
+  }
+  if (resolved?.isMultimodal || resolved?.vision) {
+    tools.push(
+      createViewImageTool({
+        policy,
+        describeImage:
+          !resolved.isMultimodal && resolved.vision
+            ? (file: string) => describeImageFile(host, file)
+            : undefined,
+      }),
+    );
+  }
+  if (settings.bash.enabled) {
+    tools.push(
+      createBashTool({
+        userId: options.userId,
+        policy,
+        config: settings.bash,
+        approvals: host.approvals,
+        reporter: options.reporter,
+        assessRisk: isAutoReviewMode(policy.level)
+          ? (command, purpose) => assessCommandRisk(host, command, purpose)
+          : undefined,
+      }),
+    );
+  }
+  if (settings.webSearch.enabled) {
+    const searchTool = createWebSearchTool({
+      settings,
+      onSearch: () => {
+        webSearchState.count += 1;
+      },
+    });
+    tools.push(searchTool);
+  }
+  if (settings.webFetch.enabled) {
+    tools.push(createWebFetchTool({ settings }));
+  }
+  tools.push(
+    createTodoTool({
+      host,
+      userId: options.userId,
+      bot: options.bot,
+      quiet: isQuietMode(policy.level),
+    }),
+  );
+
+  // TODO(skills): load chat-style external skills via aiService.registerSkill.
+  // TODO(mcp): Model Context Protocol client for external tool servers.
+  // TODO(memory): hybrid retrieval (vector + BM25 + rerank) via the shared knowledge-base service.
+
+  return {
+    tools: tools.map((tool) => ({
+      name: tool.name,
+      tool: wrapTool(tool, host, options.runId, options.activity),
+    })),
+    webSearchState,
+  };
+}

package/tools/perm.ts

@@ -0,0 +1,87 @@
+import * as path from "node:path";
+import type { AgentPermissionLevel } from "../types";
+
+export const PERMISSION_LEVELS: readonly AgentPermissionLevel[] = [
+  "read-only",
+  "workspace-write",
+  "auto",
+  "full",
+  "yolo",
+];
+
+export function normalizePermissionLevel(value: unknown): AgentPermissionLevel {
+  const raw = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if ((PERMISSION_LEVELS as readonly string[]).includes(raw)) {
+    return raw as AgentPermissionLevel;
+  }
+  return "workspace-write";
+}
+
+export interface FsPolicy {
+  level: AgentPermissionLevel;
+  workspaceRoot: string;
+}
+
+export function workspaceRootFor(baseDir: string, userId: number): string {
+  const raw = String(baseDir ?? "").trim();
+  const base =
+    raw && path.isAbsolute(raw)
+      ? raw
+      : path.resolve(
+          process.cwd(),
+          raw || path.join("data", "agent", "workspace"),
+        );
+  return path.resolve(base, String(userId));
+}
+
+export function resolveWorkspacePath(policy: FsPolicy, target: string): string {
+  const rawPath = String(target ?? "").trim();
+  if (!rawPath) throw new Error("path must be a non-empty string");
+  if (path.isAbsolute(rawPath)) return path.resolve(rawPath);
+  return path.resolve(policy.workspaceRoot, rawPath);
+}
+
+export function isInside(root: string, target: string): boolean {
+  const rel = path.relative(root, target);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+export function canWrite(policy: FsPolicy, target: string): boolean {
+  if (policy.level === "read-only") return false;
+  if (policy.level === "workspace-write") {
+    return isInside(policy.workspaceRoot, target);
+  }
+  return true;
+}
+
+export function bashRequiresApproval(level: AgentPermissionLevel): boolean {
+  return level === "read-only" || level === "workspace-write";
+}
+
+export function isAutoReviewMode(level: AgentPermissionLevel): boolean {
+  return level === "auto";
+}
+
+export function isQuietMode(level: AgentPermissionLevel): boolean {
+  return level === "yolo";
+}
+
+export function batchesActivity(level: AgentPermissionLevel): boolean {
+  return level === "full";
+}
+
+export function permissionDenied(
+  policy: FsPolicy,
+  operation: string,
+  target: string,
+): Error {
+  const scope =
+    policy.level === "read-only"
+      ? "the session is read-only"
+      : `writes are restricted to the workspace (${policy.workspaceRoot})`;
+  return new Error(
+    `[permission denied] Cannot ${operation} ${target}: ${scope}.`,
+  );
+}