@rynfar/meridian 1.63.0 → 1.65.0

package/plugin/meridian-v2.ts

@@ -0,0 +1,335 @@
+/**
+ * Meridian OpenCode plugin for the V2 beta line.
+ *
+ * OpenCode V2 runs hidden title and summary requests in the parent session,
+ * often in parallel with the visible first turn. V2's core gives all of those
+ * requests the same session-affinity headers. Meridian must detach the hidden
+ * one-shots before they reach the proxy or they can advance the visible
+ * conversation's durable lineage.
+ *
+ * The model hook applies the identity as early as V2 permits. The HTTP hook
+ * enforces it again at the final request boundary. This removes stale or
+ * spoofed control headers regardless of header casing.
+ *
+ * NOTE: OpenCode-specific. Keep this separate from plugin/meridian.ts: V1
+ * expects a default plugin function and V2 expects a Plugin.define() object.
+ */
+
+import * as Plugin from "@opencode-ai/plugin/promise/plugin"
+import {
+  PRIORITY_ATTESTATION_HEADER,
+  createPriorityAttestation,
+  deleteHeader,
+  getHeader,
+  setHeader,
+  type MutableHeaders,
+} from "./priority-attestation"
+
+/** Exact V2 host used to compile and validate this beta-only integration. */
+export const SUPPORTED_OPENCODE_V2_VERSION = "0.0.0-beta-18314"
+
+const MERIDIAN_PROVIDERS = new Set(["anthropic", "meridian"])
+const PARENT_SESSION_ONE_SHOTS = new Set(["title", "summary"])
+const ATTACHED_COMPACTION_AGENT = "compaction"
+
+const SESSION_AFFINITY_HEADERS = [
+  "x-opencode-session",
+  "x-session-affinity",
+  "x-session-id",
+  "x-parent-session-id",
+] as const
+
+const MERIDIAN_CONTROL_HEADERS = [
+  "x-meridian-source",
+  "x-opencode-agent-name",
+  "x-opencode-agent-mode",
+  PRIORITY_ATTESTATION_HEADER,
+] as const
+
+export interface AgentTraits {
+  mode: "primary" | "subagent"
+  hidden: boolean
+}
+
+const BUILTIN_AGENT_TRAITS: Record<string, AgentTraits> = {
+  build: { mode: "primary", hidden: false },
+  plan: { mode: "primary", hidden: false },
+  general: { mode: "subagent", hidden: false },
+  explore: { mode: "subagent", hidden: false },
+  // Exact beta-18314 defines all three hidden internal agents as primary.
+  title: { mode: "primary", hidden: true },
+  summary: { mode: "primary", hidden: true },
+  compaction: { mode: "primary", hidden: true },
+}
+
+export function fallbackAgentTraits(agent: string): AgentTraits {
+  return BUILTIN_AGENT_TRAITS[agent] ?? { mode: "primary", hidden: false }
+}
+
+function safeAgentName(agent: string): string {
+  return agent.replace(/[^\x20-\x7E]/g, "").trim() || "unknown"
+}
+
+export function shouldDetachFromParentSession(agent: string, _traits: AgentTraits): boolean {
+  // The exact built-in ID is authoritative. `hidden` is presentation config:
+  // making the built-in visible does not stop V2 from running its parent-
+  // session title/summary job concurrently with the primary turn.
+  return PARENT_SESSION_ONE_SHOTS.has(agent)
+}
+
+/**
+ * Rewrite one V2 request's identity without changing its body or model input.
+ * This pure helper is shared by model.request and http.request.
+ */
+export function applyMeridianV2Headers(
+  headers: MutableHeaders,
+  input: { sessionID: string; agent: string; traits: AgentTraits },
+): void {
+  for (const name of SESSION_AFFINITY_HEADERS) deleteHeader(headers, name)
+  for (const name of MERIDIAN_CONTROL_HEADERS) deleteHeader(headers, name)
+
+  const name = safeAgentName(input.agent)
+  const detached = shouldDetachFromParentSession(input.agent, input.traits)
+
+  if (detached) {
+    setHeader(headers, "x-meridian-source", `subagent-${name}`)
+  } else {
+    // Set every V2 affinity spelling from the trusted hook input. Do not retain
+    // provider-config values that can bind this request to another session.
+    setHeader(headers, "x-opencode-session", input.sessionID)
+    setHeader(headers, "x-session-affinity", input.sessionID)
+    setHeader(headers, "x-session-id", input.sessionID)
+    if (input.agent === ATTACHED_COMPACTION_AGENT) {
+      // Source selects the base model tier without making the adapter append
+      // `#compaction` to the primary session key.
+      setHeader(headers, "x-meridian-source", "subagent-compaction")
+    }
+  }
+
+  const internalMode = PARENT_SESSION_ONE_SHOTS.has(input.agent)
+    ? "subagent"
+    : input.agent === ATTACHED_COMPACTION_AGENT ? "primary" : input.traits.mode
+  setHeader(headers, "x-opencode-agent-name", name)
+  setHeader(headers, "x-opencode-agent-mode", internalMode)
+}
+
+const INTERNAL_ROUTING_AGENT_IDS = new Set(["title", "summary", "compaction"])
+const AGENT_CACHE_MAX = 256
+const AGENT_CACHE_TTL_MS = 5_000
+const LOOKUP_TIMEOUT_MS = 250
+const MAX_CONTEXT_ENTRIES = 2_048
+const SAFE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/
+
+type ExactAgentMode = "primary" | "subagent" | "all"
+type ResolvedAgentMetadata = {
+  readonly traits: AgentTraits
+  readonly exactMode: ExactAgentMode | undefined
+  readonly authoritative: boolean
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+async function withTimeout<T>(pending: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timedOut = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), timeoutMs)
+    timer.unref?.()
+  })
+  try {
+    return await Promise.race([pending, timedOut])
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+export function isRootV2Session(value: unknown, sessionID: string): boolean {
+  return isRecord(value)
+    && value.id === sessionID
+    && value.parentID === undefined
+    && value.fork === undefined
+}
+
+/**
+ * Find the exact host message ID that initiated the active model loop.
+ * Assistant/tool steps and selection records belong to the current loop and
+ * are skipped. A synthetic/compaction/shell/skill/system or unknown initiator
+ * fails closed instead of reusing an older human ID.
+ */
+type V2HumanTurn = { readonly id: string; readonly issuedAt: number }
+
+export function findLatestV2HumanTurn(value: unknown): V2HumanTurn | undefined {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_CONTEXT_ENTRIES) return undefined
+  for (let index = value.length - 1; index >= 0; index -= 1) {
+    const message = value[index]
+    if (!isRecord(message) || typeof message.type !== "string") return undefined
+    if (
+      message.type === "assistant"
+      || message.type === "agent-switched"
+      || message.type === "model-switched"
+      || message.type === "location-switched"
+    ) {
+      continue
+    }
+    if (message.type !== "user" || typeof message.id !== "string" || !SAFE_ID_PATTERN.test(message.id)) {
+      return undefined
+    }
+    const time = isRecord(message.time) ? message.time : undefined
+    const createdAt = time?.created
+    if (typeof createdAt !== "number" || !Number.isSafeInteger(createdAt) || createdAt < 0) return undefined
+    return { id: message.id, issuedAt: Math.floor(createdAt / 1000) }
+  }
+  return undefined
+}
+
+export function findLatestV2HumanMessageId(value: unknown): string | undefined {
+  return findLatestV2HumanTurn(value)?.id
+}
+
+const MeridianV2Plugin = Plugin.define({
+  id: "meridian",
+  setup: async (context) => {
+    const traitsByAgent = new Map<string, {
+      expiresAt: number
+      request: symbol
+      pending: Promise<ResolvedAgentMetadata>
+    }>()
+    const registered: Array<{ dispose: () => Promise<void> }> = []
+
+    const resolveAgentTraits = (agent: string, refresh = false): Promise<ResolvedAgentMetadata> => {
+      const cached = traitsByAgent.get(agent)
+      if (!refresh && cached && cached.expiresAt > Date.now()) return cached.pending
+      if (refresh) traitsByAgent.delete(agent)
+
+      const request = Symbol(agent)
+      const pending = (async (): Promise<ResolvedAgentMetadata> => {
+        const controller = new AbortController()
+        try {
+          const result = await withTimeout(
+            context.agent.get({ agentID: agent }, { signal: controller.signal }),
+            LOOKUP_TIMEOUT_MS,
+          )
+          const data = result?.data
+          if (
+            !data
+            || (data.mode !== "primary" && data.mode !== "subagent" && data.mode !== "all")
+            || typeof data.hidden !== "boolean"
+          ) {
+            if (traitsByAgent.get(agent)?.request === request) traitsByAgent.delete(agent)
+            return { traits: fallbackAgentTraits(agent), exactMode: undefined, authoritative: false }
+          }
+          return {
+            traits: {
+              mode: data.mode === "subagent" ? "subagent" : "primary",
+              hidden: data.hidden,
+            },
+            exactMode: data.mode,
+            authoritative: true,
+          }
+        } catch {
+          // Retry a transient failure at the final HTTP boundary or next turn.
+          if (traitsByAgent.get(agent)?.request === request) traitsByAgent.delete(agent)
+          return { traits: fallbackAgentTraits(agent), exactMode: undefined, authoritative: false }
+        } finally {
+          controller.abort()
+        }
+      })()
+      traitsByAgent.delete(agent)
+      traitsByAgent.set(agent, { request, expiresAt: Date.now() + AGENT_CACHE_TTL_MS, pending })
+      while (traitsByAgent.size > AGENT_CACHE_MAX) {
+        const oldest = traitsByAgent.keys().next().value
+        if (oldest === undefined) break
+        traitsByAgent.delete(oldest)
+      }
+      return pending
+    }
+
+    const apply = async (
+      input: { sessionID: string; agent: string; model: { providerID: string } },
+      headers: MutableHeaders,
+      refreshTraits = false,
+    ): Promise<ResolvedAgentMetadata | undefined> => {
+      if (!MERIDIAN_PROVIDERS.has(String(input.model.providerID))) return undefined
+      const agent = String(input.agent)
+      const metadata = await resolveAgentTraits(agent, refreshTraits)
+      applyMeridianV2Headers(headers, {
+        sessionID: String(input.sessionID),
+        agent,
+        traits: metadata.traits,
+      })
+      return metadata
+    }
+
+    const resolveHumanTurn = async (
+      input: { sessionID: string; agent: string },
+      headers: MutableHeaders,
+      metadata: ResolvedAgentMetadata,
+    ): Promise<V2HumanTurn | undefined> => {
+      const sessionID = String(input.sessionID)
+      const agent = String(input.agent)
+      if (
+        !metadata.authoritative
+        || metadata.exactMode !== "primary"
+        || metadata.traits.hidden
+        || INTERNAL_ROUTING_AGENT_IDS.has(agent)
+        || safeAgentName(agent) !== agent
+        || getHeader(headers, "x-meridian-profile") !== undefined
+      ) {
+        return undefined
+      }
+
+      const controller = new AbortController()
+      try {
+        const result = await withTimeout(Promise.all([
+          context.session.get({ sessionID }, { signal: controller.signal }),
+          context.session.context({ sessionID }, { signal: controller.signal }),
+        ]), LOOKUP_TIMEOUT_MS)
+        if (!result || !isRootV2Session(result[0], sessionID)) return undefined
+        return findLatestV2HumanTurn(result[1])
+      } catch {
+        return undefined
+      } finally {
+        controller.abort()
+      }
+    }
+
+    try {
+      for (const providerID of MERIDIAN_PROVIDERS) {
+        registered.push(await context.session.hook("model.request", async (input) => {
+          // Apply lineage/tier identity early, but never emit the routing
+          // attestation before the final HTTP boundary.
+          await apply(input, input.headers)
+        }, { providerID }))
+        registered.push(await context.session.hook("http.request", async (input) => {
+          // Re-read exact visibility/mode at the final boundary. The model-hook
+          // cache is capability-only and must never authorize a stale visible
+          // primary after a config reload.
+          const metadata = await apply(input, input.request.headers, true)
+          if (!metadata) return
+          const humanTurn = await resolveHumanTurn(input, input.request.headers, metadata)
+          if (!humanTurn) return
+          const token = createPriorityAttestation({
+            generation: "oc2b18314",
+            sessionId: String(input.sessionID),
+            agentId: String(input.agent),
+            humanMessageId: humanTurn.id,
+            issuedAt: humanTurn.issuedAt,
+          })
+          if (token) setHeader(input.request.headers, PRIORITY_ATTESTATION_HEADER, token)
+        }, { providerID }))
+      }
+    } catch (error) {
+      await Promise.allSettled(registered.map(({ dispose }) => dispose()))
+      throw error
+    }
+
+    return async () => {
+      const results = await Promise.allSettled(registered.map(({ dispose }) => dispose()))
+      const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : [])
+      if (failures.length > 0) throw new AggregateError(failures, "Failed to dispose Meridian V2 hooks")
+    }
+  },
+})
+
+export default MeridianV2Plugin

package/plugin/meridian.ts

@@ -14,10 +14,19 @@
  *   { "plugin": ["/absolute/path/to/plugin/meridian.ts"] }
  */
 
-type AgentInput = string | { name?: string; mode?: string }
+import {
+  PRIORITY_ATTESTATION_HEADER,
+  createPriorityAttestation,
+  deleteHeader,
+  getHeader,
+  setHeader,
+} from "./priority-attestation"
+
+type AgentInput = string | { name?: string; mode?: string; hidden?: boolean }
+type ConfigAgent = { mode?: string; hidden?: boolean }
 
 type Plugin = (input: any) => Promise<{
-  config?: (cfg: { agent?: Record<string, { mode?: string } | undefined> }) => Promise<void> | void
+  config?: (cfg: { agent?: Record<string, ConfigAgent | undefined> }) => Promise<void> | void
   "chat.headers"?: (
     input: {
       sessionID: string
@@ -26,7 +35,7 @@ type Plugin = (input: any) => Promise<{
       // passes just the agent NAME as a string. Handle both.
       agent: AgentInput
       model: { providerID: string }
-      message: { id: string }
+      message: { id: string; sessionID?: string; time?: { created?: number } }
     },
     output: { headers: Record<string, string> }
   ) => Promise<void>
@@ -50,10 +59,33 @@ const BUILTIN_AGENT_MODES: Record<string, string> = {
   compaction: "subagent",
 }
 
-const MeridianPlugin: Plugin = async () => {
-  // Modes from the merged config, per plugin instance. Replaced wholesale on
-  // every config-hook fire so a reload can't leave stale entries behind.
-  let configModes: Record<string, string> = {}
+const INTERNAL_AGENT_IDS = new Set(["title", "summary", "compaction"])
+const ROOT_SESSION_CACHE_MAX = 256
+const ROOT_SESSION_CACHE_TTL_MS = 5_000
+const LOOKUP_TIMEOUT_MS = 250
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+async function withTimeout<T>(pending: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timedOut = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), timeoutMs)
+    timer.unref?.()
+  })
+  try {
+    return await Promise.race([pending, timedOut])
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+const MeridianPlugin: Plugin = async (pluginInput) => {
+  // Agent traits from the merged config, per plugin instance. Replaced
+  // wholesale on reload so routing eligibility cannot use stale visibility.
+  let configAgents: Record<string, ConfigAgent> = {}
+  const rootSessionCache = new Map<string, { expiresAt: number; pending: Promise<boolean> }>()
 
   const resolve = (agent: AgentInput): { name: string; mode: string } => {
     if (typeof agent === "object" && agent !== null) {
@@ -63,38 +95,111 @@ const MeridianPlugin: Plugin = async () => {
     // OpenCode >= 1.17: agent is the name string. Resolve the mode from the
     // merged config (captured in the config hook) + built-in defaults.
     const name = String(agent)
-    return { name, mode: configModes[name] ?? BUILTIN_AGENT_MODES[name] ?? "primary" }
+    return { name, mode: configAgents[name]?.mode ?? BUILTIN_AGENT_MODES[name] ?? "primary" }
+  }
+
+  const isStrictVisiblePrimary = (agent: AgentInput): boolean => {
+    const name = typeof agent === "string" ? agent : agent.name
+    if (!name || INTERNAL_AGENT_IDS.has(name)) return false
+    if (typeof agent === "object") {
+      return agent.mode === "primary" && agent.hidden !== true
+    }
+    const configured = configAgents[name]
+    if (configured) return configured.mode === "primary" && configured.hidden !== true
+    return BUILTIN_AGENT_MODES[name] === "primary"
+  }
+
+  const isRootSession = async (sessionID: string): Promise<boolean> => {
+    const cached = rootSessionCache.get(sessionID)
+    if (cached && cached.expiresAt > Date.now()) return cached.pending
+    const pending = (async (): Promise<boolean> => {
+      if (!isRecord(pluginInput) || !isRecord(pluginInput.client)) return false
+      const sessionApi = pluginInput.client.session
+      if (!isRecord(sessionApi) || typeof sessionApi.get !== "function") return false
+      const controller = new AbortController()
+      try {
+        const lookup = Promise.resolve(Reflect.apply(sessionApi.get, sessionApi, [
+          { path: { id: sessionID }, signal: controller.signal },
+        ]) as unknown)
+        const result = await withTimeout(lookup, LOOKUP_TIMEOUT_MS)
+        if (!isRecord(result)) return false
+        const data = isRecord(result.data) ? result.data : result
+        return data.id === sessionID && data.parentID === undefined && data.fork === undefined
+      } catch {
+        return false
+      } finally {
+        controller.abort()
+      }
+    })()
+    rootSessionCache.delete(sessionID)
+    rootSessionCache.set(sessionID, { expiresAt: Date.now() + ROOT_SESSION_CACHE_TTL_MS, pending })
+    while (rootSessionCache.size > ROOT_SESSION_CACHE_MAX) {
+      const oldest = rootSessionCache.keys().next().value
+      if (oldest === undefined) break
+      rootSessionCache.delete(oldest)
+    }
+    const eligible = await pending
+    if (!eligible && rootSessionCache.get(sessionID)?.pending === pending) rootSessionCache.delete(sessionID)
+    return eligible
   }
 
   return {
     // Runs with the merged OpenCode config (on init, and again on config
-    // reload). Captures the mode of user-defined agents and built-in
-    // overrides so chat.headers can classify string agent names.
+    // reload). Captures user-defined agents and built-in overrides.
     config: (cfg) => {
-      const next: Record<string, string> = {}
+      const next: Record<string, ConfigAgent> = {}
       for (const [name, def] of Object.entries(cfg?.agent ?? {})) {
-        if (typeof def?.mode === "string") next[name] = def.mode
+        if (!def) continue
+        next[name] = {
+          ...(typeof def.mode === "string" ? { mode: def.mode } : {}),
+          ...(typeof def.hidden === "boolean" ? { hidden: def.hidden } : {}),
+        }
       }
-      configModes = next
+      configAgents = next
     },
 
     "chat.headers": async (incoming, output) => {
-      // Only inject headers for Anthropic provider requests
+      // This is V1's final supported outbound boundary. Remove an earlier
+      // plugin/provider spoof even when this request is not eligible.
+      deleteHeader(output.headers, PRIORITY_ATTESTATION_HEADER)
+      // Only inject headers for Anthropic provider requests.
       if (incoming.model.providerID !== "anthropic") return
 
-      // Session tracking
-      output.headers["x-opencode-session"] = incoming.sessionID
-      output.headers["x-opencode-request"] = incoming.message.id
+      // Session tracking. Replace case-insensitively so the values compared by
+      // the proxy are the same trusted hook inputs that are signed below.
+      setHeader(output.headers, "x-opencode-session", incoming.sessionID)
+      setHeader(output.headers, "x-opencode-request", incoming.message.id)
 
       const { name, mode } = resolve(incoming.agent)
+      const safeName = name.replace(/[^\x20-\x7E]/g, "").trim() || "unknown"
 
       // The proxy expects primary|subagent. "all" agents can act as either;
       // without per-request context, treat them as primary (full tier) to
-      // preserve capability.
-      output.headers["x-opencode-agent-mode"] = mode === "subagent" ? "subagent" : "primary"
+      // preserve capability. This permissive tiering decision is NOT reused as
+      // strict routing eligibility.
+      setHeader(output.headers, "x-opencode-agent-mode", mode === "subagent" ? "subagent" : "primary")
       // Strip non-ASCII characters (e.g. zero-width spaces) that cause
       // "Header has invalid value" errors in Node.js / undici.
-      output.headers["x-opencode-agent-name"] = name.replace(/[^\x20-\x7E]/g, "").trim() || "unknown"
+      setHeader(output.headers, "x-opencode-agent-name", safeName)
+
+      if (getHeader(output.headers, "x-meridian-profile") !== undefined) return
+      if (safeName !== name || !isStrictVisiblePrimary(incoming.agent)) return
+      const createdAt = incoming.message.time?.created
+      if (typeof createdAt !== "number" || !Number.isSafeInteger(createdAt) || createdAt < 0) return
+      const issuedAt = Math.floor(createdAt / 1000)
+      if (incoming.message.sessionID !== undefined && incoming.message.sessionID !== incoming.sessionID) return
+      if (!(await isRootSession(incoming.sessionID))) return
+      // A config reload can complete while the bounded root lookup is in
+      // flight. Re-check visibility at the final signing instant.
+      if (!isStrictVisiblePrimary(incoming.agent)) return
+      const token = createPriorityAttestation({
+        generation: "oc1",
+        sessionId: incoming.sessionID,
+        agentId: safeName,
+        humanMessageId: incoming.message.id,
+        issuedAt,
+      })
+      if (token) setHeader(output.headers, PRIORITY_ATTESTATION_HEADER, token)
     },
   }
 }

package/plugin/priority-attestation.ts

@@ -0,0 +1,150 @@
+/**
+ * OpenCode-side signer for Meridian priority failback attestations.
+ *
+ * This file lives under plugin/ because the V1 plugin is shipped as TypeScript.
+ * The V2 build bundles it into dist/meridian-v2.js.
+ */
+
+import { createHash, createHmac } from "node:crypto"
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export const PRIORITY_ATTESTATION_HEADER = "x-meridian-opencode-turn"
+export const PRIORITY_ATTESTATION_KEY_ENV = "MERIDIAN_OPENCODE_ATTESTATION_KEY"
+export const PRIORITY_ATTESTATION_KEY_FILE = "opencode-turn.key"
+
+const TOKEN_PREFIX = "v1"
+const MAC_DOMAIN = "meridian.opencode.turn.v1\0"
+const TURN_DOMAIN = "meridian.opencode.human.v1\0"
+const MAX_HEADER_BYTES = 768
+const MAX_PAYLOAD_BYTES = 384
+const TURN_DIGEST_PATTERN = /^[A-Za-z0-9_-]{43}$/
+const SAFE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/
+export type OpenCodeAttestationGeneration = "oc1" | "oc2b18314"
+
+export interface PriorityAttestationSignInput {
+  readonly generation: OpenCodeAttestationGeneration
+  readonly sessionId: string
+  readonly agentId: string
+  readonly humanMessageId: string
+  /** Immutable OpenCode user-message creation time, in whole Unix seconds. */
+  readonly issuedAt: number
+}
+
+function configDirectory(): string {
+  return process.env.MERIDIAN_CONFIG_DIR ?? join(homedir(), ".config", "meridian")
+}
+
+export function priorityAttestationKeyPath(): string {
+  return join(configDirectory(), PRIORITY_ATTESTATION_KEY_FILE)
+}
+
+function isSafeAgentId(value: string): boolean {
+  return value.length >= 1
+    && value.length <= 64
+    && value.trim() === value
+    && /^[\x20-\x7E]+$/.test(value)
+}
+
+function decodeCanonicalBase64Url(raw: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9_-]+$/.test(raw)) return undefined
+  const decoded = Buffer.from(raw, "base64url")
+  return decoded.toString("base64url") === raw ? decoded : undefined
+}
+
+export function decodePriorityAttestationKey(raw: string | undefined): Buffer | undefined {
+  if (raw === undefined) return undefined
+  const normalized = raw.trim()
+  const decoded = decodeCanonicalBase64Url(normalized)
+  return decoded?.length === 32 ? decoded : undefined
+}
+
+export function loadPriorityAttestationKey(): Buffer | undefined {
+  const fromEnv = process.env[PRIORITY_ATTESTATION_KEY_ENV]
+  if (fromEnv !== undefined) return decodePriorityAttestationKey(fromEnv)
+  try {
+    return decodePriorityAttestationKey(readFileSync(priorityAttestationKeyPath(), "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+export function computePriorityTurnDigest(input: {
+  readonly generation: OpenCodeAttestationGeneration
+  readonly sessionId: string
+  readonly humanMessageId: string
+}): string | undefined {
+  if (!SAFE_ID_PATTERN.test(input.sessionId) || !SAFE_ID_PATTERN.test(input.humanMessageId)) {
+    return undefined
+  }
+  return createHash("sha256")
+    .update(TURN_DOMAIN)
+    .update(input.generation)
+    .update("\0")
+    .update(input.sessionId)
+    .update("\0")
+    .update(input.humanMessageId)
+    .digest("base64url")
+}
+
+
+
+export function createPriorityAttestation(
+  input: PriorityAttestationSignInput,
+  key: Buffer = loadPriorityAttestationKey() ?? Buffer.alloc(0),
+): string | undefined {
+  if (key.length !== 32) return undefined
+  if (!SAFE_ID_PATTERN.test(input.sessionId) || !isSafeAgentId(input.agentId)) return undefined
+  const turnDigest = computePriorityTurnDigest(input)
+  if (!turnDigest || !TURN_DIGEST_PATTERN.test(turnDigest)) return undefined
+  const issuedAt = input.issuedAt
+  if (!Number.isSafeInteger(issuedAt) || issuedAt < 0) return undefined
+
+  // Fixed insertion order is part of the wire contract. The proxy reconstructs
+  // this exact JSON and rejects non-canonical or extensible payloads.
+  const payload = JSON.stringify({
+    v: 1,
+    g: input.generation,
+    s: input.sessionId,
+    a: input.agentId,
+    t: turnDigest,
+    iat: issuedAt,
+  })
+  if (Buffer.byteLength(payload) > MAX_PAYLOAD_BYTES) return undefined
+  const encodedPayload = Buffer.from(payload).toString("base64url")
+  const mac = createHmac("sha256", key)
+    .update(MAC_DOMAIN)
+    .update(payload)
+    .digest("base64url")
+  const token = `${TOKEN_PREFIX}.${encodedPayload}.${mac}`
+  return Buffer.byteLength(token) <= MAX_HEADER_BYTES ? token : undefined
+}
+
+export type MutableHeaders = Record<string, string> | Headers
+
+export function deleteHeader(headers: MutableHeaders, name: string): void {
+  if (headers instanceof Headers) {
+    headers.delete(name)
+    return
+  }
+  const lower = name.toLowerCase()
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) delete headers[key]
+  }
+}
+
+export function getHeader(headers: MutableHeaders, name: string): string | undefined {
+  if (headers instanceof Headers) return headers.get(name) ?? undefined
+  const lower = name.toLowerCase()
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower) return value
+  }
+  return undefined
+}
+
+export function setHeader(headers: MutableHeaders, name: string, value: string): void {
+  deleteHeader(headers, name)
+  if (headers instanceof Headers) headers.set(name, value)
+  else headers[name] = value
+}