claude-tempo 0.22.1 → 0.23.0

package/CLAUDE.md

@@ -27,6 +27,9 @@ src/
 │   ├── output.ts      # Shared CLI output formatting helpers
 │   └── preflight.ts   # Environment preflight checks
 ├── copilot-bridge.ts  # Copilot SDK bridge for Copilot CLI players
+├── client/
+│   ├── interface.ts   # TempoClient TypeScript interface and related types
+│   └── index.ts       # TempoClient factory implementation and barrel re-exports
 ├── worker.ts          # Temporal worker setup (used by daemon only)
 ├── connection.ts      # Temporal connection factory (shared by server + CLI)
 ├── spawn.ts           # Cross-platform process spawning helpers
@@ -80,7 +83,7 @@ src/
 │   ├── index.ts       # TUI entry point — connects to Temporal and renders the Ink app
 │   ├── App.tsx        # Root TUI component — chat-focused shell with slash commands
 │   ├── store.ts       # TUI state reducer (phase, players, messages, schedules, static history)
-│   ├── client.ts      # TempoClient interface and implementation — wraps Temporal queries via Maestro
+│   ├── client.ts      # Thin re-export shim — re-exports createTempoClient from src/client/ for backward compatibility
 │   ├── commands.ts    # Slash command parser and registry (/player, /broadcast, /status, etc.)
 │   ├── ink-loader.ts  # Dynamic ESM loader for Ink (avoids CJS/ESM conflicts)
 │   ├── ink-context.tsx # React context for injected Ink primitives
@@ -171,7 +174,7 @@ npm test
 - **Worktree**: A git worktree provisioned by the conductor for a player, giving them an isolated checkout on a separate branch. Managed via the `worktree` tool (conductor only): `create` provisions the worktree and notifies the player, `remove` cleans up after the task, `list` shows all active worktrees. Worktree assignments are stored in the conductor workflow (`WorktreeEntry` records: player, path, branch, gitRoot, createdAt, createdBy).
 - **Stage**: A fan-out/fan-in tracking primitive for the conductor. Created via `stage` (conductor only), listing via `stages`, cancelled via `cancel_stage`. Each stage tracks a set of players; when a tracked player sends a `report`, their stage status updates automatically (`waiting` → `reported` or `blocked`). When all players have reported, the conductor is notified that the stage is complete. If `failurePolicy` is `'halt'` (default), a blocker from any player fails the entire stage. Stages are stored in the conductor workflow and survive `continueAsNew`.
 - **Maestro**: Two Maestro workflow variants exist. The **per-ensemble** `claudeMaestroWorkflow` (ID: `claude-maestro-{ensemble}`) monitors a single ensemble — maintains a player snapshot, ring-buffer event log (max 200 entries), an aggregated ensemble chat cache (max 500 entries, refreshed every ~10s via `fetchEnsembleChat` activity), and queues commands for relay to the conductor via `maestroSendCommand`. The ensemble chat cache merges maestro + conductor traffic and is served via the `maestroEnsembleChat` query. The **global** `claudeGlobalMaestroWorkflow` (ID: `claude-maestro-global`) spans all ensembles — aggregates players by ensemble, maintains a cross-ensemble message ring buffer (max 500 entries), and exposes on-demand player/conductor history via `maestroFetchPlayerMessages` and `maestroFetchConductorHistory` updates. Both are implemented in `src/workflows/maestro.ts` with activities in `src/activities/maestro.ts`.
-- **TempoClient**: The TUI's API layer (`src/tui/client.ts`) — a TypeScript interface and implementation that wraps Temporal queries to the Maestro and conductor workflows. Provides `discoverEnsembles`, `getPlayers`, `getMessages`, `getConductorHistory`, `sendMessage`, `sendCommand`, `getEnsembleChat`, `getGates`, `getStages`, `getWorktrees`, and `terminatePlayer`. Uses Global Maestro as the primary source with graceful fallback to per-ensemble Maestro and direct workflow list queries.
+- **TempoClient**: The API layer for querying ensemble state (`src/client/`). The interface and types live in `interface.ts`; the factory implementation lives in `index.ts`. Provides `discoverEnsembles`, `getPlayers`, `getMessages`, `getConductorHistory`, `sendMessage`, `sendCommand`, `getEnsembleChat`, `getGates`, `getStages`, `getWorktrees`, and `terminatePlayer`. Uses Global Maestro as the primary source with graceful fallback to per-ensemble Maestro and direct workflow list queries. `src/tui/client.ts` is a thin re-export shim for backward compatibility — new consumers should import from `src/client/` directly.
 - **Wire protocol**: All Temporal signal, query, update, and workflow names are documented in [`docs/WIRE-PROTOCOL.md`](docs/WIRE-PROTOCOL.md). These names are stable as of v0.10 — renaming or removing any is a breaking change requiring a major version bump.
 - **Daemon**: A standalone background process (`src/daemon.ts`) that runs all Temporal workers. Auto-started by any claude-tempo command if not already running. PID stored at `~/.claude-tempo/daemon.pid`; logs at `~/.claude-tempo/daemon.log`. Sessions are now pure MCP clients — they no longer run in-process workers. Managed via `claude-tempo daemon start|stop|status|logs`.
 

package/README.md

@@ -86,6 +86,21 @@ Stops the daemon, installs the latest version, and restarts automatically. To up
 claude-tempo upgrade 0.22.0
 ```
 
+## Stopping & Tear Down
+
+```bash
+# Stop a specific player session
+claude-tempo stop my-ensemble player-name
+
+# Tear down everything (all sessions, schedulers, and Maestro workflows)
+claude-tempo down --all
+
+# Stop the background daemon
+claude-tempo daemon stop
+```
+
+📖 [Full CLI reference → docs/cli.md](docs/cli.md)
+
 ---
 
 ## Core Concepts

package/dist/cli/commands.js

@@ -437,6 +437,7 @@ const SEARCH_ATTRIBUTES = [
     { name: 'ClaudeTempoPlayerId', type: 'Keyword' },
     { name: 'ClaudeTempoStatus', type: 'Keyword' },
     { name: 'ClaudeTempoPlayerType', type: 'Keyword' },
+    { name: 'ClaudeTempoIsConductor', type: 'Bool' },
 ];
 async function isTemporalReachable(config) {
     try {

package/dist/client/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TempoClient — factory implementation and barrel re-exports.
+ *
+ * Extracted from `src/tui/client.ts` so that non-TUI consumers (CLI, tests,
+ * external integrations) can create a TempoClient without depending on Ink/React.
+ */
+import { Client } from '@temporalio/client';
+import type { TempoClient } from './interface';
+export type { TempoClient, EnsembleSummary } from './interface';
+export declare function createTempoClient(client: Client): TempoClient;

package/dist/client/index.js

@@ -0,0 +1,482 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTempoClient = createTempoClient;
+/**
+ * TempoClient — factory implementation and barrel re-exports.
+ *
+ * Extracted from `src/tui/client.ts` so that non-TUI consumers (CLI, tests,
+ * external integrations) can create a TempoClient without depending on Ink/React.
+ */
+const client_1 = require("@temporalio/client");
+const config_1 = require("../config");
+const signals_1 = require("../workflows/signals");
+// ── Helpers ──
+/** Escape a value for use in Temporal visibility query strings.
+ *  Strips characters that could break or inject into the query. */
+function sanitizeQueryValue(value) {
+    return value.replace(/["\\\n\r]/g, '');
+}
+// ── Factory ──
+function createTempoClient(client) {
+    const globalMaestroId = config_1.GLOBAL_MAESTRO_WORKFLOW_ID;
+    /** Helper: get a workflow handle by ID. */
+    function handle(workflowId) {
+        return client.workflow.getHandle(workflowId);
+    }
+    return {
+        async discoverEnsembles() {
+            // Strategy 1: Global Maestro playersByEnsemble query
+            try {
+                const h = handle(globalMaestroId);
+                const byEnsemble = await h.query('maestroPlayersByEnsemble');
+                const results = Object.entries(byEnsemble).map(([name, players]) => {
+                    const conductor = players.find(p => p.isConductor);
+                    return {
+                        name,
+                        playerCount: players.length,
+                        hasConductor: !!conductor,
+                        conductorStatus: conductor?.status,
+                    };
+                });
+                // Only trust Maestro if it has discovered ensembles; fall through to
+                // Strategy 2 when empty — the Maestro may not have refreshed yet.
+                if (results.length > 0)
+                    return results;
+            }
+            catch {
+                // Global Maestro not available — fall through
+            }
+            // Strategy 2: Direct workflow list scan
+            try {
+                const query = 'WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"';
+                const ensembleMap = new Map();
+                for await (const wf of client.workflow.list({ query })) {
+                    const vals = wf.searchAttributes?.ClaudeTempoEnsemble;
+                    if (!Array.isArray(vals) || vals.length === 0)
+                        continue;
+                    const name = String(vals[0]);
+                    const entry = ensembleMap.get(name) || { count: 0, hasConductor: false };
+                    entry.count++;
+                    // Preferred: ClaudeTempoIsConductor search attribute (canonical, queryable).
+                    // Fallback: workflow ID convention — covers the brief window after a
+                    // conductor spawn before the search attribute is indexed.
+                    const saFlag = wf.searchAttributes?.ClaudeTempoIsConductor;
+                    const isConductorFromSA = Array.isArray(saFlag) && saFlag[0] === true;
+                    const isConductorFromId = wf.workflowId?.endsWith('-conductor') ?? false;
+                    if (isConductorFromSA || isConductorFromId) {
+                        entry.hasConductor = true;
+                        const statusArr = wf.searchAttributes?.ClaudeTempoStatus;
+                        entry.conductorStatus = Array.isArray(statusArr) ? String(statusArr[0]) : undefined;
+                    }
+                    ensembleMap.set(name, entry);
+                }
+                return [...ensembleMap.entries()].map(([name, info]) => ({
+                    name,
+                    playerCount: info.count,
+                    hasConductor: info.hasConductor,
+                    conductorStatus: info.conductorStatus,
+                }));
+            }
+            catch {
+                return [];
+            }
+        },
+        async getPlayers(ensemble) {
+            // Strategy 1: Global Maestro — filter by ensemble
+            try {
+                const h = handle(globalMaestroId);
+                const byEnsemble = await h.query('maestroPlayersByEnsemble');
+                if (byEnsemble[ensemble])
+                    return byEnsemble[ensemble];
+            }
+            catch {
+                // Fall through
+            }
+            // Strategy 2: Per-ensemble Maestro
+            try {
+                const h = handle((0, config_1.maestroWorkflowId)(ensemble));
+                return await h.query('maestroPlayers');
+            }
+            catch {
+                // Fall through
+            }
+            // Strategy 3: Direct workflow list
+            try {
+                const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitizeQueryValue(ensemble)}"`;
+                const players = [];
+                for await (const wf of client.workflow.list({ query })) {
+                    const sa = wf.searchAttributes || {};
+                    const playerId = Array.isArray(sa.ClaudeTempoPlayerId) ? String(sa.ClaudeTempoPlayerId[0]) : wf.workflowId;
+                    // Preferred: ClaudeTempoIsConductor search attribute (canonical, queryable).
+                    // Fallback: workflow ID convention — covers the brief window after a
+                    // conductor spawn before the search attribute is indexed.
+                    const isConductorFromSA = Array.isArray(sa.ClaudeTempoIsConductor) && sa.ClaudeTempoIsConductor[0] === true;
+                    const isConductorFromId = wf.workflowId?.endsWith('-conductor') ?? false;
+                    players.push({
+                        playerId,
+                        ensemble,
+                        part: '',
+                        hostname: Array.isArray(sa.ClaudeTempoHostname) ? String(sa.ClaudeTempoHostname[0]) : '',
+                        workDir: '',
+                        isConductor: isConductorFromSA || isConductorFromId,
+                        agentType: 'claude',
+                        status: Array.isArray(sa.ClaudeTempoStatus) ? String(sa.ClaudeTempoStatus[0]) : undefined,
+                    });
+                }
+                return players;
+            }
+            catch {
+                return [];
+            }
+        },
+        async getMessages(ensemble, limit) {
+            try {
+                const h = handle(globalMaestroId);
+                const all = await h.query('maestroRecentMessages');
+                const filtered = all.filter(m => m.ensemble === ensemble);
+                return limit ? filtered.slice(-limit) : filtered;
+            }
+            catch {
+                return [];
+            }
+        },
+        async getConductorHistory(ensemble) {
+            try {
+                const h = handle(globalMaestroId);
+                const result = await h.executeUpdate('maestroFetchConductorHistory', {
+                    args: [{ ensemble }],
+                });
+                if (result.success)
+                    return result.history;
+                return [];
+            }
+            catch {
+                return [];
+            }
+        },
+        async getPlayerMessages(ensemble, playerId) {
+            try {
+                const h = handle(globalMaestroId);
+                return await h.executeUpdate('maestroFetchPlayerMessages', {
+                    args: [{ ensemble, playerId }],
+                });
+            }
+            catch {
+                return [];
+            }
+        },
+        async getPlayerMetadata(ensemble, playerId) {
+            try {
+                // Query the player's workflow directly for metadata
+                const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitizeQueryValue(ensemble)}" AND ClaudeTempoPlayerId = "${sanitizeQueryValue(playerId)}"`;
+                for await (const wf of client.workflow.list({ query })) {
+                    const h = handle(wf.workflowId);
+                    return await h.query('getMetadata');
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async sendCommand(ensemble, text, source) {
+            // Route commands through Maestro hub → conductor's commandSignal
+            let result;
+            try {
+                const h = handle(globalMaestroId);
+                result = await h.executeUpdate('maestroGlobalSendCommand', {
+                    args: [{ ensemble, text, source }],
+                });
+            }
+            catch {
+                const h = handle((0, config_1.maestroWorkflowId)(ensemble));
+                result = await h.executeUpdate('maestroSendCommand', {
+                    args: [{ text, source }],
+                });
+            }
+            // Record on maestro workflow for history persistence
+            try {
+                const maestroId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');
+                const mh = handle(maestroId);
+                await mh.signal('recordSentMessage', { to: 'conductor', text });
+            }
+            catch { /* best effort */ }
+            return result;
+        },
+        async sendMessage(ensemble, to, text, source) {
+            // Direct signal with isMaestro flag — matches web Maestro pattern
+            const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitizeQueryValue(ensemble)}" AND ClaudeTempoPlayerId = "${sanitizeQueryValue(to)}"`;
+            let sent = false;
+            for await (const wf of client.workflow.list({ query })) {
+                const h = handle(wf.workflowId);
+                await h.signal('receiveMessage', {
+                    from: source,
+                    text,
+                    isMaestro: true,
+                });
+                sent = true;
+                break;
+            }
+            if (!sent) {
+                // Fallback: try via Maestro hub if direct resolution fails
+                try {
+                    const h = handle(globalMaestroId);
+                    await h.executeUpdate('maestroSendMessage', {
+                        args: [{ ensemble, to, text, source }],
+                    });
+                }
+                catch {
+                    throw new Error(`Player "${to}" not found in ensemble "${ensemble}"`);
+                }
+            }
+            // Record on maestro workflow for history persistence
+            try {
+                const maestroId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');
+                const mh = handle(maestroId);
+                await mh.signal('recordSentMessage', { to, text });
+            }
+            catch { /* best effort */ }
+            return `maestro-msg-${Date.now()}`;
+        },
+        async terminatePlayer(ensemble, playerId) {
+            const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitizeQueryValue(ensemble)}" AND ClaudeTempoPlayerId = "${sanitizeQueryValue(playerId)}"`;
+            for await (const wf of client.workflow.list({ query })) {
+                const h = handle(wf.workflowId);
+                await h.terminate('terminated via TUI');
+                return;
+            }
+            throw new Error(`Player "${playerId}" not found in ensemble "${ensemble}"`);
+        },
+        async encorePlayer(ensemble, playerId) {
+            // Submit an encore outbox entry through the TUI's maestro session workflow.
+            // This works without a conductor — the maestro session's outbox dispatches the encore activity directly.
+            const maestroId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');
+            const h = handle(maestroId);
+            const entry = {
+                type: 'encore',
+                targetPlayerId: playerId,
+            };
+            await h.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+        },
+        async disbandEnsemble(ensemble) {
+            let terminated = 0;
+            // Terminate all session workflows in the ensemble
+            const sessionQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitizeQueryValue(ensemble)}"`;
+            for await (const wf of client.workflow.list({ query: sessionQuery })) {
+                try {
+                    const h = handle(wf.workflowId);
+                    await h.terminate('disbanded via TUI');
+                    terminated++;
+                }
+                catch { /* already closed */ }
+            }
+            // Terminate scheduler workflow
+            try {
+                const h = handle((0, config_1.schedulerWorkflowId)(ensemble));
+                await h.terminate('disbanded via TUI');
+                terminated++;
+            }
+            catch { /* no scheduler or already closed */ }
+            // Terminate per-ensemble maestro workflow
+            try {
+                const h = handle((0, config_1.maestroWorkflowId)(ensemble));
+                await h.terminate('disbanded via TUI');
+                terminated++;
+            }
+            catch { /* no maestro or already closed */ }
+            return { terminated };
+        },
+        async isConnected() {
+            try {
+                // Lightweight check: list with limit 1
+                const query = 'ExecutionStatus = "Running"';
+                for await (const _ of client.workflow.list({ query })) {
+                    return true;
+                }
+                return true; // Connected but no workflows
+            }
+            catch {
+                return false;
+            }
+        },
+        async getSchedules(ensemble) {
+            try {
+                const h = handle((0, config_1.schedulerWorkflowId)(ensemble));
+                return await h.query('getSchedules');
+            }
+            catch {
+                return [];
+            }
+        },
+        async cancelSchedule(ensemble, name) {
+            const h = handle((0, config_1.schedulerWorkflowId)(ensemble));
+            await h.signal('removeSchedule', name);
+        },
+        async getEnsembleChat(ensemble, offset, limit) {
+            try {
+                const h = handle((0, config_1.maestroWorkflowId)(ensemble));
+                return await h.query('maestroEnsembleChat', { offset, limit });
+            }
+            catch {
+                return { messages: [], total: 0, hasMore: false, hasConductor: false };
+            }
+        },
+        async getGates(ensemble) {
+            // Gates are stored on the conductor's workflow
+            try {
+                const h = handle((0, config_1.conductorWorkflowId)(ensemble));
+                return await h.query('qualityGates');
+            }
+            catch {
+                return [];
+            }
+        },
+        async getStages(ensemble) {
+            try {
+                const h = handle((0, config_1.conductorWorkflowId)(ensemble));
+                return await h.query('stages');
+            }
+            catch {
+                return [];
+            }
+        },
+        async getWorktrees(ensemble) {
+            try {
+                const h = handle((0, config_1.conductorWorkflowId)(ensemble));
+                return await h.query('worktrees');
+            }
+            catch {
+                return [];
+            }
+        },
+        async hasGlobalMaestro() {
+            try {
+                const h = handle(globalMaestroId);
+                const desc = await h.describe();
+                return desc.status.name === 'RUNNING';
+            }
+            catch {
+                return false;
+            }
+        },
+        // ── Maestro session (TUI-owned workflow for two-way messaging) ──
+        async ensureMaestroSession(ensemble) {
+            const workflowId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');
+            const sessionInput = {
+                metadata: {
+                    playerId: 'maestro',
+                    ensemble,
+                    hostname: 'dashboard',
+                    workDir: process.cwd(),
+                    isConductor: false,
+                    status: 'active',
+                    agentType: 'claude',
+                    playerType: 'maestro',
+                    playerTypeDescription: 'TUI dashboard — human operator interface',
+                },
+                part: 'Dashboard interface (human operator)',
+                disableStaleDetection: true,
+            };
+            try {
+                const wfHandle = await client.workflow.start('claudeSessionWorkflow', {
+                    workflowId,
+                    taskQueue: 'claude-tempo',
+                    args: [sessionInput],
+                    workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                    workflowExecutionTimeout: '24 hours',
+                    searchAttributes: {
+                        ClaudeTempoHostname: ['dashboard'],
+                        ClaudeTempoEnsemble: [ensemble],
+                        ClaudeTempoPlayerId: ['maestro'],
+                        ClaudeTempoPlayerType: ['maestro'],
+                    },
+                });
+                console.error(`[tui:client] Maestro session started: ${wfHandle.workflowId}`);
+                // Also ensure the per-ensemble Maestro hub workflow exists.
+                // Without this, getEnsembleChat returns empty when the hub wasn't
+                // previously created by a CLI command.
+                const maestroHubId = (0, config_1.maestroWorkflowId)(ensemble);
+                try {
+                    await client.workflow.start('claudeMaestroWorkflow', {
+                        workflowId: maestroHubId,
+                        taskQueue: 'claude-tempo',
+                        args: [{ ensemble }],
+                        workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                        searchAttributes: {
+                            ClaudeTempoEnsemble: [ensemble],
+                        },
+                    });
+                    console.error(`[tui:client] Maestro hub ensured: ${maestroHubId}`);
+                }
+                catch {
+                    // Maestro hub is non-critical — log but don't fail
+                    console.error(`[tui:client] Maestro hub start skipped (may already exist): ${maestroHubId}`);
+                }
+                return wfHandle.workflowId;
+            }
+            catch (err) {
+                console.error('[tui:client] Failed to start maestro session:', err);
+                throw err;
+            }
+        },
+        async sendAsMaestro(ensemble, targetPlayer, text) {
+            // Resolve target player workflow via search attributes
+            const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitizeQueryValue(ensemble)}" AND ClaudeTempoPlayerId = "${sanitizeQueryValue(targetPlayer)}"`;
+            let targetHandle;
+            for await (const wf of client.workflow.list({ query })) {
+                targetHandle = handle(wf.workflowId);
+                break;
+            }
+            if (!targetHandle) {
+                throw new Error(`Player "${targetPlayer}" not found in ensemble "${ensemble}"`);
+            }
+            // Signal the target with the message
+            await targetHandle.signal('receiveMessage', { from: 'maestro', text, isMaestro: true });
+            // Record outbound on maestro's own workflow
+            const maestroId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');
+            try {
+                const maestroHandle = handle(maestroId);
+                await maestroHandle.signal('recordSentMessage', { to: targetPlayer, text });
+            }
+            catch {
+                // Best-effort — maestro workflow may not exist yet
+            }
+        },
+        async getMaestroMessages(ensemble) {
+            const maestroId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');
+            try {
+                const h = handle(maestroId);
+                // Query received messages (allMessages preferred, pendingMessages fallback)
+                let received;
+                try {
+                    received = await h.query('allMessages');
+                }
+                catch {
+                    received = await h.query('pendingMessages');
+                }
+                // Auto-mark undelivered messages as delivered (maestro has no listener)
+                const undeliveredIds = received.filter(m => !m.delivered).map(m => m.id);
+                if (undeliveredIds.length > 0) {
+                    try {
+                        await h.signal('markDelivered', undeliveredIds);
+                    }
+                    catch {
+                        // Best-effort
+                    }
+                }
+                // Query sent messages
+                let sent;
+                try {
+                    sent = await h.query('allSentMessages');
+                }
+                catch {
+                    sent = [];
+                }
+                return { received, sent };
+            }
+            catch {
+                return { received: [], sent: [] };
+            }
+        },
+    };
+}

package/dist/client/interface.d.ts

@@ -0,0 +1,66 @@
+/**
+ * TempoClient — public interface and related types.
+ *
+ * Extracted from `src/tui/client.ts` so that non-TUI consumers (CLI, tests,
+ * external integrations) can depend on the interface without pulling in Ink/React.
+ */
+import type { MaestroPlayerInfo, MaestroRelayMessage, HistoryEntry, Message, SentMessage, SessionMetadata, ScheduleEntry, QualityGate, StageEntry, WorktreeEntry, EnsembleChatResult } from '../types';
+export interface EnsembleSummary {
+    name: string;
+    playerCount: number;
+    hasConductor: boolean;
+    conductorStatus?: string;
+}
+export interface TempoClient {
+    /** Discover all running ensembles across the cluster. */
+    discoverEnsembles(): Promise<EnsembleSummary[]>;
+    /** Get current player snapshot for an ensemble. */
+    getPlayers(ensemble: string): Promise<MaestroPlayerInfo[]>;
+    /** Get recent messages for an ensemble. */
+    getMessages(ensemble: string, limit?: number): Promise<MaestroRelayMessage[]>;
+    /** Get conductor command/report history for an ensemble. */
+    getConductorHistory(ensemble: string): Promise<HistoryEntry[]>;
+    /** Get a player's message history (received + sent). */
+    getPlayerMessages(ensemble: string, playerId: string): Promise<Array<Message | (SentMessage & {
+        direction: 'sent';
+    })>>;
+    /** Get a player's workflow metadata. */
+    getPlayerMetadata(ensemble: string, playerId: string): Promise<SessionMetadata | null>;
+    /** Send a command to an ensemble's conductor via Maestro. Returns command ID. */
+    sendCommand(ensemble: string, text: string, source: string): Promise<string>;
+    /** Send a message to a specific player in an ensemble. Returns message ID. */
+    sendMessage(ensemble: string, to: string, text: string, source: string): Promise<string>;
+    /** Terminate a player's workflow. */
+    terminatePlayer(ensemble: string, playerId: string): Promise<void>;
+    /** Get active schedules for an ensemble. */
+    getSchedules(ensemble: string): Promise<ScheduleEntry[]>;
+    /** Cancel a named schedule in an ensemble. */
+    cancelSchedule(ensemble: string, name: string): Promise<void>;
+    /** Get quality gates from the conductor workflow. */
+    getGates(ensemble: string): Promise<QualityGate[]>;
+    /** Get stages from the conductor workflow. */
+    getStages(ensemble: string): Promise<StageEntry[]>;
+    /** Get worktrees from the conductor workflow. */
+    getWorktrees(ensemble: string): Promise<WorktreeEntry[]>;
+    /** Get aggregated ensemble chat (maestro + conductor traffic). */
+    getEnsembleChat(ensemble: string, offset?: number, limit?: number): Promise<EnsembleChatResult>;
+    /** Encore (revive) a stale player directly via the maestro session's outbox. */
+    encorePlayer(ensemble: string, playerId: string): Promise<void>;
+    /** Disband an ensemble: terminate all sessions, scheduler, and maestro workflows. */
+    disbandEnsemble(ensemble: string): Promise<{
+        terminated: number;
+    }>;
+    /** Check if the Temporal connection is alive. */
+    isConnected(): Promise<boolean>;
+    /** Check if the Global Maestro workflow is running. */
+    hasGlobalMaestro(): Promise<boolean>;
+    /** Ensure a maestro session workflow exists for the ensemble (create or reuse). */
+    ensureMaestroSession(ensemble: string): Promise<string>;
+    /** Send a message as the maestro to a target player. */
+    sendAsMaestro(ensemble: string, targetPlayer: string, text: string): Promise<void>;
+    /** Get messages received + sent by the maestro session. */
+    getMaestroMessages(ensemble: string): Promise<{
+        received: Message[];
+        sent: SentMessage[];
+    }>;
+}

package/dist/client/interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/tui/App.d.ts

@@ -10,7 +10,7 @@
  * - PromptArea (pinned)
  */
 import React from 'react';
-import type { TempoClient } from './client';
+import type { TempoClient } from '../client';
 interface AppProps {
     api: TempoClient;
     /** If provided, start directly in ensemble view. */