weir-harness 2.0.0 → 2.1.1

package/src/capabilities/mcp-diagnostics.js

@@ -0,0 +1,169 @@
+// Secret-free, bounded MCP diagnostics. Raw Error objects, stacks, URLs with
+// credentials, and arbitrary cause chains never cross the operation boundary.
+export const MCP_DIAGNOSTIC_LIMIT = 8192
+const CAUSE_LIMIT = 6
+
+const MESSAGE = value => value instanceof Error ? value.message : String(value ?? 'unknown error')
+
+/** Known-secret metadata is internal, inherited through wrapped causes, and never enumerated on the wire. */
+function errorSecrets(error, initial = []) {
+  const secrets = [...initial]
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    if (Array.isArray(current?.secrets)) secrets.push(...current.secrets)
+    current = current?.cause
+  }
+  return secrets
+}
+
+/** Replace known secrets, then reduce sensitive URL tails to scheme/host/path. */
+function redactKnownAndUrls(text, secrets) {
+  const known = [...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]
+    .sort((a, b) => b.length - a.length)
+  for (const secret of known) text = text.split(secret).join('[redacted]')
+  // Any sensitive URL component makes the whole userinfo/query/fragment tail
+  // sensitive. Preserve only scheme/host/path for actionable diagnostics.
+  return text.replace(/\b(?:https?|wss?):\/\/[^\s<>"']+/gi, candidate => {
+    const trailing = candidate.match(/[.,;:!?)]*$/)?.[0] ?? ''
+    const raw = trailing ? candidate.slice(0, -trailing.length) : candidate
+    try {
+      const url = new URL(raw)
+      if (!url.username && !url.password && !url.search && !url.hash) return candidate
+      return `${url.protocol}//${url.host}${url.pathname}[redacted-url]${trailing}`
+    } catch {
+      return '[redacted-url]'
+    }
+  })
+}
+
+/** Free text: replace every known secret before applying pattern-based redaction. */
+export function sanitizeMcpText(value, secrets = []) {
+  let text = String(value ?? '')
+  const known = [...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]
+    .sort((a, b) => b.length - a.length)
+  for (const secret of known) text = text.split(secret).join('[redacted]')
+  // Authorization lines and common secret-bearing key/value spellings.
+  text = text.replace(/\b(?:proxy-)?authorization\s*:\s*[^\r\n,;}]+/gi, match => `${match.split(':')[0]}: [redacted]`)
+  text = text.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+  text = text.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted-jwt]')
+  text = text.replace(/\b(?:api[-_]?key|access[-_]?token|refresh[-_]?token|password|passwd|secret|client[-_]?secret)(\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}]+)/gi, (_match, key, separator) => `${key}${separator}[redacted]`)
+  // Shell/environment assignments. Values may be quoted; the key remains useful.
+  text = text.replace(/\b[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s]+)/g, assignment => `${assignment.slice(0, assignment.indexOf('='))}=[redacted]`)
+  return redactKnownAndUrls(text, [])
+}
+
+/**
+ * Structured MCP configuration fields (argv, command, cwd, label, refs) are
+ * exact values the user must be able to read, edit and approve. Secret-bearing
+ * positions are already replaced structurally (secretRefs-indexed args, env/
+ * header values, sensitive URLs); here only known secret values and sensitive
+ * URL tails are removed. The generic KEY=VALUE patterns are for free text only:
+ * applying them to argv turned `--port=8080` into `--port=[redacted]`.
+ */
+export function sanitizeMcpConfigText(value, secrets = []) {
+  return redactKnownAndUrls(String(value ?? ''), secrets)
+}
+
+// Config projections produced by redactMcpEntry. Membership is process-local and
+// lost on clone/serialization, which only falls back to the stricter free-text
+// sanitizer — never to less redaction.
+const CONFIG_PROJECTIONS = new WeakSet()
+export function markMcpConfigProjection(value) {
+  if (value && typeof value === 'object') CONFIG_PROJECTIONS.add(value)
+  return value
+}
+function sanitizeConfigProjection(value, secrets) {
+  if (typeof value === 'string') return sanitizeMcpConfigText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeConfigProjection(item, secrets))
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeConfigProjection(item, secrets)]))
+  return value
+}
+
+export function sanitizeMcpPayload(value, secrets = []) {
+  if (typeof value === 'string') return sanitizeMcpText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeMcpPayload(item, secrets))
+  if (value && typeof value === 'object') {
+    if (CONFIG_PROJECTIONS.has(value)) return markMcpConfigProjection(sanitizeConfigProjection(value, secrets))
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeMcpPayload(item, secrets)]))
+  }
+  return value
+}
+
+const RULES = [
+  ['credential-missing', /credential[- ]missing|credential.*(?:not configured|empty|missing)|missing.*credential/i, 'Configure a non-empty credential reference, then retry.'],
+  ['name-conflict', /serverName.*(?:already in use|conflict)|name[- ]conflict|namespace.*conflict/i, 'Choose a unique public server name or remove the conflicting registration.'],
+  ['executable-not-found', /\bENOENT\b|executable.*(?:not found|unavailable)|command.*not found|cannot find.*(?:command|executable)/i, 'Check the command and its GUI PATH resolution, then retry.'],
+  ['permission-denied', /\bEACCES\b|\bEPERM\b|permission denied|access denied/i, 'Check executable and credential/file permissions, then retry.'],
+  ['connection-refused', /ECONNREFUSED|connection refused/i, 'Check that the server is listening and the endpoint is correct, then retry.'],
+  ['http-unauthorized', /\bHTTP\s*40[13]\b|\b40[13]\b|unauthorized|forbidden/i, 'Check the HTTP credential reference and server authorization policy.'],
+  ['timeout', /timeout|timed out|deadline exceeded/i, 'Inspect server startup and connectivity, then retry with a healthy server.'],
+  ['invalid-config', /invalid config|validation|unsupported transport|unknown (?:option|field)|initialDelayMs|maxDelayMs/i, 'Correct the marked configuration field and preview again.'],
+  ['cleanup-unknown', /cleanup-unknown|closure could not be confirmed|unconfirmed (?:transport )?clos/i, 'Inspect residue before retrying; an immediate same-name replacement is blocked.'],
+  ['cleanup-failed', /cleanup-failed|dispose(?:d|al)?(?: rejection| failed)|remove rejection/i, 'Inspect the cleanup diagnostic and recover the remaining Loader entry before retrying.'],
+  ['unsupported', /unsupported|ephemeral.*unavailable/i, 'Use a secret-free configuration or a Host with the required ephemeral Loader support.'],
+  ['owner-changed', /owner-changed|preset.*changed|ownership.*changed/i, 'Return to the original session/preset and preview again.'],
+]
+
+export function classifyMcpError(error, secrets = []) {
+  secrets = errorSecrets(error, secrets)
+  const evidence = []
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    evidence.push(`${current?.code ?? ''} ${MESSAGE(current)}`)
+    current = current?.cause
+  }
+  const text = sanitizeMcpText(evidence.join('\n'), secrets)
+  const match = RULES.find(([, pattern]) => pattern.test(text))
+  if (!match) return { code: 'unknown-error', hint: 'Inspect the sanitized diagnostic and retry after correcting the cause.' }
+  return { code: match[0], hint: match[2] }
+}
+
+function boundedMessage(text, max = 4096) {
+  const clean = String(text)
+  return Buffer.byteLength(clean) <= max ? clean : Buffer.from(clean).subarray(0, max - 1).toString().replace(/\uFFFD+$/g, '') + '…'
+}
+
+/**
+ * Convert an Error/cause chain into one stable secret-free diagnostic. Both
+ * individual strings and the complete JSON projection are bounded to 8 KiB.
+ */
+export function mcpDiagnostic(error, options = {}) {
+  const secrets = errorSecrets(error, options.secrets ?? [])
+  const classified = options.code ? { code: options.code, hint: options.hint } : classifyMcpError(error, secrets)
+  const causes = []
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    causes.push(boundedMessage(sanitizeMcpText(MESSAGE(current), secrets), 1024))
+    current = current?.cause
+  }
+  const first = causes[0] ?? boundedMessage(sanitizeMcpText(MESSAGE(error), secrets), 1024)
+  let diagnostic = {
+    code: classified.code ?? 'unknown-error',
+    message: boundedMessage(sanitizeMcpText(options.message ?? first, secrets)),
+    hint: boundedMessage(sanitizeMcpText(options.hint ?? classified.hint ?? 'Retry after correcting the cause.'), 1024),
+    recovery: { action: options.action ?? 'retry' },
+    causes,
+  }
+  while (Buffer.byteLength(JSON.stringify(diagnostic)) > MCP_DIAGNOSTIC_LIMIT && diagnostic.causes.length > 1) {
+    diagnostic.causes.pop()
+  }
+  if (Buffer.byteLength(JSON.stringify(diagnostic)) > MCP_DIAGNOSTIC_LIMIT) {
+    diagnostic.message = boundedMessage(diagnostic.message, 2048)
+    diagnostic.hint = boundedMessage(diagnostic.hint, 512)
+  }
+  return diagnostic
+}
+
+export class McpLifecycleError extends Error {
+  constructor(code, error, options = {}) {
+    const secrets = errorSecrets(error, options.secrets ?? [])
+    const diagnostic = mcpDiagnostic(error, { ...options, secrets, code, hint: options.hint })
+    super(diagnostic.message, options.cause === undefined && error instanceof Error ? { cause: error } : {})
+    this.name = 'McpLifecycleError'
+    this.code = code
+    this.status = options.status ?? code
+    this.diagnostic = diagnostic
+    Object.defineProperty(this, 'secrets', { value: Object.freeze([...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]), enumerable: false })
+    this.cleanup = options.cleanup === undefined ? undefined : sanitizeMcpPayload(options.cleanup, secrets)
+  }
+}

package/src/capabilities/mcp-drain.js

@@ -14,12 +14,13 @@
 export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
   /** @type {Map<string, { count: number, calls: Map<number, string>, closed: boolean }>} */
   const flights = new Map()
+  const closedServers = new Set()
   let sequence = 0
 
   const keyOf = (agentId, server) => `${agentId ?? 'unknown'}${server}`
   const stateOf = (agentId, server) => {
     const key = keyOf(agentId, server)
-    if (!flights.has(key)) flights.set(key, { count: 0, calls: new Map(), closed: false })
+    if (!flights.has(key)) flights.set(key, { server, count: 0, calls: new Map(), closed: false })
     return flights.get(key)
   }
 
@@ -30,7 +31,7 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
    */
   function enter(agentId, server, label = 'call') {
     const state = stateOf(agentId, server)
-    if (state.closed) return null
+    if (state.closed || closedServers.has(server)) return null
     sequence += 1
     state.count += 1
     state.calls.set(sequence, label)
@@ -68,7 +69,7 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
   }
 
   function isClosed(agentId, server) {
-    return stateOf(agentId, server).closed
+    return stateOf(agentId, server).closed || closedServers.has(server)
   }
 
   /** The Apply-time snapshot the response carries (sent at response time). */
@@ -77,7 +78,20 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
     return { server, state: state.count === 0 ? 'settled' : 'draining', inFlight: state.count }
   }
 
-  return { enter, exit, close, reopen, isClosed, drain, snapshot }
+  function closeAll(server) { closedServers.add(server) }
+  function reopenAll(server) { closedServers.delete(server) }
+  async function drainAll(server) {
+    const states = [...flights.values()].filter(state => state.server === server)
+    const started = now()
+    const totals = () => ({ count: states.reduce((sum, state) => sum + state.count, 0), calls: states.flatMap(state => [...state.calls.values()]) })
+    while (totals().count > 0 && now() - started < timeoutMs) await sleep(Math.min(50, timeoutMs))
+    const current = totals()
+    return current.count === 0
+      ? { drained: true, waitedMs: now() - started }
+      : { drained: false, inFlight: current.count, calls: current.calls, waitedMs: now() - started }
+  }
+
+  return { enter, exit, close, reopen, isClosed, drain, snapshot, closeAll, reopenAll, drainAll }
 }
 
 /**

package/src/capabilities/mcp-facade.js

@@ -30,10 +30,11 @@ const message = error => (error instanceof Error ? error.message : String(error)
  *   admit: (agent: unknown) => Promise<boolean>,
  *   isEnabledFor: (agent: unknown) => boolean,
  *   drain?: { enter(agentId: string, server: string, label?: string): number|null, exit(agentId: string, server: string, token: number|null): void },
+ *   onRegister?: (name: string, captureRollback: (rollback: () => void) => void) => void, onUnregister?: (name: string) => void,
  *   onError?: (reason: string, cause?: unknown) => void }} config
  */
-export function createMcpFacade({ host, identity, generation, admit, isEnabledFor, drain, onRegister, onError = () => {} }) {
-  const wrapper = createMcpToolWrapper({ identity, generation, admit, drain })
+export function createMcpFacade({ host, identity, generation, admit, isEnabledFor, drain, onRegister, onUnregister, onError = () => {}, assertPermit }) {
+  const wrapper = createMcpToolWrapper({ identity, generation, admit, drain, assertPermit })
 
   const unknown = (service, method) => {
     const reason = `facade-unknown-method:${service}.${method}`
@@ -43,14 +44,44 @@ export function createMcpFacade({ host, identity, generation, admit, isEnabledFo
 
   const tools = {
     register(definition) {
-      // Bind the public name to this configured identity at registration
-      // time, then wrap the definition with the last-moment admission check.
+      // Host registration happens first, then the generation-owned fact and
+      // every live agent converge in this same synchronous segment.
       const wrapped = wrapper.wrap(definition)
       const registration = /** @type {{ register(d: unknown): unknown }} */ (host.tools).register(wrapped)
-      // Report the binding back to the manager (creation-time schema hiding
-      // and the managed listing read this map).
-      if (typeof wrapped?.name === 'string') onRegister?.(wrapped.name)
-      return registration
+      if (typeof wrapped?.name !== 'string') return registration
+      const name = wrapped.name
+      const disposeHost = typeof registration === 'function' ? registration : () => {}
+      let rollbackRegistration = null
+      try {
+        onRegister?.(name, rollback => { rollbackRegistration = rollback })
+      } catch (cause) {
+        // Host-first rollback is fail-closed: owner facts and partial denies
+        // stay in place unless Host removal is confirmed.
+        try { disposeHost() } catch (rollbackError) {
+          onError('facade-host-registration-rollback-failed', rollbackError)
+          throw cause
+        }
+        try {
+          if (typeof rollbackRegistration === 'function') rollbackRegistration()
+          else onUnregister?.(name) // legacy registration callbacks
+        } catch (rollbackError) {
+          onError('facade-owner-registration-rollback-failed', rollbackError)
+        }
+        throw cause
+      }
+      let hostRemoved = false
+      let completed = false
+      return () => {
+        if (completed) return
+        if (!hostRemoved) {
+          // Host-first is fail-closed: if removal throws, the manager fact and
+          // deny stay in place. A later retry does not double-dispose the Host.
+          disposeHost()
+          hostRemoved = true
+        }
+        onUnregister?.(name)
+        completed = true
+      }
     },
     get(...args) { return /** @type {{ get(...a: unknown[]): unknown }} */ (host.tools).get(...args) },
     list(...args) { return /** @type {{ list(...a: unknown[]): unknown }} */ (host.tools).list(...args) },
@@ -91,7 +122,7 @@ export function createMcpFacade({ host, identity, generation, admit, isEnabledFo
       const gated = typeof request === 'function'
         ? { ...provider, async request(args, exec) {
             const admitted = await admit(exec?.agent)
-            if (!admitted) {
+            if (!admitted || (assertPermit && !assertPermit(admitted))) {
               const error = new Error(`MCP server "${identity}" resources are not enabled for this agent`)
               throw Object.assign(error, { code: 'mcp-admission-refused' })
             }

package/src/capabilities/mcp-gate.js

@@ -1,23 +1,30 @@
-// Task 8.2/8.5 of the session-capability-manager change: the admission gate
-// service the facades consume. The verdict for "is this managed server
-// usable by this agent" combines, in order:
-//   1. the registry's configured identity + current generation (8.1) — a
-//      reconnect mounts a NEW generation and every old-generation handle is
-//      rejected; a same-named DIFFERENT identity inherits nothing (8.5);
-//   2. the session lifecycle snapshot: BLOCKED sessions refuse every managed
-//      call (6.4); a dispose/reload window without an initialized snapshot
-//      refuses too (8.5);
-//   3. the session's accepted managed-MCP set (the selection record's
-//      mcpServers): a server not in the set is not enabled for that agent.
-// Connections stay shared at the host plane — a session losing a server
-// never disposes anything (8.5).
+// Managed MCP admission combines runtime registration generation/incarnation,
+// the accepted lifecycle selection, and (when mounted) the per-identity runtime
+// phase. Legacy compatibility exists only when BOTH sides lack incarnations.
 
-/**
- * @param {{ registry: { read(): Promise<any> },
- *   lifecycle: { snapshotFor(sessionId: string): any },
- *   sessionMcpServers?: (sessionId: string) => string[] | null }} options
- */
-export function createMcpGate({ registry, lifecycle, sessionMcpServers }) {
+export function mcpIncarnationMatches(snapshot, identity, entry) {
+  if (!entry) return false
+  const mapping = snapshot?.mcpIncarnations
+  if (mapping && typeof mapping === 'object' && !Array.isArray(mapping)) {
+    if (!Object.hasOwn(mapping, identity)) return false
+    return mapping[identity] === (entry.incarnation ?? null)
+  }
+  // A legacy selection without a mapping remains valid only for a legacy entry.
+  return entry.incarnation == null
+}
+
+function acceptedSnapshot(lifecycle, agent, { parentFallback = false } = {}) {
+  const sessionId = agent?.session?.id
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null
+  let snapshot = lifecycle.snapshotFor(sessionId)
+  if (snapshot == null && parentFallback) {
+    const parentId = agent?.session?.header?.parentSession
+    if (typeof parentId === 'string' && parentId.length > 0) snapshot = lifecycle.snapshotFor(parentId)
+  }
+  return snapshot?.state === 'ready' ? snapshot : null
+}
+
+export function createMcpGate({ registry, lifecycle, sessionMcpServers, registrationFor, runtime }) {
   const acceptedOf = sessionId => {
     if (typeof sessionMcpServers === 'function') return sessionMcpServers(sessionId)
     const snapshot = lifecycle.snapshotFor(sessionId)
@@ -25,47 +32,39 @@ export function createMcpGate({ registry, lifecycle, sessionMcpServers }) {
     return snapshot.mcpServers
   }
 
-  /**
-   * The facade-side verdict for one call.
-   * @param {unknown} agent @param {string} identity @param {number} generation
-   * @returns {Promise<boolean>}
-   */
-  async function admit(agent, identity, generation) {
+  async function permit(agent, identity, generation) {
     const sessionId = agent?.session?.id
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return false
-    const snapshot = lifecycle.snapshotFor(sessionId)
-    // BLOCKED (6.4) or no initialized snapshot (dispose/reload window, 8.5):
-    // every managed call is refused, never an unrestricted pass.
-    if (snapshot?.state !== 'ready') return false
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return null
+    if (runtime?.enabledFor && runtime.enabledFor(identity) === false) return null
+    const snapshot = acceptedSnapshot(lifecycle, agent)
+    if (!snapshot) return null
     const accepted = acceptedOf(sessionId)
-    if (!Array.isArray(accepted) || !accepted.includes(identity)) return false
+    if (!Array.isArray(accepted) || !accepted.includes(identity)) return null
+    if (runtime?.beforeRead && runtime.beforeRead(identity) === false) return null
     const current = await registry.read()
-    if (current.kind !== 'ok') return false
+    if (current.kind !== 'ok') return null
     const entry = current.servers[identity]
-    return Boolean(entry && entry.generation === generation)
+    if (!entry || entry.generation !== generation || !mcpIncarnationMatches(snapshot, identity, entry)) return null
+    if (runtime?.afterRead && runtime.afterRead(identity) === false) return null
+    if (runtime?.permit) return runtime.permit(identity, { generation, incarnation: entry.incarnation ?? null })
+    return { identity, generation, incarnation: entry.incarnation ?? null, operationId: null }
+  }
+  async function admit(agent, identity, generation) {
+    return (await permit(agent, identity, generation)) !== null
   }
 
-  /**
-   * Instruction-section filtering (8.4): is the server in the session's
-   * accepted set? At a subagent's creation the inherited capture is what the
-   * child gets — the parent's accepted set VERBATIM at that moment — so when
-   * the child's own snapshot is not visible yet (the creation-time
-   * schema-hiding listener races the capture listener), the parent's
-   * snapshot stands in. Call admission (admit) never uses this fallback: a
-   * snapshot-less child is refused, never granted the parent's set.
-   */
   function enabledFor(agent, identity) {
-    const sessionId = agent?.session?.id
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return false
-    let snapshot = lifecycle.snapshotFor(sessionId)
-    if (snapshot?.state !== 'ready') {
-      const parentId = agent?.session?.header?.parentSession
-      if (typeof parentId === 'string' && parentId.length > 0) snapshot = lifecycle.snapshotFor(parentId)
+    if (runtime?.enabledFor && runtime.enabledFor(identity) === false) return false
+    const snapshot = acceptedSnapshot(lifecycle, agent, { parentFallback: true })
+    if (!snapshot || !Array.isArray(snapshot.mcpServers) || !snapshot.mcpServers.includes(identity)) return false
+    if (typeof registrationFor !== 'function') {
+      // Pure legacy tests without a runtime registry still get mapping-shape
+      // enforcement; production always supplies registrationFor below.
+      const mapping = snapshot.mcpIncarnations
+      return !(mapping && typeof mapping === 'object' && !Array.isArray(mapping) && !Object.hasOwn(mapping, identity))
     }
-    if (snapshot?.state !== 'ready') return false
-    const accepted = snapshot.mcpServers
-    return Array.isArray(accepted) && accepted.includes(identity)
+    return mcpIncarnationMatches(snapshot, identity, registrationFor(identity))
   }
 
-  return { admit, enabledFor }
+  return { admit, permit, enabledFor, assertPermit: value => runtime?.assertPermit ? runtime.assertPermit(value) : Boolean(value) }
 }