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