@agentshouse/mdruntime-adapter 0.1.0-c89f673dd3f40 → 0.1.0-c8f4fd4801441

package/AGENTS.md

@@ -1,22 +1,23 @@
 # Instructions for the App Creator's agent
 
 These instructions address an agent in an environment with Git. Obtain the
-App Repository, change it, build, and push. They are documentation, not
-enforcement.
+App Repository, change it, build, and push. They are documentation, not enforcement.
 
 ## The MD Runtime API
 
 App code reaches the MD Runtime through the remote client. The surfaces are
-Rooms, Query, Search, Observe, Types, Room Draft, Save, History, Call, Reached, Log,
+Rooms, Query, Search, Observe, Types, Room Draft, Save, History, the binary file
+reads, Call, Reached, Log,
 the reported persistence answer, reauthorization, conversation, the chat draft,
 and Presentation State. Sync Status, the Service Mode, the storage-loss
-statement and the deployment facts are observations only.
+statement, the deployment facts and the signed-in member are observations only.
 
 The host attaches each port with its reach, and every member and observation
-answers within it: a Room outside it answers as one the replica does not hold, a
-Room reached for single Documents shows only those Documents, the Types of the
-models that govern them and no attachments, and without conversations the
-conversation members, the chat draft and the conversation observation hold none.
+answers within it: a Room outside it answers as one the replica does not hold,
+Rooms lists only the Rooms reached whole, a Room reached for single Documents
+shows only those Documents and the Types of the models that govern them, and
+without conversations the conversation members, the chat draft and the
+conversation observation hold none.
 A change of the reach reaches every open observation as its new value, a query
 keeping every unchanged Document the same object.
 
@@ -26,6 +27,8 @@ value whole and returns its unsubscribe, and `close()` ends the observation.
 Closing the port ends every handle and rejects every pending call and
 observation; a client that reconnects observes again.
 
+`observe('agents')` answers every Agent a new conversation can go to, each
+`{ identity, name }`, whether or not it has a conversation yet.
 Each conversation the Provider's conversation list names is held complete in the
 browser. `conversation.list()` and `observe('conversations')` answer each with its
 Agent's identity and name, its name, created and finished times, last outcome and live
@@ -42,29 +45,67 @@ and none of them is stored or searchable.
 sending it is a Provider Action that needs the Provider reachable and is never
 queued.
 
-Each Room in Rooms lists its `attachments`, the files the Provider holds for it
-that its Documents link by the Provider's reference, ordered by `reference`,
-each with `name`, `byteLength`, `mediaType` and the Provider's own entry as
-`entry`. They are as the Provider last declared them and hold no bytes;
-open one through the Provider Action that serves it.
+A binary file at a Path of a Room is a binary Path entry. Query lists it by
+`path` with its `binaryFile` record and never its bytes: `{ state: 'accepted',
+revision, path, fileRef, byteLength, mediaType, sha256 }`, or, from a Save until
+the Provider accepts it, `{ state: 'pending', localId, path, byteLength,
+mediaType, sha256 }` with no revision. Write one with a Room Draft whose only part
+is `file: { blob }`, a `Blob` whose `type` is its media type; Save keeps the bytes
+in its Pending Change, works offline, and the record turns accepted with the
+Provider's revision once the Pending Change is accepted. Move or remove an
+accepted one as a Document. Move or remove a pending one the same way, before or
+after Save: the Room Draft or its queued Pending Change carries the bytes to the
+new Path or drops them, and once that Pending Change has gone to the Provider
+Save refuses it as `unknown-revision` until it is accepted. Read the bytes with
+`binaryFile.read(room, path)`: a pending record answers its saved bytes, and
+every read of an accepted one asks the Provider again and keeps nothing. Pass a
+History revision as `binaryFile.read(room, path, revision)` to open that
+revision, a removed file's last one included. Text, a Record attachment or a conversation
+message may name a file directly by its `fileRef`; read that file with
+`binaryFile.readReference({ fileRef, referrer })`, where the referrer is the
+`referrer` the Provider gave beside the reference, or `{ room, path }` of the
+document whose text names it. Both answer `{ kind: 'binary', blob }` or a
+refusal or failure. History of a binary Path lists each revision's
+`binaryFile` metadata without bytes.
 
 Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never
 touch the network.
-History and Call go to the Provider through the Adapter. A Call result whose
+History, the binary file reads and Call go to the Provider through the Adapter. Call takes the Action names
+the Adapter declares; any other name answers `undeclared` without reaching the
+Provider. A Call result whose
 effect the Provider places in a Room carries `at`, that Room and Room Version;
 `reached(room, roomVersion)` answers whether the Room's confirmed state has
 reached it, and the MD Runtime keeps refreshing that Room until it has;
 `reached(room, roomVersion, path)` answers whether the held confirmed copy of
 that document was written at a later Room Version. Each History revision
-names its author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`. Every
+names its author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`.
+History of a Path no current document holds answers the removed document's
+revisions with `deleted: true`, newest first; that revision is what a link to
+the Path opens. Every
 member of the
 client is asynchronous. Results are detached snapshots. Nothing in this
 surface returns the authorization, performs a request the App's code
 composes, or exposes the browser store.
 
+Every refusal and failure carries `code` and `retryable`: each Call and History answer
+other than its result, a refused Save or Room Draft write, a returned Room Draft's
+reason, a Room's refusal and the Connection Refusal, and every error a member rejects
+with, beside its message. A Provider refusal carries the Provider's own `retryable`.
+Every code and every value the API answers is open: handle one you do not know by its
+`code` and `retryable`.
+
 Read the deployment facts with `observe('deployment-facts')`. Interpret the
 opaque value using the host's contract.
 
+`observe('member')` answers who uses the App: the User the Provider signed in,
+`{ kind: 'user', id, name }` in the shape of a change's `author`, so a Document
+whose `change.author.id` equals its `id` is that User's own. It is `null` until
+the Provider first names one, and where it names none, such as a Site. The
+MD Runtime keeps it with the Local Replicas, so it answers offline once known,
+and every port hears the next member the Provider names; signing out answers
+`null`, then ends the observation with the authorization. It is the only way App code learns who
+uses it.
+
 The in-memory Adapter at `@agentshouse/mdruntime/memory` is for tests and
 ships in no bundle.
 
@@ -78,41 +119,48 @@ data:
 - **Filter.** `rooms` names Room locators and defaults to every Room. `types`
   names MD Types, and `any` names untyped Markdown Documents. `pathPrefix` is a
   directory: `notes` keeps `notes/a.md` and not `notes2/a.md`.
-- **Fields.** `where` names frontmatter fields, ANDs them, and nests `$and` and
-  `$or`. A bare value is equality; the operators are `$eq`, `$ne`, `$in`, `$nin`,
-  `$gt`, `$gte`, `$lt`, `$lte`, `$all`, `$size` and `$exists`. Equality on a list
-  asks whether it contains the value. Missing, null and empty differ:
+- **Fields.** Every frontmatter value is named by JSON Pointer: `/status`,
+  `/shipping/city`, `~1` for a `/` and `~0` for a `~` in a key. A segment that
+  meets a list applies to every item and a number names one item. `where` names
+  pointers, ANDs them, and nests `$and` and `$or`; a pointer through a list holds
+  when any item satisfies it. A bare value is equality; the operators are `$eq`,
+  `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$all`, `$size` and
+  `$exists`. Equality on a list asks whether it contains the value. Missing, null and empty differ:
   `$exists: false` keeps a missing field, `null` an explicit null, `''` empty
   text and `$size: 0` an empty list. A date compares in calendar order and never
   with a date-time. A reference compares by the Room Path it resolves to.
-  Untyped frontmatter is plain values. There is no text containment or regular
+  Untyped frontmatter, and a value under `oneOf` or a conditional, is plain
+  values. There is no text containment or regular
   expression.
 - **Relations.** `hop: { field, types, where, pathPrefix }` keeps Documents whose
-  reference `field` points to a matching Document of the same Room.
-  `backlinks: { field, types, where, pathPrefix }` keeps Documents that a
+  reference at pointer `field`, at any depth, points to a matching Document of the
+  same Room. `backlinks: { field, types, where, pathPrefix }` keeps Documents that a
   matching Document of the same Room references. Each keeps a Document once.
 - **Parts.** A Document query must `select`: `'all'`, or `fields`, `sections`,
-  `preamble`, `markdown`, `backlinks` and `change`, where `fields` and `sections`
-  are `'all'` or a list of names. Room and Path always return; a Markdown
-  Document also returns its MD Type. A non-Markdown Document or binary link
-  target returns only Room and Path. An unselected part is absent. Select only
+  `preamble`, `markdown`, `backlinks` and `change`, where `fields` is `'all'` or a
+  list of pointers and `sections` `'all'` or a list of names. Selected pointers
+  return the frontmatter holding only them, nested as written. A backlink names
+  the referring Path, MD Type and the pointer it came from as `field`. Room and Path always return; a Markdown
+  Document also returns its MD Type. A non-Markdown Document returns only Room
+  and Path, and a binary Path entry Room, Path and its `binaryFile` record,
+  whatever is selected. An unselected part is absent. Select only
   what a screen shows: a list that selects the Markdown hears every edit of it.
 - **Change.** `change` is `{ author, time }` of the Document's head revision as
   the Provider last delivered it: `author` is `{ kind: 'user' | 'site', id, name }`
   or `null` for a write the Provider made itself, and `time` is the Provider's
   ISO 8601 change time. It is `null` where the Provider delivered no time, as at
   a Site. An unsent edit or move keeps it, an unsent creation has none, and a
-  saved write takes the Provider's own once it is Accepted and refreshed. A
+  saved write takes the Provider's own once it is Accepted. A
   Room's last change is its Document with the latest `time`.
 - **Order and groups.** `orderBy` sorts by `room`, `path`, `type` or `{ field }`
   with TanStack DB's own options, and ties end with Room, then Path. `groupBy` by
   `room`, `type` or `{ field }` answers `{ groups: [{ key, count }] }`, counted
-  over every match and ordered by `count` or a key. `limit` bounds the Documents
-  or the groups.
+  over every match and ordered by `count` or a key. A sort or group takes only a
+  pointer that holds one value. `limit` bounds the Documents or the groups.
 - **Results and errors.** A result carries no Room Version: read freshness from
-  Rooms and Sync Status. An invalid query fails with `invalid-query`,
-  `unknown-type`, `unknown-field` or `wrong-kind`, naming where, and never
-  answers an empty result in its place.
+  Rooms and Sync Status. An invalid query fails with the `code`
+  `invalid-query`, `unknown-type`, `unknown-field` or `wrong-kind`, naming where,
+  and never answers an empty result in its place.
 
 ## Local Search rules
 
@@ -150,9 +198,9 @@ the current Room Draft; read it and write again.
 
 Save takes one Room and the Room Drafts of it to save, each with its revision,
 validates locally, and on success appends one Change Batch to that Room's
-queue and removes those Room Drafts. It is refused as `stale`, as
+queue and removes those Room Drafts. It is refused with the `code` `stale`,
 `changed-underneath` naming each part whose base no longer matches the visible
-state, or by a local validation rule, and then creates nothing and leaves every
+state, or a local validation rule, and then creates nothing and leaves every
 Room Draft in place. A directory move or removal is a move or removal part on
 each Document and binary link target beneath it, saved together.
 
@@ -172,6 +220,13 @@ it names; the MD Runtime retries the same Change Batch identity and payload and
 never infers an outcome from transport uncertainty. The MD Runtime never
 combines, reorders, or rebases.
 
+On a Site, every Save stays in the visitor's browser. Write grants and
+revisions do not refuse it, and its Pending Change shows in every query and
+across reloads until the browser's storage is cleared. It is never sent:
+`observe('queue', room)` shows it `local`, and Sync Status never waits on it.
+Once the Room changes so that it no longer applies, it leaves the queue and
+returns no Room Draft.
+
 `observe('service-mode')` answers the Provider's Service
 Mode, `open` or `write-halted`. While writes are halted, Save still succeeds,
 its Change Batch waits unsent, and the queue is submitted in order once the
@@ -207,23 +262,55 @@ the network. Data lives only in the App Creator's browser and with the Provider.
 
 ## App code takes the client its host hands it and never constructs a Runtime
 
-App code takes the client its host hands it: in House,
-`connectHouseBridge().runtime` from `@agentshouse/app-bridge` resolves to the
-client House built into the page. It never constructs a Runtime or a client.
-It imports only types from `@agentshouse/mdruntime/client`, does not call
-`connectMdRuntime` or `serveMdRuntime`, and does not import the package main,
-the host entry, or the Adapter package. Hosts and tests use those entries; the
-served App does not.
+App code takes the client its host hands it: in House, `houseBridge().runtime`
+from `@agentshouse/app-bridge` resolves to the client House built into the page.
+It never constructs a Runtime or a client. It imports only types from
+`@agentshouse/mdruntime/client`, does not call `connectMdRuntime` or
+`serveMdRuntime`, and does not import the package main, the host entry, or the
+Adapter package. Hosts and tests use those entries; the served App does not.
 
 A React App may observe and save through `@agentshouse/mdruntime/react`, which
 names React as a peer dependency. `useObserve(client, topic, ...input)` takes
-the arguments of `observe` and returns the topic's current value, `undefined`
-until it arrives, re-rendering on each change; a `null` client observes
-nothing. `useSave(client)` returns `busy`, the last `outcome` or `failure`, and
-`save(room, roomDrafts)`, which writes each Path's parts onto the Room Draft
-already there, keeping the bases its parts have, or onto a new one, and saves
-them together. A refused Save leaves the Room Drafts for the App to save again
-or discard; a failure is recorded and rejects.
+the arguments of `observe` and returns `{ state: 'loading' }` until the topic's
+first value arrives, then `{ state: 'ready', value }`, re-rendering on each
+change; a `null` client observes nothing and stays loading. `useSave(client)`
+returns `busy`, the last `outcome` or `failure`, and `save(room, roomDrafts)`,
+which writes each Path's parts onto the Room Draft already there, keeping the
+bases its parts have, or onto a new one, and saves them together. A refused
+Save leaves the Room Drafts for the App to save again or discard; a failure is
+recorded and rejects. `saveRoomDrafts(client, room, roomDrafts)` is that save
+outside a component. A react-admin or Refine App reads and writes its Rooms
+through the data providers of `@agentshouse/mdruntime-families`.
+
+## The Chat
+
+`@agentshouse/mdruntime/chat` holds the Chat, one data layer for every App.
+Its required peers are React, React DOM and `@assistant-ui/react`: add React as
+a dependency, also in an App not written in React.
+
+Place the ready chat with `<Chat client={runtime} conversation={id}
+agent={agent} width="1/3" showChats />`: `conversation` opens one, `null` for a
+new chat, `agent` is the Agent a new chat goes to, `onOpen` hears each one it
+opens, and `width` is `full` (the place you give it), or `3/4`, `1/2` or `1/3`
+of the window docked at its right edge, whole on a narrow window. `showChats`
+adds its conversation list; or draw your own inside a `ChatProvider` around a
+`<Chat />` with no `client`. It carries its own styles; theme it with CSS custom
+properties on it or an ancestor: `--chat-background`, `--chat-surface`,
+`--chat-text`, `--chat-text-muted`, `--chat-accent`, `--chat-line`,
+`--chat-attention`, `--chat-danger`, `--chat-font`, `--chat-font-mono`,
+`--chat-font-size`, `--chat-radius` and `--chat-density` (a factor for spacing);
+an unset one keeps House's light or dark look. `mountChat(element, { client })`
+places it outside React and returns `update(props)` and `unmount()`.
+
+Mix `ChatMessageList` (`components` takes your `UserMessage` and
+`AssistantMessage`), `ChatInput` and `ChatQuestionCard` with your own design
+inside a `ChatProvider`, or compose assistant-ui's primitives there; `useChat()`
+gives `send`, the conversations, the Agents, questions to `answer`, `options`
+to `choose`, `commands`, the queue to `edit` or `unqueue`, `stop`, `kill` and
+outcomes; never replace its messages, sending or store. A secret question is
+never answered here; typed answers live in Presentation State's `typed` key:
+keep it, and change Presentation State only inside `inTurn(client, work)` from
+`@agentshouse/mdruntime/client`. `Markdown` draws Markdown safely.
 
 ## What an agent must never do
 

package/dist/actions.d.ts

@@ -1,8 +1,46 @@
-import { type AcceptedMessage, type ActionDeclaration, type ActionRequest, type ActionResult, type ConversationAgents } from '@agentshouse/mdruntime';
+import { type AcceptedMessage, type ActionDeclaration, type ActionRequest, type ActionResult, type ConversationAgents, type ConversationHistories, type ConversationHistoryRequest, type FileDeclaration } from '@agentshouse/mdruntime';
 import type { HouseDoorAnswer, HouseTransport } from './transport.js';
-export declare const HOUSE_CONVERSATION_AGENTS: ConversationAgents;
+type Operated = {
+    readonly operation_id?: string;
+};
+type ConversationControl = Operated & {
+    readonly conversation: string;
+};
+type SentFile = FileDeclaration & {
+    readonly blob: Blob;
+};
+export type AppInputs = {
+    readonly 'conversation.answer': ConversationControl & {
+        readonly answer: {
+            readonly interaction_id: string;
+            readonly response: unknown;
+        };
+    };
+    readonly 'conversation.create': Operated & {
+        readonly agent_id: string;
+    };
+    readonly 'conversation.delete': ConversationControl;
+    readonly 'conversation.history': ConversationHistoryRequest;
+    readonly 'conversation.interrupt': ConversationControl;
+    readonly 'conversation.kill': ConversationControl;
+    readonly 'conversation.send': ConversationControl & {
+        readonly text?: string;
+        readonly files?: readonly SentFile[];
+    };
+};
+export type AppAnswers = {
+    readonly 'conversation.history': ConversationHistories;
+};
+export type AppAnswerAdditions = {
+    readonly 'conversation.send': {
+        readonly turn: string;
+    };
+};
+export declare const HOUSE_APP_ACTS: Readonly<Record<string, string>>;
+export declare function houseConversationAgents(locator: string): ConversationAgents;
 export declare function declaredActions(routes: readonly string[]): readonly ActionDeclaration[];
 export declare function houseAction(transport: HouseTransport, request: ActionRequest): Promise<ActionResult>;
 export declare function actionOutcome(answer: HouseDoorAnswer, name: string): ActionResult;
 export declare function acceptedMessage(entry: unknown): AcceptedMessage | null;
+export {};
 //# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAGxB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAkBtE,eAAO,MAAM,yBAAyB,EAAE,kBAKvC,CAAC;AAEF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,iBAAiB,EAAE,CASvF;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAQvB;AA4DD,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAWjF;AAuLD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAUtE"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAE1B,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQtE,KAAK,QAAQ,GAAG;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,KAAK,mBAAmB,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,KAAK,QAAQ,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,qBAAqB,EAAE,mBAAmB,GAAG;QACpD,QAAQ,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;SAAE,CAAC;KAClF,CAAC;IACF,QAAQ,CAAC,qBAAqB,EAAE,QAAQ,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,qBAAqB,EAAE,mBAAmB,CAAC;IACpD,QAAQ,CAAC,sBAAsB,EAAE,0BAA0B,CAAC;IAC5D,QAAQ,CAAC,wBAAwB,EAAE,mBAAmB,CAAC;IACvD,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IAClD,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,GAAG;QAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;KACtC,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,sBAAsB,EAAE,qBAAqB,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,mBAAmB,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD,CAAC;AAkEF,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3D,CAAC;AAMF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAE3E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,iBAAiB,EAAE,CAMvF;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAwED,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAOjF;AAkLD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAiBtE"}