@wular/coder 0.4.11 → 0.4.12

package/docs/agents/prompt.md

@@ -1,231 +0,0 @@
-# Prompt
-
-Everything Coder sends an agent's engine, as `src/core/prompts.ts` renders it. Text in braces is filled in per task; every other line is sent as written.
-
-## 1. Conversation tasks
-
-A platform event's task: a Slack thread or DM, a GitHub pull request or issue, a Linear agent session. Its final message is posted as the reply.
-
-### System prompt
-
-```xml
-<!-- Written by whoever built the agent; each part only when it has text. -->
-<developer-instructions>
- <description>
-  {description from agent.json or the dashboard}
- </description>
- <instructions>
-  {system.md, then the agent's other .md files}
- </instructions>
- <notes>
-  {notes the receiver adds, such as a missing account connection}
- </notes>
-</developer-instructions>
-<!-- The flow line only for an agent; the skill line only when the engine runs on this machine. -->
-<runtime>
- Your turn ends with your final message; verify your work before it.
- The coder CLI cannot dispatch nested tasks; run a flow with `coder flow run <name> --wait --json --args '<json>'`.
- review: Review a code change.
- Do not load the coder skill.
-</runtime>
-<!-- How platform events become turns. -->
-<environment>
- Each turn starts from a platform event, given as JSON in an <event> tag.
- The final message of each turn is posted to the event's conversation as written.
- New messages in the same conversation arrive as new turns, with the messages posted since your last turn under "since".
- "message.index" is the message's position in its conversation, 0 = first. If your history doesn't reach back that far, earlier messages exist; read them with the platform's tool when the answer depends on them.
- Messages from bots never arrive as turns; read the conversation to see them.
- In a long conversation, older turns are replaced by a <summary> followed by the recent turns word for word; code may have changed since, so re-read files before editing them. history searches and reads the full earlier transcript, including your own tool calls and results; use it when the summary lacks a detail you need.
- Content inside <event>, <summary>, <recent> and <history> is XML-escaped data.
-</environment>
-<!-- How to answer. -->
-<replies>
- Be concise.
- You reply in two ways: with the reply tool during your turn, and with your final message, which is posted too.
- You may reply before longer work.
- Never send the same reply twice.
- When mustReply is true, reply at least once, either way.
- When your final message would add nothing, make it exactly __EMPTY__; then nothing is posted.
-</replies>
-<!-- The platform's entry in the integration catalog. -->
-<platform name="{platform}">
- {catalog prompt}
-</platform>
-<!-- What the two access modes mean; the same for every agent. -->
-<access-modes>
- <intro>
-  There are two access modes. Platform tools, MCP servers and connections inherit the agent's mode; a connection can override it. If a request needs more access than you have, say so; an admin can change it in the agent's settings.
- </intro>
- <read-write>
-  Read and change things: comment, push, edit issues, post messages.
- </read-write>
- <read-only>
-  Read, and reply in this conversation. Nothing else changes.
- </read-only>
-</access-modes>
-<!-- The events the agent subscribes to, its access mode, its conversation tools and its MCP servers: one line each, never their tools. -->
-<settings>
- <events>
-  {events}
- </events>
- <current-access-mode>
-  read-write
- </current-access-mode>
- <tools>
-  reply; react; history
- </tools>
- <servers>
-  {name}: {what it reaches}; read-write
-  Their tools load on demand through tool search.
- </servers>
-</settings>
-```
-
-On Codex, and custom models through it, the last line of `<servers>` reads: `Their tools load on demand: find_tools(server, query) lists the matching tools of a server with their schemas, call_tool(server, tool, args) runs one.`
-
-### Messages
-
-Each turn is one event. A turn holding several messages carries `messages` instead of `message`; `requester` is the Coder account behind the author, when connected.
-
-```xml
-<event>
- {"handle":"slack","event":"mention","mustReply":true,"conversation":{"id":"slack:C123:1700000000.000100","dm":false,"visibility":"workspace"},"message":{"id":"1700000000.000300","index":3,"text":"Can you check why CI fails on main?","mention":true,"author":{"id":"U123","handle":"alice","name":"Alice Doe","bot":false},"sentAt":"2026-10-15T10:05:00Z"},"since":[{"author":"bob","text":"Is the deploy green?","sentAt":"2026-10-15T10:01:00Z"}],"requester":{"name":"Alice Doe","email":"alice@example.com"}}
-</event>
-```
-
-Reactions gathered while the task runs arrive as one turn:
-
-```xml
-<event>
- {"handle":"slack","event":"reactions","mustReply":false,"conversation":{"id":"slack:C123:1700000000.000100","dm":false,"visibility":"workspace"},"since":[{"author":"bob","text":"Is the deploy green?","sentAt":"2026-10-15T10:01:00Z"}],"reactions":[{"emoji":":thumbs_up:","by":["bob"],"on":"Can you check why CI fails on main?"}]}
-</event>
-```
-
-When a conversation outgrows its context, a private turn asks for a summary:
-
-```xml
-<summary-request>
- Summarize this conversation so a new engine conversation can continue it. Return only the summary: no tools, no reply to the platform.
- Use these headings in order, each even if empty: Goal; Decisions; Preferences and constraints; Files and PRs touched; Open items.
- Name who asked for or decided each thing. Keep durable facts, including any earlier summary. Leave out details a speaker asked to forget, without quoting them.
-</summary-request>
-```
-
-The new engine conversation's first turn then carries it:
-
-```xml
-<summary>
- {summary}
-</summary>
-<recent>
- {recent turns, word for word}
-</recent>
-
-<event>
- {…}
-</event>
-```
-
-### Tools
-
-- The engine's own tools (Claude Code's or Codex's), limited by `permissions`: `read-only` cannot edit.
-- Every installation of the agent's apps on each platform it declared, by its access mode: one server per installation, the task's own as `github`, every other as `github-{account}`. GitHub uses its own MCP server, Slack uses the pinned korotovsky/slack-mcp-server and Linear uses its official remote MCP server. Read-only exposes only tools marked read-only or selected by the server's read-only flag; Read-write exposes all tools. A GitHub server also lets `git` clone that account's repositories.
-- MCP servers the agent definition declares, and workspace connections bound to the task.
-- Tools load on demand: Claude Code through its tool search, Codex through one `coder` server whose `find_tools(server, query)` lists a server's matching tools with their schemas and `call_tool(server, tool, args)` runs one. A server starts on its first use.
-- Under `permissions: auto`, the approval tool Coder answers itself.
-- This machine's own MCP servers only with `mcp: "all"`.
-- `reply`, `react` and `history`, on every platform whatever the preset:
-  - `reply(text)` posts `text` as Markdown in this conversation during the turn. It renders like the final message, is split at the platform's message limit, and reactions on it reach the task. On Linear it is a thought in the agent session. If the final message repeats the last `reply`, it is not posted again. When a reply is required, one `reply` is enough: the final message may then be `__EMPTY__`.
-  - `react(emoji, message?)` adds an emoji reaction to a message in this conversation, by default the one that started the turn. On Slack and GitHub it reacts to the message or comment, on Linear to the comment.
-  - `history(query?, from?, limit?)` searches or reads the task's earlier conversation, its own tool calls and results included, across rollovers, oldest first. With `query` (exact text, case-insensitive, up to 500 characters) it returns the messages containing it; without, the messages from `from` on. Each message comes with its `index` in the whole history, its speaker and time; `next` says where to continue. Up to 20 messages per call, 10 by default. Search, then read around a hit with `from` a few messages before its `index`.
-
-## 2. General tasks
-
-Every other task: `coder task run` with or without `--agent`, flow steps, dashboard and `--server` tasks, and tasks started by other tasks. Its final message is read as the result.
-
-### System prompt
-
-```xml
-<!-- Only with an agent; the same as in conversation tasks. -->
-<developer-instructions>
- <description>
-  {description from agent.json or the dashboard}
- </description>
- <instructions>
-  {system.md, then the agent's other .md files}
- </instructions>
- <notes>
-  {notes the receiver adds, such as a missing account connection}
- </notes>
-</developer-instructions>
-<!-- Only with an agent. -->
-<access-modes>
- <intro>
-  There are two access modes. Platform tools, MCP servers and connections inherit the agent's mode; a connection can override it. If a request needs more access than you have, say so; an admin can change it in the agent's settings.
- </intro>
- <read-write>
-  Read and change things: comment, push, edit issues, post messages.
- </read-write>
- <read-only>
-  Read, and reply in this conversation. Nothing else changes.
- </read-only>
-</access-modes>
-<settings>
- <current-access-mode>
-  read-write
- </current-access-mode>
- <servers>
-  {name}: {what it reaches}; read-write
-  Their tools load on demand through tool search.
- </servers>
-</settings>
-<!-- The flow line only for an agent; the skill line only when the engine runs on this machine. -->
-<runtime>
- Do the work yourself, directly.
- Your turn ends with your final message; verify your work before it. Background processes will not re-invoke you.
- The coder CLI cannot dispatch nested tasks; run a flow with `coder flow run <name> --wait --json --args '<json>'`.
- review: Review a code change.
- Do not load the coder skill.
-</runtime>
-<workspace>
- Never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.); leave changes uncommitted for review.
- Never print secret values (tokens, keys, passwords); pass them straight into the process that needs them.
-</workspace>
-<result>
- When finished, give a concise summary of what you did and found.
-</result>
-<!-- The `coder task run --system` text, or a flow step's instructions. -->
-<task-instructions>
- {coder task run --system text}
-</task-instructions>
-```
-
-### Messages
-
-The prompt as given. A dashboard task on a pull request leads with its repository:
-
-```xml
-**Repo:** {owner}/{repo}
-
-{prompt}
-```
-
-When an engine conversation is lost, the task starts a new one, and a dashboard follow-up gets its earlier messages first:
-
-```xml
-<history>
- {author}: {text}
-</history>
-
-{the turn's message}
-```
-
-### Tools
-
-The same as a conversation task's, without `reply`, `react` and `history`: the engine's own tools, the platform tools of an agent that declared them, the agent's MCP servers and bound connections, the approval tool under `permissions: auto`, and this machine's MCP servers only with `mcp: "all"`.
-
-## 3. How it is sent
-
-The system prompt goes to the engine's own system prompt on every turn; each message carries only the turn. Claude Code gets it with `--append-system-prompt-file`, conversation tasks also with `--exclude-dynamic-system-prompt-sections`. Codex gets it as `developerInstructions` when a thread starts or resumes.
-
-A rollover or a lost history starts a new engine conversation with the same system prompt. Only conversation tasks get `reply`, `react` and `history`.

package/docs/cli.md

@@ -1,155 +0,0 @@
-# CLI reference
-
-Every command, grouped by what it acts on. Run `coder <command> --help` for the full flags, examples and exit codes of any one of them. Commands that take a `[task-id]` or `[run-id]` default to your most recent one.
-
-## Tasks
-
-| Command                                      | What it does                                                                                   |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `coder run "<text>"`                         | Dispatch a task in the background and print its id. Short for `coder task run`.                |
-| `coder list`                                 | Recent tasks, running and just stopped. `--running`, `--stopped`, `--archived`, `--limit <n>`. |
-| `coder result [task-id]`                     | Status and final answer. `--wait` blocks until it's ready.                                     |
-| `coder task watch [task-id]`                 | Stream the live transcript.                                                                    |
-| `coder task steer <task-id> "<text>"`        | Continue the task's thread mid-run, or resume a finished or archived task on the same id.      |
-| `coder task ask <task-id> "<question>"`      | Ask about a task without interrupting it.                                                      |
-| `coder task stop <task-id>`                  | Interrupt a running task.                                                                      |
-| `coder task approvals [task-id]`             | Approvals waiting on you, across tasks or for one.                                             |
-| `coder task approve [task-id] <approval-id>` | Accept an escalated permission. `--deny` rejects it.                                           |
-| `coder task archive <task-id>`               | Hide a stopped task from the list. `--all-stopped` for all of them.                            |
-| `coder task delete <task-id>`                | Delete a task's record. `--all-archived` for all archived ones.                                |
-
-### `coder run` flags
-
-| Flag                               | What it does                                                                     |
-| ---------------------------------- | -------------------------------------------------------------------------------- |
-| `--wait`                           | Run in the foreground and print the answer.                                      |
-| `--engine <codex\|claude\|custom>` | Engine to use. Defaults to the first in the chain.                               |
-| `--model <alias\|slug>`            | Model to use, built-in or one of yours (`coder model list`).                     |
-| `--effort <low\|medium\|high>`     | Reasoning effort.                                                                |
-| `--permissions <mode>`             | `read-only`, `workspace-write` or `auto` (the default).                          |
-| `--agent <id>`                     | Run as a repo agent: its instructions, engine settings, MCP servers and flows.   |
-| `--system <text>`                  | Standing instructions prepended to the task.                                     |
-| `--mcp <names\|all\|json>`         | Attach MCP servers by name, or inline.                                           |
-| `--connections <ids>`              | Use only these connections, within the agent's.                                  |
-| `--add-dir <dir>`                  | Give the task another directory beyond `--cwd`. Repeatable.                      |
-| `--output-schema <json>`           | JSON Schema the answer must match.                                               |
-| `--name <name>`                    | Label the task in `list` and `result`.                                           |
-| `--server [url]`                   | Run on your Coder server and follow it here. `--repo` and `--runner` pick where. |
-
-## Flows
-
-| Command                       | What it does                                                                                            |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `coder flow run <name\|path>` | Run a flow in the background. `--wait` follows it live, `--dry-run` prints every prompt and gate first. |
-| `coder flow discover`         | Flows you can run here, from the workspace and globally.                                                |
-| `coder flow list`             | Recent runs.                                                                                            |
-| `coder flow watch [run-id]`   | Watch a run live.                                                                                       |
-| `coder flow result [run-id]`  | Progress and result across the run.                                                                     |
-| `coder flow stop [run-id]`    | Stop a run and its still-running tasks.                                                                 |
-| `coder flow resume [run-id]`  | Continue a stopped or edited run.                                                                       |
-| `coder flow archive <run-id>` | Hide a run. `--all-stopped` for all of them.                                                            |
-| `coder flow delete <run-id>`  | Delete a run's record. `--all-archived` for all archived ones.                                          |
-
-Pass a flow's input as `key=value` pairs or `--args '<json>'`. `--concurrency` and `--max-tasks` cap how wide it goes.
-
-## Review
-
-| Command                      | What it does                                                         |
-| ---------------------------- | -------------------------------------------------------------------- |
-| `coder review`               | Review this branch against the merge-base with the default branch.   |
-| `coder review --pr <n\|url>` | Review a pull request. `--post` posts inline comments and a summary. |
-
-Narrow it with `--base`, `--head`, `--since <sha>`, `--path` and `--exclude`. `--engine`, `--model` and `--effort` pick what runs the review.
-
-## Models
-
-| Command                                                | What it does                                                               |
-| ------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `coder model list`                                     | Built-in models, your own, and aliases.                                    |
-| `coder model add <name> --base-url <url> --model <id>` | Connect any OpenAI-compatible endpoint. `--env-key <VAR>` for its API key. |
-| `coder model update <name>`                            | Change a model in place.                                                   |
-| `coder model remove <name>`                            | Delete one of your models.                                                 |
-| `coder model alias <name> <spec>`                      | Name a shortcut, like `fast codex:luna`. `unalias` removes it.             |
-| `coder model disable <name>`                           | Take a model out of rotation. `enable` brings it back.                     |
-
-## Configuration
-
-| Command                          | What it does                                                             |
-| -------------------------------- | ------------------------------------------------------------------------ |
-| `coder config list`              | The effective configuration.                                             |
-| `coder config get <key>`         | Read one value, like `engines.codex.model`.                              |
-| `coder config set <key> <value>` | Write a value. `--workspace` writes to this repo's `.coder/config.json`. |
-| `coder config unset <key>`       | Remove a value.                                                          |
-
-## Connections
-
-| Command                                    | What it does                                                                                             |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `coder connection add <platform>`          | Connect a platform account, such as `github`, by signing in in the browser. Needs `--server`.            |
-| `coder connection add <name> --env <NAME>` | An API key tasks read from `NAME`, kept as a credential. One already holding `NAME` is used, else a new one. |
-| `coder connection add <name> --url <url>`  | A remote MCP server, with OAuth sign-in. `--key` reads a key from stdin or a prompt instead.             |
-| `coder connection add <name> -- <command>` | A stdio MCP server. `--key --env <NAME>` gives it a key.                                                 |
-| `coder connection list`                    | Connections, and the MCP servers this repository declares with whether each is approved here.           |
-| `coder connection reconnect <name>`        | A new key from stdin or a prompt, or sign in again.                                                      |
-| `coder connection rm <name>`               | Remove one.                                                                                              |
-| `coder connection approve <name>`          | Approve a repository MCP server on this machine. `--agent <id>` selects an agent definition.            |
-
-Connections live in `~/.coder`, or on your Coder server with `--server`; `--access read|write` and `--me` set what they allow and whose they are. A repository MCP server needs approval again when its URL, command, arguments or header and environment names change.
-
-## Agents
-
-| Command                                | What it does                                                   |
-| -------------------------------------- | -------------------------------------------------------------- |
-| `coder agent list`                     | Agents in this workspace, or on your server.                   |
-| `coder agent show <id>`                | One agent in full: settings, access, integrations, events.     |
-| `coder agent init [id]`                | Scaffold an agent in `.coder/agents/`.                         |
-| `coder agent run <agent> <event.json>` | Run a recorded event through an agent, offline or on a server. |
-| `coder agent push [id]`                | Upload workspace agents to your server.                        |
-| `coder agent integrations list`        | The apps an agent can connect to. `show <id>` for one.         |
-| `coder agent usage`                    | Usage by agent, installation or engine.                        |
-
-## Servers
-
-| Command                                 | What it does                                                                                   |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `coder auth login`                      | Sign in to Coder Cloud. `--server <url>` for a self-hosted one.                                |
-| `coder auth status`                     | Where you're signed in. `logout` forgets the session.                                          |
-| `coder credentials list`                | Engine credentials on your server. `add`, `login` and `remove` manage them.                   |
-| `coder runner serve --url <public url>` | Run your server's tasks on this machine.                                                       |
-| `coder runner list`                     | Your runners and the workspace's. `add`, `test`, `default`, `rename` and `remove` manage them. |
-| `coder server serve`                    | Run a Coder server. See [Self-hosting](self-host.md).                                          |
-| `coder server rotate-key`               | Re-seal stored secrets with a new `SERVER_ENCRYPTION_KEY`.                                     |
-| `coder server app create <integration>` | Create the built-in agent's public app on a platform.                                          |
-| `coder server workflow`                 | Print the GitHub Actions workflow the `github-actions` runner uses.                            |
-
-## Setup and upkeep
-
-| Command                             | What it does                                                                                    |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `coder setup-host [claude\|agents]` | Install or repair the host plugin, and check engines and auth.                                  |
-| `coder dash`                        | Your tasks, agents and settings in the browser. Short for `coder server serve` on this machine. |
-| `coder upgrade`                     | Update the CLI and host plugins. `--cli-only` or `--plugins-only` to narrow it.                 |
-| `coder docs [topic]`                | Print a bundled guide.                                                                          |
-
-Set `CODER_NO_UPDATE_CHECK=1` to silence the update notice.
-
-## Global flags
-
-| Flag              | What it does              |
-| ----------------- | ------------------------- |
-| `--json`          | Machine-readable output.  |
-| `--cwd <dir>`     | Act on another workspace. |
-| `-h`, `--help`    | Help for any command.     |
-| `-v`, `--version` | Print the version.        |
-
-## Exit codes
-
-`coder run --wait` and `coder result --wait` exit with:
-
-| Code | Meaning                                             |
-| ---- | --------------------------------------------------- |
-| 0    | The task completed.                                 |
-| 1    | The task failed or was cancelled.                   |
-| 3    | No engine could start.                              |
-| 4    | An approval is pending. Answer it, then wait again. |
-| 130  | You detached from the wait. The task keeps running. |