@drscrewdriver/dsh-better-display 0.3.3-fork.1

package/src/client/types.ts

@@ -0,0 +1,89 @@
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { AssistantBlock, MessageImageLoader } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type {} from '@deepseek-ai/dsh-client-ui-chat/client';
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type {} from '@deepseek-ai/dsh-client-ui-session/client';
+import type { createReaderStore } from './store.js';
+import type { OfficialSeat } from './official-slots.js';
+import type { OpenFileOptions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type {} from '@deepseek-ai/dsh-client-ui-tool/client';
+
+export interface ReaderBlockOwner {
+  block: AssistantBlock;
+  streaming: boolean;
+  source: 'assistant' | 'user' | 'tool';
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** Trusted installed renderers may opt in; unknown model payloads never execute code. */
+    'dsh-better-display.block': { kind: 'chain'; scope: 'session'; owner: ReaderBlockOwner };
+  }
+}
+
+export interface ReaderInjected {
+  loadOlder: () => Promise<void>;
+  loadImage: (attachment: ImageAttachmentRef) => Promise<{ data: Uint8Array; mediaType: string }>;
+  /**
+   * Writes text into this session's composer draft via the sanctioned
+   * conversation input face, with a DOM fallback. Returns true when the
+   * composer accepted the text.
+   */
+  fillComposer: (text: string) => boolean;
+  /** Open a workspace file or directory; mode comes from the Better Display setting. */
+  openFile: (path: string, options?: OpenFileOptions) => Promise<void> | void;
+  officialImageLoader: MessageImageLoader;
+  officialFileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined;
+  officialPreviewFile: (path: string) => void;
+  officialHost: { getSnapshot: () => { home?: string }; subscribe: (listener: () => void) => () => void };
+  /** Root-scoped Better Display prefs (`dsh.reader.v1`), shared with Settings. */
+  openPrefs?: {
+    getSnapshot: () => {
+      deliverableOpenMode?: import('./open-file.js').DeliverableOpenMode;
+      frostedGlass?: boolean;
+      bubbles?: boolean;
+      foldIntensity?: import('./fold-intensity.js').FoldIntensity;
+      autoFold?: boolean;
+      processOnly?: boolean;
+    };
+    subscribe: (fn: () => void) => () => void;
+    actions?: {
+      setFoldIntensity?: (value: import('./fold-intensity.js').FoldIntensity) => void;
+      setAutoFold?: (value: boolean) => void;
+      setFrostedGlass?: (value: boolean) => void;
+      setBubbles?: (value: boolean) => void;
+      setDeliverableOpenMode?: (value: import('./open-file.js').DeliverableOpenMode) => void;
+    };
+  };
+  /** Reveal and highlight a workspace file in macOS Finder or Windows Explorer. */
+  revealFile?: (path: string) => Promise<void> | void;
+  /** Fork the conversation at a specific message sequence into a new branch session. */
+  forkAt?: (seq: number) => void;
+  /** Load session history through a target sequence number. */
+  loadThrough?: (seq: unknown) => Promise<void>;
+}
+export type ReaderProps = PropsRuntime<'conversation.view'>
+  & PropsLocale<'chat'>
+  & PropsRenderSlots<'dsh-better-display.block' | OfficialSeat>
+  & PropsStore<ReturnType<typeof createReaderStore>>
+  & ReaderInjected;
+export type BlockRenderProps = Pick<ReaderProps, 'renderSlotChain' | 'loadImage' | 'fillComposer'> & {
+  official?: Pick<ReaderProps, 'renderSlot' | 'renderSlotChain' | 'officialImageLoader' | 'officialFileMentions' | 'officialPreviewFile' | 'officialHost' | 'openView'>;
+  cwd?: string;
+  openFile?: (path: string, options?: OpenFileOptions) => Promise<void> | void;
+  revealFile?: (path: string) => Promise<void> | void;
+  forkAt?: (seq: number) => void;
+  /** Durable closing-message seq of this turn (turn-tail closing), used as the fork anchor. */
+  forkSeq?: number;
+  fileMentions?: MarkdownFileMentions;
+  metrics?: {
+    usage?: NonNullable<import('@deepseek-ai/dsh-client-ui-chat/client').TurnTailChatData['tokenUsage']>;
+    runMs?: number;
+    tokensPerSecond?: number;
+    ttftMs?: number;
+    /** Closing assistant-message time (turn-tail `closing.time`). */
+    endedAt?: number;
+  };
+};

package/src/client/waiting-clock.ts

@@ -0,0 +1,83 @@
+import type { ChatNodeKind } from '@deepseek-ai/dsh-client-ui-chat/client';
+
+export interface WaitingAnchor { key: string; time: number | null }
+type InputNode = { kind: string; data: unknown };
+type Submission = { requestId: string; time?: number; placement?: string };
+const timestamp = (value: number | undefined): number | null => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+
+/**
+ * Chat-layer kinds that hand the turn back to the model unconditionally.
+ *
+ * These are `ChatNodeDataMap` keys, NOT conversation-layer `ConversationNode` kinds.
+ * The two layers name the same idea differently: a returned tool is `tool-result`
+ * in the conversation contract, but the row the reader sees is the `tool-call` node.
+ * A name copied from the wrong layer silently disables the branch it guards, so
+ * the `satisfies` below makes the compiler reject any name that is not a real kind.
+ */
+export const WAIT_AFTER = new Set<ChatNodeKind>(['context', 'model-retry']);
+
+/**
+ * Every chat-kind the handover logic reasons about, checked against the host's own
+ * kind union at compile time. Adding a name here that the host does not register
+ * fails `tsc` instead of failing silently at runtime.
+ */
+export const HANDOVER_KINDS = [
+  'user', 'steering', 'context', 'model-retry', 'tool-call', 'command',
+] as const satisfies readonly ChatNodeKind[];
+
+/**
+ * Mirrors the host's `isSettledTool`: a running call has no `kind`, a settled one
+ * carries `kind: 'tool-result'`. Kept local so this module stays dependency-free,
+ * and pinned by a test against the host's own helper contract.
+ */
+function toolSettled(data: unknown): boolean {
+  const root = (data as { root?: unknown } | undefined)?.root;
+  return typeof root === 'object' && root !== null && (root as { kind?: unknown }).kind === 'tool-result';
+}
+
+/** A command that is still executing has no outcome yet; only a settled one hands over. */
+function commandSettled(data: unknown): boolean {
+  return (data as { outcome?: unknown } | undefined)?.outcome != null;
+}
+
+/**
+ * Does this node leave the model on the hook for the next move?
+ *
+ * A tool or command that is *still running* is not a wait — the tool is the one
+ * working. Only its returned form hands control back, which is exactly the moment
+ * the model can stall.
+ */
+export function handsBackToModel(node: InputNode): boolean {
+  if (node.kind === 'user' || node.kind === 'steering') return true;
+  if (node.kind === 'tool-call') return toolSettled(node.data);
+  if (node.kind === 'command') return commandSettled(node.data);
+  return WAIT_AFTER.has(node.kind as ChatNodeKind);
+}
+
+/**
+ * The moment the current wait began.
+ *
+ * This is the time of the **last** node that handed control to the model — a
+ * returned tool, an injected context, or the user's own message. Anchoring on the
+ * user's message alone made the readout count the entire turn, so a wait that had
+ * only just begun showed the minutes the tools had already spent.
+ */
+export function waitingAnchor(order: readonly string[], get: (key: string) => InputNode | undefined, pending: readonly Submission[] = []): WaitingAnchor {
+  let anchor: WaitingAnchor = { key: 'unresolved', time: null };
+  for (let i = order.length - 1; i >= 0; i--) {
+    const node = get(order[i]);
+    if (!node) continue;
+    if (!handsBackToModel(node)) continue;
+    const time = node.data && typeof node.data === 'object' && 'time' in node.data && typeof node.data.time === 'number' ? node.data.time : undefined;
+    anchor = { key: order[i], time: timestamp(time) };
+    break;
+  }
+  for (let i = pending.length - 1; i >= 0; i--) {
+    const input = pending[i];
+    if (input.placement === 'queued') continue;
+    const time = timestamp(input.time);
+    if (time === null || anchor.time === null || time >= anchor.time) return { key: `pending:${input.requestId}`, time };
+    break;
+  }
+  return anchor;
+}

package/src/client/word-motion.tsx

@@ -0,0 +1,92 @@
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from 'react';
+import type { ReactNode, RefObject } from 'react';
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives';
+import { MarkdownText } from './markdown/MarkdownText.js';
+import { readerPathImages } from './platform-media.js';
+import { WORD_MOTION, WordTimeline } from './word-timeline.js';
+import css from './Reader.module.css';
+
+const WordScope = createContext({ enabled: false, generation: 0 });
+const CODE_LABELS = { copyLabel: '复制代码', copiedLabel: '已复制' };
+
+function useSourceReveal(element: RefObject<HTMLElement>, born: number | null, generation: number) {
+  const scope = useContext(WordScope);
+  const cancelled = useRef(false);
+  useLayoutEffect(() => {
+    const target = element.current;
+    if (!target) return;
+    target.dataset.wordState = 'settled';
+    if (!scope.enabled || scope.generation !== generation) { cancelled.current = true; return; }
+    if (cancelled.current || born === null || document.hidden) return;
+    const age = Number(document.timeline.currentTime ?? performance.now()) - born;
+    if (age >= WORD_MOTION.duration || typeof target.animate !== 'function') return;
+    // The reference opacity + blur frames, applied only to this new word.
+    // No color interpolation, stylesheet mutation, or whole-paragraph wipe.
+    const animation = target.animate([
+      { opacity: 0, filter: `blur(${WORD_MOTION.blur}px)` },
+      { opacity: 1, filter: 'blur(0px)' },
+    ], { duration: WORD_MOTION.duration, easing: WORD_MOTION.easing, fill: 'backwards' });
+    // One absolute clock prevents newly mounted/resegmented leaves from getting
+    // a fresh delay or running ahead because their layout effects ran later.
+    animation.startTime = born;
+    target.dataset.wordState = 'resolving';
+    const finish = () => { animation.cancel(); target.dataset.wordState = 'settled'; document.removeEventListener('visibilitychange', hidden); };
+    animation.onfinish = finish;
+    const hidden = () => { if (document.hidden) { cancelled.current = true; finish(); } };
+    document.addEventListener('visibilitychange', hidden);
+    return () => { animation.cancel(); document.removeEventListener('visibilitychange', hidden); target.dataset.wordState = 'settled'; };
+  }, [element, born, generation, scope.enabled, scope.generation]);
+}
+
+function Word({ children, born, generation, offset, inline }: { children: string; born: number | null; generation: number; offset: number; inline: boolean }) {
+  const element = useRef<HTMLSpanElement>(null);
+  useSourceReveal(element, born, generation);
+  return <span ref={element} className={inline ? css.streamInlineWord : css.streamWord} data-reader-word data-source-start={offset} data-source-birth={born ?? undefined}>{children}</span>;
+}
+
+/** A native code block enters on the same clock, without rebuilding its text. */
+function MotionAtom({ children, born, generation, offset }: { children: ReactNode; born: number | null; generation: number; offset: number }) {
+  const element = useRef<HTMLDivElement>(null);
+  useSourceReveal(element, born, generation);
+  return <div ref={element} className={css.streamAtom} data-reader-atom data-source-start={offset} data-source-birth={born ?? undefined}>{children}</div>;
+}
+
+/** Native Think is literal text, not Markdown. Spans never alter its bytes. */
+export function MotionPlainText({ text, enabled, revision }: { text: string; enabled: boolean; revision: number }) {
+  const timeline = useRef<WordTimeline>();
+  timeline.current ??= new WordTimeline();
+  timeline.current.begin(text, enabled, revision, Number(document.timeline.currentTime ?? performance.now()));
+  const current = timeline.current;
+  const generation = current.generation;
+  const scope = useMemo(() => ({ enabled, generation }), [enabled, generation]);
+  return <WordScope.Provider value={scope}><div className={css.reasonPlain}>
+    {current.hasLiveText ? current.words(text, 0).map(word => word.text.trim()
+      ? <Word key={word.key} born={word.born} generation={generation} offset={word.key} inline>{word.text}</Word>
+      : word.text) : text}
+  </div></WordScope.Provider>;
+}
+
+/** Native DSH Markdown semantics with a stable text-leaf animation hook. */
+export function MotionMarkdown({ text, streaming, enabled, revision, fileMentions }: {
+  text: string; streaming: boolean; enabled: boolean; revision: number; fileMentions?: MarkdownFileMentions;
+}) {
+  const timeline = useRef<WordTimeline>();
+  timeline.current ??= new WordTimeline();
+  timeline.current.begin(text, enabled, revision, Number(document.timeline.currentTime ?? performance.now()));
+  const generation = timeline.current.generation;
+  const scope = useMemo(() => ({ enabled, generation }), [enabled, generation]);
+  const renderText = useMemo(() => (value: string, offset: number, inline = false): ReactNode => {
+    const current = timeline.current!;
+    if (!current.hasLiveText) return value;
+    return current.words(value, offset).map(word => word.text.trim()
+      ? <Word key={word.key} born={word.born} generation={current.generation} offset={word.key} inline={inline || /^\p{P}+$/u.test(word.text)}>{word.text}</Word>
+      : word.text);
+  }, []);
+  const renderAtom = useMemo(() => (children: ReactNode, offset: number): ReactNode => {
+    const current = timeline.current!;
+    return current.hasLiveText ? <MotionAtom born={current.bornAt(offset)} generation={current.generation} offset={offset}>{children}</MotionAtom> : children;
+  }, []);
+  return <WordScope.Provider value={scope}>
+    <MarkdownText text={text} streaming={streaming} codeLabels={CODE_LABELS} fileMentions={fileMentions} pathImages={readerPathImages} renderText={renderText} renderAtom={renderAtom} />
+  </WordScope.Provider>;
+}

package/src/client/word-timeline.ts

@@ -0,0 +1,113 @@
+/** Motion parameters from the public transitions.dev streaming-text recipe. */
+export const WORD_MOTION = {
+  duration: 350,
+  gap: 60,
+  blur: 1,
+  easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+  maxDelay: 240,
+  /** Floor for the per-word cadence once a batch is compressed. */
+  minGap: 3,
+  /** One paint's words should land inside this window, however many arrive. */
+  batchMs: 90,
+} as const;
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'word' });
+const closingPunctuation = /^[\p{Pe}\p{Pf},.!?:;，。！？、；：％‰…·]+$/u;
+const openingPunctuation = /^[\p{Ps}\p{Pi}]+$/u;
+export interface RevealingWord { key: number; text: string; born: number | null }
+interface SourceBirth { end: number; born: number | null }
+
+/** Source-offset identity survives reparsing, frozen blocks, and final formatting. */
+export class WordTimeline {
+  generation = 0;
+  hasLiveText = false;
+  private source: string | null = null;
+  private enabled = false;
+  private revision = 0;
+  private floor = 0;
+  private lastBirth = -Infinity;
+  private readonly births: SourceBirth[] = [];
+
+  begin(source: string, enabled: boolean, revision: number, now: number): void {
+    if (this.source === source && this.enabled === enabled && this.revision === revision) return;
+    const replaced = revision !== this.revision || (this.source !== null && !source.startsWith(this.source));
+    if (replaced || !enabled) {
+      this.births.length = 0;
+      this.lastBirth = -Infinity;
+      this.generation++;
+      this.floor = source.length;
+    } else if (this.source === null) {
+      // A mounted historical prefix must not replay; a fresh live buffer mounts empty.
+      this.floor = source.length;
+    } else {
+      // Allocate in source order, before Markdown can split/reorder text leaves.
+      // Intervals cover every offset, so resegmented CJK words inherit the time
+      // of their characters rather than falling through as instant "history".
+      const from = this.source.length;
+      const added = source.slice(from);
+      // The cadence follows the batch, not a constant. A fixed per-word gap caps
+      // the reveal at ~16 words/second however fast the model actually wrote, so
+      // a 500 tok/s answer still dripped out one word at a time. A batch of many
+      // words is compressed into one short window instead; a lone word keeps the
+      // original typing rhythm.
+      let arriving = 0;
+      for (const part of segmenter.segment(added)) if (part.segment.trim()) arriving++;
+      const gap = arriving > 1
+        ? Math.max(WORD_MOTION.minGap, Math.min(WORD_MOTION.gap, WORD_MOTION.batchMs / arriving))
+        : WORD_MOTION.gap;
+      for (const part of segmenter.segment(added)) {
+        let born = Number.isFinite(this.lastBirth) ? this.lastBirth : null;
+        if (part.segment.trim()) {
+          // Capping at the batch window is what stops a queue from forming: the
+          // clock can never run further ahead than one window past the newest text.
+          born = Math.min(now + WORD_MOTION.batchMs, Math.max(now, this.lastBirth + gap));
+          this.lastBirth = born;
+        }
+        const end = from + part.index + part.segment.length;
+        const previous = this.births.at(-1);
+        if (previous && previous.born === born) previous.end = end;
+        else this.births.push({ end, born });
+      }
+    }
+    this.source = source;
+    this.enabled = enabled;
+    this.revision = revision;
+    this.hasLiveText = enabled && this.births.length > 0;
+  }
+
+  bornAt(offset: number): number | null {
+    if (!this.enabled || offset < this.floor || this.births.length === 0) return null;
+    let low = 0;
+    let high = this.births.length - 1;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (this.births[middle]!.end <= offset) low = middle + 1;
+      else high = middle;
+    }
+    return this.births[low]!.born;
+  }
+
+  words(value: string, offset: number): RevealingWord[] {
+    // Atomic inline animation boxes must not turn commas into legal line starts
+    // or strand opening quotes at a line end. Keep source-offset identities when
+    // punctuation arrives in a later chunk, so the preceding word never replays.
+    // Already received text is one inert leaf, not thousands of React Words.
+    // Only the newly appended suffix needs word identities and birth times.
+    const prefixLength = Math.min(value.length, Math.max(0, this.floor - offset));
+    const prefix: RevealingWord[] = prefixLength > 0
+      ? [{ key: offset, text: value.slice(0, prefixLength), born: null }]
+      : [];
+    const parts: { index: number; segment: string }[] = [];
+    for (const segment of segmenter.segment(value.slice(prefixLength))) {
+      const part = { index: prefixLength + segment.index, segment: segment.segment };
+      const previous = parts.at(-1);
+      if (previous?.segment.trim() && (closingPunctuation.test(part.segment) || openingPunctuation.test(previous.segment))) {
+        previous.segment += part.segment;
+      } else parts.push({ index: part.index, segment: part.segment });
+    }
+    return prefix.concat(parts.map(part => {
+      const key = offset + part.index;
+      return { key, text: part.segment, born: this.bornAt(key) };
+    }));
+  }
+}

package/src/dsh-better-display.ts

@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import { scanGenerativeMcpappsStatus } from './skill-roots.js';
+import { skillsFromListResult, toPublicSkillStatus } from './skill-status.js';
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webServer?: {
+      register: (route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+      }) => () => void;
+    };
+  }
+}
+
+export const name = '@drscrewdriver/dsh-better-display';
+export const inject = ['webServer'];
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  res.setHeader('Content-Type', 'application/json');
+  res.statusCode = status;
+  res.end(JSON.stringify(body));
+}
+
+function skillLister(ctx: Context): (() => Promise<readonly { readonly name?: string }[] | undefined>) | undefined {
+  const skills = ctx.get?.('skills') as { list?: (options?: object) => Promise<unknown> } | undefined;
+  if (typeof skills?.list !== 'function') return undefined;
+  return async () => skillsFromListResult(await skills.list!({}));
+}
+
+export function apply(ctx: Context): void {
+  console.log('[my-plugins/dsh-better-display] loaded');
+
+  if (ctx.webServer) {
+    ctx.effect(() => {
+      const disposeReveal = ctx.webServer!.register({
+        kind: 'exact',
+        path: '/better-display/reveal',
+        handler: async (req, res) => {
+          if (req.method !== 'POST') {
+            res.statusCode = 405;
+            res.end();
+            return;
+          }
+          let body = '';
+          req.on('data', chunk => { body += chunk; });
+          req.on('end', () => {
+            try {
+              const data = JSON.parse(body);
+              const targetPath = typeof data.path === 'string' ? data.path.trim() : '';
+              if (!targetPath) {
+                res.statusCode = 400;
+                res.end(JSON.stringify({ ok: false, error: 'Empty path' }));
+                return;
+              }
+
+              if (process.platform === 'darwin') {
+                // Exact file reveal in macOS Finder with selection highlight
+                spawn('open', ['-R', targetPath], { detached: true, stdio: 'ignore' });
+              } else if (process.platform === 'win32') {
+                // Exact file selection in Windows Explorer
+                spawn('explorer.exe', [`/select,${targetPath}`], { detached: true, stdio: 'ignore' });
+              } else {
+                spawn('xdg-open', [targetPath], { detached: true, stdio: 'ignore' });
+              }
+
+              res.setHeader('Content-Type', 'application/json');
+              res.statusCode = 200;
+              res.end(JSON.stringify({ ok: true }));
+            } catch (err) {
+              res.statusCode = 400;
+              res.end(JSON.stringify({ ok: false, error: String(err) }));
+            }
+          });
+        },
+      });
+      const disposeSkill = ctx.webServer!.register({
+        kind: 'exact',
+        path: '/better-display/skill-status',
+        handler: async (req, res) => {
+          if (req.method !== 'GET') {
+            res.statusCode = 405;
+            res.end();
+            return;
+          }
+          try {
+            const url = new URL(req.url ?? '', 'http://127.0.0.1');
+            const cwd = url.searchParams.get('cwd') ?? undefined;
+            const status = await scanGenerativeMcpappsStatus({
+              cwd,
+              listSkills: skillLister(ctx),
+            });
+            writeJson(res, 200, toPublicSkillStatus(status));
+          } catch (err) {
+            writeJson(res, 500, { ok: false, error: String(err) });
+          }
+        },
+      });
+      return () => {
+        disposeReveal();
+        disposeSkill();
+      };
+    }, 'dsh-better-display: reveal and skill-status routes');
+  }
+}

package/src/skill-roots.ts

@@ -0,0 +1,138 @@
+import { access, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  GENERATIVE_MCPAPPS_SKILL,
+  skillListIncludes,
+  skillRootEntryMatches,
+  type HostSkillStatus,
+  type SkillRootInfo,
+} from './skill-status.js';
+
+export function expandHomePath(path: string, home = homedir()): string {
+  if (path === '~') return home;
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(home, path.slice(2));
+  return path;
+}
+
+/** `$DSH_HOME` or `~/.dsh`, matching official `resolveDshHome`. */
+export function resolveDshHome(env: Record<string, string | undefined> = process.env, home = homedir()): string {
+  const fromEnv = env.DSH_HOME;
+  const selected = fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : join(home, '.dsh');
+  return resolve(expandHomePath(selected, home));
+}
+
+/** `$DSH_AGENTS_HOME` or `~/.agents`. */
+export function resolveAgentsHome(env: Record<string, string | undefined> = process.env, home = homedir()): string {
+  const fromEnv = env.DSH_AGENTS_HOME;
+  const selected = fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : join(home, '.agents');
+  return resolve(expandHomePath(selected, home));
+}
+
+export function userSkillRoots(
+  env: Record<string, string | undefined> = process.env,
+  home = homedir(),
+): readonly SkillRootInfo[] {
+  return [
+    { source: 'user-dsh', path: join(resolveDshHome(env, home), 'skills') },
+    { source: 'user-agents', path: join(resolveAgentsHome(env, home), 'skills') },
+  ];
+}
+
+export function projectSkillRoots(projectRoot: string): readonly SkillRootInfo[] {
+  return [
+    { source: 'project-dsh', path: join(projectRoot, '.dsh', 'skills') },
+    { source: 'project-agents', path: join(projectRoot, '.agents', 'skills') },
+  ];
+}
+
+export async function findProjectRoot(cwd: string): Promise<string> {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(join(current, '.git'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(cwd);
+    current = parent;
+  }
+}
+
+export async function rootHasGenerativeMcpapps(rootPath: string): Promise<boolean> {
+  let entries;
+  try {
+    entries = await readdir(rootPath, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (entry.name === '.system') continue;
+    if (!skillRootEntryMatches(entry.name)) continue;
+    if (entry.isDirectory()) {
+      try {
+        await access(join(rootPath, entry.name, 'SKILL.md'));
+        return true;
+      } catch {
+        continue;
+      }
+    }
+    if (entry.isFile()) return true;
+  }
+  return false;
+}
+
+/** Resolve the plugin-shipped pack. This path is never treated as a skill root. */
+export function pluginSkillPackPath(moduleUrl = import.meta.url): string | undefined {
+  const here = dirname(fileURLToPath(moduleUrl));
+  const candidates = [
+    join(here, '../skills', GENERATIVE_MCPAPPS_SKILL),
+    join(here, '../../skills', GENERATIVE_MCPAPPS_SKILL),
+    join(here, 'skills', GENERATIVE_MCPAPPS_SKILL),
+  ];
+  return candidates.find(path => existsSync(join(path, 'SKILL.md')));
+}
+
+export async function scanGenerativeMcpappsStatus(options: {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  home?: string;
+  packPath?: string;
+  listSkills?: () => Promise<readonly { readonly name?: string }[] | undefined>;
+} = {}): Promise<HostSkillStatus> {
+  const env = options.env ?? process.env;
+  const home = options.home ?? homedir();
+  const roots: SkillRootInfo[] = [...userSkillRoots(env, home)];
+  const cwd = typeof options.cwd === 'string' && options.cwd.trim().length > 0
+    ? (isAbsolute(options.cwd) ? options.cwd : resolve(options.cwd))
+    : undefined;
+  if (cwd !== undefined) roots.unshift(...projectSkillRoots(await findProjectRoot(cwd)));
+
+  const inspected: SkillRootInfo[] = [];
+  let rootHit = false;
+  for (const root of roots) {
+    const present = await rootHasGenerativeMcpapps(root.path);
+    inspected.push({ ...root, present });
+    if (present) rootHit = true;
+  }
+
+  let via: HostSkillStatus['via'] = null;
+  let listHit = false;
+  if (options.listSkills) {
+    try {
+      listHit = skillListIncludes(await options.listSkills());
+      if (listHit) via = 'skills.list';
+    } catch {
+      // Registry/RPC absence falls back to the scanned roots.
+    }
+  }
+  if (!listHit && rootHit) via = 'skill-root';
+
+  const packPath = options.packPath ?? pluginSkillPackPath();
+  return {
+    name: GENERATIVE_MCPAPPS_SKILL,
+    installed: listHit || rootHit,
+    via,
+    roots: inspected,
+    ...packPath !== undefined ? { packPath } : {},
+  };
+}