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 { execFile } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { readFile, stat } from 'node:fs/promises';
import { join } from 'node:path';
import { promisify } from 'node:util';
import { sessionSchema } from '@switch-console/shared/session-v1';
import { z } from 'zod';
import type { CodexKeyringLogin, HttpMcpServerSpec, ProviderSessionStartInput } from '../adapter';
import { codexSourceHome, prepareCodexSessionHome } from '../codex/home';
import { codexKeyringReaderEnvironment } from './agent-env';
import { agentHasOwnUser } from './host-permissions';
import { type HostedCredential, hostedCredentialSchema } from './provider-login';
import { roomConnectionSchema } from './room-inbox';
import { startSchema } from './server';
import {
grantedSkills,
readServiceGrants,
type ServiceGrant,
skillContext,
} from './service-access';
import type { ServiceEndpointServer } from './service-endpoint';
import {
githubSessionEnvironment,
machineGitHubHelpers,
writeGitHubWrapper,
} from './service-github';
export const sharedConfigSchema = z.strictObject({
session: sessionSchema,
resumeOperationId: z.string().uuid().optional(),
start: startSchema,
roomConnection: roomConnectionSchema.optional(),
/**
* The room delivery this session was started to answer, and the right the
* server issued to start it.
*
* Sent with the session's first claim, so the session is created already
* holding the room instead of created empty and then binding it: between
* those two writes the room is free, and the next delivery for it would be
* answered by starting a second session. Absent from a session nobody
* addressed a room message to.
*/
grant: z.strictObject({ roomId: z.string().min(1), messageId: z.string().min(1) }).optional(),
/**
* The session continues a native conversation started outside Switch
* (`start.input.resume`), and its transcript starts with that conversation.
* Absent from every other session, and from configurations written before it.
*/
importHistory: z.boolean().optional(),
execution: z
.strictObject({
credentialsPath: z.string().min(1),
inheritEnv: z.array(z.string()),
shellSetup: z.string().optional(),
binaryPath: z.string().min(1).optional(),
/** Written by Consoles that registered an npx runtime; read by nothing. */
mcpRuntime: z.string().min(1).optional(),
codexConfig: z.string(),
skill: z.string(),
context: z.string(),
/**
* The agent's own instructions, alone (they are also part of
* `context`). What a running conversation is told when they change.
* Absent from configurations written before it existed.
*/
instructions: z.string().optional(),
/**
* A definition on the host's disk to run as, named by an earlier Console.
* Sessions saved then still relaunch from it; a current Console hands the
* definition over in `start.input` instead.
*/
agentDefinition: z
.strictObject({ name: z.string().min(1), path: z.string().min(1) })
.optional(),
})
.optional(),
});
export type SharedHostConfig = z.infer<typeof sharedConfigSchema>;
/** The agent's services as a session starts: its grants, or why Switch could not say. */
export type SessionServices = {
/** Empty when the grants could not be read. */
grants: ServiceGrant[];
/** Why the grants could not be read, or null. */
unavailable: string | null;
};
/**
* Where a session's helpers get its service tokens (`service-endpoint.ts`),
* and the bundle they run from: this host's own, on this host's runtime.
*/
export type ServiceHelpers = {
endpoint: Pick<ServiceEndpointServer, 'url' | 'token'>;
execPath: string;
entrypoint: string;
};
/**
* Whether the session gets Switch's Git credential helper and `gh` wrapper:
* for a GitHub grant, and when the grants could not be read, so that falling
* back to this machine's own sign-in is said, not silent.
*/
export function needsGitHubHelpers(services: SessionServices): boolean {
return (
services.unavailable !== null || services.grants.some((grant) => grant.service === 'github')
);
}
/** What a session is told when its agent's grants could not be read as it started. */
export function servicesUnavailableNotice(reason: string): string {
return (
`Switch could not load the services granted to this agent when this session started (${reason}). ` +
"Their skills and access (GitHub's, for one) are not set up in this session, so do not rely on " +
"them, and say so when a task needs one: git and gh use this machine's own GitHub sign-in here, if it has one, rather than the agent's grant. " +
'They are loaded again when the session next starts.'
);
}
/**
* What the provider is started with. Its Switch tools are `runtime`, the MCP
* server this host serves on loopback: no Switch credential, connection or
* session name reaches the CLI or its environment. With `helpers`, an agent
* granted GitHub gets Git's credential helper and the `gh` wrapper, which ask
* the session's service endpoint for the token. `vendors` are the granted
* vendors' MCP servers this host serves on loopback (`vendor-mcp.ts`), given
* to the CLI beside Switch's own under their own names, and named in
* `connectorMcpServers`, so their tools follow the session's runtime mode
* where Switch's own are always allowed.
*/
export async function prepareSharedConfig(
root: string,
config: SharedHostConfig,
runtime: HttpMcpServerSpec,
services: SessionServices,
helpers: ServiceHelpers | null,
vendors: Record<string, HttpMcpServerSpec>,
redact: (secret: string) => void
) {
if (config.session.provider !== config.start.provider)
throw new Error('Shared SDK host provider mismatch.');
// What the session's owner should see about its services, beyond the log.
const notices: string[] = [];
let agentApiUrl = process.env.SWITCH_API_ENDPOINT;
let token = process.env.SWITCH_API_TOKEN;
const input = structuredClone(config.start.input);
let codexKeyringLogin: CodexKeyringLogin | undefined;
if (config.execution) {
const execution = config.execution;
if (execution.agentDefinition) {
try {
if (!(await stat(join(input.cwd, execution.agentDefinition.path))).isFile())
throw new Error('The provider agent definition is not a file.');
input.agentName = execution.agentDefinition.name;
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
}
}
const credentials = await readSharedCredentials(config);
agentApiUrl = credentials.SWITCH_API_ENDPOINT;
token = credentials.SWITCH_API_TOKEN;
const inherited = await executionEnvironment(
input.cwd,
input.env,
execution.shellSetup,
execution.inheritEnv
);
input.env = { ...inherited, ...input.env };
if (config.start.provider === 'codex') {
const sourceHome = codexSourceHome(input.env);
const prepared = await prepareCodexSessionHome({
root: join(root, 'provider-home'),
sessionId: config.session.sessionId,
sourceHome,
config: execution.codexConfig,
});
if (prepared.keyringLogin)
codexKeyringLogin = {
home: sourceHome,
env: codexKeyringReaderEnvironment(input.env, process.env, process.platform),
redact,
};
input.env.CODEX_HOME = prepared.home;
}
// The skills of the agent's grants join the context for every provider
// but OpenCode, which loads them as files (`adapterFor`), as it does the
// Switch skill. Added here rather than saved with the session, so a
// resume takes the grants as they are then.
input.systemContext = [
execution.context,
...(config.start.provider === 'opencode'
? []
: grantedSkills(services.grants).map(skillContext)),
...(services.unavailable ? [servicesUnavailableNotice(services.unavailable)] : []),
]
.filter(Boolean)
.join('\n\n');
if (helpers && needsGitHubHelpers(services)) {
const wrapperDirectory = join(root, 'bin');
await writeGitHubWrapper({
directory: wrapperDirectory,
execPath: helpers.execPath,
entrypoint: helpers.entrypoint,
});
// An agent run as a user of its own (a cloud machine) keeps every other
// credential helper out; elsewhere the machine's own follow Switch's,
// for when Switch gives no token.
const isolate = agentHasOwnUser();
input.env = {
...input.env,
...githubSessionEnvironment({
env: input.env,
execPath: helpers.execPath,
entrypoint: helpers.entrypoint,
wrapperDirectory,
isolate,
machineHelpers: isolate ? [] : await machineGitHubHelpers(input.env, input.cwd),
}),
SWITCH_SERVICE_ENDPOINT: helpers.endpoint.url,
SWITCH_SERVICE_BEARER: helpers.endpoint.token,
};
}
}
for (const [name, spec] of Object.entries(vendors)) {
if (name === 'switch' || name in input.mcpServers)
throw new Error(`A granted service's MCP server is named ${name}, which is taken.`);
input.mcpServers[name] = spec;
}
input.mcpServers.switch = runtime;
if (!agentApiUrl || !token)
throw new Error('Shared SDK host requires execution-host Switch credentials.');
// Read from the grants as the session starts, never from the saved
// configuration, so a resume follows the grants as they are then.
const started: ProviderSessionStartInput = {
...input,
connectorMcpServers: Object.keys(vendors),
...(codexKeyringLogin ? { codexKeyringLogin } : {}),
};
return { agentApiUrl, token, input: started, notices };
}
/**
* The agent's service grants, read as this session starts.
*
* A session starts without them when Switch cannot tell it what they are: its
* Switch tools and the rest of its work do not depend on them. It is told so
* (`servicesUnavailableNotice`), and the log says why.
*/
export async function sessionServiceGrants(config: SharedHostConfig): Promise<SessionServices> {
if (!config.execution) return { grants: [], unavailable: null };
try {
const credentials = await readSharedCredentials(config);
const grants = await readServiceGrants({
endpoint: credentials.SWITCH_API_ENDPOINT,
token: credentials.SWITCH_API_TOKEN,
agentId: credentials.SWITCH_AGENT_ID,
});
return { grants, unavailable: null };
} catch (error) {
const reason = error instanceof Error ? error.message : String(error);
console.warn(
`Session ${config.session.sessionId} starts without its agent's service grants: ${reason}`
);
return { grants: [], unavailable: reason };
}
}
/**
* The provider login an agent controller hands this agent host with its
* credentials, when the machine has none of its own for the provider and
* Switch gave it one; null when it hands none.
*/
export async function readProviderLogin(
config: SharedHostConfig
): Promise<HostedCredential | null> {
if (!config.execution) return null;
const { providerLogin } = z
.object({ providerLogin: hostedCredentialSchema.nullable().optional() })
.parse(JSON.parse(await readFile(config.execution.credentialsPath, 'utf8')));
if (!providerLogin) return null;
if (providerLogin.status === 'connected' && providerLogin.provider !== config.start.provider)
throw new Error('The provider login handed over is for another provider than this agent’s.');
return providerLogin;
}
export async function readSharedCredentials(config: SharedHostConfig) {
if (!config.execution) throw new Error('Shared execution credentials are required.');
const credentials = z
.object({
env: z.object({
SWITCH_API_ENDPOINT: z.string().min(1),
SWITCH_API_TOKEN: z.string().min(1),
SWITCH_AGENT_ID: z.string().min(1),
// Set when an agent controller runs the agent host in a process of
// its own: the hub it hears its events on instead of Switch.
SWITCH_AGENT_HUB: z.string().min(1).optional(),
}),
})
.parse(JSON.parse(await readFile(config.execution.credentialsPath, 'utf8'))).env;
if (credentials.SWITCH_AGENT_ID !== config.session.agentId)
throw new Error('The execution host credentials belong to a different agent.');
return credentials;
}
export async function executionEnvironment(
cwd: string,
configured: Record<string, string>,
setup: string | undefined,
inheritEnv: string[]
): Promise<Record<string, string>> {
const env: Record<string, string> = {};
const inherited =
process.platform === 'win32'
? new Set(inheritEnv.map((key) => key.toUpperCase()))
: new Set(inheritEnv);
for (const [key, value] of Object.entries(process.env))
if (
value !== undefined &&
inherited.has(process.platform === 'win32' ? key.toUpperCase() : key) &&
!key.startsWith('SWITCH_') &&
!key.startsWith('ELECTRON_')
)
env[key] = value;
Object.assign(env, configured);
if (!setup) return env;
if (process.platform === 'win32')
throw new Error(
"The agent's shell setup is a POSIX shell snippet, which Windows cannot run; remove it from the agent."
);
const marker = randomUUID();
const { stdout } = await promisify(execFile)(
env.SHELL || '/bin/sh',
[
'-lc',
`set -e\n${setup}\nexec "$@"`,
'sdk-environment',
process.execPath,
'-e',
`process.stdout.write(${JSON.stringify(marker)} + JSON.stringify(process.env))`,
],
{ cwd, env, timeout: 30000, maxBuffer: 1024 * 1024 }
);
const offset = stdout.lastIndexOf(marker);
if (offset < 0) throw new Error('Shell setup did not return the execution environment.');
return z.record(z.string(), z.string()).parse(JSON.parse(stdout.slice(offset + marker.length)));
}