Projects¶
Design of record for nested projects, project policies, agents in projects, project inboxes, scheduled agents and shared threads. The status table says what exists; this page says what is planned and in which phase.
Overview¶
A workspace becomes a coworking space: a tree of projects, each with channels, each channel with threads where people and agents work side by side. Nothing here is a second system. Each piece is built on what Humagen or fiber already has:
| Need | Built on |
|---|---|
| Nested projects | a new pkg/projects store on pkg/state. A project's name stays its identity, so nothing filed under a name moves |
| Project level policies | pkg/policy project scopes, applied along the project's chain of ancestors. A narrower scope only tightens |
| Platform and project agents | Humagen's project record. fiber's AgentSpec is unchanged. Checked once, at admission |
| Scheduled agents (recaps) | fiber's cron trigger through Humagen's schedules, filed in the project |
| Project inbox and announcements | pkg/inbox, read by Source.Project. An announcement is a message kind, not a store |
| Shared threads | Humagen's conversations (threads, branches, any agent on any turn), plus human messages that start no run |
| Find Help | Read-confined project and available-agent discovery; legacy explicit human questions keep their recorded addressing |
| Context | fiber's pinned system prompt (the agent's instructions), pkg/memory (agent and project notes), instructions on the project record, and the knowledge sources the project chain names, through fiber's knowledge hook |
Decisions:
- The workspace is the root project, written
~in addresses. Runs filed with no project (project: "") are filed at the root, so no run is re-keyed. Company-wide means "in the root". - The tree is a parent pointer, at most 4 levels below the root. A name
never changes;
titleis what people see. - Policies walk the chain. A run counts toward its project, every ancestor and the tenant, and is refused by the strictest. This lands in phase 1, with the first child project.
- No implicit routing. An agent answers when it is tagged (
@ignite). In the console an untagged message is a human message and starts no run, whatever default is set, unless the person picked agents for the conversation in the + menu: then each of them that decides to take it answers, or all of them. On Slack and GitHub, where mentioning the app is what asks, an untagged message goes to the default the thread inherits, if one is set, else it starts no run. A default of*searches the agents available there and asks the best few whether to join (see The dynamic router). The workspace baseline setting is replaced by the root's default. - Context is layered and explicit: the project chain's instructions and memory, then the agent's instructions and memory, then the thread.
- Every project has an inbox: the inbox messages whose
Source.Projectis that project. Announcements are items in it, from a person or from an agent scheduled in the project. A recap is such an agent, not a feature. - Shared threads are conversations with participants and a visibility. Anyone in a thread can tag a person or an agent.
- Route permission, then project role. Every route checks one tenant permission; the platform then checks the caller's role on that one project. A project role only narrows, never grants.
- Privacy is never claimed before it is enforced. Members-only projects and private threads are refused until every read path is confined (phase 7).
Concepts¶
The tree¶
~ Acme (root: everyone is a member) #general #announcements
├── Platform (team) #general #releases
├── Company news (company) #general
└── Field (team) #general
├── Globex (account) #general #renewals
└── Initech (account) #general
Members and reach apply from phase 2, when projects gain roles.
| Kind | Where it sits | Members by default | Its announcements reach | Notes |
|---|---|---|---|---|
| root | top, one per workspace | * member |
everyone | the workspace itself: cannot be moved, archived or deleted |
company |
under the root or another company project | * member, required |
everyone | at most 10. Created and changed only with projects:govern |
team |
anywhere | * member, creator owner |
its members and the members of projects below | the default kind |
account |
under a team or company project, never under an account | creator owner, * viewer (members only from phase 7) |
its members | for field engineers; carries account{customer, external_id, url} |
| custom | as its like |
as its like |
as its like |
a workspace label over team or account (phase 2). Behaviors stay closed and testable, names stay open |
A project inherits down the tree: policies tighten, instructions and memory
are sent, knowledge sources ground its runs, enabled agents add up, ownership
flows down. Membership, the *
entry and schedules do not flow down, and a child is never more open than its
parent.
Channels and threads¶
- Every project, the root included, has channels, like Slack channels.
generalalways exists and cannot be removed. A channel has an immutable slug, a title, a purpose and an optional default agent. A channel has the project's visibility today. The per-channel membership proposal narrows it further and requires approval before implementation. - Every thread is in exactly one channel of one project. A thread is a Humagen conversation: turns, branches, any agent on any turn. It gains participants (people and agents), an optional default agent and a visibility:
- shared: everyone who can see the project reads it, like a thread in a Slack channel;
- private: its participants only (phase 7).
A conversation the console starts is private: its starter's alone, the
first participant, until they share it. Share moves it into a channel
of a project (general by default, the project the person picked, else the
workspace) and makes it shared there, so everyone who can see that project
reads it and can join it; people named in the same step become
participants, each told once in their inbox ("Ana added you to Renewal
plan in Globex #general", a mention of the latest message, read where the
conversation is). One who cannot read that project is not added, and the
answer's not_added says so ("they cannot read this project, so they
were not added"), as a tag that cannot reach someone does. Only a participant shares, into a project they are a member
of; making a private conversation shared, or moving one, also takes whoever
started it or an owner of its project, so someone tagged into a private
conversation does not publish it. It moves to another project or channel
only while no run has been filed in it ("a conversation that has runs stays
in its project"), and a thread on a Slack or GitHub surface stays where and
as its binding filed it. A mention raised in it is read where it is now.
A default or a selected agent that cannot answer where it goes is dropped
in the same write. A message posted just before a move starts nothing for
a poster who may not post where the conversation went, and says so. Only a
participant moves one, so a governor who reads it without taking part does
not. Shared is not made private again.
- A thread may select agents to answer its untagged messages: agents (at
most 5, each available in the thread's project) and mode, join or
all. The console shows them as chips beside the composer, apart from
mentions, with the project chip, which is the thread's project.
POST /api/threads takes them, and PUT /api/threads/{id} changes them:
anyone who may post in the thread selects agents, while the title,
visibility and default stay its starter's or its project owners'. The same
PUT moves a private conversation to another project or channel (project,
channel), keeping it private, and takes the same people as Share: its
starter or an owner of its project, a member where it goes, and only while
no run has been filed in it (409). The selection answers only in the console: Slack and
GitHub keep their defaults. An agent the caller may not read is refused as
one that does not exist, left out of the view, and kept when the caller
rewrites the selection, while it still fits beside theirs and can answer
there (otherwise their selection wins, and no refusal names it).
- A turn is either a human message (a person posted; no run) or an
agent's run answering a message. A person posts only as themselves; no
route lets anyone post as an agent, and agent turns exist only as runs.
Per-channel membership (proposed)¶
Design for review, not implemented. Approval of this proposal is required before changing stores, API contracts, the Platform document or the console. The existing channel routes and records still inherit project visibility.
Channel record and writes¶
Add optional members: []string to projects.Channel, ChannelInput and
ChannelUpdate. Entries are subjects or role:<name>, using the project's
existing identity grammar and role matching. At most 100 distinct entries;
blank, duplicate, unknown-form and * entries are invalid. Machines match
only their own subject, never a role. There are no channel roles: this is an
additional audience restriction, and project roles still decide actions.
| Stored value | Ordinary readers |
|---|---|
Field absent (nil) |
Inherit the project's audience, as today |
| Nonempty list | Project viewers matching at least one entry |
Explicit [] |
Nobody; recovery requires projects:govern or the managed file |
The JSON representation must preserve absence versus []; omitempty on a
slice cannot express the contract. A PUT omitting members preserves the
stored value, null restores inheritance, and [] closes the channel.
Creation with the field absent inherits. general always inherits, so every
project retains its existing landing channel. No new channel or permission
kind is introduced.
Creation and changes use the existing projects:write route guard and
project-owner check. The creator must match a restricted audience, and a
writer must see the existing channel before changing it. An ordinary owner
cannot remove their own last matching entry; a governor may do so, including
writing []. Owners are not automatically channel members. A governor's
read remains break-glass, subject to the recorded-read design when it lands.
Membership changes use the channel's expected version, validate and persist
under the store lock, and append bounded project history in the same write.
File-managed membership follows the existing ErrManaged rule.
One read rule, including private threads¶
Extend Place with an optional channel and extend Seer with a channel
snapshot from the same project-tree revision. All thread records, shared as
well as private, supply their channel. A run, called run, housekeeping run,
artifact or inbox item belonging to a thread resolves its channel from that
thread, never from a caller's field. A direct channel read supplies its
channel explicitly. An unknown or malformed channel or inconsistent thread
placement fails closed. Existing conversations without a thread record use
general, with their existing private-thread rules unchanged.
For an ordinary reader the rule is:
project role >= viewer
AND (channel inherits OR reader matches channel.members)
AND (thread is shared OR reader participates in the private thread)
Project-owner inheritance cannot skip the channel term. Private participation
cannot skip it either: removing a channel member hides their old private
threads there too, without removing their participant record. A subject or
role in members grants nothing outside the project chain or beyond the
route's permission. projects:govern keeps its existing read override; the
surface-machine exception is constrained as described below.
Use this rule in p.Sees/Seer, not a second filter in channel handlers.
Apply it to channel lists and direct reads, threads, runs, events, manifests,
traces, journal, analytics, artifacts/downloads, inbox pages and counters,
project counts, context previews and client bindings. Hidden channels have
no name, purpose, membership, default, count or history in the response.
Project history must omit hidden channel changes, including their old and
new snapshots. No total or pagination hint may count omitted objects.
A direct request naming a hidden channel or thread answers exactly like a
missing one. Bound queries on the server, filter before pagination and
aggregation, and cache membership resolution once per channel per request.
Starting or posting in a channel needs the current project member role plus the channel read rule; invitation, Share and moves also check the destination channel. Existing private-thread authorization still applies. Adding a participant never adds them to channel membership. Check admission and message writes against the current audience under the existing admission coordination; a revocation stops subsequent reads, events and starts. A request already authorized or a running turn may have received content; revocation cannot retract it. After a membership change or move, refuse a queued turn whose asker no longer has access, and recheck before execution.
Restricted-channel content must not become project-wide notes, titles, recaps or notifications. Apply the private-thread prohibition on project memory proposals to restricted channels too. Project recaps include only threads every recipient may read; a project announcement remains project content, not a new way to publish channel content.
Slack bindings¶
Slack membership is not Humagen membership and is not synchronized. A bot post is visible to Slack's audience, which this API cannot confine. The first implementation therefore refuses a restricted channel's Slack binding and refuses to restrict a channel that has a binding or any retained surface-backed thread, even after unbinding. A client's home must also stay in an inherited channel. These checks run for API writes, managed files and replay validation; they return 409 for conflicting existing state and a path-specific configuration error for a file.
The existing surface-machine read exception remains only for inherited channels. A historical surface thread cannot become a route around a newly restricted audience. Binding lists and machine reads still apply the one read rule. A mapped person's posts and answers always check that person's project, channel and private-thread access. Later support for restricted Slack bindings requires its own audience and delivery design; it is outside this proposal.
Inbox and mentions¶
Thread-backed messages keep their thread identity, so both inbox pages and per-reader counter buckets evaluate the channel where the thread lives now. Do not cache an old audience in a notification or keep counters keyed only by project: distinguish channel/thread visibility where needed. Revocation hides old messages and updates counts on the next read, including project unread dots, search, snoozed items and SSE notices. Retention and per-reader read/hide state keep their current rules.
A direct mention, expert or role recipient is notified only when they can read both channel and thread. Private-thread invitations first require channel access, then add the participant atomically with the message. A rejected recipient receives nothing, and the poster gets the existing unreachable-recipient result without disclosing hidden channel or agent names. Role mentions in private threads keep their current restriction. Project announcements retain their project audience and never include restricted channel names or excerpts.
Platform document¶
Propose the same members field under both workspace.channels[] and
workspace.projects[].channels[]:
An omitted field inherits; members: [] closes. Explicit YAML null is
invalid in a declaration, so a mistyped list cannot silently broaden reads.
To restore inheritance, remove a previously managed members field; the
file's application clears its previous ownership and value together. A file
that never owned the field preserves an API-managed value. A file owns the
whole declared list, as for other managed fields. Platform.check validates
identity forms, duplicates, the 100-entry bound, general and Slack/home
conflicts, then startup validates retained surface threads before admitting
traffic. Roles may have no current holders, and subjects need not have
signed in; neither widens access. The implementation must update
docs/reference/spec.md, reference examples and their loader tests in its own PR.
Migration and implementation acceptance¶
Existing channel records and Platform documents lack members and therefore
inherit exactly as before. Do not rewrite thread ids, run tags, binding ids
or private participants. Keep nil and [] distinct through memory writes,
state serialization, Postgres and replay; reject malformed present values
rather than treating them as inherited. Archived restricted channels retain
their audience. Deleting a project must preserve channel audiences beside
its project tombstone while conversations or artifacts still reference them,
so deleted-project reads cannot fall back to project visibility.
A binary predating channel confinement ignores the new field and would expose restricted content. Once membership is configured, downgrade requires a snapshot restored from before the restriction, or a binary that implements this rule. Document that limit before shipping; changing field names alone cannot make old binaries enforce it.
The implementation PR must change api/openapi.yaml before make client,
keep one route permission in Server.Handler, and add tests that fail on the
current implementation. Required cases: project-only outsiders; owners not
listed; matching subjects and roles; machines; empty audiences; participants
removed from a channel; malformed replay; deleted projects; moves, Share and
mentions; surface binding/home conflicts; hidden history; count/pagination
parity; queued-turn revocation; and notes/recaps. Extend the GET, 404, empty
list, write and event-stream confinement sweeps with a restricted shared
thread and a private thread in the same visible project. Exercise restart,
replay and failed writes on memory and Postgres with no skips. Add console
membership states to scripts/screens and run phone and desktop checks.
Run every CI check listed in the task before opening that implementation PR.
Tagging and defaults¶
One grammar, parsed by the platform for every surface (pkg/threads):
| Token | Means |
|---|---|
@<agent> |
that agent answers. It must be available in the thread's project |
@<handle> |
that person is notified: their inbox, and Slack when a client maps them |
@sme or @sme:<topic> |
retired; no run or notification is created, and the person is directed to Find Help |
$<skill>, /<skill> or @skill:<skill> |
the agents the message starts are told to use that skill (see Skills) |
@<kind>:<name> |
an item of a mention kind the workspace declares, resolved as the kind says (see Mention kinds) |
<@U…> (Slack only) |
the Slack person, mapped to a subject through the client's slack.people |
A $ is a skill only when a skill's whole name follows it, so $5, $PATH
and $my_var stay text. A / is a skill, as a slash command, only in a
message posted through the API or the console, at the start of the message or
after a space, before a skill's whole name that ends the word, and only when
that skill is on the chain: /tmp/x, 1/2, and/or and a / that names no
skill stay text and refuse nothing. The console offers only /; $<skill>
and @skill:<skill> are quiet aliases it still reads, so older messages,
Slack and GitHub text and agents' instructions keep working, and it shows
them as /name. At most 10 names after a / that are no
skill are looked up; any after are text. A Slack or GitHub message reads a
/ only as one of its client's commands (see Skills). A skill nobody on the project's chain declares
refuses a message typed in the console with 400 "there is no skill called
...", before anything is posted; a message Slack or GitHub posted is there
already, so it is kept and the skill is refused, saying why. At most 4 skills
a message, and they count toward its 10 places for tags that are not agents'.
Agents are read in one roster read of the tenant's agents (at most 500, a
name past them looked up on its own), so a message tags any number of
them; the text's 8,000 characters bound them.
What a message starts, first rule that applies:
- It tags agents: each tagged agent answers, side by side, each
seeing the thread up to this message. A message has no cap on the agents
it tags; budgets, admission and room limits bound what they spend. A
message a person posts in the console, as themselves, that names a skill
and tags no agent asks the agents available there whether to join, as
the dynamic router does, and each that joins is
told to use the skill (
startsForSkillsininternal/platform), unless it was posted only; with no room left in its 10 places it is refused. A message a client posts, from Slack or GitHub or through the API for a person (act_as), keeps the client's defaults: the default answers it with the skill, as the client's commands are answered. An agent tagged and refused still counts as tagged. Whichever agents a message starts are told its skills.@autotags nobody: no one goes by it. - It tags only people, experts or a role: no run. It is a message to people.
- It answers a question or replies to a mention: no run. It is a human response.
- The poster chose Post Only: no run.
- It was posted in the console and the thread selects agents (rule
routed): withjoin(the default with two or more) each of them decides whether to take the message, as the dynamic router asks, and each that does answers, its run'spickedsaying why; with none, the best match among them answers, else the first of them; withalleach of them side by side (at most 3, soallover more than 3 is refused when it is set, 400); with one, that one. A message that names a skill goes to them too, and they are told to use it; tags in a message always win over the selection. An agent the poster may not read is passed over for them. - It was posted in the console, by a person as themselves: no run (rule
untagged). Console messages run only when they tag an agent, so a person can write several messages and nothing runs until they name one; the agent they name is then sent the conversation so far.post_onlyis still accepted there and means the same. - Otherwise, for a message a client posts from Slack or GitHub, the
inherited default answers: a named agent alone, or for
*each agent that joins. With none, no run.
The default is the first set of: the thread's, the client's (for a thread a Slack or GitHub client files outside a bound channel), the channel's, the project's, each ancestor's nearest first, the root's. A default must be available in the thread's project when it is written (400 otherwise). A default that has stopped being available is not skipped in favor of the next one: the message is kept as a human message and the answer says why (fail closed).
At most 10 mentions per message. A token inside inline code or a code block is not a tag.
Every run a message starts acts for the person who posted it, never for another participant: a tool that acts as a person uses the poster's own credential. The run is sent the room up to the message, as a mention in a Slack channel thread is: one turn a line, its line breaks made spaces, after who took it, a person by name and handle, which no one else has, and an agent marked as one. The room is fenced off from the poster's words, which follow with who posted them, so nothing anyone else wrote reads as the poster's, and another person's request in the thread is acted on with the poster's credential only when the poster's own words ask for it. A failed answer is retried only by the poster, from their inbox.
Find Help and legacy expert metadata¶
Find Help suggests at most eight readable projects and readable agents available there, using the person's description of work. It grants no access, starts no run and does not publish an existing private conversation. Choosing a result is explicit. Personal projects of other people and hidden projects/agents do not contribute names, scores, reasons or counts.
New @sme and custom expert-routing tags are refused with an actionable Find
Help message. They never expand stored expert lists or notify people. Expert
mention completion and the expert line in real turn composition and context
preview are removed together. Configuration check and startup warn about
retained experts and expert-resolving mention kinds. The compatibility expert
metadata endpoint is deprecated; it does not restore routing.
Stored expert metadata and historical messages remain readable under their
original confinement. Explicit human mentions, ask_person, approvals and
existing questions continue through their recorded recipients and answerer
rules. The question addressing compatibility path is retained so a parked
question is not stranded by this migration.
Skills¶
A skill is named instructions an agent can be told to use: a name, a description, an optional argument hint, and instructions of at most 8,000 characters. Its name and description are ones a SKILL.md takes (lower case words joined by single dashes, starting with a letter, at most 64; a description of at most 1,024), so a skill declared here can be written out as a skill package, and the tests hold the two to saige's parser.
- A project declares skills, at most 32, in the Platform document
(
workspace.skills,projects[].skills, the file's when set, even as[]) or throughPUT /api/projects/{name}/skillsby an owner (the workspace and company projects needprojects:govern). A change is recorded as askillschange. Only the project's own record keeps the instructions: a change's record, and a project as the API shows it, carry each skill's name, description and hint, and the skills route reads the instructions, so 32 skills of 8,000 characters never ride along in a list of projects or in history. - They are inherited down the tree, as knowledge sources are: a message posted in a project can name the skills its project declares, then each ancestor's, nearest first, each name once from the nearest project that declares it, at most 128. A sibling's or a child's are never offered.
- A person names one with
$<name>,@skill:<name>or, in the console, the slash command/<name>. Every run the message starts is told to use it: when the message is accepted,answerMessagepins each skill's instructions into the run's tag as_warp.skills, a private key fiber keeps out of every prompt and record, so every attempt, after a restart too, is told the same whatever the projects declare later. Admission drops the key from every tag but a root run the platform's API raised, which only the platform does, so no connector, schedule, caller or calling agent can put instructions in a run, and a run an agent calls is not told its caller's skills. - The executor seam (
callExecutor.resolve) takes the pinned skills out of the request's copy of the meta and puts their instructions ahead of the turn under a line that ranks them below the agent's own instructions and says the platform enforces limits whatever they say. The run's record keeps what was asked. - Each agent asked whether to join is sent the message and each skill's description, so a skill helps it decide.
- A Slack client's commands stay as they are. A command whose name is a
skill on the chain uses that skill: the client posts
/<name> ...as the message, and the runs it starts are told to use the skill. It is answered as the client's commands always were, by the default, without asking the agents.
A skill is read by whoever reads its project, with its instructions, as the project's own instructions are.
Mention kinds¶
@<kind>:<name> completes from its own list and resolves on the server.
The built-in kind is skill (@skill:review is $review); a workspace declares more
in its Platform document (workspace.mention_kinds, at most 16, the file's
alone), each resolving to one of:
resolves |
@<kind>:<name> is |
Completes from |
|---|---|---|
experts |
retired metadata only; new routing is refused | none |
skills |
$<name> |
the skills the chain offers |
role |
everyone holding the policy role <name> is notified, in one shared mention. In a private thread, which its holders cannot read, the tag is refused, saying so |
the roles the chain names in its members |
people |
@<name>: that person, by handle |
the directory, with people:read |
A kind declared under an agent's or a person's name takes an item: @ignite
is still the agent, @ignite:sre the kind. A kind nobody declared reads as
before kinds: the name before the colon. A kind's tag is recorded as what it
resolves to (sme, skill, role or person), and a role tag counts as
tagging people.
Context layers¶
An agent's turn is given, in this order:
| # | Layer | Source | Bound |
|---|---|---|---|
| 0 | The skills the message names, each under its name, after a line that ranks them below the agent's instructions | the pinned _warp.skills |
8,000 characters each, at most 4 named and a client's command |
| 1 | Project instructions, root first, then each project down to the thread's, then the channel's purpose | Project.Instructions, Channel.Purpose |
4,000 characters per project, 8,000 in all; the farthest ancestors are dropped first, with "(instructions of Acme not sent)" |
| 2 | Project memory, the thread's project first, then its ancestors | pkg/memory owners project:<name>, and project: for the root |
own notes as today (at most 15,000 characters); ancestors share 6,000, nearest first, with "(n more notes from Field not sent)" |
| 3 | The agent's instructions | the pinned revision's AgentSpec.SystemPrompt, which fiber sends as the system message |
fiber's |
| 4 | The agent's memory | pkg/memory owner <agent> |
as today |
| 5 | The thread | the branch so far, one turn a line: human messages, and follow-ups through the API, by the name and handle of who wrote or asked them, agents' answers by agent name, then a line that ends it and names who posted the message | the workspace history limit, as today |
| 6 | The message | as posted | 8,000 characters |
Which wins on conflict: the later instruction layer. The agent's instructions win over a project's, a child project's over its ancestors', and a project's over a skill the message names, which says how to do a task and not what holds here. Memory is facts, not instructions, and nothing in the thread changes instructions: a message directs the work within them. Anything that must hold whatever the prompt says is a policy, enforced by the platform and never written into the prompt: limits, availability, tool approvals, call policies. The first line of layer 1 says this in words, so the order of authority does not depend on position.
Inbox, announcements and scheduled agents¶
- A project's inbox is every inbox message whose
Source.Projectis the project (optionally with its descendants): alerts, failures, questions, results, artifacts, memory proposals and announcements about it. One store, one set of rights per kind, as today. - An announcement is a message of kind
announcementin a project's inbox, posted by a person, or by an agent scheduled in the project. It fans out to the members of that project and of every project below it. Who gets it is decided when read: one message, never a copy per person. - A recap is an agent scheduled inside a project: a project-owned schedule
on fiber's cron, running an agent available in the project, with
deliver: project. Its answer is posted as an announcement from that agent.
Roles (phase 2)¶
viewer < member < owner, granted by entries on the project: * (everyone
who can see the parent; at the root, everyone holding projects:read), a
subject, or role:<name>. People in IdP groups are reached through the policy
language, with no claims kept on the Principal:
and then {who: "role:field-eng", role: member} on the project. An owner of a
project owns everything below it. A role never grants a tenant permission: a
viewer listed as an owner still cannot write.
Data model¶
pkg/projects (new; the store pattern of pkg/clients)¶
package projects
type Kind string
const (
Company Kind = "company"
Team Kind = "team"
Account Kind = "account"
)
// KindSpec is a workspace's own label over a built-in behavior (phase 2).
type KindSpec struct {
Name Kind `json:"name"` // ^[a-z][a-z0-9-]{0,31}$, not a built-in
Title string `json:"title,omitempty"` // <= 40
Like Kind `json:"like"` // team or account
}
type Role string // "" < viewer < member < owner
const (
None Role = ""
Viewer Role = "viewer"
Member Role = "member"
Owner Role = "owner"
)
// Entry is one member. Who is "*", "role:<name>", or a subject (a subject
// that starts with "role:" is refused). It is not called Member, which is
// the role.
type Entry struct {
Who string `json:"who"`
Role Role `json:"role"`
}
// Expert is who answers for some topics here (phase 2).
type Expert struct {
Who string `json:"who"` // a subject or "role:<name>"
Topics []string `json:"topics"` // 1..8, each ^[a-z][a-z0-9-]{0,31}$
}
// Agents is what a project turns on (phase 3).
type Agents struct {
// Enable is platform agents available here and below. "*" alone is
// every platform agent. Nil adds nothing.
Enable []string `json:"enable"`
// Allow, when set, is the only agents that may run here and below:
// a policy that only tightens. Nil narrows nothing.
Allow []string `json:"allow,omitempty"`
// Default answers an untagged message: an agent, or "*" for every
// agent available to decide ("auto" reads as "*"). "" inherits.
Default string `json:"default,omitempty"`
}
type Account struct {
Customer string `json:"customer,omitempty"` // <= 120
ExternalID string `json:"external_id,omitempty"` // <= 120
URL string `json:"url,omitempty"` // https, <= 500
}
type Project struct {
Name string `json:"name"` // identity: immutable, ^[A-Za-z0-9][A-Za-z0-9 _-]{0,62}$; "" is the root
Title string `json:"title,omitempty"` // <= 80; the root shows Settings.WorkspaceName instead
Description string `json:"description,omitempty"` // <= 500
Kind Kind `json:"kind"` // default team; the root is company
Parent string `json:"parent,omitempty"` // "" is the root
Account *Account `json:"account,omitempty"` // account-like kinds only
Instructions string `json:"instructions,omitempty"` // <= 4000 (phase 1)
Members []Entry `json:"members"` // <= 100, never nil when stored (phase 2)
Experts []Expert `json:"experts"` // <= 50 (phase 2)
Kinds []KindSpec `json:"kinds,omitempty"` // root only, <= 16 (phase 2)
Archived bool `json:"archived,omitempty"` // phase 2
Agents Agents `json:"agents"` // phase 3
Announce Role `json:"announce,omitempty"` // lowest role that may post; default owner (phase 4)
AgentPosts string `json:"agent_posts,omitempty"` // publish | review (phase 5)
Knowledge []string `json:"knowledge,omitempty"` // <= 8 knowledge sources, inherited down the tree (phase 9)
Managed string `json:"managed,omitempty"` // "file" when a Platform document declares it
Version int `json:"version"` // from 1; every write names it
CreatedBy string `json:"created_by,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedBy string `json:"updated_by,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
}
// Channel is one place in a project where threads live (phase 6).
type Channel struct {
Project string `json:"project"` // "" is the root
Name string `json:"name"` // ^[a-z0-9][a-z0-9-]{0,39}$, immutable; "general" always exists
Title string `json:"title,omitempty"` // <= 80
Purpose string `json:"purpose,omitempty"` // <= 200, sent to agents
Default string `json:"default,omitempty"` // an agent or "*"; "" inherits from the project
Slack *SlackBinding `json:"slack,omitempty"` // phase 8: {client, channel}
Archived bool `json:"archived,omitempty"`
Managed string `json:"managed,omitempty"`
Version int `json:"version"`
// created/updated by and at, as on Project
}
// Change is one entry of the record of what changed.
type Change struct {
Seq int64 `json:"seq"`
At time.Time `json:"at"`
By string `json:"by"`
Project string `json:"project"`
What string `json:"what"` // created | updated | moved | archived | deleted | members | experts | agents | knowledge | channel | managed
Before json.RawMessage `json:"before,omitempty"`
After json.RawMessage `json:"after,omitempty"`
}
Store: Get, List, Create, Update(tenant, name, version, fn, by, at),
Move (phase 2), Delete, Tree(tenant),
History(tenant, name, limit, before), Upsert (the spec). Tree is an
immutable snapshot replaced on every write. Admission, Converse, the inbox
filter and the console each read one consistent tree, with no lock held
while they do their own work. It answers Chain(name) (the project, then its
ancestors, then the root), Subtree(name), Depth, Children,
Home(agent) and Resolve(name, reader) Access.
type Reader struct{ Subject string; Roles []string; Govern bool; Machine bool }
type Access struct{ Role Role; From, Via string } // via: "*", "role:x", subject, "owner above", "projects:govern"
Resolve is a pure function over the chain, root first. At each level it takes
the best matching entry. An owner above makes every level below owner. No role
at some level means no role below it. Govern is owner everywhere. A machine
matches * and its own subject only.
Storage. One namespace, projects, so a record and its history entry are
one state.Write (all or none within a namespace):
| Key | Value |
|---|---|
p:<name> (p: is the root) |
the project, with the fields the file owns |
c:<project>/<channel> |
a channel (names cannot hold /) |
h:<seq> |
a Change, a ring of 1,000 per tenant pruned in the same write |
x:<lower(name)> |
a tombstone {name, by, at, parent, members}, at most 1,000; one is forgotten to make room only when no conversation or file is filed under its name, and a delete that would need to forget one that has something is refused (429) |
Open(st) loads everything once and trusts its memory (one writer). A write
that fails changes nothing. Open refuses a cycle or an orphan (fail closed).
internal/platform/backends.go opens it beside the other stores.
HasProject, CreateProject and DeleteProject become calls to it. That
ends today's lost update in CreateProject, which reads and writes under
separate locks: check and insert become one critical section.
Invariants, checked under the store's lock before the write:
- A name is unique ignoring case, tombstones included, and never changes. A
tombstoned name is reused only with
projects:govern, recorded as "adopts its old conversations". However many deletes follow, a tombstone whose name still has conversations or files under it is never forgotten. - The parent exists in the same tenant and is not archived. Phase 1 fixes
the parent at creation, so no cycle can form. A move (phase 2) refuses a
parent inside the moved subtree, and requires
depth(parent) + 1 + height(moved) <= 4. Both checks run against the snapshot taken under the write lock. - Kinds: a company project sits under the root or a company project; an
account-like project never sits under an account-like one;
accountonly on account-like kinds; aKindSpecin use cannot be removed. - Openness only tightens:
rank(child's * entry) <= rank(parent's), where none < viewer < member and a*owner counts as member. A move that would widen who sees something is refused. Until phase 7 every chain must hold a*entry of at least viewer: members-only answers 409 "members-only projects need read confinement, not built". From phase 7 a members-only project cannot sit under a project with a*owner entry, since ownership flows down. - Delete is refused (409, naming them) while children, schedules, alert
rules or policies point at the project, so nothing is left pointing at a
name that no longer exists. From phase 2, archiving is the alternative.
Delete drops the project's memory and leaves a tombstone. Its
conversations keep the name, and are adopted only if a
projects:governholder recreates the project. Until then they are read, not continued, by whom they were read by when it was deleted: the tombstone keeps its parent and members, read under the parent as it stands now (phase 7). A run filed in a name the tree does not hold is refused at admission (409), since nothing says which ancestors it would count toward, and a file is published only in a project the tree holds. Files keep the ancestors they were published under, so a parent's storage still counts what a deleted child published. Delete never drops a policy: onlybilling:writeremoves one. - A file-managed project cannot be deleted through the API, and a field the
file sets answers 409
ErrManaged.
Bounds. Projects per tenant: 100 in phase 1 (today's cap), 500 from phase 2
with paging. Depth 4 below the root. Children per parent 100. Company projects
10. Members 100, experts 50, channels 20 per project, agent lists 64 (as
clients.Client.Agents).
Errors, mapped in Server.problem: ErrNotFound 404 (also for a project the
caller cannot see), ErrExists 409, ErrInvalid 400, ErrLimit 429,
ErrManaged, ErrInUse and ErrVersion 409, ErrForbidden 403.
pkg/threads (new, phase 6)¶
package threads
type Visibility string // "shared" | "private" (private from phase 7)
type Participant struct {
Kind string `json:"kind"` // person | agent
Name string `json:"name"` // subject or agent name
Owner bool `json:"owner,omitempty"` // the person who started it
AddedBy string `json:"added_by,omitempty"`
At time.Time `json:"at"`
}
type Thread struct {
ID string `json:"id"` // today's conversation id (its first run) or "th-..."
Project string `json:"project"` // "" is the root
Channel string `json:"channel"`
Title string `json:"title,omitempty"`
Visibility Visibility `json:"visibility"`
Participants []Participant `json:"participants"` // <= 100 held; one writer adds up to 50
Default string `json:"default,omitempty"`
Surface *Surface `json:"surface,omitempty"` // {client, channel, ts}: one Slack thread
Version int `json:"version"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// Message is a human turn. It starts no run of its own.
type Message struct {
ID string `json:"id"` // "m-<seq>"
Thread string `json:"thread"`
Prev string `json:"prev,omitempty"` // the turn it follows: a message, or a run of a conversation from before threads
By string `json:"by"` // the person's subject; never an agent
Name string `json:"name"` // display name when posted
Text string `json:"text"` // <= 8000
Mentions []Mention `json:"mentions"` // <= 10
Answers *AnswerRef `json:"answers,omitempty"` // {run, question}: recorded as that question's answer
Via string `json:"via"` // console | <client id>
SurfaceID string `json:"surface_id,omitempty"` // a Slack ts; makes a post idempotent
At time.Time `json:"at"`
}
type Mention struct {
Kind string `json:"kind"` // agent | person | sme | skill | role
Name string `json:"name"` // agent, subject, topic, skill or role
Run string `json:"run,omitempty"` // the run an agent tag started
Refused string `json:"refused,omitempty"` // why a tag started nothing
}
Namespace threads: t:<id> a thread, m:<thread>:<seq> a message,
s:<client>:<channel>:<ts> the surface index. At most 5,000 messages per
thread (then 409 "start a new thread"). A thread holds at most 100
participants: one writer adds up to 50, counting the ones they are shown,
and the people who post and the agents who answer join past that, as does a
conversation from before threads when its record is read. A workspace holds
at most 10,000 threads and a project 2,000 (429), a conversation from before
threads counting once its record is written. A person's message starts no
run, so no limit on runs holds it: a person posts at most 30 messages a
minute and a project takes at most 120 (429), counted in at most 10,000
windows. One message notifies at most 20 people and roles.
The record keeps a person by subject, the key they sign in with. What a
thread hands out names them by handle instead (a participant, an author, a
tag, who was notified, the people in a thread's summary, a mention's by),
and calls them by their name in the directory, or their handle without one,
so a subject that holds an address is never shown. People are added to and
removed from a thread by handle.
How it joins the run index:
- A tagged agent's run has
Prev= the message andwarp.messagemeta = the message id. Runs that answer one message are shown together, not as branches. A branch is a message posted after an earlier turn, as today. Pathwalks messages and runs; the transcript (threads.Ask) renders a message asDana (@dana): textand a run asignite (agent): answer, each on one line. A run that answers no message, a follow-up through the API or a run of a conversation from before threads, renders as who asked it and its text, then its answer. The words the run answers follow a closing line that names who posted them.- A conversation with no record reads as shared, in
generalof its project, with the people its runs acted for, and its agents, as participants. A record is written the first time anything about it changes. Nothing is migrated in bulk.
pkg/people (new, phase 2)¶
The directory that tagging and member lists need: Person{Subject, Name,
Handle, SeenAt}, written at sign-in and when a client maps a Slack person. At
most 5,000 per tenant. Handle is ^[a-z0-9][a-z0-9._-]{0,31}$, unique per
tenant across people and agent names. A new agent named like a handle is
refused (409 "a person goes by @dana"), and a colliding handle at first
sign-in gets a suffix. auto and sme are reserved: no agent or person is
named either. No email is asked for
or shown: a subject that holds an address (a Tailscale login) is kept as the
key it is, left out of the directory, and subjects are never searched.
Changes to existing stores¶
| Store | Change | Phase |
|---|---|---|
platform.Settings |
projects leaves the wire. A storage-only type, storedSettings{Settings; LegacyProjects []Project}, is read once by the migration, because today one struct is both the wire and the record |
1 |
platform.Settings |
Baseline is removed; the root's Agents.Default replaces it |
3 |
runs.Run |
Within []string (ancestors nearest first, pinned at admission as warp.within), Channel, Message |
1, 6 |
runs.Index |
per-project counters {Threads, Active, ActiveAt}, updated in Record and on status changes, replacing the Threads(tenant, 0) scan in listProjects. ThreadQuery.Projects []string (one project or its subtree) and Channel |
1, 6 |
runs.Index.Summarize |
a project filter (a set of names, at most the subtree cap) | 5 |
policy.Store.For |
For(tenant, chain []string, agent, client): agent, client, the project and each ancestor nearest first, then the tenant. Decide applies all, so the strictest wins |
1 |
policy.Policy |
Authority (admin or owner); existing policies are admin |
2 |
usage.Entry |
Within []string. admission.scopes() adds p\x00<ancestor> for each; matches checks the project or Within. Spent and settled entries take the run's pinned Within |
1 |
| storage limits | storageAllows sums what Tree.Subtree holds for a project policy, and what was published below the project in one deleted since: an artifact keeps the ancestors it was published under (Within, stored and not on the wire) |
1 |
pkg/memory |
owner project: for the root's notes: it holds the colon no agent's name can, so no agent shares them |
1 |
pkg/inbox |
kind announcement; Message.Broadcast (stored, json:"-"); per-reader hide and snooze for broadcasts; Audience entry project:<name>; Reader.Projects; Query.Projects; Count returns updates; Withdraw takes by (today it records "system") |
4 |
pkg/inbox |
part draft (actions publish, discard) |
5 |
pkg/inbox |
kind mention, part mention (actions reply, done) |
6 |
pkg/prefs |
Muted []string (at most 100 project names) |
4 |
pkg/clients |
Home{Project, Channel} (default root, general) |
8 |
A project's context¶
A project is governance plus context for sessions. Besides its instructions,
its context is the corpora it attaches (Project.Context.Corpora, at most
20): every session filed there and below searches them, the project's own
first and each ancestor's after, each once, at most 40 (Tree.Corpora). A
corpus is the Knowledge store's; a project only names it. Attaching one needs
ownership of the project and that the owner may read the corpus, and makes
no one its reader: a session searches it only as each of its readers may. A
corpus a reader may not read, or one deleted since, is left out of what they
are shown and kept when they save, so saving never drops what they were not
shown (GET, PUT /api/projects/{name}/corpora).
Agents in projects¶
Agents are independent of projects¶
No agent lives in a project. Any agent answers in any project, limited by policy, not by a home:
allowed(P) = ∩ over Q in Chain(P) with Q.Allow set, of Q.Allow (none set: no narrowing)
available(P) = allowed(P)
A project's allow list is its agent policy, and a child cannot widen it.
A project's enable list and its own default, and a channel's default,
were how a project chose its agents. They are kept as stored and are not
read: an untagged message falls to the thread's default, then the client's,
then the workspace default (workspace.agents.default, the root's
Agents.Default). The Projects page has no Agents tab and no project shows
agents.
An agent's home survives only as who sees the agent, its Access:
- Workspace: no home, or the root. Everyone sees it, and it answers
anywhere it is allowed. The built-ins are the workspace's:
humagen(the entry agent, which also builds agents) andapproverin every workspace, and, once a workspace installs them from the agent store,humagen-writerandhumagen-analyst(Core) andcode-reviewer,security-reviewer,architect-reviewerandqa-reviewer(Review). - Members of a project: homed in a project. Its readers see it. Homed in a project everyone reads, it answers anywhere; homed in one kept to its members, it answers only where its readers alone read (that project and its subtree as open as it), so nothing it says reaches someone who may not see it.
- Private: homed in a Personal project, the same rule with one reader.
A stored home that names no project, or cannot be read, never refuses the
workspace: it fails closed, and nobody but projects:govern sees the agent.
Editing a homed agent still needs ownership of its home. Agent access as its
own member list, migrated once from the homes, is the likely next step.
Enforcement: one check, at admission¶
In Platform.Invoke, after placeOf and under p.admission, a run filed in a
project (the root included) must use an agent that answers there
(Platform.answersIn: allowed, and seen by everyone who reads the project).
If it does not, it is refused with ErrNotAvailable (403): "globex-helper is
not allowed in Initech", or that it is private. A refusal never says where
the agent's home is. This covers every origin, because every run passes
through admission: API turns and thread messages; cron and run-now (a
schedule whose agent stops being allowed keeps firing, is refused, and raises
the existing failure message); called runs, filed where their root is; Slack
and GitHub tags; and evals. The call tool offers, and the router asks, only
the agents that answer where the run is filed.
Housekeeping (OriginSystem) is exempt, as it is from admission. It is read
where the turn it serves is. A reader's counts are decided as of one moment,
so a conversation opened while they are read, a housekeeping run's or a
private thread's, is counted from the next read. Earlier checks use the same
function and give the same answer sooner: writing a schedule, a default or a
tag, and GET /api/join. An agent the writer may not read is not one they
are told about: naming it answers as naming an agent that does not exist, at
every one of them.
Homes¶
PUT /api/agents/{name}/home {project} sets who sees an agent. It needs
agents:write and ownership of the new home and of the old one, and answers
409 only while the agent's default skills would not fit the new home.
Schedules, alert rules, clients and defaults that use the agent hold no
change back. The spec says the same on Humagen's wrapper:
agents: [{project: Globex, spec: {...}}].
The entry agent¶
Every workspace has one entry agent, humagen unless the spec names another
(branding.entry_agent), shipped with the platform's own agents on the same
models (package humagen/entry). It is the agent people talk to the workspace
through: a console session started with no mention, where no named default
answers, belongs to it. It answers each message there in one run, the
response's root: it answers simple asks itself and brings specialists in with
the agent tool, each call a run nested under the call that made it, then
answers once, naming who did what. No run picks who answers first, and an
answer opens no child session. Routing has no page and no switch of its own:
it is this agent, on its own model. The runtime's session tools are not
offered to it.
- A message gets one answer. With no other agent mentioned, the session's
agent answers. Exactly one other agent mentioned answers the message itself,
in the session: it is the root, the entry agent does not run, and, having no
transcript of its own there, it is sent the conversation so far. Several
agents mentioned (at most 3) are each asked by the platform before the entry
agent's first model step, as
agentcalls of its run (internal/platform/mention_calls.go): activity shows them where its own calls show, and the model is never shown a tool call it did not make. What they said reaches it as content of the person's turn, and it is told to write each result as given under a heading with its agent's name, then a short synthesis if one helps. A mentioned agent that cannot be asked is said so in its place, and one whose call policy holds calls for a person is asked only once a person approves: the root parks on that approval first. An answer is limited to what its place's readers may read: an agent that lives where not everyone who reads the conversation's project reads is not asked there, mentioned alone or beside others, and the poster is told why and where it can be asked (the mention'srefused). This holds in every session, whoever owns it; where the entry agent cannot run, each mentioned agent answers for itself. A child session opens only when a request asks for one by option (agentwithfreshorlabelonPOST /api/sessions/{id}/messages). -
Why an answer came from where it did is activity. A root the platform chose (a mentioned agent, or a search match standing in for the entry agent) says why on its node of the message's trace (
pick), never as a line of the conversation. -
Who answers a console session, in order: an agent the message mentions; a default that names an agent (thread, client, workspace); the entry agent; without one (a server that ships no agents of its own), routing by search (below), so the message still lands.
- It is told who may fit. Each message it answers comes with the strong matches among the best 3 agents search finds (their names, the words that matched and their instructions, loaded only for these) and every other agent it may call with what it is for (its description, or its prompt's first sentence), so it can choose by meaning where words did not match. It leaves out agents the poster may not read.
- When it cannot run (its models name no provider the workspace has enabled or a model policy it no longer has, asked before a run is started, or it is refused where the message is), a strong search match answers as the root in its place, else the workspace's named default. A weak match, one passing word of a prompt, is never handed the message: it is refused with why the entry agent cannot run. A run that starts and then fails is a failed answer, not handed on.
- It may call every other agent whose definition pins (
Access.Spawn, kept by the platform). A run pins its whole call tree, so an agent that no longer pins is left out rather than stopping the entry agent. The list is worked out again only when an agent is added, revised or retired, and the entry agent is revised only when it changes. Each call is still held to the place: an agent not available in the session's project is refused there, as are call policy, budget and depth. EntryAgent(tenant)gives its name and the name people see (the workspace's branding, else Humagen), which the GitHub check run uses.
Root sessions on chat surfaces¶
A thread on a chat surface, a Slack thread today, has one root session, as a
console chat does: the place's, keyed by its address
(slack://<team>/<channel>/<thread ts>) and owned by the entry agent (or,
on a server that ships no agents of its own, by the client's default). The
chat service (apps/chat) posts each person's message to POST /api/sessions
with surface and act_as; only the client's own machine may, for a person
of the client. The first message starts the root (201), filed where the
Slack channel is bound, else in the client's home (private for a direct
message); every later message in the thread lands in it (200), once however
often it is sent. The one agent a message mentions answers it in the root; a
message naming nobody is the entry agent's.
The request may not say where to file the session or who owns it. A Slack
thread that started as a conversation before root sessions stays one (409).
The dynamic router¶
A message that names no agent, where the default it inherits is *
("everyone decides"), is routed by search, not by asking every agent
(pkg/join). The agents available there are searched first: BM25 over each
one's name (counted three times), what it is for (its description, or its
prompt's first sentence, counted twice), its system prompt and the asks it
answered well (an answer a person rated up files its ask under the agent,
pkg/goodasks; a rating taken back or turned down drops it, and a run that
read private context is never filed). An agent needs no description written
for routing. Common words and the filler of an instruction ("in one line",
"briefly", "what should I use instead", "identify yourself") are left out of
both the message and the agents. A match is strong when a word of the
message is in the agent's name or what it is for, or two or more words
match; one passing word of the rest of a prompt is weak. A handle kept from
before a rename (warp-writer and the like) is searched only where its
current agent is not offered, so the same agent is never listed twice. Only the best 3
matches are asked one low-effort question, all at once: "should I be
involved?". Each that says yes joins and answers in the same thread, each
reply posted and streamed on its own; in Slack, in the same Slack thread. At
most 64 agents are searched and at most 5 join one message. When search
finds nobody, nobody is asked.
A message always lands or says why, from every surface: the console, the
Slack app, a GitHub mention, the API. A message with no mention, where the
default is * or unset, goes to the entry agent, which answers it or calls
whoever fits; it answers only through a client that may route to it, and
calls only agents that client may route to. Without an entry agent there,
it goes to the best match that said yes, or with none saying yes to the
best match search found; the run
records why in warp.picked ("Joined on its own: ...", or "Picked by
search: matched deploy, cost."), which the console shows with the answer,
never before it. When search matches nobody, the workspace's named default
answers ("No agent matched it, so the workspace default answered."), else
the first agent available there. Only a place with no agent the poster may
ask refuses the message.
*is a default, never an agent's name. A default that names an agent still answers alone, and an unset default still inherits. A default stored or written asautoreads as*.autostays reserved: no agent or person is named it.@autois not a tag; no one goes by it.- An agent opts out with
tagged_only: truein its spec (fiber'sAgentSpec): it runs only when a message names it, and is never asked about one that does not. Off by default. - No workspace setting chooses the model that asks: routing moves to
the entry agent, a built-in that picks on its own model chain. Until it
lands, no agent takes a message on its own unless a program built on
Humagen supplies its own asker through
platform.Config.Router;join.Wordsis a deterministic one, with no model, that tests use. - An asker that fails, or an answer it cannot read, counts as no.
- A run that joined on its own records
warp.picked, "Joined on its own:". GET /api/join?q=<message>&project=<name>(agents:read) previews each agent's answer,{decisions: [{agent, join, reason}]}, without starting anything: the agents search found answer, every other one says search passed it over. Agents the caller may not read are left out.POST /api/runswithagentomitted uses the default chain; with none set, oragent: "*"(orauto), the message lands as above: the entry agent's run, or the first run that joined, is returned and the others start in the same conversation. Only a place where no agent may answer is 409 "tag an agent".
Clients¶
A client's DefaultAgent follows the same rule, as one more layer. It is the
default for the threads the client files outside a bound channel: DMs, the
assistant pane, an unbound channel, a GitHub issue. The order there is the
thread, then the client, then the client's home channel and its chain. In a
bound Slack channel the bound Humagen channel's chain decides. The client's
allow-list (client.Routes) still filters the result: a default the client
may not route to is refused, never swapped. A GitHub label starts nothing:
automatic review is the connection's switch. A client's default may be *, and fiber's
in-process connectors may ask for it too; surface.stamp then asks the
agents available where the run is filed that the client may route to, before
admission, and each that joins gets a tag of its own. The Slack app built on
the API names the client it answers for: POST /api/runs takes act_as
{client, user}, and Converse applies that client's allow-list and default,
asking only the agents the client may route to.
stamp also writes warp.project and warp.channel from the binding, and
runs.ProjectOf believes them for slack and github origins, because
ingress overwrites whatever a connector put there (phase 8).
How context maps onto fiber and Humagen¶
- The agent's instructions are its pinned
AgentSpec.SystemPrompt. fiber sends them as the system message for that revision. Humagen never rewrites them per run.runtime.Request.Instructionsstays only the host's return contract (fiber: "callers must not supply arbitrary system text"), so project instructions are not put there. - Layers 1, 2, 4, 5 and 6 are composed into the turn's text by one function,
p.contextOf(place, agent), and pinned in the ledger with the tag, so every attempt replays the same bytes. Converse uses it for thread turns. Invoke uses it forcronandmanualruns filed in a project, so a scheduled agent gets its project's instructions and memory (today only API conversations get memory). Called runs keep their explicit input messages. - Memory stays in
pkg/memory: owner<agent>,project:<name>, andproject:for the root. An agent's name cannot hold a colon, so no agent owns a project's notes, and the agent memory routes answer 404 for a project's owner: a project's notes are changed only through its own routes and the inbox, each asking what the project asks. The memory agent writes as today: to the run's own project, or to the agent for a run at the root. It never writes from a private thread (phase 7), nor from a conversation that acted for a person with a person-scoped tool, whose answers may carry what that person's own credential reached. Withmemory_auto_approveon, what it writes for the workspace or a company project still waits for someone holdingprojects:govern, since the turn that taught it needed onlyruns:write. What it writes for any other project is kept unasked only when the person the turn was for may change the project's notes themselves (phase 4: an owner): a member's turn teaches only proposals, which reach the project's owners, as a member's own note does. Filing the turn decides it, and the turn carries it. - Knowledge sources are inherited down the tree (phase 9). A project, the
workspace included, names at most 8 of the workspace's knowledge sources
(
Project.Knowledge). A run filed in a project is grounded in the project's, then each ancestor's, nearest first, each once from the nearest project that names it, at most 16, besides its agent's own (Tree.Knowledge). A sibling's and a child's are never given. - Pinned at accept.
pinwrites them into the tag as_warp.sources, over whatever a caller put there, under that key or the publicwarp.sourcesruns were pinned with before, which is still read for them. So every attempt of the run, after a restart too, is grounded in the same sources whatever the projects name later. A called run is given its root's, as it counts toward its root's ancestors. A housekeeping run, filed at the workspace whatever turn it serves, is given none. - Through the executor seam.
callExecutor.resolve, which already rewrites the revision for model policies, adds them to the request's copy of the revision'sSources(asknowledge://<name>) before fiber's knowledge hook reads them, so the run's retriever searches them in its own tenant. The pinned definition is not changed, and fiber is not changed. - Confined. A project's sources ground only the runs filed in it and
below it. A source is the workspace's, read with
knowledge:readwherever it is named, so naming one in a project takes an owner andknowledge:read(403), which reads it anyway, and a source the workspace has (400). A reader withoutknowledge:readis shown no source's name: not in the knowledge route, the project's record or its history. The run's pin is a private key of its tag (_warp.sources), which fiber keeps out of everything a model is sent, so the model is grounded in the sources without being told their names. Deleting a source a project names is refused (409), naming the projects the caller can see, or saying only that a project names it to a caller withoutprojects:read; a source that does not exist is not found (404). A project hidden from the caller does not hold the delete up and is not named: it keeps the name, which grounds nothing until a source of that name is made again, and an edit of its list is not refused for it. A source the workspace no longer has grounds nothing, as one an agent names does. - fiber's own thread journal (
pkg/thread) is per agent by design ("not a transcript of the room"), so Humagen keeps its own room transcript.
Announcements and recaps¶
Carrier: the inbox¶
- New kind
announcement, info only (its part isPartInfo), never in "Needs you".reads(announcement) = projects:read.writesis alsoprojects:read, because hiding your own copy changes nothing others see. Message.Broadcastis stored on the raised message. On a broadcast, Dismiss and Snooze record only the reader's own state (tenant.hidden[id][subject]). Replaying theDidDismissandDidSnoozechanges of broadcast messages rebuilds it. Every other message keeps today's shared state. Withdraw stays shared and records who withdrew.Countreturns{open, unread, updates}. Broadcasts count only inupdates; every existing kind counts exactly as today, so the badge and the phone's dot never grow from announcements. From phase 9 it adds up counters instead of reading every message (see Retention and counts).
Fan-out, decided when read¶
An announcement in P has Source.Project = P and Audience ["project:P"].
Message.For matches project:P when P is in Reader.Projects. The platform
computes that set from the tree on each read. It holds every project where the
reader is a member (an explicit entry, or * at member or above) and every
ancestor of those. So an announcement reaches the members of P and of every
project below it. Viewers who are not members can read it in the project's
inbox but are not sent it. Muted projects (prefs.Muted) are left out of a
person's inbox, never out of the project's. The root cannot be muted.
- The root's announcements reach everyone: company-wide.
- A company project's announcements reach everyone (its
*entry must be member). - An account's announcements reach its account team.
Revoking membership hides past announcements at the next read. SSE inbox
notices are filtered by InboxSees and For(reader), so an id from a project
the reader cannot see never reaches their stream.
Who posts¶
- People:
POST /api/projects/{name}/announcementswith{subject, text, severity}, by anyone whose role is at leastProject.Announce(owner by default).From{person}, keyannounce:<project>:<seq>. The author or an owner withdraws it. - Agents, on a schedule (phase 5): a schedule filed in P with
deliver: projectand an agent available in P. When its cron or run-now run completes,ended()raises an announcementFrom{agent}: - the first line is the subject (at most 150 characters) and the rest is the text (at most 4,000);
- an answer of
NONEposts nothing; - the run is linked.
Under agent_posts: review it is raised instead as a draft (kind
announcement, part draft, actions Publish and Discard), addressed to P's
owners. Publishing raises the announcement from the agent and records who
approved it. agent_posts defaults to review at the root and in company
projects, which everyone reads, and to publish in team and account
projects.
- deliver: inbox sends the answer to the schedule's creator (kind
result), which closes the gap that a scheduled run's answer reaches nobody
today.
- Humagen: a release's notes in the root, From{system, humagen} (see
Release notes).
A recap is a scheduled agent¶
Nothing recap-specific is stored. "Add Weekly Recap" on a project creates a
schedule: a jittered Monday morning, humagen-analyst (installed with the
Core package from the agent store, or any agent available there), the text "What changed in {title} since the last recap?",
deliver: project. It is a cron run: admitted, counted under every limit on
the chain, never housekeeping. Its grounding:
- the project's instructions and memory, through the context layers;
project_changes(days <= 31), a built-in read tool granted tohumagen-analystand to any agent an admin grants it. It reads only the run's own project subtree:- runs (a
Summarizefiltered by project); - threads started and finished;
- artifacts, approved notes and announcements;
- schedule and project record changes. A change of an agent's home names the agent only when everyone the recap reaches may read it.
It returns at most 50 rows a section and 32 KB in all. A run with no
project gets an error;
- runs_summary gains a project argument.
Model text is untrusted. Announcements are plain text, Slack mention syntax
(<!here>, <!channel>, <@U…>, <!subteam^…>) is escaped before
rendering, and the run that wrote the text is one click away.
Bounds¶
20 announcements per project per day and 200 per tenant per day (429). 20 open drafts per project. A project inbox page is at most 200 (default 30) with a cursor. What was settled for everyone is kept for the inbox's retention, 90 days by default (see Retention and counts).
Release notes (phase 9)¶
workspace.release_notes: true (default false) posts the running version's
feat entries from the embedded CHANGELOG.md into the root's inbox as
From{system, humagen}, keyed release:<version>, once.
- The module root package embeds CHANGELOG.md, the one package that can
reach it, and
internal/releasereads it: a release is a## 0.16.0 (date)heading, and itsfeatentries are its### Breakingand### Featuresgroups, each entry without its markup and commit link. The release tool files a breakingfeatunder Breaking alone and does not write an entry's type, so a breaking change of another type is posted too. Fixes and the rest are not posted. - The running version is what a release build stamps with
-ldflags, which counts only in Humagen's own binary, else the module version Go records for Humagen, in its binary or in a program that imports it.dev, a local build and a pseudo-version are not releases, and post nothing. - At each start, once the Platform documents are applied, each workspace
that sets it is posted the release, unless it has no breaking changes
and no features.
inbox.Store.PostOncechecks the key under the inbox lock: an announcement ever raised under it, withdrawn or not, is kept, and its key outlives it once retention drops it, so a restart or a later process on the same database posts nothing. Caller keys cannot start withannounce:, which ordinary posts use for their own keys. It is an announcement like any other in the root: everyone reads it, What's new shows it, and Hide for Me hides one reader's copy. - The Slack app connects after the start, and catches up on a bound
project's announcements when it does, so the notes reach a channel bound
to the workspace's general before that start. A reply under their post starts a thread
seeded with them, from Humagen (
ThreadAnnouncement.kindsystem,byhumagen), which the room shows without a person's or an agent's mark and a run is sent ashumagen (system).
Retention and counts (phase 9)¶
workspace.inbox_retention (default 90d, at least 7d, at most 100 years;
whole days or a Go duration such as 2160h) is how long a workspace's inbox
keeps what was settled for everyone. The platform passes it in
Config.InboxRetention, and at start and every hour after
inbox.Store.Retain drops what was settled before then.
- What goes. A message resolved, dismissed or withdrawn for everyone before the cut, with no question in it that a run still waits on, and every change recorded about it: its raise, its outcomes, each reader's reads and hides, and each client's receipts. Nothing open or snoozed goes. An announcement stays while it is open for anyone, whoever hid their own copy.
- The record. Each change is kept under its own key, as before, and a
retention step deletes the dropped messages' records and writes the tenant's
cut (key
cut) in one write, all or none, at most 5,000 operations a step, including the cut. The cut holds the number of the last id issued and the keys of announcements posted once. If one message has more history than a step can delete, the cut also names it while later steps delete the rest. Replay reads the cut first and skips those records, so an interrupted cleanup never brings a message back. It applies each kept raise under the id its record names, with-state=postgresas in memory. The inbox changes only once its step is written; a step that cannot be written changes nothing and is tried again at the next pass. - What never repeats. No message id is issued again, and a key posted
once (
release:<version>) is never posted again (PostOnce, which reads the cut's keys). Receipts and keys of what is kept still find it; those of what was dropped find nothing, so a reply under the Slack post of an announcement withdrawn and dropped starts a thread as any other there, and a thread seeded with one no longer shows it. - Counts.
Countis answered from counters kept as changes apply and rebuilt on replay. The open messages are kept in buckets alike in kind, addressing and what they are about (Source's run, project, thread and agent), each with how many it holds and, for each reader, how many of them they read or, for a broadcast, hid. A count asks who may see each bucket once, as the read rule asks of a message (Query.Sees,Visible,For), and adds up what is left. What reopens by itself with time is read one by one: messages snoozed for everyone, kept in groups alike as buckets are, so the read rule is asked once for each group, and the reader's own snoozes of broadcasts. A settled message is never read.
Permissions¶
New tenant permissions¶
pkg/auth gains, in Permissions():
projects:read: see projects, their inboxes, channels, instructions, memory, experts and people.projects:write: create projects, and do what your project role allows.projects:govern: break-glass. Owner of every project, the root included. Needed to create or change company projects and to adopt a tombstoned name.
default.authz:
role viewer { allow read on * } # gains projects:read
role operator extends viewer { allow write on runs, schedules, alerts, evals, artifacts, projects }
role manager extends operator { allow write on agents, knowledge }
role admin { allow * on * } # gains projects:govern
Operators keep what they have today ("anyone who can start a run can make a project"). The same change updates:
- the legacy table in
pkg/auth/policy_test.go; - the
Permissionenum inapi/openapi.yaml; everythingininternal/httpapi/observe_test.go;apps/web/src/access.ts(PERMISSIONS,doing,NOTABLE: "projects:govern owns every project") and its test;- docs/architecture/security.md and docs/reference/authorization.md.
Route permission, then project role¶
Every route checks exactly one permission in Server.Handler. The platform
then checks Resolve(chain, reader).Role on the one project the route names,
the way inbox resolution checks each part. Effective =
who.Can(route permission) && role >= needed. A project the caller cannot see
answers 404, with the body of a missing one; a visible project with too low a
role answers 403 ("you need to own Globex"). Another tenant's project is 404
everywhere; the tenant comes only from who.Tenant. Until phase 2 there are
no roles: the route permission alone decides, and company kind and the root
need projects:govern.
| Action | Route permission | Role needed (from phase 2) |
|---|---|---|
| See a project, its inbox, channels, instructions, memory, experts | projects:read |
viewer |
| Create a project under P (top level: P is the root) | projects:write |
member of P. Company kind: projects:govern |
| Edit title, description, instructions, account | projects:write |
owner |
| Move | projects:write |
owner, and member of the new parent. Leaving an ancestor that holds a policy also needs billing:write, and so does moving a project that holds, or has below it, an owner's limit the caller could not change before (they do not own the parent it was set from): a move never escapes a limit. Leaving an ancestor whose allow list keeps agents out needs owning it, unless the new chain allows no more: a move never widens which agents may run. Nor does it leave anything below it without an agent it has now (409, naming each): a project's, a channel's or a thread's default, an agent that lives there, or a schedule filed there. An archived channel holds no move back |
| Archive, delete | projects:write |
owner |
Members, experts, channels, agents (enable, allow, default), announce, agent_posts |
projects:write |
owner |
| Knowledge sources (phase 9) | projects:write |
owner, and knowledge:read |
| Make an agent live here | agents:write |
owner of the new and old home |
| Edit a homed agent: its spec, call policy and notes, in its routes and the inbox | agents:write |
owner of its home |
| Propose a project note (stored pending, owners approve in the inbox) | projects:write |
member |
| Add an approved note, approve, remove, in the memory routes and the inbox | projects:write |
owner; the workspace and company projects: projects:govern too, and an owner without it proposes |
| Set any project's limit | billing:write (unchanged) |
none |
Set a tighten-only limit on a descendant (Authority: owner; never touches an admin policy) |
projects:write |
owner of a strict ancestor |
| Post an announcement | projects:write |
announce (default owner) |
| Withdraw an announcement | projects:write |
its author or an owner |
| Publish or discard an agent's draft | runs:read (the inbox resolve route) |
needs(draft, publish) is projects:write, then owner |
| Schedule in P, change, pause, delete or run one filed there | schedules:write |
member; the agent available in P |
| Read a shared thread and its runs | runs:read |
viewer |
| Read a private thread and its runs (phase 7) | runs:read |
participant, or projects:govern |
| Start a thread, post a message | runs:write |
member; in a private thread, participant. A viewer posts only an answer to what they were asked (a question a run put to them, or a reply to a message that tagged them) that tags no one, which starts nothing and notifies no one: an answer's tags start agents and notify people as any message's do, so tagging in one takes a member. An answer is posted only if it is the one the run was given (409 for a question already answered, or whose run stopped), so a viewer posts once for each question |
| Tag an agent | runs:write |
member; the agent available in P |
Tag a person or @sme |
runs:write |
member; the person must be at least a viewer of P, or they are not told and the poster is ("they cannot read this project, so they were not told"). In a private thread, tagging a person invites them; a role's holders are told only in a shared thread |
| Add to or remove from a shared thread | runs:write |
member (removing anyone but oneself: the thread's owner or a project owner) |
| Invite to or remove from a private thread | runs:write |
participant (remove: the thread's owner or a project owner) |
| Change a thread's visibility, title or default | runs:write |
the thread's owner while a member, or a project owner |
| Answer an expert's question | runs:write (existing answer routes) |
fiber's answerers check, unchanged |
Machines hold exactly their scopes and match only * and their own subject. A
surface acting for a person (act_as) is checked against that person's own
roles on the project, as answering questions is today, and against their own
tenant permission: starting a run for them, posting for them and answering
for them each need their runs:write, which the policy grants their subject. Agents are never
members: their relation to a project is availability.
Default deny¶
A stored project never has nil members or a nil enable. An unknown who
form is 400. A reader with no subject matches nothing. An omitted members on
create becomes [{who: "*", role: member}, {who: <creator>, role: owner}],
which is what every project meant before. This is a documented exception, kept
for continuity. For account, the * entry is viewer instead of member, and
there is none from phase 7.
API¶
Every route is written literally in projectRoutes, threadRoutes or the
existing groups as mux.HandleFunc("METHOD /path", s.authed(auth.X, h)). In
api/openapi.yaml each has an operationId, a tag (projects, threads),
x-permission, declared path params, inline query enums (the oag 0.20.6
$ref bug) and the shared responses. Bodies keep DisallowUnknownFields and
the 1 MiB cap, and field caps are mirrored as maxLength and maxItems.
Project history also uses opaque project-scoped seq identifiers and cursors.
The tenant-global sequence remains internal, so gaps never reveal another
person's project activity. The HMAC key is persisted atomically with history
and survives replay. Old numeric/base64 history cursors must be refreshed.
Lists use opaque before/next cursors ending in next: null; a bad cursor
is 400; an empty list is []. Then run make client, make client-check
and make spec-lint, and update the hand-written apps/web/src/api.ts
mirror. {name} is ~ for the root (a name cannot start with ~).
Phase 1¶
| Route | Permission | Notes |
|---|---|---|
GET /api/projects |
projects:read |
?parent=&within=. {projects: ProjectView[]} in tree order, at most 100. ProjectView = Project + {depth, path: [{name, title, kind}] (<= 4), children, conversations, active, active_at?, schedules, notes, proposed}. Today's updated_at, which meant activity, becomes active_at |
POST /api/projects |
projects:write |
ProjectInput{name, title?, description?, kind?, parent?, account?, instructions?} → 201. 400 kind rule or depth; 409 exists; 429 cap |
GET /api/projects/{name} |
projects:read |
ProjectDetail{project: ProjectView, ancestors (<= 4), children (<= 100), limits: [{scope, from}]} |
PUT /api/projects/{name} |
projects:write |
ProjectUpdate{version, title, description, account, instructions}; name, kind, parent are 400. 409 stale version or managed field |
DELETE /api/projects/{name} |
projects:write |
204; 409 ErrInUse names what still points at it |
GET /api/projects/{name}/history |
projects:read |
?limit (<= 200, default 50)&before → {changes, next} |
| memory routes | projects:read (GET) / projects:write |
paths and shapes unchanged; regated from runs:* |
GET /api/threads |
runs:read |
gains project=&within= |
GET /api/settings, PUT /api/settings |
unchanged | projects removed; a PUT that names it is 400 |
PUT /api/policies |
billing:write |
exists() reads the store; applied along the chain |
Phase 2¶
| Route | Permission | Notes |
|---|---|---|
GET /api/projects |
projects:read |
paged: limit (<= 200), before, q (name, title, description, customer), kind; the cap rises to 500. Each view adds access {role, from, via} and actions: string[] |
GET, PUT /api/projects/{name}/members |
projects:read / projects:write |
{version, members (<= 100)}; GET also lists inherited owners with from |
GET, PUT /api/projects/{name}/experts |
projects:read / projects:write |
{version, experts (<= 50)} |
POST /api/projects/{name}/move |
projects:write |
{version, parent} → ProjectView. 400 cycle, depth, kind, openness; 403 the limit rule; 409 a default, a homed agent or a schedule below it that would lose its agent |
PUT /api/projects/{name} |
projects:write |
gains kind, archived; on the root, kinds |
PUT, DELETE /api/projects/{name}/limits |
projects:write |
owner of a strict ancestor; writes a project-scope policy with Authority: owner; looser than the effective chain is 400 naming the binding scope; an admin policy is 409 |
GET /api/people |
people:read |
?q=&limit= (<= 50)&before= → {people: [{subject?, name?, handle, roles, picture, seen_at?, projects?, projects_more?}], next}; a subject that holds an address is left out, and so is anyone known only by one. projects is the person's own projects the reader may see (none without projects:read), at most 20 |
Phase 3¶
| Route | Permission | Notes |
|---|---|---|
GET, PUT /api/projects/{name}/agents |
projects:read / projects:write |
{version, enable (<= 64), allow?, default?}; GET adds available {all, names (<= 64)}, homes, default_resolved {agent, from} |
PUT /api/agents/{name}/home |
agents:write |
{project} ("" is none); 409 in use |
GET /api/agents/{name} |
agents:read |
gains home |
GET /api/join |
agents:read |
?q=&project=, each agent's answer without starting anything; replaces GET /api/pick |
POST /api/runs |
runs:write |
agent omitted uses the default chain; none is 409; * (or auto) asks every agent available, and none taking it is 409; not available is 403 |
PUT /api/settings |
agents:write |
baseline removed (400) |
Phase 4¶
| Route | Permission | Notes |
|---|---|---|
GET /api/projects/{name}/inbox |
projects:read |
?kind (inline enum, repeatable) &children&state&limit&before (state open or all) → {messages, next}. A project: audience entry matches any reader of the project here |
POST /api/projects/{name}/announcements |
projects:write |
{subject 1..150, text 1..4000, severity} (info or warning) → 201 InboxMessage; 429 rate |
DELETE /api/projects/{name}/announcements/{id} |
projects:write |
204; 404 for an id that is not an announcement in this project |
GET /api/inbox/count |
runs:read |
{open, unread, updates} |
GET /api/inbox |
runs:read |
gains project=; InboxKind gains announcement |
PUT /api/preferences |
none | gains muted |
Phase 5¶
The Schedule wire type gains deliver: ""|inbox|project (project needs a
project and an available agent, else 400). Project gains agent_posts. The
inbox part enum gains draft; resolve accepts publish and discard on it.
Tools: project_changes, runs_summary(project).
Phase 6¶
| Route | Permission | Notes |
|---|---|---|
GET /api/projects/{name}/channels |
projects:read |
at most 20 |
POST /api/projects/{name}/channels |
projects:write |
{name, title?, purpose?, default?}; owner |
PUT, DELETE /api/projects/{name}/channels/{channel} |
projects:write |
DELETE archives; general is 409 |
GET /api/threads |
runs:read |
gains channel=; only threads the caller may read |
POST /api/threads |
runs:write |
{project, channel, visibility (required), title?, default?, text, post_only?} → 201 {thread, message, runs, refused}. private is 409 until phase 7 |
GET /api/threads/{id} |
runs:read |
{thread, turns, next}: messages and runs in order, 200 a page with a cursor (today unbounded) |
POST /api/threads/{id}/messages |
runs:write |
{text, after?, post_only?, answers? {run, question}, act_as?} → 201 {message, runs, notified, refused} |
PUT /api/threads/{id} |
runs:write |
{version, title?, visibility?, default?} |
PUT /api/threads/{id}/participants |
runs:write |
{version, add?, remove?} (<= 50 in all) |
GET /api/events |
runs:read |
new event: thread notice {id, message, at}, filtered by who may read the thread |
The inbox gains kind mention: To is the tagged person and the key is
mention:<message>:<subject>. Its mention part is {thread, message,
project, channel, by (the poster's handle), excerpt (<= 300)}, with actions reply (posts a human
message as the reader; runs:write) and done.
Phase 7¶
No new routes. visibility: private and members-only projects are accepted.
One predicate, p.Sees(who, place), filters every read of:
- runs, threads, run events, manifests and traces;
- the journal and analytics;
- artifacts and their downloads;
- schedules and the inbox;
- memory and pending memory;
/api/agents(homed agents);- the agents a client, a project's lists and the workspace's settings name;
- the agents a spec may call, its approvals of those calls and who may
approve them, a call policy's
allowandtrusted, a run manifest's definition, a channel's default, and a thread's default, the agents added to it by name and the tags in its turns.
A hidden object answers 404. A hidden agent a record names is left out of it, a change keeps it, and naming one, in any spelling of its name, answers as naming no agent: as a spec's spawn entry, a call policy's caller, a call's target, or a run's, a schedule's or a thread's agent. A default the asker may not read is passed over for them, as if it were not set. A run names the agent that ran it, which was available where it ran, and so does what is built only from runs the reader may read: a conversation's agents, the agents that answered in a thread, analytics and the analyst's summaries by agent, and a recap's rows of what was done. A refusal names where an agent lives only when everyone reads that project.
Phase 8¶
| Route | Permission | Notes |
|---|---|---|
PUT /api/projects/{name}/channels/{channel} |
projects:write |
gains slack {client, channel}; owner; the client must be a Slack client in the tenant; binding a Slack channel, or moving a binding, also takes clients:write (403), as every new thread there is filed in the project; keeping or removing one takes only the owner. The channel gains bound_at: set when a binding is made or moved, kept while it holds, absent while unbound |
GET /api/clients/{id}/bindings |
clients:read |
[{slack_channel, project, channel, bound_at}], at most 200; bound_at is when the binding was made, and the Slack app catches up on nothing announced before it. A binding made before Humagen kept the time reads as bound at its channel's last change |
PUT /api/clients/{id} |
clients:write |
gains home {project, channel} |
POST /api/clients, PUT /api/clients/{id} |
clients:write |
github gains login, the app's own GitHub login (humagen[bot]); one that is not a GitHub login is 400. A comment that mentions it and names no agent asks the client's default, then its home channel's chain (docs/reference/github.md) |
POST /api/threads, POST /api/threads/{id}/messages |
runs:write |
gain surface {client, channel, ts}: find or create the thread by surface. The platform files it from the binding, never from a request field, and only for the client's slack.machine |
POST /api/threads |
runs:write |
a surface at the channel and ts of an announcement's Slack post, as the client's receipt records, starts a thread seeded with it where the Slack channel's binding files it in the announcement's project; Thread gains announcement, its inbox id. There a reply to one that was withdrawn, or to a draft, is 410 and starts nothing. Filed anywhere else, it starts as any other thread |
GET /api/threads/{id} |
runs:read |
a seeded thread's turns start with the announcement as it stands when read: ThreadTurn.kind gains announcement, and ThreadAnnouncement {id, kind (person, agent), by, name?, subject?, text?, withdrawn?, at}. A withdrawn one says only that |
PUT /api/inbox/{id}/deliveries/{client} |
runs:write |
{channel, ts} → 204; only the client's machine. The same post again after the message changed moves the receipt's at on, so it says the post shows it; otherwise it changes nothing |
GET /api/projects/{name}/inbox, GET /api/inbox/{id} |
projects:read / runs:read |
show a client's machine its own client's receipts (deliveries, and delivered in a message's history) and nobody else any, as every inbox read does: the Slack app catches up from the project's inbox |
GET /api/inbox, GET /api/inbox/count, GET /api/inbox/{id} |
runs:read |
gain act_as_client and act_as_user for a client's machine, resolved through Client.ActsFor; the person must hold runs:read themselves (403) |
GET /api/inbox |
runs:read |
gains needs=true, what open counts: posted announcements are left out before the page is cut, and an agent's draft is kept. The Slack Home's Needs you reads it. And news=true, what updates counts: posted announcements alone, never a draft. What's new reads it, in the console and in Slack |
GET /api/events |
runs:read |
an inbox notice to a client's machine gains for {client, user}: the person it maps whom a mention or a question is addressed to, by subject or by a role they hold, one notice for each, at most 20 |
GET /api/projects |
projects:read |
gains act_as_client and act_as_user for a client's machine, as the inbox does: the projects that person may see, each as they see it. The person must hold projects:read themselves (403); one without the other is 400 |
GET /api/projects, GET /api/projects/{name} |
projects:read |
each ProjectView gains mine: whether the project names the caller, which is what Your projects lists (see App Home under Slack) |
Phase 9¶
| Route | Permission | Notes |
|---|---|---|
GET /api/projects/{name}/knowledge |
projects:read |
{version, knowledge (<= 8), given: [{name, from}] (<= 16)}: what the project names, and what a run filed there is given, nearest first. Both empty for a caller without knowledge:read |
PUT /api/projects/{name}/knowledge |
projects:write |
{version, knowledge}; owner, and knowledge:read (403); each newly named a source the workspace has (400); 409 stale version or a list the file sets |
GET /api/threads/{id} |
runs:read |
a thread seeded with a release's notes starts with them from humagen: ThreadAnnouncement.kind gains system, with by: humagen and no name |
GET /api/inbox/{id} |
runs:read |
a message retention dropped is 404, as one that never was. Its receipts go with it, so a reply under its Slack post starts a thread as any other (POST /api/threads), and a thread seeded with it no longer starts with it |
Project gains knowledge, left out for a caller without knowledge:read,
and ProjectChange.what gains knowledge. Release notes and retention add
no route and change no shape: they are workspace.release_notes and
workspace.inbox_retention in the Platform document, and
GET /api/inbox/count answers the same {open, unread, updates}, added up
from counters.
Conversations in the console¶
| Route | Permission | Notes |
|---|---|---|
POST /api/threads |
runs:write |
visibility left out (with no surface) is private: the starter is the first participant. A message a person posts as themselves runs only the agents it tags; untagged it starts nothing, rule: untagged |
POST /api/threads/{id}/messages |
runs:write |
the same rule: posted as the caller themselves, only tags start runs, and a tagged agent is sent the conversation so far. A client posting with act_as keeps the defaults |
POST /api/threads/{id}/share |
runs:write |
ThreadShare{project?, channel?, add?: [handle] (<= 50)} → 200 ThreadShared, the thread as getThread reads it with not_added: [{handle, reason}]. A person who cannot read the target project is not added; each person added is told once in their inbox. Only a participant shares (403); making a private thread shared or moving one also takes its starter, while a member, or an owner of its project (403), and a member of the target project (403, 404 for one the caller cannot see); project left out keeps the thread's own, channel left out keeps the thread's own in its own project and is general in another; an archived channel or a handle nobody goes by is 400; moving a thread that has runs is 409 "a conversation that has runs stays in its project" (or "in its channel"); a default that cannot answer where it moves is cleared; a surface's thread does not move or change visibility (400); a change made meanwhile is 409 |
GET /api/threads/{id} |
runs:read |
answers stays on the wire: who answers an untagged message a client posts. The console no longer shows it. thread.agents and thread.mode are the selection, without agents the caller may not read |
POST /api/threads, PUT /api/threads/{id} |
runs:write |
gain agents: [name] (<= 5) and mode: join \| all (join when two or more are named and no mode; none with fewer than two; a stored best_fit reads as join). Each agent must be available in the project (400, one the caller may not read as one that does not exist); all over more than 3 is 400. The PUT also takes project and channel, which move a private conversation while no run has been filed in it (409 after; 400 for a shared or surface thread). A PUT that changes only agents and mode takes anyone who may post in the thread; a move takes its starter or an owner of its project, as Share does |
ThreadRule gains untagged and routed. ThreadMode is new. Run gains
routed (join or all): set on a run the thread's selection started,
kept with the run whatever the selection becomes, and absent otherwise.
Skills and mention kinds¶
| Route | Permission | Notes |
|---|---|---|
GET /api/projects/{name}/skills |
projects:read |
{version, skills: [{name, description, argument_hint?, instructions}] (<= 32), offered: [{name, description, argument_hint, from}] (<= 128)}: what the project declares, and what a message posted there can name, nearest first |
PUT /api/projects/{name}/skills |
projects:write |
{version, skills}; owner, projects:govern for the workspace and company projects (403); a name twice or a field past its bound is 400; 409 stale version or skills the file declares |
GET /api/skills |
projects:read |
?project= (~ or left out for the workspace) → {skills: [{name, description, argument_hint, from}]} (<= 128), what the console offers after /, without instructions. A project the caller cannot see is 404 |
GET /api/mentions |
projects:read |
?project= → {kinds: [{kind, title, resolves}]}, the built-in sme and skill first. With &kind=K&q=prefix → {items: [{name, description?}]} (<= 20) by name, the items whose name starts with q, ignoring case. A kind the workspace does not have, or a project the caller cannot see, is 404; q without kind is 400; people complete only with people:read |
POST /api/threads, POST /api/threads/{id}/messages |
runs:write |
a skill nobody on the chain declares is 400 "there is no skill called ..." before anything is posted, in the console; a console message that names a skill and tags no agent asks the agents, and each that joins is told the skill; a client's message is answered by its default with the skill |
ThreadMention.kind gains skill and role; Project gains skills,
each without its instructions (ProjectSkillBrief), in a view and in a
change; ProjectChange.what gains skills. An answer to a question or a
reply from the inbox that names a skill starts no run for it.
Contract upkeep, every phase¶
- New schemas go in the
shapesmap ofTestSpecSchemasHaveTheFieldsTheGoTypesMarshal(inputswritten: true). - Each operation gets a validated 2xx and its documented errors in
TestResponsesMatchTheSpec. - Each
{name},{channel}and{id}path joins therealandvalidmaps for the globex 404 sweep and the empty-workspace[]sweep. TestSpecListsExactlyTheRegisteredRoutesandTestSpecPermissionsAreTheOnesTheServerEnforcescover 401 and 403 "you need projects:write".
Spec¶
The fields live in pkg/spec/platform.go. Every field is optional, has the
stated default, and is documented in docs/reference/spec.md. Each phase documents only
the fields it ships, so TestTheReferenceExamplesLoad always loads the
examples.
spec:
workspace:
instructions: Acme sells warehouse robots. Answer plainly. # the root's (phase 1)
knowledge: [handbook] # the root's (phase 9): every run is grounded in it
skills: # the root's: $summarize anywhere
- {name: summarize, description: Summarize a thread in five bullets., instructions: "Summarize the conversation so far in five bullets, newest last."}
mention_kinds: # besides the built-in sme and skill
- {kind: oncall, title: On call, resolves: role}
agents: {enable: [humagen-writer, humagen-analyst], default: "*"} # the root's (phase 3); replaces baseline
members: [{who: "*", role: member}, {who: "role:comms", role: owner}] # phase 2
experts: [{who: "role:security", topics: [security]}] # phase 2
project_kinds: [{name: partner, title: Partner, like: account}] # phase 2
agent_posts: review # phase 5
release_notes: false # phase 9
inbox_retention: 90d # phase 9
channels: [{name: announcements, purpose: Company news}] # phase 6
projects:
- name: Field
title: Field engineering # phase 1
kind: team # phase 1: company | team | account | a project_kinds name
instructions: Customer accounts. Never promise dates. # phase 1
knowledge: [field-playbook] # phase 9: runs here and below are grounded in it too
skills: # $review here and below
- {name: review, description: Review a renewal., argument_hint: "[account]", instructions: Check the renewal terms against the contract and list what changed.}
members: [{who: "*", role: viewer}, {who: "role:field-eng", role: member}, {who: "role:field-leads", role: owner}]
agents: {enable: [field-helper], default: field-helper} # phase 3: adds to what the root enables
schedules: # phase 5: file-managed, filed here
- {name: field-recap, cron: "41 8 * * 1", agent: humagen-analyst, text: What changed in Field this week?, deliver: project}
- name: Globex
parent: Field # phase 1: a project in this file, or omitted for the root
kind: account
account: {customer: Globex Inc, external_id: "sf:0015g00000ABC"}
members: [{who: "*", role: viewer}, {who: "okta|00u1ana", role: owner}] # "*" required until phase 7
experts: [{who: "okta|00u1ana", topics: [billing, renewals]}]
agents: {allow: [globex-helper, humagen-writer], default: globex-helper} # narrows: field-helper stops here
channels: # phase 6
- {name: renewals, purpose: Renewal work, default: globex-helper}
- {name: general, slack: {client: file-slack, channel: C0123GLOBEX}} # phase 8
agents:
- spec: {name: field-helper, provider: policy, model: default, system_prompt: You help field engineers.}
- project: Globex # phase 3: lives in Globex, available there and below
spec: {name: globex-helper, provider: policy, model: default, system_prompt: You know the Globex account.}
Workspace.Baseline is removed in phase 3; a file that still sets it fails
humagen config check with "baseline is now workspace.agents.default".
Platform.check runs these, so humagen config check catches them, each
error with its path, such as workspace.projects[2].parent:
- Names match the project regex and are unique ignoring case; channel slugs match theirs.
- A
parentnames a project in the same file. A parent that exists only in the console cannot be checked before start, so it is refused. - No cycle; depth at most 4; at most 10 company projects; company only under
the root or company; account-like never under account-like;
accountonly on account-like kinds. - Kinds are built in or in
project_kinds; aKindSpechasliketeam or account. whoforms, roles, topics and caps; until phase 7 every chain has a*entry.enable,allowanddefaultname agents in the file, built-ins,*(enable, and as a default for everyone decides;autoreads as*). An agent has at most one home, in the file. A default is available where it is set.- A schedule's cron parses, its agent is available in its project, and
deliver: projectsits on a project. knowledgenames at most 8 knowledge sources, each a source's name, once (phase 9). Whether the workspace has them is not checked: sources are filled in the console, and one the workspace does not have grounds nothing.skillsdeclares at most 32 skills a project, each a skill's name once, with a description on one line of at most 1,024 characters, an argument hint of at most 100 and instructions of at most 8,000.workspace.mention_kindsdeclares at most 16 kinds, each a kind's name that is notsme,skillorauto, once, with a title of at most 40 andresolvesone ofexperts,skills,roleorpeople.
Applying (internal/app/config.go applyWorkspace becomes
applyProjects) is a merge, never a replace. This fixes today's
s.Projects = nil, which contradicts "Nothing is deleted because it left the
file":
- Projects are upserted parents first with
managed: file. The fields the file sets win and answer 409 in the API; fields it leaves out stay the console's. An unchanged entry makes no new version. - A console project with the same name is taken over, recorded as
managed. - A project that leaves the file stays, unmanaged.
- File schedules and channels are managed the same way.
- Order: root, projects, agents, homes, channels, schedules.
docs/reference/spec.md gains:
- a "Projects" bullet in "What the file owns";
- a row in "Which level a knob lives at": "Project tree, kinds, members, experts, availability, channels | Platform | the workspace's own";
- "Baseline" leaves the "Baseline, history, projects" row.
Console and Slack¶
Console addresses (apps/web/src/route.ts, each with a round trip in route.test.ts)¶
| Route | Path |
|---|---|
{page: "projects"; q?; kind?} |
/projects, ?q=, ?kind=account |
{page: "project"; name; tab; message?} |
/projects/{name} (default tab), /projects/{name}/{tab}, ?message=<id> |
{page: "channel"; project; channel} |
/projects/{name}/channels/{channel} |
{page: "conversation"; id; message?; share?} |
/conversations/{id}, ?message=<id>, /conversations/{id}/share (the Share dialog open); /tasks/{id}, its address when conversations were called tasks, opens it and is rewritten |
{page: "new"; project?; channel?; agent?; ask?} |
/?project=&channel=&agent=&ask= |
PROJECT_TABS grow by phase:
- phase 1:
overview,context; - phase 2:
people,history,limits; - phase 3:
agents; - phase 4:
inbox, which becomes the default, so/projects/{name}opens the project's inbox; - phase 5:
schedules; - phase 6:
channels.
An unknown tab falls back to the default through pick. Names never hold
/, so nesting lives in parent and breadcrumbs, never in path segments.
~ is the root.
Screens¶
- Projects. One
Pagetitled Projects. Groups in words: Company-wide, Teams, Accounts, then custom kinds by title. At 390px the tree indents at most one level of 16px, and deeper rows print their path ("in Field › Globex"). Rows show the title, the kind in words, the customer, conversations, active, AgentMarks of the project's agents (phase 3) and a still dot for unread updates (phase 4). "New Project" opens an inline form (title, name marked "Can't change later", kind, parent, description), shown only withcan("projects:write"). - Project. A
Pagewith back to the parent's title or All projects, the title, meta in words ("Account · in Field · Lead globex-helper") and a breadcrumb of plain links. Tabs throughPage.tabs, scrolling sideways on a phone: - Overview (phase 1): today's layout (tasks paged on the server with
threads?project=&within=, shared memory, schedules, limits) plus Sub-projects with "New Sub-project". - Context: the project's instructions (editable with
projects:write, by owners from phase 2), inherited instructions and notes, read only, under "From Field", and from phase 3 a preview of what a turn here is sent, layer by layer. - People: members with display names and roles, inherited owners "from
Field", "Add Person" (a person or
role:), experts by topic. - Agents: Available here, each with its AgentMark and where it comes from
("from Acme", "lives here"); Default; Allow. "Lives Here" is editable
only with
agents:writeand warns how many projects lose the agent. - Inbox: the project's inbox in the mailbox look:
- announcements carry the sender's AgentMark or avatar, and the agent's
Strokeedge; - drafts sit at the top for owners, with Publish and Discard;
- "Post Announcement" for those allowed, and Include Sub-projects.
- announcements carry the sender's AgentMark or avatar, and the agent's
- Schedules: today's form plus
deliver, and "Add Weekly Recap". - Channels: the channel list; each opens the channel view.
- Limits: today's ScopeLimits with the chain ("Field's limit also applies here").
- History: the paged change log.
- Channel. A
Pagetitled#renewals, with the project in the meta. Threads are listed newest first and paged on the server, each with its title, AgentMarks of its agents and avatars of its people. The chat bar at the bottom starts a shared thread in the channel. Nothing under it says who answers: an agent runs only when a message tags it. - Thread. Today's conversation view, with:
- human messages with the person's avatar and name, agent answers with their AgentMark, and replies to one message shown together;
- participants in the meta, and "Shared in Globex › #renewals" or "Private" in words;
- one chat bar, the same as Home's, with completion:
@over available agents (AgentMark), people (never the person typing) and the mention kinds that name people or roles (read fromGET /api/mentions), which complete further to their items (GET /api/mentions?kind=); never a skill, nor@skill:or another kind over skills. Tab or Enter picks the highlighted item, the arrow keys move, Escape closes. Each kind keeps a place in the list's eight.$opens nothing; /at the start of the message or after a space opens the command menu over the project's skills (GET /api/skills), the only way the console offers them: each row/name, its description and the kind (Skill), filtered as the name is typed, closest name first, then by description, the matched letters highlighted. A skill the message already names, or every other once it names 4, is greyed with the reason and cannot be picked. A pick writes/name, drawn in the box as a token, and the message is sent as its text. The + menu's Skills write/nametoo. A posted message shows each skill it names as a/namechip, whether it was written/name,$nameor@skill:name(DES-047);- the + button (or Ctrl+/) opens a menu: Attach Files; Agents, a
searchable list with AgentMark colors of the agents available in the
project, several of which can be checked (arrows move, Space checks,
Enter or Escape closes); and Project, where the conversation lives,
then one of its channels, general first, changeable only while no agent
has run in it. What is selected shows as chips in the bottom row: an
agent with its color and name, the project with its path (
Globex / #dealswhen the channel is not general), each removable with ×. With two agents or more, text on that row chooses Each Decides (each of them decides whether to take a message, and each that does answers) or All of Them (each answers, side by side). The selection is the conversation's: sent withPOST /api/threadsasagentsandmode(joinorall) and saved withPUT /api/threads/{id}, so it shows for everyone in it after a reload. An answer an agent gave because it was selected, not tagged, says "helper joined on its own", read from the run'srouted, so it stays whatever the selection becomes. With nothing selected the prompt reads "Message, or @ an agent"; - no Post Only, no Private and no line saying who answers: a message
starts a run only for the agents it tags (
@agent, or$skill, which asks the agents when no agent is tagged), with the conversation so far as its context. An untagged message shows as posted; - a private conversation's header says "Private" and offers "Share", which
opens a dialog at
/conversations/{id}/share: the project (only while no agent has run in it; the server's 409 is said in words), the channel (general by default) and people to add, completed as they are typed. It callsPOST /api/threads/{id}/shareand then reads as shared there, with no Share, and says who was told in their inbox and who was not added, with the platform's reason (not_added); - a question addressed to an expert shown still, with "Reply".
Nothing waiting on a person animates; a mark shows thinking only while its
run is live.
- Home. The prompt-first chat bar, which starts a private conversation
(POST /api/threads, visibility: private, in the picked project's
general) and opens it at /conversations/{id}; there is no menu of who answers.
Suggestions sit under the bar as quiet text until the person types; a
pick writes its words and adds its agent as a chip, as a link with
?agent= does. Then
two titled boxes from the shared HomeModel: Needs you, with the inbox's
open as its count (an agent's draft waiting on its owners counts, a
posted announcement never does), its five newest items and Open Inbox; and
What's new (up to 5 announcements from your projects, unread first, never
an unpublished draft) with See All. Each row links to
/projects/{name}/inbox?message= in the project it was filed in, and a
new person with nothing in either sees one Welcome box. A project's inbox opens by id only a message
filed in that project.
- Inbox. Announcements sit under What's new with a megaphone template;
drafts and mentions sit in Needs you. On a broadcast the header reads "Hide
for Me", with "Hidden for you. Others still see it." and "Show for Me",
which brings the reader's own copy back (POST /api/inbox/{id}/unhide;
hidden on the message says the copy is set aside for them alone). The
author or an owner withdraws an announcement from the message itself, in
the project it was filed in. A draft is laid out as an announcement but
reads "Dismiss", which sets it aside for every owner, and offers no
Withdraw, as it was never announced. The Inbox adopts Page for its
title. The badge counts open only.
- Composer ProjectPicker. Reads GET /api/projects, shows paths and kind
words, and searches name, title, description and customer. Completion
offers only the agents available in the picked project; there is no agent
menu. "Create Project" in Title Case.
- Settings › Workspace. The projects editor goes, replaced by links to
Projects and to the root (/projects/~). The baseline control on the
agent page becomes "Workspace Default" on the root's Agents tab.
- Agent page, Access tab. "Lives in" and "Available in" (the projects
that enable it), using AgentDetail's unused projects prop.
Copy goes in packages/components/src/copy.ts:
- kind names;
- buttons "New Project", "New Sub-project", "Move Project", "Post Announcement", "Add Weekly Recap", "Hide for Me", "Publish", "Discard Draft", "Share", "Add Person", "Name Owners", "New Channel", "Lives Here", "Workspace Default";
- sentence-case empty states ("New announcements land here. What you hid is under Resolved.").
Shared pieces: packages/core gains HomeModel.updates and
HomeModel.projects, and packages/adapter maps announcement, draft and
mention (kinds, templateOf) and makes What's new, Your projects and
what needs the reader from the platform's reads (updatesOf, projectsOf,
notificationsOf): a posted announcement is What's new and an agent's draft
is what needs its owners, and Your projects keeps the views marked mine.
Parity tests in apps/slack/src/parity.test.tsx hold Needs you, its rows
and its total, What's new and Your projects to the same on both renderers.
Slack (one app per client)¶
- Channels. A project owner who also administers the client
(
clients:write) binds an existing Slack channel to a Humagen channel. The bot must already be in it, so no scope widens. Which of a client's Slack channels a project answers in is the client's admins' to decide: a binding files every new thread there in the project. A Slack thread in a bound channel is a shared Humagen thread in that channel. A DM or the assistant pane is a thread in the client's home channel, private from phase 7. - Addressing. In a channel, Slack delivers a message to the app only when it mentions the app, so:
@Humagen @ignite draft the renewal notetags ignite: mention the app, then the agent's handle as plain text;@Humagen what changed?goes to the thread's default chain; with none the app answers ephemerally "Tag an agent, for example @ignite";@Humagen @auto ...tags nobody, since no one goes by@auto;@Humagen <@U_dana> can you check?tags Dana (mapped throughslack.people): no run;- in a DM or the assistant pane the app mention is not needed;
- a native mention of a bot user in
client.Botsis a tag of the agent it stands for.
The app sends the raw text; the platform parses it with the one grammar.
apps/slack/src/agents.ts stops picking: its picker path goes.
- The room. When the app is mentioned in a thread, the people's messages
since it was last asked there are posted as human messages, idempotent on
their ts, instead of being folded into the run's text.
- Mentions and experts. A mention or an expert question for a mapped
person who is not already in the Slack thread goes to their DM with the app
(chat.postMessage to the user id, covered by chat:write), with "Open
Thread" and "Reply". "Reply" opens a reply modal in @humagen/render-slack
(the listed follow-up). The modal posts, as that person, a human message or
the question's answer.
- Announcements. The app's watchInbox sees an announcement of a project
whose general channel is bound. It posts it top-level once and records
PUT /api/inbox/{id}/deliveries/{client}, and the receipt is the record
of the post. The event stream does not replay, so each time it opens, at
the start and after every reconnect, the app catches up: it reads each
bound project's newest 50 announcements in the project's inbox, where its
machine is shown its own receipts, edits a post whose announcement
changed since its receipt (updated_at after its at), and posts, oldest
first, an open one with no receipt from the last 24 hours and announced
no earlier than the binding was made (bound_at on the binding), so
nothing from before the binding and nothing days late. A withdrawn post
says only that it was withdrawn, and the app records the same post again,
which moves the receipt's at on. So a restart, a reconnect, an edit or a
withdrawal updates that post instead of posting again, and a notice during
a catch-up posts nothing twice. A change to an announcement older than
the newest 50, made while the app was not listening, is not caught up on:
its post keeps what it said, withdrawn words included. The app does all
this only when its client names its credential as the machine, and a
catch-up that did not finish is tried again with backoff. A reply in its thread starts a shared thread seeded with the
announcement. Slack delivers a reply in a channel thread only when it
mentions the app, so the reply that mentions it posts, with the post's
surface, into the thread the platform finds by that post's receipt: in
the bound channel, its turns start with the announcement from whoever
posted it (the scheduled agent for a recap, Humagen itself for release
notes), then the reply as the person's own message, answered by the
channel's chain. A later reply finds the same thread, and once the
announcement is withdrawn the thread says only that. A reply under one
withdrawn before anyone replied starts nothing, and drafts never reach a
channel. Only a thread the binding files in the announcement's project is
seeded: after the Slack channel is bound to another project, or unbound, a
reply under an old post starts a thread there as any other.
- App Home. The shared Home, through homeView, replaces the bare
MailboxView for a person the client maps. It shows Needs you (at most 5, the
rest counted as the inbox's open counts them: an agent's draft waiting on
its owners is one, a posted announcement is not, and read with needs=true
so that news newer than them never pushes them off the page), What's new (at
most 5 posted announcements, read with news=true) and Your projects, read
as the mapped person through act_as (GET /api/inbox and GET
/api/projects with act_as_client and act_as_user), within the 100-block
budget. Your projects are the projects that name the person (mine on each
view): they are a member or an owner through an entry for their subject or a
role:<name> they hold, on the project or as an owner of a project above
it. Access only through *, or only through projects:govern, does not
count, and neither does an entry in a project they could not see without
projects:govern. At most 8, where something happened most recently first
and then in tree order, archived ones left out, the rest counted in "N more
in Projects", which links the console's Projects. Each opens in the console
when the app has its address. Without it, Review sends what needs the person
to their messages with the app, and What's new and Your projects are shown
to read. Ask a Question and Build an Agent open a form whose words are
posted as the person in their messages with the app, Build an Agent tagging
@humagen where the client reaches it; Search Context opens the
console. Someone the client maps to nobody keeps the mailbox.
- GitHub. The same rule: @agent in a comment is a tag; otherwise the client's default; otherwise nothing. As Slack delivers
only what mentions the app, a comment that names no agent asks the client
only when it mentions the app's own login (github.login): @humagen what
changed?. One that mentions neither starts nothing, so a busy repository
wakes no agent. Threads are filed in the client's home.
Every Slack change passes pnpm validate:slack, and
TestTheSlackManifestIsWhatHumagenGenerates stays green. The projects work
added no Slack scope, but the uploads and canvases that landed alongside it (#47)
added files:read and canvases:write, so an app installed before then is
reinstalled from the generated manifest to grant them.
Migration¶
Phase 1: projects out of settings¶
- At platform start, the migration runs for each tenant whose
projectsnamespace is empty and whose stored settings hold the legacy array (storedSettings.LegacyProjects): - One write imports every entry as
{kind: team, parent: "", title: "", created_by: "migration", created_at: SetupAt or now}with oneh:entry each, and creates the root. - The same write imports, the same way, every name a stored schedule
(
warp.project), alert rule or project-scope policy still points at that the array lacks: a project an earlier version dropped by a delete or at start while things stayed filed in it. Each one'sh:entry says "kept because a schedule, an alert rule or a limit still names it". So a schedule that ran before the upgrade is not refused after it, and nothing is left pointing at a name the tree does not hold (invariant 5). A record whose array was null imports only such names. A name the tree cannot hold (not a project's name, or one name ignoring case with an imported one) is logged and left, and what points at it is refused until it is changed. Past the 100-project cap the start fails, naming what it would have kept. - Then settings are rewritten without the array.
- If the platform stops between the two writes, the next start repairs it: the store has records, so the import is skipped and only the array is cleared.
- A failed import fails the start and changes nothing.
- Nothing keyed by a name moves:
Run.Project, thread summaries, usage entries and counters, policy scopes,project:<name>memory, schedulewarp.projectmeta, alert rules, artifacts and inboxSource.Project. - Usage entries written before phase 1 have no
Within, so they count toward their own project only, which is correct: no tree existed.usage.Rebuildreplays them unchanged. The ledger keeps 62 days. - The spec's
workspace.projectsis applied after the import, as a merge. From now on, projects made in the console survive a start. Projects a previous version dropped at start are gone as records. Their runs and memory remain under the name and reappear if the project is recreated. - Contract changes, in the same PR as the console and
make client: Settings.projectsleaves GET and PUT;updated_aton a project view becomesactive_at;- project and project-memory routes move from
runs:*toprojects:*.
Committed as feat(projects)! with a BREAKING CHANGE footer.
6. Machine tokens with explicit scopes (the Slack app, CI) need
projects:read to list projects. humagen config check warns when a
configured machine has runs:read but not projects:read. People are
unaffected under default.authz. A custom policy file adds projects to
its write rules; docs/reference/authorization.md
gives the one-line diff.
Phase 2: members¶
Every migrated project gets members: [{who: "*", role: owner}]. Under the
intersection rule only projects:write holders can act on an owner role. So
this keeps exactly today's "any operator may change any project" until an
owner narrows it. Ownership flows down, so a project created under a migrated
one is also owned by every projects:write holder. The People tab of a
*-owned project says so and offers "Name Owners".
The root gets [{who: "*", role: member}] and no explicit owner:
projects:govern holders own it. Account projects made in phase 1 keep their
entries. From phase 7 the console nudges their owners ("Globex is visible to
everyone. Make it members only?"). Nothing is closed automatically.
Phase 3: agents and the baseline¶
- The root gets
agents.enable: ["*"], so every agent stays available everywhere. No agent has a home until one is given. - The root's default comes from the baseline:
- a workspace whose baseline was set gets that agent as its default, which is what the console sent when nobody chose an agent;
- a workspace with no baseline gets
*, which lets every agent decide for API and Slack callers that name no agent.
The migration records it in the workspace's history, which the History
tab shows as a change made by the upgrade. An admin can clear it.
- Setting the workspace default moves from agents:write (managers) to
projects:govern (admins by default), since it changes the workspace
itself. Owning the root is not enough: to keep the old split, an admin
grants managers govern on projects, or a role that holds it (steward in
docs/reference/authorization.md).
Phases 4 and 5: inbox¶
New kinds, parts, Broadcast and per-reader state are additive in the
inbox's replayed change log. Old records read as non-broadcast, so replay is
unchanged. Withdraw records by from now on; old withdrawals read as
system.
Phase 6: threads¶
No bulk migration. A conversation with no thread record reads as shared, in
general of its project (or of the root), with its runs' actors as
participants. It gains a record the first time it changes. POST /api/runs
keeps working and files a new conversation as a shared thread in general.
Phase 7: confinement¶
Existing threads stay shared and existing projects keep their * entries.
Private threads and members-only projects exist only when someone chooses
them. Account projects created from then on default to members only, and the
New Project form says so.
Phase 8: Slack¶
Existing Slack conversations keep their run-derived mapping. A thread gains a surface record the first time the app is mentioned in it after the upgrade. Channels are bound only by a project owner.
Phase 9: retention¶
No migration. Retention's first pass runs at the first start after the
upgrade and drops what was settled more than 90 days before, or the
workspace's inbox_retention. Records written before phase 9 replay as they
did: their raises already name their ids. Older broadcasts carry no flag
that distinguishes an ordinary post from PostOnce, so their keys are kept
conservatively after retention, and a release posted before phase 9 is not
posted again once it is dropped. New ordinary posts need no permanent key.
No rollback after the first pass. A build from before phase 9 keys its next change by how many changes it loaded and numbers its next id by how many raises it loaded, so on a record retention has cut it would overwrite kept changes and issue ids again. Roll back only to a build with phase 9.
Docs in the same PRs¶
- docs/architecture/overview.md#status, existing rows, by name (rows move, so they are not cited by line):
- "Conversations", "
@auto, the built-in router", "Projects", "Composer project selection and creation", the console navigation rows' claim about the projects flyout, "Configurable console titles and labels"; - "
pkg/policy", "Limits set by a project's owner", "Project membership and per-project access"; - "Slack app (
apps/slack)", "Questions in Slack"; - "Schedule delivery", and the inbox and addressing rows from "
pkg/inbox" to "Messages addressed to one person, one role, a project's members or its owners". - New status rows: project tree, project policies along the tree, layered
context, agent availability and homes,
@auto, project inbox and announcements, scheduled agents in projects, channels, shared threads and tagging, experts, read confinement, Slack project channels. - docs/reference/spec.md, docs/architecture/security.md and docs/reference/slack.md.
- docs/reference/authorization.md, with a "Project roles" section covering the
intersection rule,
Resolveand the matrix. - The README feature list, and docs/plans/roadmap.md (delivery steps 1, 2 and 4 point here).
Phases¶
Phase 1: the project tree and project policies (one PR, M-L)¶
This is the smallest slice in which nesting is safe: a child can never escape its parent's limit, and nothing claims privacy.
- Backend.
pkg/projectswith the root and the fieldsName,Title,Description,Kind(company, team, account),Parent(fixed at creation),Account,Instructions,Managed,Versionand audit fields.- History and tombstones in the same namespace, and the
Treesnapshot. - Caps (100 per tenant, depth 4, 100 children, 10 company) and invariants 1, 2, 3, 5 and 6.
- Opened in
backends.go, with the migration out of settings. - Policies along the tree.
policy.Store.For(tenant, chain, agent, client);Run.Withinpinned at admission;usage.Entry.Withinand ancestor scopes; storage summed over the subtree. - Context.
p.contextOfsends, in order: instructions root first, the project's notes, ancestors' notes within 6,000 characters nearest first, the agent's notes, the transcript. Converse uses it, and so docronandmanualruns filed in a project. The root's notes live under ownerproject:. - Permissions.
projects:read,projects:writeandprojects:govern, throughdefault.authz,policy_test.go, the openapi enum,everything,access.tsand the docs. No roles yet: company kind and the root needprojects:govern. - API. The phase 1 routes, memory routes regated,
threads?project=&within=, and per-project counters inruns.Index. - Spec.
title,kind,parent,accountandinstructionson projects, andworkspace.instructions;Platform.checkrules 1 to 4; the merge apply. - Console. Projects tree grouped by kind; project page with breadcrumbs,
Sub-projects, the Context tab (instructions, inherited notes) and the chain
under Limits; ProjectPicker on
/api/projectswith paths; Settings' projects editor removed; routes and tests. - Tests.
pkg/projects:- 40 racers creating one name keep one; the cap holds under racing creates;
- depth 5 and the 101st child are 400; kind rules; name identity ignoring case; a tombstoned name needs govern;
- delete refused while children, schedules, alert rules or policies point at the project; managed fields; tenant isolation;
TestRestart, a failed write throughstatetest.NewFaulty, and Open refusing a cycle.
internal/platform:- the migration, including a stop between its two writes, and a legacy schedule filed in a dropped project still running after it;
- 40 racers in two children against a parent
max_runsof 7 admit 7, and spend stops at the parent's limit to the micro-dollar; - storage over the subtree;
- context layers in order and within budget, and a cron run in a project gets its context;
- delete keeps the policy.
pkg/usageandpkg/policy:Withincounts from day totals and from inside a day;Rebuildagrees;Forreturns the chain nearest first.internal/httpapi: route and permission tests, shapes, 2xx and errors for each operation, the globex 404 sweep,[]on an empty workspace.pkg/specandinternal/app: the reference examples load; each check with its path; a console project survives a start; a project that left the file stays unmanaged; an unchanged file makes no version.- Web: route round trips;
access.test.ts; the tree at depth 4 indents one level at 390px; the picker shows paths. - The commands
make check,pnpm typecheck && pnpm test,make client-checkandmake spec-lintall pass. - Status. The "Projects" row becomes "a tree with kinds, in its own
store", and the "
pkg/policy" row adds the chain. A new row says plainly that every project is visible to everyone and has no owners yet.
Later phases¶
The owner set this order: explicit addressing and shared threads come right
after the tree, and everyone can see who and what is in the workspace.
Sections above still name phases by their first numbering: their phase 3 is
phase 2 here, 6 is 3, 2 is 4, 4 is 5 and 5 is 6. pkg/people moves to
phase 2 and experts to phase 3, because addressing and threads need them.
| # | Phase | Scope | Size |
|---|---|---|---|
| 2 | Explicit addressing, agents in projects, and the directory | Agents{enable, allow, default}, homes and the home route, available(P), the one admission check. @auto as a reserved built-in over pkg/pick, defaults along the chain, the baseline migration. POST /api/runs without an agent, GET /api/pick?project=, stamp resolving auto, the Slack app's picker path removed. pkg/people and GET /api/people (who is in the workspace: name, handle, picture, roles, projects), from sign-ins, client people maps and the policy; a Directory in the console with People, Agents (platform and project agents, where each lives and is enabled, its handle and color) and Projects (the tree, kinds, what each holds), readable by everyone with people:read, agents:read and projects:read. Agents tab, composer menu and @auto, agent Access tab; spec agents and agents[].project. Status row "@auto, the built-in router" (once pkg/pick), and the new rows "Agents in projects", "Defaults along the chain" and "pkg/people and the Directory's people" |
M-L |
| 3 | Channels and shared threads | Channels on the record and their routes. pkg/threads with records, human messages, the tag grammar, participants, and defaults per channel and thread. Runs answering messages and the room transcript. Experts on projects (data and routes). Mentions in the inbox with Reply; @sme and ask_person addressed to experts; replies recorded as answers. Thread SSE and a paged GET /api/threads/{id}. Channel and Thread views with the @ typeahead and Post Only. Shared threads only. Status row "Conversations", and the new rows "Channels on the project record", "Shared threads, tagging and the room", "Experts on projects" and "Mentions in the inbox" |
L |
| 4 | People and project roles | Members, Resolve and the intersection rule on every project route. Members propose notes and owners approve them. Owner-set tighten-only limits with Policy.Authority. Move (subtree check under the lock, the billing:write rule) and archive. Custom kinds; paged listing and the 500 cap. People, History and Limits tabs. Every project stays visible: * required. Status rows "Limits set by a project's owner" and "Project membership and per-project access" |
L |
| 5 | Project inboxes and announcements | Kind announcement, Broadcast with per-reader hide and snooze, project: audiences and Reader.Projects, Count.updates, Withdraw(by). The project inbox route, post and withdraw routes with rate limits, prefs.Muted. Inbox tab, Home "What's new", Updates and "Hide for Me", adapter templates and parity tests. Status rows "pkg/inbox" through "Messages addressed to one person, one role, a project's members or its owners", and the new row "Project inboxes and announcements" |
M |
| 6 | Scheduled agents in projects (recaps) | deliver (project or inbox), posting on ended(), agent_posts and the draft part. project_changes, runs_summary(project), the Summarize project filter, file-managed schedules in the spec. Schedules tab and "Add Weekly Recap". Status row "Schedule delivery", and the new row "Scheduled agents in projects (recaps)" |
M |
| 7 | Read confinement: members-only projects and private threads | p.Sees with 404 on every read path (runs, threads, events, manifest, trace, journal, analytics, artifacts and downloads, schedules, inbox, memory, homed agents). Private threads; members-only projects and the account default; no memory proposals from private threads. A contract sweep reads every GET and the event stream as a non-member. Status row "Project membership and per-project access" built, and the new row "Read confinement" |
L, two PRs |
| 8 | Slack and GitHub coworking | Channel bindings, client home, surface-keyed threads, addressing, the room's messages, mention and expert DMs, the reply modal. Announcements posted top-level with delivery receipts; App Home on the shared Home through act_as; GitHub on the same rule; docs/reference/slack.md. Status rows "Slack app (apps/slack)", "Questions in Slack" and "Schedule delivery", and the new row "Slack and GitHub coworking in projects" |
L |
| 9 | Release notes, knowledge sources inherited down the tree, inbox retention and per-reader counters | Built. Release notes: workspace.release_notes posts a release's breaking changes and features once, in the root's inbox from Humagen (PostOnce, keyed release:<version>); the Slack app's catch-up brings them to a Slack channel bound to the workspace's general, where a reply starts a thread seeded with them. Knowledge: a project, the workspace included, names at most 8 of the workspace's sources (Project.Knowledge, GET and PUT /api/projects/{name}/knowledge, and the file's knowledge), and a run is grounded in its chain's, nearest first, at most 16, pinned at accept as _warp.sources and added through callExecutor.resolve. fiber gained one thing for it: a meta key starting with _ is the host's and never reaches a model (fiber#43). The console shows and edits them in the Knowledge section of a project's Context tab. Retention: workspace.inbox_retention (90 days by default) drops what was settled for everyone, with its records, at start and every hour, in steps under a cut that replay reads first; Count adds up counters kept per bucket of open messages. The inbox is still held whole in memory. Status rows "Release notes in the workspace's inbox", "Knowledge sources inherited down the project tree" and "Inbox retention and per-reader counts" |
M |
Risks¶
- A missed read path leaks.
Run.Projectand thread content appear on many reads: threads, runs, events, manifests, traces, the journal, analytics, artifacts, the inbox and Slack notices. Members-only projects and private threads are refused until phase 7. That phase puts one predicate on every read, plus a sweep test that reads every GET as a non-member. - Migrated ownership is broad.
{who: "*", role: owner}keeps today's rights exactly, and it flows down to new children. Until owners are named, an account created under a migrated project is not private, and from phase 7 it cannot be made members only (invariant 4). - The name is the identity forever. Renames are impossible;
titlecovers display. Delete is refused while anything points at a name, and tombstones stop a recreated name from silently adopting old conversations. - Breaking contract and rights.
Settings.projectsleaves the wire.- Project routes move to
projects:*. - The baseline goes, and managers lose the workspace default to
projects:govern. - An untagged API run with no default is 409.
All of it is flagged as breaking in its commit, which the generated
release notes carry, with the policy diff in docs/reference/authorization.md and a
config check warning, and the migration writes explicit defaults.
- Moves and usage. Within is pinned when a run is admitted. After a
move, later spend counts toward the new chain, so a parent's period total
shifts. That is deterministic for Rebuild but surprising to read. Leaving
a limited ancestor needs billing:write.
- Prompt growth. Inherited instructions (8,000 characters) and notes
(6,000) ride on every turn in a deep project, on top of the project's own
15,000. Budgets are fixed, the prompt says when something was cut, and
depth is capped at 4.
- Prompt injection. Project instructions are owner-written text in the
turn, not system text. Thread messages come from anyone in the thread.
Recaps are model text over conversation content. Mitigations:
- precedence is stated in words in the prompt;
- anything that must hold is a policy, not an instruction;
- posts are plain text with Slack mentions escaped;
- wide audiences default to review;
- project_changes reads only the run's subtree.
- Defaults in busy threads. A default no longer answers a message posted
in the console: there an agent runs only when it is tagged. On a surface a
shared thread with a default answers every untagged message, which can be
noisy. Messages that tag people, and replies to mentions and answers that
tag no agent, start no run, and Post Only is always there. In Slack, only
messages that mention the app reach Humagen.
- Homing narrows widely. Giving an agent a home removes it from *
everywhere else. The route answers 409 while anything outside the new
subtree uses the agent, and the console counts the projects that lose it.
Schedules that lose their agent fail visibly.
- Inbox growth. Broadcasts add one message per post, not one per
person, and per-reader state adds one change for each person who hides
one. Rate limits bound posts. What was settled for everyone is dropped
after the workspace's retention (90 days by default) with its record,
and Count adds up counters kept per bucket of open messages, never
reading a settled one (phase 9). What stays is what is open or snoozed: an
announcement nobody withdraws stays, with every reader's marks on it, and
the inbox is still held whole in memory.
- Addressing is not confidentiality. Expert questions are routed to
experts, but anyone fiber's answerers check admits may still answer
through the run, as today. A project that needs a closed set of answerers
names them in the agent's spec. A run that uses the credential of the
person it acts for is answered by that person alone, experts included.
- Membership by IdP group relies on a policy file with empty roles and
grant ... to group. The default policy has only four roles, and a group
change applies at the next sign-in. Subjects can be listed directly.
- projects:govern sees everything, customer accounts included. Reads allowed only by governance are written before access is granted, with the reader, project, thread, time and server route. Ordinary project roles and private-thread participation are checked first. Audit write failure or the 100,000-record tenant cap refuses the exceptional read. Records share the inbox retention duration, are removed at start and hourly, and survive restart. Workspace admins list at most 500 records from a window of at most 31 days at GET /api/read-audit; Settings shows the last day. Writes remain in the httpapi: change log.
- Phase 1 is broad: store, migration, permissions, the policy chain,
context and the console tree. If review finds it too big, the safe split is
1a (store, migration, permissions, routes, spec merge) and 1b (the chain
and context). But 1a must refuse children until 1b lands, or a child
escapes its parent's limit.
- One app, many agents in Slack. Slack shows every answer as the one bot
user, so the agent's name and color go in the message. In a channel, a
person must mention the app before the agent's handle. Code channels and
per-agent bot users keep working through client.Bots.
Templates and initiatives¶
The project creation form starts blank or uses a file-defined template. The
built-in catalog is pkg/projects/templates.json; applications embedding the
platform can replace it through Config.ProjectTemplates. Templates contain
instructions, channels and skills. The project and its channels are written in
one transaction, without memory, credentials, agents or live integrations.
The Initiative template marks a team project as a coordination parent. Child projects use the same role and tighten-only policy inheritance as the rest of the tree. An initiative's own agents cannot execute directly inside a child. Cross-project handoff placement remains an open design question: the current call path keeps its root's project, budget accounting and context, and no second execution path is introduced.
Forks and archives¶
A project fork captures an immutable bounded plan before copying. Destination projects, agent home reservations, channels, selected approved memory and integration rules stay hidden and cannot run until the project store publishes the entire prepared subtree in one write. A failed copy remains private and retryable after restart. Rules are copied disabled from the captured snapshot; credentials, live bindings, schedules and pending actions are not copied.
Conversation archives are an explicit opt-in, at most 20 readable conversations. They retain immutable text, not tool state, attachments or file capabilities, and accept neither messages nor agent runs. Every archive read still requires access to its original conversation. Personal live-source results cannot be copied through forks or bring-back. Copied confirmed memory retains only selected text, kind and expiry; it is newly reviewed by the copying person, with no original private run, thread or artifact capability.
Workspace discovery returns at most 50 readable destinations per query, with separate project, agent and conversation read permissions. Searches enforce query and scan bounds on the server and return no hidden-object counts.
Initiative rollups¶
GET /api/projects/{name}/rollup returns at most 100 readable descendant rows,
100 approved unexpired decision/risk notes, and 50 inbox needs for the reader.
Rows report current-placement conversation/activity counters, the reader's
unread and actionable inbox counters, and runs started during the preceding
30 days. Run counts require runs:read. Hidden projects, conversations and
source chains contribute no names or counts. More flags describe only readable
items beyond these caps. Notes omit original author/run/artifact provenance.
The initiative Overview links each item to its original project for review.
Progress and risks are never guessed from conversation text. Initiative agents
coordinate at their own level; cross-project handoff remains the explicit open
question in the control-plane spec and is denied by the existing call path.