@agentshouse/mdruntime-adapter 0.1.0-c9f1e531ad7c8 → 0.1.0-cacce09fc82c6

package/AGENTS.md

@@ -7,9 +7,19 @@ enforcement.
 ## The MD Runtime API
 
 App code reaches the MD Runtime through the remote client. The surfaces are
-Rooms, Slots, Query, Search, Observe, Types, Room Draft, Save, History, Call, Reached, Log,
-storage loss, the reported persistence answer, deployment facts, Sync Status, the Service Mode,
-reauthorization, conversation, the chat draft, and Presentation State.
+Rooms, Query, Search, Observe, Types, Room Draft, Save, History, Call, Reached, Log,
+the reported persistence answer, reauthorization, conversation, the chat draft,
+and Presentation State. Sync Status, the Service Mode, the storage-loss
+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,
+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.
 
 Every `observe` resolves, once its first value has arrived, to a handle:
 `current()` is the latest complete value, `subscribe(listener)` hears each later
@@ -17,29 +27,29 @@ 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.
 
-Each conversation a Provider card names is held complete in the browser.
+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
+`state`: `asking` while a question waits, `working` while a turn runs, else `idle`,
+and `started`, when the running turn began, or `null`.
 Observe one with `observe('conversation', id, { limit })`: the view
 holds its latest `limit` messages, or all of them, oldest first, its chat
 draft, and what the Provider streams for it whether or not anything views it:
-the growing text and plan of the running turn, the open questions, the process
-state, the CLI's commands and options, and the latest `workingNote`. These live
-only in memory: the turn's accepted message replaces its growing text and plan,
-a working note is never part of a message, and none of them is stored or
-searchable.
+the running `turn` with its message parts and its context in use and window, the
+open questions, the process state, and the CLI's commands and options. These live
+only in memory: the message accepted under the turn's id replaces the running turn,
+and none of them is stored or searchable.
 `chatDraft.write` and `chatDraft.discard` keep what the App Creator composes;
 sending it is a Provider Action that needs the Provider reachable and is never
 queued.
 
-Slots answers each Slot the Provider declares, in its order, with its entries
-in order, each a Room and its segment; a Room two Slots list is the same Room.
-
 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.
 
-Rooms, Slots, Query, Search, Observe, Types, Room Draft, Save, and Reached never
+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
 effect the Provider places in a Room carries `at`, that Room and Room Version;
@@ -47,15 +57,26 @@ effect the Provider places in a Room carries `at`, that Room and Room Version;
 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.
 
-Read deployment facts with `deploymentFacts()` and observe replacements with
-`observe('deployment-facts')`. Interpret the opaque value using the
-host's contract.
+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.
@@ -70,22 +91,28 @@ 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
+  `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 or binary link
   target returns only Room and Path. An unselected part is absent. Select only
   what a screen shows: a list that selects the Markdown hears every edit of it.
@@ -94,13 +121,13 @@ data:
   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
@@ -114,7 +141,7 @@ search.
 
 - **What is found.** A Document by its field values, its sections' headings and
   text, its preamble and its Path; a message by its text. Frontmatter keys, Room
-  Drafts, chat drafts and growing text are never found. There are no phrases,
+  Drafts, chat drafts and a running turn's parts are never found. There are no phrases,
   word forms, typo tolerance or prefix matching.
 - **Narrowing.** `documents` is a Local Query filter: `rooms`, `types`, `where`,
   `pathPrefix`, `hop` and `backlinks`. `conversations` names conversations. Both
@@ -130,7 +157,7 @@ search.
 
 The MD Runtime owns one Room Draft per Room and Path, shared by every App and
 tab. It is durable: it survives reload and navigation. A Room that Discovery
-stops listing takes its Room Drafts, its queue and their outcomes with it.
+stops listing takes its Room Drafts and its queue with it.
 Write a Room Draft with `roomDraft.write(room, path, revision, parts)`, naming
 the revision you read, or `null` when there was none, and every part it should
 now change: fields, sections and the preamble, or the whole Markdown, a
@@ -150,20 +177,21 @@ each Document and binary link target beneath it, saved together.
 
 Outcomes follow the Provider's answer. An Accepted Change Batch stays in the
 queue, drawn over the confirmed layer, until the confirmed layer reaches the
-Room Version it was accepted at, and then leaves it. Conflicted and Rejected, an expired outcome record, and a change that no
+Room Version it was accepted at, and then leaves it. Conflicted and Rejected, an expired operation, and a change that no
 longer applies over the Room each leave the queue and return as Room Drafts on
 the Documents they changed, marked with why: the Provider's structured refusal
 code and fields as returned, not known to have applied, or withdrawn locally.
 The rest of the queue keeps synchronizing, and Sync Status requires attention
-until each returned Room Draft is saved again or discarded. `outcome` answers
-the saved Change Batch's outcome, and `null` while it is Pending. Transport
+until each returned Room Draft is saved again or discarded. A Change Batch
+keeps no outcome once it leaves the queue; `observe('queue', room)` shows each
+Pending one, and a returned Room Draft says why it returned. Transport
 failure and Provider unavailability keep work Pending and do not infer a
 rejection. A refusal the Provider marks retryable stays Pending until the reset
 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.
 
-`serviceMode()` and `observe('service-mode')` answer the Provider's Service
+`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
 Provider reopens writes. An Action is never held: a write the Provider refuses
@@ -196,13 +224,28 @@ an App's override respected. What an App Creator's agent adds carries none
 of these promises by itself. Reading, querying and searching never wait for
 the network. Data lives only in the App Creator's browser and with the Provider.
 
-## App code imports only the client entry and never constructs a Runtime
-
-App code imports only `@agentshouse/mdruntime/client` and calls
-`connectMdRuntime` on the port the host hands it. It never constructs a
-Runtime. It does not import the package main, the host entry, or the Adapter
-package, and it does not call `createMdRuntime` or `serveMdRuntime`. Hosts
-and tests use those entries; the served App does not.
+## 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.
+
+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 `{ 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`.
 
 ## What an agent must never do
 

package/README.md

@@ -19,12 +19,12 @@ import { serveMdRuntime } from '@agentshouse/mdruntime/host';
 import { createAgentsHouseAdapter } from '@agentshouse/mdruntime-adapter';
 
 const adapter = createAgentsHouseAdapter({ transport, authorize });
-const host = serveMdRuntime({ adapter, shell, requiredGuarantees: [] });
+const host = serveMdRuntime({ adapter, shell });
 host.attach(port, 'my-app');
 ```
 
-App code never imports this package; it reaches the Runtime only through
-`@agentshouse/mdruntime/client`. The rules an App's agent follows are in the
+App code never imports this package; it reaches the Runtime only through the
+client its host hands it. The rules an App's agent follows are in the
 package's `AGENTS.md`.
 
 ## License

package/dist/actions.d.ts

@@ -1,6 +1,6 @@
-import { type AcceptedMessage, type ActionDeclaration, type ActionRequest, type ActionResult, type ConversationCards } from '@agentshouse/mdruntime';
+import { type AcceptedMessage, type ActionDeclaration, type ActionRequest, type ActionResult, type ConversationAgents } from '@agentshouse/mdruntime';
 import type { HouseDoorAnswer, HouseTransport } from './transport.js';
-export declare const HOUSE_CONVERSATION_CARDS: ConversationCards;
+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;

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,iBAAiB,EAGvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAkBtE,eAAO,MAAM,wBAAwB,EAAE,iBAKtC,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,EAGxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAkBtE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAE3E;AAED,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"}

package/dist/actions.js

@@ -1,6 +1,5 @@
 import { changeBatchIdentity, } from '@agentshouse/mdruntime';
 import { doorRefusal } from './refusal.js';
-import { PRIVATE_LOCATOR } from './transport.js';
 const HISTORY_PAGE = 100;
 const HISTORY_CONVERSATIONS = 64;
 const OCTET_STREAM = 'application/octet-stream';
@@ -13,12 +12,9 @@ const CONVERSATION_ROUTES = new Map([
     ['conversation.delete', '/door/conversations/delete'],
     ['conversation.history', '/door/conversations/history'],
 ]);
-export const HOUSE_CONVERSATION_CARDS = {
-    locator: PRIVATE_LOCATOR,
-    type: 'house-conversation',
-    identity: 'conversation',
-    agent: 'agent',
-};
+export function houseConversationAgents(locator) {
+    return { locator, type: 'house-agent', identity: 'agent', name: 'name' };
+}
 export function declaredActions(routes) {
     const mapped = new Map([...CONVERSATION_ROUTES].map(([name, route]) => [route.slice('/door/'.length), name]));
     return routes.map((route) => ({

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,OAAO,EACP,aAAa,EAad,MAAM,wBAAwB,CAAC;AA0ChC,OAAO,EASL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAuBxB,MAAM,MAAM,yBAAyB,GACjC;IACE,SAAS,EAAE,cAAc,CAAC;IAC1B,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;CACrC,GACD;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAiCjC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAkZpF"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,OAAO,EACP,aAAa,EAWd,MAAM,wBAAwB,CAAC;AAqChC,OAAO,EAOL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAyBxB,MAAM,MAAM,yBAAyB,GACjC;IACE,SAAS,EAAE,cAAc,CAAC;IAC1B,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;CACrC,GACD;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAsBjC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CA0WpF"}