History

wip core sdk

Rhys Sullivan committed 7 months ago

Commit 646d6d21 parent cfcca4516 files · +1493 −0Browse files

Unified · Split

16 files
  1. bun.lock +16 −0
  2. packages/core/sdk/package.json +20 −0
  3. packages/core/sdk/src/elicitation.ts +78 −0
  4. packages/core/sdk/src/errors.ts +36 −0
  5. packages/core/sdk/src/executor.ts +170 −0
  6. packages/core/sdk/src/ids.ts +13 −0
  7. packages/core/sdk/src/index.test.ts +414 −0
  8. packages/core/sdk/src/index.ts +70 −0
  9. packages/core/sdk/src/plugin.ts +73 −0
  10. packages/core/sdk/src/plugins/memory.ts +205 −0
  11. packages/core/sdk/src/policies.ts +35 −0
  12. packages/core/sdk/src/scope.ts +10 −0
  13. packages/core/sdk/src/secrets.ts +34 −0
  14. packages/core/sdk/src/testing.ts +192 −0
  15. packages/core/sdk/src/tools.ts +106 −0
  16. packages/core/sdk/tsconfig.json +21 −0
bun.lock+16−0
@@ -11,6 +11,18 @@ · 10 unmodified lines
11 "typescript": "^5.9.3",11 "typescript": "^5.9.3",
12 },12 },
13 },13 },
14 "packages/core/sdk": {
15 "name": "@executor/sdk",
16 "version": "0.0.1",
17 "dependencies": {
18 "effect": "catalog:",
19 },
20 "devDependencies": {
21 "@effect/vitest": "catalog:",
22 "typescript": "latest",
23 "vitest": "catalog:",
24 },
25 },
14 "packages/kernel/core": {26 "packages/kernel/core": {
15 "name": "@executor/codemode-core",27 "name": "@executor/codemode-core",
16 "version": "0.0.0",28 "version": "0.0.0",
@@ -155,6 +167,8 @@ · 138 unmodified lines
155 167
156 "@executor/runtime-quickjs": ["@executor/runtime-quickjs@workspace:packages/kernel/runtime-quickjs"],168 "@executor/runtime-quickjs": ["@executor/runtime-quickjs@workspace:packages/kernel/runtime-quickjs"],
157 169
170 "@executor/sdk": ["@executor/sdk@workspace:packages/core/sdk"],
171
158 "@jitl/quickjs-ffi-types": ["@jitl/quickjs-ffi-types@0.31.0", "", {}, "sha512-1yrgvXlmXH2oNj3eFTrkwacGJbmM0crwipA3ohCrjv52gBeDaD7PsTvFYinlAnqU8iPME3LGP437yk05a2oejw=="],172 "@jitl/quickjs-ffi-types": ["@jitl/quickjs-ffi-types@0.31.0", "", {}, "sha512-1yrgvXlmXH2oNj3eFTrkwacGJbmM0crwipA3ohCrjv52gBeDaD7PsTvFYinlAnqU8iPME3LGP437yk05a2oejw=="],
159 173
160 "@jitl/quickjs-wasmfile-debug-asyncify": ["@jitl/quickjs-wasmfile-debug-asyncify@0.31.0", "", { "dependencies": { "@jitl/quickjs-ffi-types": "0.31.0" } }, "sha512-YkdzQdr1uaftFhgEnTRjTTZHk2SFZdpWO7XhOmRVbi6CEVsH9g5oNF8Ta1q3OuSJHRwwT8YsuR1YzEiEIJEk6w=="],174 "@jitl/quickjs-wasmfile-debug-asyncify": ["@jitl/quickjs-wasmfile-debug-asyncify@0.31.0", "", { "dependencies": { "@jitl/quickjs-ffi-types": "0.31.0" } }, "sha512-YkdzQdr1uaftFhgEnTRjTTZHk2SFZdpWO7XhOmRVbi6CEVsH9g5oNF8Ta1q3OuSJHRwwT8YsuR1YzEiEIJEk6w=="],
@@ -437,6 +451,8 @@ · 276 unmodified lines
437 451
438 "yaml": ["yaml@2.8.3", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg=="],452 "yaml": ["yaml@2.8.3", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg=="],
439 453
454 "@executor/sdk/typescript": ["typescript@6.0.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ=="],
455
440 "bun-types/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],456 "bun-types/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
441 457
442 "bun-types/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],458 "bun-types/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
packages/core/sdk/package.json+20−0
@@ -0,0 +1,20 @@
1{
2 "name": "@executor/sdk",
3 "version": "0.0.1",
4 "private": true,
5 "type": "module",
6 "exports": {
7 ".": "./src/index.ts"
8 },
9 "scripts": {
10 "typecheck": "tsc --noEmit"
11 },
12 "dependencies": {
13 "effect": "catalog:"
14 },
15 "devDependencies": {
16 "@effect/vitest": "catalog:",
17 "vitest": "catalog:",
18 "typescript": "latest"
19 }
20}
packages/core/sdk/src/elicitation.ts+78−0
@@ -0,0 +1,78 @@
1import { Effect, Schema } from "effect";
2
3import { ToolId } from "./ids";
4
5// ---------------------------------------------------------------------------
6// Elicitation request — what a tool sends when it needs user input
7// ---------------------------------------------------------------------------
8
9/** Tool needs structured input from the user (render a form) */
10export class FormElicitation extends Schema.TaggedClass<FormElicitation>()(
11 "FormElicitation",
12 {
13 message: Schema.String,
14 /** JSON Schema describing the fields to collect */
15 requestedSchema: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
16 },
17) {}
18
19/** Tool needs the user to visit a URL (OAuth, approval page, etc.) */
20export class UrlElicitation extends Schema.TaggedClass<UrlElicitation>()(
21 "UrlElicitation",
22 {
23 message: Schema.String,
24 url: Schema.String,
25 /** Unique ID so the host can correlate the callback */
26 elicitationId: Schema.String,
27 },
28) {}
29
30export type ElicitationRequest = FormElicitation | UrlElicitation;
31
32// ---------------------------------------------------------------------------
33// Elicitation response — what the host sends back
34// ---------------------------------------------------------------------------
35
36export const ElicitationAction = Schema.Literal("accept", "decline", "cancel");
37export type ElicitationAction = typeof ElicitationAction.Type;
38
39export class ElicitationResponse extends Schema.Class<ElicitationResponse>(
40 "ElicitationResponse",
41)({
42 action: ElicitationAction,
43 /** Present when action is "accept" — the data the user provided */
44 content: Schema.optional(
45 Schema.Record({ key: Schema.String, value: Schema.Unknown }),
46 ),
47}) {}
48
49// ---------------------------------------------------------------------------
50// Elicitation handler — the host provides this to handle requests
51// ---------------------------------------------------------------------------
52
53export interface ElicitationContext {
54 readonly toolId: ToolId;
55 readonly args: unknown;
56 readonly request: ElicitationRequest;
57}
58
59/**
60 * A function the host provides to handle elicitation.
61 * The SDK calls this when a tool suspends to ask for user input.
62 * The host renders UI / prompts the user / does OAuth / etc.
63 */
64export type ElicitationHandler = (
65 ctx: ElicitationContext,
66) => Effect.Effect<ElicitationResponse>;
67
68// ---------------------------------------------------------------------------
69// Elicitation error — tool was declined or cancelled
70// ---------------------------------------------------------------------------
71
72export class ElicitationDeclinedError extends Schema.TaggedError<ElicitationDeclinedError>()(
73 "ElicitationDeclinedError",
74 {
75 toolId: ToolId,
76 action: Schema.Literal("decline", "cancel"),
77 },
78) {}
packages/core/sdk/src/errors.ts+36−0
@@ -0,0 +1,36 @@
1import { Schema } from "effect";
2
3import { ToolId, SecretId, PolicyId } from "./ids";
4
5export class ToolNotFoundError extends Schema.TaggedError<ToolNotFoundError>()(
6 "ToolNotFoundError",
7 { toolId: ToolId },
8) {}
9
10export class ToolInvocationError extends Schema.TaggedError<ToolInvocationError>()(
11 "ToolInvocationError",
12 {
13 toolId: ToolId,
14 message: Schema.String,
15 cause: Schema.optional(Schema.Unknown),
16 },
17) {}
18
19export class SecretNotFoundError extends Schema.TaggedError<SecretNotFoundError>()(
20 "SecretNotFoundError",
21 { secretId: SecretId },
22) {}
23
24export class SecretResolutionError extends Schema.TaggedError<SecretResolutionError>()(
25 "SecretResolutionError",
26 { secretId: SecretId, message: Schema.String },
27) {}
28
29export class PolicyDeniedError extends Schema.TaggedError<PolicyDeniedError>()(
30 "PolicyDeniedError",
31 {
32 policyId: PolicyId,
33 toolId: ToolId,
34 reason: Schema.String,
35 },
36) {}
packages/core/sdk/src/executor.ts+170−0
@@ -0,0 +1,170 @@
1import { Context, Effect } from "effect";
2
3import type { ScopeId, ToolId, SecretId, PolicyId } from "./ids";
4import type { Secret, SecretStore } from "./secrets";
5import type {
6 ToolMetadata,
7 ToolSchema,
8 ToolInvocationResult,
9 ToolRegistry,
10 InvokeOptions,
11} from "./tools";
12import type { Policy, PolicyEngine } from "./policies";
13import type { Scope } from "./scope";
14import type {
15 ExecutorPlugin,
16 PluginExtensions,
17 PluginHandle,
18} from "./plugin";
19import type {
20 ToolNotFoundError,
21 ToolInvocationError,
22 SecretNotFoundError,
23 PolicyDeniedError,
24} from "./errors";
25import type { ElicitationDeclinedError } from "./elicitation";
26
27// ---------------------------------------------------------------------------
28// Executor — the main public API, expands with plugins
29// ---------------------------------------------------------------------------
30
31export type Executor<
32 TPlugins extends readonly ExecutorPlugin<string, object>[] = [],
33> = {
34 readonly scope: Scope;
35
36 readonly tools: {
37 readonly list: (filter?: {
38 readonly tags?: readonly string[];
39 readonly query?: string;
40 }) => Effect.Effect<readonly ToolMetadata[]>;
41 readonly schema: (
42 toolId: string,
43 ) => Effect.Effect<ToolSchema, ToolNotFoundError>;
44 readonly invoke: (
45 toolId: string,
46 args: unknown,
47 options?: InvokeOptions,
48 ) => Effect.Effect<
49 ToolInvocationResult,
50 | ToolNotFoundError
51 | ToolInvocationError
52 | PolicyDeniedError
53 | ElicitationDeclinedError
54 >;
55 };
56
57 readonly policies: {
58 readonly list: () => Effect.Effect<readonly Policy[]>;
59 readonly add: (
60 policy: Omit<Policy, "id" | "createdAt">,
61 ) => Effect.Effect<Policy>;
62 readonly remove: (policyId: string) => Effect.Effect<boolean>;
63 };
64
65 readonly secrets: {
66 readonly list: () => Effect.Effect<readonly Secret[]>;
67 readonly store: (input: {
68 readonly name: string;
69 readonly value: string;
70 readonly purpose?: string;
71 }) => Effect.Effect<Secret>;
72 readonly remove: (
73 secretId: string,
74 ) => Effect.Effect<boolean, SecretNotFoundError>;
75 };
76
77 readonly close: () => Effect.Effect<void>;
78} & PluginExtensions<TPlugins>;
79
80// ---------------------------------------------------------------------------
81// Resolved services — what we need to build an Executor
82// ---------------------------------------------------------------------------
83
84type ToolRegistryService = Context.Tag.Service<typeof ToolRegistry>;
85type SecretStoreService = Context.Tag.Service<typeof SecretStore>;
86type PolicyEngineService = Context.Tag.Service<typeof PolicyEngine>;
87
88export interface ExecutorConfig<
89 TPlugins extends readonly ExecutorPlugin<string, object>[] = [],
90> {
91 readonly scope: Scope;
92 readonly tools: ToolRegistryService;
93 readonly secrets: SecretStoreService;
94 readonly policies: PolicyEngineService;
95 readonly plugins?: TPlugins;
96}
97
98// ---------------------------------------------------------------------------
99// createExecutor — builds an Executor, initializes plugins
100// ---------------------------------------------------------------------------
101
102export const createExecutor = <
103 const TPlugins extends readonly ExecutorPlugin<string, object>[] = [],
104>(
105 config: ExecutorConfig<TPlugins>,
106): Effect.Effect<Executor<TPlugins>, Error> =>
107 Effect.gen(function* () {
108 const { scope, tools, secrets, policies, plugins = [] } = config;
109
110 // Initialize all plugins
111 const handles = new Map<string, PluginHandle<object>>();
112 const extensions: Record<string, object> = {};
113
114 for (const plugin of plugins) {
115 const handle = yield* plugin.init({
116 scopeId: scope.id,
117 tools,
118 secrets,
119 });
120 handles.set(plugin.key, handle);
121 extensions[plugin.key] = handle.extension;
122 }
123
124 const base = {
125 scope,
126
127 tools: {
128 list: (filter?: {
129 readonly tags?: readonly string[];
130 readonly query?: string;
131 }) => tools.list(filter),
132 schema: (toolId: string) => tools.schema(toolId as ToolId),
133 invoke: (toolId: string, args: unknown, options?: InvokeOptions) => {
134 const tid = toolId as ToolId;
135 return Effect.gen(function* () {
136 yield* policies.check({ scopeId: scope.id, toolId: tid });
137 return yield* tools.invoke(tid, args, options);
138 });
139 },
140 },
141
142 policies: {
143 list: () => policies.list(scope.id),
144 add: (policy: Omit<Policy, "id" | "createdAt">) =>
145 policies.add({ ...policy, scopeId: scope.id }),
146 remove: (policyId: string) =>
147 policies.remove(policyId as PolicyId),
148 },
149
150 secrets: {
151 list: () => secrets.list(scope.id),
152 store: (input: {
153 readonly name: string;
154 readonly value: string;
155 readonly purpose?: string;
156 }) => secrets.store({ ...input, scopeId: scope.id }),
157 remove: (secretId: string) =>
158 secrets.remove(secretId as SecretId),
159 },
160
161 close: () =>
162 Effect.gen(function* () {
163 for (const handle of handles.values()) {
164 if (handle.close) yield* handle.close();
165 }
166 }),
167 };
168
169 return Object.assign(base, extensions) as Executor<TPlugins>;
170 });
packages/core/sdk/src/ids.ts+13−0
@@ -0,0 +1,13 @@
1import { Schema } from "effect";
2
3export const ScopeId = Schema.String.pipe(Schema.brand("ScopeId"));
4export type ScopeId = typeof ScopeId.Type;
5
6export const ToolId = Schema.String.pipe(Schema.brand("ToolId"));
7export type ToolId = typeof ToolId.Type;
8
9export const SecretId = Schema.String.pipe(Schema.brand("SecretId"));
10export type SecretId = typeof SecretId.Type;
11
12export const PolicyId = Schema.String.pipe(Schema.brand("PolicyId"));
13export type PolicyId = typeof PolicyId.Type;
packages/core/sdk/src/index.test.ts+414−0
@@ -0,0 +1,414 @@
1import { describe, expect, it } from "@effect/vitest";
2import { Effect, Schema } from "effect";
3
4import {
5 createExecutor,
6 makeTestConfig,
7 memoryPlugin,
8 tool,
9 FormElicitation,
10 UrlElicitation,
11 ElicitationResponse,
12 type MemoryToolContext,
13} from "./index";
14
15// ---------------------------------------------------------------------------
16// Schemas
17// ---------------------------------------------------------------------------
18
19const GetItemInput = Schema.Struct({ itemId: Schema.Number });
20const Item = Schema.Struct({ id: Schema.Number, name: Schema.String });
21const EmptyInput = Schema.Struct({});
22const LoginResult = Schema.Struct({ user: Schema.String, status: Schema.String });
23const ConnectResult = Schema.Struct({ connected: Schema.Boolean, code: Schema.String });
24
25// ---------------------------------------------------------------------------
26// Tests
27// ---------------------------------------------------------------------------
28
29describe("SDK Executor", () => {
30 it.effect("creates an executor with no plugins", () =>
31 Effect.gen(function* () {
32 const executor = yield* createExecutor(makeTestConfig());
33 expect(executor.scope.name).toBe("test");
34 expect(yield* executor.tools.list()).toHaveLength(0);
35 }),
36 );
37
38 it.effect("memory plugin registers tools and they are discoverable", () =>
39 Effect.gen(function* () {
40 const executor = yield* createExecutor(
41 makeTestConfig({
42 plugins: [
43 memoryPlugin({
44 namespace: "inventory",
45 tools: [
46 tool({
47 name: "listItems",
48 description: "List all items",
49 inputSchema: EmptyInput,
50 outputSchema: Schema.Array(Item),
51 handler: () => [
52 { id: 1, name: "Widget" },
53 { id: 2, name: "Gadget" },
54 ],
55 }),
56 tool({
57 name: "getItem",
58 description: "Get an item by ID",
59 inputSchema: GetItemInput,
60 outputSchema: Item,
61 handler: ({ itemId }: { itemId: number }) => ({ id: itemId, name: "Widget" }),
62 }),
63 ],
64 }),
65 ] as const,
66 }),
67 );
68
69 const tools = yield* executor.tools.list();
70 expect(tools).toHaveLength(2);
71 expect(tools.map((t) => t.name)).toContain("listItems");
72 expect(tools.map((t) => t.name)).toContain("getItem");
73 }),
74 );
75
76 it.effect("invokes a tool with typed args", () =>
77 Effect.gen(function* () {
78 const executor = yield* createExecutor(
79 makeTestConfig({
80 plugins: [
81 memoryPlugin({
82 namespace: "inventory",
83 tools: [
84 tool({
85 name: "getItem",
86 inputSchema: GetItemInput,
87 outputSchema: Item,
88 handler: ({ itemId }: { itemId: number }) => ({ id: itemId, name: "Widget" }),
89 }),
90 ],
91 }),
92 ] as const,
93 }),
94 );
95
96 const result = yield* executor.tools.invoke("inventory.getItem", { itemId: 42 });
97 expect(result.data).toEqual({ id: 42, name: "Widget" });
98 expect(result.error).toBeNull();
99 }),
100 );
101
102 it.effect("validates input against schema", () =>
103 Effect.gen(function* () {
104 const executor = yield* createExecutor(
105 makeTestConfig({
106 plugins: [
107 memoryPlugin({
108 namespace: "inventory",
109 tools: [
110 tool({
111 name: "getItem",
112 inputSchema: GetItemInput,
113 handler: ({ itemId }: { itemId: number }) => ({ id: itemId }),
114 }),
115 ],
116 }),
117 ] as const,
118 }),
119 );
120
121 const result = yield* Effect.either(
122 executor.tools.invoke("inventory.getItem", { itemId: "not-a-number" }),
123 );
124 expect(result._tag).toBe("Left");
125 if (result._tag === "Left") {
126 expect((result.left as { _tag: string })._tag).toBe("ToolInvocationError");
127 }
128 }),
129 );
130
131 it.effect("tool invocation fails for unknown tool", () =>
132 Effect.gen(function* () {
133 const executor = yield* createExecutor(makeTestConfig());
134 const result = yield* Effect.either(executor.tools.invoke("nonexistent", {}));
135 expect(result._tag).toBe("Left");
136 }),
137 );
138
139 it.effect("filters tools by query", () =>
140 Effect.gen(function* () {
141 const executor = yield* createExecutor(
142 makeTestConfig({
143 plugins: [
144 memoryPlugin({
145 namespace: "store",
146 tools: [
147 tool({
148 name: "listItems",
149 description: "List all items",
150 inputSchema: EmptyInput,
151 handler: () => [],
152 }),
153 tool({
154 name: "createOrder",
155 description: "Create an order",
156 inputSchema: EmptyInput,
157 handler: () => ({}),
158 }),
159 ],
160 }),
161 ] as const,
162 }),
163 );
164
165 const itemTools = yield* executor.tools.list({ query: "item" });
166 expect(itemTools).toHaveLength(1);
167 expect(itemTools[0]!.name).toBe("listItems");
168
169 const orderTools = yield* executor.tools.list({ query: "order" });
170 expect(orderTools).toHaveLength(1);
171 expect(orderTools[0]!.name).toBe("createOrder");
172 }),
173 );
174
175 it.effect("plugin extension is typed and accessible", () =>
176 Effect.gen(function* () {
177 const executor = yield* createExecutor(
178 makeTestConfig({
179 plugins: [
180 memoryPlugin({ namespace: "runtime", tools: [] }),
181 ] as const,
182 }),
183 );
184
185 expect(executor.memory).toBeDefined();
186 expect(typeof executor.memory.addTools).toBe("function");
187
188 yield* executor.memory.addTools([
189 tool({
190 name: "dynamicTool",
191 description: "Added at runtime",
192 inputSchema: EmptyInput,
193 handler: () => "dynamic result",
194 }),
195 ]);
196
197 const tools = yield* executor.tools.list();
198 expect(tools).toHaveLength(1);
199 expect(tools[0]!.name).toBe("dynamicTool");
200
201 const result = yield* executor.tools.invoke("runtime.dynamicTool", {});
202 expect(result.data).toBe("dynamic result");
203 }),
204 );
205
206 it.effect("stores and lists secrets", () =>
207 Effect.gen(function* () {
208 const executor = yield* createExecutor(makeTestConfig());
209
210 const secret = yield* executor.secrets.store({
211 name: "API Key",
212 value: "sk_test_123",
213 purpose: "auth",
214 });
215 expect(secret.name).toBe("API Key");
216
217 const listed = yield* executor.secrets.list();
218 expect(listed).toHaveLength(1);
219 expect(listed[0]!.name).toBe("API Key");
220 }),
221 );
222
223 it.effect("form elicitation: tool collects user input mid-invocation", () =>
224 Effect.gen(function* () {
225 const executor = yield* createExecutor(
226 makeTestConfig({
227 plugins: [
228 memoryPlugin({
229 namespace: "auth",
230 tools: [
231 tool({
232 name: "login",
233 inputSchema: EmptyInput,
234 outputSchema: LoginResult,
235 handler: (_, ctx: MemoryToolContext) =>
236 Effect.gen(function* () {
237 const creds = yield* ctx.elicit(
238 new FormElicitation({
239 message: "Enter credentials",
240 requestedSchema: {
241 type: "object",
242 properties: {
243 username: { type: "string" },
244 password: { type: "string" },
245 },
246 },
247 }),
248 );
249 return {
250 user: creds.username as string,
251 status: "logged_in",
252 };
253 }),
254 }),
255 ],
256 }),
257 ] as const,
258 }),
259 );
260
261 const result = yield* executor.tools.invoke("auth.login", {}, {
262 onElicitation: () =>
263 Effect.succeed(
264 new ElicitationResponse({
265 action: "accept",
266 content: { username: "alice", password: "secret" },
267 }),
268 ),
269 });
270
271 expect(result.data).toEqual({ user: "alice", status: "logged_in" });
272 }),
273 );
274
275 it.effect("elicitation declined returns error", () =>
276 Effect.gen(function* () {
277 const executor = yield* createExecutor(
278 makeTestConfig({
279 plugins: [
280 memoryPlugin({
281 namespace: "auth",
282 tools: [
283 tool({
284 name: "login",
285 inputSchema: EmptyInput,
286 handler: (_, ctx: MemoryToolContext) =>
287 ctx.elicit(
288 new FormElicitation({
289 message: "Enter credentials",
290 requestedSchema: {},
291 }),
292 ),
293 }),
294 ],
295 }),
296 ] as const,
297 }),
298 );
299
300 const result = yield* Effect.either(
301 executor.tools.invoke("auth.login", {}, {
302 onElicitation: () =>
303 Effect.succeed(new ElicitationResponse({ action: "decline" })),
304 }),
305 );
306
307 expect(result._tag).toBe("Left");
308 if (result._tag === "Left") {
309 expect((result.left as { _tag: string })._tag).toBe("ElicitationDeclinedError");
310 }
311 }),
312 );
313
314 it.effect("elicitation with no handler auto-declines", () =>
315 Effect.gen(function* () {
316 const executor = yield* createExecutor(
317 makeTestConfig({
318 plugins: [
319 memoryPlugin({
320 namespace: "auth",
321 tools: [
322 tool({
323 name: "login",
324 inputSchema: EmptyInput,
325 handler: (_, ctx: MemoryToolContext) =>
326 ctx.elicit(
327 new FormElicitation({
328 message: "Need input",
329 requestedSchema: {},
330 }),
331 ),
332 }),
333 ],
334 }),
335 ] as const,
336 }),
337 );
338
339 const result = yield* Effect.either(executor.tools.invoke("auth.login", {}));
340 expect(result._tag).toBe("Left");
341 }),
342 );
343
344 it.effect("url elicitation: tool requests URL visit", () =>
345 Effect.gen(function* () {
346 const executor = yield* createExecutor(
347 makeTestConfig({
348 plugins: [
349 memoryPlugin({
350 namespace: "oauth",
351 tools: [
352 tool({
353 name: "connect",
354 inputSchema: EmptyInput,
355 outputSchema: ConnectResult,
356 handler: (_, ctx: MemoryToolContext) =>
357 Effect.gen(function* () {
358 const result = yield* ctx.elicit(
359 new UrlElicitation({
360 message: "Please authorize the app",
361 url: "https://oauth.example.com/authorize?state=abc",
362 elicitationId: "oauth-abc",
363 }),
364 );
365 return { connected: true, code: result.code as string };
366 }),
367 }),
368 ],
369 }),
370 ] as const,
371 }),
372 );
373
374 const result = yield* executor.tools.invoke("oauth.connect", {}, {
375 onElicitation: (ctx) => {
376 expect(ctx.request._tag).toBe("UrlElicitation");
377 return Effect.succeed(
378 new ElicitationResponse({
379 action: "accept",
380 content: { code: "auth-code-123" },
381 }),
382 );
383 },
384 });
385
386 expect(result.data).toEqual({ connected: true, code: "auth-code-123" });
387 }),
388 );
389
390 it.effect("close cleans up plugin resources", () =>
391 Effect.gen(function* () {
392 const executor = yield* createExecutor(
393 makeTestConfig({
394 plugins: [
395 memoryPlugin({
396 namespace: "temp",
397 tools: [
398 tool({
399 name: "ephemeral",
400 inputSchema: EmptyInput,
401 handler: () => "here",
402 }),
403 ],
404 }),
405 ] as const,
406 }),
407 );
408
409 expect(yield* executor.tools.list()).toHaveLength(1);
410 yield* executor.close();
411 expect(yield* executor.tools.list()).toHaveLength(0);
412 }),
413 );
414});
packages/core/sdk/src/index.ts+70−0
@@ -0,0 +1,70 @@
1// IDs
2export { ScopeId, ToolId, SecretId, PolicyId } from "./ids";
3
4// Errors
5export {
6 ToolNotFoundError,
7 ToolInvocationError,
8 SecretNotFoundError,
9 SecretResolutionError,
10 PolicyDeniedError,
11} from "./errors";
12
13// Tools
14export {
15 ToolMetadata,
16 ToolSchema,
17 ToolInvocationResult,
18 ToolRegistry,
19 type ToolRegistration,
20 type InvokeOptions,
21} from "./tools";
22
23// Elicitation
24export {
25 FormElicitation,
26 UrlElicitation,
27 ElicitationAction,
28 ElicitationResponse,
29 ElicitationDeclinedError,
30 type ElicitationRequest,
31 type ElicitationHandler,
32 type ElicitationContext,
33} from "./elicitation";
34
35// Secrets
36export { Secret, SecretStore } from "./secrets";
37
38// Policies
39export { Policy, PolicyAction, PolicyEngine } from "./policies";
40
41// Scope
42export { Scope } from "./scope";
43
44// Plugin
45export {
46 definePlugin,
47 type ExecutorPlugin,
48 type PluginContext,
49 type PluginHandle,
50 type PluginExtensions,
51} from "./plugin";
52
53// Executor
54export {
55 createExecutor,
56 type Executor,
57 type ExecutorConfig,
58} from "./executor";
59
60// Built-in plugins
61export {
62 memoryPlugin,
63 tool,
64 type MemoryToolDefinition,
65 type MemoryToolContext,
66 type MemoryPluginExtension,
67} from "./plugins/memory";
68
69// Testing
70export { makeTestConfig } from "./testing";
packages/core/sdk/src/plugin.ts+73−0
@@ -0,0 +1,73 @@
1import type { Effect } from "effect";
2
3import type { ToolRegistration, ToolRegistry } from "./tools";
4import type { SecretStore } from "./secrets";
5import type { ScopeId } from "./ids";
6
7// ---------------------------------------------------------------------------
8// Plugin context — what the SDK gives a plugin when it starts
9// ---------------------------------------------------------------------------
10
11export interface PluginContext {
12 readonly scopeId: ScopeId;
13 readonly tools: Context.Tag.Service<typeof ToolRegistry>;
14 readonly secrets: Context.Tag.Service<typeof SecretStore>;
15}
16
17// ---------------------------------------------------------------------------
18// Plugin definition — what a plugin provides to the SDK
19// ---------------------------------------------------------------------------
20
21export interface ExecutorPlugin<
22 TKey extends string = string,
23 TExtension extends object = object,
24> {
25 /** Unique plugin key — becomes a property on the Executor type */
26 readonly key: TKey;
27
28 /**
29 * Called when the executor starts. The plugin should register its tools
30 * and return any cleanup logic + its public extension API.
31 */
32 readonly init: (ctx: PluginContext) => Effect.Effect<
33 PluginHandle<TExtension>,
34 Error
35 >;
36}
37
38export interface PluginHandle<TExtension extends object = object> {
39 /** Plugin's public API — exposed on the executor as `executor[plugin.key]` */
40 readonly extension: TExtension;
41 /** Called when the executor shuts down */
42 readonly close?: () => Effect.Effect<void>;
43}
44
45// ---------------------------------------------------------------------------
46// Type-level helpers — expand the Executor type based on plugins
47// ---------------------------------------------------------------------------
48
49/** Maps a tuple of plugins to their extensions keyed by plugin key */
50export type PluginExtensions<
51 TPlugins extends readonly ExecutorPlugin<string, object>[],
52> = {
53 readonly [P in TPlugins[number] as P["key"]]: P extends ExecutorPlugin<
54 string,
55 infer TExt
56 >
57 ? TExt
58 : never;
59};
60
61// We need Context imported for the Tag.Service usage
62import type { Context } from "effect";
63
64// ---------------------------------------------------------------------------
65// definePlugin — helper for type inference
66// ---------------------------------------------------------------------------
67
68export const definePlugin = <
69 const TKey extends string,
70 TExtension extends object,
71>(
72 plugin: ExecutorPlugin<TKey, TExtension>,
73): ExecutorPlugin<TKey, TExtension> => plugin;
packages/core/sdk/src/plugins/memory.ts+205−0
@@ -0,0 +1,205 @@
1import { Effect, JSONSchema, Schema } from "effect";
2
3import { ToolId } from "../ids";
4import { ToolInvocationError } from "../errors";
5import {
6 ToolInvocationResult,
7 type ToolRegistration,
8 type InvokeOptions,
9} from "../tools";
10import {
11 ElicitationDeclinedError,
12 type ElicitationRequest,
13} from "../elicitation";
14import { definePlugin, type PluginContext } from "../plugin";
15
16// ---------------------------------------------------------------------------
17// In-memory tool definition — typed via Schema
18// ---------------------------------------------------------------------------
19
20/**
21 * A tool that uses Effect Schema for typed input/output.
22 *
23 * - `inputSchema` defines and validates the args the tool receives
24 * - `outputSchema` optionally describes the output shape
25 * - `handler` receives the parsed/typed args
26 */
27export interface MemoryToolDefinition<
28 TInput = unknown,
29 TOutput = unknown,
30> {
31 readonly name: string;
32 readonly description?: string;
33 readonly tags?: readonly string[];
34 readonly inputSchema: Schema.Schema<TInput>;
35 readonly outputSchema?: Schema.Schema<TOutput>;
36 readonly handler: MemoryToolHandler<TInput>;
37}
38
39/**
40 * A handler is either:
41 * - A plain function: `(args: TInput) => TOutput`
42 * - An Effect function (can use elicitation): `(args: TInput, ctx) => Effect<TOutput, ...>`
43 */
44export type MemoryToolHandler<TInput> =
45 | ((args: TInput) => unknown)
46 | ((
47 args: TInput,
48 ctx: MemoryToolContext,
49 ) => Effect.Effect<unknown, ElicitationDeclinedError>);
50
51export interface MemoryToolContext {
52 /** Request input from the user. Returns user data or fails if declined. */
53 readonly elicit: (
54 request: ElicitationRequest,
55 ) => Effect.Effect<Record<string, unknown>, ElicitationDeclinedError>;
56}
57
58// ---------------------------------------------------------------------------
59// Plugin extension
60// ---------------------------------------------------------------------------
61
62export interface MemoryPluginExtension {
63 // eslint-disable-next-line @typescript-eslint/no-explicit-any
64 readonly addTools: (
65 tools: readonly MemoryToolDefinition<any, any>[],
66 ) => Effect.Effect<void>;
67}
68
69// ---------------------------------------------------------------------------
70// Registration builder
71// ---------------------------------------------------------------------------
72
73const toRegistration = (
74 namespace: string,
75 def: MemoryToolDefinition,
76): ToolRegistration => {
77 const id = ToolId.make(`${namespace}.${def.name}`);
78 const decode = Schema.decodeUnknownSync(def.inputSchema);
79 const isEffectHandler = def.handler.length >= 2;
80
81 return {
82 id,
83 name: def.name,
84 description: def.description,
85 tags: def.tags ? [...def.tags] : undefined,
86 inputSchema: JSONSchema.make(def.inputSchema),
87 outputSchema: def.outputSchema
88 ? JSONSchema.make(def.outputSchema)
89 : undefined,
90 mayElicit: isEffectHandler,
91 invoke: (args, options?: InvokeOptions) => {
92 // Validate + decode input
93 const parsed = Effect.try({
94 try: () => decode(args),
95 catch: (err) =>
96 new ToolInvocationError({
97 toolId: id,
98 message: `Invalid input: ${err instanceof Error ? err.message : String(err)}`,
99 cause: err,
100 }),
101 });
102
103 if (!isEffectHandler) {
104 // Plain handler
105 return parsed.pipe(
106 Effect.flatMap((input) =>
107 Effect.try({
108 try: () =>
109 new ToolInvocationResult({
110 data: (def.handler as (args: unknown) => unknown)(input),
111 error: null,
112 }),
113 catch: (err) =>
114 new ToolInvocationError({
115 toolId: id,
116 message:
117 err instanceof Error ? err.message : String(err),
118 cause: err,
119 }),
120 }),
121 ),
122 );
123 }
124
125 // Effect handler — build context with elicit
126 const ctx: MemoryToolContext = {
127 elicit: (request) =>
128 Effect.gen(function* () {
129 const handler = options?.onElicitation;
130 if (!handler) {
131 return yield* new ElicitationDeclinedError({
132 toolId: id,
133 action: "decline",
134 });
135 }
136 const response = yield* handler({
137 toolId: id,
138 args,
139 request,
140 });
141 if (response.action !== "accept") {
142 return yield* new ElicitationDeclinedError({
143 toolId: id,
144 action: response.action as "decline" | "cancel",
145 });
146 }
147 return response.content ?? {};
148 }),
149 };
150
151 const effectHandler = def.handler as (
152 args: unknown,
153 ctx: MemoryToolContext,
154 ) => Effect.Effect<unknown, ElicitationDeclinedError>;
155
156 return parsed.pipe(
157 Effect.flatMap((input) => effectHandler(input, ctx)),
158 Effect.map(
159 (data) => new ToolInvocationResult({ data, error: null }),
160 ),
161 );
162 },
163 };
164};
165
166// ---------------------------------------------------------------------------
167// Tool definition helper — infers TInput from the schema
168// ---------------------------------------------------------------------------
169
170export function tool<TInput, TOutput>(
171 def: MemoryToolDefinition<TInput, TOutput>,
172): MemoryToolDefinition<TInput, TOutput> {
173 return def;
174}
175
176// ---------------------------------------------------------------------------
177// Plugin factory
178// ---------------------------------------------------------------------------
179
180// eslint-disable-next-line @typescript-eslint/no-explicit-any
181export const memoryPlugin = (config: {
182 readonly namespace?: string;
183 readonly tools: readonly MemoryToolDefinition<any, any>[];
184}) => {
185 const ns = config.namespace ?? "memory";
186 return definePlugin<"memory", MemoryPluginExtension>({
187 key: "memory",
188 init: (ctx: PluginContext) =>
189 Effect.gen(function* () {
190 const registrations = config.tools.map((t) => toRegistration(ns, t));
191 yield* ctx.tools.register(registrations);
192
193 return {
194 extension: {
195 addTools: (newTools: readonly MemoryToolDefinition[]) =>
196 ctx.tools.register(
197 newTools.map((t) => toRegistration(ns, t)),
198 ),
199 },
200 close: () =>
201 ctx.tools.unregister(registrations.map((r) => r.id)),
202 };
203 }),
204 });
205};
packages/core/sdk/src/policies.ts+35−0
@@ -0,0 +1,35 @@
1import { Context, Effect, Schema } from "effect";
2
3import { PolicyId, ScopeId, ToolId } from "./ids";
4import { PolicyDeniedError } from "./errors";
5
6export const PolicyAction = Schema.Literal("allow", "deny", "require_approval");
7export type PolicyAction = typeof PolicyAction.Type;
8
9export class Policy extends Schema.Class<Policy>("Policy")({
10 id: PolicyId,
11 scopeId: ScopeId,
12 name: Schema.String,
13 action: PolicyAction,
14 match: Schema.Struct({
15 toolPattern: Schema.optional(Schema.String),
16 tags: Schema.optional(Schema.Array(Schema.String)),
17 }),
18 priority: Schema.Number,
19 createdAt: Schema.DateFromNumber,
20}) {}
21
22export class PolicyEngine extends Context.Tag("@executor/sdk/PolicyEngine")<
23 PolicyEngine,
24 {
25 readonly list: (scopeId: ScopeId) => Effect.Effect<readonly Policy[]>;
26 readonly check: (input: {
27 readonly scopeId: ScopeId;
28 readonly toolId: ToolId;
29 }) => Effect.Effect<void, PolicyDeniedError>;
30 readonly add: (
31 policy: Omit<Policy, "id" | "createdAt">,
32 ) => Effect.Effect<Policy>;
33 readonly remove: (policyId: PolicyId) => Effect.Effect<boolean>;
34 }
35>() {}
packages/core/sdk/src/scope.ts+10−0
@@ -0,0 +1,10 @@
1import { Schema } from "effect";
2
3import { ScopeId } from "./ids";
4
5export class Scope extends Schema.Class<Scope>("Scope")({
6 id: ScopeId,
7 parentId: Schema.NullOr(ScopeId),
8 name: Schema.String,
9 createdAt: Schema.DateFromNumber,
10}) {}
packages/core/sdk/src/secrets.ts+34−0
@@ -0,0 +1,34 @@
1import { Context, Effect, Schema } from "effect";
2
3import { SecretId, ScopeId } from "./ids";
4import { SecretNotFoundError, SecretResolutionError } from "./errors";
5
6export class Secret extends Schema.Class<Secret>("Secret")({
7 id: SecretId,
8 scopeId: ScopeId,
9 name: Schema.String,
10 purpose: Schema.optional(Schema.String),
11 createdAt: Schema.DateFromNumber,
12}) {}
13
14export class SecretStore extends Context.Tag("@executor/sdk/SecretStore")<
15 SecretStore,
16 {
17 readonly list: (scopeId: ScopeId) => Effect.Effect<readonly Secret[]>;
18 readonly get: (
19 secretId: SecretId,
20 ) => Effect.Effect<Secret, SecretNotFoundError>;
21 readonly resolve: (
22 secretId: SecretId,
23 ) => Effect.Effect<string, SecretNotFoundError | SecretResolutionError>;
24 readonly store: (input: {
25 readonly scopeId: ScopeId;
26 readonly name: string;
27 readonly value: string;
28 readonly purpose?: string;
29 }) => Effect.Effect<Secret>;
30 readonly remove: (
31 secretId: SecretId,
32 ) => Effect.Effect<boolean, SecretNotFoundError>;
33 }
34>() {}
packages/core/sdk/src/testing.ts+192−0
@@ -0,0 +1,192 @@
1import { Effect } from "effect";
2
3import { ScopeId, ToolId, SecretId, PolicyId } from "./ids";
4import {
5 ToolNotFoundError,
6 ToolInvocationError,
7 SecretNotFoundError,
8 PolicyDeniedError,
9} from "./errors";
10import type { ToolRegistration, InvokeOptions } from "./tools";
11import type { Secret } from "./secrets";
12import type { Policy } from "./policies";
13import type { Scope } from "./scope";
14import type { ExecutorConfig } from "./executor";
15import type { ExecutorPlugin } from "./plugin";
16
17// ---------------------------------------------------------------------------
18// In-memory ToolRegistry
19// ---------------------------------------------------------------------------
20
21const makeInMemoryToolRegistry = () => {
22 const tools = new Map<
23 string,
24 ToolRegistration
25 >();
26
27 return {
28 list: (filter?: {
29 readonly tags?: readonly string[];
30 readonly query?: string;
31 }) =>
32 Effect.sync(() => {
33 let result = [...tools.values()];
34 if (filter?.tags?.length) {
35 const tagSet = new Set(filter.tags);
36 result = result.filter((t) =>
37 t.tags?.some((tag) => tagSet.has(tag)),
38 );
39 }
40 if (filter?.query) {
41 const q = filter.query.toLowerCase();
42 result = result.filter(
43 (t) =>
44 t.name.toLowerCase().includes(q) ||
45 t.description?.toLowerCase().includes(q),
46 );
47 }
48 return result.map((t) => ({
49 id: t.id,
50 name: t.name,
51 description: t.description,
52 tags: t.tags ? [...t.tags] : [],
53 }));
54 }),
55
56 schema: (toolId: ToolId) =>
57 Effect.fromNullable(tools.get(toolId)).pipe(
58 Effect.mapError(() => new ToolNotFoundError({ toolId })),
59 Effect.map((t) => ({
60 id: t.id,
61 inputSchema: t.inputSchema,
62 outputSchema: t.outputSchema,
63 })),
64 ),
65
66 invoke: (toolId: ToolId, args: unknown, options?: InvokeOptions) =>
67 Effect.gen(function* () {
68 const tool = yield* Effect.fromNullable(tools.get(toolId)).pipe(
69 Effect.mapError(() => new ToolNotFoundError({ toolId })),
70 );
71 return yield* tool.invoke(args, options);
72 }),
73
74 register: (newTools: readonly ToolRegistration[]) =>
75 Effect.sync(() => {
76 for (const t of newTools) {
77 tools.set(t.id, t);
78 }
79 }),
80
81 unregister: (toolIds: readonly ToolId[]) =>
82 Effect.sync(() => {
83 for (const id of toolIds) {
84 tools.delete(id);
85 }
86 }),
87 };
88};
89
90// ---------------------------------------------------------------------------
91// In-memory SecretStore
92// ---------------------------------------------------------------------------
93
94const makeInMemorySecretStore = () => {
95 const secrets = new Map<string, Secret & { value: string }>();
96 let counter = 0;
97
98 return {
99 list: (scopeId: ScopeId) =>
100 Effect.succeed(
101 [...secrets.values()].filter((s) => s.scopeId === scopeId),
102 ),
103 get: (secretId: SecretId) =>
104 Effect.fromNullable(secrets.get(secretId)).pipe(
105 Effect.mapError(() => new SecretNotFoundError({ secretId })),
106 ),
107 resolve: (secretId: SecretId) =>
108 Effect.fromNullable(secrets.get(secretId)).pipe(
109 Effect.mapError(() => new SecretNotFoundError({ secretId })),
110 Effect.map((s) => s.value),
111 ),
112 store: (input: {
113 readonly scopeId: ScopeId;
114 readonly name: string;
115 readonly value: string;
116 readonly purpose?: string;
117 }) =>
118 Effect.sync(() => {
119 const id = SecretId.make(`secret-${++counter}`);
120 const secret = {
121 id,
122 scopeId: input.scopeId,
123 name: input.name,
124 purpose: input.purpose,
125 createdAt: new Date(),
126 value: input.value,
127 };
128 secrets.set(id, secret);
129 return secret;
130 }),
131 remove: (secretId: SecretId) =>
132 Effect.fromNullable(secrets.get(secretId)).pipe(
133 Effect.mapError(() => new SecretNotFoundError({ secretId })),
134 Effect.map(() => secrets.delete(secretId)),
135 ),
136 };
137};
138
139// ---------------------------------------------------------------------------
140// In-memory PolicyEngine
141// ---------------------------------------------------------------------------
142
143const makeInMemoryPolicyEngine = () => {
144 const policies = new Map<string, Policy>();
145 let counter = 0;
146
147 return {
148 list: (scopeId: ScopeId) =>
149 Effect.succeed(
150 [...policies.values()].filter((p) => p.scopeId === scopeId),
151 ),
152 check: (_input: { readonly scopeId: ScopeId; readonly toolId: ToolId }) =>
153 Effect.void,
154 add: (policy: Omit<Policy, "id" | "createdAt">) =>
155 Effect.sync(() => {
156 const id = PolicyId.make(`policy-${++counter}`);
157 const full: Policy = { ...policy, id, createdAt: new Date() };
158 policies.set(id, full);
159 return full;
160 }),
161 remove: (policyId: PolicyId) =>
162 Effect.succeed(policies.delete(policyId)),
163 };
164};
165
166// ---------------------------------------------------------------------------
167// makeTestConfig — one-liner to build a test ExecutorConfig
168// ---------------------------------------------------------------------------
169
170export const makeTestConfig = <
171 const TPlugins extends readonly ExecutorPlugin<string, object>[] = [],
172>(
173 options?: {
174 readonly name?: string;
175 readonly plugins?: TPlugins;
176 },
177): ExecutorConfig<TPlugins> => {
178 const scope: Scope = {
179 id: ScopeId.make("test-scope"),
180 parentId: null,
181 name: options?.name ?? "test",
182 createdAt: new Date(),
183 };
184
185 return {
186 scope,
187 tools: makeInMemoryToolRegistry(),
188 secrets: makeInMemorySecretStore(),
189 policies: makeInMemoryPolicyEngine(),
190 plugins: options?.plugins,
191 };
192};
packages/core/sdk/src/tools.ts+106−0
@@ -0,0 +1,106 @@
1import { Context, Effect, Schema } from "effect";
2
3import { ToolId } from "./ids";
4import { ToolNotFoundError, ToolInvocationError } from "./errors";
5import type {
6 ElicitationHandler,
7 ElicitationDeclinedError,
8} from "./elicitation";
9
10// ---------------------------------------------------------------------------
11// Tool models
12// ---------------------------------------------------------------------------
13
14export class ToolMetadata extends Schema.Class<ToolMetadata>("ToolMetadata")({
15 id: ToolId,
16 name: Schema.String,
17 description: Schema.optional(Schema.String),
18 tags: Schema.Array(Schema.String),
19 /** Whether this tool may request elicitation during invocation */
20 mayElicit: Schema.optional(Schema.Boolean),
21}) {}
22
23export class ToolSchema extends Schema.Class<ToolSchema>("ToolSchema")({
24 id: ToolId,
25 inputSchema: Schema.optional(Schema.Unknown),
26 outputSchema: Schema.optional(Schema.Unknown),
27}) {}
28
29export class ToolInvocationResult extends Schema.Class<ToolInvocationResult>(
30 "ToolInvocationResult",
31)({
32 data: Schema.Unknown,
33 error: Schema.NullOr(Schema.Unknown),
34 status: Schema.optional(Schema.Number),
35}) {}
36
37// ---------------------------------------------------------------------------
38// Invocation options
39// ---------------------------------------------------------------------------
40
41export interface InvokeOptions {
42 /** Handler for elicitation requests. If not provided, elicitations are auto-declined. */
43 readonly onElicitation?: ElicitationHandler;
44}
45
46// ---------------------------------------------------------------------------
47// ToolRegistry — unified view across all plugins
48// ---------------------------------------------------------------------------
49
50export class ToolRegistry extends Context.Tag("@executor/sdk/ToolRegistry")<
51 ToolRegistry,
52 {
53 readonly list: (filter?: {
54 readonly tags?: readonly string[];
55 readonly query?: string;
56 }) => Effect.Effect<readonly ToolMetadata[]>;
57
58 readonly schema: (
59 toolId: ToolId,
60 ) => Effect.Effect<ToolSchema, ToolNotFoundError>;
61
62 readonly invoke: (
63 toolId: ToolId,
64 args: unknown,
65 options?: InvokeOptions,
66 ) => Effect.Effect<
67 ToolInvocationResult,
68 ToolNotFoundError | ToolInvocationError | ElicitationDeclinedError
69 >;
70
71 /** Register tools (used by plugins to push tools into the registry) */
72 readonly register: (
73 tools: readonly ToolRegistration[],
74 ) => Effect.Effect<void>;
75
76 /** Unregister tools by id (used by plugins on cleanup) */
77 readonly unregister: (
78 toolIds: readonly ToolId[],
79 ) => Effect.Effect<void>;
80 }
81>() {}
82
83// ---------------------------------------------------------------------------
84// ToolRegistration — what a plugin provides when registering a tool
85// ---------------------------------------------------------------------------
86
87export interface ToolRegistration {
88 readonly id: ToolId;
89 readonly name: string;
90 readonly description?: string;
91 readonly tags?: readonly string[];
92 readonly mayElicit?: boolean;
93 readonly inputSchema?: unknown;
94 readonly outputSchema?: unknown;
95 /**
96 * The tool's invoke function. Receives args and an optional elicitation
97 * handler that it can call to request user input mid-invocation.
98 */
99 readonly invoke: (
100 args: unknown,
101 options?: InvokeOptions,
102 ) => Effect.Effect<
103 ToolInvocationResult,
104 ToolInvocationError | ElicitationDeclinedError
105 >;
106}
packages/core/sdk/tsconfig.json+21−0
@@ -0,0 +1,21 @@
1{
2 "compilerOptions": {
3 "target": "ESNext",
4 "module": "ESNext",
5 "moduleResolution": "bundler",
6 "strict": true,
7 "esModuleInterop": true,
8 "skipLibCheck": true,
9 "outDir": "dist",
10 "rootDir": "src",
11 "declaration": true,
12 "declarationMap": true,
13 "sourceMap": true,
14 "plugins": [
15 {
16 "name": "@effect/language-service"
17 }
18 ]
19 },
20 "include": ["src"]
21}

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t