Skip to content

How orc runs Pi ​

Orc runs only Pi, and it starts Pi itself as pi -p --mode json in the task copy, inside nono run by default or on the host with --sandbox none.

  • Orc passes the agent file's model, thinking level and tools, and the run's sessions folder as --session-dir.
  • Orc writes the prompt to Pi’s standard input, and the prompt asks the agent to print ORC_COMPLETE on its own line once the work is committed.
  • The prompt also asks the agent to print ORC_SPLIT on its own line and then a JSON document when the change outgrows the budget.
  • Pi prints one JSON event per line, and its first line is the session header with the session id and timestamp.
  • On that header orc records the session file, named after the timestamp and the id with .jsonl, so orc show names it while the step runs.
  • Orc writes each assistant message to the step's log on its own line, and each command a tool starts on a line opening with >. The implement step logs to agent.log in the run folder, and each fix to fix-<n>.log.
  • While a tool runs, orc writes orc: still running <command> (N min) to that log each minute.
  • Orc stops Pi only after the idle limit passes with no output and no tool running, so a quiet test command is never cut off.
  • Orc counts each bash command whose tool_execution_end event carries isError, as a failure of that command. A success, or a failure of another command, starts the count over, and a tool other than bash leaves it as it is.
  • At 3 failures of one command in a row orc logs orc: pi failed <command> 3 times in a row and writes failing.json to the run folder, with the command and the time. The beat opens an attention item for you on it, as The attention queue shows, and Pi carries on. Orc removes the file when the count starts over or Pi ends.
  • At 6 failures of one command in a row orc logs orc: stopped pi, it failed <command> 6 times in a row, stops Pi and asks you to continue or stop, as A looping run shows.
  • Orc counts the step complete only when the session’s final assistant message stopped with stop and holds ORC_COMPLETE on its own line.
  • A valid ORC_SPLIT proposal records the run as failed without running checks or opening a PR.
  • The beat then turns the task into a parent and starts its children.
  • When the task has a parent, its children join that parent instead, as A worker split proposal shows.
  • Orc also loads its orc_ask extension into Pi with --extension and adds orc_ask to the tools, as A worker question shows. Pi calls it to ask you a question mid-run instead of guessing or failing.
  • On resume orc passes the recorded session file as --session, and Pi continues that session instead of starting a new one.
  • Orc sums the usage input and output counts each session message carries into the run's token totals.

packages/run/src/entities/agent/pi-run.ts starts Pi and reads its lines, packages/run/src/entities/agent/pi.ts checks the final reply, and packages/run/src/features/running-a-task/run-loop.ts reads the session after each step.