Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

8.0 KB
Raw Blame
/**
 * ProviderDriver / ProviderInstance — driver SPI as plain values.
 *
 * `ProviderDriver` is a record, not a Context.Service. The thing it produces
 * (`ProviderInstance`) is also a record — three captured closures
 * (`snapshot`, `adapter`, `textGeneration`), an id, and a driver kind. There
 * are intentionally no per-driver Context tags because tags are
 * singleton-per-runtime and we need many instances of the same driver.
 *
 * The only Effect service involved is `ProviderInstanceRegistry`, which
 * owns the live `Map<InstanceId, ProviderInstance>` and is itself a
 * singleton.
 *
 * Driver factories are functions of `(typed config, env)` where:
 *   - `typed config` is decoded once by the registry via `configSchema`,
 *     so drivers never deal with raw `unknown`.
 *   - `env` flows through Effect's R channel. Each driver declares the
 *     subset of infrastructure services it needs (FileSystem,
 *     ChildProcessSpawner, …) on its `create` return type; the registry
 *     layer's R is the union of those, and the runtime layer satisfies it.
 *
 * @module provider/ProviderDriver
 */
import type {
  ProviderDriverKind,
  ProviderInstanceConfig,
  ProviderInstanceEnvironment,
  ProviderInstanceId,
  ServerProvider,
} from "@akeru/contracts";
import type * as Effect from "effect/Effect";
import type * as Schema from "effect/Schema";
import type * as Scope from "effect/Scope";
import type * as SchemaError from "effect/SchemaError";

import type * as TextGeneration from "../textGeneration/TextGeneration.ts";
import type { ProviderAdapterError, ProviderDriverError } from "./Errors.ts";
import type { ProviderAdapterShape } from "./Services/ProviderAdapter.ts";
import type { ServerProviderShape } from "./Services/ServerProvider.ts";

/**
 * Static metadata advertised by a driver. Used for default presentation
 * and (later) settings UI. Doesn't need to be Effect-typed because nothing
 * about it is dynamic — drivers are registered at startup.
 */
export interface ProviderDriverMetadata {
  /** Human-readable name for the driver itself (e.g. "Codex"). */
  readonly displayName: string;
  /**
   * Whether the driver may be instantiated more than once concurrently.
   * Defaults to `true`. Set to `false` for drivers that wrap a global
   * resource (e.g. a single desktop app socket) — the registry then
   * rejects multi-instance configurations with a clear error.
   */
  readonly supportsMultipleInstances?: boolean;
}

/**
 * One materialized provider instance. Held by the registry, looked up by
 * `instanceId`, torn down by closing the scope it was created in.
 *
 * The three "shape" fields are captured closures owned by this instance —
 * stopping one instance cannot affect another, and starting a second
 * instance of the same driver does not reach into the first instance's
 * state.
 */
export interface ProviderInstance {
  readonly instanceId: ProviderInstanceId;
  readonly driverKind: ProviderDriverKind;
  readonly continuationIdentity: ProviderContinuationIdentity;
  readonly displayName: string | undefined;
  readonly accentColor?: string | undefined;
  readonly enabled: boolean;
  /**
   * Server-only connection inputs for Akeru's Mastra model transport.
   * This value must never be projected into provider snapshots or wire contracts.
   */
  readonly mastraConnection?: {
    readonly environment: NodeJS.ProcessEnv;
    readonly instanceEnvironment: NodeJS.ProcessEnv;
    readonly useSavedCredential: boolean;
  };
  readonly snapshot: ServerProviderShape;
  /**
   * Optional workspace-scoped snapshot. Grok uses this to probe `grok inspect --json`
   * in the thread cwd so project skills are not cached as an empty machine catalog.
   */
  readonly snapshotForCwd?: (
    workspaceCwd: string,
  ) => Effect.Effect<ServerProvider, ProviderDriverError>;
  /** Present for legacy/provider-native session transports. Mastra-native drivers omit it. */
  readonly adapter: ProviderAdapterShape<ProviderAdapterError> | undefined;
  /** Present when the provider supports app-level title and source-control writing. */
  readonly textGeneration: TextGeneration.TextGeneration["Service"] | undefined;
}

export interface ProviderContinuationIdentity {
  readonly driverKind: ProviderDriverKind;
  readonly continuationKey: string;
}

export function defaultProviderContinuationIdentity(input: {
  readonly driverKind: ProviderDriverKind;
  readonly instanceId: ProviderInstanceId;
}): ProviderContinuationIdentity {
  return {
    driverKind: input.driverKind,
    continuationKey: `${input.driverKind}:instance:${input.instanceId}`,
  };
}

/**
 * Inputs the registry passes to a driver's `create` function.
 *
 * `config` is the typed payload — already decoded by the registry through
 * `driver.configSchema`. Drivers never decode their own raw envelope.
 */
export interface ProviderDriverCreateInput<Config> {
  readonly instanceId: ProviderInstanceId;
  readonly displayName: string | undefined;
  readonly accentColor?: string | undefined;
  readonly environment: ProviderInstanceEnvironment;
  readonly enabled: boolean;
  readonly config: Config;
}

/**
 * Driver SPI — registered as a plain value, not a Layer.
 *
 * `Config` is whatever the driver decoded from
 * `ProviderInstanceConfig.config`. `R` is the union of infrastructure
 * services the driver depends on; the registry layer aggregates `R` across
 * all registered drivers and the runtime supplies them.
 *
 * `create` is responsible for *all* per-instance state — process handles,
 * pubsub topics, refs, file watchers — and must release them when its
 * scope closes. Two calls to `create` with different `instanceId` /
 * `config` MUST yield instances with no shared mutable state.
 */
export interface ProviderDriver<Config, R = never> {
  readonly driverKind: ProviderDriverKind;
  readonly metadata: ProviderDriverMetadata;
  /**
   * Decoder for the opaque `ProviderInstanceConfig.config` envelope. The
   * registry runs this exactly once per (re)load of an instance; a decode
   * failure is surfaced as `ProviderDriverError` and downgraded to an
   * unavailable shadow snapshot.
   *
   * The `Encoded` parameter is intentionally left as `unknown` (not
   * `Config`) so schemas with `withDecodingDefault` / transformations — where
   * the encoded shape differs from the decoded shape — satisfy the SPI
   * without casts. The registry only ever decodes `unknown` envelopes here,
   * so the precise encoded type is irrelevant at this boundary.
   *
   * Using `Codec` rather than `Schema` pins `DecodingServices = never`, so
   * decoding does not add requirements to the registry's R channel.
   */
  readonly configSchema: Schema.Codec<Config, unknown>;
  /**
   * Default config payload used when the legacy
   * `ServerSettings.providers.<kind>` entry is empty or when the driver
   * is auto-bootstrapped without user configuration. Returning a typed
   * default keeps the migration path simple — no special-casing needed
   * to construct a "blank" instance.
   */
  readonly defaultConfig: () => Config;
  /**
   * Materialize one instance. The returned effect runs in a scope owned
   * by the registry; closing that scope releases every resource the
   * driver opened. Failures become unavailable shadow snapshots — the
   * driver MUST NOT throw defects.
   */
  readonly create: (
    input: ProviderDriverCreateInput<Config>,
  ) => Effect.Effect<ProviderInstance, ProviderDriverError, R | Scope.Scope>;
}

/** A prepared config retains its typed driver constructor inside the closure. */
export interface PreparedProviderDriver<R = never> {
  readonly config: unknown;
  readonly create: (
    input: Omit<ProviderDriverCreateInput<never>, "config">,
  ) => Effect.Effect<ProviderInstance, ProviderDriverError, R | Scope.Scope>;
}

/** Registry entry point for drivers with different config schemas. */
export interface AnyProviderDriver<R = never> {
  readonly driverKind: ProviderDriverKind;
  readonly metadata: ProviderDriverMetadata;
  readonly prepare: (
    config: ProviderInstanceConfig["config"],
  ) => Effect.Effect<PreparedProviderDriver<R>, SchemaError.SchemaError>;
}