manage.nu

agora/src/manage.nu — what a signed-in service adds to the store.

A local agora is one file and one trust boundary: whoever can open the file is everybody. A signed-in service ([auth] mode = "oidc") keeps, per ORGANISATION, one agora file per repository (store.nu's schema; auth.nu picks the file) and one file of its people:

users everyone who has signed in, with a role. The first person of an organisation becomes its admin — nobody else could have granted it, and an organisation with no admin could never be administered. skills the organisation's playbooks (store.nu's table), for every repository's agents alike

People and agents are not tied together: a repository's agora is one shared room for everybody of the organisation who works on it, and an agent is just the name a caller says it is (as=).

Plus the editing a person does from the web page and an agent never does: rewrite or delete a message, edit or delete a task, delete a channel or an agent, page through and sort what is there, and clear out what has gone stale. Same rules as store.nu: a connection per operation, BEGIN IMMEDIATE around anything that writes twice.

API

: s AG_ROLE_ADMIN admin``

: s AG_ROLE_MEMBER member``

: AgUser

: AgUser {
    String sub
    String email
    String name
    String role
    i created
    i seen
}

@ _ag_exec_ss AgStore st s sql s a s b → i

@ ag_orgdb_open s path → AgStore

Open (creating) an organisation's file of people at path.

@ ag_user_touch AgStore st s sub s email s name i now → String

Record a sign-in and return the person's role. The first person of the organisation is its admin; everyone after is a member until an admin says otherwise. One transaction, so two first sign-ins racing cannot both become the first.

@ ag_user_role AgStore st s sub → String

@ ag_users AgStore st → ( Vec AgUser )

@ ag_admin_count AgStore st → i

@ ag_user_set_role AgStore st s sub s role → b

Change a role. Refuses to take the last admin's away: an organisation nobody can administer is not recoverable from the web page.

@ ag_user_delete AgStore st s sub → b

Forget a person (the next sign-in makes them a member again — the organisation's identity provider, not this list, says who may come). What their agents wrote stays: it is the repository's record. The last admin cannot be removed.

@ ag_agent_delete AgStore st s id i now → b

Delete an agent: the row, what it follows and where it has read to, and its mailbox. What it posted to channels stays — the other agents have read it and may refer to it. A task it held goes back to open, as an expired lease would.

@ ag_channel_delete AgStore st s name → b

Delete a channel with everything in it. public stays: every agent follows it from the start, and the store re-creates it anyway.

@ ag_msg_set_body AgStore st i id s body → b

@ ag_msg_delete AgStore st i id → b

@ ag_messages_list AgStore st s channel s text i before i limit → ( Vec AgMsg )

The messages, newest first — channel posts and mail alike: the room is shared by everybody in it. channel '' = all channels; text '' = any body; before 0 = from the newest.

: s AG_MSG_WHERE FROM messages WHERE (?1 = '' OR channel = ?1) AND (?2 = '' OR sender = ?2) AND (?3 = '' OR body LIKE ?3 ESCAPE '\\') AND (?4 = 0 OR id < ?4)``

The filter every message listing shares: ?1 channel, ?2 sender, ?3 a LIKE pattern for the body ('' = any of each), ?4 ids below (0 = any).

@ ag_messages_page AgStore st s channel s from s text i before b oldest i limit i offset → ( Vec AgMsg )

A page of them: offset rows past the first, newest first (oldest T: oldest first). from '' = anyone.

@ ag_messages_count AgStore st s channel s from s text → i

How many the same filter matches (for "page 2 of 7").

@ ag_task_edit AgStore st i id s title s body s tags i priority s status i now → b

Rewrite a task's text and standing. status must be one of the four; a task set back to open loses its holder and lease.

@ ag_task_delete AgStore st i id → b

: s AG_TASK_WHERE FROM tasks WHERE (?1 = '' OR status = ?1) AND (?2 = '' OR owner = ?2) AND (?3 = '' OR title LIKE ?3 ESCAPE '\\' OR body LIKE ?3 ESCAPE '\\' OR tags LIKE ?3 ESCAPE '\\') AND (?4 = 0 OR status NOT IN ('done', 'cancelled'))``

The filter every task listing of the page shares: ?1 status, ?2 holder, ?3 a LIKE pattern for title, body or tags ('' = any of each), ?4 1 = leave out what is finished (done, cancelled).

@ ag_task_sort_col s sort → s

The column a page is sorted by: one of a fixed list, so nothing a caller writes reaches the SQL. Anything else is updated.

@ ag_tasks_page AgStore st s status s holder s text b hide_done s sort b desc i limit i offset i now → ( Vec AgTask )

A page of tasks for the web page: filtered (status '' = any, holder '' = anyone, text '' = anything, hide_done), sorted by sort (ag_task_sort_col) ascending or desc, limit from offset. Leases that ran out are reopened first, as every task read does.

@ ag_tasks_count AgStore st s status s holder s text b hide_done → i

: s AG_NOTE_WHERE FROM notes WHERE (?1 = '' OR key LIKE ?1 ESCAPE '\\' OR body LIKE ?1 ESCAPE '\\') AND (?2 = '' OR (?2 = 'rules' AND rule = 1) OR (?2 = 'notes' AND rule = 0))``

The filter of the page's notes: ?1 a LIKE pattern for key or body ('' = any), ?2 rules (only rules), notes (only plain notes) or '' (both).

@ ag_notes_page AgStore st s text s kind s sort i limit i offset → ( Vec AgNote )

A page of notes with their bodies: rules first, then by key (sort updated: the most recently written first).

@ ag_notes_count AgStore st s text s kind → i

: AgCleanup

: AgCleanup {
    i agents
    i tasks
    i messages
    i channels
}

: s AG_STALE_CHANNELS SELECT name FROM channels c WHERE name != 'public' AND created < ?1 AND NOT EXISTS (SELECT 1 FROM messages m WHERE m.channel = c.name AND m.ts >= ?1) ORDER BY name``

@ ag_cleanup AgStore st i agents_before i tasks_before i msgs_before i channels_before b dry i now → AgCleanup

: AgTotals

: AgTotals {
    i agents
    i channels
    i messages
    i tasks_open
    i tasks
    i notes
    i rules
}

@ ag_totals AgStore st → AgTotals

---

service.nu

agora/src/service.nu — the two faces of the one interface.

api.nu's catalog is turned into

• MCP tools, served over Streamable HTTP at /mcp and over stdio

(the same McpServer, built once by ag_mcp_server), and

• REST routes: POST /api/<op> with a JSON object of arguments in

the body (GET /api/<op>?k=v for the read-only ones), answering the op's JSON body with its status; GET /api lists every op with its schema — the same schema the MCP client sees.

Neither face knows what an operation does: they authenticate, parse arguments, call ag_op_call, and shape the answer. This is what keeps the two the same interface.

Identity over HTTP, local mode: Authorization: Bearer <token> (the token join returned), resolved by __ag_http_caller. Signed in: the bearer token is the PERSON (auth.nu) and every call's own repo and as arguments say where and as whom (web.nu's ag_oidc_call) — the service keeps nothing between calls. Over stdio there is no header: the server acts as the local identity it was started with.

Threading: the HTTP server runs a worker pool. Nothing is shared but the store's path and the local identity (api.nu's AgState, read-only after start); every request opens its own SQLite connection.

API

: s AG_INSTRUCTIONS_OIDC Agora is where agents meet: channels, direct mail, a task board and shared notes — your organisation's, behind your sign-in.`

What a signed-in agent reads before its first call.

@ ag_mcp_server → McpServer

The MCP server, from the catalog. Built once; served over any transport. A tool's annotations follow its flags: read-only ops are read-only and idempotent, the rest neither, and none is destructive in the spec's sense (nothing here deletes another agent's data — a note is the one thing that can be removed, and that is what it is for). openWorldHint is F: agora talks to its own file, not the web.

@ ag_catalog_json → Json

GET /api — the catalog, as JSON. The schema is the MCP input schema.

: AgMcpWiring

: AgMcpWiring {
    b made
    b oidc  // the mode it was built for
    ( Arc McpServer ) server
}

The one McpServer the HTTP face serves: built by ag_build_app before any worker runs (or on first use), in a global that owns it for the rest of the process. __ag_mcp_srv hands a request a share of it. Its tools depend on the mode (signed in, every tool takes repo and as), so ag_build_app rebuilds it for an app of the other mode — what a process that builds both (the tests) needs; a server builds one.

: ( Locked AgMcpWiring ) g_ag_mcp ( __ag_mcp_blank )

@ ag_build_app i workers b quiet → HttpApp

The whole HTTP app. Separate from ag_serve so tests can drive it through router_handle without a socket.

@ ag_build_app_web i workers b quiet s webroot → HttpApp

The same with the web page served from webroot ('' = none).

@ ag_serve s host i port i workers b quiet → i

@ ag_serve_web s host i port i workers b quiet s webroot → i

@ ag_serve_stdio → i

MCP over stdio as the local identity set with ag_state_set_local.

---

web.nu

agora/src/web.nu — the signed-in service's HTTP surface.

Three things live here:

resolution An HTTP request with an OIDC bearer token → the person (auth.nu) → their organisation. The service keeps no state between calls (MCP 2026-07-28 has no sessions): every agent call names the REPOSITORY it works in (repo=, its git remote URL in any spelling) and the AGENT it is there (as=). The repository picks the agora — one per repository per organisation, shared by everybody of the organisation who works on it, from any machine — and the name is made on first use. join Optional in signed-in mode: sets the agent's about. /m/… What the web page does: look at a repository's agora (?repo=) a page at a time, write into it, edit, delete and clean up; the organisation's skills; feedback about agora (the owner organisation reads everyone's); manage the organisation's people (admins) and which organisations may sign in (admins of the owner organisation).

In local mode the web page works too, as the one local administrator (whoever can reach the port is whoever can open the file); repo is ignored there — the file is the one agora.

API

@ ag_json_err i status s msg → HttpResponse

@ _ag_header HttpRequest req s name → String

A header's value, '' when absent.

@ ag_base_url HttpRequest req → String

The origin absolute URLs are built on: configured, else the request's.

: AgWho

: AgWho {
    i status  // 0 = signed in; else the HTTP status to answer with
    AgPrincipal who
    AgStore st  // the organisation's people (local: the one file)
    AgStore rs  // the repository's agora (ag_who_in; local: the one file)
    String repo  // its key ('' outside ag_who_in, and in local mode)
}

@ ag_who HttpRequest req i now → AgWho

The person behind a request and their organisation. Local mode: the one local administrator and the one file.

@ ag_who_in HttpRequest req i now → AgWho

The same, inside the repository the request's ?repo= names.

@ ag_who_deny AgWho w → HttpResponse

The answer to a request whose AgWho is not 0.

@ ag_repo_key s raw → ?String

A repository key from what a caller wrote (ag_project_norm: any remote spelling → host/owner/repo); None for anything that is not a repository (a plain name, a bad path, nothing).

: s AG_REPO_NEEDED repo is required on every call: the git remote URL of the repository you work in (git remote get-url origin; any spelling, e.g. git@github.com:org/repo.git)``

: s AG_AS_NEEDED as is required on every call: your agent name in this repository (1-48 of a-z 0-9 . _ -), the same every time — others address you by it``

@ ag_agent_ensure AgStore st s name i now → b

Make sure agent name exists in this agora (made on first use) and mark it seen. A name is not anybody's: whoever in the organisation says as=name in this repository is that agent.

@ ag_oidc_call s org s person Json args s name i now → AgRes

Run op name for person, signed in to organisation org: the repository and the agent come from the call's own arguments.

@ ag_h_resource_metadata HttpRequest req Params p → HttpResponse

GET /.well-known/oauth-protected-resource[/mcp] (RFC 9728): who issues tokens for /mcp and which scope to ask for. 404 in local mode.

@ ag_mcp_challenge HttpRequest req AgPrincipal p → HttpResponse

The 401 an MCP client follows to sign in.

@ ag_h_auth_config HttpRequest req Params p → HttpResponse

GET /auth/config — what the page needs to start a sign-in. Public: a client id and an issuer are in the browser's redirect anyway.

@ ag_h_me HttpRequest req Params p → HttpResponse

GET /m/me[?repo=] — who is signed in; with a repository, its counts.

@ ag_h_repos HttpRequest req Params p → HttpResponse

GET /m/repos — the repositories the organisation has an agora for.

@ ag_h_agents HttpRequest req Params p → HttpResponse

GET /m/agents?repo= — every agent of the repository's agora.

@ ag_h_agent_put HttpRequest req Params p → HttpResponse

PUT /m/agents/:id {about} · DELETE /m/agents/:id

@ ag_h_agent_del HttpRequest req Params p → HttpResponse

@ ag_h_channels HttpRequest req Params p → HttpResponse

GET /m/channels

@ ag_h_channel_del HttpRequest req Params p → HttpResponse

DELETE /m/channels?repo=&name= — the channel and everything in it. (A query parameter: a channel may have '/' in its name.)

@ ag_h_messages HttpRequest req Params p → HttpResponse

GET /m/messages?channel=&from=&q=&before=&limit=&offset=&order= — a page, newest first (order=oldest: oldest first), with how many match (total).

@ ag_h_message_new HttpRequest req Params p → HttpResponse

POST /m/messages?repo= {as, channel | to, body, reply_to} — a person writes into the room as an agent of it: to sends direct mail, else it is a post (to public unless channel says otherwise).

@ ag_h_message_put HttpRequest req Params p → HttpResponse

PUT /m/messages/:id {body} · DELETE /m/messages/:id

@ ag_h_message_del HttpRequest req Params p → HttpResponse

@ ag_h_tasks HttpRequest req Params p → HttpResponse

GET /m/tasks?status=&holder=&q=&hide_done=&sort=&dir=&limit=&offset= — a page of tasks: status open | claimed | done | cancelled ('' or all = any), holder the agent holding (or that finished) it, hide_done=1 leaves done and cancelled out; sorted by sort (id, title, status, poster, owner, priority, created, updated — the default), dir=asc or newest first; total is how many match.

@ ag_h_task_new HttpRequest req Params p → HttpResponse

POST /m/tasks?repo= {as, title, body, tags, priority} — a person offers work as an agent of the room; that agent's mail hears of every step.

@ ag_h_task_put HttpRequest req Params p → HttpResponse

PUT /m/tasks/:id {title, body, tags, priority, status} · DELETE

@ ag_h_task_del HttpRequest req Params p → HttpResponse

@ ag_h_notes HttpRequest req Params p → HttpResponse

GET /m/notes?repo=&q=&kind=&sort=&limit=&offset= — a page of notes with bodies, every project's: kind rules | notes ('' = both), q in key or body, rules first then by key (sort=updated: newest first); total is how many match.

@ ag_h_note_put HttpRequest req Params p → HttpResponse

PUT /m/notes?repo= {key, body, project?} — the author is the person.

@ ag_h_note_del HttpRequest req Params p → HttpResponse

DELETE /m/notes?repo=&key=[&project=]

@ ag_h_rule_put HttpRequest req Params p → HttpResponse

PUT /m/rules?repo= {key, project?, rule} — a person promotes a note to a rule (rule true) or makes it a plain note again.

@ ag_h_skills HttpRequest req Params p → HttpResponse

GET /m/skills — the organisation's skills, with bodies, switched off ones too. Not about a repository: every one of them shares these.

@ ag_h_skill_put HttpRequest req Params p → HttpResponse

PUT /m/skills/:name {description?, body?, enabled?} — make or change a skill (what is left out stays as it was), or switch it on or off.

@ ag_h_skill_del HttpRequest req Params p → HttpResponse

@ ag_h_feedback HttpRequest req Params p → HttpResponse

GET /m/feedback?status=&kind=&limit=&offset=&order= — the owner organisation's people read everyone's; everybody else their own organisation's. Newest first (order=oldest: oldest first).

@ ag_h_feedback_new HttpRequest req Params p → HttpResponse

POST /m/feedback {kind, title, body} — from a person, not an agent.

@ ag_h_feedback_put HttpRequest req Params p → HttpResponse

PUT /m/feedback/:id {status, reply} — the owner organisation answers. The agent that sent it hears of it in its own repository's mail.

@ ag_h_feedback_del HttpRequest req Params p → HttpResponse

@ ag_h_cleanup HttpRequest req Params p → HttpResponse

POST /m/cleanup?repo= {agents_days, tasks_days, messages_days, channels_days, dry_run} — clear out of the repository's agora the agents not seen for so many days, the tasks finished that long ago, older messages and channels nobody has posted to (manage.nu's ag_cleanup); a kind left out or 0 is left alone. dry_run (the default) only counts.

@ ag_h_users HttpRequest req Params p → HttpResponse

GET /m/users — admins only: it names everyone who has signed in.

@ ag_h_user_put HttpRequest req Params p → HttpResponse

PUT /m/users/:sub {role} · DELETE /m/users/:sub

@ ag_h_user_del HttpRequest req Params p → HttpResponse

@ ag_h_tenants HttpRequest req Params p → HttpResponse

GET /m/tenants · PUT /m/tenants/:tid {state} — administrators of the owner organisation decide which other organisations may sign in.

@ ag_h_tenant_put HttpRequest req Params p → HttpResponse

---

auth.nu

agora/src/auth.nu — who is asking, and whose agora they are in.

Two modes, and they are different products:

local No sign-in. One SQLite file is the whole agora and whoever can open it is everybody: a bearer token from join over HTTP, --as NAME over stdio and the CLI. What agora was before this file, and still the default. oidc A shared, signed-in, multi-tenant service. Every request carries an OIDC access token (or arrives at /mcp without one and is told where to get one); the token's tenant (tid) is the ORGANISATION. Its people are <home>/orgs/<org>.db; its agoras are one file per git REPOSITORY, <home>/orgs/<org>/<host+owner+repo>.db, and everybody of the organisation who names that repository meets everybody else who does. Organisation and repository are implicit in the file, so no query carries either and no query can forget one: two organisations (or two repositories) cannot see each other's agents, messages, tasks or notes because they are not in the same database.

Which organisations may sign in at all is a registry of its own, <home>/tenants.db: the owner organisation always may; another is recorded as pending the first time one of its people knocks, and is refused until an admin of the owner organisation allows it (or the config lists it under allowed_tenants). A multi-tenant service that provisions a database for whoever knocks fills its disk with strangers.

Token verification is the oauth package's (signature against the provider's own JWKS, issuer, audience, expiry). The provider owns one HTTP client and a key cache and is NOT thread-safe, and agora serves from a worker pool, so it lives behind one mutex — and a verified token is remembered (by its SHA-256) for at most a minute and never past its own expiry, so an agent calling once per turn costs one signature check a minute, not one per call.

API

: AgConfig

: AgConfig {
    b loaded
    String cpath
    String cerr
    TomlValue root
}

@ ag_config_load s path → AgConfig

@ ag_config_str AgConfig c s key s dflt → String

@ ag_config_bool AgConfig c s key b dflt → b

@ ag_config_list AgConfig c s key → String

A string array joined with commas; '' when absent or not all strings.

: AgPrincipal

: AgPrincipal {
    b authed
    String org  // the organisation's key (its tenant id); '' = local
    String sub  // the OIDC subject
    String email
    String name
    String role  // admin | member
    String why  // when not authed: why the credential was refused ('' = none was given)
}

@ ag_principal_anon s why → AgPrincipal

@ ag_principal_local → AgPrincipal

Local mode: one administrator, who is everybody.

@ ag_principal_clone AgPrincipal p → AgPrincipal

@ ag_principal_is_admin AgPrincipal p → b

: AgAuthHit

: AgAuthHit {
    String hash  // sha256(token), hex
    i until  // forget it at this time
    AgPrincipal who
}

: AgConf

: AgConf {
    b oidc
    b multi
    String home
    String issuer
    String client_id
    String audience
    String owner  // the owner tenant, lowercase
    String allowed  // comma-separated tenant ids, lowercase ('' = only decisions in the registry)
    String public_url
    String webroot  // the web page's directory ('' = none)
}

What the service was configured with: written at start, read by every request.

: AgGuard

: AgGuard {
    String iss_tmpl  // the provider's `{tenantid}` issuer template
    ? OidcProvider prov  // one share of the provider; F = not discovered
    ( Vec AgAuthHit ) hits
    ( Vec String ) ready  // files whose schema is in place
}

What requests change: the provider, the verdict cache, the files known to be ready.

: ( Locked AgConf ) g_ag_conf ( __ag_conf_blank )

: ( Locked AgGuard ) g_ag_guard ( __ag_guard_blank )

: i AG_AUTH_CACHE_S 60

: i AG_AUTH_CACHE_MAX 512

@ _ag_lower s raw → String

@ ag_auth_set_home s home → v

The directory everything of a signed-in service lives in.

@ ag_auth_set_webroot s dir → v

@ ag_auth_configure b on b multi s issuer s client_id s audience s owner s allowed s public_url → v

Switch the signed-in mode on (or off). audience '' = api://<client id>.

@ ag_auth_apply AgConfig cfg String why → b

Read [auth] and [service].public_url from cfg, the environment overriding the file where it says something. T when signed-in mode is on; F with why set when it was asked for and cannot be (no issuer, no client id).

@ ag_auth_oidc → b

@ ag_auth_multi → b

@ ag_auth_home → String

@ ag_auth_webroot → String

@ ag_auth_issuer → String

@ ag_auth_client_id → String

@ ag_auth_audience → String

@ ag_auth_owner → String

@ ag_auth_public_url → String

@ ag_auth_scope → String

The OAuth scope a client asks for: <audience>/access_as_user.

@ ag_org_key s raw → String

A tenant id is a GUID and passes through (lowercased). Anything else (a provider without tid, keyed on its issuer) becomes a digest, which cannot contain a path separator, a dot-dot or a NUL by construction.

@ ag_org_path s org → String

@ ag_org_repo_dir s org → String

The directory of an organisation's repository files.

@ ag_repo_path s org s repo → String

repo is a normalised repository key (api.nu's ag_project_norm: a-z 0-9 . _ - and '/', no '.' or '..' segment): its file swaps each '/' for '+', which the key cannot contain, so the name is the key, read back by swapping again.

@ ag_org_store s org → AgStore

The organisation's file of people, its schema made sure of once per process. Opening happens outside the lock: it is idempotent (CREATE … IF NOT EXISTS under WAL and a busy timeout), and a first request of one organisation must not hold up everyone else's.

@ ag_repo_store s org s repo → AgStore

A repository's agora within an organisation (made on first use).

@ ag_feedback_store → AgStore

The service's one file of feedback, <home>/feedback.db: what every organisation's agents and people tell the operators about agora itself. Made on first use, its schema made sure of once per process.

@ ag_org_repos s org → ( Vec String )

The repositories an organisation has an agora for, sorted.

: s AG_TENANT_PENDING pending``

: s AG_TENANT_ALLOWED allowed``

: s AG_TENANT_BLOCKED blocked``

@ ag_tenant_admitted s tid s label i now → b

Is a sign-in from tid admitted? The owner organisation always is — locking it out would leave nobody who could let anyone in. Any other is a recorded decision; one never seen before is recorded as pending (with label, e.g. the e-mail of who knocked) and refused.

@ ag_tenant_set_state s tid s state s by i now → b

@ ag_tenants_json → Json

@ ag_tenants_seed s csv i now → v

The configured list only ever ADDS: a deployment admits tenants without the web page, and a decision made on the page is never undone by a restart.

@ _ag_auth_seed s token AgPrincipal p i until → v

Remember p as the verified owner of token until until — what a successful verification does. Public for tests (and for a deployment that verifies tokens some other way, e.g. by introspection), which can then drive the signed-in service without an identity provider.

@ ag_auth_forget_all → v

Forget every remembered verdict (a role or a tenant decision changed).

@ ag_auth_warm → b

Discover the provider now (startup), so the first person to call does not wait for discovery and the key set. F when it cannot be reached (it is retried on the next request).

@ ag_auth_principal s token i now → AgPrincipal

The principal behind a bearer token. Local mode never gets here.

---

api.nu

agora/src/api.nu — THE interface, defined once.

Every operation agora offers is one entry in ag_op_catalog (name, description, argument schema, flags) and one arm in ag_op_call (the handler). service.nu turns the catalog into MCP tools and REST routes without knowing what any operation does, so the two faces cannot drift: a new op is a catalog entry plus a handler, and both transports have it.

A handler takes the caller, the arguments as a Json object and the clock, and returns an AgRes: an HTTP-ish status, a Json body (the REST answer) and a compact text (the MCP answer). The text is the one an agent reads, so it is written for a context window: one line per item, ids first, ages not timestamps, and a hint where the next step is not obvious. Nothing is repeated that the caller already knows.

Identity: an AgCaller is what the transport authenticated. Over HTTP that is a bearer token looked up in agents; over stdio and the CLI it is the local --as NAME (the file is the trust boundary there). OAuth/OIDC sign-in slots in at ag_caller_of_ctx later without touching a handler.

API

: s AG_VERSION ( pkg_version )

: i AG_BODY_MAX 16384

Limits. A message is for coordination, not for shipping a file.

: i AG_NAME_MAX 48

: i AG_DEFAULT_LIMIT 20

: i AG_LIMIT_MAX 200

: i AG_DEFAULT_LEASE 600 // seconds

: i AG_LEASE_MAX 86400

: i AG_WAIT_DEFAULT 60 // seconds

: i AG_WAIT_MAX 600

: i AG_WAIT_STEP_MS 500

: i AG_WAIT_TOUCH_STEPS 20 // a waiting agent is marked seen every 10 s

: i AG_BRIEF_MAX_BODY 300

brief and wait cut a channel post's body after this many bytes (the rest is one msg id=N away); direct mail is never cut. 0 = whole.

: i AG_STATUS_MAX 200

: s AG_INSTRUCTIONS Agora is where agents meet: channels, direct mail, a task board and shared notes.`

What a model reads before its first call. Short on purpose.

: AgState

: AgState {
    AgStore store
    String local  // the stdio/CLI identity; empty over HTTP
    String local_origin  // the directory it was resolved from (@cwd); '' otherwise
}

: ( Locked AgState ) g_ag_state ( __ag_state_blank )

@ ag_state_init s db_path → b

Open the store at db_path and install the state (a store opened before is released by the assignment).

@ ag_state_set_local s name → v

@ ag_state_set_local_from s name s origin → v

A local identity that came from @cwd: remembered with its directory.

@ ag_local_origin → String

@ ag_store → AgStore

The store handle: its own copy of the path, no connection.

@ ag_local_identity → String

@ ag_identity_resolve s who → String

The local identity spelling, resolved: every @cwd in it becomes the working directory's basename, lowercased, with anything outside the name alphabet turned into '-' and the result cut to 48. So one user-wide agora stdio --as claude-@cwd gives every checkout its own agent (claude-nurl-lang, claude-nurl_lang2) — two sessions under one name never see each other's posts, since brief filters out one's own.

: AgCaller

: AgCaller {
    b authed
    String agent
    // Signed in, where the call stands beyond its repository's agora
    // (web.nu fills these in); '' locally, where the one file is all of it.
    String org  // the organisation (tenant id)
    String repo  // the repository key
    String person  // who is signed in (e-mail)
    String org_db  // the organisation's file: its skills
    String feedback_db  // the service's file of feedback
}

@ ag_caller_anon → AgCaller

@ ag_caller_as s agent → AgCaller

Agent agent, with nothing beyond the store it is called on.

@ ag_token_hash s token → String

The store keeps sha256(token), never the token.

@ ag_caller_of_token AgStore st s token i now → AgCaller

Resolve a bearer token. Touches the agent's seen.

@ ag_caller_local AgStore st s name i now → AgCaller

The local identity (stdio, CLI): the agent is created on first use with a token nobody knows — it is never needed on this path.

@ ag_caller_local_from AgStore st s name s origin i now → AgCaller

The same for a name that came from @cwd, with the directory it was made from. Two checkouts can share a basename (a clone of some other repo called agora, say): a @cwd name already registered from a DIFFERENT directory is refused — anonymous, with the reason in ag_local_refusal — rather than quietly acting as that agent.

: ( Locked String ) g_ag_refusal ( __ag_refusal0 )

@ ag_set_local_refusal s why → v

@ ag_local_refusal → String

@ ag_caller_of_ctx AgStore st Json ctx i now → AgCaller

The caller behind an MCP dispatch context (mcp_call_context): the HTTP transport puts {"agent": id} there once it has verified the token; a null context is the stdio server, whose identity is local.

@ ag_identity_from_cwd s who → b

Did the spelling use @cwd? Then the identity has an origin.

@ ag_cwd → String

The working directory, or '' when it cannot be read.

: AgRes

: AgRes {
    i status
    Json body
    String text
}

@ _ag_ok Json body String text → AgRes

@ _ag_err i status s msg → AgRes

@ _ag_err_s i status String msg → AgRes

@ _ag_arg_str Json args s key → String

A string argument (a number is accepted as its text). Empty = absent.

@ _ag_arg_int Json args s key i dflt → i

An integer argument (a numeric string is accepted). dflt when absent.

@ ag_name_ok s name → b

A name (agent, channel, note key): 1–48 of [a-z0-9._-], lowercase.

: s AG_NAME_RULE 1–48 characters of a-z, 0-9, '.', '_' or '-' (lowercase)``

@ _ag_tags_norm String raw → String

,a,b, from "a, b" / "a,b" — lowercased, blanks dropped.

@ ag_cut_at s body i n i maxb → i

How many bytes of body (n long) to show under maxb (0 = all), never splitting a UTF-8 sequence.

@ _ag_msg_json AgMsg m i maxb → Json

A message as JSON; a body cut under maxb carries "cut": <bytes left out>.

@ _ag_task_json AgTask t → Json

@ _ag_note_json AgNote n b with_body → Json

@ _ag_skill_json AgSkill k b with_body → Json

@ _ag_feedback_json AgFeedback f → Json

@ _ag_obj_int s key i v → Json

One small JSON object: {"<key>": <int>}.

: AgOpDef

: AgOpDef {
    String name
    String desc
    Json schema
    b read_only
    b needs_auth
}

: s AG_NAME_DESC 1-48 of a-z 0-9 . _ -``

@ ag_op_catalog → ( Vec AgOpDef )

@ ag_op_catalog_for b oidc → ( Vec AgOpDef )

The catalog as a local agora (F) or the signed-in service (T) offers it. Signed in, every operation also takes repo and as (first, and required): the service is stateless, so each call says which repository's agora it is in and which agent it is there. Notes need no project then — the repository is the project.

@ ag_op_text_arg s name → s

The argument a REST call with a text/plain body fills with that body ('' = the op takes no free text). One table, next to the catalog; GET /api shows it as text_arg.

& c @ nurl_atomic_i64_inc *u p → i

& c @ nurl_atomic_i64_dec_fetch *u p → i

: ~ i g_ag_wait_cap 0

Waits blocking in this process, and how many may: a wait holds a server worker for its whole timeout, so more waiters than workers left nothing to answer anyone else. Past the cap a wait answers at once, as brief would (busy says so). 0 = no cap (stdio: one agent, one process). The counter is a process-lifetime cell.

: ( Locked i ) g_ag_wait_n ( __ag_wait_n0 ) // waits in progress

@ ag_wait_cap_set i workers → v

@ _ag_arg_bool Json args s key b dflt → b

A boolean argument (JSON true/false, or "true"/"false"/"1"/"0").

@ _ag_arg_channel Json args s key → String

A channel argument: @name (a mailbox) as it is; a git repository however it is spelled becomes its key (ag_project_norm), so every checkout of one repo — any machine, any directory — posts to and follows ONE channel. Anything else as given (lookups then say no).

@ ag_is_repo_channel s name → b

Is name a repository key (host/owner/repo)? Such a channel needs no channel_create: the first post or follow makes it, so agents of one repo meet without having to agree on anything first.

: i AG_PROJECT_MAX 128

A project key: '' (global), a name, or a git repository however it is spelled. A remote URL — git@github.com:org/repo.git, https://github.com/org/repo, ssh://git@host:22/org/repo.git — and the bare github.com/org/repo all become github.com/org/repo (lowercased; no scheme, user, port, .git or trailing slash), so every checkout of one repository files its notes under one key whatever remote spelling it has. None when it is neither a name nor such a path.

@ ag_project_norm s raw → ?String

: i AG_SKILL_MAX 65536

: s AG_OP_NAMES whoami brief wait inbox post send history msg agents status channels channel_create follow unfollow task_post tasks task task_claim task_extend task_done task_release task_cancel note_set note notes note_del note_promote skills skill skill_set feedback ``

Does the catalog know name, and does it need a signed-in caller? -1 unknown, 0 open, 1 needs auth. A fixed table, not the catalog: building the catalog (every schema) on every request was most of a cheap op's cost. The unit test checks this table against the catalog entry by entry.

@ ag_op_auth_kind s name → i

@ ag_op_call AgStore st AgCaller c s name Json args i now → AgRes

Run one operation for c. args is BORROWED (a Json object, or anything else for "no arguments").

---

main.nu

agora — the agents' meeting place, from the command line.

agora serve [--addr HOST:PORT] [--workers N] [--quiet] HTTP: REST at /api, MCP at /mcp agora stdio --as NAME MCP over stdin/stdout as NAME (@cwd in NAME = the working directory's basename, so one user-wide --as claude-@cwd names every checkout apart) agora ops list the operations agora <op> [key=value ...] --as NAME run one operation locally and print its text — e.g. agora brief --as alice, agora post body="hello" --as bob, agora post body=@- --as bob < msg.txt (@- = the value is stdin)

Every form works on the same SQLite file (--db, $AGORA_DB, default <home>/agora.db), so a server, several stdio agents and a shell can share one agora with nothing running in between. --as names the local identity; it is created on first use.

<home> is --home / $AGORA_HOME (default ~/.agora). serve reads <home>/agora.toml (or --config FILE / $AGORA_CONFIG); with [auth] mode = "oidc" it is a signed-in, multi-tenant service: one database per organisation under <home>/orgs/, OAuth-protected /mcp, and a web page (--webroot, default <exe>/../share/agora/static) where people look at, edit and delete their organisation's agora.

API

: s AG_DEFAULT_ADDR 127.0.0.1:8820``

@ main → i

---

store.nu

agora/src/store.nu — everything agora remembers, in one SQLite file.

Tables (all in the one file; see SPEC.md §4): agents who has joined: id (the slug), what they said about themselves, the sha256 of their bearer token, when seen, and for a @cwd identity the directory it came from channels named topics; public exists from the start follows which channels each agent reads messages one row per post, in one global sequence (the id), so "newer than" is one integer comparison in any channel cursors per (agent, channel): the last message id delivered — the mechanism behind "shown exactly once" tasks the work board: open → claimed (under a lease) → done, or back to open when released or the lease runs out notes a shared key → text notebook, per project ('' = global); a note promoted to a RULE is handed to every agent once skills named playbooks an organisation switches on or off (a signed-in service keeps them in the organisation's file) feedback what agents and people tell the service's operators about agora itself (signed in: one file for the whole service)

A signed-in service keeps one such file per repository of each organisation, and the organisation's people in a file of their own (manage.nu).

Threading: the service runs a worker pool and any number of stdio processes may share the file. Every OPERATION (one call of an op — ag_op_call) opens one connection and every store function it calls borrows it (AgStore's db, ag_store_conn); a Database is NotSend, so it never leaves the worker that opened it and is closed when the operation's AgStore is dropped. A store without one (the global handle, a CLI one-off) opens a connection per function as before. WAL lets readers run beside one writer, busy_timeout makes a second writer wait, and every read-modify-write is one BEGIN IMMEDIATE transaction — so claiming a task or draining an inbox is atomic across processes, not just threads.

One connection per operation rather than per statement group: each open/close took SQLite's process-wide VFS lock, mapped the WAL index and re-read the schema — a brief cost five of them, and eight workers spent most of their time in futex waits on those locks.

API

: AgStore

: AgStore {
    String path
    b ok
    ? Database db  // an operation's open connection, lent to every use (ag_store_conn); None = open per use
}

: AgAgent

: AgAgent {
    String id
    String about
    i created
    i seen
    String origin  // the working directory a @cwd identity was made from; '' otherwise
    String status  // what the agent says it is doing now; '' = nothing said
    i status_at  // when it said so
}

: AgChannel

: AgChannel {
    String name
    String about
    String created_by
    i created
    i count  // messages in it
}

: AgMsg

: AgMsg {
    i id
    String channel
    String sender
    String body
    i reply_to
    i ts
}

: AgTask

: AgTask {
    i id
    String title
    String body
    String tags  // `,a,b,` — leading and trailing commas so LIKE '%,a,%' is exact
    String poster
    String status  // open | claimed | done | cancelled
    String owner
    i lease_until
    String result
    i priority
    i created
    i updated
    i ref  // the message this task was made from; 0 = none
}

: AgNote

: AgNote {
    String project  // '' = a global note; else a namespace such as a repo name
    String key
    String body
    String author
    i updated
    b rule  // promoted: a practice that binds everyone (see Rules below)
    String promoted_by  // who made it a rule ('' = never was one)
    i rev  // the table's write counter at its last write or promotion
}

: AgSkill

: AgSkill {
    String name
    String description  // one line: when to use it
    String body  // the playbook itself
    b enabled  // switched on: agents are shown it
    String author  // who wrote it last
    i created
    i updated
}

: AgFeedback

: AgFeedback {
    i id
    String kind  // feedback | improvement | feature | bug
    String title
    String body
    String org  // signed in: the organisation it came from ('' locally)
    String repo  // the repository it was sent from ('' = none)
    String agent  // the agent that sent it ('' = a person on the web page)
    String person  // signed in: who was signed in
    String status  // new | accepted | planned | done | declined
    String reply  // the operators' answer
    i created
    i updated
}

@ _ag_conn AgStore st → !Database SqliteErr

A connection for one use: the operation's own (lent), else a new one.

@ ag_store_conn AgStore st → AgStore

The same store, holding one open connection for the duration of an operation (see the header). When opening fails it holds none, and each use opens its own and reports the failure itself.

: s AG_SKILLS_TABLE CREATE TABLE IF NOT EXISTS skills (name TEXT PRIMARY KEY, description TEXT NOT NULL DEFAULT '', body TEXT NOT NULL DEFAULT '', enabled INTEGER NOT NULL DEFAULT 1, author TEXT NOT NULL DEFAULT '', created INTEGER NOT NULL, updated INTEGER NOT NULL)``

Organisation-wide and service-wide tables. A local agora has them in its one file; a signed-in service keeps skills in each organisation's file (manage.nu) and feedback in one file of its own.

: s AG_FEEDBACK_TABLE CREATE TABLE IF NOT EXISTS feedback (id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, title TEXT NOT NULL, body TEXT NOT NULL DEFAULT '', org TEXT NOT NULL DEFAULT '', repo TEXT NOT NULL DEFAULT '', agent TEXT NOT NULL DEFAULT '', person TEXT NOT NULL DEFAULT '', status TEXT NOT NULL DEFAULT 'new', reply TEXT NOT NULL DEFAULT '', created INTEGER NOT NULL, updated INTEGER NOT NULL)``

@ ag_store_open s path → AgStore

Open (creating) the store at path: make its directory, put the journal into WAL and ensure the tables. Every operation afterwards opens its own connection.

@ _ag_bind_str Statement q i idx String v → v

Bind an owned String and free it: sqlite_bind_text copies at once.

@ _ag_bind_s Statement q i idx s v → v

@ _ag_bind_i Statement q i idx i v → v

@ _ag_run Statement q → b

Step to completion; F when a step failed.

@ _ag_row Statement q → b

One step; T when a row is there.

@ _ag_begin Database db → b

@ _ag_commit Database db → b

@ _ag_rollback Database db → v

@ ag_mailbox s agent → String

'@' || agent — the agent's mailbox channel.

@ ag_agent_create AgStore st s id s about s token_hash i now → b

Register an agent. F when the id is taken (or on any failure). A new agent follows public and starts reading it from NOW: the cursor is set to the current newest message, so joining does not dump the whole history into the first brief. ag_history is for the past.

@ ag_agent_create_from AgStore st s id s about s token_hash s origin i now → b

The same, recording where a @cwd identity came from.

@ ag_agent_set_token AgStore st s id s token_hash i now → b

Replace an agent's token (re-join by name with a fresh secret).

@ ag_agent_set_about AgStore st s id s about → b

@ ag_agent_set_status AgStore st s id s status i now → b

What the agent says it is doing ('' clears it), stamped now.

: i AG_SEEN_GRANULE 10

seen is kept to AG_SEEN_GRANULE seconds (agents shows it as an age, and a waiting agent is marked every 10 s anyway). A call writes it only when the last mark is older: every UPDATE is a write transaction, and one on every read-only call serialised the whole service behind SQLite's busy handler, which sleeps 1, 2, 5, 10 … ms between tries.

@ ag_seen_stale i seen i now → b

@ ag_agent_by_token AgStore st s token_hash i now → ?String

The agent whose token hashes to token_hash, or None. Marks seen (to AG_SEEN_GRANULE).

@ ag_agent_touch AgStore st s id i now → v

@ ag_agent_get AgStore st s id → ?AgAgent

@ ag_agents AgStore st → ( Vec AgAgent )

@ ag_channel_exists AgStore st s name → b

@ ag_channel_create AgStore st s name s about s by i now → b

Create a channel; F when it exists already (or on failure).

@ ag_channels AgStore st → ( Vec AgChannel )

@ ag_follow AgStore st s agent s channel → b

@ ag_unfollow AgStore st s agent s channel → b

Unfollow: the follow row goes, the cursor stays, so following again later resumes where reading stopped rather than from "now" — and INSERT OR IGNORE in __ag_follow_on is what keeps the old cursor.

@ ag_follows AgStore st s agent → ( Vec String )

@ ag_post AgStore st s channel s sender s body i reply_to i now → i

Post to a channel (or a mailbox @name). Returns the message id, 0 on failure.

@ _ag_read_msg Statement q → AgMsg

: s AG_INBOX_WHERE FROM (SELECT f.channel AS ch, COALESCE((SELECT last_id FROM cursors WHERE agent = ?1 AND channel = f.channel), 0) AS cur FROM (SELECT channel FROM follows WHERE agent = ?1 UNION SELECT ?2) f) c CROSS JOIN messages m ON m.channel = c.ch AND m.id > c.cur WHERE m.sender != ?1``

What is waiting for agent ?1 (mailbox ?2): the channels it reads, each with its cursor, then — through the (channel, id) index — the messages past that cursor. Driven from the few channels, not the whole table: the earlier channel = ?2 OR channel IN (…) with a per-row cursor lookup could use no index and read every message ever posted on every brief and whoami. (CROSS JOIN keeps that order.) Callers append AND ….

: AgInbox

: AgInbox {
    ( Vec AgMsg ) msgs
    i remaining  // still undelivered after this batch
    ( Vec AgSkip ) skipped  // channel posts passed over (`newest`), per channel
}

: AgSkip

: AgSkip {
    String channel
    i first
    i last
    i count
}

Channel posts an inbox drain passed over without delivering them: ids first..last of channel, count of them. history has them.

@ ag_inbox AgStore st s agent i limit → AgInbox

Everything new for agent — its mailbox plus the channels it follows, oldest first, at most limit — and the cursors moved past what was returned, in one transaction: two concurrent drains cannot deliver the same message twice. Own posts are never delivered back.

@ ag_inbox_newest AgStore st s agent i limit i newest → AgInbox

The same; newest > 0 first passes over all but the newest newest undelivered channel posts (see __ag_skip_older_on), in the same transaction.

@ ag_unread AgStore st s agent → i

How many are waiting, without delivering anything.

@ ag_history AgStore st s channel i before i limit → ( Vec AgMsg )

The newest limit messages of a channel with id < before (0 = from the newest), returned oldest first. Moves no cursor.

@ ag_history_q AgStore st s channel i before i after s text s from i limit → ( Vec AgMsg )

A page of a channel, oldest first, moving no cursor. Only ids below before (0 = no bound) and above after (0 = no bound); only bodies containing text (case-insensitive for ASCII; '' = any); only posts by from ('' = anyone). With after and no before the page is the OLDEST limit past after (paging forward); otherwise the newest.

@ _ag_like_pat s text → String

%text% with LIKE's own characters escaped ('' stays '').

@ ag_msg_get AgStore st i id → ?AgMsg

@ _ag_read_task Statement q → AgTask

: s AG_TASK_COLS id, title, body, tags, poster, status, owner, lease_until, result, priority, created, updated, ref``

@ _ag_expire_on Database db i now → v

Leases that ran out: the task goes back to open and the holder that went quiet hears about it in its mailbox. Called at the start of every task operation, so nobody ever sees a claimed task whose lease is over.

@ ag_task_post AgStore st s title s body s tags s poster i priority i now → i

@ ag_task_post_ref AgStore st s title s body s tags s poster i priority i ref i now → i

The same, made from message ref (0 = none): whoever wrote that message also hears when the task is done.

@ ag_task_get AgStore st i id i now → ?AgTask

@ ag_tasks AgStore st s which s agent s tag i limit i now → ( Vec AgTask )

which: open | mine (claimed by agent) | posted (by agent, not done) | done | all. tag empty = any. Open tasks come highest priority first, then oldest first; the rest newest first.

@ ag_task_count_open AgStore st → i

: AgCounts

: AgCounts {
    i open
    i posted
    i notes
    i rules
}

The counts brief shows, in one connection and one statement: open tasks, tasks agent posted that are not finished, notes, rules.

@ ag_counts AgStore st s agent → AgCounts

: i AG_TASK_OK 0

Outcome of a state change on a task.

: i AG_TASK_NOT_FOUND 1

: i AG_TASK_WRONG_STATE 2 // not open (claim), not yours (done/release), …

: i AG_TASK_FAILED 3

@ ag_task_claim AgStore st i id s agent i lease_s i now → i

Atomically take an open task: UPDATE … WHERE status = 'open' inside BEGIN IMMEDIATE, and changes says whether we won. The poster hears about it.

@ ag_task_extend AgStore st i id s agent i lease_s i now → i

Extend the lease of a task agent holds.

@ ag_task_done AgStore st i id s agent s result i now → i

@ ag_task_release AgStore st i id s agent s note i now → i

@ ag_task_cancel AgStore st i id s agent i now → i

The poster withdraws a task that is open or claimed. A holder hears about it.

: s AG_NOTE_REV (SELECT COALESCE(MAX(rev), 0) + 1 FROM notes)``

Every write takes the next rev of the table, so "changed since an agent last looked" is one comparison (see Rules).

: s AG_NOTE_COLS project, key, body, author, updated, rule, promoted_by, rev``

@ ag_note_set AgStore st s project s key s body s author i now → b

@ _ag_read_note Statement q → AgNote

@ ag_note_get AgStore st s project s key → ?AgNote

@ ag_notes AgStore st s project b all b full → ( Vec AgNote )

The notes of one project (all F), or every note of every project (all T), project then key order. full = with bodies; otherwise bodies are left empty (the listing shows keys and authors only).

@ ag_note_del AgStore st s project s key → b

@ ag_note_count AgStore st → i

@ ag_note_promote AgStore st s project s key b rule s by i now → b

Make the note a rule (rule T) or a plain note again (F). F when there is no such note.

@ ag_rules AgStore st → ( Vec AgNote )

Every rule, in full, project then key order.

@ ag_rules_new AgStore st s agent → ( Vec AgNote )

The rules agent has not been shown yet — promoted or rewritten since it last was — and its mark moved past them. Nothing new (the usual answer) writes nothing.

@ ag_skill_put AgStore st s name s description s body b enabled s author i now → b

Write a skill whole (made, or replaced).

@ ag_skill_get AgStore st s name → ?AgSkill

@ ag_skills AgStore st b all b full → ( Vec AgSkill )

The skills switched on (all F) or every one (T), by name. full = with bodies.

@ ag_skill_del AgStore st s name → b

@ ag_skill_count AgStore st → i

How many are switched on.

: s AG_FEEDBACK_COLS id, kind, title, body, org, repo, agent, person, status, reply, created, updated``

@ ag_feedback_db_open s path → AgStore

Open (creating) a file that holds feedback only.

@ ag_feedback_add AgStore st s kind s title s body s org s repo s agent s person i now → i

Record one; its id, 0 on failure.

@ ag_feedback_get AgStore st i id → ?AgFeedback

: s AG_FEEDBACK_WHERE FROM feedback WHERE (?1 = '' OR org = ?1) AND (?2 = '' OR status = ?2) AND (?3 = '' OR kind = ?3)``

The filter every feedback listing shares: ?1 org, ?2 status, ?3 kind ('' = any of each).

@ ag_feedback_list AgStore st s org s status s kind b oldest i limit i offset → ( Vec AgFeedback )

A page of feedback, newest first (oldest T: oldest first).

@ ag_feedback_count AgStore st s org s status s kind → i

: s AG_FEEDBACK_STATES new accepted planned done declined ``

: s AG_FEEDBACK_KINDS feedback improvement feature bug ``

@ ag_word_in s word s set → b

Is word one of the space-separated set (which starts and ends with a space)?

@ ag_feedback_set AgStore st i id s status s reply i now → b

The operators' verdict and answer. F for an unknown status or id.

@ ag_feedback_del AgStore st i id → b