puzzlebox

Coordinating agents with state machines

What problem does puzzlebox address?

Teams need coordination

• A large software project typically moves through a multi-step, occasionally backtracking path from inception to design to building to testing to documentation to marketing to production.

• Different teams are focused on different aspects over time, informed by what's gone before and with an eye toward an ever-changing goal that is refined according to lessons learned.

• Even within a phase, teams may cycle through their own phases, like Agile sprints. A certain amount of work is scoped for the sprint, the team works on their parts, and at the end of the sprint they decide what to tackle next. It accepts that each sprint could change the course of future development. These cycles can also be represented as puzzles.

Scenario: Teams passing the torch

• Agent 1 is specifying the domain language.

• Agent 2 is defining project scope.

• Agent 3 is producing the specification document.

• The agents collaborate to reach the final specification document.

• Once the spec is done, Agent 3 initiates a transition to "Design" state.

What is a puzzle?

A stateful thing you can act upon

Properties of a puzzle

• A finite number of discrete states, e.g., "Series Concept and Tone", "World Building", "Arc Plotting", "Episode Planning", "Plotline Blending", "Episode Outline", "Script Writing" etc.

• Each state may have any number of actions (including 0) that initiate transition to another state.

• There is an initial state.

• There is a current state that may differ after actions have been performed on the puzzle.

• Transitions can be canceled by state exit and enter guards, e.g., Consult LLM via client sampling request.

A Simple Example

What is puzzlebox?

Many clients sharing dynamic resources

• Supports multiple client connections that can create and monitor shared, dynamic resources.

• Manages puzzle instances

• Exposes tools for:

• Exposes registered puzzles as resources

How It Works

1. Clients connect to a puzzlebox SSE server.

2. Clients register puzzles with the server.

3. Clients can subscribe to a given puzzle to receive updates when its state changes.

4. Clients perform actions on puzzles that may change their state and available actions.

5. The puzzlebox server ensures that any attempted action is valid for the current state of the given puzzle.

6. If an action is valid, a transition to the target state is initiated.

7. During transition, optional exit and enter guards may send sampling requests to the client, the results of which could lead to cancellation of the transition (think acceptance testing by stakeholders)

8. If guards pass, the state transition completes.

9. When a client receives a resource updated notification, they can either read the resource or use the get_puzzle_snapshot tool to get the current state and available actions.

10. Clients update their UI based on the new state.

MCP Tools

**`add_puzzle`**

Add a new instance of a puzzle (finite state machine).

• Inputs: None

• Returns: JSON object with boolean success and puzzleId

**`get_puzzle_snapshot`**

Get a snapshot of a puzzle (its current state and available actions).

• Inputs: puzzleId

• Returns: JSON object with currentState and availableActions array

• Note: MCP clients that don't support resource subscriptions can poll this tool to watch for state changes.

**`perform_action_on_puzzle`**

Perform an action on a puzzle (attempt a state transition).

• Inputs: puzzleId and actionName

• Returns: JSON object with currentState and availableActions array

**`count_puzzles`**

Get the count of registered puzzles

• Inputs: None

• Returns: JSON object with current count of registered puzzles

Local Setup

Install Dependencies

• cd /path/to/puzzlebox/

• npm install

Build

• npm run build

• Builds the MCP server runtime at /dist/index.js

Start

• npm run start

• Launches an SSE-based/MCP server on port :3001 with endpoint /sse

• MUST BE LAUNCHED BEFORE RUNNING INSPECTOR

Inspector

• npm run inspector

• Runs the Model Context Protocol Inspector

• The Inspector UI will be available at: http://localhost:5173

• In the Inspector UI:

Format

• npm run format

• Runs prettier on the code, adjusting formatting

Typecheck

• npm run typecheck

• Runs tsc with args to check and report type issues

Lint

• npm run lint

• Runs eslint to non-destructively check for and report syntax problems

LintFix

• npm run lint:fix

• Runs eslint to check for and fix syntax problems

Test

• npm run test

• Run the unit tests

Screenshots

0 - List Tools

1 - Add Puzzle

2 - Get Puzzle Snapshot (Initial State)

3 - Perform Action On Puzzle

4 - Get Puzzle Snapshot (New State)

5 - Perform Action On Puzzle

6 - Get Puzzle Snapshot (Another New State)

7 - List Resources

8 - Resource Template

9 - Unsubscribed Resource

10 - Subscribed Resource

11 - Resource Updated Notification

puzzlebox

Coordinating agents with state machines

What problem does puzzlebox address?

Teams need coordination

• A large software project typically moves through a multi-step, occasionally backtracking path from inception to design to building to testing to documentation to marketing to production.

• Different teams are focused on different aspects over time, informed by what's gone before and with an eye toward an ever-changing goal that is refined according to lessons learned.

• Even within a phase, teams may cycle through their own phases, like Agile sprints. A certain amount of work is scoped for the sprint, the team works on their parts, and at the end of the sprint they decide what to tackle next. It accepts that each sprint could change the course of future development. These cycles can also be represented as puzzles.

Scenario: Teams passing the torch

• Agent 1 is specifying the domain language.

• Agent 2 is defining project scope.

• Agent 3 is producing the specification document.

• The agents collaborate to reach the final specification document.

• Once the spec is done, Agent 3 initiates a transition to "Design" state.

What is a puzzle?

A stateful thing you can act upon

Properties of a puzzle

• A finite number of discrete states, e.g., "Series Concept and Tone", "World Building", "Arc Plotting", "Episode Planning", "Plotline Blending", "Episode Outline", "Script Writing" etc.

• Each state may have any number of actions (including 0) that initiate transition to another state.

• There is an initial state.

• There is a current state that may differ after actions have been performed on the puzzle.

• Transitions can be canceled by state exit and enter guards, e.g., Consult LLM via client sampling request.

A Simple Example

What is puzzlebox?

Many clients sharing dynamic resources

• Supports multiple client connections that can create and monitor shared, dynamic resources.

• Manages puzzle instances

• Exposes tools for:

• Exposes registered puzzles as resources

How It Works

1. Clients connect to a puzzlebox SSE server.

2. Clients register puzzles with the server.

3. Clients can subscribe to a given puzzle to receive updates when its state changes.

4. Clients perform actions on puzzles that may change their state and available actions.

5. The puzzlebox server ensures that any attempted action is valid for the current state of the given puzzle.

6. If an action is valid, a transition to the target state is initiated.

7. During transition, optional exit and enter guards may send sampling requests to the client, the results of which could lead to cancellation of the transition (think acceptance testing by stakeholders)

8. If guards pass, the state transition completes.

9. When a client receives a resource updated notification, they can either read the resource or use the get_puzzle_snapshot tool to get the current state and available actions.

10. Clients update their UI based on the new state.

MCP Tools

**`add_puzzle`**

Add a new instance of a puzzle (finite state machine).

• Inputs: None

• Returns: JSON object with boolean success and puzzleId

**`get_puzzle_snapshot`**

Get a snapshot of a puzzle (its current state and available actions).

• Inputs: puzzleId

• Returns: JSON object with currentState and availableActions array

• Note: MCP clients that don't support resource subscriptions can poll this tool to watch for state changes.

**`perform_action_on_puzzle`**

Perform an action on a puzzle (attempt a state transition).

• Inputs: puzzleId and actionName

• Returns: JSON object with currentState and availableActions array

**`count_puzzles`**

Get the count of registered puzzles

• Inputs: None

• Returns: JSON object with current count of registered puzzles

Local Setup

Install Dependencies

• cd /path/to/puzzlebox/

• npm install

Build

• npm run build

• Builds the MCP server runtime at /dist/index.js

Start

• npm run start

• Launches an SSE-based/MCP server on port :3001 with endpoint /sse

• MUST BE LAUNCHED BEFORE RUNNING INSPECTOR

Inspector

• npm run inspector

• Runs the Model Context Protocol Inspector

• The Inspector UI will be available at: http://localhost:5173

• In the Inspector UI:

Format

• npm run format

• Runs prettier on the code, adjusting formatting

Typecheck

• npm run typecheck

• Runs tsc with args to check and report type issues

Lint

• npm run lint

• Runs eslint to non-destructively check for and report syntax problems

LintFix

• npm run lint:fix

• Runs eslint to check for and fix syntax problems

Test

• npm run test

• Run the unit tests

Screenshots

0 - List Tools

1 - Add Puzzle

2 - Get Puzzle Snapshot (Initial State)

3 - Perform Action On Puzzle

4 - Get Puzzle Snapshot (New State)

5 - Perform Action On Puzzle

6 - Get Puzzle Snapshot (Another New State)

7 - List Resources

8 - Resource Template

9 - Unsubscribed Resource

10 - Subscribed Resource

11 - Resource Updated Notification