octoflow-core 1.0.0

package/dist/actions/builtin/shell.js

@@ -0,0 +1,221 @@
+import { execFile, execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { checkCommandSafety } from "../../adapters/agents/runtime/command-safety.js";
+import { assertWorkspacePath } from "../../runtime/isolation/workspace-boundary.js";
+import { defineAction } from "../define.js";
+import {
+  optionalNumberArg,
+  optionalStringArg,
+  optionalStringArrayArg,
+  optionalStringRecordArg,
+  requiredStringArg
+} from "./args.js";
+import {
+  mergeProcessEnv,
+  shellQuote,
+  validateEnvKeys
+} from "./shell-shared.js";
+function isTmuxAvailable() {
+  try {
+    execFileSync("tmux", ["-V"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runInTmux(opts) {
+  const { command, args, cwd, env = {}, timeoutMs, sessionPrefix } = opts;
+  const workDir = await fsp.mkdtemp(path.join(os.tmpdir(), "ab-tmux-"));
+  const stdinPath = path.join(workDir, "stdin.txt");
+  const stdoutPath = path.join(workDir, "stdout.log");
+  const stderrPath = path.join(workDir, "stderr.log");
+  const exitCodePath = path.join(workDir, "exit-code.txt");
+  const stdoutPipePath = path.join(workDir, "stdout.pipe");
+  const stderrPipePath = path.join(workDir, "stderr.pipe");
+  const scriptPath = path.join(workDir, "run.sh");
+  const sessionName = `${sessionPrefix.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 20)}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
+  try {
+    await fsp.writeFile(stdinPath, "", { encoding: "utf8", mode: 384 });
+    const commandParts = [command, ...args].map(shellQuote);
+    const script = [
+      "#!/bin/sh",
+      "umask 077",
+      `EXIT_FILE=${shellQuote(exitCodePath)}`,
+      `STDOUT_FILE=${shellQuote(stdoutPath)}`,
+      `STDERR_FILE=${shellQuote(stderrPath)}`,
+      `STDOUT_PIPE=${shellQuote(stdoutPipePath)}`,
+      `STDERR_PIPE=${shellQuote(stderrPipePath)}`,
+      `STDIN_FILE=${shellQuote(stdinPath)}`,
+      "cleanup() {",
+      "  code=$?",
+      "  trap - EXIT INT TERM",
+      '  wait "$stdout_tee_pid" "$stderr_tee_pid" 2>/dev/null || true',
+      '  rm -f "$STDOUT_PIPE" "$STDERR_PIPE"',
+      `  printf '%s' "$code" > "$EXIT_FILE"`,
+      '  exit "$code"',
+      "}",
+      "trap cleanup EXIT INT TERM",
+      'rm -f "$STDOUT_PIPE" "$STDERR_PIPE"',
+      'mkfifo "$STDOUT_PIPE" "$STDERR_PIPE"',
+      'tee "$STDOUT_FILE" < "$STDOUT_PIPE" &',
+      "stdout_tee_pid=$!",
+      'tee "$STDERR_FILE" < "$STDERR_PIPE" >&2 &',
+      "stderr_tee_pid=$!",
+      'exec < "$STDIN_FILE"',
+      `${commandParts.join(" ")} > "$STDOUT_PIPE" 2> "$STDERR_PIPE"`
+    ].join("\n");
+    await fsp.writeFile(scriptPath, script, { mode: 448 });
+    const tmuxArgs = ["new-session", "-d", "-s", sessionName];
+    if (cwd) tmuxArgs.push("-c", cwd);
+    tmuxArgs.push("/bin/sh", scriptPath);
+    const mergedEnv = mergeProcessEnv(env);
+    execFileSync("tmux", tmuxArgs, { stdio: "ignore", env: mergedEnv });
+    const deadline = Date.now() + timeoutMs;
+    let missingChecks = 0;
+    while (true) {
+      if (fs.existsSync(exitCodePath)) break;
+      if (Date.now() >= deadline) {
+        try {
+          execFileSync("tmux", ["kill-session", "-t", sessionName], {
+            stdio: "ignore"
+          });
+        } catch {
+        }
+        throw new Error(`tmux_exec timed out after ${timeoutMs}ms`);
+      }
+      await delay(50);
+      try {
+        execFileSync("tmux", ["has-session", "-t", sessionName], {
+          stdio: "ignore"
+        });
+      } catch {
+        missingChecks++;
+        if (missingChecks >= 3) break;
+      }
+    }
+    const stdout = await fsp.readFile(stdoutPath, "utf8").catch(() => "");
+    const stderr = await fsp.readFile(stderrPath, "utf8").catch(() => "");
+    const exitCodeRaw = (await fsp.readFile(exitCodePath, "utf8").catch(() => "")).trim();
+    const parsed = Number.parseInt(exitCodeRaw, 10);
+    return { stdout, stderr, exitCode: Number.isNaN(parsed) ? 1 : parsed };
+  } finally {
+    try {
+      execFileSync("tmux", ["kill-session", "-t", sessionName], {
+        stdio: "ignore"
+      });
+    } catch {
+    }
+    await fsp.rm(workDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+function runDirect(command, args, cwd, env, timeoutMs) {
+  return new Promise((resolve) => {
+    const mergedEnv = mergeProcessEnv(env);
+    execFile(
+      command,
+      args,
+      { cwd, env: mergedEnv, timeout: timeoutMs },
+      (error, stdout, stderr) => {
+        const exitCode = error && "code" in error ? typeof error.code === "number" ? error.code : 1 : 0;
+        resolve({ stdout, stderr, exitCode });
+      }
+    );
+  });
+}
+function createShellActions(options = {}) {
+  return [
+    defineAction({
+      name: "tmux_exec",
+      description: 'Run a shell command in an isolated tmux session (falls back to direct process exec when tmux is missing). Returns { stdout, stderr, exitCode, runner: "tmux"|"direct" }. Use for scripts, CLI tools, builds, tests. Dangerous patterns (rm -rf, curl | sh, shell eval) are blocked.',
+      parameters: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: 'The executable to run (e.g. "npm", "python3", "bash", "git").'
+          },
+          args: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Command arguments as a string array (e.g. ["test", "--run", "mytest"]).'
+          },
+          cwd: {
+            type: "string",
+            description: "Working directory for the command \u2014 supports git worktree paths. When OctoFlow is configured with a workspace, cwd must stay inside that workspace."
+          },
+          env: {
+            type: "object",
+            additionalProperties: { type: "string" },
+            description: "Extra environment variables to set (merged on top of the current environment). Keys must be valid identifier names."
+          },
+          timeout_ms: {
+            type: "number",
+            description: "Maximum execution time in milliseconds. Defaults to 30000 (30 s)."
+          },
+          session_prefix: {
+            type: "string",
+            description: 'Optional prefix for the tmux session name (useful for log identification). Defaults to "ab-shell".'
+          }
+        },
+        required: ["command"]
+      },
+      execute: async (args) => {
+        const command = requiredStringArg(args, "command");
+        const cmdArgs = optionalStringArrayArg(args, "args") ?? [];
+        const cwdInput = optionalStringArg(args, "cwd");
+        let cwd;
+        if (options.workspace) {
+          try {
+            cwd = assertWorkspacePath(cwdInput, { workspace: options.workspace });
+          } catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+          }
+        } else {
+          cwd = cwdInput;
+        }
+        const env = optionalStringRecordArg(args, "env");
+        const timeoutMs = optionalNumberArg(args, "timeout_ms") ?? 3e4;
+        const sessionPrefix = optionalStringArg(args, "session_prefix") ?? "ab-shell";
+        const safety = checkCommandSafety(command, cmdArgs);
+        if (!safety.safe) {
+          return {
+            error: `Command blocked: ${safety.reason}`,
+            command,
+            args: cmdArgs
+          };
+        }
+        if (env) {
+          try {
+            validateEnvKeys(env);
+          } catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+          }
+        }
+        if (isTmuxAvailable()) {
+          const result2 = await runInTmux({
+            command,
+            args: cmdArgs,
+            cwd,
+            env,
+            timeoutMs,
+            sessionPrefix
+          });
+          return { ...result2, runner: "tmux" };
+        }
+        const result = await runDirect(command, cmdArgs, cwd, env, timeoutMs);
+        return { ...result, runner: "direct" };
+      },
+      tags: ["shell", "exec", "builtin"]
+    })
+  ];
+}
+export {
+  createShellActions
+};
+//# sourceMappingURL=shell.js.map

package/dist/actions/builtin/shell.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/actions/builtin/shell.ts"],
+  "sourcesContent": ["import { execFile, execFileSync } from 'node:child_process';\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport fsp from 'node:fs/promises';\nimport os from 'node:os';\nimport path from 'node:path';\nimport { setTimeout as delay } from 'node:timers/promises';\n\nimport { checkCommandSafety } from '../../adapters/agents/runtime/command-safety.js';\nimport { assertWorkspacePath } from '../../runtime/isolation/workspace-boundary.js';\nimport { defineAction } from '../define.js';\nimport type { ActionDefinition } from '../types.js';\nimport {\n  optionalNumberArg,\n  optionalStringArg,\n  optionalStringArrayArg,\n  optionalStringRecordArg,\n  requiredStringArg,\n} from './args.js';\nimport {\n  mergeProcessEnv,\n  shellQuote,\n  validateEnvKeys,\n} from './shell-shared.js';\n\nfunction isTmuxAvailable(): boolean {\n  try {\n    execFileSync('tmux', ['-V'], { stdio: 'ignore' });\n    return true;\n  } catch {\n    return false;\n  }\n}\n\ninterface TmuxExecOpts {\n  command: string;\n  args: string[];\n  cwd?: string;\n  env?: Record<string, string>;\n  timeoutMs: number;\n  sessionPrefix: string;\n}\n\nasync function runInTmux(\n  opts: TmuxExecOpts\n): Promise<{ stdout: string; stderr: string; exitCode: number }> {\n  const { command, args, cwd, env = {}, timeoutMs, sessionPrefix } = opts;\n  const workDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'ab-tmux-'));\n  const stdinPath = path.join(workDir, 'stdin.txt');\n  const stdoutPath = path.join(workDir, 'stdout.log');\n  const stderrPath = path.join(workDir, 'stderr.log');\n  const exitCodePath = path.join(workDir, 'exit-code.txt');\n  const stdoutPipePath = path.join(workDir, 'stdout.pipe');\n  const stderrPipePath = path.join(workDir, 'stderr.pipe');\n  const scriptPath = path.join(workDir, 'run.sh');\n  const sessionName = `${sessionPrefix.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 20)}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;\n\n  try {\n    await fsp.writeFile(stdinPath, '', { encoding: 'utf8', mode: 0o600 });\n\n    const commandParts = [command, ...args].map(shellQuote);\n    const script = [\n      '#!/bin/sh',\n      'umask 077',\n      `EXIT_FILE=${shellQuote(exitCodePath)}`,\n      `STDOUT_FILE=${shellQuote(stdoutPath)}`,\n      `STDERR_FILE=${shellQuote(stderrPath)}`,\n      `STDOUT_PIPE=${shellQuote(stdoutPipePath)}`,\n      `STDERR_PIPE=${shellQuote(stderrPipePath)}`,\n      `STDIN_FILE=${shellQuote(stdinPath)}`,\n      'cleanup() {',\n      '  code=$?',\n      '  trap - EXIT INT TERM',\n      '  wait \"$stdout_tee_pid\" \"$stderr_tee_pid\" 2>/dev/null || true',\n      '  rm -f \"$STDOUT_PIPE\" \"$STDERR_PIPE\"',\n      '  printf \\'%s\\' \"$code\" > \"$EXIT_FILE\"',\n      '  exit \"$code\"',\n      '}',\n      'trap cleanup EXIT INT TERM',\n      'rm -f \"$STDOUT_PIPE\" \"$STDERR_PIPE\"',\n      'mkfifo \"$STDOUT_PIPE\" \"$STDERR_PIPE\"',\n      'tee \"$STDOUT_FILE\" < \"$STDOUT_PIPE\" &',\n      'stdout_tee_pid=$!',\n      'tee \"$STDERR_FILE\" < \"$STDERR_PIPE\" >&2 &',\n      'stderr_tee_pid=$!',\n      'exec < \"$STDIN_FILE\"',\n      `${commandParts.join(' ')} > \"$STDOUT_PIPE\" 2> \"$STDERR_PIPE\"`,\n    ].join('\\n');\n\n    await fsp.writeFile(scriptPath, script, { mode: 0o700 });\n\n    const tmuxArgs = ['new-session', '-d', '-s', sessionName];\n    if (cwd) tmuxArgs.push('-c', cwd);\n    tmuxArgs.push('/bin/sh', scriptPath);\n\n    // Merge process.env with user overrides so the tmux session has a usable PATH etc.\n    const mergedEnv = mergeProcessEnv(env) as Record<string, string>;\n    execFileSync('tmux', tmuxArgs, { stdio: 'ignore', env: mergedEnv });\n\n    const deadline = Date.now() + timeoutMs;\n    let missingChecks = 0;\n    while (true) {\n      if (fs.existsSync(exitCodePath)) break;\n      if (Date.now() >= deadline) {\n        try {\n          execFileSync('tmux', ['kill-session', '-t', sessionName], {\n            stdio: 'ignore',\n          });\n        } catch {\n          /* session already gone \u2014 best-effort cleanup */\n        }\n        throw new Error(`tmux_exec timed out after ${timeoutMs}ms`);\n      }\n      await delay(50);\n      try {\n        execFileSync('tmux', ['has-session', '-t', sessionName], {\n          stdio: 'ignore',\n        });\n      } catch {\n        missingChecks++;\n        if (missingChecks >= 3) break;\n      }\n    }\n\n    const stdout = await fsp.readFile(stdoutPath, 'utf8').catch(() => '');\n    const stderr = await fsp.readFile(stderrPath, 'utf8').catch(() => '');\n    const exitCodeRaw = (\n      await fsp.readFile(exitCodePath, 'utf8').catch(() => '')\n    ).trim();\n    const parsed = Number.parseInt(exitCodeRaw, 10);\n    return { stdout, stderr, exitCode: Number.isNaN(parsed) ? 1 : parsed };\n  } finally {\n    try {\n      execFileSync('tmux', ['kill-session', '-t', sessionName], {\n        stdio: 'ignore',\n      });\n    } catch {\n      /* session already gone \u2014 best-effort cleanup in finally */\n    }\n    await fsp.rm(workDir, { recursive: true, force: true }).catch(() => {\n      /* workdir may already be removed \u2014 best-effort cleanup in finally */\n    });\n  }\n}\n\nfunction runDirect(\n  command: string,\n  args: string[],\n  cwd: string | undefined,\n  env: Record<string, string> | undefined,\n  timeoutMs: number\n): Promise<{ stdout: string; stderr: string; exitCode: number }> {\n  return new Promise((resolve) => {\n    const mergedEnv = mergeProcessEnv(env) as\n      | Record<string, string>\n      | undefined;\n    execFile(\n      command,\n      args,\n      { cwd, env: mergedEnv, timeout: timeoutMs },\n      (error, stdout, stderr) => {\n        const exitCode =\n          error && 'code' in error\n            ? typeof error.code === 'number'\n              ? error.code\n              : 1\n            : 0;\n        resolve({ stdout, stderr, exitCode });\n      }\n    );\n  });\n}\n\nexport interface ShellActionsOptions {\n  readonly workspace?: string;\n}\n\nexport function createShellActions(\n  options: ShellActionsOptions = {}\n): ActionDefinition[] {\n  return [\n    defineAction({\n      name: 'tmux_exec',\n      description:\n        'Run a shell command in an isolated tmux session (falls back to direct process exec when tmux is missing). Returns { stdout, stderr, exitCode, runner: \"tmux\"|\"direct\" }. Use for scripts, CLI tools, builds, tests. Dangerous patterns (rm -rf, curl | sh, shell eval) are blocked.',\n      parameters: {\n        type: 'object',\n        properties: {\n          command: {\n            type: 'string',\n            description:\n              'The executable to run (e.g. \"npm\", \"python3\", \"bash\", \"git\").',\n          },\n          args: {\n            type: 'array',\n            items: { type: 'string' },\n            description:\n              'Command arguments as a string array (e.g. [\"test\", \"--run\", \"mytest\"]).',\n          },\n          cwd: {\n            type: 'string',\n            description:\n              'Working directory for the command \u2014 supports git worktree paths. When OctoFlow is configured with a workspace, cwd must stay inside that workspace.',\n          },\n          env: {\n            type: 'object',\n            additionalProperties: { type: 'string' },\n            description:\n              'Extra environment variables to set (merged on top of the current environment). Keys must be valid identifier names.',\n          },\n          timeout_ms: {\n            type: 'number',\n            description:\n              'Maximum execution time in milliseconds. Defaults to 30000 (30 s).',\n          },\n          session_prefix: {\n            type: 'string',\n            description:\n              'Optional prefix for the tmux session name (useful for log identification). Defaults to \"ab-shell\".',\n          },\n        },\n        required: ['command'],\n      },\n      execute: async (args) => {\n        const command = requiredStringArg(args, 'command');\n        const cmdArgs = optionalStringArrayArg(args, 'args') ?? [];\n        const cwdInput = optionalStringArg(args, 'cwd');\n        let cwd: string | undefined;\n        if (options.workspace) {\n          try {\n            cwd = assertWorkspacePath(cwdInput, { workspace: options.workspace });\n          } catch (err) {\n            return { error: err instanceof Error ? err.message : String(err) };\n          }\n        } else {\n          cwd = cwdInput;\n        }\n        const env = optionalStringRecordArg(args, 'env');\n        const timeoutMs = optionalNumberArg(args, 'timeout_ms') ?? 30_000;\n        const sessionPrefix =\n          optionalStringArg(args, 'session_prefix') ?? 'ab-shell';\n\n        // Security: block dangerous command patterns\n        const safety = checkCommandSafety(command, cmdArgs);\n        if (!safety.safe) {\n          return {\n            error: `Command blocked: ${safety.reason}`,\n            command,\n            args: cmdArgs,\n          };\n        }\n\n        // Security: validate env variable key names\n        if (env) {\n          try {\n            validateEnvKeys(env);\n          } catch (err) {\n            return { error: err instanceof Error ? err.message : String(err) };\n          }\n        }\n\n        if (isTmuxAvailable()) {\n          const result = await runInTmux({\n            command,\n            args: cmdArgs,\n            cwd,\n            env,\n            timeoutMs,\n            sessionPrefix,\n          });\n          return { ...result, runner: 'tmux' };\n        }\n\n        const result = await runDirect(command, cmdArgs, cwd, env, timeoutMs);\n        return { ...result, runner: 'direct' };\n      },\n      tags: ['shell', 'exec', 'builtin'],\n    }),\n  ];\n}\n"],
+  "mappings": "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",
+  "names": ["result"]
+}

package/dist/actions/builtin/tasks.d.ts

@@ -0,0 +1,3 @@
+import type { ActionDefinition } from '../types.js';
+export declare function createTaskActions(): ActionDefinition[];
+//# sourceMappingURL=tasks.d.ts.map

package/dist/actions/builtin/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../src/actions/builtin/tasks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAOpD,wBAAgB,iBAAiB,IAAI,gBAAgB,EAAE,CAuDtD"}

package/dist/actions/builtin/tasks.js

@@ -0,0 +1,54 @@
+import { defineAction } from "../define.js";
+import {
+  optionalNumberArg,
+  optionalStringArg,
+  requiredStringArg
+} from "./args.js";
+function createTaskActions() {
+  return [
+    defineAction({
+      name: "get_task",
+      description: "Retrieve details of a specific task by ID, including status, history, and artifacts.",
+      parameters: {
+        type: "object",
+        properties: {
+          taskId: { type: "string", description: "Task ID to retrieve" }
+        },
+        required: ["taskId"]
+      },
+      execute: (args, ctx) => ctx.bridge.getTask(requiredStringArg(args, "taskId")),
+      tags: ["tasks", "builtin"]
+    }),
+    defineAction({
+      name: "list_tasks",
+      description: "List tasks, optionally filtered by context or status. Returns task summaries with IDs, states, and timestamps.",
+      parameters: {
+        type: "object",
+        properties: {
+          contextId: {
+            type: "string",
+            description: "Filter by conversation context ID"
+          },
+          state: {
+            type: "string",
+            description: "Filter by task state (submitted, working, completed, failed, canceled)"
+          },
+          limit: {
+            type: "number",
+            description: "Max number of tasks to return (default: 50)"
+          }
+        }
+      },
+      execute: (args, ctx) => ctx.bridge.listTasks({
+        ...optionalStringArg(args, "contextId") ? { contextId: optionalStringArg(args, "contextId") } : {},
+        ...optionalStringArg(args, "state") ? { state: optionalStringArg(args, "state") } : {},
+        ...optionalNumberArg(args, "limit") ? { limit: optionalNumberArg(args, "limit") } : {}
+      }),
+      tags: ["tasks", "builtin"]
+    })
+  ];
+}
+export {
+  createTaskActions
+};
+//# sourceMappingURL=tasks.js.map

package/dist/actions/builtin/tasks.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/actions/builtin/tasks.ts"],
+  "sourcesContent": ["import { defineAction } from '../define.js';\nimport type { ActionDefinition } from '../types.js';\nimport {\n  optionalNumberArg,\n  optionalStringArg,\n  requiredStringArg,\n} from './args.js';\n\nexport function createTaskActions(): ActionDefinition[] {\n  return [\n    defineAction({\n      name: 'get_task',\n      description:\n        'Retrieve details of a specific task by ID, including status, history, and artifacts.',\n      parameters: {\n        type: 'object',\n        properties: {\n          taskId: { type: 'string', description: 'Task ID to retrieve' },\n        },\n        required: ['taskId'],\n      },\n      execute: (args, ctx) =>\n        ctx.bridge.getTask(requiredStringArg(args, 'taskId')),\n      tags: ['tasks', 'builtin'],\n    }),\n\n    defineAction({\n      name: 'list_tasks',\n      description:\n        'List tasks, optionally filtered by context or status. Returns task summaries with IDs, states, and timestamps.',\n      parameters: {\n        type: 'object',\n        properties: {\n          contextId: {\n            type: 'string',\n            description: 'Filter by conversation context ID',\n          },\n          state: {\n            type: 'string',\n            description:\n              'Filter by task state (submitted, working, completed, failed, canceled)',\n          },\n          limit: {\n            type: 'number',\n            description: 'Max number of tasks to return (default: 50)',\n          },\n        },\n      },\n      execute: (args, ctx) =>\n        ctx.bridge.listTasks({\n          ...(optionalStringArg(args, 'contextId')\n            ? { contextId: optionalStringArg(args, 'contextId') }\n            : {}),\n          ...(optionalStringArg(args, 'state')\n            ? { state: optionalStringArg(args, 'state') }\n            : {}),\n          ...(optionalNumberArg(args, 'limit')\n            ? { limit: optionalNumberArg(args, 'limit') }\n            : {}),\n        }),\n      tags: ['tasks', 'builtin'],\n    }),\n  ];\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAE7B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEA,SAAS,oBAAwC;AACtD,SAAO;AAAA,IACL,aAAa;AAAA,MACX,MAAM;AAAA,MACN,aACE;AAAA,MACF,YAAY;AAAA,QACV,MAAM;AAAA,QACN,YAAY;AAAA,UACV,QAAQ,EAAE,MAAM,UAAU,aAAa,sBAAsB;AAAA,QAC/D;AAAA,QACA,UAAU,CAAC,QAAQ;AAAA,MACrB;AAAA,MACA,SAAS,CAAC,MAAM,QACd,IAAI,OAAO,QAAQ,kBAAkB,MAAM,QAAQ,CAAC;AAAA,MACtD,MAAM,CAAC,SAAS,SAAS;AAAA,IAC3B,CAAC;AAAA,IAED,aAAa;AAAA,MACX,MAAM;AAAA,MACN,aACE;AAAA,MACF,YAAY;AAAA,QACV,MAAM;AAAA,QACN,YAAY;AAAA,UACV,WAAW;AAAA,YACT,MAAM;AAAA,YACN,aAAa;AAAA,UACf;AAAA,UACA,OAAO;AAAA,YACL,MAAM;AAAA,YACN,aACE;AAAA,UACJ;AAAA,UACA,OAAO;AAAA,YACL,MAAM;AAAA,YACN,aAAa;AAAA,UACf;AAAA,QACF;AAAA,MACF;AAAA,MACA,SAAS,CAAC,MAAM,QACd,IAAI,OAAO,UAAU;AAAA,QACnB,GAAI,kBAAkB,MAAM,WAAW,IACnC,EAAE,WAAW,kBAAkB,MAAM,WAAW,EAAE,IAClD,CAAC;AAAA,QACL,GAAI,kBAAkB,MAAM,OAAO,IAC/B,EAAE,OAAO,kBAAkB,MAAM,OAAO,EAAE,IAC1C,CAAC;AAAA,QACL,GAAI,kBAAkB,MAAM,OAAO,IAC/B,EAAE,OAAO,kBAAkB,MAAM,OAAO,EAAE,IAC1C,CAAC;AAAA,MACP,CAAC;AAAA,MACH,MAAM,CAAC,SAAS,SAAS;AAAA,IAC3B,CAAC;AAAA,EACH;AACF;",
+  "names": []
+}

package/dist/actions/builtin/web.d.ts

@@ -0,0 +1,8 @@
+import type { ActionDefinition } from '../types.js';
+export interface WebActionsOptions {
+    readonly timeoutMs?: number;
+    readonly maxBodyBytes?: number;
+    readonly allowedHosts?: readonly string[];
+}
+export declare function createWebActions(opts?: WebActionsOptions): ActionDefinition[];
+//# sourceMappingURL=web.d.ts.map

package/dist/actions/builtin/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../../src/actions/builtin/web.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AA+FD,wBAAgB,gBAAgB,CAC9B,IAAI,GAAE,iBAAsB,GAC3B,gBAAgB,EAAE,CAmFpB"}

package/dist/actions/builtin/web.js

@@ -0,0 +1,143 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { defineAction } from "../define.js";
+function validateUrl(rawUrl, allowedHosts) {
+  if (typeof rawUrl !== "string" || rawUrl.length === 0) {
+    return { error: "Missing required parameter: url" };
+  }
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return { error: `Invalid URL: ${rawUrl}` };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return { error: "web_fetch only supports http:// and https:// URLs" };
+  }
+  if (allowedHosts && !allowedHosts.includes(url.hostname)) {
+    return { error: `Host is not allowed: ${url.hostname}` };
+  }
+  return url;
+}
+function isPrivateIpv4(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) {
+    return true;
+  }
+  const [a, b] = parts;
+  return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a >= 224;
+}
+function isPrivateIpv6(address) {
+  const normalized = address.toLowerCase();
+  if (normalized === "::" || normalized === "::1" || normalized.startsWith("fe80:") || normalized.startsWith("fc") || normalized.startsWith("fd")) {
+    return true;
+  }
+  if (normalized.startsWith("::ffff:")) {
+    const mapped = normalized.slice("::ffff:".length);
+    return isPrivateIpv4(mapped);
+  }
+  return false;
+}
+async function assertPublicHost(url) {
+  if (url.hostname === "localhost" || url.hostname.endsWith(".localhost")) {
+    throw new Error(`Blocked private host: ${url.hostname}`);
+  }
+  const family = isIP(url.hostname);
+  if (family === 4 && isPrivateIpv4(url.hostname)) {
+    throw new Error(`Blocked private IPv4 host: ${url.hostname}`);
+  }
+  if (family === 6 && isPrivateIpv6(url.hostname)) {
+    throw new Error(`Blocked private IPv6 host: ${url.hostname}`);
+  }
+  if (family !== 0) return;
+  const records = await lookup(url.hostname, { all: true, verbatim: true });
+  for (const record of records) {
+    if (record.family === 4 && isPrivateIpv4(record.address) || record.family === 6 && isPrivateIpv6(record.address)) {
+      throw new Error(
+        `Blocked private DNS resolution for ${url.hostname}: ${record.address}`
+      );
+    }
+  }
+}
+function stripHtml(input) {
+  return input.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+function createWebActions(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const maxBodyBytes = opts.maxBodyBytes ?? 2e5;
+  return [
+    defineAction({
+      name: "web_fetch",
+      description: "Fetch a public HTTP(S) URL and return readable text. Default web tool; raw HTTP/search extras are opt-in.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "HTTP(S) URL to fetch." },
+          max_length: {
+            type: "number",
+            description: "Maximum text characters to return."
+          },
+          include_html: {
+            type: "boolean",
+            description: "Return raw HTML instead of readable text."
+          }
+        },
+        required: ["url"]
+      },
+      execute: async (args) => {
+        let url = validateUrl(args["url"], opts.allowedHosts);
+        if ("error" in url) return url;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+          let response;
+          for (let redirects = 0; redirects <= 5; redirects++) {
+            await assertPublicHost(url);
+            response = await fetch(url, {
+              headers: {
+                accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8",
+                "user-agent": "OctoFlow/0.3 (+https://octoflow.dev)"
+              },
+              redirect: "manual",
+              signal: controller.signal
+            });
+            if (![301, 302, 303, 307, 308].includes(response.status)) break;
+            const location = response.headers.get("location");
+            if (!location) break;
+            const nextUrl = validateUrl(
+              new URL(location, url).toString(),
+              opts.allowedHosts
+            );
+            if ("error" in nextUrl) return nextUrl;
+            url = nextUrl;
+          }
+          if (!response) return { url: url.toString(), error: "No response" };
+          const body = await response.arrayBuffer();
+          const truncatedBytes = body.byteLength > maxBodyBytes;
+          const text = new TextDecoder().decode(body.slice(0, maxBodyBytes));
+          const maxLength = typeof args["max_length"] === "number" ? Math.max(0, args["max_length"]) : 5e4;
+          const content = args["include_html"] === true ? text : stripHtml(text);
+          return {
+            url: url.toString(),
+            status: response.status,
+            ok: response.ok,
+            contentType: response.headers.get("content-type") ?? void 0,
+            text: content.slice(0, maxLength),
+            truncated: truncatedBytes || content.length > maxLength
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return { url: url.toString(), status: 0, error: message };
+        } finally {
+          clearTimeout(timer);
+        }
+      },
+      timeout: timeoutMs,
+      tags: ["web", "http", "read", "builtin"]
+    })
+  ];
+}
+export {
+  createWebActions
+};
+//# sourceMappingURL=web.js.map

package/dist/actions/builtin/web.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/actions/builtin/web.ts"],
+  "sourcesContent": ["import { lookup } from 'node:dns/promises';\nimport { isIP } from 'node:net';\n\nimport { defineAction } from '../define.js';\nimport type { ActionDefinition } from '../types.js';\n\nexport interface WebActionsOptions {\n  readonly timeoutMs?: number;\n  readonly maxBodyBytes?: number;\n  readonly allowedHosts?: readonly string[];\n}\n\nfunction validateUrl(\n  rawUrl: unknown,\n  allowedHosts: readonly string[] | undefined\n): URL | { error: string } {\n  if (typeof rawUrl !== 'string' || rawUrl.length === 0) {\n    return { error: 'Missing required parameter: url' };\n  }\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    return { error: `Invalid URL: ${rawUrl}` };\n  }\n  if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n    return { error: 'web_fetch only supports http:// and https:// URLs' };\n  }\n  if (allowedHosts && !allowedHosts.includes(url.hostname)) {\n    return { error: `Host is not allowed: ${url.hostname}` };\n  }\n  return url;\n}\n\nfunction isPrivateIpv4(address: string): boolean {\n  const parts = address.split('.').map(Number);\n  if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) {\n    return true;\n  }\n  const [a, b] = parts as [number, number, number, number];\n  return (\n    a === 0 ||\n    a === 10 ||\n    a === 127 ||\n    (a === 169 && b === 254) ||\n    (a === 172 && b >= 16 && b <= 31) ||\n    (a === 192 && b === 168) ||\n    a >= 224\n  );\n}\n\nfunction isPrivateIpv6(address: string): boolean {\n  const normalized = address.toLowerCase();\n  if (\n    normalized === '::' ||\n    normalized === '::1' ||\n    normalized.startsWith('fe80:') ||\n    normalized.startsWith('fc') ||\n    normalized.startsWith('fd')\n  ) {\n    return true;\n  }\n  if (normalized.startsWith('::ffff:')) {\n    const mapped = normalized.slice('::ffff:'.length);\n    return isPrivateIpv4(mapped);\n  }\n  return false;\n}\n\nasync function assertPublicHost(url: URL): Promise<void> {\n  if (url.hostname === 'localhost' || url.hostname.endsWith('.localhost')) {\n    throw new Error(`Blocked private host: ${url.hostname}`);\n  }\n\n  const family = isIP(url.hostname);\n  if (family === 4 && isPrivateIpv4(url.hostname)) {\n    throw new Error(`Blocked private IPv4 host: ${url.hostname}`);\n  }\n  if (family === 6 && isPrivateIpv6(url.hostname)) {\n    throw new Error(`Blocked private IPv6 host: ${url.hostname}`);\n  }\n  if (family !== 0) return;\n\n  const records = await lookup(url.hostname, { all: true, verbatim: true });\n  for (const record of records) {\n    if (\n      (record.family === 4 && isPrivateIpv4(record.address)) ||\n      (record.family === 6 && isPrivateIpv6(record.address))\n    ) {\n      throw new Error(\n        `Blocked private DNS resolution for ${url.hostname}: ${record.address}`\n      );\n    }\n  }\n}\n\nfunction stripHtml(input: string): string {\n  return input\n    .replace(/<script\\b[^>]*>[\\s\\S]*?<\\/script>/gi, '')\n    .replace(/<style\\b[^>]*>[\\s\\S]*?<\\/style>/gi, '')\n    .replace(/<[^>]+>/g, ' ')\n    .replace(/\\s+/g, ' ')\n    .trim();\n}\n\nexport function createWebActions(\n  opts: WebActionsOptions = {}\n): ActionDefinition[] {\n  const timeoutMs = opts.timeoutMs ?? 30_000;\n  const maxBodyBytes = opts.maxBodyBytes ?? 200_000;\n\n  return [\n    defineAction({\n      name: 'web_fetch',\n      description:\n        'Fetch a public HTTP(S) URL and return readable text. Default web tool; raw HTTP/search extras are opt-in.',\n      parameters: {\n        type: 'object',\n        properties: {\n          url: { type: 'string', description: 'HTTP(S) URL to fetch.' },\n          max_length: {\n            type: 'number',\n            description: 'Maximum text characters to return.',\n          },\n          include_html: {\n            type: 'boolean',\n            description: 'Return raw HTML instead of readable text.',\n          },\n        },\n        required: ['url'],\n      },\n      execute: async (args) => {\n        let url = validateUrl(args['url'], opts.allowedHosts);\n        if ('error' in url) return url;\n\n        const controller = new AbortController();\n        const timer = setTimeout(() => controller.abort(), timeoutMs);\n        try {\n          let response: Response | undefined;\n          for (let redirects = 0; redirects <= 5; redirects++) {\n            await assertPublicHost(url);\n            response = await fetch(url, {\n              headers: {\n                accept:\n                  'text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8',\n                'user-agent': 'OctoFlow/0.3 (+https://octoflow.dev)',\n              },\n              redirect: 'manual',\n              signal: controller.signal,\n            });\n            if (![301, 302, 303, 307, 308].includes(response.status)) break;\n            const location = response.headers.get('location');\n            if (!location) break;\n            const nextUrl = validateUrl(\n              new URL(location, url).toString(),\n              opts.allowedHosts\n            );\n            if ('error' in nextUrl) return nextUrl;\n            url = nextUrl;\n          }\n          if (!response) return { url: url.toString(), error: 'No response' };\n          const body = await response.arrayBuffer();\n          const truncatedBytes = body.byteLength > maxBodyBytes;\n          const text = new TextDecoder().decode(body.slice(0, maxBodyBytes));\n          const maxLength =\n            typeof args['max_length'] === 'number'\n              ? Math.max(0, args['max_length'])\n              : 50_000;\n          const content =\n            args['include_html'] === true ? text : stripHtml(text);\n\n          return {\n            url: url.toString(),\n            status: response.status,\n            ok: response.ok,\n            contentType: response.headers.get('content-type') ?? undefined,\n            text: content.slice(0, maxLength),\n            truncated: truncatedBytes || content.length > maxLength,\n          };\n        } catch (err) {\n          const message = err instanceof Error ? err.message : String(err);\n          return { url: url.toString(), status: 0, error: message };\n        } finally {\n          clearTimeout(timer);\n        }\n      },\n      timeout: timeoutMs,\n      tags: ['web', 'http', 'read', 'builtin'],\n    }),\n  ];\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/actions/define.d.ts

@@ -0,0 +1,40 @@
+import type { BridgeMcpSchemaBudget } from '../capabilities/types.js';
+import type { ActionContext, ActionDefinition, ActionExample } from './types.js';
+export interface DefineActionOptions {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters?: Record<string, unknown>;
+    /** Function executor — the most common form. Pass `'cli'` for shell commands. */
+    readonly execute?: ((args: Record<string, unknown>, ctx: ActionContext) => Promise<unknown>) | 'cli';
+    /** CLI executor fields (used when `execute` is `'cli'`). */
+    readonly command?: string | ((args: Record<string, unknown>) => string);
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly shell?: boolean;
+    /** MCP executor. */
+    readonly source?: {
+        readonly type: 'mcp';
+        readonly server: string;
+        readonly tool: string;
+        readonly invoke: (args: Record<string, unknown>, ctx: ActionContext) => Promise<unknown>;
+        readonly timeoutMs?: number;
+        readonly schemaBudget?: BridgeMcpSchemaBudget;
+    };
+    readonly requireApproval?: boolean;
+    readonly permission?: 'allow' | 'deny' | 'ask';
+    readonly tags?: readonly string[];
+    readonly timeout?: number;
+    readonly metadata?: Record<string, unknown>;
+    /** Opt-in strict JSON-schema validation on the wire (Anthropic / OpenAI). */
+    readonly strict?: boolean;
+    /** JSON-schema for the value returned by `execute`. */
+    readonly outputSchema?: Record<string, unknown>;
+    /** Worked input examples — Anthropic-style `input_examples`. */
+    readonly inputExamples?: readonly ActionExample[];
+    /** Long-form usage notes. Not size-limited. */
+    readonly usageNotes?: string;
+    /** Richer narrative description for tool catalog surfaces. */
+    readonly longDescription?: string;
+}
+export declare function defineAction(opts: DefineActionOptions): ActionDefinition;
+//# sourceMappingURL=define.d.ts.map

package/dist/actions/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/actions/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE9C,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EACb,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,GACzE,KAAK,CAAC;IAEV,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB,oBAAoB;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,CACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,OAAO,CAAC,CAAC;QACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;KAC/C,CAAC;IAEF,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,CA8ExE"}

package/dist/actions/define.js

@@ -0,0 +1,77 @@
+function defineAction(opts) {
+  const {
+    name,
+    description,
+    parameters = {},
+    tags,
+    timeout,
+    metadata,
+    requireApproval,
+    permission
+  } = opts;
+  if (!name) throw new Error("[octoflow] defineAction: name is required");
+  if (!description) {
+    throw new Error("[octoflow] defineAction: description is required");
+  }
+  const shared = {
+    name,
+    description,
+    parameters,
+    tags,
+    timeout,
+    metadata,
+    requireApproval,
+    permission,
+    strict: opts.strict,
+    outputSchema: opts.outputSchema,
+    inputExamples: opts.inputExamples,
+    usageNotes: opts.usageNotes,
+    longDescription: opts.longDescription
+  };
+  if (opts.source) {
+    if (opts.execute) {
+      throw new Error(
+        `[octoflow] defineAction('${name}'): cannot set both 'execute' and 'source'`
+      );
+    }
+    return {
+      ...shared,
+      executor: {
+        type: "mcp",
+        server: opts.source.server,
+        tool: opts.source.tool,
+        invoke: opts.source.invoke,
+        timeoutMs: opts.source.timeoutMs,
+        schemaBudget: opts.source.schemaBudget
+      }
+    };
+  }
+  if (opts.execute === "cli") {
+    if (!opts.command) {
+      throw new Error(
+        `[octoflow] defineAction('${name}'): 'command' is required when execute is 'cli'`
+      );
+    }
+    return {
+      ...shared,
+      executor: {
+        type: "cli",
+        command: opts.command,
+        cwd: opts.cwd,
+        timeout: opts.timeout,
+        env: opts.env,
+        shell: opts.shell
+      }
+    };
+  }
+  if (typeof opts.execute === "function") {
+    return { ...shared, executor: { type: "function", fn: opts.execute } };
+  }
+  throw new Error(
+    `[octoflow] defineAction('${name}'): must provide 'execute' (function or 'cli') or 'source' (mcp)`
+  );
+}
+export {
+  defineAction
+};
+//# sourceMappingURL=define.js.map