@particle-academy/fancy-chat-js
The agent chat wire contract: the thread log fancy-chat-php projects Prism Harness runs into. Run, turn, message and human-in-the-loop events with a gapless per-thread seq and resumable replay, typed message parts, the turn-state machine, delivery states, the agent status vocabulary and a pure thread projection. Zero runtime dependencies and isomorphic, so the UI reads it in the browser. Held to particle-academy/fancy-chat-php by shared conformance fixtures.
Part of Fancy Chat — 3 packages, one productSee the familynpm install @particle-academy/fancy-chat-jsAPI surface
Headless package — drive it from code or an agent. No component grid.
@particle-academy/fancy-chat-js
The wire contract of the Fancy agent chat (council change CC-fancy-0042), which is
built on the Prism ecosystem. A chat turn runs on Prism Harness, and the server
projects the run (Harness's g282.1 RunSteps and its run events) into this thread
log. A server stores and replays the log, and a chat UI projects it into rows. Zero
runtime dependencies and isomorphic (browser, worker, Node), because the UI reads it
in the browser.
It holds no copy of a Prism type. It never reads a RunStep: the server maps them
(FancyChat\Prism\HarnessBackend in fancy-chat-php), and the types those come in
are @particle-academy/prism-harness's. prism-graph, prism-memory and the other
extras are optional, and nothing here needs them.
This package is the ONE contract every server implements. The PHP server,
particle-academy/fancy-chat-php, passes the same conformance fixture (conformance/chat-v1.json) to the same output, and vendors the same
transition table (contract/machines.json). Both files are pinned by SHA-256 in
both repositories. A Node server twin, on @particle-academy/prism-harness and
@particle-academy/prism-acp, is next and will run the same fixtures.
Design: .ai/plans/agent-chat-on-prism.md in the Fancy envelope.
For agents. This package is listed on the Fancy MCP catalog server at
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), with install commands and docs, alongside the rest of the kit. How an agent installs and uses this package is in AGENTS.md.
What it holds
| Module | What |
|---|---|
| Events | v1 envelope (validateEvent): seq is per thread, monotonic and gapless, and is the only ordering. Core types are a closed set; apps add x-<app>.<name>. An unknown major is refused, unknown fields are ignored. |
| Resumable replay | createSeqLog / ingestEvents: drop duplicates, hold events past a gap and report it, so the transport re-requests after = lastSeq. thread.reset jumps the cursor. A missed broadcast costs nothing. |
| Parts | validatePart, partToText, createPartRegistry: text, code, table, chart, file, image, tool-call, tool-result, card, question, approval, plus app kinds. Size, count and depth caps are configurable. |
| Turn machine | transitionTurn, from contract/machines.json. Only turn.settled settles a turn; no client infers it from rows. |
| Delivery | transitionDelivery: sending, sent, queued, steered, delivered, failed, dropped, unsent. |
| HITL | transitionApproval, optionTone (tone from the option KIND, never its label), canDecide (humans only), isReservedToolName, canSubmitAnswer, pickActionable (one actionable item, in-flight lock). |
| Status | deriveAgentStatus(snapshot, config): one pure derivation of not-started, starting, working, cooling, idle, sleeping, parked, paused-limit, signed-out, broken, each with recovery action ids the host can override. |
| Typed approval | matchTypedApproval(text, approval, config): OPT-IN per app, off with no phrases by default (ENGLISH_TYPED_APPROVAL_PHRASES is there to opt into). Exact phrases after NFKC, case, spacing and trailing-punctuation folding; picks a one-time option only, never "always", never edit. |
| Undo window | undoWindow(entry, now): time left and whether a revert may still land. Shut at the deadline and on an unreadable one. The projection lets only a human revert. |
| Plan-step HITL | checkPlanUpdate(prev, next, approvals): a held step releases only through its approval; refused approvals allow only skipped or failed. The projection refuses any other release. |
| Edit and resend | The projection records each superseded branch in state.branches; the HOST's policy decides (branch, the default, keeps it; truncate retracts it on the server). |
| Projection | projectThread(events) / applyEvent(state, event): messages, one merged thinking block per run, tool rows, plans and HITL placements. The state is plain JSON and is the snapshot format. |
Two rules the projection enforces
- A decision or answer counts only from a human.
approval.decidedandquestion.answeredare applied only when the event's actor is a human and the recorded decider is that same human. Anything else is counted as illegal and changes nothing. - Approval and question parts come only from server records. An agent-origin part of either kind fails validation, and so do raw ECharts options: an agent may only send the neutral chart spec.
Use
import { createSeqLog, ingestEvents, emptyThreadState, applyEvent, rowsOf } from "@particle-academy/fancy-chat-js";
let log = createSeqLog();
const state = emptyThreadState();
function onEvents(batch) {
const r = ingestEvents(log, batch);
log = r.log;
for (const e of r.applied) applyEvent(state, e);
if (r.missing) refetch({ after: r.missing.after });
render(rowsOf(state));
}
Install
npm i @particle-academy/fancy-chat-js
With the React surfaces: npm i @particle-academy/fancy-chat-js @particle-academy/fancy-chat-ui. The Laravel server is
composer require particle-academy/fancy-chat-php. npx fancy-chat-check-install checks every
@particle-academy package's entry files after an install. Node >=22. Zero
runtime dependencies.
Develop
npm install
npm test # vitest: the conformance fixture, resume, parts, packaging (zero deps)
npm run lint # tsc --noEmit
npm run sabotage # breaks one clause at a time; the suite must notice each
MIT licence.

