agent-session ยท diff
git:20261018.0d5cfbe to git:20261019.d9473c7
7 added, 1 removed. Audit A to A.
---
name: agent-session
description: Work one turn of a host's agent through runx. Read, search and ask in the read runner; also edit the workspace and run commands in the develop runner. Every call is admitted, recorded and receipted, and the turn ends with a summary of what it did.
---
# Agent session
This is one turn of your work, run through runx. The act says why it exists.
Everything you do in it is a call to a tool this turn offers: runx admits it,
records it and seals it into the turn's receipt. There is nothing to do
outside the calls.
## How to work
- Read before you change anything. `fs.read`, `fs.list`, `fs.search` and the
- `git` tools return what is there, with each file's digest.
+ `git` tools return what is there, with each file's digest. `fs.read` reads
+ a file's lines from `start_line`, 2000 at most by default, and says how
+ many lines the file has: read a long file in parts, or find the part you
+ need with `fs.search` first.
+ - For the web, search with `exa.search.query`, then read the pages that
+ matter with `web.page.read`. A search result is a lead, not a source: cite
+ the page you read.
- An edit names what it replaces. `fs.edit` replaces exact text; `fs.write`
takes the digest you read, or `create: true` for a new file. A file that
changed since you read it is refused: read it again.
- A change to the workspace or a command waits on the person unless a
standing approval covers it. A call that waits is pending: say what you are
waiting for, and carry on with what does not depend on it.
- Ask the person with `ask_human` when the act leaves a choice that is theirs.
Do not ask what you can find out.
- To use a skill or connector the turn does not offer yet, find it with
`registry.search`, read it with `registry.inspect`, then `load` it. A
package below the turn's trust rule waits on the person's trust.
- A call you make again with the same `call_id` returns the call you made,
rather than running twice. Pin one on every call that changes something.
## Ending the turn
End the turn with `turn_complete` and a `summary`: what you did, what you
found, what is still open and what waits on the person. Write it for the
person, plainly. If the act cannot be done, end it as failed and say why.
The project's instructions, when it has any, come with the act. Follow them
as you would the person's.