@fg-lab/amadeus-qq 0.0.0-stage → 1.2.1

package/src/owner-workspace.js

@@ -0,0 +1,394 @@
+// Restricted Owner workspace: the only sanctioned file surface for the Owner
+// Agent. It never exposes a shell, never accepts absolute paths, and confines
+// every operation to one operator-configured directory. Writes require a real
+// Host approval ask for that single call; a missing approval service denies.
+
+import { randomUUID } from 'node:crypto'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+export const OWNER_WORKSPACE_TOOL = 'qq_owner_workspace'
+export const OWNER_WORKSPACE_CAPABILITY = 'qq.owner.workspace'
+export const DEFAULT_MAX_BYTES = 64 * 1024
+export const MAX_ALLOWED_BYTES = 256 * 1024
+export const MAX_PATH_CHARS = 512
+
+const MAX_SEGMENTS = 32
+const DENIED_SEGMENTS = new Set([
+  '.credentials.yaml', '.credentials', 'credentials.yaml', 'credentials.yml', 'auth.json',
+])
+
+function ownerError(code, message) {
+  const error = new Error(message)
+  error.code = code
+  return error
+}
+
+const PATH_INVALID = () => ownerError('QQ_OWNER_WORKSPACE_PATH_INVALID', 'owner workspace path is invalid')
+const PATH_OUTSIDE = () => ownerError('QQ_OWNER_WORKSPACE_PATH_OUTSIDE', 'owner workspace path escapes the configured directory')
+const SYMLINK = () => ownerError('QQ_OWNER_WORKSPACE_PATH_UNSAFE', 'owner workspace path uses a symbolic link')
+const TOO_LARGE = () => ownerError('QQ_OWNER_WORKSPACE_TOO_LARGE', 'owner workspace content exceeds the configured limit')
+const NOT_UTF8 = () => ownerError('QQ_OWNER_WORKSPACE_NOT_UTF8', 'owner workspace file is not UTF-8 text')
+const UNAVAILABLE = () => ownerError('QQ_OWNER_WORKSPACE_UNAVAILABLE', 'owner workspace is not configured')
+const REVOKED = () => ownerError('QQ_OWNER_WORKSPACE_REVOKED', 'owner workspace authorization is no longer valid')
+const APPROVAL_UNAVAILABLE = () => ownerError('QQ_OWNER_WORKSPACE_APPROVAL_UNAVAILABLE', 'owner workspace write approval is unavailable')
+const UNAPPROVED = () => ownerError('QQ_OWNER_WORKSPACE_UNAPPROVED', 'owner workspace write was not approved')
+
+/** Parse the preset-row owner workspace knobs. Invalid values fail activation. */
+export function resolveOwnerWorkspacePolicy(config = {}) {
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    throw new TypeError('owner workspace config must be an object')
+  }
+  const root = config.ownerWorkspaceRoot === undefined ? '' : config.ownerWorkspaceRoot
+  if (typeof root !== 'string') throw new TypeError('ownerWorkspaceRoot must be a string')
+  const allowWrite = config.ownerWorkspaceWrites === undefined ? false : config.ownerWorkspaceWrites
+  if (typeof allowWrite !== 'boolean') throw new TypeError('ownerWorkspaceWrites must be a boolean')
+  const maxBytes = config.ownerWorkspaceMaxBytes === undefined ? DEFAULT_MAX_BYTES : config.ownerWorkspaceMaxBytes
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_ALLOWED_BYTES) {
+    throw new TypeError('ownerWorkspaceMaxBytes must be an integer from 1 to ' + MAX_ALLOWED_BYTES)
+  }
+  if (root !== '' && (!path.isAbsolute(root) || path.parse(root).root === root)) {
+    throw new TypeError('ownerWorkspaceRoot must be an absolute non-root directory')
+  }
+  return Object.freeze({ root: root === '' ? '' : path.resolve(root), allowWrite, maxBytes })
+}
+
+/** True for one path segment that must never be reachable through this surface. */
+export function isDeniedOwnerSegment(segment) {
+  if (typeof segment !== 'string' || segment === '' || segment === '.' || segment === '..') return true
+  if (segment.includes('\u0000') || segment.includes(':') || segment.includes('/') || segment.includes('\\')) return true
+  if (segment.startsWith('.')) return true
+  return DENIED_SEGMENTS.has(segment.toLowerCase())
+}
+
+/** Split and validate a model-supplied relative path into safe segments. */
+export function ownerPathSegments(requested) {
+  if (typeof requested !== 'string') throw PATH_INVALID()
+  if (requested.length === 0 || requested.length > MAX_PATH_CHARS) throw PATH_INVALID()
+  if (requested.includes('\u0000')) throw PATH_INVALID()
+  if (path.isAbsolute(requested) || /^[A-Za-z]:/.test(requested) || /^[\\/]{2}/.test(requested)) throw PATH_INVALID()
+  const segments = requested.split(/[\\/]/)
+  if (segments.length === 0 || segments.length > MAX_SEGMENTS) throw PATH_INVALID()
+  if (segments.some(isDeniedOwnerSegment)) throw PATH_INVALID()
+  return segments
+}
+
+async function resolveRoot(root) {
+  if (typeof root !== 'string' || root === '') throw UNAVAILABLE()
+  let real
+  try {
+    real = await fs.realpath(root)
+  } catch {
+    throw UNAVAILABLE()
+  }
+  const stat = await fs.lstat(real)
+  if (!stat.isDirectory()) throw UNAVAILABLE()
+  if (path.parse(real).root === real) throw UNAVAILABLE()
+  return real
+}
+
+function contained(root, target) {
+  if (target === root) return true
+  const relative = path.relative(root, target)
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+}
+
+/**
+ * Resolve one relative owner path. Existing components must not be symlinks,
+ * and the final target must canonicalize inside the configured root.
+ */
+export async function resolveOwnerWorkspacePath(root, requested) {
+  const segments = ownerPathSegments(requested)
+  const rootReal = await resolveRoot(root)
+  let cursor = rootReal
+  for (let index = 0; index < segments.length; index += 1) {
+    cursor = path.join(cursor, segments[index])
+    let stat
+    try {
+      stat = await fs.lstat(cursor)
+    } catch (error) {
+      if (error?.code === 'ENOENT') break
+      throw PATH_INVALID()
+    }
+    if (stat.isSymbolicLink()) throw SYMLINK()
+    if (index < segments.length - 1 && !stat.isDirectory()) throw PATH_INVALID()
+  }
+  let absolute = path.join(rootReal, ...segments)
+  let exists = false
+  let targetReal = absolute
+  try {
+    const stat = await fs.lstat(absolute)
+    if (stat.isSymbolicLink()) throw SYMLINK()
+    exists = true
+    targetReal = await fs.realpath(absolute)
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error?.code ? error : PATH_INVALID()
+  }
+  if (exists && !contained(rootReal, targetReal)) throw PATH_OUTSIDE()
+  if (!exists) {
+    const parent = path.dirname(absolute)
+    let parentReal
+    try {
+      parentReal = await fs.realpath(parent)
+    } catch {
+      throw PATH_INVALID()
+    }
+    if (!contained(rootReal, parentReal)) throw PATH_OUTSIDE()
+  }
+  return { absolute, rootReal, relative: segments.join('/'), exists }
+}
+
+/** Read one UTF-8 file from the owner workspace. No approval is needed to read. */
+export async function readOwnerWorkspaceFile({ root, requested, maxBytes = DEFAULT_MAX_BYTES, authorize, signal }) {
+  if (typeof authorize === 'function') await assertAuthorized(authorize, signal)
+  const resolved = await resolveOwnerWorkspacePath(root, requested)
+  if (!resolved.exists) throw PATH_INVALID()
+  let handle
+  try {
+    handle = await fs.open(resolved.absolute, 'r')
+  } catch {
+    throw PATH_INVALID()
+  }
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile()) throw PATH_INVALID()
+    if (stat.size > maxBytes) throw TOO_LARGE()
+    const bytes = await handle.readFile()
+    if (bytes.length > maxBytes) throw TOO_LARGE()
+    const text = bytes.toString('utf8')
+    if (!Buffer.from(text, 'utf8').equals(bytes)) throw NOT_UTF8()
+    // Revocation may land while the read is in flight; recheck before the body
+    // is handed to the model.
+    if (typeof authorize === 'function') await assertAuthorized(authorize, signal)
+    return { name: path.basename(resolved.absolute), bytes: bytes.length, text }
+  } finally {
+    await handle.close().catch(() => {})
+  }
+}
+
+function assertNotAborted(signal) {
+  if (signal?.aborted) throw REVOKED()
+}
+
+async function assertAuthorized(authorize, signal) {
+  assertNotAborted(signal)
+  if (typeof authorize !== 'function' || (await authorize()) !== true) throw REVOKED()
+}
+
+/**
+ * Ask the Host approval service for this one write. The request carries only
+ * the tool name and a fixed reason; no path, content, credential or URL.
+ */
+export async function requestOwnerWriteApproval({ approval, agent, callId, signal }) {
+  if (!approval || typeof approval.request !== 'function') throw APPROVAL_UNAVAILABLE()
+  let outcome
+  try {
+    outcome = await approval.request({
+      agent,
+      toolName: OWNER_WORKSPACE_TOOL,
+      callId,
+      reason: 'Owner workspace write requires approval',
+      signal,
+    })
+  } catch {
+    throw APPROVAL_UNAVAILABLE()
+  }
+  if (outcome !== 'allowed-once') throw UNAPPROVED()
+}
+
+/**
+ * Write one UTF-8 file inside the owner workspace. The write is temp-then-rename
+ * so a failure leaves any existing file untouched; authorization and the abort
+ * signal are rechecked after approval and immediately before the commit.
+ */
+export async function writeOwnerWorkspaceFile({
+  root, requested, content, maxBytes = DEFAULT_MAX_BYTES,
+  authorize, approve, signal,
+}) {
+  if (typeof content !== 'string') throw PATH_INVALID()
+  const bytes = Buffer.from(content, 'utf8')
+  if (bytes.length > maxBytes) throw TOO_LARGE()
+  await assertAuthorized(authorize, signal)
+  const resolved = await resolveOwnerWorkspacePath(root, requested)
+  assertNotAborted(signal)
+  if (typeof approve !== 'function') throw APPROVAL_UNAVAILABLE()
+  await approve()
+  await assertAuthorized(authorize, signal)
+  assertNotAborted(signal)
+  // Re-resolve after approval so a replacement during the ask cannot redirect us.
+  const confirmed = await resolveOwnerWorkspacePath(root, requested)
+  if (confirmed.absolute !== resolved.absolute) throw PATH_INVALID()
+  const temporary = path.join(path.dirname(confirmed.absolute), '.qq-owner-' + randomUUID() + '.tmp')
+  let created = true
+  try {
+    const existing = await fs.lstat(confirmed.absolute)
+    created = !existing.isFile()
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw PATH_INVALID()
+  }
+  let handle
+  try {
+    handle = await fs.open(temporary, 'wx', 0o600)
+    try {
+      await handle.writeFile(bytes)
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    if (signal?.aborted) throw REVOKED()
+    await assertAuthorized(authorize, signal)
+    await fs.rename(temporary, confirmed.absolute)
+  } catch (error) {
+    await fs.rm(temporary, { force: true }).catch(() => {})
+    throw error?.code ? error : PATH_INVALID()
+  }
+  return { name: path.basename(confirmed.absolute), bytes: bytes.length, created }
+}
+
+/** Fixed, model-facing text; never includes an absolute path or raw reason. */
+function ownerErrorText(error) {
+  switch (error?.code) {
+    case 'QQ_OWNER_WORKSPACE_PATH_INVALID': return 'Invalid owner workspace path.'
+    case 'QQ_OWNER_WORKSPACE_PATH_OUTSIDE': return 'Path is outside the owner workspace.'
+    case 'QQ_OWNER_WORKSPACE_PATH_UNSAFE': return 'Symbolic links are not allowed in the owner workspace.'
+    case 'QQ_OWNER_WORKSPACE_TOO_LARGE': return 'File exceeds the owner workspace size limit.'
+    case 'QQ_OWNER_WORKSPACE_NOT_UTF8': return 'Only UTF-8 text files can be read here.'
+    case 'QQ_OWNER_WORKSPACE_APPROVAL_UNAVAILABLE': return 'Owner workspace write approval is unavailable; nothing was written.'
+    case 'QQ_OWNER_WORKSPACE_UNAPPROVED': return 'Owner workspace write was not approved; nothing was written.'
+    case 'QQ_OWNER_WORKSPACE_REVOKED': return 'Owner workspace authorization is no longer valid.'
+    default: return 'Owner workspace operation failed.'
+  }
+}
+
+/**
+ * Build the model-facing tool. It is only registered by an Owner preset
+ * (level 4) that also configures a root; it is never visible otherwise.
+ */
+export function createOwnerWorkspaceTool({ root, allowWrite, maxBytes, getService, getApproval }) {
+  return {
+    name: OWNER_WORKSPACE_TOOL,
+    description: 'Read or write UTF-8 files inside the configured Owner workspace only. This is not a shell and cannot reach other directories.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        op: { type: 'string', enum: ['read', 'write'] },
+        path: { type: 'string', description: 'Relative path inside the Owner workspace.' },
+        content: { type: 'string', description: 'UTF-8 text to write (write only).' },
+      },
+      required: ['op', 'path'],
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value?.op === 'read'
+          ? String(value.text ?? '')
+          : JSON.stringify({ op: value?.op, name: value?.name, bytes: value?.bytes, created: value?.created }),
+      }],
+    },
+    async execute(args, exec) {
+      const sessionId = exec?.agent?.session?.id
+      if (typeof sessionId !== 'string' || !sessionId) throw new Error('Owner workspace requires a bound DSH Session.')
+      if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('Owner workspace arguments are invalid.')
+      const keys = Object.keys(args)
+      if (keys.some(key => !['op', 'path', 'content'].includes(key))) throw new Error('Owner workspace arguments are invalid.')
+      if (args.op !== 'read' && args.op !== 'write') throw new Error('Owner workspace op must be read or write.')
+      if (typeof args.path !== 'string') throw new Error('Owner workspace path is invalid.')
+      if (args.op === 'write' && typeof args.content !== 'string') throw new Error('Owner workspace write requires content.')
+      const service = typeof getService === 'function' ? getService() : undefined
+      const authorize = () => {
+        try {
+          const scene = service?.resolveTrustedSessionScene?.(sessionId)
+          if (!scene || scene.admin !== true) return false
+          return service?.authorizeSessionCapability?.(sessionId, OWNER_WORKSPACE_CAPABILITY) === true
+        } catch {
+          return false
+        }
+      }
+      try {
+        if (args.op === 'read') {
+          if (!authorize()) throw REVOKED()
+          const file = await readOwnerWorkspaceFile({
+            root,
+            requested: args.path,
+            maxBytes,
+            authorize,
+            signal: exec?.signal,
+          })
+          return {
+            op: 'read',
+            name: file.name,
+            bytes: file.bytes,
+            text: file.text,
+          }
+        }
+        if (!allowWrite) throw ownerError('QQ_OWNER_WORKSPACE_WRITE_DISABLED', 'owner workspace writes are disabled')
+        if (!authorize()) throw REVOKED()
+        const result = await writeOwnerWorkspaceFile({
+          root,
+          requested: args.path,
+          content: args.content,
+          maxBytes,
+          signal: exec?.signal,
+          authorize,
+          approve: () => requestOwnerWriteApproval({
+            approval: typeof getApproval === 'function' ? getApproval() : undefined,
+            agent: exec?.agent,
+            callId: exec?.callId,
+            signal: exec?.signal,
+          }),
+        })
+        return { op: 'write', name: result.name, bytes: result.bytes, created: result.created }
+      } catch (error) {
+        throw new Error(ownerErrorText(error))
+      }
+    },
+  }
+}
+
+// Read-only management metadata for the Settings page. No absolute path, no
+// file list: only whether the feature is configured and what it allows.
+let runtimeStatus = Object.freeze({ configured: false, writes: false, maxBytes: DEFAULT_MAX_BYTES })
+
+export function setOwnerWorkspaceStatus(status) {
+  const source = status ?? {}
+  runtimeStatus = Object.freeze({
+    configured: source.configured === true,
+    writes: source.writes === true,
+    maxBytes: Number.isSafeInteger(source.maxBytes) && source.maxBytes > 0 ? source.maxBytes : DEFAULT_MAX_BYTES,
+  })
+}
+
+export function ownerWorkspaceStatus() {
+  return runtimeStatus
+}
+
+export function resetOwnerWorkspaceStatus() {
+  runtimeStatus = Object.freeze({ configured: false, writes: false, maxBytes: DEFAULT_MAX_BYTES })
+}
+
+// Provider status for the Settings page. No process starts or credentials are
+// read here; the connector wires these once media send and QZone exist.
+const EMPTY_PROVIDER = Object.freeze({ installed: false, configured: false, enabled: false })
+let providerRuntime = Object.freeze({ mediaSend: EMPTY_PROVIDER, qzone: EMPTY_PROVIDER })
+
+export function setProviderStatus(patch = {}) {
+  const pick = source => Object.freeze({
+    installed: source?.installed === true,
+    configured: source?.configured === true,
+    enabled: source?.enabled === true,
+  })
+  providerRuntime = Object.freeze({
+    mediaSend: pick(patch.mediaSend ?? providerRuntime.mediaSend),
+    qzone: pick(patch.qzone ?? providerRuntime.qzone),
+  })
+}
+
+export function providerStatus() {
+  return providerRuntime
+}
+
+export function resetProviderStatus() {
+  providerRuntime = Object.freeze({ mediaSend: EMPTY_PROVIDER, qzone: EMPTY_PROVIDER })
+}

package/src/permissions.js

@@ -0,0 +1,250 @@
+// Capability decisions for a trusted QQ Scene. The caller must obtain Scene
+// identity from the platform adapter/Session binding, never from model args.
+
+export const MODE_IDS = Object.freeze([
+  'observe', 'safe-chat', 'enhanced', 'autonomous-social', 'owner-agent',
+])
+
+export const BEHAVIOR_PRESETS = Object.freeze({
+  observe: Object.freeze({ activity: 'low', quietWindowMs: 0, waitTimeoutMs: 0, replyCooldownMs: 0, contextBudget: 20 }),
+  'safe-chat': Object.freeze({ activity: 'low', quietWindowMs: 5000, waitTimeoutMs: 30000, replyCooldownMs: 0, contextBudget: 20 }),
+  enhanced: Object.freeze({ activity: 'medium', quietWindowMs: 10000, waitTimeoutMs: 30000, replyCooldownMs: 0, contextBudget: 20 }),
+  'autonomous-social': Object.freeze({ activity: 'medium', quietWindowMs: 12000, waitTimeoutMs: 30000, replyCooldownMs: 15000, contextBudget: 20 }),
+  'owner-agent': Object.freeze({ activity: 'medium', quietWindowMs: 10000, waitTimeoutMs: 30000, replyCooldownMs: 0, contextBudget: 20 }),
+})
+const BEHAVIOR_VALUES = Object.freeze({
+  activity: ['low', 'medium', 'high'], quietWindowMs: [0, 5000, 10000, 12000, 15000],
+  waitTimeoutMs: [0, 15000, 30000, 60000, 120000],
+  replyCooldownMs: [0, 10000, 15000, 30000, 60000], contextBudget: [10, 20, 40],
+})
+
+function validateBehavior(behavior) {
+  if (!behavior || typeof behavior !== 'object' || Array.isArray(behavior) ||
+    Object.keys(behavior).length !== Object.keys(BEHAVIOR_VALUES).length) {
+    throw new TypeError('Scene behavior must be a complete preset-compatible object')
+  }
+  for (const [key, values] of Object.entries(BEHAVIOR_VALUES)) {
+    if (!values.includes(behavior[key])) throw new TypeError(`Invalid Scene behavior: ${key}`)
+  }
+  if (Object.keys(behavior).some(key => !Object.hasOwn(BEHAVIOR_VALUES, key))) {
+    throw new TypeError('Unknown Scene behavior field')
+  }
+  return { ...behavior }
+}
+
+const GROUP_WRITE_DEFAULTS = [
+  'qq.group.essence', 'qq.group.notice', 'qq.group.card',
+  'qq.group.ban', 'qq.group.whole_ban', 'qq.group.kick',
+  'qq.group.name', 'qq.group.admin', 'qq.group.special_title',
+]
+const MODE_TO_CAPABILITIES = Object.freeze({
+  observe: ['qq.read'],
+  'safe-chat': ['qq.read', 'qq.send'],
+  enhanced: ['qq.read', 'qq.send', 'dsh.search', 'qq.media.read', 'qq.reaction.write', 'qq.poke', 'qq.recall'],
+  'autonomous-social': ['qq.read', 'qq.send', 'dsh.search', 'qq.media.read', 'qq.reaction.write', 'qq.poke', 'qq.recall'],
+  'owner-agent': ['qq.read', 'qq.send', 'dsh.search', 'qq.media.read', 'dsh.shell', 'qq.reaction.write', 'qq.poke', 'qq.recall'],
+})
+
+/**
+ * Capability catalog shared by the decision engine and the management API.
+ * `implemented` means this plugin has a real execution path today; false marks
+ * decision-only capabilities that must never be presented as usable.
+ */
+export const CAPABILITY_CATALOG = Object.freeze([
+  Object.freeze({ id: 'qq.read', implemented: true }),
+  Object.freeze({ id: 'qq.send', implemented: true }),
+  Object.freeze({ id: 'dsh.search', implemented: true }),
+  Object.freeze({ id: 'qq.friends.read', implemented: true }),
+  Object.freeze({ id: 'qq.groups.read', implemented: true }),
+  Object.freeze({ id: 'qq.media.read', implemented: true }),
+  Object.freeze({ id: 'qq.owner.workspace', implemented: true }),
+  Object.freeze({ id: 'qq.owner.tools', implemented: true }),
+  Object.freeze({ id: 'qq.reaction.write', implemented: true }),
+  Object.freeze({ id: 'qq.poke', implemented: true }),
+  Object.freeze({ id: 'qq.recall', implemented: true }),
+  Object.freeze({ id: 'qq.group.essence', implemented: true }),
+  Object.freeze({ id: 'qq.group.notice', implemented: true }),
+  Object.freeze({ id: 'qq.group.card', implemented: true }),
+  Object.freeze({ id: 'qq.group.ban', implemented: true }),
+  Object.freeze({ id: 'qq.group.whole_ban', implemented: true }),
+  Object.freeze({ id: 'qq.group.kick', implemented: true }),
+  Object.freeze({ id: 'qq.group.name', implemented: true }),
+  Object.freeze({ id: 'qq.group.admin', implemented: true }),
+  Object.freeze({ id: 'qq.group.special_title', implemented: true }),
+  Object.freeze({ id: 'qq.profile.write', implemented: true }),
+  Object.freeze({ id: 'qq.qzone.use', implemented: true }),
+  Object.freeze({ id: 'qq.qzone.read', implemented: true }),
+  Object.freeze({ id: 'qq.qzone.publish', implemented: true }),
+  Object.freeze({ id: 'dsh.shell', implemented: false }),
+])
+const KNOWN_CAPABILITIES = new Set(CAPABILITY_CATALOG.map(item => item.id))
+const DIRECTORY_CAPABILITIES = new Set(['qq.friends.read', 'qq.groups.read'])
+const QZONE_CAPABILITIES = new Set(['qq.qzone.use', 'qq.qzone.read', 'qq.qzone.publish'])
+const GROUP_WRITE_CAPABILITIES = new Set(GROUP_WRITE_DEFAULTS)
+const OVERRIDE_VALUES = new Set(['inherit', 'allow', 'deny'])
+const ID_PATTERN = /^[1-9]\d{0,19}$/
+
+function validMode(mode) { return MODE_IDS.includes(mode) }
+
+export function validateScenePermissions(access, { requireRevision = false, allowRevision = true } = {}) {
+  if (!access || typeof access !== 'object' || Array.isArray(access)) throw new TypeError('Scene permissions must be an object')
+  const keys = new Set(allowRevision ? ['mode', 'overrides', 'behavior', 'revision'] : ['mode', 'overrides', 'behavior'])
+  for (const key of Object.keys(access)) if (!keys.has(key)) throw new TypeError(`Unknown Scene permission field: ${key}`)
+  if (!validMode(access.mode)) throw new TypeError('Invalid Scene permission mode')
+  const overrides = access.overrides ?? {}
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) throw new TypeError('Scene permission overrides must be an object')
+  for (const [capability, value] of Object.entries(overrides)) {
+    if (!KNOWN_CAPABILITIES.has(capability) || !OVERRIDE_VALUES.has(value)) {
+      throw new TypeError(`Invalid Scene capability override: ${capability}`)
+    }
+  }
+  if ((requireRevision || access.revision !== undefined) && (!Number.isSafeInteger(access.revision) || access.revision < 1)) {
+    throw new TypeError('Invalid Scene permission revision')
+  }
+  return { mode: access.mode, overrides: { ...overrides },
+    ...(access.behavior === undefined ? {} : { behavior: validateBehavior(access.behavior) }) }
+}
+
+function idSet(values, label) {
+  if (!Array.isArray(values)) throw new TypeError(`${label} must be an array`)
+  const result = new Set()
+  for (const value of values) {
+    const id = typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : value
+    if (typeof id !== 'string' || !ID_PATTERN.test(id)) throw new TypeError(`${label} contains an invalid platform ID`)
+    result.add(id)
+  }
+  return result
+}
+
+function stringSet(values, label) {
+  if (!Array.isArray(values)) throw new TypeError(`${label} must be an array`)
+  const result = new Set(values)
+  for (const value of result) if (!KNOWN_CAPABILITIES.has(value)) throw new TypeError(`${label} contains an unknown capability`)
+  return result
+}
+
+function accountCanPublish(grants, botId) {
+  const account = grants?.byBotId?.[botId]
+  return account?.qzonePublish === true
+}
+
+export class PermissionEngine {
+  constructor(raw = {}) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new TypeError('Permission policy must be an object')
+    this.defaultMode = raw.defaultMode ?? 'safe-chat'
+    this.groupDefaultMode = raw.groupDefaultMode ?? this.defaultMode
+    this.privateDefaultMode = raw.privateDefaultMode ?? this.defaultMode
+    for (const mode of [this.defaultMode, this.groupDefaultMode, this.privateDefaultMode]) {
+      if (!validMode(mode)) throw new TypeError('Invalid default permission mode')
+    }
+    // A group is never an Owner Agent Scene, even by default. Reject at
+    // construction so a GUI cannot inherit and display that configuration.
+    if (this.groupDefaultMode === 'owner-agent') {
+      throw new TypeError('groupDefaultMode cannot be owner-agent: groups cannot be Owner Agent Scenes')
+    }
+    this.ownerPrivateIds = idSet(raw.ownerPrivateIds ?? [], 'ownerPrivateIds')
+    this.ownerTools = stringSet(raw.ownerTools ?? [], 'ownerTools')
+    this.globalDeny = stringSet(raw.globalDeny ?? [], 'globalDeny')
+    this.accountGrants = raw.accountGrants ?? {}
+    if (!this.accountGrants || typeof this.accountGrants !== 'object' || Array.isArray(this.accountGrants)) {
+      throw new TypeError('accountGrants must be an object')
+    }
+  }
+
+  evaluate(scene, access, capability) {
+    if (!KNOWN_CAPABILITIES.has(capability)) return { allowed: false, mode: null, reason: 'unknown-capability' }
+    if (!scene || !['group', 'private'].includes(scene.kind) ||
+      typeof scene.botId !== 'string' || !ID_PATTERN.test(scene.botId) ||
+      typeof scene.peerId !== 'string' || !ID_PATTERN.test(scene.peerId)) {
+      return { allowed: false, mode: null, reason: 'invalid-scene' }
+    }
+    let normalized
+    try {
+      normalized = access == null ? null : validateScenePermissions(access)
+    } catch {
+      return { allowed: false, mode: null, reason: 'invalid-scene-access' }
+    }
+    const mode = normalized?.mode ?? (scene.kind === 'group' ? this.groupDefaultMode : this.privateDefaultMode)
+    const decision = (allowed, reason) => ({ allowed, mode, reason })
+    if (this.globalDeny.has(capability)) return decision(false, 'global-deny')
+    if (QZONE_CAPABILITIES.has(capability)) {
+      // A unified revoke must also close the legacy read/publish aliases.
+      for (const related of QZONE_CAPABILITIES) {
+        if (this.globalDeny.has(related)) return decision(false, 'global-deny')
+        if (normalized?.overrides?.[related] === 'deny') return decision(false, 'scene-deny')
+      }
+    }
+    const owner = scene.kind === 'private' && this.ownerPrivateIds.has(scene.peerId)
+    if (mode === 'owner-agent' && !owner) return decision(false, 'owner-private-required')
+    const override = normalized?.overrides?.[capability] ?? 'inherit'
+    if (GROUP_WRITE_CAPABILITIES.has(capability) && scene.kind !== 'group') {
+      return decision(false, 'group-only')
+    }
+    if (DIRECTORY_CAPABILITIES.has(capability)) {
+      // Account-wide directories are never inherited from the Owner mode and
+      // never granted by a non-owner Scene; each call needs an explicit allow on
+      // a verified owner private Scene in owner-agent mode.
+      if (!owner || mode !== 'owner-agent' || override !== 'allow') {
+        return decision(false, 'owner-directory-required')
+      }
+      return decision(true, 'scene-allow')
+    }
+    if (capability === 'qq.owner.tools') {
+      // Native Host tools are available only for a verified owner private
+      // Scene in owner-agent mode; no extra per-tool approval is required.
+      if (!owner || mode !== 'owner-agent' || override === 'deny') {
+        return decision(false, 'owner-tools-required')
+      }
+      return decision(true, 'owner-agent')
+    }
+    if (capability === 'qq.owner.workspace') {
+      // The file surface is never implied by owner-agent mode and is never
+      // reachable from Safe Chat; the Owner must explicitly allow this Scene.
+      if (!owner || mode !== 'owner-agent' || override !== 'allow') {
+        return decision(false, 'owner-workspace-required')
+      }
+      return decision(true, 'scene-allow')
+    }
+    if (capability === 'qq.qzone.use') {
+      // Unified QZone access covers reads and writes, but still requires the
+      // account-level grant and an explicit Scene grant in autonomous-social or
+      // a verified owner private owner-agent Scene.
+      if (override !== 'allow') return decision(false, 'qzone-use-explicit')
+      if (!accountCanPublish(this.accountGrants, scene.botId)) {
+        return decision(false, 'account-publish-required')
+      }
+      if (owner && mode === 'owner-agent') return decision(true, 'scene-allow')
+      if (mode === 'autonomous-social') return decision(true, 'scene-allow')
+      return decision(false, 'qzone-use-explicit')
+    }
+    if (capability === 'qq.qzone.read') {
+      // QZone reads expose account-wide content. Require either an explicit
+      // Owner private grant or an explicitly allowed Autonomous Social Scene.
+      if (override !== 'allow') return decision(false, 'qzone-read-explicit')
+      if (owner && mode === 'owner-agent') return decision(true, 'scene-allow')
+      if (mode === 'autonomous-social') return decision(true, 'scene-allow')
+      return decision(false, 'qzone-read-explicit')
+    }
+    if (capability === 'qq.profile.write') {
+      // Account profile writes are global and require a verified Owner private
+      // Scene, owner-agent mode and an explicit Scene allow.
+      if (!owner || mode !== 'owner-agent' || override !== 'allow') {
+        return decision(false, 'profile-write-explicit')
+      }
+      return decision(true, 'scene-allow')
+    }
+    if (capability === 'dsh.shell' && (!owner || mode !== 'owner-agent' || !this.ownerTools.has(capability))) {
+      return decision(false, 'owner-tool-required')
+    }
+    if (capability === 'qq.qzone.publish') {
+      if (override !== 'allow') return decision(false, 'qzone-publish-explicit')
+      if (!accountCanPublish(this.accountGrants, scene.botId)) return decision(false, 'account-publish-required')
+      if (owner && mode === 'owner-agent') return decision(true, 'scene-allow')
+      if (mode === 'autonomous-social') return decision(true, 'scene-allow')
+      return decision(false, 'qzone-publish-explicit')
+    }
+    if (override === 'deny') return decision(false, 'scene-deny')
+    if (override === 'allow') return decision(true, 'scene-allow')
+    return decision(MODE_TO_CAPABILITIES[mode].includes(capability), 'mode')
+  }
+}