@pattern-js/mod-agents 0.2.2-main.b9393c1 → 0.3.0-main.4a77893

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/types.js CHANGED
@@ -32,6 +32,63 @@ export const messagePartSchema = z.union([
32
32
  * format losslessly.
33
33
  */
34
34
  export const historySchema = z.array(z.unknown());
35
+ /* ── model reference ───────────────────────────────────────────────────── */
36
+ /**
37
+ * A provider-neutral reference to a model. Plain JSON, structured-cloneable, it
38
+ * flows on a value port into every capability op and into an agent. The CAPABILITY
39
+ * layer (mod-ai) turns it into a concrete SDK model; the neutral layer only ever
40
+ * passes it around. Routing is first-class: `direct` (a native provider package +
41
+ * a provider key) or `gateway` (the Vercel AI Gateway, one key, `provider/model` ids).
42
+ */
43
+ export const modelRefSchema = z.object({
44
+ kind: z.literal("model"),
45
+ routing: z.enum(["direct", "gateway"]),
46
+ modality: z
47
+ .enum(["language", "embedding", "image", "speech", "transcription", "video"])
48
+ .default("language"),
49
+ /** direct: provider package id ("openai"); gateway: the provider half of "provider/model". */
50
+ provider: z.string(),
51
+ /** direct: bare model id ("gpt-5"); gateway: the full "provider/model" string. */
52
+ modelId: z.string(),
53
+ /** Vault secret NAME to resolve the key (defaults per routing/provider in mod-ai). */
54
+ credential: z.string().optional(),
55
+ /**
56
+ * Optional reference to a named mod-ai **alias** — a fully-configured model
57
+ * (provider + routing + explicitly-chosen secrets, incl. structured creds for
58
+ * Azure/Bedrock/Vertex, + options). When set, mod-ai resolves everything from
59
+ * the alias at run time; the inline fields above stay for display/catalog.
60
+ * This is what `ai.alias` produces, so re-pointing the alias in Settings
61
+ * instantly re-targets every workflow and agent using it.
62
+ */
63
+ alias: z.string().optional(),
64
+ /** Pass-through provider options (temperature, reasoning, dimensions, voice…). */
65
+ providerOptions: z.record(z.string(), z.unknown()).optional(),
66
+ });
67
+ /** Token accounting common to every generation, when the provider reports it. */
68
+ export const usageSchema = z
69
+ .object({
70
+ inputTokens: z.number(),
71
+ outputTokens: z.number(),
72
+ totalTokens: z.number(),
73
+ })
74
+ .partial();
75
+ /**
76
+ * A provider-neutral chat message (parts-based content, reusing messagePartSchema).
77
+ * The agent loop owns history losslessly in this shape; mod-ai maps it to/from the
78
+ * AI SDK's message format. `tool` messages carry the call linkage; an `assistant`
79
+ * message may carry the tool calls it requested.
80
+ */
81
+ export const neutralMessageSchema = z.object({
82
+ role: z.enum(["system", "user", "assistant", "tool"]),
83
+ content: z.union([z.string(), z.array(messagePartSchema)]),
84
+ /** tool result messages: which call this answers. */
85
+ toolCallId: z.string().optional(),
86
+ toolName: z.string().optional(),
87
+ /** assistant messages: the tool calls requested this step. */
88
+ toolCalls: z
89
+ .array(z.object({ callId: z.string(), toolName: z.string(), args: z.unknown() }))
90
+ .optional(),
91
+ });
35
92
  /* ── descriptors ───────────────────────────────────────────────────────── */
36
93
  export const toolRefSchema = z.discriminatedUnion("origin", [
37
94
  z.object({
@@ -76,8 +133,7 @@ export const agentSchema = z.lazy(() => z.object({
76
133
  kind: z.literal("agent"),
77
134
  name: z.string(),
78
135
  instructions: z.string(),
79
- model: z.string().optional(),
80
- modelSettings: z.record(z.string(), z.unknown()).optional(),
136
+ model: modelRefSchema.optional(),
81
137
  tools: toolsetSchema.optional(),
82
138
  guardrails: z.array(guardrailSchema).optional(),
83
139
  handoffs: z.array(agentSchema).optional(),
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @pattern-js/mod-agents — the well-known service seam.
3
3
  *
4
- * Provider mods (mod-agents-openai…) and consumers (mod-chat) meet here:
4
+ * The model provider (mod-ai) and consumers (mod-chat) meet here:
5
5
  * the tool registry lives on AGENTS_SERVICE; nobody imports a provider mod
6
6
  * to find tools.
7
7
  */
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @pattern-js/mod-agents — the well-known service seam.
3
3
  *
4
- * Provider mods (mod-agents-openai…) and consumers (mod-chat) meet here:
4
+ * The model provider (mod-ai) and consumers (mod-chat) meet here:
5
5
  * the tool registry lives on AGENTS_SERVICE; nobody imports a provider mod
6
6
  * to find tools.
7
7
  */
@@ -5,16 +5,16 @@ order: 10
5
5
 
6
6
  # Authoring agent tools
7
7
 
8
- A tool is just a workflow with a `boundary.tool` trigger and a
8
+ A tool is a workflow with a `boundary.tool` trigger and a
9
9
  `boundary.tool.return` out-gate. Reach for one whenever the model needs to
10
- *do* something — look data up, call an API, change state — rather than only
11
- talk. Three things make it a good tool.
10
+ *do* something: look data up, call an API, or change state. Three things make
11
+ it a good tool.
12
12
 
13
13
  ## 1. A tight schema
14
14
 
15
15
  The trigger's `params` is a JSON Schema the **engine validates** before your
16
- graph runs — the model's arguments are checked at the door, so a hallucinated
17
- shape becomes a clean `TriggerInputError`, never a malformed value deep in
16
+ graph runs. The model's arguments are checked at the door, so a hallucinated
17
+ shape becomes a clean `TriggerInputError` before any malformed value reaches
18
18
  your logic. Be specific: required fields, enums, and descriptions (the model
19
19
  reads them to decide *when* and *how* to call).
20
20
 
@@ -42,31 +42,31 @@ calling principal). In the editor, `params` is a visual SchemaBuilder.
42
42
 
43
43
  ## 2. A real return
44
44
 
45
- Wire your result into `boundary.tool.return`'s `result` — that's exactly what
45
+ Wire your result into `boundary.tool.return`'s `result`: that's exactly what
46
46
  the model sees. Keep it small and structured; the model pays attention tokens
47
- for every field. A weather tool returns `{ tempC, summary }`, not the raw API
48
- envelope. `boundary.tool.return` is the only legal terminal for a tool
47
+ for every field. A weather tool returns `{ tempC, summary }`, the few fields
48
+ the model needs. `boundary.tool.return` is the only legal terminal for a tool
49
49
  workflow, so every branch must converge on it.
50
50
 
51
51
  ## 3. It's debuggable for free
52
52
 
53
53
  Every tool call runs as a **linked sub-run** (`ctx.invoke`). Open the agent's
54
54
  run in the admin and each invocation is a child run (↳) with its own node
55
- waterfall and sampled I/O — you see exactly what the model passed and what
55
+ waterfall and sampled I/O: you see exactly what the model passed and what
56
56
  came back. No print-debugging an opaque function.
57
57
 
58
- ## Three origins — and when to choose each
58
+ ## Three origins and when to choose each
59
59
 
60
- - **Workflow tools** — what we just built; `agents.tools.workflows` collects
60
+ - **Workflow tools**: what we just built; `agents.tools.workflows` collects
61
61
  every `boundary.tool` in the app (or a named subset). The default: visible,
62
62
  debuggable, yours. With no names it auto-includes everything *except*
63
63
  guardrail-only tools.
64
- - **MCP servers** — `agents.mcp.server` exposes an existing MCP server's tools
64
+ - **MCP servers**: `agents.mcp.client` exposes an existing MCP server's tools
65
65
  (HTTP or stdio, pooled per process). Choose this to borrow tools you don't
66
66
  want to re-implement.
67
- - **Op tools** — a mod registers plain-function tools in its setup
67
+ - **Op tools**: a mod registers plain-function tools in its setup
68
68
  (`AGENTS_SERVICE.registerOpTool`), picked by `agents.tools.ops`. Choose this
69
- for tools a mod ships as code rather than a visible workflow.
69
+ for tools a mod ships as code.
70
70
 
71
71
  Merge any combination with `agents.tools.merge` (config `count` = how many
72
72
  toolset inputs) and wire the result into `agents.agent`'s `tools` input.
@@ -77,19 +77,19 @@ Set `needsApproval: true` on the `boundary.tool` config and the agent pauses
77
77
  before the call, emitting an `approval.request` (with an opaque resume
78
78
  `stateToken`). The chat app turns that into Approve/Deny buttons;
79
79
  `agents.run.resume` continues the **same** turn with the decision. Use it for
80
- tools with side effects — sending mail, spending money, deleting rows.
80
+ tools with side effects: sending mail, spending money, deleting rows.
81
81
 
82
82
  ## Authoring a guardrail
83
83
 
84
84
  A guardrail reuses the **same** `boundary.tool` pair: a tool workflow whose
85
- `result` is `{ tripwire: boolean, info? }`. The provider calls it as an input
85
+ `result` is `{ tripwire: boolean, info? }`. The run loop calls it as an input
86
86
  or output guardrail (a linked sub-run, like any tool), and a `tripwire: true`
87
87
  ends the turn cleanly with an inline card.
88
88
 
89
89
  1. Author the classifier as a `boundary.tool` workflow. Mark it
90
- `guardrail: true` so `agents.tools.workflows` leaves it **out** of the
91
- model's callable toolbox — a moderation classifier must not become a tool
92
- the model can invoke.
90
+ `guardrail: true` so `agents.tools.workflows` keeps it **out** of the
91
+ model's callable toolbox: the classifier vets messages without becoming a
92
+ tool the model can invoke.
93
93
  2. Wrap it with `agents.guardrail` (config: `tool` = the workflow's name,
94
94
  `direction` = `input` | `output`).
95
95
  3. Wire the descriptor into `agents.agent`'s `guardrails` input (one or an
package/docs/index.md CHANGED
@@ -1,19 +1,20 @@
1
1
  # Agents (contracts)
2
2
 
3
- `@pattern-js/mod-agents` is the **neutral** agents layer — plain-JSON
4
- descriptors and the turn event protocol, with no SDK dependency. Provider
5
- mods (like `@pattern-js/mod-agents-openai`) reify the descriptors into running
6
- agents; apps (like `@pattern-js/mod-chat`) consume the events. Neither has to
7
- know about the other.
3
+ `@pattern-js/mod-agents` is the **neutral** agents layer: plain-JSON
4
+ descriptors, the turn event protocol, and the native agent run loop, with no
5
+ provider SDK. It calls a model through a neutral seam that
6
+ `@pattern-js/mod-ai` implements (the only mod that touches the AI SDK); apps
7
+ (like `@pattern-js/mod-chat`) consume the events. Each layer is decoupled.
8
8
 
9
9
  ## When to use
10
10
 
11
- Install this whenever you want agents in your app — but you never install it
12
- *alone*. It contributes the `boundary.tool` pair, the toolset/guardrail ops,
13
- and the live tool registry (`AGENTS_SERVICE`); it does **not** run an agent.
14
- Pair it with a provider (`@pattern-js/mod-agents-openai`) for `agents.agent` /
15
- `agents.run`, and usually with `@pattern-js/mod-store` (history + blobs) and
16
- `@pattern-js/mod-vault` (the API key).
11
+ Install this whenever you want agents in your app, always alongside a model
12
+ provider. It contributes the `boundary.tool` pair, the toolset/guardrail ops,
13
+ and the live tool registry (`AGENTS_SERVICE`); the run loop needs a model to
14
+ run. Pair it with `@pattern-js/mod-ai` (the model provider: it backs
15
+ `agents.run` and adds the `ai.model` node + capability ops), and usually with
16
+ `@pattern-js/mod-store` (history + blobs) and `@pattern-js/mod-vault`
17
+ (provider keys).
17
18
 
18
19
  **When not:** if all you need is a single model call with no tools, no agent
19
20
  loop, and no streaming turn events, a provider op straight from the canvas is
@@ -21,8 +22,8 @@ lighter than the agents stack. The agents layer earns its keep the moment
21
22
  there are tools, handoffs, guardrails, or a live transcript.
22
23
 
23
24
  ```jsonc
24
- // pattern.config.json — the contracts always ship with a provider
25
- { "mods": ["@pattern-js/mod-agents", "@pattern-js/mod-agents-openai"] }
25
+ // pattern.config.json: the contracts always ship with the model provider
26
+ { "mods": ["@pattern-js/mod-agents", "@pattern-js/mod-ai"] }
26
27
  ```
27
28
 
28
29
  ## Tools are workflows
@@ -30,68 +31,66 @@ there are tools, handoffs, guardrails, or a live transcript.
30
31
  A tool is a **workflow** that starts with a `boundary.tool` trigger and ends
31
32
  with `boundary.tool.return`. The trigger's config carries the `name` and
32
33
  `description` the model reads, plus a JSON-Schema `params` the **engine**
33
- validates before your graph runs — a model's hallucinated args become a clean
34
- `TriggerInputError` at the door, never a malformed value deep in your logic.
35
- That one shape also buys discovery (the registry scans for these triggers,
34
+ validates before your graph runs. A model's hallucinated args become a clean
35
+ `TriggerInputError` at the door, caught before any malformed value reaches your
36
+ logic. That one shape also buys discovery (the registry scans for these triggers,
36
37
  live) and debugging: every call is a **linked sub-run** (↳ in the Runs page,
37
38
  with sampled I/O), so the admin's run view is your agent debugger.
38
39
 
39
- ### Three tool origins — and when to choose each
40
+ ### Three tool origins and when to choose each
40
41
 
41
42
  | origin | op | reach for it when |
42
43
  | --- | --- | --- |
43
- | **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). |
44
- | **MCP server** | `agents.mcp.server` (provider mod) | you want to expose an existing MCP server's tools (HTTP or stdio) without re-implementing them. |
44
+ | **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). |
45
+ | **MCP server** | `agents.mcp.client` (mod-ai connects) | you want to call an existing MCP server's tools (HTTP or stdio) without re-implementing them. |
45
46
  | **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. |
46
47
 
47
48
  `agents.tools.workflows` with no names auto-collects every `boundary.tool` in
48
49
  the app **except** guardrail-only ones (`guardrail: true` on the trigger keeps
49
- a moderation classifier from becoming a callable tool — name it explicitly to
50
+ a moderation classifier from becoming a callable tool; name it explicitly to
50
51
  include it anyway). Combine any origins with `agents.tools.merge` (config
51
52
  `count` sets the input ports) and wire the result into `agents.agent`'s
52
53
  `tools` input.
53
54
 
54
55
  ## Guardrails reuse the tool shape
55
56
 
56
- A guardrail is the same `boundary.tool` pair by convention — a tool workflow
57
+ A guardrail is the same `boundary.tool` pair by convention: a tool workflow
57
58
  whose `result` is `{ tripwire: boolean, info? }`. `agents.guardrail` wraps a
58
59
  named tool workflow as an `input` or `output` guardrail descriptor; input
59
60
  guardrails vet the user's message before the model sees it, output guardrails
60
61
  vet the answer. A trip surfaces as an inline error card in the chat and the
61
- turn ends cleanly with the reason — never a crash. Mark the underlying tool
62
+ turn ends cleanly with the reason. Mark the underlying tool
62
63
  `guardrail: true` so it stays out of the model's callable toolbox.
63
64
 
64
65
  ## The turn event protocol
65
66
 
66
67
  A running agent emits one **modality-agnostic** stream that every surface
67
- speaks — SSE responses, the chat's persisted log, future voice surfaces:
68
+ speaks (SSE responses, the chat's persisted log, future voice surfaces):
68
69
 
69
- - `text.delta` / `text.done` — streaming text, then the settled message.
70
- - `tool.activity` — a tool's lifecycle (`start` → `done` | `error`), with an
70
+ - `text.delta` / `text.done`: streaming text, then the settled message.
71
+ - `tool.activity`: a tool's lifecycle (`start` → `done` | `error`), with an
71
72
  optional `subRunId` deep-linking into the admin.
72
- - `approval.request` — the turn paused for human approval (HITL), carrying an
73
- opaque `stateToken` only the provider mod reads.
74
- - `error` — errors are turn **content** (chats render an inline card, not a
75
- toast).
76
- - `audio.ref` — reserved for the voice round.
77
- - `done { stopReason }` — a **guaranteed** terminal event
73
+ - `approval.request`: the turn paused for human approval (HITL), carrying an
74
+ opaque `stateToken` only the run loop reads (resume with `agents.run.resume`).
75
+ - `error`: errors are turn **content**; the chat renders them as an inline card.
76
+ - `audio.ref`: reserved for the voice round.
77
+ - `done { stopReason }`: a **guaranteed** terminal event
78
78
  (`complete | interrupted | error | cancelled`), so a consumer can always
79
79
  settle.
80
80
 
81
- These are event-name constants on the wire, not ops. Descriptors and events
82
- are both plain JSON (structured-cloneable) so they flow on edges and cross
83
- worker boundaries; provider SDK objects never do — a provider mod reifies
84
- descriptors into SDK instances only at execute time.
81
+ These are event-name constants on the wire that a consumer reads. Descriptors
82
+ and events are both plain JSON (structured-cloneable), so they flow on edges and
83
+ cross worker boundaries; the AI SDK stays inside `@pattern-js/mod-ai`.
85
84
 
86
85
  ## Integration
87
86
 
88
- - **Provider** (`@pattern-js/mod-agents-openai`) — meets this mod at the
89
- `AGENTS_SERVICE` service seam: it asks the registry for tools, nobody
90
- imports a provider to find them. Reifies descriptors → SDK; emits the turn
91
- events.
92
- - **`@pattern-js/mod-store`** — history is opaque provider items pulled from a
93
- store and pushed back; image-part tools resolve blob ids through it.
94
- - **`@pattern-js/mod-chat`** — the product surface; its `chat.turn.pipeline`
87
+ - **`@pattern-js/mod-ai`**: the model provider. It implements the neutral
88
+ model-service seam this mod's run loop calls, and adds `ai.model`, the
89
+ capability ops (text/image/embed/STT/TTS/video), and the MCP client + server.
90
+ The only mod that imports the AI SDK.
91
+ - **`@pattern-js/mod-store`**: history (the loop's own neutral messages) is
92
+ pulled from a store and pushed back; image-part tools resolve blob ids through it.
93
+ - **`@pattern-js/mod-chat`**: the product surface; its `chat.turn.pipeline`
95
94
  wires `agents.tools.workflows` → `agents.agent` → `agents.run` and persists
96
95
  the event stream.
97
96
 
@@ -107,16 +106,18 @@ run → stream the response. The canvas version, end to end:
107
106
  { "id": "in", "op": "boundary.http.request", "config": { "method": "POST", "path": "/api/agent" } },
108
107
  { "id": "msg", "op": "core.object.get", "config": { "path": "message" }, "comment": "the user's text out of the body" },
109
108
  { "id": "tools", "op": "agents.tools.workflows", "comment": "every boundary.tool in the app; name a subset to narrow" },
109
+ { "id": "model", "op": "ai.model", "config": { "routing": "direct", "provider": "openai", "modelId": "gpt-5" }, "comment": "or skip this and set a default in Settings → AI Providers" },
110
110
  { "id": "agent", "op": "agents.agent", "config": { "name": "assistant", "instructions": "You are a helpful assistant." } },
111
- { "id": "run", "op": "agents.run", "comment": "streams turn events; needs an API key" },
111
+ { "id": "run", "op": "agents.run", "comment": "streams turn events; runs on the wired/default model" },
112
112
  { "id": "out", "op": "boundary.http.response" } ],
113
113
  "edges": [
114
114
  { "from": { "node": "in", "port": "body" }, "to": { "node": "msg", "port": "object" } },
115
115
  { "from": { "node": "tools", "port": "toolset" }, "to": { "node": "agent", "port": "tools" } },
116
+ { "from": { "node": "model", "port": "model" }, "to": { "node": "agent", "port": "model" } },
116
117
  { "from": { "node": "agent", "port": "agent" }, "to": { "node": "run", "port": "agent" } },
117
118
  { "from": { "node": "msg", "port": "out" }, "to": { "node": "run", "port": "input" } },
118
119
  { "from": { "node": "run", "port": "events" }, "to": { "node": "out", "port": "stream" } } ] }
119
120
  ```
120
121
 
121
122
  For the full agentic app (history, persistence, approvals, Stop), use
122
- `@pattern-js/mod-chat` — its turn pipeline is this shape, hardened.
123
+ `@pattern-js/mod-chat`. Its turn pipeline is this shape, hardened.
@@ -1,5 +1,5 @@
1
1
  Wrap a `boundary.tool` workflow (one that returns `{ tripwire, info? }`) as an
2
2
  input or output guardrail and feed it into `agents.agent`'s guardrails input.
3
- A tripped guardrail surfaces as an inline card in the chat — the run ends
4
- cleanly with the reason, never a crash. Input guardrails vet the user's
3
+ A tripped guardrail surfaces as an inline card in the chat, and the run ends
4
+ cleanly with the reason. Input guardrails vet the user's
5
5
  message before the model sees it; output guardrails vet the model's answer.
@@ -1,5 +1,5 @@
1
- Combine several toolsets into one — workflow tools (`agents.tools.workflows`),
2
- MCP servers (`agents.mcp.server`), and op tools (`agents.tools.ops`) all
1
+ Combine several toolsets into one: workflow tools (`agents.tools.workflows`),
2
+ MCP servers (`agents.mcp.client`), and op tools (`agents.tools.ops`) all
3
3
  produce toolset values, and this merges them (config `count` sets how many
4
4
  inputs). Wire the result into `agents.agent`'s tools. The three tool origins,
5
5
  one toolbox.
@@ -1,4 +1,4 @@
1
1
  Collect mod-contributed CODE tools (registered via
2
- `AGENTS_SERVICE.registerOpTool`) into a toolset — config `tools` names which
3
- to include, empty = all. The third tool origin alongside workflow tools and
4
- MCP: for tools a mod ships as plain functions rather than visible workflows.
2
+ `AGENTS_SERVICE.registerOpTool`) into a toolset. Config `tools` names which
3
+ to include; empty = all. The third tool origin alongside workflow tools and
4
+ MCP, for tools a mod ships as plain functions.
@@ -1,5 +1,5 @@
1
1
  The trigger that makes a workflow callable by agents. Config: `name`,
2
- `description`, `params` (JSON Schema — engine-validated, so your graph never
3
- sees malformed args), optional `needsApproval` for human-in-the-loop. Outputs
2
+ `description`, `params` (JSON Schema, engine-validated, so your graph only
3
+ sees validated args), optional `needsApproval` for human-in-the-loop. Outputs
4
4
  `args` (validated) + `user` (the principal). Pair with `boundary.tool.return`
5
5
  whose `result` becomes the tool's return value to the model.
@@ -1 +1 @@
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.
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 the few fields the model needs, like `{ tempC, summary }`. 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 CHANGED
@@ -1,7 +1,15 @@
1
1
  {
2
2
  "name": "@pattern-js/mod-agents",
3
- "version": "0.2.2-main.b9393c1",
4
- "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).",
3
+ "version": "0.3.0-main.4a77893",
4
+ "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-ai (the model provider).",
5
+ "keywords": [
6
+ "pattern",
7
+ "mod",
8
+ "agents",
9
+ "tools",
10
+ "mcp",
11
+ "workflow"
12
+ ],
5
13
  "type": "module",
6
14
  "license": "MIT",
7
15
  "exports": {
@@ -19,8 +27,8 @@
19
27
  ],
20
28
  "dependencies": {
21
29
  "zod": "^4.0.0",
22
- "@pattern-js/core": "0.2.2-main.b9393c1",
23
- "@pattern-js/runtime-node": "0.2.2-main.b9393c1"
30
+ "@pattern-js/core": "0.3.0-main.4a77893",
31
+ "@pattern-js/runtime-node": "0.3.0-main.4a77893"
24
32
  },
25
33
  "devDependencies": {
26
34
  "@types/node": "^22.0.0",