Loa/Arbor
English
  • English
  • 简体中文
  • 日本語
  • Español

Examples

Three apps, whole.

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

SpeedPlaying at 0.5× the speed it was recorded. Pauses longer than 2 seconds are cut to 2.
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

SpeedPlaying at 0.5× the speed it was recorded. Pauses longer than 2 seconds are cut to 2.
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 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:

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.
%% 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

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.
%% 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

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

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

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:

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:

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.
%% 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

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

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

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:

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

prompts/combat-rules.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:

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):

# 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

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:

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:

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.
%% 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

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

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

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

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:

    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:

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:

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:

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:

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:

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:

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:

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.