@symerian/symi 3.0.18 → 3.0.19

package/extensions/pipeline/README.md

@@ -1,75 +0,0 @@
-# Pipeline (plugin)
-
-Adds the `pipeline` agent tool as an **optional** plugin tool.
-
-## What this is
-
-- Pipeline is a standalone workflow shell (typed JSON-first pipelines + approvals/resume).
-- This plugin integrates Pipeline with Symi _without core changes_.
-
-## Enable
-
-Because this tool can trigger side effects (via workflows), it is registered with `optional: true`.
-
-Enable it in an agent allowlist:
-
-```json
-{
-  "agents": {
-    "list": [
-      {
-        "id": "main",
-        "tools": {
-          "allow": [
-            "pipeline" // plugin id (enables all tools from this plugin)
-          ]
-        }
-      }
-    ]
-  }
-}
-```
-
-## Using `symi.invoke` (Pipeline → Symi tools)
-
-Some pipelines may include a `symi.invoke` step to call back into Symi tools/plugins (for example: `gog` for Google Workspace, `gh` for GitHub, `message.send`, etc.).
-
-For this to work, the Symi Gateway must expose the tool bridge endpoint and the target tool must be allowed by policy:
-
-- Symi provides an HTTP endpoint: `POST /tools/invoke`.
-- The request is gated by **gateway auth** (e.g. `Authorization: Bearer …` when token auth is enabled).
-- The invoked tool is gated by **tool policy** (global + per-agent + provider + group policy). If the tool is not allowed, Symi returns `404 Tool not available`.
-
-### Allowlisting recommended
-
-To avoid letting workflows call arbitrary tools, set a tight allowlist on the agent that will be used by `symi.invoke`.
-
-Example (allow only a small set of tools):
-
-```jsonc
-{
-  "agents": {
-    "list": [
-      {
-        "id": "main",
-        "tools": {
-          "allow": ["pipeline", "web_fetch", "web_search", "gog", "gh"],
-          "deny": ["gateway"],
-        },
-      },
-    ],
-  },
-}
-```
-
-Notes:
-
-- If `tools.allow` is omitted or empty, it behaves like "allow everything (except denied)". For a real allowlist, set a **non-empty** `allow`.
-- Tool names depend on which plugins you have installed/enabled.
-
-## Security
-
-- Runs the pipeline executable as a local subprocess.
-- Does not manage OAuth/tokens.
-- Uses timeouts, stdout caps, and strict JSON envelope parsing.
-- Ensure the pipeline runtime is available on `PATH` for the gateway process.

package/extensions/pipeline/SKILL.md

@@ -1,97 +0,0 @@
-# Pipeline
-
-Pipeline executes multi-step workflows with approval checkpoints. Use it when:
-
-- User wants a repeatable automation (triage, monitor, sync)
-- Actions need human approval before executing (send, post, delete)
-- Multiple tool calls should run as one deterministic operation
-
-## When to use Pipeline
-
-| User intent                                            | Use Pipeline?                                 |
-| ------------------------------------------------------ | --------------------------------------------- |
-| "Triage my email"                                      | Yes — multi-step, may send replies            |
-| "Send a message"                                       | No — single action, use message tool directly |
-| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval        |
-| "What's the weather?"                                  | No — simple query                             |
-| "Monitor this PR and notify me of changes"             | Yes — stateful, recurring                     |
-
-## Basic usage
-
-### Run a pipeline
-
-```json
-{
-  "action": "run",
-  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
-}
-```
-
-Returns structured result:
-
-```json
-{
-  "protocolVersion": 1,
-  "ok": true,
-  "status": "ok",
-  "output": [{ "summary": {...}, "items": [...] }],
-  "requiresApproval": null
-}
-```
-
-### Handle approval
-
-If the workflow needs approval:
-
-```json
-{
-  "status": "needs_approval",
-  "output": [],
-  "requiresApproval": {
-    "prompt": "Send 3 draft replies?",
-    "items": [...],
-    "resumeToken": "..."
-  }
-}
-```
-
-Present the prompt to the user. If they approve:
-
-```json
-{
-  "action": "resume",
-  "token": "<resumeToken>",
-  "approve": true
-}
-```
-
-## Example workflows
-
-### Email triage
-
-```
-gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
-```
-
-Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
-
-### Email triage with approval gate
-
-```
-gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
-```
-
-Same as above, but halts for approval before returning.
-
-## Key behaviors
-
-- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
-- **Approval gates**: `approve` command halts execution, returns token
-- **Resumable**: Use `resume` action with token to continue
-- **Structured output**: Always returns JSON envelope with `protocolVersion`
-
-## Don't use Pipeline for
-
-- Simple single-action requests (just use the tool directly)
-- Queries that need LLM interpretation mid-flow
-- One-off tasks that won't be repeated

package/extensions/pipeline/index.ts

@@ -1,18 +0,0 @@
-import type {
-  AnyAgentTool,
-  SymiPluginApi,
-  SymiPluginToolFactory,
-} from "../../src/plugins/types.js";
-import { createPipelineTool } from "./src/pipeline-tool.js";
-
-export default function register(api: SymiPluginApi) {
-  api.registerTool(
-    ((ctx) => {
-      if (ctx.sandboxed) {
-        return null;
-      }
-      return createPipelineTool(api) as AnyAgentTool;
-    }) as SymiPluginToolFactory,
-    { optional: true },
-  );
-}

package/extensions/pipeline/package.json

@@ -1,11 +0,0 @@
-{
-  "name": "@symi/pipeline",
-  "version": "3.0.9",
-  "description": "Pipeline workflow tool plugin (typed pipelines + resumable approvals)",
-  "type": "module",
-  "symi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  }
-}

package/extensions/pipeline/src/pipeline-tool.test.ts

@@ -1,345 +0,0 @@
-import { EventEmitter } from "node:events";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { PassThrough } from "node:stream";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import type { SymiPluginApi, SymiPluginToolContext } from "../../../src/plugins/types.js";
-
-const spawnState = vi.hoisted(() => ({
-  queue: [] as Array<{ stdout: string; stderr?: string; exitCode?: number }>,
-  spawn: vi.fn(),
-}));
-
-vi.mock("node:child_process", () => ({
-  spawn: (...args: unknown[]) => spawnState.spawn(...args),
-}));
-
-let createPipelineTool: typeof import("./pipeline-tool.js").createPipelineTool;
-
-function fakeApi(overrides: Partial<SymiPluginApi> = {}): SymiPluginApi {
-  return {
-    id: "pipeline",
-    name: "pipeline",
-    source: "test",
-    config: {},
-    pluginConfig: {},
-    // oxlint-disable-next-line typescript/no-explicit-any
-    runtime: { version: "test" } as any,
-    logger: { info() {}, warn() {}, error() {}, debug() {} },
-    registerTool() {},
-    registerHttpHandler() {},
-    registerChannel() {},
-    registerGatewayMethod() {},
-    registerCli() {},
-    registerService() {},
-    registerProvider() {},
-    registerHook() {},
-    registerHttpRoute() {},
-    registerCommand() {},
-    on() {},
-    resolvePath: (p) => p,
-    ...overrides,
-  };
-}
-
-function fakeCtx(overrides: Partial<SymiPluginToolContext> = {}): SymiPluginToolContext {
-  return {
-    config: {},
-    workspaceDir: "/tmp",
-    agentDir: "/tmp",
-    agentId: "main",
-    sessionKey: "main",
-    messageChannel: undefined,
-    agentAccountId: undefined,
-    sandboxed: false,
-    ...overrides,
-  };
-}
-
-function setProcessPlatform(platform: NodeJS.Platform) {
-  Object.defineProperty(process, "platform", {
-    value: platform,
-    configurable: true,
-  });
-}
-
-describe("pipeline plugin tool", () => {
-  let tempDir = "";
-  const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
-  const originalPath = process.env.PATH;
-  const originalPathAlt = process.env.Path;
-  const originalPathExt = process.env.PATHEXT;
-  const originalPathExtAlt = process.env.Pathext;
-
-  beforeAll(async () => {
-    ({ createPipelineTool } = await import("./pipeline-tool.js"));
-
-    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "symi-pipeline-plugin-"));
-  });
-
-  afterEach(() => {
-    if (originalPlatform) {
-      Object.defineProperty(process, "platform", originalPlatform);
-    }
-    if (originalPath === undefined) {
-      delete process.env.PATH;
-    } else {
-      process.env.PATH = originalPath;
-    }
-    if (originalPathAlt === undefined) {
-      delete process.env.Path;
-    } else {
-      process.env.Path = originalPathAlt;
-    }
-    if (originalPathExt === undefined) {
-      delete process.env.PATHEXT;
-    } else {
-      process.env.PATHEXT = originalPathExt;
-    }
-    if (originalPathExtAlt === undefined) {
-      delete process.env.Pathext;
-    } else {
-      process.env.Pathext = originalPathExtAlt;
-    }
-  });
-
-  afterAll(async () => {
-    if (!tempDir) {
-      return;
-    }
-    if (process.platform === "win32") {
-      await fs.rm(tempDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
-    } else {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  beforeEach(() => {
-    spawnState.queue.length = 0;
-    spawnState.spawn.mockReset();
-    spawnState.spawn.mockImplementation(() => {
-      const next = spawnState.queue.shift() ?? { stdout: "" };
-      const stdout = new PassThrough();
-      const stderr = new PassThrough();
-      const child = new EventEmitter() as EventEmitter & {
-        stdout: PassThrough;
-        stderr: PassThrough;
-        kill: (signal?: string) => boolean;
-      };
-      child.stdout = stdout;
-      child.stderr = stderr;
-      child.kill = () => true;
-
-      setImmediate(() => {
-        if (next.stderr) {
-          stderr.end(next.stderr);
-        } else {
-          stderr.end();
-        }
-        stdout.end(next.stdout);
-        child.emit("exit", next.exitCode ?? 0);
-      });
-
-      return child;
-    });
-  });
-
-  const queueSuccessfulEnvelope = (hello = "world") => {
-    spawnState.queue.push({
-      stdout: JSON.stringify({
-        ok: true,
-        status: "ok",
-        output: [{ hello }],
-        requiresApproval: null,
-      }),
-    });
-  };
-
-  const createWindowsShimFixture = async (params: {
-    shimPath: string;
-    scriptPath: string;
-    scriptToken: string;
-  }) => {
-    await fs.mkdir(path.dirname(params.scriptPath), { recursive: true });
-    await fs.mkdir(path.dirname(params.shimPath), { recursive: true });
-    await fs.writeFile(params.scriptPath, "module.exports = {};\n", "utf8");
-    await fs.writeFile(params.shimPath, `@echo off\r\n"${params.scriptToken}" %*\r\n`, "utf8");
-  };
-
-  it("runs pipeline and returns parsed envelope in details", async () => {
-    spawnState.queue.push({
-      stdout: JSON.stringify({
-        ok: true,
-        status: "ok",
-        output: [{ hello: "world" }],
-        requiresApproval: null,
-      }),
-    });
-
-    const tool = createPipelineTool(fakeApi());
-    const res = await tool.execute("call1", {
-      action: "run",
-      pipeline: "noop",
-      timeoutMs: 1000,
-    });
-
-    expect(spawnState.spawn).toHaveBeenCalled();
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
-  });
-
-  it("tolerates noisy stdout before the JSON envelope", async () => {
-    const payload = { ok: true, status: "ok", output: [], requiresApproval: null };
-    spawnState.queue.push({
-      stdout: `noise before json\n${JSON.stringify(payload)}`,
-    });
-
-    const tool = createPipelineTool(fakeApi());
-    const res = await tool.execute("call-noisy", {
-      action: "run",
-      pipeline: "noop",
-      timeoutMs: 1000,
-    });
-
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
-  });
-
-  it("requires action", async () => {
-    const tool = createPipelineTool(fakeApi());
-    await expect(tool.execute("call-action-missing", {})).rejects.toThrow(/action required/);
-  });
-
-  it("requires pipeline for run action", async () => {
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call-pipeline-missing", {
-        action: "run",
-      }),
-    ).rejects.toThrow(/pipeline required/);
-  });
-
-  it("requires token and approve for resume action", async () => {
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call-resume-token-missing", {
-        action: "resume",
-        approve: true,
-      }),
-    ).rejects.toThrow(/token required/);
-    await expect(
-      tool.execute("call-resume-approve-missing", {
-        action: "resume",
-        token: "resume-token",
-      }),
-    ).rejects.toThrow(/approve required/);
-  });
-
-  it("rejects unknown action", async () => {
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call-action-unknown", {
-        action: "explode",
-      }),
-    ).rejects.toThrow(/Unknown action/);
-  });
-
-  it("rejects absolute cwd", async () => {
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call2c", {
-        action: "run",
-        pipeline: "noop",
-        cwd: "/tmp",
-      }),
-    ).rejects.toThrow(/cwd must be a relative path/);
-  });
-
-  it("rejects cwd that escapes the gateway working directory", async () => {
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call2d", {
-        action: "run",
-        pipeline: "noop",
-        cwd: "../../etc",
-      }),
-    ).rejects.toThrow(/must stay within/);
-  });
-
-  it("rejects invalid JSON from pipeline", async () => {
-    spawnState.queue.push({ stdout: "nope" });
-
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call3", {
-        action: "run",
-        pipeline: "noop",
-      }),
-    ).rejects.toThrow(/invalid JSON/);
-  });
-
-  it("runs Windows cmd shims through Node without enabling shell", async () => {
-    setProcessPlatform("win32");
-    const shimScriptPath = path.join(tempDir, "shim-dist", "lobster-cli.cjs");
-    const shimPath = path.join(tempDir, "shim-bin", "lobster.cmd");
-    await createWindowsShimFixture({
-      shimPath,
-      scriptPath: shimScriptPath,
-      scriptToken: "%dp0%\\..\\shim-dist\\lobster-cli.cjs",
-    });
-    process.env.PATHEXT = ".CMD;.EXE";
-    process.env.PATH = `${path.dirname(shimPath)};${process.env.PATH ?? ""}`;
-    queueSuccessfulEnvelope();
-
-    const tool = createPipelineTool(fakeApi());
-    await tool.execute("call-win-shim", {
-      action: "run",
-      pipeline: "noop",
-    });
-
-    const [command, argv, options] = spawnState.spawn.mock.calls[0] ?? [];
-    expect(command).toBe(process.execPath);
-    expect(argv).toEqual([shimScriptPath, "run", "--mode", "tool", "noop"]);
-    expect(options).toMatchObject({ windowsHide: true });
-    expect(options).not.toHaveProperty("shell");
-  });
-
-  it("does not retry a failed Windows spawn with shell fallback", async () => {
-    setProcessPlatform("win32");
-    spawnState.spawn.mockReset();
-    spawnState.spawn.mockImplementationOnce(() => {
-      const child = new EventEmitter() as EventEmitter & {
-        stdout: PassThrough;
-        stderr: PassThrough;
-        kill: (signal?: string) => boolean;
-      };
-      child.stdout = new PassThrough();
-      child.stderr = new PassThrough();
-      child.kill = () => true;
-      const err = Object.assign(new Error("spawn failed"), { code: "ENOENT" });
-      setImmediate(() => child.emit("error", err));
-      return child;
-    });
-
-    const tool = createPipelineTool(fakeApi());
-    await expect(
-      tool.execute("call-win-no-retry", {
-        action: "run",
-        pipeline: "noop",
-      }),
-    ).rejects.toThrow(/spawn failed/);
-    expect(spawnState.spawn).toHaveBeenCalledTimes(1);
-  });
-
-  it("can be gated off in sandboxed contexts", async () => {
-    const api = fakeApi();
-    const factoryTool = (ctx: SymiPluginToolContext) => {
-      if (ctx.sandboxed) {
-        return null;
-      }
-      return createPipelineTool(api);
-    };
-
-    expect(factoryTool(fakeCtx({ sandboxed: true }))).toBeNull();
-    expect(factoryTool(fakeCtx({ sandboxed: false }))?.name).toBe("pipeline");
-  });
-});