@modesto_ma/dsh-channels 0.4.0 → 0.5.0-beta.2

package/src/feishu/wiki/api.ts

@@ -0,0 +1,346 @@
+/**
+ * Feishu wiki (知识库) and docx OpenAPI calls used by the wiki tools, made
+ * with the app identity (tenant access token).
+ *
+ * Structure calls use `wiki/v2` (`spaces/get_node`, `spaces/:id`,
+ * `spaces/:id/nodes`); document content uses the `docs_ai/v1` document
+ * endpoints, which read and write Markdown or Feishu document XML directly
+ * (block ids are exported only in XML); the revision check uses
+ * `docx/v1/documents/:id`. Every call maps a thrown transport error or a
+ * non-zero Feishu `code` to {@link FeishuApiError}.
+ *
+ * @module dsh-channels/feishu/wiki/api
+ */
+
+import { FeishuApiError } from '../../feishu-channel.ts'
+
+/** Object kinds a wiki node can hold. */
+export type WikiObjType = 'doc' | 'docx' | 'sheet' | 'mindnote' | 'bitable' | 'file' | 'slides'
+
+/** One wiki node as the tools use it. */
+export interface WikiNode {
+  readonly spaceId: string
+  readonly nodeToken: string
+  /** Token of the document the node holds (the docx `document_id` for docx). */
+  readonly objToken: string
+  readonly objType: WikiObjType
+  /** Parent node; absent for a top-level node of its space. */
+  readonly parentNodeToken?: string
+  readonly nodeType: 'origin' | 'shortcut'
+  readonly title: string
+  readonly hasChild: boolean
+  /** Owner id as Feishu reports it (an open_id; the app's bot open_id when the app owns it). */
+  readonly owner?: string
+  /** Web link, when Feishu returned one. */
+  readonly url?: string
+}
+
+/** One page of child nodes. */
+export interface WikiNodePage {
+  readonly items: readonly WikiNode[]
+  /** Cursor of the next page; absent on the last page. */
+  readonly pageToken?: string
+}
+
+/** Read scopes of `docs_ai` fetch. */
+export type WikiReadScope = 'full' | 'outline' | 'section' | 'range' | 'keyword'
+
+/** Content format of `docs_ai` reads and writes. */
+export type WikiDocFormat = 'markdown' | 'xml'
+
+/** One `docs_ai` fetch request. */
+export interface WikiFetchRequest {
+  readonly format: WikiDocFormat
+  /** Export block ids (XML only; Feishu ignores it for Markdown). */
+  readonly withBlockIds: boolean
+  readonly scope: WikiReadScope
+  readonly startBlockId?: string
+  readonly endBlockId?: string
+  readonly keyword?: string
+  /** `outline`: heading level cap; other scopes: subtree depth. */
+  readonly maxDepth?: number
+}
+
+/** One fetched document. */
+export interface WikiDocument {
+  readonly revisionId: number
+  readonly content: string
+}
+
+/** `docs_ai` update commands. */
+export type WikiUpdateCommand =
+  | 'str_replace'
+  | 'block_insert_after'
+  | 'block_replace'
+  | 'block_delete'
+  | 'overwrite'
+
+/** One `docs_ai` update request. */
+export interface WikiUpdateRequest {
+  readonly command: WikiUpdateCommand
+  readonly format: WikiDocFormat
+  readonly content?: string
+  readonly pattern?: string
+  /** Anchor or target block; `-1` = document end for `block_insert_after`. */
+  readonly blockId?: string
+  readonly startBlockId?: string
+  readonly endBlockId?: string
+  /** Base revision; Feishu rejects the update when the document moved past it. */
+  readonly revisionId?: number
+}
+
+/** Outcome of one update. */
+export interface WikiUpdateResult {
+  /** `success`, `partial_success`, or `failed` as Feishu reports it. */
+  readonly result: string
+  readonly revisionId?: number
+  readonly updatedBlocks?: number
+  readonly warnings: readonly string[]
+}
+
+/** The wiki/docx endpoints the wiki tools consume. */
+export interface WikiApi {
+  /**
+   * Resolve a node token (or, with `objType: 'docx'`, a docx token mounted in
+   * the wiki) to its node.
+   * @param token Node token or docx token.
+   * @param objType `wiki` for a node token, `docx` for a document token.
+   * @returns The node.
+   */
+  getNode(token: string, objType: 'wiki' | 'docx'): Promise<WikiNode>
+  /**
+   * Name of one space.
+   * @param spaceId Wiki space id.
+   * @returns The space name.
+   */
+  spaceName(spaceId: string): Promise<string>
+  /**
+   * One page of children; the space's top-level nodes without a parent.
+   * @param spaceId Wiki space id.
+   * @param parentNodeToken Parent node, or undefined for the space top level.
+   * @param pageToken Cursor from the previous page.
+   * @returns The page.
+   */
+  listChildren(spaceId: string, parentNodeToken: string | undefined, pageToken?: string): Promise<WikiNodePage>
+  /**
+   * Create one empty docx node.
+   * @param spaceId Wiki space id.
+   * @param parentNodeToken Parent node, or undefined for the space top level.
+   * @param title Node title.
+   * @returns The new node.
+   */
+  createDocxNode(spaceId: string, parentNodeToken: string | undefined, title: string): Promise<WikiNode>
+  /**
+   * Current revision of one docx document.
+   * @param documentId Docx document id (the node's `objToken`).
+   * @returns The revision id.
+   */
+  documentRevision(documentId: string): Promise<number>
+  /**
+   * Read one docx document.
+   * @param documentId Docx document id.
+   * @param request Format and scope.
+   * @returns Content and revision.
+   */
+  fetchDocument(documentId: string, request: WikiFetchRequest): Promise<WikiDocument>
+  /**
+   * Apply one update command to a docx document.
+   * @param documentId Docx document id.
+   * @param request The command.
+   * @returns Feishu's outcome.
+   */
+  updateDocument(documentId: string, request: WikiUpdateRequest): Promise<WikiUpdateResult>
+}
+
+/** The SDK's generic authenticated request (`Client.request`). */
+export type WikiRawRequest = <T>(input: {
+  method: 'GET' | 'POST' | 'PUT'
+  url: string
+  params?: Record<string, string | number>
+  data?: object
+}) => Promise<T>
+
+interface FeishuEnvelope<T> {
+  code?: number
+  msg?: string
+  data?: T
+}
+
+interface RawNode {
+  space_id?: string
+  node_token?: string
+  obj_token?: string
+  obj_type?: string
+  parent_node_token?: string
+  node_type?: string
+  title?: string
+  has_child?: boolean
+  owner?: string
+  url?: string
+}
+
+const OBJ_TYPES: ReadonlySet<string> = new Set(['doc', 'docx', 'sheet', 'mindnote', 'bitable', 'file', 'slides'])
+
+/** Feishu's per-page maximum for `spaces/:id/nodes`. */
+const LIST_PAGE_SIZE = 50
+
+function thrownError(error: unknown): FeishuApiError {
+  if (error instanceof FeishuApiError) return error
+  const data = (error as { response?: { data?: { code?: unknown; msg?: unknown } } } | undefined)?.response?.data
+  const code = typeof data?.code === 'number' ? data.code : undefined
+  const msg = typeof data?.msg === 'string' ? data.msg : undefined
+  if (code === undefined && msg === undefined) return new FeishuApiError(error instanceof Error ? error.message : String(error))
+  return new FeishuApiError([code === undefined ? undefined : `code=${code}`, msg].filter(Boolean).join(' '), code)
+}
+
+async function call<T>(request: WikiRawRequest, input: Parameters<WikiRawRequest>[0]): Promise<T> {
+  let response: FeishuEnvelope<T>
+  try {
+    response = await request<FeishuEnvelope<T>>(input)
+  } catch (error) {
+    throw thrownError(error)
+  }
+  if (response.code !== undefined && response.code !== 0) {
+    throw new FeishuApiError(`code=${response.code}${response.msg === undefined ? '' : ` ${response.msg}`}`, response.code)
+  }
+  if (response.data === undefined) throw new FeishuApiError(`${input.url}: response has no data`)
+  return response.data
+}
+
+function wikiNode(raw: RawNode | undefined, where: string): WikiNode {
+  if (raw?.space_id === undefined || raw.node_token === undefined || raw.obj_token === undefined
+    || raw.obj_type === undefined || !OBJ_TYPES.has(raw.obj_type)) {
+    throw new FeishuApiError(`${where}: response node is incomplete`)
+  }
+  return {
+    spaceId: raw.space_id,
+    nodeToken: raw.node_token,
+    objToken: raw.obj_token,
+    objType: raw.obj_type as WikiObjType,
+    ...(raw.parent_node_token === undefined || raw.parent_node_token === '' ? {} : { parentNodeToken: raw.parent_node_token }),
+    nodeType: raw.node_type === 'shortcut' ? 'shortcut' : 'origin',
+    title: raw.title ?? '',
+    hasChild: raw.has_child === true,
+    ...(raw.owner === undefined || raw.owner === '' ? {} : { owner: raw.owner }),
+    ...(raw.url === undefined || raw.url === '' ? {} : { url: raw.url }),
+  }
+}
+
+function segment(value: string): string {
+  return encodeURIComponent(value)
+}
+
+/**
+ * {@link WikiApi} over the SDK's generic authenticated request.
+ *
+ * @param request `Client.request` of the connected SDK client.
+ * @returns The API.
+ */
+export function createWikiApi(request: WikiRawRequest): WikiApi {
+  return {
+    async getNode(token, objType) {
+      const url = '/open-apis/wiki/v2/spaces/get_node'
+      const data = await call<{ node?: RawNode }>(request, { method: 'GET', url, params: { token, obj_type: objType } })
+      return wikiNode(data.node, url)
+    },
+    async spaceName(spaceId) {
+      const data = await call<{ space?: { name?: string } }>(request, {
+        method: 'GET', url: `/open-apis/wiki/v2/spaces/${segment(spaceId)}`,
+      })
+      return data.space?.name ?? ''
+    },
+    async listChildren(spaceId, parentNodeToken, pageToken) {
+      const url = `/open-apis/wiki/v2/spaces/${segment(spaceId)}/nodes`
+      const data = await call<{ items?: RawNode[]; page_token?: string; has_more?: boolean }>(request, {
+        method: 'GET',
+        url,
+        params: {
+          page_size: LIST_PAGE_SIZE,
+          ...(parentNodeToken === undefined ? {} : { parent_node_token: parentNodeToken }),
+          ...(pageToken === undefined ? {} : { page_token: pageToken }),
+        },
+      })
+      return {
+        items: (data.items ?? []).map(item => wikiNode(item, url)),
+        ...(data.has_more === true && data.page_token !== undefined && data.page_token !== '' ? { pageToken: data.page_token } : {}),
+      }
+    },
+    async createDocxNode(spaceId, parentNodeToken, title) {
+      const url = `/open-apis/wiki/v2/spaces/${segment(spaceId)}/nodes`
+      const data = await call<{ node?: RawNode }>(request, {
+        method: 'POST',
+        url,
+        data: {
+          obj_type: 'docx',
+          node_type: 'origin',
+          title,
+          ...(parentNodeToken === undefined ? {} : { parent_node_token: parentNodeToken }),
+        },
+      })
+      return wikiNode(data.node, url)
+    },
+    async documentRevision(documentId) {
+      const url = `/open-apis/docx/v1/documents/${segment(documentId)}`
+      const data = await call<{ document?: { revision_id?: number } }>(request, { method: 'GET', url })
+      const revision = data.document?.revision_id
+      if (typeof revision !== 'number') throw new FeishuApiError(`${url}: response has no revision_id`)
+      return revision
+    },
+    async fetchDocument(documentId, fetch) {
+      const url = `/open-apis/docs_ai/v1/documents/${segment(documentId)}/fetch`
+      const ids = fetch.format === 'xml' && fetch.withBlockIds
+      const readOption = fetch.scope === 'full' ? undefined : {
+        read_mode: fetch.scope,
+        ...(fetch.startBlockId === undefined ? {} : { start_block_id: fetch.startBlockId }),
+        ...(fetch.endBlockId === undefined ? {} : { end_block_id: fetch.endBlockId }),
+        ...(fetch.keyword === undefined ? {} : { keyword: fetch.keyword }),
+        ...(fetch.maxDepth === undefined ? {} : { max_depth: String(fetch.maxDepth) }),
+      }
+      const data = await call<{ document?: { revision_id?: number; content?: string } }>(request, {
+        method: 'POST',
+        url,
+        data: {
+          format: fetch.format,
+          export_option: { export_block_id: ids, export_style_attrs: false, export_cite_extra_data: false },
+          ...(readOption === undefined ? {} : { read_option: readOption }),
+        },
+      })
+      const document = data.document
+      if (document === undefined || typeof document.content !== 'string') {
+        throw new FeishuApiError(`${url}: response has no document content`)
+      }
+      return { revisionId: document.revision_id ?? 0, content: document.content }
+    },
+    async updateDocument(documentId, update) {
+      const url = `/open-apis/docs_ai/v1/documents/${segment(documentId)}`
+      const data = await call<{
+        result?: string
+        updated_blocks_count?: number
+        warnings?: unknown
+        document?: { revision_id?: number }
+      }>(request, {
+        method: 'PUT',
+        url,
+        data: {
+          format: update.format,
+          command: update.command,
+          ...(update.content === undefined ? {} : { content: update.content }),
+          ...(update.pattern === undefined ? {} : { pattern: update.pattern }),
+          ...(update.blockId === undefined ? {} : { block_id: update.blockId }),
+          ...(update.startBlockId === undefined ? {} : { start_block_id: update.startBlockId }),
+          ...(update.endBlockId === undefined ? {} : { end_block_id: update.endBlockId }),
+          ...(update.revisionId === undefined ? {} : { revision_id: update.revisionId }),
+        },
+      })
+      const warnings = Array.isArray(data.warnings)
+        ? data.warnings.filter((item): item is string => typeof item === 'string' && item !== '')
+        : []
+      return {
+        result: data.result ?? 'success',
+        ...(data.document?.revision_id === undefined ? {} : { revisionId: data.document.revision_id }),
+        ...(data.updated_blocks_count === undefined ? {} : { updatedBlocks: data.updated_blocks_count }),
+        warnings,
+      }
+    },
+  }
+}

package/src/feishu/wiki/consent.ts

@@ -0,0 +1,183 @@
+/**
+ * Topic-owner consent for wiki tool calls.
+ *
+ * A wiki tool that opens, creates, or edits a document asks the topic owner
+ * on a consent card in the topic and waits for the answer. Only the topic
+ * owner (`route.senderUserId`) can decide; a click by anyone else adds the
+ * owner-only notice once. An unanswered card is denied after the configured
+ * window (`approvalTimeoutMs`). A read consent is remembered per Session and
+ * document, in memory only: it ends with the Session (`/renew`) or the
+ * process. Create and edit consents are never remembered.
+ *
+ * @module dsh-channels/feishu/wiki/consent
+ */
+
+import { randomUUID } from 'node:crypto'
+import { buildWikiConsentCard, buildWikiConsentSettledCard } from '../../cards/wiki.ts'
+import type { WikiConsentAction, WikiConsentCardState, WikiConsentQuestion } from '../../cards/wiki.ts'
+import type { CardActionEvent, FeishuChannel } from '../../feishu-channel.ts'
+import { PendingCardTable } from '../../interactions/pending.ts'
+import type { InteractionRoute, PendingCardEntry } from '../../interactions/pending.ts'
+
+/** How one consent request ended. */
+export type WikiConsentOutcome = 'allowed' | 'denied' | 'expired' | 'cancelled' | 'unavailable'
+
+/** One consent to ask for. */
+export interface WikiConsentRequest {
+  readonly sessionId: string
+  readonly route: InteractionRoute
+  readonly action: WikiConsentAction
+  readonly title: string
+  readonly url?: string
+  readonly location: string
+  readonly details: readonly string[]
+  /** The tool call's abort signal; aborting withdraws the card. */
+  readonly signal: AbortSignal
+}
+
+interface Pending extends PendingCardEntry {
+  readonly question: WikiConsentQuestion
+  resolve(outcome: WikiConsentOutcome): void
+}
+
+export interface WikiConsentDeps {
+  /** Live Feishu channel; undefined while disconnected. */
+  channel(): FeishuChannel | undefined
+  /** Decision window per card, read per request (`approvalTimeoutMs`). */
+  timeoutMs(): number
+  /** Log a non-fatal delivery/update failure. */
+  onError(sessionId: string, error: unknown): void
+}
+
+/** Consent cards for the wiki tools. */
+export class WikiConsent {
+  /** One table per channel instance (cards are patched through their channel). */
+  private table: { channel: FeishuChannel; entries: PendingCardTable<Pending> } | undefined
+  /** sessionId → document ids with a standing read consent. */
+  private readonly readGrants = new Map<string, Set<string>>()
+
+  constructor(private readonly deps: WikiConsentDeps) {}
+
+  /**
+   * Whether the Session already holds a read consent for one document.
+   * @param sessionId The Session.
+   * @param documentId Docx document id.
+   * @returns True when reading needs no new card.
+   */
+  hasReadGrant(sessionId: string, documentId: string): boolean {
+    return this.readGrants.get(sessionId)?.has(documentId) === true
+  }
+
+  /**
+   * Record a standing read consent (after an allowed read, or for a document
+   * the topic owner just approved creating).
+   * @param sessionId The Session.
+   * @param documentId Docx document id.
+   */
+  grantRead(sessionId: string, documentId: string): void {
+    let grants = this.readGrants.get(sessionId)
+    if (grants === undefined) {
+      grants = new Set()
+      this.readGrants.set(sessionId, grants)
+    }
+    grants.add(documentId)
+  }
+
+  /**
+   * Ask the topic owner and wait for the decision. Never rejects.
+   * @param request What to ask.
+   * @returns The outcome; `unavailable` when no card could be delivered.
+   */
+  request(request: WikiConsentRequest): Promise<WikiConsentOutcome> {
+    if (request.signal.aborted) return Promise.resolve('cancelled')
+    const channel = this.deps.channel()
+    if (channel === undefined) return Promise.resolve('unavailable')
+    const table = this.tableFor(channel)
+    const timeoutMs = this.deps.timeoutMs()
+    const question: WikiConsentQuestion = {
+      token: randomUUID(),
+      action: request.action,
+      title: request.title,
+      ...(request.url === undefined ? {} : { url: request.url }),
+      location: request.location,
+      details: request.details,
+      timeoutMs,
+    }
+    return new Promise<WikiConsentOutcome>((resolve) => {
+      const entry: Pending = {
+        token: question.token,
+        sessionId: request.sessionId,
+        route: request.route,
+        messageId: undefined,
+        settled: false,
+        timer: undefined,
+        signal: request.signal,
+        onAbort: undefined,
+        unauthorizedNoted: false,
+        question,
+        resolve,
+      }
+      const onAbort = (): void => this.settle(table, entry, 'cancelled', 'cancelled')
+      entry.onAbort = onAbort
+      request.signal.addEventListener('abort', onAbort, { once: true })
+      table.add(entry)
+      void table.deliver(entry, {
+        card: buildWikiConsentCard(question),
+        onWithdrawn: e => table.patch(e, buildWikiConsentSettledCard(e.question, 'cancelled')),
+        onDelivered: e => table.armTimeout(e, timeoutMs, () => this.settle(table, e, 'expired', 'expired')),
+        onFailure: e => this.settle(table, e, 'unavailable'),
+      })
+    })
+  }
+
+  /**
+   * Route one card button callback to its pending consent; unknown cards are
+   * ignored.
+   * @param event The card action.
+   */
+  onCardAction(event: CardActionEvent): void {
+    const table = this.table?.entries
+    if (table === undefined) return
+    const entry = table.resolveAction(event, (candidate) => {
+      if (candidate.unauthorizedNoted) return
+      candidate.unauthorizedNoted = true
+      table.patch(candidate, buildWikiConsentCard(candidate.question, { unauthorizedNote: true }))
+    })
+    if (entry === undefined) return
+    const decision = (event.action.value as { decision?: unknown } | undefined)?.decision
+    if (decision === 'allow') this.settle(table, entry, 'allowed', 'allowed')
+    else if (decision === 'deny') this.settle(table, entry, 'denied', 'denied')
+  }
+
+  /** Withdraw every pending card and forget every read consent (shutdown). */
+  dispose(): void {
+    const table = this.table?.entries
+    table?.withdrawAll(entry => this.settle(table, entry, 'cancelled', 'cancelled'))
+    this.table = undefined
+    this.readGrants.clear()
+  }
+
+  /** Pending consent count (diagnostics/tests). */
+  pendingCount(): number {
+    return this.table?.entries.count() ?? 0
+  }
+
+  private tableFor(channel: FeishuChannel): PendingCardTable<Pending> {
+    if (this.table?.channel !== channel) {
+      this.table = { channel, entries: new PendingCardTable<Pending>(channel, this.deps.onError) }
+    }
+    return this.table.entries
+  }
+
+  private settle(
+    table: PendingCardTable<Pending>,
+    entry: Pending,
+    outcome: WikiConsentOutcome,
+    cardState?: WikiConsentCardState,
+  ): void {
+    const closed = table.close(entry, () => {
+      if (cardState !== undefined) table.patch(entry, buildWikiConsentSettledCard(entry.question, cardState))
+    })
+    if (closed) entry.resolve(outcome)
+  }
+}

package/src/feishu/wiki/links.ts

@@ -0,0 +1,122 @@
+/**
+ * Feishu wiki (知识库) link parsing: the `wikiRoots` allow-list entries and
+ * the document references the model passes to the wiki tools.
+ *
+ * Pure module: no I/O. Hosts are not checked because tenants use their own
+ * subdomains (`<tenant>.feishu.cn`) and the API never uses the link host.
+ *
+ * @module dsh-channels/feishu/wiki/links
+ */
+
+/** Feishu wiki space id: decimal digits. */
+const SPACE_ID_PATTERN = /^\d{1,32}$/u
+
+/** Feishu wiki node / docx token: letters and digits. */
+const TOKEN_PATTERN = /^[A-Za-z0-9]{8,64}$/u
+
+/** One configured `wikiRoots` entry. */
+export type WikiRoot =
+  | {
+    /** A whole wiki space (`/wiki/space/<space_id>`). */
+    readonly kind: 'space'
+    readonly spaceId: string
+    /** The link as configured. */
+    readonly link: string
+  }
+  | {
+    /** One wiki node and every node below it (`/wiki/<node_token>`). */
+    readonly kind: 'node'
+    readonly nodeToken: string
+    /** The link as configured. */
+    readonly link: string
+  }
+
+/** Why a `wikiRoots` entry was rejected. */
+export type WikiRootLinkError =
+  | 'not-a-url'
+  | 'not-https'
+  | 'not-a-wiki-link'
+
+/** Readable reasons for {@link WikiRootLinkError}. */
+export const WIKI_ROOT_LINK_ERRORS: Readonly<Record<WikiRootLinkError, string>> = {
+  'not-a-url': '不是有效的链接',
+  'not-https': '必须是 https 链接',
+  'not-a-wiki-link': '只支持知识空间链接 https://<租户>.feishu.cn/wiki/space/<space_id> 或节点链接 https://<租户>.feishu.cn/wiki/<node_token>',
+}
+
+/**
+ * Parse one `wikiRoots` entry.
+ *
+ * @param link Link as configured (surrounding whitespace is ignored).
+ * @returns The root, or the reason it is invalid.
+ */
+export function parseWikiRootLink(link: string): { ok: true; root: WikiRoot } | { ok: false; error: WikiRootLinkError } {
+  const trimmed = link.trim()
+  let url: URL
+  try {
+    url = new URL(trimmed)
+  } catch {
+    // Unparseable input: reported as a configuration error below.
+    return { ok: false, error: 'not-a-url' }
+  }
+  if (url.protocol !== 'https:') return { ok: false, error: 'not-https' }
+  const segments = url.pathname.split('/').filter(segment => segment !== '')
+  if (segments[0] !== 'wiki') return { ok: false, error: 'not-a-wiki-link' }
+  if (segments.length === 3 && segments[1] === 'space' && SPACE_ID_PATTERN.test(segments[2]!)) {
+    return { ok: true, root: { kind: 'space', spaceId: segments[2]!, link: trimmed } }
+  }
+  if (segments.length === 2 && segments[1] !== 'space' && TOKEN_PATTERN.test(segments[1]!)) {
+    return { ok: true, root: { kind: 'node', nodeToken: segments[1]!, link: trimmed } }
+  }
+  return { ok: false, error: 'not-a-wiki-link' }
+}
+
+/**
+ * Parse every configured root. Callers validate the config first, so an
+ * invalid entry here is a programming error.
+ *
+ * @param links Validated `wikiRoots` entries.
+ * @returns The parsed roots, in configuration order.
+ */
+export function parseWikiRoots(links: readonly string[]): WikiRoot[] {
+  return links.map((link) => {
+    const parsed = parseWikiRootLink(link)
+    if (!parsed.ok) throw new Error(`dsh-channels: invalid wikiRoots entry ${link}: ${WIKI_ROOT_LINK_ERRORS[parsed.error]}`)
+    return parsed.root
+  })
+}
+
+/** A document or node the model names: a wiki node, a docx, or a whole space. */
+export type WikiRef =
+  | { readonly kind: 'node'; readonly token: string }
+  | { readonly kind: 'docx'; readonly token: string }
+  | { readonly kind: 'space'; readonly spaceId: string }
+
+/**
+ * Parse a model-supplied reference: a wiki node link, a docx link, a space
+ * link, or a bare node token.
+ *
+ * @param input Raw tool argument.
+ * @returns The reference, or `undefined` when it names nothing recognizable.
+ */
+export function parseWikiRef(input: string): WikiRef | undefined {
+  const trimmed = input.trim()
+  if (TOKEN_PATTERN.test(trimmed)) return { kind: 'node', token: trimmed }
+  let url: URL
+  try {
+    url = new URL(trimmed)
+  } catch {
+    // Neither a token nor a URL.
+    return undefined
+  }
+  if (url.protocol !== 'https:') return undefined
+  const segments = url.pathname.split('/').filter(segment => segment !== '')
+  if (segments[0] === 'wiki' && segments.length === 3 && segments[1] === 'space' && SPACE_ID_PATTERN.test(segments[2]!)) {
+    return { kind: 'space', spaceId: segments[2]! }
+  }
+  if (segments.length === 2 && TOKEN_PATTERN.test(segments[1]!)) {
+    if (segments[0] === 'wiki' && segments[1] !== 'space') return { kind: 'node', token: segments[1]! }
+    if (segments[0] === 'docx') return { kind: 'docx', token: segments[1]! }
+  }
+  return undefined
+}