# session_health_data — Collect Raw Session Health Data for Classification

**Script name:** `session_health_data`

**Script location:** [`scripts/session_health_data.ts`](../../../scripts/session_health_data.ts)

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_health_data.ts \
  [--message-limit N] [--server URL]
```

**CRITICAL:** Always invoke the script using bash and the format noted above. **Never** try to use the skill as a task, or invoke it through any other method than by directly calling bash with a command of the form listed above under "Invoke:".

## Synopsis

```
session_health_data.ts [--message-limit N] [--server URL]
```

Collects all sessions, their current `busy`/`idle` status, last-activity
timestamp, and recent message text. Returns all this raw data as a single JSON
array. This script **does not classify health states** — that interpretation
step is performed by the `async-agent-util` agent after receiving this data.

## Arguments

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--message-limit N` | integer | `15` | Max recent messages to fetch per session |
| `--server URL` | string | `http://localhost:4096` | OpenCode Server base URL |
| `-h`, `--help` | — | — | Print usage to stderr and exit 0 |

## Output

Written to **stdout** as a JSON array of `HealthDataEntry` objects, one per session:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Session ID |
| `title` | string | Full session title |
| `tag` | string \| null | Extracted `[TAG]`, or `null` for untagged sessions |
| `status` | string | `busy` or `idle` |
| `last_active` | number | Epoch ms of last session update |
| `recent_messages` | `FormattedMessage[]` | Last N messages (role, agent, text, time) |

## Health Classification (performed by the caller)

This script only provides the raw signals. The caller (`async-agent-util`'s
`health` operation) classifies each entry using these health states:

| State | Busy? | Meaning |
|-------|:-----:|---------|
| `healthy` | yes | Active, recent message activity within idle threshold |
| `stuck` | yes | No message activity for longer than idle threshold |
| `idle` | no | Paused mid-task, would resume if sent "continue" |
| `finished` | no | Completed its job, nothing remaining to do |
| `unhealthy` | any | Struggling with permissions/errors but finding poor workarounds |
| `errored` | any | Unresolvable error — cannot continue, needs intervention |

## Diagnostics / stderr

```
Fetching health data (last 15 msgs/session) from http://localhost:4096…
Found 5 session(s). Fetching recent messages…
Health data collected for 5 session(s).
```

Message fetches are performed concurrently (up to 10 in-flight at once).
A warning is written to stderr if a session's messages cannot be fetched;
that session's `recent_messages` will be an empty array in the output.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — JSON array written to stdout |
| 1 | Fatal error |

## When to Use This Script

This script is the **data-collection step** of the `health` operation in
`async-agent-util`. Call it when you need to provide an LLM with the raw
signals needed to classify session health states.

## Usage Examples

```bash
# Collect health data with default message limit (15)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_health_data.ts

# Collect health data with more message context (30 messages)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_health_data.ts \
  --message-limit 30

# Get just the status and tag for each session
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_health_data.ts \
  | jq '[.[] | {id, tag, status, last_active}]'

# List sessions with no recent messages (likely stuck or finished)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_health_data.ts \
  | jq '[.[] | select(.recent_messages | length == 0)]'
```

## Dependencies

- Node.js ≥ 18 (native `fetch` API)
- `npx tsx` for TypeScript execution
- Zero external npm packages
