Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
import type { ModelChoice, SessionContext } from '@switch-console/shared/session-v1';
import type {
ApprovalDecision,
ProviderKind,
ProviderRuntimeEvent,
UserInputAnswers,
} from './events';
/**
* An agent definition in the shape Claude Code's SDK takes it (`AgentDefinition`),
* restricted to what a Switch agent's settings can set.
*/
export type AgentLaunchDefinition = {
description: string;
prompt: string;
tools?: string[];
disallowedTools?: string[];
model?: string;
effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto';
maxTurns?: number;
background?: boolean;
memory?: 'user' | 'project' | 'local';
};
/**
* How much the agent may do without asking. Maps onto each vendor's own
* permission model inside the adapter; orchestration only ever sees this.
* `auto` is the vendor's own automatic review: safe actions run, risky ones
* still ask.
*/
export type RuntimeMode = 'approval-required' | 'auto-accept-edits' | 'auto' | 'full-access';
/**
* The runtime mode an agent's two permission settings select. Bypass
* (`autoApprove`) wins over auto mode.
*/
export function runtimeModeFor(settings: { autoApprove: boolean; autoMode: boolean }): RuntimeMode {
if (settings.autoApprove) return 'full-access';
if (settings.autoMode) return 'auto';
return 'approval-required';
}
export interface StdioMcpServerSpec {
transport: 'stdio';
command: string;
args: string[];
env?: Record<string, string>;
envVars?: string[];
}
export interface HttpMcpServerSpec {
transport: 'http';
url: string;
headers?: Record<string, string>;
}
export type McpServerSpec = StdioMcpServerSpec | HttpMcpServerSpec;
export interface ModelSelection {
id: string;
/** Vendor-specific knobs such as reasoning effort or an OpenCode variant. */
options?: Record<string, string>;
}
export interface ProviderSessionStartInput {
/** Switch's own session id; the adapter keys everything by it. */
sessionId: string;
cwd: string;
runtimeMode: RuntimeMode;
/** Resume the vendor's own session/thread instead of starting a fresh one. */
resume?: { nativeSessionId: string };
model?: ModelSelection;
/** Complete environment for any spawned process. Not merged with `process.env`. */
env: Record<string, string>;
/** MCP servers the session must expose to the agent, keyed by server name. */
mcpServers: Record<string, McpServerSpec>;
/**
* Servers whose tools follow `runtimeMode` instead of being auto-approved:
* the granted connectors' (`host/shared-config.ts`). Every other server in
* {@link mcpServers}, Switch's own above all, is auto-approved in every mode.
*/
connectorMcpServers: string[];
/** Extra system-level context appended to whatever the vendor loads itself. */
systemContext?: string;
/**
* A named agent definition the session should run *as* — its system prompt,
* tool restrictions and model. Claude Code's `--agent <name>`.
*
* Without {@link agentDefinition} the vendor must already know the name —
* Claude Code reads `.claude/agents/<name>.md`, and naming a definition it
* cannot find is an error there.
*/
agentName?: string;
/** The definition of {@link agentName}, handed to the vendor directly instead
* of read from its own files. */
agentDefinition?: AgentLaunchDefinition;
/**
* Codex only: the execution machine's Codex home has no auth.json, so a
* session with no login of its own is handed the API key that Codex keeps
* in the OS keyring as it starts.
*/
codexKeyringLogin?: CodexKeyringLogin;
}
/**
* Where a Codex session's keyring login comes from (`codex/keyring-login.ts`).
* It lives only in the session host's memory: `redact` is a function, so it
* never reaches a configuration file, and the key itself is read anew each
* time the session's Codex starts.
*/
export interface CodexKeyringLogin {
/** The execution machine's own Codex home, whose login is in the keyring. */
home: string;
/** The environment Codex reads that login with. */
env: Record<string, string>;
/** Called with the key as soon as it is read, so everything the host records scrubs it. */
redact: (secret: string) => void;
}
export interface ProviderSession {
sessionId: string;
nativeSessionId: string;
provider: ProviderKind;
}
export interface TurnAttachment {
path: string;
mimeType: string;
}
export interface ProviderSendTurnInput {
sessionId: string;
/** Caller-chosen id; the adapter echoes it in turn events for this turn. */
turnId: string;
text: string;
attachments?: TurnAttachment[];
model?: ModelSelection;
}
export interface ProviderTurnStartResult {
turnId: string;
/**
* When a turn was already running the message was steered into it and this
* is that turn's id, not the requested one.
*/
steeredInto?: string;
}
/** One turn of a saved native conversation, as a transcript that starts with it shows it. */
export interface ConversationHistoryTurn {
/** The same every time the same conversation is read, so reading it twice adds nothing. */
turnId: string;
items: ConversationHistoryItem[];
}
export interface ConversationHistoryItem {
itemId: string;
kind: 'user-message' | 'assistant-message' | 'tool-activity';
status: 'completed' | 'failed';
title: string;
text: string;
}
export interface ProviderCapabilities {
/** The adapter can switch models on a live session, not only at start. */
modelSwitchInSession: boolean;
/** A message sent mid-turn joins the running turn instead of queueing behind it. */
steering: boolean;
/** The adapter can resume a vendor session after its own process died. */
resume: boolean;
/** Permission requests surface as `request.opened` and can be answered. */
approvals: boolean;
/** Clarifying questions surface as `user-input.requested` and can be answered. */
userInput: boolean;
}
/**
* One adapter instance drives many sessions of one provider. Every method is
* keyed by Switch's session id; native ids stay inside the adapter.
*
* Errors are thrown, never returned. A session that dies emits
* `session.exited` and then rejects further calls with `ProviderSessionError`.
*/
export interface ProviderAdapter {
readonly provider: ProviderKind;
readonly capabilities: ProviderCapabilities;
startSession(input: ProviderSessionStartInput): Promise<ProviderSession>;
sendTurn(input: ProviderSendTurnInput): Promise<ProviderTurnStartResult>;
interruptTurn(sessionId: string): Promise<void>;
respondToRequest(sessionId: string, requestId: string, decision: ApprovalDecision): Promise<void>;
respondToUserInput(
sessionId: string,
requestId: string,
answers: UserInputAnswers
): Promise<void>;
compactSession?(sessionId: string): Promise<void>;
canCompact?(sessionId: string): Promise<boolean>;
listModels?(sessionId: string): Promise<ModelChoice[]>;
setModel?(sessionId: string, model: ModelSelection): Promise<void>;
/**
* How full the conversation's context window is now, as the provider
* measures it; null when it has not said. Absent means it never reports one.
*/
contextUsage?(sessionId: string): Promise<Omit<SessionContext, 'updatedAt'> | null>;
/**
* Adds a developer message to the conversation, read by the model before
* the next turn with a developer message's weight. Absent means the provider
* has no such channel; a caller says it in the next user message instead.
*/
addDeveloperMessage?(sessionId: string, text: string): Promise<void>;
/**
* The turns of a saved native conversation, oldest first: what a session
* that continues a conversation started outside Switch shows before its own.
* Read without starting the session, from where a session with `env` would
* find it. Absent means the provider cannot read its saved conversations.
*/
conversationHistory?(
nativeSessionId: string,
cwd: string,
env: Record<string, string>
): Promise<ConversationHistoryTurn[]>;
stopSession(sessionId: string): Promise<void>;
stopAll(): Promise<void>;
hasSession(sessionId: string): boolean;
/**
* Whether the session is still at work outside any turn — subagents started
* in the background that outlive the turn that started them. A session with
* background work is not idle. Absent means the provider has none to report.
*/
hasBackgroundWork?(sessionId: string): boolean;
/** Events for every session this adapter drives. Returns the unsubscribe. */
subscribe(listener: (event: ProviderRuntimeEvent) => void): () => void;
}
export class ProviderSessionError extends Error {
constructor(
readonly provider: ProviderKind,
readonly sessionId: string,
message: string,
options?: { cause?: unknown }
) {
super(`[${provider}:${sessionId}] ${message}`, options);
this.name = 'ProviderSessionError';
}
}
export class ProviderConversationUnavailableError extends ProviderSessionError {}
export class ProviderUnavailableError extends Error {
constructor(
readonly provider: ProviderKind,
message: string,
options?: { cause?: unknown }
) {
super(`[${provider}] ${message}`, options);
this.name = 'ProviderUnavailableError';
}
}