# Examples · Loa Arbor

Each app below is built in stages. Every stage is a whole `app.ts` you can run, followed by what each new name in it does. After an app's last stage come its settings and the commands to try it.

## Built by a coding agent

Terminal recording (https://arbor.getloa.app/casts/01-zero-to-a-running-app.cast): Claude Code, in a terminal, building an Arbor support-desk app from an empty directory and talking to it.

A real Claude Code session (Sonnet), unedited. From an empty directory it reads `arbor docs`, runs `arbor init`, writes a support-desk agent, and talks to it on a local model. It goes wrong on screen too: two commands the allowlist refused, a docs heading that doesn't exist, and a `session follow` that returned before the reply, which the agent worked around. Recorded on Arbor's main branch at fb647c60.

## A coding agent whose push waits

Terminal recording (https://arbor.getloa.app/casts/05-a-coding-agent-whose-push-waits.cast): Claude Code, in a terminal, building an Arbor app whose own coding agent fixes a failing Go test in a workspace, commits, and has its push held for a person.

A real Claude Code session (Sonnet 5.5), unedited except that long pauses are cut short. It shows the engineering team's coding agent. The repository starts with one commit whose test fails. From an empty directory, Claude Code builds an Arbor app with a `fixer` agent that has a workspace, and asks it for the fix. The app's agent, on a local model, opens a workspace on a branch, runs `go test` and sees it fail, changes `a - b` to `a + b`, runs it again and sees it pass, and commits. Its push is held for a person. Claude Code had been told not to approve it, so at the end the repository still has only its first commit. It goes wrong on screen too: a command run before the node was up; a first deploy refused until the settings named a repository, which the agent fixed as the error said; the agent saying there is no command to answer the push, when there is one (`arbor session call answer`); a stray `<channel|>` from the local model; and a workspace named `app-fix-test` instead of `repo`, so one listing at the end finds none. Recorded on Arbor's main branch at 3583bc66.

These apps are cut down from the seed apps in the Arbor repo (`examples/seed/`). Each seed adds one feature to the one before it. These examples take only what their story needs, so none of them carries leftovers from the others. The code is typechecked against `@arbor/sdk`. Read [the building blocks](../blocks/) first if you want each idea on its own; here they work together.

## Before you start

A few words come up in every example.

- An **actor** is a part of your app that receives messages and sends replies. An **agent** is an actor driven by a model.
- A **session** is one conversation with your app. A **root** is an actor the session starts with. The `bundle()` at the end of each file lists them: `roots` are all of them, and `session.exposed` are the ones people can talk to.
- A **role** is a part a person plays in a session, such as `customer` or `staff`. The bundle declares the roles. The **settings** file says which callers may hold each one, in a `role` map from role to audience. An audience is who the caller is to Arbor's sign-in: `anonymous` for someone with no account; beyond that, your deployment names its own audiences, and these examples use `customer` and `employee`. Staff sign in with the `employee` audience; `staff` is the role they hold in the session.
- **Settings** are a YAML file beside `app.ts` with the details of one place you run the app: who holds which role, a spending cap, the URLs of outside services. None of the examples needs a secret in it. None of them names a model either, so the node's own default model is used (start the node with `--model`, `--model-base-url` and `--model-api`).

### Running an example

`arbor seed` publishes every app it finds in a directory whose subdirectories are named `NN-name` (a number, a dash, a name) and hold an `app.ts` and a `settings.yaml`. It builds each one, applies its settings, and publishes it. A **node** is one running Arbor server, here `arbor serve` on your machine. Make one directory per example (`01-support-desk`, `02-game-night` and `03-eng-team` below), then run a local node and seed it:

```sh
mkdir -p apps/01-support-desk          # app.ts and settings.yaml go here
arbor serve --data-dir ~/.arbor        # a local node; add the model flags for your model
arbor seed --dir apps --only 01-support-desk
```

`--only` takes the directory name or the app name, `--reset` first ends the app's running sessions, and each line of output ends with the app's page in the node's console, at `/ui/`. The session page there has a Chat tab. Each example also lists the shell commands: `arbor session open` prints the new session's id on its own line, so `SID=$(arbor session open --app <app>)` captures it, and `arbor session chat --session $SID --text "..."` sends a message and follows the reply.

## 1. A support desk

A customer talks to a support agent. Staff can join the same conversation. The agent can refund an order, but a refund over $100 waits until a member of staff approves it. When a customer asks about several orders, the agent hands each one to a researcher and answers once they all report. Beside the agent there is a second room where customer and staff talk to each other, and where staff can leave a note the customer does not see.

Who is in it:

- `front`, an agent: the support agent the customer talks to.
- `researcher`, an agent the front agent starts, one per order.
- `lobby`, a relay: the room for people. A relay is an actor Arbor ships whose only job is to decide who reads each message.
- The people, in two roles: `customer` and `staff`.

```mermaid
%% Who talks to whom in the support desk
flowchart TB
  customer(["customer"]) --> front["front<br/>agent"]
  staff(["staff"]) --> front
  front -- "spawn, one per order" --> researcher["researcher<br/>agent"]
  customer --> lobby["lobby<br/>relay"]
  staff --> lobby
  lobby -. "text: everyone<br/>note: staff only" .-> staff
```

### Stage 1: an agent, two roles, a refund that waits

```ts
import { agent, bundle } from '@arbor/sdk';

const front = agent('front', {
  instructions:
    'You are the support agent of an online shop, in a conversation with a customer and, at times, a member of staff. ' +
    'Each message starts with who said it in brackets: [customer] or [staff <name>]. Never write a bracketed prefix yourself. ' +
    'Answer the customer plainly. When a member of staff speaks, follow their lead. ' +
    'When the customer asks for a refund, call refund with the order number and the amount, then say whether it went through.',
})
  .wake('chat')
  .participants(['customer', 'staff'])
  .tool({
    name: 'refund',
    description: 'Refund an order. A refund over $100 waits for a member of staff to approve it.',
    params: {
      type: 'object',
      properties: { order: { type: 'string' }, amount: { type: 'number' } },
      required: ['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`, { to: { role: 'staff' } });
      }
      return { refunded: true, order: String(args['order']), amount, approved_by: ctx.approved?.by ?? null };
    },
  });

export default bundle({
  app: 'support-desk',
  roots: [front],
  session: {
    roles: {
      customer: { max: 1, principal: true },
      staff: { max: 2 },
    },
    exposed: [front],
  },
});
```

What is new:

- `agent('front', { instructions })` makes an agent: an actor whose function is the model loop. It calls the model, runs the tools the model asks for, and repeats until it replies. `instructions` is what the model is told about its job.
- `.wake('chat')` runs the agent whenever a person writes to it.
- `.participants(['customer', 'staff'])` says which roles may talk to this agent. With two roles in one conversation, Arbor puts who said each message at the start of it, as `[customer] ...` or `[staff Sam] ...`. That is why the instructions describe the brackets and tell the model never to write one itself.
- `.tool({ name, description, params, handler })` gives the model a function to call. `name` and `description` are what the model reads. `params` is a JSON Schema for the arguments it sends. `handler` is your code, which receives the arguments (`args`) and a context (`ctx`) and returns the result.
- `ctx.needsApproval(reason, { to: { role: 'staff' } })` stops the call instead of finishing it. The agent waits, and the reason is shown to whoever may answer. `to` says who: here anyone holding the role `staff`. Without `to`, in an app with roles like this one, the operators answer (the people who run the node, in its console). The customer sees that the refund waits, and for whom, but not its arguments.
- `ctx.approved` is empty on the first run. After a person says yes, the handler runs again with the same arguments and `ctx.approved` set to `{ by, note }`, and this time the refund goes through. If the person says no, the model reads the refusal.
- `bundle({ app, roots, session })` ends the file. `app` is the app's name. `session.roles` declares the roles: `max` is how many people may hold one at the same time, and exactly one role is `principal: true`, the person the session is for. The customer who opens the session holds it. `session.exposed` lists the roots people can talk to.

```mermaid
%% A refund over $100 waits for staff, then goes through
sequenceDiagram
  participant C as Customer
  participant F as front (agent)
  participant T as refund tool
  participant S as Staff
  C->>F: Refund order 8, $250
  F->>T: refund(order 8, 250)
  T-->>F: held, needs staff approval
  F-->>C: it waits for staff
  S->>T: call answer --approve
  T->>T: runs again with ctx.approved set
  T-->>F: refunded, approved_by staff
  F-->>C: it went through
```

### Stage 2: researchers and a label

```ts
import { agent, bundle } from '@arbor/sdk';

const researcher = agent('researcher', {
  instructions:
    'You look up one question about an order for a support agent. Call set_status with what you are checking, ' +
    'call lookup_order, then report what you found in under 80 words.',
}).tool({
  name: 'lookup_order',
  description: 'Look up an order by its number. Returns its status and total.',
  params: { type: 'object', properties: { order: { type: 'string' } }, required: ['order'] },
  // A stand-in for your own order system.
  handler: (args) => ({ order: String(args['order']), status: 'shipped', total: 140 }),
});

const front = agent('front', {
  instructions:
    'You are the support agent of an online shop, in a conversation with a customer and, at times, a member of staff. ' +
    'Each message starts with who said it in brackets: [customer] or [staff <name>]. Never write a bracketed prefix yourself. ' +
    'Answer the customer plainly. When a member of staff speaks, follow their lead. ' +
    'When the customer asks about several orders, call spawn once per order with template researcher and a short name for each, ' +
    'then call join with all their names and stop. When the reports arrive, answer once and call close on the researchers. ' +
    'When the customer asks for a refund, call refund with the order number and the amount, then say whether it went through. ' +
    'When the customer\'s problem is solved, call set_label with key resolved and value true.',
})
  .wake('chat')
  .participants(['customer', 'staff'])
  .labels({ resolved: { type: 'boolean', mutable: true } })
  .subagents({ template: researcher, when: 'one order that needs looking up' })
  .tool({
    name: 'refund',
    description: 'Refund an order. A refund over $100 waits for a member of staff to approve it.',
    params: {
      type: 'object',
      properties: { order: { type: 'string' }, amount: { type: 'number' } },
      required: ['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`, { to: { role: 'staff' } });
      }
      return { refunded: true, order: String(args['order']), amount, approved_by: ctx.approved?.by ?? null };
    },
  });

export default bundle({
  app: 'support-desk',
  roots: [front],
  session: {
    roles: {
      customer: { max: 1, principal: true },
      staff: { max: 2 },
    },
    exposed: [front],
  },
});
```

What is new:

- `researcher` is a second agent. It has its own tool, `lookup_order`, which here returns a fixed answer. Replace its handler with a call to your order system.
- `.subagents({ template: researcher, when })` lets the front agent start researchers. The model gets four tools: `spawn` (start one from the template), `join` (wait for named ones to report), `send` (message one) and `close` (end one). `when` is a short phrase that tells the model when to spawn. Each researcher also gets `set_status`, a tool to say in one line what it is checking. The instructions tell the front agent to spawn one researcher per order, `join` them all, answer once, and `close` them. Researchers work at the same time, and what they spend counts against the session's cap.
- `.labels({ resolved: { type: 'boolean', mutable: true } })` declares a label: a typed tag on the session that you can search by. Because it is `mutable`, the model gets a `set_label` tool, and the instructions say to call it when the problem is solved. Later, `arbor session list --app support-desk --label resolved=true` lists only the conversations that ended well, without reading any of them.

### Stage 3: a room where staff can leave notes

```ts
import { agent, bundle, relay } from '@arbor/sdk';

const researcher = agent('researcher', {
  instructions:
    'You look up one question about an order for a support agent. Call set_status with what you are checking, ' +
    'call lookup_order, then report what you found in under 80 words.',
}).tool({
  name: 'lookup_order',
  description: 'Look up an order by its number. Returns its status and total.',
  params: { type: 'object', properties: { order: { type: 'string' } }, required: ['order'] },
  // A stand-in for your own order system.
  handler: (args) => ({ order: String(args['order']), status: 'shipped', total: 140 }),
});

const front = agent('front', {
  instructions:
    'You are the support agent of an online shop, in a conversation with a customer and, at times, a member of staff. ' +
    'Each message starts with who said it in brackets: [customer] or [staff <name>]. Never write a bracketed prefix yourself. ' +
    'Answer the customer plainly. When a member of staff speaks, follow their lead. ' +
    'When the customer asks about several orders, call spawn once per order with template researcher and a short name for each, ' +
    'then call join with all their names and stop. When the reports arrive, answer once and call close on the researchers. ' +
    'When the customer asks for a refund, call refund with the order number and the amount, then say whether it went through. ' +
    'When the customer\'s problem is solved, call set_label with key resolved and value true.',
})
  .wake('chat')
  .participants(['customer', 'staff'])
  .labels({ resolved: { type: 'boolean', mutable: true } })
  .subagents({ template: researcher, when: 'one order that needs looking up' })
  .tool({
    name: 'refund',
    description: 'Refund an order. A refund over $100 waits for a member of staff to approve it.',
    params: {
      type: 'object',
      properties: { order: { type: 'string' }, amount: { type: 'number' } },
      required: ['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`, { to: { role: 'staff' } });
      }
      return { refunded: true, order: String(args['order']), amount, approved_by: ctx.approved?.by ?? null };
    },
  });

const lobby = relay('lobby', {
  roles: ['customer', 'staff'],
  messages: {
    text: {},
    note: { for: { role: 'staff' } },
  },
});

export default bundle({
  app: 'support-desk',
  roots: [front, lobby],
  session: {
    roles: {
      customer: { max: 1, principal: true },
      staff: { max: 2 },
    },
    exposed: [front, lobby],
  },
});
```

What is new:

- `relay('lobby', { roles, messages })` makes a relay. Each message posted to it is re-emitted to the audience its kind calls for. `roles` lists the roles that may post and read. `messages` declares the kinds it takes, each with an audience.
- `text: {}` is a kind for everyone. `note: { for: { role: 'staff' } }` is a kind only holders of `staff` read. A customer who posts to the lobby is read by staff and the customer; a note from staff is never delivered to the customer. The names `text` and `note` are your own; any lower-case name works.
- To post a kind, put it in the message: `{"payload": {"kind": "note", "text": "..."}}`. A post with no `kind` is the first one declared, `text`.
- `roots: [front, lobby]` and `exposed: [front, lobby]` add the lobby beside the agent. The agent never reads the lobby, so a note is for people only. If a root that reads a relay were exposed, its reply would reach whoever reads it, so this example keeps the two rooms apart.
- The lobby has no model and no instructions: it is Arbor's own code. It costs nothing to run.

### Settings

```yaml
name: support-desk
role:
  customer: [anonymous, customer]
  staff: [employee]
app:
  budget: { session_micros: 100000 }
```

- `name` is the app these settings belong to.
- `role` says who may hold each role. Anyone with no account, and customers, are `customer`. Employees are `staff`.
- `app.budget.session_micros` is a spending cap for one session, in millionths of a dollar: `100000` is $0.10. It counts everything the session spends, researchers included.

### Try it

Open a session as the customer. An anonymous caller is a customer, and the command prints a session token on its error output, which you pass to later commands:

```sh
SID=$(arbor session open --app support-desk)
export ARBOR_TOKEN=<the customer's token>
arbor session chat --session $SID --text "Please refund order 7. It was \$40."
arbor session chat --session $SID --text "Now refund order 8. It was \$250."
```

The first refund runs at once. The second waits. Join as staff with an employee token, then list and answer what waits:

```sh
STAFF=$(arbor admin token --audience employee --scope sessions:create --scope sessions:read --scope sessions:write)
arbor session join --session $SID --role staff --token $STAFF
arbor session call list --session $SID --token $STAFF
arbor session call answer --session $SID --call <id> --approve --token $STAFF
```

The Chat tab shows the same thing as a card with Approve and Deny. Then ask about several orders in one message and watch the researchers in the console's session page. To use the lobby, post to it as each person with the route `POST /v1/apps/support-desk/sessions/{id}/roots/lobby/messages`, as the customer with `{"payload": {"text": "Any news?"}}` and as staff with `{"payload": {"kind": "note", "text": "Order 8 is lost. Refund it."}}`. Reading the lobby's outbox as the customer shows the text and not the note.

## 2. A game night

A narrator runs a fantasy adventure for a table of players. Everyone sees the table. Each player also has a private line to the narrator, for secrets and asides, which no other player can reach. The adventure runs over several evenings: what is true of the world is remembered from one evening to the next. Characters live on sheets, which are documents the narrator edits as the story goes. Rules for fights and journeys load only when the story needs them.

Who is in it:

- `table`, an agent: the narrator, for everyone at once.
- `whisper`, an agent made once per player: the private line.
- The people, in two roles: `dm` (the one who opens the evening) and `player`.

```mermaid
%% Who talks to whom at the game table
flowchart TB
  dm(["dm"]) --> table["table<br/>one narrator for everyone"]
  p1(["player 1"]) --> table
  p2(["player 2"]) --> table
  p1 --> w1["whisper[p1]"]
  p2 --> w2["whisper[p2]"]
```

### Stage 1: a shared table and a private line per player

```ts
import { agent, bundle } from '@arbor/sdk';

const table = agent('table', {
  instructions:
    'You are the narrator of a small fantasy adventure, telling it to the whole table. ' +
    'Each message starts with who said it in brackets: [player <name>] or [dm <name>]. Never write a bracketed prefix yourself. ' +
    'Keep the scene moving for everyone present.',
})
  .wake('chat')
  .participants(['player', 'dm']);

const whisper = agent('whisper', {
  instructions:
    'You are the narrator, in a private line with one player: secrets, asides, a private roll. ' +
    'Never repeat here what was said at the table, and never repeat at the table what is said here.',
})
  .wake('chat')
  .participants(['player'])
  .instance('participant');

export default bundle({
  app: 'game-night',
  roots: [table, whisper],
  session: {
    roles: {
      dm: { max: 1, principal: true },
      player: { max: 6 },
    },
    exposed: [table, whisper],
  },
});
```

What is new:

- `.participants(['player', 'dm'])` on `table` lets both roles talk to it, with each message tagged by who said it, as in the support desk.
- `.instance('participant')` on `whisper` makes it an instanced root: instead of one `whisper` for the session, Arbor makes one per player, the first time that player posts to it. Each is named `whisper[<participant id>]`, for example `whisper[p2]`. A player can reach only their own, and each starts with nothing of the others. A root without `.instance()` is a singleton, one for everyone, which is what `table` is.
- `session.roles` has two roles here. `dm` is the principal role, with `max: 1`: whoever opens the session. `player` has `max: 6` and joins on their own.
- `session.exposed: [table, whisper]` exposes both. For an instanced root, being exposed means each person reaches their own copy.

### Stage 2: a campaign that outlives the evening, and character sheets

```ts
import { agent, bundle } from '@arbor/sdk';

// A character sheet: one JSON document. A change is a merge patch, checked against this schema.
const sheet = {
  description: 'a character sheet',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string', minLength: 1 },
      hp: { type: 'integer', minimum: 0, maximum: 30 },
      inventory: { type: 'array', items: { type: 'string' } },
    },
    required: ['name', 'hp'],
    additionalProperties: false,
  },
  across: 'partition' as const,
};

const table = agent('table', {
  instructions:
    'You are the narrator of a long-running fantasy campaign, telling it to the whole table. ' +
    'Each message starts with who said it in brackets: [player <name>] or [dm <name>]. Never write a bracketed prefix yourself. ' +
    'When something becomes true of the world that later evenings must remember (a place, a person, an event), ' +
    'rewrite the world note with remember, keeping it under 400 characters. ' +
    'The secrets note is for the narrators only; never reveal it at the table. ' +
    'Keep every character on a sheet (kind sheet, named after the character, owned by its player: artifact_write with owner). ' +
    'When a character is hurt or heals, change only hp with artifact_patch.',
})
  .wake('chat')
  .participants(['player', 'dm'])
  .artifacts(['sheet'], { write: ['sheet'] });

const whisper = agent('whisper', {
  instructions:
    'You are the narrator, in a private line with one player: secrets, asides, a private roll. ' +
    'Never repeat here what was said at the table, and never repeat at the table what is said here. ' +
    'When the player sets up something the table must not know yet, add it to the secrets note with remember ' +
    '(keep what is there; under 400 characters).',
})
  .wake('chat')
  .participants(['player'])
  .instance('participant');

export default bundle({
  app: 'game-night',
  roots: [table, whisper],
  session: {
    roles: {
      dm: { max: 1, principal: true, may: ['artifacts.read'] },
      player: { max: 6, may: ['artifacts.create:sheet'] },
    },
    partition: 'campaign',
    exposed: [table, whisper],
  },
  inputs: { campaign: 'string' },
  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' },
      },
    },
    artifacts: { kinds: { sheet } },
  },
});
```

What is new:

- `inputs: { campaign: 'string' }` declares a value you give when you open a session. `session.partition: 'campaign'` names it as the **partition**: a key that groups sessions. Every evening of one campaign is a session with the same partition. The input is required, and only an operator or a service can set it, so a player cannot open an evening of someone else's campaign.
- `uses.memory` turns on the memory module. The model gets `remember`, `recall` and `forget` for facts it chooses to keep. `notes` declares two named notes, short texts kept outside the conversation. `across: 'partition'` is the reach: the note is shared by every evening of the campaign, so what the narrator writes on Monday is there on Tuesday. The instructions tell the narrator to write the `world` note when something becomes true that later evenings must know.
- `groups: { narrator: [table, whisper] }` names a group of agent definitions, and `among: 'narrator'` on `secrets` limits that note to them. Only `table` and `whisper` exist here, so both are in the group. It matters once you add another agent, such as a character the narrator voices: it would read `world` and never `secrets`. The instructions also tell the narrator never to reveal the note at the table.
- `sheet` is a kind of document, declared under `uses.artifacts.kinds`. Its `schema` is a JSON Schema, and Arbor checks every write against it: a character has a `name` and `hp` from 0 to 30, and nothing else beyond `inventory`. `across: 'partition'` keeps the same sheets for every evening of the campaign.
- `.artifacts(['sheet'], { write: ['sheet'] })` gives the narrator the tools to work with sheets. The first list is the kinds it reads, the `write` list the kinds it may change. It gets `artifact_list`, `artifact_write`, `artifact_patch`, `artifact_delete`, `artifact_pin`, `artifact_unpin`, `read` and (for kinds declared searchable) `search`. The narrator writes a sheet with `owner` set to the player, and a hurt character is a patch of `hp` alone: `artifact_patch` takes a JSON merge patch, so `{"hp": 7}` changes `hp` and nothing else. Each change is a new version.
- `may` on a role says what its holders may do with documents. `dm` may `artifacts.read` every kind. `player` may `artifacts.create:sheet`, which lets a player make a sheet, own it, and write the sheets they own. Anyone reads their own sheet whatever else they may read.

### Stage 3: rules that load when the story needs them

```ts
import { agent, bundle, fromPrompt, skill } from '@arbor/sdk';

const roll = (n: number): number[] => Array.from({ length: n }, () => 1 + Math.floor(Math.random() * 6));

const strike = {
  name: 'strike',
  description: "Resolve one attack: 2d6 plus the attacker's edge against the defender's guard. Returns the dice, hit or miss, and the harm dealt.",
  params: {
    type: 'object' as const,
    properties: {
      edge: { type: 'integer', description: "the attacker's edge, -1 to 3" },
      guard: { type: 'integer', description: "the defender's guard, usually 7 to 10" },
    },
    required: ['edge', 'guard'],
  },
  handler: (args: Record<string, unknown>) => {
    const dice = roll(2);
    const total = dice[0]! + dice[1]! + Number(args['edge']);
    const guard = Number(args['guard']);
    const hit = total >= guard;
    return { dice, total, guard, hit, harm: hit ? (total - guard >= 3 ? 2 : 1) : 0 };
  },
};

const forage = {
  name: 'forage',
  description: "Search for food at the end of a travel leg: 1d6 plus the party's woodcraft.",
  params: {
    type: 'object' as const,
    properties: { woodcraft: { type: 'integer', description: 'the best woodcraft in the party, 0 to 2' } },
    required: ['woodcraft'],
  },
  handler: (args: Record<string, unknown>) => {
    const total = roll(1)[0]! + Number(args['woodcraft']);
    return { total, days_found: total >= 6 ? 2 : total >= 4 ? 1 : 0 };
  },
};

const combat = skill('combat', {
  description: 'Resolving fights: who acts first, attacks against guard, harm and hp',
  prompt: fromPrompt('combat-rules'),
  tools: [strike],
});

const travel = skill('travel', {
  description: 'Journeys: legs, supplies, foraging and weather',
  prompt: fromPrompt('travel-rules'),
  tools: [forage],
});

const sheet = {
  description: 'a character sheet',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string', minLength: 1 },
      hp: { type: 'integer', minimum: 0, maximum: 30 },
      inventory: { type: 'array', items: { type: 'string' } },
    },
    required: ['name', 'hp'],
    additionalProperties: false,
  },
  across: 'partition' as const,
};

const table = agent('table', {
  instructions:
    'You are the narrator of a long-running fantasy campaign, telling it to the whole table. ' +
    'Each message starts with who said it in brackets: [player <name>] or [dm <name>]. Never write a bracketed prefix yourself. ' +
    'You know the story, not the rules. When a fight breaks out, load the combat skill (skill_load); ' +
    'when the party sets out on a journey, load the travel skill. Unload a skill when that part of the story is over. ' +
    'When a player asks how a rule works, call search with a few words and read the section; never invent a rule the rule book has. ' +
    'When something becomes true of the world that later evenings must remember, rewrite the world note with remember, under 400 characters. ' +
    'The secrets note is for the narrators only; never reveal it at the table. ' +
    'Keep every character on a sheet (kind sheet, named after the character, owned by its player: artifact_write with owner). ' +
    'When a character is hurt or heals, change only hp with artifact_patch.',
})
  .wake('chat')
  .participants(['player', 'dm'])
  .artifacts(['sheet'], { write: ['sheet'] })
  .skills([combat, travel], { maxLoaded: 2 })
  .docs({ search: true, paths: ['docs/rules/**'] });

const whisper = agent('whisper', {
  instructions:
    'You are the narrator, in a private line with one player: secrets, asides, a private roll. ' +
    'Never repeat here what was said at the table, and never repeat at the table what is said here. ' +
    'When the player sets up something the table must not know yet, add it to the secrets note with remember ' +
    '(keep what is there; under 400 characters).',
})
  .wake('chat')
  .participants(['player'])
  .instance('participant');

export default bundle({
  app: 'game-night',
  roots: [table, whisper],
  session: {
    roles: {
      dm: { max: 1, principal: true, may: ['artifacts.read'] },
      player: { max: 6, may: ['artifacts.create:sheet'] },
    },
    partition: 'campaign',
    exposed: [table, whisper],
  },
  inputs: { campaign: 'string' },
  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' },
      },
    },
    artifacts: { kinds: { sheet } },
  },
});
```

What is new:

- `skill(name, { description, prompt, tools })` makes a skill: a prompt of rules plus the tools that go with them. `combat` goes with the `strike` tool and `travel` with `forage`. A tool here is a plain object with the same fields `.tool()` takes, and `strike` and `forage` roll dice with `Math.random`.
- `fromPrompt('combat-rules')` points at a file the app ships, `prompts/combat-rules.md`. The rules are text a person can edit, not a string in the code.
- `.skills([combat, travel], { maxLoaded: 2 })` lists the skills the narrator may load. None is loaded at the start. The model gets `skill_list`, `skill_load` and `skill_unload`. While a skill is loaded, its rules and its tool are available, and `skill_unload` removes both. `maxLoaded` caps how many are loaded at once. The narrator's instructions say when: a fight starts, a journey begins.
- `.docs({ search: true, paths: ['docs/rules/**'] })` gives the model `search` and `read` over the files the app ships under `docs/rules/`. `search` returns the best-matching sections with snippets, and `read` returns one section whole, so the rule book never sits in the model's context. These two tools come from the artifacts module, which `uses.artifacts` already turns on.

The app now ships these files beside `app.ts`:

```text
prompts/combat-rules.md
prompts/travel-rules.md
docs/rules/combat.md
docs/rules/travel.md
```

`prompts/combat-rules.md`:

```md
Combat is told in rounds. At the start of a fight, settle who acts first as the
rule book's Initiative section says, then keep that order.

To resolve an attack, call strike with the attacker's edge and the defender's
guard. On a hit, take the harm strike returns from the defender's hp on their
sheet; at zero hp a character is out of the fight, not dead. Describe every roll
in the fiction: what the blow looks like, not the numbers.
```

`prompts/travel-rules.md`:

```md
A journey is told in legs of about a day. At the end of each leg, the party
spends one day of supplies; if the player asks to look for food, call forage
with the party's best woodcraft and add the days it finds.

A party with no supplies left grows weary: describe hunger, and lower every
edge by one until they eat. Weather is the narrator's to describe; look up
the Weather section of the rule book when it matters.
```

`docs/rules/combat.md` (the first of its sections; `travel.md` is written the same way, with Supplies, Foraging and Weather sections):

```md
# Combat

A fight is a short scene told in rounds. In each round, every character who is
still standing acts once, in initiative order.

## Initiative

When a fight begins, each side rolls one die and adds the edge of its quickest
member. The side with the higher total acts first; on a tie, the side that was
not surprised acts first, and if neither was surprised, the player's side
does. Initiative order holds until the fight ends or someone flees.
```

### Settings

```yaml
name: game-night
role:
  dm: [anonymous, customer, employee, service]
  player: [anonymous, customer, employee]
app:
  budget: { session_micros: 100000 }
  artifacts:
    sheet: { max_bytes: 16384, max_count: 50 }
```

- `role.dm` and `role.player` both admit the same kinds of caller. `dm` is the principal role, so the caller who opens the session is the `dm`, and anyone who joins afterward names `player` explicitly. `service` is in the `dm` list because opening an evening of a campaign takes an operator or a service.
- `app.budget.session_micros` caps one evening at $0.10.
- `app.artifacts.sheet` caps the documents of the `sheet` kind: `max_bytes` for one version and `max_count` for how many names. Without it the defaults are 256 KB for a structured version and 1000 names.

### Try it

As an operator, open the first evening of a campaign. The `campaign` input is required:

```sh
SID=$(arbor session open --app game-night --input campaign=ashfall)
arbor session send --session $SID --root table "Welcome, adventurers. The door creaks open."
```

Players join with their own tokens, then talk at the table and in their private line. A player's first post to `whisper` makes their own copy:

```sh
arbor session join --session $SID --role player --name Ana --token $ANA
arbor session send --session $SID --root table "I open the door." --token $ANA
arbor session send --session $SID --root whisper "Is there treasure in here?" --token $ANA
```

Ask the table for a sheet ("Ana joins the party: make her sheet"), then say "A goblin leaps out of the bushes". The narrator should load `combat`, may search the rule book for "initiative", and resolve the attack with `strike`. Say "We set off north for the hills" and it should switch to `travel`. Open a second evening with `--input campaign=ashfall` and the table already reads the `world` note and Ana's sheet. An evening of another campaign sees neither. The app's Partitions tab in the console lists the campaigns and their notes.

## 3. An engineering team

A small team shares one session. A desk at the front asks an outside directory service which group the conversation belongs to. Each person has an assistant of their own that reads their own Jira, using their own Atlassian account. There is also a coding agent that fixes a failing test in a repository and pushes a branch once a person approves. Every five minutes, a schedule asks each person's assistant for their open issues.

Who is in it:

- `desk`, a plain actor with no model: it works out the group and passes messages on.
- `assistant`, an agent made once per person, acting for that person.
- `coder`, an agent that works in a copy of a repository.
- The people, in one role: `engineer`.
- An outside service, the directory, which you run or already have.

```mermaid
%% Who talks to whom in the engineering team
flowchart TB
  eng(["engineers"]) --> desk["desk<br/>plain actor"]
  eng --> asst["assistant[person]<br/>agent, one per person"]
  eng --> coder["coder<br/>agent"]
  desk -- "asks" --> dir["directory service"]
  desk -- "peer edge: send" --> asst
  asst -- "jira.* tools" --> jira["Jira, the person's own account"]
  coder -- "spawns" --> ws["workspace<br/>clone of a repository"]
  sched["checkin schedule"] --> desk
```

### Stage 1: a desk that asks an outside service

```ts
import { actor, bundle, isMessage } from '@arbor/sdk';
import { endpoint } from 'arbor:http';

const desk = actor('desk', { state: { group: '' } })
  .labels({ group: { type: 'string', mutable: true } })
  .wake('chat')
  .receive(async (ctx, batch) => {
    for (const m of batch) {
      if (!isMessage(m, 'user_msg')) continue;

      if (!ctx.state.group) {
        const res = await endpoint('directory').get('/group', { query: { session: ctx.session.id } });
        ctx.state.group = (res.json as { group: string }).group;
        ctx.setLabel('group', ctx.state.group);
      }

      ctx.emit('reply', { text: `This conversation is in group ${ctx.state.group}.` });
    }
  });

export default bundle({
  app: 'eng-team',
  roots: [desk],
  session: { exposed: [desk] },
  http: { directory: { url: 'https://directory.example', methods: ['GET'] } },
});
```

What is new:

- `actor('desk', { state })` makes an actor: plain code, with no model. Its `state` is saved after every step, so any node can pick up the conversation. `.receive((ctx, batch) => ...)` is the code Arbor runs with the batch of messages that are due, and `.wake('chat')` runs it whenever a person writes. `isMessage(m, 'user_msg')` keeps only a person's messages.
- `endpoint('directory')` comes from `import { endpoint } from 'arbor:http'`. It is a handle to an outside service the bundle declares under `http`: a `url` and the `methods` it may be called with. `.get('/group', { query })` calls it. The call is recorded: if the node dies after the answer arrived and the turn runs again, the saved answer is used, and the directory is not asked a second time. The reply's body parsed as JSON is `res.json`.
- The desk asks only when it has no group yet, then keeps the answer in `ctx.state.group`, so each conversation asks once.
- `.labels({ group: ... })` and `ctx.setLabel('group', ...)` set a label, as in the support desk, here from code instead of from the model. The session page shows `group=PLAT`.
- `ctx.emit('reply', { text })` is how a plain actor speaks to the person.

### Stage 2: an assistant for each person, with their own Jira

```ts
import { actor, agent, bundle, isMessage } from '@arbor/sdk';
import { endpoint } from 'arbor:http';

const assistant = agent('assistant', {
  instructions:
    "You are one engineer's own Jira assistant. You act for this person alone, with their own Atlassian account, " +
    'through the jira tools. A message may start with [group NAME]: the group the conversation is in, which is also a Jira project key. ' +
    'When asked about their work, search with jira.searchJiraIssuesUsingJql and the JQL ' +
    '"project = NAME AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC" ' +
    '(if the tool asks for a cloudId, call jira.getAccessibleAtlassianResources first and use the first site). ' +
    'If the only jira tool you have is jira.connect, call it: it waits until the person connects their account. ' +
    'Answer with how many open issues they have, then each key and summary on its own line. Never invent an issue.',
})
  .wake('chat')
  .participants(['engineer'])
  .instance('participant')
  .principal('opener')
  .tools('jira.*');

const desk = actor('desk', { state: { group: '' } })
  .labels({ group: { type: 'string', mutable: true } })
  .participants(['engineer'])
  .wake('chat')
  .receive(async (ctx, batch) => {
    for (const m of batch) {
      if (!isMessage(m, 'user_msg')) continue;

      if (!ctx.state.group) {
        const res = await endpoint('directory').get('/group', { query: { session: ctx.session.id } });
        ctx.state.group = (res.json as { group: string }).group;
        ctx.setLabel('group', ctx.state.group);
      }

      const who = m.sender.principal === 'participant' ? m.sender.participant : '';
      const text = String((m.body as { text?: unknown }).text ?? '');
      try {
        // A send reaches an assistant that is already open; it never opens one.
        ctx.send(`assistant[${who}]`, 'user_msg', { text: `[group ${ctx.state.group}] ${text}` });
        ctx.emit('reply', { text: `Group ${ctx.state.group}. Sent to your own assistant, assistant[${who}]: it answers you alone.` });
      } catch {
        ctx.emit('reply', { text: `Group ${ctx.state.group}. Post to the assistant root once first: it opens just for you.` });
      }
    }
  });

export default bundle({
  app: 'eng-team',
  roots: [desk, assistant],
  session: {
    roles: { engineer: { max: 4, principal: true } },
    exposed: [desk, assistant],
  },
  peers: [{ from: desk, to: assistant }],
  http: { directory: { url: 'https://directory.example', methods: ['GET'] } },
  uses: {
    connections: {
      jira: { provider: 'atlassian-mcp', scopes: ['read:jira:agent-interface', 'search:jira:agent-interface'] },
    },
  },
});
```

What is new:

- `assistant` is an agent with `.instance('participant')`: one copy per person, made the first time that person posts to it, as in the game night's whisper. `.principal('opener')` says it acts for the person whose copy it is, so what it says is theirs alone, and a connection (below) it uses is theirs alone.
- `.tools('jira.*')` gives the assistant the tools of an outside tool server, here every tool whose name starts with `jira.`. Until the person connects their account, the only one it has is `jira.connect`, and calling it waits.
- `uses.connections.jira` declares a connection named `jira`. A connection is a person's own authorization to an outside service, kept by Arbor: no token appears in your code, in the model's view or in the ledger. `provider: 'atlassian-mcp'` names Atlassian's remote tool server, which the environment must know (below), and `scopes` is what you ask Atlassian's permission for, here reading and searching issues, the least the assistant needs. Without `scopes`, Atlassian grants its defaults, which include write access, and the publish warns about it.
- The desk's `peers: [{ from: desk, to: assistant }]` is an edge between two roots: a root may only send to a root it has an edge to. The desk then uses `ctx.send('assistant[<person>]', 'user_msg', { text })` to pass the message on. A send reaches an assistant that is open already and never opens one, so a person who has not posted to `assistant` yet gets a note saying to do that. The `try` and `catch` is how the desk tells the two cases apart.
- The desk prefixes the message with `[group PLAT]`, and the assistant's instructions say the name is a Jira project key, so its search is limited to that project. In this example a group is a Jira project.
- `m.sender.principal === 'participant'` is true when a person sent the message, and `m.sender.participant` is who. `engineer` is declared in `session.roles` with `max: 4`, and the desk and assistant admit it with `.participants(['engineer'])`.

### Stage 3: a coding agent and a check-in schedule

```ts
import { actor, agent, bundle, isMessage, workspace } from '@arbor/sdk';
import { endpoint } from 'arbor:http';

const assistant = agent('assistant', {
  instructions:
    "You are one engineer's own Jira assistant. You act for this person alone, with their own Atlassian account, " +
    'through the jira tools. A message may start with [group NAME]: the group the conversation is in, which is also a Jira project key. ' +
    'When asked about their work, search with jira.searchJiraIssuesUsingJql and the JQL ' +
    '"project = NAME AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC" ' +
    '(if the tool asks for a cloudId, call jira.getAccessibleAtlassianResources first and use the first site). ' +
    'If the only jira tool you have is jira.connect, call it: it waits until the person connects their account. ' +
    'Answer with how many open issues they have, then each key and summary on its own line. Never invent an issue.',
})
  .wake('chat')
  .participants(['engineer'])
  .instance('participant')
  .principal('opener')
  .tools('jira.*');

const coder = agent('coder', {
  instructions:
    'You fix failing tests in the repository app. Open a workspace on it first (spawn, template workspace, ' +
    'task app, name repo). Find the function with ws_grep, read it with ws_read, change it with ws_edit, ' +
    'commit with a message saying what you fixed and why, push the branch with ws_push, and report the branch.',
})
  .wake('chat')
  .participants(['engineer'])
  .subagents(workspace);

const CHECKIN = 'Scheduled check-in: how many Jira issues are assigned to you and not done? List their keys.';

const desk = actor('desk', { state: { group: '', checkins: 0 } })
  .labels({ group: { type: 'string', mutable: true } })
  .participants(['engineer'])
  .wake('chat')
  .receive(async (ctx, batch) => {
    for (const m of batch) {
      if (!isMessage(m, 'user_msg')) continue;

      if (!ctx.state.group) {
        const res = await endpoint('directory').get('/group', { query: { session: ctx.session.id } });
        ctx.state.group = (res.json as { group: string }).group;
        ctx.setLabel('group', ctx.state.group);
      }
      const prefix = `[group ${ctx.state.group}] `;

      if (m.sender.principal === 'participant') {
        const who = m.sender.participant;
        const text = String((m.body as { text?: unknown }).text ?? '');
        try {
          ctx.send(`assistant[${who}]`, 'user_msg', { text: prefix + text });
          ctx.emit('reply', { text: `Group ${ctx.state.group}. Sent to your own assistant, assistant[${who}]: it answers you alone.` });
        } catch {
          ctx.emit('reply', { text: `Group ${ctx.state.group}. Post to the assistant root once first: it opens just for you.` });
        }
        continue;
      }

      // The schedule's post: no person sent it. Ask every open assistant.
      let asked = 0;
      for (const a of await ctx.instances(assistant)) {
        ctx.send(`assistant[${a.key}]`, 'user_msg', { text: prefix + CHECKIN });
        asked += 1;
      }
      ctx.state.checkins += 1;
      ctx.emit('reply', { text: `Check-in ${ctx.state.checkins}: asked ${asked} assistant(s).` });
    }
  });

export default bundle({
  app: 'eng-team',
  roots: [desk, assistant, coder],
  session: {
    roles: { engineer: { max: 4, principal: true } },
    partition: { by: 'team', mode: 'one', from: 'identity.partition' },
    exposed: [desk, assistant, coder],
  },
  inputs: { team: 'string' },
  peers: [{ from: desk, to: assistant }],
  http: { directory: { url: 'https://directory.example', methods: ['GET'] } },
  uses: {
    coding: {},
    connections: {
      jira: { provider: 'atlassian-mcp', scopes: ['read:jira:agent-interface', 'search:jira:agent-interface'] },
    },
  },
  schedules: {
    checkin: { text: 'check in', description: "ask each open assistant for its person's open issues", root: desk },
  },
});
```

What is new:

- `coder` is an agent with `.subagents(workspace)`. `workspace` ships with the SDK: a child that holds a clone of a repository. Listing it gives the agent tools that each do one thing in the clone: `ws_read`, `ws_write`, `ws_edit`, `ws_list`, `ws_glob`, `ws_grep`, `ws_shell`, `ws_process`, `ws_status`, `ws_diff`, `ws_log`, `ws_commit`, `ws_checkout` and `ws_push`. Its instructions tell it to spawn the workspace with task `app`, which is the name of a repository in the settings, then find, read, edit, commit and push.
- `uses: { coding: {} }` turns on the coding module. What a workspace may clone is the environment's, in the settings, never the bundle's.
- The workspace commits on a branch of its own, `arbor/<session>/repo`. `ws_push` asks first: the first push of a session waits for a person to approve, and the branch lands on the remote only then. Every shell command runs under the node's operating system sandbox. A file may be edited only after the workspace has shown it to the agent (read before write).
- `schedules: { checkin: { text, description, root } }` declares a schedule: the text it posts, and the root that gets it. When it fires, the desk gets a message with no person behind it, so `m.sender.principal` is not `'participant'`. The desk then lists the open assistants with `await ctx.instances(assistant)`, sends each one the check-in text, and tells the room how many it asked. How often it fires, and whether it is on, are settings.
- `partition: { by: 'team', mode: 'one', from: 'identity.partition' }` groups sessions by a `team` input. `mode: 'one'` means at most one session of a team runs at a time, so a firing reaches it. `from: 'identity.partition'` takes the value from the signed-in caller's token, not from the request, so a person can only be in their own team's session. The schedule posts to the partition, as the app itself.
- A team is the people who share one session; a group is the part of it that the directory names. They are different things.

### Settings

```yaml
name: eng-team
role:
  engineer: [customer, employee]
app:
  budget: { session_micros: 200000 }
http:
  directory: { url: "http://127.0.0.1:8795" }
coding:
  repo:
    app:
      url: /tmp/eng-team/app.git
      push: branch
  sandbox: auto
schedule:
  checkin: { spec: "every 5m", partition: eng, overlap: allow, paused: true }
```

- `role.engineer` admits customers and employees. The first person to open the session holds the principal role, and the others join it.
- `app.budget` caps a session at $0.20, because it has agents.
- `http.directory.url` is where the directory service is in this place. The bundle's address is a default. A loopback address like this one is refused unless the node allows it (below).
- `coding.repo.app` names the repository the workspace may clone: `url` is a bare repository on the node, and `push: branch` lets it push branches only. A real repository is an `https` or `ssh` address with an `auth` entry that refers to a stored secret. `sandbox: auto` uses what the node has: Seatbelt on macOS, bubblewrap on Linux.
- `schedule.checkin` says when the schedule fires. `spec: "every 5m"` is how often, `partition: eng` is the team it posts to, `overlap: allow` lets a firing happen while the session is still running, and `paused: true` ships it off, so a freshly published app never calls Atlassian by itself.

The environment needs a few more things for the Jira connection, none of which goes in your code:

1. Atlassian's recipe, `atlassian-mcp`, which Arbor ships. `arbor admin recipe get atlassian-mcp` shows it.
2. The node's public address, as `--public-url`. Atlassian sends the person's browser back to `<public-url>/v1/connections/callback`. Atlassian allows `http://127.0.0.1` and `http://localhost` on any port by default.
3. A tools file, passed as `--tools tools.yaml`, that names the server by the recipe's address exactly:

   ```yaml
   mcp:
     - name: jira
       url: https://mcp.atlassian.com/v2/mcp
   ```

4. A root key for the node's stored secrets, `--master-key-ref`. Without one, tokens are stored in clear and the node warns.
5. Tokens bound to the team, because the partition comes from the token: `arbor admin token --subject alice --audience customer --partition eng`.

### Try it

First the directory. This stand-in answers every call with the group `PLAT` and needs only Python 3:

```python
import http.server, json

class Handler(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({"group": "PLAT"}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

http.server.HTTPServer(("127.0.0.1", 8795), Handler).serve_forever()
```

Run it, then start the node with permission to call that loopback address and publish the app:

```sh
python3 directory.py
arbor serve --data-dir ~/.arbor --http-allow 127.0.0.1:8795 --public-url http://127.0.0.1:8080 --tools tools.yaml
arbor seed --dir apps --only 03-eng-team
```

Stage 1 needs only the desk, the `role` and `http` settings. Open a session and send a message. The desk answers with the group, and the session page shows the `group=PLAT` label:

```sh
export ARBOR_TOKEN=$(arbor admin token --subject alice --audience customer --partition eng)   # the partition comes from the token
SID=$(arbor session open --app eng-team)
arbor session chat --session $SID --text "which plan suits me?"
```

For stages 2 and 3, join as a second person and post to the desk, then to your assistant:

```sh
arbor session join --session $SID --role engineer
arbor session send --session $SID --root desk "hello"        # says to post to assistant first
arbor session send --session $SID --root assistant "What are my open Jira issues?"
```

The assistant has one tool, `jira.connect`, and its call holds. The session's outbox (`arbor session outbox`, or the console's session page) shows a waiting call with the authorize link, which only that person reads. Open it, consent, and Atlassian sends the browser back to the node. The call runs again and the assistant lists the person's issues. The second person does the same, with their own link. Then:

```sh
arbor schedule resume checkin --app eng-team     # within five minutes the desk asks each open assistant
arbor schedule pause checkin
arbor connection list --app eng-team --session $SID
arbor connection revoke jira --app eng-team --session $SID --yes   # the next ask holds again
```

For the coder, make the repository the settings name, a bare remote with a failing test:

```sh
mkdir -p /tmp/eng-team && cd /tmp/eng-team
git init -q --bare -b main app.git && git clone -q app.git work && cd work
printf 'package calc\n\n// Add sums two numbers.\nfunc Add(a, b int) int { return a - b }\n' > calc.go
printf 'package calc\n\nimport "testing"\n\nfunc TestAdd(t *testing.T) {\n\tif Add(2, 3) != 5 {\n\t\tt.Fatal("Add(2, 3) != 5")\n\t}\n}\n' > calc_test.go
printf 'module calc\n\ngo 1.22\n' > go.mod
git add -A && git commit -qm seed && git push -q origin HEAD:main
```

The node needs a `--coding-home`. A coding agent also wants a model that holds its tool calls through a long turn, such as a frontier model through the gateway: the node's default open-weights model may return empty completions after its tool calls, and the turn then ends with no reply (`examples/seed/22-coding/README.md`). Then:

```sh
arbor session send --session $SID --root coder "TestAdd fails: Add(2, 3) gives -1"
arbor session workspace list $SID
arbor session workspace log $SID repo
arbor session call list --session $SID            # the first push waits for you
arbor session call answer --session $SID --call <id> --approve
git -C /tmp/eng-team/app.git branch               # arbor/<session>/repo
```

Because the app declares roles, the push is answered by the operators, not by the engineer who asked: that is the rule for any held call that names no one (`docs/model.md` §3.1, "Held calls"). The tool that holds the call is the SDK's, so the app cannot choose another approver for `ws_push`.

- [The building blocks](https://arbor.getloa.app/en/../blocks/): Every block on its own, in a few lines each.
- [Reference](https://arbor.getloa.app/en/../reference/): Look up a name, a setting or a command.

Loa Arbor. © Richard Clayton. All rights reserved. Intended licence: FSL-1.1-MIT, at launch. Coming soon: the download opens when the repository goes public.
