dsh-cindy-host 0.1.20

package/src/host-models.js

@@ -0,0 +1,231 @@
+/**
+ * Map DSH's model catalog onto the capability payload the Cindy controller reads.
+ *
+ * The controller validates every field before it will use any of it
+ * (`normalizeMobileAgentCapabilities` in `maker-shared/agentCapabilities.ts`), and
+ * two of its names are counter-intuitive enough to be worth stating outright:
+ *
+ *   - the display label is read from **`displayName`**, not from `label`;
+ *   - plan mode is read from **`planMode.supported`**, an object, not from a
+ *     boolean of the same meaning.
+ *
+ * Getting either wrong does not fail loudly: the field is simply dropped, the
+ * picker loses its list (or its label), and the surface looks like a Host that
+ * offers nothing.
+ */
+
+/** One `MobileChoiceOption`, in the wire shape the controller validates. */
+function toChoiceOption(id, name) {
+  if (typeof id !== 'string' || id === '') return null;
+  return {
+    id,
+    displayName: typeof name === 'string' && name !== '' ? name : id,
+  };
+}
+
+/**
+ * One `MobileModelOption`.
+ * @param model - a DSH `ModelCatalogModel`.
+ * @returns the wire option, or null when the model has no usable id.
+ */
+function toModelOption(model) {
+  if (typeof model?.id !== 'string' || model.id === '') return null;
+  const reasons = Array.isArray(model?.reasoning?.efforts) ? model.reasoning.efforts : [];
+  const efforts = [];
+  const effortDisplayNames = {};
+  for (const effort of reasons) {
+    if (typeof effort?.id !== 'string' || effort.id === '') continue;
+    efforts.push(effort.id);
+    effortDisplayNames[effort.id] = typeof effort.name === 'string' && effort.name !== '' ? effort.name : effort.id;
+  }
+
+  return {
+    id: model.id,
+    displayName: typeof model.name === 'string' && model.name !== '' ? model.name : model.id,
+    ...(typeof model.description === 'string' && model.description !== '' ? { description: model.description } : {}),
+    efforts,
+    effortDisplayNames,
+    defaultEffort: typeof model?.reasoning?.defaultEffort === 'string' && model.reasoning.defaultEffort !== ''
+      ? model.reasoning.defaultEffort
+      : null,
+    // DSH has no per-model fast mode, so the controller must not offer one.
+    supportsFastMode: false,
+  };
+}
+
+/**
+ * Every model the catalog offers, in provider order.
+ * @param catalog - a DSH `ModelCatalog`.
+ * @returns the controller's `availableModels`.
+ */
+export function toAvailableModels(catalog) {
+  const groups = Array.isArray(catalog?.groups) ? catalog.groups : [];
+  const models = [];
+  for (const group of groups) {
+    for (const model of Array.isArray(group?.models) ? group.models : []) {
+      const option = toModelOption(model);
+      if (option !== null) models.push(option);
+    }
+  }
+  return models;
+}
+
+/**
+ * The flat effort list the controller falls back to.
+ *
+ * DSH declares effort per model route, so this is the union — deduplicated in
+ * first-seen order, which keeps the list stable across catalog reads.
+ * @param availableModels - the options `toAvailableModels` produced.
+ * @returns the controller's `effortLevels`.
+ */
+export function toEffortLevels(availableModels) {
+  const seen = new Map();
+  for (const model of availableModels) {
+    for (const effort of Array.isArray(model?.efforts) ? model.efforts : []) {
+      if (seen.has(effort)) continue;
+      const option = toChoiceOption(effort, model?.effortDisplayNames?.[effort]);
+      if (option !== null) seen.set(effort, option);
+    }
+  }
+  return [...seen.values()];
+}
+
+/**
+ * The capability payload for one agent kind.
+ * @param catalog - a DSH `ModelCatalog`, or undefined when none loaded.
+ * @returns the payload `maker:get-capabilities` answers with.
+ */
+export function toAgentCapabilities(catalog) {
+  const availableModels = toAvailableModels(catalog);
+  return {
+    availableModels,
+    effortLevels: toEffortLevels(availableModels),
+    // This Host enforces no permission-mode vocabulary of its own; DSH's
+    // presets are not the controller's list, so the honest answer is empty.
+    permissionModes: [],
+    hasFastMode: false,
+    // Read as an object by the controller; a boolean here is silently ignored.
+    planMode: { supported: false },
+    supportsSessionAgentSwitch: false,
+    supportsModelWindowSwitchGuard: false,
+  };
+}
+
+/**
+ * The model id a session row should carry.
+ *
+ * The controller matches its current model with
+ * `availableModels.find(item => item.id === session.model)`, so a row whose
+ * `model` is a placeholder selects nothing and the picker shows no current model
+ * even when the catalog is correct.
+ * @param options - the catalog default and the session's recorded selection.
+ * @returns the model id, or null when the catalogue names none.
+ */
+export function modelIdFor({ catalog, selection }) {
+  const selected = selection?.model;
+  if (typeof selected === 'string' && selected !== '') return selected;
+  const fallback = catalog?.default?.model;
+  return typeof fallback === 'string' && fallback !== '' ? fallback : null;
+}
+
+/** Cindy's permission vocabulary mapped onto DSH's sandbox presets. */
+const CINDY_PERMISSION_BY_DSH = new Map([
+  ['read-only', { id: 'ask', displayName: 'Ask' }],
+  ['workspace-write', { id: 'acceptEdits', displayName: 'Accept edits' }],
+  ['danger-full-access', { id: 'bypassPermissions', displayName: 'Full access' }],
+]);
+const DSH_PERMISSION_BY_CINDY = new Map([...CINDY_PERMISSION_BY_DSH].map(([dsh, cindy]) => [cindy.id, dsh]));
+
+/** Translate one DSH permission preset to the public Cindy option id. */
+export function toCindyPermissionMode(value) {
+  return CINDY_PERMISSION_BY_DSH.get(value)?.id ?? 'ask';
+}
+
+/** Translate one Cindy permission choice back to the DSH preset name. */
+export function toDshPermissionMode(value) {
+  return DSH_PERMISSION_BY_CINDY.get(value) ?? null;
+}
+
+/** Advertise only DSH presets that have an exact Cindy control meaning. */
+export function toPermissionOptions(names) {
+  const seen = new Set();
+  const options = [];
+  for (const name of Array.isArray(names) ? names : []) {
+    const option = CINDY_PERMISSION_BY_DSH.get(name);
+    if (option === undefined || seen.has(option.id)) continue;
+    seen.add(option.id);
+    options.push({ ...option });
+  }
+  return options;
+}
+
+/**
+ * Project DSH's provider-grouped catalog into Cindy desktop's ProviderView wire shape.
+ * Routing credentials never cross this boundary; every Cindy harness alias reaches the
+ * same DSH catalog, so each provider exposes the same models under all aliases.
+ */
+export function toProviderList(catalog, agentKinds = []) {
+  const routable = new Set(Array.isArray(catalog?.routableProviders) ? catalog.routableProviders : []);
+  const agents = [...new Set((Array.isArray(agentKinds) ? agentKinds : []).filter((kind) => typeof kind === 'string' && kind !== ''))];
+  const providers = [];
+  for (const group of Array.isArray(catalog?.groups) ? catalog.groups : []) {
+    if (typeof group?.id !== 'string' || group.id === '') continue;
+    const models = [];
+    for (const model of Array.isArray(group.models) ? group.models : []) {
+      if (typeof model?.id !== 'string' || model.id === '') continue;
+      const contextWindow = Number(model.contextWindow);
+      if (!Number.isFinite(contextWindow) || contextWindow <= 0) continue;
+      const efforts = Array.isArray(model?.reasoning?.efforts)
+        ? model.reasoning.efforts.map((effort) => effort?.id).filter((id) => typeof id === 'string' && id !== '')
+        : [];
+      const defaultEffort = typeof model?.reasoning?.defaultEffort === 'string'
+        && efforts.includes(model.reasoning.defaultEffort)
+        ? model.reasoning.defaultEffort
+        : (efforts[0] ?? null);
+      models.push({
+        id: model.id,
+        name: typeof model.name === 'string' && model.name !== '' ? model.name : model.id,
+        contextWindow,
+        efforts,
+        defaultEffort,
+        supportsFastMode: false,
+        defaultEnabled: true,
+      });
+    }
+    if (models.length === 0) continue;
+    providers.push({
+      id: group.id,
+      name: typeof group.name === 'string' && group.name !== '' ? group.name : group.id,
+      agents,
+      connected: routable.has(group.id),
+      models: Object.fromEntries(agents.map((agent) => [agent, models.map((model) => ({ ...model }))])),
+    });
+  }
+  return { providers, providerOrder: providers.map((provider) => provider.id) };
+}
+
+/** The new-session defaults DSH can state without owning Cindy's draft preferences. */
+export function toNewMakerDefaults(catalog) {
+  const providerId = typeof catalog?.default?.provider === 'string' && catalog.default.provider !== ''
+    ? catalog.default.provider
+    : null;
+  const modelId = typeof catalog?.default?.model === 'string' && catalog.default.model !== ''
+    ? catalog.default.model
+    : null;
+  if (modelId === null) return {};
+  const group = (Array.isArray(catalog?.groups) ? catalog.groups : []).find((entry) => entry?.id === providerId);
+  const model = (Array.isArray(group?.models) ? group.models : []).find((entry) => entry?.id === modelId);
+  const efforts = Array.isArray(model?.reasoning?.efforts)
+    ? model.reasoning.efforts.map((effort) => effort?.id).filter((id) => typeof id === 'string' && id !== '')
+    : [];
+  const effort = typeof model?.reasoning?.defaultEffort === 'string' && efforts.includes(model.reasoning.defaultEffort)
+    ? model.reasoning.defaultEffort
+    : (efforts[0] ?? undefined);
+  return {
+    model: modelId,
+    modelChosenByUser: false,
+    ...(effort === undefined ? {} : { effort }),
+    fastMode: false,
+    providerId,
+  };
+}

package/src/host-palette.js

@@ -0,0 +1,111 @@
+/**
+ * The composer's `/` and `@` palettes, in the controller's vocabulary.
+ *
+ * Three channels feed them and they are easy to conflate:
+ *
+ *  - `maker:list-agent-commands` — the agent's own slash commands, e.g. `/compact`;
+ *  - `maker:list-agent-skills`   — user-invocable skills, listed separately so the
+ *    palette can offer them without pretending they are built-ins;
+ *  - `maker:scan-at-resources`   — the `@` menu, which lists paths, not commands.
+ *
+ * `maker:list-desktop-commands` is a fourth: commands that only the controlling
+ * desktop can run (Cindy's `/learn`). This Host owns none, and answering with an
+ * empty *success* is correct there — unlike the provider catalog, an empty list
+ * here means "nothing to offer", not "there is no such feature".
+ *
+ * Every list result is an envelope (`{ success, commands|skills|items }`), not a
+ * bare array: the controller reads the envelope, so an array would be dropped in
+ * silence.
+ */
+
+/**
+ * Map one DSH skill source onto the controller's `'user' | 'skill'`.
+ *
+ * DSH names where a skill came from; the controller only asks whether the user
+ * put it there.
+ */
+function skillSourceOf(source) {
+  return source === 'user-dsh' || source === 'user-agents' || source === 'custom' ? 'user' : 'skill';
+}
+
+/**
+ * Build the `maker:list-agent-skills` answer.
+ *
+ * Only skills a human may invoke are listed: `invocation.userInvocable` is DSH's
+ * own statement that a skill belongs in a human-facing catalog, and offering one
+ * that says no would put an entry in the palette that cannot run.
+ *
+ * @param summaries - `ctx.skills.list()` output.
+ * @returns the controller's `MobileAgentSkillListResult`.
+ */
+export function toAgentSkills(summaries) {
+  const skills = [];
+  for (const skill of Array.isArray(summaries) ? summaries : []) {
+    if (typeof skill?.name !== 'string' || skill.name === '') continue;
+    if (skill?.invocation?.userInvocable !== true) continue;
+    skills.push({
+      kind: 'agent-skill',
+      name: skill.name,
+      description: typeof skill.description === 'string' ? skill.description : undefined,
+      source: skillSourceOf(skill.source),
+    });
+  }
+  return { success: true, skills };
+}
+
+/**
+ * Build the `maker:list-agent-commands` / `maker:list-desktop-commands` answer.
+ * @param descriptors - `ctx.commands.list(agent)` output, or nothing.
+ * @param kind - the controller's command kind for this channel.
+ * @returns the controller's command list result.
+ */
+export function toAgentCommands(descriptors, kind = 'agent-builtin') {
+  const commands = [];
+  for (const command of Array.isArray(descriptors) ? descriptors : []) {
+    if (typeof command?.name !== 'string' || command.name === '') continue;
+    commands.push({
+      kind,
+      name: command.name,
+      description: typeof command.description === 'string' ? command.description : '',
+    });
+  }
+  return { success: true, commands };
+}
+
+/** Sort entries the way a palette reads: directories first, then by name. */
+function compareEntries(a, b) {
+  if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+  return a.name.localeCompare(b.name);
+}
+
+/**
+ * Build the `maker:scan-at-resources` answer for one working directory.
+ *
+ * The `@` menu lists what a message can reference, so this is a shallow listing
+ * of one directory rather than a tree: the controller re-scans with a deeper
+ * `relPath` when the user descends, and a tree would be both slower and larger
+ * than the palette can show.
+ *
+ * @param entries - directory entries: `{ name, kind }` where `kind` is `'dir'` or `'file'`.
+ * @param options - the base directory the entries are relative to, a cap, and a query filter.
+ * @returns the controller's `MobileAtResourceScanResult`.
+ */
+export function toAtResources(entries, { workingDir = '', cap = 200, query = '' } = {}) {
+  const wanted = typeof query === 'string' ? query.trim().toLowerCase() : '';
+  const items = [];
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (typeof entry?.name !== 'string' || entry.name === '') continue;
+    const isDir = entry.kind === 'dir';
+    if (wanted !== '' && !entry.name.toLowerCase().includes(wanted)) continue;
+    items.push({
+      type: isDir ? 'dir' : 'file',
+      name: entry.name,
+      // Relative to the working directory, which is the coordinate the
+      // controller sends back when the user picks the entry.
+      relPath: entry.name,
+    });
+  }
+  items.sort(compareEntries);
+  const limit = Number.isFinite(cap) && cap > 0 ? Math.floor(cap) : 200;
+  return { success: true, items: items.slice(0, limit), truncated: items.length > limit };
+}

package/src/host-push-channels.js

@@ -0,0 +1,37 @@
+/**
+ * Every push channel this Host sends, and the code that sends it.
+ *
+ * This list lives in `src` rather than in a tool because two callers need the same
+ * answer and had no way to share it: `tools/channel-audit.mjs` classifies the push
+ * side of the wire (what the phone handles, what this Host sends, what it declines
+ * and why), and `tools/acceptance.mjs` reports *coverage* — which of these channels a
+ * run actually produced. A second copy would drift, and the drift would be invisible:
+ * a channel added to the Host and forgotten here simply stops being audited.
+ *
+ * The value is the evidence for the claim, not a restatement of the code: each entry
+ * names the function that emits the frame, so a reader can check the pairing.
+ *
+ * @module dsh-cindy-host/host-push-channels
+ */
+
+/** Push channel → the emitting path in this Host. */
+export const HOST_PUSH_CHANNELS = new Map([
+  ['maker:event', 'host.js announceTurnRunning/announceTurnIdle (turn boundaries)'],
+  ['local-db:messages:created', 'host.js pushSessionMessage (live fold)'],
+  // The history view's own invalidation. The controller handles this channel *before* any
+  // store logic (`DeviceLinkContext`: `historyView?.invalidate(); return;`), and it is what
+  // refreshes a session the controller is already inside — without it a new message only
+  // appeared after re-entering the session (报：重新进入会话之后对话就出来了). The audit
+  // used to record this channel as deliberately unsent because the view it invalidates was
+  // the one this Host refused; the Host serves the view now, so the reason expired with it.
+  ['maker:history-view-changed', 'host.js pushSessionMessage (the view a session is showing)'],
+  ['maker:input:projection', 'host.js pushInputProjection (queue changes)'],
+  ['maker:goal:status-changed', 'host.js pushGoalStatus + applyControlFrame (goal projection)'],
+  ['maker:interaction-request', 'host.js askApproval/askUserQuestion'],
+  ['maker:interaction-dismissed', 'host.js onDismissed (answered, timed out, withdrawn)'],
+  ['local-db:sessions:created', 'session-publisher.publishLifecycle'],
+  ['local-db:sessions:patched', 'session-publisher.publishLifecycle'],
+  ['local-db:sessions:activity', 'session-publisher.publishActivity'],
+]);
+
+export default HOST_PUSH_CHANNELS;

package/src/host-reconnect.js

@@ -0,0 +1,54 @@
+/**
+ * Reconnect policy for the relay socket.
+ *
+ * The reference is the Cindy device-link **client** (`packages/device-link/src/client.ts`),
+ * which never treats a lost socket as a terminal state: it keeps a `connecting` status
+ * and retries with exponential backoff, which is why a Cindy client "从来没有掉线过".
+ * This Host used to do the opposite — drop the socket, report `failed`, and wait for a
+ * person to press reconnect. On a phone-controlled Host that is a silent outage: the
+ * card says 断线 and the handset simply has no DSH in its device list until someone
+ * walks over to the desktop.
+ *
+ * The numbers are the client's defaults, so both ends of the same link recover on the
+ * same schedule:
+ *
+ * | constant | value | meaning |
+ * | --- | --- | --- |
+ * | `RECONNECT_BASE_MS` | 1s | first retry |
+ * | `RECONNECT_MAX_MS` | 30s | cap, so retries continue forever at ≤30s |
+ * | `RECONNECT_STABLE_RESET_MS` | 10s | stably online this long resets the ladder |
+ *
+ * One deliberate omission: the client's separate **congestion** ladder
+ * (`congestionBackoffBaseMs`/`congestionStableResetMs`) is driven by its reliable
+ * transport's backpressure signal (`transport-timeout-close-v1`), and this Host has no
+ * such layer — inventing a second ladder without that signal would only make the delay
+ * harder to predict.
+ *
+ * @module dsh-cindy-host/host-reconnect
+ */
+
+/** First retry delay, matching the Cindy client. */
+export const RECONNECT_BASE_MS = 1_000;
+/** Longest gap between retries: retries continue indefinitely at this ceiling. */
+export const RECONNECT_MAX_MS = 30_000;
+/** How long a connection must hold before the attempt counter is forgotten. */
+export const RECONNECT_STABLE_RESET_MS = 10_000;
+
+/**
+ * Delay before the next attempt.
+ *
+ * Exponential from the base, capped, then multiplied by a **downward** jitter
+ * (0.7×–1.0×): many hosts that lose the same relay at the same moment must not come
+ * back in lockstep and re-congest it. Non-finite inputs are clamped rather than
+ * propagated — a `NaN` delay would silently become an immediate retry storm.
+ *
+ * @param options - `attempt` (0 for the first retry), the two bounds, and `random` in
+ *   `[0, 1]` (injected so a test can pin the curve).
+ * @returns milliseconds to wait.
+ */
+export function computeReconnectDelayMs({ attempt, reconnectBaseMs = RECONNECT_BASE_MS, reconnectMaxMs = RECONNECT_MAX_MS, random = 0 } = {}) {
+  const step = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
+  const roll = Number.isFinite(random) ? Math.min(Math.max(random, 0), 1) : 0;
+  const base = Math.min(reconnectBaseMs * 2 ** step, reconnectMaxMs);
+  return Math.round(base * (0.7 + roll * 0.3));
+}