Update to SHIP

{
  "description": "Use when the user wants to read an agent's log, find why a run failed, follow a run live or stop an agent. It reads and controls the agent runs of SHIP missions, and each run is one agent in its own sandbox. List the runs of a mission or of the organization, and read the status, resource use and cost of one run. Read what the agent did from its log, follow one run live until it ends, and stop one run. For example, the user asks \"what did the builder do on SHIP-412\", \"why did the QA run fail\" or \"show me the agent log\". Also use it when the user says \"stop that agent\", or to find the run that makes a mission slow or expensive.",
  "included_files": [],
  "name": "ship-agent-runs",
  "skill_md_contents": "---\nname: ship-agent-runs\ndescription: Use when the user wants to read an agent's log, find why a run failed, follow a run live or stop an agent. It reads and controls the agent runs of SHIP missions, and each run is one agent in its own sandbox. List the runs of a mission or of the organization, and read the status, resource use and cost of one run. Read what the agent did from its log, follow one run live until it ends, and stop one run. For example, the user asks \"what did the builder do on SHIP-412\", \"why did the QA run fail\" or \"show me the agent log\". Also use it when the user says \"stop that agent\", or to find the run that makes a mission slow or expensive.\n---\n\n# Read and control agent runs\n\nA mission is the work that SHIP does for one issue. The agents of a mission do that work in runs. A run is one agent\nin its own sandbox, for example one Planner run, three Builder runs and one QA run. The id of a run is its sandbox id,\nsuch as `builder-ship-412-3f9c41aa-coding-1`.\n\nThis skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at\n<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do\nthe setup too. If its `version` is older than `ship --version`, run `ship init --force`.\n\n| Command | Token scope |\n| --- | --- |\n| `ship run list`, `ship run get`, `ship run logs`, `ship run watch` | `sandboxes:read` |\n| `ship run stop` | `sandboxes:stop` (an org admin's token) |\n\n## When to use it\n\n- The user asks what an agent does now, or what it did.\n- You must wait for a run to end before your next step.\n- A run failed, and you must find the cause before you send an instruction to the mission.\n- A mission costs more or takes longer than the user expects, and you must find the run that is the cause.\n- The user asks you to stop one agent.\n\nTo read the state of the mission itself, or to send it feedback, use the `ship-missions` skill.\n\n## Find the runs of a mission\n\n```bash\nship status SHIP-412\nship run list --mission SHIP-412\n```\n\n`ship status` lists the runs of the mission, oldest first, with the id of each run. The current run has the mark\n`(current)`. `ship run list` gives the same runs with their harness and start time, newest first.\n\nYou can also find runs across the organization. A list covers every project of the token, unless `--project` names one.\n`SHIP_PROJECT_ID` does not narrow a list.\n\n```bash\nship run list --status running\nship run list --mission SHIP-412 --role qa\nship run list --status failed --limit 20 --json\nship run list --status failed --limit 20 --cursor eyJhIjoxfQ\n```\n\nWhen more runs match, the last line gives the `--cursor` for the next page. Give the same filters with it. A status is `running`, `completed`, `stopped`, `failed` or `stale`. A `stopped` run ended on purpose before it finished,\nfor example because a newer run replaced it. A `stale` run closed without a report, after its time limit. A role is\n`planner`, `builder`, `reviewer` or `qa`.\n\n## Read one run\n\n```bash\nship run get builder-ship-412-3f9c41aa-coding-1\n```\n\nThe command prints the mission and the role of the run, its status, and the reason when a run ended early. It also\nprints the harness and the size of the sandbox, the start and end time, and the latest CPU, memory and disk use. The\n`session` line is the session of this run, with its outcome and its cost. The `other` line names the sessions of other\nruns with the same role. Their cost is not part of the cost of this run.\n\n## Watch a run live\n\n```bash\nship run watch builder-ship-412-3f9c41aa-coding-1\nship run watch qa-ship-412-77d0e2c1-qa-1 --max-seconds 300\nship run watch qa-ship-412-77d0e2c1-qa-1 --since 118\n```\n\nThe command prints the last events of the agent. Then it prints each new event on one line, for example a thought, a\ntool call or an error. It also prints a line when the mission moves to another stage.\n\nWhen the run ends, the command exits 0 if the run completed, and 7 if it ended in another way. With `--max-seconds`,\nthe command stops after that time and exits 5 if the run is still active. Its message gives the `--since` value, so\nthat the next command prints only the events that came after. Use this command to wait for a run, not a loop of\n`ship run get` calls.\n\nAn agent that uses the SHIP MCP server calls the `watch_agent_run` tool with the id of the run. The call returns when\nthe run ends, when its mission moves to another stage, or after `maxSeconds` (300 by default, 600 at most). While the\ncall waits, the server sends each event as a progress notification, if the request has a progress token. The result\nhas the status of the run, the stage, `ended`, the reason for the return, the last 20 events and a `cursor`. If the run\nis still active, call the tool again with `since` set to the cursor.\n\n## Read what the agent did\n\n```bash\nship run logs builder-ship-412-3f9c41aa-coding-1\nship run logs builder-ship-412-3f9c41aa-coding-1 --part system\nship run logs qa-ship-412-77d0e2c1-qa-1 --part prompt\nship run logs builder-ship-412-3f9c41aa-coding-1 --session s-91c2\n```\n\nA log has three parts:\n\n| Part | What it has |\n| --- | --- |\n| `session` (the default) | The event stream of the agent, one JSON event on each line: its thoughts, its tool calls and their results. |\n| `system` | The output of the sandbox: the clone, the dependency install, the checks before a push, and git. |\n| `prompt` | The text that the repository added to the prompt of the agent, for example from `.ship/agents/<role>.md`. |\n\nThe command reads the session of the run itself. To read a session of another run of the same role, name it with\n`--session`. The `session` part is long, so filter it before you read it. For example, pipe `--json` output to `jq`, or\nsearch for the error text.\n\nThe platform saves the log when the agent ends. While a run is still `running`, the command exits 4 and says so. Read\n`ship run get` for its status, and read the log after the run ends. Some old runs did not record their own session. For\nsuch a run, the command also exits 4 and lists the sessions of the role, so that you can name one with `--session`.\n\n## Stop one run\n\nStop a run only when the user asks for it, because the work in progress of the agent is lost.\n\n```bash\nship run stop builder-ship-412-3f9c41aa-coding-1\n```\n\nThe status of the run becomes `stopped` a few seconds later. The command stops one run, not the mission. The mission\ncontinues, and it can start a new run for the same stage. To stop the whole mission, use `ship mission stop` from the\n`ship-missions` skill.\n\n## Exit codes\n\nEvery command also takes `--json`, which prints the raw API response.\n\n| Exit code | Meaning | What to do |\n| --- | --- | --- |\n| 2 | The arguments are wrong. The message names the problem. | Fix the command. |\n| 3 | The token is not set, or it does not have the scope of the command, or it is not an admin's token for `ship run stop`. | Ask the user for a token with the scope. Do not retry. |\n| 4 | SHIP found no such run, or the run has no saved log yet. | Check the id with `ship run list`. For a log, wait until the run ends. |\n| 5 | `ship run watch` stopped at `--max-seconds`, and the run is still active. | Run the command again with the `--since` value from its message. |\n| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |\n| 7 | The run that `ship run watch` followed ended, but it did not complete. | Read the reason with `ship run get`, then its log. |\n"
}