import { Effect } from "effect";import type { Context, Layer } from "effect";import type { HttpClient } from "effect/unstable/http";import type { HttpApiGroup } from "effect/unstable/httpapi";import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";import type { DBSchema, StorageFailure } from "@executor-js/storage-core"; import type { PluginBlobStore } from "./blob";import type {  ConnectionProvider,  ConnectionRef,  ConnectionRefreshError,  CreateConnectionInput,  RemoveConnectionInput,  UpdateConnectionTokensInput,} from "./connections";import type { CredentialBindingsFacade } from "./credential-bindings";import type { DefinitionsInput, SourceInput, ToolAnnotations, ToolRow } from "./core-schema";import type { RemoveSourceInput, SourceDetectionResult } from "./types";import type {  ElicitationDeclinedError,  ElicitationHandler,  ElicitationRequest,  ElicitationResponse,} from "./elicitation";import type {  ConnectionInUseError,  ConnectionNotFoundError,  ConnectionProviderNotRegisteredError,  ConnectionReauthRequiredError,  ConnectionRefreshNotSupportedError,  SecretInUseError,  SecretOwnedByConnectionError,} from "./errors";import type { OAuthService } from "./oauth";import type { Scope } from "./scope";import type { ScopedDBAdapter, ScopedTypedAdapter } from "./scoped-adapter";import type { RemoveSecretInput, SecretProvider, SecretRef, SetSecretInput } from "./secrets";import type { Usage, UsagesForConnectionInput, UsagesForSecretInput } from "./usages"; // ---------------------------------------------------------------------------// StorageDeps — backing passed to a plugin's `storage` factory. The only// place a plugin ever sees storage; `PluginCtx` does not carry it. The// `adapter` field is a `TypedAdapter<TSchema>` view narrowed by the// plugin's own declared `schema` — plugins never import or construct// a typed adapter themselves, the executor infers TSchema from the// `schema` field on their spec and hands back a typed view.//// Plugins with no schema (secret-provider-only plugins, etc.) get a// bare `DBAdapter` they can ignore.// --------------------------------------------------------------------------- export interface StorageDeps<TSchema extends DBSchema | undefined = undefined> {  /**   * Precedence-ordered scope stack visible to this executor. Innermost   * first. Reads on scoped tables walk every scope; writes require the   * plugin to name a target scope explicitly (via `scope_id` on the   * adapter payload, via `options.scope` on the blob store).   */  readonly scopes: readonly Scope[];  /**   * Plugin-facing typed adapter. Failures surface as raw `StorageFailure`   * (`StorageError` | `UniqueViolationError`). Plugins can   * `catchTag("UniqueViolationError", …)` to translate to their own   * user-facing errors. `StorageError` bubbles up; the HTTP edge (see   * `@executor-js/api` `withCapture`) is the one place that   * translates it to the opaque `InternalError({ traceId })`.   */  readonly adapter: TSchema extends DBSchema ? ScopedTypedAdapter<TSchema> : ScopedDBAdapter;  readonly blobs: PluginBlobStore;} // ---------------------------------------------------------------------------// defineSchema — sugar around `as const satisfies DBSchema`. Preserves// literal types via the `const` type parameter modifier so plugins can// just write `const mySchema = defineSchema({ ... })` without annotation// ceremony.// --------------------------------------------------------------------------- export const defineSchema = <const S extends DBSchema>(schema: S): S => schema; // ---------------------------------------------------------------------------// Elicit — suspends the fiber, calls the invoke-time elicitation// handler, resumes with the user's response. Available on both static// tool handlers and dynamic `invokeTool` handlers. Threaded through// the executor from `createExecutor({ onElicitation })`.// --------------------------------------------------------------------------- export type Elicit = (  request: ElicitationRequest,) => Effect.Effect<ElicitationResponse, ElicitationDeclinedError>; // ---------------------------------------------------------------------------// PluginCtx — threaded into every extension method, static tool handler,// and dynamic tool handler. No raw adapter, no raw blobs. Core writes// go through `core.sources.register` / `core.definitions.register`.// --------------------------------------------------------------------------- export interface PluginCtx<TStore = unknown> {  /**   * Precedence-ordered scope stack visible to this executor. Innermost   * first. Plugins that write scoped rows must pick an element of   * `scopes` as the `scope`/`scope_id` they stamp; reads through the   * adapter or `ctx.secrets` automatically fall through the stack.   */  readonly scopes: readonly Scope[];  readonly storage: TStore;  readonly httpClientLayer: Layer.Layer<HttpClient.HttpClient>;   readonly core: {    readonly sources: {      readonly register: (input: SourceInput) => Effect.Effect<void, StorageFailure>;      readonly unregister: (input: RemoveSourceInput) => Effect.Effect<void, StorageFailure>;      readonly update: (input: {        readonly id: string;        readonly scope: string;        readonly name?: string;        readonly url?: string | null;      }) => Effect.Effect<void, StorageFailure>;    };    /** Register shared JSON-schema `$defs` for a source. Tool     *  input/output schemas registered via `sources.register` can carry     *  `$ref: "#/$defs/X"` pointers; `executor.tools.schema(toolId)`     *  attaches matching defs to the returned schema. Call inside the     *  same `ctx.transaction` as `sources.register` for atomicity.     *  Replaces any existing defs for the given sourceId. */    readonly definitions: {      readonly register: (input: DefinitionsInput) => Effect.Effect<void, StorageFailure>;    };  };   readonly secrets: {    readonly get: (      id: string,    ) => Effect.Effect<string | null, SecretOwnedByConnectionError | StorageFailure>;    readonly getAtScope: (      id: string,      scope: string,    ) => Effect.Effect<string | null, SecretOwnedByConnectionError | StorageFailure>;    /** List user-visible secrets. Connection-owned secrets (rows with     *  `owned_by_connection_id` set) are filtered out so they don't     *  clutter the UI — users see the Connection instead. */    readonly list: () => Effect.Effect<      readonly { readonly id: string; readonly name: string; readonly provider: string }[],      StorageFailure    >;    /** Write a secret value through a provider. Used by plugins that     *  mint secrets on behalf of the user (OAuth2 token storage,     *  interactive onboarding flows). Normally writes go through     *  `executor.secrets.set` on the host surface, but OAuth2 refresh     *  and one-shot token capture from plugin-owned flows need it here     *  too. Same routing rules as the host-level setter. */    readonly set: (input: SetSecretInput) => Effect.Effect<SecretRef, StorageFailure>;    /** Delete a secret from its pinned provider and the core table.     *  Rejects with `SecretOwnedByConnectionError` if the row is owned     *  by a connection — callers must go through `connections.remove`     *  to drop the whole sign-in. Rejects with `SecretInUseError` if     *  any plugin reports the secret as in use; the caller should ask     *  the user to detach the listed sources first. */    readonly remove: (      input: RemoveSecretInput,    ) => Effect.Effect<void, SecretOwnedByConnectionError | SecretInUseError | StorageFailure>;  };   /** Connections — product-level sign-in state. Owns backing secret   *  rows via `secret.owned_by_connection_id`. Plugins call   *  `connections.accessToken(id)` at invoke time to get a guaranteed-   *  fresh token (the SDK handles refresh via the registered provider   *  keyed by `connection.provider`). */  readonly connections: {    readonly get: (id: string) => Effect.Effect<ConnectionRef | null, StorageFailure>;    readonly getAtScope: (      id: string,      scope: string,    ) => Effect.Effect<ConnectionRef | null, StorageFailure>;    readonly list: () => Effect.Effect<readonly ConnectionRef[], StorageFailure>;    readonly create: (      input: CreateConnectionInput,    ) => Effect.Effect<ConnectionRef, ConnectionProviderNotRegisteredError | StorageFailure>;    readonly updateTokens: (      input: UpdateConnectionTokensInput,    ) => Effect.Effect<ConnectionRef, ConnectionNotFoundError | StorageFailure>;    readonly setIdentityLabel: (      id: string,      label: string | null,    ) => Effect.Effect<void, ConnectionNotFoundError | StorageFailure>;    /** Get a guaranteed-fresh access token. Calls the provider's     *  `refresh` handler if `expires_at` is in the past / within the     *  refresh skew window. */    readonly accessToken: (      id: string,    ) => Effect.Effect<      string,      | ConnectionNotFoundError      | ConnectionProviderNotRegisteredError      | ConnectionRefreshNotSupportedError      | ConnectionReauthRequiredError      | ConnectionRefreshError      | StorageFailure    >;    readonly accessTokenAtScope: (      id: string,      scope: string,    ) => Effect.Effect<      string,      | ConnectionNotFoundError      | ConnectionProviderNotRegisteredError      | ConnectionRefreshNotSupportedError      | ConnectionReauthRequiredError      | ConnectionRefreshError      | StorageFailure    >;    /** Refuses with `ConnectionInUseError` if any plugin reports the     *  connection as in use. Caller surfaces the `usages` list to the     *  user. */    readonly remove: (      input: RemoveConnectionInput,    ) => Effect.Effect<void, ConnectionInUseError | StorageFailure>;  };   readonly credentialBindings: CredentialBindingsFacade;   /** Shared OAuth service. Plugins use this to probe/start/complete OAuth   *  flows; invocation should still resolve tokens via `connections.accessToken`. */  readonly oauth: OAuthService;   /** Run `effect` inside a database transaction. Wraps the underlying   *  adapter's transaction method. Use this in extension methods that   *  need atomicity across plugin storage writes AND core source/tool   *  registration. */  readonly transaction: <A, E>(effect: Effect.Effect<A, E>) => Effect.Effect<A, E | StorageFailure>;} // ---------------------------------------------------------------------------// Static tool / source declarations. Pure data + handlers declared at// plugin-definition time.//// Importantly, `StaticToolDecl.handler` does NOT reference TExtension.// If it did, the nested generic would break inference for the whole// PluginSpec (TS would fall back to the `object` constraint on TExtension).// `self: NoInfer<TExtension>` lives on `staticSources` one level up// instead, and plugin authors close over it via the arrow-function// closure when they write their handler.// --------------------------------------------------------------------------- export interface StaticToolHandlerInput<TStore = unknown> {  readonly ctx: PluginCtx<TStore>;  readonly args: unknown;  /** Suspend the fiber to request user input. The handler passed to   *  `createExecutor({ onElicitation })` is called. */  readonly elicit: Elicit;} export interface StaticToolExecuteContext<TStore = unknown> {  readonly ctx: PluginCtx<TStore>;  /** Suspend the fiber to request user input. The handler passed to   *  `createExecutor({ onElicitation })` is called. */  readonly elicit: Elicit;} export type StaticToolSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> &  StandardJSONSchemaV1<Input, Output>; export interface StaticToolDecl<TStore = unknown> {  readonly name: string;  readonly description: string;  readonly inputSchema?: StaticToolSchema;  readonly outputSchema?: StaticToolSchema;  /** Default-policy annotations — `requiresApproval`, `approvalDescription`,   *  `mayElicit`. Enforced by the executor before the handler runs.   *  Inline because static tools have no plugin storage to resolve from;   *  the plugin author literally writes this at definition time. */  readonly annotations?: ToolAnnotations;  readonly handler: (input: StaticToolHandlerInput<TStore>) => Effect.Effect<unknown, unknown>;} const decodeStaticToolArgs = (  schema: StaticToolSchema | undefined,  args: unknown,): Effect.Effect<unknown, unknown> => {  if (schema == null) return Effect.succeed(args);  return Effect.promise(() => Promise.resolve(schema["~standard"].validate(args))).pipe(    Effect.flatMap((result) =>      "value" in result ? Effect.succeed(result.value) : Effect.fail(result),    ),  );}; export interface StaticToolInput<  TStore = unknown,  TInputSchema extends StaticToolSchema | undefined = StaticToolSchema | undefined,> {  readonly name: string;  readonly description: string;  readonly inputSchema?: TInputSchema;  readonly outputSchema?: StaticToolSchema;  /** Default-policy annotations — `requiresApproval`, `approvalDescription`,   *  `mayElicit`. Enforced by the executor before the handler runs. */  readonly annotations?: ToolAnnotations;  readonly execute: (    args: TInputSchema extends StaticToolSchema      ? StandardSchemaV1.InferOutput<TInputSchema>      : unknown,    context: StaticToolExecuteContext<TStore>,  ) => Effect.Effect<unknown, unknown>;} export const tool = <  TStore = unknown,  TInputSchema extends StaticToolSchema | undefined = StaticToolSchema | undefined,>(  input: StaticToolInput<TStore, TInputSchema>,): StaticToolDecl<TStore> => ({  name: input.name,  description: input.description,  inputSchema: input.inputSchema,  outputSchema: input.outputSchema,  annotations: input.annotations,  handler: ({ args, ctx, elicit }) =>    decodeStaticToolArgs(input.inputSchema, args).pipe(      Effect.flatMap((decoded) =>        input.execute(          decoded as TInputSchema extends StaticToolSchema            ? StandardSchemaV1.InferOutput<TInputSchema>            : unknown,          { ctx, elicit },        ),      ),    ),}); export interface StaticSourceDecl<TStore = unknown> {  readonly id: string;  readonly kind: string;  readonly name: string;  readonly url?: string;  /** Static sources default to `canRemove: false` because they are   *  plugin-provided surfaces and shouldn't usually be user-removable.   *  Override only if you really want that. */  readonly canRemove?: boolean;  readonly canRefresh?: boolean;  readonly canEdit?: boolean;  readonly tools: readonly StaticToolDecl<TStore>[];} // ---------------------------------------------------------------------------// Dynamic invoke / source lifecycle inputs.// --------------------------------------------------------------------------- export interface InvokeToolInput<TStore = unknown> {  readonly ctx: PluginCtx<TStore>;  /** Already-loaded tool row. Plugin doesn't need to re-fetch or parse   *  the tool id. Carries source_id, name, input/output schemas,   *  annotations. */  readonly toolRow: ToolRow;  readonly args: unknown;  /** Elicitation handle for plugins that need mid-invocation user input   *  (onepassword auth prompt, interactive MCP tools, etc.). */  readonly elicit: Elicit;} export interface SourceLifecycleInput<TStore = unknown> {  readonly ctx: PluginCtx<TStore>;  readonly sourceId: string;  /**   * Scope of the source row being removed/refreshed — resolved by the   * SDK's `sources.remove` / `sources.refresh` via innermost-wins lookup   * across the executor's scope stack. Plugins that own a side table   * keyed by (id, scope_id) must pin their own cleanup to this scope;   * relying on the scoped adapter's `scope_id IN (stack)` fall-through   * would widen the mutation across the whole stack and wipe a   * shadowed outer-scope row.   */  readonly scope: string;} // ---------------------------------------------------------------------------// PluginSpec — what a `definePlugin(factory)` call returns.// --------------------------------------------------------------------------- // Defaults are `any` for slots that surface in contravariant positions// (storage/extension callbacks consume `TStore`/`TSchema`; `staticSources`// closes over `TExtension` via `NoInfer`). `any` is bivariant, so// `Plugin<string>` is a structural supertype of every concrete plugin// — `AnyPlugin = Plugin<string>` keeps the generic explosion contained// to this single declaration. Concrete specs ignore the defaults; TS// infers each slot from the literal returned by the author factory.//// eslint-disable-next-line @typescript-eslint/no-explicit-anyexport interface PluginSpec<  TId extends string = string,  // eslint-disable-next-line @typescript-eslint/no-explicit-any  TExtension extends object = any,  // eslint-disable-next-line @typescript-eslint/no-explicit-any  TStore = any,  // eslint-disable-next-line @typescript-eslint/no-explicit-any  TSchema extends DBSchema | undefined = any,  // eslint-disable-next-line @typescript-eslint/no-explicit-any  TExtensionService extends Context.Service<any, any> | undefined = any,  // eslint-disable-next-line @typescript-eslint/no-explicit-any  THandlersLayer extends Layer.Layer<any, any, any> = any,  TGroup extends HttpApiGroup.Any = HttpApiGroup.Any,> {  readonly id: TId;  /** npm package name. The Vite plugin uses this to derive the   *  `./client` import path for the frontend bundle (so the same   *  `executor.config.ts` drives both server and client) — `${packageName}/client`   *  is what gets bundled. The author writes the same string they   *  publish to npm; no transforms, no scope conventions. Required for   *  plugins that ship a `./client` entry; can be omitted for SDK-only   *  plugins (no client bundle = nothing to resolve). */  readonly packageName?: string;  /** Plugin-declared schema. Merged with coreSchema and other plugins'   *  schemas at executor startup via `collectSchemas`. The type flows   *  into the `storage` factory's `deps.adapter` as a `TypedAdapter<TSchema>`   *  so plugins get narrowed model names + typed rows for free. */  readonly schema?: TSchema;  /** Build the plugin's typed store from backing. `deps.adapter` is   *  already narrowed to this plugin's schema; `deps.blobs` is already   *  scoped to the plugin id so key collisions across plugins are   *  structurally impossible. */  readonly storage: (deps: StorageDeps<TSchema>) => TStore;   /** JSON-serializable config the plugin wants its `./client` bundle to   *  see. The Vite plugin reads this off each `executor.config.ts` spec   *  at build time and bakes it into the virtual `plugins-client`   *  module by calling the plugin's default `./client` export as a   *  factory: `__p(<JSON.stringify(clientConfig)>)`. Plugins that don't   *  set this stay as bare-value default exports — no churn.   *   *  Use this when a server-side option (e.g. `dangerouslyAllowStdioMCP`)   *  needs to drive client UI behaviour: declaring it once in   *  `executor.config.ts` flows through to the bundle automatically,   *  with no runtime fetch and no parallel client-side flag to keep in   *  sync. */  readonly clientConfig?: unknown;   /** Build the plugin's extension API. The returned object becomes   *  `executor[plugin.id]` and is also the `self` passed to   *  `staticSources`. Field order matters: `extension` MUST appear   *  before `staticSources` so TS infers TExtension from this   *  factory's return BEFORE type-checking `self: NoInfer<TExtension>`. */  readonly extension?: (ctx: PluginCtx<TStore>) => TExtension;   /** Static sources contributed by this plugin with inline tool   *  handlers. Lives entirely in memory — no DB writes at startup.   *  Handlers close over `self` via the closure, so a control tool   *  that delegates to the plugin's real API is a one-liner:   *  `({ args }) => self.addSpec(args)`. */  readonly staticSources?: (self: NoInfer<TExtension>) => readonly StaticSourceDecl<TStore>[];   /** HttpApiGroup contributed by this plugin. Composed into the host's   *  `HttpApi` via the `addGroup` helper at runtime. The host mounts   *  the group at `/_executor/plugins/{id}/...` (or wherever the   *  plugin declares its base path) with the host's auth + scope   *  middleware applied. Endpoints automatically appear in the   *  executor OpenAPI doc and the typed reactive client.   *   *  TGroup is inferred from the plugin's own group declaration so the   *  precise group identity flows through `composePluginApi(plugins)` —   *  the host's typed `HttpApi<"executor", CoreGroups | PluginGroups>`   *  is derived from the plugin tuple alone, with no per-plugin Group   *  imports at the host. Per-endpoint typing already lives inside the   *  plugin — its `handlers` Layer is built against its own bundled   *  `HttpApi.make("foo").add(FooApi)` for full `.handle("name", ...)`   *  inference, and its client imports the same group directly. */  readonly routes?: () => TGroup;   /** Handlers Layer for this plugin's group. Built by the plugin against   *  its own bundled API for full type safety on `.handle("name", ...)`,   *  composes into the host's runtime `FullApi` because   *  `HttpApiBuilder.group` keys the layer by group identity, not by the   *  surrounding API.   *   *  Late-binding: the layer leaves the plugin's extension as a Service   *  Tag requirement (see `extensionService` below). The host satisfies   *  it however its runtime wants:   *    - local: at boot via `Layer.succeed(extensionService)(executor[id])`   *      (see `composePluginHandlers`)   *    - cloud: per-request via `Effect.provideService(extensionService,   *      requestExecutor[id])` in the auth middleware   *   *  The Layer's channels are typed `any` because `Layer<RIn, E, ROut>`'s   *  `ROut` is contravariant — the host accepts any layer here and merges   *  them; per-plugin requirements flow through the merge. */  readonly handlers?: () => THandlersLayer;   /** Service tag the plugin's `handlers` layer requires. Set by plugins   *  whose handlers consume their extension via a `Context.Service` tag   *  (the established pattern: `*Handlers` reads `*ExtensionService`).   *  The host binds the tag to the live extension — at boot for local,   *  per request for cloud. Pairs with `handlers`; either both fields   *  are set or neither.   *   *  Inferred via the `TExtensionService` generic so the per-plugin   *  Service class identity propagates through `composePluginHandlers`,   *  `composePluginHandlerLayer`, and `providePluginExtensions` —   *  cloud's per-request middleware needs the precise tag for layer   *  satisfaction. */  readonly extensionService?: TExtensionService;

Lines 1–500 of 699. Load more