Task Management

Synapses provides a task system that persists across sessions. Agents can create plans, track progress, declare dependencies between tasks, and resume unfinished work — even after a session ends or crashes.

Creating a Plan

Use tasks(action="create_plan") to define a set of tasks:

{
  "tool": "tasks",
    "action": "create_plan",
  "arguments": {
    "plan": "Migrate authentication from sessions to JWT",
    "tasks": [
      {
        "id": "jwt-1",
        "title": "Create JWT utility package",
        "description": "Implement token generation, validation, and refresh in internal/auth/jwt.go"
      },
      {
        "id": "jwt-2",
        "title": "Update middleware to use JWT",
        "description": "Replace session checks with JWT validation in middleware chain",
        "depends_on": ["jwt-1"]
      },
      {
        "id": "jwt-3",
        "title": "Migrate existing sessions",
        "description": "Write migration script to convert active sessions to JWT tokens",
        "depends_on": ["jwt-1"]
      },
      {
        "id": "jwt-4",
        "title": "Update tests",
        "description": "Update all auth-related tests for JWT flow",
        "depends_on": ["jwt-2", "jwt-3"]
      }
    ]
  }
}

Tasks start in pending status. The depends_on field declares ordering constraints.

Updating Task Status

As work progresses, update tasks:

{
  "tool": "tasks",
    "action": "update",
  "arguments": {
    "task_id": "jwt-1",
    "status": "in_progress"
  }
}

{
  "tool": "tasks",
    "action": "update",
  "arguments": {
    "task_id": "jwt-1",
    "status": "done",
    "outcome": "Created internal/auth/jwt.go with Sign, Validate, Refresh functions"
  }
}

Available statuses: pending, in_progress, done, blocked, cancelled.

Task Dependencies

Dependencies prevent tasks from starting before their prerequisites are complete:

{
  "depends_on": ["jwt-1", "jwt-3"]
}

When you query pending tasks via session_init, Synapses marks tasks whose dependencies are not yet satisfied. Agents should work on tasks whose dependencies are all done.

Cross-Session Continuity

Tasks persist in Synapses’ SQLite store. When a new session starts:

{
  "tool": "session_init",
  "arguments": { "agent_id": "agent-42" }
}

The response includes all pending and in-progress tasks. The agent can pick up exactly where the previous session left off.

Saving Session State

For long-running tasks, checkpoint progress mid-session:

{
  "tool": "tasks",
  "arguments": {
    "action": "save_state",
    "agent_id": "agent-42",
    "state": {
      "current_task": "jwt-2",
      "files_modified": ["internal/middleware/auth.go"],
      "next_step": "Update the token extraction logic in extractBearerToken"
    }
  }
}

The next session_init with the same agent_id restores this state.

Git Commit Tracking

Link tasks to git commits for traceability:

{
  "tool": "tasks",
    "action": "update",
  "arguments": {
    "task_id": "jwt-1",
    "status": "done",
    "outcome": "Implemented JWT utility package",
    "commit": "a1b2c3d"
  }
}

This creates a link between the task and the commit, visible when reviewing task history.

Task-Linked Context Boost

When you call get_context or get_context(mode="intent") while a task is in_progress, entities related to that task receive a relevance boost. This means the context you get is naturally aligned with what you are working on.

// If task "jwt-2" is in_progress and involves internal/middleware/auth.go,
// then get_context queries will prioritize entities in that file and its
// direct relationships.
{
  "tool": "get_context",
  "arguments": {
    "query": "bearer token extraction",
    "intent": "modify"
  }
}
// → auth middleware entities are boosted in results

Querying Tasks

Get all pending tasks:

{
  "tool": "tasks",
  "arguments": {
    "action": "pending"
  }
}

This returns tasks with their status, dependencies, and whether they are ready to work on (all dependencies satisfied).

Example Workflow

Session 1:
  1. session_init(agent_id="migration")
  2. tasks(action="create_plan", plan="JWT migration", tasks=[jwt-1, jwt-2, jwt-3, jwt-4])
  3. tasks(action="update", task_id="jwt-1", status="in_progress")
  4. [implement JWT utility package]
  5. tasks(action="update", task_id="jwt-1", status="done", commit="a1b2c3d")
  6. tasks(action="update", task_id="jwt-2", status="in_progress")
  7. tasks(action="save_state", state={current_task: "jwt-2", next_step: "..."})
  8. end_session(summary="Completed JWT package, started middleware update")

Session 2:
  1. session_init(agent_id="migration")
     → Sees jwt-2 in_progress, jwt-3 pending (deps met), jwt-4 blocked
  2. [continue jwt-2 from saved state]
  3. tasks(action="update", task_id="jwt-2", status="done")
  4. tasks(action="update", task_id="jwt-3", status="in_progress")
  5. ...