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.

5.9 KB
Raw Blame
import type {
  AkeruConversationMemorySnapshot,
  AkeruMemoryThreadAccess,
  ComposioToolkit,
  BotEngine,
  BotId,
  ModelSelection,
  McpServer,
  ProviderInteractionMode,
  ProviderInterruptTurnInput,
  ProviderRespondToRequestInput,
  ProviderRespondToUserInputInput,
  ProviderRuntimeEvent,
  ProviderSendTurnInput,
  ProviderSession,
  ProviderSessionStartInput,
  ProviderStopSessionInput,
  ProviderTurnStartResult,
  ProviderUploadFeedbackInput,
  ProviderUploadFeedbackResult,
  OrchestrationCommand,
  OrchestrationReadModel,
  OrchestrationThread,
  ThreadId,
} from "@akeru/contracts";
import * as Context from "effect/Context";
import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";

import type { AkeruDelegationDispatch, AkeruDelegationHandle } from "../AkeruDelegationRuntime.ts";
import type { AgentControllerError, AgentControllerRuntimeError } from "../Errors.ts";
import type { ProviderAdapterCapabilities } from "./ProviderAdapter.ts";
import type { ProviderInstanceRoutingInfo } from "./ProviderAdapterRegistry.ts";

export interface AgentControllerAvailableEngine {
  readonly modelSelection: ModelSelection;
  readonly routing: ProviderInstanceRoutingInfo;
  readonly capabilities: ProviderAdapterCapabilities;
}

export interface AgentControllerEngineSelection extends AgentControllerAvailableEngine {
  readonly mode: ProviderInteractionMode;
}

export type AgentControllerSendTurnInput = ProviderSendTurnInput & {
  readonly botUsage?: {
    readonly botId: BotId;
  };
  /**
   * Finished child work acknowledged for this turn, formatted as context. Each
   * provider path adds it to this turn only; it is never queued as a message.
   */
  readonly delegationResults?: string;
};

export interface AgentControllerShape {
  readonly configurePluginRuntime?: (input: {
    readonly readSnapshot: () => Promise<OrchestrationReadModel>;
    readonly dispatch: (
      command: OrchestrationCommand,
    ) => Promise<{ readonly sequence: number } | void>;
    readonly searchComposioToolkits?: (input: {
      readonly query?: string;
      readonly limit?: number;
    }) => Promise<{
      readonly status: "available" | "setup-required" | "unavailable";
      readonly toolkits: readonly ComposioToolkit[];
    }>;
  }) => Effect.Effect<void>;
  readonly configureDelegation?: (input: {
    readonly readSnapshot: () => Promise<OrchestrationReadModel>;
    readonly readThread?: (threadId: ThreadId) => Promise<OrchestrationThread | undefined>;
    readonly dispatch: (command: OrchestrationCommand) => Promise<{ readonly sequence: number }>;
  }) => Effect.Effect<void>;
  readonly failDelegation?: (input: {
    readonly threadId: ThreadId;
    readonly error: string;
  }) => Effect.Effect<void>;
  /** Starts a delegation retry or a scheduled delegation; no live turn owns it. */
  readonly dispatchDelegation?: (
    input: AkeruDelegationDispatch,
  ) => Effect.Effect<AkeruDelegationHandle, AgentControllerRuntimeError>;

  readonly authenticateMcpServer: (input: {
    readonly server: McpServer;
    readonly onAuthorizationUrl: (url: string) => void;
  }) => Effect.Effect<
    { readonly toolCount: number; readonly recoveryFailures: readonly string[] },
    AgentControllerError
  >;

  readonly readConversationMemory?: (
    threadId: ThreadId,
  ) => Effect.Effect<AkeruConversationMemorySnapshot, AgentControllerError>;

  readonly clearConversationMemory?: (
    threadId: ThreadId,
  ) => Effect.Effect<void, AgentControllerError>;

  readonly restoreConversationMemory?: (
    threadId: ThreadId,
    snapshot: AkeruConversationMemorySnapshot,
    expectedSnapshot?: AkeruConversationMemorySnapshot,
  ) => Effect.Effect<void, AgentControllerError>;

  /** Resolve a thread's selected mode and model to an available Akeru provider instance. */
  readonly resolveEngine: (input: {
    readonly threadId: ThreadId;
    readonly engine: BotEngine | null;
    readonly fallback: ModelSelection;
    readonly mode: ProviderInteractionMode;
    readonly botConversation: boolean;
  }) => Effect.Effect<AgentControllerEngineSelection, AgentControllerError>;

  /** Read routing metadata without changing the thread's active runtime session. */
  readonly inspectEngine: (
    modelSelection: ModelSelection,
  ) => Effect.Effect<AgentControllerAvailableEngine, AgentControllerError>;

  readonly startSession: (
    threadId: ThreadId,
    input: ProviderSessionStartInput & { readonly memoryAccess?: AkeruMemoryThreadAccess },
  ) => Effect.Effect<ProviderSession, AgentControllerError>;

  readonly sendTurn: (
    input: AgentControllerSendTurnInput,
  ) => Effect.Effect<ProviderTurnStartResult, AgentControllerError>;

  readonly interruptTurn: (
    input: ProviderInterruptTurnInput,
  ) => Effect.Effect<void, AgentControllerError>;

  readonly respondToRequest: (
    input: ProviderRespondToRequestInput,
  ) => Effect.Effect<void, AgentControllerError>;

  readonly respondToUserInput: (
    input: ProviderRespondToUserInputInput,
  ) => Effect.Effect<void, AgentControllerError>;

  readonly stopSession: (
    input: ProviderStopSessionInput,
  ) => Effect.Effect<void, AgentControllerError>;

  readonly listSessions: () => Effect.Effect<ReadonlyArray<ProviderSession>>;

  readonly rollbackConversation: (input: {
    readonly threadId: ThreadId;
    readonly numTurns: number;
  }) => Effect.Effect<void, AgentControllerError>;

  readonly uploadFeedback: (
    input: ProviderUploadFeedbackInput,
  ) => Effect.Effect<ProviderUploadFeedbackResult, AgentControllerError>;

  /**
   * Codex events are normalized from Mastra controller sessions. Other provider
   * adapters already produce the canonical event contract. Runtime ingestion
   * consumes the merged stream once.
   */
  readonly streamEvents: Stream.Stream<ProviderRuntimeEvent>;
}

export class AgentController extends Context.Service<AgentController, AgentControllerShape>()(
  "akeru-bot/provider/Services/AgentController",
) {}