@pattern-js/mod-buddy 0.4.0-main.c8eb671

package/dist/turn.js

@@ -0,0 +1,276 @@
+/**
+ * @pattern-js/mod-buddy — the turn pipeline (Buddy's backend half).
+ *
+ * POST /buddy/api/turn → buddy.turn.begin (thread + instructions + model) →
+ * agents.agent + the ten pattern_* tools → agents.run → SSE out, while
+ * buddy.turn.save persists the updated history back to the thread. The
+ * pipeline is an ordinary editable workflow — Buddy is built from Pattern
+ * workflows, all the way down.
+ *
+ * The dock reads tool calls (incl. proposed docs) straight from the SSE
+ * turn events: `tool.activity` carries the tool's name and args.
+ */
+import { fromBody, fromParams, fromQuery, httpEndpoint, value, z } from "@pattern-js/core";
+import { AGENTS_SERVICE } from "@pattern-js/mod-agents";
+import { BUDDY_INSTRUCTIONS, contextBlock } from "./prompts.js";
+import { clearThread, hasThreadStore, loadThread, saveThread } from "./threads.js";
+import { CONTROL_PLANE_TOOLS } from "./tools.js";
+const AI_CONFIG_SERVICE = "aiConfig";
+/** The language alias Buddy runs on: "buddy" when configured, else the agent default. */
+function buddyModelRef(services) {
+    const config = services[AI_CONFIG_SERVICE];
+    if (!config || typeof config.aliases !== "function")
+        return undefined;
+    const buddy = config.aliases().find((a) => a.name === "buddy" && (a.modality ?? "language") === "language");
+    return buddy ? { alias: "buddy" } : undefined;
+}
+const GLOBAL_SLUG = "~app";
+/* ── ops ─────────────────────────────────────────────────────────────────── */
+const turnBegin = {
+    type: "buddy.turn.begin",
+    title: "buddy.turn.begin",
+    description: "Start a Buddy turn: load the caller's thread for this workflow, assemble instructions (system prompt + canvas/run " +
+        "context), resolve the model (alias \"buddy\" → agent default). Outputs feed agents.agent/agents.run.",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: {
+        message: value(z.string()),
+        slug: value(z.string().optional()),
+        doc: value(z.record(z.string(), z.unknown()).optional()),
+        runId: value(z.string().optional()),
+        turnId: value(z.string().optional()),
+    },
+    outputs: {
+        input: value(z.string()),
+        history: value(),
+        instructions: value(z.string()),
+        model: value(),
+        turnId: value(z.string()),
+        slug: value(z.string()),
+    },
+    execute: async (ctx) => {
+        const [message, slug, doc, runId, turnId] = await Promise.all([
+            ctx.input.value("message"),
+            ctx.input.has("slug") ? ctx.input.value("slug") : undefined,
+            ctx.input.has("doc") ? ctx.input.value("doc") : undefined,
+            ctx.input.has("runId") ? ctx.input.value("runId") : undefined,
+            ctx.input.has("turnId") ? ctx.input.value("turnId") : undefined,
+        ]);
+        if (!message?.trim())
+            throw new Error("buddy: an empty message is not a turn");
+        const threadSlug = slug?.trim() || GLOBAL_SLUG;
+        return {
+            input: message,
+            history: await loadThread(ctx, threadSlug),
+            instructions: BUDDY_INSTRUCTIONS + contextBlock({ slug: slug ?? undefined, doc, runId: runId ?? undefined }),
+            model: buddyModelRef(ctx.services),
+            turnId: turnId?.trim() || crypto.randomUUID(),
+            slug: threadSlug,
+        };
+    },
+};
+const turnSave = {
+    type: "buddy.turn.save",
+    title: "buddy.turn.save",
+    description: "Persist a finished turn: agents.run's updated history replaces the thread's messages (CAS-retried). " +
+        "Without mod-store this is a graceful no-op — Buddy just stays stateless.",
+    reusable: false,
+    inputs: { history: value(), slug: value(z.string()) },
+    outputs: { saved: value(z.boolean()) },
+    execute: async (ctx) => {
+        const [history, slug] = await Promise.all([ctx.input.value("history"), ctx.input.value("slug")]);
+        if (!Array.isArray(history))
+            return { saved: false };
+        return { saved: await saveThread(ctx, slug, history) };
+    },
+};
+const turnAbort = {
+    type: "buddy.turn.abort",
+    title: "buddy.turn.abort",
+    description: "Stop an in-flight Buddy turn by turnId (the dock's Stop button). Idempotent.",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: { turnId: value(z.string()) },
+    outputs: { result: value() },
+    execute: async (ctx) => {
+        const turnId = await ctx.input.value("turnId");
+        const agents = ctx.services[AGENTS_SERVICE];
+        const aborted = agents?.abortTurn(turnId) ?? false;
+        return { result: { ok: true, aborted } };
+    },
+};
+const threadGet = {
+    type: "buddy.thread.get",
+    title: "buddy.thread.get",
+    description: "The caller's Buddy thread for a workflow slug: { messages } (empty without mod-store).",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: { slug: value(z.string().optional()) },
+    outputs: { thread: value() },
+    execute: async (ctx) => {
+        const slug = ctx.input.has("slug") ? await ctx.input.value("slug") : undefined;
+        const messages = await loadThread(ctx, slug?.trim() || GLOBAL_SLUG);
+        return { thread: { slug: slug?.trim() || GLOBAL_SLUG, messages, persistent: hasThreadStore(ctx.services) } };
+    },
+};
+const threadClear = {
+    type: "buddy.thread.clear",
+    title: "buddy.thread.clear",
+    description: "Forget the caller's Buddy thread for a workflow slug (the dock's New conversation).",
+    reusable: false,
+    sensitivity: "privileged",
+    inputs: { slug: value(z.string().optional()) },
+    outputs: { result: value() },
+    execute: async (ctx) => {
+        const slug = ctx.input.has("slug") ? await ctx.input.value("slug") : undefined;
+        return { result: { ok: true, cleared: await clearThread(ctx, slug?.trim() || GLOBAL_SLUG) } };
+    },
+};
+/** The dock's boot probe: what Buddy can do in THIS app. */
+export function statusOp(knowledge) {
+    return {
+        type: "buddy.status",
+        title: "buddy.status",
+        description: "Buddy's capabilities in this app: tool count, model alias in use, semantic-vs-lexical knowledge, thread persistence.",
+        reusable: false,
+        sensitivity: "privileged",
+        inputs: {},
+        outputs: { status: value() },
+        execute: async (ctx) => ({
+            status: {
+                ok: true,
+                tools: CONTROL_PLANE_TOOLS.length,
+                model: buddyModelRef(ctx.services)?.alias ?? "default",
+                knowledge: knowledge().isSemantic() ? "semantic" : "lexical",
+                threads: hasThreadStore(ctx.services),
+            },
+        }),
+    };
+}
+export function turnOps(knowledge) {
+    return [turnBegin, turnSave, turnAbort, threadGet, threadClear, statusOp(knowledge)];
+}
+/* ── the pipeline + routes ───────────────────────────────────────────────── */
+const admin = { scopes: ["admin"] };
+/** POST /buddy/api/turn → SSE turn events (the dock's one streaming call). */
+export function turnPipelineWorkflow() {
+    return {
+        id: "buddy.turn",
+        name: "Buddy · turn pipeline",
+        description: "A Buddy turn: message + editor context in → thread + instructions assembled → the agent runs with the ten " +
+            "pattern_* control-plane tools → turn events stream out (SSE) while the thread persists. Edit me to reshape " +
+            "Buddy — it is a workflow like any other.",
+        source: "code",
+        nodes: [
+            {
+                id: "in",
+                op: "boundary.http.request",
+                config: { method: "POST", path: "/buddy/api/turn", requireAuth: admin },
+                ui: { x: 40, y: 200, pair: "ok" },
+            },
+            {
+                id: "ex_body",
+                op: "core.object.extract",
+                config: { keys: ["message", "slug", "doc", "runId", "turnId"] },
+                ui: { x: 280, y: 200 },
+            },
+            {
+                id: "begin",
+                op: "buddy.turn.begin",
+                comment: "Thread + system prompt + canvas/run context + model resolution.",
+                ui: { x: 540, y: 200 },
+            },
+            {
+                id: "tools",
+                op: "agents.tools.workflows",
+                config: { tools: CONTROL_PLANE_TOOLS },
+                comment: "The ten restricted pattern_* tools, by explicit name.",
+                ui: { x: 800, y: 40 },
+            },
+            {
+                id: "agent",
+                op: "agents.agent",
+                config: { name: "Buddy", instructions: "(overridden per turn by buddy.turn.begin)" },
+                ui: { x: 1060, y: 120 },
+            },
+            {
+                id: "run",
+                op: "agents.run",
+                config: { maxTurns: 16 },
+                comment: "Streams turn events; tool calls are linked sub-runs.",
+                ui: { x: 1320, y: 200 },
+            },
+            {
+                id: "save",
+                op: "buddy.turn.save",
+                comment: "The updated history replaces the thread (CAS).",
+                ui: { x: 1580, y: 60 },
+            },
+            { id: "ok", op: "boundary.http.response", config: { mode: "sse" }, ui: { x: 1580, y: 280, pair: "in" } },
+        ],
+        edges: [
+            { from: { node: "in", port: "body" }, to: { node: "ex_body", port: "object" } },
+            { from: { node: "ex_body", port: "message" }, to: { node: "begin", port: "message" } },
+            { from: { node: "ex_body", port: "slug" }, to: { node: "begin", port: "slug" } },
+            { from: { node: "ex_body", port: "doc" }, to: { node: "begin", port: "doc" } },
+            { from: { node: "ex_body", port: "runId" }, to: { node: "begin", port: "runId" } },
+            { from: { node: "ex_body", port: "turnId" }, to: { node: "begin", port: "turnId" } },
+            // Control-thread the collector + the SSE gate onto the begin path (an
+            // out-gate with only a stream input would otherwise capture instantly).
+            { from: { node: "begin", port: "out" }, to: { node: "tools", port: "in" } },
+            { from: { node: "begin", port: "out" }, to: { node: "ok", port: "in" } },
+            { from: { node: "tools", port: "toolset" }, to: { node: "agent", port: "tools" } },
+            { from: { node: "begin", port: "instructions" }, to: { node: "agent", port: "instructions" } },
+            { from: { node: "begin", port: "model" }, to: { node: "agent", port: "model" } },
+            { from: { node: "agent", port: "agent" }, to: { node: "run", port: "agent" } },
+            { from: { node: "begin", port: "input" }, to: { node: "run", port: "input" } },
+            { from: { node: "begin", port: "history" }, to: { node: "run", port: "history" } },
+            { from: { node: "begin", port: "turnId" }, to: { node: "run", port: "turnId" } },
+            { from: { node: "run", port: "events" }, to: { node: "ok", port: "stream" } },
+            { from: { node: "run", port: "history" }, to: { node: "save", port: "history" } },
+            { from: { node: "begin", port: "slug" }, to: { node: "save", port: "slug" } },
+        ],
+    };
+}
+/** The dock's plumbing routes (thread load/clear, stop, status). */
+export function buddyRoutes() {
+    return [
+        httpEndpoint({
+            id: "buddy.route.thread.get",
+            name: "Buddy · GET /buddy/api/thread",
+            method: "GET",
+            path: "/buddy/api/thread",
+            op: "buddy.thread.get",
+            io: { in: { slug: fromQuery() }, out: "thread" },
+            auth: admin,
+        }),
+        httpEndpoint({
+            id: "buddy.route.thread.clear",
+            name: "Buddy · POST /buddy/api/thread/clear",
+            method: "POST",
+            path: "/buddy/api/thread/clear",
+            op: "buddy.thread.clear",
+            io: { in: { slug: fromBody() }, out: "result" },
+            auth: admin,
+        }),
+        httpEndpoint({
+            id: "buddy.route.turn.abort",
+            name: "Buddy · POST /buddy/api/turn/:turnId/abort",
+            method: "POST",
+            path: "/buddy/api/turn/:turnId/abort",
+            op: "buddy.turn.abort",
+            io: { in: { turnId: fromParams() }, out: "result" },
+            auth: admin,
+        }),
+        httpEndpoint({
+            id: "buddy.route.status",
+            name: "Buddy · GET /buddy/api/status",
+            method: "GET",
+            path: "/buddy/api/status",
+            op: "buddy.status",
+            io: { out: "status" },
+            auth: admin,
+        }),
+    ];
+}
+//# sourceMappingURL=turn.js.map

package/dist/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../src/turn.ts"],"names":[],"mappings":"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"}

package/docs/index.md

@@ -0,0 +1,76 @@
+# Buddy
+
+`@pattern-js/mod-buddy` puts an assistant **inside the editor**: describe what
+you want, and Buddy drafts the workflow — grounding itself in this app's
+handbook and op catalog, repairing its own mistakes against the validator,
+and applying proposals to your open canvas as ordinary, undoable edits. You
+keep the Save and Deploy buttons. And because Buddy's own pipeline is a
+Pattern workflow, you can open it on the canvas and reshape it.
+
+```jsonc
+{
+  "mods": [
+    "@pattern-js/mod-ai", "@pattern-js/mod-agents", "@pattern-js/mod-docs",
+    "@pattern-js/mod-admin", "@pattern-js/mod-identity",
+    "@pattern-js/mod-buddy"
+  ]
+}
+```
+
+`@pattern-js/mod-docs` is a **hard requirement**, not a nicety: the
+`pattern_list_ops` / `pattern_get_op` / `pattern_search_docs` tools wire its
+`docs.*` ops, and the knowledge engine retrieves over its handbook. Load
+order in `mods` doesn't matter — seeded workflows register once every mod's
+ops are in.
+
+Optional but recommended: `@pattern-js/mod-store` (threads survive reloads)
+and `@pattern-js/mod-vectors` (semantic knowledge — see below).
+
+## The control-plane tools
+
+Buddy's hands are ten **restricted** `boundary.tool` workflows — the
+`pattern_*` control plane:
+
+| Tool | What it does | Scope its ops demand |
+| --- | --- | --- |
+| `pattern_list_ops` / `pattern_get_op` | the op catalog, schemas + prose | `workflows:read` |
+| `pattern_search_docs` | handbook + catalog retrieval | `workflows:read` |
+| `pattern_get_workflow` | meta, versions, live/latest docs | `workflows:read` |
+| `pattern_validate_workflow` | located errors, nothing saved | `workflows:read` |
+| `pattern_propose_workflow` | validate + surface an Apply card | `workflows:read` |
+| `pattern_save_workflow_draft` | mint an immutable draft version | `workflows:write` |
+| `pattern_deploy_workflow` | activate a version (needs approval) | `deploy` |
+| `pattern_list_runs` / `pattern_get_run` | traces, spans, masked I/O | `runs:read` |
+
+`restricted: true` keeps them out of every `["*"]` toolset and MCP wildcard —
+they are offered only by explicit name, and every call is a traced sub-run on
+the Runs page.
+
+## The same tools, outside: the Pattern MCP server
+
+`POST /mcp/pattern` exposes exactly these ten tools to external MCP clients
+(Claude Code, Cursor, …), gated by **API tokens** (admin → Access → API
+tokens). A token's scopes decide what succeeds: `workflows:read` +
+`workflows:write` makes an authoring token that can draft but never ship;
+`deploy` is its own decision. For local dev, `pattern mcp` serves the same
+tools over stdio with no token — your shell already owns the box.
+
+## Knowledge: lexical first, semantic when present
+
+`buddy.knowledge.search` answers from the live handbook and op catalog. The
+baseline is lexical — genuinely strong on structured docs and exact op names.
+When `@pattern-js/mod-vectors` **and an embedding alias** are installed, a
+boot indexer chunks the handbook into the `buddy.docs` collection
+(content-hashed — upgrades re-embed only the diff) and the same op silently
+upgrades to hybrid semantic retrieval. Name an embedding alias `buddy` to
+pin which model indexes; otherwise the first embedding alias wins.
+
+## Threads, model, and the pipeline
+
+- Conversations persist per (workflow, user) in mod-store's `buddy.threads`
+  — reload the editor and the conversation is still there.
+- Buddy runs on the `buddy` **language alias** when you define one (Settings →
+  AI Providers), else the app's default alias.
+- The whole turn is the `buddy.turn` workflow: request → `buddy.turn.begin`
+  (thread + context + model) → agent + tools → SSE out, history saved back.
+  Fork it, add a guardrail, swap the toolset — it's yours.

package/docs/ops/buddy.knowledge.search.md

@@ -0,0 +1,13 @@
+Buddy's retrieval op: search the live handbook (every mod's docs chapter) and
+the op catalog in one query. Returns `{ results: [{ title, path, snippet,
+score }] }` — `path` is `guide/<chapter>/<file>` for handbook pages and
+`op/<type>` for catalog hits.
+
+Two engines, one shape: the baseline is lexical (token overlap over titles,
+headings, op types and descriptions — genuinely strong on this corpus of
+structured docs and exact op names). When `@pattern-js/mod-vectors` and an
+embedding alias (`buddy`, falling back to `default`) are installed, the same
+op silently upgrades to semantic retrieval. Nothing downstream changes.
+
+This is the body of the `pattern_search_docs` tool; wire it directly anywhere
+you want docs-grounded answers.

package/docs/ops/buddy.status.md

@@ -0,0 +1,6 @@
+Buddy's capability probe — what the dock reads on mount: `{ ok, tools,
+model, knowledge, threads }`. `model` is the alias Buddy runs on (`buddy`
+when defined, else `default`), `knowledge` reports `semantic` once the boot
+indexer has the handbook in mod-vectors (else `lexical`), and `threads` says
+whether conversations persist (mod-store present). Privileged: gate the
+trigger with the `admin` scope.

package/docs/ops/buddy.thread.clear.md

@@ -0,0 +1,4 @@
+Forget the caller's Buddy thread for a workflow slug — the dock's "New
+conversation". Deletes the persisted messages (no-op without mod-store) and
+answers `{ ok, cleared }`. Privileged: gate the trigger with the `admin`
+scope.

package/docs/ops/buddy.thread.get.md

@@ -0,0 +1,5 @@
+The caller's Buddy thread for a workflow slug: `{ slug, messages,
+persistent }` — the dock loads this on mount so conversations survive
+reloads. `persistent: false` means mod-store is absent and threads are
+per-session only. Threads are scoped per (workflow, user); no slug means the
+app-wide thread. Privileged: gate the trigger with the `admin` scope.

package/docs/ops/buddy.turn.abort.md

@@ -0,0 +1,6 @@
+Stop an in-flight Buddy turn by its `turnId` (the dock's Stop button). A
+streaming agent turn settles for the engine as soon as its out-gates capture,
+so run-cancel can't reach it — this goes through the agents service's
+per-turn AbortController instead. Idempotent: aborting a finished or unknown
+turn answers `{ ok: true, aborted: false }`. Privileged: gate the trigger
+with the `admin` scope.

package/docs/ops/buddy.turn.begin.md

@@ -0,0 +1,7 @@
+The head of the `buddy.turn` pipeline: takes the dock's `{ message, slug?,
+doc?, runId?, turnId? }`, loads the caller's thread for that workflow (empty
+without mod-store), assembles the instructions (Buddy's system prompt + the
+open canvas document + the run under debug), and resolves the model — the
+`buddy` language alias when you've defined one, else the agent default.
+Outputs wire straight into `agents.agent`/`agents.run`. Privileged: gate the
+trigger with the `admin` scope.

package/docs/ops/buddy.turn.save.md

@@ -0,0 +1,4 @@
+The tail of the `buddy.turn` pipeline: waits for `agents.run`'s updated
+`history` and replaces the thread's messages with it (compare-and-swap,
+retried). Without mod-store it is a graceful no-op — Buddy just stays
+stateless. Wire `history` from agents.run and `slug` from buddy.turn.begin.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pattern-js/mod-buddy",
+  "version": "0.4.0-main.c8eb671",
+  "description": "Buddy — the in-admin workflow assistant for Pattern. A chat dock in the editor that drafts workflows, self-repairs against the validator, debugs failed runs from traces, and applies proposals to your open canvas. Its control-plane toolset (the pattern_* tools) doubles as the Pattern MCP server surface.",
+  "keywords": [
+    "pattern",
+    "mod",
+    "buddy",
+    "assistant",
+    "agent",
+    "mcp",
+    "control-plane"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@pattern-js/core": "0.4.0-main.c8eb671",
+    "@pattern-js/mod-ai": "0.4.0-main.c8eb671",
+    "@pattern-js/mod-agents": "0.4.0-main.c8eb671",
+    "@pattern-js/runtime-node": "0.4.0-main.c8eb671",
+    "@pattern-js/mod-docs": "0.4.0-main.c8eb671"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "@pattern-js/mod-admin": "0.4.0-main.c8eb671",
+    "@pattern-js/mod-identity": "0.4.0-main.c8eb671"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makkr-studio/pattern.git",
+    "directory": "packages/mod-buddy"
+  },
+  "homepage": "https://github.com/makkr-studio/pattern#readme",
+  "bugs": "https://github.com/makkr-studio/pattern/issues",
+  "author": "Makkr Studio (https://github.com/makkr-studio)",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}