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 * as Sqlite from 'node:sqlite';
import type { DatabaseSync } from 'node:sqlite';
import { ConfigurationError } from './errors';
import { errorMessage } from './log';
import { type Assignment, assignmentSchema, type ReasonCode } from './schemas';
import type { UpdateAttempt } from './self-update';
/**
* The controller's local state, in one SQLite file: who it is, the last
* assignment it pulled, what it applied for each agent, where each agent's
* events resume, the relay's port, and the status sequence. Everything except
* the identity can be rebuilt from the server; the credential itself is in
* the secret store, never here.
*/
export type Identity = {
controllerId: string;
server: string;
name: string;
enrolledAt: string;
};
export type CachedAssignment =
| { kind: 'none' }
| { kind: 'saved'; assignment: Assignment; etag: string | null }
| { kind: 'unreadable'; detail: string };
export type AgentRow = {
agentId: string;
appliedRevision: number | null;
/** When the controller last started, restarted or stopped it. */
changedAt: string;
/** A failure applying a revision locally, before any process ran. */
failure: { revision: number; reason: ReasonCode; detail: string } | null;
};
const MIGRATIONS: readonly string[] = [
`CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
CREATE TABLE assignment (
id INTEGER PRIMARY KEY CHECK (id = 1),
revision INTEGER NOT NULL,
etag TEXT,
body TEXT NOT NULL,
fetched_at TEXT NOT NULL
);
CREATE TABLE agents (
agent_id TEXT PRIMARY KEY,
applied_revision INTEGER,
changed_at TEXT NOT NULL,
failure_revision INTEGER,
failure_reason TEXT,
failure_detail TEXT,
credentials_stale INTEGER NOT NULL DEFAULT 0,
credentials_refetched_at TEXT
);
CREATE TABLE restarts (agent_id TEXT NOT NULL, at INTEGER NOT NULL);
CREATE INDEX restarts_by_agent ON restarts (agent_id, at);`,
// Agents hold no Switch key, so nothing tracks fetching one; where each
// agent's events resume is kept instead.
`ALTER TABLE agents DROP COLUMN credentials_stale;
ALTER TABLE agents DROP COLUMN credentials_refetched_at;
CREATE TABLE agent_cursors (
agent_id TEXT PRIMARY KEY,
cursor INTEGER NOT NULL,
updated_at TEXT NOT NULL
);`,
// Which of the Linux users set up for agents each agent runs as, when the
// controller runs every agent as a user of its own.
`CREATE TABLE agent_users (
slot INTEGER PRIMARY KEY,
agent_id TEXT NOT NULL UNIQUE,
claimed_at TEXT NOT NULL
);`,
];
export const STORE_SCHEMA_VERSION = MIGRATIONS.length;
/**
* Node 22 announces node:sqlite as experimental on first load. That one
* warning is dropped here, where the module is loaded; every other warning
* passes through untouched.
*/
function loadSqlite(): typeof Sqlite {
const emitWarning = process.emitWarning;
process.emitWarning = ((warning: string | Error, ...rest: unknown[]) => {
const text = typeof warning === 'string' ? warning : warning.message;
const type = typeof rest[0] === 'string' ? rest[0] : (rest[0] as { type?: string })?.type;
if (type === 'ExperimentalWarning' && text.startsWith('SQLite is an experimental feature'))
return;
(emitWarning as (...args: unknown[]) => void).call(process, warning, ...rest);
}) as typeof process.emitWarning;
try {
return process.getBuiltinModule('node:sqlite') as typeof Sqlite;
} finally {
process.emitWarning = emitWarning;
}
}
type Row = Record<string, unknown>;
export class ControllerStore {
private constructor(private readonly db: DatabaseSync) {}
static open(path: string): ControllerStore {
const { DatabaseSync } = loadSqlite();
const db = new DatabaseSync(path);
try {
db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;');
migrate(db);
} catch (error) {
db.close();
throw error;
}
return new ControllerStore(db);
}
close(): void {
this.db.close();
}
schemaVersion(): number {
return Number((this.db.prepare('PRAGMA user_version').get() as Row).user_version);
}
identity(): Identity | null {
const controllerId = this.meta('controller_id');
if (!controllerId) return null;
return {
controllerId,
server: this.requireMeta('server'),
name: this.requireMeta('name'),
enrolledAt: this.requireMeta('enrolled_at'),
};
}
saveIdentity(identity: Identity): void {
this.transaction(() => {
this.setMeta('controller_id', identity.controllerId);
this.setMeta('server', identity.server);
this.setMeta('name', identity.name);
this.setMeta('enrolled_at', identity.enrolledAt);
this.db.prepare("DELETE FROM meta WHERE key = 'revoked_at'").run();
});
}
/**
* Where `enroll` put the controller credential. Null for a data directory
* enrolled before the choice was recorded, which kept it in files.
*/
secretStoreKind(): string | null {
return this.meta('secret_store');
}
saveSecretStoreKind(kind: string): void {
this.setMeta('secret_store', kind);
}
/** Records the name the server now has for this controller. */
saveName(name: string): void {
if (!this.meta('controller_id'))
throw new Error('There is no identity whose name could be changed.');
this.setMeta('name', name);
}
/** Moves the identity to another server URL, keeping everything else. */
saveServer(server: string): void {
if (!this.meta('controller_id'))
throw new Error('There is no identity whose server could be changed.');
this.setMeta('server', server);
}
revokedAt(): string | null {
return this.meta('revoked_at');
}
markRevoked(at: string): void {
this.setMeta('revoked_at', at);
}
/**
* The assignment last pulled. One saved by an earlier version that this one
* no longer reads (a definition field was added since) is `unreadable`, with
* why; the caller discards it and pulls a fresh copy.
*/
cachedAssignment(): CachedAssignment {
const row = this.db.prepare('SELECT etag, body FROM assignment WHERE id = 1').get() as
| Row
| undefined;
if (!row) return { kind: 'none' };
let body: unknown;
try {
body = JSON.parse(String(row.body));
} catch (error) {
return { kind: 'unreadable', detail: errorMessage(error) };
}
const parsed = assignmentSchema.safeParse(body);
if (!parsed.success) return { kind: 'unreadable', detail: parsed.error.message };
return {
kind: 'saved',
assignment: parsed.data,
etag: row.etag === null ? null : String(row.etag),
};
}
discardAssignment(): void {
this.db.prepare('DELETE FROM assignment WHERE id = 1').run();
}
saveAssignment(assignment: Assignment, etag: string | null, at: string): void {
this.db
.prepare(
`INSERT INTO assignment (id, revision, etag, body, fetched_at) VALUES (1, ?, ?, ?, ?)
ON CONFLICT (id) DO UPDATE SET revision = excluded.revision, etag = excluded.etag,
body = excluded.body, fetched_at = excluded.fetched_at`
)
.run(assignment.revision, etag, JSON.stringify(assignment), at);
}
agent(agentId: string): AgentRow | null {
const row = this.db.prepare('SELECT * FROM agents WHERE agent_id = ?').get(agentId) as
| Row
| undefined;
return row ? toAgentRow(row) : null;
}
agents(): AgentRow[] {
return (this.db.prepare('SELECT * FROM agents ORDER BY agent_id').all() as Row[]).map(
toAgentRow
);
}
/** The revision is now what runs (or, for a stopped agent, what is stopped). */
recordApplied(agentId: string, revision: number, at: string): void {
this.db
.prepare(
`INSERT INTO agents (agent_id, applied_revision, changed_at) VALUES (?, ?, ?)
ON CONFLICT (agent_id) DO UPDATE SET applied_revision = excluded.applied_revision,
changed_at = excluded.changed_at, failure_revision = NULL, failure_reason = NULL,
failure_detail = NULL`
)
.run(agentId, revision, at);
}
recordFailure(
agentId: string,
failure: { revision: number; reason: ReasonCode; detail: string },
at: string
): void {
this.db
.prepare(
`INSERT INTO agents (agent_id, applied_revision, changed_at, failure_revision,
failure_reason, failure_detail) VALUES (?, NULL, ?, ?, ?, ?)
ON CONFLICT (agent_id) DO UPDATE SET changed_at = excluded.changed_at,
failure_revision = excluded.failure_revision, failure_reason = excluded.failure_reason,
failure_detail = excluded.failure_detail`
)
.run(agentId, at, failure.revision, failure.reason, failure.detail);
}
deleteAgent(agentId: string): void {
this.transaction(() => {
this.db.prepare('DELETE FROM agents WHERE agent_id = ?').run(agentId);
this.db.prepare('DELETE FROM restarts WHERE agent_id = ?').run(agentId);
this.db.prepare('DELETE FROM agent_cursors WHERE agent_id = ?').run(agentId);
});
}
/**
* Where each agent's events resume on the controller stream: the last
* sequence its watcher confirmed reading.
*/
cursors(): Map<string, number> {
const rows = this.db.prepare('SELECT agent_id, cursor FROM agent_cursors').all() as Row[];
return new Map(rows.map((row) => [String(row.agent_id), Number(row.cursor)]));
}
saveCursor(agentId: string, cursor: number, at: string): void {
this.db
.prepare(
`INSERT INTO agent_cursors (agent_id, cursor, updated_at) VALUES (?, ?, ?)
ON CONFLICT (agent_id) DO UPDATE SET cursor = excluded.cursor,
updated_at = excluded.updated_at`
)
.run(agentId, cursor, at);
}
/** The agent user (`1`…) the agent runs as, or null when it holds none. */
agentUser(agentId: string): number | null {
const row = this.db.prepare('SELECT slot FROM agent_users WHERE agent_id = ?').get(agentId) as
| Row
| undefined;
return row ? Number(row.slot) : null;
}
/**
* The agent user the agent runs as, claiming the lowest free one of
* `1`…`count` when it holds none; null when every one is taken.
*/
claimAgentUser(agentId: string, count: number, at: string): number | null {
return this.transaction(() => {
const held = this.agentUser(agentId);
if (held !== null) return held;
const taken = new Set(
(this.db.prepare('SELECT slot FROM agent_users').all() as Row[]).map((row) =>
Number(row.slot)
)
);
for (let slot = 1; slot <= count; slot++)
if (!taken.has(slot)) {
this.db
.prepare('INSERT INTO agent_users (slot, agent_id, claimed_at) VALUES (?, ?, ?)')
.run(slot, agentId, at);
return slot;
}
return null;
});
}
releaseAgentUser(agentId: string): void {
this.db.prepare('DELETE FROM agent_users WHERE agent_id = ?').run(agentId);
}
/** The loopback port the relay last listened on, which running watchers were given. */
relayPort(): number | null {
const value = this.meta('relay_port');
return value === null ? null : Number(value);
}
saveRelayPort(port: number): void {
this.setMeta('relay_port', String(port));
}
recordRestart(agentId: string, atMs: number): void {
this.transaction(() => {
this.db.prepare('INSERT INTO restarts (agent_id, at) VALUES (?, ?)').run(agentId, atMs);
// Only the last ten minutes are ever asked about.
this.db.prepare('DELETE FROM restarts WHERE at < ?').run(atMs - 60 * 60 * 1000);
});
}
restartsSince(agentId: string, sinceMs: number): number {
const row = this.db
.prepare('SELECT COUNT(*) AS n FROM restarts WHERE agent_id = ? AND at >= ?')
.get(agentId, sinceMs) as Row;
return Number(row.n);
}
/**
* The next status `seq`. Never below the clock in milliseconds, so a data
* directory rebuilt from scratch still sends numbers above the last one the
* server accepted, rather than being ignored until it catches up.
*/
nextStatusSeq(nowMs: number): number {
return this.transaction(() => {
const previous = Number(this.meta('status_seq') ?? '0');
const next = Math.max(previous + 1, Math.floor(nowMs));
this.setMeta('status_seq', String(next));
return next;
});
}
/** The last attempt at updating to a release Switch named; see `SelfUpdater`. */
updateAttempt(): UpdateAttempt | null {
const value = this.meta('update_attempt');
if (value === null) return null;
try {
const parsed = JSON.parse(value) as Partial<UpdateAttempt>;
if (typeof parsed.target === 'string' && typeof parsed.at === 'number')
return {
target: parsed.target,
at: parsed.at,
problem: typeof parsed.problem === 'string' ? parsed.problem : null,
};
} catch {
// Unreadable: as if no attempt was recorded.
}
return null;
}
saveUpdateAttempt(attempt: UpdateAttempt | null): void {
if (attempt === null) this.db.prepare("DELETE FROM meta WHERE key = 'update_attempt'").run();
else this.setMeta('update_attempt', JSON.stringify(attempt));
}
private meta(key: string): string | null {
const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get(key) as Row | undefined;
return row ? String(row.value) : null;
}
private requireMeta(key: string): string {
const value = this.meta(key);
if (value === null) throw new Error(`The controller store is missing '${key}'.`);
return value;
}
private setMeta(key: string, value: string): void {
this.db
.prepare(
'INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value'
)
.run(key, value);
}
private transaction<T>(body: () => T): T {
this.db.exec('BEGIN IMMEDIATE');
try {
const result = body();
this.db.exec('COMMIT');
return result;
} catch (error) {
this.db.exec('ROLLBACK');
throw error;
}
}
}
function migrate(db: DatabaseSync): void {
const current = Number((db.prepare('PRAGMA user_version').get() as Row).user_version);
if (current > MIGRATIONS.length)
throw new ConfigurationError(
`The controller store is at schema version ${current}, newer than this controller understands (${MIGRATIONS.length}). Run a newer controller, or move the data directory aside to start again.`
);
for (let version = current; version < MIGRATIONS.length; version++) {
db.exec('BEGIN IMMEDIATE');
try {
db.exec(MIGRATIONS[version]!);
db.exec(`PRAGMA user_version = ${version + 1}`);
db.exec('COMMIT');
} catch (error) {
db.exec('ROLLBACK');
throw error;
}
}
}
function toAgentRow(row: Row): AgentRow {
return {
agentId: String(row.agent_id),
appliedRevision: row.applied_revision === null ? null : Number(row.applied_revision),
changedAt: String(row.changed_at),
failure:
row.failure_reason === null
? null
: {
revision: Number(row.failure_revision),
reason: String(row.failure_reason) as ReasonCode,
detail: String(row.failure_detail ?? ''),
},
};
}