cli-aimlock 7.0.35 → 7.0.37

package/aimlock-read-budget-state.mjs

@@ -0,0 +1,71 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { appendAudit, ensureManagedDirectory, fail, identifier, managedPath, repositoryRoot } from './aimlock-local-fs.mjs'
+
+const BUDGET_SCHEMA = 'aimlock.read-budget/1.0'
+const TOKEN_ESTIMATE_ALGORITHM = 'utf8-bytes-div-4-ceil'
+const READ_BUDGETS = Object.freeze({
+  lock: Object.freeze({ maxFiles: 3, maxTokenEstimate: null, maxDurationMs: 120_000 }),
+  probe: Object.freeze({ maxFiles: 10, maxTokenEstimate: 30_000, maxDurationMs: 480_000 }),
+  swarm: Object.freeze({ maxFiles: 30, maxTokenEstimate: 100_000, maxDurationMs: 3_600_000 }),
+})
+
+async function readBudget(root, chainId) {
+  const id = identifier(chainId, 'chainId')
+  const path = managedPath(root, 'runs', id, 'read-budget.json')
+  const state = JSON.parse(await readFile(path, 'utf8'))
+  if (state.schemaVersion !== BUDGET_SCHEMA || state.chainId !== id) {
+    fail('AIMLOCK_BUDGET_INVALID', 'read budget authority is invalid')
+  }
+  return { path, state }
+}
+
+function budgetView(state, now = Date.now()) {
+  const elapsedMs = now - Date.parse(state.startedAt)
+  const remainingFiles = Math.max(0, state.maxFiles - state.uniqueFiles.length)
+  const remainingTokenEstimate = state.maxTokenEstimate === null ? null
+    : Math.max(0, state.maxTokenEstimate - state.tokenEstimate)
+  const remainingDurationMs = Math.max(0, state.maxDurationMs - elapsedMs)
+  const autoRenewEligible = !state.completedAt && remainingDurationMs === 0
+    && remainingFiles > 0 && remainingTokenEstimate !== 0 && state.autoRenew?.status === 'active'
+    && requiredRenewalIntervals(state, now) <= state.autoRenew.policy.maxRenewals - state.autoRenew.renewalCount
+  const decisionRequired = Boolean(state.completedAt) || remainingFiles === 0 || (remainingDurationMs === 0 && !autoRenewEligible)
+    || remainingTokenEstimate === 0
+  return { ...state, elapsedMs, remainingFiles, remainingTokenEstimate, remainingDurationMs,
+    autoRenewEligible, decisionRequired,
+    nextActions: decisionRequired ? ['execute', 'plan', 'blocked'] : autoRenewEligible ? ['budget-read'] : [] }
+}
+
+function requiredRenewalIntervals(state, now = Date.now()) {
+  if (!state.autoRenew) return null
+  return Math.max(0, Math.floor((now - Date.parse(state.startedAt) - state.maxDurationMs)
+    / state.autoRenew.policy.intervalMs) + 1)
+}
+
+async function initializeReadBudget(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const chainId = identifier(input.chainId, 'chainId')
+  const limits = READ_BUDGETS[input.mode]
+  if (!limits) fail('AIMLOCK_MODE_INVALID', 'mode must be lock, probe, or swarm')
+  const directory = await ensureManagedDirectory(root, 'runs', chainId)
+  const state = {
+    schemaVersion: BUDGET_SCHEMA,
+    chainId,
+    mode: input.mode,
+    startedAt: new Date().toISOString(),
+    ...limits,
+    uniqueFiles: [],
+    readCalls: 0,
+    tokenEstimate: 0,
+    tokenEstimateAlgorithm: TOKEN_ESTIMATE_ALGORITHM,
+    extensions: [],
+  }
+  await writeFile(resolve(directory, 'read-budget.json'), `${JSON.stringify(state)}\n`, {
+    flag: 'wx', mode: 0o600,
+  })
+  await appendAudit(root, { event: 'read-budget-initialized', chainId, mode: input.mode })
+  return budgetView(state)
+}
+
+export { BUDGET_SCHEMA, TOKEN_ESTIMATE_ALGORITHM, READ_BUDGETS, readBudget, budgetView,
+  requiredRenewalIntervals, initializeReadBudget }

package/aimlock-read-budget.mjs

@@ -0,0 +1,127 @@
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import { LOCAL_SCHEMA, appendAudit, atomicJson, fail, identifier, managedPath,
+  repositoryRoot, resolvedProjectPath, safeRelativePath, withFileLock } from './aimlock-local-fs.mjs'
+import { assertChainNotSuspended } from './aimlock-coordination.mjs'
+import { readBudget, budgetView } from './aimlock-read-budget-state.mjs'
+import { assertReadBudgetActive, assertRenewalScope, renewReadBudgetTime } from './aimlock-read-budget-renewal.mjs'
+
+const CONFIRMATION_SCHEMA = 'confirm-protocol.skill.response/1.0'
+
+async function readFileWithinBudget(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const chainId = identifier(input.chainId, 'chainId')
+  await assertChainNotSuspended({ repositoryRoot: root, chainId })
+  const budgetPath = managedPath(root, 'runs', chainId, 'read-budget.json')
+  return withFileLock(budgetPath, async () => {
+    const authority = await readBudget(root, chainId)
+    const path = safeRelativePath(input.path)
+    let state = authority.state
+    await assertReadBudgetActive(root, state)
+    const before = budgetView(state)
+    const isNew = !state.uniqueFiles.includes(path)
+    if (isNew && before.remainingFiles === 0) fail('AIMLOCK_DECISION_REQUIRED', 'read file budget exhausted')
+    const projectFile = await resolvedProjectPath(root, path)
+    if (!projectFile.status.isFile()) fail('AIMLOCK_READ_NOT_FILE', `${path} is not a file`)
+    assertRenewalScope(state, path, relative(root, projectFile.target).split('\\').join('/'))
+    const tokenEstimate = Math.ceil(projectFile.status.size / 4)
+    if (before.remainingTokenEstimate !== null && tokenEstimate > before.remainingTokenEstimate) {
+      fail('AIMLOCK_DECISION_REQUIRED', 'read token estimate budget exhausted')
+    }
+    state = await renewReadBudgetTime(root, authority, path)
+    const content = await readFile(projectFile.target, 'utf8')
+    const updated = {
+      ...state,
+      uniqueFiles: isNew ? [...state.uniqueFiles, path] : state.uniqueFiles,
+      readCalls: state.readCalls + 1,
+      tokenEstimate: state.tokenEstimate + tokenEstimate,
+    }
+    await atomicJson(authority.path, updated)
+    await appendAudit(root, { event: 'read-consumed', chainId, path, tokenEstimate })
+    return { schemaVersion: LOCAL_SCHEMA, path, content, budget: budgetView(updated) }
+  })
+}
+
+async function checkCachedReadAccess(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const chainId = identifier(input.chainId, 'chainId')
+  await assertChainNotSuspended({ repositoryRoot: root, chainId })
+  const budgetPath = managedPath(root, 'runs', chainId, 'read-budget.json')
+  return withFileLock(budgetPath, async () => {
+    const authority = await readBudget(root, chainId)
+    const { state } = authority
+    await assertReadBudgetActive(root, state)
+    const path = safeRelativePath(input.path)
+    const budget = budgetView(state)
+    if (budget.remainingTokenEstimate === 0) fail('AIMLOCK_DECISION_REQUIRED', 'read token estimate budget exhausted')
+    if (!state.uniqueFiles.includes(path)) fail('AIMLOCK_CACHE_UNCHARGED', 'cached source was not read by this chain')
+    const projectFile = await resolvedProjectPath(root, path)
+    assertRenewalScope(state, path, relative(root, projectFile.target).split('\\').join('/'))
+    return { schemaVersion: LOCAL_SCHEMA, path,
+      budget: budgetView(await renewReadBudgetTime(root, authority, path)) }
+  })
+}
+
+async function readBudgetStatus(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  return budgetView((await readBudget(root, input.chainId)).state)
+}
+
+function confirmedBudgetExtension(input) {
+  const confirmation = input.confirmation
+  const audit = confirmation?.auditEntry
+  const callback = confirmation?.callbackRequest
+  const payload = callback?.payload
+  const fields = ['files', 'tokenEstimate', 'durationMs']
+  if (!confirmation || confirmation.schemaVersion !== CONFIRMATION_SCHEMA || confirmation.status !== 'succeeded'
+    || audit?.schemaVersion !== 'confirm.audit-entry/1.0' || audit.risk !== 'low' || audit.answer !== 'approve'
+    || typeof audit.remembered !== 'boolean' || !Number.isFinite(Date.parse(audit.answeredAt))
+    || callback?.operation !== 'budget-extend' || payload?.answer !== 'approve'
+    || payload.chainId !== input.chainId || payload.requestId !== audit.requestId
+    || !payload.additions || fields.some((key) => payload.additions[key] !== input.additions?.[key])) {
+    fail('AIMLOCK_CONFIRMATION_REQUIRED', 'a low-risk Confirm Protocol interaction-answer bound to this chain and exact additions is required')
+  }
+  identifier(audit.actorId, 'actorId')
+  identifier(audit.requestId, 'requestId')
+  return identifier(audit.auditId, 'auditId')
+}
+
+async function extendReadBudget(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const confirmationId = confirmedBudgetExtension(input)
+  const additions = input.additions
+  if (!additions || !Number.isSafeInteger(additions.files) || additions.files < 0
+    || !Number.isSafeInteger(additions.tokenEstimate) || additions.tokenEstimate < 0
+    || !Number.isSafeInteger(additions.durationMs) || additions.durationMs < 0
+    || additions.files + additions.tokenEstimate + additions.durationMs === 0) {
+    fail('AIMLOCK_EXTENSION_INVALID', 'budget additions must contain a positive integer increase')
+  }
+  const chainId = identifier(input.chainId, 'chainId')
+  const budgetPath = managedPath(root, 'runs', chainId, 'read-budget.json')
+  return withFileLock(budgetPath, async () => {
+    const authority = await readBudget(root, chainId)
+    const state = authority.state
+    await assertReadBudgetActive(root, state)
+    if (state.extensions.some((item) => item.confirmationId === confirmationId)) {
+      fail('AIMLOCK_CONFIRMATION_REPLAYED', 'this budget confirmation has already been applied')
+    }
+    const updated = {
+      ...state,
+      maxFiles: state.maxFiles + additions.files,
+      maxTokenEstimate: state.maxTokenEstimate === null && additions.tokenEstimate === 0
+        ? null : (state.maxTokenEstimate ?? 0) + additions.tokenEstimate,
+      maxDurationMs: state.maxDurationMs + additions.durationMs,
+      extensions: [...state.extensions, {
+        confirmationId,
+        additions,
+        at: new Date().toISOString(),
+      }],
+    }
+    await atomicJson(authority.path, updated)
+    await appendAudit(root, { event: 'read-budget-extended', chainId,
+      confirmationId, additions })
+    return budgetView(updated)
+  })
+}
+
+export { checkCachedReadAccess, extendReadBudget, readBudgetStatus, readFileWithinBudget }

package/aimlock-runtime.mjs

@@ -209,7 +209,7 @@ const RESPONSE_SCHEMA = "aimlock.skill.response/1.1";
 const ERROR_SCHEMA = "aimlock.skill.error/1.0";
 const CONTRACT_SCHEMA = "aimlock.scope-contract/1.0";
 const COMPILER_NAME = "aimlock";
-const COMPILER_VERSION = "v7.0.35";
+const COMPILER_VERSION = "v7.0.37";
 const KEEP_ALIVE_SECONDS = 90;
 const KEEP_ALIVE_MESSAGE = "智能目标持续执行中，请勿关闭！";
 const BYPASS_LINE_BUDGET = 500;
@@ -1330,7 +1330,7 @@ async function executeRun(request) {
         localTrustedExecution: {
           requiredFor: ["filesystem-probe", "read-budget", "mutate-pass", "guarded-write", "autocoord-lease"],
           operations: ["capabilities", "probe", "reassess", "budget-init", "budget-read", "budget-status",
-            "budget-extend", "gate-issue", "gate-verify", "guarded-write"],
+            "budget-extend", "budget-auto-renew-request", "budget-auto-renew", "budget-auto-renew-stop", "gate-issue", "gate-verify", "guarded-write"],
           command: "cli-aimlock local <operation> <repositoryRoot>",
           schemaDiscovery: "cli-aimlock local capabilities <repositoryRoot>",
           boundary: "Only host writes routed through guarded-write are physically intercepted.",

package/brain-client.mjs

@@ -4,6 +4,7 @@ import { inspectBrainTarget, brainStateDirectory, saveBrainRequest } from './bra
 export { inspectBrainTarget } from './brain-client-files.mjs'
 import { resolve } from 'node:path'
 import { brainClientAuthorization, transportFailureCode } from './broker.mjs'
+import { createBrokerTransport } from './broker-transport.mjs'
 import { executeCommand } from './aimlock-chain-process.mjs'
 
 export const BRAIN_ENDPOINT = 'https://cli.tax/api/v1/brain'
@@ -45,7 +46,7 @@ export async function invokeBrain(operation, input, dependencies = {}) {
   if (Buffer.byteLength(body) > MAX_INPUT_BYTES) throw new Error('Brain request exceeds the size limit')
   let response
   try {
-    response = await (dependencies.request ?? fetch)(endpoint, {
+    response = await (dependencies.request ?? createBrokerTransport({ environment }))(endpoint, {
       method: 'POST', redirect: 'error', headers: { Authorization: authorization, 'Content-Type': 'application/json' },
       body, signal: AbortSignal.timeout(TIMEOUT_MS),
     })

package/broker-failures.mjs

@@ -0,0 +1,68 @@
+const TRANSPORT_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]{1,63}$/
+const NETWORK_TRANSPORT_ERROR = 'NETWORK_TRANSPORT'
+const SKILL_INVOCATION_ERROR = 'SKILL_INVOCATION_FAILED'
+const TRANSPORT_STAGES = new Set(['configuration', 'connecting', 'tls', 'request-sent', 'response-body', 'complete'])
+const MAX_TRANSPORT_ATTEMPTS = 3
+
+export function transportDiagnostics(value) {
+  if (!value || typeof value !== 'object' || !Number.isSafeInteger(value.attempts)
+    || value.attempts < 0 || value.attempts > MAX_TRANSPORT_ATTEMPTS
+    || !TRANSPORT_STAGES.has(value.stage) || typeof value.submitted !== 'boolean') return null
+  return { attempts: value.attempts, stage: value.stage, submitted: value.submitted }
+}
+
+export class OfficialSkillInvocationError extends Error {
+  constructor(context, request, transportCode, stage, transport) {
+    super(`${context.displayName} ${request.operation} invocation failed: network transport ${transportCode}`)
+    this.name = 'OfficialSkillInvocationError'
+    this.code = NETWORK_TRANSPORT_ERROR
+    this.requestId = request.requestId
+    this.operation = request.operation
+    const diagnostic = transportDiagnostics(transport)
+    this.stage = diagnostic ? diagnostic.stage : stage
+    if (diagnostic) this.transport = diagnostic
+    this.retryable = false
+    this.transportCode = transportCode
+  }
+}
+
+export class OfficialSkillResponseError extends Error {
+  constructor(request, stage, message) {
+    super(message)
+    this.name = 'OfficialSkillResponseError'
+    this.code = SKILL_INVOCATION_ERROR
+    this.requestId = request.requestId
+    this.operation = request.operation
+    this.stage = stage
+    this.retryable = false
+  }
+}
+
+export function transportFailureCode(error) {
+  const inspected = new Set()
+  let candidate = error
+  while (candidate && typeof candidate === 'object' && !inspected.has(candidate)) {
+    inspected.add(candidate)
+    const code = typeof candidate.code === 'string' ? candidate.code.trim() : ''
+    if (TRANSPORT_ERROR_CODE_PATTERN.test(code)) return code
+    const name = typeof candidate.name === 'string' ? candidate.name.trim() : ''
+    if (name === 'AbortError' || name === 'TimeoutError') return name
+    candidate = candidate.cause
+  }
+  return 'UNKNOWN_TRANSPORT_ERROR'
+}
+
+export function officialSkillFailureResponse(error) {
+  if (error instanceof OfficialSkillInvocationError || error instanceof OfficialSkillResponseError) {
+    const failure = { code: error.code, message: error.message, requestId: error.requestId,
+      operation: error.operation, stage: error.stage, retryable: error.retryable }
+    if (typeof error.transportCode === 'string') failure.transportCode = error.transportCode
+    if (typeof error.receiptStatus === 'string') failure.receiptStatus = error.receiptStatus
+    if (error.recovery) failure.recovery = error.recovery
+    const diagnostic = transportDiagnostics(error.transport)
+    if (diagnostic) failure.transport = diagnostic
+    return { ok: false, error: failure }
+  }
+  return { ok: false, error: { code: SKILL_INVOCATION_ERROR,
+    message: error instanceof Error ? error.message : 'Skill invocation failed', retryable: false } }
+}

package/broker-recovery.mjs

@@ -0,0 +1,110 @@
+import { OfficialSkillResponseError, transportFailureCode, transportDiagnostics } from './broker-failures.mjs'
+
+export const SKILL_RECEIPT_SCHEMA = 'skill-runtime-receipt/1.0'
+export const SKILL_RECEIPT_HEADER = 'X-Skill-Receipt'
+const RECEIPT_API_PATH = '/api/v1/skill-invocations'
+const QUERY_TIMEOUT_MS = 5_000
+const QUERY_ATTEMPTS = 3
+const QUERY_DELAY_MS = 250
+const TERMINAL_STATUSES = new Set(['completed', 'failed'])
+const RECEIPT_STATUSES = new Set([...TERMINAL_STATUSES, 'pending', 'expired', 'not-found'])
+
+class ReceiptRecoveryError extends OfficialSkillResponseError {
+  constructor(request, status, message, transportCode) {
+    super(request, 'receipt-query', message)
+    this.name = 'ReceiptRecoveryError'
+    this.code = 'SKILL_INVOCATION_UNCERTAIN'
+    this.receiptStatus = status
+    if (transportCode) this.transportCode = transportCode
+  }
+}
+
+function validateReceipt(response, payload, context, request) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+    || payload.schemaVersion !== SKILL_RECEIPT_SCHEMA || payload.runtimeCode !== context.runtimeCode
+    || payload.requestId !== request.requestId || !RECEIPT_STATUSES.has(payload.status)) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Receipt query returned invalid or mismatched execution identity')
+  }
+  const expectedHttpStatus = payload.status === 'pending' ? 202
+    : payload.status === 'expired' ? 410 : payload.status === 'not-found' ? 404 : 200
+  if (response.status !== expectedHttpStatus || (payload.status !== 'not-found'
+    && !Number.isFinite(Date.parse(payload.expiresAt)))) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Receipt status or expiration metadata is invalid')
+  }
+  if (TERMINAL_STATUSES.has(payload.status) && (!Number.isInteger(payload.httpStatus)
+    || payload.httpStatus < 100 || payload.httpStatus > 599 || !payload.response
+    || typeof payload.response !== 'object' || Array.isArray(payload.response))) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Receipt has no valid recorded HTTP result')
+  }
+  if (payload.status === 'failed' && (payload.httpStatus < 400
+    || typeof payload.response.error !== 'string' || typeof payload.response.code !== 'string')) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Failed receipt has no valid recorded error')
+  }
+  return payload
+}
+
+async function fetchReceipt(context, request, dependencies, authorization) {
+  const endpoint = new URL(context.endpoint)
+  const path = `${RECEIPT_API_PATH}/${encodeURIComponent(context.runtimeCode)}/${encodeURIComponent(request.requestId)}`
+  let response
+  let payload
+  try {
+    response = await dependencies.request(new URL(path, endpoint.origin).href, {
+      method: 'GET', redirect: 'error', headers: { Authorization: authorization },
+      signal: AbortSignal.timeout(QUERY_TIMEOUT_MS),
+    })
+  } catch (error) {
+    throw new ReceiptRecoveryError(request, 'query-failed', 'Receipt query failed; execution outcome remains uncertain',
+      transportFailureCode(error))
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new ReceiptRecoveryError(request, 'unauthorized', `Receipt query authorization failed: HTTP ${response.status}`)
+  }
+  try {
+    payload = await response.json()
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new ReceiptRecoveryError(request, 'invalid', 'Receipt query returned invalid JSON')
+    throw new ReceiptRecoveryError(request, 'query-failed', 'Receipt body was interrupted; execution outcome remains uncertain',
+      transportFailureCode(error))
+  }
+  return { receipt: validateReceipt(response, payload, context, request), transport: transportDiagnostics(response.transport) }
+}
+
+function receiptOutcome(receipt, context, request, validateInvocation, transport) {
+  if (receipt.status === 'failed') {
+    throw new OfficialSkillResponseError(request, 'http-response',
+      `${context.displayName} ${request.operation} failed: HTTP ${receipt.httpStatus} (recorded receipt)`)
+  }
+  if (receipt.httpStatus !== 200 || receipt.response.ok !== true) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Completed receipt does not contain a successful HTTP response')
+  }
+  try {
+    const invocation = validateInvocation(receipt.response)
+    return { ...invocation, recovery: { status: 'completed', requestId: request.requestId },
+      ...(transport ? { transport } : {}) }
+  } catch (error) {
+    throw new OfficialSkillResponseError(request, 'receipt-validation',
+      error instanceof Error ? error.message : 'Recorded skill response validation failed')
+  }
+}
+
+export async function queryOfficialSkillReceipt(context, request, dependencies, authorization, validateInvocation) {
+  let lastFailure
+  for (let attempt = 0; attempt < QUERY_ATTEMPTS; attempt += 1) {
+    if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, QUERY_DELAY_MS))
+    let fetched
+    try {
+      fetched = await fetchReceipt(context, request, dependencies, authorization)
+    } catch (error) {
+      if (!(error instanceof ReceiptRecoveryError) || error.receiptStatus !== 'query-failed') throw error
+      lastFailure = error
+      continue
+    }
+    const { receipt, transport } = fetched
+    if (TERMINAL_STATUSES.has(receipt.status)) return receiptOutcome(receipt, context, request, validateInvocation, transport)
+    lastFailure = new ReceiptRecoveryError(request, receipt.status,
+      `Invocation outcome is ${receipt.status}; query this requestId again before any new execution`)
+    if (receipt.status !== 'pending') throw lastFailure
+  }
+  throw lastFailure
+}

package/broker-transport-attempt.mjs

@@ -0,0 +1,86 @@
+function responseValue(message, chunks, state) {
+  const headers = new Headers()
+  for (let index = 0; index < message.rawHeaders.length; index += 2) {
+    headers.append(message.rawHeaders[index], message.rawHeaders[index + 1])
+  }
+  const status = message.statusCode
+  if (!Number.isInteger(status) || status < 200 || status > 599) throw new Error('BROKER_RESPONSE_STATUS_INVALID')
+  const body = Buffer.concat(chunks)
+  const emptyBody = status === 204 || status === 205 || status === 304
+  const response = new Response(emptyBody ? null : body, { status, headers })
+  response.transport = Object.freeze({ ...state, stage: 'complete' })
+  return response
+}
+
+/** No write/end/flushHeaders is permitted before the destination TLS socket is authenticated. */
+export function attemptBrokerHttps(input, dependencies) {
+  return new Promise((resolve, reject) => {
+    const { state, signal, failure } = dependencies
+    const agent = dependencies.createAgent({ ...input.agentOptions, keepAlive: false, maxSockets: 1, maxCachedSessions: 0 })
+    let request
+    let settled = false
+    let connectTimer
+    const cleanup = () => {
+      clearTimeout(connectTimer)
+      signal.removeEventListener('abort', abort)
+      agent.destroy()
+    }
+    const finishError = code => {
+      if (settled) return
+      settled = true
+      const error = failure(code)
+      request?.destroy()
+      cleanup()
+      reject(error)
+    }
+    const abort = () => finishError('ABORT_ERR')
+    const receive = response => {
+      state.stage = 'response-body'
+      const chunks = []
+      let bytes = 0
+      response.on('error', error => finishError(error.code))
+      response.on('aborted', () => finishError('BROKER_RESPONSE_TRUNCATED'))
+      response.on('close', () => { if (!response.complete) finishError('BROKER_RESPONSE_TRUNCATED') })
+      response.on('data', chunk => {
+        bytes += chunk.length
+        if (bytes > dependencies.maxResponseBytes) finishError('BROKER_RESPONSE_TOO_LARGE')
+        else chunks.push(chunk)
+      })
+      response.on('end', () => {
+        if (settled) return
+        if (!response.complete) return finishError('BROKER_RESPONSE_TRUNCATED')
+        const coding = response.headers['content-encoding']
+        if (coding !== undefined && coding !== 'identity') return finishError('BROKER_RESPONSE_ENCODING_UNSUPPORTED')
+        let value
+        try { value = responseValue(response, chunks, state) }
+        catch (error) { return finishError(error.message) }
+        settled = true
+        cleanup()
+        resolve(value)
+      })
+    }
+    try {
+      request = dependencies.request(input.target, { method: input.method, headers: input.headers, agent,
+        rejectUnauthorized: true }, receive)
+      request.on('error', error => finishError(error.code))
+      request.once('socket', socket => {
+        state.stage = 'tls'
+        const send = () => {
+          if (settled) return
+          if (signal.aborted) return abort()
+          if (socket.encrypted !== true || socket.authorized !== true) return finishError('BROKER_TLS_UNAUTHORIZED')
+          clearTimeout(connectTimer)
+          state.stage = 'request-sent'
+          state.submitted = true
+          try { request.end(input.body) } catch (error) { finishError(error.code) }
+        }
+        if (socket.encrypted === true && socket.authorized === true) send()
+        else socket.once('secureConnect', send)
+      })
+      connectTimer = setTimeout(() => finishError('ETIMEDOUT'), dependencies.connectTimeoutMs)
+      connectTimer.unref()
+      signal.addEventListener('abort', abort, { once: true })
+      if (signal.aborted) abort()
+    } catch (error) { finishError(error.code) }
+  })
+}

package/broker-transport.mjs

@@ -0,0 +1,107 @@
+import { Agent, request as httpsRequest } from 'node:https'
+import { setTimeout as delay } from 'node:timers/promises'
+import { attemptBrokerHttps } from './broker-transport-attempt.mjs'
+
+export const BROKER_TRANSPORT_TIMEOUT_MS = 120_000
+export const BROKER_TRANSPORT_CONNECT_TIMEOUT_MS = 8_000
+export const BROKER_TRANSPORT_MAX_ATTEMPTS = 3
+export const BROKER_TRANSPORT_MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+const RETRY_DELAY_MS = 150
+const PROXY_KEYS = ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy', 'NO_PROXY', 'no_proxy']
+const TRANSIENT_CODES = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ENETUNREACH', 'EHOSTUNREACH'])
+const CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,79}$/
+
+export class BrokerTransportError extends Error {
+  constructor(code, transport) {
+    const safeCode = typeof code === 'string' && CODE_PATTERN.test(code) ? code : 'BROKER_TRANSPORT_FAILED'
+    super(`HTTPS broker transport failed (${safeCode})`)
+    this.name = 'BrokerTransportError'
+    this.code = safeCode
+    this.transport = Object.freeze({ ...transport })
+  }
+}
+
+/** Native Agent proxyEnv: https://nodejs.org/api/https.html#new-agentoptions */
+export function brokerProxyEnvironment(environment, nodeVersion = process.versions.node) {
+  const proxyEnv = {}
+  for (const key of PROXY_KEYS) {
+    if (environment[key] !== undefined) {
+      if (typeof environment[key] !== 'string') throw new Error('BROKER_PROXY_ENV_INVALID')
+      proxyEnv[key] = environment[key]
+    }
+  }
+  const hasProxy = PROXY_KEYS.slice(0, 4).some(key => typeof proxyEnv[key] === 'string' && proxyEnv[key].trim())
+  const version = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(nodeVersion)
+  if (!version) throw new Error('BROKER_NODE_VERSION_INVALID')
+  const major = Number(version[1]), minor = Number(version[2])
+  const supportsProxy = major > 24 || major === 24 && minor >= 5 || major === 22 && minor >= 21
+  if (hasProxy && !supportsProxy) throw new Error('BROKER_PROXY_UNSUPPORTED_NODE')
+  for (const key of PROXY_KEYS.slice(0, 4)) {
+    if (!proxyEnv[key]) continue
+    let proxy
+    try { proxy = new URL(proxyEnv[key]) } catch { throw new Error('BROKER_PROXY_ENV_INVALID') }
+    if (!['http:', 'https:'].includes(proxy.protocol)) throw new Error('BROKER_PROXY_ENV_INVALID')
+  }
+  return supportsProxy ? { proxyEnv } : {}
+}
+
+function requestInput(url, options) {
+  const target = new URL(url)
+  if (target.protocol !== 'https:' || target.username || target.password) throw new Error('BROKER_HTTPS_REQUIRED')
+  const method = options.method === undefined ? 'GET' : options.method
+  if (typeof method !== 'string' || !/^[A-Z]+$/.test(method)) throw new Error('BROKER_METHOD_INVALID')
+  const headers = new Headers(options.headers)
+  headers.set('accept-encoding', 'identity')
+  const source = options.body
+  if (source !== undefined && source !== null && typeof source !== 'string' && !(source instanceof Uint8Array)) {
+    throw new Error('BROKER_BODY_INVALID')
+  }
+  const body = source === undefined || source === null ? undefined : Buffer.from(source)
+  if (body !== undefined) headers.set('content-length', String(body.length))
+  return { target, method, headers: Object.fromEntries(headers), body }
+}
+
+function overallSignal(external) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(external.reason)
+  if (external?.aborted) controller.abort(external.reason)
+  else external?.addEventListener('abort', abort, { once: true })
+  const timer = setTimeout(() => controller.abort(new Error('ETIMEDOUT')), BROKER_TRANSPORT_TIMEOUT_MS)
+  timer.unref()
+  return { signal: controller.signal, cleanup() {
+    clearTimeout(timer)
+    external?.removeEventListener('abort', abort)
+  } }
+}
+
+/** Dependencies support isolated native TLS tests; production callers supply only environment. */
+export function createBrokerTransport({ environment = process.env, request = httpsRequest,
+  createAgent = options => new Agent(options), nodeVersion = process.versions.node } = {}) {
+  return async function brokerRequest(url, options = {}) {
+    const state = { attempts: 0, stage: 'configuration', submitted: false }
+    let configured
+    try { configured = { ...requestInput(url, options), agentOptions: brokerProxyEnvironment(environment, nodeVersion) } }
+    catch (error) { throw new BrokerTransportError(error.message, state) }
+    const overall = overallSignal(options.signal)
+    try {
+      for (let number = 1; number <= BROKER_TRANSPORT_MAX_ATTEMPTS; number += 1) {
+        if (overall.signal.aborted) throw new BrokerTransportError('ABORT_ERR', state)
+        state.attempts = number
+        state.stage = 'connecting'
+        try {
+          return await attemptBrokerHttps(configured, { request, createAgent, signal: overall.signal, state,
+            connectTimeoutMs: BROKER_TRANSPORT_CONNECT_TIMEOUT_MS, maxResponseBytes: BROKER_TRANSPORT_MAX_RESPONSE_BYTES,
+            failure: code => new BrokerTransportError(code, state) })
+        } catch (error) {
+          const failure = error instanceof BrokerTransportError ? error : new BrokerTransportError(error.code, state)
+          const reconnect = !state.submitted && !overall.signal.aborted && TRANSIENT_CODES.has(failure.code)
+            && number < BROKER_TRANSPORT_MAX_ATTEMPTS
+          if (!reconnect) throw failure
+          try { await delay(RETRY_DELAY_MS, undefined, { signal: overall.signal }) }
+          catch { throw new BrokerTransportError('ABORT_ERR', state) }
+        }
+      }
+      throw new BrokerTransportError('BROKER_TRANSPORT_ATTEMPTS_EXHAUSTED', state)
+    } finally { overall.cleanup() }
+  }
+}