@aos-harness/adapter-shared 0.4.1

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@aos-harness/adapter-shared",
+  "version": "0.4.1",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*"
+  },
+  "files": ["src/"],
+  "dependencies": {
+    "@aos-harness/runtime": "0.4.1",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/bun": "latest",
+    "typescript": "^5.8.0"
+  }
+}

package/src/base-agent-runtime.ts

@@ -0,0 +1,331 @@
+// ── BaseAgentRuntime (L1) ─────────────────────────────────────────
+// Abstract subprocess lifecycle for CLI-based adapters.
+// Concrete implementations override CLI-specific methods.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  AgentRuntimeAdapter,
+  AgentHandle,
+  AgentResponse,
+  AgentConfig,
+  ChildAgentConfig,
+  MessageOpts,
+  AuthMode,
+  ModelCost,
+  ModelTier,
+  ThinkingMode,
+  ContextUsage,
+} from "@aos-harness/runtime/types";
+import type { HandleState, ParsedEvent, StdoutFormat, ModelInfo } from "./types";
+import type { BaseEventBus } from "./base-event-bus";
+
+export abstract class BaseAgentRuntime implements AgentRuntimeAdapter {
+  protected handles = new Map<string, HandleState>();
+  protected activeProcesses = new Set<ChildProcess>();
+  protected orchestratorPrompt: string | undefined;
+  protected eventBus: BaseEventBus;
+  protected modelOverrides: Partial<Record<ModelTier, string>> = {};
+  private cachedModels: ModelInfo[] | null = null;
+  private cleanupRegistered = false;
+
+  constructor(eventBus: BaseEventBus, modelOverrides?: Partial<Record<ModelTier, string>>) {
+    this.eventBus = eventBus;
+    if (modelOverrides) this.modelOverrides = modelOverrides;
+    this.registerCleanup();
+  }
+
+  private registerCleanup(): void {
+    if (this.cleanupRegistered) return;
+    this.cleanupRegistered = true;
+
+    const cleanup = () => {
+      for (const proc of this.activeProcesses) {
+        try { proc.kill("SIGTERM"); } catch {}
+      }
+    };
+
+    process.on("beforeExit", cleanup);
+    process.on("SIGTERM", () => { cleanup(); process.exit(143); });
+    process.on("SIGINT", () => { cleanup(); process.exit(130); });
+  }
+
+  // ── Abstract methods ───────────────────────────────────────────
+
+  abstract cliBinary(): string;
+  abstract stdoutFormat(): StdoutFormat;
+  abstract buildArgs(state: HandleState, message: string, isFirstCall: boolean, opts?: MessageOpts): string[];
+  abstract parseEventLine(line: string): ParsedEvent | null;
+  abstract buildSubprocessEnv(): Record<string, string>;
+  abstract discoverModels(): Promise<ModelInfo[]>;
+  abstract defaultModelMap(): Record<ModelTier, string>;
+  abstract getAuthMode(): AuthMode;
+  abstract getModelCost(tier: ModelTier): ModelCost;
+
+  // ── Model resolution ───────────────────────────────────────────
+
+  resolveModelId(tier: ModelTier): string {
+    if (this.modelOverrides[tier]) return this.modelOverrides[tier]!;
+    const envKeys: Record<ModelTier, string> = {
+      economy: "AOS_MODEL_ECONOMY",
+      standard: "AOS_MODEL_STANDARD",
+      premium: "AOS_MODEL_PREMIUM",
+    };
+    const envVal = process.env[envKeys[tier]];
+    if (envVal) return envVal;
+    return this.defaultModelMap()[tier];
+  }
+
+  async getAvailableModels(): Promise<ModelInfo[]> {
+    if (this.cachedModels) return this.cachedModels;
+    try {
+      this.cachedModels = await this.discoverModels();
+    } catch (err: any) {
+      console.warn(`Model discovery failed for ${this.cliBinary()}: ${err.message}. Using default models.`);
+      const defaults = this.defaultModelMap();
+      this.cachedModels = Object.entries(defaults).map(([_tier, id]) => ({
+        id, name: id, contextWindow: 200_000, provider: this.cliBinary(),
+      }));
+    }
+    return this.cachedModels;
+  }
+
+  // ── AgentRuntimeAdapter ────────────────────────────────────────
+
+  async spawnAgent(config: AgentConfig, sessionId: string): Promise<AgentHandle> {
+    const sessionDir = join(".aos", "sessions", sessionId);
+    mkdirSync(sessionDir, { recursive: true });
+    const sessionFile = join(sessionDir, `${config.id}.jsonl`);
+
+    const handle: AgentHandle = {
+      id: `${sessionId}:${config.id}`,
+      agentId: config.id,
+      sessionId,
+    };
+
+    this.handles.set(handle.id, {
+      config,
+      sessionFile,
+      contextFiles: [],
+      modelConfig: { tier: config.model.tier, thinking: config.model.thinking },
+      lastContextTokens: 0,
+    });
+
+    return handle;
+  }
+
+  async sendMessage(handle: AgentHandle, message: string, opts?: MessageOpts): Promise<AgentResponse> {
+    return this.sendMessageWithRetry(handle, message, opts);
+  }
+
+  async sendMessageWithRetry(
+    handle: AgentHandle, message: string, opts?: MessageOpts,
+    maxRetries: number = 2, backoff: "exponential" | "linear" = "exponential",
+    timeoutMs: number = 120000,
+  ): Promise<AgentResponse> {
+    let lastResponse: AgentResponse | null = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const response = await this.sendMessageOnce(handle, message, opts, timeoutMs);
+      if (response.status === "success") return response;
+      lastResponse = response;
+      if (response.status === "aborted") return response;
+      if (attempt < maxRetries) {
+        const delayMs = backoff === "exponential" ? 1000 * Math.pow(2, attempt) : 1000 * (attempt + 1);
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+    }
+    return lastResponse!;
+  }
+
+  private async sendMessageOnce(
+    handle: AgentHandle, message: string, opts?: MessageOpts, timeoutMs: number = 120000,
+  ): Promise<AgentResponse> {
+    const state = this.handles.get(handle.id);
+    if (!state) {
+      return { text: "", tokensIn: 0, tokensOut: 0, cost: 0, contextTokens: 0, model: "unknown", status: "failed", error: `No state found for handle ${handle.id}` };
+    }
+
+    const isFirstCall = !existsSync(state.sessionFile);
+    const args = this.buildArgs(state, message, isFirstCall, opts);
+    const format = this.stdoutFormat();
+
+    return new Promise<AgentResponse>((resolve) => {
+      const timeoutController = new AbortController();
+      const timeoutId = setTimeout(() => { timeoutController.abort(); }, timeoutMs);
+
+      const proc = spawn(this.cliBinary(), args, {
+        shell: false, stdio: ["ignore", "pipe", "pipe"], env: this.buildSubprocessEnv(),
+      });
+      this.activeProcesses.add(proc);
+
+      let buffer = "";
+      let stderr = "";
+      let accumulatedText = "";
+      let finalResponse = "";
+      let tokensIn = 0, tokensOut = 0, cost = 0, contextTokens = 0;
+      let model = this.resolveModelId(state.modelConfig.tier);
+      let wasAborted = false;
+
+      const processEvent = (event: ParsedEvent) => {
+        switch (event.type) {
+          case "text_delta":
+            accumulatedText += event.text;
+            opts?.onStream?.(accumulatedText);
+            break;
+          case "message_end":
+            finalResponse = event.text;
+            tokensIn += event.tokensIn;
+            tokensOut += event.tokensOut;
+            cost += event.cost;
+            contextTokens = event.contextTokens;
+            if (event.model) model = event.model;
+            break;
+          case "tool_call":
+            this.eventBus.fireToolCall(event.name, event.input);
+            break;
+          case "tool_result":
+            this.eventBus.fireToolResult(event.name, event.input, event.result);
+            break;
+          case "ignored":
+            break;
+        }
+      };
+
+      const processLine = (line: string) => {
+        if (!line.trim()) return;
+        let jsonLine = line;
+        if (format === "sse") {
+          if (!line.startsWith("data:")) return;
+          jsonLine = line.slice(5).trim();
+          if (jsonLine === "[DONE]") return;
+        }
+        const event = this.parseEventLine(jsonLine);
+        if (event) processEvent(event);
+      };
+
+      proc.stdout!.on("data", (data: Buffer) => {
+        buffer += data.toString();
+        if (format === "ndjson" || format === "sse") {
+          const lines = buffer.split("\n");
+          buffer = lines.pop() || "";
+          for (const line of lines) processLine(line);
+        } else if (format === "chunked-json") {
+          let braceDepth = 0;
+          let start = -1;
+          for (let i = 0; i < buffer.length; i++) {
+            if (buffer[i] === "{") {
+              if (braceDepth === 0) start = i;
+              braceDepth++;
+            } else if (buffer[i] === "}") {
+              braceDepth--;
+              if (braceDepth === 0 && start >= 0) {
+                processLine(buffer.slice(start, i + 1));
+                buffer = buffer.slice(i + 1);
+                i = -1;
+                start = -1;
+              }
+            }
+          }
+        }
+      });
+
+      proc.stderr!.on("data", (data: Buffer) => { stderr += data.toString(); });
+
+      proc.on("close", (code: number | null) => {
+        clearTimeout(timeoutId);
+        if (buffer.trim()) processLine(buffer);
+        this.activeProcesses.delete(proc);
+        if (contextTokens > 0) state.lastContextTokens = contextTokens;
+        if (tokensIn > 0 || tokensOut > 0 || cost > 0) {
+          this.eventBus.fireMessageEnd({ cost, tokens: tokensIn + tokensOut });
+        }
+        if (wasAborted) {
+          resolve({ text: accumulatedText, tokensIn, tokensOut, cost, contextTokens, model, status: "aborted", error: "Agent call was aborted" });
+          return;
+        }
+        if (code !== 0 && !finalResponse && !accumulatedText) {
+          resolve({ text: "", tokensIn, tokensOut, cost, contextTokens, model, status: "failed", error: `Process exited with code ${code}: ${stderr.slice(0, 500)}` });
+          return;
+        }
+        resolve({ text: finalResponse || accumulatedText, tokensIn, tokensOut, cost, contextTokens, model, status: "success" });
+      });
+
+      proc.on("error", (err: Error) => {
+        clearTimeout(timeoutId);
+        this.activeProcesses.delete(proc);
+        resolve({ text: "", tokensIn: 0, tokensOut: 0, cost: 0, contextTokens: 0, model, status: "failed", error: `Failed to spawn ${this.cliBinary()}: ${err.message}` });
+      });
+
+      timeoutController.signal.addEventListener("abort", () => {
+        wasAborted = true;
+        proc.kill("SIGTERM");
+        setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 5000);
+        clearTimeout(timeoutId);
+        this.activeProcesses.delete(proc);
+        resolve({ text: accumulatedText, tokensIn, tokensOut, cost, contextTokens, model, status: "failed", error: `Agent timed out after ${Math.round(timeoutMs / 1000)}s` });
+      }, { once: true });
+
+      if (opts?.signal) {
+        const killProc = () => {
+          wasAborted = true;
+          proc.kill("SIGTERM");
+          setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 5000);
+        };
+        if (opts.signal.aborted) killProc();
+        else opts.signal.addEventListener("abort", killProc, { once: true });
+      }
+    });
+  }
+
+  async destroyAgent(handle: AgentHandle): Promise<void> {
+    this.handles.delete(handle.id);
+  }
+
+  setOrchestratorPrompt(prompt: string): void {
+    this.orchestratorPrompt = prompt;
+  }
+
+  async injectContext(handle: AgentHandle, files: string[]): Promise<void> {
+    const state = this.handles.get(handle.id);
+    if (state) state.contextFiles = files;
+  }
+
+  getContextUsage(handle: AgentHandle): ContextUsage {
+    const state = this.handles.get(handle.id);
+    const tokens = state?.lastContextTokens || 0;
+    return { tokens, percent: (tokens / 200_000) * 100 };
+  }
+
+  setModel(handle: AgentHandle, modelConfig: { tier: ModelTier; thinking: ThinkingMode }): void {
+    const state = this.handles.get(handle.id);
+    if (state) state.modelConfig = modelConfig;
+  }
+
+  abort(): void {
+    for (const proc of this.activeProcesses) {
+      proc.kill("SIGTERM");
+      setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 5000);
+    }
+    this.activeProcesses.clear();
+  }
+
+  async spawnSubAgent(parentId: string, config: ChildAgentConfig, sessionId: string): Promise<AgentHandle> {
+    const agentConfig = {
+      ...config,
+      model: config.model ?? { tier: "standard" as ModelTier, thinking: "on" as ThinkingMode },
+    } as AgentConfig;
+    const handle = await this.spawnAgent(agentConfig, sessionId);
+    handle.parentAgentId = parentId;
+    return handle;
+  }
+
+  async destroySubAgent(_parentId: string, childId: string): Promise<void> {
+    for (const [key] of this.handles) {
+      if (key.endsWith(`:${childId}`)) {
+        this.handles.delete(key);
+        return;
+      }
+    }
+  }
+}

package/src/base-event-bus.ts

@@ -0,0 +1,133 @@
+// ── BaseEventBus (L2) ─────────────────────────────────────────────
+// Concrete handler storage + sequential async dispatch.
+// All fire*() methods serialize through a queue to prevent interleaving.
+
+import type { EventBusAdapter } from "@aos-harness/runtime/types";
+
+export class BaseEventBus implements EventBusAdapter {
+  private handlers: {
+    sessionStart: (() => Promise<void>) | null;
+    sessionShutdown: (() => Promise<void>) | null;
+    beforeAgentStart: ((prompt: string) => Promise<{ systemPrompt?: string }>) | null;
+    agentEnd: (() => Promise<void>) | null;
+    toolCall: ((toolName: string, input: unknown) => Promise<{ block?: boolean }>) | null;
+    toolResult: ((toolName: string, input: unknown, result: unknown) => Promise<void>) | null;
+    messageEnd: ((usage: { cost: number; tokens: number }) => Promise<void>) | null;
+    compaction: (() => Promise<void>) | null;
+  } = {
+    sessionStart: null,
+    sessionShutdown: null,
+    beforeAgentStart: null,
+    agentEnd: null,
+    toolCall: null,
+    toolResult: null,
+    messageEnd: null,
+    compaction: null,
+  };
+
+  // Sequential dispatch queue
+  private queue: Promise<void> = Promise.resolve();
+
+  private enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    let resolve!: (value: T) => void;
+    let reject!: (err: unknown) => void;
+    const result = new Promise<T>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.queue = this.queue.then(() => fn().then(resolve, reject));
+    return result;
+  }
+
+  // ── Registration (EventBusAdapter interface) ───────────────────
+
+  onSessionStart(handler: () => Promise<void>): void {
+    this.handlers.sessionStart = handler;
+  }
+
+  onSessionShutdown(handler: () => Promise<void>): void {
+    this.handlers.sessionShutdown = handler;
+  }
+
+  onBeforeAgentStart(handler: (prompt: string) => Promise<{ systemPrompt?: string }>): void {
+    this.handlers.beforeAgentStart = handler;
+  }
+
+  onAgentEnd(handler: () => Promise<void>): void {
+    this.handlers.agentEnd = handler;
+  }
+
+  onToolCall(handler: (toolName: string, input: unknown) => Promise<{ block?: boolean }>): void {
+    this.handlers.toolCall = handler;
+  }
+
+  onToolResult(handler: (toolName: string, input: unknown, result: unknown) => Promise<void>): void {
+    this.handlers.toolResult = handler;
+  }
+
+  onMessageEnd(handler: (usage: { cost: number; tokens: number }) => Promise<void>): void {
+    this.handlers.messageEnd = handler;
+  }
+
+  onCompaction(handler: () => Promise<void>): void {
+    this.handlers.compaction = handler;
+  }
+
+  // ── Fire methods (called by BaseAgentRuntime) ──────────────────
+
+  fireSessionStart(): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.handlers.sessionStart) await this.handlers.sessionStart();
+    });
+  }
+
+  fireSessionShutdown(): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.handlers.sessionShutdown) await this.handlers.sessionShutdown();
+    });
+  }
+
+  fireBeforeAgentStart(prompt: string): Promise<{ systemPrompt?: string }> {
+    return this.enqueue(async () => {
+      if (this.handlers.beforeAgentStart) {
+        return await this.handlers.beforeAgentStart(prompt);
+      }
+      return {};
+    });
+  }
+
+  fireAgentEnd(): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.handlers.agentEnd) await this.handlers.agentEnd();
+    });
+  }
+
+  fireToolCall(toolName: string, input: unknown): Promise<{ block?: boolean }> {
+    return this.enqueue(async () => {
+      if (this.handlers.toolCall) {
+        return await this.handlers.toolCall(toolName, input);
+      }
+      return { block: false };
+    });
+  }
+
+  fireToolResult(toolName: string, input: unknown, result: unknown): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.handlers.toolResult) {
+        await this.handlers.toolResult(toolName, input, result);
+      }
+    });
+  }
+
+  fireMessageEnd(usage: { cost: number; tokens: number }): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.handlers.messageEnd) await this.handlers.messageEnd(usage);
+    });
+  }
+
+  fireCompaction(): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.handlers.compaction) await this.handlers.compaction();
+    });
+  }
+}

package/src/base-workflow.ts

@@ -0,0 +1,392 @@
+// ── BaseWorkflow (L4) ────────────────────────────────────────────
+// Parallel dispatch, file operations, state persistence, artifacts,
+// code execution, and skill invocation. CLI-agnostic.
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import * as yaml from "js-yaml";
+import type {
+  WorkflowAdapter,
+  AgentHandle,
+  AgentResponse,
+  MessageOpts,
+  ArtifactManifest,
+  LoadedArtifact,
+  ExecuteCodeOpts,
+  ExecutionResult,
+  SkillInput,
+  SkillResult,
+  ReviewResult,
+} from "@aos-harness/runtime/types";
+import { UnsupportedError } from "@aos-harness/runtime/types";
+
+// Minimal interface for the agent runtime dependency
+interface AgentMessageSender {
+  sendMessage(handle: AgentHandle, message: string, opts?: MessageOpts): Promise<AgentResponse>;
+}
+
+export class BaseWorkflow implements WorkflowAdapter {
+  private agentRuntime: AgentMessageSender;
+  private projectRoot: string;
+
+  constructor(agentRuntime: AgentMessageSender, projectRoot: string = process.cwd()) {
+    this.agentRuntime = agentRuntime;
+    this.projectRoot = resolve(projectRoot);
+  }
+
+  private validatePath(filePath: string): string {
+    const resolved = resolve(filePath);
+    if (!resolved.startsWith(this.projectRoot)) {
+      throw new Error(`Path "${filePath}" is outside the project directory`);
+    }
+    return resolved;
+  }
+
+  private validateStateKey(key: string): void {
+    if (!/^[a-zA-Z0-9_-]+$/.test(key)) {
+      throw new Error(`Invalid state key: "${key}" — must be alphanumeric with hyphens/underscores`);
+    }
+  }
+
+  async dispatchParallel(
+    handles: AgentHandle[],
+    message: string,
+    opts?: { signal?: AbortSignal; onStream?: (agentId: string, partial: string) => void },
+  ): Promise<AgentResponse[]> {
+    const tasks = handles.map((handle) =>
+      this.agentRuntime.sendMessage(handle, message, {
+        signal: opts?.signal,
+        onStream: opts?.onStream
+          ? (partial: string) => opts.onStream!(handle.agentId, partial)
+          : undefined,
+      }),
+    );
+
+    const results = await Promise.allSettled(tasks);
+
+    return results.map((result): AgentResponse => {
+      if (result.status === "fulfilled") {
+        return result.value;
+      }
+      const err = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      return {
+        text: "",
+        tokensIn: 0,
+        tokensOut: 0,
+        cost: 0,
+        contextTokens: 0,
+        model: "",
+        status: "failed",
+        error: err,
+      };
+    });
+  }
+
+  async isolateWorkspace(): Promise<{ path: string; cleanup: () => Promise<void> }> {
+    const id = `aos-worktree-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const worktreePath = join(".aos", "worktrees", id);
+
+    await new Promise<void>((resolve, reject) => {
+      const proc = spawn("git", ["worktree", "add", "--detach", worktreePath], {
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let stderr = "";
+      proc.stderr?.on("data", (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+      proc.on("close", (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`git worktree add failed (exit ${code}): ${stderr.trim()}`));
+      });
+    });
+
+    const cleanup = async (): Promise<void> => {
+      await new Promise<void>((resolve, reject) => {
+        const proc = spawn("git", ["worktree", "remove", "--force", worktreePath], {
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stderr = "";
+        proc.stderr?.on("data", (chunk: Buffer) => {
+          stderr += chunk.toString();
+        });
+        proc.on("close", (code) => {
+          if (code === 0) resolve();
+          else reject(new Error(`git worktree remove failed (exit ${code}): ${stderr.trim()}`));
+        });
+      });
+    };
+
+    return { path: worktreePath, cleanup };
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const safe = this.validatePath(path);
+    const dir = dirname(safe);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(safe, content, "utf-8");
+  }
+
+  async readFile(path: string): Promise<string> {
+    const safe = this.validatePath(path);
+    if (!existsSync(safe)) {
+      throw new Error(`File not found: ${path}`);
+    }
+    return readFileSync(safe, "utf-8");
+  }
+
+  private static ALLOWED_EDITORS = new Set(["code", "vim", "nvim", "nano", "emacs", "subl", "mate", "open"]);
+
+  async openInEditor(path: string, editor: string): Promise<void> {
+    const safePath = this.validatePath(path);
+    const editorName = editor.split("/").pop() ?? editor;
+    if (!BaseWorkflow.ALLOWED_EDITORS.has(editorName)) {
+      throw new Error(`Editor "${editor}" is not in the allowed list: ${[...BaseWorkflow.ALLOWED_EDITORS].join(", ")}`);
+    }
+    spawn(editor, [safePath], { detached: true, stdio: "ignore" }).unref();
+  }
+
+  async persistState(key: string, value: unknown): Promise<void> {
+    this.validateStateKey(key);
+    const stateDir = join(this.projectRoot, ".aos", "state");
+    if (!existsSync(stateDir)) {
+      mkdirSync(stateDir, { recursive: true });
+    }
+    const filePath = join(stateDir, `${key}.json`);
+    writeFileSync(filePath, JSON.stringify(value, null, 2), "utf-8");
+  }
+
+  async loadState(key: string): Promise<unknown> {
+    this.validateStateKey(key);
+    const filePath = join(this.projectRoot, ".aos", "state", `${key}.json`);
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  }
+
+  async createArtifact(artifact: ArtifactManifest, content: string): Promise<void> {
+    await this.writeFile(artifact.content_path, content);
+    const manifestPath = artifact.content_path.replace(/\.[^.]+$/, ".artifact.yaml");
+    await this.writeFile(manifestPath, yaml.dump(artifact));
+  }
+
+  async loadArtifact(artifactId: string, sessionDir: string): Promise<LoadedArtifact> {
+    const manifestPath = join(sessionDir, "artifacts", `${artifactId}.artifact.yaml`);
+    const manifestYaml = await this.readFile(manifestPath);
+    const manifest = yaml.load(manifestYaml, { schema: yaml.JSON_SCHEMA }) as ArtifactManifest;
+    const content = await this.readFile(manifest.content_path);
+    return { manifest, content };
+  }
+
+  async submitForReview(
+    artifact: LoadedArtifact,
+    reviewer: AgentHandle,
+    reviewPrompt?: string,
+  ): Promise<ReviewResult> {
+    const prompt =
+      reviewPrompt ||
+      `Review the following artifact and provide your assessment:
+
+## Artifact: ${artifact.manifest.id}
+- Produced by: ${artifact.manifest.produced_by.join(", ")}
+- Format: ${artifact.manifest.format}
+
+Respond with:
+1. Status: APPROVED, REJECTED, or NEEDS-REVISION
+2. If not approved, list issues with severity (critical/major/minor/suggestion)
+3. Specific feedback for improvement`;
+
+    const fullPrompt = `${prompt}\n\n---\n\n${artifact.content}`;
+
+    try {
+      const response = await this.agentRuntime.sendMessage(reviewer, fullPrompt);
+      const text = response.text ?? "";
+
+      const upperText = text.toUpperCase();
+      let status: "approved" | "rejected" | "needs-revision" = "needs-revision";
+      if (upperText.includes("APPROVED") && !upperText.includes("NOT APPROVED")) {
+        status = "approved";
+      } else if (upperText.includes("REJECTED")) {
+        status = "rejected";
+      }
+
+      return { status, feedback: text, reviewer: reviewer.agentId };
+    } catch (err: any) {
+      return {
+        status: "needs-revision",
+        feedback: `Review failed: ${err.message}`,
+        reviewer: reviewer.agentId,
+      };
+    }
+  }
+
+  async executeCode(handle: AgentHandle, code: string, opts?: ExecuteCodeOpts): Promise<ExecutionResult> {
+    const language = opts?.language ?? "bash";
+    const timeout = opts?.timeout_ms ?? 30000;
+    const cwd = opts?.cwd ?? process.cwd();
+    const sandbox = opts?.sandbox ?? "strict";
+
+    let cmd: string;
+    let args: string[];
+
+    switch (language) {
+      case "bash":
+      case "sh":
+        cmd = "/bin/bash";
+        args = ["-c", code];
+        break;
+      case "typescript":
+      case "ts":
+        cmd = "bun";
+        args = ["eval", code];
+        break;
+      case "python":
+      case "py":
+        cmd = "python3";
+        args = ["-c", code];
+        break;
+      case "node":
+      case "javascript":
+      case "js":
+        cmd = "node";
+        args = ["-e", code];
+        break;
+      default:
+        throw new Error(`Unsupported language: ${language}. Supported: bash, typescript, python, javascript`);
+    }
+
+    return new Promise<ExecutionResult>((resolve) => {
+      const startTime = Date.now();
+      let stdout = "";
+      let stderr = "";
+      let killed = false;
+
+      const child = spawn(cmd, args, {
+        cwd: this.validatePath(cwd),
+        env: {
+          ...this.buildSafeEnv(sandbox),
+          ...(opts?.env ?? {}),
+        },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      const timer = setTimeout(() => {
+        killed = true;
+        child.kill("SIGKILL");
+      }, timeout);
+
+      child.stdout.on("data", (data: Buffer) => {
+        stdout += data.toString();
+        if (stdout.length > 1_048_576) {
+          stdout = stdout.slice(0, 1_048_576) + "\n[TRUNCATED]";
+          killed = true;
+          child.kill("SIGKILL");
+        }
+      });
+
+      child.stderr.on("data", (data: Buffer) => {
+        stderr += data.toString();
+        if (stderr.length > 1_048_576) {
+          stderr = stderr.slice(0, 1_048_576) + "\n[TRUNCATED]";
+        }
+      });
+
+      child.on("close", (exitCode: number | null) => {
+        clearTimeout(timer);
+        resolve({
+          success: exitCode === 0 && !killed,
+          exit_code: exitCode ?? (killed ? 137 : 1),
+          stdout,
+          stderr:
+            killed && !stderr.includes("TRUNCATED")
+              ? stderr + "\n[KILLED: timeout or output limit]"
+              : stderr,
+          duration_ms: Date.now() - startTime,
+        });
+      });
+
+      child.on("error", (err: Error) => {
+        clearTimeout(timer);
+        resolve({
+          success: false,
+          exit_code: 1,
+          stdout,
+          stderr: err.message,
+          duration_ms: Date.now() - startTime,
+        });
+      });
+    });
+  }
+
+  private buildSafeEnv(sandbox: "strict" | "relaxed"): Record<string, string> {
+    const base: Record<string, string> = {
+      PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+      HOME: process.env.HOME ?? "/tmp",
+      LANG: process.env.LANG ?? "en_US.UTF-8",
+      TERM: "dumb",
+    };
+
+    if (sandbox === "relaxed") {
+      for (const key of ["NODE_PATH", "BUN_INSTALL", "PYTHONPATH", "SHELL"]) {
+        if (process.env[key]) base[key] = process.env[key]!;
+      }
+    }
+
+    return base;
+  }
+
+  async invokeSkill(handle: AgentHandle, skillId: string, input: SkillInput): Promise<SkillResult> {
+    const skillDir = join(this.projectRoot, "core", "skills", skillId);
+    const skillYamlPath = join(skillDir, "skill.yaml");
+
+    if (!existsSync(skillYamlPath)) {
+      throw new UnsupportedError("invokeSkill", `Skill "${skillId}" not found at ${skillYamlPath}`);
+    }
+
+    const skillYamlRaw = readFileSync(skillYamlPath, "utf-8");
+    const skillConfig = yaml.load(skillYamlRaw, { schema: yaml.JSON_SCHEMA }) as any;
+
+    let skillPrompt = skillConfig.description;
+    const promptPath = join(skillDir, "prompt.md");
+    if (existsSync(promptPath)) {
+      skillPrompt = readFileSync(promptPath, "utf-8");
+    }
+
+    const contextParts: string[] = [];
+    if (input.args) contextParts.push(`Arguments: ${input.args}`);
+    if (input.context) {
+      for (const [key, value] of Object.entries(input.context)) {
+        contextParts.push(`${key}: ${value}`);
+      }
+    }
+
+    const fullPrompt = [skillPrompt, "", "## Input Context", contextParts.join("\n")].join("\n");
+
+    try {
+      const response = await this.agentRuntime.sendMessage(handle, fullPrompt);
+      return {
+        success: true,
+        output: response.text ?? JSON.stringify(response),
+      };
+    } catch (err: any) {
+      return {
+        success: false,
+        output: "",
+        error: err.message ?? String(err),
+      };
+    }
+  }
+
+  async enforceToolAccess(
+    _agentId: string,
+    _toolCall: { tool: string; path?: string; command?: string },
+  ): Promise<{ allowed: boolean; reason?: string }> {
+    return { allowed: true };
+  }
+}

package/src/compose.ts

@@ -0,0 +1,76 @@
+// ── composeAdapter ────────────────────────────────────────────────
+// Combines 4 adapter layers into a single AOSAdapter with explicit
+// method binding. TypeScript enforces the result satisfies AOSAdapter.
+
+import type {
+  AgentRuntimeAdapter,
+  EventBusAdapter,
+  UIAdapter,
+  WorkflowAdapter,
+  AOSAdapter,
+} from "@aos-harness/runtime/types";
+
+export function composeAdapter(
+  agentRuntime: AgentRuntimeAdapter,
+  eventBus: EventBusAdapter,
+  ui: UIAdapter,
+  workflow: WorkflowAdapter,
+): AOSAdapter {
+  return {
+    // AgentRuntimeAdapter (L1)
+    spawnAgent: agentRuntime.spawnAgent.bind(agentRuntime),
+    sendMessage: agentRuntime.sendMessage.bind(agentRuntime),
+    destroyAgent: agentRuntime.destroyAgent.bind(agentRuntime),
+    setOrchestratorPrompt: agentRuntime.setOrchestratorPrompt.bind(agentRuntime),
+    injectContext: agentRuntime.injectContext.bind(agentRuntime),
+    getContextUsage: agentRuntime.getContextUsage.bind(agentRuntime),
+    setModel: agentRuntime.setModel.bind(agentRuntime),
+    getAuthMode: agentRuntime.getAuthMode.bind(agentRuntime),
+    getModelCost: agentRuntime.getModelCost.bind(agentRuntime),
+    abort: agentRuntime.abort.bind(agentRuntime),
+    spawnSubAgent: agentRuntime.spawnSubAgent.bind(agentRuntime),
+    destroySubAgent: agentRuntime.destroySubAgent.bind(agentRuntime),
+
+    // EventBusAdapter (L2)
+    onSessionStart: eventBus.onSessionStart.bind(eventBus),
+    onSessionShutdown: eventBus.onSessionShutdown.bind(eventBus),
+    onBeforeAgentStart: eventBus.onBeforeAgentStart.bind(eventBus),
+    onAgentEnd: eventBus.onAgentEnd.bind(eventBus),
+    onToolCall: eventBus.onToolCall.bind(eventBus),
+    onToolResult: eventBus.onToolResult.bind(eventBus),
+    onMessageEnd: eventBus.onMessageEnd.bind(eventBus),
+    onCompaction: eventBus.onCompaction.bind(eventBus),
+
+    // UIAdapter (L3)
+    registerCommand: ui.registerCommand.bind(ui),
+    registerTool: ui.registerTool.bind(ui),
+    renderAgentResponse: ui.renderAgentResponse.bind(ui),
+    renderCustomMessage: ui.renderCustomMessage.bind(ui),
+    setWidget: ui.setWidget.bind(ui),
+    setFooter: ui.setFooter.bind(ui),
+    setStatus: ui.setStatus.bind(ui),
+    setTheme: ui.setTheme.bind(ui),
+    promptSelect: ui.promptSelect.bind(ui),
+    promptConfirm: ui.promptConfirm.bind(ui),
+    promptInput: ui.promptInput.bind(ui),
+    notify: ui.notify.bind(ui),
+    blockInput: ui.blockInput.bind(ui),
+    unblockInput: ui.unblockInput.bind(ui),
+    steerMessage: ui.steerMessage.bind(ui),
+
+    // WorkflowAdapter (L4)
+    dispatchParallel: workflow.dispatchParallel.bind(workflow),
+    isolateWorkspace: workflow.isolateWorkspace.bind(workflow),
+    writeFile: workflow.writeFile.bind(workflow),
+    readFile: workflow.readFile.bind(workflow),
+    openInEditor: workflow.openInEditor.bind(workflow),
+    persistState: workflow.persistState.bind(workflow),
+    loadState: workflow.loadState.bind(workflow),
+    executeCode: workflow.executeCode.bind(workflow),
+    invokeSkill: workflow.invokeSkill.bind(workflow),
+    createArtifact: workflow.createArtifact.bind(workflow),
+    loadArtifact: workflow.loadArtifact.bind(workflow),
+    submitForReview: workflow.submitForReview.bind(workflow),
+    enforceToolAccess: workflow.enforceToolAccess.bind(workflow),
+  };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export type {
+  StdoutFormat,
+  ParsedEvent,
+  ModelInfo,
+  HandleState,
+} from "./types";
+export { BaseAgentRuntime } from "./base-agent-runtime";
+export { BaseEventBus } from "./base-event-bus";
+export { TerminalUI } from "./terminal-ui";
+export { BaseWorkflow } from "./base-workflow";
+export { composeAdapter } from "./compose";

package/src/terminal-ui.ts

@@ -0,0 +1,140 @@
+// ── TerminalUI (L3) ───────────────────────────────────────────────
+// ANSI terminal-native UI for non-Pi adapters.
+// Console-based rendering, readline prompts, command/tool registry.
+
+import * as readline from "node:readline";
+import type { UIAdapter } from "@aos-harness/runtime/types";
+
+function parseHexColor(hex: string): { r: number; g: number; b: number } {
+  const clean = hex.replace(/^#/, "");
+  return {
+    r: parseInt(clean.substring(0, 2), 16) || 0,
+    g: parseInt(clean.substring(2, 4), 16) || 0,
+    b: parseInt(clean.substring(4, 6), 16) || 0,
+  };
+}
+
+export class TerminalUI implements UIAdapter {
+  private commands = new Map<string, (args: string) => Promise<void>>();
+  private tools = new Map<string, { schema: Record<string, unknown>; handler: (params: Record<string, unknown>) => Promise<unknown> }>();
+  private inputBlocked = false;
+  private allowedCommands: string[] = [];
+  private steeredMessage: string | null = null;
+
+  registerCommand(name: string, handler: (args: string) => Promise<void>): void {
+    this.commands.set(name, handler);
+  }
+
+  async dispatchCommand(name: string, args: string): Promise<boolean> {
+    const handler = this.commands.get(name);
+    if (!handler) return false;
+    await handler(args);
+    return true;
+  }
+
+  registerTool(
+    name: string,
+    schema: Record<string, unknown>,
+    handler: (params: Record<string, unknown>) => Promise<unknown>,
+  ): void {
+    this.tools.set(name, { schema, handler });
+  }
+
+  hasTool(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  async invokeTool(name: string, params: Record<string, unknown>): Promise<unknown> {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Unknown tool: ${name}`);
+    return await tool.handler(params);
+  }
+
+  renderAgentResponse(agent: string, response: string, color: string): void {
+    const { r, g, b } = parseHexColor(color);
+    const bgOpen = `\x1b[48;2;${r};${g};${b}m`;
+    const fgDark = `\x1b[38;2;30;30;30m`;
+    const reset = `\x1b[0m`;
+    const dim = `\x1b[2m`;
+    console.log(`${bgOpen}${fgDark} ${agent} ${reset}`);
+    console.log(`${dim}${response}${reset}`);
+  }
+
+  renderCustomMessage(type: string, content: string, _details: Record<string, unknown>): void {
+    console.log(`[${type}] ${content}`);
+  }
+
+  setWidget(_id: string, _renderer: (() => string[]) | undefined): void {}
+  setFooter(_renderer: (width: number) => string[]): void {}
+  setStatus(_key: string, _text: string): void {}
+  setTheme(_name: string): void {}
+
+  async promptSelect(label: string, options: string[]): Promise<number> {
+    console.log(`\n${label}`);
+    for (let i = 0; i < options.length; i++) {
+      console.log(`  ${i + 1}. ${options[i]}`);
+    }
+    const answer = await this.readLine("Enter number: ");
+    const idx = parseInt(answer, 10) - 1;
+    return idx >= 0 && idx < options.length ? idx : 0;
+  }
+
+  async promptConfirm(title: string, message: string): Promise<boolean> {
+    console.log(`\n${title}`);
+    console.log(message);
+    const answer = await this.readLine("Confirm? (y/n): ");
+    return answer.toLowerCase().startsWith("y");
+  }
+
+  async promptInput(label: string): Promise<string> {
+    return this.readLine(`${label}: `);
+  }
+
+  private readLine(prompt: string): Promise<string> {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    return new Promise((resolve) => {
+      rl.question(prompt, (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    });
+  }
+
+  notify(message: string, level: "info" | "warning" | "error"): void {
+    const prefix = level === "error" ? "[ERROR]" : level === "warning" ? "[WARN]" : "[INFO]";
+    const colorCode = level === "error" ? "\x1b[31m" : level === "warning" ? "\x1b[33m" : "\x1b[36m";
+    const reset = "\x1b[0m";
+    console.log(`${colorCode}${prefix}${reset} ${message}`);
+  }
+
+  blockInput(allowedCommands: string[]): void {
+    this.inputBlocked = true;
+    this.allowedCommands = allowedCommands;
+  }
+
+  unblockInput(): void {
+    this.inputBlocked = false;
+    this.allowedCommands = [];
+  }
+
+  isInputBlocked(): boolean {
+    return this.inputBlocked;
+  }
+
+  getAllowedCommands(): string[] {
+    return this.allowedCommands;
+  }
+
+  steerMessage(message: string): void {
+    this.steeredMessage = message;
+  }
+
+  consumeSteeredMessage(): string | null {
+    const msg = this.steeredMessage;
+    this.steeredMessage = null;
+    return msg;
+  }
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+// ── Shared Adapter Types ──────────────────────────────────────────
+
+import type { AgentConfig, ModelTier, ThinkingMode } from "@aos-harness/runtime/types";
+
+// ── Stdout format declaration ────────────────────────────────────
+
+export type StdoutFormat = "ndjson" | "sse" | "chunked-json";
+
+// ── Parsed event normalization ───────────────────────────────────
+
+export type ParsedEvent =
+  | { type: "text_delta"; text: string }
+  | {
+      type: "message_end";
+      text: string;
+      tokensIn: number;
+      tokensOut: number;
+      cost: number;
+      contextTokens: number;
+      model: string;
+    }
+  | { type: "tool_call"; name: string; input: unknown }
+  | { type: "tool_result"; name: string; input: unknown; result: unknown }
+  | { type: "ignored" };
+
+// ── Model info from CLI discovery ────────────────────────────────
+
+export interface ModelInfo {
+  id: string;
+  name: string;
+  contextWindow: number;
+  provider: string;
+}
+
+// ── Per-handle state tracked by BaseAgentRuntime ─────────────────
+
+export interface HandleState {
+  config: AgentConfig;
+  sessionFile: string;
+  contextFiles: string[];
+  modelConfig: { tier: ModelTier; thinking: ThinkingMode };
+  lastContextTokens: number;
+}