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 { spawn } from 'node:child_process';
import { randomBytes } from 'node:crypto';
import { createWriteStream } from 'node:fs';
import {
copyFile,
cp,
lstat,
mkdir,
mkdtemp,
readdir,
readFile,
realpath,
rename,
rm,
stat,
writeFile,
} from 'node:fs/promises';
import { basename, dirname, join, relative, resolve, sep } from 'node:path';
import {
serveMcpOverHttp,
type ToolDefinition,
type ToolResult,
} from '@sandboxaq/switch-agent-runtime/hosted';
import type { HttpMcpServerSpec } from '../adapter';
import type { Redactions } from './redaction';
import { type CliTool, type ServiceGrant, serviceTokenAnswerSchema } from './service-access';
import { redactServiceToken, type ServiceCredential } from './service-credential';
import type { HostAsk } from './session-channel';
import type { VendorServers } from './vendor-mcp';
/** The most a run may write to its standard output before it is stopped. */
export const CAPTURE_LIMIT_BYTES = 64 * 1024 * 1024;
/** How much of a failed run's standard error is passed on. */
const STDERR_LIMIT_BYTES = 64 * 1024;
const MAX_ARGUMENTS = 200;
const MAX_ARGUMENT_LENGTH = 64 * 1024;
/**
* The host's own settings a run keeps: how this machine reaches the internet
* and which certificate authorities it trusts. Nothing of the coding tool's
* environment reaches a run.
*/
const PASSED_THROUGH = [
'HTTPS_PROXY',
'https_proxy',
'HTTP_PROXY',
'http_proxy',
'ALL_PROXY',
'all_proxy',
'NO_PROXY',
'no_proxy',
'SSL_CERT_FILE',
'SSL_CERT_DIR',
];
/** A command the checker refuses, with why, for the coding tool to read. */
export class CommandRefused extends Error {}
type PathArgument = {
/** Where in the command the path is, and what precedes it there (`--output=`, `-o`, or nothing). */
index: number;
prefix: string;
path: string;
direction: 'read' | 'write';
};
export type CheckedCommand = { args: string[]; paths: PathArgument[] };
function isLong(flag: string): boolean {
return flag.startsWith('--');
}
/** `arg` as an occurrence of `flag`: its value written into it, `''` when the value follows, or null. */
function flagValue(arg: string, flag: string): string | null {
if (arg === flag) return '';
if (arg.startsWith(`${flag}=`)) return arg.slice(flag.length + 1);
if (!isLong(flag) && arg.startsWith(flag)) return arg.slice(flag.length);
return null;
}
/**
* `args` checked against the tool's catalog entry, without touching the
* filesystem: the first argument allowed, no denied command or flag, short
* options never combined (so a path flag cannot hide in a cluster), and every
* path flag's value found.
*/
export function checkCommand(tool: CliTool, args: unknown): CheckedCommand {
if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string'))
throw new CommandRefused('`args` must be a list of strings, one per argument.');
const list = args as string[];
if (list.length === 0)
throw new CommandRefused(`Give a command: one of ${tool.allow.join(', ')}.`);
if (list.length > MAX_ARGUMENTS)
throw new CommandRefused(`A command may have at most ${MAX_ARGUMENTS} arguments.`);
for (const arg of list) {
if (arg.length > MAX_ARGUMENT_LENGTH)
throw new CommandRefused(`An argument may be at most ${MAX_ARGUMENT_LENGTH} characters.`);
if (arg.includes('\0')) throw new CommandRefused('An argument may not contain a NUL.');
}
const [command] = list;
if (tool.deny.includes(command) || !tool.allow.includes(command))
throw new CommandRefused(
`\`${tool.binary} ${command}\` is not available here. The first argument is one of: ${tool.allow.join(', ')}.`
);
const deniedFlags = tool.deny.filter((entry) => entry.startsWith('-'));
const pathFlags = Object.entries(tool.path_flags);
const paths: PathArgument[] = [];
for (let index = 1; index < list.length; index += 1) {
const arg = list[index];
// A positional file argument follows its word directly, wherever the word
// stands; held to that, no option can come between them and hide it.
const positional = tool.path_args.find((path) => path.after === arg);
if (positional) {
const next = list[index + 1];
if (next === undefined || next.startsWith('-'))
throw new CommandRefused(`\`${arg}\` takes a file path right after it.`);
paths.push({ index: index + 1, prefix: '', path: next, direction: positional.direction });
index += 1;
continue;
}
if (!arg.startsWith('-') || arg === '-') continue;
if (arg === '--') throw new CommandRefused('`--` is not accepted; pass options as options.');
const denied = deniedFlags.find((flag) => flagValue(arg, flag) !== null);
if (denied) throw new CommandRefused(`\`${denied}\` is not available here.`);
const pathFlag = pathFlags.find(([flag]) => flagValue(arg, flag) !== null);
if (!pathFlag) {
if (!isLong(arg) && arg.length > 2 && !/^-\d/.test(arg))
throw new CommandRefused(
`Short options may not be combined (\`${arg}\`); give each on its own.`
);
continue;
}
const [flag, direction] = pathFlag;
const inline = flagValue(arg, flag)!;
if (inline !== '') {
paths.push({
index,
prefix: arg.slice(0, arg.length - inline.length),
path: inline,
direction,
});
continue;
}
if (arg.endsWith('=') || index + 1 >= list.length)
throw new CommandRefused(`\`${flag}\` needs a file path.`);
paths.push({ index: index + 1, prefix: '', path: list[index + 1], direction });
index += 1;
}
return { args: list, paths };
}
function inside(root: string, path: string): boolean {
return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
}
/** A path argument, found inside the session's folder: the file read, or the one to write. */
export type ResolvedPath = PathArgument & { file: string };
/**
* Each path argument as the file it names, symbolic links resolved, which
* must be inside the session's folder (`cwd`): a file read must exist; a
* file written must be in an existing folder there, and be a plain file if
* it exists. Done before anything is asked for or run.
*/
export async function resolvePaths(checked: CheckedCommand, cwd: string): Promise<ResolvedPath[]> {
const root = await realpath(cwd);
const resolved: ResolvedPath[] = [];
for (const path of checked.paths) {
const named = resolve(cwd, path.path);
if (path.direction === 'read') {
let source: string;
try {
source = await realpath(named);
} catch {
throw new CommandRefused(`There is no file at \`${path.path}\`.`);
}
if (!inside(root, source))
throw new CommandRefused(`\`${path.path}\` is outside this session's folder.`);
if (!(await stat(source)).isFile())
throw new CommandRefused(`\`${path.path}\` is not a file.`);
resolved.push({ ...path, file: source });
continue;
}
const name = basename(named);
if (!name || path.path.endsWith('/') || path.path.endsWith(sep))
throw new CommandRefused(`\`${path.path}\` names a folder, not a file.`);
let parent: string;
try {
parent = await realpath(dirname(named));
} catch {
throw new CommandRefused(`The folder for \`${path.path}\` does not exist.`);
}
if (!inside(root, parent))
throw new CommandRefused(`\`${path.path}\` is outside this session's folder.`);
const target = join(parent, name);
const existing = await lstat(target).catch(() => null);
if (existing && !existing.isFile())
throw new CommandRefused(`\`${path.path}\` exists and is not a plain file.`);
resolved.push({ ...path, file: target });
}
return resolved;
}
type Staged = { args: string[]; moves: { from: string; to: string; named: string }[] };
/**
* The command with each path argument replaced by a file in the run's own
* folder (`run`): a file read is copied in from the session's folder; a file
* written is moved out to it once the run succeeds.
*/
async function stagePaths(args: string[], paths: ResolvedPath[], run: string): Promise<Staged> {
const staged = [...args];
const moves: Staged['moves'] = [];
for (const [n, path] of paths.entries()) {
const folder = join(run, path.direction === 'read' ? 'in' : 'out', String(n));
await mkdir(folder, { recursive: true });
const inRun = join(folder, basename(path.file));
if (path.direction === 'read') await copyFile(path.file, inRun);
else moves.push({ from: inRun, to: path.file, named: path.path });
staged[path.index] = path.prefix + relative(run, inRun);
}
return { args: staged, moves };
}
/** Moves a file or folder, across filesystems too. */
async function move(from: string, to: string): Promise<void> {
try {
await rename(from, to);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
await cp(from, to, { recursive: true });
await rm(from, { recursive: true, force: true });
}
}
/**
* The run's environment: its token (or its key's fields, each variable of
* `env` rendered from the key), its folders, and the host's network settings.
* Nothing else.
*/
export function runEnvironment(input: {
tool: CliTool;
credential: ServiceCredential;
home: string;
config: string;
tmp: string;
hostEnv: NodeJS.ProcessEnv;
platform: NodeJS.Platform;
}): NodeJS.ProcessEnv {
const env: NodeJS.ProcessEnv = {};
for (const name of PASSED_THROUGH) {
const value = input.hostEnv[name];
if (value) env[name] = value;
}
if (input.platform === 'win32') {
// Windows' networking and TLS need to find the system.
const systemRoot = input.hostEnv.SystemRoot ?? input.hostEnv.SYSTEMROOT;
if (systemRoot) env.SystemRoot = systemRoot;
env.USERPROFILE = input.home;
env.TEMP = input.tmp;
env.TMP = input.tmp;
}
env.HOME = input.home;
env.TMPDIR = input.tmp;
if (input.tool.config_env) env[input.tool.config_env] = input.config;
if (input.tool.env !== null)
for (const [name, template] of Object.entries(input.tool.env))
env[name] = input.credential.render(template);
else if (input.tool.token_env !== null) env[input.tool.token_env] = input.credential.token;
else throw new Error(`${input.tool.name} names no variable to put its token in.`);
return env;
}
type RunOutcome = {
code: number | null;
timedOut: boolean;
overflowed: boolean;
stdoutPath: string;
stdoutBytes: number;
stderr: string;
};
function runBinary(input: {
binary: string;
args: string[];
cwd: string;
env: NodeJS.ProcessEnv;
stdoutPath: string;
timeoutMs: number;
}): Promise<RunOutcome> {
return new Promise((done, fail) => {
const child = spawn(input.binary, input.args, {
cwd: input.cwd,
env: input.env,
shell: false,
windowsHide: true,
stdio: ['ignore', 'pipe', 'pipe'],
});
const out = createWriteStream(input.stdoutPath, { mode: 0o600 });
let stdoutBytes = 0;
let overflowed = false;
let timedOut = false;
const stderr: Buffer[] = [];
let stderrBytes = 0;
const timer = setTimeout(() => {
timedOut = true;
child.kill('SIGKILL');
}, input.timeoutMs);
child.stdout.on('data', (chunk: Buffer) => {
stdoutBytes += chunk.length;
if (stdoutBytes > CAPTURE_LIMIT_BYTES) {
if (!overflowed) child.kill('SIGKILL');
overflowed = true;
return;
}
out.write(chunk);
});
child.stderr.on('data', (chunk: Buffer) => {
if (stderrBytes >= STDERR_LIMIT_BYTES) return;
stderr.push(chunk.subarray(0, STDERR_LIMIT_BYTES - stderrBytes));
stderrBytes += chunk.length;
});
child.once('error', (error) => {
clearTimeout(timer);
out.destroy();
fail(error);
});
child.once('close', (code) => {
clearTimeout(timer);
out.end(() =>
done({
code,
timedOut,
overflowed,
stdoutPath: input.stdoutPath,
stdoutBytes: Math.min(stdoutBytes, CAPTURE_LIMIT_BYTES),
stderr: Buffer.concat(stderr).toString('utf8'),
})
);
});
});
}
function pathValue(document: unknown, path: string): unknown {
let value = document;
for (const part of path.split('.')) {
if (typeof value !== 'object' || value === null) return undefined;
value = (value as Record<string, unknown>)[part];
}
return value;
}
/** Whether a run ended the way the catalog says a refused token does. */
export function refusedToken(tool: CliTool, code: number | null, stdout: string): boolean {
if (code !== tool.token_refused.exit_code) return false;
try {
return pathValue(JSON.parse(stdout), tool.token_refused.json_path) === tool.token_refused.value;
} catch {
return false;
}
}
/**
* Each granted vendor command-line tool, served to this session's CLI on
* loopback as one tool taking `{args}`.
*
* The session host runs the vendor's binary itself, never through a shell:
* each command is checked against the catalog (`checkCommand`), runs in a
* fresh folder of its own holding an empty `.env` (so the tool reads no
* settings from the folders around it), and gets an environment of its token,
* a configuration folder for the session, and the host's network settings.
* The token is asked for on every run over the pipe, added (with each secret
* field of a key) to this session's redactions, and never reaches the coding
* tool: not its environment,
* arguments or files, and not the output, which is redacted. A run that ends
* as the catalog says a refused token does is run once more on a token asked
* for again. Output past the catalog's cap is saved to a file in the session's
* folder (`.switch/<tool>/`, which git ignores), and the path returned.
*/
export async function startVendorClis(input: {
grants: ServiceGrant[];
ask: (ask: HostAsk) => Promise<unknown>;
redactions: Redactions;
/** The session's working folder. */
cwd: string;
/** This session's own folder for the tools' configuration and runs. */
stateDir: string;
binary: (tool: CliTool) => Promise<string>;
hostEnv: NodeJS.ProcessEnv;
platform: NodeJS.Platform;
}): Promise<VendorServers> {
const specs: Record<string, HttpMcpServerSpec> = {};
const closers: (() => Promise<void>)[] = [];
try {
for (const grant of input.grants)
for (const tool of grant.cli_tools) {
const runner = new CliRunner(grant.service, tool, input);
const bearer = randomBytes(32).toString('hex');
const served = await serveMcpOverHttp(bearer, {
listTools: async () => [runner.definition()],
callTool: (name, args) => runner.call(name, args),
});
closers.push(served.close);
specs[tool.name] = {
transport: 'http',
url: served.url,
headers: { Authorization: `Bearer ${bearer}` },
};
}
} catch (error) {
await Promise.all(closers.map((close) => close()));
throw error;
}
return { specs, close: async () => void (await Promise.all(closers.map((close) => close()))) };
}
class CliRunner {
private readonly folder: string;
constructor(
private readonly service: string,
private readonly tool: CliTool,
private readonly deps: {
ask: (ask: HostAsk) => Promise<unknown>;
redactions: Redactions;
cwd: string;
stateDir: string;
binary: (tool: CliTool) => Promise<string>;
hostEnv: NodeJS.ProcessEnv;
platform: NodeJS.Platform;
}
) {
this.folder = join(deps.stateDir, tool.name);
}
definition(): ToolDefinition {
const { binary, allow } = this.tool;
const writes = Object.entries(this.tool.path_flags)
.filter(([, direction]) => direction === 'write')
.map(([flag]) => `\`${flag}\``);
return {
name: binary,
description:
`Runs \`${binary}\`, ${this.service}'s command-line tool, as the agent's owner, with the ` +
`arguments given, one per item and never through a shell. The first argument is one of: ` +
`${allow.join(', ')}. Files read or written must be inside the session's folder` +
(writes.length ? ` (write them with ${writes.join(' or ')})` : '') +
`. Output longer than ${this.tool.output_cap_bytes} bytes is saved to a file, whose ` +
`path is returned.`,
inputSchema: {
type: 'object',
properties: {
args: {
type: 'array',
items: { type: 'string' },
description: `The command line after \`${binary}\`, e.g. ["${allow[0]}", "--help"].`,
},
},
required: ['args'],
additionalProperties: false,
},
};
}
async call(name: string, input: Record<string, unknown>): Promise<ToolResult> {
if (name !== this.tool.binary) throw new Error(`There is no tool ${name} here.`);
let checked: CheckedCommand;
let paths: ResolvedPath[];
try {
checked = checkCommand(this.tool, input.args);
paths = await resolvePaths(checked, this.deps.cwd);
} catch (error) {
if (error instanceof CommandRefused) return refusal(error.message);
throw error;
}
const binary = await this.deps.binary(this.tool);
let rejected: string | null = null;
for (let attempt = 0; ; attempt += 1) {
const credential = await this.credential(rejected);
const result = await this.runOnce(binary, checked.args, paths, credential);
if (result.kind === 'done') return result.result;
if (attempt > 0)
return refusal(
`${this.service} refused this agent's token again after Switch issued a new one.`
);
rejected = credential.token;
}
}
private async credential(rejected: string | null): Promise<ServiceCredential> {
const answer = serviceTokenAnswerSchema.parse(
await this.deps.ask({ type: 'service-token', service: this.service, rejected })
);
if (answer.kind === 'refused') throw new Error(answer.message);
return redactServiceToken(this.deps.redactions, answer.token);
}
private async runOnce(
binary: string,
args: string[],
paths: ResolvedPath[],
credential: ServiceCredential
): Promise<{ kind: 'done'; result: ToolResult } | { kind: 'token-refused' }> {
const home = join(this.folder, 'home');
const config = join(this.folder, 'config');
const runs = join(this.folder, 'runs');
await mkdir(home, { recursive: true, mode: 0o700 });
await mkdir(config, { recursive: true, mode: 0o700 });
await mkdir(runs, { recursive: true, mode: 0o700 });
const base = await mkdtemp(join(runs, 'run-'));
try {
const run = join(base, 'cwd');
const tmp = join(base, 'tmp');
await mkdir(run, { mode: 0o700 });
await mkdir(tmp, { mode: 0o700 });
// An empty .env of its own, so the tool loads none from a folder above.
await writeFile(join(run, '.env'), '', { mode: 0o600 });
const staged = await stagePaths(args, paths, run);
const outcome = await runBinary({
binary,
args: staged.args,
cwd: run,
env: runEnvironment({
tool: this.tool,
credential,
home,
config,
tmp,
hostEnv: this.deps.hostEnv,
platform: this.deps.platform,
}),
stdoutPath: join(base, 'stdout'),
timeoutMs: this.tool.timeout_s * 1000,
});
const stdout = await readFile(outcome.stdoutPath, 'utf8');
if (refusedToken(this.tool, outcome.code, stdout)) return { kind: 'token-refused' };
return { kind: 'done', result: await this.answer(outcome, stdout, staged, run) };
} finally {
await rm(base, { recursive: true, force: true });
}
}
private async answer(
outcome: RunOutcome,
stdout: string,
staged: Staged,
run: string
): Promise<ToolResult> {
const { binary } = this.tool;
const notes: string[] = [];
if (outcome.timedOut)
return refusal(
`\`${binary}\` did not finish within ${this.tool.timeout_s} s and was stopped.`
);
if (outcome.overflowed)
return refusal(
`\`${binary}\` wrote more than ${CAPTURE_LIMIT_BYTES} bytes and was stopped. Ask for ` +
'less, or write the result to a file.'
);
for (const { from, to, named } of staged.moves) {
if (!(await stat(from).catch(() => null))) continue;
if (outcome.code !== 0) {
notes.push(`Left ${named} as it was, since the command failed.`);
continue;
}
await move(from, to);
notes.push(`Wrote ${named}.`);
}
for (const saved of await this.keepStrayFiles(run)) notes.push(`Saved ${saved}.`);
let text = this.deps.redactions.text(stdout);
if (Buffer.byteLength(text) > this.tool.output_cap_bytes) {
const saved = await this.saveOutput(text);
const head = Buffer.from(text).subarray(0, this.tool.output_cap_bytes).toString('utf8');
text =
`The output is ${Buffer.byteLength(text)} bytes, more than ${this.tool.output_cap_bytes}; ` +
`all of it is saved at ${saved}. It begins:\n\n${head}`;
}
const failed = outcome.code !== 0;
const parts = [
...(failed ? [`\`${binary}\` exited with code ${outcome.code}.`] : []),
text,
...(failed && outcome.stderr ? [this.deps.redactions.text(outcome.stderr)] : []),
...notes,
].filter(Boolean);
return {
...(failed ? { isError: true } : {}),
content: [{ type: 'text', text: parts.join('\n') }],
};
}
/** The session's folder for what this tool saves: inside it, and ignored by git. */
private async outputFolder(): Promise<string> {
const folder = join(this.deps.cwd, '.switch', this.tool.name);
await mkdir(folder, { recursive: true });
const ignore = join(folder, '.gitignore');
if (!(await stat(ignore).catch(() => null))) await writeFile(ignore, '*\n');
return folder;
}
private async saveOutput(text: string): Promise<string> {
const folder = await this.outputFolder();
const file = join(folder, `output-${Date.now()}-${randomBytes(3).toString('hex')}.txt`);
await writeFile(file, text);
return relative(this.deps.cwd, file);
}
/** What the run left in its folder unasked, such as a download: moved to the output folder. */
private async keepStrayFiles(run: string): Promise<string[]> {
const kept: string[] = [];
for (const entry of await readdir(run, { withFileTypes: true })) {
if (['.env', 'in', 'out'].includes(entry.name)) continue;
const folder = await this.outputFolder();
const target = join(folder, `${Date.now()}-${entry.name}`);
await move(join(run, entry.name), target);
kept.push(relative(this.deps.cwd, target));
}
return kept;
}
}
function refusal(message: string): ToolResult {
return { isError: true, content: [{ type: 'text', text: message }] };
}