aos-harness 0.4.1 → 0.5.0

package/adapters/claude-code/package.json

@@ -1,12 +1,23 @@
 {
   "name": "@aos-harness/claude-code-adapter",
-  "version": "0.2.0",
+  "version": "0.5.0",
+  "description": "AOS Harness adapter for Anthropic's Claude Code CLI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aos-engineer/aos-harness.git",
+    "directory": "adapters/claude-code"
+  },
+  "homepage": "https://aos.engineer",
+  "keywords": ["aos-harness", "ai-agents", "claude-code", "adapter"],
   "type": "module",
+  "engines": { "bun": ">=1.0.0" },
   "exports": { ".": "./src/index.ts" },
-  "files": ["src/"],
+  "files": ["src/", "README.md"],
+  "publishConfig": { "access": "public" },
   "dependencies": {
-    "@aos-harness/runtime": "0.4.1",
-    "@aos-harness/adapter-shared": "0.4.1"
+    "@aos-harness/runtime": "0.5.0",
+    "@aos-harness/adapter-shared": "0.5.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/adapters/claude-code/src/agent-runtime.ts

@@ -17,6 +17,13 @@ import {
 } from "@aos-harness/adapter-shared";
 import type { BaseEventBus } from "@aos-harness/adapter-shared";
 
+// ── McpBridgeOptions ─────────────────────────────────────────────
+
+export interface McpBridgeOptions {
+  bridgeScriptPath: string;
+  socketPath: string;
+}
+
 // ── ClaudeCodeAgentRuntime ────────────────────────────────────────
 
 export class ClaudeCodeAgentRuntime extends BaseAgentRuntime {
@@ -57,6 +64,9 @@ export class ClaudeCodeAgentRuntime extends BaseAgentRuntime {
       args.push("--resume", state.sessionFile);
     }
 
+    // Extra args (e.g. MCP flags) are spliced in before the positional message
+    args.push(...(opts?.extraArgs ?? []));
+
     // Message is always the final argument
     args.push(message);
     return args;
@@ -179,4 +189,22 @@ export class ClaudeCodeAgentRuntime extends BaseAgentRuntime {
     };
     return pricing[tier];
   }
+
+  buildMcpArgs(opts: McpBridgeOptions): string[] {
+    const config = JSON.stringify({
+      mcpServers: {
+        aos: {
+          command: "bun",
+          args: [opts.bridgeScriptPath],
+          env: { AOS_BRIDGE_SOCKET: opts.socketPath },
+        },
+      },
+    });
+    return [
+      "--mcp-config", config,
+      "--strict-mcp-config",
+      "--allowedTools", "mcp__aos__delegate mcp__aos__end",
+      "--permission-mode", "bypassPermissions",
+    ];
+  }
 }

package/adapters/claude-code/src/index.ts

@@ -1,2 +1,2 @@
-export { ClaudeCodeAgentRuntime } from "./agent-runtime";
+export { ClaudeCodeAgentRuntime, type McpBridgeOptions } from "./agent-runtime";
 export { BaseEventBus, TerminalUI, BaseWorkflow, composeAdapter } from "@aos-harness/adapter-shared";

package/adapters/codex/README.md

@@ -0,0 +1,14 @@
+# @aos-harness/codex-adapter
+
+AOS Harness adapter for OpenAI's [Codex CLI](https://github.com/openai/codex). Lets you run AOS deliberation and execution profiles with Codex as the underlying agent runtime.
+
+Part of the [AOS Harness](https://aos.engineer) monorepo. Bundled with the `aos-harness` CLI — install standalone only if you want a lean, Codex-only setup.
+
+## Requirements
+
+- Bun ≥ 1.0.0
+- Codex CLI installed and authenticated on the host
+
+## License
+
+MIT

package/adapters/codex/package.json

@@ -1,12 +1,23 @@
 {
   "name": "@aos-harness/codex-adapter",
-  "version": "0.1.0",
+  "version": "0.5.0",
+  "description": "AOS Harness adapter for OpenAI's Codex CLI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aos-engineer/aos-harness.git",
+    "directory": "adapters/codex"
+  },
+  "homepage": "https://aos.engineer",
+  "keywords": ["aos-harness", "ai-agents", "codex", "adapter"],
   "type": "module",
+  "engines": { "bun": ">=1.0.0" },
   "exports": { ".": "./src/index.ts" },
-  "files": ["src/"],
+  "files": ["src/", "README.md"],
+  "publishConfig": { "access": "public" },
   "dependencies": {
-    "@aos-harness/runtime": "0.4.1",
-    "@aos-harness/adapter-shared": "0.4.1"
+    "@aos-harness/runtime": "0.5.0",
+    "@aos-harness/adapter-shared": "0.5.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/adapters/codex/src/agent-runtime.ts

@@ -17,6 +17,13 @@ import {
 } from "@aos-harness/adapter-shared";
 import type { BaseEventBus } from "@aos-harness/adapter-shared";
 
+// ── McpBridgeOptions ──────────────────────────────────────────────
+
+export interface McpBridgeOptions {
+  bridgeScriptPath: string;
+  socketPath: string;
+}
+
 // ── CodexAgentRuntime ─────────────────────────────────────────────
 
 export class CodexAgentRuntime extends BaseAgentRuntime {
@@ -54,6 +61,9 @@ export class CodexAgentRuntime extends BaseAgentRuntime {
       args.push("--session", state.sessionFile);
     }
 
+    // Extra args (e.g. MCP flags) are spliced in before the positional message
+    args.push(...(opts?.extraArgs ?? []));
+
     // Message is always the final argument
     args.push(message);
     return args;
@@ -174,6 +184,18 @@ export class CodexAgentRuntime extends BaseAgentRuntime {
     return { type: "unknown", metered: false };
   }
 
+  // Paths are controlled by adapter-session.ts (temp sock in /tmp, script in installed package) — shell-safe characters guaranteed; no escaping needed.
+  buildMcpArgs(opts: McpBridgeOptions): string[] {
+    return [
+      "-c", `mcp_servers.aos.command="bun"`,
+      "-c", `mcp_servers.aos.args=["${opts.bridgeScriptPath}"]`,
+      "-c", `mcp_servers.aos.env={AOS_BRIDGE_SOCKET="${opts.socketPath}"}`,
+      "-c", `mcp_servers.aos.required=true`,
+      "-c", `mcp_servers.aos.enabled_tools=["delegate","end"]`,
+      "-c", `mcp_servers.aos.tool_timeout_sec=600`,
+    ];
+  }
+
   getModelCost(tier: ModelTier): ModelCost {
     const pricing: Record<ModelTier, ModelCost> = {
       economy: {

package/adapters/gemini/package.json

@@ -1,12 +1,23 @@
 {
   "name": "@aos-harness/gemini-adapter",
-  "version": "0.2.0",
+  "version": "0.5.0",
+  "description": "AOS Harness adapter for Google's Gemini CLI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aos-engineer/aos-harness.git",
+    "directory": "adapters/gemini"
+  },
+  "homepage": "https://aos.engineer",
+  "keywords": ["aos-harness", "ai-agents", "gemini", "adapter"],
   "type": "module",
+  "engines": { "bun": ">=1.0.0" },
   "exports": { ".": "./src/index.ts" },
-  "files": ["src/"],
+  "files": ["src/", "README.md"],
+  "publishConfig": { "access": "public" },
   "dependencies": {
-    "@aos-harness/runtime": "0.4.1",
-    "@aos-harness/adapter-shared": "0.4.1"
+    "@aos-harness/runtime": "0.5.0",
+    "@aos-harness/adapter-shared": "0.5.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/adapters/gemini/src/agent-runtime.ts

@@ -2,6 +2,11 @@
 // Extends BaseAgentRuntime with Gemini CLI integration.
 
 import { execSync } from "node:child_process";
+
+export interface McpBridgeOptions {
+  bridgeScriptPath: string;
+  socketPath: string;
+}
 import type {
   AuthMode,
   ModelCost,
@@ -54,6 +59,9 @@ export class GeminiAgentRuntime extends BaseAgentRuntime {
       args.push("--session", state.sessionFile);
     }
 
+    // Extra args (e.g. MCP flags) are spliced in before the positional message
+    args.push(...(opts?.extraArgs ?? []));
+
     // Message is always the final argument
     args.push(message);
     return args;
@@ -190,4 +198,48 @@ export class GeminiAgentRuntime extends BaseAgentRuntime {
     };
     return pricing[tier];
   }
+
+  buildMcpArgs(): string[] {
+    return [
+      "--yolo",
+      "--allowed-mcp-server-names", "aos",
+    ];
+  }
+
+  /**
+   * Writes a project-local .gemini/settings.json with our MCP server config.
+   * Returns a restore function that the caller MUST invoke on shutdown to
+   * restore any pre-existing settings file.
+   */
+  writeMcpSettings(opts: McpBridgeOptions & { projectRoot: string }): () => void {
+    const { mkdirSync, writeFileSync, existsSync, renameSync, unlinkSync } = require("node:fs") as typeof import("node:fs");
+    const { join } = require("node:path") as typeof import("node:path");
+
+    const geminiDir = join(opts.projectRoot, ".gemini");
+    const settingsPath = join(geminiDir, "settings.json");
+    const backupPath = join(geminiDir, "settings.json.aos-backup");
+
+    mkdirSync(geminiDir, { recursive: true });
+    const hadBackup = existsSync(settingsPath);
+    if (hadBackup) renameSync(settingsPath, backupPath);
+
+    writeFileSync(settingsPath, JSON.stringify({
+      mcpServers: {
+        aos: {
+          command: "bun",
+          args: [opts.bridgeScriptPath],
+          env: { AOS_BRIDGE_SOCKET: opts.socketPath },
+          trust: true,
+          timeout: 600000,
+        },
+      },
+    }, null, 2));
+
+    return () => {
+      try { unlinkSync(settingsPath); } catch { /* ignore */ }
+      if (hadBackup) {
+        try { renameSync(backupPath, settingsPath); } catch { /* ignore */ }
+      }
+    };
+  }
 }

package/adapters/gemini/src/index.ts

@@ -1,2 +1,2 @@
-export { GeminiAgentRuntime } from "./agent-runtime";
+export { GeminiAgentRuntime, type McpBridgeOptions } from "./agent-runtime";
 export { BaseEventBus, TerminalUI, BaseWorkflow, composeAdapter } from "@aos-harness/adapter-shared";

package/adapters/pi/package.json

@@ -1,15 +1,26 @@
 {
   "name": "@aos-harness/pi-adapter",
-  "version": "0.1.0",
+  "version": "0.5.0",
+  "description": "AOS Harness adapter for the Pi coding agent runtime.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aos-engineer/aos-harness.git",
+    "directory": "adapters/pi"
+  },
+  "homepage": "https://aos.engineer",
+  "keywords": ["aos-harness", "ai-agents", "pi", "adapter"],
   "type": "module",
+  "engines": { "bun": ">=1.0.0" },
   "pi": {
     "extensions": ["./src/index.ts"]
   },
   "exports": { ".": "./src/index.ts" },
-  "files": ["src/"],
+  "files": ["src/", "README.md"],
+  "publishConfig": { "access": "public" },
   "dependencies": {
-    "@aos-harness/adapter-shared": "0.4.1",
-    "@aos-harness/runtime": "0.4.1",
+    "@aos-harness/adapter-shared": "0.5.0",
+    "@aos-harness/runtime": "0.5.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

package/adapters/pi/src/index.ts

@@ -2,9 +2,9 @@
 // Wires all 4 adapter layers together and makes the AOS Harness
 // runnable as a Pi extension.
 
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync, symlinkSync, rmSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { join, dirname, basename, resolve } from "node:path";
+import { join, dirname, basename } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Text, truncateToWidth } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -12,8 +12,7 @@ import { Type } from "@sinclair/typebox";
 import { PiAgentRuntime } from "./agent-runtime";
 import { PiEventBus } from "./event-bus";
 import { PiUI } from "./ui";
-import { BaseWorkflow } from "@aos-harness/adapter-shared";
-import { composeAdapter } from "@aos-harness/adapter-shared";
+import { BaseWorkflow, composeAdapter, discoverAgents, createFlatAgentsDir, findProjectRoot } from "@aos-harness/adapter-shared";
 
 import { AOSEngine } from "@aos-harness/runtime";
 import type { AOSAdapter, ConstraintState, ProfileConfig } from "@aos-harness/runtime/types";
@@ -22,75 +21,6 @@ import { validateBrief } from "@aos-harness/runtime/config-loader";
 
 // ── Helpers ─────────────────────────────────────────────────────
 
-/** Walk up from `cwd` looking for a directory containing `core/`. */
-function findProjectRoot(cwd: string): string | null {
-  let dir = resolve(cwd);
-  for (let i = 0; i < 20; i++) {
-    if (existsSync(join(dir, "core"))) return dir;
-    if (existsSync(join(dir, ".aos"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
-/**
- * Recursively discover all agent directories (those containing agent.yaml).
- * Returns a Map of agentId -> absolute directory path.
- */
-function discoverAgents(agentsDir: string): Map<string, string> {
-  const agents = new Map<string, string>();
-
-  function walk(dir: string): void {
-    if (!existsSync(dir)) return;
-    const entries = readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const subDir = join(dir, entry.name);
-      const yamlPath = join(subDir, "agent.yaml");
-      if (existsSync(yamlPath)) {
-        // Read the id from agent.yaml
-        try {
-          const raw = readFileSync(yamlPath, "utf-8");
-          const idMatch = raw.match(/^id:\s*(.+)$/m);
-          if (idMatch) {
-            agents.set(idMatch[1].trim(), subDir);
-          }
-        } catch {
-          // Skip unreadable
-        }
-      }
-      // Recurse into subdirectories
-      walk(subDir);
-    }
-  }
-
-  walk(agentsDir);
-  return agents;
-}
-
-/**
- * Create a flat temporary directory with symlinks so the engine can
- * resolve agent IDs via `join(agentsDir, id)`.
- */
-function createFlatAgentsDir(projectRoot: string, agentMap: Map<string, string>): string {
-  const flatDir = join(projectRoot, ".aos", "_flat_agents");
-  if (existsSync(flatDir)) {
-    rmSync(flatDir, { recursive: true, force: true });
-  }
-  mkdirSync(flatDir, { recursive: true });
-
-  for (const [id, dirPath] of agentMap) {
-    const linkPath = join(flatDir, id);
-    if (!existsSync(linkPath)) {
-      symlinkSync(dirPath, linkPath, "dir");
-    }
-  }
-
-  return flatDir;
-}
-
 /** List subdirectories that contain a given file. */
 function listDirsWithFile(parentDir: string, fileName: string): { name: string; dir: string; mtime: number }[] {
   if (!existsSync(parentDir)) return [];

package/adapters/shared/README.md

@@ -0,0 +1,15 @@
+# @aos-harness/adapter-shared
+
+Shared base classes and utilities used by every AOS Harness platform adapter (Claude Code, Codex, Gemini, Pi).
+
+Re-exports common types (`AgentRuntime`, `EventBus`, etc.) and provides composition helpers (`composeAdapter`, `BaseEventBus`, `BaseWorkflow`) so each adapter only needs to implement platform-specific runtime logic.
+
+Part of the [AOS Harness](https://aos.engineer) monorepo. Most users install `aos-harness` (the CLI) instead of consuming this package directly.
+
+## Requirements
+
+- Bun ≥ 1.0.0
+
+## License
+
+MIT

package/adapters/shared/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@aos-harness/adapter-shared",
-  "version": "0.4.1",
+  "version": "0.5.0",
+  "description": "Shared base classes and utilities for AOS Harness platform adapters.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aos-engineer/aos-harness.git",
+    "directory": "adapters/shared"
+  },
+  "homepage": "https://aos.engineer",
+  "keywords": ["aos-harness", "ai-agents", "adapter", "shared"],
   "type": "module",
+  "engines": { "bun": ">=1.0.0" },
   "exports": {
     ".": "./src/index.ts",
     "./*": "./src/*"
   },
-  "files": ["src/"],
+  "files": ["src/", "README.md"],
+  "publishConfig": { "access": "public" },
   "dependencies": {
-    "@aos-harness/runtime": "0.4.1",
+    "@aos-harness/runtime": "0.5.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

package/adapters/shared/src/agent-discovery.ts

@@ -0,0 +1,71 @@
+import { existsSync, readdirSync, readFileSync, mkdirSync, symlinkSync, rmSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+
+/** Walk up from `cwd` looking for a directory containing `core/`. */
+export function findProjectRoot(cwd: string): string | null {
+  let dir = resolve(cwd);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(dir, "core"))) return dir;
+    if (existsSync(join(dir, ".aos"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Recursively discover all agent directories (those containing agent.yaml).
+ * Returns a Map of agentId -> absolute directory path.
+ */
+export function discoverAgents(agentsDir: string): Map<string, string> {
+  const agents = new Map<string, string>();
+
+  function walk(dir: string): void {
+    if (!existsSync(dir)) return;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const subDir = join(dir, entry.name);
+      const yamlPath = join(subDir, "agent.yaml");
+      if (existsSync(yamlPath)) {
+        // Read the id from agent.yaml
+        try {
+          const raw = readFileSync(yamlPath, "utf-8");
+          const idMatch = raw.match(/^id:\s*(.+)$/m);
+          if (idMatch) {
+            agents.set(idMatch[1].trim(), subDir);
+          }
+        } catch {
+          // Skip unreadable
+        }
+      }
+      // Recurse into subdirectories
+      walk(subDir);
+    }
+  }
+
+  walk(agentsDir);
+  return agents;
+}
+
+/**
+ * Create a flat temporary directory with symlinks so the engine can
+ * resolve agent IDs via `join(agentsDir, id)`.
+ */
+export function createFlatAgentsDir(projectRoot: string, agentMap: Map<string, string>): string {
+  const flatDir = join(projectRoot, ".aos", "_flat_agents");
+  if (existsSync(flatDir)) {
+    rmSync(flatDir, { recursive: true, force: true });
+  }
+  mkdirSync(flatDir, { recursive: true });
+
+  for (const [id, dirPath] of agentMap) {
+    const linkPath = join(flatDir, id);
+    if (!existsSync(linkPath)) {
+      symlinkSync(dirPath, linkPath, "dir");
+    }
+  }
+
+  return flatDir;
+}

package/adapters/shared/src/index.ts

@@ -9,3 +9,4 @@ export { BaseEventBus } from "./base-event-bus";
 export { TerminalUI } from "./terminal-ui";
 export { BaseWorkflow } from "./base-workflow";
 export { composeAdapter } from "./compose";
+export { discoverAgents, createFlatAgentsDir, findProjectRoot } from "./agent-discovery";

package/adapters/shared/tests/agent-discovery.test.ts

@@ -0,0 +1,65 @@
+import { test, expect } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, lstatSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverAgents, findProjectRoot, createFlatAgentsDir } from "../src/agent-discovery";
+
+test("discoverAgents finds agents recursively by agent.yaml", () => {
+  const root = mkdtempSync(join(tmpdir(), "discover-"));
+  mkdirSync(join(root, "alice"), { recursive: true });
+  writeFileSync(join(root, "alice", "agent.yaml"), "id: alice\n");
+  mkdirSync(join(root, "nested", "bob"), { recursive: true });
+  writeFileSync(join(root, "nested", "bob", "agent.yaml"), "id: bob\n");
+
+  const map = discoverAgents(root);
+  expect(map.get("alice")).toBe(join(root, "alice"));
+  expect(map.get("bob")).toBe(join(root, "nested", "bob"));
+});
+
+test("findProjectRoot walks up to find core/ or .aos/", () => {
+  const root = mkdtempSync(join(tmpdir(), "proj-"));
+  mkdirSync(join(root, "core"));
+  const deep = join(root, "a", "b", "c");
+  mkdirSync(deep, { recursive: true });
+  expect(findProjectRoot(deep)).toBe(root);
+});
+
+test("createFlatAgentsDir creates symlinks and wipes on re-call", () => {
+  // Set up a projectRoot temp dir
+  const projectRoot = mkdtempSync(join(tmpdir(), "flat-agents-"));
+
+  // Create two agent dirs
+  const agentAliceDir = mkdtempSync(join(tmpdir(), "agent-alice-"));
+  const agentBobDir = mkdtempSync(join(tmpdir(), "agent-bob-"));
+
+  const agentMap = new Map<string, string>([
+    ["alice", agentAliceDir],
+    ["bob", agentBobDir],
+  ]);
+
+  // First call
+  const flatDir = createFlatAgentsDir(projectRoot, agentMap);
+
+  // Assert returned path
+  expect(flatDir).toBe(join(projectRoot, ".aos", "_flat_agents"));
+
+  // Assert symlinks exist and resolve correctly
+  const aliceLink = join(flatDir, "alice");
+  const bobLink = join(flatDir, "bob");
+
+  expect(lstatSync(aliceLink).isSymbolicLink()).toBe(true);
+  expect(lstatSync(bobLink).isSymbolicLink()).toBe(true);
+  expect(realpathSync(aliceLink)).toBe(realpathSync(agentAliceDir));
+  expect(realpathSync(bobLink)).toBe(realpathSync(agentBobDir));
+
+  // Second call with only bob — alice should be gone (dir wiped+recreated)
+  const agentMapReduced = new Map<string, string>([["bob", agentBobDir]]);
+  createFlatAgentsDir(projectRoot, agentMapReduced);
+
+  // alice symlink from the first call must no longer exist
+  expect(() => lstatSync(aliceLink)).toThrow();
+
+  // bob symlink must still be present and valid
+  expect(lstatSync(bobLink).isSymbolicLink()).toBe(true);
+  expect(realpathSync(bobLink)).toBe(realpathSync(agentBobDir));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aos-harness",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Agentic Orchestration System — assemble AI agents into deliberation and execution teams",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,9 @@
     "test": "bun run src/index.ts validate"
   },
   "dependencies": {
-    "@aos-harness/runtime": "0.4.1",
+    "@aos-harness/adapter-shared": "0.5.0",
+    "@aos-harness/runtime": "0.5.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

package/src/adapter-config.ts

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+export interface AdapterConfig {
+  platform?: string;
+  model_overrides?: Partial<Record<string, string>>;
+  theme?: string;
+  editor?: string;
+}
+
+export function readAdapterConfig(root: string): AdapterConfig | null {
+  const p = join(root, ".aos", "adapter.yaml");
+  if (!existsSync(p)) return null;
+  return yaml.load(readFileSync(p, "utf-8")) as AdapterConfig;
+}

package/src/adapter-session.ts

@@ -0,0 +1,319 @@
+// ── adapter-session.ts ────────────────────────────────────────────
+// Orchestration entrypoint used by the CLI to run a deliberation
+// session against one of the non-Pi adapters (Claude Code, Gemini, Codex).
+//
+// Responsibilities:
+//   1. Dynamically load the chosen AgentRuntime class.
+//   2. Compose the 4 adapter layers into an AOSAdapter.
+//   3. Build the AOSEngine and kick off with the brief.
+//   4. Start a Unix-socket bridge that forwards MCP `delegate`/`end`
+//      tool calls from the arbiter process into the engine.
+//   5. Resolve the arbiter prompt template and spawn the arbiter,
+//      threading MCP CLI flags through MessageOpts.extraArgs.
+//   6. Run a readline loop for `/aos-*` interactive commands.
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { readFileSync } from "node:fs";
+import readline from "node:readline";
+import {
+  BaseEventBus,
+  TerminalUI,
+  BaseWorkflow,
+  composeAdapter,
+  discoverAgents,
+  createFlatAgentsDir,
+} from "@aos-harness/adapter-shared";
+import { AOSEngine } from "@aos-harness/runtime";
+import { loadAgent } from "@aos-harness/runtime/config-loader";
+import { resolveTemplate } from "@aos-harness/runtime/template-resolver";
+import { startBridgeServer } from "./bridge-server";
+import { renderTextGauge, renderRoundOneLiner } from "./gauges";
+
+export interface AdapterSessionConfig {
+  platform: string; // "claude-code" | "gemini" | "codex"
+  profileDir: string;
+  briefPath: string;
+  domainName: string | null;
+  root: string;
+  sessionId: string;
+  deliberationDir: string;
+  verbose: boolean;
+  workflowConfig: any | null;
+  workflowsDir: string;
+  modelOverrides?: Partial<Record<string, string>>;
+}
+
+const ADAPTER_MAP: Record<string, { package: string; className: string }> = {
+  "claude-code": {
+    package: "@aos-harness/claude-code-adapter",
+    className: "ClaudeCodeAgentRuntime",
+  },
+  gemini: {
+    package: "@aos-harness/gemini-adapter",
+    className: "GeminiAgentRuntime",
+  },
+  codex: {
+    package: "@aos-harness/codex-adapter",
+    className: "CodexAgentRuntime",
+  },
+};
+
+async function loadAdapterRuntime(platform: string): Promise<any> {
+  const entry = ADAPTER_MAP[platform];
+  if (!entry) throw new Error(`Unknown adapter: ${platform}`);
+
+  async function readAdapterVersion(fromPath: string): Promise<string> {
+    try {
+      const pkgUrl = new URL("../package.json", fromPath).href;
+      const { readFile } = await import("node:fs/promises");
+      const raw = await readFile(new URL(pkgUrl), "utf-8");
+      return (JSON.parse(raw) as { version: string }).version ?? "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+
+  try {
+    const mod = await import(entry.package);
+    const resolved = (import.meta as any).resolve?.(entry.package) ?? entry.package;
+    const version = await readAdapterVersion(resolved);
+    console.error(`[adapter] loaded ${entry.package}@${version} (standalone)`);
+    return mod[entry.className];
+  } catch {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const fallback = join(here, "..", "..", "adapters", platform, "src", "index.ts");
+    const mod = await import(fallback);
+    const version = await readAdapterVersion(`file://${fallback}`);
+    console.error(`[adapter] loaded ${entry.package}@${version} (bundled: ${fallback})`);
+    return mod[entry.className];
+  }
+}
+
+function toolNamesForPlatform(platform: string): { delegate: string; end: string } {
+  if (platform === "claude-code") {
+    return { delegate: "mcp__aos__delegate", end: "mcp__aos__end" };
+  }
+  return { delegate: "delegate", end: "end" };
+}
+
+export async function runAdapterSession(config: AdapterSessionConfig): Promise<void> {
+  const log = (msg: string) => {
+    if (config.verbose) console.error(`[session] ${msg}`);
+  };
+
+  log("loading adapter runtime");
+  const RuntimeClass = await loadAdapterRuntime(config.platform);
+
+  // ── Layer composition ──────────────────────────────────────
+  const eventBus = new BaseEventBus();
+  const agentRuntime = new RuntimeClass(eventBus, config.modelOverrides);
+  const ui = new TerminalUI();
+  const workflow = new BaseWorkflow(agentRuntime, config.root);
+  const adapter = composeAdapter(agentRuntime, eventBus, ui, workflow);
+  log("layers composed");
+
+  // ── Agent discovery (flatten nested core/agents layout) ───
+  const agentsDir = join(config.root, "core", "agents");
+  const agentMap = discoverAgents(agentsDir);
+  const flatAgentsDir = createFlatAgentsDir(config.root, agentMap);
+  const domainsDir = join(config.root, "core", "domains");
+  log(`agents discovered (${agentMap.size})`);
+
+  // ── Engine setup & brief intake ────────────────────────────
+  const engine = new AOSEngine(adapter, config.profileDir, {
+    agentsDir: flatAgentsDir,
+    domain: config.domainName ?? undefined,
+    domainDir: config.domainName ? domainsDir : undefined,
+  });
+  log("starting engine");
+  await engine.start(config.briefPath);
+  log("engine started");
+
+  // ── Bridge server (MCP tool calls → engine) ────────────────
+  const sockPath = join(tmpdir(), `aos-bridge-${config.sessionId}.sock`);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const bridgeScriptPath = join(here, "mcp-arbiter-bridge.ts");
+
+  let halted = false;
+  const steerQueue: string[] = [];
+
+  async function waitWhileHalted(): Promise<void> {
+    while (halted) await new Promise((r) => setTimeout(r, 200));
+  }
+
+  function drainSteer(): string {
+    if (steerQueue.length === 0) return "";
+    const msgs = steerQueue.splice(0);
+    return `\n\n[user steer]\n${msgs.join("\n")}`;
+  }
+
+  log(`starting bridge server sock=${sockPath}`);
+  const closeBridge = await startBridgeServer(sockPath, {
+    delegate: async (params) => {
+      await waitWhileHalted();
+      const steer = drainSteer();
+      const responses = await engine.delegateMessage(
+        params.to as any,
+        (params.message as string) + steer,
+      );
+      const cs = engine.getConstraintState();
+      process.stdout.write(
+        "\n" +
+          renderRoundOneLiner({
+            round: cs.rounds_completed,
+            maxRounds: 8,
+            minutes: cs.elapsed_minutes,
+            dollars: cs.budget_spent,
+          }) +
+          "\n",
+      );
+      return { responses, constraints: cs };
+    },
+    end: async (params) => {
+      await waitWhileHalted();
+      const responses = await engine.end(params.closing_message as string);
+      return { ok: true, responses };
+    },
+  });
+
+  log("bridge listening");
+  // ── Arbiter prompt resolution ──────────────────────────────
+  const arbiterDir = agentMap.get("arbiter");
+  if (!arbiterDir) throw new Error("No arbiter agent found in core/agents/");
+
+  const promptPath = join(arbiterDir, "prompt.md");
+  const rawPrompt = readFileSync(promptPath, "utf-8");
+  const briefContent = readFileSync(config.briefPath, "utf-8");
+  const participants = [...agentMap.keys()].filter((id) => id !== "arbiter");
+  const memoPath = join(config.deliberationDir, "memo.md");
+  const transcriptPath = join(config.deliberationDir, "transcript.jsonl");
+  const tools = toolNamesForPlatform(config.platform);
+
+  const templateVars: Record<string, string> = {
+    // Spec-compliant underscore names
+    session_id: config.sessionId,
+    brief_slug: config.sessionId,
+    brief: briefContent,
+    format: "brief",
+    agent_id: "arbiter",
+    agent_name: "Arbiter",
+    participants: participants.join(", "),
+    constraints: "(see constraint state in tool responses)",
+    expertise_block: "",
+    output_path: memoPath,
+    deliberation_dir: config.deliberationDir,
+    transcript_path: transcriptPath,
+    delegate_tool: tools.delegate,
+    end_tool: tools.end,
+    role_override: "",
+    // Back-compat hyphenated aliases
+    "session-id": config.sessionId,
+    "brief-content": briefContent,
+    "output-path": memoPath,
+    "deliberation-dir": config.deliberationDir,
+    "memo-path": memoPath,
+  };
+
+  const resolvedPrompt = resolveTemplate(rawPrompt, templateVars);
+
+  // The arbiter prompt was authored when tools were named bare (`delegate`, `end`).
+  // Claude Code exposes MCP tools as `mcp__aos__delegate` / `mcp__aos__end`, so the
+  // model would attempt to call tools that don't exist. Prepend a short preamble
+  // that maps the names it'll see to the names the prompt uses.
+  const toolPreamble =
+    config.platform === "claude-code"
+      ? `IMPORTANT — Tool names for this session:\n` +
+        `- Where the instructions below say \`delegate(...)\`, call \`${tools.delegate}\` (that is the actual MCP tool name you will see).\n` +
+        `- Where they say \`end(...)\`, call \`${tools.end}\`.\n` +
+        `- These are the ONLY two tools available to you. Use them exactly as described.\n\n---\n\n`
+      : "";
+  adapter.setOrchestratorPrompt(toolPreamble + resolvedPrompt);
+
+  // ── Build MCP args and launch arbiter ──────────────────────
+  const mcpOpts = { bridgeScriptPath, socketPath: sockPath };
+  const mcpArgs: string[] =
+    (agentRuntime as any).buildMcpArgs?.(mcpOpts) ?? [];
+
+  let restoreGeminiSettings: (() => void) | undefined;
+  if ((agentRuntime as any).writeMcpSettings) {
+    restoreGeminiSettings = (agentRuntime as any).writeMcpSettings({
+      ...mcpOpts,
+      projectRoot: config.root,
+    });
+  }
+
+  // Load the arbiter AgentConfig from disk (uses the flat dir so
+  // loadAgent sees the same shape the engine sees). Override the
+  // systemPrompt with the resolved template.
+  const arbiterFlatDir = join(flatAgentsDir, "arbiter");
+  const arbiterConfig = loadAgent(arbiterFlatDir);
+  arbiterConfig.systemPrompt = resolvedPrompt;
+
+  log("spawning arbiter");
+  const arbiterHandle = await adapter.spawnAgent(arbiterConfig, config.sessionId);
+
+  // ── Kickoff message ────────────────────────────────────────
+  const kickoff =
+    "Read the brief below and begin the multi-agent deliberation. " +
+    `Use the \`${tools.delegate}\` tool to engage perspective agents and ` +
+    `\`${tools.end}\` when ready to wrap up.\n\n` +
+    `---\n\n## Brief\n\n${briefContent}`;
+
+  // ── Interactive readline commands ──────────────────────────
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on("line", (input) => {
+    const trimmed = input.trim();
+    if (!trimmed) return;
+    if (trimmed === "/aos-halt") {
+      halted = true;
+      console.log("Deliberation paused. Type /aos-resume to continue.");
+    } else if (trimmed === "/aos-resume") {
+      halted = false;
+      console.log("Resumed.");
+    } else if (trimmed === "/aos-end") {
+      steerQueue.push("Please wrap up now and call the end tool.");
+    } else if (trimmed === "/aos-status") {
+      const cs = engine.getConstraintState();
+      console.log(renderTextGauge("TIME", cs.elapsed_minutes, 2, 10, "min"));
+      if (cs.metered) {
+        console.log(renderTextGauge("BUDGET", cs.budget_spent, 1, 10, "$"));
+      }
+      console.log(renderTextGauge("ROUNDS", cs.rounds_completed, 2, 8, "rounds"));
+    } else if (trimmed.startsWith("/aos-steer ")) {
+      steerQueue.push(trimmed.slice("/aos-steer ".length));
+    } else if (!trimmed.startsWith("/")) {
+      steerQueue.push(trimmed);
+    }
+  });
+
+  try {
+    log(`sending kickoff to arbiter (mcpArgs=${mcpArgs.length})`);
+    console.log(
+      `\nArbiter running (${config.platform}). ` +
+        `Tool calls will stream as rounds complete. ` +
+        `Bridge socket: ${sockPath}\n`,
+    );
+    const response = await adapter.sendMessage(arbiterHandle, kickoff, {
+      extraArgs: mcpArgs,
+    });
+    if ((response as any).status !== "success") {
+      console.error(
+        `\n[arbiter] call failed: status=${(response as any).status} ` +
+          `error=${(response as any).error ?? "(none)"}`,
+      );
+    }
+    console.log("\n" + response.text);
+  } finally {
+    rl.close();
+    await closeBridge();
+    if (restoreGeminiSettings) restoreGeminiSettings();
+    const cs = engine.getConstraintState();
+    console.log(
+      `\nSession complete. Rounds: ${cs.rounds_completed}, ` +
+        `Cost: $${cs.budget_spent.toFixed(4)}, ` +
+        `Time: ${cs.elapsed_minutes.toFixed(1)}min`,
+    );
+  }
+}

package/src/bridge-server.ts

@@ -0,0 +1,54 @@
+import { createServer, Socket } from "node:net";
+import { unlinkSync, existsSync } from "node:fs";
+
+export interface BridgeHandlers {
+  delegate: (params: { to: string | string[]; message: string }) => Promise<unknown>;
+  end: (params: { closing_message: string }) => Promise<unknown>;
+}
+
+export async function startBridgeServer(
+  socketPath: string,
+  handlers: BridgeHandlers,
+): Promise<() => Promise<void>> {
+  if (existsSync(socketPath)) unlinkSync(socketPath);
+
+  const open = new Set<Socket>();
+
+  const server = createServer((sock: Socket) => {
+    open.add(sock);
+    sock.on("close", () => open.delete(sock));
+    let buf = "";
+    sock.on("data", async (chunk) => {
+      buf += chunk.toString("utf-8");
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        let req: any;
+        try { req = JSON.parse(line); } catch { continue; }
+        try {
+          let result: unknown;
+          if (req.method === "delegate") result = await handlers.delegate(req.params);
+          else if (req.method === "end") result = await handlers.end(req.params);
+          else throw new Error(`unknown method: ${req.method}`);
+          sock.write(JSON.stringify({ id: req.id, result }) + "\n");
+        } catch (err: any) {
+          sock.write(JSON.stringify({ id: req.id, error: String(err?.message ?? err) }) + "\n");
+        }
+      }
+    });
+    sock.on("error", () => { /* client disconnect is fine */ });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => resolve());
+  });
+
+  return async () => {
+    for (const s of open) s.destroy();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    if (existsSync(socketPath)) unlinkSync(socketPath);
+  };
+}

package/src/commands/run.ts

@@ -7,6 +7,8 @@ import { join, resolve, basename } from "node:path";
 import { c, type ParsedArgs } from "../colors";
 import { getHarnessRoot, discoverDirs, promptSelect, getAdapterDir } from "../utils";
 import type { TranscriptEntry } from "@aos-harness/runtime/types";
+import { runAdapterSession } from "../adapter-session";
+import { readAdapterConfig } from "../adapter-config";
 
 function createEventBuffer(platformUrl: string, sessionId: string) {
   const buffer: TranscriptEntry[] = [];
@@ -304,7 +306,7 @@ ${c.bold(`AOS ${sessionType} Session`)}
   Output:   ${c.cyan(deliberationDir)}
 `);
 
-  // Check for .aos/config.yaml to determine adapter
+  // Determine adapter: --adapter flag > .aos/config.yaml > default "pi"
   let platformUrl = (args.flags["platform-url"] as string) || null;
   const aosConfigPath = join(process.cwd(), ".aos", "config.yaml");
   let adapter = "pi";
@@ -317,6 +319,7 @@ ${c.bold(`AOS ${sessionType} Session`)}
       platformUrl = (config.platform as Record<string, unknown>).url as string;
     }
   }
+  if (args.flags["adapter"]) adapter = args.flags["adapter"] as string;
 
   const adapterName = adapter === "claude-code" ? "claude-code" : adapter;
   // Resolve adapter from: 1) project dir, 2) installed package, 3) monorepo
@@ -374,13 +377,19 @@ ${c.bold(`AOS ${sessionType} Session`)}
     }
     process.exit(exitCode);
   } else {
-    console.log(c.yellow(`Adapter "${adapter}" is not yet fully supported in the CLI.`));
-    console.log(c.dim(`The framework launched with profile="${profileName}", domain="${domainName || "none"}", brief="${briefPath}".`));
-    if (isExecutionProfile && workflowConfig) {
-      console.log(c.dim(`Workflow: ${workflowConfig.id} (${workflowConfig.steps.length} steps)`));
-      console.log(c.dim(`Workflows dir: ${workflowsDir}`));
-    }
-    console.log(c.dim(`Deliberation dir: ${deliberationDir}`));
-    console.log(c.dim(`Implement the ${adapter} adapter at adapters/${adapter}/ to enable full execution.`));
+    const adapterConfig = readAdapterConfig(root);
+    await runAdapterSession({
+      platform: adapter,
+      profileDir: profileDir!,
+      briefPath,
+      domainName,
+      root,
+      sessionId,
+      deliberationDir,
+      verbose: !!args.flags.verbose,
+      workflowConfig: isExecutionProfile ? workflowConfig : null,
+      workflowsDir,
+      modelOverrides: adapterConfig?.model_overrides,
+    });
   }
 }

package/src/gauges.ts

@@ -0,0 +1,33 @@
+const BAR_WIDTH = 16;
+
+function color(text: string, code: string): string {
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+export function renderTextGauge(
+  label: string,
+  value: number,
+  min: number,
+  max: number,
+  unit: string,
+): string {
+  const ratio = Math.max(0, Math.min(1, value / max));
+  const filled = Math.round(ratio * BAR_WIDTH);
+  const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+  const colored = value < min ? color(bar, "32") : value >= max * 0.9 ? color(bar, "31") : color(bar, "33");
+  const valueStr = unit === "$" ? `$${value.toFixed(2)}` : `${value.toFixed(1)} ${unit}`;
+  const minStr = unit === "$" ? `$${min}` : `${min}`;
+  const maxStr = unit === "$" ? `$${max}` : `${max}`;
+  return `  ${label.padEnd(7)} ${valueStr.padEnd(10)} [${colored}] (min: ${minStr}, max: ${maxStr})`;
+}
+
+export interface RoundSummary {
+  round: number;
+  maxRounds: number;
+  minutes: number;
+  dollars: number;
+}
+
+export function renderRoundOneLiner(s: RoundSummary): string {
+  return color(`[Round ${s.round}/${s.maxRounds} · ${s.minutes.toFixed(1)}min · $${s.dollars.toFixed(2)}]`, "90");
+}

package/src/mcp-arbiter-bridge.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { connect, Socket } from "node:net";
+import { randomUUID } from "node:crypto";
+
+const SOCK = process.env.AOS_BRIDGE_SOCKET;
+if (!SOCK) {
+  console.error("AOS_BRIDGE_SOCKET env var is required");
+  process.exit(1);
+}
+
+let sock: Socket | null = null;
+const pending = new Map<string, (msg: any) => void>();
+let buf = "";
+
+function ensureSock(): Promise<Socket> {
+  if (sock && !sock.destroyed) return Promise.resolve(sock);
+  return new Promise((resolve, reject) => {
+    const s = connect(SOCK!);
+    s.on("connect", () => { sock = s; resolve(s); });
+    s.on("error", reject);
+    s.on("data", (chunk) => {
+      buf += chunk.toString("utf-8");
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        try {
+          const msg = JSON.parse(line);
+          const cb = pending.get(msg.id);
+          if (cb) { pending.delete(msg.id); cb(msg); }
+        } catch { /* ignore */ }
+      }
+    });
+    s.on("close", () => { sock = null; });
+  });
+}
+
+async function rpc(method: string, params: unknown): Promise<unknown> {
+  const s = await ensureSock();
+  const id = randomUUID();
+  return new Promise((resolve, reject) => {
+    pending.set(id, (msg) => {
+      if (msg.error) reject(new Error(msg.error));
+      else resolve(msg.result);
+    });
+    s.write(JSON.stringify({ id, method, params }) + "\n");
+  });
+}
+
+const server = new Server(
+  { name: "aos-arbiter-bridge", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "delegate",
+      description: "Delegate a message to one or more participant agents and receive their responses.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          to: { description: "Agent id, list of ids, or 'all'", type: "string" },
+          message: { type: "string" },
+        },
+        required: ["to", "message"],
+      },
+    },
+    {
+      name: "end",
+      description: "End the deliberation. Provide a closing summary message.",
+      inputSchema: {
+        type: "object" as const,
+        properties: { closing_message: { type: "string" } },
+        required: ["closing_message"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const result = await rpc(req.params.name, req.params.arguments ?? {});
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+  };
+});
+
+await server.connect(new StdioServerTransport());