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.
import * as Match from "effect/Match";
import * as Predicate from "effect/Predicate";
import { createProviderSessionBindings } from "./providerService/ProviderSessionBindings.ts";
import { createProviderMcpSessions } from "./providerService/ProviderMcpSessions.ts";
import { createProviderSessionRecovery } from "./providerService/ProviderSessionRecovery.ts";
import { createProviderSessionListing } from "./providerService/ProviderSessionListing.ts";
import { createProviderSessionStart } from "./providerService/ProviderSessionStart.ts";
/**
* ProviderServiceLive - Cross-provider orchestration layer.
*
* Routes validated transport/API calls to provider adapters through
* `ProviderAdapterRegistry` and `ProviderSessionDirectory`, and exposes a
* unified provider event stream for subscribers.
*
* It does not implement provider protocol details (adapter concern).
*
* @module ProviderServiceLive
*/
import {
ProviderInterruptTurnInput,
ProviderRespondToRequestInput,
ProviderRespondToUserInputInput,
ProviderSendTurnInput,
ProviderStopSessionInput,
ProviderUploadFeedbackInput,
type ProviderInstanceId,
type ProviderRuntimeEvent,
} from "@akeru/contracts";
import { causeErrorTag } from "@akeru/shared/observability";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as PubSub from "effect/PubSub";
import * as Ref from "effect/Ref";
import * as Stream from "effect/Stream";
import { resolveAttachmentPath } from "../../attachmentStore.ts";
import * as ServerConfig from "../../config.ts";
import {
providerMetricAttributes,
providerSessionsTotal,
providerTurnDuration,
providerTurnsTotal,
providerTurnMetricAttributes,
withMetrics,
} from "../../observability/Metrics.ts";
import { type ProviderAdapterError, ProviderUnsupportedError } from "../Errors.ts";
import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
import * as ProviderAdapterRegistry from "../Services/ProviderAdapterRegistry.ts";
import * as ProviderService from "../Services/ProviderService.ts";
import * as ProviderSessionDirectory from "../Services/ProviderSessionDirectory.ts";
import { type EventNdjsonLogger } from "./logging/EventLogTypes.ts";
import * as ProviderEventLoggers from "./ProviderEventLoggers.ts";
import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
import * as McpSessionRegistry from "../../mcp/McpSessionRegistry.ts";
import { cancelActiveImageGenerations } from "../../image-generation/ImageGenerationRuntime.ts";
import * as ServerSettings from "../../serverSettings.ts";
import {
type ProviderServiceMethod,
ProviderRollbackConversationInput,
toValidationError,
decodeInputOrValidationError,
dieOnMissingBindingInstanceId,
} from "./providerService/ProviderSessionMapping.ts";
/**
* Hook for tests that want to override the canonical event logger pulled
* from `ProviderEventLoggers`. Production wiring leaves this undefined and
* reads the logger off the tag.
*/
export interface ProviderServiceLiveOptions {
readonly canonicalEventLogger?: EventNdjsonLogger;
/**
* Overrides MCP credential issuance. The real issuer reads a module-global
* registry that only a running MCP server installs, which makes the
* agent-browser-access gate unobservable from a unit test; this seam lets a
* test see whether a credential was requested at all.
*/
readonly issueMcpCredential?: typeof McpSessionRegistry.issueActiveMcpCredential;
/** Same seam as `issueMcpCredential`, for observing the deny path's revoke. */
readonly revokeMcpCredential?: typeof McpSessionRegistry.revokeActiveMcpThread;
}
const makeProviderService = Effect.fn("makeProviderService")(function* (
options?: ProviderServiceLiveOptions,
) {
const serverConfig = yield* ServerConfig.ServerConfig;
const eventLoggers = yield* ProviderEventLoggers.ProviderEventLoggers;
// Options-provided logger wins (test overrides); otherwise we take whatever
// the `ProviderEventLoggers` tag exposes — `undefined` means "no canonical
// log writer is attached", which downstream code already handles as a
// no-op.
const canonicalEventLogger = options?.canonicalEventLogger ?? eventLoggers.canonical;
const registry = yield* ProviderAdapterRegistry.ProviderAdapterRegistry;
const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
const serverSettings = yield* ServerSettings.ServerSettingsService;
const issueMcpCredential =
options?.issueMcpCredential ?? McpSessionRegistry.issueActiveMcpCredential;
const revokeMcpCredential =
options?.revokeMcpCredential ?? McpSessionRegistry.revokeActiveMcpThread;
const runtimeEventPubSub = yield* PubSub.unbounded<ProviderRuntimeEvent>();
const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
/**
* Attach the `akeru` MCP server to the session that is about to start.
*
* This is the only place a credential is minted, so withholding one here is
* what disables agent browser access everywhere: every adapter already
* treats a missing session as "no MCP server", and the `/mcp` endpoint
* accepts nothing but tokens issued from this path.
*/
/**
* Capabilities for the session's `/mcp` credential: browser preview when
* agent browser access is on, and `generate_image` when an image provider is
* enabled.
*
* Deny on an unreadable settings file rather than letting the read failure
* escape: adding `ServerSettingsError` to `ProviderServiceError` would widen
* a union every caller handles, for a branch that only decides whether one
* optional toolset is attached. Denying is the safe direction — an explicit
* "off" silently becoming "on" would violate the user's stated choice,
* whereas the reverse costs an agent one toolset and is visible immediately.
*/
const { prepareMcpSession, clearMcpSession } = createProviderMcpSessions({
serverSettings,
revokeMcpCredential,
issueMcpCredential,
});
const publishRuntimeEvent = (event: ProviderRuntimeEvent): Effect.Effect<void> =>
Effect.succeed(event).pipe(
Effect.tap((canonicalEvent) =>
canonicalEventLogger
? canonicalEventLogger.write(canonicalEvent, canonicalEvent.threadId)
: Effect.void,
),
Effect.flatMap((canonicalEvent) => PubSub.publish(runtimeEventPubSub, canonicalEvent)),
Effect.asVoid,
);
const { requireBindingInstanceId, upsertSessionBinding, processRuntimeEvent } =
createProviderSessionBindings({
get directory() {
return directory;
},
get publishRuntimeEvent() {
return publishRuntimeEvent;
},
});
// `subscribedAdapters` is our source-of-truth for "which instance adapters
// are currently wired into the runtime event bus". It both tracks the set
// of live subscriptions (so `reconcileInstanceSubscriptions` can diff and
// fork only the *new* or *rebuilt* ones) and serves as the dynamic adapter
// list consumed by `stopStaleSessionsForThread`, `listSessions`, and
// `runStopAll` — replacing the pre-Slice-D startup snapshot so hot-added
// instances become visible to those call sites as soon as settings edits
// land.
const subscribedAdapters = yield* Ref.make(
new Map<ProviderInstanceId, ProviderAdapterShape<ProviderAdapterError>>(),
);
const getAdapterEntries = Ref.get(subscribedAdapters).pipe(
Effect.map((map) => Array.from(map.entries())),
);
// Rebuild the map of id → adapter from the registry and fork a new event
// subscription for every instance that is either brand new or whose adapter
// identity changed (indicating the underlying `ProviderInstance` was torn
// down and rebuilt by `ProviderInstanceRegistry.reconcile`). Orphaned
// fibers for removed/replaced instances exit on their own because their
// adapter's `streamEvents` source terminates when the old scope closes.
const reconcileInstanceSubscriptions = Effect.gen(function* () {
const previous = yield* Ref.get(subscribedAdapters);
const currentIds = yield* registry.listInstances();
const next = new Map<ProviderInstanceId, ProviderAdapterShape<ProviderAdapterError>>();
for (const id of currentIds) {
const adapterOption = yield* registry.getByInstance(id).pipe(
// Mastra-native drivers (Kimi For Coding, OpenCode Go) have no legacy adapter by
// design; their events reach orchestration through the agent controller instead.
Effect.tapError((cause) =>
Effect.logDebug("Provider instance has no legacy adapter event stream", {
instanceId: id,
cause,
}),
),
Effect.option,
);
if (Option.isNone(adapterOption)) continue;
const adapter = adapterOption.value;
next.set(id, adapter);
if (previous.get(id) !== adapter) {
yield* Stream.runForEach(adapter.streamEvents, (event) =>
processRuntimeEvent(
{
instanceId: id,
provider: adapter.provider,
},
event,
),
).pipe(Effect.forkScoped);
}
}
yield* Ref.set(subscribedAdapters, next);
});
const instanceChanges = yield* registry.subscribeChanges;
yield* reconcileInstanceSubscriptions;
yield* Stream.runForEach(
Stream.fromSubscription(instanceChanges),
() => reconcileInstanceSubscriptions,
).pipe(Effect.forkScoped);
const { resolveRoutableSession, stopStaleSessionsForThread } = createProviderSessionRecovery({
requireBindingInstanceId,
registry,
upsertSessionBinding,
prepareMcpSession,
clearMcpSession,
directory,
getAdapterEntries,
});
const startSession = createProviderSessionStart({
registry,
directory,
requireBindingInstanceId,
upsertSessionBinding,
prepareMcpSession,
clearMcpSession,
stopStaleSessionsForThread,
});
const sendTurn: ProviderServiceMethod<"sendTurn"> = Effect.fn("sendTurn")(function* (rawInput) {
const parsed = yield* decodeInputOrValidationError({
operation: "ProviderService.sendTurn",
schema: ProviderSendTurnInput,
payload: rawInput,
});
const attachments = parsed.attachments ?? [];
if (!parsed.input && attachments.length === 0) {
return yield* toValidationError(
"ProviderService.sendTurn",
"Either input text or at least one attachment is required",
);
}
// Adapters inline attachment pixels into the model prompt, but the model's
// tools cannot dereference pixels. Appending the on-disk path is what lets
// a turn like "include this screenshot in the PR" copy the actual file.
// This runs after schema decode, so the appended lines are exempt from the
// PROVIDER_SEND_TURN_MAX_INPUT_CHARS check; attachment count is capped, so
// the overhead is bounded. Unresolvable ids are skipped here and surface
// as adapter errors when the file is read for inlining.
const attachmentPathLines = attachments.flatMap((attachment) => {
const attachmentPath = resolveAttachmentPath({
attachmentsDir: serverConfig.attachmentsDir,
attachment,
});
return attachmentPath === null
? []
: [`[Attached ${attachment.type} "${attachment.name}" is saved at: ${attachmentPath}]`];
});
const inputTextWithAttachmentPaths =
attachmentPathLines.length === 0
? parsed.input
: [parsed.input, attachmentPathLines.join("\n")]
.filter((part): part is string => Predicate.isString(part) && part.length > 0)
.join("\n\n");
const input = {
...parsed,
...(inputTextWithAttachmentPaths !== undefined
? { input: inputTextWithAttachmentPaths }
: {}),
attachments,
};
yield* Effect.annotateCurrentSpan({
"provider.operation": "send-turn",
"provider.thread_id": input.threadId,
"provider.interaction_mode": input.interactionMode,
"provider.attachment_count": input.attachments.length,
});
let metricProvider = "unknown";
let metricModel = input.modelSelection?.model;
return yield* Effect.gen(function* () {
const routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.sendTurn",
allowRecovery: true,
});
// A selection pinned to a different instance than the persisted session
// binding must not reach the adapter: adapters that re-resolve the
// provider would otherwise route the turn away from the session's own
// instance (or silently drop the model switch).
if (
input.modelSelection !== undefined &&
input.modelSelection.instanceId !== routed.instanceId
) {
return yield* toValidationError(
"ProviderService.sendTurn",
`Model selection targets provider instance '${input.modelSelection.instanceId}' but thread '${input.threadId}' is bound to '${routed.instanceId}'.`,
);
}
metricProvider = routed.adapter.provider;
metricModel = input.modelSelection?.model;
yield* Effect.annotateCurrentSpan({
"provider.kind": routed.adapter.provider,
...(input.modelSelection?.model ? { "provider.model": input.modelSelection.model } : {}),
});
// A turn is the clearest sign a session is still alive. The MCP
// credential is minted once at session start and cannot be rotated into
// an already-spawned agent process, so we keep the existing token valid
// rather than issuing a new one: sessions that go a long time between
// browser tool calls used to lose the toolkit outright.
yield* McpSessionRegistry.touchActiveMcpThread(input.threadId);
const turn = yield* routed.adapter.sendTurn(input);
yield* directory.upsert({
threadId: input.threadId,
provider: routed.adapter.provider,
providerInstanceId: routed.instanceId,
status: "running",
...(turn.resumeCursor !== undefined ? { resumeCursor: turn.resumeCursor } : {}),
runtimePayload: {
...(input.modelSelection !== undefined ? { modelSelection: input.modelSelection } : {}),
activeTurnId: turn.turnId,
lastRuntimeEvent: "provider.sendTurn",
lastRuntimeEventAt: yield* nowIso,
},
});
return turn;
}).pipe(
withMetrics({
counter: providerTurnsTotal,
timer: providerTurnDuration,
attributes: () =>
providerTurnMetricAttributes({
provider: metricProvider,
model: metricModel,
extra: {
operation: "send",
},
}),
}),
);
});
const interruptTurn: ProviderServiceMethod<"interruptTurn"> = Effect.fn("interruptTurn")(
function* (rawInput) {
const input = yield* decodeInputOrValidationError({
operation: "ProviderService.interruptTurn",
schema: ProviderInterruptTurnInput,
payload: rawInput,
});
// Stop runs before the image request finishes; an interrupted request
// posts nothing and aborts its provider call.
yield* cancelActiveImageGenerations(input.threadId);
let metricProvider = "unknown";
return yield* Effect.gen(function* () {
const routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.interruptTurn",
allowRecovery: true,
});
metricProvider = routed.adapter.provider;
yield* Effect.annotateCurrentSpan({
"provider.operation": "interrupt-turn",
"provider.kind": routed.adapter.provider,
"provider.thread_id": input.threadId,
"provider.turn_id": input.turnId,
});
yield* routed.adapter.interruptTurn(routed.threadId, input.turnId);
}).pipe(
withMetrics({
counter: providerTurnsTotal,
outcomeAttributes: () =>
providerMetricAttributes(metricProvider, {
operation: "interrupt",
}),
}),
);
},
);
const respondToRequest: ProviderServiceMethod<"respondToRequest"> = Effect.fn("respondToRequest")(
function* (rawInput) {
const input = yield* decodeInputOrValidationError({
operation: "ProviderService.respondToRequest",
schema: ProviderRespondToRequestInput,
payload: rawInput,
});
let metricProvider = "unknown";
return yield* Effect.gen(function* () {
const routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.respondToRequest",
allowRecovery: true,
});
metricProvider = routed.adapter.provider;
yield* Effect.annotateCurrentSpan({
"provider.operation": "respond-to-request",
"provider.kind": routed.adapter.provider,
"provider.thread_id": input.threadId,
"provider.request_id": input.requestId,
});
yield* routed.adapter.respondToRequest(routed.threadId, input.requestId, input.decision);
}).pipe(
withMetrics({
counter: providerTurnsTotal,
outcomeAttributes: () =>
providerMetricAttributes(metricProvider, {
operation: "approval-response",
}),
}),
);
},
);
const respondToUserInput: ProviderServiceMethod<"respondToUserInput"> = Effect.fn(
"respondToUserInput",
)(function* (rawInput) {
const input = yield* decodeInputOrValidationError({
operation: "ProviderService.respondToUserInput",
schema: ProviderRespondToUserInputInput,
payload: rawInput,
});
let metricProvider = "unknown";
return yield* Effect.gen(function* () {
const routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.respondToUserInput",
allowRecovery: true,
});
metricProvider = routed.adapter.provider;
yield* Effect.annotateCurrentSpan({
"provider.operation": "respond-to-user-input",
"provider.kind": routed.adapter.provider,
"provider.thread_id": input.threadId,
"provider.request_id": input.requestId,
});
yield* routed.adapter.respondToUserInput(routed.threadId, input.requestId, input.answers);
}).pipe(
withMetrics({
counter: providerTurnsTotal,
outcomeAttributes: () =>
providerMetricAttributes(metricProvider, {
operation: "user-input-response",
}),
}),
);
});
const stopSession: ProviderServiceMethod<"stopSession"> = Effect.fn("stopSession")(
function* (rawInput) {
const input = yield* decodeInputOrValidationError({
operation: "ProviderService.stopSession",
schema: ProviderStopSessionInput,
payload: rawInput,
});
// A stopped chat must not receive an image that finishes later.
yield* cancelActiveImageGenerations(input.threadId);
let metricProvider = "unknown";
return yield* Effect.gen(function* () {
const routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.stopSession",
allowRecovery: false,
});
metricProvider = routed.adapter.provider;
yield* Effect.annotateCurrentSpan({
"provider.operation": "stop-session",
"provider.kind": routed.adapter.provider,
"provider.thread_id": input.threadId,
});
if (routed.isActive) {
yield* routed.adapter.stopSession(routed.threadId);
}
yield* clearMcpSession(input.threadId);
yield* directory.upsert({
threadId: input.threadId,
provider: routed.adapter.provider,
providerInstanceId: routed.instanceId,
status: "stopped",
runtimePayload: {
activeTurnId: null,
},
});
}).pipe(
withMetrics({
counter: providerSessionsTotal,
outcomeAttributes: () =>
providerMetricAttributes(metricProvider, {
operation: "stop",
}),
}),
);
},
);
const listSessions = createProviderSessionListing({ directory, getAdapterEntries });
const getCapabilities: ProviderServiceMethod<"getCapabilities"> = (instanceId) =>
registry.getByInstance(instanceId).pipe(Effect.map((adapter) => adapter.capabilities));
const getInstanceInfo: ProviderServiceMethod<"getInstanceInfo"> = (instanceId) =>
registry.getInstanceInfo(instanceId);
const dispatchIfEnabled: ProviderServiceMethod<"dispatchIfEnabled"> = (
instanceId,
operation,
dispatch,
) =>
Effect.gen(function* () {
const result = yield* registry.dispatchIfEnabled(instanceId, dispatch);
return yield* Match.value(result).pipe(
Match.tag("Dispatched", ({ value }) => Effect.succeed(value)),
Match.tag("Disabled", () =>
toValidationError(
operation,
`Provider instance '${instanceId}' is disabled in Akeru Bot settings.`,
),
),
Match.tag("Missing", () =>
Effect.fail(new ProviderUnsupportedError({ provider: instanceId })),
),
Match.exhaustive,
);
});
const rollbackConversation: ProviderServiceMethod<"rollbackConversation"> = Effect.fn(
"rollbackConversation",
)(function* (rawInput) {
const input = yield* decodeInputOrValidationError({
operation: "ProviderService.rollbackConversation",
schema: ProviderRollbackConversationInput,
payload: rawInput,
});
if (input.numTurns === 0) {
return;
}
let metricProvider = "unknown";
return yield* Effect.gen(function* () {
const routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.rollbackConversation",
allowRecovery: true,
});
metricProvider = routed.adapter.provider;
yield* Effect.annotateCurrentSpan({
"provider.operation": "rollback-conversation",
"provider.kind": routed.adapter.provider,
"provider.thread_id": input.threadId,
"provider.rollback_turns": input.numTurns,
});
yield* routed.adapter.rollbackThread(routed.threadId, input.numTurns);
}).pipe(
withMetrics({
counter: providerTurnsTotal,
outcomeAttributes: () =>
providerMetricAttributes(metricProvider, {
operation: "rollback",
}),
}),
);
});
const uploadFeedback: ProviderServiceMethod<"uploadFeedback"> = Effect.fn("uploadFeedback")(
function* (rawInput) {
const input = yield* decodeInputOrValidationError({
operation: "ProviderService.uploadFeedback",
schema: ProviderUploadFeedbackInput,
payload: rawInput,
});
let routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.uploadFeedback",
allowRecovery: false,
});
if (routed.adapter.uploadFeedback === undefined) {
return yield* toValidationError(
"ProviderService.uploadFeedback",
`Provider '${routed.adapter.provider}' does not support feedback uploads.`,
);
}
if (!routed.isActive) {
routed = yield* resolveRoutableSession({
threadId: input.threadId,
operation: "ProviderService.uploadFeedback",
allowRecovery: true,
});
}
const uploadFeedback = routed.adapter.uploadFeedback;
if (uploadFeedback === undefined) {
return yield* toValidationError(
"ProviderService.uploadFeedback",
`Provider '${routed.adapter.provider}' does not support feedback uploads.`,
);
}
yield* Effect.annotateCurrentSpan({
"provider.operation": "upload-feedback",
"provider.kind": routed.adapter.provider,
"provider.thread_id": input.threadId,
});
return yield* uploadFeedback(input);
},
);
const runStopAll = Effect.fn("runStopAll")(function* () {
const currentAdapters = yield* getAdapterEntries;
const activeSessions = yield* Effect.forEach(currentAdapters, ([instanceId, adapter]) =>
adapter.listSessions().pipe(
Effect.map((sessions) =>
sessions.map((session) => ({
...session,
providerInstanceId: instanceId,
})),
),
),
).pipe(Effect.map((sessionsByAdapter) => sessionsByAdapter.flatMap((sessions) => sessions)));
yield* Effect.forEach(activeSessions, (session) =>
Effect.flatMap(nowIso, (lastRuntimeEventAt) =>
upsertSessionBinding(session, session.threadId, {
lastRuntimeEvent: "provider.stopAll",
lastRuntimeEventAt,
}),
),
).pipe(Effect.asVoid);
yield* Effect.forEach(currentAdapters, ([, adapter]) => adapter.stopAll()).pipe(Effect.asVoid);
yield* McpSessionRegistry.revokeAllActiveMcpCredentials();
McpProviderSession.clearAllMcpProviderSessions();
const bindings = yield* directory.listBindings().pipe(Effect.orElseSucceed(() => []));
yield* Effect.forEach(bindings, (binding) =>
Effect.gen(function* () {
const providerInstanceId = dieOnMissingBindingInstanceId(
"ProviderService.stopAll",
binding,
);
return yield* directory.upsert({
threadId: binding.threadId,
provider: binding.provider,
providerInstanceId,
status: "stopped",
runtimePayload: {
activeTurnId: null,
lastRuntimeEvent: "provider.stopAll",
lastRuntimeEventAt: yield* nowIso,
},
});
}),
).pipe(Effect.asVoid);
});
yield* Effect.addFinalizer(() =>
runStopAll().pipe(
Effect.catchCause((cause) =>
Effect.logWarning("failed to stop provider service", {
errorTag: causeErrorTag(cause),
}),
),
),
);
return {
startSession,
sendTurn,
interruptTurn,
respondToRequest,
respondToUserInput,
stopSession,
listSessions,
getCapabilities,
getInstanceInfo,
dispatchIfEnabled,
rollbackConversation,
uploadFeedback,
// Each access creates a fresh PubSub subscription so that multiple
// consumers (ProviderRuntimeIngestion, CheckpointReactor, etc.) each
// independently receive all runtime events.
get streamEvents(): ProviderServiceMethod<"streamEvents"> {
return Stream.fromPubSub(runtimeEventPubSub);
},
} satisfies ProviderService.ProviderService["Service"];
});
export const ProviderServiceLive = Layer.effect(
ProviderService.ProviderService,
makeProviderService(),
);
export function providerServiceLayerWith(options?: ProviderServiceLiveOptions) {
return Layer.effect(ProviderService.ProviderService, makeProviderService(options));
}