Documentation for AgentRun 0.1.0-beta.27. Use the matching setup instructions → GitHub’s main branch may include unreleased changes.
The agent home
An agent you can carry. Its definition, its saved sign-ins and an index of every run live in one directory, the agent home. Each run keeps its own store inside it. Copy the directory and the agent goes with it.
Status. The agent home is source only. @parcha/pi-durable-agent is built and tested in the open repository at the v0.1.0-beta.27 tag, and it is not published to npm yet. It needs Node 22.19 or later.
What is in a home
acme/ the agent home
agent.sqlite the agent store: identity, definition, skills, sign-ins, the runs index
owner.lock the writer lock; never open, copy or move it with the home
runs/<run id>/ a pi-durable-disk run directory
store/run.sqlite that run's pi-durable store
work/ that run's files, with the agent's skills under .agents/skills/
Both stores are ordinary pi-durable stores, read and written with pi's own session. There is no second format and no second durability layer.
The definition names the agent's tools, skills and instructions. It names no model: the host picks the model, the thinking level, the tools and where each tool runs.
A run
startRuncreatesruns/<run id>/, writes the skills into the workspace, copies the agent's saved sign-ins into the run store, and records the run in the agent's index. Seeding is a host step. It is never a tool, and the model never sees a sign-in.- The host opens its own harness on the run store with its model and its tools.
durableProfileStoregives pi-browser's saved-profile store over the run store. A sign-in that already exists is reused. A new one is made once.- When the run ends,
carryBackcopies the sign-ins the run made back into the agent home and completes the run's entry in the index. A second call for the same run changes nothing.
Try it
The package ships a quickstart that needs no key and no network. It signs in once in run 1, and run 2 finds that sign-in ready. In a checkout of the repository at the release tag:
npm ci --ignore-scripts
npm run build -w @parcha/pi-durable-agent
node quickstart.mjs
Save the script from the package README as quickstart.mjs at the repository root first. The README shows the output you should see.
The save lease
Two runs of one agent can run at once, and neither Browserbase nor Kernel locks a saved sign-in: the last writer wins. So one run at a time holds a profile's save lease. Only that run gets the saved sign-in, and only its changes go back. A lease expires after six hours by default, so a run that died does not hold a sign-in forever.
What is stored
Every document is session-scoped and versioned. Times are ISO 8601 strings in UTC.
| Kind | Store | What it holds |
|---|---|---|
agent.identity |
agent | the agent's id, name and format version |
agent.definition |
agent | version, name, instructions, skills and tools by name, optional input and output schemas, an optional workflow, an optional cost ceiling. No model |
agent.skills |
agent | each skill file with its SHA-256 |
agent.aliases |
agent | the agent's id in each host |
agent.bindings |
agent | where each tool runs in each host |
agent.runs |
agent | one entry per run: its path, host, start, end, outcome and cost |
agent.leases |
agent | which run holds the save lease on a profile |
browser.profiles |
agent and run | a saved sign-in: the provider's reference and its state |
A saved sign-in's reference opens a signed-in session, so it is as secret as the password behind it. It reaches a run only through the host. No tool reads or returns one.
The timeline
@parcha/pi-durable-agent/timeline turns a run into one readable timeline. It has no dependency and uses no Node built-in, so a page, a viewer and a harness can import the same code. A live run and a finished run give equal rows. A row never carries a live-view URL, a browser context id or a cookie.
Not yet
- Read-only SQL over an agent's tables.
- A vault: credentials kept as ciphertext that only the host decrypts.
- Tables whose rows commit inside pi's own commit.
- An agent home on a network disk, and a reader of both stores for viewers in another process.