Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 79 additions & 1 deletion docs/agents.feature
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te
3. Whoever posts an item is its subscriber: what the person sends on it reaches that session, inside raea or out.
4. A session states its own role. One started from a template in raea gets the template's role without asking;
one started outside raea says who it is when it posts, and may change it.
5. There's no Director. The workspace has one primary: the harness that runs at its root (its own chats) and
whatever the person doesn't pick for. It's a provider on a model, or one of the person's agents; making an agent
the primary is how someone gets an orchestrator, and it's still only that choice (A6, Shane 11-12).

Background:
Given the app is apps/app (raea-feed): src/chat, src/agent, src/model/agents.ts, host/acp, host/feed-items.ts
Expand All @@ -48,9 +51,24 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te

Scenario: A1b. A template is a choice, never a requirement
Given a workspace with no agents
Then New chat, the feed's composer and a project's chat all work, each on the workspace's default provider
Then New chat, the feed's composer and a project's chat all work, each on the workspace's primary

Scenario: A1c. One menu picks the AI, its model or an agent
# Shane 11-12: "when I go to composer and I select a model, I could pick a model provider that I have, only show
# the ones that are connected ... groups with those model providers at the top of the dropdown, and then we
# could scroll down and look at our agents or type to search and select an agent"
# Status 11-12: built (raea-feed primary-agents: src/chat/RunsOn.tsx; e2e "New chat runs on a provider",
# "an agent is a provider on a model").
When I open what a chat runs on, under New chat's box
Then the AIs signed in on this Mac come first, Kimi first, each a group of its models; one that isn't signed in
or isn't on this Mac isn't offered (Settings → Plugins connects it)
And the person's agents come under them, each with its square mark and what it runs on
And typing searches both, and Enter picks the first match
And the pick is that chat's: the next New chat starts on the primary again

Rule: A2. raea ships no agent types
# Status 11-12: the dev page's sample agents (Planner, Builder, Cutter, ...) are authors only too: they keep their
# recorded sessions for the e2e suite, and no list offers them (raea-feed primary-agents, model/data.ts).
# Status 11-09: built (raea-feed 601d4ae). No Director or Critic is made; the planner and critique post as raea
# (raeaAgent, provider "raea"), tasks for it say @raea and an old brief's @director reads as raea. The built app's
# sample world keeps its agents as `by` authors only (model/data.ts sampleAuthors); the dev page keeps them as
Expand Down Expand Up @@ -139,3 +157,63 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te
And the hooks hold inside the raea app too, which runs each ACP agent with its own shell and config
And `raea show` names its poster from the harness that started it, found up its parent processes when the
harness doesn't mark its shell, so Kimi, OpenCode and the rest post as themselves with an inbox per session

Rule: A6. One primary, and agents are providers with more on top
# Shane 11-12: "in our docs we say like there's a director and the director owns everything. That's not really
# true. All we have is a primary agent harness that runs in the global root of the workspace ... I could assign an
# agent to be that level, that orchestrator or that like director, but it's really just a primary harness choice
# or model choice." And: "the ability to create an agent that is something beyond calling the model harness ...
# those agents ... are in fact just the model provider with all the same bells and whistles".
# Status 11-12: built (raea-feed primary-agents). The primary is settings.chatOn + chatModel (chat/provider.ts
# primaryOf); Settings → Agents sets it. Agents are kept as agents/<id>.json in the workspace's folder
# (host/agents.ts, POST /host/agents) with launch.model.

Scenario: A6a. The primary runs the workspace
Given Settings → Agents, whose first row is the primary, Kimi on its own default model until changed
When I pick an AI's model or one of my agents there
Then the workspace's own chats (New chat with no project, the Inbox's composer, the Controllers page's bar) run on
it at the workspace's root, and so does every chat, feed message and task where nothing else is picked or named
And no page calls it a Director: an agent made the primary is an orchestrator only because it's there

Scenario: A6b. An agent is a provider on a model, with its own name, instructions and tools
When I make an agent in Settings → Agents (New agent)
Then I pick what it runs on (Kimi, Claude, ChatGPT, Gemini, OpenCode, or a command of my own) and, for a provider,
one of its models, beside its name, colour, instructions, tools and approvals
And it's kept in the workspace's folder as agents/<id>.json, so it's there after a restart and travels with the
workspace's repo
And chats on it run its model with its instructions, as a chat on the bare provider would with none

Rule: A7. Each AI's own settings, for the AI and for an agent on it
# Shane 11-12: "acp allows us to adjust provider/harness specific options?" and "selecting a harness for a custom
# agent ... we would need the same settings and options once we select what we pick".
# An ACP session reports its config options (session/new configOptions): each has a category (mode, model,
# thought_level, model_config, or the AI's own) and is a select or a switch. Claude's: mode, model, effort, fast,
# ultracode. Kimi's: model, thinking, mode. raea draws them as reported, so no AI needs code of its own.
# Status 11-12: built (raea-feed primary-agents). Page: agent/AgentOptions.tsx, settings/AIOptions.tsx and the
# agent editor; host: app-prefs providers (POST /host/onboard ai-prefs), host/acp/hub.ts optionsFor, bridge.ts
# useOptions.

Scenario: A7a. An AI's defaults on this Mac
Given Settings → Agents, whose Your AIs lists every AI signed in on this Mac, each saying what's set for it
When I open an AI's Options
Then I see every setting it reports but its model, grouped as Thinking, Mode and More, each on Default, which names
the AI's own value
And I can give it environment variables (NAME=value) and extra arguments to start with
And what I save is kept on this Mac and reaches every chat on that AI started afterwards: the primary, a chat
picked in New chat, and an agent on it that doesn't set its own

Scenario: A7b. An agent on an AI has the same settings
When I pick what an agent runs on in its editor
Then the same settings show for that AI, each on Default, which names the value I gave the AI ("Claude's: High")
or else the AI's own
And what I set is the agent's (launch.options, launch.env, launch.extraArgs), and picking another AI starts them
over
And a command of my own has no settings to show; only its environment is kept

Scenario: A7c. Settings layer, and one that no longer applies says so
Given the AI's own default, then my defaults for the AI, then the agent's settings, then the chat's model
When a session starts
Then each setting is the last of those that sets it, applied with session/set_config_option
And one the AI no longer reports, or a value it refuses, is skipped with a notice in the chat, never a failure
And raea changes no mode for me: Approve everything (Settings → General) already answers the AI's permission asks,
so its own bypass or yolo mode, or a plan-only mode, is on only if I pick it
30 changes: 19 additions & 11 deletions docs/manual/tutorials/connect-your-agent.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
title: "Connect your agent"
summary: "Bring the AI you already pay for over ACP, add agents to your workspace with their own instructions, and start work with the Director."
summary: "Bring the AI you already pay for over ACP, pick the primary that runs your workspace, and make agents of your own when you want them."
order: 2
sources: ["apps/app/src/plugins", "apps/app/src/settings/Agents.tsx", "apps/app/src/agent/AgentEditor.tsx", "apps/app/src/acp", "apps/app/src/chat"]
tutorial: "connect-your-agent"
---

raea runs the agent you already use. This tutorial connects one, shows where your workspace's agents live, and
introduces the Director, the agent you talk to first.
raea runs the agent you already use. This tutorial connects one, picks the primary that runs your workspace, and
shows how to make agents of your own when you want them.

## How raea uses your agent

Expand All @@ -29,17 +29,25 @@ If your agent isn't listed, choose Your own agent, and give raea the command tha
over standard input and output will work. raea starts it in the project's folder, so it reads and writes the project's
files directly.

## Agents in your workspace
## The primary

Now open Settings, then Agents. Each agent here is a role, such as the Director, a Designer or an Animator, and each one
says which AI runs it and whether it's signed in. Press New agent to add another. Give it a name, choose what runs it,
and write its instructions in plain words. Agents belong to the workspace, so every project can call on them.
Now open Settings, then Agents. The first row is the primary: the AI that runs your workspace. It answers in New chat
when no project is picked, takes what you write in the Inbox and on the Controllers page, and starts any work you don't
hand to someone else. Pick any AI you've connected and one of its models, Kimi until you change it. That's all the
primary is. raea doesn't add a director or a cast of agents on top.

## The Director
## Choosing in New chat

Every workspace has a Director. It's the agent you talk to in New chat. It reads the whole workspace, makes projects,
and builds controllers when you ask for them. Write what you want in New chat, pick a project under the box, and the
Director starts the work there.
Under New chat's box, one menu says what the chat runs on. The AIs signed in on this computer come first, each with
its models, and your agents come after them. Type to search. What you pick is for that chat only; the next one starts
on the primary again.

## Agents of your own

raea ships no agents. When you want one, press New agent. An agent is one of your AIs with more on top: a name you can
mention with @, the model it runs, instructions in plain words, the tools it may use, and what it may do without
asking. It's kept in your workspace's folder, so it's still there tomorrow, and every project can call on it. You can
even make one the primary, if you want a lead that works your way.

## Agents in a terminal

Expand Down
4 changes: 2 additions & 2 deletions docs/manual/tutorials/controllers.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ saved at once, for the whole project.

## Make one in plain words

To add a controller, press New controller, and say what you want in plain words. The Director builds it from raea's
field types, and it appears on the page, ready to adjust.
To add a controller, press New controller, and say what you want in plain words. Your workspace's primary builds it
from raea's field types, and it appears on the page, ready to adjust.

## Workflows

Expand Down
2 changes: 1 addition & 1 deletion docs/manual/tutorials/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ to your agent. Take them in order the first time: each one builds on the one bef
## Start here

- [Get started with raea](get-started.md): download the app, sign in on raea.io, link your Mac, and land in your first project.
- [Connect your agent](connect-your-agent.md): bring the AI you already pay for, add agents to your workspace, and meet the Director.
- [Connect your agent](connect-your-agent.md): bring the AI you already pay for, pick the primary that runs your workspace, and make agents of your own.
- [A tour of the app](tour.md): what each part of the sidebar is for, from New chat to Settings.

## Make and review
Expand Down
12 changes: 10 additions & 2 deletions docs/manual/tutorials/tour.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,20 @@ menu, or make a new one for each client.
## New chat

New chat is where work starts. It's one box. Write what you want made, in your own words, and pick a project under the
box. The workspace's Director reads it and starts the work, and the session appears in the sidebar.
box. The workspace's primary, the AI you picked in Settings, reads it and starts the work, and the session appears in
the sidebar.

## Inbox

The Inbox gathers everything your agents make, across every project, newest first. Each card is the real thing: a
cut, a still, a sound, a board or a game. The number beside the Inbox counts what you haven't seen yet. The Inbox is the
best place to start your day.

When the Inbox or a feed gets long, fold it up: right-click past its cards, or open its settings, and choose
Consolidate. Everything but your pins becomes one summary on the timeline, which says how many, from when to when, what
kinds, who made them and how many are unread. It opens in place to its cards, a search still finds what's inside, and
Ungroup in its menu puts them back. What comes after shows as ever until you consolidate again.

## Publish

Publish is where finished work goes out, to the accounts you've connected, such as YouTube, LinkedIn or Bluesky. It
Expand All @@ -40,7 +46,9 @@ you publish to, generation services, and computers of your own.

Under Projects, each project is a folder. Open one, and it has three pages. The Feed shows the project's work. The
Compositions page shows what each piece is made of. And Controllers holds the project's settings, which every agent
works to. In the Feed, the Agents button lists the project's agents, and what each one is working on.
works to. In the Feed, the Agents button lists the project's agents, and what each one is working on. While an agent
works, a stop button sits beside it, in that list, beside its status in the Feed's chat and on the message it's
answering in the Inbox. Press it to stop that agent.

## Chats and Settings

Expand Down
Loading