@pattern-js/mod-agents 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pattern contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @pattern-js/mod-agents
+
+The **neutral** agents contracts layer for [Pattern](../../README.md) — plain-JSON
+agent/tool/guardrail descriptors and the modality-agnostic turn event protocol,
+with **no SDK dependency**. Provider mods reify the descriptors; apps consume the
+events. Neither has to know about the other.
+
+```bash
+npm install @pattern-js/mod-agents
+```
+
+## When to use
+
+Install it whenever you want agents in your app — but never *alone*. It
+contributes the `boundary.tool` pair, the toolset/guardrail ops, and the live
+tool registry (`AGENTS_SERVICE`); it does **not** run an agent. Pair it with a
+provider (`@pattern-js/mod-agents-openai`) that reifies the descriptors and emits
+the turn events.
+
+**When not:** a single model call with no tools, no agent loop, and no streaming
+turn events — a provider op straight from the canvas is lighter than the agents
+stack.
+
+## Prerequisites
+
+Always ship it with a provider. Usually also `@pattern-js/mod-store` (history +
+blobs) and `@pattern-js/mod-vault` (the API key).
+
+## Config
+
+The contracts always ship paired with a provider — add both as strings in
+`pattern.config.json`:
+
+```jsonc
+{ "mods": ["@pattern-js/mod-agents", "@pattern-js/mod-agents-openai"] }
+```
+
+For options, export a local wrapper mod that calls the `agentsMod({...})` factory.
+
+Full documentation: the **Agents (contracts)** chapter at `/docs` (served by
+`@pattern-js/mod-docs`), or [the source](docs/index.md).

package/dist/boundaries.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @pattern-js/mod-agents — the boundary.tool pair.
+ *
+ * A tool is a WORKFLOW that starts with `boundary.tool` (name, description,
+ * params as JSON Schema — the SchemaBuilder UI in the editor) and ends with
+ * `boundary.tool.return`. That one shape buys, for free:
+ *
+ *  - engine-side argument validation (`validate: true` → TriggerInputError
+ *    before the body runs — an LLM's malformed args never reach your graph),
+ *  - discovery (the registry scans for these triggers, like hook listeners),
+ *  - run linkage (each call is a ctx.invoke sub-run: ↳ links + sampled I/O —
+ *    the Runs page is the agent debugger).
+ *
+ * Guardrails reuse the SAME pair by convention: a guardrail is a tool
+ * workflow whose result is `{ tripwire: boolean, info?: unknown }`.
+ */
+import { type OpDefinition } from "@pattern-js/core";
+export declare const toolTrigger: OpDefinition;
+export declare const toolReturn: OpDefinition;
+export declare const agentBoundaryOps: OpDefinition[];
+//# sourceMappingURL=boundaries.d.ts.map

package/dist/boundaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundaries.d.ts","sourceRoot":"","sources":["../src/boundaries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAML,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAC;AAI1B,eAAO,MAAM,WAAW,EAAE,YAwCzB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,YAUxB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,YAAY,EAA8B,CAAC"}

package/dist/boundaries.js

@@ -0,0 +1,71 @@
+/**
+ * @pattern-js/mod-agents — the boundary.tool pair.
+ *
+ * A tool is a WORKFLOW that starts with `boundary.tool` (name, description,
+ * params as JSON Schema — the SchemaBuilder UI in the editor) and ends with
+ * `boundary.tool.return`. That one shape buys, for free:
+ *
+ *  - engine-side argument validation (`validate: true` → TriggerInputError
+ *    before the body runs — an LLM's malformed args never reach your graph),
+ *  - discovery (the registry scans for these triggers, like hook listeners),
+ *  - run linkage (each call is a ctx.invoke sub-run: ↳ links + sampled I/O —
+ *    the Runs page is the agent debugger).
+ *
+ * Guardrails reuse the SAME pair by convention: a guardrail is a tool
+ * workflow whose result is `{ tripwire: boolean, info?: unknown }`.
+ */
+import { jsonSchemaToZod, required, userInputSchema, value, z, } from "@pattern-js/core";
+const jsonSchema = z.record(z.string(), z.unknown());
+export const toolTrigger = {
+    type: "boundary.tool",
+    title: "boundary.tool",
+    description: "Declares this workflow as an agent-callable tool. config: { name, description, params (JSON Schema) }. " +
+        "Outputs { args (validated), user }.",
+    boundary: "trigger",
+    pair: "boundary.tool.return",
+    inputs: {},
+    // Wire a core.schema.define node into `params` and the resolve phase
+    // freezes it — same trick as http.request's body/query/params.
+    configInputs: {
+        name: value(z.string()),
+        description: value(z.string()),
+        params: value(jsonSchema),
+    },
+    outputs: (config) => ({
+        args: config.params
+            ? value(jsonSchemaToZod(config.params), { validate: true })
+            : value(z.record(z.string(), z.unknown())),
+        user: value(userInputSchema),
+    }),
+    config: z.object({
+        /** Tool name the model sees (unique per app; snake_case reads best). */
+        name: z.string().min(1),
+        /** What the model reads to decide when to call this tool. */
+        description: z.string().optional(),
+        /** JSON Schema for the arguments (engine-validated on every call). */
+        params: jsonSchema.optional(),
+        /** Pause for human approval before each call (HITL). */
+        needsApproval: z.boolean().optional(),
+        /**
+         * Reserve this tool for use as a GUARDRAIL (or other by-name invocation)
+         * only — it's still resolvable via `agents.guardrail`, but the default
+         * `agents.tools.workflows` toolset leaves it out, so the model is never
+         * offered it as a callable tool. Name it explicitly to include it anyway.
+         */
+        guardrail: z.boolean().optional(),
+    }),
+    execute: () => ({}),
+};
+export const toolReturn = {
+    type: "boundary.tool.return",
+    title: "boundary.tool.return",
+    description: "Tool out-gate: { result } goes back to the calling agent as the tool's output.",
+    boundary: "outgate",
+    pair: "boundary.tool",
+    reusable: false,
+    inputs: { result: required() },
+    outputs: {},
+    execute: async (ctx) => ({ result: await ctx.input.value("result") }),
+};
+export const agentBoundaryOps = [toolTrigger, toolReturn];
+//# sourceMappingURL=boundaries.js.map

package/dist/boundaries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundaries.js","sourceRoot":"","sources":["../src/boundaries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,eAAe,EACf,QAAQ,EACR,eAAe,EACf,KAAK,EACL,CAAC,GAGF,MAAM,kBAAkB,CAAC;AAE1B,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,eAAe;IACtB,WAAW,EACT,yGAAyG;QACzG,qCAAqC;IACvC,QAAQ,EAAE,SAAS;IACnB,IAAI,EAAE,sBAAsB;IAC5B,MAAM,EAAE,EAAE;IACV,qEAAqE;IACrE,+DAA+D;IAC/D,YAAY,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACvB,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC9B,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC;KAC1B;IACD,OAAO,EAAE,CAAC,MAA4B,EAAS,EAAE,CAAC,CAAC;QACjD,IAAI,EAAE,MAAM,CAAC,MAAM;YACjB,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,MAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YACpE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5C,IAAI,EAAE,KAAK,CAAC,eAAe,CAAC;KAC7B,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,wEAAwE;QACxE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,6DAA6D;QAC7D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAClC,sEAAsE;QACtE,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE;QAC7B,wDAAwD;QACxD,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QACrC;;;;;WAKG;QACH,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;KAClC,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAiB;IACtC,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,sBAAsB;IAC7B,WAAW,EAAE,gFAAgF;IAC7F,QAAQ,EAAE,SAAS;IACnB,IAAI,EAAE,eAAe;IACrB,QAAQ,EAAE,KAAK;IACf,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAC9B,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;CACtE,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAmB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/** @pattern-js/mod-agents — public surface (the neutral agent contracts). */
+export { agentsMod } from "./mod.js";
+export { default } from "./mod.js";
+export { AGENTS_SERVICE, agentsService, workflowToolRef, type AgentsService, type OpToolRegistration, type WorkflowToolRegistration, } from "./well-known.js";
+export { AgentsRegistry } from "./service.js";
+export { agentBoundaryOps, toolTrigger, toolReturn } from "./boundaries.js";
+export { agentsOps } from "./ops.js";
+export { agentSchema, guardrailSchema, historySchema, messagePartSchema, toolRefSchema, toolsetSchema, turnEventSchema, type AgentDescriptor, type GuardrailDescriptor, type History, type MessagePart, type ToolRef, type ToolsetDescriptor, type TurnEvent, type TurnStopReason, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/** @pattern-js/mod-agents — public surface (the neutral agent contracts). */
+export { agentsMod } from "./mod.js";
+export { default } from "./mod.js";
+export { AGENTS_SERVICE, agentsService, workflowToolRef, } from "./well-known.js";
+export { AgentsRegistry } from "./service.js";
+export { agentBoundaryOps, toolTrigger, toolReturn } from "./boundaries.js";
+export { agentsOps } from "./ops.js";
+export { agentSchema, guardrailSchema, historySchema, messagePartSchema, toolRefSchema, toolsetSchema, turnEventSchema, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,GAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,GAShB,MAAM,YAAY,CAAC"}

package/dist/mod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @pattern-js/mod-agents — the mod. Registers the boundary.tool pair, the
+ * neutral toolset/guardrail ops, and the live tool registry (AGENTS_SERVICE).
+ */
+import { type PatternMod } from "@pattern-js/core";
+export declare function agentsMod(): PatternMod;
+/** A ready-to-use agents-contracts mod (for `loadMods`/`engine.use`). */
+declare const _default: PatternMod;
+export default _default;
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAiB3E,wBAAgB,SAAS,IAAI,UAAU,CAUtC;AAED,yEAAyE;;AACzE,wBAA2B"}

package/dist/mod.js

@@ -0,0 +1,37 @@
+/**
+ * @pattern-js/mod-agents — the mod. Registers the boundary.tool pair, the
+ * neutral toolset/guardrail ops, and the live tool registry (AGENTS_SERVICE).
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { localFs, provideFilesystem } from "@pattern-js/runtime-node";
+import { defineMod } from "@pattern-js/core";
+import { agentBoundaryOps } from "./boundaries.js";
+import { agentsOps } from "./ops.js";
+import { AgentsRegistry } from "./service.js";
+import { AGENTS_SERVICE } from "./well-known.js";
+/** The packaged docs/ chapter (the `docs` contribution points at "agents-docs"). */
+function packagedDocs(engine) {
+    try {
+        const dir = fileURLToPath(new URL("../docs", import.meta.url));
+        if (existsSync(dir))
+            provideFilesystem(engine, "agents-docs", localFs(dir));
+    }
+    catch {
+        /* packaged without docs — the contribution is simply skipped */
+    }
+}
+export function agentsMod() {
+    return defineMod({
+        name: "@pattern-js/mod-agents",
+        docs: { filesystem: "agents-docs", title: "Agents", order: 50 },
+        ops: [...agentBoundaryOps, ...agentsOps],
+        setup: (engine) => {
+            packagedDocs(engine);
+            engine.provideService(AGENTS_SERVICE, new AgentsRegistry(engine));
+        },
+    });
+}
+/** A ready-to-use agents-contracts mod (for `loadMods`/`engine.use`). */
+export default agentsMod();
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,SAAS,EAAgC,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD,oFAAoF;AACpF,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/D,IAAI,UAAU,CAAC,GAAG,CAAC;YAAE,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,SAAS,CAAC;QACf,IAAI,EAAE,wBAAwB;QAC9B,IAAI,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;QAC/D,GAAG,EAAE,CAAC,GAAG,gBAAgB,EAAE,GAAG,SAAS,CAAC;QACxC,KAAK,EAAE,CAAC,MAAc,EAAE,EAAE;YACxB,YAAY,CAAC,MAAM,CAAC,CAAC;YACrB,MAAM,CAAC,cAAc,CAAC,cAAc,EAAE,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;QACpE,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,eAAe,SAAS,EAAE,CAAC"}

package/dist/ops.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @pattern-js/mod-agents — neutral ops (toolset plumbing + guardrail refs).
+ *
+ * Provider-independent nodes: pick workflow tools into a toolset, merge
+ * toolsets from several sources, wrap a tool workflow as a guardrail
+ * descriptor. The agent/run ops live in provider mods.
+ */
+import { type OpDefinition } from "@pattern-js/core";
+export declare const agentsOps: OpDefinition[];
+//# sourceMappingURL=ops.d.ts.map

package/dist/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAmH/D,eAAO,MAAM,SAAS,EAAE,YAAY,EAAsD,CAAC"}

package/dist/ops.js

@@ -0,0 +1,110 @@
+/**
+ * @pattern-js/mod-agents — neutral ops (toolset plumbing + guardrail refs).
+ *
+ * Provider-independent nodes: pick workflow tools into a toolset, merge
+ * toolsets from several sources, wrap a tool workflow as a guardrail
+ * descriptor. The agent/run ops live in provider mods.
+ */
+import { value, z } from "@pattern-js/core";
+import { agentsService, workflowToolRef } from "./well-known.js";
+import { toolsetSchema } from "./types.js";
+const toolsWorkflows = {
+    type: "agents.tools.workflows",
+    title: "agents.tools.workflows",
+    description: 'Collect boundary.tool workflows into a toolset. config.tools: tool names to include, or empty/["*"] for all.',
+    config: z.object({
+        /** Tool names to include; empty (or ["*"]) = every discovered tool. */
+        tools: z.array(z.string()).default([]),
+    }),
+    inputs: {},
+    outputs: { toolset: value(toolsetSchema) },
+    execute: (ctx) => {
+        const svc = agentsService(ctx);
+        const wanted = ctx.config.tools.filter((t) => t !== "*");
+        const all = svc.listWorkflowTools();
+        const picked = wanted.length === 0
+            ? // Auto-pickup offers every tool to the model EXCEPT guardrail-only
+                // ones (a moderation classifier must not become a callable tool).
+                // Name one explicitly below to include it anyway.
+                all.filter((t) => !t.guardrail)
+            : wanted.map((name) => {
+                const reg = svc.getWorkflowTool(name);
+                if (!reg) {
+                    const known = all.map((t) => t.name).join(", ") || "(none)";
+                    throw new Error(`agents: no tool workflow named "${name}" — known tools: ${known}`);
+                }
+                return reg;
+            });
+        const toolset = { kind: "toolset", tools: picked.map(workflowToolRef) };
+        return { toolset };
+    },
+};
+const toolsOps = {
+    type: "agents.tools.ops",
+    title: "agents.tools.ops",
+    description: "Collect mod-contributed code tools into a toolset. config.tools: names to include, empty = all registered.",
+    config: z.object({ tools: z.array(z.string()).default([]) }),
+    inputs: {},
+    outputs: { toolset: value(toolsetSchema) },
+    execute: (ctx) => {
+        const svc = agentsService(ctx);
+        const wanted = ctx.config.tools;
+        const all = svc.listOpTools();
+        const picked = wanted.length === 0 ? all : all.filter((t) => wanted.includes(t.name));
+        const toolset = {
+            kind: "toolset",
+            tools: picked.map((t) => ({ origin: "op", name: t.name, needsApproval: t.needsApproval })),
+        };
+        return { toolset };
+    },
+};
+const toolsMerge = {
+    type: "agents.tools.merge",
+    title: "agents.tools.merge",
+    description: "Merge toolsets (workflow tools + MCP servers + op tools) into one. config.count sets the inputs.",
+    config: z.object({ count: z.number().int().min(2).max(8).default(2) }),
+    inputs: (config) => Object.fromEntries(Array.from({ length: config.count ?? 2 }, (_v, i) => [`tools${i}`, value(toolsetSchema)])),
+    outputs: { toolset: value(toolsetSchema) },
+    execute: async (ctx) => {
+        const count = ctx.config.count;
+        const sets = await Promise.all(Array.from({ length: count }, (_v, i) => ctx.input.has(`tools${i}`) ? ctx.input.value(`tools${i}`) : undefined));
+        const tools = sets.filter(Boolean).flatMap((s) => s.tools);
+        // De-dup by identity (a tool picked twice via different routes is once).
+        const seen = new Set();
+        const deduped = tools.filter((t) => {
+            const key = JSON.stringify(t);
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+        return { toolset: { kind: "toolset", tools: deduped } };
+    },
+};
+const guardrail = {
+    type: "agents.guardrail",
+    title: "agents.guardrail",
+    description: "Wrap a boundary.tool workflow (returning { tripwire, info? }) as an input or output guardrail.",
+    config: z.object({
+        /** The tool workflow's declared name. */
+        tool: z.string().min(1),
+        direction: z.enum(["input", "output"]).default("input"),
+    }),
+    inputs: {},
+    outputs: { guardrail: value() },
+    execute: (ctx) => {
+        const cfg = ctx.config;
+        const reg = agentsService(ctx).getWorkflowTool(cfg.tool);
+        if (!reg)
+            throw new Error(`agents: no tool workflow named "${cfg.tool}" to use as a guardrail`);
+        const descriptor = {
+            kind: "guardrail",
+            direction: cfg.direction,
+            workflowId: reg.workflowId,
+            name: reg.name,
+        };
+        return { guardrail: descriptor };
+    },
+};
+export const agentsOps = [toolsWorkflows, toolsOps, toolsMerge, guardrail];
+//# sourceMappingURL=ops.js.map

package/dist/ops.js.map

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

package/dist/service.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @pattern-js/mod-agents — the registry implementation.
+ *
+ * Workflow tools are DISCOVERED, never registered by hand: the service scans
+ * the engine's workflow registry for `boundary.tool` triggers and keeps the
+ * index live via `onWorkflowsChanged` (the same pattern hook listeners use) —
+ * deploy a tool workflow from the admin and the next agent run sees it.
+ */
+import type { Engine } from "@pattern-js/core";
+import type { AgentsService, OpToolRegistration, WorkflowToolRegistration } from "./well-known.js";
+export declare class AgentsRegistry implements AgentsService {
+    private readonly engine;
+    private workflowTools;
+    private opTools;
+    private turns;
+    constructor(engine: Engine);
+    private rescan;
+    private index;
+    listWorkflowTools(): WorkflowToolRegistration[];
+    getWorkflowTool(name: string): WorkflowToolRegistration | undefined;
+    registerOpTool(reg: OpToolRegistration): void;
+    listOpTools(): OpToolRegistration[];
+    getOpTool(name: string): OpToolRegistration | undefined;
+    registerTurn(turnId: string, controller: AbortController): void;
+    releaseTurn(turnId: string): void;
+    abortTurn(turnId: string, reason?: unknown): boolean;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAY,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,iBAAiB,CAAC;AAEzB,qBAAa,cAAe,YAAW,aAAa;IAKtC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,KAAK,CAAsC;gBAEtB,MAAM,EAAE,MAAM;IAK3C,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,KAAK;IA8Bb,iBAAiB,IAAI,wBAAwB,EAAE;IAI/C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS;IAInE,cAAc,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAO7C,WAAW,IAAI,kBAAkB,EAAE;IAInC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIvD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI;IAI/D,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIjC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;CAOrD"}

package/dist/service.js

@@ -0,0 +1,81 @@
+/**
+ * @pattern-js/mod-agents — the registry implementation.
+ *
+ * Workflow tools are DISCOVERED, never registered by hand: the service scans
+ * the engine's workflow registry for `boundary.tool` triggers and keeps the
+ * index live via `onWorkflowsChanged` (the same pattern hook listeners use) —
+ * deploy a tool workflow from the admin and the next agent run sees it.
+ */
+export class AgentsRegistry {
+    engine;
+    workflowTools = new Map();
+    opTools = new Map();
+    turns = new Map();
+    constructor(engine) {
+        this.engine = engine;
+        for (const wf of engine.workflows.list())
+            this.index(wf);
+        engine.onWorkflowsChanged(() => this.rescan());
+    }
+    rescan() {
+        this.workflowTools.clear();
+        for (const wf of this.engine.workflows.list())
+            this.index(wf);
+    }
+    index(workflow) {
+        for (const node of workflow.nodes) {
+            if (node.op !== "boundary.tool")
+                continue;
+            const cfg = (node.config ?? {});
+            if (!cfg.name)
+                continue;
+            const existing = this.workflowTools.get(cfg.name);
+            if (existing && existing.workflowId !== workflow.id) {
+                console.warn(`[pattern/mod-agents] tool name "${cfg.name}" is declared by both "${existing.workflowId}" and "${workflow.id}" — keeping the first`);
+                continue;
+            }
+            this.workflowTools.set(cfg.name, {
+                workflowId: workflow.id,
+                nodeId: node.id,
+                name: cfg.name,
+                description: cfg.description,
+                params: cfg.params,
+                needsApproval: cfg.needsApproval,
+                guardrail: cfg.guardrail,
+            });
+        }
+    }
+    listWorkflowTools() {
+        return [...this.workflowTools.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    getWorkflowTool(name) {
+        return this.workflowTools.get(name);
+    }
+    registerOpTool(reg) {
+        if (this.opTools.has(reg.name)) {
+            throw new Error(`[pattern/mod-agents] op tool "${reg.name}" is already registered`);
+        }
+        this.opTools.set(reg.name, reg);
+    }
+    listOpTools() {
+        return [...this.opTools.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    getOpTool(name) {
+        return this.opTools.get(name);
+    }
+    registerTurn(turnId, controller) {
+        this.turns.set(turnId, controller);
+    }
+    releaseTurn(turnId) {
+        this.turns.delete(turnId);
+    }
+    abortTurn(turnId, reason) {
+        const ctrl = this.turns.get(turnId);
+        if (!ctrl)
+            return false;
+        this.turns.delete(turnId);
+        ctrl.abort(reason ?? new Error("turn aborted"));
+        return true;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @pattern-js/mod-agents — the neutral contracts.
+ *
+ * Two families of shapes, both PLAIN JSON (structured-cloneable: they flow on
+ * edges and may cross worker boundaries — provider SDK objects never do; a
+ * provider mod reifies descriptors into SDK instances at execute time):
+ *
+ *  - **Descriptors** — what an agent/toolset/guardrail value IS on the canvas.
+ *  - **Turn events** — the modality-agnostic stream a running agent emits
+ *    (text deltas, tool activity, approval requests, a guaranteed terminal
+ *    event). Chat UIs, stores and SSE responses all speak this one protocol;
+ *    voice surfaces later consume the same stream (`audio.ref` is reserved).
+ *
+ * Message content is PARTS-based from day one (text | image_ref) — retrofitting
+ * parts into string messages is the painful version.
+ */
+import { z } from "@pattern-js/core";
+export declare const messagePartSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image_ref">;
+    blobId: z.ZodString;
+    mime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export type MessagePart = z.infer<typeof messagePartSchema>;
+/**
+ * Conversation history: provider-shaped items, treated as OPAQUE by everything
+ * except the provider mod that produced them (pull from the store → agent run
+ * → push back). Keeping them opaque lets each provider use its native item
+ * format losslessly.
+ */
+export declare const historySchema: z.ZodArray<z.ZodUnknown>;
+export type History = unknown[];
+export declare const toolRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    origin: z.ZodLiteral<"workflow">;
+    workflowId: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    needsApproval: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodLiteral<"mcp">;
+    transport: z.ZodEnum<{
+        http: "http";
+        stdio: "stdio";
+    }>;
+    url: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    serverLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodLiteral<"op">;
+    name: z.ZodString;
+    needsApproval: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "origin">;
+export type ToolRef = z.infer<typeof toolRefSchema>;
+export declare const toolsetSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"toolset">;
+    tools: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        origin: z.ZodLiteral<"workflow">;
+        workflowId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        needsApproval: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodLiteral<"mcp">;
+        transport: z.ZodEnum<{
+            http: "http";
+            stdio: "stdio";
+        }>;
+        url: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        serverLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodLiteral<"op">;
+        name: z.ZodString;
+        needsApproval: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>], "origin">>;
+}, z.core.$strip>;
+export type ToolsetDescriptor = z.infer<typeof toolsetSchema>;
+export declare const guardrailSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"guardrail">;
+    direction: z.ZodEnum<{
+        input: "input";
+        output: "output";
+    }>;
+    workflowId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type GuardrailDescriptor = z.infer<typeof guardrailSchema>;
+export interface AgentDescriptor {
+    kind: "agent";
+    name: string;
+    instructions: string;
+    model?: string;
+    modelSettings?: Record<string, unknown>;
+    tools?: ToolsetDescriptor;
+    guardrails?: GuardrailDescriptor[];
+    /** Other agents this one may hand off to. */
+    handoffs?: AgentDescriptor[];
+    handoffDescription?: string;
+    /** JSON Schema for structured final output (provider-enforced). */
+    outputSchema?: Record<string, unknown>;
+}
+export declare const agentSchema: z.ZodType<AgentDescriptor>;
+export declare const turnEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text.delta">;
+    delta: z.ZodString;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text.done">;
+    text: z.ZodString;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool.activity">;
+    toolName: z.ZodString;
+    callId: z.ZodOptional<z.ZodString>;
+    phase: z.ZodEnum<{
+        error: "error";
+        start: "start";
+        done: "done";
+    }>;
+    args: z.ZodOptional<z.ZodUnknown>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+    subRunId: z.ZodOptional<z.ZodString>;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"audio.ref">;
+    blobId: z.ZodString;
+    mime: z.ZodString;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"approval.request">;
+    interruption: z.ZodObject<{
+        id: z.ZodString;
+        toolName: z.ZodString;
+        args: z.ZodUnknown;
+    }, z.core.$strip>;
+    stateToken: z.ZodString;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    stopReason: z.ZodEnum<{
+        error: "error";
+        complete: "complete";
+        interrupted: "interrupted";
+        cancelled: "cancelled";
+    }>;
+    turnId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>], "type">;
+export type TurnEvent = z.infer<typeof turnEventSchema>;
+export type TurnStopReason = Extract<TurnEvent, {
+    type: "done";
+}>["stopReason"];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAIrC,eAAO,MAAM,iBAAiB;;;;;;;mBAQ5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,0BAAuB,CAAC;AAClD,MAAM,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;AAIhC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;6BA2BxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGxB,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE9D,eAAO,MAAM,eAAe;;;;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAapB,CAAC;AAMhC,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAoC1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,YAAY,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,126 @@
+/**
+ * @pattern-js/mod-agents — the neutral contracts.
+ *
+ * Two families of shapes, both PLAIN JSON (structured-cloneable: they flow on
+ * edges and may cross worker boundaries — provider SDK objects never do; a
+ * provider mod reifies descriptors into SDK instances at execute time):
+ *
+ *  - **Descriptors** — what an agent/toolset/guardrail value IS on the canvas.
+ *  - **Turn events** — the modality-agnostic stream a running agent emits
+ *    (text deltas, tool activity, approval requests, a guaranteed terminal
+ *    event). Chat UIs, stores and SSE responses all speak this one protocol;
+ *    voice surfaces later consume the same stream (`audio.ref` is reserved).
+ *
+ * Message content is PARTS-based from day one (text | image_ref) — retrofitting
+ * parts into string messages is the painful version.
+ */
+import { z } from "@pattern-js/core";
+/* ── message parts ─────────────────────────────────────────────────────── */
+export const messagePartSchema = z.union([
+    z.object({ type: z.literal("text"), text: z.string() }),
+    z.object({
+        type: z.literal("image_ref"),
+        /** A blob id (mod-store) — providers inline it (e.g. base64 data URL). */
+        blobId: z.string(),
+        mime: z.string().optional(),
+    }),
+]);
+/**
+ * Conversation history: provider-shaped items, treated as OPAQUE by everything
+ * except the provider mod that produced them (pull from the store → agent run
+ * → push back). Keeping them opaque lets each provider use its native item
+ * format losslessly.
+ */
+export const historySchema = z.array(z.unknown());
+/* ── descriptors ───────────────────────────────────────────────────────── */
+export const toolRefSchema = z.discriminatedUnion("origin", [
+    z.object({
+        origin: z.literal("workflow"),
+        workflowId: z.string(),
+        name: z.string(),
+        description: z.string().optional(),
+        /** JSON Schema for the tool arguments (engine-enforced via boundary.tool). */
+        params: z.record(z.string(), z.unknown()).optional(),
+        /** Pause for human approval before each call (HITL). */
+        needsApproval: z.boolean().optional(),
+    }),
+    z.object({
+        origin: z.literal("mcp"),
+        transport: z.enum(["http", "stdio"]),
+        url: z.string().optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        command: z.string().optional(),
+        args: z.array(z.string()).optional(),
+        env: z.record(z.string(), z.string()).optional(),
+        serverLabel: z.string().optional(),
+    }),
+    z.object({
+        origin: z.literal("op"),
+        /** Name in the AGENTS_SERVICE op-tool registry (mods register in setup). */
+        name: z.string(),
+        needsApproval: z.boolean().optional(),
+    }),
+]);
+export const toolsetSchema = z.object({
+    kind: z.literal("toolset"),
+    tools: z.array(toolRefSchema),
+});
+export const guardrailSchema = z.object({
+    kind: z.literal("guardrail"),
+    direction: z.enum(["input", "output"]),
+    /** A boundary.tool workflow returning { tripwire: boolean, info?: unknown }. */
+    workflowId: z.string(),
+    name: z.string(),
+});
+export const agentSchema = z.lazy(() => z.object({
+    kind: z.literal("agent"),
+    name: z.string(),
+    instructions: z.string(),
+    model: z.string().optional(),
+    modelSettings: z.record(z.string(), z.unknown()).optional(),
+    tools: toolsetSchema.optional(),
+    guardrails: z.array(guardrailSchema).optional(),
+    handoffs: z.array(agentSchema).optional(),
+    handoffDescription: z.string().optional(),
+    outputSchema: z.record(z.string(), z.unknown()).optional(),
+}));
+/* ── the turn event protocol ───────────────────────────────────────────── */
+const base = { turnId: z.string(), runId: z.string() };
+export const turnEventSchema = z.discriminatedUnion("type", [
+    /** Streaming text. */
+    z.object({ ...base, type: z.literal("text.delta"), delta: z.string() }),
+    /** A complete assistant message (also emitted after deltas). */
+    z.object({ ...base, type: z.literal("text.done"), text: z.string() }),
+    /** Tool lifecycle: start → done | error. Args/results may be elided/truncated. */
+    z.object({
+        ...base,
+        type: z.literal("tool.activity"),
+        toolName: z.string(),
+        callId: z.string().optional(),
+        phase: z.enum(["start", "done", "error"]),
+        args: z.unknown().optional(),
+        result: z.unknown().optional(),
+        error: z.string().optional(),
+        /** Set when the tool ran as a linked sub-run (deep-link into the admin). */
+        subRunId: z.string().optional(),
+    }),
+    /** Reserved for the voice round: a chunk of audio parked as a blob. */
+    z.object({ ...base, type: z.literal("audio.ref"), blobId: z.string(), mime: z.string() }),
+    /** HITL: the turn paused awaiting approval; resume via the provider mod. */
+    z.object({
+        ...base,
+        type: z.literal("approval.request"),
+        interruption: z.object({ id: z.string(), toolName: z.string(), args: z.unknown() }),
+        /** Opaque serialized run state — only the provider mod reads it. */
+        stateToken: z.string(),
+    }),
+    /** An error, as turn CONTENT (chat UIs render an inline card, not a toast). */
+    z.object({ ...base, type: z.literal("error"), message: z.string(), code: z.string().optional() }),
+    /** GUARANTEED terminal event — a consumer can always settle on `done`. */
+    z.object({
+        ...base,
+        type: z.literal("done"),
+        stopReason: z.enum(["complete", "interrupted", "error", "cancelled"]),
+    }),
+]);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/well-known.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @pattern-js/mod-agents — the well-known service seam.
+ *
+ * Provider mods (mod-agents-openai…) and consumers (mod-chat) meet here:
+ * the tool registry lives on AGENTS_SERVICE; nobody imports a provider mod
+ * to find tools.
+ */
+import type { OpContext } from "@pattern-js/core";
+import type { ToolRef } from "./types.js";
+export declare const AGENTS_SERVICE = "agentsService";
+/** A boundary.tool workflow discovered in the registry. */
+export interface WorkflowToolRegistration {
+    workflowId: string;
+    nodeId: string;
+    name: string;
+    description?: string;
+    params?: Record<string, unknown>;
+    needsApproval?: boolean;
+    /** Guardrail-only: resolvable by name, but excluded from the default toolset. */
+    guardrail?: boolean;
+}
+/** A code tool a mod contributes directly (registered in its `setup`). */
+export interface OpToolRegistration {
+    name: string;
+    description: string;
+    /** JSON Schema for the arguments. */
+    params: Record<string, unknown>;
+    execute(args: Record<string, unknown>, ctx: OpContext): unknown | Promise<unknown>;
+    needsApproval?: boolean;
+}
+export interface AgentsService {
+    /** Live view of every boundary.tool workflow (registered ⇄ discovered). */
+    listWorkflowTools(): WorkflowToolRegistration[];
+    getWorkflowTool(name: string): WorkflowToolRegistration | undefined;
+    /** Mods contribute ready-made tools here from their setup. */
+    registerOpTool(reg: OpToolRegistration): void;
+    listOpTools(): OpToolRegistration[];
+    getOpTool(name: string): OpToolRegistration | undefined;
+    /**
+     * Turn-scoped cancellation. A STREAMING run settles for the engine as soon
+     * as its out-gates capture (the SSE tail flows after), so engine.cancelRun
+     * can't reach an in-flight agent turn — providers register an
+     * AbortController per turnId instead, and a Stop button calls `abortTurn`.
+     */
+    registerTurn(turnId: string, controller: AbortController): void;
+    releaseTurn(turnId: string): void;
+    abortTurn(turnId: string, reason?: unknown): boolean;
+}
+export declare function agentsService(ctx: OpContext): AgentsService;
+/** ToolRef for a workflow tool registration (what flows on toolset edges). */
+export declare function workflowToolRef(reg: WorkflowToolRegistration): ToolRef;
+//# sourceMappingURL=well-known.d.ts.map

package/dist/well-known.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.d.ts","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAE9C,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,iBAAiB,IAAI,wBAAwB,EAAE,CAAC;IAChD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS,CAAC;IACpE,8DAA8D;IAC9D,cAAc,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,WAAW,IAAI,kBAAkB,EAAE,CAAC;IACpC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACxD;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IAChE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CACtD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CAQ3D;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAStE"}

package/dist/well-known.js

@@ -0,0 +1,27 @@
+/**
+ * @pattern-js/mod-agents — the well-known service seam.
+ *
+ * Provider mods (mod-agents-openai…) and consumers (mod-chat) meet here:
+ * the tool registry lives on AGENTS_SERVICE; nobody imports a provider mod
+ * to find tools.
+ */
+export const AGENTS_SERVICE = "agentsService";
+export function agentsService(ctx) {
+    const svc = ctx.services[AGENTS_SERVICE];
+    if (!svc) {
+        throw new Error('agent ops need @pattern-js/mod-agents installed — add "@pattern-js/mod-agents" to your pattern.config.json mods');
+    }
+    return svc;
+}
+/** ToolRef for a workflow tool registration (what flows on toolset edges). */
+export function workflowToolRef(reg) {
+    return {
+        origin: "workflow",
+        workflowId: reg.workflowId,
+        name: reg.name,
+        description: reg.description,
+        params: reg.params,
+        needsApproval: reg.needsApproval,
+    };
+}
+//# sourceMappingURL=well-known.js.map

package/dist/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;AA2C9C,MAAM,UAAU,aAAa,CAAC,GAAc;IAC1C,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,cAAc,CAA8B,CAAC;IACtE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,iHAAiH,CAClH,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,GAA6B;IAC3D,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,aAAa,EAAE,GAAG,CAAC,aAAa;KACjC,CAAC;AACJ,CAAC"}

package/docs/guides/authoring-tools.md

@@ -0,0 +1,99 @@
+---
+title: Authoring tools
+order: 10
+---
+
+# Authoring agent tools
+
+A tool is just a workflow with a `boundary.tool` trigger and a
+`boundary.tool.return` out-gate. Reach for one whenever the model needs to
+*do* something — look data up, call an API, change state — rather than only
+talk. Three things make it a good tool.
+
+## 1. A tight schema
+
+The trigger's `params` is a JSON Schema the **engine validates** before your
+graph runs — the model's arguments are checked at the door, so a hallucinated
+shape becomes a clean `TriggerInputError`, never a malformed value deep in
+your logic. Be specific: required fields, enums, and descriptions (the model
+reads them to decide *when* and *how* to call).
+
+```jsonc
+// workflows/tool-weather.json
+{ "id": "tool-weather",
+  "nodes": [
+    { "id": "in", "op": "boundary.tool",
+      "config": {
+        "name": "get_weather",
+        "description": "Current weather for a city.",
+        "params": {
+          "type": "object",
+          "properties": { "city": { "type": "string", "description": "City name, e.g. \"Lyon\"" } },
+          "required": ["city"] } } },
+    { "id": "fetch", "op": "…your graph…", "comment": "call the weather API" },
+    { "id": "out",   "op": "boundary.tool.return" } ],
+  "edges": [
+    { "from": { "node": "in",    "port": "args" },   "to": { "node": "fetch", "port": "in" } },
+    { "from": { "node": "fetch", "port": "result" }, "to": { "node": "out",   "port": "result" } } ] }
+```
+
+The trigger outputs `args` (validated against your schema) and `user` (the
+calling principal). In the editor, `params` is a visual SchemaBuilder.
+
+## 2. A real return
+
+Wire your result into `boundary.tool.return`'s `result` — that's exactly what
+the model sees. Keep it small and structured; the model pays attention tokens
+for every field. A weather tool returns `{ tempC, summary }`, not the raw API
+envelope. `boundary.tool.return` is the only legal terminal for a tool
+workflow, so every branch must converge on it.
+
+## 3. It's debuggable for free
+
+Every tool call runs as a **linked sub-run** (`ctx.invoke`). Open the agent's
+run in the admin and each invocation is a child run (↳) with its own node
+waterfall and sampled I/O — you see exactly what the model passed and what
+came back. No print-debugging an opaque function.
+
+## Three origins — and when to choose each
+
+- **Workflow tools** — what we just built; `agents.tools.workflows` collects
+  every `boundary.tool` in the app (or a named subset). The default: visible,
+  debuggable, yours. With no names it auto-includes everything *except*
+  guardrail-only tools.
+- **MCP servers** — `agents.mcp.server` exposes an existing MCP server's tools
+  (HTTP or stdio, pooled per process). Choose this to borrow tools you don't
+  want to re-implement.
+- **Op tools** — a mod registers plain-function tools in its setup
+  (`AGENTS_SERVICE.registerOpTool`), picked by `agents.tools.ops`. Choose this
+  for tools a mod ships as code rather than a visible workflow.
+
+Merge any combination with `agents.tools.merge` (config `count` = how many
+toolset inputs) and wire the result into `agents.agent`'s `tools` input.
+
+## Gating a tool behind approval (HITL)
+
+Set `needsApproval: true` on the `boundary.tool` config and the agent pauses
+before the call, emitting an `approval.request` (with an opaque resume
+`stateToken`). The chat app turns that into Approve/Deny buttons;
+`agents.run.resume` continues the **same** turn with the decision. Use it for
+tools with side effects — sending mail, spending money, deleting rows.
+
+## Authoring a guardrail
+
+A guardrail reuses the **same** `boundary.tool` pair: a tool workflow whose
+`result` is `{ tripwire: boolean, info? }`. The provider calls it as an input
+or output guardrail (a linked sub-run, like any tool), and a `tripwire: true`
+ends the turn cleanly with an inline card.
+
+1. Author the classifier as a `boundary.tool` workflow. Mark it
+   `guardrail: true` so `agents.tools.workflows` leaves it **out** of the
+   model's callable toolbox — a moderation classifier must not become a tool
+   the model can invoke.
+2. Wrap it with `agents.guardrail` (config: `tool` = the workflow's name,
+   `direction` = `input` | `output`).
+3. Wire the descriptor into `agents.agent`'s `guardrails` input (one or an
+   array).
+
+Input guardrails vet the user's message before the model sees it; output
+guardrails vet the model's answer before it reaches the user.

package/docs/index.md

@@ -0,0 +1,122 @@
+# Agents (contracts)
+
+`@pattern-js/mod-agents` is the **neutral** agents layer — plain-JSON
+descriptors and the turn event protocol, with no SDK dependency. Provider
+mods (like `@pattern-js/mod-agents-openai`) reify the descriptors into running
+agents; apps (like `@pattern-js/mod-chat`) consume the events. Neither has to
+know about the other.
+
+## When to use
+
+Install this whenever you want agents in your app — but you never install it
+*alone*. It contributes the `boundary.tool` pair, the toolset/guardrail ops,
+and the live tool registry (`AGENTS_SERVICE`); it does **not** run an agent.
+Pair it with a provider (`@pattern-js/mod-agents-openai`) for `agents.agent` /
+`agents.run`, and usually with `@pattern-js/mod-store` (history + blobs) and
+`@pattern-js/mod-vault` (the API key).
+
+**When not:** if all you need is a single model call with no tools, no agent
+loop, and no streaming turn events, a provider op straight from the canvas is
+lighter than the agents stack. The agents layer earns its keep the moment
+there are tools, handoffs, guardrails, or a live transcript.
+
+```jsonc
+// pattern.config.json — the contracts always ship with a provider
+{ "mods": ["@pattern-js/mod-agents", "@pattern-js/mod-agents-openai"] }
+```
+
+## Tools are workflows
+
+A tool is a **workflow** that starts with a `boundary.tool` trigger and ends
+with `boundary.tool.return`. The trigger's config carries the `name` and
+`description` the model reads, plus a JSON-Schema `params` the **engine**
+validates before your graph runs — a model's hallucinated args become a clean
+`TriggerInputError` at the door, never a malformed value deep in your logic.
+That one shape also buys discovery (the registry scans for these triggers,
+live) and debugging: every call is a **linked sub-run** (↳ in the Runs page,
+with sampled I/O), so the admin's run view is your agent debugger.
+
+### Three tool origins — and when to choose each
+
+| origin | op | reach for it when |
+| --- | --- | --- |
+| **workflow** | `agents.tools.workflows` | the tool is your own logic, and you want it visible/debuggable on the canvas (the default — drop a `boundary.tool` workflow in the app and every agent picks it up). |
+| **MCP server** | `agents.mcp.server` (provider mod) | you want to expose an existing MCP server's tools (HTTP or stdio) without re-implementing them. |
+| **op (code)** | `agents.tools.ops` | a mod ships a ready-made tool as a plain function (registered via `AGENTS_SERVICE.registerOpTool` in setup) rather than a visible workflow. |
+
+`agents.tools.workflows` with no names auto-collects every `boundary.tool` in
+the app **except** guardrail-only ones (`guardrail: true` on the trigger keeps
+a moderation classifier from becoming a callable tool — name it explicitly to
+include it anyway). Combine any origins with `agents.tools.merge` (config
+`count` sets the input ports) and wire the result into `agents.agent`'s
+`tools` input.
+
+## Guardrails reuse the tool shape
+
+A guardrail is the same `boundary.tool` pair by convention — a tool workflow
+whose `result` is `{ tripwire: boolean, info? }`. `agents.guardrail` wraps a
+named tool workflow as an `input` or `output` guardrail descriptor; input
+guardrails vet the user's message before the model sees it, output guardrails
+vet the answer. A trip surfaces as an inline error card in the chat and the
+turn ends cleanly with the reason — never a crash. Mark the underlying tool
+`guardrail: true` so it stays out of the model's callable toolbox.
+
+## The turn event protocol
+
+A running agent emits one **modality-agnostic** stream that every surface
+speaks — SSE responses, the chat's persisted log, future voice surfaces:
+
+- `text.delta` / `text.done` — streaming text, then the settled message.
+- `tool.activity` — a tool's lifecycle (`start` → `done` | `error`), with an
+  optional `subRunId` deep-linking into the admin.
+- `approval.request` — the turn paused for human approval (HITL), carrying an
+  opaque `stateToken` only the provider mod reads.
+- `error` — errors are turn **content** (chats render an inline card, not a
+  toast).
+- `audio.ref` — reserved for the voice round.
+- `done { stopReason }` — a **guaranteed** terminal event
+  (`complete | interrupted | error | cancelled`), so a consumer can always
+  settle.
+
+These are event-name constants on the wire, not ops. Descriptors and events
+are both plain JSON (structured-cloneable) so they flow on edges and cross
+worker boundaries; provider SDK objects never do — a provider mod reifies
+descriptors into SDK instances only at execute time.
+
+## Integration
+
+- **Provider** (`@pattern-js/mod-agents-openai`) — meets this mod at the
+  `AGENTS_SERVICE` service seam: it asks the registry for tools, nobody
+  imports a provider to find them. Reifies descriptors → SDK; emits the turn
+  events.
+- **`@pattern-js/mod-store`** — history is opaque provider items pulled from a
+  store and pushed back; image-part tools resolve blob ids through it.
+- **`@pattern-js/mod-chat`** — the product surface; its `chat.turn.pipeline`
+  wires `agents.tools.workflows` → `agents.agent` → `agents.run` and persists
+  the event stream.
+
+## The agentic shape
+
+Request → extract the user's message → collect tools + define the agent →
+run → stream the response. The canvas version, end to end:
+
+```workflow
+{ "id": "agent.turn",
+  "name": "Agent · one turn",
+  "nodes": [
+    { "id": "in",    "op": "boundary.http.request", "config": { "method": "POST", "path": "/api/agent" } },
+    { "id": "msg",   "op": "core.object.get", "config": { "path": "message" }, "comment": "the user's text out of the body" },
+    { "id": "tools", "op": "agents.tools.workflows", "comment": "every boundary.tool in the app; name a subset to narrow" },
+    { "id": "agent", "op": "agents.agent", "config": { "name": "assistant", "instructions": "You are a helpful assistant." } },
+    { "id": "run",   "op": "agents.run", "comment": "streams turn events; needs an API key" },
+    { "id": "out",   "op": "boundary.http.response" } ],
+  "edges": [
+    { "from": { "node": "in",    "port": "body" },    "to": { "node": "msg",   "port": "object" } },
+    { "from": { "node": "tools", "port": "toolset" }, "to": { "node": "agent", "port": "tools" } },
+    { "from": { "node": "agent", "port": "agent" },   "to": { "node": "run",   "port": "agent" } },
+    { "from": { "node": "msg",   "port": "out" },     "to": { "node": "run",   "port": "input" } },
+    { "from": { "node": "run",   "port": "events" },  "to": { "node": "out",   "port": "stream" } } ] }
+```
+
+For the full agentic app (history, persistence, approvals, Stop), use
+`@pattern-js/mod-chat` — its turn pipeline is this shape, hardened.

package/docs/ops/agents.guardrail.md

@@ -0,0 +1,5 @@
+Wrap a `boundary.tool` workflow (one that returns `{ tripwire, info? }`) as an
+input or output guardrail and feed it into `agents.agent`'s guardrails input.
+A tripped guardrail surfaces as an inline card in the chat — the run ends
+cleanly with the reason, never a crash. Input guardrails vet the user's
+message before the model sees it; output guardrails vet the model's answer.

package/docs/ops/agents.tools.merge.md

@@ -0,0 +1,5 @@
+Combine several toolsets into one — workflow tools (`agents.tools.workflows`),
+MCP servers (`agents.mcp.server`), and op tools (`agents.tools.ops`) all
+produce toolset values, and this merges them (config `count` sets how many
+inputs). Wire the result into `agents.agent`'s tools. The three tool origins,
+one toolbox.

package/docs/ops/agents.tools.ops.md

@@ -0,0 +1,4 @@
+Collect mod-contributed CODE tools (registered via
+`AGENTS_SERVICE.registerOpTool`) into a toolset — config `tools` names which
+to include, empty = all. The third tool origin alongside workflow tools and
+MCP: for tools a mod ships as plain functions rather than visible workflows.

package/docs/ops/agents.tools.workflows.md

@@ -0,0 +1,3 @@
+Collects `boundary.tool` workflows into a toolset descriptor. Default: every
+tool workflow in the app ("drop a file in workflows/, the agent learns it").
+Name specific workflows in config to narrow an agent's toolbox.

package/docs/ops/boundary.tool.md

@@ -0,0 +1,5 @@
+The trigger that makes a workflow callable by agents. Config: `name`,
+`description`, `params` (JSON Schema — engine-validated, so your graph never
+sees malformed args), optional `needsApproval` for human-in-the-loop. Outputs
+`args` (validated) + `user` (the principal). Pair with `boundary.tool.return`
+whose `result` becomes the tool's return value to the model.

package/docs/ops/boundary.tool.return.md

@@ -0,0 +1 @@
+The out-gate that closes a `boundary.tool` workflow: whatever you wire into `result` is exactly what the calling agent reads back as the tool's output. Keep it small and structured — the model spends attention tokens on every field, so return `{ tempC, summary }`, not a raw API envelope. For a guardrail tool, this is where `{ tripwire, info? }` goes. Pairs with `boundary.tool`; it's the only legal terminal for a tool workflow, so every branch must converge here.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pattern-js/mod-agents",
+  "version": "0.2.0",
+  "description": "Neutral agent contracts for Pattern: agent/tool/guardrail descriptors that flow on edges, the boundary.tool workflow pair (engine-validated params), the modality-agnostic turn event protocol, and the tool registry — no model-provider dependency. Pair with @pattern-js/mod-agents-openai (or a future provider mod).",
+  "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.2.0",
+    "@pattern-js/runtime-node": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makkr-studio/pattern.git",
+    "directory": "packages/mod-agents"
+  },
+  "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"
+  }
+}