# session_prompt — Send a Prompt to an Existing OpenCode Session

**Script name:** `session_prompt`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_prompt.ts \
  --session-id ID --agent AGENT (--prompt TEXT | --prompt-file PATH) [--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_prompt.ts --session-id ID --agent AGENT (--prompt TEXT | --prompt-file PATH)
```

Sends a prompt to a session that **already exists**, without creating a new one.
Uses `POST /session/{id}/prompt_async` (fire-and-forget) and returns immediately.

The canonical use case is the **"send continue"** pattern: when a supervisor or
worker is `idle` but healthy (it paused mid-task and needs a nudge), send it
`"continue"` to resume operation. It is also used to send any other follow-up
message to an ongoing session.

**This is distinct from `session_start.ts`**, which creates a new session before
sending a prompt. Use `session_prompt.ts` when you already have a `session_id`
and want to send to that specific session.

## Arguments

### Required

| Flag | Type | Description |
|------|------|-------------|
| `--session-id ID` | string | Target session ID (e.g. `ses_abc123`) |
| `--agent AGENT` | string | Agent definition name to invoke (e.g. `pr-merge-supervisor`) |
| `--prompt TEXT` | string | Prompt text to send (ideal for short strings like `"continue"`) |
| `--prompt-file PATH` | string | Path to file containing prompt text (preferred for long prompts) |

Exactly one of `--prompt` or `--prompt-file` is required.

### Optional

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--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 object:

```json
{
  "session_id": "ses_abc123",
  "agent": "pr-merge-supervisor",
  "sent": true,
  "message": "Prompt sent to session ses_abc123 via agent \"pr-merge-supervisor\""
}
```

## Diagnostics / stderr

```
Sending prompt to session ses_abc123 (agent: pr-merge-supervisor)…
Prompt sent (prompt_async returned 204).
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Prompt sent successfully |
| 1 | Missing required arg or API error (session not found, server unreachable) |

## Common Use Cases

### Nudge an idle-but-healthy supervisor

When `session_health_data.ts` + health classification identifies a session as
`idle` (not busy, but paused mid-task), send it `"continue"`:

```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_prompt.ts \
  --session-id ses_abc123 \
  --agent pr-merge-supervisor \
  --prompt "continue"
```

### Send follow-up instructions to a worker

```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_prompt.ts \
  --session-id ses_def456 \
  --agent task-implementor \
  --prompt "The CI failure is in the auth module, focus there."
```

### Send a complex follow-up from a file

```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_prompt.ts \
  --session-id ses_abc123 \
  --agent implementation-supervisor \
  --prompt-file /tmp/followup-instructions.txt
```

## When to Use This Script vs `session_start.ts`

| Scenario | Use |
|----------|-----|
| Session exists, send a follow-up or nudge | `session_prompt.ts` |
| Session does not exist yet, need to create and launch | `session_start.ts` |
| Session exists but want to restart with fresh context | `session_start.ts --restart` |

## Dependencies

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