@nullsquare/agent-authority 0.4.0

package/src/agent-auth.js

@@ -0,0 +1,135 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+
+const ISSUER = 'agent-authority';
+const AUDIENCE = 'agent-authority';
+
+function b64url(value) {
+  return Buffer.from(typeof value === 'string' ? value : JSON.stringify(value)).toString('base64url');
+}
+
+function decodeJson(segment, label) {
+  try {
+    return JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+  } catch {
+    const error = new Error(`invalid ${label}`);
+    error.code = 'invalid_agent_token';
+    throw error;
+  }
+}
+
+function sign(key, signingInput) {
+  return createHmac('sha256', key).update(signingInput).digest('base64url');
+}
+
+function tokenError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function parseTtl(value, fallback = 3600) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'number' || /^\d+$/.test(String(value))) return Number(value);
+  const match = String(value).trim().match(/^(\d+)(s|m|h|d)$/i);
+  if (!match) throw new Error('TTL must be seconds or a value such as 30m, 2h, or 1d');
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  return amount * ({ s: 1, m: 60, h: 3600, d: 86400 }[unit]);
+}
+
+export function createAgentToken({
+  key,
+  principal_id,
+  agent_id,
+  mission_id = null,
+  capabilities = ['evaluate', 'prepare', 'execute', 'approval.read'],
+  ttl_seconds = 3600,
+  now = Date.now()
+}) {
+  if (!key || Buffer.byteLength(key) < 32) throw new Error('agent signing key must contain at least 32 bytes');
+  if (!principal_id) throw new Error('principal_id is required');
+  if (!agent_id) throw new Error('agent_id is required');
+  const ttl = Number(ttl_seconds);
+  if (!Number.isFinite(ttl) || ttl < 1 || ttl > 86400) throw new Error('agent token TTL must be between 1 and 86400 seconds');
+
+  const issued = Math.floor(now / 1000);
+  const header = { alg: 'HS256', typ: 'AAUTH' };
+  const payload = {
+    v: 1,
+    iss: ISSUER,
+    aud: AUDIENCE,
+    sub: agent_id,
+    principal_id,
+    mission_id,
+    capabilities: [...new Set(capabilities)],
+    iat: issued,
+    exp: issued + ttl,
+    jti: randomUUID()
+  };
+
+  const encodedHeader = b64url(header);
+  const encodedPayload = b64url(payload);
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  return `${signingInput}.${sign(key, signingInput)}`;
+}
+
+export function decodeAgentToken(token) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) throw tokenError('invalid_agent_token', 'agent token must contain three segments');
+  return { header: decodeJson(parts[0], 'agent token header'), payload: decodeJson(parts[1], 'agent token payload') };
+}
+
+export function verifyAgentToken(token, {
+  key,
+  principal_id,
+  mission = null,
+  mission_id = null,
+  capability = null,
+  now = Date.now()
+} = {}) {
+  if (!key) throw new Error('agent signing key is required');
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) throw tokenError('invalid_agent_token', 'missing or malformed agent bearer token');
+  const [encodedHeader, encodedPayload, providedSignature] = parts;
+  const header = decodeJson(encodedHeader, 'agent token header');
+  const payload = decodeJson(encodedPayload, 'agent token payload');
+  if (header.alg !== 'HS256' || header.typ !== 'AAUTH') throw tokenError('invalid_agent_token', 'unsupported agent token format');
+
+  const expected = sign(key, `${encodedHeader}.${encodedPayload}`);
+  const expectedBuffer = Buffer.from(expected);
+  const providedBuffer = Buffer.from(providedSignature);
+  if (expectedBuffer.length !== providedBuffer.length || !timingSafeEqual(expectedBuffer, providedBuffer)) {
+    throw tokenError('invalid_agent_token', 'agent token signature is invalid');
+  }
+
+  const current = Math.floor(now / 1000);
+  if (payload.iss !== ISSUER || payload.aud !== AUDIENCE || payload.v !== 1) throw tokenError('invalid_agent_token', 'agent token issuer, audience, or version is invalid');
+  if (!payload.sub || !payload.principal_id || !payload.exp) throw tokenError('invalid_agent_token', 'agent token claims are incomplete');
+  if (current >= Number(payload.exp)) throw tokenError('agent_token_expired', 'agent token has expired');
+  if (Number(payload.iat) > current + 60) throw tokenError('invalid_agent_token', 'agent token was issued in the future');
+  if (principal_id && payload.principal_id !== principal_id) throw tokenError('principal_mismatch', 'agent token principal does not match this authority instance');
+
+  const expectedMissionId = mission?.mission_id || mission_id;
+  if (payload.mission_id && expectedMissionId && payload.mission_id !== expectedMissionId) {
+    throw tokenError('mission_binding_mismatch', 'agent token is bound to a different mission');
+  }
+  if (mission) {
+    if (mission.principal?.id !== payload.principal_id) throw tokenError('principal_mismatch', 'mission principal does not match agent token');
+    if (mission.agent?.id !== payload.sub) throw tokenError('agent_identity_mismatch', 'mission agent does not match authenticated agent instance');
+  }
+
+  if (capability) {
+    const capabilities = Array.isArray(payload.capabilities) ? payload.capabilities : [];
+    if (!capabilities.includes('*') && !capabilities.includes(capability)) {
+      throw tokenError('agent_capability_denied', `agent token does not permit ${capability}`);
+    }
+  }
+  return payload;
+}
+
+export function bearerToken(headers = {}) {
+  const value = typeof headers.get === 'function' ? headers.get('authorization') : headers.authorization;
+  const match = String(value || '').match(/^Bearer\s+(.+)$/i);
+  if (!match) throw tokenError('missing_agent_token', 'Authorization: Bearer <agent-token> is required');
+  return match[1].trim();
+}

package/src/approvals.js

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { hashObject } from './index.js';
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  try { chmodSync(path, 0o700); } catch {}
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function atomicJson(path, value) {
+  ensureDir(dirname(path));
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  try { chmodSync(tmp, 0o600); } catch {}
+  renameSync(tmp, path);
+  try { chmodSync(path, 0o600); } catch {}
+}
+
+function approvalError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function requestForFingerprint(request = {}) {
+  const { approval_id, ...rest } = request;
+  return rest;
+}
+
+export function approvalFingerprint(mission, request) {
+  return hashObject({
+    mission_hash: hashObject(mission),
+    request: requestForFingerprint(request)
+  });
+}
+
+function summarizeContext(context = {}) {
+  const summary = {};
+  for (const key of ['repository', 'account', 'resource', 'amount', 'currency', 'domain', 'zone', 'project']) {
+    if (context[key] !== undefined) summary[key] = context[key];
+  }
+  return summary;
+}
+
+export class JsonFileApprovalStore {
+  constructor(path, { defaultTtlSeconds = 600 } = {}) {
+    this.path = path;
+    this.defaultTtlSeconds = defaultTtlSeconds;
+    ensureDir(dirname(path));
+  }
+
+  all() { return readJson(this.path); }
+  write(value) { atomicJson(this.path, value); }
+
+  request({ mission, request, reason = 'human approval required', ttl_seconds = this.defaultTtlSeconds, now = Date.now() }) {
+    const fingerprint = approvalFingerprint(mission, request);
+    const all = this.all();
+    const currentMs = Number(now);
+    const existing = Object.values(all).find((record) =>
+      record.fingerprint === fingerprint &&
+      record.status === 'pending' &&
+      Date.parse(record.expires_at) > currentMs
+    );
+    if (existing) return { ...existing };
+
+    const approvalId = `approval:${randomUUID()}`;
+    const created = new Date(currentMs);
+    const expires = new Date(currentMs + Number(ttl_seconds) * 1000);
+    const record = {
+      approval_id: approvalId,
+      status: 'pending',
+      principal_id: mission.principal.id,
+      agent_id: mission.agent.id,
+      mission_id: mission.mission_id,
+      service: request.service,
+      action: request.action,
+      context: summarizeContext(request.context),
+      reason,
+      fingerprint,
+      created_at: created.toISOString(),
+      expires_at: expires.toISOString(),
+      decided_at: null,
+      decided_by: null,
+      consumed_at: null
+    };
+    all[approvalId] = record;
+    this.write(all);
+    return { ...record };
+  }
+
+  get(approvalId) {
+    const record = this.all()[approvalId];
+    return record ? { ...record } : null;
+  }
+
+  list({ principal_id, status } = {}) {
+    return Object.values(this.all())
+      .filter((record) => !principal_id || record.principal_id === principal_id)
+      .filter((record) => !status || record.status === status)
+      .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))
+      .map((record) => ({ ...record }));
+  }
+
+  decide(approvalId, { principal_id, decision, now = Date.now() }) {
+    if (!['approved', 'denied'].includes(decision)) throw new Error('approval decision must be approved or denied');
+    const all = this.all();
+    const record = all[approvalId];
+    if (!record) throw approvalError('approval_not_found', 'approval request does not exist');
+    if (principal_id && record.principal_id !== principal_id) throw approvalError('principal_mismatch', 'approval belongs to another principal');
+    if (record.status !== 'pending') throw approvalError('approval_already_decided', `approval is already ${record.status}`);
+    if (Date.parse(record.expires_at) <= Number(now)) {
+      record.status = 'expired';
+      all[approvalId] = record;
+      this.write(all);
+      throw approvalError('approval_expired', 'approval request has expired');
+    }
+    record.status = decision;
+    record.decided_at = new Date(Number(now)).toISOString();
+    record.decided_by = principal_id || record.principal_id;
+    all[approvalId] = record;
+    this.write(all);
+    return { ...record };
+  }
+
+  approve(approvalId, options = {}) { return this.decide(approvalId, { ...options, decision: 'approved' }); }
+  deny(approvalId, options = {}) { return this.decide(approvalId, { ...options, decision: 'denied' }); }
+
+  consume(approvalId, { mission, request, now = Date.now() }) {
+    const all = this.all();
+    const record = all[approvalId];
+    if (!record) throw approvalError('approval_not_found', 'approval request does not exist');
+    if (Date.parse(record.expires_at) <= Number(now)) throw approvalError('approval_expired', 'approval request has expired');
+    if (record.status === 'denied') throw approvalError('approval_denied', 'human denied this action');
+    if (record.status === 'consumed' || record.consumed_at) {
+      throw approvalError('approval_replayed', 'approval has already been consumed');
+    }
+    if (record.status !== 'approved') throw approvalError('approval_pending', 'approval has not been granted yet');
+    if (record.principal_id !== mission.principal.id || record.agent_id !== mission.agent.id || record.mission_id !== mission.mission_id) {
+      throw approvalError('approval_binding_mismatch', 'approval is bound to a different principal, agent, or mission');
+    }
+    if (record.fingerprint !== approvalFingerprint(mission, request)) {
+      throw approvalError('approval_binding_mismatch', 'approval is bound to a different action or request context');
+    }
+
+    record.status = 'consumed';
+    record.consumed_at = new Date(Number(now)).toISOString();
+    all[approvalId] = record;
+    this.write(all);
+    return { ...record };
+  }
+}

package/src/cli.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { stdin as input } from 'node:process';
+import { assertMission, evaluateMissionPolicy } from './index.js';
+import { createAgentToken, parseTtl } from './agent-auth.js';
+import { createRuntimeEnvironment } from './runtime-env.js';
+import { authorityHome, ensureAuthorityHome, loadConfig, saveConfig } from './storage.js';
+
+const VERSION = '0.3.0';
+
+function fail(message, code = 1) {
+  console.error(`error: ${message}`);
+  process.exitCode = code;
+}
+
+function json(value) { console.log(JSON.stringify(value, null, 2)); }
+function flag(args, name, fallback = undefined) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] !== undefined ? args[i + 1] : fallback;
+}
+function has(args, name) { return args.includes(name); }
+function homeFrom(args) { return flag(args, '--home', process.env.AGENT_AUTHORITY_HOME || authorityHome()); }
+
+async function readStdinSecret() {
+  if (process.stdin.isTTY) throw new Error('credential input must be piped on stdin; use `printf %s "$TOKEN" | agent-authority connect github --token-stdin`');
+  let value = '';
+  for await (const chunk of input) value += chunk;
+  value = value.trim();
+  if (!value) throw new Error('no credential received on stdin');
+  return value;
+}
+
+function help() {
+  console.log(`Agent Authority ${VERSION}
+
+Usage:
+  agent-authority setup [--principal user:id] [--home PATH]
+  agent-authority status [--home PATH]
+  agent-authority doctor [--home PATH]
+  agent-authority config show [--home PATH]
+  agent-authority serve [--host HOST] [--port PORT] [--home PATH]
+
+MCP gateway (read-only first milestone):
+  agent-authority mcp proxy --upstream URL --mission FILE [--service mcp:NAME] [--port 8790]
+
+Connections:
+  agent-authority connections [--home PATH]
+  agent-authority connect github --token-stdin [--account ID] [--no-verify]
+  agent-authority disconnect github [--account ID]
+
+Agent instances:
+  agent-authority agent token --agent AGENT_ID [--mission MISSION_ID] [--ttl 1h]
+  agent-authority agent token --agent AGENT_ID --admin [--ttl 15m]
+
+Human approvals:
+  agent-authority approvals list [--status pending]
+  agent-authority approvals approve APPROVAL_ID
+  agent-authority approvals deny APPROVAL_ID
+
+Missions:
+  agent-authority mission validate FILE
+  agent-authority mission evaluate FILE --service NAME --action NAME [--repository OWNER/REPO] [--context JSON]
+
+Security:
+  Provider credentials are never accepted as command-line values.
+  Daemon /v1 APIs require short-lived signed agent-instance bearer tokens.
+  Human approvals are one-time and bound to the exact mission + request.
+  MCP proxy binds loopback only and exposes only tools explicitly declared read-only.
+
+Environment:
+  AGENT_AUTHORITY_HOME   Override ~/.agent-authority
+  AGENT_AUTHORITY_HOST   Override serve host
+  AGENT_AUTHORITY_PORT   Override serve port`);
+}
+
+async function setup(args) {
+  const home = homeFrom(args);
+  const principal = flag(args, '--principal', 'user:local');
+  ensureAuthorityHome({ home, principal_id: principal });
+  const config = loadConfig({ home });
+  if (config.principal_id !== principal) {
+    config.principal_id = principal;
+    saveConfig(config, { home });
+  }
+  const env = createRuntimeEnvironment({ home });
+  env.secrets.key();
+  console.log(`✓ Agent Authority initialized at ${home}`);
+  console.log(`Principal: ${principal}`);
+  console.log('Next: agent-authority doctor');
+  console.log('Then connect a provider and issue a short-lived token to an agent harness.');
+}
+
+function safeConnection(c) {
+  const { credential_ref, ...safe } = c;
+  return safe;
+}
+
+async function status(args) {
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  const connections = env.broker.listConnections(env.config.principal_id);
+  const pendingApprovals = env.approvals.list({ principal_id: env.config.principal_id, status: 'pending' }).length;
+  json({
+    version: VERSION,
+    home,
+    principal_id: env.config.principal_id,
+    server: env.config.server,
+    connections,
+    pending_approvals: pendingApprovals,
+    api_authentication: 'agent-instance-bearer-token'
+  });
+}
+
+async function doctor(args) {
+  const home = homeFrom(args);
+  const checks = [];
+  try {
+    const env = createRuntimeEnvironment({ home });
+    checks.push({ check: 'config', ok: true, path: `${home}/config.json` });
+    env.secrets.key();
+    checks.push({ check: 'encrypted-vault', ok: true, path: env.config.paths.secrets });
+    checks.push({ check: 'agent-signing-key', ok: env.agentAuthKey.length === 32, path: env.agentAuthKeyPath });
+    checks.push({ check: 'connections-store', ok: true, count: env.broker.listConnections(env.config.principal_id).length });
+    checks.push({ check: 'approval-store', ok: true, pending: env.approvals.list({ principal_id: env.config.principal_id, status: 'pending' }).length });
+    checks.push({ check: 'loopback-default', ok: env.config.server.host === '127.0.0.1' || env.config.server.host === '::1', host: env.config.server.host });
+  } catch (error) {
+    checks.push({ check: 'runtime', ok: false, error: error.message });
+  }
+  for (const c of checks) console.log(`${c.ok ? '✓' : '✗'} ${c.check}${c.error ? `: ${c.error}` : ''}`);
+  if (checks.some((c) => !c.ok)) process.exitCode = 2;
+}
+
+async function configCommand(args) {
+  const sub = args.shift();
+  if (sub !== 'show') throw new Error('config command currently supports `show`');
+  const home = homeFrom(args);
+  json({ home, ...loadConfig({ home }) });
+}
+
+async function connectionsCommand(args) {
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  json({ connections: env.broker.listConnections(env.config.principal_id) });
+}
+
+async function connectGitHub(args) {
+  if (!has(args, '--token-stdin')) throw new Error('GitHub currently requires --token-stdin; browser OAuth/PKCE is the next provider-onboarding milestone');
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  const token = await readStdinSecret();
+  let accountId = flag(args, '--account');
+  let metadata = {};
+  let scopes = [];
+
+  if (!has(args, '--no-verify')) {
+    const response = await fetch('https://api.github.com/user', {
+      headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'user-agent': 'agent-authority-cli' }
+    });
+    if (!response.ok) throw new Error(`GitHub credential verification failed (${response.status})`);
+    const profile = await response.json();
+    accountId ||= profile.login;
+    metadata = { login: profile.login, id: profile.id, html_url: profile.html_url };
+    const scopeHeader = response.headers.get('x-oauth-scopes');
+    if (scopeHeader) scopes = scopeHeader.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+
+  accountId ||= 'default';
+  const connection = env.broker.connect({
+    principal_id: env.config.principal_id,
+    service: 'github',
+    account_id: accountId,
+    auth_kind: 'github-token',
+    credential: { access_token: token },
+    scopes,
+    metadata
+  });
+  console.log(`✓ GitHub connected as ${metadata.login || accountId}`);
+  json(safeConnection(connection));
+}
+
+async function disconnectGitHub(args) {
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  const accountId = flag(args, '--account', 'default');
+  const result = env.broker.disconnect({ principal_id: env.config.principal_id, service: 'github', account_id: accountId });
+  if (!result) throw new Error(`GitHub account ${accountId} is not connected`);
+  console.log(`✓ GitHub ${accountId} disconnected and local credential removed`);
+}
+
+async function agentCommand(args) {
+  const sub = args.shift();
+  if (sub !== 'token') throw new Error('agent command currently supports `token`');
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  const agentId = flag(args, '--agent');
+  if (!agentId) throw new Error('--agent AGENT_ID is required');
+  const missionId = flag(args, '--mission', null);
+  const ttl = parseTtl(flag(args, '--ttl', has(args, '--admin') ? '15m' : '1h'));
+  const capabilities = has(args, '--admin')
+    ? ['*']
+    : (flag(args, '--capabilities')
+      ? flag(args, '--capabilities').split(',').map((v) => v.trim()).filter(Boolean)
+      : ['evaluate', 'prepare', 'execute', 'approval.read']);
+  const token = createAgentToken({
+    key: env.agentAuthKey,
+    principal_id: env.config.principal_id,
+    agent_id: agentId,
+    mission_id: missionId,
+    capabilities,
+    ttl_seconds: ttl
+  });
+  if (has(args, '--json')) {
+    json({ token, agent_id: agentId, mission_id: missionId, ttl_seconds: ttl, capabilities });
+  } else {
+    console.log(token);
+  }
+}
+
+async function approvalsCommand(args) {
+  const sub = args.shift();
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  if (sub === 'list') {
+    const statusFilter = flag(args, '--status');
+    return json({ approvals: env.approvals.list({ principal_id: env.config.principal_id, status: statusFilter }) });
+  }
+  const approvalId = args.shift();
+  if (!approvalId) throw new Error('approval id is required');
+  if (sub === 'approve') {
+    const result = env.approvals.approve(approvalId, { principal_id: env.config.principal_id });
+    console.log(`✓ approved ${approvalId}`);
+    return json(result);
+  }
+  if (sub === 'deny') {
+    const result = env.approvals.deny(approvalId, { principal_id: env.config.principal_id });
+    console.log(`✓ denied ${approvalId}`);
+    return json(result);
+  }
+  throw new Error('approvals command must be `list`, `approve`, or `deny`');
+}
+
+function loadMission(path) {
+  if (!path) throw new Error('mission file is required');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+async function missionCommand(args) {
+  const sub = args[0];
+  const file = args[1];
+  if (sub === 'validate') {
+    const mission = assertMission(loadMission(file));
+    json({ ok: true, mission_id: mission.mission_id });
+    return;
+  }
+  if (sub === 'evaluate') {
+    const mission = loadMission(file);
+    const service = flag(args, '--service');
+    const action = flag(args, '--action');
+    const repository = flag(args, '--repository');
+    const rawContext = flag(args, '--context');
+    const context = rawContext ? JSON.parse(rawContext) : {};
+    if (repository) context.repository = repository;
+    const result = evaluateMissionPolicy(mission, { service, action, context });
+    json(result);
+    if (result.decision === 'deny') process.exitCode = 3;
+    return;
+  }
+  throw new Error('mission command must be `validate` or `evaluate`');
+}
+
+async function mcpCommand(args) {
+  const sub = args.shift();
+  if (sub !== 'proxy') throw new Error('mcp command currently supports `proxy`');
+  const upstreamUrl = flag(args, '--upstream');
+  const missionPath = flag(args, '--mission');
+  if (!upstreamUrl) throw new Error('--upstream URL is required');
+  if (!missionPath) throw new Error('--mission FILE is required');
+
+  const home = homeFrom(args);
+  const env = createRuntimeEnvironment({ home });
+  const mission = assertMission(loadMission(missionPath));
+  if (mission.principal.id !== env.config.principal_id) {
+    throw new Error(`mission principal ${mission.principal.id} does not match local principal ${env.config.principal_id}`);
+  }
+
+  const host = flag(args, '--host', '127.0.0.1');
+  const port = Number(flag(args, '--port', '8790'));
+  const service = flag(args, '--service', 'mcp:upstream');
+  const { startMcpProxyServer } = await import('./mcp-server.js');
+  const instance = await startMcpProxyServer({
+    mission,
+    runtime: env.runtime,
+    upstreamUrl,
+    service,
+    host,
+    port
+  });
+  console.log(`✓ Agent Authority MCP gateway listening on http://${instance.host}:${instance.port}/mcp`);
+  console.log(`Mission: ${mission.mission_id}`);
+  console.log(`Service: ${service}`);
+  console.log(`Upstream: ${upstreamUrl}`);
+  console.log('Mode: read-only (write tools are not advertised or callable)');
+  return instance;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args.shift();
+  if (!command || command === 'help' || command === '--help' || command === '-h') return help();
+  if (command === '--version' || command === 'version') return console.log(VERSION);
+  if (command === 'setup' || command === 'init') return setup(args);
+  if (command === 'status') return status(args);
+  if (command === 'doctor') return doctor(args);
+  if (command === 'config') return configCommand(args);
+  if (command === 'connections') return connectionsCommand(args);
+  if (command === 'agent') return agentCommand(args);
+  if (command === 'approvals') return approvalsCommand(args);
+  if (command === 'mission') return missionCommand(args);
+  if (command === 'mcp') return mcpCommand(args);
+  if (command === 'connect') {
+    if (args.shift() !== 'github') throw new Error('only the GitHub native connection is implemented today');
+    return connectGitHub(args);
+  }
+  if (command === 'disconnect') {
+    if (args.shift() !== 'github') throw new Error('only the GitHub native connection is implemented today');
+    return disconnectGitHub(args);
+  }
+  if (command === 'serve' || command === 'start') {
+    const { startServer } = await import('./server.js');
+    return startServer({ home: homeFrom(args), host: flag(args, '--host'), port: flag(args, '--port') ? Number(flag(args, '--port')) : undefined });
+  }
+  throw new Error(`unknown command: ${command}`);
+}
+
+main().catch((error) => fail(error.message));