@agentsquared/cli 1.0.0

package/lib/runtime/report.mjs

@@ -0,0 +1,302 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+import { defaultReceiptFile } from '../shared/paths.mjs'
+import { currentRuntimeRevision } from '../gateway/state.mjs'
+import { loadRuntimeKeyBundle, publicKeyFingerprint } from './keys.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const PACKAGE_ROOT = path.resolve(__dirname, '../..')
+const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, 'package.json')
+
+function clean(value) {
+  return `${value ?? ''}`.trim()
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function runGit(args = []) {
+  const result = spawnSync('git', args, {
+    cwd: PACKAGE_ROOT,
+    encoding: 'utf8'
+  })
+  if (result.status !== 0) {
+    return { ok: false, stdout: clean(result.stdout), stderr: clean(result.stderr) }
+  }
+  return { ok: true, stdout: clean(result.stdout), stderr: clean(result.stderr) }
+}
+
+function parseGatewayPort(gatewayBase = '') {
+  try {
+    return new URL(gatewayBase).port || ''
+  } catch {
+    return ''
+  }
+}
+
+function parseHumanName(agentId = '') {
+  const cleaned = clean(agentId)
+  const at = cleaned.lastIndexOf('@')
+  return at >= 0 ? cleaned.slice(at + 1) : ''
+}
+
+function latestStatusLabel(status = '') {
+  switch (clean(status)) {
+    case 'up-to-date':
+      return 'up to date'
+    case 'ahead':
+      return 'ahead of upstream'
+    case 'behind':
+      return 'behind upstream'
+    case 'diverged':
+      return 'diverged from upstream'
+    default:
+      return 'unknown'
+  }
+}
+
+function latestStatus() {
+  const upstream = runGit(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+  if (!upstream.ok || !clean(upstream.stdout)) {
+    return {
+      status: 'unknown',
+      detail: 'No upstream tracking branch was available from local git metadata.'
+    }
+  }
+  const counts = runGit(['rev-list', '--left-right', '--count', `HEAD...${clean(upstream.stdout)}`])
+  if (!counts.ok) {
+    return {
+      status: 'unknown',
+      detail: 'Upstream comparison was unavailable from local git metadata.'
+    }
+  }
+  const [aheadRaw, behindRaw] = clean(counts.stdout).split(/\s+/)
+  const ahead = Number.parseInt(aheadRaw ?? '0', 10) || 0
+  const behind = Number.parseInt(behindRaw ?? '0', 10) || 0
+  if (ahead === 0 && behind === 0) {
+    return { status: 'up-to-date', detail: `Local HEAD matches ${clean(upstream.stdout)}.` }
+  }
+  if (ahead > 0 && behind === 0) {
+    return { status: 'ahead', detail: `Local HEAD is ahead of ${clean(upstream.stdout)} by ${ahead} commit(s).` }
+  }
+  if (ahead === 0 && behind > 0) {
+    return { status: 'behind', detail: `Local HEAD is behind ${clean(upstream.stdout)} by ${behind} commit(s).` }
+  }
+  return { status: 'diverged', detail: `Local HEAD has diverged from ${clean(upstream.stdout)}.` }
+}
+
+export function currentRuntimeMetadata() {
+  const pkg = readJson(PACKAGE_JSON_PATH) ?? {}
+  const repo = runGit(['remote', 'get-url', 'origin'])
+  const commit = runGit(['rev-parse', '--short=12', 'HEAD'])
+  return {
+    packageName: clean(pkg.name) || '@agentsquared/cli',
+    packageVersion: clean(pkg.version) || 'unknown',
+    gitCommit: commit.ok ? clean(commit.stdout) : 'unknown',
+    repoUrl: repo.ok ? clean(repo.stdout) : 'https://github.com/AgentSquaredNet/agentsquared-cli.git',
+    runtimeRevision: currentRuntimeRevision(),
+    latest: latestStatus()
+  }
+}
+
+function receiptFilePath(keyFile, agentId) {
+  return defaultReceiptFile(keyFile, agentId)
+}
+
+export function loadReceiptForAgent({ keyFile = '', agentId = '' } = {}) {
+  const filePath = receiptFilePath(keyFile, agentId)
+  const receipt = readJson(filePath)
+  return {
+    filePath,
+    receipt
+  }
+}
+
+function summarizeUpdateCommits(previousGitCommit = '', currentGitCommit = '') {
+  const from = clean(previousGitCommit)
+  const to = clean(currentGitCommit)
+  if (!from || !to || from === to) {
+    return []
+  }
+  const log = runGit(['log', '--oneline', '--no-merges', `${from}..${to}`])
+  if (!log.ok || !clean(log.stdout)) {
+    return []
+  }
+  return clean(log.stdout)
+    .split('\n')
+    .map((line) => clean(line.replace(/^[0-9a-f]+\s+/, '')))
+    .filter(Boolean)
+    .slice(0, 6)
+}
+
+export function buildRuntimeUpdateSection({
+  previousState = null,
+  currentRuntime = currentRuntimeMetadata()
+} = {}) {
+  const previous = {
+    packageVersion: clean(previousState?.runtimePackageVersion || previousState?.skillsPackageVersion) || 'unknown',
+    gitCommit: clean(previousState?.runtimeGitCommit || previousState?.skillsGitCommit) || 'unknown',
+    runtimeRevision: clean(previousState?.runtimeRevision) || 'unknown'
+  }
+  const current = {
+    packageVersion: clean(currentRuntime.packageVersion) || 'unknown',
+    gitCommit: clean(currentRuntime.gitCommit) || 'unknown',
+    runtimeRevision: clean(currentRuntime.runtimeRevision) || 'unknown'
+  }
+  const changed = previous.gitCommit !== 'unknown' && current.gitCommit !== 'unknown'
+    ? previous.gitCommit !== current.gitCommit
+    : previous.runtimeRevision !== 'unknown' && current.runtimeRevision !== 'unknown' && previous.runtimeRevision !== current.runtimeRevision
+  const initialInstall = previous.gitCommit === 'unknown' && previous.runtimeRevision === 'unknown'
+  return {
+    changed,
+    initialInstall,
+    from: previous,
+    to: current,
+    capabilityNotes: summarizeUpdateCommits(previous.gitCommit, current.gitCommit)
+  }
+}
+
+function extractRelayHealth(gatewayHealth = null) {
+  const relayControl = gatewayHealth?.relayControl ?? null
+  if (typeof relayControl?.ok === 'boolean') {
+    return {
+      ok: relayControl.ok,
+      detail: clean(relayControl.detail)
+        || (relayControl.ok
+          ? 'Relay control-plane handshake succeeded.'
+          : 'Relay control-plane handshake failed.')
+    }
+  }
+  const startupRelay = Boolean(gatewayHealth?.startupChecks?.relay?.ok)
+  const relayAddrs = Array.isArray(gatewayHealth?.relayAddrs) ? gatewayHealth.relayAddrs : []
+  return {
+    ok: startupRelay && relayAddrs.length > 0,
+    detail: startupRelay
+      ? (relayAddrs.length > 0 ? 'Relay startup check passed and relay-backed addresses are present.' : 'Relay startup check passed but no relay-backed addresses were reported yet.')
+      : clean(gatewayHealth?.startupChecks?.relay?.error) || 'Relay startup check did not pass.'
+  }
+}
+
+function extractHostRuntimeHealth(gatewayHealth = null, detectedHostRuntime = null) {
+  const resolved = clean(detectedHostRuntime?.resolved) || 'none'
+  const startupHost = Boolean(gatewayHealth?.startupChecks?.hostRuntime?.ok)
+  return {
+    ok: resolved === 'none' ? true : startupHost,
+    detail: resolved === 'none'
+      ? 'No host runtime adapter is active.'
+      : (startupHost
+          ? `${resolved} host adapter startup check passed.`
+          : clean(gatewayHealth?.startupChecks?.hostRuntime?.error) || `${resolved} host adapter startup check failed.`)
+  }
+}
+
+export function buildStandardRuntimeReport({
+  apiBase = 'https://api.agentsquared.net',
+  agentId = '',
+  keyFile = '',
+  detectedHostRuntime = null,
+  registration = null,
+  gateway = null,
+  gatewayHealth = null,
+  previousState = null
+} = {}) {
+  const currentRuntime = currentRuntimeMetadata()
+  let keyBundle = null
+  if (keyFile) {
+    try {
+      keyBundle = loadRuntimeKeyBundle(keyFile)
+    } catch {
+      keyBundle = null
+    }
+  }
+  const receiptResult = loadReceiptForAgent({ keyFile, agentId })
+  const receipt = receiptResult.receipt ?? {}
+  const registrationFacts = registration ?? receipt ?? {}
+  const relayStatus = extractRelayHealth(gatewayHealth)
+  const hostStatus = extractHostRuntimeHealth(gatewayHealth, detectedHostRuntime)
+  const effectiveGatewayHealth = gatewayHealth ?? gateway?.health ?? null
+  return {
+    overall: {
+      humanId: registrationFacts.humanId ?? null,
+      humanName: clean(registrationFacts.humanName) || parseHumanName(registrationFacts.fullName || agentId),
+      agentId: clean(registrationFacts.fullName || agentId),
+      chainAgentId: clean(registrationFacts.chainAgentId),
+      publicKey: clean(registrationFacts.publicKey || keyBundle?.publicKey),
+      publicKeyFingerprint: keyBundle ? publicKeyFingerprint(keyBundle) : '',
+      relayApiBase: clean(apiBase) || 'https://api.agentsquared.net',
+      runtimeRepoUrl: clean(currentRuntime.repoUrl),
+      runtimePackageVersion: clean(currentRuntime.packageVersion),
+      runtimeGitCommit: clean(currentRuntime.gitCommit),
+      runtimeRevision: clean(currentRuntime.runtimeRevision),
+      latestStatus: currentRuntime.latest,
+      hostRuntime: clean(detectedHostRuntime?.resolved) || 'none'
+    },
+    runtimeUpdate: buildRuntimeUpdateSection({
+      previousState,
+      currentRuntime
+    }),
+    gatewayStatus: {
+      runtimeRevision: clean(currentRuntime.runtimeRevision),
+      runtimeGitCommit: clean(currentRuntime.gitCommit),
+      runtimePackageVersion: clean(currentRuntime.packageVersion),
+      latestStatus: currentRuntime.latest,
+      gatewayBase: clean(gateway?.gatewayBase || effectiveGatewayHealth?.gatewayBase),
+      listeningPort: parseGatewayPort(clean(gateway?.gatewayBase || effectiveGatewayHealth?.gatewayBase)),
+      peerId: clean(effectiveGatewayHealth?.peerId),
+      started: Boolean(gateway?.started ?? effectiveGatewayHealth),
+      relay: relayStatus,
+      hostRuntime: hostStatus,
+      startupChecks: effectiveGatewayHealth?.startupChecks ?? null
+    }
+  }
+}
+
+export function buildStandardRuntimeOwnerLines(report = {}) {
+  const overall = report.overall ?? {}
+  const runtimeUpdate = report.runtimeUpdate ?? {}
+  const gatewayStatus = report.gatewayStatus ?? {}
+  const lines = [
+    'AgentSquared standard runtime report:',
+    `Overall: human=${clean(overall.humanName) || 'unknown'}${overall.humanId != null ? ` (id ${overall.humanId})` : ''}, agent=${clean(overall.agentId) || 'unknown'}, host mode=${clean(overall.hostRuntime) || 'none'}.`,
+    `Overall: public key=${clean(overall.publicKey) || 'unknown'}, fingerprint=${clean(overall.publicKeyFingerprint) || 'unknown'}.`,
+    `Overall: official relay=${clean(overall.relayApiBase) || 'unknown'}, runtime repo=${clean(overall.runtimeRepoUrl) || 'unknown'}.`,
+    `Overall: current package=${clean(overall.runtimePackageVersion) || 'unknown'}, git=${clean(overall.runtimeGitCommit) || 'unknown'}, runtimeRevision=${clean(overall.runtimeRevision) || 'unknown'}, version status=${latestStatusLabel(overall.latestStatus?.status)}.`
+  ]
+
+  if (runtimeUpdate.initialInstall) {
+    lines.push('Runtime update: this is the first standard runtime report for the current local AgentSquared setup, so there is no previous version to compare against.')
+  } else if (runtimeUpdate.changed) {
+    lines.push(
+      `Runtime update: upgraded from ${clean(runtimeUpdate.from?.gitCommit) || 'unknown'} (package ${clean(runtimeUpdate.from?.packageVersion) || 'unknown'}) to ${clean(runtimeUpdate.to?.gitCommit) || 'unknown'} (package ${clean(runtimeUpdate.to?.packageVersion) || 'unknown'}).`
+    )
+    if (Array.isArray(runtimeUpdate.capabilityNotes) && runtimeUpdate.capabilityNotes.length > 0) {
+      lines.push(`Runtime update: capability changes include ${runtimeUpdate.capabilityNotes.join('; ')}.`)
+    } else {
+      lines.push('Runtime update: local git metadata did not include a concise capability summary.')
+    }
+  } else {
+    lines.push(
+      `Runtime update: no version change was detected. Current package=${clean(runtimeUpdate.to?.packageVersion) || 'unknown'}, git=${clean(runtimeUpdate.to?.gitCommit) || 'unknown'}.`
+    )
+  }
+
+  lines.push(
+    `A2 gateway status: running on package=${clean(gatewayStatus.runtimePackageVersion) || 'unknown'}, git=${clean(gatewayStatus.runtimeGitCommit) || 'unknown'}, version status=${latestStatusLabel(gatewayStatus.latestStatus?.status)}.`
+  )
+  lines.push(
+    `A2 gateway status: listening port=${clean(gatewayStatus.listeningPort) || 'unknown'}, Peer ID=${clean(gatewayStatus.peerId) || 'unknown'}.`
+  )
+  lines.push(
+    `A2 gateway status: relay communication is ${gatewayStatus.relay?.ok ? 'healthy' : 'unhealthy'} (${clean(gatewayStatus.relay?.detail) || 'no detail'}), host communication is ${gatewayStatus.hostRuntime?.ok ? 'healthy' : 'unhealthy'} (${clean(gatewayStatus.hostRuntime?.detail) || 'no detail'}).`
+  )
+  return lines
+}

package/lib/runtime/safety.mjs

@@ -0,0 +1,72 @@
+function clean(value) {
+  return `${value ?? ''}`.trim()
+}
+
+function stripDelimitedBlock(text = '', begin = '', end = '') {
+  const start = text.indexOf(begin)
+  const finish = text.indexOf(end)
+  if (start < 0 || finish < start) {
+    return text
+  }
+  return `${text.slice(0, start)}${text.slice(finish + end.length)}`.trim()
+}
+
+function stripAgentSquaredTransportText(text = '') {
+  let value = clean(text)
+  if (!value) {
+    return value
+  }
+  value = stripDelimitedBlock(value, 'BEGIN_A2_OWNER_REQUEST', 'END_A2_OWNER_REQUEST')
+  const strippedLines = value
+    .split('\n')
+    .filter((line) => {
+      const normalized = clean(line)
+      if (!normalized) {
+        return true
+      }
+      if (normalized.includes('[AgentSquared]')) {
+        return false
+      }
+      if (normalized === 'This is an AgentSquared private agent message.') {
+        return false
+      }
+      if (normalized === 'Please read the AgentSquared official skill before sending or replying through AgentSquared.') {
+        return false
+      }
+      if (/^(From|To|Sent At \(UTC\)|Owner Request|Local Skill Snapshot):/i.test(normalized)) {
+        return false
+      }
+      if (normalized === 'Please reply to me for my owner.') {
+        return false
+      }
+      return true
+    })
+  value = strippedLines.join('\n').replace(/\n{3,}/g, '\n\n').trim()
+  return value
+}
+
+// This module is intentionally narrow.
+// The main safety decision path lives in the host runtime triage prompt.
+// Local code here is only a lightweight outbound redaction layer.
+const SECRET_PATTERNS = [
+  /-----begin [a-z0-9 _-]*private key-----/i,
+  /\bsk-[a-z0-9]{16,}\b/i,
+  /\bghp_[a-z0-9]{20,}\b/i,
+  /\bxox[baprs]-[a-z0-9-]{10,}\b/i,
+  /\b(?:api|access|refresh|bearer|auth(?:orization)?) token\b/i,
+  /\bseed phrase\b/i,
+  /\bprivate key\b/i,
+  /\bm(nemonic)?\b.{0,20}\bphrase\b/i
+]
+
+export function scrubOutboundText(text = '') {
+  let value = clean(text)
+  if (!value) {
+    return value
+  }
+  value = stripAgentSquaredTransportText(value)
+  for (const pattern of SECRET_PATTERNS) {
+    value = value.replace(pattern, '[REDACTED]')
+  }
+  return value
+}

package/lib/shared/paths.mjs

@@ -0,0 +1,155 @@
+import path from 'node:path'
+
+function clean(value) {
+  return `${value ?? ''}`.trim()
+}
+
+export function safeAgentId(value) {
+  return clean(value).replace(/[^a-zA-Z0-9_.-]+/g, '_')
+}
+
+export function resolveUserPath(inputPath) {
+  return path.resolve(`${inputPath ?? ''}`.replace(/^~(?=$|\/|\\)/, process.env.HOME || '~'))
+}
+
+export function resolveHostWorkspaceDir(detectedHostRuntime = null) {
+  return clean(
+    detectedHostRuntime?.workspaceDir
+      ?? detectedHostRuntime?.overviewStatus?.agents?.agents?.find?.((item) => clean(item?.workspaceDir))?.workspaceDir
+      ?? detectedHostRuntime?.overviewStatus?.agents?.agents?.[0]?.workspaceDir
+  )
+}
+
+export function resolveAgentSquaredDir(args = {}, detectedHostRuntime = null) {
+  const explicit = clean(args?.['agentsquared-dir'])
+  if (explicit) {
+    return resolveUserPath(explicit)
+  }
+  const workspaceDir = resolveHostWorkspaceDir(detectedHostRuntime)
+  if (workspaceDir) {
+    return path.join(resolveUserPath(workspaceDir), 'AgentSquared')
+  }
+  if (process.env.HOME) {
+    return path.join(process.env.HOME, '.openclaw', 'workspace', 'AgentSquared')
+  }
+  return path.join(process.cwd(), 'AgentSquared')
+}
+
+export function resolveAgentScopeDir(agentNameOrId, args = {}, detectedHostRuntime = null) {
+  const safeId = safeAgentId(agentNameOrId)
+  if (!safeId) {
+    throw new Error('agentNameOrId is required to derive the AgentSquared agent scope directory')
+  }
+  return path.join(resolveAgentSquaredDir(args, detectedHostRuntime), safeId)
+}
+
+export function inferAgentSquaredScopeFromArtifact(filePath) {
+  const resolved = resolveUserPath(filePath)
+  const name = path.basename(resolved)
+  const parent = path.dirname(resolved)
+  const grandparent = path.dirname(parent)
+
+  if ((name === 'runtime-key.json' || name === 'registration-receipt.json' || name === 'onboarding-summary.json') && path.basename(parent) === 'identity') {
+    return grandparent
+  }
+  if ((name === 'gateway.json' || name === 'gateway-peer.key' || name === 'gateway.log' || name === 'openclaw-device.json' || name === 'openclaw-device-auth.json') && path.basename(parent) === 'runtime') {
+    return grandparent
+  }
+  if ((name === 'index.json' || name === 'inbox.md') && path.basename(parent) === 'inbox') {
+    return grandparent
+  }
+  if (path.basename(parent) === 'entries' && path.basename(grandparent) === 'inbox') {
+    return path.dirname(grandparent)
+  }
+  if (name === 'AGENT_RELATIONSHIPS.md') {
+    return parent
+  }
+  return ''
+}
+
+export function resolveAgentScopeDirFromKeyFile(keyFile) {
+  const scopeDir = inferAgentSquaredScopeFromArtifact(keyFile)
+  if (!scopeDir || path.basename(resolveUserPath(keyFile)) !== 'runtime-key.json') {
+    throw new Error(`keyFile is not inside the AgentSquared multi-agent layout: ${resolveUserPath(keyFile)}`)
+  }
+  return scopeDir
+}
+
+export function identityDirForAgentScope(scopeDir) {
+  return path.join(resolveUserPath(scopeDir), 'identity')
+}
+
+export function runtimeDirForAgentScope(scopeDir) {
+  return path.join(resolveUserPath(scopeDir), 'runtime')
+}
+
+export function inboxDirForAgentScope(scopeDir) {
+  return path.join(resolveUserPath(scopeDir), 'inbox')
+}
+
+export function defaultRuntimeKeyFile(agentName, args = {}, detectedHostRuntime = null) {
+  return path.join(identityDirForAgentScope(resolveAgentScopeDir(agentName, args, detectedHostRuntime)), 'runtime-key.json')
+}
+
+function scopeDirForKeyAndAgent(keyFile, agentId = '') {
+  try {
+    return resolveAgentScopeDirFromKeyFile(keyFile)
+  } catch {
+    const safeId = safeAgentId(agentId)
+    if (!safeId) {
+      throw new Error(`Cannot derive AgentSquared scope directory from keyFile without agentId: ${resolveUserPath(keyFile)}`)
+    }
+    const keyDir = path.dirname(resolveUserPath(keyFile))
+    const identityDir = path.basename(keyDir) === 'identity' ? keyDir : path.join(keyDir, 'identity')
+    return path.dirname(identityDir)
+  }
+}
+
+export function defaultGatewayStateFile(keyFile, agentId) {
+  if (!keyFile || !agentId) {
+    throw new Error('keyFile and agentId are required to derive the gateway state file')
+  }
+  return path.join(runtimeDirForAgentScope(scopeDirForKeyAndAgent(keyFile, agentId)), 'gateway.json')
+}
+
+export function defaultPeerKeyFile(keyFile, agentId) {
+  if (!keyFile || !agentId) {
+    throw new Error('keyFile and agentId are required to derive the peer key file')
+  }
+  return path.join(runtimeDirForAgentScope(scopeDirForKeyAndAgent(keyFile, agentId)), 'gateway-peer.key')
+}
+
+export function defaultGatewayLogFile(keyFile, agentId) {
+  if (!keyFile || !agentId) {
+    throw new Error('keyFile and agentId are required to derive the gateway log file')
+  }
+  return path.join(runtimeDirForAgentScope(scopeDirForKeyAndAgent(keyFile, agentId)), 'gateway.log')
+}
+
+export function defaultOpenClawStateDir(keyFile, agentId) {
+  if (!keyFile || !agentId) {
+    throw new Error('keyFile and agentId are required to derive the OpenClaw state directory')
+  }
+  return runtimeDirForAgentScope(scopeDirForKeyAndAgent(keyFile, agentId))
+}
+
+export function defaultInboxDir(keyFile, agentId) {
+  if (!keyFile || !agentId) {
+    throw new Error('keyFile and agentId are required to derive the inbox directory')
+  }
+  return inboxDirForAgentScope(scopeDirForKeyAndAgent(keyFile, agentId))
+}
+
+export function defaultReceiptFile(keyFile, fullName = '') {
+  if (!keyFile) {
+    throw new Error('keyFile is required to derive the receipt file')
+  }
+  return path.join(identityDirForAgentScope(scopeDirForKeyAndAgent(keyFile, fullName)), 'registration-receipt.json')
+}
+
+export function defaultOnboardingSummaryFile(keyFile, fullName = '') {
+  if (!keyFile) {
+    throw new Error('keyFile is required to derive the onboarding summary file')
+  }
+  return path.join(identityDirForAgentScope(scopeDirForKeyAndAgent(keyFile, fullName)), 'onboarding-summary.json')
+}

package/lib/shared/primitives.mjs

@@ -0,0 +1,43 @@
+import crypto from 'node:crypto'
+
+export function parseArgs(argv) {
+  const out = { _: [] }
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]
+    if (value.startsWith('--')) {
+      const key = value.slice(2)
+      const next = argv[index + 1]
+      if (next && !next.startsWith('--')) {
+        out[key] = next
+        index += 1
+      } else {
+        out[key] = 'true'
+      }
+      continue
+    }
+    out._.push(value)
+  }
+  return out
+}
+
+export function parseList(value, fallback = []) {
+  const raw = (value ?? '').trim()
+  if (!raw) return [...fallback]
+  return raw.split(',').map((item) => item.trim()).filter(Boolean)
+}
+
+export function randomRequestId(prefix = 'req') {
+  return `${prefix}_${crypto.randomBytes(8).toString('hex')}`
+}
+
+export function utcNow() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')
+}
+
+export function requireArg(value, message) {
+  const trimmed = (value ?? '').trim()
+  if (!trimmed) {
+    throw new Error(message)
+  }
+  return trimmed
+}

package/lib/transport/http_json.mjs

@@ -0,0 +1,96 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+export const DEFAULT_USER_AGENT = 'curl/8.1.2'
+const STATUS_MARKER = '__AGENTSQUARED_HTTP_STATUS__:'
+
+function parseBody(text) {
+  const trimmed = text.trim()
+  return trimmed ? JSON.parse(trimmed) : {}
+}
+
+function buildStatusError(status, text, statusText = '') {
+  let data = {}
+  try {
+    data = parseBody(text)
+  } catch {
+    data = {}
+  }
+  const detail = data?.error?.message ?? (text.trim() || statusText || 'Request failed')
+  return new Error(`${status} ${detail}`)
+}
+
+function isStatusError(error) {
+  return typeof error?.message === 'string' && /^[1-5][0-9][0-9]\s/.test(error.message)
+}
+
+async function fetchJson(url, { method = 'GET', headers = {}, body } = {}) {
+  const response = await fetch(url, {
+    method,
+    headers,
+    body
+  })
+  const text = await response.text()
+  if (!response.ok) {
+    throw buildStatusError(response.status, text, response.statusText)
+  }
+  return parseBody(text)
+}
+
+async function curlJson(url, { method = 'GET', headers = {}, body } = {}) {
+  const args = [
+    '--silent',
+    '--show-error',
+    '--location',
+    '--connect-timeout', '10',
+    '--max-time', '60',
+    '--request', method,
+  ]
+  for (const [name, value] of Object.entries(headers)) {
+    args.push('--header', `${name}: ${value}`)
+  }
+  if (body !== undefined) {
+    args.push('--data-binary', body)
+  }
+  args.push('--write-out', `\n${STATUS_MARKER}%{http_code}`, url)
+  const { stdout } = await execFileAsync('curl', args, { maxBuffer: 1024 * 1024 * 4 })
+  const markerIndex = stdout.lastIndexOf(`\n${STATUS_MARKER}`)
+  if (markerIndex < 0) {
+    throw new Error('curl response did not include an HTTP status marker')
+  }
+  const text = stdout.slice(0, markerIndex)
+  const status = Number.parseInt(stdout.slice(markerIndex + 1 + STATUS_MARKER.length).trim(), 10)
+  if (!Number.isInteger(status)) {
+    throw new Error('curl response did not include a valid HTTP status code')
+  }
+  if (status < 200 || status >= 300) {
+    throw buildStatusError(status, text)
+  }
+  return parseBody(text)
+}
+
+export async function requestJson(url, { method = 'GET', headers = {}, payload } = {}) {
+  const normalizedHeaders = {
+    Accept: 'application/json',
+    'User-Agent': DEFAULT_USER_AGENT,
+    ...headers
+  }
+  let body
+  if (payload !== undefined) {
+    body = JSON.stringify(payload)
+    if (!normalizedHeaders['Content-Type']) {
+      normalizedHeaders['Content-Type'] = 'application/json'
+    }
+  }
+
+  try {
+    return await fetchJson(url, { method, headers: normalizedHeaders, body })
+  } catch (error) {
+    if (isStatusError(error)) {
+      throw error
+    }
+    return curlJson(url, { method, headers: normalizedHeaders, body })
+  }
+}