dsh-cindy-host 0.1.20

package/src/host-approvals.js

@@ -0,0 +1,329 @@
+/**
+ * The inbound half of DSH approvals: a question DSH asks, answered by the Cindy
+ * controller instead of the local UI.
+ *
+ * DSH raises `approval/request` as a **waterfall** event
+ * (`@deepseek-ai/dsh-user-approval`), and the chain's terminal answerer is
+ * fail-closed. That shape dictates the whole design here:
+ *
+ *  - if no Cindy controller is watching the asking session, this registry is not
+ *    in the chain's business and the answerer must call `next()` so the local UI
+ *    (or the fail-closed default) decides — a Host must never swallow a question
+ *    the user could have answered at the desk;
+ *  - if a controller *is* watching, the question is registered, pushed, and the
+ *    answerer waits for the phone's `maker:resolve-interaction`.
+ *
+ * Outcomes are DSH's own vocabulary (`'allowed-once' | 'rejected' | 'cancelled' |
+ * 'unavailable'`), not the controller's: `'allowed-once'` is the only grant DSH
+ * defines, so every non-allow answer maps to `'rejected'`.
+ */
+
+/** The controller's interaction kind for a permission question. */
+export const PERMISSION_KIND = 'permission';
+
+/**
+ * Map a controller decision onto a DSH approval outcome.
+ *
+ * The controller sends `{ kind: 'permission', behavior: 'allow' | … }`.
+ * @param decision - the raw `maker:resolve-interaction` decision.
+ * @returns the outcome, or null when this is not a permission decision.
+ */
+export function decisionOutcome(decision) {
+  if (decision === null || typeof decision !== 'object') return null;
+  if (typeof decision.kind === 'string' && decision.kind !== PERMISSION_KIND) return null;
+  const behavior = typeof decision.behavior === 'string'
+    ? decision.behavior
+    : (typeof decision.decision === 'string' ? decision.decision : null);
+  if (behavior === null) return null;
+  return behavior === 'allow' ? 'allowed-once' : 'rejected';
+}
+
+/**
+ * The controller's interaction kind for a structured question.
+ *
+ * DSH's `user-questions/request` waterfall is a *different* seam from
+ * `approval/request`, and the controller renders it as its own card — but the
+ * answer travels the same `maker:resolve-interaction` channel, so both share this
+ * registry and are told apart by kind. Without an answerer here the tool call
+ * waits for a human nobody can answer, and the conversation stops.
+ */
+export const QUESTION_KIND = 'ask_user_question';
+
+/**
+ * Translate the controller's question answer into DSH's shape.
+ *
+ * The two sides key answers differently, and that is the whole job:
+ *  - the controller answers by **question text** (`answerKey` is the question's
+ *    own string), one string per question, JSON-encoded as an array when the
+ *    question is multi-select;
+ *  - DSH answers by question **id**, as `{ id, selected: string[], custom? }`.
+ *
+ * The questions that were asked are therefore the lookup table, and anything the
+ * controller returned that is not one of the offered labels is carried as
+ * `custom` rather than silently dropped.
+ *
+ * @param questions - the DSH questions that were asked.
+ * @param decision - the controller's `{ kind, answers }`.
+ * @returns DSH's `AskUserQuestionAnswer`.
+ */
+export function questionAnswerOf(questions, decision) {
+  // The decision's own kind must match: a permission decision aimed at a
+  // question would otherwise be read as "every question unanswered", which the
+  // controller would take as a real answer.
+  if (decision?.kind !== undefined && decision.kind !== QUESTION_KIND) return null;
+  const given = decision?.answers;
+  if (given === null || typeof given !== 'object') return { answers: [] };
+  const answers = [];
+  for (const question of Array.isArray(questions) ? questions : []) {
+    const raw = given[question?.question];
+    const labels = new Set((Array.isArray(question?.options) ? question.options : [])
+      .map((option) => (typeof option?.label === 'string' ? option.label : ''))
+      .filter((label) => label !== ''));
+    let chosen = typeof raw === 'string' && raw !== '' ? [raw] : [];
+    if (chosen.length > 0 && question?.multiSelect === true) {
+      try {
+        const parsed = JSON.parse(chosen[0]);
+        if (Array.isArray(parsed)) chosen = parsed.filter((entry) => typeof entry === 'string' && entry !== '');
+      } catch {
+        // Not the encoded array: keep the single string as given.
+      }
+    }
+    const selected = chosen.filter((label) => labels.has(label));
+    const free = chosen.filter((label) => !labels.has(label));
+    answers.push({
+      id: String(question?.id ?? ''),
+      selected,
+      ...(free.length === 0 ? {} : { custom: free.join(', ') }),
+    });
+  }
+  return { answers };
+}
+
+/**
+ * Build the pending-interaction registry.
+ * @param options - injectable clock and timers.
+ * @returns the registry the channels and the answerers share.
+ */
+export function createApprovalRegistry({
+  now = () => new Date(),
+  timeoutMs = 120_000,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  onDismissed,
+} = {}) {
+  /** requestId -> { sessionId, request, settle, timer } */
+  const pending = new Map();
+  /** Web bridges observing structured questions; observing never owns or settles them. */
+  const questionObservers = new Set();
+  let counter = 0;
+
+  function questionRequestEvent(request) {
+    return {
+      type: 'interaction-request',
+      sessionId: request.sessionId,
+      requestId: request.requestId,
+      kind: request.kind,
+      questions: request.questions.map((question) => ({ ...question })),
+    };
+  }
+
+  function notifyQuestionObservers(event) {
+    for (const observer of questionObservers) {
+      try {
+        observer(event);
+      } catch {
+        // An unavailable Web observer must not affect the single pending answer.
+      }
+    }
+  }
+
+  function nextRequestId(prefix = 'dsh-approval') {
+    counter += 1;
+    return `${prefix}-${counter}`;
+  }
+
+  /**
+   * Register one pending interaction and hand back its lifetime controls.
+   *
+   * Both seams go through here so their timeouts, aborts and dismissals behave
+   * identically — a question that can hang a turn deserves the same care as an
+   * approval that can.
+   */
+  function register({ sessionId, request, prefix, signal, answerOf }) {
+    let settle;
+    const answered = new Promise((resolve) => {
+      settle = resolve;
+    });
+
+    const finish = (outcome) => {
+      const entry = pending.get(request.requestId);
+      if (entry === undefined) return;
+      pending.delete(request.requestId);
+      if (entry.timer !== null) clearTimer(entry.timer);
+      if (entry.onAbort !== null && signal !== undefined) signal.removeEventListener('abort', entry.onAbort);
+      // Every close — answered, timed out, or withdrawn — tells the watching
+      // controllers the card is done. Without it a second screen keeps showing a
+      // question that no longer exists, and the panel only clears on its next
+      // poll.
+      if (typeof onDismissed === 'function') {
+        try {
+          onDismissed({ sessionId, requestId: request.requestId });
+        } catch {
+          // A broken listener must not strand the answer the asker is waiting on.
+        }
+      }
+      if (request.kind === QUESTION_KIND) {
+        notifyQuestionObservers({
+          type: 'interaction-dismissed',
+          sessionId,
+          requestId: request.requestId,
+          kind: request.kind,
+        });
+      }
+      settle(outcome);
+    };
+
+    // The asker withdrawing the question settles it immediately, and a late
+    // answer from the controller is then discarded by `finish`'s guard.
+    const onAbort = signal === undefined ? null : () => finish(answerOf.cancelled);
+    if (onAbort !== null) signal.addEventListener('abort', onAbort, { once: true });
+
+    const timer = timeoutMs > 0
+      ? setTimer(() => finish(answerOf.cancelled), timeoutMs)
+      : null;
+    if (typeof timer?.unref === 'function') timer.unref();
+
+    pending.set(request.requestId, { sessionId, request, settle: finish, timer, onAbort, answerOf });
+    if (request.kind === QUESTION_KIND) notifyQuestionObservers(questionRequestEvent(request));
+    return { requestId: request.requestId, request, answered };
+  }
+
+  /**
+   * Register a question and wait for the controller's answer.
+   * @param options - the question, the asking session, and the caller's abort signal.
+   * @returns DSH's outcome vocabulary.
+   */
+  async function ask({ sessionId, toolName, reason, callId, signal }) {
+    const requestId = nextRequestId();
+    const request = {
+      kind: PERMISSION_KIND,
+      requestId,
+      sessionId,
+      toolName,
+      ...(typeof reason === 'string' && reason !== '' ? { reason } : {}),
+      ...(typeof callId === 'string' ? { callId } : {}),
+      createdAt: now().toISOString(),
+    };
+    // DSH's approval vocabulary, and the controller's mapping onto it.
+    return register({
+      sessionId,
+      request,
+      signal,
+      answerOf: {
+        cancelled: 'cancelled',
+        from: (decision) => decisionOutcome(decision),
+      },
+    });
+  }
+
+  /**
+   * Register a structured question and wait for the controller's answer.
+   *
+   * DSH's `user-questions/request` waterfall blocks the tool call until this
+   * resolves, which is why it cannot be left unanswered: a controller that never
+   * sees the card cannot answer it, and the conversation stops there.
+   *
+   * @param options - the questions, the asking session, and the caller's abort signal.
+   * @returns DSH's `AskUserQuestionAnswer`; a cancellation answers every question with nothing.
+   */
+  async function askUser({ sessionId, questions, signal }) {
+    const items = Array.isArray(questions) ? questions : [];
+    const requestId = nextRequestId('dsh-question');
+    const request = {
+      kind: QUESTION_KIND,
+      requestId,
+      sessionId,
+      // The controller reads `questions` and keys its answer by the question text.
+      questions: items.map((question) => ({ ...question })),
+      createdAt: now().toISOString(),
+    };
+    const cancelled = { answers: items.map((question) => ({ id: String(question?.id ?? ''), selected: [] })) };
+    return register({
+      sessionId,
+      request,
+      signal,
+      answerOf: {
+        cancelled,
+        from: (decision) => questionAnswerOf(items, decision),
+      },
+    });
+  }
+
+  /** The questions still open for one session, in the controller's shape. */
+  function list(sessionId) {
+    const rows = [];
+    for (const entry of pending.values()) {
+      if (sessionId !== undefined && entry.sessionId !== sessionId) continue;
+      rows.push({ request: { ...entry.request } });
+    }
+    return rows;
+  }
+
+  /**
+   * Observe structured questions without acquiring any right to settle them.
+   *
+   * Registration first replays all still-pending question entries, so a Web bridge
+   * that reconnects renders the same registry the phone lists. It returns a
+   * disposer; disconnecting only stops observation and never cancels a turn.
+   */
+  function observeUserQuestions(observer) {
+    if (typeof observer !== 'function') return () => {};
+    questionObservers.add(observer);
+    for (const entry of pending.values()) {
+      if (entry.request.kind !== QUESTION_KIND) continue;
+      try {
+        observer(questionRequestEvent(entry.request));
+      } catch {
+        // A failed initial replay is no different from a failed live push.
+      }
+    }
+    return () => questionObservers.delete(observer);
+  }
+
+  /**
+   * Answer one pending interaction.
+   *
+   * The mapping comes from the **stored** entry, not from the decision's own
+   * kind: the entry knows which seam is waiting, so a permission decision aimed
+   * at a question — or the reverse — is refused rather than mistranslated.
+   * @param requestId - the id the controller echoes back.
+   * @param decision - the controller's decision payload.
+   * @returns whether the answer was accepted.
+   */
+  function settle(requestId, decision) {
+    const entry = pending.get(requestId);
+    if (entry === undefined) return { accepted: false };
+    const outcome = entry.answerOf.from(decision);
+    if (outcome === null) return { accepted: false };
+    entry.settle(outcome);
+    return { accepted: true };
+  }
+
+
+  /** Settle one pending interaction with an outcome already validated by DSH's local UI. */
+  function settleOutcome(requestId, outcome) {
+    const entry = pending.get(requestId);
+    if (entry === undefined) return { accepted: false };
+    entry.settle(outcome);
+    return { accepted: true };
+  }
+
+  /** Forget every open question (the switch going off). */
+  function clear() {
+    for (const requestId of [...pending.keys()]) {
+      pending.get(requestId).settle(pending.get(requestId).answerOf.cancelled);
+    }
+  }
+
+  return { ask, askUser, list, observeUserQuestions, settle, settleOutcome, clear, size: () => pending.size };
+}

package/src/host-attachments.js

@@ -0,0 +1,249 @@
+/**
+ * Turn a controller's attachment into a DSH prompt content part.
+ *
+ * The controller attaches files **inside the message**, not over a channel of
+ * their own: `maker:send` / `maker:input:enqueue` carry
+ * `files?: RemoteSerializedAttachment[]`. Two forms arrive, and both are serveable:
+ *
+ *  - **host path** — an absolute path on this machine (the file browser's "send to
+ *    session"). Readable through `ctx.fs`, so it becomes a durable attachment.
+ *  - **uploaded** — the bytes went to the Cindy account's OSS staging area and the
+ *    reference is a transit ref (`cindy-oss-attach://…` or the pre-rebrand
+ *    `xdt-oss-attach://…`). Fetching it is the controlled end's job and this Host
+ *    does it with its own account credential (`host-media.js`). Phones use the
+ *    **legacy** scheme, so both must be recognized; a reference this Host cannot
+ *    fetch is reported per attachment rather than guessed at.
+ *
+ * DSH's prompt content accepts exactly two attachment shapes
+ * (`PromptContentPart` in dsh-api-session-controller):
+ *
+ *  - `{ type: 'image', mediaType, data: <base64> }` — the Host promotes the bytes
+ *    to a durable reference itself;
+ *  - `{ type: 'file', receiptId }` — the receipt of a preceding `uploadFile`.
+ *
+ * So images are read and encoded here, and files go through
+ * `ctx.fileUploads.upload(agent, { data, name }, signal)`.
+ *
+ * @module dsh-cindy-host/host-attachments
+ */
+import { isAttachmentOssRef, parseAttachmentOssRef } from './host-media.js';
+
+/** Longest attachment this Host will read into memory. */
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+
+/**
+ * Image extensions DSH's attachment service admits, mapped to its media types.
+ *
+ * `ImageMediaType` is a closed union (`image/png | image/jpeg | image/webp |
+ * image/gif`), so an extension outside it is sent as a file rather than being
+ * forced into a media type the service would reject.
+ */
+export const IMAGE_MEDIA_TYPE_BY_EXT = Object.freeze({
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+});
+
+/** The extension of a path, lowercase, including the dot. */
+export function extensionOf(path) {
+  const text = typeof path === 'string' ? path : '';
+  const cut = Math.max(text.lastIndexOf('/'), text.lastIndexOf('\\'));
+  const leaf = cut < 0 ? text : text.slice(cut + 1);
+  const dot = leaf.lastIndexOf('.');
+  return dot <= 0 ? '' : leaf.slice(dot).toLowerCase();
+}
+
+/**
+ * Which media type an attachment claims, if it claims an image one.
+ *
+ * The controller's `mimeType` is taken only when it agrees with a media type DSH
+ * accepts; otherwise the extension decides, and a non-image extension means the
+ * bytes travel as a file.
+ * @param attachment - `{ path, name, mimeType }` from the controller.
+ * @returns a DSH `ImageMediaType`, or null for a non-image.
+ */
+export function imageMediaTypeOf(attachment) {
+  const declared = typeof attachment?.mimeType === 'string' ? attachment.mimeType.toLowerCase() : '';
+  if (Object.values(IMAGE_MEDIA_TYPE_BY_EXT).includes(declared)) return declared;
+  const byExtension = IMAGE_MEDIA_TYPE_BY_EXT[extensionOf(attachment?.path) ];
+  return byExtension ?? null;
+}
+
+/**
+ * Build the materializer over whatever filesystem and upload services exist.
+ *
+ * Either service may be absent when the profile does not compose it, which is
+ * reported per attachment rather than as a failure of the whole message: a prompt
+ * with an unresolvable attachment still carries its text, and the controller is
+ * told what was dropped.
+ *
+ * @param options - `{ fileSystem, fileUploads, resolveAttachmentRef, maxBytes }`.
+ *   `resolveAttachmentRef` fetches an uploaded attachment's bytes from the account's
+ *   media staging area; without it a transit ref is reported as unsupported rather
+ *   than passed to a filesystem as if it were a path.
+ * @returns `{ materialize }`, which answers `{ parts, dropped, consumed }` —
+ *   `consumed` being the staging keys whose bytes were taken, for the caller to
+ *   release once the prompt has landed.
+ */
+export function createAttachmentMaterializer({ fileSystem, fileUploads, resolveAttachmentRef, maxBytes = MAX_ATTACHMENT_BYTES } = {}) {
+  /** Read one whole file through the composed filesystem, or say why not. */
+  async function readWholeFile(path) {
+    if (fileSystem === undefined || fileSystem === null) return { ok: false, reason: 'no-filesystem' };
+    let target;
+    try {
+      target = typeof fileSystem.resolve === 'function' ? await fileSystem.resolve(path) : undefined;
+    } catch {
+      return { ok: false, reason: 'unreadable' };
+    }
+    if (target === undefined) return { ok: false, reason: 'unreadable' };
+    let info;
+    try {
+      info = await fileSystem.stat(target);
+    } catch {
+      return { ok: false, reason: 'unreadable' };
+    }
+    if (info?.type === 'directory') return { ok: false, reason: 'directory' };
+    const size = Number.isFinite(info?.size) ? info.size : null;
+    if (size !== null && size > maxBytes) return { ok: false, reason: 'oversize' };
+    try {
+      const bytes = await fileSystem.readByteRange(target, { offset: 0, length: size === null ? maxBytes : size });
+      const buffer = Buffer.from(bytes);
+      if (buffer.length > maxBytes) return { ok: false, reason: 'oversize' };
+      return { ok: true, buffer };
+    } catch {
+      // A sandbox denial surfaces here; it is the policy's answer, not a crash.
+      return { ok: false, reason: 'unreadable' };
+    }
+  }
+
+  /**
+   * Turn bytes this Host now holds into the prompt part the agent reads.
+   *
+   * One place for both sources, because the *shape* is DSH's contract and must not
+   * depend on where the bytes came from.
+   */
+  async function partFor({ buffer, name, mediaType, agent, signal }) {
+    if (mediaType !== null) return { part: { type: 'image', mediaType, data: buffer.toString('base64'), name } };
+    if (typeof fileUploads?.upload !== 'function') return { dropped: 'no-upload-service' };
+    try {
+      const uploaded = await fileUploads.upload(agent, { data: buffer.toString('base64'), name }, signal);
+      const receiptId = typeof uploaded?.receiptId === 'string' ? uploaded.receiptId : '';
+      if (receiptId === '') return { dropped: 'no-receipt' };
+      return { part: { type: 'file', receiptId } };
+    } catch (error) {
+      return { dropped: `upload-failed: ${String(error?.message ?? error)}` };
+    }
+  }
+
+  /**
+   * Materialize the controller's attachments for one prompt.
+   * @param options - the receiving agent, the controller's attachments, and a signal.
+   * @returns the content parts (text excluded), what was dropped and why, and the
+   *   staging keys the bytes came out of.
+   */
+  async function materialize({ agent, attachments: incoming = [], signal } = {}) {
+    const parts = [];
+    const dropped = [];
+    const consumed = [];
+    for (const attachment of Array.isArray(incoming) ? incoming : []) {
+      const path = typeof attachment?.path === 'string' ? attachment.path : '';
+      const name = typeof attachment?.name === 'string' && attachment.name !== ''
+        ? attachment.name
+        : leafNameOf(path);
+      if (path === '') {
+        dropped.push({ name, reason: 'no-path' });
+        continue;
+      }
+
+      let buffer;
+      let mediaType;
+      if (isAttachmentOssRef(path)) {
+        const ref = parseAttachmentOssRef(path);
+        if (ref === null) {
+          dropped.push({ name, reason: 'malformed-ref' });
+          continue;
+        }
+        if (typeof resolveAttachmentRef !== 'function') {
+          dropped.push({ name, reason: 'oss-ref-unsupported' });
+          continue;
+        }
+        const fetched = await resolveAttachmentRef(ref, { signal });
+        if (fetched?.ok !== true) {
+          dropped.push({ name, reason: String(fetched?.reason ?? 'fetch-failed') });
+          continue;
+        }
+        buffer = fetched.buffer;
+        // The reference's own claim about the type is the sender's, and it is the
+        // one the phone wrote when it uploaded the bytes; the attachment's `mimeType`
+        // is the fallback.
+        mediaType = imageMediaTypeOf({ mimeType: fetched.mimeType || ref.mimeType || attachment.mimeType, path: ref.originalName || name });
+        const built = await partFor({ buffer, name: fetched.name || name, mediaType, agent, signal });
+        if (built.part === undefined) dropped.push({ name, reason: built.dropped });
+        else {
+          parts.push(built.part);
+          consumed.push(ref.ossKey);
+        }
+        continue;
+      }
+
+      const read = await readWholeFile(path);
+      if (!read.ok) {
+        dropped.push({ name, reason: read.reason });
+        continue;
+      }
+      mediaType = imageMediaTypeOf(attachment);
+      const built = await partFor({ buffer: read.buffer, name, mediaType, agent, signal });
+      if (built.part === undefined) dropped.push({ name, reason: built.dropped });
+      else parts.push(built.part);
+    }
+    return { parts, dropped, consumed };
+  }
+
+  return { materialize };
+}
+
+/** The leaf name of a path, for a display name that never carries a directory. */
+function leafNameOf(path) {
+  const text = typeof path === 'string' ? path.replace(/[\\/]+$/, '') : '';
+  const cut = Math.max(text.lastIndexOf('/'), text.lastIndexOf('\\'));
+  return cut < 0 ? text : text.slice(cut + 1);
+}
+
+/**
+ * The controller's own attachments, split into what this Host can serve.
+ *
+ * Two forms are serveable and both are kept: an absolute host path, and an upload
+ * transit reference (either scheme), whose bytes this Host fetches with its own
+ * account credential. A path that is neither — a relative path, or some other
+ * `scheme://` this Host has no way to resolve — is dropped here rather than handed
+ * to a filesystem: the controller's claim about where a file lives is not evidence
+ * that it lives there.
+ *
+ * @param message - the controller's `QueuedRemoteMessage` (or send argument).
+ * @returns the serveable attachments, in submission order.
+ */
+export function hostAttachmentsOf(message) {
+  if (message === null || typeof message !== 'object') return [];
+  const files = Array.isArray(message.files) ? message.files : [];
+  const out = [];
+  for (const file of files) {
+    if (file === null || typeof file !== 'object') continue;
+    const path = typeof file.path === 'string' ? file.path.trim() : '';
+    if (path === '') continue;
+    const name = typeof file.name === 'string' && file.name !== '' ? file.name : leafNameOf(path);
+    const mimeType = typeof file.mimeType === 'string' ? file.mimeType : '';
+    const category = typeof file.category === 'string' ? file.category : '';
+    if (isAttachmentOssRef(path)) {
+      // A transit ref, not a path: the materializer fetches it. `name` is kept for
+      // the drop report, because a ref carries its own `originalName`.
+      out.push({ path, name, mimeType, category });
+      continue;
+    }
+    if (path.includes('://')) continue;
+    if (!/^[A-Za-z]:[\\/]/.test(path) && !path.startsWith('/')) continue;
+    out.push({ path, name, mimeType, category });
+  }
+  return out;
+}

package/src/host-authorization.js

@@ -0,0 +1,51 @@
+/**
+ * The link-accept this Host answers a controller's `link-open` with.
+ *
+ * Two payload fields matter beyond the formality of accepting:
+ *
+ *  - `allowlistHash` — a fingerprint of the channel set, so a controller can notice that
+ *    the two ends disagree about what exists.
+ *  - `capabilities` — the **optional end-to-end** features this controlled end offers.
+ *    They are negotiated here and nowhere else: the phone's transport reads
+ *    `accepted.capabilities` before it will even call a gated channel
+ *    (`apps/mobile/src/device-link/historyViewCapability.ts` refuses the three
+ *    `local-db:messages:*view*` channels unless `history-view-v1` is present). Serving a
+ *    gated channel without advertising its capability therefore changes nothing at all —
+ *    which is exactly the trap this file now documents.
+ */
+
+const CHANNELS = ['device-link:subscribe', 'local-db:sessions:list'];
+
+/**
+ * Optional capabilities this Host offers.
+ *
+ * `history-view-v1` (`DEVICE_LINK_CAPABILITY_HISTORY_VIEW_V1` in the Cindy protocol) turns
+ * on the work-grouped history window: the controller keeps a projection with its own cursor
+ * instead of re-deriving continuity from 20-row pages, which is what made re-entering a
+ * session drop the history it had already loaded.
+ */
+export const HOST_CAPABILITIES = Object.freeze(['history-view-v1']);
+
+export function computeAllowlistHash() { const text = [...CHANNELS].sort().join('\n'); let hash = 0x811c9dc5; for (let i = 0; i < text.length; i++) { hash ^= text.charCodeAt(i); hash = Math.imul(hash, 0x01000193) >>> 0; } return hash.toString(16).padStart(8, '0'); }
+
+/**
+ * Accept one controller's link and tell it what this Host can do.
+ * @param frame - the `link-open` frame being answered.
+ * @param acceptedControllers - the set of controllers this Host accepts.
+ * @param capabilities - what to advertise; defaults to {@link HOST_CAPABILITIES}.
+ * @returns the `link-accept` frame.
+ */
+export function acceptLink(frame, acceptedControllers, capabilities = HOST_CAPABILITIES) {
+  acceptedControllers.add(frame.src);
+  return {
+    v: 1,
+    kind: 'link-accept',
+    id: frame.id,
+    dst: frame.src,
+    payload: {
+      appVersion: '0.1.0',
+      allowlistHash: computeAllowlistHash(),
+      ...(capabilities.length === 0 ? {} : { capabilities: [...capabilities] }),
+    },
+  };
+}

package/src/host-demo.js

@@ -0,0 +1,3 @@
+import { FixtureDshSource } from './fixture-source.js';
+import { startHost } from './host.js';
+await startHost(new FixtureDshSource());