Phase 15: Phoenix migration + API hardening + CLI upgrade

Phase 2 of the architecture restructure. Three parallel teams:

Team 2A — Phoenix migration:
- Replaced Plug.Router with Phoenix.Router (pipelines, scoped routes)
- Created Phoenix.Endpoint with CORS support
- All 7 controllers converted to Phoenix.Controller pattern
- Added Phoenix.PubSub for pipeline event broadcasting
- Created SSE EventsController (GET /api/v1/pipeline/:id/events)
- Pipeline broadcasts stage_complete/pipeline_complete events

Team 2B — API hardening:
- Replaced 130-line hand-rolled YAML parser with yaml_elixir
- Created AgentOS.JobTracker GenServer (ETS-backed job status)
- Added pagination to agent list (limit/offset params)
- Created EscrowController (balance + set_balance endpoints)

Team 2C — CLI upgrade:
- Added ~/.agent-os/config.json persistent config
- Added login/logout commands with token storage
- Added audit <pipeline-id> command
- Added contracts list command
- Fixed docker-compose v1 → docker compose v2
- Added progress indicator (dots) for long-running commands
- 13 new CLI tests

196 tests pass (149 Elixir + 47 CLI), zero warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MagnetonIO

cli/src/commands/audit.js

@@ -0,0 +1,46 @@
+/**
+ * Audit commands — trail.
+ *
+ *   agent-os audit <pipeline-id>
+ */
+
+import * as http from '../http.js';
+import * as out from '../output.js';
+
+/**
+ * Show the audit trail for a pipeline run.
+ * GET /api/v1/audit/:id
+ * @param {string[]} args - Positional arguments (args[0] = pipeline id)
+ * @param {object} opts - Global CLI options
+ */
+export async function trail(args, opts) {
+  const id = args[0];
+  if (!id) {
+    out.error('Usage: agent-os audit <pipeline-id>');
+    process.exit(1);
+  }
+
+  const result = await http.get(`/api/v1/audit/${id}`, opts);
+
+  if (opts.json) {
+    out.json(result);
+    return;
+  }
+
+  const entries = result.data || result.entries || result;
+  if (Array.isArray(entries) && entries.length > 0) {
+    out.info(`Audit trail for ${id}:`);
+    const headers = ['TIMESTAMP', 'STAGE', 'STATUS', 'DETAIL'];
+    const rows = entries.map((e) => [
+      e.timestamp || e.ts || '-',
+      e.stage || e.name || '-',
+      e.status || '-',
+      (e.detail || e.message || '-').slice(0, 60),
+    ]);
+    out.table(headers, rows);
+  } else if (Array.isArray(entries)) {
+    out.info(`No audit entries found for ${id}.`);
+  } else {
+    out.json(entries);
+  }
+}

cli/src/commands/auth.js

@@ -0,0 +1,49 @@
+/**
+ * Auth commands — login, logout.
+ */
+
+import * as config from '../config.js';
+import * as out from '../output.js';
+import { createInterface } from 'node:readline';
+
+/**
+ * Prompt the user for an API key via stdin.
+ * @returns {Promise<string>} The entered API key
+ */
+function promptForKey() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question('API key: ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Login — store API key and host in config.
+ * @param {string[]} args - Positional arguments
+ * @param {object} opts - Global CLI options
+ */
+export async function login(args, opts) {
+  const apiKey = opts.apiKey || await promptForKey();
+  if (!apiKey) {
+    out.error('API key is required. Pass --api-key <key> or enter interactively.');
+    process.exit(1);
+  }
+  config.set('apiKey', apiKey);
+  if (opts.host && opts.host !== 'http://localhost:4000') {
+    config.set('host', opts.host);
+  }
+  out.success('Logged in. Config saved to ~/.agent-os/config.json');
+}
+
+/**
+ * Logout — clear stored API key.
+ * @param {string[]} args - Positional arguments
+ * @param {object} opts - Global CLI options
+ */
+export async function logout(args, opts) {
+  config.set('apiKey', null);
+  out.success('Logged out.');
+}

cli/src/commands/contracts.js

@@ -0,0 +1,33 @@
+/**
+ * Contracts commands — list.
+ *
+ *   agent-os contracts list
+ */
+
+import * as http from '../http.js';
+import * as out from '../output.js';
+
+/**
+ * List available contracts.
+ * GET /api/v1/contracts
+ * @param {string[]} args - Positional arguments
+ * @param {object} opts - Global CLI options
+ */
+export async function listContracts(args, opts) {
+  const result = await http.get('/api/v1/contracts', opts);
+
+  if (opts.json) {
+    out.json(result);
+    return;
+  }
+
+  const contracts = result.contracts || result.data || result;
+  if (Array.isArray(contracts) && contracts.length > 0) {
+    out.info('Available contracts:');
+    for (const name of contracts) {
+      out.info(`  - ${typeof name === 'string' ? name : name.name || JSON.stringify(name)}`);
+    }
+  } else {
+    out.info('No contracts found.');
+  }
+}

cli/src/commands/deploy.js

@@ -38,7 +38,7 @@ export async function docker(args, opts) {
   run('docker', ['build', '-t', 'agent-os', '.'], root);
 
   out.info('Starting containers...');
-  run('docker-compose', ['up', '-d'], root);
+  run('docker', ['compose', 'up', '-d'], root);
 
   out.info('Checking health...');
   try {

cli/src/commands/run.js

@@ -34,7 +34,17 @@ export async function runSingle(args, opts) {
   if (opts.model) body.model = opts.model;
   if (opts.provider) body.provider = opts.provider;
 
-  const result = await http.post('/api/v1/run', body, opts);
+  const spinner = setInterval(() => process.stdout.write('.'), 1000);
+  let result;
+  try {
+    result = await http.post('/api/v1/run', body, opts);
+    clearInterval(spinner);
+    console.log(''); // newline after dots
+  } catch (e) {
+    clearInterval(spinner);
+    console.log('');
+    throw e;
+  }
 
   out.success('Pipeline completed!');
 
@@ -68,10 +78,20 @@ export async function runPipeline(args, opts) {
   out.info(`Running pipeline '${opts.contract}'...`);
   out.info(`Topic: ${opts.topic}`);
 
-  const result = await http.post('/api/v1/pipeline/run', {
-    contract: opts.contract,
-    topic: opts.topic,
-  }, opts);
+  const spinner = setInterval(() => process.stdout.write('.'), 1000);
+  let result;
+  try {
+    result = await http.post('/api/v1/pipeline/run', {
+      contract: opts.contract,
+      topic: opts.topic,
+    }, opts);
+    clearInterval(spinner);
+    console.log(''); // newline after dots
+  } catch (e) {
+    clearInterval(spinner);
+    console.log('');
+    throw e;
+  }
 
   out.success('Pipeline completed!');
 

cli/src/config.js

@@ -0,0 +1,37 @@
+/**
+ * Persistent config file support for Agent-OS CLI.
+ * Stores config in ~/.agent-os/config.json.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CONFIG_DIR = join(homedir(), '.agent-os');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export function load() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function save(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+export function get(key) {
+  return load()[key];
+}
+
+export function set(key, value) {
+  const config = load();
+  config[key] = value;
+  save(config);
+}
+
+// Exported for testing
+export { CONFIG_DIR, CONFIG_FILE };

cli/src/http.js

@@ -3,25 +3,27 @@
  * Uses Node.js built-in fetch() (Node 18+).
  */
 
+import * as config from './config.js';
+
 /**
  * Resolve the API host URL.
- * Priority: opts.host → AGENT_OS_HOST env → default.
+ * Priority: opts.host → AGENT_OS_HOST env → config → default.
  * @param {object} opts - Global CLI options
  * @returns {string} Base URL without trailing slash
  */
 function resolveHost(opts = {}) {
-  const host = opts.host || process.env.AGENT_OS_HOST || 'http://localhost:4000';
+  const host = opts.host || process.env.AGENT_OS_HOST || config.get('host') || 'http://localhost:4000';
   return host.replace(/\/+$/, '');
 }
 
 /**
  * Resolve the API key.
- * Priority: opts.apiKey → AGENT_OS_API_KEY env → undefined.
+ * Priority: opts.apiKey → AGENT_OS_API_KEY env → config → undefined.
  * @param {object} opts - Global CLI options
  * @returns {string|undefined}
  */
 function resolveApiKey(opts = {}) {
-  return opts.apiKey || process.env.AGENT_OS_API_KEY || undefined;
+  return opts.apiKey || process.env.AGENT_OS_API_KEY || config.get('apiKey') || undefined;
 }
 
 /**

cli/src/main.js

@@ -13,6 +13,9 @@ import * as jobCmd from './commands/job.js';
 import * as memoryCmd from './commands/memory.js';
 import * as deployCmd from './commands/deploy.js';
 import * as runCmd from './commands/run.js';
+import * as authCmd from './commands/auth.js';
+import * as auditCmd from './commands/audit.js';
+import * as contractsCmd from './commands/contracts.js';
 import * as http from './http.js';
 import * as out from './output.js';
 
@@ -23,6 +26,9 @@ USAGE
   agent-os <command> <subcommand> [options]
 
 COMMANDS
+  login           Store API key          [--api-key <key>] [--host <url>]
+  logout          Clear stored API key
+
   agent create    Create an agent        --type <type> --name <name> [--oversight <level>]
   agent list      List agents
   agent start     Start an agent         <id> --job '<json>'
@@ -38,6 +44,9 @@ COMMANDS
   run <type>      Run a single agent     --topic <topic> [--model <m>] [--provider <p>]
   run pipeline    Run a pipeline         --contract <name> --topic <topic>
 
+  contracts list  List available contracts
+  audit           Show audit trail       <pipeline-id>
+
   deploy docker   Deploy with Docker
   deploy fly      Deploy to Fly.io       [--region <region>] [--app <name>]
 
@@ -148,6 +157,29 @@ export async function main(argv) {
         out.info(`agent-os v${getVersion()}`);
         break;
 
+      case 'login':
+        await authCmd.login(args, opts);
+        break;
+
+      case 'logout':
+        await authCmd.logout(args, opts);
+        break;
+
+      case 'audit':
+        // subcommand becomes the first positional arg for audit
+        await auditCmd.trail(subcommand ? [subcommand, ...args] : args, opts);
+        break;
+
+      case 'contracts':
+        switch (subcommand) {
+          case 'list': await contractsCmd.listContracts(args, opts); break;
+          default:
+            out.error(`Unknown contracts command: ${subcommand}`);
+            out.info('Available: list');
+            process.exit(1);
+        }
+        break;
+
       case 'health': {
         const result = await http.get('/api/v1/health', opts);
         if (opts.json) {