Skip to content

Architecture

This is the plan of record. The status table says what exists.

What this repo is

Humagen is the composition. It owns the pieces that only exist once the parts are put together: the call tree, governance, routing work to people, and the stores behind them. It does not reimplement what it composes.

Part Owns Repo
Event union, bus, egress, connectors, durable runtime, definition pinning Transport and surfaces fiber, now saige/flow (github.com/urmzd/saige/flow/...)
Agent loop, tools, MCP client, RAG, evals, OTel Runtime saige
Sandboxed execution nodes, NGAC Confinement saige/sandbox, formerly playscape
Durable runs and replay Crash survival saige/durable, formerly anchor
Components and helpers for web, Slack and GitHub Presentation This repository: packages/, internal/presentation/github

The presentation boundary

The packages/ UI libraries and internal/presentation/github are components and helpers only. They take data in as props and events and emit actions out.

The test for where something goes: if it needs a network call, a database or an identity, it belongs in the platform or a surface host. The platform owns the wire. It reads fiber's event.Envelope into Humagen's run model and raises Humagen's actions as events. internal/wire is the only place the two meet.

The event flow

Every event is one event.Envelope with a typed body, and type is its only discriminator, such as message.posted.v1 or run.completed.v1 (fiber's design). A run goes:

surface (console, Slack, GitHub, cron)
  -> ingress: a typed event on its channel (message.posted.v1, github.*.v1, cron.tick.v1)
  -> Platform.Invoke: the agent named, or each that joins (pkg/join); limits and policy (pkg/call)
  -> runtime.Accept: the definition pinned (name, version, digest, sub-agents, policy hash)
  -> anchor: fiber.turn.v2 activities; each turn is a turn.Runtime in a playscape sandbox
  -> run.* events on the bus, on the trigger's channel, under the run's tenant
  -> egress: the sink of the channel's scheme (Slack, GitHub); the API's event stream; the journal
  • One bus, by channel and type prefix. A subscription names a tenant, channel prefixes and type prefixes. An empty one receives nothing, control channels only reach a subscription that names them, and run.usage and run.context only one that names them. The tenant is the principal's.
  • Hops. Each event carries hops; fiber drops one over DefaultMaxHops, and an agent's own output never wakes it.
  • At least once. fiber keys a run by the event and its agent, so a redelivered trigger joins the run it started. Humagen keeps its own run ids (runtime.AcceptOwn), and a call key joins its run.
  • The model reads the catalog. The trigger reaches the model as its catalog rendering, byte stable across replay. A sensitive body (human text, private host data) reaches the model but not egress logs or webhooks unless a subscriber opts in.
  • Who answers. Humagen picks agents itself: by name, through the entry agent that owns each root session naming nobody (internal/platform/entry.go), or through the dynamic router (pkg/join). fiber's channel membership (saige/flow/membership) is built but not wired in; its dispatch package was not carried into saige.

One primitive: the call

An agent is defined by a spec and runs in a sandbox. When one agent needs another, it makes a call: a new run of the other agent, in its own sandbox, raised as a tag on the bus and linked to its caller by an edge.

A subagent, a handoff and a delegation are the same call with a different mode.

Mode Context passed Caller after the call Answer goes to
Subagent Explicit ordered messages Waits, then resumes The caller
Handoff, low-level API only Explicit input No automatic termination; ownership transfer is not exposed as an agent tool The inherited surface
Delegate Explicit ordered messages Keeps working The inbox, later

One origin, two lifetimes

Every run belongs to one origin: the run a person, a schedule or a trigger started. Runs nest under it as deep as the limits allow, and each records its origin, its caller and how it was called.

Lifetime How it is started If the caller fails or is stopped When the caller answers first
Attached An agent call, which waits It is stopped, and so is all that is attached to it The caller is held open until it ends
Delegated An agent call with background: true, or a low-level delegate or handoff call Nothing. It carries on Nothing. The caller is done

What a delegated run attaches dies with it, not with whoever delegated to it. A run stopped this way is stopped, not failed, and says why.

Stopping a run

A stop is the runtime's, not the platform's. POST /api/runs/{id}/stop and a Slack stop button both call fiber's runtime.Stop with a reason and who asked. The runtime records the request on the run in the anchor ledger (runtime.WithStopLedger), so a run still in the queue or between attempts honours it whenever it starts, and publishes it on the bus to the attempt executing the run, which cancels the model call in flight and any running tools, and ends the run with lifecycle.stopped carrying what the agent had said. "Stopped" means cut short: the agent loop judges it, and a turn that had finished its answer before the request took effect ends completed.

State Status stopping What it means
Asked unchanged (accepted, running, parked) true The request is published. The run can start no further calls from this moment.
Stopped stopped absent The runtime confirmed it. answer is the partial answer people saw, cause is the reason.
Finished first completed or failed absent The turn ended before the request reached it. It is reported as it ended, never as stopped.

The route answers 202 with stopping while the run has not ended and does not wait for it. A run that has ended is answered 200 as it is, so asking twice is safe. The runtime gives a turn StopGrace (ten seconds by default) to wrap up before it cancels it, and the run still ends stopped. A run in the queue stops before its first model call when a worker picks it up.

After asking, the platform reads the ledger (runtime.StopRequested). A run the ledger holds no request for had already ended there, so it is settled from the ledger at once and the route answers 200 with how it ended. When the runtime cancels a delegation because the caller was stopped (runtime.ErrStopped as the context's cause), the run Humagen started for it is asked to stop too.

A run parked on a person is stopped the same way: the runtime resolves its question as stopped and ends it without calling a model, and its inbox message settles as stopped, with the cause.

A run that has answered and is only held open by what it attached has no turn left to interrupt, and was not cut short. What is attached to it is stopped through the runtime, and once they have ended it completes with its answer.

If the runtime cannot carry a stop (runtime.ErrStopUnavailable, a bus that cannot be subscribed to), the request fails closed: the run is still marked stopping, so it starts nothing more, the route answers 503, and the run ends as its own events say. It is never reported stopped while it is still working.

A stopped turn is kept in its conversation. The next turn is sent its partial answer followed by fiber's StopMarker line. Who stopped it and why is not sent to a model. Housekeeping (titles, memory) does not run after a stopped turn, an eval case that was stopped is a failed case, and a stopped run counts as stopped in the statistics, not as active.

Detached branches

The child is a durable run of its own, with its own journal, context window and topic (agent:<name>:<runID>). The caller holds a reference and a result, never the child's work. Each branch compacts alone, and a tree can spread across nodes.

Humagen exposes one agent tool for allowed targets: {agent, title, brief, background?}. The calls endpoint takes ordered messages, examples and references, with a discriminated return contract. The harness resolves and freezes inputs, injects the return instruction, and validates results. See Agent calls for the contract and lifecycle.

Governance rides the edge

Concern Rule
Cost A child leases budget from its caller and settles when it completes: the lease is released and what the child spent, priced by the runtime, becomes the caller's. Limits apply to the whole tree: every run counts against its root's project and client. See Usage and spend.
Access A child gets the intersection of its spec's access and its caller's grant. It is never wider.
Consent Both sides agree to a call. The caller's spec names the callee in its spawn allowlist, and the callee's call policy (pkg/callpolicy) admits the caller: anyone, only the agents it listed, or none. The policy also says which admitted calls wait for a person (never, always, or callers not trusted when unlisted), who approves them, and how long they wait. A refusal names the side that refused. The agent tool offers only the agents both sides agree to.
Shape Depth and fan-out are capped. The zero limits allow no calls.
Tracking Root, parent, depth and trace context travel with the tag, so telemetry shows one tree.
Stopping Stopping a run stops everything attached beneath it, through the runtime. What it delegated carries on.

Usage and spend

The runtime reports what every model call used (fiber's usage family, v0.10.0 and later): tokens, cost from saige's price catalog in integer micros of a currency, and the model's context window. Humagen counts it, holds it against limits, and stops what goes over.

Counted once

Source When Key What it adds
run.usage.v1 on a run's stream As each call completes The runtime's accounting_id The call, to the usage ledger, under the run's place
The run's total (run.completed.v1 or run.stopped.v1, else the ledger's output, else runtime.RecordedUsage for a failed run) When the run ends run:<id> Only what the calls already counted for the run do not cover: a call whose event was missed

The platform's observer sees every event (a subscription with no kind filter receives the usage family). A redelivered call, a redelivered terminal event and a reconciler pass all find their key already counted and add nothing. A run is counted as the larger, field by field, of the calls seen for it and its settled total, and both are kept after it settles: a call whose event arrives after the settlement (the call a stop cut short is reported late, while the settlement runs from the reconciler or the stop) adds only what goes beyond the settled total, in either order. Once a run has settled its spent no longer moves, since it has settled into its caller. A run's settled total is its own calls (RunUsage.Own), never the runs it called, which settle their own: each model call in a tree is counted once, in the run that made it.

Every ledger entry is stamped with the server's clock when it is appended (the call's own time is kept as event_at), and counts in the period its stamp falls in, whatever order entries arrive in. Counts are kept per scope and UTC day as entries are applied, so judging a call reads at most 62 days of totals.

Roll-up

An attached run (tagged, the caller waits) is rolled up into its caller: once it has ended and the ledger records it, the Delegator calls runtime.ReportChildUsage, and the caller's usage.children and usage.total include it, once. A run the platform ends from the ledger, before it has observed the run's final event, is ended with the usage the runtime recorded in the same write, so a caller that reads it as ended reads all it used and does not leave it out. A delegated run (a background agent call) is not rolled up: the turn that handed it over has moved on, so there is no turn to report it to. Its spend is the same request's work, so it counts against the same budgets: every run in a tree counts against its root's project and client, its own agent, and the workspace. The run manifest's usage.total sums every run's own calls in the tree, attached and delegated alike.

Enforced

When What is judged What happens
A run asks to start Spend and tokens in the period, with runs and concurrency, under one lock A scope that has reached its spend limit, to the micro-dollar, or its token limit refuses: 402 for spend, 429 for tokens, with the limit, the policy and its version, and resets_at
A call is counted Spend and tokens of every scope the run is in (policy.Exceeded), each limit raised for this run by what people granted it there this period At the warning threshold, one budget alert and one inbox message per scope and limit while it is open. At the limit, the run is stopped through runtime.Stop, with a reason naming the limit, the scope and the policy version, a halted notice, and one alert. Every other run in the scope is stopped at its own next call. Where the policy's action is approve, the run is held for a person instead (see Approving a run at a limit); a limit that blocks outranks one that approves
A run with a lease spends Its spent plus what it has handed to calls still working (granted), against its lease Stopped through the runtime once the two reach the lease
A called run ends Its lease and its spend The caller's granted releases the lease and its spent gains what the child spent. If the caller has already settled, the spend climbs on to the nearest ancestor still open, or the root

An agent's own calls, waited on or in the background, lease from a metered caller without naming an amount: each is granted half of what the caller has left. What is left is read from the calls already counted, and the model call that asked may not be counted yet, so the other half holds room for it; everything is trued up when the call settles. A caller with nothing left is refused. A stop at a limit that could not be requested is asked again at the run's next counted call. Housekeeping runs are never refused or stopped, and what they spend is still counted.

Approving a run at a limit

A policy whose action is approve names what one approval grants: max_grant (micro-USD) with a spend limit, max_grant_tokens with a token limit. A run in flight that reaches that limit is not stopped. The platform asks the runtime to hold it (runtime.Hold, topic budget), and the run parks at its next batch of tool calls, before any of it runs: one model call after the one that reached the limit, since that call's usage is reported as it ends. A held notice is written to the usage ledger.

The question is a budget question: an approval in the inbox (kind approval, part kind budget with the scope, limit, usage and grant), on the run and in Slack, from Limits. Anyone who reads the run sees it; only billing:write is offered its actions or may answer it.

Answer What happens
Grant (approve) The run may use the policy's grant more in that scope, in the policy's period. The amount is read from the policy when the grant is made, never more than the question offered; a policy no longer approve grants nothing and the answer is refused. The grant is a granted entry in the usage ledger with the run, scope, limit, policy version and who granted it, and the run carries on. Reaching the limit plus what was granted holds it again
Stop (deny) The run is stopped, with the note as its cause, and the batch it held never runs
Nobody answers in time The same as stop: a hold defaults to a denial

A run is held once per scope, limit and grant. A hold the runtime cannot record stops the run as before, so a limit is never left unenforced. A run asking to start at an approve limit is refused as at a block one: there is no run yet to hold. Grants are read from this process's usage ledger (written to the store and replayed at start), not from the shared counters.

Unpriced calls and other currencies

A limit is in US dollars. A call saige could not price (a model with no rate card) and money in any other currency are never counted as zero dollars and never compared with a dollar limit. They are counted apart: unpriced_calls and other_costs on the run, on GET /api/usage, and in Analytics, where the spend is shown as a lower bound. The first such call in a scope with a spend limit raises one alert, open until settled, saying its spend is a lower bound. Tokens are counted for every call, priced or not, so max_tokens on a policy is the bound that holds whatever the price.

Where it shows

Surface What
GET /api/runs/{id} usage (own, children, total, context), spent, granted
The event stream and listRunEvents run.usage.v1 and run.usage.child.v1
GET /api/usage spend (used, limit, unpriced_calls, other_costs) and tokens per scope
GET /api/analytics usage per group: calls, tokens, spend, unpriced calls
Console The run's Activity page (calls, tokens, cost, context), the session gauge's context edge, Analytics, Limits
Slack app Nothing. Usage is not shown on a turn in the console either, so the shared adapter carries none (see clients)

People in the loop

A run that needs a person parks on a question. fiber (v0.11.0) owns the waiting: the question is recorded on the run in the ledger, the run holds no worker while it waits, and the first answer recorded is the answer. Humagen owns who is asked and where.

A batch of tool calls that each wait (several approvals, several ask_person questions, several calls to other agents in one model message) parks the run once on all of them. run.parked.v1 carries question, the first, and questions, all of them, when there is more than one; run.resumed.v1 carries answer and answers. Each question is still answered on its own, and the run resumes when every one is answered. Calls to other agents in one batch start side by side.

Question Raised by Answered with
Budget The platform, when a run reaches a limit whose policy asks for approval (runtime.Hold, see Approving a run at a limit) approve, which grants the policy's amount and resumes the run, or deny, which stops it. Answered by billing:write only
Approval A call to a tool the agent's spec lists in approvals approve (optionally with edited arguments, checked against the tool's schema, and for a call that acts as a person, tool.acts_for_person on the run and in the inbox, only by that person, so every approval card says so and none offers an edit of it) or deny (with a note the model is shown). In a run whose answers may reach a person's own credentials, only that person edits any of its calls or adds a note, and the question names them (steered_for), so an agent's approval queue offers nobody else a note
Choice The agent calls ask_person with options choose one option
Reply The agent calls ask_person without options reply in words

Who is asked

Who may answer is decided from the run's pinned revision, so revising an agent does not change who may answer a question a run already asked:

Question Who may answer
Approval approvers when the spec names them, else anyone in the workspace. Never the person whose request raised the run, nor the person who started the tree it is in, by any name they go by (a Slack user is also every principal a Slack client of the run's team maps them to, pinned when the run starts), unless the spec sets self_approval. fiber's AnswerRequest takes no requester alias, so Humagen checks this before it asks the runtime. A GitHub actor is mapped to no principal, so self-approval there is not detected
Choice, reply answerers when the spec names them, else anyone in the workspace. A run whose answer may reach the credentials of the person it acts for (it, or a run that called it, acts for a person and is answered by a revision granted a person-scoped tool provider) is answered by that person alone, since an answer steers what its tools, and its callers', are asked next: the question is addressed to them, and anyone else's answer is refused (maySteer, steeredFor). When answerers, a called agent's own for what it asks, leaves that person out, nobody may answer: the run waits until the question expires and takes its default, or until it is stopped

approvers and answerers name principals by subject and this workspace's roles as role:<name>. The runtime asks Humagen for a person's roles (runtime.WithRoles): the roles they signed in with, or for a person a surface answers for, what the authorization policy grants their subject. Anyone else holds no role, so a role admits nobody it was not asked about.

Each question becomes one inbox message (kind approval or clarification, with an approval, choice or reply part), addressed to exactly those people: a reader sees it only when the spec names them or a role they hold, and the requester never sees an approval of their own call. The agent's asked_of hint narrows that to whom it asked, when that is one of them; it admits nobody. A question whose rules cannot be read is addressed to nobody. Answering needs runs:write as well (for a person a surface answers for, their own grant must include it, not only the surface's credential's), and the runtime checks who may answer again before it records anything.

Addressing routes a question to its inbox; it is not confidential. The question and an approval's arguments are also on the run, its event stream and its manifest, for anyone with runs:read. See security.

Answering

From the inbox (resolveInboxPart), on the run (answerQuestion), or in Slack, an answer is one call: runtime.Answer, with the person as By and the credential's own subject as Via. A refusal is 403 and changes nothing. A second answer, or one after the question expired or its run was stopped, is answered with the message showing what was recorded. The decision is recorded in the inbox's record of changes, with who answered and, for a surface, which surface user.

The message settles in place when the run resumes (approved by olu, chose eu-west), when nobody answered in time (expired, with the default the run carried on with: a denial for an approval), when the run is stopped while it waits (stopped, with the cause), and when the run ends without an answer (closed). A run is woken through the queue as soon as it is answered or stopped (runtime.WithWaker), and at its question's deadline, so a default applies when it is due. Questions wait a day by default (QuestionTTL).

Called runs

An attached run (tagged) that parks shows its question on its caller's stream as lifecycle.child.parked (runtime.WatchChildQuestions), and its message is addressed by the called agent's own spec. The caller keeps waiting in the Delegator, holding its place, while the called run holds none. fiber's WithChildRuns, which frees the caller too, is not used: it starts the child inside the runtime, so the call would bypass Humagen's call path (the spawn allowlist, depth and fan-out, the lease, admission and spend, the call tree, and the conversation and sandbox the child shares), and it has no hook for a host to make or refuse that call. Usage is rolled up as before, by the Delegator's ReportChildUsage, once per child. Since one place is always kept for work that waits on nobody, parents waiting on parked children can refuse new attached calls (ErrBusy), never hang.

Calls held for a person

A call the callee's policy holds for a person is decided by callApproval in internal/platform/call_policy.go. The agent tool declares it as its per-call approval, the wrapper every run tool passes through is a native.Approving tool (saige/flow/turn/native), and fiber's host call tool wrapper forwards Approving, so the runtime parks the caller on an approval addressed to the policy's approvers (role:manager and role:admin when it names nobody, so a held call is never open to the whole workspace). The call goes through only when a person approved that very tool call; otherwise the callee refuses it. The question waits the policy's expires_seconds (ApprovalRequest.ExpiresIn, capped by the runtime), then is denied.

Decentralized

A peer node is a connector. One node addresses an agent on another the same way it addresses a Slack thread, so a cross-node call is a tag with a route.

This depends on execution nodes that publish to the bus themselves. Today fiber streams out of the sandbox through an in-process channel, so every agent runs inside the serving process.

Storage

Target the Postgres wire protocol. AlloyDB is one deployment of it, not a requirement.

Every store has one choice, memory or Postgres, made in one place: platform.Config.Backends, which humagen serve -state=postgres fills from HUMAGEN_POSTGRES_URL through platform.OpenPostgres. Agent definitions are kept by pkg/agents on pkg/state, and fiber's pkg/durable keeps anchor's run ledger and queue. Humagen's own stores do not each get a SQL copy of their rules. They keep their records in pkg/state: a namespaced, tenant-scoped document store with a Memory and a Postgres backend, one table, held to one conformance suite. Every store reads and writes it per request (RFC 0004, horizontal data): it holds no copy of its records in memory, replays nothing at start, writes before it reports a change, and writes nothing behind. A cache in front of a store is kept only where dropping it changes no answer: a record that never changes, or one checked by version.

Memory is files. pkg/drive keeps versioned file trees, one per person, per project and per agent, with each version's manifest (path, content hash, size) and the trees' heads and open proposals on pkg/state, and the content once per tenant, by hash, in the configured blob store. A deployment whose blob store is in memory keeps memory's content beside its manifests instead, so a restart that keeps a note's place keeps its text. Versions and content are read when asked for and held in a bounded cache. pkg/memory is the notes' view of those trees: a note is the file notes/<id>.md, approved at the head and pending as a proposal. The notes kept in its old namespace move into files once, at start (RFC 0004).

Lookup reads one record with its version, List reads one page of one tenant's keys by prefix, at most state.MaxList (1,000) records, with a cursor, and an op may name the version it read (state.PutAt, state.DeleteAt) or require no record (state.Create): a write whose record moved fails whole with state.ErrConflict, and the store reads again and retries (state.Retry, Table.Update). Every record's version is 1 when it is written and one more on every write after; rows from before versions read as 1. The rules for a store:

  • The tenant is the shard key. A request reads one tenant, never a scan across tenants. A background loop that walks tenants pages a namespace's tenant directory (state.Tenants).
  • A key starts with what a request pages by, so a page is a prefix: a run's call tree under t:<root>:, a conversation's messages under m:<conversation>:, ordered by state.Seq. A list ordered by activity keeps an index key moved in the same write as the record.
  • A write changes one tenant, all its records and index keys at once. A link to another tenant's record is its id, and work across tenants is a run that retries, not one transaction.
  • Every read is bounded: a page, a row cap (state.Table.All fails past its cap), and caps on what a tenant may hold, enforced on write by a count kept in the same write.
  • An event folded twice changes nothing. Until delivery is split between replicas, every replica folds every event, and a takeover may fold a few again: the run index folds a lifecycle event only past the run's last sequence and a usage report once by its accounting id (or run#seq), the journal keeps an event once by run and sequence, and the usage ledger counts an entry once by its key.
  • The database is the truth.

state.OpenPostgres migrates the table and takes no lock, so any number of processes may open one database. Records an older release kept in another layout are moved once, by whichever process opens a store first, behind a marker in the tenant ""; each move is a conditional write, so processes opening together move each record once. Load, which reads a namespace across tenants, is used only for those moves. Stop every process of an older release before a newer one starts: an older release keeps its stores in memory.

The run index (pkg/runs, runs.v2) is the busiest: a run under o:<seq> with its number under i:<run>, runs in flight under a:, call trees, a conversation's turns, a conversation at a glance (s:) and its place in the activity order (u:), and project counts, all moved in the run's write. A caller's count of attached runs still working moves in the same write as the attached run's ending, so a stop asked through any replica, and a caller settling on one while its call ends on another, agree. Threads, the inbox, the journal (100,000 events per tenant), memory and drive, artifacts, knowledge and the catalog, projects, people and the rest follow the same rules; each package's doc gives its layout.

The usage ledger's counts are the exception: on Postgres they are kept in the database, not in memory (usage.Counters, tables humagen_usage_*). Every change to the counts is one transaction that moves them and writes the ledger entry that moved them (state.WriteTx), with the entry's key from a database sequence. A call's spend is counted once by its key whichever process saw it, under the tenant's advisory lock, since it reads and rewrites its run's row. Entries, notices, grants and a run's spend are read from the database, paged and capped, so a grant approved through one replica is judged by every other.

The counts an admission moves, runs started and runs in flight, are striped: usage.Stripes (8) rows per scope (humagen_usage_admits, humagen_usage_slots, locked through humagen_usage_stripes). A policy's run and concurrency limits are quotas (usage.Quota) that usage.Ledger.Admit takes in the transaction that counts the run. A limit is split into a share per stripe; an admission locks one stripe at random in each scope it has a quota in and goes ahead when that stripe has room, counting every other stripe at its share or its count, whichever is more, since no other stripe can pass that while this one is held. When it has no room, the admission locks every stripe of those scopes, in order, and goes ahead on any stripe if the total has room. So the limit is exact, an admission is refused only when the total has reached it, and admissions far from a limit do not wait on each other; one with no quota takes no lock. The judge decides the rest (spend, tokens, a lease's size) and warns, on the counts as they are. Counts a release before stripes wrote are read as stripe 0. The first start on a database fills the counters from the ledger's entries. On memory the counts stay in the process.

The event bus is on the same database: fiber's bus.Postgres keeps events in fiber_events (with fiber_event_runs and fiber_event_tenants) and wakes readers with LISTEN/NOTIFY on one connection per process, whose payload is the tenant published to, so only that tenant's readers query. It is the default whenever the stores are on Postgres, and there is no Redis bus. Each tenant's events have a position of their own (tseq), taken under an advisory lock per tenant, so publishes to one tenant are serialized and publishes to different tenants do not wait on each other. Egress, the observer and fiber's dispatch read through consumer groups (RFC 0006): a cursor and a lease per group and tenant in fiber_consumers, so one replica at a time handles a tenant's events for each, another takes over when its lease expires (15 seconds by default), and it resumes from the last cursor committed. anchor's Postgres queue still has no delta log; the bus carries every event, so streaming does not need it.

The in-memory bus reaches one process only: two replicas on it would each miss the other's events, with no error. So more than one replica on it is refused (RFC 0006, change 8). A deployment declares its replica count as server.replicas (or -replicas, 1 when left out); humagen config check refuses a file that declares more than one with a memory bus (a bus left out is memory unless the file says stores.kind: postgres), the start refuses it on the bus it opened, and the Helm chart refuses replicaCount or autoscaling.maxReplicas above 1 with memory stores or system.spec.bus.kind=memory. The message names the fix: stores and the bus on Postgres, or one replica.

The inbox's and the threads' change notices (Watch, which feeds the event stream and a conversation's live updates) reach every replica through bus.Notices: Postgres NOTIFY on the channel fiber_notices, with no table, scoped to the schema and carrying the tenant, and one LISTEN connection per process. pkg/notice keeps each process's watchers, tells them at once, and queues the notice for the others (at most 256 waiting, 2 seconds a send, 2 KB a notice); a process does not hear its own notice twice. A notice is lossy: a watcher not keeping up, a full queue or a dropped connection loses one, and the watcher fetches again on the next. On memory a notice stays in the process.

A worker stopping mid-claim on Postgres no longer leases a run to nobody: since anchor v0.5.1 the queue waits out a claim it has already sent, for up to 5 seconds after the stop, and the worker hands back unexecuted a run a claim returns after it stopped. Before, the database could carry out a claim the worker had given up on, and the next process could not resume that run until its lease ran out, 30 seconds later.

A run delivered again to the process still executing it, because its lease lapsed under the attempt at work, is handed back to the queue uncharged and offered again every second until that attempt lets go (TestARunDeliveredAgainWhileItsFirstAttemptWorksCompletes); a lease that lapses still costs the run one failure. The wait is bounded: 5 seconds after the attempt's heartbeat is told its lease is gone, or one lease (30 seconds) after the run first came back if that heartbeat says nothing, the next delivery is taken whether or not the attempt let go (TestTheGateStopsWaitingForAnAttemptToldItsLeaseIsGone, TestTheGateStopsWaitingForAnAttemptWithNoHeartbeat).

Limits at scale

Admission and spend are counted in the shared store on Postgres (see Storage): two processes on one database cannot both admit the last run a limit allows, and each sees the other's spend at its next read. Admission is striped, so it no longer waits on one lock per tenant: 32 racers admitting into one tenant from two processes went from about 350 to about 3,500 admissions a second with no limit, and from about 310 to about 2,000 under a run limit (Postgres 17 in Docker on a laptop; BenchmarkSharedAdmission). Spend is still counted under one lock per tenant. The stores read and write per request and pkg/state takes no lock, so the chart allows more than one replica; delivery, the observer and the loops that must run once are shared between replicas by consumer groups and process roles, which land separately.

Limit today What it needs
Client secret values are kept in the database as written A secret manager behind clients.Secrets, or encryption at rest
Lists that span a tenant (a page of conversations, a summary, a search) read at most 20,000 records from the newest, and a search matches words over that window or a stored token index rather than a search engine. A search outside the record store
A client changed through one replica is seated on the others within 2 seconds, polled from one change count; a webhook in that window is looked up at once only if no other unclaimed request read the count in the last 250ms. A connector's stream state (the message a run is editing) is in its replica's memory, so a reseat or a lease takeover starts a new message A change notice pushed to every replica, and stream state kept with the run
A download reads the whole file into memory, which the 2 MB cap makes safe Streaming, before the cap is raised
A conversation's room (pkg/rooms) counts its readers per server, so rooms.coalesce_above is per replica, and each room reads the tenant's whole run stream once and keeps its conversation's events. The workspace-wide stream the console's lists follow is not coalesced: every reader with it open is still sent every run state change and thread notice they may read The bus sharded by conversation (RFC 0004), and the lists' stream moved onto rooms
The journal keeps 100,000 events per tenant, each twice (by time and by run), and a query looks at most at 10,000 An event store, or OTel export

Status

humagen import sessions keeps in each session's document what its export holds: every turn's time and original id, tool calls linked to their results (ChatGPT's too), attachments by name, type and size, and each branch in a section naming the turn it forks after, in the order the export's parent links give. A document that would now read differently, one an earlier version wrote included, is replaced in place under the same id by one conditional call (PUT /api/knowledge/{name}/documents/{id}/text, taken only from the digest of title and text last read), and keeps whether it is left out of search. An import the server refuses never writes over the winner: it reports the session as a conflict. With --project NAME the sessions of a ChatGPT or claude.ai export, which carry no directory, go in the source --by-project names for NAME, never the one that holds a directory's sessions, and that source is attached to the project of that name; a session an earlier run put in another source is left there and reported, not moved and not updated. A source named for a directory or a project is added to and attached only when its description says it is that one's; the monthly sources are not checked this way. It is tested with synthetic exports and read back from a local server; it is not checked against real exports of each tool, and file bytes are not imported (import).

Each imported session's document is kept with the session's structure, written through its own routes in the same write as the document (pkg/knowledge/imported.go, internal/httpapi/import_documents.go), with a digest of the structure itself, so a later stage can pin source, document, document digest and structure digest together; a structure kept for a revision is never replaced in place (409). Each route checks knowledge:import, and the platform also requires knowledge:write, since the text is written too; the built-in manager and admin roles hold both. The structure is the tool, the conversation's id, its start and end, the main path's turns with speaker, time and text, every branch not on it counted, and exact counts of what was left out or cut, at most 200 turns and 128 KiB a structure and 8 MiB a source, tool results dropped before turns and the oldest first. It is the importer's assertion, kept with who sent it and when; the server cannot verify the session. The ordinary document routes refuse a structure, and an ordinary edit leaves it untrusted for good, until an import writes it again; it goes with the document or its source. ImportedOrigin in internal/platform reads it as the reader, with its importer, or says why it is unknown (not_kept, changed, malformed). The CLI falls back to the ordinary routes, without structures, against a server that has no import routes or a token that may not import, says so with how many documents remain without one, and a later run that may import restores them (restored), writing the structure alone: no new embedding, no new content version. A restore refused for lack of room among a source's structures leaves the document present and counted (structures_full), and a token without knowledge:write fails the run with that reason instead of falling back. Tested: the store on memory and Postgres, the four formats' generated records included (pkg/knowledge); the routes, the read function and the CLI against a real server and a stub older server on memory only (internal/httpapi, internal/platform, internal/app).

Continuing an imported conversation is built in the platform, with no route and no console yet (ContinueImport in internal/platform/import_continue.go). It starts a private plain thread of the caller's, in the source's project (the one it is scoped to, else the one it is attached to, else the workspace itself), holding the conversation's origin (Thread.import, read only in the contract): the source and its id, the document, the document digest and the structure digest the caller read, pinned together; who imported the structure and when; who continued it and when; the conversation's start and end; the branches not continued; what the import itself left out; and the passive turns its agent is sent. Those are the newest turns of the main path that fit, when the conversation is started, half the workspace's history limit, counted as that limit is (each line with its label, its mark and its line break), and a fork's bounds (200 turns, 128 KiB), tool results left out first and every turn left out counted; nothing is summarized. So the first turn sends them whole, even at the smallest limit (1,000 characters). That half is not reserved: each turn is sent the newest lines that fit the whole limit, so as the thread's own turns grow, the oldest lines, imported ones included, are left out and counted as omitted. Each line is labelled from fixed lists, such as imported from chatgpt, the assistant there, and what it says starts (imported, not said here), on one line, so it cannot open or close the transcript or pose as a speaker.

A document no import kept a structure with is continued as one block whose speakers are not known; one whose structure was edited or is malformed, or that is not an imported session's, is refused. So is one whose document or structure digest changed since it was read, whose source was detached from the project it was seen in, excluded, deleted or hidden, or where the caller may not start a run (runs:write) or post. The source and the document are read twice, to check who may continue it and again just before the thread is written; the record is built from the second read, and any difference between the two (another source of that name, another importer or import time, another project) refuses it. Knowledge and threads are separate stores, so a source deleted or made again after the second read and before the write is not seen then; the thread pins the source's id, so no one sees it. It is audited (conversation.continue_import, with the source's id).

A workspace whose history setting is none sends agents no earlier conversation, so it starts no continuation. When the setting becomes none later, nothing is posted, run, followed up or forked in an existing continuation; its runs are refused as they start, with the settings that would decide what they are sent, and it works again once history is sent.

A reader must still see the origin source to read the thread, as a fork's reader must see its source, on every read path; a fork of it keeps its origin and that rule, and neither is published raw. Each source has an id, set when it is created and never given to another, so a source deleted and made again under the same name is another source: a continuation of the first stays hidden from everyone. A continuation always pins an id: a source kept before sources had ids is given one, in a write guarded by its record's version, when a conversation imported into it is continued, and an empty id matches nothing. A server on an earlier release rewrites a source without its id, so during a rolling upgrade that source's continuations become hidden from everyone for good (fails closed), and a source it deletes and makes again revives none (upgrade note). Removing or excluding the origin document after it was continued does not hide the continuation or change what its agent is sent: it holds the turns read when it was started.

A continuation is a plain thread: its first turn carries the imported lines in the transcript, and there is no earlier session for it to select, since a turn's conversation is found by its thread, never by what its history says. Tested: the thread record and the source's id on memory and Postgres (pkg/threads, pkg/knowledge), and so is a continuation of a source with no id and an earlier release's rewrite of one (internal/platform); the platform's other continuation tests, its seed, its refusals and who sees it, on memory only (internal/platform); the contract's fields against the Go types (internal/httpapi). The route that starts one and the console's Continue Conversation are not built.

A library skill's supporting file may be up to 1 MiB and its package 256 files and 2 MiB, while SKILL.md, whose body is what a model is asked, stays at 128 KiB. So humagen import skills drafts a skill that ships a large schema or source file, or a tree of many schema files, instead of naming it under failed. A turn's text lists at most 63 of a skill's supporting files, those its instructions name first, and says how many more there are; file_read reads any of them. A skill's revisions hold at most 16 MiB of file bytes together, as 32 revisions of the earlier 512 KiB package did; with paths and text, a stored record or history answer is at most about 41.8 MiB (about 32.9 MiB before), and a skill with large files holds fewer than 32 revisions. A full skill takes no more and cannot be emptied: the import names it under failed and says to go on under another name or scope. A model is told a file is over the 128 KiB file_read returns, and file_read refuses it. A record this release cannot read fails only itself: its scope is listed without it and names it under unreadable. Checked by test on memory and Postgres with generated files, and by an import of a real skill library; not checked in a live run (managed library).

This is forward-only once a package past the earlier bounds (64 files, 128 KiB a file, 512 KiB in all) is drafted: a release before it cannot read that skill's record, and its listing of that skill's whole scope fails with 400 library: invalid, so the console's Library page for that scope and humagen import skills into it fail. Other skills of the scope still resolve by name in runs; the large one cannot be read or used. See upgrading.

The console shows a skill of up to 256 files as the API gives it, but its own checks are the earlier ones: Add File refuses at 64 files with "A skill can contain up to 64 files.", its folder upload stops at 64 files, 128 KiB a file and 512 KiB in all, and its editor takes no typing in a file over 131072 characters. It does not read unreadable, so a skill this server cannot read is missing from its Library page without a word. Read from code, not opened in a browser.

Mail has an existing-account CLI path: Codex apps searched and read one exact unsent non-personal Gmail fixture and its actual CSV attachment through Humagen. Contacts returned no match for an exact audit marker; contact writes are not exposed. Calendar schemas were discovered, but an exact event action still needs approval. The full mail/contacts/calendar requirement remains partial; no event, personal mail or contact was changed.

Cloud documents have an existing-account CLI path: Codex apps retrieve actual Drive revision text, and a separately selected Claude Code agent applies an approved Docs edit with the required revision. A real private-account fixture exercised history fetches, an exact guarded change and an actual stale-token rejection. Coalesced revisions were reported as unknown; exhaustive history, real user documents and OneDrive are not covered.

Account exports have a configured CLI path: an agent on Claude Code runs a shipped script that removes duplicates, reconciles balances and totals months and debts, and drafts a plan whose amounts are all copied from that output, with writes confined to an output folder. Checked on five invented exports with a checker that shares no code with the script; real exports, a bank's own format and the quality of the plan are not covered.

Travel refunds have a configured CLI path: one agent on Claude Code reads a booking and current policy pages and cannot write, and a second writes the request a person approves, under an output folder only. Checked on an invented booking; a real itinerary, an airline's own policy and sending anything are not covered.

Records research has a configured CLI path: an agent on Claude Code builds a chronology from a folder of records, quoting each dated event from its record, lists what is unknown or in conflict, and opens current official pages, with writes confined to an output folder. Checked on six invented records; real records, scans and legal correctness are not covered.

Raster generation has a configured Codex path: a real account-backed image was generated, inspected and revised using its actual pixels, with both PNGs independently opened and the original hash preserved. Checked on Codex CLI 0.167.0 and a generated fixture. Files stay on the CLI host; automatic console publication and image-specific journal events are not covered. Edits can change texture outside the requested region.

Bulk local files have a configured CLI path: an agent on Claude Code surveys a folder on this host in place, writes a plan with a hash for every file, and applies only the part a person approves. Checked on a generated folder of 322 files and 117 MiB; real folders, cloud folders and a console view of the plan are not covered.

Office files have a configured CLI path: an agent on Claude Code edits a .docx run by run and audits .xlsx formulas across saved revisions, in a folder on this host. Checked on generated files, with a part-by-part comparison and Quick Look renders of the document; real templates, Word and Excel, tracked changes and cloud revision history are not covered.

Public-source research has a configured CLI path with built-in tools restricted to WebSearch and WebFetch; the program's user settings, hooks and plugins still load. A real HTTP run executed both and its reported version matched a separate official-feed retrieval. This does not establish authenticated browser access or validate every generated claim.

Native Mac control has a pinned stdio connection in the desktop guide. Exact-window targeting is requested by the prompt; the granted tools can also address other windows or global input. Native image capture, producer-bound references and actions remain unverified. The connector's real discovery and permission checks run through Humagen. The opt-in native fixture test requires an unlocked GUI session; permissions alone do not establish capture or action success.

The response's Worked/tools control has a 44px minimum touch target on coarse pointers. The canonical session browser check measures the visible control and opens/closes Details before its capture.

Browser automation has a pinned external-worker path in the browser guide: explicit MCP grants, inline page snapshots, interactions, selected downloads, and image results. The local connector acceptance uses a real isolated browser. The optional Claude Code profile and connected acceptance helper also exercise an independently launched, signed-in local fixture through an explicit CDP endpoint: actual model screenshot interpretation, the same retained tab, a selected action and exact-byte CSV reads pass at both widths and themes. The CLI's restricted file tools actually refuse an outside-directory Read; capture artifacts and previously verified downloads stay outside that directory. Wire receipts verify inline PNG blocks, not just saved paths. Third-party portal login, SSO/MFA and extension handoff remain unverified. Prompts are not tab authorization boundaries; existing browser downloads follow Chrome settings and need explicit shared file access.

Markdown inline-code fragments retain their own padding and rounded background when they wrap, including long unbroken paths. The session-inline-code browser fixture checks each fragment against its text column at responsive widths.

Multimodal message and MCP content

The browser screenshot workflow has an opt-in real acceptance check: a PNG is uploaded and analyzed without tools, then the same conversation captures and compares an actually changed page. All four desktop/phone and light/dark cases passed on a generated local fixture, with real PNG response blocks before and after the action. This does not establish a third-party portal, every-pixel comparison or the same workflow through the console.

A local media CLI path renders original PDF pages, inspects image pixels and video frames, and retains source offsets for local English ASR and original-clip checks. Generated-fixture acceptance includes a valid 126 MB video and independently verified frame PTS. ASR errors and coarse word boundaries are retained as uncertainty; correlated passes are not manual listening. Real records, long-recording coverage and a native console media timeline are not covered.

People can supply up to five inline uploads, 25 MiB decoded in total, with a session or thread message. The platform sniffs the bytes, stores them through saige's existing attachment intake under the principal's tenant, and retains immutable references in the transcript and run trigger. Existing attachment resolution sends a supported modality to the model and reports unsupported forms explicitly. Console queues retain uploaded bytes through waiting, editing and retry. Text file selection retains its existing 200 KiB picker cap. Posted human messages render retained upload names as shared file references, including after a reload and when another participant reads them. References without names fall back to alternative text or media type; they do not expose storage digests or offer an unimplemented download.

Reviewed workspace and personal MCP tools now return saige's RichTool output: ordered text, image, audio and embedded document/file parts, with cumulative bounds and credential-redacted text. Grant, schema, personal consent and revocation checks apply on the rich path. Text-only callers receive a media summary. Media bytes are not included in debug logs. Native continuation codecs retain inline media; user uploads use the deployment's existing file-blob store. Workers must share that store's directory for cross-host attachment reads.

Evidence: TestAcceptedMCPMediaReachesTheNextModelCall, personal-tool revocation regression, TestUploadedImageReachesModelAndLaterHistory, message batch validation, API schema tests and attachments.test.ts. These are content-path checks, not a claim that OCR, video transcription, a signed-in browser, a hardware connector or an external provider has been configured.

Session persistence now has a shared-state adapter for stable identities, read grants, child admission, usage receipts and an append-only transcript. Thread records can carry one immutable session agent. Runtime and console integration are delivered by subsequent layers.

The platform and presentation sources now share this repository. UI packages use the @humagen/* scope and one pnpm workspace; GitHub presentation belongs to the main Go module. No sibling UI checkout is required.

Releases run the reusable CI workflow before publishing a versioned Go module and GitHub release from main, using the main-only release environment.

Piece State
BigQuery connection preset Built: dedicated Google read-only consent, persisted private setup, scoped ADC/reference fallback, actual metadata verification with count/time, explicit consent renewal and separate publish/withdraw. Managed names and definitions are reserved atomically and survive restart. OAuth metadata only; existing authorized ADC/reference connectors retain bounded SQL. Local race and pure/DOM tests pass; live BigQuery and browser layout remain unverified. See BigQuery connection guide.
Console design review, issues 1 to 7 Implemented: shared agent metric headers, consistent hub page titles, Home toolbar and starter proximity, thread jump clearance, per-agent sandbox links and context percentage deduplication. See design requirements, November 7 review.
Model and effort per message Implemented (DES-067): an agent spec's choices lists the models and reasoning efforts a person may pick; model and effort on a posted message are pinned to its runs under private meta keys and applied per turn where the agent offers them, within the run's ceilings. Effort reaches the provider through orchagent's turn.Spec.Effort. The console's composer picks them; the agent editor does not edit choices yet
Console code loading Implemented: Home loads the shell, the sidebar, the composer and its session line; every other page, both conversation views and the composer's light are read when opened or ahead of use (apps/web/src/pages.ts, lazy.tsx), each with a loading state and a failure with Retry; search and the fork sheet say so in a notice and read again on the next press. The service worker precaches the shell alone and keeps a page's code when it is first opened, and nothing is read ahead for a person saving data. entry-graph.test.ts holds Home to that list and to a source budget. Not covered: Markdown rendering, the agent marks, React and the shared packages/web components still load with Home.
Conversation overview and work controls Implemented: /conversations/{id}/overview composes sandbox, trace, event and GitHub reads in the existing inspector. Overview, Workspace, Context and Activity have visible header controls above the conversation's 3xl breakpoint. Delegated calls share one collapsed transcript disclosure. Route and DOM regressions cover DES-069; live browser verification was unavailable.
Customize and personal tool servers Existing agents, skills, connections and personal server pages are grouped under Customize. Personal MCP clients execute in trusted workers with explicit person_tools grants, reviewed snapshots, change invalidation and write approvals (DES-062); screenshot review remains in CI.
Automations /automations reuses schedule editing and lists GitHub label triggers; bounded installation rules match signed issue, pull request, push and check-run webhooks. Rules reuse client grants, event capabilities and run deduplication. Bot commits are ignored; missing commit author evidence fails closed. Tests and screen definitions cover the builder; CI screens pending.
Save as Artifact and diffs Implemented: POST /api/threads/{id}/artifacts saves an answer, a message (a structured review as its JSON) or a scratchpad through the publication path; retries of the same source, title and content return the existing artifact across processes and restarts, while changed scratchpad content makes a new version; artifact version comparison and file changes share ChangeReview, side by side on a desktop, with line pins for review findings. See conversation-workspace.md.
Native GitHub feedback and fix provenance Implemented: durable reaction IDs confine removals to their original assessments; exact suggestion commits produce reserved system evidence without human ratings or evaluation candidates. Fix PR backlinks use validated session/source-alert identity and the configured public URL. Focused race tests cover replay, ambiguous commits and revoked access; live GitHub writes remain unverified. See GitHub integration.
GitHub review tabs Implemented: Workspace pull, issue and review tabs read bounded GitHub evidence through tenant-authorized clients, display exact-head workflow status and changed-file findings, and preserve their tab references in the address.
Workspace pane Implemented: the Workspace is a tabbed pane beside the conversation (pane.ts: tabs, active, Expand and split in the address; at most 12 tabs), opened from Conversation Settings and from artifacts in the conversation; a full-screen sheet on a phone. See conversation-workspace.md.
Memories by scope Project-chain regression verified: the run's project mounts writable, ancestors mount read-only, and Run.memory plus per-run scope paths agree (TestMemoryMountsKeepOwnProjectWritableAndAncestorsReadOnly). Implemented: Run.memory recorded at memory install and finish on lease and release, GET /api/threads/{id}/memory, and the Workspace's read-only Memories section by conversation, session and message. See conversation-workspace.md.
Conversation scratchpads Implemented: pkg/scratchpads on pkg/state per request (50 per conversation, 80-character names, 256 KiB, versioned), /api/threads/{id}/scratchpads, the Workspace's Scratchpads section, and file_read scratch:<name> for the conversation's agents. See conversation-workspace.md.
Conversation Workspace panel Implemented: the visible Workspace header control opens Sandboxes (session sandbox and a nested sandbox per run, from GET /api/threads/{id}/sandboxes and the bounded Run.sandbox record), Files and Artifacts. Below the conversation's 3xl breakpoint, panel controls move into Conversation Settings. See conversation-workspace.md.
Conversation files, scratchpads and change review Implemented: shared agent/human scratch files with conditional saves, native text editing, Markdown/static HTML previews, unified patch review, contextual composer feedback, immutable publication and editable artifact copies. Host-local scratch expires after seven untouched days. Verified: 739 console tests, full platform/HTTP/artifact/thread race suites, 21 client transport tests, package typechecks, a production build, zero Go lint issues and 27 responsive browser captures. Imported PR patches support contextual review; comments prepare a message without posting an external review. See conversation-workspace.md.
Process roles and leader election (RFC 0004, change 7): server.role / -role (all, api, worker), humagen worker, and one leader per database for the singleton loops Built. all is the default and unchanged. api runs no anchor worker; worker (humagen worker) runs the turns with no listener and no sign-in; both need Postgres stores, refused otherwise. pkg/leader elects with pg_try_advisory_lock on a dedicated connection per schema, checked every 2s and campaigned for again when lost; a winner waits three intervals before it leads so the old term has ended; memory always leads. The reconciler, the cron trigger, inbox retention, email notices, source refresh and catalog crawls run on the leader only; connector flush, the sandbox sweep, the observer and egress stay per process. Platform.Process() reports the role and leadership for a readiness probe; both are logged. Tested: one leader of two electors and of two platforms on one Postgres, failover when the leader's backend is terminated, a schema per deployment, an api platform leaving a run to a worker on a shared queue, a worker that listens on nothing, and serve all-in-one by default. Separate processes still wait on the stores' lock (Limits at scale)
Large rooms (RFC 0004, change 8): a conversation's stream, coalesced reads, per-room rate and per-person runs in flight Built. GET /api/events?thread=<id> follows one conversation through a room per server (pkg/rooms.Hub), which reads its events once for every reader. At most rooms.coalesce_above readers (200) it is sent as the workspace's stream sends it; above, a reader is sent at once what involves them (their messages and mentions, runs they asked for, questions put to them) and the rest as one event: page (RoomPage) every rooms.tail_interval (3s), and the console's conversation reads its newest turns on a page. A room's event stream is answered only after the room's source has subscribed to the conversation, so nothing posted after the answer is missed, and a source that fails before that answers 500. Admission judges rooms.max_runs_per_minute (600 per conversation) and rooms.max_runs_per_person (25 in flight) inside the usage ledger's admission step, counted in memory or, on Postgres, in humagen_room_rate and humagen_room_holds under an advisory lock per key, shared by replicas; refused with 429 Refusal (room_rate, person_runs). Tested: hub delivery and bounds (pkg/rooms), the gate on memory and Postgres with racers in two pools holding both limits exactly, the stream end to end and against the spec (internal/httpapi/rooms_test.go), and the console's page refresh. Load, in process: 100,000 readers at 2,000 events a second deliver 21 frames an event (4,762 times fewer than a broadcast), p99 under 0.1 ms for what involves a reader. See the limits at scale
Project work presentation The console's ProjectWork has explicit loaded-row filters, recoverable reads and paging errors. The newer consolidated navigation hubs and shared renderer font entry remain authoritative. The Storybook previews were removed on October 30, 2026; make screens checks the console itself. See DES-019 and DES-020 in docs/reference/design-requirements.md.
Hierarchical composer context choices The plus menu groups Agents, Projects and Skills in named subpanes. Personal chats keep their internal General default out of the root menu; actual channel choices stay within the selected project. Skills reuse the project-scoped resolver and normal tags, preserving drafts and files until explicit Send. Scoped-loading, keyboard and native phone/desktop regressions cover the flow.
Console agent experience: calls as messages, Stop on the mark, Activity, checkpoints, inline thinking and steps with how long a turn worked, initials and mention profiles Built. DES-024 to DES-036. Agents call agents by default: execution.concurrency is 4, so a caller waits in one place while its callee runs in another. Checked live with real providers
Memory as files (RFC 0004, change 6): pkg/drive versioned trees per person, project and agent, with manifests on pkg/state, content by hash in the blob store, restore, proposals, bounded history and search, and an in-memory cache; pkg/memory notes as notes/<id>.md in those trees; memory_search; /api/memory/files, /content (read, PUT to write or create one file and DELETE to remove one, each against the version it was read at), /history (of the tree, or with file of one file), /restore, /proposals/{id} and /api/memory/search; install into and diff from a run's files (drive.Target, Platform.InstallMemory, Platform.FinishMemory) Built, tested: versions, restore and restart on memory and Postgres (TestVersionsRestoreAndSurviveARestart), one blob per content per tenant (TestContentIsStoredOncePerTenant), a person's tree theirs alone and other tenants' unreachable, proposals and approval, a file write only by whoever may change the tree's notes, with a stale base a conflict (TestWritingAMemoryFileTakesTheRightToChangeTheTree), a file created and deleted by the same right and the same conflict rule, the delete audited (TestCreatingAndDeletingAMemoryFile), one file's history as the versions that changed it (TestAFilesHistoryIsTheVersionsThatChangedIt), the one-time export of old notes and its repeat after a crash (TestNotesAreExportedToFilesOnce), install, diff and a run's end (TestARunsMemoryIsInstalledAndItsChangesKept), and the composed turn byte for byte unchanged (TestTheComposedTurnMatchesItsGolden). Wired into an isolated run's lifecycle (runMemory, internal/platform/memory_lease.go): installed into the instance's own /project and /me when the run leases it, and kept when it is released, before the instance is destroyed: committed to the requester's tree on the installed version, so a file changed meanwhile is a conflict and never overwritten (TestAnIsolatedRunsMemoryIsInstalledOnLeaseAndKeptOnRelease). /project is read only in an instance, so a run there proposes to project or agent memory only through the API. No per-host content cache yet: content comes through the drive's cache in this process. An unisolated run gets no memory files. pkg/memory is still the notes' API for every caller; it reads and writes the files
Health: GET /api/health and the Health tab, each model provider and dependency with recent checks and uptime Built (DES-037). No provider configured reads as down. Anthropic, OpenAI and Gemini are the default providers; a local model server is reached as OpenAI-compatible
Shared web foundation and managed resource browsers Standard shadcn Radix controls share a semantic theme, self-hosted IBM Plex Sans/Mono fonts, scope drawers and file navigation. Red/yellow/green presets are real settings; default red preserves legacy accent choices and agent hues. Glass is limited to chrome (the sidebar on the app frame, sticky tabs, the search modal and the Inspector); content and popovers remain opaque. A change of screen holds the current screen until the next one's reads land, then cross-fades the content area with the View Transitions API; loading states are delayed, layout-stable skeletons (DES-039). The current console has seven navigation entries; Sessions and Alerts replace the former activity and notification hubs, with Watching for alert rules. Skills and Memory use native immutable/scoped resources. Shared settings rows, the Audit calendar and serialized optimistic pin operations are implemented. Automated delivery checks pass; final browser/CI verification remains pending. See DES-015 through DES-018 and managed-library.md.
Consistent action icons and readable inbox recovery Message actions share semantic inline icons, consistent footer sizing and coarse-pointer targets. Inbox alert diagnostics accompanying a failure are disclosed on demand; recovery callout, actions and reference stay grouped, and metadata and related-object labels wrap. Render regressions and native phone/desktop recovery captures cover the reported layout.
Notification views and a reader's own marks Built. Each reader keeps their own marks on any message: read, hidden and deleted, with Unhide and Restore. Views (inbox, unread, hidden, done) are drawn from them on GET /api/inbox; POST /api/inbox/marks marks 1 to 200 messages and POST /api/inbox/read-all the newest 600 unread in a view. Counters kept in the same write as each mark give the Inbox and Hidden counts without reading settled messages; Hidden stops at 1000. A shared message is never removed for others. Tested: per-reader and tenant isolation, bounds, replay, retention and the randomized count-against-a-scan check. An announcement hidden before this change is counted in the Inbox total until it is unhidden or settled
The console on a phone and as an installed app Built. 44px touch targets and 16px fields on a touch screen, checked by make screens; a modal phone drawer (focus, Escape, swipe, inert page); the composer above the on-screen keyboard (viewport.ts); safe areas; the Inspector as a bottom sheet. A service worker (apps/web/src/sw.ts) precaches the shell and serves an offline screen, never caches /api or /auth, never serves an old page, and waits for the person to accept a new version. Safari's keyboard and iOS install need a real device. See DES-040 in docs/reference/design-requirements.md.
Independent sidebar and content scrolling The console is bounded to the dynamic viewport; sidebar lists and page content scroll separately. Sidebar header and account controls remain visible, including in the phone drawer. The sidebar-scroll Chromium screen fixture exercises wheel input and scroll boundaries with long content on phone and desktop. See DES-006 in docs/reference/design-requirements.md.
Project conversation workspace and native deliverables Built in the web console. One left-aligned page title, a draft-preserving project picker with wrapping starters, Share placement, docked Context and People drawers, Activity under More, and conversations grouped by project with the agents that took part. Completed tool work is grouped; technical inputs and outputs remain inspectable, and clarification choices require a separate submit. Saved artifacts open in the conversation with immutable-version selection, DOCX and Markdown text, PPTX slides and notes, CSV and first-sheet XLSX previews, presentation mode, original downloads and version-specific revision prompts. Context shows recorded document origins and import times. See conversation-workspace.md for supported formats, limits and the separate backend work for completed conversation moves and live ingestion.
Indexed workspace search Built. The centered native search modal uses bounded GET /api/discovery?content=true results across destinations, saved messages and answers, current file text and authored local knowledge passages. Retained external source passages are withheld. Read permissions and current placement apply before excerpts are returned. Derived indexes rebuild from saved records. Message/run window is one year; candidates are capped at 1000 per kind, file text at 65536 characters and source buckets at 50. Historical conversation text is not retroactively erased by a source-access check. See DES-012 in design requirements and sources.md.
Company agents, personal projects, movable conversations, announcement banner and project/agent finder Company root homes and durable human personal-project provisioning are implemented in the project store and GET /api/me, with owner confinement ahead of inherited ownership and memory/Postgres replay and race tests. Company homes preserve existing enable/allow behavior. Backend publication previews now bind explicit confirmation to current contents and destination versions; completed work moves with immutable accounting, scoped audit attempts and atomic placement history. Active, waiting and externally delivered work stays put. Operational run/artifact/inbox/count/stream projections follow current placement and remove former private provenance. Raw private-source and retained operational-contract publication requires a reviewed summary copy, which creates only explicit human text in a new shared conversation. The original stays private. Company welcome is a retained idempotent announcement; Home banner and the read-confined discovery API are implemented. Agent/project discovery lives inside the new-conversation composer picker, preserving drafts and attachments; existing conversations keep their fixed project. New expert tags/completions and prompt injection are retired, with actionable config diagnostics and retained human-question compatibility. Project history IDs/cursors are opaque and project-scoped; see company-workspace.md.
Reviewed agent setup Backend implemented: bounded owner-confined durable setup records, inactive registry creation, resumable configuration, exact owner/revision test capability through the real runtime, native tool approval and completed-test activation. Public agent creation shares the name reservation boundary. Memory/Postgres restart, partial-failure, concurrent-creation and native OpenAI adapter approval regressions pass. The mounted create wizard uses real provider/model choices, explicit grants, recorded native approvals, resumable inactive drafts and completed-model-test activation. Exact published default skills and final screenshot acceptance are the remaining upper integration work.
Initiatives, bounded discovery and safe project forks File-defined atomic project templates and coordination-only initiative scope are implemented. Initiative Overview shows read-confined descendant activity, reader needs, approved unexpired typed decisions/risks and 30-day run counts. Project forks stage all copied resources behind a central deny gate, publish atomically, retain private resumable plans and optionally capture passive read-only archives. Source-link rules are copied disabled; original source access remains required. Bounded global discovery finds readable projects, agents and conversations. Shared host wiring and final screenshot verification are completed in the upper UI stack. Project-fork operations use a bounded lock pool separate from conversation archive locks; deterministic colliding-ID regressions cover memory and Postgres. Cross-project execution remains denied pending its explicit design question.
internal/wire: the one seam onto fiber's run model Built. Only internal/wire reads or writes a trigger's request (text, actor, context) and the connector meta keys, decodes event bodies, and reaches fiber's definitions; pkg/call builds a child through wire.NewEvent, and the platform reads definitions through Platform.Catalog(). TestSeam fails on a new read elsewhere, of orchagent/flow/definition outside pkg/agents and internal/legacy, and of orchagent/flow/event/legacy outside internal/legacy
orchagent: fiber, anchor and playscape as one dependency Built. Humagen depends on github.com/urmzd/orchagent and has no fiber/ directory: fiber is orchagent/flow (fiber/pkg/durable is flow/runschema), anchor is orchagent/durable, playscape is orchagent/sandbox. The run ledger and queue are opened only through runschema.Open, which maps durable's Postgres adapters onto the fiber_runs, fiber_run_records and fiber_run_queue tables, so no table is renamed. Its errors start durable:, sandbox: and flow:. Its own test variable is FLOW_POSTGRES_TEST_URL
fiber folded in: Humagen on fiber's event union Built. fiber now lives in github.com/urmzd/orchagent/flow (see the orchagent row) and github.com/urmzd/fiber is gone from go.mod. One event.Envelope replaces the tag and the run event: a trigger is message.posted.v1 (or a connector's own type), Humagen sets its Agent, and its meta is the request's context. The bus is subscribed per tenant (Platform.RunSubscription), egress delivers a run's events to the sink of its channel's scheme, and runtime.AcceptOwn keeps run ids as before. Old shapes are read only in internal/legacy: a run row's tag (TestARunRowWrittenBeforeTheUnionIsReadAsItsEvent), a schedule's Meta, and an old reader's SSE topic and journal kind (legacy.Topic, legacy.KindSelector). The composed turn is pinned byte for byte, and matched the version before (TestTheComposedTurnMatchesItsGolden); a call key joins its run however often it is made (TestTheSameCallKeyJoinsTheSameRun). A Slack message names an agent by a bot mention, or by a plain @name the client may route to. Not run against Postgres here
The API on the event union: api/openapi.yaml, @humagen/client, packages/adapter, the console and the Slack app Built. The event stream, listRunEvents and the run manifest send the envelope with data as inline JSON (platform.APIEvent), never base64. RunEvent is a oneOf told apart by type, one variant per type in fiber's catalog, and UnknownEvent is the documented fallback; TestSpecSchemasHaveTheFieldsTheGoTypesMarshal derives the mapping from event.Types() and checks each body against its Go type, and TestEventUnionParityCatchesAMissingVariant proves a missing variant fails. GET /api/events takes channel, type and run, defaults to the run family, refuses any other family or a control channel, and reads the old topic through internal/legacy (TestLegacyTopicParam, TestSSEDefaultDenyAcrossTenants). The journal filters by type. The adapter takes the generated RunEvent, so a contract change fails its typecheck; a type it does not know gives nothing. The console and the Slack app are on the union: the console's list follows the run state types (runStateTypes) and reads agents again through the agents API on every (re)connect, a run's page follows it by run, and Analytics asks the journal by type prefix (type is repeatable); the Slack app reads frames as RunEvent and InboxNotice, hands each run's events on once by seq, follows a run by run, and reads its inbox with inbox=true, which sends notices alone (TestSSEInboxOnly)
pkg/agents: each tenant's saige agent definitions on pkg/state, and the one-time move from fiber's registry Built and wired in: the platform's agents are pkg/agents, resolved by fiber's definition.Resolver, and platform.OpenPostgres runs the move at start. pkg/agents is a definition.Source held to definitiontest on memory and Postgres. legacy.ConvertAgents moves fiber_agents and fiber_agent_revisions through definition.FromAgentSpec once, behind a state marker, in revision order, keeping who wrote each and when; an agent that cannot be moved is disabled and kept in the report (legacy.AgentConversionOf), and a platform agent that cannot be moved fails the move. wire.DefinitionCatalog reads the store as an AgentCatalog
Event union (orchagent/flow/event): one envelope, a sealed body per type, Unknown for a type this build does not know, and one catalog of decoder, renderer, sensitivity and opt-in per type Built. TestCatalogComplete fails on a type with no renderer, TestUnknownKeepsBytes and TestDecodeRejectsMalformedKnown hold the decode rules, and TestSpecSchemasHaveTheFieldsTheGoTypesMarshal holds api/openapi.yaml to the catalog
Channel bus (orchagent/flow/bus): one bus by tenant, channel and type prefix, with hops and at-least-once delivery Built: memory and Postgres, held to bustest (TestEmptySubscriptionMatchesNothing, TestRootDoesNotSeeControl). Humagen subscribes per tenant (Platform.RunSubscription) and refuses a control channel on the API. fiber's membership and dispatch (TestSelfOutputNeverWakesSelf, TestHopLimitDrops, TestRedeliveryJoinsRun) are built and not wired in: Humagen chooses agents with pkg/join. New bus tables; old rows age out in 24 hours. Postgres runs are CI's integration job, not run here
Definitions: saige .agent.md plus a policy, pinned per run Built. A run pins name, version, digest, sub-agent versions and policy hash, and fails terminally when any moved (TestAPinnedRevisionWhoseHashMovedFailsTerminally, TestVerifyFailsClosedOnEmptyDigest). A spec's agent may be an .agent.md file with a policy (TestAnAgentMdFileLandsWithItsPolicy). Runs under the v1 activity names fail terminally
Runtime seam (orchagent/flow/turn): one turn of a pinned definition for an input event, streaming catalog bodies. turn/native wraps saige, turn/sandbox puts any Runtime in playscape Built and held to runtimetest. humagen.WithRuntime (platform.Config.Runtime) replaces the native turn inside the same sandbox (TestAConfiguredRuntimeRunsTheTurn)
Durable agent operations Built: durable versioned assignments and handoff contracts, effective workspace/agent/setup pause at admission, tighten-only action policy with safe inherited provenance, native durable approvals and bounded read-confined network APIs. Reviewed deadline corrections retain the same ledger run; bounded native inbox reminders survive restart without repeating or resuming work. An assignment may carry done checks (contains, does not contain, is exactly, matches): an answer that fails one is held, and the same conversation is continued up to a cap, across a restart. Console controls, policy editor, assignments and network components use the real APIs; an assignment's card lists its checks and how often it was continued, and its recorded run opens the run that answered, with the answer. Global navigation, source-health integration and screenshot states are completed by the corresponding stack layers. See agent-operations.md for semantics and verification.

The pieces below are listed, not tabled: their names hold test names and routes too long for a table column. Each is followed by its state.

  • Agentic workspace and control plane: standing assignments, per-action autonomy, pause, agent network, context health and access modes, skills and memory library, initiatives, forking, integration auto-linking
  • Prepared design in assets/control-plane (the clickable boards were removed on October 30, 2026), with a gap analysis against this code. Not implemented beyond what the gap analysis marks as built.
  • Renamed from warp to Humagen: module github.com/urmzd/humagen, command humagen, chart deploy/helm/humagen, scope @humagen, settings HUMAGEN_*, api_version: humagen/v1, scopes humagen:, groups humagen-*
  • Built. Every name people typed before still works, each with a note at start, through internal/legacy and the apps' legacy.ts; every name stored data or a running deployment depends on is kept, each pinned by a test; upgrading-from-warp.md lists both. The chart and humagen deploy refuse an image from before 0.21.0, which cannot read the spec they write. Tested: internal/legacy, TestWhatWasStoredBeforeTheRenameSurvivesARestart (memory and Postgres), TestPostgresReadsWhatAnOlderReleaseWrote, the deploy tests in internal/app/rename_deploy_test.go, deploy/helm/check.sh, TestNoNewOldName. The default Postgres upgrade also passes on a live kind cluster with Helm and Flux, retaining the Deployment, PVC and Secrets (rename verification). Live rejection without nameOverride was not exercised. Helm 4 memory-store reuse-values now omits null store entries without weakening strict spec validation (issue #62); both memory and default Postgres upgrades pass the live Deployment, PVC, Secret and pod checks
  • Slack feedback, uploads, skills, canvases and connection controls
  • Built: like and dislike open the shared feedback modal; run references, ratings, reasons and comments write through the state backend; prompt, answer and conversation context are retrieved from the existing run and thread records and can be collected through a run-scoped paginated API (GET /api/runs/{id}/feedback), which names each rater by handle and by name, marks the reader's own rating, never shows a subject, and pages by a number in the order ratings were first given (those kept before come first, in the order last rated), never by a subject (TestFeedbackNamesRatersAndNeverShowsAnAddress, TestFeedbackPagesByANumberThatSurvivesARestart). Mapped people's uploads are read from the actual Slack message and resolved through Fiber's attachment pipeline. /skill lists and invokes the client's configured commands, also registered dynamically in code channels. /agent canvas RUN_ID publishes a finished answer only from its own channel, after reading it as the mapped person. /agent connections shows private status and connects or disconnects their own allowed credential references. Tested with fake Slack, the HTTP contract and tenant/person confinement tests. Live Slack validation is checked separately by CI.
  • GitHub and Slack integrations: signed webhook ingress, tenant-bound tools and delivery through Invoke
  • Built, tested with simulated APIs. Durable versioned event/action controls tighten actual installations at execution. Slack bridges support passive inbound, outcomes-only and two-way directions, with server checks withholding private context and native-host checks excluding Activity/source metadata. Memory/Postgres replay, contract, policy and native-host regressions cover these boundaries. Live external delivery remains unverified.
  • pkg/clients: a workspace's Slack apps and GitHub installations as records, each with an identity, an allow-list of agents, options and an enabled flag. Several per surface per workspace, and several workspaces per process. See clients
  • Built behind clients.Store, in memory or kept with -state=postgres, where a restart starts every enabled client again. A client the environment configures is not kept: it is made again at every start. A client saved through the API names only agents that exist and that the writer may read, besides those its record already holds (TestAClientNamesAgentsThatExist). Tested with two clients in one workspace and two workspaces in one team
  • Routing a webhook to a client: offered to the clients whose identity it states, taken by the first whose own secret verifies the bytes. 404 for unknown or disabled, 401 for a signature no offered client accepts
  • Built. One surface per address scheme sits in fiber's registry and fans in and out to the clients behind it
  • Client secrets: written as a value or an env:HUMAGEN_* reference, never returned or logged
  • Built behind clients.Secrets. In memory, or kept with -state=postgres, where a value is stored as written: guard the database as you would the secrets. A reference keeps no value
  • Secret references are default deny per tenant: read only for a variable the operator listed for that tenant with -secret-refs, checked where the secret is read, refused the same way whatever the reason
  • Built, tested across tenants and against a record written straight into the store
  • Client limits: max_clients and max_clients_per_surface on the tenant's policy, and a client policy scope for runs, concurrency, spend and tokens
  • Built on pkg/policy and admission (usage.Ledger.Admit). Storage per client is not
  • A default client per surface from the HUMAGEN_SLACK_* and HUMAGEN_GITHUB_* variables
  • Built. Managed by the environment and read-only in the API
  • Client API: /api/clients create, read, replace, delete, behind clients:read and clients:write
  • Built, tested across tenants
  • Console for clients: Settings, Connections lists them, and an admin can create, disable or remove one
  • Built. The Slack and GitHub connection form writes through the existing clients API, accepts write-only credentials or allowed environment references, and grants no agent reach by default. Creation, refusal, permission and credential-clearing behavior is covered by console DOM tests. Phone and desktop screen checks cover the forms, pending requests and refusal. Limits remain API calls. External delivery still needs a live trial. See design requirements.
  • Replay with an agent
  • Completed turns offer an agent picker with AgentMark. The existing Fork and message APIs preserve passive history through the selected turn and resend its prompt to the chosen agent. Unit and DOM regressions cover routing, saved branch points and refusal; conversation-replay-agent is registered for CI screen checks (DES-058).
  • Conversation message metadata and exact timestamps
  • Human messages and announcements expose their recorded local date, time and timezone on hover, focus and tap, with Escape dismissal. Touched conversation and source metadata use spacing instead of separator dots. Console DOM tests cover timestamp access and mixed pointer/focus behavior; phone and desktop captures check that the tooltip stays inside the viewport. Native conversation fork storage, bounded read-only history, immutable lineage, source-chain read checks, source selection and explicit passive bring-back are tested on memory and Postgres. Fork and People inspectors and bounded project switching have DOM and route tests; shared message action wiring is tracked in design requirements.
  • Project configuration forks
  • Bounded durable private plans copy visible project structure, agent configurations with reserved homes, detached channels, skills and explicitly selected confirmed memory/sources. Pending resources are absent from normal reads and denied execution, including governance reads; one project-store transaction publishes the prepared subtree. Memory/Postgres failure, restart, source revocation and concurrent-reader tests cover the gate. Disabled integration rules replay from the captured plan, and optional conversation archives retain passive text only, remain source-confined, and cannot accept messages or runs. Rollups remain tracked in the implementation matrix. File-defined templates atomically create channel and skill configuration; the Initiative template provides an optional coordination parent whose agents cannot execute directly in descendants. Template and initiative scope tests cover memory and Postgres.
  • Minting GitHub installation tokens, Slack OAuth installation
  • GitHub: built. A client whose token is a GitHub App private key PEM, with identity.app_id and identity.installation, signs an RS256 App JWT and exchanges it for an installation token, cached until two minutes before it expires (pkg/integrations/github/app_token.go, on orchagent's HTTPAPI); a key without its app or installation is refused when the client is created. Tested against a fake GitHub (TestAppTokenSourceMintsAndRefreshesInstallationTokens) and through CreateClient. Not live-validated. Slack OAuth installation creates disabled, empty-grant managed clients after verified team/app consent; per-team encrypted tokens refresh before API/file requests. Offline native installation tests pass; live Slack OAuth remains unverified
  • GitHub auto-label and per-commit reviews, PR guides, explicit writer-authorized fix commits and workflow reruns
  • Built in pkg/integrations/github, on fiber API capabilities. Rendering in internal/presentation/github
  • Structured reviews in the console and Slack, with cited code in place
  • Built. A humagen.github.review.v1 answer is a review card on both surfaces (ReviewCard, the Review primitive); evidence pinned to a commit opens its lines through GET /api/github/source, read by the workspace's GitHub client. See DES-046
  • Slack agent-session status and code-channel command policy
  • Built in pkg/integrations/slack. Signed command decoding and optional AgentAPI in fiber. Not live-validated
  • Slack stop button: agent_session_stopped asks the runtime to stop the runs answering in that session, confirms in the thread and settles the status. The run's message keeps its partial answer, marked stopped
  • Built, tested end to end against the fake with a scripted model whose call is shown to be cancelled. The session-to-run map is in memory and per client: one app's button cannot stop a run another app raised. Not live-validated
  • Slack app (apps/slack): Socket Mode, a client of the HTTP API as a machine. DMs, mentions, /agent, shortcuts, Home, native streaming, session status, stop, inbox items in the run's thread. A thread's conversation is derived from the thread, so a restart loses neither it nor deduplication. Name, tagline, disclaimer and suggested prompts come from a checked branding file (SLACK_BRANDING). Streams a crashed process left open are closed at the next start from a file journal. A silent or slept-through socket is replaced, with backoff, and the app exits non-zero after repeated failures. A person the app's client maps posts as themselves into the Humagen thread their Slack thread is (POST /api/threads with a surface): the platform reads the tags and files it, the people's messages since the app was last asked there go first as their own messages, posted only, and a message posted before starts nothing again. Anyone else asks through the app, as before, with people's messages folded into the run's text, except in a bound channel: that is a project's channel, so they are told to ask an admin to connect their Slack account and Humagen is not asked (in a bound channel, someone the client maps to nobody is told to be connected). The Home tab is the shared Home (homeView) for a person the app's client maps, read as them through the client (act_as on GET /api/inbox and GET /api/projects): at most five that need them, newest first, with the rest counted as the inbox's open counts them, an agent's draft waiting on them as an owner among them and a posted announcement never; five posted announcements of their projects, unread first; and eight of the projects that name them (mine on each project 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 above it, and access only through * or only through projects:govern does not count), where something happened most recently first and then in tree order, archived ones left out and the rest counted in "N more in Projects", each opening in the console when the app has its address (HUMAGEN_PUBLIC_URL). Without it, Review sends what needs them to their messages with the app, where a press is theirs, done for them through the client, with no Snooze or Dismiss since Humagen does those only as the caller, 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 them in their messages with the app, Build an Agent tagging @humagen-builder where the client reaches it, and Search Context opens the console. It shows no access or connections, which it cannot know. Someone the client maps to nobody keeps the mailbox
  • Built, tested with fakes for Slack and Humagen (history.test.ts, announce.test.tsx, dm.test.tsx, home.test.tsx), What's new against the console's Home, and Needs you, its rows and its total, What's new and Your projects the same on both renderers (parity.test.tsx), the projects list read for a person against the server on memory and Postgres (TestAClientsMachineListsAPersonsProjectsAsTheySeeThem), which of them name the person (TestNamedIsWhereAnEntryNamesTheReader, and TestAPersonsOwnProjectsAreTheOnesThatNameThem on memory and Postgres), and against a real server with a fake Slack. A run is recorded as the Slack person's when the app's client maps them (act_as), and acts for them, so a tool that acts as a person uses theirs; else it is the app's, and acts for nobody. Asking about someone else's message with the shortcut is the app's, for nobody, since those words are the whole request, and in a bound channel it is refused, since only a person's own words are posted there. A message that starts several runs is followed for the first; the others answer in Humagen. Not live-validated
  • Questions in Slack: a run's question shows in its thread with Humagen's approval and choice cards and live buttons, answered through Humagen as the Slack person the app's client maps (slack.machine, slack.people), refused for anyone unmapped without asking, and settled in place
  • Built, tested with fakes for Slack and Humagen. A reply to a question in the inbox, and to a mention in a person's direct messages, is typed in the reply modal (replyModal), sent as the person through the client; a mention's reply goes through their inbox, so it posts in the thread as a human message and starts no run, whatever the thread's default, and a viewer who was tagged replies too (TestASlackReplyToAMentionStartsNoRun); Something Else on a run's own card still points to the console. Not live-validated, and not run against a real server: no model that asks is wired into test:server
  • Slack and GitHub coworking in projects
  • Built. A project's owners bind a channel to a Slack channel of a Slack client (slack {client, channel} on the channel, in the API or the Platform document; one Slack channel bound once, archiving unbinds it; GET /api/clients/{id}/bindings); binding one or moving a binding also takes clients:write, so no owner captures a Slack channel the client's admins did not give the project (TestBindingASlackChannelTakesTheClientsAdmin). A client's home is a project and one of its channels, shown only to those who may read that project: a change that names no home keeps one the caller is not shown (TestAClientsHomeIsShownOnlyWhereTheCallerMayReadIt). The client's machine posts a mapped person's Slack message with its surface: one Slack thread is one Humagen thread, found by its surface or started and filed from the binding, shared in a bound channel and otherwise in the home, private for a direct message or the assistant pane; the text is read in the one grammar, each message ts is posted once, the client's default answers outside a bound channel, and its allow-list holds, the agents asked for a default of * included, there and on every message its machine posts for a person in any other thread (TestAClientsListHoldsWhereverItPostsForAPerson). The machine reads its own surface's threads wherever they are filed. An in-process connector's run is filed by the same binding (stamp), and runs.ProjectOf believes it for slack and github; it acts for the person the team maps the Slack user to only if they may start it there, as act_as asks (the policy grants their subject runs:write, and they are a member of the project), and is not started otherwise, nor for someone mapped to nobody in a bound channel (TestAConnectorsRunIsHeldToThePersonItActsFor); a Slack mention that names no agent is answered as one in a thread there would be, by the bound channel's chain in a bound channel and by the client's default first in its home (TestAConnectorsRunIsFiledByItsBinding). Announcements of a project whose general channel is bound are posted there top-level once, with a delivery receipt, the record of the post; drafts never reach a channel, and a withdrawn one's post says only that it was withdrawn. 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 a client's machine is shown its own receipts and nobody else any (TestAProjectsInboxShowsOnlyTheReadersOwnReceipts), edits a post whose announcement changed since its receipt and records the same post again, which moves the receipt's at on only after a change (TestARereportedPostMovesItsReceiptOnOnlyAfterAChange, on memory and Postgres), and posts, oldest first, an open one with no receipt from the last 24 hours and announced no earlier than the Slack channel was bound (bound_at on the channel and on GET /api/clients/{id}/bindings, kept while the binding holds, TestABindingSaysWhenItWasMade). So an edit, a withdrawal, a restart or a reconnect updates that post, release notes posted at a start after the binding reach a bound workspace general, and a notice during a catch-up posts nothing twice, as each announcement is looked at one look at a time and read afresh, receipt and all; a look asked for during one that fails still runs. The app does this only when its client names its credential as the machine, the only one shown the receipts, and a catch-up that could not read Humagen is tried again with backoff until one finishes, skipping a project the machine may not read; an announcement a notice names is posted only as a catch-up would post it, and the app reads it once more after each receipt, so a change between an edit and its receipt is shown too (announce.test.tsx, units.test.ts, humagen.server.test.ts). Not caught up on: a change to an announcement older than a bound project's newest 50 made while the app was away, whose post keeps its words, withdrawn ones included; old posts in a Slack channel no longer bound; and a post whose receipt Humagen did not take is remembered only by the process that made it. A message's history shows a receipt (delivered) to its client's machine alone (TestOnlyAClientsMachineRecordsAndSeesItsDeliveries). A reply in an announcement's Slack thread, the one that mentions the app since Slack delivers no other in a channel, starts a shared thread in the bound channel, found by the post's surface: the platform finds the announcement by the receipt at that channel and ts (inbox.ByDelivery, rebuilt on replay), and the thread names it (announcement). Its turns, and the room each run is sent, start with the announcement as it stands, from the person who posted it, the agent a schedule ran, or Humagen itself for release notes (kind: system, sent to a run as humagen (system)), never from the replier, who posts the reply as their own message, read in the one grammar and answered by the channel's chain; what it says tags nobody, a later reply finds the same thread, and a withdrawn one then says only that. It seeds only a thread the Slack channel's binding files in its own project, so only those who see that project read the thread, and the announcement is then part of the thread and of its runs' input, read with them under runs:read, not projects:read. In that channel a reply under one withdrawn before anyone replied, or under a draft, starts nothing (410), and the app says so; after the Slack channel is bound to another project, or unbound, a reply under an old post starts a thread where it is now filed, as any other, open or withdrawn, and nobody there is told what became of it (TestAReplyToAnAnnouncementsSlackPostStartsAThreadSeededWithIt, TestAReplyToAWithdrawnAnnouncementOrADraftStartsNothing, TestAnAnnouncementSeedsOnlyAThreadInItsOwnProject, TestAnAnnouncementsThreadIsFoundByItsPostAfterARestart with -state=postgres, TestAnAnnouncementsSlackThreadIsReadAsTheSpecSays, TestAReplyToReleaseNotesStartsAThreadSeededWithThem, TestReleaseNotesSeedAThreadAsTheSpecSays, announce.test.tsx, room.dom.test.tsx). The client's machine is told of them wherever it may see the project, as a viewer too, and a members-only project's only where it names the machine among its members (TestAMachineIsToldOfAnnouncementsWhereItsClientIsBound, TestAnAnnouncementWhereTheAppOnlyViewsKeepsItsReceipt). The event stream tells a client's machine of a mention or a question addressed to a person it maps, by subject or by a role they hold, once for each such person and at most 20, and for whom (TestAMachineHearsOfAnExpertQuestionForEveryoneItMapsInTheRole); the app reads it for them (act_as), posts it to their direct messages with Open Thread and Reply, unless they are already in the app's own Slack thread it was raised in (they wrote there, or were mentioned there the Slack way, read with conversations.replies), and keeps each person's current. A tag by handle, an invitation into a private thread and an expert asked by a run ping nobody in Slack, so they reach the person's direct messages (dm.test.tsx). A reply in the thread settles the mention of its poster. Tested in pkg/projects, pkg/threads, the platform (surface_threads_test.go), the contract and the Slack app. GitHub comments follow the same addressing: a comment's @agent and auto_labels tag, and one that mentions the app's own login (github.login) and names no agent reaches stamp untagged and is answered as an untagged Slack message outside a bound channel is, by the client's default and then its home channel's chain, under its allow-list, filed in the client's home for nobody, with nothing run or posted when no default answers; it posts no PR guide (TestAGitHubCommentToTheAppIsTheClientsDefaults, in memory and with Postgres, TestAnUntaggedGitHubCommentFallsToTheHomesChain, TestAnUntaggedGitHubCommentNobodyMayAnswerStartsNothing, driven by a fake connector's tag in the shape fiber's connector raises, and TestACommentWhoseAgentIsResolvedLaterPostsNoGuide). fiber's GitHub connector raises such a comment (github.Config with Login and DefaultAgent), and through it a signed comment that mentions the app and names no agent is answered by the client's default, while one that mentions neither the app nor an agent starts nothing (TestASignedCommentToTheAppIsAnsweredByTheClientsDefault)
  • packages/adapter: the shared platform-to-UI adapter, run events and inbox messages to Humagen's model and Humagen actions back to platform calls, shared by the console and the Slack app
  • Built. A parity test renders one adapted state with both renderers
  • Slack app routing: a message that names no agent, with no client or app default, is sent with no agent, so the platform's default chain decides. The app picks nothing itself, and when the platform answers 409 it says "Tag an agent, for example @helper". Where the default is *, the platform asks the agents available there whether to join, only those the client may route to, and each that joins answers in the same Slack thread; @auto in a message tags nobody
  • Built, tested with fakes. pnpm validate:slack was not run for this change: its checks call slack.com, which this environment could not reach
  • pkg/call: edge, modes, depth, fan-out and lease checks
  • Built, tested
  • pkg/runs: run index, call tree, statistics, and what each project holds (its conversations, the runs in flight in them and when one last changed), counted as runs are recorded and change rather than scanned
  • Built. Read and written per request (runs.v2): every change is written before it is reported, at the version it read, nothing is written behind, and a run's usage tally is kept with the run, so a report folded twice counts once
  • internal/platform: fiber composed, Invoke, Call with the spawn allowlist
  • Built, tested
  • Ledger reconciler: ends runs whose retries ran out with no final event
  • Built, tested
  • pkg/auth: OIDC sign-in, machine tokens, roles and scopes
  • Built, tested against an in-process issuer
  • Okta SSO and Tailscale Serve identity
  • Okta uses OIDC without forcing reauthentication. -auth=tailscale trusts Serve on loopback, maps namespaced subjects through the authorization policy, and needs no application sign-in
  • pkg/authz: a policy language mapping claims to roles and roles to permissions, with Explain
  • Built. The built-in policy declares the four roles. HUMAGEN_AUTHZ_POLICY loads a file
  • pkg/auth/mockidp: a loopback-only development identity provider, -auth=mock
  • Built. Tokens go through the real verifier
  • Pull requests board and list
  • Visible recent agent reviews, URL-backed filters and conversation pull-tab links; endpoint race tests and DOM coverage, screens registered for CI
  • HTTP API, sessions, event stream
  • Built, tested
  • Managed BigQuery setup and consent renewal
  • Private immutable definitions, explicit dedicated OAuth binding, scoped ADC/reference fallback, per-use authorization and metadata verification implemented. Race/API tests and actual PostgreSQL managed-name/cross-process tests pass. OAuth is metadata-only. See BigQuery setup.
  • Encrypted service authorization and managed Slack/GitHub installation
  • Backend and API implemented with tenant/person consent, empty installation grants, persistent health and confined connection detail. Offline native-provider and full HTTP response/spec race tests pass. Live provider consent and the console follow in separate layers. See connections.
  • API contract: api/openapi.yaml, OpenAPI 3.2, every route with its permission and a typed event union. Tests check it against the registered routes, the permissions the server enforces, the Go types' JSON fields, and real responses and the event stream. See API
  • Built. Webhook ingress under /connectors is left out on purpose
  • packages/client: @humagen/client, generated by oag from the contract, with a hand-written layer for auth, decoded events and downloads
  • Built, tested against an in-process server and run once against make dev. No surface uses it yet: the console still has its own apps/web/src/api.ts
  • Schedules through fiber's cron trigger: pause, run now, next fires, history
  • Built. Kept with -state=postgres, paused or not. A clock occurrence runs the agent its schedule names, tested through the cron connector's own tick (TestAClockTickStartsARunOfTheSchedulesAgent); one that cannot start a run is logged as an error and tells nobody else.
  • Each scheduled run is a session in its project (internal/platform/schedule_sessions.go): once admitted, a cron occurrence or a run-now opens a session keyed (schedule://<name>, its agent, the occurrence), filed in the schedule's project, read by the project's readers and belonging to who wrote what the schedule runs; the same occurrence again finds the same session, a refused one leaves none, and a thread the tag names is never believed. GET /api/sessions?parent=schedule://<name> lists a schedule's runs, ?project=~ is the workspace itself, and GET /api/schedules?project= lists the schedules filed in one project. A project's view says its visibility (private, shared or workspace)
  • Built, tested (TestEachScheduledRunIsASessionInItsProject, TestAScheduledRunNamesNoThreadOfItsOwnAndARefusalLeavesNoSession, TestVisibilitySaysHowWidelyAProjectIsRead, the routes in the contract test). A session that cannot be opened leaves the run its own conversation, as before, and logs why
  • Editing a schedule (PUT /api/schedules/{name}): expression, agent, text, project and a description, keeping its pause state, creator and history. The edit is checked in full before it replaces anything, and an edited schedule starts afresh rather than catching up on its new expression
  • Built, tested
  • pkg/journal: event log, query, run traces
  • Built, 100,000 events per tenant. Read and written per request: an event is kept by time and by run, once by run and sequence, and nothing is written behind
  • pkg/alerts: rules on run failure, failure rate and duration
  • Built. Kept with -state=postgres: rules, alerts, numbering and cooldowns
  • Canonical session console and audit follow-on
  • Implemented: seven-entry navigation, session Details, persistent feedback, builder previews and health, source-anchored alerts, explicit continuation, readable context names, priority notification preferences and visible recovery paths. New/Search stay outside sidebar scrolling; unknown paths stay Not found. Automated behavior is covered by console/native suites; responsive screenshots, live providers and measured browser request totals remain unverified. See DES-070 through DES-074.
  • Session alert delivery
  • Built. Canonical priority controls native and opt-in email delivery; reads never resolve attention. Authoritative question outcomes settle projected alerts, and session lists prioritize visible open attention. Confirmed credential rejection creates a private owner reconnect session with replica-safe dedupe and transport repair. Native Slack use, MCP and health rejection reports compare the exact consent revision and token; GitHub App mint rejection uses a verified current-owner receipt with disconnect and reconnect fences. Fake-provider race tests cover these boundaries; live consent remains unverified. See session alerts.
  • Configurable alert rules: replace (PUT /api/alert-rules/{name}), description, pause, project scope beside agent scope, a cooldown, a spend kind over a window in micro-USD, and notify, which addresses the inbox message to subjects and role:<name> entries among the people who may read alerts
  • Built, tested. Notify names people by subject, not by email
  • pkg/knowledge: sources, documents, BM25 search, per-document exclusion, saved variants
  • Built. Lexical by default; with knowledge.embedder (hashing, OpenAI-compatible or Vertex AI) passages also get vectors in the background, kept beside them, and search fuses vector and BM25 rankings over the same permitted passages (RFC 0005, change 1). Kept with -state=postgres, passages included. Native scoped source creation saves its refresh cadence atomically; bounded selection, last-good copies, frozen versions, freshness stops and current-policy scheduled refresh share the durable lifecycle. External retained text and per-file metadata are withheld pending current-reader file authorization. Explicit unfrozen provider queries use the reader's current reference and selected resources, never cached fallback; external saved variants and frozen-snapshot queries fail closed. Native evidence records source authority before model input; external, unknown and missing-source citation projections are withheld without network calls. Authored manual collections keep native search and curation. Rule previews and observed relationships remain bounded and permission-confined. Source-access and full Go race regressions pass; final browser/CI verification is pending. See sources.md.
  • pkg/catalog: the catalog of what exists in connected systems (tables, columns, descriptions; never data) (RFC 0005, change 2)
  • Store built, tested: connectors per tenant, a crawl replaces a connector's entries in one write (TestReplaceIsWholeOrNothing), hybrid search with the same embedder as pkg/knowledge, vectors kept across a recrawl when an entry's text is unchanged, the owner sees entries by default and the project's members only while published, with who published or withdrew and when (TestPublishAndWithdrawAreRecorded). pkg/catalog/bigquery, the first connector kind: a crawl lists a project's datasets and tables with schemas and stats, all or nothing (TestCrawlFailsWhole); a query is dry-run first and refused before it runs unless it is a single SELECT, inside the connector's datasets and under its byte cap, then runs with that cap as BigQuery's maximum bytes billed and a row and size bound (TestQueryIsRefusedBeforeItRuns). The credential is a reference to a service account key, or Application Default Credentials. Wired: connectors in a Platform document declare each tenant's connectors, crawled on their refresh cadence or on the owner's POST /api/catalog/connectors/{name}/crawl; GET /api/catalog browses and searches what the caller sees; publish and withdraw are owner routes, withdraw also open to whoever governs the workspace. catalog_search shows a run published entries everyone its answer reaches may see, and the owner's own only in their private conversation (TestCatalogSearchFollowsTheAudience); catalog_query runs with the connector's credential, so only for its owner in their private conversation (TestCatalogQueryIsTheOwnersAlone). Built: Snowflake catalog/live SQL and GCS/S3 metadata catalog and per-reader collected text (changes 3 and 4). Library > Catalog browses and searches entries, expands columns, and exposes owner crawl/publish/withdraw actions (change 5, DES-063). The Sources page also lists the connectors and entries a reader sees, with columns on demand, and offers the owner Crawl, Publish and Withdraw (CatalogBrowser in apps/web/src/SourceCatalog.tsx, DES-065). DOM, route and connector race tests cover the boundaries. Sample values remain off.
  • Voice notes and Groq (docs/guides/voice.md): the System spec's speech slot (none, the default, or groq), pkg/speech's Transcriber (and Synthesizer, built for groq and used by nothing yet) with an in-memory Fake; kind: groq under models, the OpenAI-compatible adapter on Groq's base URL with env:GROQ_API_KEY; the ingress hook (*Platform).TranscribeVoiceNotes, called when a Slack message that starts or continues a thread carries files, which puts each audio attachment's transcript after the text, marked [Voice note, <language>], and keeps the recording attached; GET /api/voice and POST /api/voice/transcriptions (speech:write, the body capped at 10 MiB and its type sniffed); the console's microphone records with MediaRecorder and puts the words in the draft
  • Built, tested: the groq client against a fake server (multipart, verbose_json, the key, the size cap before anything is sent, the timeout, a provider error without the key in it), the hook (only audio, another tenant's digest unread, at most 4 notes, the text within 8,000 characters, each failure said in the message), the routes in the contract test and their permission, the spec's and the guide's examples, the composer with a fake recorder (recorded, transcribed, too long, refused, failed). Not tested against Groq's live API: its request and answer shapes are from its OpenAI-compatible documentation as read from other sources, and its text-to-speech is not called anywhere. Not tested end to end through a Slack download (the hook and the two lines that call it are). Not built: WhatsApp, iMessage and SMS (the connectors in urmzd/orchagent call the same hook), spoken replies
  • pkg/memory: per-agent notes sent with every turn, written by people or by a memory agent
  • Built. Kept with -state=postgres
  • Housekeeping runs: a title agent names a conversation, a memory agent writes notes after a turn
  • Built. Off until a workspace picks the agents, and never on the offline provider. The settings keep each agent by its own name, whatever spelling names it. The memory agent is not asked about a conversation that acted for a person with a person-scoped tool. A housekeeping run, and the conversation of its own it makes, is read where the turn it serves is, and a title or memory agent that lives in a project is asked only about the turns there and below, so nobody who reads a turn is shown a run of an agent they may not read. A summary counts the run with the turn, and the directory counts the conversation at the workspace, where it is filed, only for a reader who may read the turn (TestAHousekeepingAgentThatLivesInAProjectServesOnlyItsTurns, TestAPrivateThreadsHousekeepingStaysInIt, TestAHousekeepingRunIsCountedWithTheTurnItServes, TestSystemThreadsAreTheConversationsSystemRunsOpened)
  • pkg/corpora: corpora, named bodies of knowledge that hold knowledge sources and catalog connectors, with an owner, readers and cross-corpus links (sources.md)
  • Built: the store on memory and Postgres with the 200-corpus bound held across two processes (TestTwoProcessesAgreeOnCorpora), /api/corpora routes, readers by person, project or workspace, owner-only changes and hand-off, members shown by the source's own rules with hidden ones kept (TestACorpusIsReadByItsReadersAndChangedByItsOwner). Not built: corpus search and tools, live warehouse queries as the reader, the console pages, graph, maintenance and sensitivity
  • pkg/evals: suites of deterministic checks for agents, retrieval metrics for knowledge, scored by saige
  • Built. Kept with -state=postgres. A run going when the process stopped is read back as errored
  • pkg/signals: one run's signals (own spend, model calls, tokens, latency, time parked, tool calls and errors, attempts and retries, ratings), a pure fold of its events and feedback records (RFC 0008, change 1)
  • Built as a library only. Not stored, not served and not shown yet. Tested in pkg/signals
  • Eval candidate review queue (RFC 0008, the eval case part of change 4)
  • Built: a down rating with a reason opens a candidate, listed newest first by GET /api/eval-candidates (evals:read) and shown on an agent's Evals tab. A reviewer with evals:write accepts it into one of the agent's suites with their own checks (POST /api/eval-candidates/{id}/accept) or dismisses it (DELETE /api/eval-candidates/{id}); both are audited. Only the question and the checks are copied, never the answer, and a candidate from a run the reader may not read is neither listed nor told apart from one that does not exist. Not built: instruction and memory proposals, drafting into a new suite, and the routes as agent tools. Tested in internal/httpapi (eval_candidates_test.go, the confinement sweeps) and the console's eval-candidates.dom.test.tsx
  • Conversations: threads, branches, any agent on any turn, replayed history with a configurable limit. Listed by project (project=), by a project and everything below it (within=), ~ for the workspace, and by channel (channel=). A conversation from before threads reads as a shared thread in general of its project, with its people and agents as participants, and gains a record the first time it changes. Its people, and every conversation's in a list, are whom its runs acted for: a connector's run is the person its user is mapped to, never that user, and a run that acted for nobody, such as one for a Slack user no client maps, is neither a participant nor the owner (TestAConversationsPeopleAreWhomItsRunsActedFor). GET /api/threads/{id} is paged: the thread's record, who answers there, and 200 turns a page, newest page first. A turn through POST /api/runs is answered as a message posted in its thread would be: untagged, by the thread's default, the acting client's, the channel's (a new conversation is in general), then the project chain's; a follow-up after an answer in a room is sent the room up to it, each earlier follow-up with who asked it, and its own words with who asks them, and is filed in the room's channel, and the next message's agents are sent it (TestAFollowUpInARoomNamesWhoAskedEachTurn)
  • Built. Kept with -state=postgres, with the run index and the thread store. The console's conversation reads every page (at most 50) to walk the branch from its start, and a room keeps every turn it has read as its newest page moves on; both tested against a stubbed API, with 201 turns. Its chat bar posts a message to the conversation after the turn on screen, which runs only the agents it tags, or with none tagged the agents the conversation has selected; Retry and Regenerate still ask a turn again through POST /api/runs. On a phone a conversation's and a room's title has a line of its own
  • Channels on the project record (pkg/projects): every project has general, which cannot be archived; at most 20 a project, archived ones included; a channel's title, purpose (sent to every agent answering there) and default, which must be able to answer in the project; the file's channels changed only by the file; every change in the project's history. Routes GET, POST /api/projects/{name}/channels, PUT, DELETE (archives) /api/projects/{name}/channels/{channel}, behind projects:read and projects:write. The Platform document's channels, on the workspace and on each project, are merged at every start and changed only by the file
  • Built and tested, kept with -state=postgres. A file's channel default is checked for its form at humagen config check, and whether it can answer only when a message is posted. The console's project page has a Channels tab (/projects/{name}/channels) listing each channel with who answers there and New Channel, and each channel is a page (/projects/{name}/channels/{channel}) listing its threads, paged on the server, with a composer that starts a shared thread
  • Shared threads, tagging and the room (pkg/threads, internal/platform/threads.go): a thread's record with participants and a default, people's messages that start no run, the tag grammar (@agent, @handle, @sme, @sme:topic, Slack <@U…> through the posting client's people, nothing inside code), what a message starts (tags first, every tagged agent side by side, however many it tags, bounded by budgets and admission like any run (TestEveryAgentAConsoleMessageTagsAnswers, TestABudgetStillRefusesTagsPastItsLimit), and a skill named in a console message with no agent tagged goes to the conversation's selected agents, or with none asks the agents available whether to join, each that joins told to use it, while a client's message goes to its default with the skill; tagging only people or experts, an answer, a reply or Post Only starts nothing; a message a person posts in the console, as themselves, runs only the agents it tags or, with none tagged, the agents the conversation has selected (rule routed), so with neither it starts nothing (rule untagged), whatever default is set (TestTheConsoleRunsOnlyWhatAMessageTags); otherwise, for a message a client posts from Slack or GitHub, the default the thread inherits from the thread, the client, the channel and the project's chain, a named agent alone or, for *, each agent that joins; one that stopped being available starts nothing and says why (TestOnASurfaceTheDefaultAnswersAndFailsClosed)). A thread may select agents (agents, at most 5, and mode, join or all (a stored best_fit reads as join), on POST /api/threads and PUT /api/threads/{id}, which anyone who may post there changes; the PUT also moves a private conversation that has no runs, which takes its starter or an owner of its project, as Share does, TestAPrivateConversationMovesWhileItHasNoRuns, TestOnlyItsStarterMovesAPrivateConversation): its untagged console messages go to them (Slack and GitHub keep their defaults), each of them that decides to take the message, or each side by side (at most 3), with none taking it waiting for a person (TestAMessageNoSelectedAgentTakesWaits), and each such run records how in routed, a skill named goes to them, and a tag wins over them (TestSelectedAgentsAnswerAConversationsUntaggedMessages, TestASkillGoesToTheSelectedAgents, TestSelectingAHiddenAgentAnswersAsAnUnknownOne, TestAHiddenSelectedAgentIsNoOracle, TestJoiningInASlackThreadAsksOnlyAgentsTheClientRoutesTo, TestRoutingIsKept on memory and Postgres). A conversation the console starts is private, its starter's alone, until it is shared: POST /api/threads/{id}/share moves it into a channel of a project the sharer is a member of (general in another project) and makes it shared there, adding the people it names who can read that project, each told once in their inbox, and saying in not_added who was not and why (TestSharingTellsThePeopleItAddsAndAddsOnlyWhoCanRead). Only a participant shares, and publishing a private conversation or moving one takes its starter or an owner of its project, so someone tagged into it does not publish it (TestOnlyItsStarterPublishesAPrivateConversation); it moves only while no run has been filed in it (409), a share and the start of the thread's runs are serialized so no run is filed in the project it left, a default or selected agent that cannot answer where it goes is dropped in the same write (TestSharingDropsSelectedAgentsThatCannotAnswerThere), a message posted just before a move starts nothing for a poster who may not post where it went (TestAMessageStartsNothingWhereItsConversationMovedOutOfReach), only a participant moves one (TestAGovernorWhoTakesNoPartDoesNotMoveAPrivateConversation), a person counts as posting in the console only with no acting client, whatever a client is called (TestAClientCalledConsoleKeepsAClientsRules), a surface's thread stays where and as it was filed, a mention raised in it is read where it is now (TestAMentionIsReadWhereItsConversationWent), and it answers the thread as GET /api/threads/{id} reads it (TestSharingAConversationMakesItSharedInAChannel, TestAConversationIsPrivateUntilShared, TestShareIsKept on memory and Postgres). Each run is sent the room up to its message, one turn a line after who took it, people by name and handle and agents marked as agents, fenced off from the message, which follows with who posted it, so nobody's words read as the poster's (TestNoOneInTheRoomPutsWordsInThePostersMouth); it records the channel and the message it answers. Each run a message starts acts for the person who posted it, never for another participant, so a tool that acts as a person uses the poster's own credential, though the run reads what others said in the room (TestARunAMessageStartsActsForThePersonWhoPostedIt). A failed answer is retried from the inbox by the poster alone, as an answer to the same message (TestARetryOfAThreadsRunAnswersTheSameMessageForThePoster), and a turn whose room holds an answer that reached a person's own credential is not taught to memory (TestWhatAPersonsCredentialReachedInARoomIsNotTaughtToMemory). A person posts only as themselves or as the person a client's credential acts for, and no route names an author. Every thread route names people by handle and calls them by their name or else their handle, so a subject that holds an address is never shown, and people are added to a thread by handle; an answer posted in a thread for that person is checked against them and recorded as theirs, with the credential as the way it came. A message is refused before its tags are looked up when it is empty or over 8,000 characters, and each name it writes is looked up once: agents in one read of the tenant's agents, so a message tags any number of them (TestFifteenTaggedAgentsAllAnswer, TestARosterLetsAMessageTagAnyNumberOfAgents), and at most 10 people, experts, roles and skills, each a lookup of its own. A workspace holds at most 10,000 threads and a project 2,000 (429); a person posts at most 30 messages a minute and a project takes at most 120 (429), in at most 10,000 windows; one message notifies at most 20 people and roles. A list of threads copies only the records it keeps, with at most 200 characters of a first message. Routes POST /api/threads, PUT /api/threads/{id}, POST /api/threads/{id}/messages, PUT /api/threads/{id}/participants, POST /api/threads/{id}/share behind runs:write, and an event: thread notice on /api/events
  • Built and tested under the race detector, kept with -state=postgres. A private thread is read by its participants alone (see Read confinement). In the console a thread people have posted in opens as a room (/conversations/{id}, ?message= to open at one): people's messages by name, agents' answers by AgentMark, where it is shared, an @ typeahead over the agents available in the project (under *, never one that lives in another project), people and expert topics, each kind keeping places in its list of eight and the person writing left out; in the console, one chat bar with no Post Only, no Private and no line saying who answers, / offering skills as commands and @kind: a mention kind's items, and a private conversation's header offering Share (a dialog at /conversations/{id}/share: project while no agent has run, channel, people to add; POST /api/threads/{id}/share, a 409 said in words); a thread started in Slack, and each message posted there, says so. A question a run waits on is offered only to the people it is for: a thread's turn says to each reader whether it is theirs (ask, checked as answering would check them) and whom it is for otherwise (the person the run acts for by handle, the experts on a topic, the owners of a project, named only to a reader who may see it, the people its agent's rules name), which the room and the conversation say in place of a way to answer (TestAThreadSaysWhomAQuestionIsForAndOffersItOnlyToThem). A reply to a question in words is posted in the thread as the person's message and recorded as its answer; a refusal is said under the question and the words typed stay in its box. A settled question sits between the step that asked it and the answer, and a typed answer reads as one. The question's inbox message says whom the agent asked ("asks the billing experts") and ends a long question with an ellipsis, and what a message is about names its conversation by the thread's title, for a reader who may read it, never by an id. A run waiting on a person is shown still. A room offers neither Retry nor Regenerate: a failed answer says the person it acted for retries it from their inbox, and a failed turn that acted for nobody, such as a machine's from before threads, says anyone who may start runs retries it there. Tested as DOM interactions (room.dom.test.tsx, an agent homed elsewhere under * included) and the typeahead's rules (tags.test.ts). A mapped person's Slack messages are posted as theirs (see Slack and GitHub coworking); anyone else's are still filed as runs
  • Experts on projects: a person or role:<name> with up to 8 topics, at most 50 a project, found along the chain nearest first. GET, PUT /api/projects/{name}/experts. Tagging @sme:<topic> notifies them; a question an agent asks with asked_of: sme:<topic> (or sme) is addressed to them, narrowed to the spec's answerers when it names any, and an answer posted in the thread resumes the run. A question in a run that uses the credentials of the person it acts for goes to that person alone, even when it asks the experts, and an expert's answer to it is refused (TestAnExpertDoesNotAnswerWhatARunAsksWithAnotherPersonsCredential). Every turn in a project is told which topics have experts. The Platform document's experts, on the workspace and on each project, are the file's when set
  • Built and tested. A question with no expert on the chain goes to the owners of the nearest project on the run's chain that names any by its own entries who own the run's project now (an entry for everyone names none, and one a members-only project above makes inert is passed over, TestAQuestionForExpertsSkipsOwnersWhoCannotReadTheRun); an owner is judged with the roles they held when last seen, so one let in above by a policy role counts (TestAQuestionForExpertsReachesAnOwnerLetInByARole); in a private thread it stays with whoever may answer there (TestAQuestionForExpertsInAPrivateThreadStaysWithItsParticipants), though a question to the experts there still goes to experts who do not take part; narrowed to the spec's answerers as experts are, and its message says "asks the project's owners"; a thread tells anyone else it is for owners, naming the project (owners_of) only to a reader who may see it, and the room says "for the owners of Field engineering" or, unnamed, "for the owners who answer for this project" (room.dom.test.tsx); only when no project on the chain names an owner does it go to the answerers, or anyone (TestAQuestionForExpertsWithNoExpertGoesToTheNearestOwners)
  • Mentions in the inbox: kind and part mention, raised once for each person a message tags (and once for the experts a role names), read with runs:read and listed with GET /api/inbox?kind=mention; Reply posts a message in the thread as the reader, which the default does not answer (one that tags anyone takes a member of the thread's project, since its tags start agents and tell people as any message's do), Done (done, the API's) sets it aside, both with runs:write
  • Built and tested, the reads and both actions against the contract. The adapter lays a mention out with its own template (Mention) as a message to reply to, the same in the console and in Slack (parity.test.tsx); Done is the header's Dismiss
  • Prompt landing, tasks and areas navigation, configuration overview and routing settings
  • Built. Tasks use existing threads and areas use projects; conversation and execution history remain available
  • Structured helper calls: ordered messages and references, text/summary/JSON Schema return contracts, frozen inputs, validated outputs and one answering agent
  • Built and tested, on fiber v0.20.0
  • The dynamic router (pkg/join), which replaced @auto and pkg/pick: a message that names no agent where the default it inherits is * ("everyone decides") asks every agent available there, at most 64, one low-effort question at once, "should I be involved?", and each that says yes, at most 5, answers in the same thread, each reply posted and streamed on its own (in Slack, the same Slack thread). With none, nothing starts and the message waits for a person to answer or tag an agent; there is no fallback to a named default. A named default still answers alone. An agent whose spec says tagged_only: true runs only when named and is never asked. The workspace chooses the model that asks in its settings, router: {enabled, provider, model}, off by default (and then no agent joins), on a provider the deployment declares, whose key is a credential reference never kept in the settings; a program built on Humagen can pass its own asker as platform.Config.Router. An asker error or an unreadable answer is no. A joined run's picked says "Joined on its own: ". GET /api/join?q=&project= (agents:read) previews each agent's answer, {decisions: [{agent, join, reason}]}, leaving out agents the caller may not read. POST /api/runs with agent: "*" returns the first joined run and starts the others in the same conversation, 409 when none takes it. A client's default may be *, and stamp asks only the agents the client may route to, where the run is filed. auto stays reserved, never an agent's or a person's name; @auto tags nobody, and a default stored or written as auto reads as * (a Platform file gets a load note)
  • Built, tested in pkg/join with the model-free join.Words asker (TestEveryAgentIsAskedAndEachYesJoins, TestFailingOrMissingAskerJoinsNobody), the platform (TestOnlyAgentsAvailableWhereAMessageIsPostedAreAskedToJoin, TestEveryAgentThatJoinsAnswersAndNoTakersStartsNothing, TestATaggedOnlyAgentIsNeverAskedToJoin, TestJoiningThroughAClientAsksOnlyItsAgents, TestAutoTagsNobody) and the contract. Not yet tried against a live model
  • Projects: a tree under the workspace, which is the root. Conversations filed together, shared memory and instructions sent to every agent in the project and below it, schedules whose runs are filed there
  • Built as a tree with kinds, in its own store: pkg/projects, kept with -state=postgres. Kinds company, team and account with their rules, and the workspace's own kinds over team or account; a name is the identity, unique ignoring case and never changed; a project moves under another parent under one lock, with no cycle and its height counted, and is archived rather than deleted when it should stay; at most 500 projects, paged, 4 levels, 100 children and 10 company projects. A change and its history entry are one write, and a deleted name leaves a tombstone only projects:govern reuses: at most 1,000, one forgotten only when no conversation or file is filed under its name, and a delete refused (429) when none can be. Delete is refused while sub-projects, schedules, alert rules or limits point at a project. The projects a workspace kept in its settings move there at start, once, with every name a schedule, an alert rule or a limit still points at, repaired if a start stops between the two writes. The Platform document declares projects (title, kind, parent, account, instructions, members), workspace.instructions, workspace.members and workspace.project_kinds: humagen config check refuses a broken tree with the entry's path, and each start merges the file in, parents first. A field the file sets is the file's (409 in the API), a project made in the console survives a start, and one that leaves the file stays, unmanaged. Tested on memory and Postgres, with 40 racers on one name, and across a restart on Postgres
  • Project API: /api/projects pages the tree in order (parent=, within=, q=, kind=, limit, before), each view with the caller's access and actions and mine on the projects that name them; creates, reads a project with its ancestors, sub-projects and the limits that hold it, replaces its title, description, account, instructions, kind, archiving and who may announce by version, moves it (/move), deletes, and pages its history; /members, /limits and /memory. ~ is the workspace. Behind projects:read and projects:write, then the caller's role on the project, with projects:govern for the workspace, company projects, their notes and a deleted name. Settings.projects left the wire
  • Built, tested: every route's permission, shapes and documented statuses in the contract tests, another workspace's projects not found, an empty workspace listing [], filing a schedule, an alert rule or a limit racing a delete of its project, where exactly one wins, and the role tests below
  • Layered context: a turn is sent its project chain's instructions, the workspace's first, then the project's notes, its ancestors' notes nearest first, the agent's own notes, and the conversation. The first line says which instruction wins
  • Built in one function, for conversations and for scheduled and run-now runs filed in a project, and pinned in the run's tag so every attempt is sent the same text. Instructions share 8,000 characters and ancestors' notes 6,000; what is cut is named in the text. The workspace's own notes are kept under the memory owner project:, which no agent's name can be, and the agent memory routes answer 404 for any project's owner. Tested in order and within budget, and that an agent named workspace never reads or writes the workspace's notes
  • Console for the project tree: Projects as a tree grouped by kind (Company-wide, headed by the workspace, then Teams, then Accounts, then the workspace's own kinds by their titles), searched by name, title, description or customer (?q=, ?kind=, a workspace kind included). A project page at /projects/{name}, ~ for the workspace, with a breadcrumb and back to its parent, opens on its Inbox tab. Overview: its tasks paged on the server (project=, or within= with its sub-projects), Sub-projects and New Sub-project, shared memory and schedules. Context: its instructions, and read only what each project above sends, the workspace's first. Agents, People (members, and owners from above), Limits (its limit with every limit above it in words, "Field's limit also applies here", and the owner's limit form) and History tabs. Move Project, Archive and Mute in the page's actions, each offered only where the server says the caller may. New Project takes a title, a name marked as fixed, a kind and a parent, and offers a workspace's own kinds where they may sit by the kind they behave as; company-wide is offered only with projects:govern, and the workspace and company-wide projects are changed only with it. Settings' projects editor is gone, replaced by links to Projects and the workspace
  • Built. Checked in a browser at desktop width and at 390px, where the tree indents at most one 16px level and deeper rows print their path, with no sideways scroll, before the Inbox, People, Limits and History tabs came; those are not yet looked at in a browser. Tested: every address round trips, the tree's layout at 390px with a workspace kind, the kind rules through like, what an update and a move send, and the Inbox, People and Limits tabs against a stubbed API. Archive, Mute, the History tab and the owner's limit form have no console tests
  • Composer project selection and creation
  • Built. Select project, explicit Projectless choice, the project tree with each project's kind, customer and path ("Account · in Field › Globex"), searched by name, title, description or customer, and inline creation of a top-level team, offered with projects:write, that selects the project and preserves the draft. Console terminology uses Projects throughout. See UI review
  • Project icons and collapsed navigation
  • Built. Shared Humagen folder icons across project surfaces. Collapsed, the sidebar is a rail of icons, Projects among them, each with a hover and keyboard label; there is no flyout of projects. Compose, history and sidebar direction use distinct symbols
  • Configurable console titles and labels
  • Not built. Follow-up: allow workspace configuration to override display titles and labels while keeping project identifiers stable
  • Workspace settings, pkg/prefs: per-person theme, accent and profile picture, and the projects a person mutes
  • Built. Kept with -state=postgres, the picture included. muted holds at most 100 projects the person can see, never the workspace
  • Run context (RFC 0004, change 5): setting kinds (pkg/settings), the person store (pkg/personctx, GET/PUT /api/me/context) and the context pinned at admission (pkg/runctx)
  • Built. workspace.run and a project's run set ceilings (tools, models, call_depth, tool_servers, egress) and preferences (model, compaction_tokens); a person adds their own level. Resolved once at admission with who the run acts for, pinned to its trigger with a digest, inherited and only narrowed by called runs. Turns apply the preferred model, the model and tool ceilings and the history budget; calls apply the depth ceiling and only reach agents the requester may read. Not yet: person tool servers are pinned but not connected (they wait for the sandbox, changes 2 and 4), the memory volume is an id only, the requester's permissions come from project membership and the workspace policy, not sign-in claims. A runtime passed with humagen.WithRuntime is handed the budget as turn.Input.Compaction. In the console, You > Connections lists, adds and removes a person's tool servers (apps/web/src/ToolServers.tsx), and says they are not connected yet; the other settings have no screen
  • Branding (internal/branding, branding in the spec)
  • Built. The System document brands the deployment: the tab title, page metadata, manifest and icons are written into the console as it is served, and its palette and fonts as a stylesheet. A Platform document brands its workspace over that, read through GET /api/branding, its logo and stylesheet beside it. A person's workspace accent, the default, is the branded one. The welcome announcement, the empty conversation's suggestions, notification emails and the console's own text by key (branding.copy, checked against keys generated from copy.ts) come from it too. The Slack manifest takes its description, color and command copy from surfaces.slack. Files are read and checked at start. Tested in pkg/spec, internal/branding, internal/httpapi, internal/app and apps/web; not yet checked in a browser
  • Development workflow under Tilt (deploy/tilt/dev, dev.Tiltfile, make tilt): a Tilt extension, humagen_dev, that a project built on humagen loads with its own command and spec. It builds the binary, checks the spec and lists unset credentials (doctor), runs Postgres in Docker on a kept volume, humagen serve restarted on a new binary or a changed spec and ready on /healthz, and the Vite console with hot reload that never restarts the API. Tilt is the only supervisor; run.sh refuses a held port and execs
  • Built. The Tiltfiles were run with Tilt stubbed out, and the commands they produce were run: the build, doctor on good, unset-key and failing specs, the API and console through run.sh with the proxy answering, a held port refused, SIGTERM leaving both ports free. tilt up and the Docker database have not been run here (docs/guides/develop.md#what-has-been-checked)
  • Local Kubernetes with Tilt (Tiltfile, deploy/tilt)
  • Built, not run here. The chart's development.loopback puts the listener on the pod's loopback for kubectl port-forward, lets dev and mock sign-in through only then, runs the probes inside the pod and refuses an Ingress. make chart-check renders the Tilt values and the refusals; tilt up has not been run against a cluster
  • Agents in projects: agents {enable, allow, default} on every project, and a home for an agent that lives in one (pkg/projects). Available in a project is what its chain offers (an enable list; *, every agent with no home; the agents living there) and every allow list on the chain permits. One check, at admission: a run whose agent is not available where it is filed is refused, 403 globex-helper is not available in Initech, for every origin (API turns, schedules and run-now, called runs where their root is filed, client tags). Housekeeping is exempt. An eval's cases are filed where the agent lives, so the home's limits count them and the runs they call are checked there. A scheduled run refused this way raises one alert while it stays open. Writing a schedule, a default or an enable list answers the same sooner. GET, PUT /api/projects/{name}/agents; PUT /api/agents/{name}/home, 409 while a default, a list, a schedule or alert rule elsewhere or a client would lose the agent; GET /api/agents gains homes and enabled_in. In the Platform document as workspace.agents, projects[].agents and agents[].project, checked by rule 6
  • Built, tested: the store on memory and Postgres (restart, a faulty write, 40 racers on one home, tenant isolation), admission and homes in the platform, an eval held by its home's limits, the routes in the contract test, the file's lists and homes at start. Call policies are not counted as losing a homed agent: they name callers, not places. A schedule written in the instant before its agent is homed elsewhere is not caught by the home's check, and is refused at each occurrence instead. In the console, a project's Agents tab (/projects/{name}/agents) shows what is available there and where each comes from ("from Acme", "Lives here"), the default with what it inherits, the enable and allow lists, and Lives Here, which says how many places would lose an agent; on the workspace the default is the Workspace Default, which replaced the baseline switch on the agent page. An agent's Access tab says where it lives and where it is enabled, and moves it. Tested in happy-dom and static renders, and looked at in headless Chromium at 1280 and 390 pixels wide against make dev
  • Defaults along the chain: a message a client posts from Slack or GitHub that tags no agent goes to the default its place inherits (in the console an untagged message starts nothing; an agent runs there only when tagged), the project's, each ancestor's nearest first, then the workspace's (the root's default, the Workspace Default). With none set nothing runs: POST /api/runs answers 409 "tag an agent". A default that has stopped being available is refused, not passed over. The workspace baseline is gone: at the upgrade each workspace's root enables every platform agent and takes the old baseline as its default, or * with none, then the settings are written without it; a stop between the two writes is repaired at the next start. A workspace never written reads the same. Setting the workspace default needs projects:govern
  • Built, tested with the migration on memory and Postgres, including a stop between its writes. With shared threads, the thread's default, the acting client's and the channel's are nearer than the project's (see the Conversations row); a message from a client outside a bound channel is answered by the client's default and then its home channel's chain (see Slack and GitHub coworking in projects)
  • pkg/people and the Directory's people: each person's name, handle, roles and where they were seen. Recorded when a person who holds any permission makes a request (a sign-in; nothing is written while nothing changed, for an hour), when a client maps a Slack person, and from the policy's grants to a subject at start, in the workspace -tenant names; with tenants from a claim (-tenant-claim, and always under -auth=mock) a grant names no tenant, so it records nobody. A handle is unique across people and agents, auto and sme are reserved (@auto tags nobody), an agent cannot take a person's handle (409 "a person goes by @dana"), and no email is asked for or shown: a subject that holds an address, as a Tailscale login does, is kept as the key it is, left out of GET /api/people, and subjects are never searched. GET /api/people (people:read, which every built-in role holds through read on *) pages it with the person's own picture, served by GET /api/people/{handle}/photo and never fetched from elsewhere. Every other route that names a person by subject keeps the subject, as the key it is, and sends what they are called beside it, the name they chose for themselves, else the one they signed in with, else their handle, never a subject that holds an address (platform.Names, as the Directory names them): an inbox message's sender (from.display) and whoever decided a part (outcome.by_name), a project's members and the owners from above (name), its record of changes, notes, limits and their changes, schedules, alert rules and acknowledgements, call policies, agent revisions (*_name), and who answered a question on the run's events (answer.by_name on lifecycle.resumed, handed out by GET /api/runs/{id}/events and /api/events; the journal keeps the subject). A thread's message is called what its poster is called now. The words the platform writes about a person (a proposed note's subject line, a stop's cause, a refusal naming whose credentials a run uses, who did what in a recap's project_changes) use the name too
  • Built, tested: the store on memory and Postgres (restart, a faulty write, 40 racers on one subject, the 5,000 cap, tenant isolation), sign-in, a subject that is an address, grants under a tenant claim, the contract. Machines are not people. Each person lists their own projects (projects, in tree order: a member or an owner through an entry naming their subject or a role they held when last seen, or as an owner above; never one reached only through everyone, and not the workspace), only those the reader may see and none without projects:read, at most 20 with projects_more counting the rest the reader may see (TestTheDirectoryListsAPersonsProjectsTheReaderMaySee, TestADirectoryPersonsProjectsAreBounded). The console's Directory does not show them yet. The console's Directory (/directory, /directory/agents, /directory/projects, in the sidebar) lists people by name and handle with their own picture and roles, agents by color with where each lives and is enabled, and the tree with what each project holds and the agents living in it; each tab only for those who may read it. Tested in happy-dom, and looked at in headless Chromium against make dev. Every page that names a person shows the name the platform sends, and a project above by its title ("Owner from Field engineering"); tested in Go against an address subject (names_test.go), in the adapter, and as DOM interactions (roles.dom.test.tsx)
  • Memory approval: what the memory agent writes waits for a person, following saige's memory policy
  • Built. With memory_auto_approve on, an agent's notes are kept as they come; project and workspace notes always wait for explicit human review, even when the proposing turn belongs to an owner
  • pkg/policy: versioned limits per workspace, project, agent and client on runs, concurrency, spend, tokens and lease; a narrower scope can only tighten. A project's limit holds everything below it: a run falls under its project's policy and every ancestor's, and the strictest refuses
  • Built. Kept with -state=postgres, history included. Two pure functions, Decide at admission and Exceeded mid-run, so a refusal or a stop can be replayed from the policy version it names. The ancestors a run counts toward are pinned at admission (Run.Within, usage.Entry.Within), and a called run takes its root's. A run filed in a project the tree no longer holds is refused (409), so deleting a child with no limit of its own does not let its conversations out from under its parent's; a file keeps the ancestors it was published under, so the parent's storage still counts it. Tested with 40 racers in two children against a parent's limit of 7, with spend stopped at a parent's limit to the micro-dollar, and with a deleted child's next turns and files
  • pkg/usage: append-only ledger of admitted, refused, warned, halted and ended runs, and of spend (one entry per model call, keyed by the runtime's accounting_id, and one settlement per run), with counters per scope and day and Rebuild from its entries
  • Built. Kept with -state=postgres: an admission that cannot be written is refused, and every other entry is counted at once and written then or, if that fails, at the next write or flush. Admissions and spend are kept 62 days, whole days, in memory and in the database. On Postgres the counts are shared (usage.Counters): an admission takes its quotas (a policy's run and concurrency limits) and is counted in one transaction with its entry, on striped counters with no lock per tenant; spend is counted under the tenant's advisory lock. Tested: a call or a settlement delivered twice counts once, a call after its run settled counts only beyond the settled total, entries out of time order count in their own period, and a rebuild agrees; on Postgres, 40 racers in two ledgers on separate pools admit exactly a limit of 7, a run ended in one frees its place for the other, 60 calls delivered to both count once and a ledger rebuilt from the entries reads the same, and the counters are filled once from a ledger that predates them. Striped (RFC 0004, horizontal data, step 4): limits of 1, 3, 8, 13 and 100 against twice as many racers plus 20 over two processes admit exactly the limit, a run limit and a concurrency limit hold together while runs end through the other process, a limit lowered below what the stripes hold admits only up to it, and counts from before stripes count against a quota. With the stripe locks removed, the limit tests fail (16 of 7, 15 of 1). Admissions a second, 32 racers in one tenant, before and after: 2 processes, no limit, 343 to 398 and 3,569 to 3,611; with a limit, 298 to 329 and 1,925 to 2,116; 8 processes, no limit, 280 to 369 and 3,377 to 3,604; with a limit, 281 to 333 and 1,899 to 2,182. Part of the gain is that an admission no longer holds its ledger's lock while it talks to the database
  • Admission: every run is checked under one lock before it is accepted; a refusal answers 429 or 402 with the limit, the policy version and the reset time, and raises a budget alert
  • Built, tested with 40 racers against a limit of 7, and at a spend limit reached to the micro-dollar
  • Console for limits: Settings, each project page, and usage against limits in Analytics, with token limits and a lower-bound note on spend
  • Built. Not checked in a browser
  • Spend and token limits: enforced at admission and mid-run, with the warning threshold and a stop through the runtime. See Usage and spend
  • Built on fiber v0.10.0's usage reports, tested with scripted priced models under the race detector. Not run against a real provider here: no model key was available. Cost is a list price from saige's catalog, not a provider's invoice. A call in flight when the limit is crossed finishes and is counted, so a scope can end a little over its limit
  • Unpriced calls and other currencies: counted apart, never as dollars, one lower-bound alert per scope, bounded by max_tokens
  • Built, tested
  • Asking a person to approve a run at a limit: a policy's approve action with max_grant / max_grant_tokens, fiber's runtime.Hold, a budget question in the inbox, on the run and in Slack, and grants in the usage ledger. See Approving a run at a limit
  • Built mid-run, tested with scripted priced models under the race detector (internal/platform/budget_test.go: grant, stop, a policy that no longer grants, a blocking limit outranking), in fiber (TestAHeldRun*, TestADeniedOrExpiredHold*, TestAHoldMadeMidTurn*), and in the adapter, the console mailbox and the Slack renderer. Admission still refuses at an approve limit. The console's Limits form does not offer approve yet; the API does. Not run against a real provider here
  • Limits set by a project's owner
  • Built. An owner of a project above sets a tighten-only limit on it (PUT /api/projects/{name}/limits, authority: owner), refused where an admin set one and when looser than any limit over it, naming the scope that binds, both decided under the policy store's lock. An admin's limits stay billing:write's, and the console's Limits tab shows the chain ("Field's limit also applies here"). A move that leaves a project holding a limit needs billing:write, and so does one that would hand the caller an owner's limit they could not change before (the moved project, or one below it, holds a limit set from a parent they do not own), both decided under the project store's lock, so no move escapes one. Tested in pkg/policy and through the routes (TestAnOwnerLimitsOnlyWhatIsBelowWhatTheyOwn, TestAMoveNeverEscapesALimit, TestAMoveNeverHandsSomeoneALimitTheyCouldNotChange)
  • Direct entry after sign-in, with optional personal preferences
  • Built. Everyone opens the console directly, including first admins. Profile and Appearance settings hold optional preferences
  • Recents: conversations paged by an opaque keyset cursor, 200 a page
  • Built
  • Read confinement: members-only projects and private threads, one predicate on every read path
  • Built. One rule, platform.Seer over seesPlace: a role of at least viewer in the project, and in a private thread taking part, or projects:govern. Every read path asks it and answers 404 "not found" for what it hides, exactly as for what does not exist: runs, their events, manifest and trace, threads and their pages, the journal, analytics, alerts and rules, published files and downloads, storage, schedules and the runs each lists as recent (found by its name, so a schedule moved out of a project, or a name used again, shows only those the reader may read), the inbox and its counts, memory, limits, usage and notices, eval suites, and the agents that live in a project. A record that names agents names only those the reader may read: a client's default, list, bots and auto-labels (all but to the machine that hosts it), a project's enable, allow and default and its history, the workspace's title and memory agents, an agent's spec (the agents it may call and the approvals of those calls, hashed as shown) and its call policy's allow and trusted, a run manifest's definition, a channel's default and its history, and a thread's default, the agents added to it by name who never answered there, and the tags in its turns that started nothing (a tag of such an agent reads as one of nobody), all but to the machine that hosts its surface, leave out one that lives in a project the reader may not read, as if it were not there, and so does what the builder reads of a spec; a spec whose every approval is left out leaves out who may approve too. A run names the agent that ran it, which was available where it ran, even one moved since, and so does what is built only from runs the reader may read: a conversation's agents, the agents that joined a thread by answering there, a tag that started a run, analytics and the analyst's summaries by agent and their slowest runs, a recap's rows of what was done, and a filter of runs by agent, so one page never hides a name another shows. Such a title or memory agent is asked only about the turns there and below, so its runs reach only who may read it. A model policy such an agent runs on is not removed, and the refusal does not name it. A change to any of them keeps what the writer was not shown (in a project's lists, the allow names, which let nothing run there while their agents live where they do, since its owners read every project below it; an enable entry or a default never names such an agent; in a spec, the agents it may call, their approvals and, when the writer was shown none of those, who may approve; in a call policy, the callers while its mode still lists them; in a channel or a thread, its default when none is written; in a thread, a participant, whose removal is that of one not there). What the writer was not shown counts toward no limit they are told of (a call policy's 100 callers, past which a list holds only names already stored, and the 50 participants a change that adds to a thread leaves, of at most 100; a spec's kept approvals keep who may approve them, which a writer shown no approvals who adds one reads back), and a spec's is kept against the revision the write expects, a call policy's, a channel's and a thread's under their store's lock, so an entry another writer adds meanwhile is kept too; a client's and the settings' are kept against what was read when the write began, and naming such an agent, in any spelling of its name, answers in the words for one that does not exist, there and wherever else a request names an agent: the agent a run, a call from a run or a schedule asks, a thread's tags, default and participants, a channel's default, a limit's scope, an alert rule's agent and an eval's subject. A thread's, a client's or a channel's default the person a read, a turn or a message is for may not read is passed over for them, as if it were not set: who answers is the next default along, so what they read and what their messages do never tell it from none, and no agent they may not read is asked to join for them. Moving an agent into a project is refused while a channel's default would lose it, as for a project's or a client's; a thread's is kept and left out instead. A refusal that an agent is not available says where it lives only when everyone in the workspace reads that project, and the call tool offers a run only the agents available where its calls are filed (TestAClientNamesOnlyTheAgentsTheCallerMayRead, TestAProjectsListsNameOnlyTheAgentsTheCallerMayRead, TestTheSettingsNameOnlyTheAgentsTheCallerMayRead, TestAThreadNamesOnlyTheAgentsItsPosterMayRead, TestASpecAndItsCallPolicyNameOnlyTheAgentsTheCallerMayRead, TestAThreadShowsOnlyTheAgentsItsReaderMayRead, TestATurnNamesNoDefaultItsPersonMayNotRead, TestARefusalNamesWhereAnAgentLivesOnlyWhereEveryoneReadsIt, TestTheCallToolOffersOnlyAgentsAvailableWhereTheRunIs, TestTheAnalystNamesWhoRanAndTheBuilderOnlyAgentsEveryoneTheyReachMayRead, TestAChannelNamesNoDefaultItsReaderMayNotRead, TestASpecWhoseEveryApprovalIsHiddenNamesNoApprovers, TestWhatAWriterIsNotShownCountsTowardNoLimit, TestPutKeepingKeepsWhatIsStoredWhenItWrites, TestABusyThreadsParticipantsStillChange). The event stream drops a hidden run's events and a hidden thread's or message's notice, and a project's counts in the directory leave out the sub-projects, the private threads and the conversations of housekeeping runs serving a turn the reader is not shown. They are decided as of one moment, so a conversation opened while they are read is counted from the next read and never for a reader who may not read it (TestAProjectsCountsLeaveOutWhatTheCallerMayNotRead, TestCountsNeverTellOfAConversationOpenedWhileTheyAreRead, TestProjectCountsAreReadAsOfAMark). A person a surface reads, posts or answers for is held to where they may read, never where the surface's machine may: the machine reads every thread on its surface wherever it is filed, but a mapped person who may not read a run finds nothing to answer in it, and nothing is recorded (TestAMappedPersonAnswersOnlyWhatTheyMayRead). Members-only projects are accepted, and account projects are members only from creation; a private thread is read by its participants, tagging a person invites them, and nothing said there is proposed as a note or titled where others read it. What a deleted project held is read by whom it was read by when it was deleted: its tombstone keeps its parent and members. A recap reads only what everyone it reaches may read, and names as configuration only the agents they may all read; its rows of what was done name the agent that ran, as the runs do (TestARecapNamesOnlyTheAgentsEveryoneItReachesMayRead). The sweep reads every GET in the contract and the event stream as another workspace and as a non-member of a members-only project in the same workspace, checking that a hidden object answers as a missing one and that no list, filter or event carries it (TestAnOutsiderReadsNothingHidden, TestAnOutsiderStreamCarriesNothingHidden). The hidden project's channel is bound to a Slack client the non-member may read, so a client's bindings are swept too and leave the hidden one out, and so is that client with its home in the hidden project and the hidden agent as its default, in its list and behind a bot, beside a project the non-member reads whose allow list names the hidden agent and one of whose channels the platform file gave the hidden agent as its default, an agent they read whose spec may call it and whose call policy admits and trusts it, read with a run of that agent and its manifest, a conversation in the workspace whose default and participant came to live in the hidden project, and the workspace's title agent set to it, which titles a conversation in the hidden project and is not asked about one in a project the non-member reads, and a schedule that ran in the hidden project and was moved to the workspace is swept with its recent runs. It also sends every other operation that names an object against a hidden one, and bodies naming the hidden project or following its run, or naming the hidden agent, as it is spelled and in capitals, in a client, a project's lists, the settings, a run, a schedule, a channel's default, a limit, an alert rule, an eval, a spec's spawn list or approvals, a call policy's lists or a call from a run, checking each answers as for one that does not exist and changes nothing, and that saving the client, the settings, the open agent's spec and its call policy as the non-member reads them keeps the hidden agent (TestAnOutsiderChangesNothingHidden). A second sweep hides only a private thread in a project the reader is a member of, with its run, a file it published, the alert a rule raised for the run and that alert's inbox message, and reads, writes and streams as that member while a participant posts there (TestAPrivateThreadIsItsParticipantsAlone). With TestSeesNeedsARoleAndInAPrivateThreadToTakePart, TestAPrivateThreadsHousekeepingStaysInIt, TestTaggingAPersonInAPrivateThreadInvitesThem and TestADeletedProjectIsReadByWhoReadItThen. The console says "Private" in a thread's meta and its row, offers Private in a channel's composer, says on New Project that accounts are members only, and asks an account's owners whether to make one everyone sees members only, except under a project everyone owns, where it says to name owners above first; nothing is closed for them
  • Versioned skills, private memory, personal settings and native console notifications
  • Implemented backend and standalone console workflows: immutable drafts, real forced-approval test runs, tested publication and scoped promotion; exact-owner personal memory with explicit shared-project opt-in; durable native delivery with hourly digests, quiet hours and projection-only dismissal. Agent defaults durably bind up to four exact published skill revisions to the current agent spec revision; home moves cannot widen their scope. Exact-revision Used By lists real readable agent bindings separately from tests; stale bindings surface a review-required readiness state and link to Context. humagen import skills drafts a folder that changed since it was imported as a new unpublished revision and leaves the published one, reports a skill edited in the library since as a conflict unless --force, and loses cleanly to a concurrent import; a revision records via: import and answers carry package_hash (TestImportSkillsDraftsAChangedFolderAndLeavesThePublishedRevision, TestImportSkillsReportsAConflictWithAnEditMadeInTheLibrary, TestTwoSkillImportsAtOnceLeaveOneDraft, TestASkillRevisionSaysItWasImportedAndCarriesItsPackageHash). The import's tests run against a server that holds the real skill store in memory; the store's conditional draft runs on memory and Postgres in the store suite (TestImportDraftsARevisionMarkedAsImported), and no import was run against a Postgres server. Canonical Library routes preserve resource scope in copied links and reloads; You routes alias Settings. The retained legacy notification components remain for compatibility. The current console routes /inbox and /notifications to Alerts, uses one open Urgent/Normal count, and keeps delivery preferences by priority separate; DOM and route tests cover canonical behavior; earlier phone/desktop captures do not certify the new session console. Memory corrections retain provenance; scope/search/kind/expiry controls and explicit reviewed project promotion are implemented. Audit date/actor/domain filters, resource links, expanded snapshots and CSV export are implemented.
  • Cross-domain change audit foundation
  • Built: bounded, credential-redacted attempts and observed outcomes, principal-derived actors, opaque public IDs that reveal no hidden-record count, memory/Postgres replay, and inbox retention. Mutations can persist an attempt before acting and leave an unknown completion pending. Upper library work adds GET /api/audit and an Audit view with exact-owner personal confinement, retained break-glass/project history adapters and explicitly labeled current call-policy snapshots. Historical unknown rules are left absent.
  • Recorded break-glass reads: a read made only through projects:govern (a project or thread the reader sees by no role of their own) kept in an audit record a workspace's admins can list
  • Built. The confinement rule records governance-only reads before granting access, with subject, project, thread, time and server route. Audit failure fails closed. Records use the state backend and inbox retention duration, with a 100,000-record tenant cap. Workspace admins list a bounded time window through GET /api/read-audit and Settings.
  • Per-channel membership: a channel read by its own members alone, narrower than its project
  • Design proposed in docs/architecture/projects.md, pending approval. Not implemented: channels still inherit project visibility
  • Project knowledge in the console: naming a project's knowledge sources, and its Context tab showing which sources ground a turn there
  • Built (#49). The Context tab has a Knowledge section: an owner who reads knowledge picks the workspace's sources the project names, at most 8, and saves them from the version read; everyone who reads knowledge sees what runs there are grounded in and which project each source comes from; a list the platform file sets turns read only once a save is refused; a reader without knowledge:read sees no section and the console asks for none. DELETE /api/knowledge/{name} answers 409 while a project the caller can see names the source, naming those projects; a hidden one neither holds the delete up nor is named, and keeps a name that grounds nothing
  • Project tree rows with the AgentMarks of the project's agents and a still dot for unread updates
  • Built. Project views send the caller's unread open inbox messages and announcements filed directly there, counted from the inbox's per-reader counters with the same confinement rule. Tree and sub-project rows show up to eight read-confined agents that live there and a still unread dot. Tested on memory and Postgres, and in rendered project rows
  • A layer-by-layer preview of what a turn in a project is sent (instructions along the chain, the channel's purpose, the experts line, notes, knowledge)
  • Built. The Context tab previews a selected agent and channel through GET /api/projects/{name}/context, behind projects:read. The agent's current system instructions are shown first; the live turn composer supplies project instructions, channel purpose, experts and notes with their budgets and omissions; knowledge names require knowledge:read, and skills are shown as available when named. Hidden layers are omitted. The conversation, retrieval and runtime compaction depend on the turn
  • A run stopped before its attempt starts records no pinned sources or skills
  • Built. fiber (v0.24) keeps tag meta keys that start with envelope.PrivateMetaPrefix out of every prompt it writes and so out of what it records, a stopped run's prompt included, while the tag, the ledger and the run's record keep them. Humagen pins its sources (_warp.sources, read under the released warp.sources too), the skills a message named with their instructions (_warp.skills) and how selected agents started a run (_warp.routed) under it (TestARunStoppedBeforeItStartsJournalsNoPinnedKeys reads the ledger's record of a stopped, queued run). The other warp.* keys (warp.ask, warp.thread, warp.prev, warp.message, warp.channel, warp.project, warp.within, warp.picked, warp.client, warp.keeps_notes) still show as trigger context there, as in every turn's prompt. That does not matter for confinement: each is what the run's own record says, read by whoever reads the run, and what the model is sent anyway
  • Project membership and per-project access
  • Built. Members hold viewer, member or owner, through *, role:<name> or a subject, read along the chain with Resolve: an owner above owns everything below, no role at one level means none below, projects:govern owns every project, and a machine matches only * and itself. Every project route checks its permission and then the role, which only narrows: a viewer reads, a member creates under a project and proposes notes, which reach its owners' inbox, an owner changes it, its members, notes and who may announce; the workspace's notes and a company project's take projects:govern as well, by every route: the project's memory routes, the inbox and the actions a view offers; an owner without it proposes, as a member does. Starting work in a project takes a member: a conversation or a turn in one (act_as checks the person it names, who must hold runs:write themselves, as for posting and answering for them; a machine's token carries the workspace's policy, which says what that person holds), and filing, changing, pausing, running or deleting a schedule there. In its channels and threads the same holds: an owner adds and changes its channels and names its experts; a member starts a thread, posts, tags and adds people and agents to a thread, and in a private thread only a participant does (a surface's credential is checked as the person it posts for); 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, since an answer's tags start agents and tell people as any message's do; an answer is posted only if it is the one the run was given, so an answer to a question already answered, or whose run stopped, is 409 for everyone; and a thread is changed, or someone else removed from it, by whoever started it while a member, or an owner of the project. A conversation from before threads that nobody asked in is owned by the first member who changes it or posts in it; a viewer's change there makes nobody its owner (TestOnlyAMemberBecomesTheOwnerOfAConversationNobodyAskedIn). What a thread's runs teach the project is kept unasked only for a poster who could keep it themselves, as for a turn. The console offers a viewer no composer in a channel or a room, and says they answer what they're asked from their inbox (room.dom.test.tsx). An agent that lives in a project is its owners' to change: its spec, its call policy and its notes, in the agent's routes and in the inbox. Those routes take an agent's canonical name only, so another spelling of it (another case, spaces around it) is 404 rather than a way around its home's owners. A move never escapes a limit above it (billing:write) or widens which agents may run there (owning the ancestor whose allow list it leaves), and never leaves 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. A project the caller has no role in is 404, and so is everything in it (see Read confinement); too low a role is 403 ("you need to own Globex"). A project without an entry for everyone is members only; a company-wide project keeps everyone as at least a member, no project is more open than its parent, and nobody makes a project members only below one everyone owns. Accounts are members only from creation, and existing projects keep their entries. Migrated records read as everyone owning them. The console's People tab lists members and owners from above, says when a project is members only, and lets an owner remove everyone. Tested in pkg/projects, internal/platform and internal/httpapi (TestAProjectRoleOnlyNarrowsATenantPermission, TestAMembersOnlyProjectIsHiddenFromEveryoneElse, TestAProjectMayBeMembersOnlyWhereNobodyOwnsAll, TestANewProjectGetsDefaultMembers, TestMembersProposeNotesAndOwnersKeepThem, TestNotesOnTheWorkspaceAndACompanyProjectNeedGovernToo, TestAViewerStartsNothingInAProject, TestOwnersDecideAProjectsAgentsAndWhereAnAgentLives, TestAHomedAgentIsItsHomesUnderEverySpellingOfItsName, TestKeepingAHomedAgentsNotesNeedsItsHome, TestRetryingAFailedTurnInAProjectTakesAMember, TestAMoveNeverWidensWhichAgentsMayRun, TestAProjectsRolesHoldInItsChannelsExpertsAndThreads, TestWhatAThreadTeachesAProjectIsKeptUnaskedOnlyForItsOwners, TestAViewerAnswersOnceAndTagsNoOne, TestTheSlackAppAsksOnlyForPeopleWhoMayStartRuns, TestAMoveNeverStrandsAChannelsDefaultOrAHomedAgent, TestAMoveNeverLeavesWhatItsProjectsRunWithoutTheirAgent) and as DOM interactions (roles.dom.test.tsx). The person's project role in the act_as case of starting work and of posting is not tested through the routes. A person tagged, or named as an expert, is told only when they are at least a viewer of the project, as their directory roles and the policy make them, and a role's holders only in a shared thread; otherwise the poster is told plainly ("they cannot read this project, so they were not told") and nobody is invited (TestOnlySomeoneWhoCanReadAConversationIsToldOfIt)
  • Web console on humagen: chat, inbox, agent editor with revisions, evals, knowledge, schedules, analytics, alerts, settings
  • Built
  • Agent message choices editor
  • Built: Model tab edits choices.models and choices.efforts through versioned revisions, with default-deny clearing, validation, discard, error preservation and read-only controls. Six DOM regressions, typecheck and focused native browser checks pass. See DES-068.
  • Conversation archive and reviewed deletion
  • Conversation owners can archive or request deletion. Archiving hides list rows and waits 30 days; requested deletion is eligible immediately. The admin-only Settings deletion queue returns at most 100 readable records, with due rows first. Approval removes stored messages and search entries and keeps a hidden tombstone; run journal retention is unchanged. Restoration cancels deletion. HTTP, DOM and memory-restart regressions cover the lifecycle. See DES-022 in docs/reference/design-requirements.md.
  • Console navigation: New, Inbox, Projects, Schedules, Monitor, Context, Agents, Artifacts, then Pinned and Conversations (called Tasks until they were renamed; /tasks/{id} still opens one at /conversations/{id}). Every page, tab and selection has a path, with back and forward, and old /alerts and /knowledge links land where those moved. Project shortcuts and conversations pin independently in a person's preferences; conversation rows distinguish agents and people. The list's views are Recents, Projects and Archived; each row shows its project, its age or an unread dot, and whether it needs the reader, runs or failed; archiving is the reader's own (pkg/marks, DES-054)
  • Built. Preferences use the shared durable store. Project pins have bounded lists, new-pin read checks, hidden unreadable shortcuts, rollback and ordered saves. Memory restart, HTTP contract and DOM tests cover both pin types; the sidebar browser fixture checks reloads and participant layout at phone and desktop widths with a simulated multi-person roster. See DES-021 in docs/reference/design-requirements.md.
  • Monitor (/monitor, /monitor/rules): run statistics and the alert rules, with a count of what fired that sends the reader to the inbox (/inbox?kind=alert). An alert's link opens the message it raised
  • Built, tested as rendered markup and by route
  • On a phone: no bottom bar. One small button in the top corner opens the sidebar as a drawer, with a dot when the inbox needs you, and the drawer closes on navigation. Also 40px touch targets on coarse pointers, dictation in the composer, and an installable web app manifest that opens on the inbox
  • Built, checked in a mobile browser at 390px. No offline support or push notifications
  • Model policies: an agent's primary model, up to four ordered fallbacks and the errors that move a call on (fallback_on), on fiber's agent spec. A workspace keeps named policies that agents follow with the provider policy; the policy is read when each call starts, and one in use cannot be removed
  • Built, on fiber v0.20.0. Policies live with the workspace settings, kept with -state=postgres. The refusal to remove one names only the agents on it the writer may read, and says the others are in projects they may not read (TestAModelPolicyInUseNamesOnlyTheAgentsTheCallerMayRead)
  • Call governance: the agent being called decides which agents may call it (anyone its spec allows, only those listed, or none) and when a call waits for a person (never, always, or unless the caller is trusted), who approves (roles such as manager and admin, or named people) and how long a call waits. A caller is only offered agents that take its calls. Each agent has an approval queue; a held call also waits in its task and in the approvers' inboxes
  • Built. Policies are kept with -state=postgres. Approval rides fiber's per-call approval hook
  • Agent marks: exact pixel footprints with room for the shared orb's halo and satellite, aligned in compact rows
  • Built on Humagen AgentOrb numeric sizes. The console gallery covers every activity at 12, 14, 16, 18, 24 and 32 pixels in clipped rows. Permanent workspace hue reservations (pkg/agentcolors) keep names distinct as agents are added and survive replay and restart on memory-backed state and Postgres. The API returns only readable names; a mark waits for its reservation before drawing its orb. See Stable agent colors
  • Console landing: a prompt-first Home page using the conversation's chat bar, with optional attachments and project selection before sending, and no agent menu. The former overview is removed. The root opens Home; chat has its own explicit address
  • Built, with the server's tag-only runs, POST /api/threads/{id}/share, GET /api/skills and GET /api/mentions (claude/chat-threads, claude/chat-skills). Home's chat bar starts a private conversation (POST /api/threads, private, in the picked project's general) and opens it at /conversations/{id}, where later messages are posted (POST /api/threads/{id}/messages). Completion replaces the menu of who answers: @ people, agents and mention kinds (@kind:, then its items), Tab or Enter to pick (apps/web/src/completion.ts, tags.ts). / at the start of the message or after a space opens a command menu over the same skills, fuzzy filtered with the match highlighted, a skill the message already names or one past the limit greyed with the reason, and a pick writes /name as a token in the box (commands.ts, DES-047). / is the only way the console offers skills: @ offers no skill and no @skill: or other kind over skills, $ opens nothing, the + menu's Skills write /name, and a posted message shows $name and @skill:name, which the platform still reads as quiet aliases, as /name chips (Mentioned, skillRefs). Nothing under the bar says who answers: an untagged message starts no run, and shows as posted. The + button (or Ctrl+/) opens a menu to attach files, mention agents and pick the project and channel. A picked agent is written into the box as @name at the cursor (the start of an empty draft), as @ completion writes it, and the agents checked in the menu are the ones the draft mentions (mentionsIn in apps/web/src/tags.ts), so deleting the words takes the agent off and picking a mentioned agent again takes its mention out. Only the project and channel show under the box. A message is sent as its text alone and its mentions route it by the tag rule, every agent it tags answering (TestEveryAgentAConsoleMessageTagsAnswers); an untagged follow-up runs nothing. A thread's agents and mode stay in the API, and an earlier selection keeps routing that thread's untagged messages, but the console no longer sets them; a move keeps them as they are. An answer's "Routed to" line is read from the run's routed, so it stays. Suggestions under the bar, ?agent= and Find Help's choice mention the agent the same way. A conversation that holds only runs (a schedule's, the analyst's, the API's) has the same + menu, its project fixed. Share and moving a conversation are offered to its starter by handle, as GET /api/me names the caller (handle), since a subject may hold an address the directory does not show. A conversation of runs from before threads stays at its address; a message posted to it makes it a room. Tested as DOM interactions (chat.dom.test.tsx, room.dom.test.tsx). Run permissions are enforced
  • Console Home under the chat bar: Needs you and What's new as two boxes from the shared Home model. Needs you lists the five newest things waiting on the person (GET /api/inbox?needs=true, through the adapter's notificationsOf), from whom and when, and in words when it is above normal ("Urgent", as the Slack Home says it too), with the inbox's open count in its heading and Open Inbox; What's new lists announcements (news=true, updatesOf), unread marked in words, with where each was posted and See All to the inbox's announcements, which the inbox also calls What's new. An empty box says so; a person with nothing in either gets one box saying what Home is for. Nothing in them animates
  • Built, tested as rendered markup and as DOM interactions (home.test.tsx, home.dom.test.tsx), and captured by make screens
  • Console layout check: make screens starts Humagen with the development sign-in, seeded agents and example data through the API, captures every page and tab at 390x844 and 1280x800 with an installed Chromium, and fails on horizontal overflow, anything past the 16px phone gutter, a control under 24px, a page without exactly one h1, or text over text in the main column (scripts/screens). CI runs it on pull requests that change the console or packages and uploads the screenshots. It also captures the chat's states, each a page and what a person does on it: @ completion open, the / command menu (chat-slash, chat-slash-picked), the + menu with two agents checked, the box with their mentions (chat-mentions), a private conversation answered, its Share dialog, a shared conversation, and answers routed to the selected agents; a menu or list that opens over the page (data-layer) is checked for overlap only against itself
  • Built. The checks are a pure function of the measured page, tested on their own. The agent status-badge case checks dark mode and enlarged text containment. SCREENS_SHOWCASE=1 make screens refreshes the eight committed showcase images after the layout checks pass, using the same seed and the existing console gallery for primitives and the approval card
  • Console menu: Home, New conversation, Inbox, then Work, Build, Watch and Workspace. An entry is hidden from someone who may not read what it opens
  • Built. Connections, Access and Limits open their Settings sections
  • "Why can I do this?": GET /api/access/explain and the Access panel. A sign-in keeps the grant behind each role, not the claims or the token
  • Built, tested. Sessions are in memory, so a restart signs everyone out
  • Local accounts with a first-user admin, for running without an identity provider
  • Not built. Without OIDC, use Tailscale Serve identity, loopback dev auth or the loopback mock provider
  • Model parameters on an agent (temperature, token and step limits)
  • Not built. fiber's agent spec has no fields for them
  • A stop control in the console conversation
  • Built beside the running turn. Stop Turn calls the existing API and waits for the recorded terminal state, with bounded polling and retryable errors. The queue waits for the actual ending
  • Skill consolidation
  • Not built
  • Sandbox: each conversation has a scratch directory that agents with the file tools read and write. It is opened as an os.Root, bounded in file size, count and total, and removed after 7 days untouched
  • Built, tested against traversal, absolute paths and planted links
  • Tools in a run's isolated instance (RFC 0004, layer 4): each turn claims an instance (orchagent/flow/isolation, a lazy lease per turn, never shared with another run or a called run, released however the turn ends). The file tools work in its work directory, loaded from the conversation's scratch directory and written back when it is released; a shell tool runs sh -c in its workload compartment; stdio MCP servers run in its connectors compartment with their credential in that command's environment, a session per run, closed with it. The sandbox System slot chooses docker (default, runtime runsc; runc only with insecure_development_runtime, which humagen start, make dev and Tilt set), local or unisolated, said at start, over playscape's pkg/isolate pool (orchagent/flow/isolation/isolate)
  • Built. Tested with a host-process test leaser under the race detector (one lease per run, release on success, failure and cancellation, files round trip, path rules and planted links, the shell refused unisolated, a failed lease failing closed, stdio servers per run in the connectors compartment) and against Docker 27 with runc: the shell cannot read host files beside its work directory, write the root, reach the network or run as root; a link it plants is not followed by the host; the connectors compartment cannot see the work directory, and the workload cannot read a stdio server's credential. Not tested on runsc (gVisor is not installed here). Instances have no network unless the egress slot is gate (see the egress row). /project and /me are each instance's own directories (playscape Instance.Project() and Me()), filled with the run's memory at the lease and read back at the release. A person's own tool servers pinned in the run context (runctx.Context.ToolServers, HTTPS) are not connected yet: reaching them from the connectors compartment needs the egress gate
  • pkg/blob: put, get, stat, delete, list behind one interface, on disk, in memory, in an S3-compatible bucket (AWS, MinIO, R2) or in Google Cloud Storage, with a conformance suite a new backend must pass
  • Built. The S3 store is chosen with -storage=s3 and the -s3-* flags, credentials from HUMAGEN_S3_ACCESS_KEY_ID and HUMAGEN_S3_SECRET_ACCESS_KEY or the AWS default chain. It passes the suite against a fake S3 in the unit tests and against a real S3-compatible gateway (versitygw) through TestS3Live, which runs when HUMAGEN_TEST_S3_BUCKET is set. Not run against AWS, MinIO or R2 themselves. The GCS store is chosen with -storage=gcs and the -gcs-* flags or blobs.kind: gcs, credentials from Application Default Credentials (Workload Identity on GKE, GOOGLE_APPLICATION_CREDENTIALS, gcloud). It passes the suite against a fake of the Cloud Storage JSON API in the unit tests; TestGCSLive runs it against a real bucket when HUMAGEN_TEST_GCS_BUCKET is set, and has not been run
  • pkg/artifacts: published files with a sniffed type, sha256, and a version per title per conversation
  • Built. The index is kept with -state=postgres, the bytes are in the blob store. An id that was published is never issued again, so no blob key is reused. Unit tested on its own: titles, versions, tenants, paging, usage, and concurrent use under the race detector
  • Publishing: the publish_artifact tool copies a sandbox file to storage and reports it on the run's stream, where the console shows it as a card
  • Built
  • Web search and fetch: the web_search and web_fetch tools read the public web from the server (pkg/webtools), with no key
  • Built. Internal addresses are refused when the connection is dialled; unit tested with local servers, and checked once against the real search and a real page (HUMAGEN_WEB_LIVE=1). Not yet checked in a live agent run. The search has one backend, which may refuse automated clients; PDFs are not read
  • Native deliverable production and exact revisions
  • Built. file_write native JSON produces editable DOCX/PPTX/XLSX and actual PDF in the existing bounded sandbox; publication retains immutable versions. file_read reads an exact artifact version only in the authoritative run's conversation. The workbench exports that immutable native model to PDF through a read-confined route; PDF refuses unsupported Windows-1252 characters and overfull slides. Office outputs independently opened, edited and re-saved; PDF independently parsed in tests
  • Authored outcomes and retained evidence
  • Built. Explicit record_outcome records bounded recommendation/decision/update, decisions and next action through the action projection, separate from execution and approval records. Citations persist on runs independently of journal retention. Shared primitives render outcomes; Redirect prepares human intent without sending it. Memory/Postgres restart and UI interactions are tested
  • Storage limits per workspace, project and agent, as max_storage on a policy
  • Built. A project's use is what its whole subtree holds, and a file counts toward every ancestor's limit. A refusal raises a message in the inbox
  • Artifacts page (/artifacts, one artifact at /artifacts/{id}): delete a version, image preview, over the limit, See more
  • Built. Tested through the API (TestStoragePageFlows), as rendered markup (storage.test.tsx), and by clicking through it in happy-dom (storage.dom.test.tsx). Not checked in a real browser
  • Downloads: tenant and right checked on every request, always an attachment unless an inert type is asked for inline, never HTML or SVG inline
  • Built, tested
  • Built-in agents: humagen-writer writes a document and publishes it. Provided by the platform, not editable, present only when the server is given -builtin-provider and -builtin-model
  • Built, one of seven (the analyst, builder and four review agents are below). The document, analyst and builder handles use humagen-*; compatibility definitions preserve old keys and pinned revisions, tested across restart in memory and Postgres. The server refuses a save, and the console's agent page opens it read only with a note saying why; its memory can still be changed, and it can still be the workspace default. Tested in happy-dom (agents.dom.test.tsx). Not run against a real model here: no provider key was available
  • Called agents are runs: an agent that tags another starts a run with its own id, events and record, in the caller's conversation and sandbox
  • Built, on fiber's WithDelegator hook
  • Run ids are the runtime's, derived from the workspace and the tag id together, so two workspaces offering one trigger id get two runs. Every index, route, ledger entry and grant uses the id the runtime returns
  • Built on fiber v0.7.0 and later, tested with two workspaces reusing one tag id and one Slack event id
  • Two lifetimes for a called run. Attached (call_agent, subagent mode): ends with its caller, and the caller is not done until it is. Delegated (call_agent, delegate mode): independent, and its answer goes to the inbox
  • Built, tested three levels deep under the race detector
  • Stopping a run: POST /api/runs/{id}/stop asks the runtime to stop it and everything attached to it. The model call in flight is cancelled, the run ends stopped with its partial answer and cause, and what it delegated keeps running. See Stopping a run
  • Built on fiber v0.8.0's runtime.Stop, recorded in the run ledger, tested with scripted models under the race detector, three levels deep, and against a completion racing the stop
  • A place is always kept for work that waits on nobody, so runs waiting on each other cannot fill every place and hang
  • Built. With Concurrency 4 by default, three runs may wait at once and a fourth is told no
  • Publishing that waits for approval
  • Built: list publish_artifact in an agent's approvals. Nothing is stored until a person approves, a denial publishes nothing, and an approver who edits the arguments publishes what they approved. Tested with scripted models
  • Built-in review agents: type @code-reviewer review PR #12 in an ordinary conversation, with repository context or a supplied diff. code-reviewer checks correctness and delegates through its spawn allowlist and the existing call path to security-reviewer, architect-reviewer and qa-reviewer as needed, then merges findings into one verdict. All four have only file and GitHub read tools; specialists cannot spawn. They use the configured builtin provider and model, and platform-owned definitions are revised on drift
  • Built. TestBuiltinNamesAndReviewGrants checks all seven names, read-only grants, spawn edges, wire validation and specialist call admission; TestBuiltinReviewGrantsFollowThePlatform checks grant restoration and idempotence. Not run against a real model here
  • Built-in agents, when the server is given -builtin-provider and -builtin-model: humagen-writer (documents), humagen-analyst (runs_summary, list_alerts, and files for reports) and humagen-builder (list_agents, read_agent, save_agent). Every save waits for a manager or an admin; only the builder may save, and it may grant only file tools and ask_person. Package agents can be customized and reset like other agent revisions. The console offers them as starters on a new conversation, from Monitor and from Agents
  • Built, tested with the offline provider (TestBuiltinAnalystAndBuilder, TestRunsSummaryTool, TestSaveAgentTool, TestAgentPackageUpgradeCustomizeReset, TestPackageAgentsCanBeCustomizedAndReset). Not run against a real model here
  • Parking a run on a person: approvals of tool calls, choices and replies (ask_person), on fiber v0.11.0 with the run queue as waker, Humagen's roles, and a question deadline. See People in the loop
  • Built. Answer recording and inbox settlement are serialized so resumed or terminal events cannot drop surface attribution. Tested under the race detector with scripted models: each kind, who may answer, a requester refused, two answers at once, expiry, stop while parked, a called run's question, usage counted once, tenant isolation. Not run against a real model here: no model key was available
  • Agent editor: may ask a person, approve a tool first, who may approve, self-approval, who may answer
  • Built. Not checked in a browser
  • Run manifest: one JSON document of a run, every run under it, each pinned definition, every event with its body, and the tree's usage
  • Built, from the journal. A run older than the journal's ring comes back marked incomplete
  • Token counts, context window and cost per run: usage on the run (own, rolled-up attached runs, total, context), live while it works and the runtime's record once it ends, recorded once whatever is redelivered
  • Built, tested with redelivered events, a reconciler pass, a stopped run and a three-run tree. A run ended from the ledger carries the usage the runtime recorded in the write that ends it, and is not ended in a pass where that record cannot be read. Context fill is the latest call's prompt against the window saige's catalog declares; a model with no declared window shows tokens only
  • Leases on real cost: a called run is held to its lease by what it spends and what it has handed on, and settles with its caller when it ends, climbing past a caller that settled first
  • Built, tested, with a grant made before the caller's own call was counted and a call that ends after its caller. An API caller still names a lease; an agent's own calls lease half of what is left
  • Usage in the Slack app
  • Not shown, on purpose: the console shows none on a turn either. A Humagen usage summary would let both show it
  • Uploading binary files (PDF, images) to knowledge or a message
  • Not built. Files are read as text in the browser
  • Evals against a knowledge variant
  • Not built. Evals search the current view
  • Eval history preserves original replay access after suite edits
  • Built. Per-run dependencies survive save, restart and interrupted-run cleanup. HTTP and builder history recheck current source and run access; unknown historical provenance fails closed. Covered by TestHistoryRetainsExecutionAccessAcrossSaveRestartAndInterruption, TestEvalHistoryRetainsOriginalAccessAfterCasesRemovedOrReplaced, TestEvalHistoryRechecksOriginalRunAndSourceAccess and TestEvalHistoryRoutesDoNotDeclassifyRemovedPrivateReplay
  • Stable instruction snapshots bound text, layer metadata and encoded bytes
  • Built. Unicode character limits and the persisted byte bound are checked before pinning and on read. TestLayerLabelsAndEncodedSnapshotsAreBounded and TestBoundedSnapshotsAlwaysRoundtripIncludingEmptyWorkspaceOrigin cover malformed labels, JSON expansion and accepted roundtrips
  • Summarizing history
  • Not built. Long conversations are truncated to the limit, oldest turns first
  • Resource link rules and project fork snapshots
  • Durable bounded rule matching and ambiguity fallback in pkg/sourcelinks. Recorded fork snapshots restore only immutable Off rules, without credentials or live bindings. Configuration and connector wiring remain under implementation
  • Conversation-first collections, browser and protocol expansion
  • Proposed next backend delivery: tenant-scoped Corpus, CorpusRun, stable CorpusFile, immutable FileVersion, RunFile membership and version-bound chunks with derived vector/fact provenance. Verified pull planning separates content, metadata, ACL and deletion changes; bounded resumable attempts stage complete manifests before atomic last-good publication, with independent authorization/cache invalidation. Preserve Source API compatibility and compose Saige SyncSource/retrieval. Browser and A2UI/A2A/AG-UI adapters remain planned; native AgentSpec, pkg/call and human-reviewed publication remain authoritative. See the corpus and workspace design.
  • Source lifecycle storage and publication safety
  • Durable bounded refresh attempts, atomic last-good copies, failure causes and stale stop rules are implemented in pkg/knowledge. Native Drive/Notion boundaries, per-reader references, lifecycle APIs, selected resources and recorded dependencies use the existing tenant and project checks. Project visibility does not grant upstream file access. Provider collection and private current-reader queries remain separate; retained external source history cannot be published raw. Transport, persistence, HTTP and UI fixtures exist; source-access and full Go race regressions pass; final browser/CI verification is pending. Live provider-account trials remain unverified. See sources.md.
  • Knowledge retrieval inside a run: an agent's declared sources ground each turn in its tenant
  • Built for authored local collections through BM25, with trusted evidence bound to model input. External retained collections do not enter automatic grounding; provider access requires the explicit private current-reader source tool. Saige vector/graph composition remains planned, not a hidden fallback. See sources.md and the conversation-first design.
  • Knowledge sources inherited down the project tree: a project, the workspace included, names at most 8 of the workspace's knowledge sources, and a run filed in it is grounded in them and in those of every project above it, nearest first, each once, at most 16, besides its agent's own. GET, PUT /api/projects/{name}/knowledge. The Platform document's knowledge, on the workspace and on each project, is the file's when set
  • Built and tested. Pinned in the run's tag at admission (_warp.sources, a key fiber keeps out of the prompt) and added by Humagen's executor seam (callExecutor.resolve) to the request's copy of the pinned revision's Sources before fiber's knowledge hook reads them; fiber's one part is keeping a _ key out of the prompt (fiber#43). A run in a sub-project is given its parent's sources and never a sibling's or a child's, and a caller cannot name its own (TestARunIsGroundedInTheKnowledgeOfItsProjectAndThoseAboveIt); a called run is given its root's (TestACalledRunIsGivenItsRootsKnowledge); a housekeeping run none (TestAHousekeepingRunIsGivenNoKnowledge). A run keeps what it was accepted with across a change to its projects and a restart, on memory and on Postgres (TestARunKeepsItsKnowledgeAcrossAnEditAndARestart). Naming takes an owner and knowledge:read, and only sources the workspace has, and a reader without knowledge:read is shown no source's name, in the knowledge route, the project's record or its history (TestAProjectsKnowledgeIsNamedByOwnersAndShownToWhoReadsKnowledge, TestNamingAProjectsKnowledgeTakesKnowledgeRead); a hidden project's answers as a missing one's (the confinement sweeps). The console shows them on a project's Context tab, in a Knowledge section: an owner with knowledge:read picks from the workspace's sources, everyone with it sees what runs there are grounded in and where each comes from, a list the file sets turns read only, and a reader without it sees no section (the knowledge: tests in apps/web/src/projects.test.tsx and the the Context tab knowledge tests in apps/web/src/projects.dom.test.tsx). Deleting a source a project names is refused, naming the projects the caller can see; a project hidden from the caller neither holds it up nor is named (TestASourceAProjectNamesIsNotDeletedFromUnderIt). The pin is a private key of the tag (_warp.sources), which fiber keeps out of everything a model is sent (TestARunIsGroundedInTheKnowledgeOfItsProjectAndThoseAboveIt)
  • Skills and mention kinds: a project, the workspace included, declares at most 32 skills (named instructions: a SKILL.md's name and description, an argument hint, instructions of at most 8,000 characters), and a message posted in it names one with $<name> or @skill:<name>; it can name its project's and every project's above it, nearest first, never a sibling's or a child's. The runs the message starts are told to use them, and a console message that names a skill and tags no agent asks the agents available whether to join, each that joins told to use it (startsForSkills), unless posted only; a client's message is answered by its default with the skill (TestOnASurfaceASkillIsAnsweredByTheDefault). A skill nobody on the chain declares refuses a console message with 400 before anything is posted. @<kind>:<name> resolves the kinds the Platform document declares (workspace.mention_kinds: experts, skills, a role, or people) besides the built-in sme and skill. GET, PUT /api/projects/{name}/skills; GET /api/skills?project=; GET /api/mentions?project=[&kind=&q=]. The Platform document's skills, on the workspace and on each project, is the file's when set
  • Built and tested. The grammar reads $ only before a whole skill's name, so $5 and $PATH stay text, and, in a message posted through the API or the console, / at the start or after a space before a whole skill's name that is on the chain, so a path or a slash that names no skill stays text (TestASlashCommandNamesASkill, TestSlashCommandsCostBoundedLookups, TestASlashCommandIsPinnedAsItsSkill); Slack and GitHub keep their client's commands, at most 4 skills a message, each looked up once (TestSkillsAndMentionKinds, TestSkillsAndKindsCostBoundedLookups). Pinned in the run's tag when the message is accepted (_warp.skills, with the instructions, a private key fiber keeps out of the prompt and of what a run stopped before it starts records) and put ahead of the turn by Humagen's executor seam (callExecutor.resolve), which takes the key out of the request's copy of the meta so fiber does not write it into the prompt (TestASkillAMessageNamesIsPinnedAndToldToTheAgent); admission drops it from every tag but a root run the platform's API raised, so no other origin, caller or calling agent can add instructions (TestOnlyAPersonsMessagePinsSkills). A Slack client's command named for a skill uses it, answered by the default as before (TestASlackCommandNamedForASkillUsesIt). A role kind notifies the role's holders in one shared mention, and is refused in a private thread they cannot read (TestAMentionKindResolvesAsItSays, TestARoleIsNotToldInAPrivateThread); in a private thread an expert tag tells only the experts taking part, invites none, and says the others were not told (TestExpertsAreToldOfAPrivateThreadOnlyWhenTheyTakePart, on memory and Postgres). A retry keeps a client command's skill (TestARetryKeepsACommandsSkill). A run started with POST /api/runs is given the skills its message names by the same grammar and lookup, the published revision only, and an unknown or unpublished name answers 400 with nothing started; tags of agents and people in it stay text (TestARunIsGivenTheSkillsItsMessageNamesAsAThreadMessageIs, TestParseSkillsReadsOnlyTheSkillsATextNames). Completion is by prefix, at most 20, people only with people:read (TestMentionKindsComplete); a hidden project answers as a missing one on every route (TestAProjectsSkillsAreDeclaredByOwnersAndListedWhereTheyAreSeen, the confinement sweeps). Kept on memory and Postgres (TestSkillsSurviveARestart). Only the project's own record keeps the instructions; a project's view, list and history carry each skill's name, description and hint (TestAProjectsViewAndHistoryStaySmallWithLargeSkills, TestAChangeRecordsSkillsWithoutTheirInstructions). An answer or an inbox reply that names a skill starts no run (TestAReplyThatNamesASkillStartsNothing). Not built: skills read from SKILL.md packages on disk. The console completes $ and @kind: from these routes (see the console landing row)
  • MCP servers as tool providers: declared per workspace in the spec (tools, kind mcp, over HTTP or stdio), or by a program with humagen.WithToolProvider, recorded at start with the tools accepted from each pinned by schema hash, and granted to an agent as mcp:<name> or mcp:<name>:write. A provider is reached with one shared credential (credential_scope: shared, the default), a reference read when a session opens, or with the credential of the person a run acts for (credential_scope: person), on fiber's mcptools.Grants with Humagen as its PersonResolver. A person-scoped provider names no shared credential, is seeded from each tool's declared form since it is not dialled at start, and a person with no credential gets no tools from it while the agent is told they have not connected one
  • Built on fiber's toolprovider and mcptools (per-person credentials since fiber v0.22.0). The spec's documents are tested, and agents are run against a fake MCP server over streamable HTTP: two people each reach one provider with their own credential, one by reference and one by stored value, on memory and on Postgres 16; a person with none, a run for nobody and a machine's own run reach nothing, including after a provider moved from shared to person, whose old credential is never sent again; each token stays out of answers, run events, model requests and the log (internal/platform/credentials_test.go). The records are in memory and made again at each start, unless a program passes humagen.WithToolProviderStore. Two people in one thread can be offered different tools, so the thread's prompt cache misses when the person changes. Not run against a real MCP server
  • Who a run acts for: the actor's user on the run's record, set when it is accepted. The signed-in person for the console and the API, and for Run Now when they wrote what the schedule runs (whoever last changed its text, or its creator, unless someone else has since chosen its agent or its project), else nobody; the mapped person for a surface's act_as, and for a message the Slack app posts for them into a Humagen thread, as for any message; for a Slack connector's run the one person the team's enabled Slack clients map the Slack user to. A machine as itself, a schedule on its own clock, an eval, housekeeping and a called agent act for nobody, and a trigger's tag cannot name anyone
  • Built, tested: the Slack app's run for a mapped Slack user reaches the tool with that person's credential and its own run with nothing (TestTheSlackAppsRunsActAsTheMappedPerson), Run Now acts for the presser only on words they wrote (TestRunNowActsForThePresserOnlyOnWordsTheyWrote), a Slack connector's run acts for the mapped person and an ambiguous mapping for nobody. A called agent acting for nobody is a limitation: it gets no tools that act as the person who started the tree. GitHub runs act for nobody, as no client maps GitHub logins
  • A person's own tool credentials (pkg/credentials): GET /api/me/credentials (runs:read), PUT and DELETE /api/me/credentials/{provider} (runs:write), and Your connections in the console (/connections). A client's machine lists, connects and disconnects them for a person its people map names, with act_as_client and act_as_user, the person holding the route's permission themselves (as /agent connections in the Slack app does, TestSlackConnectionControlsActOnlyForTheirMappedPerson); another machine, or a person the client does not map, is refused. A reference (env:, keychain:, op://) only the person's own under the starts the operator lists for the workspace (person_refs, each naming its person with {subject}, no two sharing a place), of which only the reference is stored; a value only where the workspace allows it (workspace.person_credentials.values), stored in the secrets store client secrets are kept in. At most 64 per person
  • Built, tested: the store against memory and Postgres 16 with a restart and a failed write, a platform restart on both (TestThePlatformSurvivesARestart), the routes in the contract test (a stored value never appears in a response), a person refused another's reference (TestNobodyConnectsAnotherPersonsReference), and the page's parts as static renders. A value is not encrypted by humagen: with -state=postgres it is in the database as written. Nothing is listed in person_refs by default. The page was not checked in a browser
  • Tools that act as a person through Slack and GitHub themselves
  • Not built. Slack and GitHub credentials are held per client, see above: the surfaces' own actions and deliveries use their client's token, whoever the run acts for
  • OAuth to third parties
  • Built: encrypted actor-bound OAuth with PKCE, public discovery, DCR or issuer-bound registered clients, rotating refresh leases and exact API audiences. Native Drive/Slack/BigQuery consent remains separate from MCP. Connections projects actual scopes, visible configured uses and persisted access observations. Confirmed credential rejection requires reconnect and raises owner attention. Offline boundary/race/DOM tests cover these paths; live provider consent remains unverified. See Connections.
  • Schedule delivery: where a scheduled run's answer goes, set as deliver on the schedule and pinned on each run it raises
  • Built for deliver: inbox and deliver: project. Inbox: a completed run's answer is sent to the schedule's creator as a result only they see, from the clock or a person's run now (TestAScheduledAnswerReachesItsCreator). Project: see the recaps row. An answer of NONE sends nothing. A run now that acted for the person who pressed it, and whose answer may hold what their own credentials reached, is delivered to them alone, never posted, held for the owners or sent to someone else who created the schedule (TestAScheduledAnswerThatMayHoldAPersonsCredentialIsTheirsAlone). Slack, email or another system: not built, needs connections
  • Scheduled agents in projects (recaps): a schedule with deliver: project posts each answer in its project as an announcement from the agent, the first line its subject and the run linked; agent_posts (publish or review, review by default at the workspace and in company projects) holds it instead as a draft addressed to the project's owners, who publish it (posted from the agent, recording who approved it) or discard it. project_changes(days) reads the run's own project and the projects below it (runs by agent and project, threads started and settled, announcements, files published, notes kept, schedules created or changed, the projects' own record changes; 50 rows a section, 32 KB in all), and runs_summary(project) counts a subtree; both are granted to humagen-analyst. File-managed schedules (projects[].schedules, agent_posts), the project's Schedules tab and Add Weekly Recap
  • Built, tested: a team project's post reaches exactly its members, NONE posts nothing, a draft is shown only to an owner and a member cannot publish it, publishing twice posts once, a post past 20 a day or 20 open drafts goes to the schedule's creator saying why (TestARecapIsPostedInItsProject, TestAReviewedPostWaitsForAnOwner, TestARecapPastTheDailyLimitReachesItsCreator), project_changes reads only its subtree and names an agent whose home changed only when everyone the recap reaches may read it (TestARecapNamesOnlyTheAgentsEveryoneItReachesMayRead), and names each person by what the platform calls them, never by a subject that holds an address (TestARecapNamesPeopleAndNeverAnAddress), a file schedule is the file's (409 on a change or delete through the API, released when it leaves the file, its agent available in its project or the start fails). A schedule in the file cannot deliver to an inbox: it has no creator. A recap at the workspace has no project_changes, which needs a project
  • Call tool inside the sandbox
  • Not built. Calls are made through the API
  • A remote sandbox driver: each run's instance started on a sandbox host, without Humagen holding the Docker socket (which is root on its host)
  • Built. sandbox.docker.host and tls_dir drive a daemon on another machine through playscape's docker driver (pinned at a pre-release commit until playscape tags it): the work directory is a volume there and the file tools reach it through docker exec. Tested by playscape's conformance suite against a daemon reached through its endpoint, and here by spec and flag tests. Not tested against a real tcp:// sandbox host from Humagen. The image now carries the Docker CLI (no socket)
  • A Kubernetes sandbox driver: each run's instance as its own pod
  • Not built. The chart and the compose stack set unisolated explicitly
  • Returning a subagent's answer to its caller
  • Built for a call made by tagging: the answer is the tool's result. A subagent that was stopped returns an error saying so, not its partial answer. A call made through the API is not returned to the caller's model
  • Cancel propagation down a tree
  • Built through attached runs: each is asked to stop through the runtime, at the request and again when the runtime cancels the delegation it was waiting on, and keeps its own partial answer. Delegated runs are not touched
  • Access intersection across a call
  • Not built
  • pkg/inbox: one server inbox of messages with typed parts, per-person read state, paging, and a record of changes that rebuilds it
  • Built. Kept with -state=postgres: each change is written before it takes effect and replayed at start, and one that cannot be written is undone and not announced. Retention drops what was settled and its records (see the inbox retention row), so the record holds what is kept. A message's history (GET /api/inbox/{id}) shows each reader what changed it for everyone and their own marks, never another reader's reads or hides, at most 100 changes, the newest kept (TestAReadersOwnMarksStayOutOfAnotherReadersHistory)
  • What lands in the inbox: fired alert rules, failed runs no rule caught, proposed memories, reached limits, the answers of delegated runs, and published artifacts
  • Built. An alert and its message are one state: settling either settles both. An artifact's message is there to be read: a new version withdraws the message about the one before, and deleting a version withdraws its message (TestPublishingTellsTheInbox)
  • Inbox templates: each message is laid out by its template (alert, approval, question, failed run, memory, limit, artifact, result, note), named by the server's kind or read from its parts (messageTemplate). The console's list puts what needs a person above updates, filters by kind with chips, and reads a message as an email does: subject, sender, then its parts, with Snooze and Dismiss in the header
  • Built, tested as rendered markup (ui.test.tsx) and checked in a browser through the gallery, dark and light, wide and phone width
  • Resolving in the inbox: acknowledge, retry a failed turn, keep or discard proposed memories, raise a limit, dismiss, snooze
  • Built. Each needs the right for the thing it does, and a second resolve returns the first outcome. A retry acts for whoever the turn acted for, so a turn that acted for a person is retried only by them, and each person's retry is a run of its own. It asks the agent that answered the turn again, also when the turn tagged no agent, so a default changed since does not change who answers it (TestARetryOfAnUntaggedTurnAsksTheAgentThatAnsweredForTheSamePerson). It is filed where the conversation is, a retry of the first turn included, and it is refused when that agent is no longer available there (TestARetryIsRefusedWhereTheConversationIsFiledOnceItsAgentIsNotAvailableThere). The Slack app's Retry and Resume follow the same rule, and a console conversation offers Retry and Regenerate only on a turn that acted for the reader, or one they asked under their own name, with words of their own, before Humagen recorded whom a run acts for, and files a retry of its first turn in the conversation's project (apps/slack/src/app.test.tsx, apps/web/src/chat.dom.test.tsx). Anyone else reading a person's failed turn in the inbox is told only that person can retry it, and is offered no Retry (ui.test.tsx). A proposal for a project's notes needs what the project's memory routes need: projects:write and owning the project, and projects:govern as well for the workspace's and a company project's. Retrying a failed turn filed in a project also takes a member of it, as starting one does, so a viewer is not offered Retry
  • Approve, deny, choose and reply parts for a run waiting on a person
  • Built. Raised from lifecycle.parked, answered through runtime.Answer from the inbox, the run, or Slack, each action needing runs:write, and settled in place when the run resumes, expires, stops or ends. A choice or reply in a run that uses the credentials of the person it acts for, or that such a run called, is addressed to and answered by that person alone, also when it asks the project's experts, and anyone else approves or denies its calls only as asked, without an edit or a note (TestOnlyThePersonARunActsForAnswersWhatItAsksWithTheirCredential, TestAnApprovalCarriesNoOneElsesWordsToAPersonsCredential, TestAnApprovalCarriesNoOneElsesEditToAPersonsCredential, TestACalledRunIsAnsweredByThePersonWhoseCredentialsItsCallerUses, TestAnExpertDoesNotAnswerARunCalledByOneWithAnotherPersonsCredential). When the spec's answerers, or a called agent's, leave that person out, nobody may answer, and the run waits until the question expires or the run is stopped (TestAnswerersThatLeaveOutThePersonLeaveNobodyToAnswer, TestACalledAgentsAnswerersThatLeaveOutThePersonLeaveNobodyToAnswer). This covers what a run is answered, not what a later turn reads: the next turn of the conversation is sent earlier turns and their answers, whoever asked or answered them, in a transcript that does not say who, so someone else's reply to an earlier turn that reached no person's credential reaches the person's tools when they continue. Shown by the shared adapter as Humagen's cards on the run and in the inbox alike, with a parity test per kind
  • Messages addressed to one person, one role, a project's members or its owners
  • Built. Questions are addressed to the principals and role:<name> entries that may answer, never to the requester of an approval, and a mention to the person a message tags, or the role an expert entry names. An announcement is addressed to project:<name>, which reaches the members of the project and of every project below it, and a proposed project note to owners:<name>, which reaches whoever owns the project; both are decided from the tree at each read, so a revoked membership hides them at the next one. The event stream carries a notice only to a reader the message is for. Every other kind still goes to everyone who may read it
  • Project inboxes and announcements
  • Built. A project's inbox is every message filed in it (GET /api/projects/{name}/inbox, with its sub-projects on request), read by everyone who can see it. An announcement is one broadcast message (POST /api/projects/{name}/announcements, by the role the project lets announce, owner by default; at most 20 a project and 200 a workspace a UTC day, counted under the inbox lock), which each reader hides ("Hide for Me") or snoozes for themselves and brings back ("Show for Me", POST /api/inbox/{id}/unhide, with hidden on the message saying the copy is set aside for them alone), rebuilt on replay and kept out of everyone else's history of it, which whoever posted it has read from the start, and which its author or an owner withdraws for everyone from the message, recorded with who, whether or not they hid it first. Whatever a project's inbox shows a reader they may open, mark, snooze and hide through the inbox's own routes, a viewer who is not a member and a member who muted it included, and they are still not sent it. Platform.Announce is the one way in, for people, for scheduled agents and for Humagen's release notes. Muted projects (muted in preferences) stay out of a person's own inbox and in the project's; the workspace is never muted. GET /api/inbox/count adds updates, so announcements never grow the badge. GET /api/inbox?needs=true pages what open counts, posted announcements left out before the page is cut and an agent's draft kept, which the Slack Home's Needs you reads, and news=true pages what updates counts, the posted announcements alone, which What's new on Home reads in the console and in Slack. The console opens a project on its Inbox tab and shows What's new on Home. A client's machine is shown its own client's delivery receipts in a project's inbox, as wherever it reads a message, and nobody else any. Posting from a scheduled agent and its drafts are in the Scheduled agents in projects row, and Slack delivery to a bound channel in the Slack and GitHub coworking in projects row. Tested in pkg/inbox, internal/platform and internal/httpapi (TestAnAnnouncementReachesTheMembersOfItsProjectAndBelow, TestAnnouncementsNeverGrowTheBadge, TestHidingAnAnnouncementHidesOnlyTheReadersCopy, TestMutingKeepsAProjectsNewsOutOfOnesOwnInboxOnly, TestAProjectsInboxIsReadByEveryoneWhoSeesIt, TestWithdrawingAnAnnouncementOneHidWithdrawsItForEveryone, TestAReaderBringsBackWhatTheyHid, TestThePosterHasReadWhatTheyPosted, TestAnAnnouncementIsReadByItsAuthorAndAHiddenOneComesBack, TestNeedsLeavesOutBroadcastsBeforeThePageIsCut, TestNeedsAndNewsPageWhatOpenAndUpdatesCount)
  • Release notes in the workspace's inbox
  • Built. workspace.release_notes: true in the Platform document (off by default) posts the running release's feat entries, the Breaking and Features groups of the CHANGELOG.md the binary embeds (the module root package embeds it, internal/release reads it), in the workspace's own inbox as an announcement from Humagen (From{system, humagen}), keyed release:<version> and posted once (inbox.Store.PostOnce, checked under the inbox lock, whether or not it was withdrawn since or dropped by retention). 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. The release is the version a release build stamps with -ldflags, else the module version Go records for Humagen, in Humagen's binary or in a program that imports it; dev, a local build and a pseudo-version post nothing, and so does a release of fixes alone. Tested on the release tool's real format in the embedded changelog, where 0.15.0's one entry is a breaking feat (TestTheEmbeddedChangelogReadsAsReleaseNotes, TestAReleaseIsItsBreakingChangesAndFeatures, TestTheTextFitsItsLimit), which version a build runs (TestTheRunningRelease), posted once across a withdrawal and a restart on memory and on Postgres 16 (TestPostOnceNeverPostsAKeyTwice, and TestReleaseNotesArePostedOnceAcrossRestartsOnPostgres, which starts Humagen five times on one database: off, on, on again, as a dev build and as a release of fixes), off by default, posted for a release of breaking changes alone, and nothing for a dev build or a release of fixes (TestReleaseNotesArePostedWhereTurnedOn), and read by everyone in the workspace, in What's new and the workspace's inbox, hidden by one reader for themselves and withdrawn by an owner (TestReleaseNotesReachEveryoneWhoReadsTheWorkspace). The Slack app catches up on a bound project's announcements each time its event stream opens, so release notes, posted before it connects, reach a channel bound to the workspace's general before that start, and a reply under their post starts a thread seeded with them, from Humagen (TestAReplyToReleaseNotesStartsAThreadSeededWithThem, TestReleaseNotesSeedAThreadAsTheSpecSays, announce.test.tsx, room.dom.test.tsx)
  • Inbox retention and per-reader counts
  • Built. workspace.inbox_retention in the Platform document (90d by default, at least 7d, at most 100 years, whole days or a duration) is how long a workspace's inbox keeps what was settled for everyone. At start and every hour, inbox.Store.Retain drops each message resolved, dismissed or withdrawn before the cut with no question a run still waits on, and every change about it, from memory and from the state store: a step deletes the records and writes the tenant's cut (the last id issued, and the keys of what was posted once) in one write of at most 5,000 operations including the cut, and the inbox changes only once it is written. A message with more history is named in the cut while later steps clear its remaining records; replay skips those records across an interrupted cleanup. Older broadcast keys are kept conservatively because their records do not distinguish ordinary posts from PostOnce. Nothing open or snoozed is dropped, nor an announcement open for anyone. No id is issued again and no release:<version> posted again, after a restart too; receipts and keys of what is kept still find it. Count (the badge and updates) is added up from counters kept as changes apply and rebuilt on replay: the open messages in buckets alike in kind, addressing and what they are about, each asked of the read rule once, less what each reader read or hid, plus the snoozes whose time came; it reads no settled message. Tested against a scan of every message over randomized raises, reads, hides, unhides, snoozes, resolves, withdrawals, receipts, broadcasts to projects a reader is in and not in, mutes, kinds a reader may not see and retention cuts, with a restart halfway and at the end, on memory and on Postgres 16 (TestCountsAgreeWithAScan, TestACountAsksOnceForMessagesAlike); what is dropped and kept, ids, receipts, keys and release keys across a restart (TestRetentionDropsOnlyWhatWasSettledBeforeTheCut); receipt reuse in delivery order across retention and restart (TestRetentionRebuildsKeptReceiptLookups); steps, a step that cannot be written, long histories across interrupted cleanup, empty inbox cleanup and legacy keys (TestRetentionWritesInStepsAndAFailedStepChangesNothing, TestRetentionBoundsALongHistoryAcrossRestarts, TestRetentionFinishesAnEmptyInbox, TestRetentionKeepsLegacyPostOnceKeys, TestARecordedReleaseIsPostedOnceAfterRetention); each workspace's own retention, the default and the least, at start and across a restart (TestEachInboxKeepsWhatWasSettledForItsRetention, TestAStartKeepsEachInboxForItsRetention, TestAnInboxRetentionIsDaysOrADuration). The inbox is still held whole in memory, and once a pass has cut the record, a build from before it cannot read it (docs/architecture/projects.md, Phase 9: retention)
  • Alert delivery outside the console
  • Not built
  • OTel export
  • Not built. Traces are rebuilt from the journal
  • Evals that run on their own, on a schedule or on each revision
  • Built: leader-driven schedules, deterministic checks on ordinary completed runs, and sampled gates for agent/shared-prompt revisions. Recorded replay rechecks current person and source authority before admission and around each case. Builder scorecards require reviewed application and an explicit reason for a measured regression; incomplete checks fail closed. Isolated race tests cover gates, privacy, replay, prompt pinning, setup isolation, and structured review format. No model judge or live provider validation is claimed
  • Model-graded evals
  • Not built, on purpose for now: every check is exact
  • Email notification delivery
  • Built. Optional operator-configured SMTP with verified TLS, exact tenant/subject recipient mappings, current standing policy and read confinement. Personal opt-in and per-kind settings default off; digest and quiet hours are rechecked before retry. Independent durable email acknowledgments survive replay and use inbox retention. Consent uses a read version and private audited mutation; no mailbox is exposed by the API. See email notifications. Tested through a real loopback SMTP relay and memory/Postgres delivery, replay, revocation and HTTP cases.
  • Email connector and Jira wiring
  • Not built
  • Remote execution nodes, peer connector
  • Not built
  • pkg/state: one record store for Humagen's own stores, by namespace, tenant and key, in memory or in Postgres (one table, migrated by OpenPostgres), held to the statetest suite, with Retry, Table.Update, Table.All and a tenant directory (state.Tenants)
  • Built, tested against both backends on Postgres 16. Any number of processes may open one database: OpenPostgres takes no lock (TestPostgresTakesNoLock)
  • Egress gate in sandboxes (RFC 0004, change 3, wired): the egress System slot (none, the default, or gate) runs playscape's isolate/egress proxy in the server; each run's instance is granted the hosts its pinned ceilings.egress allows (default deny, opened only by workspace.run, narrowed by projects and the person), both compartments go through it (orchagent/flow/isolation/isolate, Config.Egress), the grant is revoked when the instance is destroyed, and every decision is audited as sandbox.egress
  • Built. Tested under the race detector with the local driver and a real gate: a lease's commands get the gate's proxy variables over their own, a host it was not granted gets 403, an allowed host is reached, a released lease's token gets 407, a failed grant releases the lease, and decisions reach the audit log with their run (allowed as succeeded, refused as failed). docker joins the instances to the --internal network egress.gate.network and refuses a gate with no network or a loopback address; the path through a real daemon is covered by playscape's own end-to-end test, not here. Not yet: credential injection (the gate supports it; nothing in Humagen grants injections), a host's ports beyond 80 and 443, per-agent narrowing, and the unisolated sandbox, whose host processes keep the host's network
  • Consumer groups on the bus (RFC 0006, changes 2 to 6): a position and a publish lock per tenant in bus.Postgres (fiber_event_tenants, tseq, filled for retained rows on migrate), Bus.Consume with a lease and a cursor per (group, tenant) on both backends (fiber_consumers on Postgres), and egress (egress.Group), the platform observer (platform.ObserverGroup) and fiber's dispatch (dispatch.Group) reading through one each. Dispatch keeps the runs it started per channel in dispatch.Runs (fiber_dispatch_runs on Postgres), so a Slack session stop reaches a run another replica started
  • Built. bustest.Groups holds memory and Postgres to one delivery per group, takeover from the cursor after a member dies without releasing, resume after a released lease, and a lease per tenant; on Postgres two buses on one pool share a group, a publish to one tenant does not wait on another's lock, and a table from before positions is numbered on migrate. Two egress Engines (one bus, and two buses on one database) post each event once, and one that stops is taken over from its committed cursor; two dispatchers accept each event once, and a session stop reaches a run started before a failover. Delivery stays at-least-once: after a crash the next owner redoes what followed the last commit. Not yet: the observer's fold is not idempotent by (run, seq) (the stores side, RFC 0004 change 9), the chart still runs one replica, and egress still skips events older than 15 minutes, since a group seen for the first time starts at the oldest event retained
  • Cross-replica watch notices: the inbox's and the threads' Watch on pkg/notice, relayed between processes by fiber's bus.Notices (Postgres NOTIFY, Backends.Notices, set by OpenPostgres)
  • Built. TestAChangeOnOnePlatformWakesAWatcherOnTheOther runs two platforms on one Postgres: an inbox change and a thread started on one wake a watcher on the other (about 1 ms on a laptop, bound 5 s), and the platform that made the change tells its own watcher once. bus.Notices is tested across two pools on one schema, deaf to another schema and another topic, and refuses a notice over 2 KB; pkg/notice holds the send queue to its bound and drops rather than block. Lossy by design: nothing is replayed after a reconnect
  • Clients on every replica: webhook clients (pkg/clients) seated on every process and kept in step through a change count (clients.Generations, read every 2s, and at once by a webhook or event no seat matches, at most every 250ms); a Socket Mode Slack app run under a lease per app (leader.WithKey, WithDelay to spread apps across replicas)
  • Built. TestAClientChangedOnOneReplicaIsSeatedOnTheOther runs two platforms on one Postgres: a Slack client created on one answers a signed webhook on the other at once, a rotated signing secret is verified there within the sync interval and the old one refused, and a deleted client is a 404 there. TestALeaseIsHeldOnceAndTakenOver and TestLeasesSpreadAcrossProcesses hold a key to one process at a time beside the leader, take it over when the holder stops, and give two processes one of two keys each; TestASlackAppRunsOnOneReplicaAndMovesWhenItStops runs one app's connection on one of two replicas and moves it. Managed Slack/GitHub message handles, accumulated answers and sequence cursors now survive reseats and takeover through orchagent's shared delivery state, opened by platform.OpenPostgres and scoped per tenant and client. TestClientDeliverySurvivesReseatingAndReplicaChanges checks resume, duplicate delivery and tenant/client isolation on memory and Postgres. The external create and database commit remain separate, so a crash between them can still duplicate a new message
  • Stores that read and write per request (RFC 0004, horizontal data, steps 2 and 3): every store, with no replay at start and no write-behind; then pkg/state drops its lock and the chart allows more than one replica (RollingUpdate, one pod at a time)
  • Built. Each store has two-process tests: two stores on two pools on one schema see each other's writes at once, and writers in both lose nothing (the run index: 8 writers adding spend and 80 turns to one conversation; one ending reported per run when both fold the same events; a caller and its attached call settling across processes over 10 rounds). Each conversion is tested with four processes opening at once. Delivery, the observer and singleton loops are still per process until consumer groups and process roles land
  • Lists that read a page, not a workspace: state.LookupMany reads at most 1,000 of one tenant's keys in one statement (key = ANY, on the primary key), and the lists the console reads on every load use it. A listing takes one snapshot of what its reader sees (Seer.Snapshot), which reads each thread's record once and the runs its alerts were raised by together. GET /api/runs reads its 200 runs in one page of 200 and their threads in one statement; GET /api/sessions orders the sessions by what the run index keeps of them and summarizes only the page it returns; GET /api/alerts/count is the number Home's line and the console's badge show, without the alerts. A reader who reads by exception (projects:govern) is recorded for what a response shows them: a list of sessions records the sessions it returns that they see only by exception, each with the session above it when that one is also seen only by exception, and nothing for a session that was examined to order, filter or page the list and not returned; the records of one response are written together or not at all, before it is sent, and when they cannot be written none is kept and the response is refused whole (404), a list with no rows and no cursor; a count records each alert it counts that they see only by exception
  • Built. On Postgres 17 in Docker on a laptop on 2026-11-18, with 360 sessions and 4,000 runs in one workspace, read by an administrator, and 60 alerts when the first figures were taken and 90 for the last: GET /api/runs went from 5,870 statements and 1.63 s to first byte to about 100 and 32 ms, answering the same bytes, GET /api/sessions from 12,619 and 2.75 s to about 80 and 55 ms, and Home shows its count 0.2 to 0.5 s after load where it took 4.5 to 6.5 s. With 1, 10 and 30 more alerts raised by runs, GET /api/alerts/count made 18, 19 and 18 statements and answered in 8 to 10 ms. Tested in internal/httpapi (TestListReadsAreBoundedByThePageNotTheWorkspace and TestRunLinkedAlertsAreReadTogetherHoweverMany, which count only a request's own statements, on a platform whose loops never start; TestSessionPagesAreTheWholeListingInOrder; TestASessionPageRecordsExactlyTheExceptionalReadsItShows, for each paging filter across pages; TestASessionPageIsRefusedWholeWhenARecordCannotBeWritten; TestAHeadIsRecordedAndRefusedAsItsGetIs; TestARefusedStreamAnswersAtOnceAndEnds; TestASessionShownWithoutItsRunsNamesPeopleAsTheDirectoryDoes; TestAlertCountIsWhatTheListHoldsForTheCallerAlone), pkg/runs (TestSeveralConversationsReadAtOnceAreEachOnesOwn, BenchmarkConversations) and statetest. Not yet bounded the same way: GET /api/threads, GET /api/projects and GET /api/inbox/count still read a thread's record for each row they pass over (about 3,090, 2,670 and 560 statements on that workspace), a session listing still reads every thread's record to find the sessions (one statement for each 1,000), a listing filtered by status still reads the turns of every session it could hold, and a reader holding projects:govern is still recorded once for each private conversation of others a response shows, now in one write a response (33 records in one transaction for GET /api/runs on that workspace, about 35 of its statements)
  • Per-request reads and versioned writes in pkg/state (RFC 0004, horizontal data, step 1): Lookup, List (one tenant, a key prefix, a cursor, at most 1,000 records, either order) and conditional ops (Create, PutAt, DeleteAt, ErrConflict), also on state.Table
  • Built. statetest holds both backends to it on Postgres 17: versions, conditional writes all or none, 8 racers incrementing one record by compare-and-set to exactly 80, paging by prefix both ways, and prefix bounds past ASCII. No store uses it yet
  • Choosing the backends: platform.Config.Backends (Humagen's state.Store, the agent store, anchor's ledger and queue, the bus), zero for memory; platform.OpenPostgres puts all of them on one database, with pkg/agents on pkg/state for agents and fiber's pkg/durable for the run ledger and queue. humagen serve -state=postgres, the default when HUMAGEN_POSTGRES_URL is set
  • Built. TestThePlatformSurvivesARestart runs a platform on each backend, stops it and starts another on the same one. TestARunClaimedAsThePlatformStopsIsResumedAfterTheRestart holds a worker's claim on its way to Postgres until the stopping worker has handed its run back, and the next platform resumes the run at once. Run by hand against Postgres 16 with -auth dev -seed: settings, an agent, a client, an alert rule, runs, the inbox and artifacts survived a restart. Sessions are still in memory
  • The spec and the commands (pkg/spec, internal/app): System and Platform documents whose backends are kinds in slots (spec). humagen start runs a laptop's defaults (dev sign-in on loopback, example agents when nothing is configured, the first-run questions on a terminal, humagen.yaml in the config directory); humagen serve keeps a server's (OIDC, nothing seeded, only the files -f names). Also humagen setup, humagen config check (which warns of a Slack app whose humagen_client reads runs but not projects, TestConfigCheckWarnsOfAMachineThatReadsRunsButNotProjects) and print, humagen deploy (local, compose or kubernetes) and humagen slack manifest. A downstream program passes humagen.Main options and kinds instead of forking
  • Built, tested: humagen start runs with nothing configured, a spec file runs the platform, the spec's examples load, mistakes are refused with their place, what humagen setup writes loads back as the same spec, an unregistered kind stops startup, and a spec on Postgres keeps its agents across a restart. The file's GitHub client follows the file at the next start, with no new version when nothing changed, on memory and Postgres (TestTheFilesGitHubClientFollowsTheFileAtEveryStart). enabled: false turns it off, so a signed webhook is answered 404, and it stays off across a restart (TestEnabledFalseTurnsTheFilesGitHubClientOff). humagen deploy is tested with docker, helm and kubectl replaced by a recorder; it has not been run against a Docker daemon or a cluster. It refuses person_refs starts in this machine's keychain or 1Password for a compose or kubernetes target, and says people's env: variables are the target's to set
  • In-repo deploy, on the spec: a container image (Dockerfile: the console and a static humagen, non-root, /var/lib/warp volume, serve -f /etc/warp), a compose stack (deploy/compose: a mounted humagen.yaml with System and Platform documents, secrets in .env named by references, Postgres and a MinIO profile, a dev override on host networking, make up/make down), a Helm chart (deploy/helm/humagen: system and platforms values rendered into one humagen.yaml, replicaCount replicas replaced one at a time (RollingUpdate, no surge), existingSecret, a workspace PVC only for disk blobs (emptyDir with s3 or gcs), probes on /healthz (liveness, startup) and /readyz (readiness), drain flags with a termination grace checked to exceed them, a PodDisruptionBudget, an optional HPA held at one server replica, an optional humagen worker Deployment with a KEDA ScaledObject on fiber_run_queue depth, an optional Tailscale proxy sidecar for auth.kind: tailscale; refuses loopback-only sign-in without that proxy) and an example Flux setup (deploy/flux). See deploy
  • Written. make chart-check lints and renders the chart, runs kubeconform -strict on the renders and humagen config check on each rendered humagen.yaml and on both compose specs. The compose files pass docker compose config; the dev spec, with memory stores, was started and served the console. The Flux manifests pass kubeconform after kustomize build. config check lists env references the shell has not set; it does not read keychains or named files, so those fail only at start. The root image builds and runs as both command names; a default Postgres release upgrades in place from the last pre-rename chart through Helm and Flux on kind, with the Deployment, PVC contents, Secret data and container name retained (rename verification). The worker Deployment needs a release with humagen worker, and neither it, KEDA nor the Tailscale sidecar has run on a cluster. The memory-slot edge in issue #62 remains open. No image is published by releases
  • Readiness and graceful drain: GET /readyz (internal/ready: started, the database answers, not draining; /healthz stays liveness); on SIGTERM the server leaves rotation, refuses new turns with 503 and Retry-After (platform.ErrDraining), claims only runs its held runs called, waits up to server.drain_grace for runs in flight, gives open requests server.shutdown_timeout, then hands back what is left uncharged for another process to resume
  • Built, tested: the claim gate on anchor's memory queue (TestADrainStopsClaims, TestADrainStillClaimsWhatHeldWorkCalled, TestTheGateCountsWhatIsHeld), refusal of new turns (TestADrainingPlatformRefusesNewTurns), the probe's states (internal/ready), and serve ready then stopping on SIGTERM (TestServeIsReadyAndStopsOnSIGTERM). Across two processes on Postgres by the two-replica end-to-end check below
  • Durable run completion
  • Built: each terminal index transition atomically leaves pending completion work. The observer and leader reconciler claim fenced leases, persist per-action success, and retry failures after restart. Admission release, operation outcomes, usage settlement, alerts, open questions, attached-child stops, scheduled/delegated answers and title/memory housekeeping resume independently. Settlement receipts retain the original cost delta; alert receipts and one-shot inbox/announcement keys make interrupted delivery safe to retry. Pending scans rotate bounded pages across tenants. Tested on memory and Postgres with interrupted transitions, lease takeover, stale owners, storage failures and answer replay. Applies to runs ending after this release; historical completions are not replayed.
  • Two replicas end to end (internal/e2e, scripts/two-replica.sh): two humagen serve processes on one Postgres with a fake Anthropic model
  • Built, run locally. A run started on one replica streams live to a reader on the other, first event included, with the same events once each; a question asked through one is answered through the other; a replica stopped mid-turn (SIGTERM) leaves rotation, drains and hands the run back, and one killed (SIGKILL) loses it when its lease runs out, and either way the other replica finishes it, folds its events and takes the lead. The running-replica harness accepts HUMAGEN_E2E_HOST for public-host authentication through port forwards, with regression coverage for readiness, API calls and streams. Not yet run on GKE (the server's HPA holds one replica)
  • Call policies: each agent says which agents may call it (anyone, listed, none) and which calls wait for a person. GET/PUT /api/agents/{name}/call-policy (agents:read/agents:write), enforced in the call path beside the caller's spawn allowlist, and the call_agent tool offers only callees that admit the caller
  • Built, tested. Kept with -state=postgres. Per tenant, at most 1,000 policies and 100 names per list. The console edits one on the agent's page
  • Discoverability: GET /api/agents/{name}/reachable says, for that agent as a caller, whether each other agent admits it, is in its spawn allowlist, and needs approval, with a reason
  • Built, tested. One page of up to 500 agents, with truncated
  • Per-call approval held by the callee's policy: call_agent implements native.Approving (orchagent/flow/turn/native), the question carries the policy's approvers and self-approval, the inbox addresses it to them, and only a call a person approved goes through
  • Built. fiber's host call tool wrapper forwards Approving, so the caller parks on the approval; TestACallTheCalleeHoldsWaitsForItsApprovers covers approve and deny end to end. The question waits the policy's expires_seconds
  • An agent's approval queue: approval questions about calling an agent carry it as source.target, and GET /api/inbox?kind=approval&agent=X&state=open lists what was raised by or would call X. It offers a note only where the run takes one from the viewer (steered_for), and says when a call acts as the person
  • Built, tested, the queue's notes in happy-dom (governance.dom.test.tsx)
  • Built-in manager role: everything an operator has, and writing agents (their call policies among them) and knowledge. Granted by -manager-group (humagen-managers); mock persona mock-manager
  • Built, tested

Platform agent packages

The platform ships its agents as versioned packages. humagen/entry (the entry agent, humagen) and humagen/system (the approval agent, approver) are in every workspace. The rest wait in the agent store, and a workspace installs them: humagen/core (Core: the writer and the analyst) and humagen/review (Review: code-reviewer and its three specialists). A package's version is a SHA-256 hash of its specifications, including prompts and configured models. Only a latest revision written by platform receives automatic upgrades. Workspace edits retain the package version they were based on and are never overwritten by EnsureBuiltins, which adds the entry and approval agents and only keeps the store's installed agents current: it never adds or restores one.

Whether a package is installed is read from the workspace's agents, never stored: it is installed while any of its agents is there, not retired. GET /api/store/packages (agents:read) lists each package with its version, its agents, installed and the missing agents. Each agent says what installing grants it, read from the spec the package ships and never stored beside it: its provider, model and fallbacks, its tools, the agents it may call (access.spawn), and the connectors and tool_servers those tools need. The console shows them on the package's card, above Install. POST /api/store/packages/{name}/install (agents:write) adds the missing agents as platform revisions at the current version, with their old handles; a retired name is revived, so its versions continue and pinned revisions stay valid, and installing again restores an agent someone retired. It is refused with 409, before anything is added, while one of the workspace's own agents holds a package name. DELETE /api/store/packages/{name} (agents:write) retires the package's agents and their old handles; history and pinned revisions stay readable. An agent changed in the workspace is retired only with force=true, and without it the removal is refused with 409 naming it. Both are audited (agent.package.install, agent.package.remove). The three operations are system tools too (list_store_packages, install_store_package, remove_store_package), offered over MCP and declared in the tool registry. A run of a store agent that is not installed is refused saying which package to install, and so are a mention of one in a message and a call to one with the agent tool; a schedule's refusal raises an alert; automatic pull request review skips with a log line naming the Review package. The console lists the store under Agents.

Revision and directory JSON expose package: {name, version, latest}, customized and update_available. Package provenance is stored in saige definition metadata and inherited on every customization, including builder saves. Pre-package revisions keep their hashes. A customization without recorded provenance has an empty base version and is shown as having an update available. A custom agent that predates a reserved name is still protected from adoption.

POST /api/agents/{name}/reset with {"expected_rev": N} restores the latest package specification as a new revision written by platform, retaining history. It requires agents:write, tenant visibility and the same home ownership as an edit. An ordinary agent has no package to reset. There is no agent DELETE route. Package agents retain their Company home because moving one narrows its routing availability across the workspace; customizing its specification does not change that scope.

Evidence: TestAgentPackageUpgradeCustomizeReset, TestPackageAgentsCanBeCustomizedAndReset and TestPackageMetadataKeepsPinnedOldRevisionHash. No UI changes are included.

Built-in agent handles after the rename

Every workspace's directory offers humagen (which took over from humagen-builder) and approver; installing Core adds humagen-writer and humagen-analyst, and installing Review adds code-reviewer, security-reviewer, architect-reviewer and qa-reviewer. Compatibility definitions keep old registry keys and pinned revisions usable; existing schedules, client defaults and allow-lists continue addressing those keys without new grants. TestBuiltinCompatibilitySurvivesRestart covers the memory and Postgres backends. Slack task cards link to their conversation when HUMAGEN_PUBLIC_URL is configured; the shared follower retains that URL while streaming and settling the run.

Library and personal settings

The library implementation adds private human-owned memory, fact/decision/preference/person/risk kinds, expiry excluded from every context layer, provenance and persisted use counts. A preview does not count as use. Personal forgetting records an attempt before removing the note and does not retain the forgotten text in its audit snapshot. Personal briefing, notification delivery policy, quiet hours and privacy choices survive restart; native console notifications now use a bounded durable authenticated delivery worker with immediate, hourly digest, quiet-hour and Off policies. Email is available only when the operator configures delivery and a permitted recipient, and the person opts in. See native notifications and email notifications. Audit, Memory and Personal Preferences are mounted under their canonical routes. The primary navigation is New, Sessions, Alerts, Agents, Connections, Artifacts and Settings. Agents groups Skills, Knowledge and Memory at their existing addresses; Connections groups Agent tools, Data sources and permitted Workspace apps. Published artifacts have their own destination. The managed resources and shared web foundation are described in managed-library.md.

Memory corrections preserve original provenance and record the editor and review. New note IDs are opaque, so public IDs do not expose private note volume. Explicit promotion copies a selected approved, unexpired note to a destination project as a pending suggestion. Only text, kind and expiry cross the boundary; the copier replaces private source provenance. The destination owners must review it before it enters context. An approved note drawn from an artifact is sent to agents with the address of that artifact's version after its text, so an agent can say where the note comes from; who wrote or copied a note is not sent. ReadContext Ask and Never, including forced-approval dry runs, withhold automatic memory grounding; fixed instructions and briefing preferences remain.

Catalog connectors include Snowflake (catalog and live SELECT) and GCS/S3 (metadata catalog and per-reader collected text copies). Each connector uses an explicit credential reference; object catalog crawling never reads content.

Catalog at /library/catalog browses and searches connector metadata, expands table columns, and exposes crawl, publish and withdraw actions to connector owners.

Session alert state now persists priority, resolution, snooze, and Undo in the existing alert engine. Lifecycle receipts are idempotent across restart. Retention prunes resolved history and refuses new alerts when all retained alerts still need attention. Session API and projection wiring follow in the next layers.

Canonical session routes now start or continue an agent, post messages, read transcripts and children, invite people, link evidence, and stop a subtree. Reads and streams recheck ancestor visibility. SSE resumes by per-run cursors and sends an authoritative reset when the retained cursor window fills. Native child calls use the existing governed call path and shared session stores.

Evaluation persistence now retains deterministic online checks, version change scorecards, feedback candidates, and exact tool/retrieval replay receipts. Shared prompt snapshots enforce content hashes and bounded layers. Public suite reads hide retained source bytes and recheck the original run and current source access. Builder change previews apply sampled deterministic eval gates before revision; shared prompt snapshots are pinned at admission. Scheduled recorded replays recheck current source and person access before and after each case. Setup validation remains isolated from ordinary conversations and alerts. Offline policy, privacy, format, and replay tests cover these boundaries.

Session alerts now project authoritative question outcomes, retain private reconnect attention, and use explicit priority preferences for delivery. Reads never resolve attention; visible open alerts determine session ordering. See session alerts.