@ryuhq/sdk 0.1.14 → 0.2.2

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.
Files changed (105) hide show
  1. package/README.md +69 -7
  2. package/dist/action.cjs +839 -0
  3. package/dist/action.d.cts +88 -0
  4. package/dist/action.d.ts +88 -0
  5. package/dist/action.js +8 -0
  6. package/dist/agent-plugin.cjs +46 -0
  7. package/dist/agent-plugin.d.cts +43 -33
  8. package/dist/agent-plugin.d.ts +43 -33
  9. package/dist/agent-plugin.js +1 -1
  10. package/dist/agent.cjs +16 -0
  11. package/dist/agent.d.cts +377 -1
  12. package/dist/agent.d.ts +377 -1
  13. package/dist/agent.js +4 -2
  14. package/dist/app-B0Z9Ew_R.d.cts +141 -0
  15. package/dist/app-C-BDJwfG.d.ts +141 -0
  16. package/dist/builder.cjs +1194 -0
  17. package/dist/builder.d.cts +217 -0
  18. package/dist/builder.d.ts +217 -0
  19. package/dist/builder.js +29 -0
  20. package/dist/chunk-4TPUZDTI.js +94 -0
  21. package/dist/chunk-BC3A7HMO.js +164 -0
  22. package/dist/chunk-FZSFZOIN.js +200 -0
  23. package/dist/{chunk-ODFEUVPW.js → chunk-HACAGK65.js} +1 -18
  24. package/dist/chunk-HLKJZAFK.js +361 -0
  25. package/dist/chunk-IKEDLLFY.js +19 -0
  26. package/dist/{chunk-G6FLVEC4.js → chunk-JX6DDRXV.js} +46 -0
  27. package/dist/{chunk-AO2KJRDD.js → chunk-NZKVOSC2.js} +192 -3
  28. package/dist/chunk-QYFUNJOH.js +83 -0
  29. package/dist/chunk-SN2QBJUF.js +148 -0
  30. package/dist/chunk-TLDPEGC7.js +21 -0
  31. package/dist/chunk-TXSHHZF2.js +0 -0
  32. package/dist/chunk-VLIRNNAE.js +154 -0
  33. package/dist/{chunk-MTUBUPIV.js → chunk-Z57QDDJR.js} +8 -227
  34. package/dist/chunk-ZTJWBRUL.js +282 -0
  35. package/dist/cli.cjs +347 -18
  36. package/dist/cli.js +128 -23
  37. package/dist/client-D5U6ssPc.d.cts +84 -0
  38. package/dist/client-D5U6ssPc.d.ts +84 -0
  39. package/dist/index.cjs +810 -86
  40. package/dist/index.d.cts +19 -634
  41. package/dist/index.d.ts +19 -634
  42. package/dist/index.js +82 -699
  43. package/dist/manifest.cjs +200 -4
  44. package/dist/manifest.d.cts +260 -5
  45. package/dist/manifest.d.ts +260 -5
  46. package/dist/manifest.js +15 -1
  47. package/dist/mcp/client.cjs +180 -0
  48. package/dist/mcp/client.d.cts +49 -0
  49. package/dist/mcp/client.d.ts +49 -0
  50. package/dist/mcp/client.js +10 -0
  51. package/dist/mcp/server.cjs +370 -0
  52. package/dist/mcp/server.d.cts +127 -0
  53. package/dist/mcp/server.d.ts +127 -0
  54. package/dist/mcp/server.js +9 -0
  55. package/dist/mcp.cjs +376 -0
  56. package/dist/mcp.d.cts +2 -0
  57. package/dist/mcp.d.ts +2 -0
  58. package/dist/mcp.js +17 -0
  59. package/dist/model.cjs +141 -0
  60. package/dist/model.d.cts +33 -0
  61. package/dist/model.d.ts +33 -0
  62. package/dist/model.js +18 -0
  63. package/dist/plugin.cjs +46 -0
  64. package/dist/plugin.d.cts +215 -0
  65. package/dist/plugin.d.ts +215 -0
  66. package/dist/plugin.js +8 -0
  67. package/dist/runnable.cjs +1438 -0
  68. package/dist/runnable.d.cts +274 -0
  69. package/dist/runnable.d.ts +274 -0
  70. package/dist/runnable.js +34 -0
  71. package/dist/{index-B6SkaAjJ.d.ts → tool-AjkdFvhE.d.ts} +88 -461
  72. package/dist/{index-BvAB5eMk.d.cts → tool-CgzW92O_.d.cts} +88 -461
  73. package/package.json +48 -3
  74. package/src/agent/loop.test.ts +4 -4
  75. package/src/agent/tools.ts +3 -3
  76. package/src/agent-plugin.test.ts +58 -0
  77. package/src/agent-plugin.ts +109 -36
  78. package/src/builder.ts +9 -0
  79. package/src/cli/dev.test.ts +26 -47
  80. package/src/cli/dev.ts +10 -2
  81. package/src/cli-security.test.ts +109 -0
  82. package/src/cli.ts +141 -25
  83. package/src/contracts-lockstep.test.ts +16 -2
  84. package/src/exports-lockstep.test.ts +93 -0
  85. package/src/generated/plugin-manifest.ts +322 -29
  86. package/src/index.ts +53 -0
  87. package/src/manifest-schema.test.ts +30 -1
  88. package/src/manifest.fixtures.test.ts +22 -6
  89. package/src/manifest.test.ts +165 -10
  90. package/src/manifest.ts +454 -188
  91. package/src/mcp/index.ts +18 -0
  92. package/src/mcp/server.ts +2 -1
  93. package/src/model/index.ts +22 -0
  94. package/src/plugin/ryu-plugin.ts +82 -0
  95. package/src/runnable/action.test.ts +128 -0
  96. package/src/runnable/action.ts +202 -0
  97. package/src/runnable/app.test.ts +2 -0
  98. package/src/runnable/app.ts +50 -14
  99. package/src/runnable/index.ts +20 -3
  100. package/src/runnable/primitives.test.ts +34 -0
  101. package/src/runnable/primitives.ts +116 -0
  102. package/src/runnable/runnable-types.ts +3 -0
  103. package/src/runnable/tool.ts +36 -5
  104. package/src/runnable/turn-hook.ts +8 -3
  105. package/src/slash-command.test.ts +69 -0
@@ -0,0 +1,274 @@
1
+ export { ActionAnnotations, ActionEffect, ActionManifestOptions, ActionOptions, ActionRunnable, defineAction } from './action.cjs';
2
+ import { CapabilityReq, PluginManifest } from './manifest.cjs';
3
+ import { j as Runnable, k as RunnableContext } from './tool-CgzW92O_.cjs';
4
+ export { B as BackgroundClient, a as BackgroundProcess, D as DurableClient, E as EnginesClient, G as GatewayClient, H as HttpPrimitiveTransportOptions, I as ImageClient, b as InlineToolManifestOptions, J as JsonSchemaProperty, M as MemoryClient, c as MemoryItem, P as PRIMITIVE_BINDINGS, d as PrimitiveBinding, e as PrimitiveTransport, R as RagChunk, f as RagClient, g as RagRerankResult, h as RealtimeClient, i as RealtimeSubscription, l as RyuPrimitives, S as StorageClient, m as SttClient, n as ToolOptions, o as ToolSchema, p as TtsClient, q as createPrimitives, r as defineTool, s as httpPrimitiveTransport } from './tool-CgzW92O_.cjs';
5
+ export { A as AppToolSpec, a as DefineAppOptions, b as appToolId, d as defineApp } from './app-B0Z9Ew_R.cjs';
6
+ import './mcp/server.cjs';
7
+ import './mcp/client.cjs';
8
+ import 'zod';
9
+ import './client-D5U6ssPc.cjs';
10
+
11
+ /**
12
+ * defineAgent — factory for Runnable agents.
13
+ *
14
+ * An agent is a Runnable that drives a multi-turn model loop. It may reference a
15
+ * workflow as a named tool by including a Runnable with kind="workflow" in its
16
+ * `tools` list; the agent's run() implementation calls it like any other tool.
17
+ *
18
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
19
+ *
20
+ * ## Composable primitive slots (the "Pokémon card" model, program §6b)
21
+ *
22
+ * `defineAgent` additionally accepts swappable-provider SLOTS —
23
+ * `defineAgent({ chat, rag, memory, tools, tts, stt })` — where each slot picks
24
+ * a provider for one attribute of the card. They **lower** to the manifest:
25
+ * - `chat` → the agent `RunnableMeta.config` (model / engine / persona);
26
+ * - `rag` / `memory` / `tts` / `stt` → `requires.capabilities` edges the
27
+ * capability broker binds to a provider (with an optional explicit override);
28
+ * - `tools` → the tool ids the agent exposes.
29
+ *
30
+ * The slots are ADDITIVE: the classic `defineAgent({ id, name, run })` signature
31
+ * is unchanged. When `run` is omitted, a thin default run drives the `chat` slot
32
+ * through `ctx.gateway` (never a direct provider).
33
+ */
34
+
35
+ /**
36
+ * A capability-backed slot (rag / memory / tts / stt). Written as:
37
+ * - `true` — require the capability; the broker/registry picks the provider;
38
+ * - `"com.acme.graphrag"` — bind this explicit provider app id;
39
+ * - `{ provider?, minVersion? }` — provider override and/or a version floor.
40
+ */
41
+ type CapabilitySlot = boolean | string | {
42
+ provider?: string;
43
+ minVersion?: string;
44
+ };
45
+ /**
46
+ * The chat/model slot — the agent's own, swappable model config. Written as a
47
+ * model-id string shorthand or the full object. Every field is a `string`; no
48
+ * provider union, so a new provider never needs an SDK change.
49
+ */
50
+ type ChatSlot = string | {
51
+ /** Model id (swappable). */
52
+ model?: string;
53
+ /** Engine id (e.g. `"llamacpp"`, `"openai-compat"`). */
54
+ engine?: string;
55
+ /** System persona / instructions. */
56
+ persona?: string;
57
+ /** Preference key Core resolves to a model id (swappable, not hardcoded). */
58
+ modelPrefKey?: string;
59
+ };
60
+ /** The composable slots an agent card declares. All optional. */
61
+ interface AgentSlots {
62
+ /** The chat/model slot (model + engine + persona). */
63
+ chat?: ChatSlot;
64
+ /** Memory provider slot → `requires.capabilities: [{ capability: "memory" }]`. */
65
+ memory?: CapabilitySlot;
66
+ /** RAG provider slot → `requires.capabilities: [{ capability: "rag" }]`. */
67
+ rag?: CapabilitySlot;
68
+ /** STT provider slot → `requires.capabilities: [{ capability: "stt" }]`. */
69
+ stt?: CapabilitySlot;
70
+ /** Tools the agent exposes — Runnables (workflows/tools) or bare tool ids. */
71
+ tools?: readonly (Runnable | string)[];
72
+ /** TTS provider slot → `requires.capabilities: [{ capability: "tts" }]`. */
73
+ tts?: CapabilitySlot;
74
+ }
75
+ /** Options accepted by `defineAgent`. */
76
+ interface AgentOptions<TInput, TOutput> extends AgentSlots {
77
+ /** Stable unique identifier (e.g. "agent-researcher"). */
78
+ id: string;
79
+ /** Human-readable display name. */
80
+ name: string;
81
+ /**
82
+ * The agent's run implementation. OPTIONAL when slots are declared — a
83
+ * `chat`-slot default is synthesized (drives `ctx.gateway`). All model calls
84
+ * MUST go through `ctx.gateway`.
85
+ */
86
+ run?(input: TInput, ctx: RunnableContext): Promise<TOutput>;
87
+ }
88
+ /**
89
+ * The lowered "card": the swappable slots resolved to manifest-ready pieces —
90
+ * the persona/model config plus the `requires.capabilities` edges. This is what
91
+ * makes the Pokémon-card model literal in code.
92
+ */
93
+ interface AgentCard {
94
+ /** Lowered capability edges for `requires.capabilities`. */
95
+ capabilities: CapabilityReq[];
96
+ /** Engine id from the `chat` slot. */
97
+ engine?: string;
98
+ /** Model id from the `chat` slot. */
99
+ model?: string;
100
+ /** Preference key from the `chat` slot. */
101
+ modelPrefKey?: string;
102
+ /** Persona/instructions from the `chat` slot. */
103
+ persona?: string;
104
+ /** Explicit provider bindings by capability (a slot that named a provider). */
105
+ providers: Record<string, string>;
106
+ /** Tool ids the agent exposes. */
107
+ tools: string[];
108
+ }
109
+ /** A defined agent: a Runnable plus its lowered card + a manifest lowering. */
110
+ interface AgentRunnable<TInput = unknown, TOutput = unknown> extends Runnable<TInput, TOutput> {
111
+ /** The lowered slot card (empty edges when no slots were declared). */
112
+ readonly card: AgentCard;
113
+ /**
114
+ * Lower this agent (card + run identity) to a single-agent `manifest.json`
115
+ * `PluginManifest`: the agent `RunnableMeta` carries the persona/model
116
+ * config; `requires.capabilities` carries the slot edges. Throws if the
117
+ * assembled manifest is invalid.
118
+ */
119
+ toManifest(options: AgentManifestOptions): PluginManifest;
120
+ }
121
+ /** Options for {@link AgentRunnable.toManifest}. */
122
+ interface AgentManifestOptions {
123
+ /** Extra permission grants beyond those implied by slots. */
124
+ grants?: string[];
125
+ /** Reverse-domain plugin id (e.g. `"com.acme.researcher"`). */
126
+ id: string;
127
+ /** Display name (defaults to the agent's name). */
128
+ name?: string;
129
+ /** Semver version (e.g. `"1.0.0"`). */
130
+ version: string;
131
+ }
132
+ /**
133
+ * Create a Runnable agent.
134
+ *
135
+ * The returned value satisfies `Runnable<TInput, TOutput>` with `kind = "agent"`
136
+ * and additionally exposes the lowered {@link AgentCard} + a `toManifest()`
137
+ * lowering, so a slot-composed agent round-trips to a valid `manifest.json`.
138
+ *
139
+ * @example Classic (unchanged, back-compat):
140
+ * ```ts
141
+ * const a = defineAgent({
142
+ * id: "agent-researcher",
143
+ * name: "Researcher",
144
+ * async run({ query }, ctx) {
145
+ * const r = await ctx.gateway.chat([{ role: "user", content: query }]);
146
+ * return { answer: r.content };
147
+ * },
148
+ * });
149
+ * ```
150
+ *
151
+ * @example Composable slots (the Pokémon card):
152
+ * ```ts
153
+ * const cmo = defineAgent({
154
+ * id: "agent-cmo",
155
+ * name: "CMO",
156
+ * chat: { model: "gpt-4o", persona: "You are a CMO." },
157
+ * rag: true, // requires.capabilities: [{ capability: "rag" }]
158
+ * memory: { minVersion: "1.2" },
159
+ * tts: "com.acme.elevenlabs", // explicit provider override
160
+ * });
161
+ * const manifest = cmo.toManifest({ id: "com.acme.cmo", version: "1.0.0" });
162
+ * ```
163
+ */
164
+ declare function defineAgent<TInput = unknown, TOutput = unknown>(options: AgentOptions<TInput, TOutput>): AgentRunnable<TInput, TOutput>;
165
+
166
+ /**
167
+ * defineSkill — factory for Runnable skills.
168
+ *
169
+ * A skill is a prompt-template / capability block that is reusable across
170
+ * agents and workflows. Like a tool it is stateless, but its primary purpose
171
+ * is to encapsulate a reusable prompt pattern rather than a side-effectful
172
+ * function.
173
+ *
174
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
175
+ */
176
+
177
+ /** Options accepted by `defineSkill`. */
178
+ interface SkillOptions<TInput, TOutput> {
179
+ /** Stable unique identifier (e.g. "skill-summarise"). */
180
+ id: string;
181
+ /** Human-readable display name. */
182
+ name: string;
183
+ /**
184
+ * The skill's run implementation.
185
+ *
186
+ * Skills typically build a prompt from `input` and call `ctx.gateway.chat()`
187
+ * to get a model response, then return structured output. All model calls
188
+ * MUST go through `ctx.gateway`.
189
+ */
190
+ run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
191
+ }
192
+ /**
193
+ * Create a Runnable skill.
194
+ *
195
+ * The returned value satisfies the `Runnable<TInput, TOutput>` interface with
196
+ * `kind = "skill"`.
197
+ *
198
+ * @example
199
+ * ```ts
200
+ * const summariseSkill = defineSkill({
201
+ * id: "skill-summarise",
202
+ * name: "Summarise",
203
+ * async run({ text }, ctx) {
204
+ * const result = await ctx.gateway.chat([
205
+ * { role: "user", content: `Summarise the following:\n\n${text}` },
206
+ * ]);
207
+ * return { summary: result.content };
208
+ * },
209
+ * });
210
+ * ```
211
+ */
212
+ declare function defineSkill<TInput = unknown, TOutput = unknown>(options: SkillOptions<TInput, TOutput>): Runnable<TInput, TOutput>;
213
+
214
+ /**
215
+ * defineWorkflow — factory for Runnable workflows.
216
+ *
217
+ * A workflow orchestrates agents (and other Runnables) as sequential steps.
218
+ * It exposes the peer relationship described in packages/sdk/README.md §2:
219
+ * a workflow may list an agent as a step and call it via its run() method.
220
+ *
221
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
222
+ */
223
+
224
+ /**
225
+ * A single step inside a workflow definition.
226
+ *
227
+ * A step is any `Runnable` — most commonly an agent, but may also be a tool
228
+ * or a nested workflow (allowing composition without a strict hierarchy).
229
+ */
230
+ type WorkflowStep<TStepInput = unknown, TStepOutput = unknown> = Runnable<TStepInput, TStepOutput>;
231
+ /** Options accepted by `defineWorkflow`. */
232
+ interface WorkflowOptions<TInput, TOutput> {
233
+ /** Stable unique identifier (e.g. "workflow-report"). */
234
+ id: string;
235
+ /** Human-readable display name. */
236
+ name: string;
237
+ /**
238
+ * The workflow's run implementation.
239
+ *
240
+ * May call any step via `step.run(input, ctx)`. All model calls that
241
+ * steps make MUST go through `ctx.gateway`.
242
+ */
243
+ run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
244
+ /**
245
+ * Optional list of Runnables this workflow orchestrates as steps.
246
+ *
247
+ * An agent may be listed here so the workflow can invoke it by calling
248
+ * `step.run(input, ctx)` — this is the peer relationship described in
249
+ * packages/sdk/README.md §2.
250
+ */
251
+ steps?: readonly Runnable[];
252
+ }
253
+ /**
254
+ * Create a Runnable workflow.
255
+ *
256
+ * The returned value satisfies the `Runnable<TInput, TOutput>` interface with
257
+ * `kind = "workflow"`.
258
+ *
259
+ * @example
260
+ * ```ts
261
+ * const myWorkflow = defineWorkflow({
262
+ * id: "workflow-report",
263
+ * name: "Report Workflow",
264
+ * steps: [researchAgent],
265
+ * async run({ topic }, ctx) {
266
+ * const { answer } = await researchAgent.run({ query: topic }, ctx);
267
+ * return { report: answer };
268
+ * },
269
+ * });
270
+ * ```
271
+ */
272
+ declare function defineWorkflow<TInput = unknown, TOutput = unknown>(options: WorkflowOptions<TInput, TOutput>): Runnable<TInput, TOutput>;
273
+
274
+ export { type AgentCard, type AgentManifestOptions, type AgentOptions, type AgentRunnable, type AgentSlots, type CapabilitySlot, type ChatSlot, Runnable, RunnableContext, type SkillOptions, type WorkflowOptions, type WorkflowStep, defineAgent, defineSkill, defineWorkflow };
@@ -0,0 +1,274 @@
1
+ export { ActionAnnotations, ActionEffect, ActionManifestOptions, ActionOptions, ActionRunnable, defineAction } from './action.js';
2
+ import { CapabilityReq, PluginManifest } from './manifest.js';
3
+ import { j as Runnable, k as RunnableContext } from './tool-AjkdFvhE.js';
4
+ export { B as BackgroundClient, a as BackgroundProcess, D as DurableClient, E as EnginesClient, G as GatewayClient, H as HttpPrimitiveTransportOptions, I as ImageClient, b as InlineToolManifestOptions, J as JsonSchemaProperty, M as MemoryClient, c as MemoryItem, P as PRIMITIVE_BINDINGS, d as PrimitiveBinding, e as PrimitiveTransport, R as RagChunk, f as RagClient, g as RagRerankResult, h as RealtimeClient, i as RealtimeSubscription, l as RyuPrimitives, S as StorageClient, m as SttClient, n as ToolOptions, o as ToolSchema, p as TtsClient, q as createPrimitives, r as defineTool, s as httpPrimitiveTransport } from './tool-AjkdFvhE.js';
5
+ export { A as AppToolSpec, a as DefineAppOptions, b as appToolId, d as defineApp } from './app-C-BDJwfG.js';
6
+ import './mcp/server.js';
7
+ import './mcp/client.js';
8
+ import 'zod';
9
+ import './client-D5U6ssPc.js';
10
+
11
+ /**
12
+ * defineAgent — factory for Runnable agents.
13
+ *
14
+ * An agent is a Runnable that drives a multi-turn model loop. It may reference a
15
+ * workflow as a named tool by including a Runnable with kind="workflow" in its
16
+ * `tools` list; the agent's run() implementation calls it like any other tool.
17
+ *
18
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
19
+ *
20
+ * ## Composable primitive slots (the "Pokémon card" model, program §6b)
21
+ *
22
+ * `defineAgent` additionally accepts swappable-provider SLOTS —
23
+ * `defineAgent({ chat, rag, memory, tools, tts, stt })` — where each slot picks
24
+ * a provider for one attribute of the card. They **lower** to the manifest:
25
+ * - `chat` → the agent `RunnableMeta.config` (model / engine / persona);
26
+ * - `rag` / `memory` / `tts` / `stt` → `requires.capabilities` edges the
27
+ * capability broker binds to a provider (with an optional explicit override);
28
+ * - `tools` → the tool ids the agent exposes.
29
+ *
30
+ * The slots are ADDITIVE: the classic `defineAgent({ id, name, run })` signature
31
+ * is unchanged. When `run` is omitted, a thin default run drives the `chat` slot
32
+ * through `ctx.gateway` (never a direct provider).
33
+ */
34
+
35
+ /**
36
+ * A capability-backed slot (rag / memory / tts / stt). Written as:
37
+ * - `true` — require the capability; the broker/registry picks the provider;
38
+ * - `"com.acme.graphrag"` — bind this explicit provider app id;
39
+ * - `{ provider?, minVersion? }` — provider override and/or a version floor.
40
+ */
41
+ type CapabilitySlot = boolean | string | {
42
+ provider?: string;
43
+ minVersion?: string;
44
+ };
45
+ /**
46
+ * The chat/model slot — the agent's own, swappable model config. Written as a
47
+ * model-id string shorthand or the full object. Every field is a `string`; no
48
+ * provider union, so a new provider never needs an SDK change.
49
+ */
50
+ type ChatSlot = string | {
51
+ /** Model id (swappable). */
52
+ model?: string;
53
+ /** Engine id (e.g. `"llamacpp"`, `"openai-compat"`). */
54
+ engine?: string;
55
+ /** System persona / instructions. */
56
+ persona?: string;
57
+ /** Preference key Core resolves to a model id (swappable, not hardcoded). */
58
+ modelPrefKey?: string;
59
+ };
60
+ /** The composable slots an agent card declares. All optional. */
61
+ interface AgentSlots {
62
+ /** The chat/model slot (model + engine + persona). */
63
+ chat?: ChatSlot;
64
+ /** Memory provider slot → `requires.capabilities: [{ capability: "memory" }]`. */
65
+ memory?: CapabilitySlot;
66
+ /** RAG provider slot → `requires.capabilities: [{ capability: "rag" }]`. */
67
+ rag?: CapabilitySlot;
68
+ /** STT provider slot → `requires.capabilities: [{ capability: "stt" }]`. */
69
+ stt?: CapabilitySlot;
70
+ /** Tools the agent exposes — Runnables (workflows/tools) or bare tool ids. */
71
+ tools?: readonly (Runnable | string)[];
72
+ /** TTS provider slot → `requires.capabilities: [{ capability: "tts" }]`. */
73
+ tts?: CapabilitySlot;
74
+ }
75
+ /** Options accepted by `defineAgent`. */
76
+ interface AgentOptions<TInput, TOutput> extends AgentSlots {
77
+ /** Stable unique identifier (e.g. "agent-researcher"). */
78
+ id: string;
79
+ /** Human-readable display name. */
80
+ name: string;
81
+ /**
82
+ * The agent's run implementation. OPTIONAL when slots are declared — a
83
+ * `chat`-slot default is synthesized (drives `ctx.gateway`). All model calls
84
+ * MUST go through `ctx.gateway`.
85
+ */
86
+ run?(input: TInput, ctx: RunnableContext): Promise<TOutput>;
87
+ }
88
+ /**
89
+ * The lowered "card": the swappable slots resolved to manifest-ready pieces —
90
+ * the persona/model config plus the `requires.capabilities` edges. This is what
91
+ * makes the Pokémon-card model literal in code.
92
+ */
93
+ interface AgentCard {
94
+ /** Lowered capability edges for `requires.capabilities`. */
95
+ capabilities: CapabilityReq[];
96
+ /** Engine id from the `chat` slot. */
97
+ engine?: string;
98
+ /** Model id from the `chat` slot. */
99
+ model?: string;
100
+ /** Preference key from the `chat` slot. */
101
+ modelPrefKey?: string;
102
+ /** Persona/instructions from the `chat` slot. */
103
+ persona?: string;
104
+ /** Explicit provider bindings by capability (a slot that named a provider). */
105
+ providers: Record<string, string>;
106
+ /** Tool ids the agent exposes. */
107
+ tools: string[];
108
+ }
109
+ /** A defined agent: a Runnable plus its lowered card + a manifest lowering. */
110
+ interface AgentRunnable<TInput = unknown, TOutput = unknown> extends Runnable<TInput, TOutput> {
111
+ /** The lowered slot card (empty edges when no slots were declared). */
112
+ readonly card: AgentCard;
113
+ /**
114
+ * Lower this agent (card + run identity) to a single-agent `manifest.json`
115
+ * `PluginManifest`: the agent `RunnableMeta` carries the persona/model
116
+ * config; `requires.capabilities` carries the slot edges. Throws if the
117
+ * assembled manifest is invalid.
118
+ */
119
+ toManifest(options: AgentManifestOptions): PluginManifest;
120
+ }
121
+ /** Options for {@link AgentRunnable.toManifest}. */
122
+ interface AgentManifestOptions {
123
+ /** Extra permission grants beyond those implied by slots. */
124
+ grants?: string[];
125
+ /** Reverse-domain plugin id (e.g. `"com.acme.researcher"`). */
126
+ id: string;
127
+ /** Display name (defaults to the agent's name). */
128
+ name?: string;
129
+ /** Semver version (e.g. `"1.0.0"`). */
130
+ version: string;
131
+ }
132
+ /**
133
+ * Create a Runnable agent.
134
+ *
135
+ * The returned value satisfies `Runnable<TInput, TOutput>` with `kind = "agent"`
136
+ * and additionally exposes the lowered {@link AgentCard} + a `toManifest()`
137
+ * lowering, so a slot-composed agent round-trips to a valid `manifest.json`.
138
+ *
139
+ * @example Classic (unchanged, back-compat):
140
+ * ```ts
141
+ * const a = defineAgent({
142
+ * id: "agent-researcher",
143
+ * name: "Researcher",
144
+ * async run({ query }, ctx) {
145
+ * const r = await ctx.gateway.chat([{ role: "user", content: query }]);
146
+ * return { answer: r.content };
147
+ * },
148
+ * });
149
+ * ```
150
+ *
151
+ * @example Composable slots (the Pokémon card):
152
+ * ```ts
153
+ * const cmo = defineAgent({
154
+ * id: "agent-cmo",
155
+ * name: "CMO",
156
+ * chat: { model: "gpt-4o", persona: "You are a CMO." },
157
+ * rag: true, // requires.capabilities: [{ capability: "rag" }]
158
+ * memory: { minVersion: "1.2" },
159
+ * tts: "com.acme.elevenlabs", // explicit provider override
160
+ * });
161
+ * const manifest = cmo.toManifest({ id: "com.acme.cmo", version: "1.0.0" });
162
+ * ```
163
+ */
164
+ declare function defineAgent<TInput = unknown, TOutput = unknown>(options: AgentOptions<TInput, TOutput>): AgentRunnable<TInput, TOutput>;
165
+
166
+ /**
167
+ * defineSkill — factory for Runnable skills.
168
+ *
169
+ * A skill is a prompt-template / capability block that is reusable across
170
+ * agents and workflows. Like a tool it is stateless, but its primary purpose
171
+ * is to encapsulate a reusable prompt pattern rather than a side-effectful
172
+ * function.
173
+ *
174
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
175
+ */
176
+
177
+ /** Options accepted by `defineSkill`. */
178
+ interface SkillOptions<TInput, TOutput> {
179
+ /** Stable unique identifier (e.g. "skill-summarise"). */
180
+ id: string;
181
+ /** Human-readable display name. */
182
+ name: string;
183
+ /**
184
+ * The skill's run implementation.
185
+ *
186
+ * Skills typically build a prompt from `input` and call `ctx.gateway.chat()`
187
+ * to get a model response, then return structured output. All model calls
188
+ * MUST go through `ctx.gateway`.
189
+ */
190
+ run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
191
+ }
192
+ /**
193
+ * Create a Runnable skill.
194
+ *
195
+ * The returned value satisfies the `Runnable<TInput, TOutput>` interface with
196
+ * `kind = "skill"`.
197
+ *
198
+ * @example
199
+ * ```ts
200
+ * const summariseSkill = defineSkill({
201
+ * id: "skill-summarise",
202
+ * name: "Summarise",
203
+ * async run({ text }, ctx) {
204
+ * const result = await ctx.gateway.chat([
205
+ * { role: "user", content: `Summarise the following:\n\n${text}` },
206
+ * ]);
207
+ * return { summary: result.content };
208
+ * },
209
+ * });
210
+ * ```
211
+ */
212
+ declare function defineSkill<TInput = unknown, TOutput = unknown>(options: SkillOptions<TInput, TOutput>): Runnable<TInput, TOutput>;
213
+
214
+ /**
215
+ * defineWorkflow — factory for Runnable workflows.
216
+ *
217
+ * A workflow orchestrates agents (and other Runnables) as sequential steps.
218
+ * It exposes the peer relationship described in packages/sdk/README.md §2:
219
+ * a workflow may list an agent as a step and call it via its run() method.
220
+ *
221
+ * All model calls must go through `ctx.gateway` — no direct provider imports.
222
+ */
223
+
224
+ /**
225
+ * A single step inside a workflow definition.
226
+ *
227
+ * A step is any `Runnable` — most commonly an agent, but may also be a tool
228
+ * or a nested workflow (allowing composition without a strict hierarchy).
229
+ */
230
+ type WorkflowStep<TStepInput = unknown, TStepOutput = unknown> = Runnable<TStepInput, TStepOutput>;
231
+ /** Options accepted by `defineWorkflow`. */
232
+ interface WorkflowOptions<TInput, TOutput> {
233
+ /** Stable unique identifier (e.g. "workflow-report"). */
234
+ id: string;
235
+ /** Human-readable display name. */
236
+ name: string;
237
+ /**
238
+ * The workflow's run implementation.
239
+ *
240
+ * May call any step via `step.run(input, ctx)`. All model calls that
241
+ * steps make MUST go through `ctx.gateway`.
242
+ */
243
+ run(input: TInput, ctx: RunnableContext): Promise<TOutput>;
244
+ /**
245
+ * Optional list of Runnables this workflow orchestrates as steps.
246
+ *
247
+ * An agent may be listed here so the workflow can invoke it by calling
248
+ * `step.run(input, ctx)` — this is the peer relationship described in
249
+ * packages/sdk/README.md §2.
250
+ */
251
+ steps?: readonly Runnable[];
252
+ }
253
+ /**
254
+ * Create a Runnable workflow.
255
+ *
256
+ * The returned value satisfies the `Runnable<TInput, TOutput>` interface with
257
+ * `kind = "workflow"`.
258
+ *
259
+ * @example
260
+ * ```ts
261
+ * const myWorkflow = defineWorkflow({
262
+ * id: "workflow-report",
263
+ * name: "Report Workflow",
264
+ * steps: [researchAgent],
265
+ * async run({ topic }, ctx) {
266
+ * const { answer } = await researchAgent.run({ query: topic }, ctx);
267
+ * return { report: answer };
268
+ * },
269
+ * });
270
+ * ```
271
+ */
272
+ declare function defineWorkflow<TInput = unknown, TOutput = unknown>(options: WorkflowOptions<TInput, TOutput>): Runnable<TInput, TOutput>;
273
+
274
+ export { type AgentCard, type AgentManifestOptions, type AgentOptions, type AgentRunnable, type AgentSlots, type CapabilitySlot, type ChatSlot, Runnable, RunnableContext, type SkillOptions, type WorkflowOptions, type WorkflowStep, defineAgent, defineSkill, defineWorkflow };
@@ -0,0 +1,34 @@
1
+ import {
2
+ defineAgent,
3
+ defineSkill,
4
+ defineWorkflow
5
+ } from "./chunk-BC3A7HMO.js";
6
+ import {
7
+ appToolId,
8
+ defineApp
9
+ } from "./chunk-SN2QBJUF.js";
10
+ import {
11
+ PRIMITIVE_BINDINGS,
12
+ createPrimitives,
13
+ httpPrimitiveTransport
14
+ } from "./chunk-ZTJWBRUL.js";
15
+ import {
16
+ defineAction
17
+ } from "./chunk-4TPUZDTI.js";
18
+ import {
19
+ defineTool
20
+ } from "./chunk-QYFUNJOH.js";
21
+ import "./chunk-NZKVOSC2.js";
22
+ import "./chunk-IKEDLLFY.js";
23
+ export {
24
+ PRIMITIVE_BINDINGS,
25
+ appToolId,
26
+ createPrimitives,
27
+ defineAction,
28
+ defineAgent,
29
+ defineApp,
30
+ defineSkill,
31
+ defineTool,
32
+ defineWorkflow,
33
+ httpPrimitiveTransport
34
+ };