claude-tempo 0.1.0

package/src/workflows/session.ts

@@ -0,0 +1,204 @@
+import {
+  setHandler,
+  condition,
+  continueAsNew,
+  workflowInfo,
+  allHandlersFinished,
+  upsertSearchAttributes,
+  getExternalWorkflowHandle,
+  uuid4,
+} from '@temporalio/workflow';
+
+import {
+  SessionInput,
+  Message,
+  SentMessage,
+  Command,
+  PlayerReport,
+  HistoryEntry,
+  receiveMessageSignal,
+  setPartSignal,
+  setNameSignal,
+  shutdownSignal,
+  markDeliveredSignal,
+  getPartQuery,
+  getMetadataQuery,
+  pendingMessagesQuery,
+  allMessagesQuery,
+  recordSentMessageSignal,
+  allSentMessagesQuery,
+  commandSignal,
+  playerReportSignal,
+  historyQuery,
+} from './signals';
+
+export async function claudeSessionWorkflow(input: SessionInput): Promise<void> {
+  const STALE_MESSAGE_MS = 3 * 60 * 1000; // 3 minutes
+
+  // State (carried across continue-as-new)
+  let part = input.part ?? input.autoSummary ?? 'No description set';
+  const messages: Message[] = input.messages ?? [];
+  const sentMessages: SentMessage[] = input.sentMessages ?? [];
+  let shuttingDown = false;
+
+  // ── Player Signal Handlers ──
+
+  setHandler(receiveMessageSignal, (msg) => {
+    messages.push({
+      id: uuid4(),
+      from: msg.from,
+      text: msg.text,
+      timestamp: new Date().toISOString(),
+      delivered: false,
+    });
+  });
+
+  setHandler(setPartSignal, (newPart) => {
+    part = newPart;
+  });
+
+  setHandler(setNameSignal, (newName) => {
+    input.metadata.playerId = newName;
+    upsertSearchAttributes({ ClaudeTempoPlayerId: [newName] });
+  });
+
+  setHandler(shutdownSignal, () => {
+    shuttingDown = true;
+  });
+
+  setHandler(markDeliveredSignal, (ids) => {
+    for (const msg of messages) {
+      if (ids.includes(msg.id)) {
+        msg.delivered = true;
+      }
+    }
+  });
+
+  setHandler(recordSentMessageSignal, (msg) => {
+    sentMessages.push({
+      id: uuid4(),
+      to: msg.to,
+      text: msg.text,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  // ── Player Query Handlers ──
+
+  setHandler(getPartQuery, () => part);
+  setHandler(getMetadataQuery, () => input.metadata);
+  setHandler(pendingMessagesQuery, () => messages.filter((m) => !m.delivered));
+  setHandler(allMessagesQuery, () => messages);
+  setHandler(allSentMessagesQuery, () => sentMessages);
+
+  // ── Conductor State ──
+
+  const commandHistory: Command[] = input.commandHistory ?? [];
+  const reportHistory: PlayerReport[] = input.reportHistory ?? [];
+
+  // ── Conductor-specific Handlers ──
+
+  if (input.metadata.isConductor) {
+
+    setHandler(commandSignal, (cmd) => {
+      commandHistory.push({
+        ...cmd,
+        timestamp: new Date().toISOString(),
+      });
+      // Deliver command as a message to self so the conductor's Claude session sees it
+      messages.push({
+        id: uuid4(),
+        from: cmd.source,
+        text: cmd.text,
+        timestamp: new Date().toISOString(),
+        delivered: false,
+      });
+    });
+
+    setHandler(playerReportSignal, (report) => {
+      reportHistory.push({
+        ...report,
+        timestamp: new Date().toISOString(),
+      });
+      // Deliver report as a message to self
+      messages.push({
+        id: uuid4(),
+        from: report.playerId,
+        text: `[${report.type}] ${report.text}`,
+        timestamp: new Date().toISOString(),
+        delivered: false,
+      });
+    });
+
+    setHandler(historyQuery, (): HistoryEntry[] => {
+      const entries: HistoryEntry[] = [
+        ...commandHistory.map((c): HistoryEntry => ({
+          type: 'command',
+          timestamp: c.timestamp,
+          data: c,
+        })),
+        ...reportHistory.map((r): HistoryEntry => ({
+          type: 'report',
+          timestamp: r.timestamp,
+          data: r,
+        })),
+      ];
+      return entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    });
+  }
+
+  // ── Main Loop ──
+
+  let staleExit = false;
+
+  while (!shuttingDown) {
+    await condition(() => shuttingDown, '5 minutes');
+
+    if (shuttingDown) break;
+
+    // Detect stale session: messages pending longer than threshold means poller is dead
+    if (!input.disableStaleDetection) {
+      const now = Date.now();
+      const staleMessages = messages.filter(
+        (m) => !m.delivered && now - new Date(m.timestamp).getTime() > STALE_MESSAGE_MS,
+      );
+      if (staleMessages.length > 0) {
+        staleExit = true;
+        break;
+      }
+    }
+
+    // Prevent unbounded history growth
+    const info = workflowInfo();
+    if (info.continueAsNewSuggested || info.historyLength > 10_000) {
+      await condition(allHandlersFinished);
+      await continueAsNew<typeof claudeSessionWorkflow>({
+        ...input,
+        part,
+        messages: messages.filter((m) => !m.delivered),
+        sentMessages: sentMessages.slice(-50),
+        ...(input.metadata.isConductor ? { commandHistory, reportHistory } : {}),
+      });
+    }
+  }
+
+  // Notify conductor with undelivered messages before exiting
+  if (staleExit && !input.metadata.isConductor) {
+    try {
+      const undelivered = messages.filter((m) => !m.delivered);
+      const summary = undelivered.map((m) => `  From ${m.from}: ${m.text}`).join('\n');
+      const conductorWfId = `claude-session-${input.metadata.ensemble}-conductor`;
+      const handle = getExternalWorkflowHandle(conductorWfId);
+      await handle.signal(playerReportSignal, {
+        playerId: input.metadata.playerId,
+        text: `Session ended — ${undelivered.length} undelivered message(s):\n${summary}`,
+        type: 'blocker',
+      });
+    } catch {
+      // No conductor running — that's fine
+    }
+  }
+
+  // Graceful shutdown — wait for in-flight handlers
+  await condition(allHandlersFinished);
+}

package/src/workflows/signals.ts

@@ -0,0 +1,44 @@
+import { defineSignal, defineQuery } from '@temporalio/workflow';
+import type {
+  SessionMetadata,
+  Message,
+  SentMessage,
+  HistoryEntry,
+} from '../types';
+
+// Re-export types for convenience within workflow code
+export type {
+  SessionMetadata,
+  SessionInput,
+  Message,
+  Command,
+  PlayerReport,
+  SentMessage,
+  HistoryEntry,
+} from '../types';
+
+// ── Player Signals ──
+
+export const receiveMessageSignal = defineSignal<[{ from: string; text: string }]>('receiveMessage');
+export const recordSentMessageSignal = defineSignal<[{ to: string; text: string }]>('recordSentMessage');
+export const setPartSignal = defineSignal<[string]>('setPart');
+export const shutdownSignal = defineSignal('shutdown');
+export const markDeliveredSignal = defineSignal<[string[]]>('markDelivered');
+export const setNameSignal = defineSignal<[string]>('setName');
+
+// ── Player Queries ──
+
+export const getPartQuery = defineQuery<string>('getPart');
+export const getMetadataQuery = defineQuery<SessionMetadata>('getMetadata');
+export const pendingMessagesQuery = defineQuery<Message[]>('pendingMessages');
+export const allMessagesQuery = defineQuery<Message[]>('allMessages');
+export const allSentMessagesQuery = defineQuery<SentMessage[]>('allSentMessages');
+
+// ── Conductor Signals ──
+
+export const commandSignal = defineSignal<[{ text: string; source: string; replyTo?: string }]>('command');
+export const playerReportSignal = defineSignal<[{ playerId: string; text: string; type: 'result' | 'blocker' | 'question' }]>('playerReport');
+
+// ── Conductor Queries ──
+
+export const historyQuery = defineQuery<HistoryEntry[]>('history');

package/tests/recruit-terminal-test-plan.md

@@ -0,0 +1,201 @@
+# Recruit Terminal Spawn — Manual Test Plan
+
+Tests for `src/tools/recruit.ts` terminal spawning across platforms and configurations.
+
+## Prerequisites
+
+- Temporal dev server running (`temporal server start-dev`)
+- Project built (`npm run build`)
+- Claude Code installed and on PATH
+- `CLAUDE_TEMPO_ENSEMBLE` set in the conductor session
+
+---
+
+## macOS — Ghostty
+
+### GT-1: Basic recruit opens Ghostty window
+- **Setup**: Ghostty is the active terminal
+- **Steps**: Call `recruit` with a name and workDir
+- **Expected**: A new Ghostty window opens, fish (or default shell) initializes, `claude` launches with the correct name in the title bar
+- **Verify**: `ensemble` shows the new session within 30 seconds
+
+### GT-2: Environment variables are passed through
+- **Setup**: Conductor is in ensemble "myband"
+- **Steps**: Recruit a new session
+- **Expected**: The recruited session's MCP server activates (not idle mode), confirming `CLAUDE_TEMPO_ENSEMBLE=myband` was received
+- **Verify**: New session appears in `ensemble` output with matching ensemble
+
+### GT-3: Node manager (fnm/nvm) PATH is preserved
+- **Setup**: Node is managed via fnm or nvm (not a system install)
+- **Steps**: Recruit a new session
+- **Expected**: The MCP server starts successfully (requires `node` on PATH)
+- **Verify**: `/mcp` in the new session shows claude-tempo connected, not failed
+
+### GT-4: Shell with slow startup
+- **Setup**: Add `sleep 2` to fish config (`~/.config/fish/config.fish`)
+- **Steps**: Recruit a new session
+- **Expected**: `initial input` waits for the shell prompt; claude command runs correctly after shell init completes
+- **Verify**: Session registers in ensemble (may take longer than usual)
+- **Cleanup**: Remove the `sleep 2` from fish config
+
+### GT-5: Working directory is set correctly
+- **Setup**: Use a workDir different from the conductor's (e.g., `/tmp`)
+- **Steps**: `recruit({ workDir: "/tmp", name: "test-dir" })`
+- **Expected**: New Ghostty window opens in `/tmp`
+- **Verify**: `ensemble` shows `Dir: /tmp` for the new session
+
+### GT-6: Special characters in workDir
+- **Setup**: Create a directory with spaces: `mkdir -p "/tmp/my project"`
+- **Steps**: `recruit({ workDir: "/tmp/my project", name: "test-spaces" })`
+- **Expected**: Claude launches in the correct directory without shell quoting errors
+- **Cleanup**: `rm -rf "/tmp/my project"`
+
+---
+
+## macOS — iTerm2
+
+### IT-1: Basic recruit opens iTerm2 window
+- **Setup**: iTerm2 is the active terminal (Ghostty not running)
+- **Steps**: Call `recruit`
+- **Expected**: A new iTerm2 window opens with default profile, shell initializes, `claude` launches
+- **Verify**: `ensemble` shows the new session
+
+### IT-2: Environment and PATH preserved
+- **Setup**: Node managed via nvm/fnm, iTerm2 as terminal
+- **Steps**: Recruit a new session
+- **Expected**: MCP server connects to Temporal (node is on PATH, env vars passed)
+- **Verify**: `/mcp` in new session shows claude-tempo connected
+
+### IT-3: Uses `write text` not `command`
+- **Setup**: iTerm2 active
+- **Steps**: Recruit and observe the new window
+- **Expected**: Shell prompt appears briefly, then the claude command is typed in (not a direct command execution). Shell profile is fully loaded before claude starts.
+
+---
+
+## macOS — Terminal.app
+
+### TA-1: Basic recruit opens Terminal.app window
+- **Setup**: Neither Ghostty nor iTerm2 running; Terminal.app is default
+- **Steps**: Call `recruit`
+- **Expected**: Terminal.app opens via `.command` file, shell profiles are sourced, `claude` launches
+- **Verify**: `ensemble` shows the new session
+
+### TA-2: zsh user with nvm
+- **Setup**: Terminal.app, zsh default shell, nvm installed
+- **Steps**: Recruit a new session
+- **Expected**: `.command` script sources `.zshrc` and `.nvm/nvm.sh`, node is available
+- **Verify**: MCP server connects successfully
+
+### TA-3: fish user on Terminal.app
+- **Setup**: Terminal.app, `SHELL=/usr/local/bin/fish` (or `/opt/homebrew/bin/fish`)
+- **Steps**: Recruit a new session
+- **Expected**: `.command` script detects fish and re-execs into `fish -c` for proper environment
+- **Verify**: MCP server connects, node is on PATH
+
+### TA-4: .command file cleanup
+- **Steps**: Recruit a session, note the timestamp
+- **Expected**: A `.command` file exists in `$TMPDIR` named `claude-tempo-recruit-<timestamp>.command`
+- **Note**: These are not auto-cleaned; consider periodic cleanup in future
+
+---
+
+## Terminal Detection
+
+### TD-1: TERM_PROGRAM takes priority
+- **Setup**: `TERM_PROGRAM=ghostty` in environment, iTerm2 also running
+- **Steps**: Recruit a new session
+- **Expected**: Ghostty path is used (not iTerm2)
+- **Verify**: Check MCP server logs for "Using Ghostty initial-input path"
+
+### TD-2: Frontmost app fallback when TERM_PROGRAM missing
+- **Setup**: Unset `TERM_PROGRAM` in MCP server env, Ghostty is frontmost app
+- **Steps**: Recruit a new session
+- **Expected**: AppleScript detects Ghostty as frontmost app, uses Ghostty path
+- **Verify**: Check MCP server logs
+
+### TD-3: pgrep fallback
+- **Setup**: `TERM_PROGRAM` unset, AppleScript frontmost detection returns a non-terminal app (e.g., Finder is focused)
+- **Steps**: Recruit a new session
+- **Expected**: Falls back to pgrep, finds the correct terminal
+- **Verify**: Check MCP server logs
+
+### TD-4: No terminal detected defaults to Terminal.app
+- **Setup**: Neither Ghostty nor iTerm2 installed/running
+- **Steps**: Recruit a new session
+- **Expected**: Falls through to Terminal.app `.command` file path
+- **Verify**: Terminal.app opens
+
+---
+
+## Claude Binary Resolution
+
+### CB-1: claude on PATH via node manager
+- **Setup**: `claude` installed in `~/.local/bin/` or via npm global
+- **Steps**: Recruit a new session
+- **Expected**: `resolveClaudePath()` returns the absolute path, used in spawn command
+
+### CB-2: claude not on MCP server PATH
+- **Setup**: `claude` is only on the user's shell PATH (via fnm), not in the MCP server's PATH
+- **Steps**: Recruit a new session
+- **Expected**: `resolveClaudePath()` falls back to bare `claude`, but the `initial input` approach runs in the user's shell where `claude` is on PATH
+- **Verify**: Session starts successfully despite MCP server not finding claude
+
+---
+
+## Error Handling
+
+### EH-1: Duplicate name rejected
+- **Steps**: Recruit "Alice", then recruit "Alice" again
+- **Expected**: Second recruit returns error: "Session Alice is already active"
+
+### EH-2: Invalid name rejected
+- **Steps**: `recruit({ name: "bad name!", workDir: "/tmp" })`
+- **Expected**: Returns error about invalid characters
+
+### EH-3: Session spawned but slow to register
+- **Steps**: Recruit with a very slow workDir (e.g., network mount)
+- **Expected**: Returns "spawned but did not register within 15 seconds" message
+- **Verify**: Session eventually appears in `ensemble`
+
+### EH-4: Initial message delivered after registration
+- **Steps**: Recruit with an `initialMessage`
+- **Expected**: After the session registers, it receives the name instruction AND the initial message
+- **Verify**: New session calls `set_name` and then acts on the initial message
+
+---
+
+## Cross-Platform (if applicable)
+
+### WIN-1: Windows recruit opens cmd.exe window
+- **Setup**: Windows with Claude Code installed
+- **Steps**: Call `recruit`
+- **Expected**: New cmd.exe window opens with `claude` running, env vars set via process env
+
+### LIN-1: Linux with gnome-terminal
+- **Setup**: GNOME desktop with gnome-terminal
+- **Steps**: Call `recruit`
+- **Expected**: New gnome-terminal window opens with `claude` running
+
+### LIN-2: Linux headless fallback
+- **Setup**: No GUI terminal emulator available
+- **Steps**: Call `recruit`
+- **Expected**: Falls back to headless `bash -c` spawn, logs warning
+- **Verify**: Session registers in ensemble (no visible window)
+
+---
+
+## Regression Checks
+
+### RG-1: Ghostty `command` property is NOT used
+- **Verify**: The Ghostty AppleScript uses `initial input`, not `set command of cfg`
+- **Why**: `command` bypasses shell init, breaking node managers
+
+### RG-2: No `export` syntax in Ghostty/iTerm2 paths
+- **Verify**: The command typed into the shell uses inline `KEY=val` syntax, not `export KEY=val`
+- **Why**: `export` is not valid fish syntax
+
+### RG-3: Shell quoting handles single quotes in paths
+- **Steps**: Create dir `/tmp/it's-a-test`, recruit into it
+- **Expected**: shellQuote escapes the apostrophe correctly
+- **Cleanup**: Remove the directory

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}