claude-tempo 0.1.0

package/src/tools/ensemble.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import * as os from 'os';
+import { Config } from '../config';
+import { SessionMetadata } from '../types';
+import { defineTool } from './helpers';
+
+export function registerEnsembleTool(
+  server: McpServer,
+  client: Client,
+  config: Config,
+  getPlayerId: () => string,
+  ownWorkflowId: string,
+) {
+  defineTool(
+    server,
+    'ensemble',
+    `Discover active Claude Code sessions in the "${config.ensemble}" ensemble. Returns player IDs, descriptions, and metadata.`,
+    {
+      scope: z.string().optional().describe('Filter scope: "machine" (same hostname), "repo" (same git root), "all" (default). All scopes are within the current ensemble.'),
+    },
+    async (args) => {
+      const scope = (args.scope ?? 'all') as 'machine' | 'repo' | 'all';
+      let query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${config.ensemble}"`;
+
+      if (scope === 'machine') {
+        query += ` AND ClaudeTempoHostname = "${os.hostname()}"`;
+      }
+
+      const players: Array<{
+        playerId: string;
+        part: string;
+        hostname: string;
+        workDir: string;
+        gitRoot?: string;
+        gitBranch?: string;
+        isConductor: boolean;
+        isYou: boolean;
+      }> = [];
+
+      try {
+        for await (const workflow of client.workflow.list({ query })) {
+          try {
+            const handle = client.workflow.getHandle(workflow.workflowId);
+            const metadata: SessionMetadata = await handle.query('getMetadata');
+            const part: string = await handle.query('getPart');
+
+            if (scope === 'repo') {
+              const ownHandle = client.workflow.getHandle(ownWorkflowId);
+              const ownMeta: SessionMetadata = await ownHandle.query('getMetadata');
+              if (metadata.gitRoot !== ownMeta.gitRoot) continue;
+            }
+
+            players.push({
+              playerId: metadata.playerId,
+              part,
+              hostname: metadata.hostname,
+              workDir: metadata.workDir,
+              gitRoot: metadata.gitRoot,
+              gitBranch: metadata.gitBranch,
+              isConductor: metadata.isConductor,
+              isYou: metadata.playerId === getPlayerId(),
+            });
+          } catch {
+            // Workflow may have just completed — skip it
+          }
+        }
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Error listing workflows: ${err}` }],
+          isError: true,
+        };
+      }
+
+      if (players.length === 0) {
+        return {
+          content: [{ type: 'text' as const, text: 'No active sessions found.' }],
+        };
+      }
+
+      const lines = players.map((p) => {
+        const tags = [
+          p.isYou ? '(you)' : '',
+          p.isConductor ? '(conductor)' : '',
+        ].filter(Boolean).join(' ');
+
+        return [
+          `**${p.playerId}** ${tags}`.trim(),
+          `  Part: ${p.part}`,
+          `  Dir: ${p.workDir}`,
+          p.gitBranch ? `  Branch: ${p.gitBranch}` : '',
+          `  Host: ${p.hostname}`,
+        ].filter(Boolean).join('\n');
+      });
+
+      return {
+        content: [{ type: 'text' as const, text: lines.join('\n\n') }],
+      };
+    },
+  );
+}

package/src/tools/helpers.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Wrapper around McpServer.tool() that avoids TS2589 deep type instantiation
+ * errors caused by Zod 3.25 + MCP SDK type inference interaction.
+ */
+export function defineTool(
+  server: McpServer,
+  name: string,
+  description: string,
+  paramsSchema: Record<string, z.ZodTypeAny>,
+  handler: (args: Record<string, any>, extra: any) => Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }>,
+) {
+  (server.tool as Function)(name, description, paramsSchema, handler);
+}

package/src/tools/listen.ts

@@ -0,0 +1,43 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WorkflowHandle } from '@temporalio/client';
+import { Message } from '../types';
+import { defineTool } from './helpers';
+
+export function registerListenTool(
+  server: McpServer,
+  handle: WorkflowHandle,
+) {
+  defineTool(
+    server,
+    'listen',
+    'Check for pending messages from other sessions. Use this if you want to manually check for new messages.',
+    {},
+    async () => {
+      try {
+        const messages: Message[] = await handle.query('pendingMessages');
+
+        if (messages.length === 0) {
+          return {
+            content: [{ type: 'text' as const, text: 'No pending messages.' }],
+          };
+        }
+
+        // Mark messages as delivered
+        const ids = messages.map((m) => m.id);
+        await handle.signal('markDelivered', ids);
+
+        const lines = messages.map(
+          (m) => `**${m.from}** (${m.timestamp}):\n${m.text}`,
+        );
+        return {
+          content: [{ type: 'text' as const, text: lines.join('\n\n') }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to check messages: ${err}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/recruit.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config } from '../config';
+import { spawnInTerminal } from '../spawn';
+import { resolveSession } from './resolve';
+import { defineTool } from './helpers';
+
+const log = (...args: unknown[]) => console.error('[claude-tempo:recruit]', ...args);
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function registerRecruitTool(
+  server: McpServer,
+  client: Client,
+  config: Config,
+  getPlayerId: () => string,
+) {
+  defineTool(
+    server,
+    'recruit',
+    'Start a new named Claude Code session in a directory. Rejects if the name is already active.',
+    {
+      workDir: z.string().describe('The working directory for the new session'),
+      name: z.string().describe('Name for the new session'),
+      initialMessage: z.string().optional()
+        .describe('Optional task or message for the new session (sent after it sets its name)'),
+    },
+    async (args) => {
+      const { workDir, name, initialMessage } = args as {
+        workDir: string;
+        name: string;
+        initialMessage?: string;
+      };
+      // Validate name to prevent search attribute query injection
+      if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: `Invalid name "${name}". Names must contain only letters, numbers, hyphens, and underscores.`,
+          }],
+          isError: true,
+        };
+      }
+
+      try {
+        // Check if a session with this name is already active
+        const existing = await resolveSession(client, config.ensemble, name);
+        if (existing) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: `Session **${name}** is already active. Use \`cue\` to send it a message, or \`terminate\` it first.`,
+            }],
+            isError: true,
+          };
+        }
+
+        // Record existing workflows so we can find the new one
+        const existingIds = new Set<string>();
+        const listQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${config.ensemble}"`;
+        for await (const wf of client.workflow.list({ query: listQuery })) {
+          existingIds.add(wf.workflowId);
+        }
+
+        // Spawn a new Claude Code session in a visible terminal
+        const spawnArgs = [
+          '--dangerously-skip-permissions',
+          '--dangerously-load-development-channels', 'server:claude-tempo',
+          '-n', name,
+        ];
+        const { pid } = spawnInTerminal(spawnArgs, workDir, {
+          CLAUDE_TEMPO_ENSEMBLE: config.ensemble,
+          CLAUDE_TEMPO_CONDUCTOR: '',
+        });
+
+        log(`Spawned claude process (pid ${pid}) in ${workDir} as "${name}"`);
+
+        // Poll for the new workflow to appear (up to ~15s)
+        let newWorkflowId: string | null = null;
+        for (let attempt = 0; attempt < 30; attempt++) {
+          await sleep(500);
+          for await (const wf of client.workflow.list({ query: listQuery })) {
+            if (!existingIds.has(wf.workflowId)) {
+              newWorkflowId = wf.workflowId;
+              break;
+            }
+          }
+          if (newWorkflowId) break;
+        }
+
+        if (!newWorkflowId) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: `Session "${name}" spawned but did not register within 15 seconds. It may still be starting up. Check \`ensemble\` shortly.`,
+            }],
+          };
+        }
+
+        // Send it a message instructing it to set its name
+        const newHandle = client.workflow.getHandle(newWorkflowId);
+        const nameInstruction = `You have been recruited as "${name}". Call set_name("${name}") immediately.`;
+        const fullMessage = initialMessage
+          ? `${nameInstruction}\n\nThen: ${initialMessage}`
+          : nameInstruction;
+
+        await newHandle.signal('receiveMessage', {
+          from: getPlayerId(),
+          text: fullMessage,
+        });
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: `Recruited session **${name}** in ${workDir}. It will set its name shortly.${initialMessage ? ' Initial task sent.' : ''}`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to recruit: ${err}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/report.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config, conductorWorkflowId, sessionWorkflowId } from '../config';
+import { defineTool } from './helpers';
+
+const log = (...args: unknown[]) => console.error('[claude-tempo:report]', ...args);
+
+export function registerReportTool(
+  server: McpServer,
+  client: Client,
+  config: Config,
+  getPlayerId: () => string,
+) {
+  defineTool(
+    server,
+    'report',
+    'Send an update to the conductor. Use this to report task completion, blockers, or questions. No-op if no conductor is running.',
+    {
+      text: z.string().describe('The report content'),
+      type: z.enum(['result', 'blocker', 'question']).optional()
+        .describe('Type of report: "result" (default, task done), "blocker" (stuck), "question" (need input)'),
+    },
+    async (args) => {
+      const text = args.text as string;
+      const type = (args.type ?? 'result') as 'result' | 'blocker' | 'question';
+      try {
+        const conductorHandle = client.workflow.getHandle(conductorWorkflowId(config.ensemble));
+        await conductorHandle.signal('playerReport', {
+          playerId: getPlayerId(),
+          text,
+          type,
+        });
+
+        // Record outbound on sender's own workflow
+        try {
+          const senderHandle = client.workflow.getHandle(
+            sessionWorkflowId(config.ensemble, getPlayerId()),
+          );
+          await senderHandle.signal('recordSentMessage', { to: 'conductor', text: `[${type}] ${text}` });
+        } catch (err) {
+          log('Failed to record sent message:', err);
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: `Report sent to conductor: [${type}] ${text}` }],
+        };
+      } catch {
+        return {
+          content: [{ type: 'text' as const, text: 'No conductor running. Report not sent (this is normal for peer-only ensembles).' }],
+        };
+      }
+    },
+  );
+}

package/src/tools/resolve.ts

@@ -0,0 +1,39 @@
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { SessionMetadata } from '../types';
+
+/**
+ * Resolve a session by player name.
+ * 1. Try search attribute query (fast, indexed — but eventually consistent)
+ * 2. Fall back to listing all ensemble workflows and querying metadata (always current)
+ */
+function escapeQueryString(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export async function resolveSession(
+  client: Client,
+  ensemble: string,
+  playerName: string,
+): Promise<WorkflowHandle | null> {
+  // Fast path: search attribute (may lag behind by a few seconds after rename)
+  const saQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${escapeQueryString(ensemble)}" AND ClaudeTempoPlayerId = "${escapeQueryString(playerName)}"`;
+  for await (const wf of client.workflow.list({ query: saQuery })) {
+    return client.workflow.getHandle(wf.workflowId);
+  }
+
+  // Fallback: list all ensemble workflows and check in-memory metadata
+  const fallbackQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${escapeQueryString(ensemble)}"`;
+  for await (const wf of client.workflow.list({ query: fallbackQuery })) {
+    try {
+      const handle = client.workflow.getHandle(wf.workflowId);
+      const metadata: SessionMetadata = await handle.query('getMetadata');
+      if (metadata.playerId === playerName) {
+        return handle;
+      }
+    } catch {
+      // Workflow may have just completed — skip
+    }
+  }
+
+  return null;
+}

package/src/tools/set-name.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WorkflowHandle, Client } from '@temporalio/client';
+import { Config } from '../config';
+import { resolveSession } from './resolve';
+import { defineTool } from './helpers';
+
+export function registerSetNameTool(
+  server: McpServer,
+  client: Client,
+  config: Config,
+  handle: WorkflowHandle,
+  getPlayerId: () => string,
+  setPlayerId: (id: string) => void,
+) {
+  defineTool(
+    server,
+    'set_name',
+    'Set a human-readable name for this session. Visible to other players in the ensemble.',
+    {
+      name: z.string().describe('The name for this session (e.g., "UX", "API", "test-runner")'),
+    },
+    async (args) => {
+      const { name } = args as { name: string };
+
+      // Validate name to prevent search attribute query injection
+      if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        return {
+          content: [{ type: 'text' as const, text: `Invalid name "${name}". Names must contain only letters, numbers, hyphens, and underscores.` }],
+          isError: true,
+        };
+      }
+
+      // Check if the name is already taken
+      const existing = await resolveSession(client, config.ensemble, name);
+      if (existing && existing.workflowId !== handle.workflowId) {
+        return {
+          content: [{ type: 'text' as const, text: `Name **${name}** is already taken by another session. Choose a different name.` }],
+          isError: true,
+        };
+      }
+
+      try {
+        await handle.signal('setName', name);
+        setPlayerId(name);
+        return {
+          content: [{ type: 'text' as const, text: `Session name set to **${name}**. Run \`/rename ${name}\` to match your Claude Code session name.` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to set name: ${err}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/set-part.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WorkflowHandle } from '@temporalio/client';
+import { defineTool } from './helpers';
+
+export function registerSetPartTool(
+  server: McpServer,
+  handle: WorkflowHandle,
+) {
+  defineTool(
+    server,
+    'set_part',
+    'Update your description of what you are currently working on. Visible to other sessions via ensemble.',
+    {
+      part: z.string().describe('A short description of your current work'),
+    },
+    async (args) => {
+      const { part } = args as { part: string };
+      try {
+        await handle.signal('setPart', part);
+        return {
+          content: [{ type: 'text' as const, text: `Part updated: "${part}"` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to update part: ${err}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/terminate.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config } from '../config';
+import { resolveSession } from './resolve';
+import { defineTool } from './helpers';
+
+export function registerTerminateTool(
+  server: McpServer,
+  client: Client,
+  config: Config,
+  getPlayerId: () => string,
+) {
+  defineTool(
+    server,
+    'terminate',
+    'Terminate a player session by name. Use this to clean up orphaned sessions.',
+    {
+      playerId: z.string().describe('The player name of the session to terminate'),
+    },
+    async (args) => {
+      const { playerId } = args as { playerId: string };
+
+      if (playerId === getPlayerId()) {
+        return {
+          content: [{ type: 'text' as const, text: 'Cannot terminate your own session.' }],
+          isError: true,
+        };
+      }
+
+      try {
+        const handle = await resolveSession(client, config.ensemble, playerId);
+        if (!handle) {
+          return {
+            content: [{ type: 'text' as const, text: `No active session found with name "${playerId}".` }],
+            isError: true,
+          };
+        }
+        // Warn the session before terminating
+        try {
+          await handle.signal('receiveMessage', {
+            from: getPlayerId(),
+            text: `Your session is being terminated by player ${getPlayerId()}. Please save your work and close this terminal.`,
+          });
+        } catch {
+          // May fail if workflow is in a bad state — proceed with termination
+        }
+
+        await handle.terminate(`Terminated by player ${getPlayerId()}`);
+        return {
+          content: [{ type: 'text' as const, text: `Session **${playerId}** terminated. If the Claude Code terminal is still open, the user will need to close it manually.` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to terminate: ${err}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+// Shared types used by both workflow code (V8 sandbox) and Node.js server code.
+// This file must NOT import from @temporalio/* — it's pure TypeScript types.
+
+export interface SessionMetadata {
+  playerId: string;
+  ensemble: string;
+  hostname: string;
+  workDir: string;
+  gitRoot?: string;
+  gitBranch?: string;
+  isConductor: boolean;
+}
+
+export interface SessionInput {
+  metadata: SessionMetadata;
+  /** Restored from continue-as-new */
+  part?: string;
+  /** Restored from continue-as-new (undelivered only) */
+  messages?: Message[];
+  /** Restored from continue-as-new */
+  sentMessages?: SentMessage[];
+  /** Restored from continue-as-new (conductor only) */
+  commandHistory?: Command[];
+  /** Restored from continue-as-new (conductor only) */
+  reportHistory?: PlayerReport[];
+  autoSummary?: string;
+  /** Disable stale session detection (for passive mailbox workflows like maestro) */
+  disableStaleDetection?: boolean;
+}
+
+export interface Message {
+  id: string;
+  from: string;
+  text: string;
+  timestamp: string;
+  delivered: boolean;
+}
+
+export interface SentMessage {
+  id: string;
+  to: string;
+  text: string;
+  timestamp: string;
+}
+
+export interface Command {
+  text: string;
+  source: string;
+  replyTo?: string;
+  timestamp: string;
+}
+
+export interface PlayerReport {
+  playerId: string;
+  text: string;
+  type: 'result' | 'blocker' | 'question';
+  timestamp: string;
+}
+
+export interface HistoryEntry {
+  type: 'command' | 'report';
+  timestamp: string;
+  data: Command | PlayerReport;
+}

package/src/worker.ts

@@ -0,0 +1,34 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { Worker, NativeConnection, bundleWorkflowCode } from '@temporalio/worker';
+import { Config } from './config';
+
+const BUNDLE_PATH = path.resolve(__dirname, '..', 'workflow-bundle.js');
+
+async function getWorkflowBundle(): Promise<{ code: string }> {
+  // Use pre-built bundle if it exists, otherwise bundle from source
+  if (fs.existsSync(BUNDLE_PATH)) {
+    return { code: fs.readFileSync(BUNDLE_PATH, 'utf-8') };
+  }
+  const bundle = await bundleWorkflowCode({
+    workflowsPath: path.resolve(__dirname, 'workflows', 'session'),
+  });
+  // Cache for subsequent workers
+  fs.writeFileSync(BUNDLE_PATH, bundle.code);
+  return bundle;
+}
+
+export async function createWorker(config: Config): Promise<Worker> {
+  const connection = await NativeConnection.connect({
+    address: config.temporalAddress,
+  });
+
+  const workflowBundle = await getWorkflowBundle();
+
+  return await Worker.create({
+    connection,
+    namespace: config.temporalNamespace,
+    taskQueue: config.taskQueue,
+    workflowBundle,
+  });
+}