dsh-bailinghub 0.4.0 → 0.6.0

package/lib/invocation-journal.js

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto'
+import { memberBinding } from './session-scope.js'
+
+const SCHEMA = 'bailing.agent-invocations.v2'
+const LEGACY_SCHEMA = 'bailing.agent-invocations.v1'
+const ID = /^[a-f0-9]{64}$/
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i
+const STATES = new Set(['unknown', 'executed', 'business_rejected', 'awaiting_approval', 'denied', 'rejected_before_dispatch', 'reconciliation_required', 'in_progress'])
+const IDENTITY_FIELDS = ['id', 'scopeHash', 'scopeRevision', 'target', 'runId', 'turn', 'callId', 'tool', 'capabilityRevision', 'parameterHash', 'taskBinding']
+const FIELDS = [...IDENTITY_FIELDS, 'lastKnownState', 'retryAt', 'resultHash']
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+  return value
+}
+
+export function metadataHash(value) {
+  return createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')
+}
+
+export function scopeFingerprint(scope) {
+  if (!scope?.locked || scope.state !== 'ready' || !scope.authorizations?.length) throw recoveryError('invocation_binding_conflict')
+  return metadataHash({ sessionId: scope.sessionId, revision: scope.revision,
+    members: scope.authorizations.map(member => ({ connectionKey: member.connectionKey,
+      ...memberBinding(scope, member), agentSessionId: member.sessionId,
+    })).sort((a, b) => a.connectionKey.localeCompare(b.connectionKey)),
+  })
+}
+
+export function recoveryError(code, invocationId, dispatch = 'not_dispatched') {
+  const storage = ['invocation_store_unavailable', 'invocation_store_conflict'].includes(code)
+  const error = new Error(code)
+  error.publicCode = code
+  error.feedback = {
+    schema: 'bailing.agent-feedback.v1', origin: 'dsh', operation: 'resume', code,
+    category: storage ? 'storage_error' : code === 'invocation_store_unsupported' ? 'unsupported' : 'invocation_recovery_unavailable',
+    dispatch, next_action: storage ? 'restore_invocations' : 'inspect_original',
+    ...(invocationId ? { invocation_id: invocationId, original_outcome: 'unverified' } : {}),
+  }
+  return error
+}
+
+function checkedEntry(value, legacy = false) {
+  const entry = structuredClone(value)
+  if (!entry || Array.isArray(entry) || Object.keys(entry).some(key => !FIELDS.includes(key)) ||
+    !ID.test(entry.id ?? '') || !ID.test(entry.scopeHash ?? '') ||
+    !Number.isSafeInteger(entry.scopeRevision) || entry.scopeRevision < 1 || !UUID.test(entry.runId ?? '') ||
+    !Number.isSafeInteger(entry.turn) || entry.turn < 0 ||
+    typeof entry.callId !== 'string' || !entry.callId.length || entry.callId.length > 4096 ||
+    !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(entry.tool ?? '') ||
+    !ID.test(entry.capabilityRevision ?? '') || !ID.test(entry.parameterHash ?? '') ||
+    !STATES.has(entry.lastKnownState) || !Number.isSafeInteger(entry.retryAt) || entry.retryAt < 0 ||
+    !(entry.resultHash === null || ID.test(entry.resultHash ?? ''))) throw recoveryError('invocation_binding_conflict')
+  if (legacy && Object.hasOwn(entry, 'taskBinding')) throw recoveryError('invocation_binding_conflict')
+  if (entry.taskBinding !== undefined && (!entry.taskBinding ||
+    Object.keys(entry.taskBinding).sort().join(',') !== 'schema_version,scope_hash,task_id' ||
+    entry.taskBinding.schema_version !== 'bailing.agent-task-binding.v1' ||
+    !UUID.test(entry.taskBinding.task_id ?? '') || !ID.test(entry.taskBinding.scope_hash ?? ''))) throw recoveryError('invocation_binding_conflict')
+  const target = entry.target
+  if (!target || Array.isArray(target) || Object.keys(target).sort().join(',') !== 'agentSessionId,authorizationRef,clientAppId,connectionKey,hubUrl,workspace' ||
+    !/^conn_[a-f0-9]{32}$/.test(target.connectionKey ?? '') || !UUID.test(target.agentSessionId ?? '') ||
+    !/^[a-z0-9][a-z0-9_-]{1,63}$/.test(target.clientAppId ?? '') ||
+    !/^[a-z0-9][a-z0-9_-]{1,63}$/.test(target.workspace ?? '') ||
+    typeof target.hubUrl !== 'string' || target.hubUrl.length > 2048 ||
+    typeof target.authorizationRef !== 'string' || !/^auth_[a-f0-9]{24}$/.test(target.authorizationRef)) throw recoveryError('invocation_binding_conflict')
+  return entry
+}
+
+function sameBinding(a, b) {
+  return metadataHash(Object.fromEntries(IDENTITY_FIELDS.map(key => [key, a[key]]))) ===
+    metadataHash(Object.fromEntries(IDENTITY_FIELDS.map(key => [key, b[key]])))
+}
+
+/** Trusted host metadata only; transcript text and model-provided bindings are never consumed. */
+export class InvocationJournal {
+  constructor(store) {
+    if (store != null && (typeof store.load !== 'function' || typeof store.save !== 'function')) throw new TypeError('An invocation store with load/save is required')
+    this.store = store
+    this.queues = new Map()
+    this.revisions = new Map()
+    this.pending = new Map()
+    this.failures = new Map()
+  }
+
+  serial(sessionId, operation) {
+    const previous = this.queues.get(sessionId) ?? Promise.resolve()
+    const result = previous.then(operation)
+    const tail = result.catch(() => {})
+    this.queues.set(sessionId, tail)
+    void tail.finally(() => { if (this.queues.get(sessionId) === tail) this.queues.delete(sessionId) })
+    return result
+  }
+
+  normalizeFailure(error, id) {
+    return error?.feedback ? error : recoveryError(error?.code === 'INVOCATION_STORE_CONFLICT'
+      ? 'invocation_store_conflict' : 'invocation_store_unavailable', id)
+  }
+
+  async read(sessionId) {
+    if (!this.store) throw recoveryError('invocation_store_unsupported')
+    try {
+      const raw = await this.store.load(sessionId)
+      const seen = this.revisions.get(sessionId) ?? 0
+      if (!raw) {
+        if (seen) throw recoveryError('invocation_binding_conflict')
+        return { schema: SCHEMA, sessionId, revision: 0, entries: [] }
+      }
+      if (![SCHEMA, LEGACY_SCHEMA].includes(raw.schema) || raw.sessionId !== sessionId || !Number.isSafeInteger(raw.revision) || raw.revision < 1 || raw.revision < seen ||
+        Object.keys(raw).some(key => !['schema', 'sessionId', 'revision', 'entries'].includes(key)) || !Array.isArray(raw.entries)) throw recoveryError('invocation_binding_conflict')
+      const entries = raw.entries.map(value => checkedEntry(value, raw.schema === LEGACY_SCHEMA))
+      if (new Set(entries.map(entry => entry.id)).size !== entries.length) throw recoveryError('invocation_binding_conflict')
+      this.revisions.set(sessionId, raw.revision)
+      return { schema: SCHEMA, sessionId, revision: raw.revision, entries }
+    } catch (error) { throw this.normalizeFailure(error) }
+  }
+
+  async write(record, entries) {
+    const next = { ...record, revision: record.revision + 1, entries }
+    const saved = await this.store.save(record.sessionId, structuredClone(next), record.revision || null)
+    if (metadataHash(saved) !== metadataHash(next)) throw recoveryError('invocation_store_unavailable')
+    this.revisions.set(record.sessionId, next.revision)
+  }
+
+  reserve(sessionId, value) {
+    if (!this.store) return Promise.resolve({ created: true, supported: false })
+    return this.serial(sessionId, async () => {
+      try {
+        const entry = checkedEntry(value)
+        if (this.failures.has(sessionId) || this.pending.get(sessionId)?.size) throw recoveryError(this.failures.get(sessionId) ?? 'invocation_store_unavailable', entry.id)
+        const record = await this.read(sessionId)
+        const existing = record.entries.find(item => item.id === entry.id)
+        if (existing) {
+          if (!sameBinding(existing, entry)) throw recoveryError('invocation_binding_conflict', entry.id)
+          return { created: false, supported: true, entry: structuredClone(existing) }
+        }
+        await this.write(record, [...record.entries, entry])
+        this.failures.delete(sessionId)
+        return { created: true, supported: true, entry: structuredClone(entry) }
+      } catch (error) {
+        const failure = this.normalizeFailure(error, value.id)
+        this.failures.set(sessionId, failure.publicCode)
+        throw failure
+      }
+    })
+  }
+
+  async updateOnce(sessionId, entry, previous) {
+    const record = await this.read(sessionId)
+    const index = record.entries.findIndex(item => item.id === entry.id)
+    if (index < 0 || !sameBinding(record.entries[index], entry)) throw recoveryError('invocation_binding_conflict', entry.id)
+    // A lost save acknowledgement is idempotent; a different outcome written by
+    // another process must not be overwritten by a stale in-flight response.
+    if (metadataHash(record.entries[index]) === metadataHash(entry)) return
+    if (metadataHash(record.entries[index]) !== metadataHash(previous)) throw recoveryError('invocation_store_conflict', entry.id)
+    const entries = [...record.entries]
+    entries[index] = checkedEntry(entry)
+    await this.write(record, entries)
+  }
+
+  update(sessionId, value, previous) {
+    if (!this.store) return Promise.resolve()
+    return this.serial(sessionId, async () => {
+      const entry = checkedEntry(value)
+      const pending = this.pending.get(sessionId) ?? new Map()
+      pending.set(entry.id, { entry, previous: checkedEntry(previous) })
+      this.pending.set(sessionId, pending)
+      try {
+        await this.updateOnce(sessionId, entry, previous)
+        pending.delete(entry.id)
+        if (!pending.size) this.failures.delete(sessionId)
+      } catch (error) {
+        const failure = this.normalizeFailure(error, entry.id)
+        failure.feedback.dispatch = 'unknown'
+        this.failures.set(sessionId, failure.publicCode)
+        throw failure
+      }
+    })
+  }
+
+  async find(sessionId, id, scopeHash) {
+    return this.serial(sessionId, async () => {
+      const record = await this.read(sessionId)
+      const entry = record.entries.find(value => value.id === id)
+      if (!entry) throw recoveryError('invocation_binding_unavailable', id)
+      if (entry.scopeHash !== scopeHash) throw recoveryError('invocation_binding_conflict', id)
+      return structuredClone(entry)
+    })
+  }
+
+  status(sessionId, scopeHash, restore = false) {
+    if (!this.store) return Promise.resolve({ state: 'unsupported', reason: 'invocation_store_unsupported', entries: [], unsavedRecords: 0 })
+    return this.serial(sessionId, async () => {
+      try {
+        let record = await this.read(sessionId)
+        if (record.entries.some(entry => entry.scopeHash !== scopeHash)) throw recoveryError('invocation_binding_conflict')
+        if (restore) {
+          for (const { entry, previous } of this.pending.get(sessionId)?.values() ?? []) {
+            if (entry.scopeHash !== scopeHash) throw recoveryError('invocation_binding_conflict')
+            await this.updateOnce(sessionId, entry, previous)
+            this.pending.get(sessionId).delete(entry.id)
+          }
+          this.failures.delete(sessionId)
+          record = await this.read(sessionId)
+        }
+        const unsavedRecords = this.pending.get(sessionId)?.size ?? 0
+        const reason = this.failures.get(sessionId)
+        return { state: reason || unsavedRecords ? 'storage_error' : 'ready', ...(reason ? { reason } : {}),
+          revision: record.revision || null, unsavedRecords,
+          entries: record.entries.map(entry => ({ invocation_id: entry.id, authorization_ref: entry.target.authorizationRef,
+            tool: entry.tool, ...(entry.taskBinding ? { task_binding: structuredClone(entry.taskBinding) } : {}), original_run_id: entry.runId, last_known_state: entry.lastKnownState,
+            result_verified: false, retry_at: entry.retryAt,
+          })),
+        }
+      } catch (error) {
+        const failure = this.normalizeFailure(error)
+        this.failures.set(sessionId, failure.publicCode)
+        return { state: failure.publicCode === 'invocation_binding_conflict' ? 'blocked' : 'storage_error',
+          reason: failure.publicCode, entries: [], unsavedRecords: this.pending.get(sessionId)?.size ?? 0 }
+      }
+    })
+  }
+}

package/lib/invocation-store.js

@@ -0,0 +1,275 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { isProxy } from 'node:util/types'
+
+const SCHEMAS = new Set(['bailing.agent-invocations.v1', 'bailing.agent-invocations.v2'])
+const RECORD_KEYS = new Set(['schema', 'sessionId', 'revision', 'entries'])
+const MAX_BYTES = 8 * 1024 * 1024
+const LOCK_TIMEOUT_MS = 1_000
+const PRIVATE_KEYS = new Set([
+  'token', 'tokens', 'accesstoken', 'refreshtoken', 'password', 'clientsecret',
+  'authorization', 'credential', 'credentials', 'secret', 'apikey',
+  'args', 'arguments', 'content', 'contents', 'body', 'prompt', 'messages',
+])
+const MAX_DEPTH = 128
+
+function storeError(code = 'INVOCATION_STORE_UNAVAILABLE') {
+  const error = new Error(code === 'INVOCATION_STORE_CONFLICT'
+    ? 'The invocation record changed or is being saved. Read it again before retrying.'
+    : 'The invocation store is unavailable. Recovery metadata was not safely confirmed.')
+  error.code = code
+  return error
+}
+
+function safeError(error) {
+  return ['INVOCATION_STORE_CONFLICT', 'INVOCATION_STORE_UNAVAILABLE'].includes(error?.code)
+    ? error : storeError()
+}
+
+function sessionKey(sessionId) {
+  if (typeof sessionId !== 'string' || !sessionId.length || sessionId.length > 4_096) throw storeError()
+  return createHash('sha256').update(sessionId).digest('hex')
+}
+
+// The coordinator validates each original execution binding. This boundary accepts
+// only JSON metadata and refuses credential or business payload fields. Tool names
+// are values, so a tool named "content" or "arguments" remains valid metadata.
+function snapshotJson(value, seen = new Set(), depth = 0) {
+  if (depth > MAX_DEPTH) throw storeError()
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)) return value
+  if (!value || typeof value !== 'object' || seen.has(value) || isProxy(value)) throw storeError()
+  const array = Array.isArray(value)
+  if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw storeError()
+  seen.add(value)
+  try {
+    const entries = Reflect.ownKeys(value).filter((key) => !array || key !== 'length')
+    if (array && (entries.length !== value.length || entries.some((key, index) => key !== String(index)))) throw storeError()
+    const copy = array ? [] : {}
+    for (const key of entries) {
+      const property = Object.getOwnPropertyDescriptor(value, key)
+      if (typeof key !== 'string' || !property.enumerable || !Object.hasOwn(property, 'value') ||
+        PRIVATE_KEYS.has(key.replace(/[_-]/gu, '').toLowerCase()) || ['__proto__', 'constructor', 'prototype'].includes(key)) throw storeError()
+      copy[key] = snapshotJson(property.value, seen, depth + 1)
+    }
+    return copy
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function snapshotRecord(sessionId, record) {
+  const copy = snapshotJson(record)
+  if (!copy || Array.isArray(copy) || !SCHEMAS.has(copy.schema) || copy.sessionId !== sessionId ||
+    !Number.isSafeInteger(copy.revision) || copy.revision < 1 || !Array.isArray(copy.entries) ||
+    Object.keys(copy).some((key) => !RECORD_KEYS.has(key))) throw storeError()
+  if (Buffer.byteLength(JSON.stringify(copy)) > MAX_BYTES) throw storeError()
+  return copy
+}
+
+function nextRecord(sessionId, record, expectedRevision) {
+  sessionKey(sessionId)
+  if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)) throw storeError()
+  const copy = snapshotRecord(sessionId, record)
+  if (copy.revision !== (expectedRevision ?? 0) + 1) throw storeError()
+  return copy
+}
+
+function assertRevision(current, expectedRevision) {
+  if ((current?.revision ?? null) !== expectedRevision) throw storeError('INVOCATION_STORE_CONFLICT')
+}
+
+function assertOwned(stat, kind) {
+  if (!(kind === 'directory' ? stat.isDirectory() : stat.isFile()) ||
+    (kind === 'file' && stat.nlink !== 1) ||
+    (typeof process.getuid === 'function' && stat.uid !== process.getuid()) ||
+    (process.platform !== 'win32' && (stat.mode & 0o777) !== (kind === 'directory' ? 0o700 : 0o600))) throw storeError()
+}
+
+function sameFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino
+}
+
+function defaultDirectory() {
+  const configured = process.env.DSH_HOME
+  const base = typeof configured === 'string' && configured.trim() ? configured : join(homedir(), '.dsh')
+  const expanded = base === '~' ? homedir() : /^~[/\\]/u.test(base) ? join(homedir(), base.slice(2)) : base
+  return join(resolve(expanded), 'plugins', 'dsh-bailinghub', 'invocation-records')
+}
+
+async function ensureDirectory(directory, create) {
+  if (create) await mkdir(directory, { recursive: true, mode: 0o700 })
+  let stat
+  try {
+    stat = await lstat(directory)
+  } catch (error) {
+    if (!create && error.code === 'ENOENT') return false
+    throw error
+  }
+  assertOwned(stat, 'directory')
+  return true
+}
+
+async function readRecord(path, sessionId) {
+  let before
+  try {
+    before = await lstat(path)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  assertOwned(before, 'file')
+  if (before.size > MAX_BYTES) throw storeError()
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const opened = await file.stat()
+    assertOwned(opened, 'file')
+    if (!sameFile(before, opened) || opened.size > MAX_BYTES) throw storeError()
+    // Bound the read even if an abnormal writer grows the file after fstat.
+    const bytes = Buffer.alloc(MAX_BYTES + 1)
+    let length = 0
+    while (length < bytes.length) {
+      const result = await file.read(bytes, length, bytes.length - length, length)
+      if (!result.bytesRead) break
+      length += result.bytesRead
+    }
+    if (length > MAX_BYTES) throw storeError()
+    return snapshotRecord(sessionId, JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length))))
+  } finally {
+    await file.close()
+  }
+}
+
+async function acquireLock(path) {
+  const deadline = performance.now() + LOCK_TIMEOUT_MS
+  while (true) {
+    let file
+    let stat
+    try {
+      file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+      stat = await file.stat()
+      await file.chmod(0o600)
+      assertOwned(await file.stat(), 'file')
+      return { file, stat }
+    } catch (error) {
+      if (file) {
+        if (stat) await releaseLock(path, { file, stat })
+        else await file.close().catch(() => {})
+      }
+      if (error.code !== 'EEXIST') throw error
+      try {
+        assertOwned(await lstat(path), 'file')
+      } catch (inspectionError) {
+        if (inspectionError.code === 'ENOENT') continue
+        throw inspectionError
+      }
+      if (performance.now() >= deadline) throw storeError('INVOCATION_STORE_CONFLICT')
+      // Never infer staleness or remove another process's lock.
+      await delay(20)
+    }
+  }
+}
+
+async function releaseLock(path, lock) {
+  try {
+    const current = await lstat(path)
+    if (!sameFile(current, lock.stat) || !current.isFile()) throw storeError()
+    await unlink(path)
+  } finally {
+    await lock.file.close()
+  }
+}
+
+async function syncDirectory(directory) {
+  // Windows does not expose fsync on directory handles through Node.
+  if (process.platform === 'win32') return
+  const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
+  try {
+    assertOwned(await handle.stat(), 'directory')
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Durable execution metadata only. No user directory is touched until load/save. */
+export function createFileInvocationStore({ directory } = {}) {
+  if (directory !== undefined && (typeof directory !== 'string' || !directory.trim())) throw storeError()
+  const root = directory === undefined ? defaultDirectory() : resolve(directory)
+  return {
+    async load(sessionId) {
+      try {
+        const key = sessionKey(sessionId)
+        if (!await ensureDirectory(root, false)) return null
+        return await readRecord(join(root, `${key}.json`), sessionId)
+      } catch (error) {
+        throw safeError(error)
+      }
+    },
+    async save(sessionId, record, expectedRevision) {
+      let lock
+      let temporaryPath
+      const key = sessionKey(sessionId)
+      const path = join(root, `${key}.json`)
+      const lockPath = join(root, `${key}.lock`)
+      try {
+        const copy = nextRecord(sessionId, record, expectedRevision)
+        await ensureDirectory(root, true)
+        lock = await acquireLock(lockPath)
+        assertRevision(await readRecord(path, sessionId), expectedRevision)
+        temporaryPath = join(root, `.${key}.${randomUUID()}.tmp`)
+        const temporary = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+        try {
+          await temporary.chmod(0o600)
+          assertOwned(await temporary.stat(), 'file')
+          await temporary.writeFile(JSON.stringify(copy), 'utf8')
+          await temporary.sync()
+        } finally {
+          await temporary.close()
+        }
+        await rename(temporaryPath, path)
+        temporaryPath = undefined
+        await syncDirectory(root)
+        return snapshotRecord(sessionId, copy)
+      } catch (error) {
+        throw safeError(error)
+      } finally {
+        try {
+          if (temporaryPath) await unlink(temporaryPath).catch((error) => {
+            if (error.code !== 'ENOENT') throw storeError()
+          })
+        } finally {
+          if (lock) {
+            try {
+              await releaseLock(lockPath, lock)
+            } catch {
+              throw storeError()
+            }
+          }
+        }
+      }
+    },
+  }
+}
+
+/** Explicit in-memory adapter: CAS-compatible, but never survives process restart. */
+export function createMemoryInvocationStore() {
+  const records = new Map()
+  return {
+    async load(sessionId) {
+      sessionKey(sessionId)
+      const record = records.get(sessionId)
+      return record ? snapshotRecord(sessionId, record) : null
+    },
+    async save(sessionId, record, expectedRevision) {
+      const copy = nextRecord(sessionId, record, expectedRevision)
+      assertRevision(records.get(sessionId), expectedRevision)
+      records.set(sessionId, copy)
+      return snapshotRecord(sessionId, copy)
+    },
+  }
+}