ulysses-protocol

Ulysses Protocol

Ulysses is a Thoughtbox-owned debugging protocol.

The invariants live in the server-side Ulysses implementation behind tb.ulysses(...). The durable trace lives in Thoughtbox thoughts and knowledge. Codex hooks only enforce the current server state.

Do not use .ulysses/ files or scripts/ulysses.sh as authoritative state. Do not use legacy direct handles like thoughtbox_gateway or thoughtbox_ulysses as the interaction surface when Code Mode is available.

API Surface

The current public Thoughtbox MCP surface is Code Mode:

• Discovery: thoughtbox_search
• Execution: thoughtbox_execute
• Ulysses operations: tb.ulysses({ ... })
• Validator notebook setup: tb.notebook.create(...) and tb.notebook.addCell(...)

Each thoughtbox_execute call should contain at most one state-mutating Ulysses operation. Read-only confirmation calls such as tb.ulysses({ operation: "status" }) are safe to use for state checks.

Example execution wrapper:

async () => {
  return await tb.ulysses({
    operation: "status",
  });
}

Runtime Contract

1. Protocol entry is explicit-only in v1.
2. If you need schema or example confirmation, call thoughtbox_search before executing.
3. Use thoughtbox_execute and call tb.ulysses({ operation: ... }) for every protocol transition.
4. Hooks may block mutating work when the server reports S=2; read-only inspection remains allowed.
5. Helper agents may gather evidence after reflect, but only the coordinator calls tb.ulysses.

Commands

init

Required inputs:

• Problem statement
• Optional constraints

Call:

async () => {
  return await tb.ulysses({
    operation: "init",
    problem: "<problem>",
    constraints: ["<optional constraint>"],
  });
}

Then record a structured Thoughtbox thought summarizing the debugging context.

plan

Required inputs:

• Primary action
• Recovery action
• Primary validator: a notebook code cell that decides the primary step's outcome
• Recovery validator: a notebook code cell that decides the recovery step's outcome
• Optional irreversible