Skip to content

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:

  1. 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".
  2. The tree is a parent pointer, at most 4 levels below the root. A name never changes; title is what people see.
  3. 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.
  4. 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.
  5. Context is layered and explicit: the project chain's instructions and memory, then the agent's instructions and memory, then the thread.
  6. Every project has an inbox: the inbox messages whose Source.Project is 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.
  7. Shared threads are conversations with participants and a visibility. Anyone in a thread can tag a person or an agent.
  8. 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.
  9. 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. general always 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[]:

channels:
  - name: general
  - name: renewals
    members: ["okta|00u1ana", "role:renewals"]

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:

  1. 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 (startsForSkills in internal/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. @auto tags nobody: no one goes by it.
  2. It tags only people, experts or a role: no run. It is a message to people.
  3. It answers a question or replies to a mention: no run. It is a human response.
  4. The poster chose Post Only: no run.
  5. It was posted in the console and the thread selects agents (rule routed): with join (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's picked saying why; with none, the best match among them answers, else the first of them; with all each of them side by side (at most 3, so all over 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.
  6. 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_only is still accepted there and means the same.
  7. 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 through PUT /api/projects/{name}/skills by an owner (the workspace and company projects need projects:govern). A change is recorded as a skills change. 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, answerMessage pins 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.Project is 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 announcement in 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:

role field-eng {}
grant operator, field-eng to group "field-engineering"

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:

  1. 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.
  2. 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.
  3. Kinds: a company project sits under the root or a company project; an account-like project never sits under an account-like one; account only on account-like kinds; a KindSpec in use cannot be removed.
  4. 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.
  5. 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:govern holder 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: only billing:write removes one.
  6. 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 and warp.message meta = 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.
  • Path walks messages and runs; the transcript (threads.Ask) renders a message as Dana (@dana): text and a run as ignite (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 general of 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) and approver in every workspace, and, once a workspace installs them from the agent store, humagen-writer and humagen-analyst (Core) and code-reviewer, security-reviewer, architect-reviewer and qa-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 agent calls 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's refused). 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 (agent with fresh or label on POST /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 as auto reads as *.
  • auto stays reserved: no agent or person is named it. @auto is not a tag; no one goes by it.
  • An agent opts out with tagged_only: true in its spec (fiber's AgentSpec): 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.Words is 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/runs with agent omitted uses the default chain; with none set, or agent: "*" (or auto), 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.Instructions stays 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 for cron and manual runs 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>, and project: 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. With memory_auto_approve on, what it writes for the workspace or a company project still waits for someone holding projects:govern, since the turn that taught it needed only runs: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. pin writes them into the tag as _warp.sources, over whatever a caller put there, under that key or the public warp.sources runs 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's Sources (as knowledge://<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:read wherever it is named, so naming one in a project takes an owner and knowledge:read (403), which reads it anyway, and a source the workspace has (400). A reader without knowledge:read is 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 without projects: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 is PartInfo), never in "Needs you". reads(announcement) = projects:read. writes is also projects:read, because hiding your own copy changes nothing others see.
  • Message.Broadcast is stored on the raised message. On a broadcast, Dismiss and Snooze record only the reader's own state (tenant.hidden[id][subject]). Replaying the DidDismiss and DidSnooze changes of broadcast messages rebuilds it. Every other message keeps today's shared state. Withdraw stays shared and records who withdrew.
  • Count returns {open, unread, updates}. Broadcasts count only in updates; 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}/announcements with {subject, text, severity}, by anyone whose role is at least Project.Announce (owner by default). From{person}, key announce:<project>:<seq>. The author or an owner withdraws it.
  • Agents, on a schedule (phase 5): a schedule filed in P with deliver: project and an agent available in P. When its cron or run-now run completes, ended() raises an announcement From{agent}:
  • the first line is the subject (at most 150 characters) and the rest is the text (at most 4,000);
  • an answer of NONE posts 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 to humagen-analyst and to any agent an admin grants it. It reads only the run's own project subtree:
  • runs (a Summarize filtered 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/release reads it: a release is a ## 0.16.0 (date) heading, and its feat entries are its ### Breaking and ### Features groups, each entry without its markup and commit link. The release tool files a breaking feat under 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.PostOnce checks 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 with announce:, 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.kind system, by humagen), which the room shows without a person's or an agent's mark and a run is sent as humagen (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=postgres as 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. Count is 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 Permission enum in api/openapi.yaml;
  • everything in internal/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 allow and trusted, 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 shapes map of TestSpecSchemasHaveTheFieldsTheGoTypesMarshal (inputs written: true).
  • Each operation gets a validated 2xx and its documented errors in TestResponsesMatchTheSpec.
  • Each {name}, {channel} and {id} path joins the real and valid maps for the globex 404 sweep and the empty-workspace [] sweep.
  • TestSpecListsExactlyTheRegisteredRoutes and TestSpecPermissionsAreTheOnesTheServerEnforces cover 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:

  1. Names match the project regex and are unique ignoring case; channel slugs match theirs.
  2. A parent names a project in the same file. A parent that exists only in the console cannot be checked before start, so it is refused.
  3. No cycle; depth at most 4; at most 10 company projects; company only under the root or company; account-like never under account-like; account only on account-like kinds.
  4. Kinds are built in or in project_kinds; a KindSpec has like team or account.
  5. who forms, roles, topics and caps; until phase 7 every chain has a * entry.
  6. enable, allow and default name agents in the file, built-ins, * (enable, and as a default for everyone decides; auto reads as *). An agent has at most one home, in the file. A default is available where it is set.
  7. A schedule's cron parses, its agent is available in its project, and deliver: project sits on a project.
  8. knowledge names 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.
  9. skills declares 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_kinds declares at most 16 kinds, each a kind's name that is not sme, skill or auto, once, with a title of at most 40 and resolves one of experts, skills, role or people.

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 Page titled 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 with can("projects:write").
  • Project. A Page with 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 through Page.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:write and 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 Stroke edge;
    • drafts sit at the top for owners, with Publish and Discard;
    • "Post Announcement" for those allowed, and Include Sub-projects.
  • 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 Page titled #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 from GET /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 /name too. A posted message shows each skill it names as a /name chip, whether it was written /name, $name or @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 / #deals when 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 with POST /api/threads as agents and mode (join or all) and saved with PUT /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's routed, 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 calls POST /api/threads/{id}/share and 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 note tags 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 through slack.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.Bots is 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

  1. At platform start, the migration runs for each tenant whose projects namespace is empty and whose stored settings hold the legacy array (storedSettings.LegacyProjects):
  2. One write imports every entry as {kind: team, parent: "", title: "", created_by: "migration", created_at: SetupAt or now} with one h: entry each, and creates the root.
  3. 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's h: 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.
  4. Then settings are rewritten without the array.
  5. 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.
  6. A failed import fails the start and changes nothing.
  7. Nothing keyed by a name moves: Run.Project, thread summaries, usage entries and counters, policy scopes, project:<name> memory, schedule warp.project meta, alert rules, artifacts and inbox Source.Project.
  8. Usage entries written before phase 1 have no Within, so they count toward their own project only, which is correct: no tree existed. usage.Rebuild replays them unchanged. The ledger keeps 62 days.
  9. The spec's workspace.projects is 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.
  10. Contract changes, in the same PR as the console and make client:
  11. Settings.projects leaves GET and PUT;
  12. updated_at on a project view becomes active_at;
  13. project and project-memory routes move from runs:* to projects:*.

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, Resolve and 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/projects with the root and the fields Name, Title, Description, Kind (company, team, account), Parent (fixed at creation), Account, Instructions, Managed, Version and audit fields.
  • History and tombstones in the same namespace, and the Tree snapshot.
  • 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.Within pinned at admission; usage.Entry.Within and ancestor scopes; storage summed over the subtree.
  • Context. p.contextOf sends, 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 do cron and manual runs filed in a project. The root's notes live under owner project:.
  • Permissions. projects:read, projects:write and projects:govern, through default.authz, policy_test.go, the openapi enum, everything, access.ts and the docs. No roles yet: company kind and the root need projects:govern.
  • API. The phase 1 routes, memory routes regated, threads?project=&within=, and per-project counters in runs.Index.
  • Spec. title, kind, parent, account and instructions on projects, and workspace.instructions; Platform.check rules 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/projects with 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 through statetest.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_runs of 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/usage and pkg/policy: Within counts from day totals and from inside a day; Rebuild agrees; For returns 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/spec and internal/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-check and make spec-lint all 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.Project and 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; title covers 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.projects leaves 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.