# session_messages — Retrieve and Format Messages From an OpenCode Session

**Script name:** `session_messages`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_messages.ts \
  --session-id ID [--limit N] [--raw] [--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_messages.ts --session-id ID [--limit N] [--raw] [--server URL]
```

Fetches the message history for a single session. By default returns all
messages as `FormattedMessage` objects (role, agent, joined text, timestamp).
Use `--limit N` to restrict to the last N messages, and `--raw` to return the
full API message objects instead of the formatted subset.

## Arguments

### Required

| Flag | Type | Description |
|------|------|-------------|
| `--session-id ID` | string | Target session ID (e.g. `ses_abc123`) |

### Optional

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit N` | integer | (none — all) | Return only the last N messages |
| `--raw` | flag | false | Output full Message objects instead of FormattedMessage |
| `--server URL` | string | `http://localhost:4096` | OpenCode Server base URL |
| `-h`, `--help` | — | — | Print usage to stderr and exit 0 |

## Output

**Default** (formatted): JSON array of `FormattedMessage` objects:

| Field | Type | Description |
|-------|------|-------------|
| `role` | string | `user` or `assistant` |
| `agent` | string \| undefined | Agent name, or `undefined` for user messages |
| `text` | string | All text parts joined into a single string |
| `time` | number | Epoch ms of message creation |

**With `--raw`**: JSON array of full `Message` API objects with `info` and `parts` fields.

## Diagnostics / stderr

```
Fetching last 10 message(s) from ses_abc123…
Retrieved 10 message(s).
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — JSON array written to stdout |
| 1 | Fatal error (missing arg or API failure) |

## When to Use This Script

- **Monitor agent progress:** retrieve the last few messages to see what an
  agent has been doing recently.
- **Detect completion or errors:** scan recent messages for completion signals
  or error patterns.
- **Feed context to the `health` operation:** the `async-agent-util` agent
  calls `session_health_data.ts` (which wraps this script) to collect message
  context for health classification.

## Usage Examples

```bash
# Get all messages from a session
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_messages.ts \
  --session-id ses_abc123

# Get the last 5 messages
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_messages.ts \
  --session-id ses_abc123 \
  --limit 5

# Get raw API message objects (includes tool_call, tool_result parts)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_messages.ts \
  --session-id ses_abc123 \
  --limit 10 \
  --raw

# Extract just the text content of the most recent assistant message
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_messages.ts \
  --session-id ses_abc123 \
  --limit 10 \
  | jq 'last(.[] | select(.role == "assistant")) | .text'
```

## Dependencies

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