Unified · Split
| @@ -11,6 +11,18 @@ · 10 unmodified lines | ||
| 11 | 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 | 26 | "packages/kernel/core": { |
| 15 | 27 | "name": "@executor/codemode-core", |
| 16 | 28 | "version": "0.0.0", |
| @@ -155,6 +167,8 @@ · 138 unmodified lines | ||
| 155 | 167 | |
| 156 | 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 | 172 | "@jitl/quickjs-ffi-types": ["@jitl/quickjs-ffi-types@0.31.0", "", {}, "sha512-1yrgvXlmXH2oNj3eFTrkwacGJbmM0crwipA3ohCrjv52gBeDaD7PsTvFYinlAnqU8iPME3LGP437yk05a2oejw=="], |
| 159 | 173 | |
| 160 | 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 | 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 | 456 | "bun-types/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="], |
| 441 | 457 | |
| 442 | 458 | "bun-types/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="], |
| @@ -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 | +} | |
| @@ -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 | +) {} | |
| @@ -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 | +) {} | |
| @@ -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 | + }); | |
| @@ -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; | |
| @@ -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 | +}); | |
| @@ -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"; | |
| @@ -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; | |
| @@ -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 | +}; | |
| @@ -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 | +>() {} | |
| @@ -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 | +}) {} | |
| @@ -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 | +>() {} | |
| @@ -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 | +}; | |
| @@ -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 | +} | |
| @@ -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 | +} | |