Actors
Plain code with saved state, a function over the next batch of messages. Routing, timers and status labels are actors that never call a model.
Loa Arbor
Arbor runs agents, plain code and people together, each doing its part. Start with one agent and add a teammate at a time.
Example: Shared coding session. A product manager and two engineers shape the plan in one conversation, and agents pick up the work, each coming back with a branch for a person to approve.
Plain code with saved state, a function over the next batch of messages. Routing, timers and status labels are actors that never call a model.
An actor whose function is the model loop. It builds the context, calls the model, runs the tools the model asks for and repeats until it replies. Each agent picks its own model and provider, so one app can mix them, and a new revision can change them.
An agent starts children for work that can run in parallel. They message each other while both are working, so a parent can correct a child halfway through and a child can report progress before it's done.
People join a session in the roles the app declares, and each sees only what is meant for them. A message addressed to one person goes to that person's stream alone.
A ready-made actor that sends each message to its audience, everyone, one role or one person, so people and agents share one record.
Tools come from your code or from MCP servers. A call can wait for a person to approve it, for an answer on someone's screen, or for outside work to finish, for minutes or days and across restarts.
One store of notes, each with a reach, a session, a partition or the whole app, and an audience. Documents are named and versioned, and can be held to a schema.
A partition groups sessions by customer, campaign or tenant, so what was noted on Monday is there on Tuesday. A schedule posts a message on a timer, with no one having to write in.
An agent loads a skill, its rules and its tools, only when it needs it. With the run tool, the model writes a short program over its tools, and every call inside it is still a saved step.
An assistant can act for one person, with that person's own account on an MCP server; the token never reaches the code, the model or the record. A workspace gives an agent its own clone of a repository, where every command runs in the OS sandbox.
Arbor was designed to be written and run by coding agents like Claude Code. It's built for the command line first, with a console operators can use to keep track of things.
A coding agent builds and manages the app from a terminal, with a person reviewing. A person can run the same commands by hand.
arbor docs search and arbor docs get work offline and match the version that's running. A new project gets an AGENTS.md that points the agent there.
Every command takes --json. An error is one JSON object with a stable code, the fields at fault and whether a retry can help, and the exit code says what kind of error it was.
The agent stages settings into a draft, a person or the agent reviews it, and one command publishes it as a new version. A command that destroys something runs only with --yes, and a script is refused rather than left waiting for a keypress.
Your product opens a session, posts each message and reads one stream of everything that happens, over HTTP or with the client library for browsers and phones.
The console comes with Arbor. It shows each session's people, what it has spent against its budget, and a graph of the app's actors drawn from the app itself.
import { actor, bundle, isMessage } from '@arbor/sdk';
const front = actor('front', {
receive(ctx, batch) {
for (const m of batch) {
if (isMessage(m, 'user_msg')) ctx.emit('reply', { text: m.body.text });
}
},
}).wake('chat');
export default bundle({ app: 'seed-echo', roots: [front], session: { exposed: [front] } });import { agent, bundle } from '@arbor/sdk';
const front = agent('front', {
instructions: 'You are the assistant of a small shop. Answer briefly and plainly. …',
})
.wake('chat')
.labels({ sale_captured: { type: 'boolean', mutable: true } })
.hooks({
beforeTurn: (ctx) => { /* … */ },
afterTurn: (ctx, { answered, reply }) => { /* … */ },
});
export default bundle({ app: 'seed-labels', roots: [front], session: { exposed: [front] } });const researcher = agent('researcher', {
instructions: 'You research one question for the shop. Answer in under 120 words. …',
});
const front = agent('front', { instructions })
.wake('chat')
.labels({ sale_captured: { type: 'boolean', mutable: true } })
.subagents({ template: researcher, when: 'one independent question that needs looking up' });
export default bundle({
app: 'seed-team',
roots: [front],
session: { exposed: [front] },
uses: {
memory: {
notes: {
tone: { across: 'session', among: 'subtree', description: 'how to talk to this customer' },
house_style: { across: 'app', description: "the shop's standing guidance" },
},
},
},
});const front = agent('front', { instructions })
.wake('chat')
.participants(['customer', 'staff'])
.principal('opener')
.clientEvents({ subtypes: ['participant_joined', 'participant_left'] });
export default bundle({
app: 'seed-participants',
roots: [front],
session: {
roles: {
customer: { max: 1, principal: true },
staff: { max: 2, join: 'invite', may: ['session.grant'] },
},
exposed: [front],
},
});const front = agent('front', { instructions })
.wake('chat')
.participants(['customer', 'staff'])
.tool({
name: 'refund',
description: 'Refund an order. Refunds over $100 wait for a member of staff to approve them.',
params: { /* order, amount */ },
handler: (args, ctx) => {
const amount = Number(args.amount);
if (amount > 100 && !ctx.approved) return ctx.needsApproval(`a refund of $${amount} is over $100`);
return { refunded: true, amount, approved_by: ctx.approved?.by ?? null };
},
});const coach = agent('coach')
.wake('chat')
.hooks({ beforeTurn: async (ctx) => { /* fold what it heard; a "NOTE: " line goes to the staff */ } });
const lobby = relay('lobby', {
roles: ['customer', 'staff'],
messages: {
text: {},
note: { for: { role: 'staff' } },
whisper: { for: { participant: 'to' } },
},
readers: [coach],
writers: [coach],
});
const desk = agent('desk', { instructions })
.wake('chat')
.participants(['customer', 'staff'])
.subagents(breakout);
export default bundle({
app: 'seed-relay',
roots: [lobby, coach, desk],
session: { roles: { customer: { max: 2, principal: true }, staff: { max: 3 } }, exposed: [lobby, desk] },
});From a single actor to a room of customers, staff and agents, one block at a time. Each step is one of the seed apps in Arbor's repository, and the count is its lines of code, comments left out. The code with each step is cut down, with what the step adds marked.
Plain code that answers each message. No model.
Give it instructions and the same actor becomes an agent, with a model loop inside.
The agent starts researchers for questions it can look up in parallel, and keeps notes for this conversation and for the whole shop.
A member of staff joins the same conversation in a role of their own. The agent knows who said what.
A refund over $100 waits for a member of staff to approve it, for minutes or days, across restarts.
A relay sends each message to its audience, to everyone, to staff only or to one person. A coach agent hears it all and writes notes for the staff.
import { agent, bundle } from '@arbor/sdk';
const table = agent('table', {
instructions: 'You are the game master of a small dungeon crawl, narrating for the whole table. …',
})
.wake('chat')
.participants(['player', 'dm']);
const whisper = agent('whisper', {
instructions: 'You are the game master, in a private line with one player. …',
})
.wake('chat')
.participants(['player'])
.instance('participant')
.principal('opener');
export default bundle({
app: 'seed-instances',
roots: [table, whisper],
session: {
roles: { dm: { max: 1, principal: true }, player: { max: 6 } },
exposed: [table, whisper],
},
uses: { memory: {} },
});const npc = agent('npc', {
instructions: 'You voice one character of the campaign for a single scene. …',
});
const table = agent('table', { instructions })
.wake('chat')
.participants(['player', 'dm'])
.subagents({ template: npc, when: 'a player speaks to a character of the world' });
export default bundle({
app: 'seed-campaign',
roots: [table, whisper],
session: {
roles: { dm: { max: 1, principal: true }, player: { max: 6 } },
partition: { by: 'campaign', from: 'input' },
exposed: [table, whisper],
},
uses: {
memory: {
groups: { narrator: [table, whisper] },
notes: {
world: { across: 'partition', description: 'what is true of the campaign world' },
secrets: { across: 'partition', among: 'narrator', description: 'what the narrators keep from the table' },
},
},
},
});const combat = skill('combat', {
description: 'Resolving fights: who acts first, attacks against guard, harm and vigour',
prompt: fromPrompt('combat-rules'),
tools: [strike],
});
const travel = skill('travel', {
description: 'Journeys: legs, supplies, foraging and weather',
prompt: fromPrompt('travel-rules'),
tools: [forage],
});
const narrator = agent('front', { instructions: fromPrompt('narrator') })
.wake('chat')
.skills([combat, travel], { maxLoaded: 2 })
.docs({ search: true, paths: ['docs/rules/**'] });
export default bundle({
app: 'seed-skills',
roots: [narrator],
session: { exposed: [narrator] },
uses: { artifacts: {} },
});const sheet = {
description: 'a character sheet',
schema: { type: 'object', properties: { name: { type: 'string' }, hp: { type: 'integer', minimum: 0 } /* … */ } },
across: 'partition' as const,
};
const handout = { description: 'a handout: a map, a letter, a rumour', across: 'partition' as const, search: 'lexical' as const };
const table = agent('table', { instructions })
.wake('chat')
.participants(['gm', 'player'])
.artifacts(['sheet', 'handout'], { write: ['sheet', 'handout'], maxPins: 2 });
export default bundle({
app: 'seed-artifacts',
roots: [table],
session: {
roles: {
gm: { max: 2, principal: true, may: ['artifacts.read'] },
player: { max: 6, may: ['artifacts.read:handout', 'artifacts.create:sheet'] },
},
partition: { by: 'campaign', from: 'input' },
exposed: [table],
},
uses: { artifacts: { kinds: { sheet, handout } } },
});A tabletop campaign that a game master and up to six players come back to over many evenings. Each step is a seed app; 14 starts again from a one-agent chat.
One agent narrates for the whole table. Each player also gets a private line to the game master, made the first time they use it; no player reads another's.
Each evening is a session, and the campaign ties them together. Notes on the world last from one evening to the next, the narrators keep secrets the players never see, and the table spawns a character to voice each scene.
The narrator loads the combat or the travel rules, each a prompt and a tool, only when the story calls for them, and searches the rule book instead of reading all of it.
Each character lives on a sheet its player owns, checked against a schema, and the narrator changes only what changed, such as hit points. Handouts are kept and searched the same way.
import { actor, agent, bundle, isMessage } from '@arbor/sdk';
import { endpoint } from 'arbor:http';
const quick = agent('quick', { instructions: 'Answer in one short sentence.' }).wake('chat');
const careful = agent('careful', { instructions: 'Give two short reasons, then the answer.' }).wake('chat');
const router = actor('router', { state: { cohort: '', routed: 0 } })
.wake('chat')
.receive(async (ctx, batch) => {
for (const m of batch) {
if (!isMessage(m, 'user_msg')) continue;
if (!ctx.state.cohort) {
const res = await endpoint('experiments').get('/cohort', { query: { session: ctx.session.id } });
ctx.state.cohort = (res.json as { cohort: string }).cohort;
}
ctx.send(ctx.state.cohort === 'b' ? careful : quick, 'user_msg', m.body);
}
});
export default bundle({
app: 'seed-router',
roots: [router, quick, careful],
session: { exposed: [router] },
peers: [{ from: router, to: quick }, { from: router, to: careful }],
http: { experiments: { url: 'https://experiments.example', methods: ['GET'] } },
});const worker = agent('worker', { instructions: "You are one person's own Jira assistant. …" })
.instance('participant')
.principal('opener')
.participants(['user'])
.tools('jira.*');
const desk = actor('desk', { state: { checkins: 0 } })
.participants(['user'])
.receive(async (ctx, batch) => {
for (const m of batch) {
if (m.sender.principal === 'participant') {
ctx.send(`worker[${m.sender.participant}]`, 'user_msg', { text: m.body.text });
continue;
}
for (const w of await ctx.instances(worker)) ctx.send(`worker[${w.key}]`, 'user_msg', { text: CHECKIN });
}
});
export default bundle({
app: 'seed-connections',
roots: [desk, worker],
peers: [{ from: desk, to: worker }],
uses: { connections: { jira: { provider: 'atlassian-mcp', scopes: [/* read, search */] } } },
schedules: { checkin: { text: 'check in', root: desk } },
});import { agent, bundle, workspace } from '@arbor/sdk';
const fixer = agent('fixer', {
instructions:
'You fix failing tests in the repository app. Open a workspace on it first. Find the function with ws_grep, ' +
'change it with ws_edit, commit, push the branch with ws_push, and report the branch. …',
})
.wake('chat')
.subagents(workspace);
export default bundle({
app: 'seed-coding',
roots: [fixer],
session: { exposed: [fixer] },
uses: { coding: {} },
});Three apps, each built from the same blocks as the others. 23 builds on 17; 22 starts again from a one-agent chat.
Plain code asks an outside service once which group a conversation belongs to, and hands every message to that group's agent. The answer is recorded, so a restart never asks twice.
Each person on the team gets their own assistant, which reads their own Jira issues with their own account; nobody's token reaches the code or the model. A schedule wakes the desk to check in with everyone present.
Told a test fails, an agent opens a workspace, a clone on its own branch where every command runs in the OS sandbox. It finds the function, fixes it and commits, and the branch is pushed only once a person approves.
Each step is saved in one write before the next begins. If a node dies, another picks the actor up after the last saved step, and no finished model or tool call is made twice. A session that is waiting uses no compute.
A model call's cost is saved in the same write as its answer, so the bill and the record can't disagree. Caps on an actor, on an agent and its subagents, or on a session can warn, refuse further calls, or stop.
For each app or agent, a tool call can be allowed, warned about, blocked, halted or held for a person. If a node dies mid-call, a read-only or repeatable tool runs again; any other is not, and the agent is told the outcome is unknown, unless the tool's author chose to hold it for a person.
Copy a real conversation at the step where it went wrong, give the copy a new prompt, model or tool, and compare the two, with what each cost. The copied steps aren't run again, and for each kind of call you choose who answers: the live system, the recorded answer, or a stand-in. A tool that sent an email in the original doesn't send it again.
A session keeps the version of the app it started on until it closes. A new version can take a share of new sessions first.
Any node can carry on any actor, so you can add and remove nodes while Arbor runs. One node runs on a SQLite file; a fleet shares Postgres, Redis and a blob store.
Where the time went, what each actor decided and what it cost come from the same saved steps, so they always agree. Traces are OpenTelemetry, and a console ships in the binary.
About 2,900 Go tests run with the race detector, plus an integration suite against Postgres. Each storage interface has one test suite that every implementation must pass.