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
1111 "typescript": "^5.9.3",
1212 },
1313 },
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+ },
1426 "packages/kernel/core": {
1527 "name": "@executor/codemode-core",
1628 "version": "0.0.0",
@@ -155,6 +167,8 @@ · 138 unmodified lines
155167
156168 "@executor/runtime-quickjs": ["@executor/runtime-quickjs@workspace:packages/kernel/runtime-quickjs"],
157169
170+ "@executor/sdk": ["@executor/sdk@workspace:packages/core/sdk"],
171+
158172 "@jitl/quickjs-ffi-types": ["@jitl/quickjs-ffi-types@0.31.0", "", {}, "sha512-1yrgvXlmXH2oNj3eFTrkwacGJbmM0crwipA3ohCrjv52gBeDaD7PsTvFYinlAnqU8iPME3LGP437yk05a2oejw=="],
159173
160174 "@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
437451
438452 "yaml": ["yaml@2.8.3", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg=="],
439453
454+ "@executor/sdk/typescript": ["typescript@6.0.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ=="],
455+
440456 "bun-types/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
441457
442458 "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 @@
1+import { Effect, Schema } from "effect";
2+
3+import { 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) */
10+export 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.) */
20+export 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+
30+export type ElicitationRequest = FormElicitation | UrlElicitation;
31+
32+// ---------------------------------------------------------------------------
33+// Elicitation response — what the host sends back
34+// ---------------------------------------------------------------------------
35+
36+export const ElicitationAction = Schema.Literal("accept", "decline", "cancel");
37+export type ElicitationAction = typeof ElicitationAction.Type;
38+
39+export 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+
53+export 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+ */
64+export type ElicitationHandler = (
65+ ctx: ElicitationContext,
66+) => Effect.Effect<ElicitationResponse>;
67+
68+// ---------------------------------------------------------------------------
69+// Elicitation error — tool was declined or cancelled
70+// ---------------------------------------------------------------------------
71+
72+export 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 @@
1+import { Schema } from "effect";
2+
3+import { ToolId, SecretId, PolicyId } from "./ids";
4+
5+export class ToolNotFoundError extends Schema.TaggedError<ToolNotFoundError>()(
6+ "ToolNotFoundError",
7+ { toolId: ToolId },
8+) {}
9+
10+export 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+
19+export class SecretNotFoundError extends Schema.TaggedError<SecretNotFoundError>()(
20+ "SecretNotFoundError",
21+ { secretId: SecretId },
22+) {}
23+
24+export class SecretResolutionError extends Schema.TaggedError<SecretResolutionError>()(
25+ "SecretResolutionError",
26+ { secretId: SecretId, message: Schema.String },
27+) {}
28+
29+export 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 @@
1+import { Context, Effect } from "effect";
2+
3+import type { ScopeId, ToolId, SecretId, PolicyId } from "./ids";
4+import type { Secret, SecretStore } from "./secrets";
5+import type {
6+ ToolMetadata,
7+ ToolSchema,
8+ ToolInvocationResult,
9+ ToolRegistry,
10+ InvokeOptions,
11+} from "./tools";
12+import type { Policy, PolicyEngine } from "./policies";
13+import type { Scope } from "./scope";
14+import type {
15+ ExecutorPlugin,
16+ PluginExtensions,
17+ PluginHandle,
18+} from "./plugin";
19+import type {
20+ ToolNotFoundError,
21+ ToolInvocationError,
22+ SecretNotFoundError,
23+ PolicyDeniedError,
24+} from "./errors";
25+import type { ElicitationDeclinedError } from "./elicitation";
26+
27+// ---------------------------------------------------------------------------
28+// Executor — the main public API, expands with plugins
29+// ---------------------------------------------------------------------------
30+
31+export 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+
84+type ToolRegistryService = Context.Tag.Service<typeof ToolRegistry>;
85+type SecretStoreService = Context.Tag.Service<typeof SecretStore>;
86+type PolicyEngineService = Context.Tag.Service<typeof PolicyEngine>;
87+
88+export 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+
102+export 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 @@
1+import { Schema } from "effect";
2+
3+export const ScopeId = Schema.String.pipe(Schema.brand("ScopeId"));
4+export type ScopeId = typeof ScopeId.Type;
5+
6+export const ToolId = Schema.String.pipe(Schema.brand("ToolId"));
7+export type ToolId = typeof ToolId.Type;
8+
9+export const SecretId = Schema.String.pipe(Schema.brand("SecretId"));
10+export type SecretId = typeof SecretId.Type;
11+
12+export const PolicyId = Schema.String.pipe(Schema.brand("PolicyId"));
13+export type PolicyId = typeof PolicyId.Type;
packages/core/sdk/src/index.test.ts+414−0
@@ -0,0 +1,414 @@
1+import { describe, expect, it } from "@effect/vitest";
2+import { Effect, Schema } from "effect";
3+
4+import {
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+
19+const GetItemInput = Schema.Struct({ itemId: Schema.Number });
20+const Item = Schema.Struct({ id: Schema.Number, name: Schema.String });
21+const EmptyInput = Schema.Struct({});
22+const LoginResult = Schema.Struct({ user: Schema.String, status: Schema.String });
23+const ConnectResult = Schema.Struct({ connected: Schema.Boolean, code: Schema.String });
24+
25+// ---------------------------------------------------------------------------
26+// Tests
27+// ---------------------------------------------------------------------------
28+
29+describe("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
2+export { ScopeId, ToolId, SecretId, PolicyId } from "./ids";
3+
4+// Errors
5+export {
6+ ToolNotFoundError,
7+ ToolInvocationError,
8+ SecretNotFoundError,
9+ SecretResolutionError,
10+ PolicyDeniedError,
11+} from "./errors";
12+
13+// Tools
14+export {
15+ ToolMetadata,
16+ ToolSchema,
17+ ToolInvocationResult,
18+ ToolRegistry,
19+ type ToolRegistration,
20+ type InvokeOptions,
21+} from "./tools";
22+
23+// Elicitation
24+export {
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
36+export { Secret, SecretStore } from "./secrets";
37+
38+// Policies
39+export { Policy, PolicyAction, PolicyEngine } from "./policies";
40+
41+// Scope
42+export { Scope } from "./scope";
43+
44+// Plugin
45+export {
46+ definePlugin,
47+ type ExecutorPlugin,
48+ type PluginContext,
49+ type PluginHandle,
50+ type PluginExtensions,
51+} from "./plugin";
52+
53+// Executor
54+export {
55+ createExecutor,
56+ type Executor,
57+ type ExecutorConfig,
58+} from "./executor";
59+
60+// Built-in plugins
61+export {
62+ memoryPlugin,
63+ tool,
64+ type MemoryToolDefinition,
65+ type MemoryToolContext,
66+ type MemoryPluginExtension,
67+} from "./plugins/memory";
68+
69+// Testing
70+export { makeTestConfig } from "./testing";
packages/core/sdk/src/plugin.ts+73−0
@@ -0,0 +1,73 @@
1+import type { Effect } from "effect";
2+
3+import type { ToolRegistration, ToolRegistry } from "./tools";
4+import type { SecretStore } from "./secrets";
5+import type { ScopeId } from "./ids";
6+
7+// ---------------------------------------------------------------------------
8+// Plugin context — what the SDK gives a plugin when it starts
9+// ---------------------------------------------------------------------------
10+
11+export 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+
21+export 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+
38+export 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 */
50+export 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
62+import type { Context } from "effect";
63+
64+// ---------------------------------------------------------------------------
65+// definePlugin — helper for type inference
66+// ---------------------------------------------------------------------------
67+
68+export 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 @@
1+import { Effect, JSONSchema, Schema } from "effect";
2+
3+import { ToolId } from "../ids";
4+import { ToolInvocationError } from "../errors";
5+import {
6+ ToolInvocationResult,
7+ type ToolRegistration,
8+ type InvokeOptions,
9+} from "../tools";
10+import {
11+ ElicitationDeclinedError,
12+ type ElicitationRequest,
13+} from "../elicitation";
14+import { 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+ */
27+export 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+ */
44+export type MemoryToolHandler<TInput> =
45+ | ((args: TInput) => unknown)
46+ | ((
47+ args: TInput,
48+ ctx: MemoryToolContext,
49+ ) => Effect.Effect<unknown, ElicitationDeclinedError>);
50+
51+export 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+
62+export 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+
73+const 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+
170+export 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
181+export 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 @@
1+import { Context, Effect, Schema } from "effect";
2+
3+import { PolicyId, ScopeId, ToolId } from "./ids";
4+import { PolicyDeniedError } from "./errors";
5+
6+export const PolicyAction = Schema.Literal("allow", "deny", "require_approval");
7+export type PolicyAction = typeof PolicyAction.Type;
8+
9+export 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+
22+export 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 @@
1+import { Schema } from "effect";
2+
3+import { ScopeId } from "./ids";
4+
5+export 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 @@
1+import { Context, Effect, Schema } from "effect";
2+
3+import { SecretId, ScopeId } from "./ids";
4+import { SecretNotFoundError, SecretResolutionError } from "./errors";
5+
6+export 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+
14+export 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 @@
1+import { Effect } from "effect";
2+
3+import { ScopeId, ToolId, SecretId, PolicyId } from "./ids";
4+import {
5+ ToolNotFoundError,
6+ ToolInvocationError,
7+ SecretNotFoundError,
8+ PolicyDeniedError,
9+} from "./errors";
10+import type { ToolRegistration, InvokeOptions } from "./tools";
11+import type { Secret } from "./secrets";
12+import type { Policy } from "./policies";
13+import type { Scope } from "./scope";
14+import type { ExecutorConfig } from "./executor";
15+import type { ExecutorPlugin } from "./plugin";
16+
17+// ---------------------------------------------------------------------------
18+// In-memory ToolRegistry
19+// ---------------------------------------------------------------------------
20+
21+const 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+
94+const 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+
143+const 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+
170+export 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 @@
1+import { Context, Effect, Schema } from "effect";
2+
3+import { ToolId } from "./ids";
4+import { ToolNotFoundError, ToolInvocationError } from "./errors";
5+import type {
6+ ElicitationHandler,
7+ ElicitationDeclinedError,
8+} from "./elicitation";
9+
10+// ---------------------------------------------------------------------------
11+// Tool models
12+// ---------------------------------------------------------------------------
13+
14+export 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+
23+export class ToolSchema extends Schema.Class<ToolSchema>("ToolSchema")({
24+ id: ToolId,
25+ inputSchema: Schema.optional(Schema.Unknown),
26+ outputSchema: Schema.optional(Schema.Unknown),
27+}) {}
28+
29+export 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+
41+export 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+
50+export 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+
87+export 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