@executor-js/sdk 0.0.1 → 0.1.0

package/README.md

@@ -1,158 +1,176 @@
-# @executor/sdk
+# @executor-js/sdk
 
 A TypeScript SDK for building executors that wire together tool sources, secrets, and policies across MCP, OpenAPI, GraphQL, and custom plugins.
 
-Everything is `async`/`await`. Plug in any combination of plugins, register your own tools, and invoke them through a unified catalog.
+The default surface is `Promise`-based — plugins are built on [Effect](https://effect.website/) under the hood, but consumers never have to touch it.
 
 ## Install
 
 ```sh
-bun add @executor/sdk
+bun add @executor-js/sdk
 # or
-npm install @executor/sdk
+npm install @executor-js/sdk
 ```
 
 ## Quick start
 
 ```ts
-import {
-  createExecutor,
-  definePlugin,
-  ToolRegistration,
-  ToolId,
-  ToolInvocationResult,
-} from "@executor/sdk";
-
-// Define a custom plugin with async/await.
-const weatherPlugin = definePlugin({
-  key: "weather",
-  init: async (ctx) => {
-    await ctx.tools.registerInvoker("weather", {
-      invoke: async (_toolId, args) => {
-        const { city } = args as { city: string };
-        return new ToolInvocationResult({
-          data: { city, temperature: 72, condition: "sunny" },
-          error: null,
-        });
-      },
-    });
-
-    await ctx.tools.register([
-      new ToolRegistration({
-        id: ToolId.make("weather.getForecast"),
-        pluginKey: "weather",
-        sourceId: "weather",
-        name: "getForecast",
-        description: "Get weather forecast for a city",
-        inputSchema: {
-          type: "object",
-          properties: { city: { type: "string" } },
-          required: ["city"],
-        },
-      }),
-    ]);
-
-    return {
-      extension: {
-        forecast: async (city: string) => {
-          const result = await ctx.tools.invoke(
-            "weather.getForecast",
-            { city },
-            { onElicitation: "accept-all" },
-          );
-          return result.data as { city: string; temperature: number; condition: string };
-        },
-      },
-    };
-  },
-});
+import { createExecutor } from "@executor-js/sdk";
 
 const executor = await createExecutor({
-  scope: { name: "my-app" },
-  plugins: [weatherPlugin] as const,
+  // Required: how to respond when a tool requests user input mid-call.
+  // `"accept-all"` auto-approves every prompt — fine for tests/automation.
+  // For an interactive host, pass a handler `(ctx) => Promise<ElicitationResponse>`.
+  onElicitation: "accept-all",
 });
 
-// The plugin's extension is available under its key.
-const forecast = await executor.weather.forecast("San Francisco");
-
-// Every plugin contributes to a unified tool catalog.
 const tools = await executor.tools.list();
+console.log(`scope=${executor.scopes[0]!.id} tools=${tools.length}`);
 
-// Invoke any tool with the same call shape.
-const result = await executor.tools.invoke(
-  "weather.getForecast",
-  { city: "Tokyo" },
-  { onElicitation: "accept-all" },
-);
+await executor.close();
+```
+
+`createExecutor` returns an executor backed by an in-memory store and a default scope (`default-scope`). Without plugins it has no tools or secret providers — the surface is still there, it just enumerates empty. Add plugins to contribute tools, secret providers, and per-plugin extension methods.
+
+To invoke a tool once one is registered:
+
+```ts
+import { createExecutor } from "@executor-js/sdk";
+
+const executor = await createExecutor({ onElicitation: "accept-all" });
+
+const tools = await executor.tools.list();
+const target = tools[0];
+if (target) {
+  const result = await executor.tools.invoke(target.id, {
+    /* args matching target.inputSchema */
+  });
+  console.log(result);
+}
 
 await executor.close();
 ```
 
-## Using plugins
+Pass an `options` object only if you need to override the executor-level handler for a single call (rare — typically used by hosts that bridge per-client elicitation channels):
+
+```ts
+await executor.tools.invoke(target.id, args, {
+  onElicitation: customHandler,
+});
+```
+
+## Two import paths
+
+The SDK ships two surfaces from the same package:
+
+- `@executor-js/sdk` — the **Promise** surface for end users. Returns plain `Promise`s, no Effect required. This is what the quick start above uses.
+- `@executor-js/sdk/core` — the **Effect** surface for plugin authors. Exposes `definePlugin`, the typed error classes, schema helpers, and the Effect-shaped `Executor`. Every `@executor-js/plugin-*` package mirrors the same split.
+
+End users only ever need the root import. Plugin authors reach for `/core` because writing a plugin means returning Effect-shaped callbacks for storage, tool invocation, and secret providers.
 
-Install whichever plugins you need and pass their factory call into `plugins`:
+## Authoring a plugin
+
+A plugin is a factory that returns a spec object. The factory accepts plugin-author options and returns `{ id, storage, extension?, secretProviders?, ... }`. The shape of `extension` becomes `executor[plugin.id]` in the resulting executor — and on the Promise side every Effect-returning method is automatically promisified.
 
 ```ts
-import { createExecutor } from "@executor/sdk";
-import { mcpPlugin } from "@executor/plugin-mcp";
-import { openApiPlugin } from "@executor/plugin-openapi";
-import { graphqlPlugin } from "@executor/plugin-graphql";
+import { Effect } from "effect";
+import { definePlugin, type SecretProvider } from "@executor-js/sdk/core";
+import { createExecutor } from "@executor-js/sdk";
+
+interface MemorySecretsConfig {
+  readonly initial?: Readonly<Record<string, string>>;
+}
+
+// definePlugin takes a factory and returns a configured-plugin function
+// that the consumer calls with options.
+export const memorySecretsPlugin = definePlugin(
+  (options?: MemorySecretsConfig) => {
+    const map = new Map<string, string>(
+      Object.entries(options?.initial ?? {}),
+    );
+    const provider: SecretProvider = {
+      key: "memory",
+      writable: true,
+      get: (id: string) => Effect.sync(() => map.get(id) ?? null),
+      has: (id: string) => Effect.sync(() => map.has(id)),
+      set: (id: string, value: string) =>
+        Effect.sync(() => void map.set(id, value)),
+      delete: (id: string) => Effect.sync(() => map.delete(id)),
+      list: () =>
+        Effect.sync(() =>
+          Array.from(map.keys()).map((k) => ({ id: k, name: k })),
+        ),
+    };
 
+    return {
+      id: "memorySecrets" as const,
+      storage: () => ({}),
+      extension: () => ({
+        label: "in-memory secrets",
+      }),
+      secretProviders: () => [provider],
+    };
+  },
+);
+
+// End users compose the executor exactly the same way as above —
+// the plugin's extension is reachable as `executor.memorySecrets`.
 const executor = await createExecutor({
-  scope: { name: "my-app" },
-  plugins: [mcpPlugin(), openApiPlugin(), graphqlPlugin()] as const,
+  plugins: [memorySecretsPlugin({ initial: { greeting: "hello" } })] as const,
+  onElicitation: "accept-all",
 });
 
-await executor.mcp.addSource({
-  transport: "remote",
-  name: "Context7",
-  endpoint: "https://mcp.context7.com/mcp",
-});
-await executor.openapi.addSpec({
-  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-  namespace: "petstore",
+console.log(executor.memorySecrets.label); // "in-memory secrets"
+
+await executor.secrets.set({
+  id: "api-token",
+  name: "API Token",
+  value: "sk_live_xxx",
+  scope: executor.scopes[0]!.id,
 });
-await executor.graphql.addSource({ endpoint: "https://graphql.anilist.co", namespace: "anilist" });
 
-const tools = await executor.tools.list();
+console.log(await executor.secrets.get("api-token")); // "sk_live_xxx"
+
+await executor.close();
 ```
 
-Available plugins:
+The same pattern is what every shipped `@executor-js/plugin-*` package does internally. See [`packages/plugins/file-secrets`](https://github.com/RhysSullivan/executor/tree/main/packages/plugins/file-secrets) for a production example that backs `secretProviders` with an XDG-located JSON file.
+
+## Plugins
+
+These plugin packages are published from the monorepo:
 
-- [`@executor/plugin-mcp`](https://www.npmjs.com/package/@executor/plugin-mcp) — Model Context Protocol (stdio + remote)
-- [`@executor/plugin-openapi`](https://www.npmjs.com/package/@executor/plugin-openapi) — OpenAPI specs as tools
-- [`@executor/plugin-graphql`](https://www.npmjs.com/package/@executor/plugin-graphql) — GraphQL endpoints as tools
-- [`@executor/plugin-google-discovery`](https://www.npmjs.com/package/@executor/plugin-google-discovery) — Google Discovery APIs
-- [`@executor/plugin-file-secrets`](https://www.npmjs.com/package/@executor/plugin-file-secrets) — file-backed secret store
-- [`@executor/plugin-keychain`](https://www.npmjs.com/package/@executor/plugin-keychain) — OS keychain secret store
-- [`@executor/plugin-onepassword`](https://www.npmjs.com/package/@executor/plugin-onepassword) — 1Password secret source
+- [`@executor-js/plugin-mcp`](https://www.npmjs.com/package/@executor-js/plugin-mcp) — Model Context Protocol sources (stdio + remote)
+- [`@executor-js/plugin-openapi`](https://www.npmjs.com/package/@executor-js/plugin-openapi) — OpenAPI specs as tools
+- [`@executor-js/plugin-graphql`](https://www.npmjs.com/package/@executor-js/plugin-graphql) — GraphQL endpoints as tools
+- [`@executor-js/plugin-google-discovery`](https://www.npmjs.com/package/@executor-js/plugin-google-discovery) — Google Discovery APIs
+- [`@executor-js/plugin-file-secrets`](https://www.npmjs.com/package/@executor-js/plugin-file-secrets) — file-backed secret store
+- [`@executor-js/plugin-keychain`](https://www.npmjs.com/package/@executor-js/plugin-keychain) — OS keychain secret store
+- [`@executor-js/plugin-onepassword`](https://www.npmjs.com/package/@executor-js/plugin-onepassword) — 1Password secret source
+
+Each plugin exposes the same dual `.` / `./core` entry split as the SDK itself: end users import from the root, plugin authors who need to compose internals import from `/core`.
 
 ## Secrets
 
-Secrets are scoped per executor and shared across every plugin that resolves them:
+Secrets are scoped per executor and shared across every plugin that contributes a provider. A writable provider must be registered (via a plugin) before `set` will succeed.
 
 ```ts
+import { createExecutor } from "@executor-js/sdk";
+
+declare const executor: Awaited<ReturnType<typeof createExecutor>>;
+
 await executor.secrets.set({
   id: "github-token",
   name: "GitHub Token",
   value: "ghp_...",
-  purpose: "authentication",
+  scope: executor.scopes[0]!.id, // which scope owns the secret
 });
 
-const value = await executor.secrets.resolve("github-token");
-```
-
-Plugins accept `{ secretId, prefix }` wherever a header value is expected, so you never write tokens into source configs.
-
-## Using with Effect
-
-The SDK is built on [Effect](https://effect.website/) under the hood. If you want the raw Effect-based primitives instead of the promise wrapper, import from the `/core` subpath:
-
-```ts
-import { createExecutor } from "@executor/sdk";
+const value = await executor.secrets.get("github-token");
+const refs = await executor.secrets.list();
 ```
 
-`/core` exposes `createExecutor` returning an `Effect`, the `ToolRegistry` / `SourceRegistry` / `SecretStore` / `PolicyEngine` Context tags, the in-memory store factories, and every branded ID + error class. Every `@executor/plugin-*` ships a matching `/core` subpath.
+Plugins that need a token — HTTP-backed sources, OAuth flows, etc. — accept a secret id at the source-config layer and resolve through the executor, so token strings never live in your config files.
 
 ## Status
 

package/dist/blob.d.ts

@@ -0,0 +1,48 @@
+import { Effect } from "effect";
+import { StorageError } from "@executor-js/storage-core";
+export interface BlobStore {
+    readonly get: (namespace: string, key: string) => Effect.Effect<string | null, StorageError>;
+    /** Multi-namespace lookup for a single key. Backends issue one query
+     *  (`WHERE namespace IN (...) AND key = ?`) and return the hits keyed
+     *  by namespace — the caller applies its own precedence. Lets
+     *  `pluginBlobStore` walk the scope stack in O(1) round-trips instead
+     *  of one per scope. */
+    readonly getMany: (namespaces: readonly string[], key: string) => Effect.Effect<ReadonlyMap<string, string>, StorageError>;
+    readonly put: (namespace: string, key: string, value: string) => Effect.Effect<void, StorageError>;
+    readonly delete: (namespace: string, key: string) => Effect.Effect<void, StorageError>;
+    readonly has: (namespace: string, key: string) => Effect.Effect<boolean, StorageError>;
+}
+export interface PluginBlobStore {
+    /** Walk the scope stack (innermost first) and return the first
+     *  non-null value for `key`. */
+    readonly get: (key: string) => Effect.Effect<string | null, StorageError>;
+    /** Write `value` under `key` at the named scope. Scope must be one
+     *  of the executor's configured scopes. */
+    readonly put: (key: string, value: string, options: {
+        readonly scope: string;
+    }) => Effect.Effect<void, StorageError>;
+    /** Delete `key` at the named scope. */
+    readonly delete: (key: string, options: {
+        readonly scope: string;
+    }) => Effect.Effect<void, StorageError>;
+    /** Walk the scope stack and return true if any scope has a value for `key`. */
+    readonly has: (key: string) => Effect.Effect<boolean, StorageError>;
+}
+/**
+ * Bind a `BlobStore` to a specific scope stack and plugin id. Reads
+ * fall through the stack; writes require an explicit scope. Used by
+ * the executor to build the `blobs` field handed to each plugin's
+ * `storage` factory.
+ */
+export declare const pluginBlobStore: (store: BlobStore, scopes: readonly string[], pluginId: string) => PluginBlobStore;
+/**
+ * Minimal in-memory BlobStore — good for tests and trivial hosts. Real
+ * backends (filesystem, S3/R2, SQLite-table-backed) implement the same
+ * interface.
+ *
+ * Every method is `Effect<_, never>` — a pure in-memory Map can't fail.
+ * `never` is assignable to `StorageError`, so the result still fits the
+ * `BlobStore` interface.
+ */
+export declare const makeInMemoryBlobStore: () => BlobStore;
+//# sourceMappingURL=blob.d.ts.map

package/dist/blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CACZ,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,KACR,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC;IAChD;;;;4BAIwB;IACxB,QAAQ,CAAC,OAAO,EAAE,CAChB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,GAAG,EAAE,MAAM,KACR,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC;IAC9D,QAAQ,CAAC,GAAG,EAAE,CACZ,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,KACV,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,CACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,KACR,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,CACZ,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,KACR,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B;oCACgC;IAChC,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC;IAC1E;+CAC2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,CACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAChC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,CACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAChC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;CACrE;AAmBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,SAAS,EAChB,QAAQ,SAAS,MAAM,EAAE,EACzB,UAAU,MAAM,KACf,eA2BD,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,QAAO,SAwBxC,CAAC"}

package/dist/blob.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blob.test.d.ts.map

package/dist/blob.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.test.d.ts","sourceRoot":"","sources":["../src/blob.test.ts"],"names":[],"mappings":""}