AGORA+ Taste Council

A household assistant that turns what it remembers about each person into Qloo signals, ranks one shortlist for each of them, and picks the option nobody ranks low.

Live demo: https://agora-plus-295478535981.us-central1.run.app (household passcode: tastecouncil — a fictional family is preloaded)

Submitted to the Qloo Agentic Hackathon ("Agents, but with taste"). Source code is MIT (LICENSE). The deep dive is docs/QLOO.md. Copy-ready submission text is docs/SUBMISSION_QLOO.md.

The problem

AGORA+ is a self-hosted household assistant. It keeps facts about each family member in a file on your server, every write comes back with a receipt, and anything with side effects waits for a person's yes. It is reachable as an MCP server (Claude, ChatGPT, Alexa+-style clients) and from a voice and text assistant on its Home page.

It already knew "Mia loves Encanto", "Dadi is 74" and "Arjun is vegetarian". But when someone asked "what should we watch tonight?", a language model alone could only guess. It tends to pick something generic, or something for whoever spoke last. It has no grounded way to say how a 74-year-old who loves Raj Kapoor films and a 9-year-old who loves Encanto would each rank the same five films.

That is a daily question in multigenerational homes, which are common in India and in many other places: movie night, dinner out, a road-trip playlist, a show to watch together, a family book club, a weekend outing. The Taste Council answers it with Qloo, and shows its work.

Related MCP server: Swiggy Syndicate

Try it in 60 seconds

On the live demo (a fictional family: Mia 9, Rohan 16, Arjun 41, Dadi 74):

1. Open the link and enter the household passcode. Home opens.

2. Find the Taste Council card. There is one chip per person, with their age band, what they love, and what Keeper watches for (for example "Keeper watches: vegetarian").

3. Leave everyone in, choose Family movie night, and press Ask the council.

4. The result sheet shows the pick, each person's rank for it ("#2 of 10"), who it suits least ("Lowest fit"), Qloo's tags, and the runners-up.

5. Open Qloo calls at the bottom. Every call is listed: the tool, who it was for, the status, the result count, the time in ms, and the exact arguments sent.

6. Choose Dinner out with the location "Bandra, Mumbai". Arjun's Qloo calls ask for places with vegetarian options, and if a candidate is clearly meat-centric (a kebab or fried-chicken place) or a satay place, Keeper sets it aside under "Keeper removed" and quotes the fact ("Arjun is vegetarian", "Mia is allergic to peanuts").

7. Tap a chip to leave someone out, for example only Mia and Dadi, and ask again.

8. In the assistant box, type "What should we watch tonight?". The model calls the taste_council MCP tool, and Under the hood shows that tools/call.

How the council decides

flowchart TD
  mem["Household memory: 'Mia loves Encanto', 'Dadi is 74', 'Arjun is vegetarian'"]
  parse["profile.ts: per person loves, likes, age band, constraints (no model)"]
  rec["qloo_recommend, once per person: their loves as signals, plus age band and location"]
  short["Shortlist: round-robin across people, deduplicated, at most 10"]
  rank["qloo_rank, once per person, same shortlist: ordinal ranks"]
  maximin["Maximin: best worst-rank, then best mean rank"]
  keeper["Keeper: drop picks that clash with a diet, allergy or 'no X' fact, and quote it"]
  out["Top 5 picks, one spoken sentence, every Qloo call"]
  mem --> parse --> rec --> short --> rank --> maximin --> keeper --> out
  home["Home page: POST /api/taste/council"] --> parse
  mcp["MCP tool taste_council: Claude, ChatGPT, the Gemini voice assistant"] --> parse

1. Facts become signals. server/taste/profile.ts reads household memory with plain rules. "Dadi loves Raj Kapoor films, Lata Mangeshkar and Mughal-e-Azam" gives three named loves. "Arjun likes thrillers" gives a tag. "Dadi is 74" gives the band 55+. "Mia is allergic to peanuts" gives a constraint.

2. Candidates per person. One qloo_recommend call per person, for the target type of the occasion (movie, tv_show, artist, book, or place). Dinner asks for Qloo's restaurant genre, an outing for attractions such as parks and museums. A vegetarian's or vegan's dinner calls also carry Qloo's vegetarian or vegan options tag. When someone is under 18, films, shows, music and books rated for adults are left out, and the result says so.

3. One shared shortlist. Round-robin across people, so everyone's candidates get in. At most 10 options, because qloo_rank accepts at most 10.

4. Rank the same list per person. One qloo_rank call per person over that shortlist. Qloo says scores from separate calls are not comparable, so the council keeps only each person's order (1st, 2nd, ...).

5. Maximin. The winner is the option whose worst rank across people is best. Ties go to the better mean rank. Nobody gets their 9th choice so that someone else gets their 1st.

6. Keeper. Picks that clash with a diet, allergy, or "no horror" fact are removed, and the fact is quoted. Here Keeper is plain code (a keyword check), not the model agent of the same name in the household team.

7. Receipts. The result carries every Qloo call. The Home page keeps the last few councils after a reload.

The algorithm is in server/taste/council.ts. The contract shared by server and page is shared/taste.ts.

Qloo tools used, and why

The council talks to Qloo through Qloo's official harness, qloo mcp (package @qloo/qloo-harness@0.1.26), started as a child process over stdio (server/taste/qlooClient.ts). That is the route Qloo's hackathon kit recommends. There are no raw HTTP calls to Qloo in this repository.

The harness offers nine workflow tools. The council uses the two that fit a group decision. qloo_describe, qloo_entity_tags, qloo_find_tags, qloo_compare_audiences, qloo_audience_demographics, qloo_where_popular and qloo_trends are not used yet.

When Qloo cannot resolve a name, the harness returns needs_input with candidate matches. The council chooses one (a film or artist over an album of the same name), retries once with its Qloo id, and remembers it in taste-entities.json, so later calls send the id (server/taste/entityMemo.ts). With AGORA_DEMO_SEED=1 the demo family starts out resolved. Calls are cached for 30 minutes and run one at a time by default (AGORA_QLOO_IN_FLIGHT, 1 to 4). A rate-limited (429) call is retried after 1.5 s and 4 s, within the council's 40-second deadline. A location such as "Bandra, Mumbai" filters places to Bandra and sends Mumbai as the audience location. See docs/QLOO.md, which also has live results from the deployed demo.

What is Qloo, what is code, what is Gemini

No model chooses the winner. The Home page's Ask the council button runs with no model at all.

Why it needs Qloo

Take Qloo out and the council has nothing to rank with.

• Cross-domain taste. Dadi's signals are a filmmaker, a playback singer and a 1960 film. Mia's are two animated films and a pop star. Qloo's taste graph turns both into ranked films, books or restaurants. A model can name films, but it has no measured affinity behind the order.

• Audience demographics. An age band and a location become a Qloo demographic signal, so "seniors in Bengaluru" and "teens in Bengaluru" pull the ranking in different directions.

• Rank against a profile. qloo_rank puts one fixed list in order for one person. That per-person order is the input to the fairness rule. A model has no grounded per-audience ranking to give.

Responsible use

• What goes to Qloo: entity names as written in memory ("Encanto"), abstract likes as tags ("thrillers"), an age-band phrase ("seniors", "adults 35-44"), a location string, the target type, and the shortlist's Qloo entity ids. An "avoid" fact such as "no horror" is sent as an exclude tag for films, shows, music and books. At dinner, a vegetarian or vegan diet is sent as Qloo's "vegetarian options" or "vegan options" place tag, with no name attached.

• What stays on the server: first names, exact ages, allergies, other diets, and the text of the facts. Names appear only in the local call log ("for Mia"). Keeper checks diets and allergies locally.

• The key is read by the qloo mcp child from QLOO_API_KEY or the harness's own config. Our code never logs it or returns it, and scrubs it from error text.

• Aggregate, not personal. Qloo results are aggregate cultural affinities, not predictions about any one person. The card and the result sheet both say so.

• Nothing is booked or bought. The council suggests. Adding a pick to the to-do list is a separate button.

• The demo family is fictional. It is written only when AGORA_DEMO_SEED=1 and memory is empty, and it is tagged demo.

Limits

What a council result does not establish:

• That a person will enjoy the pick. "#2 of 10 for Dadi" means Qloo placed it second among those ten options for a profile built from Dadi's saved favourites.

• That the pick is the best option anywhere. Ranks are only within a shortlist of at most 10.

• That the pick is suitable for a child. With someone under 18, only adult ratings (R, TV-MA, A, 18) and explicit titles are left out. Only an age band is known, so TV-14 and PG-13 still pass for a 9-year-old, and books have no rating. A parent should check.

• That a place is safe for an allergy or a diet. Keeper is a keyword check on names, tags and descriptions, not a menu or ingredient check. The diet tag only says whether Qloo lists vegetarian or vegan options.

• That "#2 for Mia" and "#2 for Dadi" mean the same strength of liking. Only order within one person's call is used.

Other limits:

• Under-18 maps to the phrase "teens", which Qloo's harness turns into its youngest age bucket (24 and younger). There is no "children" demographic, so a 9-year-old and a 16-year-old get the same age signal.

• Age and location signals are sent only when a location is known (the request, or AGORA_TASTE_LOCATION). Only the first comma part of a location filters places.

• A person with only abstract likes ("street food") and no named favourite or location cannot be ranked. The result says so.

• The fact parser is English pattern rules. Unusual phrasing is missed. taste_profile shows what it understood.

• Maximin is one fairness rule. It can choose a pick everyone ranks third over one most people rank first.

• When needs_input offers several matches, the council chooses one without asking and remembers it. It can be the wrong "Coco", and stays wrong until taste-entities.json is cleared.

• One household per server.

Run it yourself

Full setup from a clean machine, environment variables, and the Cloud Run command are in docs/QLOO.md. The short version:

npm install --global @qloo/qloo-harness@0.1.26
qloo setup --qloo                                        # paste the key; it is hidden
qloo config set base-url https://hackathon.api.qloo.com
git clone https://github.com/Ritesh-Root/agora-taste-council.git && cd agora-taste-council
npm ci
AGORA_DEMO_SEED=1 AGORA_TASTE_LOCATION=Bengaluru npm run dev

Open http://127.0.0.1:3000/. The Taste Council card works without any language model. The assistant box needs one (see Quick start).

From Claude Code, with AGORA_MCP_TOKEN set (at least 32 characters):

claude mcp add --transport http agora http://127.0.0.1:3000/mcp --header "Authorization: Bearer $AGORA_MCP_TOKEN"

Then ask "What should the family watch tonight?" or "Where should Arjun and Mia eat in Bengaluru?".

The rest of AGORA+

The household layer was first built for the Amazon Developer Hackathon (Alexa+ track), on top of the AGORA office. The sections below describe that base. They are still accurate for this build.

Household memory is a file on a server you run. Every write returns a receipt whose verified flag is a second read of that file. Nothing with side effects starts until a person says yes, and that wait is in the tool result, not only in a prompt.

The surfaces that were run for the Alexa+ entry are the unofficial voice page at /alexa and the MCP server at /mcp, used from Claude Code with AGORA_MCP_TOKEN. MCP clients such as Alexa+ add-ons, Claude, and ChatGPT can connect to that same server. ChatGPT was not run against it, and a live Alexa+ add-on was not deployed. The add-on package in alexa-addon/addon.json is still a template: every URL contains <host>.

Why memory with receipts

Other assistants already advertise family memory, shopping lists, and device control. This server keeps household facts on the machine you run, and a plan does not start until a person says yes. Lights, locks, calendars, and countdown timers are not in this build.

The Alexa+ entry was shaped by four complaints from an 8 Oct 2026 research pass: jobs that stop halfway, slow replies, stored facts that disappear, and people who want a checkpoint before an agent acts. Quotes and sources are in docs/research/alexa-plus-voice-of-customer.md and docs/research/sources.json. In this build:

• remember, recall, and forget are backed by memory.json and the MCP resource agora://memory. A fact can name a person (who). The Household panel can edit it.

• forget and plan_and_run return needs_approval. Remembering a fact and adding a task do not wait. On /alexa the model cannot call approve_action. A person says an exact yes or no, or uses a button. approve_action stays an MCP tool for external clients.

• A plan shows its steps and waits for a yes before the team starts. The receipt on a write is a separate thing: verified is a read-back from disk.

What it does

• Household Home at / (also /alexa). This is the page to open first. A greeting with the briefing, the assistant, the Taste Council, Today's reminders, the Shopping and To-do lists (tick, untick, remove, clear the basket), Family facts grouped by person with Allergy, Diet, and Medical badges, and Plans. While a plan runs, the Plans card shows each team member's step and its status; a finished plan opens in the page. Connect shows the /mcp endpoint and the claude mcp add command. Under the hood opens the MCP trace beside the page.

• Voice assistant on Home. Unofficial simulated Alexa+ experience. Type, or tap or hold to talk. Remember, recall ("What is Mia allergic to?"), the briefing, the shopping list, reminders, and an exact yes or no are routed with no model call (server/alexaSim/fastPath.ts). Other turns go to the server model, which calls tools through the real /mcp endpoint. A plan asks the model once for the step list, and only after that preview returns steps does the page wait for a yes. Orders, purchases, bookings, payments, and phone calls are refused, with no approval id. The page shows an "Under the hood" trace of each MCP tools/call. While it is open it polls GET /api/household about every 30 seconds and speaks "Reminder: <title>." once per due task per page load.

• MCP server at /mcp. Thirteen tools always (including taste_council and taste_profile), and web_research as a fourteenth when FIRECRAWL_API_KEY or EXA_API_KEY is set. Three resources (agora://memory, agora://tasks, agora://runs/{id}/document) and two prompts (morning-briefing, plan-a-week-of-meals). Streamable HTTP. The server negotiates protocol 2025-11-25 and newer (server/mcp/mcp.test.ts). Alexa's published client sample sends 2025-03-26. The specification index on 8 Oct 2026 names 2026-07-28 as current (docs/council/reports/g4-spec-followup.md). OAuth is in server/mcp/oauth.ts. daily_briefing and list_tasks put the MCP Apps card on the tool result as well as the tool definition (ui://daily_briefing/household-card.html). The tool reference is skills/agora-household/references/TOOLS.md.

• People, lists, and reminders. A fact can store who (a leading name such as "Mia is allergic to peanuts" is enough). A task can store who, list (shopping is its own list; absent means the main to-do list), and dueAt (ISO 8601 with a numeric offset). The free-text due stays. The briefing speaks one memory line, allergies and medicine first ("Remember: Mia is allergic to peanuts."). Recall says both facts when they tie.

• Agent Skill skills/agora-household/SKILL.md. How to connect, which tool to call, and the rule that a needs_approval result waits for a person.

• Server model. AGORA_SERVER_LLM picks it. vertex calls Gemini on Vertex AI through its OpenAI-compatible endpoint, with Application Default Credentials (server/llm/vertexProvider.ts). bedrock calls Amazon Bedrock through the Claude Messages endpoint (server/llm/bedrockProvider.ts), only when AWS credentials are present. openai calls any OpenAI-compatible endpoint (AGORA_LLM_* in .env.example, server/llm/openaiProvider.ts).

• Household team: Agora, Scout, Planner, and Keeper (server/household/team.ts), on whichever server model is set. Keeper checks plans against memory. A step whose model call fails is marked for help and the rest of the team finishes. The plans recorded during the Alexa+ hackathon used the openai mode with open Qwen models on Featherless, because no AWS credentials were present. A live Bedrock call was not recorded in this workspace.

• Polly speaks when AWS credentials are present (server/alexaSim/tts.ts). The browser voice speaks when Polly returns 503. A successful Polly synthesize was not recorded, so time to first audio was not measured.

• Approvals and receipts. forget and plan_and_run wait. Remembering and adding a task do not. Every write can show { action, id, verified, at }. verified is a follow-up read. A failed yes leaves the approval pending so it can be retried. Waiting approvals still live in the process and expire after ten minutes.

• 3D office at /office. The Household cast is the roster. A household run is written to runs/<id>.json with status: "running" when it starts, and again when it ends. The Society panel shows spokenSummary when the run has one.

• Alexa+ add-on package in alexa-addon/addon.json, plus public/privacy.html and public/terms.html. Account linking is enabled in the file (authorization code, PKCE S256). The manifest lists the United States only, and every URL is still https://<host>/.... alexa-ai was not deployed from this workspace.

The file map is docs/ARCHITECTURE.md.

Screenshots

Captured from the running app on 10 and 12 Oct 2026, before the Taste Council was added.

Claude Code, a separate MCP client, answering from the same household. The output of a real claude -p run, set as text:

A forget request sent over MCP comes back as needs_approval and waits on the Home page for a person:

Quick start

You need Node.js and npm. The Dockerfile uses Node 22. Qloo's harness asks for Node 22.19.0 or newer. The repository does not declare an engines field.

git clone https://github.com/Ritesh-Root/agora-taste-council.git
cd agora-taste-council
npm ci
cp .env.example .env

The voice page, remember, the briefing, the shopping list, recall, and the Taste Council card do not need a language model. The Taste Council needs Qloo (docs/QLOO.md).

For Gemini on Vertex AI, sign in with gcloud auth application-default login and start the server with these in the shell. npm run dev copies only AGORA_*, AWS_*, BEDROCK_*, POLLY_*, QLOO_* and a few other named settings from .env into the server, so GOOGLE_CLOUD_PROJECT and VERTEX_* must come from the shell:

AGORA_SERVER_LLM=vertex GOOGLE_CLOUD_PROJECT=your-project npm run dev

Defaults are google/gemini-3.8-flash, and google/gemini-3.5-flash-lite for spoken turns. Override with VERTEX_MODEL and VERTEX_FAST_MODEL, or set ALEXA_SIM_MODEL=google/gemini-3.8-flash to use Flash for spoken turns too.

For Amazon Bedrock instead, with AWS credentials on the standard chain (aws login, a profile, or a task role), in .env (values only, never commit the file):

AGORA_SERVER_LLM=bedrock
AWS_REGION=us-east-1

Bedrock defaults are anthropic.claude-sonnet-5 and anthropic.claude-haiku-4-5. Override with BEDROCK_MODEL and BEDROCK_FAST_MODEL if you need to.

Claude Code needs a development token of at least 32 characters. A shorter value is ignored.

AGORA_MCP_TOKEN=choose-at-least-32-random-characters

OAuth also needs AGORA_OAUTH_CLIENT_ID, AGORA_OAUTH_CLIENT_SECRET, and AGORA_TOKEN_SECRET (at least 32 characters). A public process also needs AGORA_PUBLIC_URL and AGORA_HOUSEHOLD_PASSCODE. If the OAuth secrets are empty, those routes return 503 and the development token is the one that can call tools. The token is ignored when NODE_ENV=production or AGORA_PUBLIC_URL is https, unless AGORA_ALLOW_DEV_TOKEN=1. The voice assistant reaches its tools through /mcp, so it needs OAuth or an accepted development token too.

npm run dev

npm run dev starts Vite on port 3000 and binds 127.0.0.1, with the room relay and /mcp. Open http://127.0.0.1:3000/ for the household Home. The optional 3D team view is http://127.0.0.1:3000/office. /alexa is the same Home. npm run dev:lan binds 0.0.0.0. On that bind, /mcp and OAuth return 503 until AGORA_PUBLIC_URL is set, and household routes from another machine return 403 until AGORA_HOUSEHOLD_PASSCODE is set.

Environment

Names the server reads. Empty in .env.example means unset. The Qloo and Vertex names are in docs/QLOO.md. The full table, including office and deploy names, is docs/DEPLOY.md. Do not commit real values.

Other scripts:

npm run build        # client in dist/, and the household card
npm run preview      # static client only; no room and no MCP
npm run lint         # client typecheck
npm run lint:server  # server typecheck
npm test             # unit tests
npm run test:e2e     # Playwright; starts its own server on port 3000

./run-agora.sh is an optional Chrome launcher for hardware WebGPU on Linux. The office runs without it.

Hosting (named tunnel, ECS, Cloud Run) is docs/DEPLOY.md. The Cloud Run command with Qloo and Vertex is in docs/QLOO.md.

Connect from Claude Code or any MCP client

The skill is skills/agora-household/SKILL.md. With the development token:

claude mcp add --transport http agora http://127.0.0.1:3000/mcp --header "Authorization: Bearer $AGORA_MCP_TOKEN"

Any other client uses Streamable HTTP POST http://127.0.0.1:3000/mcp with Accept: application/json, text/event-stream and Authorization: Bearer <token>. A client-credentials token (scope=mcp:service) can list tools. Calling them needs mcp:tools, from the authorization-code grant or from AGORA_MCP_TOKEN.

Try: "What is Mia allergic to?" after you have saved that fact on /alexa, or "What should the family watch tonight?" once Qloo is set up.

History: the Alexa+ hackathon (Aug 31 – Oct 23, 2026)

AGORA existed before that window. The baseline tag pre-window is commit 4f61371 (2026-08-20). git diff --stat pre-window..HEAD on 8 Oct 2026, at commit fa7a9c0, was 288 files changed, 29768 insertions, 2318 deletions, over 40 commits dated 2026-09-23 through 2026-10-08. September kept building the office. 8 Oct added the household brain and the fix wave: people on facts and tasks, the shopping list, reminders, the approval gate in the voice loop, the household lock, persisted OAuth refresh, the MCP Apps card on tool results, and the Household cast in the office. The phase log is docs/HACKATHON_CHANGES.md.

That entry's tracks were Alexa+ (primary), AWS Builder, and Open Source. Its Devpost text is docs/SUBMISSION.md. Also: docs/ARCHITECTURE.md, docs/AWS.md, docs/DEMO_SCRIPT.md, docs/FEEDBACK.md, docs/FRICTION_LOG.md.

The number to read on /alexa is time to first audio. It was not measured: the browsers on the build machine had no speech voices, so the fast path only ever showed "text only", and Polly and the model path need credentials. Older local timings were acknowledgement and screen times, not first audio: phase 4 saw the acknowledgement on the wire in 5 ms and on screen in 50 ms and 63 ms; phase 6 logged 55–58 ms to that acknowledgement, about 100 ms for a full remember turn, and about 800 ms from "plan dinners" to the approval card when a preview existed.

The Taste Council, the Vertex AI provider, the demo family, and the Qloo docs were added after that window, for the Qloo Agentic Hackathon.

Household limits

• One household per server, and one office room in the memory of that process (server/roomState.ts, docs/DEPLOY.md). Waiting approvals and authorization codes are in that same process. Approvals expire after ten minutes. OAuth refresh records and the simulator's linked account are files and survive a restart.

• Household files are on the task disk (.agora-data or AGORA_DATA_DIR). Replacing the task deletes them unless that directory is on a volume. POST /api/memory and POST /api/tasks do not yet accept who, list, or dueAt. A fact that starts with a capitalised name still stores who. The MCP tools accept the fields.

• The Alexa+ add-on manifest distributes to the US only and was not deployed (alexa-addon/addon.json).

• No device control, no calendar, and no countdown timer. Lights, locks, and Hue routines stay out of the demo (docs/research/feature-matrix.md).

• The microphone uses Web Speech (src/alexa/useSpeechInput.ts). Record in Chrome. The text box works when that API is missing.

• A live Bedrock call and a successful Polly clip were not recorded here.

• Taste Council limits are above and in docs/QLOO.md.

The shared office

AGORA is Ritesh-Root’s open-source workspace where people and AI agents share tasks, chat, and one Markdown document. The session is drawn as a 3D office. When WebGPU and WebGL2 are both unavailable, the same session uses a 2D office.

This repository is a working local workspace, not a finished hosted product. A room lives in the memory of one server process. The current source includes a production process and host controls. The office has no public deployment URL of its own; the live demo link at the top is the household Home.

What you can do

Implemented in the current source:

• Join one shared room, up to five people, with a display name and a color. There are no accounts.

• Talk in the room. @all asks the team to discuss the idea. @name addresses one teammate. Chat does not start the document.

• The host submits a brief and starts the run with Run Swarm, then Execute Swarm.

• Watch planning, worker tasks, a debate when the run calls for one, and the assembled Markdown document.

• See the session in a 3D office (WebGPU, or WebGL2) or the 2D fallback.

• Save the document to your own machine as agora-document.md.

• Leave on your own, or, as host, end the session for everyone.

• Save more than one OpenAI-compatible model connection in this browser. One is the default. An agent can use another connection and override its model. Keys stay in the browser and are not stored in the room.

• Start the header’s benchmark control. That automated comparison is not a user study. See Validation and performance.

Not in this build: saved cloud rooms, accounts, spending caps, and host approval before a document edit becomes final. See Roadmap.

Joining the office

Install and run from Quick start. Open http://127.0.0.1:3000/ for the household Home. The optional 3D team view is http://127.0.0.1:3000/office.

On loopback, with no DEMO_HOST_SECRET, the first person to join is the host. On an open bind (0.0.0.0) with that secret unset, the first caller is not the host. The host seat is a household session, which exists only when AGORA_HOUSEHOLD_PASSCODE is set. With neither the secret nor the passcode, that room has no host. With the secret set, only a matching host code, or the server-issued resume token, makes someone the host. A display name does not. When a passcode is set, the office socket needs the agora_household cookie.

A browser-supplied model key stays in localStorage under Model connections. The room does not store it. With a server model set (AGORA_SERVER_LLM), the office can call it when the browser sent no key. See docs/AWS.md.

How a session works

1. People join the room. Everyone connected can see the brief, the tasks, the document, and public chat.

2. @all and @name send chat. The named agents can reply. That discussion does not create the document.

3. The host runs Execute Swarm. A second Execute while a run is active is refused with “A run is already in progress.”

4. Planning splits the brief into tasks. Workers run those tasks. An invalid worker output can be retried once.

5. Debate is conditional. With fewer than two usable worker outputs, there is no debate. Otherwise the first two are debated for up to two rounds. A referee scores each round, and a clear winner ends it early. Without one, the referee sums up the decision the host has to make. Then the lead writes one Markdown document.

6. If the brief says “under 400 words,” the document may be at most 399 words. A word is a whitespace-separated span after trimming, and headings count. Up to two shortening passes may run. A draft that is still over the limit is kept and labelled “Needs revision: exceeds word limit.” If both the word limit and required sections fail, the word-limit label is the one shown. Repair calls are counted separately from the other model calls.

7. Section checks run only when the brief names problem, audience, priorities, and next steps. A miss is labelled “Needs revision: missing required sections.”

8. Save a copy downloads the Markdown. The room copy disappears when the process restarts.

Leave room drops only that person. End session, confirmed with End for everyone, is host-only. The server rejects anyone else with “Only the room host can end the session.” and does not wipe the room. A successful end stops scheduling, clears the room and the run, tells every client, and closes the sockets. A late model result cannot restore that document.

After you leave or the host ends the session, the page stays disconnected. An unexpected drop shows a reconnect screen. The separate Watch a live run control is an explicit local replay.

System architecture

flowchart LR
  ui[Browser UI]
  http[HTTP and WebSocket server]
  room[In-memory room and run]
  orch[Orchestrator]
  model[OpenAI-compatible chat API]

  ui --> http
  http --> room
  room --> orch
  orch --> model
  model --> orch
  orch --> room
  room --> ui

The browser shows the office, chat, task board, and document. In development, the Vite server attaches the relay and the /api/cors-proxy route. The production entry, server/prod.ts, listens on PORT (8080 if unset). It binds 0.0.0.0 only when AGORA_HOUSEHOLD_PASSCODE is set, and 127.0.0.1 otherwise. It serves dist/ and attaches the same relay and proxy.

One process holds one room: roster, the last 100 public chat messages, cabin assignment, and a single run. Stages reported on that run are planning, working, debating, assembling, and repairing.

The orchestrator asks an OpenAI-compatible /chat/completions endpoint. The browser proxy forwards only an https URL whose path ends in /chat/completions, and only when the caller sends Authorization. It refuses private, loopback, and link-local targets, and it refuses redirects.

The office room is still the memory of one process. A restart clears the roster, the chat, and the live run. Household facts, tasks, and finished runs are files under .agora-data (or AGORA_DATA_DIR). See docs/ARCHITECTURE.md.

Model configuration

Open Model connections in the header. Each saved connection has a name, an OpenAI-compatible base URL, an API key, and a default model ID. Test connection calls that endpoint and shows a short error. It does not print the key.

One connection is the default for this browser. An agent uses that default unless you pick another connection for it. A model ID on the agent replaces the connection’s model only when it differs. Every browser connection uses the same chat-completions protocol. The server's Bedrock path is separate and uses the Claude Messages endpoint. See docs/AWS.md.

A single configuration saved earlier under byok-config is copied into the connection list on the next load. The key, URL, and model are kept. The copy is stored in this browser under agora-model-connections.

Key handling:

• Your connections and keys stay in this browser. Room state stores chat, tasks, and the document. It does not store keys.

• A caller key is sent as-is and is never replaced by the server key or by another connection’s key.

• A call without a caller key fails with “Add an API key for that model endpoint.” when no server model is set. With AGORA_SERVER_LLM set to bedrock, openai, or vertex, server/relay.ts uses that server model instead.

• A failed call does not switch to another person’s key, or to a different saved connection.

• The browser proxy copies the caller’s Authorization header and does not attach the server key.

• Provider failures shown in the room are short messages, such as “The API key was rejected.” or “That model is not available.” The provider body and the key are not shown.

Do not commit keys. .env is gitignored.

Validation and performance

These are reported local validation results from clean commit 6983ddc (“Keep a swarm document inside the brief and one active run per room.”). They are functional gate checks. They are not real-user benchmarks and they are not proof of usefulness. This README pass did not rerun them. Later commits, including the production entry and host controls, are not covered by this table.

For the debate-reload run, reported usage was 13 model calls: eight planning/worker/merge, four debate/other, one repair; 7,176 input tokens and 4,651 output tokens.

For the assembly-reload run, reported usage was 11 calls: seven planning/worker/merge and four debate/other; 13,239 input tokens and 13,573 output tokens.

How to read the numbers:

• A word is a whitespace-separated span, including headings. The current source still counts that way in server/society/documentCheck.ts.

• “Under 400 words” means at most 399.

• Up to two shortening passes are allowed.

• A draft still over the limit is preserved and labelled “Needs revision: exceeds word limit.”

• Repair usage is counted separately.

• The reload checks did not create a second run id.

• Cost was unavailable. It is not zero.

• The timings are single observations on different briefs and conditions. They are not averages and they are not a speed ranking.

• No controlled single-agent versus swarm comparison, and no independent user study, has been completed.

• Swarm Bench’s automated judge is not evidence that the workspace is useful to a person.

Deployment

Verified from this repository:

• npm run dev serves the app and the room together.

• npm run build writes the client to dist/.

• npm run preview serves that client and does not start the room.

• Dockerfile builds the client, bundles server/prod.ts to dist/server.mjs, and runs node dist/server.mjs.

• That process listens on PORT, default 8080, and binds 0.0.0.0 only when AGORA_HOUSEHOLD_PASSCODE is set. It serves dist/ and attaches the relay.

The static prototype is https://agora-gamma-seven.vercel.app. Joining there opens a local preview in the browser. It does not start the shared room, and it does not call a model.

For the Alexa+ entry, a container image and a Cloud Run service were not verified from that workspace, and the tunnel, ECS, and Cloud Run commands in docs/DEPLOY.md were not run. The Qloo build's Cloud Run command is in docs/QLOO.md. There is no static Pages deploy, because a static copy has no /api, /mcp, or room. .github/workflows/ci.yml type-checks the client and server, runs the unit tests, and builds on every push and pull request.

When every browser disconnects, the sockets close. With a platform that stops an idle process, the in-memory room is gone. A model call still in flight is not a background job. This repository does not promise that a document finishes after everyone leaves, or that it survives a restart.

Current limitations and security

• One process, one room, at most five people.

• Everyone in the room can see the brief, the tasks, the document, and public chat.

• There are no accounts. On loopback, with no DEMO_HOST_SECRET, the first joiner is the host. On an open bind without that secret, the household session holds the host seat when a passcode is set, and the room has no host when it is not. With the secret set, host authority is the host code or the resume token.

• Only the host can start a swarm, start a benchmark, or end the session.

• Room state is memory. A restart or an idle shutdown clears it. Save a copy if you want a file.

• There is no spending cap.

• A provider can reject a key, lack a model, or time out. The room shows a short error and does not echo the upstream body.

• Browser keys remain in localStorage on that origin. They are not part of the room snapshot.

• The server key must not be used against an arbitrary base URL. The proxy is not an open forwarder.

• Bundled 3D models are CC BY-NC 4.0. They are placeholders and are not licensed for commercial use. See License and maintainer.

Roadmap

The household MCP server, approvals, receipts, and on-disk memory are built. See What it does. No dates are set for the office items below.

• Persist a cloud room across restarts, and keep an in-flight run when nobody is connected.

• Hold lasting document edits until the host accepts them.

• Replace the CC BY-NC office models before any commercial use.

• Planned, not built: a temporary workspace, separate from the room server, where a participant can install a CLI and connect a compatible tool to the room. Installing a CLI does not make it an agent. The deliverable today remains one Markdown document.

License and maintainer

Source code is MIT. See LICENSE.

Third-party code and assets have their own notices. Those notices stay in the files the licenses require:

• NOTICE.md — MIT attribution for the upstream office shell, and the CC BY-NC terms for the bundled models.

• public/models/ASSETS-LICENSE.md — CC BY-NC 4.0 for the 3D assets.

• public/models/README.txt — the same asset terms, next to the model files.

Maintainer: Ritesh-Root <workstationritalks@gmail.com> · https://github.com/Ritesh-Root

Repository: https://github.com/Ritesh-Root/agora-taste-council (forked from https://github.com/Ritesh-Root/agora-plus) · built on AGORA, https://github.com/Ritesh-Root/agora