claude-tempo 0.5.0 → 0.7.0

package/README.md

@@ -91,16 +91,17 @@ claude-tempo <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `up [ensemble]` | First-time setup: start Temporal, configure MCP, launch conductor |
+| `up [ensemble]` | First-time setup: start Temporal, configure MCP, launch conductor. Use `--from` to load a blueprint. |
 | `down` | Stop Temporal, terminate sessions, remove MCP config |
 | `server` | Start the Temporal dev server and register search attributes |
-| `conduct [ensemble]` | Start a conductor session (one per ensemble) |
+| `conduct [ensemble]` | Start a conductor session (one per ensemble). Use `--resume` or `--replace` if one exists. |
 | `start [ensemble]` | Start a player session |
 | `status [ensemble]` | Show active sessions and Temporal health |
 | `config` | Configure Temporal connection settings (interactive or `set`/`show`) |
 | `stop [ensemble]` | Stop sessions (`-n <name>` for one, `--all` for everything) |
 | `init` | Register claude-tempo MCP server globally (`--project` for per-directory) |
 | `preflight` | Run environment checks |
+| `ensemble <sub>` | Manage saved blueprints (`save`, `list`, `show`) |
 | `help` | Show usage info |
 
 ### Global options
@@ -115,6 +116,9 @@ claude-tempo <command> [options]
 --skip-preflight              Skip preflight checks (start/conduct)
 -d, --dir <path>              Target directory (default: cwd)
 --background                  Run Temporal in background (server only)
+--from <file>                 Load an ensemble blueprint on startup (up only)
+--resume                      Resume an existing conductor session (conduct only)
+--replace                     Stop existing conductor and start fresh (conduct only)
 ```
 
 ### `claude-tempo up`
@@ -173,6 +177,9 @@ Ensemble: myband
   bob
     Working on the dashboard
     /Users/me/projects/app  feat/ui  my-machine.local
+
+  1 active schedule
+  deploy-watch → ops | every 1h | next: 3:00:00 PM
 ```
 
 ### `claude-tempo preflight`
@@ -201,9 +208,119 @@ These tools are available inside Claude Code sessions connected to claude-tempo:
 | `set_name` | Set a human-readable name for this session. |
 | `set_part` | Describe what you're working on. Visible to others via `ensemble`. |
 | `listen` | Manually check for pending messages. |
-| `recruit` | Spawn a new Claude Code session in a directory. Opens a new terminal window. |
+| `recruit` | Spawn a new Claude Code session in a directory. Can recruit a conductor with `conductor: true`. |
 | `report` | Send updates to the conductor. No-op if no conductor exists. |
 | `terminate` | Terminate a player session by name. |
+| `schedule` | Create a one-shot or recurring schedule to cue a player. |
+| `unschedule` | Cancel a named schedule. |
+| `schedules` | List all active schedules. |
+| `save_ensemble` | Save the current ensemble as a YAML blueprint (conductor only). |
+| `load_ensemble` | Load a blueprint to recruit players and create schedules. |
+
+## Scheduling
+
+Players can set up schedules to send messages on timers — useful for periodic checks, reminders, and recurring coordination.
+
+Three tools are available:
+- **`schedule`** — Create a named schedule (one-shot or recurring)
+- **`unschedule`** — Remove a schedule by name
+- **`schedules`** — List all active schedules
+
+### Examples
+
+Tell your session things like:
+
+- *"Schedule a check every hour called 'deploy-watch' — cue ops to check deployment status"*
+- *"Remind me in 30 minutes to review PR #42"*
+- *"Every 5 minutes for the next hour, ping frontend to check their progress"*
+- *"Set up a daily standup reminder at 9am UTC for the conductor"*
+- *"Cancel the deploy-watch schedule"*
+- *"Show me all active schedules"*
+
+Schedules support one-shot delays, fixed times, and recurring intervals with optional bounds (max count or end time).
+
+### How it works
+
+- Scheduled messages arrive with a `[scheduled: name]` prefix so recipients can distinguish them from direct cues
+- The `from` field is set to the schedule creator, so replies go to the right person
+- If the target player is gone when a schedule fires, the creator is notified so they can re-recruit if needed. Falls back to notifying the conductor if the creator is also unavailable
+- Messages include `isScheduled` metadata for dashboard integrations
+- `claude-tempo status` shows active schedules alongside sessions
+- A single durable scheduler workflow per ensemble manages all schedules using Temporal timers
+
+## Ensemble Blueprints
+
+Define reusable ensemble configurations as YAML files. A blueprint specifies which players to recruit, what instructions to give them, what schedules to create, and optionally which custom agent files to use.
+
+### Example blueprint
+
+```yaml
+name: my-project
+conductor:
+  instructions: "Coordinate the frontend and backend teams"
+players:
+  - name: frontend
+    workDir: /repos/my-app
+    instructions: "Build the React dashboard in src/components"
+  - name: backend
+    workDir: /repos/my-api
+    instructions: "Implement the REST endpoints in src/routes"
+  - name: ops
+    workDir: /repos/infra
+    agent: agents/ops-agent.md
+    instructions: "Monitor deployments and run health checks"
+schedules:
+  - name: status-check
+    message: "Report your current progress and any blockers"
+    target: all
+    every: 30m
+  - name: deploy-reminder
+    message: "Check if the staging deploy succeeded"
+    target: ops
+    delay: 10m
+```
+
+### Three ways to use blueprints
+
+1. **From the CLI** — load a blueprint when starting an ensemble:
+
+   ```bash
+   claude-tempo up --from my-blueprint.yaml
+   ```
+
+2. **From inside a session** — use the `load_ensemble` tool:
+
+   *"Load the blueprint from ~/.claude-tempo/ensembles/my-project.yaml"*
+
+3. **Save the current state** — snapshot a running ensemble as a blueprint (conductor only):
+
+   *"Save this ensemble as a blueprint called my-project"*
+
+### Natural language examples
+
+Tell your session things like:
+
+- *"Load the my-project blueprint"*
+- *"Save this ensemble as a blueprint"*
+- *"Load the blueprint from /repos/configs/team.yaml"*
+
+### Fan-out schedules
+
+Use `target: "all"` in a schedule to deliver a message to every active player (excluding the conductor). This is useful for periodic status checks or broadcast announcements:
+
+- *"Schedule a message every 30 minutes to all players asking for a progress update"*
+
+### Custom agents
+
+The `agent` field on a player can be a path to a `.md` file that will be used as the session's system prompt via `--system-prompt`. This lets you create specialized agents with domain-specific instructions:
+
+```yaml
+players:
+  - name: security-reviewer
+    workDir: /repos/my-app
+    agent: agents/security-review.md
+    instructions: "Review the latest PR for security issues"
+```
 
 ## Conductors
 
@@ -274,11 +391,12 @@ Inside a session, try:
 
 Sessions start with a random 8-character hex ID. Set a name at launch with `-n` or use `set_name` inside a session.
 
-- Names are stored as Temporal search attributes (`ClaudeTempoPlayerId`)
+- Names are stored in workflow metadata and discoverable via metadata queries. Search attributes are also set for Temporal UI visibility.
 - Other players use names to send messages via `cue`
 - `recruit` automatically tells new sessions to set their name
 - Names must be unique within an ensemble
 - Names must contain only letters, numbers, hyphens, and underscores
+- The name "conductor" is reserved for conductor sessions
 
 ### Terminal support
 

package/dist/activities/schedule-fire.d.ts

@@ -0,0 +1,21 @@
+import { Client } from '@temporalio/client';
+export interface FireScheduleInput {
+    ensemble: string;
+    scheduleName: string;
+    message: string;
+    target: string;
+    createdBy: string;
+}
+export interface FireScheduleResult {
+    success: boolean;
+    error?: string;
+}
+/** Activity interface — used by proxyActivities in the scheduler workflow. */
+export interface ScheduleActivities {
+    fireSchedule(input: FireScheduleInput): Promise<FireScheduleResult>;
+}
+/**
+ * Create the schedule-fire activity bound to a Temporal client.
+ * The returned object is registered with the worker as activities.
+ */
+export declare function createScheduleActivities(client: Client): ScheduleActivities;

package/dist/activities/schedule-fire.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createScheduleActivities = createScheduleActivities;
+/**
+ * Create the schedule-fire activity bound to a Temporal client.
+ * The returned object is registered with the worker as activities.
+ */
+function createScheduleActivities(client) {
+    return {
+        async fireSchedule(input) {
+            const { ensemble, scheduleName, message, target, createdBy } = input;
+            try {
+                const text = `[scheduled: ${scheduleName}] ${message}`;
+                // Handle target "all" — deliver to every active player except the conductor
+                if (target === 'all') {
+                    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+                    const failures = [];
+                    let delivered = 0;
+                    for await (const wf of client.workflow.list({ query })) {
+                        try {
+                            const handle = client.workflow.getHandle(wf.workflowId);
+                            const metadata = await handle.query('getMetadata');
+                            if (metadata.ensemble !== ensemble)
+                                continue;
+                            if (metadata.isConductor)
+                                continue; // skip conductor
+                            await handle.signal('receiveMessage', {
+                                from: createdBy,
+                                text,
+                                isScheduled: true,
+                                scheduleName,
+                            });
+                            delivered++;
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            failures.push(`${wf.workflowId}: ${msg}`);
+                        }
+                    }
+                    if (delivered === 0 && failures.length === 0) {
+                        await notifyFailure(client, ensemble, createdBy, scheduleName, target, 'No active players found in the ensemble.');
+                        return { success: false, error: 'No active players found' };
+                    }
+                    return {
+                        success: failures.length === 0,
+                        error: failures.length > 0 ? `Delivered to ${delivered} players, ${failures.length} failed: ${failures.join('; ')}` : undefined,
+                    };
+                }
+                // Resolve single target player by querying running session workflows
+                const handle = await resolveSession(client, ensemble, target);
+                if (!handle) {
+                    // Notify the creator (or conductor as fallback) about the failure
+                    await notifyFailure(client, ensemble, createdBy, scheduleName, target, `Player "${target}" not found — session may have been terminated.`);
+                    return { success: false, error: `No active session found for "${target}"` };
+                }
+                // Send cue signal with from set to the original creator's name
+                await handle.signal('receiveMessage', {
+                    from: createdBy,
+                    text,
+                    isScheduled: true,
+                    scheduleName,
+                });
+                return { success: true };
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                return { success: false, error: errorMsg };
+            }
+        },
+    };
+}
+/**
+ * Notify the schedule creator (or conductor as fallback) that delivery failed.
+ * This lets the creator's AI session decide whether to re-recruit the target.
+ */
+async function notifyFailure(client, ensemble, createdBy, scheduleName, target, reason) {
+    const failureText = `[scheduled: ${scheduleName}] Delivery to "${target}" failed — ${reason}`;
+    // Try the creator first
+    const creatorHandle = await resolveSession(client, ensemble, createdBy);
+    if (creatorHandle) {
+        try {
+            await creatorHandle.signal('receiveMessage', {
+                from: 'scheduler',
+                text: failureText,
+                isScheduled: true,
+                scheduleName,
+            });
+            return;
+        }
+        catch {
+            // creator signal failed, fall through to conductor
+        }
+    }
+    // Fallback: notify the conductor
+    try {
+        const conductorId = `claude-session-${ensemble}-conductor`;
+        const conductorHandle = client.workflow.getHandle(conductorId);
+        await conductorHandle.signal('receiveMessage', {
+            from: 'scheduler',
+            text: failureText,
+            isScheduled: true,
+            scheduleName,
+        });
+    }
+    catch {
+        // Nobody available to notify — logged by the workflow
+    }
+}
+/**
+ * Resolve a session by player name — mirrors src/tools/resolve.ts logic.
+ * We duplicate here because activities run in Node.js and need their own copy.
+ */
+async function resolveSession(client, ensemble, playerName) {
+    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+    for await (const wf of client.workflow.list({ query })) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            const metadata = await handle.query('getMetadata');
+            if (metadata.ensemble === ensemble && metadata.playerId === playerName) {
+                return handle;
+            }
+        }
+        catch {
+            // Workflow may have just completed — skip
+        }
+    }
+    return null;
+}

package/dist/cli/commands.d.ts

@@ -27,6 +27,7 @@ export declare function server(opts: ServerOpts): Promise<void>;
 interface UpOpts extends CliOverrides {
     ensemble: string;
     name?: string;
+    from?: string;
     agent: AgentType;
 }
 export declare function up(opts: UpOpts): Promise<void>;
@@ -44,6 +45,11 @@ interface StopOpts extends CliOverrides {
     all?: boolean;
 }
 export declare function stop(opts: StopOpts): Promise<void>;
+interface EnsembleCommandOpts extends CliOverrides {
+    subcommand?: string;
+    name?: string;
+}
+export declare function ensembleCommand(opts: EnsembleCommandOpts): Promise<void>;
 export declare function help(): void;
 export declare function version(): void;
 export {};