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 { z } from 'zod';
import { validServiceToken } from './service-github';
/**
* An agent's access to its owner's outside services (GitHub, later Jira and
* Google), as Switch grants it.
*
* A session reads the agent's grants when it starts or resumes, through the
* agent's own Switch endpoint: its own key, or the agent controller's relay,
* which forwards `/agents/{id}/...` as the controller. A grant gives the
* session its service's skill and, through the agent host, the service's
* tokens. A change of access reaches its tokens within half a minute
* (`AgentServiceTokens`); a service granted or taken away needs new tools, so
* the agent's watcher restarts the session's host on its own conversation
* once it is idle (`session-services.ts`).
*/
const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/;
const ENV_NAME = /^[A-Z][A-Z0-9_]{0,62}$/;
const COMMAND = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,62}$/;
const FLAG = /^(-[A-Za-z]|--[a-z0-9][a-z0-9-]{0,62})$/;
const HEADER_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
/**
* A vendor's command-line tool, as the catalog entry's `cli` block has it
* (contract §5). The token goes in `token_env`; a key's fields go in `env`'s
* variables instead, each a template of them (`service-credential.ts`).
*/
export const cliToolSchema = z
.object({
name: z.string().regex(SLUG),
binary: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/),
token_env: z.string().regex(ENV_NAME).nullable().default(null),
/** Absent from a Switch from before keys, whose tools all take `token_env`. */
env: z.record(z.string().regex(ENV_NAME), z.string()).nullable().default(null),
config_env: z.string().regex(ENV_NAME).nullable(),
allow: z.array(z.string().regex(COMMAND)).min(1),
deny: z.array(z.string().refine((value) => COMMAND.test(value) || FLAG.test(value))),
path_flags: z.record(z.string().regex(FLAG), z.enum(['read', 'write'])),
/** Positional file arguments: the one right after `after`, wherever it stands. */
path_args: z.array(
z.object({
after: z.string().regex(/^\+?[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/),
direction: z.enum(['read', 'write']),
})
),
output_cap_bytes: z.number().int().min(1024),
timeout_s: z.number().int().min(1),
token_refused: z.object({
exit_code: z.number().int().min(1).max(255),
json_path: z.string().regex(/^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/),
value: z.union([z.number(), z.string()]),
}),
/** The pinned build, per `<platform>-<arch>` as Node names them. */
release: z.object({
version: z.string().regex(/^[0-9A-Za-z][0-9A-Za-z.+-]{0,31}$/),
targets: z.record(
z.string().regex(/^[a-z0-9]+-[a-z0-9]+$/),
z.object({
url: z
.string()
.url()
.refine((url) => url.startsWith('https://')),
sha256: z.string().regex(/^[0-9a-f]{64}$/),
path: z
.string()
.regex(/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,99}(\/[A-Za-z0-9_-][A-Za-z0-9._-]{0,99}){0,3}$/),
})
),
}),
})
.refine((tool) => (tool.token_env === null) !== (tool.env === null), {
message: 'A command-line tool takes its token in token_env or its key in env: one of the two.',
});
export type CliTool = z.infer<typeof cliToolSchema>;
export const serviceGrantSchema = z.object({
service: z.string().regex(SLUG),
access: z.enum(['read', 'write']),
tool_mode: z.enum(['allow', 'deny']),
tools: z.array(z.string()),
resources: z.record(z.string(), z.unknown()),
/** Moves on every change to the grant. Absent from a Switch from before it. */
revision: z.number().int().optional(),
skill: z.object({ name: z.string().regex(SLUG), content: z.string() }).nullable(),
/**
* The vendor's MCP servers a session calls for this service, each under its
* own name. Empty for a service whose tools are not MCP (GitHub's are git
* and gh), and from a Switch that predates them. `url` and each header's
* value are templates of the token (`service-credential.ts`); a Switch from
* before header templates sends none, meaning the token as a bearer.
*/
mcp_servers: z
.array(
z.object({
name: z.string().regex(SLUG),
url: z.string().url(),
headers: z
.record(z.string().regex(HEADER_NAME), z.string())
.default({ Authorization: 'Bearer {token}' }),
})
)
.default([]),
/**
* The vendor's command-line tool, which this host runs for the session
* (`vendor-cli.ts`), as Switch's catalog describes it. Empty for most
* services, and from a Switch that predates it.
*/
cli_tools: z.array(cliToolSchema).default([]),
});
export type ServiceGrant = z.infer<typeof serviceGrantSchema>;
const grantsResponseSchema = z.object({ grants: z.array(serviceGrantSchema) });
/** A granted service's skill: its name and its SKILL.md, frontmatter and all. */
export type ServiceSkill = { name: string; content: string };
/** Where the agent reaches Switch, and as whom. */
export type ServiceEndpoint = { endpoint: string; token: string; agentId: string };
/**
* How long a Switch that answered the grants route with 404 is taken at its
* word before it is asked again. Its refusals are counted: asked on every
* check (every 30 s, and each session start) it soon answers 429 instead,
* which reads as Switch refusing the grants rather than having none.
*/
export const NO_GRANTS_ROUTE_MS = 10 * 60_000;
/** Where the grants route answered 404, by endpoint and agent, until when that is believed. */
const noGrantsRoute = new Map<string, number>();
/**
* The agent's grants. A Switch from before service connections, or one with
* them off, answers the route with 404, which is the truth: it grants nothing.
*/
export async function readServiceGrants(
switchEndpoint: ServiceEndpoint,
fetchImpl: typeof fetch = fetch
): Promise<ServiceGrant[]> {
const url =
switchEndpoint.endpoint.replace(/\/$/, '') +
`/agents/${encodeURIComponent(switchEndpoint.agentId)}/service-grants`;
if ((noGrantsRoute.get(url) ?? 0) > Date.now()) return [];
let response: Response;
try {
response = await fetchImpl(url, {
headers: { Authorization: `Bearer ${switchEndpoint.token}` },
redirect: 'error',
signal: AbortSignal.timeout(15_000),
});
} catch (error) {
throw new Error(
`Switch could not be reached for this agent's service grants: ${error instanceof Error ? error.message : String(error)}`
);
}
if (response.status === 404) {
await response.body?.cancel();
noGrantsRoute.set(url, Date.now() + NO_GRANTS_ROUTE_MS);
return [];
}
noGrantsRoute.delete(url);
if (!response.ok) {
await response.body?.cancel();
throw new Error(`Switch refused this agent's service grants (HTTP ${response.status}).`);
}
return grantsResponseSchema.parse(await response.json()).grants;
}
/** The skills of the agent's grants, one per service. */
export function grantedSkills(grants: ServiceGrant[]): ServiceSkill[] {
return grants.flatMap((grant) => (grant.skill ? [grant.skill] : []));
}
/** A skill as system context: its body, without the frontmatter a skills folder needs. */
export function skillContext(skill: ServiceSkill): string {
return skill.content.replace(/^---\n[\s\S]*?\n---\n+/, '').trim();
}
/**
* Refusals that end a session's use of a service: the grant or the owner's
* connection is gone or changed, and asking again cannot help. Anything else
* (Switch or the service unreachable, say) is worth asking again later.
*/
export function endsServiceUse(code: string): boolean {
return (
code === 'grant_missing' ||
code === 'grant_account_changed' ||
code === 'forbidden' ||
code.startsWith('connector_')
);
}
/** What a session host is answered when it asks for a service token. */
export const serviceTokenAnswerSchema = z.discriminatedUnion('kind', [
z.object({ kind: z.literal('token'), token: z.string().min(1), expiresAt: z.string() }),
z.object({
kind: z.literal('refused'),
code: z.string(),
message: z.string(),
/** The refusal ends this session's use of the service (`endsServiceUse`). */
final: z.boolean(),
}),
]);
export type ServiceTokenAnswer = z.infer<typeof serviceTokenAnswerSchema>;
/**
* A token as this machine holds it, both times on this machine's clock:
* `expiresAt` when the vendor stops taking it, and `useUntil` when Switch
* must be asked again (at most an hour after the issue, so its checks run
* at least hourly whatever the vendor's lifetime). `grantRevision` is the
* grant's revision it was issued under, or null from a Switch from before it,
* whose tokens are kept until `useUntil`.
*/
export type IssuedServiceToken = {
token: string;
expiresAt: number;
useUntil: number;
grantRevision: number | null;
};
export type ServiceRefusal = { code: string; message: string; retryable: boolean };
const issuedSchema = z.object({
token: z.string(),
expires_at: z.string(),
// Additive in contract §5; absent from a Switch that predates them.
expires_in: z.number().int().nonnegative().optional(),
use_until: z.string().optional(),
grant_revision: z.number().int().optional(),
});
const refusalSchema = z.object({
error: z.object({ code: z.string(), message: z.string(), retryable: z.boolean() }),
});
/**
* Ask Switch for a token for `service`, as the agent (contract §5). Each call
* issues one. Raises when Switch cannot be reached or answers nonsense; a
* refusal in the contract's envelope is returned, for the caller to act on.
*/
export async function issueServiceToken(
switchEndpoint: ServiceEndpoint,
service: string,
fetchImpl: typeof fetch = fetch
): Promise<IssuedServiceToken | ServiceRefusal> {
const url =
switchEndpoint.endpoint.replace(/\/$/, '') +
`/agents/${encodeURIComponent(switchEndpoint.agentId)}/service-tokens/${encodeURIComponent(service)}`;
let response: Response;
try {
response = await fetchImpl(url, {
method: 'POST',
headers: { Authorization: `Bearer ${switchEndpoint.token}` },
redirect: 'error',
signal: AbortSignal.timeout(60_000),
});
} catch (error) {
throw new Error(
`Switch could not be reached for a ${service} token: ${error instanceof Error ? error.message : String(error)}`
);
}
if (!response.ok) {
const refusal = refusalSchema.safeParse(await response.json().catch(() => null));
if (refusal.success) return refusal.data.error;
return {
code: `http_${response.status}`,
message: `Switch refused a ${service} token (HTTP ${response.status}).`,
retryable: response.status >= 500,
};
}
const issued = issuedSchema.safeParse(await response.json().catch(() => null));
const expiresAt = issued.success ? Date.parse(issued.data.expires_at) : Number.NaN;
const useUntil =
issued.success && issued.data.use_until !== undefined
? Date.parse(issued.data.use_until)
: expiresAt;
if (
!issued.success ||
!validServiceToken(issued.data.token) ||
!Number.isFinite(expiresAt) ||
!Number.isFinite(useUntil) ||
useUntil > expiresAt
)
throw new Error(`Switch answered a ${service} token request with something that is not one.`);
// Timed from when the answer arrived, by Switch's own count, so this
// machine's clock is never compared with Switch's.
const localExpiry =
issued.data.expires_in !== undefined
? Date.now() + issued.data.expires_in * 1000 - 1000
: onLocalClock(expiresAt, response);
return {
token: issued.data.token,
expiresAt: localExpiry,
useUntil: localExpiry - (expiresAt - useUntil),
grantRevision: issued.data.grant_revision ?? null,
};
}
/**
* `expiresAt`, by Switch's clock, on this machine's: how long the token has
* left by Switch's `Date` header, counted from now. A clock an hour fast would
* otherwise read every token as expired and fetch a new one for each command.
* The header has whole seconds, so a second is taken off to stay early.
*/
function onLocalClock(expiresAt: number, response: Response): number {
const serverNow = Date.parse(response.headers.get('date') ?? '');
if (!Number.isFinite(serverNow)) return expiresAt;
return Date.now() + (expiresAt - serverNow) - 1000;
}