@gobing-ai/ts-ai-runner 0.4.7 → 0.4.9

package/README.md

@@ -13,7 +13,7 @@ bun add @gobing-ai/ts-ai-runner
 `ts-ai-runner` normalizes the command-line surface of common coding agents so application code can work with stable TypeScript APIs instead of hard-coded executable arguments.
 
 | Export | Purpose |
-|--------|---------|
+| -------- | --------- |
 | `AiRunner` | Runs help, version, auth, prompt, and slash commands through a pluggable process executor; can also build a prompt command without executing it. Emits typed events via optional `EventBus<AgentEvents>`. |
 | `AgentDetector` | Probes supported agent CLIs and parses version output |
 | `DoctorRunner` | Combines installation and authentication checks into a usability report |
@@ -25,14 +25,15 @@ bun add @gobing-ai/ts-ai-runner
 | `buildIdentityPreamble()` / `getGitContext()` | Builds team-mode identity, communication context, and git metadata for prompts |
 | `loadAgentSpecs()` / `saveAgentSpec()` / `deleteAgentSpec()` | Persist agent definitions as YAML-compatible config |
 | `validateAgentId()` | Enforces agent ID format rules |
-| `MessageService` | Thin service wrapper around `@gobing-ai/ts-db/inbox` |
+| `formatMessage()` | Renders a `DrainedMessage` into the line injected into an agent's stdin pipe |
+| `MessageStore` / `DrainedMessage` | ai-runner-owned orchestration persistence port and minimal message view consumed by `TeamOrchestrator` |
 | `TeamAgentProcess` | Manages a long-running agent subprocess with pipe-mode stdin/stdout |
 | `TeamOrchestrator` | Loads specs, starts/stops agents, routes durable/live messages, and emits lifecycle events |
 | `AgentEvents` / `AiRunnerProcessEvents` | Typed event maps for agent and process-level observability |
 | `AGENT_SHIMS` / `TIER1_PRIORITY` / `TIER2_AGENTS` / `DISPLAY_ORDER` | Agent registry constants |
 | `isAgentName()` | Type guard for supported agent identifiers |
 
-Supported agent identifiers: `claude`, `codex`, `gemini` (deprecated), `pi`, `omp`, `opencode`, `antigravity-cli`, `openclaw`, `hermes`. The `antigravity` id is a deprecated alias of `antigravity-cli`. See [Deprecation & Aliases](#deprecation--aliases).
+Supported agent identifiers: `claude`, `codex`, `gemini` (deprecated), `pi`, `omp`, `opencode`, `antigravity-cli`, `openclaw`, `hermes`, `grok`. The `antigravity` id is a deprecated alias of `antigravity-cli`. See [Deprecation & Aliases](#deprecation--aliases).
 
 ## Architecture
 
@@ -62,11 +63,13 @@ graph TB
         TeamOrchestrator["TeamOrchestrator<br/>loadSpecs / startAgent / stopAgent<br/>sendMessage / getAgentStatus / stopAll"]
         AgentSpec["AgentSpec<br/>(YAML config)<br/>load / save / delete"]
         TeamAgentProcess["TeamAgentProcess<br/>(pipe-mode subprocess)<br/>start / stop / send / subscribe"]
-        MessageService["MessageService<br/>(InboxMessageDao wrapper)<br/>enqueue / drain / deliver / fail"]
+        MessageStore["<b>MessageStore</b><br/>(ai-runner-owned port)<br/>enqueue / drainPending / markDelivered / markFailed"]
+        InboxMessageDao["<i>InboxMessageDao<br/>(@gobing-ai/ts-db/inbox)</i><br/>structural provider"]
 
         TeamOrchestrator -->|"loads"| AgentSpec
         TeamOrchestrator -->|"creates + manages"| TeamAgentProcess
-        TeamOrchestrator -->|"routes through"| MessageService
+        TeamOrchestrator -->|"writes/reads via"| MessageStore
+        InboxMessageDao -.->|"satisfies"| MessageStore
         TeamOrchestrator -->|"resolves command via"| AgentShim
         TeamOrchestrator -.->|"emits events"| EventBus
         TeamOrchestrator -.->|"builds preamble"| Identity
@@ -75,6 +78,7 @@ graph TB
 ```
 
 ### One-shot prompt flow
+
 ```mermaid
 sequenceDiagram
     participant Caller
@@ -116,7 +120,6 @@ sequenceDiagram
     participant Shim as AgentShim
     participant Identity as buildIdentityPreamble
     participant Proc as TeamAgentProcess
-    participant Msg as MessageService
     participant DB as InboxMessageDao
     participant Agent as Coding Agent (CLI)
     participant EventBus
@@ -135,15 +138,13 @@ sequenceDiagram
     Orch->>Proc: start()
     Proc->>Agent: spawn pipe-mode subprocess
     Agent-->>Proc: stdout/stderr streams
-    Orch->>Msg: drain("coder")
-    Msg->>DB: drain(toId)
-    DB-->>Msg: pending messages
-    Msg-->>Orch: messages[]
+    Orch->>DB: drainPending("coder")
+    DB-->>Orch: pending messages
     alt pending messages exist
         loop for each message
             Orch->>Proc: send(formattedMessage)
             Proc->>Agent: write to stdin
-            Orch->>Msg: deliver(msg.id)
+            Orch->>DB: markDelivered(msg.id)
         end
     end
     Orch->>EventBus: emit("agent.started")
@@ -151,18 +152,15 @@ sequenceDiagram
 
     Note over Host,EventBus: Sending a message (durable + live)
     Host->>Orch: sendMessage(null, "coder", "Implement task 0005")
-    Orch->>Msg: enqueue(null, "coder", body)
-    Msg->>DB: enqueue(from, to, body)
-    DB-->>Msg: messageId
-    Msg-->>Orch: messageId
+    Orch->>DB: enqueue(null, "coder", body)
+    DB-->>Orch: messageId
     alt agent is running
-        Orch->>Msg: drain("coder")
-        Msg->>DB: drain(toId)
-        DB-->>Msg: pending messages
+        Orch->>DB: drainPending("coder")
+        DB-->>Orch: pending messages
         loop for each message
             Orch->>Proc: send(formattedMessage)
             Proc->>Agent: write to stdin
-            Orch->>Msg: deliver(msg.id)
+            Orch->>DB: markDelivered(msg.id)
         end
     end
     Orch->>EventBus: emit("agent.message.sent")
@@ -182,9 +180,9 @@ Key design decisions:
 - **Shims are pure**: `AgentShim` produces `{ command, args }` without touching the filesystem or launching processes. All side effects live in `AiRunner` and `TeamAgentProcess`.
 - **ProcessExecutor is injectable**: tests inject a stub executor; production uses `NodeProcessExecutor` (or the Bun pipe-process seam for team mode).
 - **Events are opt-in**: `AiRunnerOptions.events` and `TeamOrchestratorOptions.events` accept an `EventBus<AgentEvents>` for structured observability. Without it, the runner is silent.
-- **Team mode is composable**: `AgentSpec`, `TeamAgentProcess`, `MessageService`, and `TeamOrchestrator` are small building blocks. Downstream apps compose them into their own orchestration layer.
+- **Team mode is composable**: `AgentSpec`, `TeamAgentProcess`, and `TeamOrchestrator` are small building blocks. `TeamOrchestrator` depends on the ai-runner-owned `MessageStore` port; `InboxMessageDao` from `@gobing-ai/ts-db/inbox` is one structural provider — no adapter class — and in-memory test doubles implement the port directly. Downstream apps compose them into their own orchestration layer.
 
-The package depends on `@gobing-ai/ts-runtime` for process execution, `@gobing-ai/ts-db` for team-mode inbox types, and `@gobing-ai/ts-infra` for structured logging and EventBus. The target agent CLIs are not bundled; install them separately in the host environment.
+The package depends on `@gobing-ai/ts-runtime` for process execution and `@gobing-ai/ts-infra` for structured logging and EventBus. `@gobing-ai/ts-db` is a development dependency only: production source under `packages/ai-runner/src` has no direct `@gobing-ai/ts-db` imports for message access, and only the DB-backed integration test resolves the concrete `InboxMessageDao`. The target agent CLIs are not bundled; install them separately in the host environment.
 
 ## Detect Installed Agents
 
@@ -312,7 +310,7 @@ const runner = new AiRunner({ events: bus });
 Available events:
 
 | Event | When |
-|-------|------|
+| ------- | ------ |
 | `agent.invoke.start` | Immediately before an agent CLI invocation starts |
 | `agent.invoke.exit` | After an agent CLI invocation exits |
 | `agent.started` | When a long-running team agent process starts |
@@ -424,7 +422,7 @@ interface AgentShim {
 Agent-specific behavior:
 
 | Agent | CLI | Tier | Auth check | Prompt flags |
-|-------|-----|------|------------|--------------|
+| ------- | ----- | ------ | ------------ | -------------- |
 | `claude` | `claude` | 1 | `claude auth status` | `-p`, `--continue`, `--model`, `--output-format` |
 | `codex` | `codex` | 1 | `codex login status` | `exec <prompt>`, `exec resume --last`, `-m`, `--json` |
 | `gemini` *(deprecated)* | `gemini` | 1 | env-only | `-p`, `-r latest` (resume), `-m`, `-o` |
@@ -433,6 +431,9 @@ Agent-specific behavior:
 | `opencode` | `opencode` | 1 | `opencode providers` | `run`, `-c`, `-m`, `--format json` |
 | `antigravity-cli` | `agy` | 1 | env-only | `-p`, `--continue`, `--model` |
 | `openclaw` | `openclaw` | 2 | `openclaw health` | `agent --local -m` |
+| `hermes` | `hermes` | 1 | `hermes doctor` | `chat -q`, `--continue`, `-m` |
+| `grok` | `grok` | 1 | env/file (`XAI_API_KEY` or `~/.grok/auth.json`) | `-p`, `-c` (resume), `-m`, `--output-format plain\|json` (maps ai-runner `text` → `plain`) |
+
 This is the right layer for UI previews, audit logging, and custom launchers.
 
 ## Deprecation & Aliases
@@ -453,15 +454,15 @@ resolveAgentName('cursor');          // → undefined
 **Current deprecation map:**
 
 | Id | Status | Canonical | Notes |
-|----|--------|-----------|-------|
+| ---- | -------- | ----------- | ------- |
 | `antigravity` | alias of `antigravity-cli` | `antigravity-cli` | Old tier-2 id; both use binary `agy`. Resolving warns. |
 | `gemini` | deprecated | `gemini` (self) → replaced by `antigravity-cli` | Gemini CLI sunset 2026-06-18. Shim stays functional. |
 | `omp` | canonical | `omp` | First-class; NOT a pi alias. |
 | `hermes` | canonical | `hermes` | First-class; OpenClaw-compatible but distinct binary. |
+| `grok` | canonical | `grok` | Grok Build CLI; headless via `-p`; auth is env/file only (no status verb). |
 
 `getAgentShim()` and `isAgentName()` are alias-aware: passing `'antigravity'` resolves to the `antigravity-cli` shim. `DoctorResult` and `DetectedAgent` surface `deprecated` + `replacedBy` when the resolved canonical id is marked deprecated.
 
-
 ## Team Mode Primitives
 
 The team-mode APIs are intentionally small building blocks. They do not implement an HTTP API, dashboard, or product workflow; downstream apps compose them into their own orchestration layer.
@@ -494,24 +495,38 @@ const specs = loadAgentSpecs('./agents');
 
 ### Durable messages
 
-`MessageService` wraps `InboxMessageDao` from `@gobing-ai/ts-db/inbox`. It owns no subprocess behavior; it only persists, drains, marks delivery/failure, and formats messages.
+`TeamOrchestrator` depends on the ai-runner-owned `MessageStore` port — a minimal interface with
+`enqueue`, `drainPending`, `markDelivered`, and `markFailed` — plus the `DrainedMessage` view
+containing only the fields the orchestrator consumes (`id`, `fromId`, `body`). The port is the
+orchestration boundary; production source under `packages/ai-runner/src` has no direct
+`@gobing-ai/ts-db` import for message access.
+
+`InboxMessageDao` from `@gobing-ai/ts-db/inbox` is one structural provider: it satisfies
+`MessageStore` without an adapter class, so no `ts-db` runtime changes are required. In-memory
+test doubles implement the port directly. Consumers compose `InboxMessageDao` +
+`EventBus<InboxMessageEvents>` and pass the DAO to `TeamOrchestrator`:
 
 ```ts
-import { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
-import { MessageService } from '@gobing-ai/ts-ai-runner';
+import { type BusLifecycleEvents, EventBus } from '@gobing-ai/ts-infra';
+import { InboxMessageDao, type InboxMessageEvents } from '@gobing-ai/ts-db/inbox';
+import { formatMessage, type MessageStore } from '@gobing-ai/ts-ai-runner';
 
-const messages = new MessageService(new InboxMessageDao(adapter));
+const lifecycleBus = new EventBus<BusLifecycleEvents>();
+const events = new EventBus<InboxMessageEvents>({ lifecycleBus });
+const inbox: MessageStore = new InboxMessageDao(adapter, { events });
 
-const id = await messages.enqueue(null, 'coder', 'Review the runtime process seam');
-const pending = await messages.drain('coder');
+const id = await inbox.enqueue(null, 'coder', 'Review the runtime process seam');
+const pending = await inbox.drainPending('coder');
 
 for (const msg of pending) {
-    console.log(MessageService.formatMessage(msg));
-    await messages.deliver(msg.id);
+    console.log(formatMessage(msg));
+    await inbox.markDelivered(msg.id);
 }
 ```
 
-`MessageService` also exposes `fail(msgId, error)`, `inbox(toId, limit?, offset?)`, and `countPending(toId)`.
+Message lifecycle events are metadata-only and do not include the durable message body. A
+`message.failed` event does include the caller-provided error string; pre-redact it when the
+lifecycle bus is attached to persistent System Events observers.
 
 ### Persistent agent processes
 
@@ -547,24 +562,27 @@ unsubscribe();
 
 ### Team orchestrator
 
-`TeamOrchestrator` connects specs, shims, processes, and messages. On start it loads an agent spec, builds the agent command through the matching shim, starts the process, drains pending inbox messages, and injects them live. `sendMessage()` always persists first, then injects immediately when the target agent is running.
+`TeamOrchestrator` connects specs, shims, processes, and the `MessageStore` port. On start it loads an agent spec, builds the agent command through the matching shim, starts the process, drains pending inbox messages, and injects them live. `sendMessage()` always persists first, then injects immediately when the target agent is running.
 
 ```ts
-import { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
-import { MessageService, TeamOrchestrator } from '@gobing-ai/ts-ai-runner';
+import { type BusLifecycleEvents, EventBus } from '@gobing-ai/ts-infra';
+import { InboxMessageDao, type InboxMessageEvents } from '@gobing-ai/ts-db/inbox';
+import { TeamOrchestrator, type MessageStore } from '@gobing-ai/ts-ai-runner';
 
-const messages = new MessageService(new InboxMessageDao(adapter));
-const team = new TeamOrchestrator('./agents', messages);
+const lifecycleBus = new EventBus<BusLifecycleEvents>();
+const events = new EventBus<InboxMessageEvents>({ lifecycleBus });
+const inbox: MessageStore = new InboxMessageDao(adapter, { events });
+const team = new TeamOrchestrator('./agents', inbox, { lifecycleBus });
 
 await team.startAgent('coder');
 await team.sendMessage(null, 'coder', 'Please implement task 0005');
 
-console.log(team.getAgentStatus('coder')); // running
+console.log(await team.getAgentStatus('coder')); // running
 
 await team.stopAll();
 ```
 
-The orchestrator also provides `restartAgent(id)`, `getRunningAgents()`, `getPeerSpecs(workspace, excludeId?)`, and `on(event, listener)` for event subscription.
+Any object implementing `MessageStore` can be supplied to `TeamOrchestrator`; `InboxMessageDao` is one structural provider, and in-memory test doubles implement the port directly without an adapter class. The orchestrator also provides `restartAgent(id)`, `getRunningAgents()`, `getPeerSpecs(workspace, excludeId?)`, and `on(event, listener)` for event subscription.
 
 ## Adding a New Coding Agent
 
@@ -631,7 +649,7 @@ If the agent supports an auth-status command, `getAuthCommand()` already returns
 ### Summary checklist
 
 | Step | File | What to change |
-|------|------|----------------|
+| ------ | ------ | ---------------- |
 | Shim | `src/agents/shims.ts` | Add `AgentShim` impl, update `AgentName`, `AGENT_SHIMS`, `DISPLAY_ORDER` |
 | Tier | `src/agents/shims.ts` | Add to `TIER1_PRIORITY` or `TIER2_AGENTS` |
 | Slash | `src/slash-command.ts` | Add case if dialect differs from default |
@@ -646,5 +664,5 @@ After these changes, the new agent is automatically available to `AiRunner`, `Ag
 - It does not install agent CLIs or manage credentials.
 - It does not parse agent responses beyond process result capture.
 - It keeps subprocess launching behind `ProcessExecutor` / `PipeProcess`, so tests can stay deterministic.
-- Team-mode persistence is delegated to `@gobing-ai/ts-db/inbox`; host apps own migrations and adapter lifecycle.
+- Team-mode persistence is consumed through the ai-runner-owned `MessageStore` port; `InboxMessageDao` from `@gobing-ai/ts-db/inbox` is one structural provider. Host apps own migrations and adapter lifecycle, and `@gobing-ai/ts-db` is a development dependency of this package (only the DB-backed integration test resolves the concrete DAO).
 - Platform APIs (`node:fs`, `node:path`, `Bun.spawn`, etc.) are confined to `@gobing-ai/ts-runtime` per ADR-011. This package accesses them through the runtime's `FileSystem`, `ProcessExecutor`, and path utilities.

package/dist/agents/auth-shims.d.ts

@@ -37,6 +37,8 @@ export interface AuthContext {
  * - **gemini** — credential-like content in `~/.gemini/settings.json`.
  * - **codex** — `codex login status` CLI output, falling back to an
  *   `~/.codex/auth{.json,}` credential file.
+ * - **grok** — non-empty `XAI_API_KEY` env, else non-empty `~/.grok/auth.json`;
+ *   no CLI auth-status verb (shim `getAuthCommand` is null).
  * - **pi / omp** — a non-empty `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` in env
  *   (an empty export is not a usable credential), else the CLI auth probe.
  * - **others** — the shim's auth command; matched against {@link AUTH_PATTERNS}.

package/dist/agents/auth-shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-shims.d.ts","sourceRoot":"","sources":["../../src/agents/auth-shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAmC,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAExE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IACxB,0CAA0C;IAC1C,MAAM,EAAE,QAAQ,CAAC;IACjB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,0EAA0E;IAC1E,UAAU,EAAE,UAAU,CAAC;IACvB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AA6CD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAgB5F;AA8CD,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"auth-shims.d.ts","sourceRoot":"","sources":["../../src/agents/auth-shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAmC,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAExE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IACxB,0CAA0C;IAC1C,MAAM,EAAE,QAAQ,CAAC;IACjB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,0EAA0E;IAC1E,UAAU,EAAE,UAAU,CAAC;IACvB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAiB5F;AA+DD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/agents/auth-shims.js

@@ -49,6 +49,8 @@ function isNonEmpty(value) {
  * - **gemini** — credential-like content in `~/.gemini/settings.json`.
  * - **codex** — `codex login status` CLI output, falling back to an
  *   `~/.codex/auth{.json,}` credential file.
+ * - **grok** — non-empty `XAI_API_KEY` env, else non-empty `~/.grok/auth.json`;
+ *   no CLI auth-status verb (shim `getAuthCommand` is null).
  * - **pi / omp** — a non-empty `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` in env
  *   (an empty export is not a usable credential), else the CLI auth probe.
  * - **others** — the shim's auth command; matched against {@link AUTH_PATTERNS}.
@@ -63,6 +65,8 @@ export async function isAuthenticated(agent, ctx) {
         return geminiSettingsContainCredentials(fs, home);
     if (agent === 'codex')
         return checkCodexAuth(ctx.runner, fs, home, timeout);
+    if (agent === 'grok')
+        return checkGrokAuth(fs, home, env);
     // pi and omp read provider keys from the environment; require a non-empty
     // value rather than mere presence (an empty export is not a usable credential).
     if ((agent === 'pi' || agent === 'omp') && (isNonEmpty(env.GOOGLE_API_KEY) || isNonEmpty(env.ANTHROPIC_API_KEY))) {
@@ -78,6 +82,20 @@ async function checkCodexAuth(runner, fs, home, timeout) {
         (await hasNonEmptyFile(fs, joinPath(home, '.codex', 'auth')));
     return hasFile ? 'authenticated' : 'unknown';
 }
+/**
+ * Grok has no auth-status CLI verb. Credential sources (never false-negative
+ * to `unauthenticated` when missing):
+ * 1. non-empty `XAI_API_KEY`
+ * 2. non-empty `~/.grok/auth.json`
+ * Else `unknown`.
+ */
+async function checkGrokAuth(fs, home, env) {
+    if (isNonEmpty(env.XAI_API_KEY))
+        return 'authenticated';
+    if (await hasNonEmptyFile(fs, joinPath(home, '.grok', 'auth.json')))
+        return 'authenticated';
+    return 'unknown';
+}
 async function geminiSettingsContainCredentials(fs, home) {
     try {
         const content = await fs.readFile(joinPath(home, '.gemini', 'settings.json'));

package/dist/agents/shims.d.ts

@@ -1,5 +1,5 @@
 /** Identifier for one supported coding agent (canonical id). */
-export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity-cli' | 'openclaw' | 'hermes' | 'omp';
+export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity-cli' | 'openclaw' | 'hermes' | 'omp' | 'grok';
 /** Output mode for prompt invocations. */
 export type OutputMode = 'text' | 'json';
 /** Concrete executable and argv pair returned by an agent shim. */

package/dist/agents/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACf,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,IAAI,GACJ,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,QAAQ,GACR,KAAK,CAAC;AAEZ,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,oCAAoC;IACpC,cAAc,IAAI,WAAW,CAAC;IAC9B,yCAAyC;IACzC,iBAAiB,IAAI,WAAW,CAAC;IACjC,yCAAyC;IACzC,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAAC;IACtD,8DAA8D;IAC9D,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;CACxC;AA+JD,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAU9D,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAQ9C,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAU7C,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,SAAS,CAAyB,CAAC;AAU1E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAQrE;AAED;mEACmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAMxD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACf,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,IAAI,GACJ,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,QAAQ,GACR,KAAK,GACL,MAAM,CAAC;AAEb,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,oCAAoC;IACpC,cAAc,IAAI,WAAW,CAAC;IAC9B,yCAAyC;IACzC,iBAAiB,IAAI,WAAW,CAAC;IACjC,yCAAyC;IACzC,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAAC;IACtD,8DAA8D;IAC9D,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;CACxC;AAuLD,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAW9D,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAS9C,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAW7C,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,SAAS,CAAyB,CAAC;AAU1E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAQrE;AAED;mEACmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAMxD"}

package/dist/agents/shims.js

@@ -166,6 +166,31 @@ const ompShim = {
     },
     getAuthCommand: () => ({ command: 'omp', args: ['--list-models'] }),
 };
+/**
+ * Grok Build CLI (`grok`) — xAI coding agent. Headless one-shot via `-p`/`--single`;
+ * continue with `-c`; model via `-m`. Output formats are `plain`/`json`/`streaming-json`
+ * (map ai-runner `text` → `plain`). No auth-status verb — `getAuthCommand` is null;
+ * credential probing lives in auth-shims (env / `~/.grok/auth.json`).
+ */
+const grokShim = {
+    name: 'grok',
+    command: 'grok',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'grok', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'grok', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true)
+            args.push('-c');
+        if (options.model !== undefined)
+            args.push('-m', options.model);
+        // Grok has no `text` format; map ai-runner OutputMode `text` → `plain`.
+        const format = (options.mode ?? 'text') === 'json' ? 'json' : 'plain';
+        args.push('--output-format', format);
+        return { command: 'grok', args };
+    },
+    getAuthCommand: () => null,
+};
 /** All bundled agent shims keyed by canonical agent name. */
 export const AGENT_SHIMS = {
     claude: claudeShim,
@@ -177,6 +202,7 @@ export const AGENT_SHIMS = {
     openclaw: openclawShim,
     hermes: hermesShim,
     omp: ompShim,
+    grok: grokShim,
 };
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
 export const TIER1_PRIORITY = [
@@ -187,6 +213,7 @@ export const TIER1_PRIORITY = [
     'claude',
     'hermes',
     'opencode',
+    'grok',
 ];
 /** Display order for doctor and list commands. */
 export const DISPLAY_ORDER = [
@@ -199,6 +226,7 @@ export const DISPLAY_ORDER = [
     'antigravity-cli',
     'openclaw',
     'hermes',
+    'grok',
 ];
 /** Set of gateway/TUI-constrained agents. */
 export const TIER2_AGENTS = new Set(['openclaw']);

package/dist/ai-runner.d.ts

@@ -1,4 +1,4 @@
-import { type EventBus, type Logger } from '@gobing-ai/ts-infra';
+import { type BusLifecycleEvents, EventBus, type Logger } from '@gobing-ai/ts-infra';
 import { type ProcessExecutor, type TracerPort } from '@gobing-ai/ts-runtime';
 import { type AgentName, type PromptOptions, type ShimCommand } from './agents/shims';
 import type { AgentEvents, AiRunnerProcessEvents } from './events';
@@ -38,6 +38,12 @@ export interface AiRunnerOptions {
     processEvents?: EventBus<AiRunnerProcessEvents>;
     /** Event bus receiving agent-level invocation observability. */
     events?: EventBus<AgentEvents>;
+    /**
+     * Optional lifecycle bus to bridge `agent.*` and `process.*` events into
+     * the application System Events stream (R4). When `events` / `processEvents`
+     * are omitted the runner constructs internal buses parented to this bus.
+     */
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
     /** Tracer adapter for the default executor. Defaults to `ts-infra` traceAsync. */
     tracer?: TracerPort;
 }
@@ -48,6 +54,8 @@ export declare class AiRunner {
     private readonly defaultTimeout;
     private readonly logger;
     private readonly events;
+    /** Internal process-level observability bus, parented to `lifecycleBus` when auto-constructed. Exposed for introspection/testing. */
+    readonly processEvents: EventBus<AiRunnerProcessEvents> | undefined;
     constructor(options?: AiRunnerOptions);
     /** Run an agent help command. */
     runHelpCommand(agent: AgentName, options?: AgentRunOptions): Promise<AgentRunResult>;

package/dist/ai-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"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"}

package/dist/ai-runner.js

@@ -1,5 +1,5 @@
-import { getLogger, traceAsync } from '@gobing-ai/ts-infra';
-import { getProcessCwd, NodeProcessExecutor, } from '@gobing-ai/ts-runtime';
+import { EventBus, getLogger, traceAsync } from '@gobing-ai/ts-infra';
+import { getProcessCwd, nodeBunFactory, } from '@gobing-ai/ts-runtime';
 import { getAgentShim } from './agents/shims.js';
 import { buildIdentityPreamble } from './identity.js';
 import { translateSlashCommand } from './slash-command.js';
@@ -10,15 +10,23 @@ export class AiRunner {
     defaultTimeout;
     logger;
     events;
+    /** Internal process-level observability bus, parented to `lifecycleBus` when auto-constructed. Exposed for introspection/testing. */
+    processEvents;
     constructor(options = {}) {
+        const processEvents = options.processEvents ??
+            (options.lifecycleBus
+                ? new EventBus({ lifecycleBus: options.lifecycleBus })
+                : undefined);
+        const events = options.events ??
+            (options.lifecycleBus ? new EventBus({ lifecycleBus: options.lifecycleBus }) : undefined);
         this.processExecutor =
             options.processExecutor ??
-                new NodeProcessExecutor({
-                    ...(options.processEvents !== undefined
+                nodeBunFactory.createProcessExecutor({
+                    ...(processEvents !== undefined
                         ? {
                             events: {
                                 emit: (event, detail) => {
-                                    void options.processEvents?.emit(event, detail);
+                                    void processEvents?.emit(event, detail);
                                 },
                             },
                         }
@@ -30,7 +38,8 @@ export class AiRunner {
         this.defaultCwd = options.defaultCwd;
         this.defaultTimeout = options.defaultTimeout;
         this.logger = options.logger ?? getLogger('ai-runner');
-        this.events = options.events;
+        this.events = events;
+        this.processEvents = processEvents;
     }
     /** Run an agent help command. */
     runHelpCommand(agent, options = {}) {

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './ai-runner';
 export * from './doctor-runner';
 export * from './events';
 export * from './identity';
+export * from './message-store';
 export * from './messages';
 export * from './model-health-probe';
 export * from './slash-command';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './ai-runner.js';
 export * from './doctor-runner.js';
 export * from './events.js';
 export * from './identity.js';
+export * from './message-store.js';
 export * from './messages.js';
 export * from './model-health-probe.js';
 export * from './slash-command.js';

package/dist/message-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ai-runner-owned orchestration persistence boundary (ADR-023 follow-up A4).
+ *
+ * `TeamOrchestrator` depends only on this port. `InboxMessageDao` from
+ * `@gobing-ai/ts-db/inbox` satisfies it structurally — no adapter class — and
+ * in-memory test doubles implement it directly.
+ */
+/**
+ * Minimal read-only view of a drained message containing only the fields
+ * `ts-ai-runner` consumes. It deliberately does not mirror the full
+ * `InboxMessage` persistence model.
+ */
+export interface DrainedMessage {
+    readonly id: string;
+    readonly fromId: string | null;
+    readonly body: string;
+}
+/**
+ * Message store operations consumed by `TeamOrchestrator`. Mirrors the subset
+ * of `InboxMessageDao` operations the orchestrator uses: enqueue a message,
+ * drain pending messages for a recipient, mark a message delivered, and mark
+ * a message failed.
+ */
+export interface MessageStore {
+    enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string>;
+    drainPending(toId: string): Promise<DrainedMessage[]>;
+    markDelivered(msgId: string): Promise<void>;
+    markFailed(msgId: string, error: string): Promise<void>;
+}
+//# sourceMappingURL=message-store.d.ts.map

package/dist/message-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-store.d.ts","sourceRoot":"","sources":["../src/message-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACtD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D"}

package/dist/message-store.js

@@ -0,0 +1,7 @@
+/**
+ * ai-runner-owned orchestration persistence boundary (ADR-023 follow-up A4).
+ *
+ * `TeamOrchestrator` depends only on this port. `InboxMessageDao` from
+ * `@gobing-ai/ts-db/inbox` satisfies it structurally — no adapter class — and
+ * in-memory test doubles implement it directly.
+ */

package/dist/messages.d.ts

@@ -1,4 +1,4 @@
-import type { InboxMessage } from '@gobing-ai/ts-db/inbox';
-/** Renders an inbox message into the line injected into an agent's stdin. */
-export declare function formatMessage(msg: InboxMessage): string;
+import type { DrainedMessage } from './message-store';
+/** Renders a drained message into the line injected into an agent's stdin. */
+export declare function formatMessage(msg: DrainedMessage): string;
 //# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAEzD"}

package/dist/messages.js

@@ -1,4 +1,4 @@
-/** Renders an inbox message into the line injected into an agent's stdin. */
+/** Renders a drained message into the line injected into an agent's stdin. */
 export function formatMessage(msg) {
     return `[task from=${msg.fromId ?? 'operator'} id=${msg.id}] ${msg.body}`;
 }

package/dist/team-agent-process.d.ts

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { type Logger } from '@gobing-ai/ts-infra';
-import { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { AgentSpec } from './agent-spec';
 /** Options for spawning a team agent subprocess. */
 export interface AgentProcessOptions {

package/dist/team-agent-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"team-agent-process.d.ts","sourceRoot":"","sources":["../src/team-agent-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAoB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;gBAErD,OAAO,EAAE,mBAAmB;IASlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAerD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,SAAS,IAAI,aAAa;IAI1B,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,MAAM,GAAG,IAAI;YAId,IAAI;IAiBlB,OAAO,CAAC,IAAI;CAOf"}
+{"version":3,"file":"team-agent-process.d.ts","sourceRoot":"","sources":["../src/team-agent-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;gBAErD,OAAO,EAAE,mBAAmB;IASlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAerD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,SAAS,IAAI,aAAa;IAI1B,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,MAAM,GAAG,IAAI;YAId,IAAI;IAiBlB,OAAO,CAAC,IAAI;CAOf"}

package/dist/team-agent-process.js

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { getLogger } from '@gobing-ai/ts-infra';
-import { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { nodeBunFactory } from '@gobing-ai/ts-runtime';
 /**
  * Manages the lifecycle of a single agent subprocess — start, stop, message send, and stdout/stderr subscription.
  * The identity preamble is built by `TeamOrchestrator` and baked into `command` before the process is constructed.
@@ -21,7 +21,7 @@ export class TeamAgentProcess {
         this.command = options.command;
         this.env = options.env;
         this.cwd = options.cwd ?? options.spec.workspace;
-        this.processExecutor = options.processExecutor ?? new ProcessExecutor();
+        this.processExecutor = options.processExecutor ?? nodeBunFactory.createProcessExecutor();
         this.logger = options.logger ?? getLogger('team-agent');
     }
     async start() {

package/dist/team-orchestrator.d.ts

@@ -1,13 +1,19 @@
-import type { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
-import { EventBus } from '@gobing-ai/ts-infra';
+import { type BusLifecycleEvents, EventBus } from '@gobing-ai/ts-infra';
 import type { AgentSpec } from './agent-spec';
 import type { AgentEvents } from './events';
+import type { MessageStore } from './message-store';
 import { TeamAgentProcess } from './team-agent-process';
 type AgentProcessFactory = (options: ConstructorParameters<typeof TeamAgentProcess>[0]) => TeamAgentProcess;
 /** Configuration options for `TeamOrchestrator`. */
 export interface TeamOrchestratorOptions {
     processFactory?: AgentProcessFactory;
     events?: EventBus<AgentEvents>;
+    /**
+     * Optional lifecycle bus to bridge `agent.*` events into the application
+     * System Events stream (R4). When `events` is omitted the orchestrator
+     * constructs an internal `EventBus<AgentEvents>` parented to this bus.
+     */
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
 }
 /**
  * Orchestrates a team of AI agents — loads specs, starts/stops agent processes, routes messages between them,
@@ -20,7 +26,7 @@ export declare class TeamOrchestrator {
     private readonly running;
     private readonly processFactory;
     private readonly events;
-    constructor(configDir: string, inbox: InboxMessageDao, options?: TeamOrchestratorOptions);
+    constructor(configDir: string, inbox: MessageStore, options?: TeamOrchestratorOptions);
     loadSpecs(): Promise<AgentSpec[]>;
     getSpec(id: string): Promise<AgentSpec | undefined>;
     startAgent(id: string): Promise<TeamAgentProcess>;

package/dist/team-orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"team-orchestrator.d.ts","sourceRoot":"","sources":["../src/team-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC;AAE5G,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACpC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAOrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAP1B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAG1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,EACvC,OAAO,GAAE,uBAA4B;IAMnC,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAKjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKnD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAiCjD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKnD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzG,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAI3C,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAMlF,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAKzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;YAKjE,WAAW;IAMzB,OAAO,CAAC,gBAAgB;YAMV,qBAAqB;YAIrB,UAAU;CAa3B"}
+{"version":3,"file":"team-orchestrator.d.ts","sourceRoot":"","sources":["../src/team-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC;AAE5G,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACpC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAOrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAP1B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAG1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,EACpC,OAAO,GAAE,uBAA4B;IAUnC,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAKjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKnD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAiCjD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKnD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzG,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAI3C,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAMlF,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAKzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;YAKjE,WAAW;IAMzB,OAAO,CAAC,gBAAgB;YAMV,qBAAqB;YAIrB,UAAU;CAa3B"}

package/dist/team-orchestrator.js

@@ -19,7 +19,11 @@ export class TeamOrchestrator {
         this.configDir = configDir;
         this.inbox = inbox;
         this.processFactory = options.processFactory ?? ((processOptions) => new TeamAgentProcess(processOptions));
-        this.events = options.events ?? new EventBus();
+        this.events =
+            options.events ??
+                (options.lifecycleBus
+                    ? new EventBus({ lifecycleBus: options.lifecycleBus })
+                    : new EventBus());
     }
     async loadSpecs() {
         this.specs = await loadAgentSpecs(this.configDir);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.4.7",
+    "version": "0.4.9",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,12 +47,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.4.7",
-        "@gobing-ai/ts-infra": "^0.4.7",
-        "@gobing-ai/ts-runtime": "^0.4.7"
+        "@gobing-ai/ts-infra": "^0.4.9",
+        "@gobing-ai/ts-runtime": "^0.4.9"
     },
     "devDependencies": {
-        "@types/bun": "1.3.14"
+        "@types/bun": "1.3.14",
+        "@gobing-ai/ts-db": "^0.4.9"
     },
     "publishConfig": {
         "access": "public"

package/src/agents/auth-shims.ts

@@ -83,6 +83,8 @@ function isNonEmpty(value: string | undefined): boolean {
  * - **gemini** — credential-like content in `~/.gemini/settings.json`.
  * - **codex** — `codex login status` CLI output, falling back to an
  *   `~/.codex/auth{.json,}` credential file.
+ * - **grok** — non-empty `XAI_API_KEY` env, else non-empty `~/.grok/auth.json`;
+ *   no CLI auth-status verb (shim `getAuthCommand` is null).
  * - **pi / omp** — a non-empty `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` in env
  *   (an empty export is not a usable credential), else the CLI auth probe.
  * - **others** — the shim's auth command; matched against {@link AUTH_PATTERNS}.
@@ -96,6 +98,7 @@ export async function isAuthenticated(agent: AgentName, ctx: AuthContext): Promi
 
     if (agent === 'gemini') return geminiSettingsContainCredentials(fs, home);
     if (agent === 'codex') return checkCodexAuth(ctx.runner, fs, home, timeout);
+    if (agent === 'grok') return checkGrokAuth(fs, home, env);
 
     // pi and omp read provider keys from the environment; require a non-empty
     // value rather than mere presence (an empty export is not a usable credential).
@@ -115,6 +118,23 @@ async function checkCodexAuth(runner: AiRunner, fs: FileSystem, home: string, ti
     return hasFile ? 'authenticated' : 'unknown';
 }
 
+/**
+ * Grok has no auth-status CLI verb. Credential sources (never false-negative
+ * to `unauthenticated` when missing):
+ * 1. non-empty `XAI_API_KEY`
+ * 2. non-empty `~/.grok/auth.json`
+ * Else `unknown`.
+ */
+async function checkGrokAuth(
+    fs: FileSystem,
+    home: string,
+    env: Record<string, string | undefined>,
+): Promise<AuthState> {
+    if (isNonEmpty(env.XAI_API_KEY)) return 'authenticated';
+    if (await hasNonEmptyFile(fs, joinPath(home, '.grok', 'auth.json'))) return 'authenticated';
+    return 'unknown';
+}
+
 async function geminiSettingsContainCredentials(fs: FileSystem, home: string): Promise<AuthState> {
     try {
         const content = await fs.readFile(joinPath(home, '.gemini', 'settings.json'));

package/src/agents/shims.ts

@@ -10,7 +10,8 @@ export type AgentName =
     | 'antigravity-cli'
     | 'openclaw'
     | 'hermes'
-    | 'omp';
+    | 'omp'
+    | 'grok';
 
 /** Output mode for prompt invocations. */
 export type OutputMode = 'text' | 'json';
@@ -232,6 +233,30 @@ const ompShim: AgentShim = {
     getAuthCommand: () => ({ command: 'omp', args: ['--list-models'] }),
 };
 
+/**
+ * Grok Build CLI (`grok`) — xAI coding agent. Headless one-shot via `-p`/`--single`;
+ * continue with `-c`; model via `-m`. Output formats are `plain`/`json`/`streaming-json`
+ * (map ai-runner `text` → `plain`). No auth-status verb — `getAuthCommand` is null;
+ * credential probing lives in auth-shims (env / `~/.grok/auth.json`).
+ */
+const grokShim: AgentShim = {
+    name: 'grok',
+    command: 'grok',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'grok', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'grok', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true) args.push('-c');
+        if (options.model !== undefined) args.push('-m', options.model);
+        // Grok has no `text` format; map ai-runner OutputMode `text` → `plain`.
+        const format = (options.mode ?? 'text') === 'json' ? 'json' : 'plain';
+        args.push('--output-format', format);
+        return { command: 'grok', args };
+    },
+    getAuthCommand: () => null,
+};
+
 /** All bundled agent shims keyed by canonical agent name. */
 export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
     claude: claudeShim,
@@ -243,6 +268,7 @@ export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
     openclaw: openclawShim,
     hermes: hermesShim,
     omp: ompShim,
+    grok: grokShim,
 };
 
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
@@ -254,6 +280,7 @@ export const TIER1_PRIORITY: readonly AgentName[] = [
     'claude',
     'hermes',
     'opencode',
+    'grok',
 ];
 
 /** Display order for doctor and list commands. */
@@ -267,6 +294,7 @@ export const DISPLAY_ORDER: readonly AgentName[] = [
     'antigravity-cli',
     'openclaw',
     'hermes',
+    'grok',
 ];
 
 /** Set of gateway/TUI-constrained agents. */

package/src/ai-runner.ts

@@ -1,7 +1,7 @@
-import { type EventBus, getLogger, type Logger, traceAsync } from '@gobing-ai/ts-infra';
+import { type BusLifecycleEvents, EventBus, getLogger, type Logger, traceAsync } from '@gobing-ai/ts-infra';
 import {
     getProcessCwd,
-    NodeProcessExecutor,
+    nodeBunFactory,
     type ProcessExecutor,
     type ProcessResult,
     type TracerPort,
@@ -49,6 +49,12 @@ export interface AiRunnerOptions {
     processEvents?: EventBus<AiRunnerProcessEvents>;
     /** Event bus receiving agent-level invocation observability. */
     events?: EventBus<AgentEvents>;
+    /**
+     * Optional lifecycle bus to bridge `agent.*` and `process.*` events into
+     * the application System Events stream (R4). When `events` / `processEvents`
+     * are omitted the runner constructs internal buses parented to this bus.
+     */
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
     /** Tracer adapter for the default executor. Defaults to `ts-infra` traceAsync. */
     tracer?: TracerPort;
 }
@@ -60,16 +66,26 @@ export class AiRunner {
     private readonly defaultTimeout: number | undefined;
     private readonly logger: Logger;
     private readonly events: EventBus<AgentEvents> | undefined;
+    /** Internal process-level observability bus, parented to `lifecycleBus` when auto-constructed. Exposed for introspection/testing. */
+    readonly processEvents: EventBus<AiRunnerProcessEvents> | undefined;
 
     constructor(options: AiRunnerOptions = {}) {
+        const processEvents =
+            options.processEvents ??
+            (options.lifecycleBus
+                ? new EventBus<AiRunnerProcessEvents>({ lifecycleBus: options.lifecycleBus })
+                : undefined);
+        const events =
+            options.events ??
+            (options.lifecycleBus ? new EventBus<AgentEvents>({ lifecycleBus: options.lifecycleBus }) : undefined);
         this.processExecutor =
             options.processExecutor ??
-            new NodeProcessExecutor({
-                ...(options.processEvents !== undefined
+            nodeBunFactory.createProcessExecutor({
+                ...(processEvents !== undefined
                     ? {
                           events: {
                               emit: (event, detail) => {
-                                  void options.processEvents?.emit(event, detail);
+                                  void processEvents?.emit(event, detail);
                               },
                           },
                       }
@@ -81,7 +97,8 @@ export class AiRunner {
         this.defaultCwd = options.defaultCwd;
         this.defaultTimeout = options.defaultTimeout;
         this.logger = options.logger ?? getLogger('ai-runner');
-        this.events = options.events;
+        this.events = events;
+        this.processEvents = processEvents;
     }
 
     /** Run an agent help command. */

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './ai-runner';
 export * from './doctor-runner';
 export * from './events';
 export * from './identity';
+export * from './message-store';
 export * from './messages';
 export * from './model-health-probe';
 export * from './slash-command';

package/src/message-store.ts

@@ -0,0 +1,31 @@
+/**
+ * ai-runner-owned orchestration persistence boundary (ADR-023 follow-up A4).
+ *
+ * `TeamOrchestrator` depends only on this port. `InboxMessageDao` from
+ * `@gobing-ai/ts-db/inbox` satisfies it structurally — no adapter class — and
+ * in-memory test doubles implement it directly.
+ */
+
+/**
+ * Minimal read-only view of a drained message containing only the fields
+ * `ts-ai-runner` consumes. It deliberately does not mirror the full
+ * `InboxMessage` persistence model.
+ */
+export interface DrainedMessage {
+    readonly id: string;
+    readonly fromId: string | null;
+    readonly body: string;
+}
+
+/**
+ * Message store operations consumed by `TeamOrchestrator`. Mirrors the subset
+ * of `InboxMessageDao` operations the orchestrator uses: enqueue a message,
+ * drain pending messages for a recipient, mark a message delivered, and mark
+ * a message failed.
+ */
+export interface MessageStore {
+    enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string>;
+    drainPending(toId: string): Promise<DrainedMessage[]>;
+    markDelivered(msgId: string): Promise<void>;
+    markFailed(msgId: string, error: string): Promise<void>;
+}

package/src/messages.ts

@@ -1,6 +1,6 @@
-import type { InboxMessage } from '@gobing-ai/ts-db/inbox';
+import type { DrainedMessage } from './message-store';
 
-/** Renders an inbox message into the line injected into an agent's stdin. */
-export function formatMessage(msg: InboxMessage): string {
+/** Renders a drained message into the line injected into an agent's stdin. */
+export function formatMessage(msg: DrainedMessage): string {
     return `[task from=${msg.fromId ?? 'operator'} id=${msg.id}] ${msg.body}`;
 }

package/src/team-agent-process.ts

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { getLogger, type Logger } from '@gobing-ai/ts-infra';
-import { type PipeProcess, ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { nodeBunFactory, type PipeProcess, type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { AgentSpec } from './agent-spec';
 
 /** Options for spawning a team agent subprocess. */
@@ -36,7 +36,7 @@ export class TeamAgentProcess {
         this.command = options.command;
         this.env = options.env;
         this.cwd = options.cwd ?? options.spec.workspace;
-        this.processExecutor = options.processExecutor ?? new ProcessExecutor();
+        this.processExecutor = options.processExecutor ?? nodeBunFactory.createProcessExecutor();
         this.logger = options.logger ?? getLogger('team-agent');
     }
 

package/src/team-orchestrator.ts

@@ -1,10 +1,10 @@
-import type { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
-import { EventBus } from '@gobing-ai/ts-infra';
+import { type BusLifecycleEvents, EventBus } from '@gobing-ai/ts-infra';
 import type { AgentSpec } from './agent-spec';
 import { loadAgentSpecs } from './agent-spec';
 import { type AgentName, resolveAgentName } from './agents/shims';
 import { buildAgentCommand } from './ai-runner';
 import type { AgentEvents } from './events';
+import type { MessageStore } from './message-store';
 import { formatMessage } from './messages';
 import { TeamAgentProcess } from './team-agent-process';
 
@@ -14,6 +14,12 @@ type AgentProcessFactory = (options: ConstructorParameters<typeof TeamAgentProce
 export interface TeamOrchestratorOptions {
     processFactory?: AgentProcessFactory;
     events?: EventBus<AgentEvents>;
+    /**
+     * Optional lifecycle bus to bridge `agent.*` events into the application
+     * System Events stream (R4). When `events` is omitted the orchestrator
+     * constructs an internal `EventBus<AgentEvents>` parented to this bus.
+     */
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
 }
 
 /**
@@ -28,11 +34,15 @@ export class TeamOrchestrator {
 
     constructor(
         private readonly configDir: string,
-        private readonly inbox: InboxMessageDao,
+        private readonly inbox: MessageStore,
         options: TeamOrchestratorOptions = {},
     ) {
         this.processFactory = options.processFactory ?? ((processOptions) => new TeamAgentProcess(processOptions));
-        this.events = options.events ?? new EventBus<AgentEvents>();
+        this.events =
+            options.events ??
+            (options.lifecycleBus
+                ? new EventBus<AgentEvents>({ lifecycleBus: options.lifecycleBus })
+                : new EventBus<AgentEvents>());
     }
 
     async loadSpecs(): Promise<AgentSpec[]> {