@ljwei-stak/dsh-model-route-bot 0.66.3 → 0.67.0

package/packages/orchestration/src/team-tool-contract.mjs

@@ -0,0 +1,284 @@
+/**
+ * The ONE description of the four teammate-coordination tools.
+ *
+ * The SDK registration (team-sdk-tools.mjs) and the native MCP handler factory
+ * (native-team-tools.mjs) both read this module, so a tool name, a description, a
+ * parameter or an argument projection cannot drift between the two doors: what the
+ * model is told and what the coordination service is actually called with are the
+ * same facts. This is the data-tool-contract.mjs pattern applied to the team family.
+ *
+ * Authority stays outside this file. The service that executes a call
+ * (createTeamCoordination in team-bridge.mjs) resolves the calling Bot, the roster,
+ * the targets, the lineage and the work-thread identity from committed Host state —
+ * never from these arguments. `parseTeamToolArgs` refuses every key an entry does not
+ * declare, so a model that tries to smuggle a `botId`, an `owner`, a route, a session
+ * or a credential through the arguments is stopped here, before any service is
+ * reached; and the projection below only ever forwards business content.
+ *
+ * Two schemas describe the same contract on purpose:
+ *  - `parameters` is the dsh-tools author map the installed SDK compiles (arrays use
+ *    the SDK's own `{ type:'array', items:{...} }` node — the same node the vendor
+ *    browser/goals tools already use);
+ *  - `inputSchema` is a real MCP JSON Schema object with `additionalProperties:false`,
+ *    so a native client is told the truth — there is no authority key to pass.
+ *
+ * This contract is upstream-coordinate_bots-shaped but deliberately narrower, and the
+ * narrowing is recorded rather than hidden: no `group_id`/rooms, no `title`/
+ * `in_my_folder`, no `answers` (question routing), no `reason` chip, and
+ * `assignment_status` exposes no `wait_ms` long-poll (a Bot must not hold a turn, and
+ * a long-poll surface would need an owner-shaped endpoint). Those are phased gaps,
+ * not promises.
+ */
+
+/** JSON argument bytes one team call may carry; the same bound the native tools use. */
+export const MAX_ARGS_BYTES = 128_000
+
+/** Bounds, chosen to match upstream and the product's own turn-input bound. */
+export const MAX_TARGETS = 4
+export const MAX_MESSAGE_CHARS = 4000
+export const MAX_DONE_WHEN_CHARS = 1000
+export const MAX_REQUEST_KEY_CHARS = 128
+export const MAX_REASON_CHARS = 200
+
+/** Assignment modes. */
+export const MODE_WORK = 'work'
+export const MODE_CONSULT = 'consult'
+export const MODE_NOTICE = 'notice'
+export const TEAM_MODES = Object.freeze([MODE_WORK, MODE_CONSULT, MODE_NOTICE])
+
+/** Sender reply semantics. */
+export const REPLY_RESUME = 'resume'
+export const REPLY_NONE = 'none'
+export const TEAM_REPLIES = Object.freeze([REPLY_RESUME, REPLY_NONE])
+
+/** Durable assignment states (coherent with `outcome`, never overlapping it). */
+export const STATE_QUEUED = 'queued'
+export const STATE_ADMITTING = 'admitting'
+export const STATE_RUNNING = 'running'
+export const STATE_WAITING = 'waiting'
+export const STATE_SETTLED = 'settled'
+export const STATE_CANCELLED = 'cancelled'
+export const STATE_UNKNOWN = 'unknown'
+export const TEAM_STATES = Object.freeze([STATE_QUEUED, STATE_ADMITTING, STATE_RUNNING, STATE_WAITING, STATE_SETTLED, STATE_CANCELLED, STATE_UNKNOWN])
+/** States a reader treats as "this assignment will not change on its own". */
+export const TEAM_TERMINAL_STATES = Object.freeze([STATE_SETTLED, STATE_CANCELLED, STATE_UNKNOWN])
+
+/** Outcomes, only meaningful once an assignment is terminal. */
+export const OUTCOME_SUCCEEDED = 'succeeded'
+export const OUTCOME_FAILED = 'failed'
+export const OUTCOME_CANCELLED = 'cancelled'
+export const OUTCOME_UNKNOWN = 'unknown'
+export const TEAM_OUTCOMES = Object.freeze([OUTCOME_SUCCEEDED, OUTCOME_FAILED, OUTCOME_CANCELLED, OUTCOME_UNKNOWN])
+
+/** Result-return / sender-resume sub-state: at-most-one automated attempt. */
+export const RESUME_NONE = 'none'
+export const RESUME_WAITING = 'waiting'
+export const RESUME_SENDING = 'sending'
+export const RESUME_DELIVERED = 'delivered'
+export const RESUME_UNCERTAIN = 'uncertain'
+export const TEAM_RESUME_STATES = Object.freeze([RESUME_NONE, RESUME_WAITING, RESUME_SENDING, RESUME_DELIVERED, RESUME_UNCERTAIN])
+
+/** Thread references. `standing`/`new` are keywords; anything else is a thread id. */
+export const THREAD_STANDING = 'standing'
+export const THREAD_NEW = 'new'
+const THREAD_ID = /^[A-Za-z0-9_-]{1,128}$/
+
+/** Coded refusals and observations, so a model and an owner read the same reason. */
+export const TEAM_CODES = Object.freeze({
+  INVALID_ARGS: 'TEAM_INVALID_ARGS',
+  CALLER_NOT_COMMITTED: 'TEAM_CALLER_NOT_COMMITTED',
+  CALLER_NOT_AUTHORIZED: 'TEAM_CALLER_NOT_AUTHORIZED',
+  TARGET_NOT_COMMITTED: 'TEAM_TARGET_NOT_COMMITTED',
+  SELF_TARGET: 'TEAM_SELF_TARGET',
+  DUPLICATE: 'TEAM_DUPLICATE',
+  REQUEST_CONFLICT: 'TEAM_REQUEST_CONFLICT',
+  REWORK_NOT_TERMINAL: 'TEAM_REWORK_NOT_TERMINAL',
+  CYCLE: 'TEAM_CYCLE',
+  TOO_DEEP: 'TEAM_TOO_DEEP',
+  FANOUT_LIMIT: 'TEAM_FANOUT_LIMIT',
+  THREAD_NOT_OWNED: 'TEAM_THREAD_NOT_OWNED',
+  TARGET_BUSY: 'TEAM_TARGET_BUSY',
+  ACCESS_CHANGED: 'TEAM_ACCESS_CHANGED',
+  ASSIGNMENT_NOT_FOUND: 'TEAM_ASSIGNMENT_NOT_FOUND',
+  OUTCOME_UNKNOWN: 'TEAM_OUTCOME_UNKNOWN',
+})
+
+const objectSchema = (properties, required = []) => Object.freeze({
+  type: 'object',
+  properties: Object.freeze(properties),
+  required: Object.freeze(required),
+  additionalProperties: false,
+})
+
+const stringProp = description => ({ type: 'string', description })
+const boundedStringProp = (description, max) => ({ type: 'string', description: `${description}（最多 ${max} 字）`, maxLength: max })
+
+/** The SDK author map for `bot_ids`: a bounded, unique array of teammate ids. */
+const BOT_IDS_SDK = Object.freeze({
+  type: 'array',
+  minItems: 1, maxItems: MAX_TARGETS, uniqueItems: true,
+  items: { type: 'string', description: 'A teammate id exactly as list_bots prints it. 1–4 distinct teammates.' },
+  required: true,
+  description: 'The teammates to send to, by id from list_bots. 1–4 distinct ids; never yourself.',
+})
+
+const inputSchemaFor = parameters => {
+  const properties = {}
+  for (const [key, spec] of Object.entries(parameters)) {
+    if (spec.type === 'array') {
+      properties[key] = Object.freeze({
+        type: 'array',
+        items: Object.freeze({ type: spec.items.type, ...(spec.items.description ? { description: spec.items.description } : {}) }),
+        ...(spec.description ? { description: spec.description } : {}),
+        ...(spec.minItems !== undefined ? { minItems: spec.minItems } : {}),
+        ...(spec.maxItems !== undefined ? { maxItems: spec.maxItems } : {}),
+        ...(spec.uniqueItems !== undefined ? { uniqueItems: spec.uniqueItems } : {}),
+      })
+      continue
+    }
+    const schema = { type: spec.type }
+    if (spec.enum) schema.enum = spec.enum
+    if (spec.maxLength !== undefined) schema.maxLength = spec.maxLength
+    if (spec.minLength !== undefined) schema.minLength = spec.minLength
+    schema.description = spec.description
+    properties[key] = Object.freeze(schema)
+  }
+  const required = Object.entries(parameters).filter(([, spec]) => spec.required === true).map(([key]) => key)
+  return objectSchema(properties, required)
+}
+
+const defineEntry = ({ name, description, parameters, method }) => Object.freeze({
+  name,
+  description,
+  parameters: Object.freeze(parameters),
+  inputSchema: inputSchemaFor(parameters),
+  capability: 'tool/team',
+  method,
+})
+
+const ENTRIES = Object.freeze([
+  defineEntry({
+    name: 'coordinate_bots',
+    method: 'coordinateBots',
+    description: [
+      'The one way to hand work to teammates: ask 1–4 existing teammates a question or assign them concrete work.',
+      'They see only what you send and run under their OWN model, tools, permissions and funding — never yours.',
+      'thread "standing" (default) reuses this conversation\'s one work thread with each teammate; "new" opens a fresh thread with its own history; a thread id picks one you opened.',
+      'consult true asks a question they answer from what they know, acting on nothing; reply "none" is a one-way notice nothing comes back from.',
+      'Confirmed results resume this original conversation when it is still active and access still permits it. Interrupted or ambiguous delivery is surfaced without automatic resend. After sending END your turn; assignment_status is refused in the same turn.',
+      'Never target yourself. On return, verify the requested outcome and request concrete corrections with rework true before giving one final answer. Never repeat a refused call unchanged.',
+    ].join(' '),
+    parameters: {
+      bot_ids: BOT_IDS_SDK,
+      message: { type: 'string', required: true, minLength: 1, maxLength: MAX_MESSAGE_CHARS, description: 'The self-contained question or task. Exact paths, constraints and what must be verified.' },
+      thread: { type: 'string', description: '"standing" (default), "new", or a thread id you opened. Results return to this conversation.' },
+      reply: { type: 'string', enum: [REPLY_RESUME, REPLY_NONE], description: '"resume" (default): the result resumes you. "none": a one-way notice, nothing comes back.' },
+      consult: { type: 'boolean', description: 'True for a question the teammate answers from what it knows, acting on nothing. Omit for work.' },
+      rework: { type: 'boolean', description: 'True only to send concrete work again to a teammate whose request already finished or failed: a correction, re-check or retry.' },
+      done_when: { type: 'string', maxLength: MAX_DONE_WHEN_CHARS, description: 'What must be true for this to count as done; the teammate is held to it.' },
+      request_key: { type: 'string', maxLength: MAX_REQUEST_KEY_CHARS, description: 'Optional idempotency name: a repeat with the same content is not sent again but returns the first receipt; a repeat with other content is refused.' },
+    },
+  }),
+  defineEntry({
+    name: 'assignment_status',
+    method: 'assignmentStatus',
+    description: [
+      'Read-only: one assignment\'s state, outcome and result (give its id from a coordinate_bots receipt or a list_threads row),',
+      'or, with no id, everything this conversation still waits on. A result resumes you on its own, so you never need this to wait:',
+      'use it in a later turn when the person asks how a hand-off is going. It starts nothing and changes nothing.',
+    ].join(' '),
+    parameters: {
+      id: { type: 'string', description: 'The assignment id. Omit to list every outstanding assignment of this conversation.' },
+    },
+  }),
+  defineEntry({
+    name: 'list_bots',
+    method: 'listBots',
+    description: 'List every OTHER teammate you can contact with its Main flag, committed model and current runtime mode. Call this to discover exact teammate ids before coordinate_bots.',
+    parameters: {},
+  }),
+  defineEntry({
+    name: 'list_threads',
+    method: 'listThreads',
+    description: 'Read-only: your own work threads and the threads you opened on teammates, newest first, each with its teammate, title, state and delegation id. This is a read: it starts nothing and changes nothing.',
+    parameters: {},
+  }),
+])
+
+if (ENTRIES.length !== 4 || ENTRIES.some((entry, index) => entry.name !== ['coordinate_bots', 'assignment_status', 'list_bots', 'list_threads'][index])) {
+  throw new Error('TEAM_TOOL_ENTRIES_DIVERGED')
+}
+
+export const TEAM_TOOL_NAMES = Object.freeze(ENTRIES.map(entry => entry.name))
+export const TEAM_TOOL_ENTRIES = ENTRIES
+export const teamToolEntry = name => ENTRIES.find(entry => entry.name === name) ?? null
+
+const invalid = key => { throw Object.assign(new Error(`${TEAM_CODES.INVALID_ARGS}:${key}`), { code: TEAM_CODES.INVALID_ARGS, field: key }) }
+const isPlainObject = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+  && Object.getPrototypeOf(value) === Object.prototype
+const typeOf = (type, value) => type === 'string' ? typeof value === 'string'
+  : type === 'boolean' ? typeof value === 'boolean'
+    : type === 'integer' ? Number.isSafeInteger(value)
+      : false
+
+/** A thread reference: the two keywords, or a bounded thread id. */
+export const threadReferenceOk = value => value === THREAD_STANDING || value === THREAD_NEW
+  || (typeof value === 'string' && THREAD_ID.test(value))
+
+/**
+ * Strictly validate one team call's arguments against the shared contract and return
+ * the SAME parsed object. Nothing is coerced and nothing is defaulted here: defaults
+ * belong to the service, which is the only place that knows them.
+ *
+ * Refused: a non-plain object, any key the entry does not declare (an authority key
+ * such as botId/owner, or any other key), a missing required key, a wrong type, a
+ * value outside an enum, a string past its maxLength, an unsafe integer, and a JSON
+ * payload larger than MAX_ARGS_BYTES.
+ */
+export function parseTeamToolArgs(name, args) {
+  const entry = teamToolEntry(name)
+  if (!entry) throw new TypeError(`unknown team tool: ${String(name)}`)
+  if (!isPlainObject(args)) invalid('args')
+  let bytes
+  try { bytes = Buffer.byteLength(JSON.stringify(args), 'utf8') } catch { invalid('args') }
+  if (bytes > MAX_ARGS_BYTES) invalid('args')
+  const { parameters } = entry
+  if (Object.keys(args).some(key => !Object.hasOwn(parameters, key))) invalid('args')
+  for (const [key, spec] of Object.entries(parameters)) if (spec.required === true && !Object.hasOwn(args, key)) invalid(key)
+  for (const [key, value] of Object.entries(args)) {
+    const schema = parameters[key]
+    if (schema.type === 'array') {
+      if (!Array.isArray(value)) invalid(key)
+      if (schema.minItems !== undefined && value.length < schema.minItems) invalid(key)
+      if (schema.maxItems !== undefined && value.length > schema.maxItems) invalid(key)
+      if (schema.uniqueItems === true && new Set(value).size !== value.length) invalid(key)
+      if (value.some(item => typeof item !== schema.items.type || !/^[A-Za-z0-9_-]{1,128}$/.test(item))) invalid(key)
+      continue
+    }
+    if (!typeOf(schema.type, value)) invalid(key)
+    if (schema.enum && !schema.enum.includes(value)) invalid(key)
+    if (schema.minLength !== undefined && value.length < schema.minLength) invalid(key)
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) invalid(key)
+    if (key === 'thread' && !threadReferenceOk(value)) invalid(key)
+  }
+  return args
+}
+
+/**
+ * Project one validated coordinate_bots call onto the business shape the service
+ * consumes. Only the declared business keys are forwarded; there is no botId, owner,
+ * route, session or credential to forward, because none was ever accepted.
+ */
+export function projectCoordinateArgs(args) {
+  const trimmed = String(args.message).replace(/\r\n?/g, '\n').trim()
+  return {
+    targets: args.bot_ids.map(id => String(id)),
+    message: trimmed,
+    thread: typeof args.thread === 'string' ? args.thread : THREAD_STANDING,
+    reply: args.reply === REPLY_NONE ? REPLY_NONE : REPLY_RESUME,
+    consult: args.consult === true,
+    rework: args.rework === true,
+    ...(typeof args.done_when === 'string' ? { doneWhen: args.done_when } : {}),
+    ...(typeof args.request_key === 'string' && args.request_key ? { requestKey: args.request_key.slice(0, MAX_REQUEST_KEY_CHARS) } : {}),
+  }
+}

package/packages/orchestration/src/ui-host-namespace.mjs

@@ -0,0 +1,23 @@
+import { randomBytes } from 'node:crypto'
+
+/** Public UI storage identity, persisted by the Host; never an authentication credential. */
+export function openUiHostNamespace({ Database, file }) {
+  const db = new Database(file)
+  let closed = false
+  try {
+    db.pragma('busy_timeout = 5000')
+    db.pragma('synchronous = FULL')
+    db.exec('CREATE TABLE IF NOT EXISTS product_ui_namespace (scope TEXT PRIMARY KEY, namespace TEXT NOT NULL)')
+    db.prepare('INSERT OR IGNORE INTO product_ui_namespace(scope,namespace) VALUES(?,?)').run('owner', `host-${randomBytes(8).toString('hex')}`)
+    const hostId = db.prepare('SELECT namespace FROM product_ui_namespace WHERE scope=?').get('owner')?.namespace
+    if (!/^host-[a-f0-9]{16}$/.test(hostId ?? '')) throw Object.assign(new Error('宿主界面存储标识无效，请核对插件状态。'), { code: 'UI_NAMESPACE_INVALID' })
+    return Object.freeze({
+      read(payload = {}) {
+        if (closed) throw Object.assign(new Error('宿主界面存储已关闭。'), { code: 'UI_NAMESPACE_CLOSED' })
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload) || Object.keys(payload).length) throw Object.assign(new Error('无效的界面标识请求。'), { code: 'INVALID_UI_NAMESPACE_REQUEST' })
+        return { schemaVersion: 1, hostId }
+      },
+      close() { if (!closed) { closed = true; db.close() } },
+    })
+  } catch (error) { db.close(); throw error }
+}

package/packages/orchestration/src/web-panel-actions.mjs

@@ -0,0 +1,103 @@
+// The owner-only product-channel surface for pinned web panels: what the panel
+// list reads, what a person may change, and the one probe that asks a page
+// whether it can be framed.
+//
+// Every entry here is a console operation, not a Bot capability. Nothing is
+// registered as a model tool, so a Bot cannot ask this Host to fetch a page, and
+// the caller's owner class comes from the authenticated channel context — a
+// payload that claims `kind: 'owner'` is data, and is ignored as such. The only
+// origin used is the one the channel reports as the client's embedding origin.
+//
+// A probe names a stored panel by id. The URL is the owner's own pin, never a
+// string a client hands over on the side, so there is no "fetch this address"
+// door here at all.
+
+import { checkFraming, PROBE_TIMEOUT_MS } from './web-panel-framing.mjs'
+import { probeUrlOf } from './web-panel-store.mjs'
+
+export const WEB_PANEL_ACTIONS = Object.freeze([
+  'webPanels.list', 'webPanels.probe', 'webPanels.save', 'webPanels.remove', 'webPanels.order',
+])
+
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+const plain = value => value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+const payloadOf = (payload, allowed) => {
+  if (!plain(payload) || Object.keys(payload).some(key => !allowed.includes(key))) fail('WEB_PANEL_INPUT')
+  return payload
+}
+const owner = context => { if (context?.kind !== 'owner') fail('REMOTE_OWNER_REQUIRED') }
+
+export function createWebPanelActions({ store, probe = checkFraming, now = Date.now, concurrency = 2, queue = 8, logger = () => {} }) {
+  if (!store || typeof store.save !== 'function' || typeof store.read !== 'function') throw new TypeError('WEB_PANEL_STORE_REQUIRED')
+  const limit = Number.isSafeInteger(concurrency) && concurrency > 0 ? concurrency : 2
+  const waiting = Number.isSafeInteger(queue) && queue >= 0 ? queue : 8
+  let active = 0
+  const pending = []
+
+  // Bounded by two gates: only `limit` probes run at once, and only `waiting`
+  // may wait behind them. A Host is not a scanner, and a panel that cannot get a
+  // slot says so instead of piling requests up behind a slow page.
+  const release = () => {
+    active--
+    const next = pending.shift()
+    if (next) { active++; next() }
+  }
+  const slot = work => new Promise((resolve, reject) => {
+    const start = () => { work().then(resolve, reject).finally(release) }
+    if (active < limit) { active++; start(); return }
+    if (pending.length >= waiting) { reject(Object.assign(new Error('WEB_PANEL_PROBE_BUSY'), { code: 'WEB_PANEL_PROBE_BUSY' })); return }
+    pending.push(start)
+  })
+
+  const list = () => {
+    const { revision, panels, limits } = store.read()
+    return { revision, panels, limits }
+  }
+
+  const provider = async () => {
+    const value = list()
+    // The read model's contract: a status and an items array, never a bare list.
+    return { status: 'available', items: value.panels, revision: value.revision, limits: value.limits }
+  }
+
+  const actions = {
+    'webPanels.list': (payload, context) => { owner(context); payloadOf(payload ?? {}, []); return list() },
+    'webPanels.save': (payload, context) => {
+      owner(context)
+      const request = payloadOf(payload, ['id', 'name', 'url', 'expectedRevision'])
+      const saved = store.save({ id: request.id ?? null, name: request.name, url: request.url,
+        expectedRevision: request.expectedRevision, embeddingOrigin: context.clientOrigin ?? '' })
+      // The readback is the store's own; this is the channel's confirmation that
+      // the row a client is about to be shown is the row that was written.
+      const after = store.read()
+      if (after.revision !== saved.revision || !after.panels.some(panel => panel.id === saved.panel.id
+        && panel.name === saved.panel.name && panel.url === saved.panel.url)) fail('WEB_PANEL_READBACK_MISMATCH')
+      return { revision: saved.revision, panel: saved.panel }
+    },
+    'webPanels.remove': (payload, context) => {
+      owner(context)
+      const request = payloadOf(payload, ['id', 'expectedRevision'])
+      return store.remove({ id: request.id, expectedRevision: request.expectedRevision })
+    },
+    'webPanels.order': (payload, context) => {
+      owner(context)
+      const request = payloadOf(payload, ['ids', 'expectedRevision'])
+      return store.order({ ids: request.ids, expectedRevision: request.expectedRevision })
+    },
+    'webPanels.probe': async (payload, context) => {
+      owner(context)
+      const request = payloadOf(payload, ['id'])
+      const panel = store.read().panels.find(entry => entry.id === request.id)
+      if (!panel) fail('WEB_PANEL_NOT_FOUND')
+      const started = now()
+      const result = await slot(() => probe(probeUrlOf(panel.url), context.clientOrigin ?? '',
+        { signal: context.signal, timeoutMs: PROBE_TIMEOUT_MS, maxBytes: 1, maxRedirects: 0 }))
+      // A URL's query is the owner's business and never a log line; the origin is
+      // enough to recognise the page in a diagnostic.
+      logger('web-panel-probe', { panelId: panel.id, host: result.host, framing: result.framing, reason: result.reason, ms: now() - started })
+      return { panelId: panel.id, framing: result.framing, reason: result.reason, host: result.host, checkedAt: now() }
+    },
+  }
+
+  return Object.freeze({ actions, provider, list })
+}

package/packages/orchestration/src/web-panel-framing.mjs

@@ -0,0 +1,227 @@
+// Whether a pinned page lets this app frame it, decided the way a browser
+// decides: HTML's X-Frame-Options processing and CSP Level 3's frame-ancestors.
+// Ported from the upstream product (OpenMausBot server/web-panel-framing.ts,
+// pinned 1bc4749aa8307d7d6998bf86de4ef6478460dd93) so a refusal reads the same
+// here as it does there.
+//
+// Chrome fires `load` on a frame it refused, and the parent page cannot tell
+// that frame from a working cross-origin one, so only the page's own headers say
+// why a pinned panel stays blank.
+//
+// Three deliberate differences from the upstream probe, all of them about scope
+// rather than verdict:
+//
+// 1. Loopback and private addresses are allowed. A pinned panel is very often the
+//    owner's own localhost dashboard, so the upstream "never from this computer
+//    or a private network" rule would refuse the product's most common page. The
+//    URL still comes only from an owner's explicit pin.
+// 2. The request carries no credentials of any kind: no cookie jar, no
+//    Authorization header, nothing from this Host's configuration. A redirect or
+//    an error answer may therefore be a sign-in page the owner's browser never
+//    gets, which is why those read as `unknown` rather than `blocked`.
+// 3. The answer is a verdict, never a page. No body is returned to a client and
+//    no HTML is executed on the Host, so a site cannot use the probe as an open
+//    proxy or as a way to run its markup here.
+//
+// `embeddingOrigin` is supplied by the Host channel from the real client origin
+// (the native shell's `dsh-app://app`, or the browser origin). It is used only to
+// evaluate frame-ancestors; it grants nothing.
+
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { isIP } from 'node:net'
+import { lookup as dnsLookup } from 'node:dns/promises'
+
+/** `unknown` whenever this cannot be sure. */
+export const FRAMING = Object.freeze(['allowed', 'blocked', 'unknown'])
+
+/** A closed vocabulary: the panel shows one of these, never a server's own words. */
+export const PROBE_REASONS = Object.freeze([
+  'invalid-url', 'unsupported-scheme', 'credentials-in-url', 'redirect', 'bad-status',
+  'unreachable', 'timeout', 'response-limit', 'aborted',
+])
+
+export const PROBE_TIMEOUT_MS = 8_000
+// Framing is decided by headers. One byte of body is enough to learn that a body
+// exists; the rest is never downloaded, so a hostile page cannot make the Host
+// pull megabytes to answer a yes/no question.
+export const PROBE_MAX_BYTES = 1
+// A redirect is not followed: it may lead to a sign-in page the owner's browser
+// never gets, and following it would turn the probe into a crawler.
+export const PROBE_MAX_REDIRECTS = 0
+
+const SCHEME_SOURCE = /^[a-z][a-z0-9+.-]*:$/
+const HOST_SOURCE = /^(?:([a-z][a-z0-9+.-]*):\/\/)?(\*|(?:\*\.)?[a-z0-9-]+(?:\.[a-z0-9-]+)*)(?::(\d+|\*))?(\/[^?#]*)?$/
+
+function headerItems(value) {
+  return (value === undefined ? [] : [value].flat()).flatMap(item => item.split(','))
+}
+
+/** An app on https may sit in a frame that only names http, as CSP lets a scheme upgrade. */
+function schemeMatches(scheme, app) {
+  return scheme === app.protocol || (scheme === 'http:' && app.protocol === 'https:')
+}
+
+function hostMatches(host, app) {
+  if (host === '*') return true
+  if (host.startsWith('*.')) return app.hostname.endsWith(host.slice(1))
+  return app.hostname === host
+}
+
+function sourceMatches(token, page, app) {
+  const source = token.toLowerCase()
+  if (source === '*') return true
+  if (source === "'self'") return app.origin === page.origin
+  if (source.startsWith("'")) return false
+  if (SCHEME_SOURCE.test(source)) return schemeMatches(source, app)
+  const parts = HOST_SOURCE.exec(source)
+  if (!parts) return null
+  const [, scheme, host, port, path] = parts
+  if (!schemeMatches(scheme ? `${scheme}:` : page.protocol, app)) return false
+  if (!hostMatches(host, app)) return false
+  const defaultPort = app.protocol === 'https:' ? '443' : '80'
+  const appPort = app.port || defaultPort
+  if (port === '80' && appPort === '443') return null
+  if (port !== '*' && (port ?? defaultPort) !== appPort) return false
+  return path === undefined || path === '/' ? true : null
+}
+
+function ancestorsAllow(sources, page, app) {
+  let unsure = false
+  for (const source of sources) {
+    const matches = sourceMatches(source, page, app)
+    if (matches) return true
+    if (matches === null) unsure = true
+  }
+  return unsure ? null : false
+}
+
+/** The source list of each enforced policy's first frame-ancestors directive. */
+function frameAncestorLists(value) {
+  const lists = []
+  for (const policy of headerItems(value)) {
+    const directive = policy.split(';').map(part => part.trim().split(/\s+/)).find(([name]) => name.toLowerCase() === 'frame-ancestors')
+    if (directive) lists.push(directive.slice(1))
+  }
+  return lists
+}
+
+function xFrameOptionsAllow(value, page, app) {
+  const options = new Set(headerItems(value).map(item => item.trim().toLowerCase()))
+  if (options.size > 1) return !['deny', 'allowall', 'sameorigin'].some(option => options.has(option))
+  if (options.has('deny')) return false
+  return !options.has('sameorigin') || page.origin === app.origin
+}
+
+export function framingOf(headers, pageUrl, embeddingOrigin) {
+  let page, app
+  try {
+    page = new URL(pageUrl)
+    app = new URL(embeddingOrigin)
+  } catch {
+    return 'unknown'
+  }
+  const lists = frameAncestorLists(headers['content-security-policy'])
+  if (lists.length === 0) return xFrameOptionsAllow(headers['x-frame-options'], page, app) ? 'allowed' : 'blocked'
+  let unsure = false
+  for (const sources of lists) {
+    const allows = ancestorsAllow(sources, page, app)
+    if (allows === false) return 'blocked'
+    if (allows === null) unsure = true
+  }
+  return unsure ? 'unknown' : 'allowed'
+}
+
+/** The verdict for a page, or the reason it cannot be reached. Never a message, never a path. */
+export function framingResult(framing, reason = null, host = '') {
+  return Object.freeze({ framing: FRAMING.includes(framing) ? framing : 'unknown', reason: reason ?? null, host })
+}
+
+function requestOnce(url, address, signal, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const pinned = (_host, options, callback) => {
+      if (options.all) callback(null, [address])
+      else callback(null, address.address, address.family)
+    }
+    const send = url.protocol === 'https:' ? httpsRequest : httpRequest
+    const req = send(url, {
+      agent: false, signal, lookup: pinned,
+      // Nothing that identifies this Host: no cookie, no authorization, no
+      // referer. A page that behaves differently for a signed-in browser is
+      // exactly the case this probe must not speak for.
+      headers: { 'user-agent': 'dsh-model-router-web-panel-probe', accept: 'text/html,text/plain;q=0.9,*/*;q=0.1' },
+    }, response => {
+      const status = response.statusCode ?? 0
+      const { headers } = response
+      if (status < 200 || status >= 300) {
+        response.destroy()
+        resolve({ status, location: headers.location, headers })
+        return
+      }
+      let size = 0
+      response.on('data', chunk => {
+        size += chunk.length
+        if (size >= maxBytes) { response.destroy(); resolve({ status, headers, truncated: true }) }
+      })
+      response.on('end', () => resolve({ status, headers, truncated: false }))
+      response.on('error', () => resolve({ status, headers, truncated: true }))
+    })
+    req.on('error', reject)
+    req.end()
+  })
+}
+
+async function addressesFor(host, lookup) {
+  const literal = isIP(host)
+  if (literal) return [{ address: host, family: literal }]
+  const found = typeof lookup === 'function' ? await lookup(host) : await dnsLookup(host, { all: true })
+  return Array.isArray(found) ? found.filter(entry => entry && typeof entry.address === 'string') : []
+}
+
+function abortableLookup(host, lookup, signal) {
+  return new Promise((resolve, reject) => {
+    const done = (settle, value) => { signal.removeEventListener('abort', abort); settle(value) }
+    const abort = () => done(reject, signal.reason)
+    if (signal.aborted) { reject(signal.reason); return }
+    signal.addEventListener('abort', abort, { once: true })
+    addressesFor(host, lookup).then(value => done(resolve, value), error => done(reject, error))
+  })
+}
+
+/**
+ * Read one page's headers and decide. `options.lookup` exists so a test can point
+ * a name at loopback without touching the machine's resolver.
+ */
+export async function checkFraming(rawUrl, embeddingOrigin, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : PROBE_TIMEOUT_MS
+  const maxBytes = Number.isSafeInteger(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : PROBE_MAX_BYTES
+  const maxRedirects = Number.isSafeInteger(options.maxRedirects) && options.maxRedirects >= 0 ? options.maxRedirects : PROBE_MAX_REDIRECTS
+  const signal = AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(options.signal ? [options.signal] : [])])
+  let url
+  try { url = new URL(rawUrl) } catch { return framingResult('unknown', 'invalid-url') }
+  const host = url.host
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return framingResult('unknown', 'unsupported-scheme', host)
+  if (url.username || url.password) return framingResult('unknown', 'credentials-in-url', host)
+  try {
+    for (let hop = 0; ; hop++) {
+      signal.throwIfAborted()
+      const bare = url.hostname.replace(/^\[|\]$/g, '')
+      const addresses = await abortableLookup(bare, options.lookup, signal)
+      signal.throwIfAborted()
+      if (!addresses.length) return framingResult('unknown', 'unreachable', url.host)
+      const answer = await requestOnce(url, addresses[0], signal, maxBytes)
+      if (answer.status >= 300 && answer.status < 400) {
+        if (!answer.location || hop >= maxRedirects) return framingResult('unknown', 'redirect', url.host)
+        url = new URL(answer.location, url)
+        continue
+      }
+      if (answer.status < 200 || answer.status >= 300) return framingResult('unknown', 'bad-status', url.host)
+      return framingResult(framingOf(answer.headers, url.href, embeddingOrigin), null, url.host)
+    }
+  } catch {
+    // A cancelled probe is the caller's own business; a deadline is the page's.
+    if (options.signal?.aborted) return framingResult('unknown', 'aborted', url.host)
+    if (signal.aborted) return framingResult('unknown', 'timeout', url.host)
+    return framingResult('unknown', 'unreachable', url.host)
+  }
+}