@ai-matrx/chat 0.4.0 → 0.4.7

package/dist/host/defaults/workspace-gate.js

@@ -0,0 +1,89 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useChatHost } from "../react.js";
+import { chatHostHasDatabase } from "../configure.js";
+import { invalidateMandateCache } from "../../mandates/service.js";
+const PAGE = 500;
+const CHUNK = 100;
+function DefaultWorkspaceGate({ blocked, sentence, description, children, className }) {
+  const host = useChatHost();
+  const active = useSyncExternalStore(host.org.subscribe, host.org.active, () => null);
+  if (!blocked || active || !host.org.choose || !chatHostHasDatabase()) return /* @__PURE__ */ jsx(Fragment, { children });
+  return /* @__PURE__ */ jsx(WorkspacePicker, { sentence, description, className });
+}
+function WorkspacePicker({ sentence, description, className }) {
+  const host = useChatHost();
+  const [orgs, setOrgs] = useState(null);
+  const [error, setError] = useState(null);
+  const [filter, setFilter] = useState("");
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      const db = host.db;
+      const ids = [];
+      for (let from = 0; ; from += PAGE) {
+        const { data, error: e } = await db.rpc("mbr_for_user", { p_container_type: "organization" }).order("id", { ascending: true }).range(from, from + PAGE - 1);
+        if (e) throw new Error(e.message);
+        const page = Array.isArray(data) ? data : [];
+        ids.push(...page.map((row) => row.container_id));
+        if (page.length < PAGE) break;
+      }
+      const found = [];
+      for (let i = 0; i < ids.length; i += CHUNK) {
+        const { data, error: e } = await db.schema("iam").from("organizations").select("id,name").in("id", ids.slice(i, i + CHUNK)).is("archived_at", null);
+        if (e) throw new Error(e.message);
+        found.push(...data ?? []);
+      }
+      found.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+      if (!cancelled) setOrgs(found);
+    })().catch((e) => {
+      if (cancelled) return;
+      const message = e instanceof Error ? e.message : String(e);
+      host.diagnostics.capture(e, { area: "org", code: "workspace-list-failed" });
+      setError(message);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [host]);
+  const shown = useMemo(() => {
+    const q = filter.trim().toLowerCase();
+    return (orgs ?? []).filter((o) => !q || (o.name ?? "").toLowerCase().includes(q)).slice(0, 50);
+  }, [orgs, filter]);
+  const choose = (org) => {
+    host.org.choose?.(org);
+    invalidateMandateCache();
+  };
+  return /* @__PURE__ */ jsx("div", { "data-testid": "workspace-gate", className: className ?? "flex h-full min-h-0 w-full flex-col items-center overflow-y-auto p-6", children: /* @__PURE__ */ jsxs("div", { className: "w-full max-w-sm space-y-2", children: [
+    /* @__PURE__ */ jsx("p", { className: "text-sm font-medium", children: sentence }),
+    description ? /* @__PURE__ */ jsx("p", { className: "text-xs text-muted-foreground", children: description }) : null,
+    error ? /* @__PURE__ */ jsxs("p", { className: "text-xs text-destructive", children: [
+      "Couldn't list your organizations: ",
+      error
+    ] }) : orgs === null ? /* @__PURE__ */ jsx("p", { className: "text-xs text-muted-foreground", children: "Loading your organizations\u2026" }) : orgs.length === 0 ? /* @__PURE__ */ jsx("p", { className: "text-xs text-muted-foreground", children: "You are not a member of any organization." }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+      orgs.length > 8 ? /* @__PURE__ */ jsx(
+        "input",
+        {
+          value: filter,
+          onChange: (e) => setFilter(e.target.value),
+          placeholder: "Find an organization",
+          className: "w-full rounded-md border border-border bg-background px-2 py-1 text-sm"
+        }
+      ) : null,
+      /* @__PURE__ */ jsx("ul", { className: "divide-y divide-border rounded-md border border-border", children: shown.map((org) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          "data-workspace-choice": org.id,
+          onClick: () => choose(org),
+          className: "w-full px-3 py-2 text-left text-sm hover:bg-muted",
+          children: org.name ?? org.id
+        }
+      ) }, org.id)) })
+    ] })
+  ] }) });
+}
+export {
+  DefaultWorkspaceGate
+};

package/dist/host/diagnostics.d.ts

@@ -81,8 +81,13 @@ export interface StreamClientErrorInput {
 export declare function captureStreamClientError(input: StreamClientErrorInput): void;
 /** Test-only: drop held entries and restart local ids. */
 export declare function _resetDiagnosticsForTests(): void;
+/** The one degradation that is NOT a stand-in: the registration is missing and the call throws. */
+export declare const SLOT_CANNOT_RUN = "it cannot run";
 /**
- * A host registration (UI slot, usage gate, model-class hooks) was never made, so a stand-in
- * is running: say so ONCE, to the console and the host's diagnostics port (Law 4).
+ * A host registration (UI slot, usage gate, model-class hooks) was never made.
+ *
+ * A stand-in is an OPTIONAL enhancement the host may add: it announces itself ONCE as a quiet
+ * console info line and nothing else (Law 4: announced, not an error). A registration the package
+ * CANNOT run without (`SLOT_CANNOT_RUN`) is an error: console warning + the host's diagnostics.
  */
 export declare function reportUnregisteredHostSlot(name: string, degraded: string): void;

package/dist/host/diagnostics.js

@@ -146,8 +146,13 @@ function _resetDiagnosticsForTests() {
   early = [];
   localIds = 0;
 }
+const SLOT_CANNOT_RUN = "it cannot run";
 function reportUnregisteredHostSlot(name, degraded) {
   const message = `The host registered no "${name}" for the chat package, so ${degraded}.`;
+  if (degraded !== SLOT_CANNOT_RUN) {
+    announceOnce(`chat-host-slot:${name}`, message, "info");
+    return;
+  }
   if (!announceOnce(`chat-host-slot:${name}`, message)) return;
   captureError({
     source: "surface-registration",
@@ -162,6 +167,7 @@ function reportUnregisteredHostSlot(name, degraded) {
 export {
   EARLY_DIAGNOSTICS_LIMIT,
   RecordUnavailableError,
+  SLOT_CANNOT_RUN,
   _resetDiagnosticsForTests,
   captureError,
   captureReactRenderError,

package/dist/host/identity.js

@@ -1,5 +1,5 @@
 import { SIGNED_OUT_IDENTITY } from "./defaults/identity.js";
-import { getChatHost } from "./configure.js";
+import { chatHostHasDatabase, getChatHost } from "./configure.js";
 import { announceOnce } from "./errors.js";
 import { getStoreSingleton } from "../store/store-singleton.js";
 function identityOf(state) {
@@ -41,6 +41,7 @@ function requireUserId() {
   return id;
 }
 async function hasBrowserSession() {
+  if (!chatHostHasDatabase()) return false;
   let db;
   try {
     db = getChatHost().db;

package/dist/host/index.d.ts

@@ -2,14 +2,15 @@
  * @ai-matrx/chat/host — the host contract (no React). React door: `@ai-matrx/chat/host/react`.
  */
 export * from "./contract.js";
-export { configureChat, getChatHost, isChatHostConfigured, resolveChatHost, _resetChatHostForTests, } from "./configure.js";
+export { configureChat, DEFAULT_CHAT_APP, getChatHost, isChatHostConfigured, resolveChatHost, _resetChatHostForTests, } from "./configure.js";
+export { attributionForSend, currentChatApp, type WireAttribution } from "./app-identity.js";
 export { ChatHostInvalidError, ChatHostNotConfiguredError, ChatOrganizationRequiredError, } from "./errors.js";
 export { createLogClientErrorDiagnostics, isChatSourceApp, CHAT_SOURCE_FEATURE, DIAGNOSTICS_FLUSH_DELAY_MS, DIAGNOSTICS_MAX_PER_FLUSH, } from "./defaults/diagnostics.js";
 export { createDbIdentity, SIGNED_OUT_IDENTITY } from "./defaults/identity.js";
-export { createNoPickerOrg } from "./defaults/org.js";
+export { createNoPickerOrg, createStoredOrg, CHAT_ACTIVE_ORG_STORAGE_KEY } from "./defaults/org.js";
 export { createDefaultServer, DEFAULT_CHAT_SERVER_URL, } from "./defaults/server.js";
 export { createDomNotifier } from "./defaults/notify.js";
-export { createWebPrefs, CHAT_PREFS_PREFIX } from "./defaults/prefs.js";
+export { createWebPrefs, createHostKeptPrefs, CHAT_PREFS_PREFIX } from "./defaults/prefs.js";
 export { createWindowNavigation } from "./defaults/navigation.js";
 export { createUnhostedWindows } from "./defaults/windows.js";
 export { CHAT_WINDOWS, CHAT_WINDOW_IDS, DEFAULT_WINDOW_INSTANCE_ID, isChatWindowId, type ChatWindowId, } from "./windows.js";
@@ -21,3 +22,5 @@ export { createUnhostedCanvas, UNHOSTED_CANVAS_VIEW } from "./defaults/canvas.js
 export { DEFAULT_CHAT_ROUTES } from "./configure.js";
 export { createClient, getClaimsUser, schedulerDb, supabase, type ChatClaimsUser, type ClaimsCapableClient, } from "./db.js";
 export type { ChatDatabase } from "./db-types.js";
+export { ChatNoDatabaseError, NO_DATABASE_CODE_PREFIX, createNoDatabaseStandIn, isChatNoDatabaseError, isNoDatabase, } from "./no-database.js";
+export * from "./source.js";

package/dist/host/index.js

@@ -1,11 +1,13 @@
 export * from "./contract.js";
 import {
   configureChat,
+  DEFAULT_CHAT_APP,
   getChatHost,
   isChatHostConfigured,
   resolveChatHost,
   _resetChatHostForTests
 } from "./configure.js";
+import { attributionForSend, currentChatApp } from "./app-identity.js";
 import {
   ChatHostInvalidError,
   ChatHostNotConfiguredError,
@@ -19,13 +21,13 @@ import {
   DIAGNOSTICS_MAX_PER_FLUSH
 } from "./defaults/diagnostics.js";
 import { createDbIdentity, SIGNED_OUT_IDENTITY } from "./defaults/identity.js";
-import { createNoPickerOrg } from "./defaults/org.js";
+import { createNoPickerOrg, createStoredOrg, CHAT_ACTIVE_ORG_STORAGE_KEY } from "./defaults/org.js";
 import {
   createDefaultServer,
   DEFAULT_CHAT_SERVER_URL
 } from "./defaults/server.js";
 import { createDomNotifier } from "./defaults/notify.js";
-import { createWebPrefs, CHAT_PREFS_PREFIX } from "./defaults/prefs.js";
+import { createWebPrefs, createHostKeptPrefs, CHAT_PREFS_PREFIX } from "./defaults/prefs.js";
 import { createWindowNavigation } from "./defaults/navigation.js";
 import { createUnhostedWindows } from "./defaults/windows.js";
 import {
@@ -45,23 +47,36 @@ import {
   schedulerDb,
   supabase
 } from "./db.js";
+import {
+  ChatNoDatabaseError,
+  NO_DATABASE_CODE_PREFIX,
+  createNoDatabaseStandIn,
+  isChatNoDatabaseError,
+  isNoDatabase
+} from "./no-database.js";
+export * from "./source.js";
 export {
+  CHAT_ACTIVE_ORG_STORAGE_KEY,
   CHAT_PREFS_PREFIX,
   CHAT_SOURCE_FEATURE,
   CHAT_WINDOWS,
   CHAT_WINDOW_IDS,
   ChatHostInvalidError,
   ChatHostNotConfiguredError,
+  ChatNoDatabaseError,
   ChatOrganizationRequiredError,
+  DEFAULT_CHAT_APP,
   DEFAULT_CHAT_ROUTES,
   DEFAULT_CHAT_SERVER_URL,
   DEFAULT_CHROME_STYLES,
   DEFAULT_WINDOW_INSTANCE_ID,
   DIAGNOSTICS_FLUSH_DELAY_MS,
   DIAGNOSTICS_MAX_PER_FLUSH,
+  NO_DATABASE_CODE_PREFIX,
   SIGNED_OUT_IDENTITY,
   UNHOSTED_CANVAS_VIEW,
   _resetChatHostForTests,
+  attributionForSend,
   configureChat,
   createClient,
   createDbCatalogGetter,
@@ -70,17 +85,23 @@ export {
   createDefaultChrome,
   createDefaultServer,
   createDomNotifier,
+  createHostKeptPrefs,
   createLogClientErrorDiagnostics,
+  createNoDatabaseStandIn,
   createNoPickerOrg,
+  createStoredOrg,
   createUnhostedCanvas,
   createUnhostedWindows,
   createWebPrefs,
   createWindowNavigation,
+  currentChatApp,
   getChatHost,
   getClaimsUser,
   isChatHostConfigured,
+  isChatNoDatabaseError,
   isChatSourceApp,
   isChatWindowId,
+  isNoDatabase,
   resolveChatHost,
   schedulerDb,
   supabase

package/dist/host/no-database.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The no-database stand-in (HOST-OWNED-SOURCE-PLAN §2.3, P28a).
+ *
+ * A host that passes a message `source` and no `db` still gets a `db` port — this stand-in. Every
+ * use of it throws `ChatNoDatabaseError` naming the feature that reached for a database, and is
+ * reported to diagnostics ONCE per feature (Law 4: a stand-in announces itself). The engine's
+ * doors branch before they reach it (G-DOOR, `scripts/check-host-source-doors.mjs`); the forcing
+ * test (`host-source-runs-a-turn.test.tsx`) mounts the real column over it and fails on any report.
+ *
+ * Pure: no React, no Redux, no `window` at import.
+ */
+import type { ChatDb, ChatDiagnosticsPort } from "./contract.js";
+/** Diagnostics `code` prefix every stand-in report carries: `no-database:<feature>`. */
+export declare const NO_DATABASE_CODE_PREFIX = "no-database:";
+export declare class ChatNoDatabaseError extends Error {
+    readonly feature: string;
+    readonly code = "chat-no-database";
+    constructor(feature: string);
+}
+export declare function isChatNoDatabaseError(error: unknown): error is ChatNoDatabaseError;
+/** True when `db` is the stand-in (the host has no database). */
+export declare function isNoDatabase(db: unknown): boolean;
+/**
+ * The `db` for a host with none. `report(feature)` is called once per feature, then the access
+ * throws. Reading `then` or a symbol answers `undefined`, so the stand-in is never a thenable and
+ * survives `await`, logging and React dev tooling.
+ */
+export declare function createNoDatabaseStandIn(report: (feature: string) => void): ChatDb;
+/** Diagnostics for a host with no database: the console, each class said once. */
+export declare function createConsoleDiagnostics(): ChatDiagnosticsPort;
+/**
+ * The server client for a host with no database and no `server` port: every call refuses, named
+ * `server.<call>`, through the same once-per-feature report (the platform server needs a signed-in
+ * caller this host does not have).
+ */
+/** Members of the server client that never leave the page: the stream parser and state readers. */
+export declare function isLocalServerMember(key: string): boolean;
+export declare function createNoServerApi(report: (feature: string) => void, local?: Record<string, unknown>): unknown;

package/dist/host/no-database.js

@@ -0,0 +1,107 @@
+import { announceOnce } from "./errors.js";
+const NO_DATABASE_CODE_PREFIX = "no-database:";
+class ChatNoDatabaseError extends Error {
+  constructor(feature) {
+    super(
+      `"${feature}" needs a database, and this chat host has none (it was given a message source). The control that reached it should be absent here; pass \`db\` to the chat host to enable it.`
+    );
+    this.feature = feature;
+    this.name = "ChatNoDatabaseError";
+  }
+  feature;
+  code = "chat-no-database";
+}
+function isChatNoDatabaseError(error) {
+  return error instanceof ChatNoDatabaseError || typeof error === "object" && error !== null && error.code === "chat-no-database";
+}
+const STAND_IN = /* @__PURE__ */ Symbol.for("@ai-matrx/chat/no-database");
+function isNoDatabase(db) {
+  return typeof db === "object" && db !== null && db[STAND_IN] === true;
+}
+const NAMED_CALLS = new Set("from rpc schema channel".split(" "));
+function createNoDatabaseStandIn(report) {
+  const reported = /* @__PURE__ */ new Set();
+  const refuse = (feature) => {
+    if (!reported.has(feature)) {
+      reported.add(feature);
+      try {
+        report(feature);
+      } catch {
+      }
+    }
+    throw new ChatNoDatabaseError(feature);
+  };
+  return new Proxy({}, {
+    get(_target, key) {
+      if (key === STAND_IN) return true;
+      if (typeof key === "symbol" || key === "then" || key === "toJSON") return void 0;
+      if (NAMED_CALLS.has(key)) {
+        return (name) => refuse(`db.${key}(${typeof name === "string" ? name : "?"})`);
+      }
+      return refuse(`db.${key}`);
+    },
+    has(_target, key) {
+      return key === STAND_IN;
+    },
+    set(_target, key) {
+      return refuse(`db.${String(key)}=`);
+    }
+  });
+}
+function createConsoleDiagnostics() {
+  return {
+    capture(error, ctx) {
+      announceOnce(
+        `console-diagnostics:${ctx.area}:${ctx.code}`,
+        `${ctx.area}/${ctx.code}: ${error instanceof Error ? error.message : String(error)}`,
+        "error"
+      );
+    }
+  };
+}
+function isLocalServerMember(key) {
+  return key === "parseNdjsonStream" || /^select[A-Z]/.test(key);
+}
+function createNoServerApi(report, local = {}) {
+  const reported = /* @__PURE__ */ new Set();
+  const refuse = (feature) => {
+    if (!reported.has(feature)) {
+      reported.add(feature);
+      try {
+        report(feature);
+      } catch {
+      }
+    }
+    throw new ChatNoDatabaseError(feature);
+  };
+  const at = (path) => new Proxy(() => {
+  }, {
+    get(_target, key) {
+      if (typeof key === "symbol" || key === "then" || key === "toJSON") return void 0;
+      return at(`${path}.${key}`);
+    },
+    apply() {
+      return refuse(path);
+    }
+  });
+  return new Proxy(
+    {},
+    {
+      get(_target, key) {
+        if (typeof key === "symbol" || key === "then" || key === "toJSON") return void 0;
+        if (isLocalServerMember(key) && key in local) return local[key];
+        return at(`server.${key}`);
+      }
+    }
+  );
+}
+export {
+  ChatNoDatabaseError,
+  NO_DATABASE_CODE_PREFIX,
+  createConsoleDiagnostics,
+  createNoDatabaseStandIn,
+  createNoServerApi,
+  isChatNoDatabaseError,
+  isLocalServerMember,
+  isNoDatabase
+};

package/dist/host/react.d.ts

@@ -30,3 +30,4 @@ export declare function ChatProvider({ host, store, children }: ChatProviderProp
 export declare function useMaybeChatHost(): ResolvedChatHost | null;
 /** The host from the nearest <ChatProvider>. Throws the named, remedied error outside one. */
 export declare function useChatHost(): ResolvedChatHost;
+export { Link, usePathname, useRouter, useSearchParams } from "./navigation.js";

package/dist/host/react.js

@@ -8,12 +8,32 @@ import { ChatStoreContext } from "../store/context.js";
 import { createChatStore } from "../store/create-chat-store.js";
 import { useChatHostSync } from "../store/chat-host-sync.js";
 import { setStoreSingleton } from "../store/store-singleton.js";
+import { BareHostChrome } from "./bare-host-chrome.js";
+import { AlchemyActionsProvider, useOptionalAlchemyActions } from "@ai-matrx/alchemy/react/host";
+import { captureError } from "./diagnostics.js";
+import {
+  isRemarkDurabilityRegistered,
+  registerRemarkDurability
+} from "../agents/redux/execution-system/instance-resources/remarks.js";
+import { createDbRemarkDurability } from "../agents/redux/execution-system/instance-resources/default-remark-durability.js";
 const ChatHostContext = createContext(null);
 function ChatProvider({ host, store, children }) {
   const resolved = typeof window === "undefined" ? resolveChatHost(host) : configureChat(host);
   const [privateStore] = useState(() => {
     if (store) return null;
     const created = createChatStore();
+    if (typeof window !== "undefined" && !isRemarkDurabilityRegistered()) {
+      registerRemarkDurability(
+        createDbRemarkDurability({
+          db: resolved.db,
+          dispatch: created.dispatch,
+          onFailure: (message, error) => {
+            resolved.notify.error(message);
+            console.error("[remarks] write failed:", error);
+          }
+        })
+      );
+    }
     return { store: created, snapshot: created.getState() };
   });
   const chatStore = store ?? privateStore.store;
@@ -21,8 +41,21 @@ function ChatProvider({ host, store, children }) {
   const serverState = privateStore?.snapshot ?? (parent && parent.store === store ? parent.getServerState?.() : void 0);
   if (typeof window !== "undefined") setStoreSingleton(chatStore);
   useChatHostSync(chatStore, resolved);
-  return /* @__PURE__ */ jsx(ChatHostContext.Provider, { value: resolved, children: /* @__PURE__ */ jsx(Provider, { store: chatStore, context: ChatStoreContext, serverState, children }) });
+  const outerAlchemy = useOptionalAlchemyActions();
+  const body = privateStore ? /* @__PURE__ */ jsx(BareHostChrome, { host: resolved, children }) : children;
+  return /* @__PURE__ */ jsx(ChatHostContext.Provider, { value: resolved, children: /* @__PURE__ */ jsx(Provider, { store: chatStore, context: ChatStoreContext, serverState, children: outerAlchemy ? body : /* @__PURE__ */ jsx(AlchemyActionsProvider, { ports: BARE_ALCHEMY_PORTS, children: body }) }) });
 }
+const BARE_ALCHEMY_PORTS = {
+  diagnostics: {
+    capture: (error, context) => {
+      captureError({
+        source: "chat",
+        message: `Alchemy ${context.area}: ${error instanceof Error ? error.message : String(error)}`,
+        raw: context.detail
+      });
+    }
+  }
+};
 function useMaybeChatHost() {
   return useContext(ChatHostContext);
 }
@@ -31,8 +64,13 @@ function useChatHost() {
   if (!host) throw new ChatHostNotConfiguredError();
   return host;
 }
+import { Link, usePathname, useRouter, useSearchParams } from "./navigation.js";
 export {
   ChatProvider,
+  Link,
   useChatHost,
-  useMaybeChatHost
+  useMaybeChatHost,
+  usePathname,
+  useRouter,
+  useSearchParams
 };

package/dist/host/registered-source.js

@@ -1,5 +1,5 @@
 import { createElement } from "react";
-import { reportUnregisteredHostSlot } from "./diagnostics.js";
+import { reportUnregisteredHostSlot, SLOT_CANNOT_RUN } from "./diagnostics.js";
 function createRegisteredSource(sourceName, registerCall, defaults) {
   let impl = null;
   const label = (key) => `${sourceName}.${String(key)}`;
@@ -12,7 +12,7 @@ function createRegisteredSource(sourceName, registerCall, defaults) {
       reportUnregisteredHostSlot(label(key), "its generic default runs");
       return defaults[key];
     }
-    reportUnregisteredHostSlot(label(key), "it cannot run");
+    reportUnregisteredHostSlot(label(key), SLOT_CANNOT_RUN);
     throw new Error(
       `The host registered no "${label(key)}" for the chat package (${registerCall}).`
     );

package/dist/host/source.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @ai-matrx/chat/host/source — THE host-owned message source (HOST-OWNED-SOURCE-PLAN §2.2, P28a).
+ *
+ * A host with no database (coding sessions, desktop) still renders through the ONE real message
+ * list + composer: it hands the package history as records and live turns as platform stream
+ * events, and receives sends. It mirrors the engine's own two inputs — history arrives as
+ * records (`hydrateMessages`), live turns as events (`processStream`) — so nothing downstream
+ * learns a second shape. Capability by presence: a handler left out is a control left out.
+ *
+ * Pure: no React, no Redux, no `window` at import.
+ */
+import type { MessagePart, TypedStreamEvent } from "@ai-matrx/agents/generated/stream-events";
+/** One stored message the host hands over. `content` is the platform's own `MessagePart[]`. */
+export interface HostMessageRecord {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: MessagePart[];
+    position: number;
+    /** ISO timestamp. */
+    createdAt: string;
+    /** Presence means the turn failed; `message` is the sentence the person reads, `code` its class. */
+    error?: {
+        message: string;
+        code?: string | null;
+    } | null;
+}
+/**
+ * One finished (or still running) tool call in the host's history: what a saved `tool_call` part's
+ * card shows — its result, its failure, its display name. A database-backed conversation reads
+ * these from its tool-call rows; a host hands them over with the page.
+ */
+export interface HostToolCall {
+    /** The `call_id` of the `tool_call` part it belongs to. */
+    callId: string;
+    name: string;
+    /** What the card's title says ("Run a command"), when the host has a friendlier name. */
+    displayName?: string | null;
+    arguments: Record<string, unknown>;
+    /** The tool's output as text (JSON text renders structured); null while it runs. */
+    output: string | null;
+    isError: boolean;
+    status: "running" | "completed" | "failed";
+    /** The assistant message it belongs to. */
+    messageId?: string | null;
+}
+export interface HostHistoryPage {
+    records: HostMessageRecord[];
+    /** The tool calls the records' `tool_call` parts refer to. */
+    toolCalls?: HostToolCall[];
+    hasMoreOlder: boolean;
+    /** The host's sentence when its history could not be read ("This chat's file could not be read"). */
+    unavailable?: string | null;
+}
+/** A live turn: the platform NDJSON as-is, or typed events. */
+export interface HostTurn {
+    requestId: string;
+    /** The person's message, when the HOST started the turn (another device, the CLI). */
+    user?: MessagePart[] | null;
+    events: Response | AsyncIterable<TypedStreamEvent>;
+}
+/** What the package gives the host for one bound conversation. */
+export interface HostSourceSink {
+    /** A turn the host started (or a reconnect to one already running). */
+    turn(turn: HostTurn): void;
+    /** The host's history changed out of band: re-load it. */
+    history(): void;
+    /** The composer waits, with the host's sentence; null releases it. */
+    held(reason: string | null): void;
+}
+export interface HostSendInput {
+    conversationId: string;
+    text: string;
+    /** "send" when idle; "queue" / "steer" when a turn is running (per `whileBusy`). */
+    mode: "send" | "queue" | "steer";
+}
+/** The host's conversation list. Ids are always the host's — the package never mints one. */
+export interface HostConversationSummary {
+    id: string;
+    title: string | null;
+    updatedAt: string | null;
+}
+export interface HostConversationList {
+    list(): Promise<HostConversationSummary[]>;
+    /** Absent ⇒ no New control. Resolves the host's id for the new conversation. */
+    start?(): Promise<string>;
+}
+export type HostPersistence = {
+    saved: true;
+    where: string;
+} | {
+    saved: false;
+    reason: string;
+};
+export interface ChatMessageSource {
+    /** Stable id of the source ("coding-sessions"). */
+    id: string;
+    load(conversationId: string, page?: {
+        before: number | null;
+    }): Promise<HostHistoryPage>;
+    subscribe(conversationId: string, sink: HostSourceSink): () => void;
+    /** Absent ⇒ read-only. Returns the turn when it holds the stream, `void` when the turn arrives via `sink.turn`. */
+    send?(input: HostSendInput, signal: AbortSignal): Promise<HostTurn | void>;
+    stop?(conversationId: string, requestId: string | null): Promise<void>;
+    retry?(conversationId: string, messageId: string, signal: AbortSignal): Promise<HostTurn | void>;
+    answer?(conversationId: string, askId: string, value: unknown): Promise<void>;
+    conversations?: HostConversationList;
+    whileBusy: "queue" | "steer" | "refuse";
+    persistence: HostPersistence;
+}
+/** The host refused a send. `message` is the host's sentence; the words go back in the box. */
+export declare class HostSendRefused extends Error {
+    readonly code = "host-send-refused";
+    constructor(message: string);
+}
+export declare function isHostSendRefused(error: unknown): error is HostSendRefused;
+/** Typed events as the platform's NDJSON `Response` — the one shape `processStream` reads. */
+export declare function eventsToResponse(events: AsyncIterable<TypedStreamEvent>): Response;
+/** A turn's events as the NDJSON `Response` `processStream` reads. */
+export declare function hostTurnResponse(turn: HostTurn): Response;
+export interface HostTurnWriter {
+    turn: HostTurn;
+    push(event: TypedStreamEvent): void;
+    end(): void;
+    fail(error: unknown): void;
+}
+/**
+ * A turn the host fills as its own events arrive (a socket, an IPC channel). Events pushed before
+ * the package reads are buffered in order; `end()` closes the stream, `fail()` errors it.
+ */
+export declare function createHostTurn(requestId: string): HostTurnWriter;