Todo Plugin

from jaato import PluginRegistry

registry = PluginRegistry()
registry.discover()

# Expose todo plugin with defaults
registry.expose_tool('todo')

# With custom configuration
registry.expose_tool('todo', config={
    'reporter_type': 'console',
    'storage_type': 'file',
    'storage_path': '.jaato/plans.json',
})

# 1. Create the plan
createPlan(
    title="Refactor auth module",
    steps=[
        "Review current auth implementation",
        "Extract token validation to separate module",
        "Add unit tests for new module",
        "Update imports in dependent files"
    ]
)

# 2. Request user approval
startPlan(message="Ready to proceed?")

# 3. Report progress on each step
setStepStatus(step_id="step_1", status="completed")
setStepStatus(step_id="step_2", status="in_progress")

# 4. Complete the plan
completePlan(status="completed", summary="Refactoring done")

# Console reporter with file storage
registry.expose_tool('todo', config={
    'reporter_type': 'console',
    'storage_type': 'file',
    'storage_path': '.jaato/plans.json',
})

# Webhook reporter for remote monitoring
registry.expose_tool('todo', config={
    'reporter_type': 'webhook',
    'reporter_config': {
        'url': 'https://api.example.com/plans',
        'headers': {'Authorization': 'Bearer token'},
    },
})

# File reporter for log-based tracking
registry.expose_tool('todo', config={
    'reporter_type': 'file',
    'reporter_config': {
        'path': '/var/log/jaato/plans.log',
    },
})

{
  "reporter_type": "console",
  "storage_type": "file",
  "storage_path": ".jaato/plans.json"
}

{
  "plan_id": "plan_abc123",
  "title": "Refactor auth module",
  "status": "pending",
  "steps": [
    {"id": "step_1", "description": "Review current auth...", "status": "pending"},
    {"id": "step_2", "description": "Extract token...", "status": "pending"},
    {"id": "step_3", "description": "Add unit tests...", "status": "pending"},
    {"id": "step_4", "description": "Update imports...", "status": "pending"}
  ],
  "message": "Plan created. Call startPlan to request approval."
}

{
  "plan_id": "plan_abc123",
  "title": "Refactor auth module",
  "status": "in_progress",
  "progress": {
    "completed": 2,
    "total": 4,
    "percentage": 50
  },
  "steps": [
    {"id": "step_1", "status": "completed", "result": "..."},
    {"id": "step_2", "status": "completed", "result": "..."},
    {"id": "step_3", "status": "in_progress"},
    {"id": "step_4", "status": "pending"}
  ]
}

> plan

Current Plan: Refactor auth module
Status: in_progress

Steps:
  [x] step_1: Review current auth implementation
  [x] step_2: Extract token validation to separate module
  [>] step_3: Add unit tests for new module
  [ ] step_4: Update imports in dependent files

Progress: 2/4 (50%)

# Correct: Step fully achieved
setStepStatus(
    step_id="step_1",
    status="completed",
    result="Found 3 auth-related files: auth.py, tokens.py, session.py"
)

# Correct: Step failed
setStepStatus(
    step_id="step_2",
    status="failed",
    error="Could not find token validation logic in expected location"
)

# Correct: Step became unnecessary
setStepStatus(
    step_id="step_3",
    status="skipped",
    result="Tests already exist, no need to add more"
)

# WRONG: Marking partial success as completed
setStepStatus(
    step_id="step_4",
    status="completed",  # Should be "failed"!
    result="Unable to update 2 of 5 imports due to circular dependencies"
)

# === PARENT AGENT ===

# 1. Subscribe to events BEFORE spawning subagents
#    (subscribeToEvents is a session-level core tool, not a todo tool)
subscribeToEvents(
    event_types=['plan_created', 'step_completed']
)

# 2. Create your master plan (include a step for awaiting results)
createPlan(title="Main Task", steps=[
    "Spawn implementer",
    "Await and integrate results",  # will get dependency added
])
startPlan()

# 3. Spawn subagent (subagent creates its own plan)
# ... spawn_subagent('implementer', task="...")

# 4. When you see plan_created event, link existing step to subagent work
addDependentStep(
    step_id="",  # existing step in YOUR plan
    depends_on=[
        {"agent_id": "implementer", "step_id": "final_step"}
    ]
)
# → Your existing step is now BLOCKED

# 5. Wait... step auto-unblocks when subagent completes

# 6. Check received outputs
status = getPlanStatus()
# status.steps[await_step].received_outputs = {'implementer:final_step': {...}}

# === SUBAGENT ===

# Complete the step WITH structured output
completeStepWithOutput(
    step_id="final_step",
    output={
        "passed": True,
        "results": ["file1.py created", "tests pass"],
        "errors": []
    },
    result="Implementation completed successfully"
)
# → Parent's dependent step auto-unblocks
# → Output delivered to parent's received_outputs

{
  "step_id": "step_abc123",
  "sequence": 2,
  "description": "Review implementation results",
  "status": "blocked",
  "blocked_by": [
    {"agent_id": "implementer", "step_id": "final_step"}
  ],
  "message": "Step added with 1 dependencies (BLOCKED)"
}

{
  "blocked_steps": [
    {
      "step_id": "step_abc123",
      "description": "Review implementation results",
      "blocked_by": [
        {"agent_id": "implementer", "step_id": "final_step"}
      ],
      "received_outputs": {}
    }
  ],
  "count": 1
}

{
  "blocked_steps": [],
  "message": "No blocked steps"
}

// Step status in getPlanStatus:
{
  "step_id": "step_abc123",
  "status": "pending",  // Was "blocked", now ready
  "received_outputs": {
    "implementer:final_step": {
      "passed": true,
      "results": ["file1.py created"]
    }
  }
}