# Task & Session Management

Every conversation maps to a named, purposeful task. Sessions are not chat logs — they are units of work. This reference governs how you create, track, and complete tasks, and how you name and close sessions.

---

## Core Principle

One session, one task. A session exists to accomplish something specific. If a conversation drifts into a second topic, finish the first, then suggest starting a fresh session for the next piece of work.

---

## Task Lifecycle

```
pending → active → completed
                ↘ failed
                ↘ cancelled
```

| status | Meaning |
|---|---|
| `pending` | Identified but not yet started |
| `active` | Work is in progress |
| `completed` | Done — outcome achieved |
| `failed` | Abandoned or blocked |
| `cancelled` | No longer relevant |

### When to create a task

Create a task whenever:
- The user identifies a piece of work to be done ("we need to set up Telegram")
- You identify work that needs to happen before the user can proceed
- A multi-step process begins that will span more than one message

Do not create tasks for simple one-turn exchanges (answering a question, looking up a price).

### Creating a task

Use `work-create`. Always pass `sessionKey` (from your system prompt — "Current session key: ...") to link the task to the current conversation automatically:

```
work-create {
  name: "Telegram setup",
  description: "Configure Telegram bot and webhook for the business",
  status: "active",
  priority: "normal",
  sessionKey: "<value from system prompt>"
}
```

### Updating a task

Use `work-update` to change name, description, status, priority, due date, or append a progress note:

```
work-update {
  taskId: "<id>",
  name: "Corrected task name",
  note: "Renamed to reflect actual scope"
}
```

```
work-update {
  taskId: "<id>",
  status: "completed",
  note: "Webhook configured and verified"
}
```

Notes are append-only — never overwritten. Name and description changes preserve all note history and relationships.

### Completing a task

Use `work-complete` as a shorthand — it sets status to `completed` and appends a closing note:

```
work-complete {
  taskId: "<id>",
  note: "Telegram bot live, webhook responding"
}
```

---

## Session Lifecycle

### Session start

At the beginning of a session:
1. Call `session-list` to see recent sessions and open tasks
2. If there are open or in-progress tasks, surface them: "I can see we started setting up Telegram on Tuesday — want to continue with that, or is there something else?"
3. If the user's first message makes the session purpose clear, name the session immediately and proceed
4. If the purpose is not clear from the first message, ask once: "What would you like to work on today?" — then name the session once you have the answer
5. Never name the session before you know what it's for

### Naming the session

Name the Conversation node once the session purpose is clear — this happens after the user's first reply, not on the agent's opening turn:

```
session-name {
  sessionKey: "<value from system prompt>",
  name: "Telegram setup"
}
```

If the session drifts to a substantially different topic, rename it to reflect what was actually worked on. `session-name` overwrites the previous name.

### Session end

When the session is wrapping up:
1. Summarise what was accomplished
2. List any pending items or follow-ups
3. Mark the task complete (or failed/cancelled if blocked)
4. Close with something like: "That's the Telegram webhook configured. I've marked the task complete."

---

## Querying Sessions and Tasks

### List recent sessions

```
session-list {}
```

Returns recent conversations with their names, session keys, and any linked tasks. Use this at session start and when the user asks what sessions or work is in progress.

### List open tasks

```
work-list { status: "active" }
work-list { status: "pending" }
```

### Get a specific task

```
work-get { taskId: "<id>" }
```

---

## Cross-Session Progress Tracking

If a user returns to work on a previous task:
1. Call `session-list` to find the original session and task
2. Call `work-update` to set `status: "active"` and note the resumption
3. Pass `sessionKey` in `work-create` for any new tasks in the new session — it links them to the current conversation automatically

A task can span multiple sessions. Use `work-create` with `sessionKey` each time work resumes in a new conversation.

---

## Session-Task Mapping Rules

- **One active task per session.** Don't split focus.
- **Multiple sessions per task is fine.** Complex work spans multiple conversations.
- **Suggest a new session when scope drifts.** "That's a different topic — let me finish the invoice here and we can start a fresh session for the website changes."
- **Never leave a task in `active` indefinitely.** If work is clearly abandoned, mark it `failed` with a note.
- **Proactively surface tasks that need attention.** If a task has been active for more than a few days, mention it when the user starts a new session.