@agentsquared/cli 1.0.0

package/lib/gateway/state.mjs

@@ -0,0 +1,175 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { defaultGatewayStateFile as defaultGatewayStateFileFromLayout } from '../shared/paths.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const RUNTIME_GATEWAY_ROOT = path.resolve(__dirname, '../..')
+const REVISION_FILE_PATHS = [
+  path.join(RUNTIME_GATEWAY_ROOT, 'a2_cli.mjs'),
+  path.join(RUNTIME_GATEWAY_ROOT, 'package.json'),
+  path.join(RUNTIME_GATEWAY_ROOT, 'package-lock.json')
+]
+const REVISION_DIR_PATHS = [
+  path.join(RUNTIME_GATEWAY_ROOT, 'lib'),
+  path.join(RUNTIME_GATEWAY_ROOT, 'adapters'),
+  path.join(RUNTIME_GATEWAY_ROOT, 'bin')
+]
+
+export function defaultGatewayStateFile(keyFile, agentId) {
+  return defaultGatewayStateFileFromLayout(keyFile, agentId)
+}
+
+export function readGatewayState(gatewayStateFile) {
+  const cleaned = path.resolve(gatewayStateFile)
+  if (!fs.existsSync(cleaned)) {
+    return null
+  }
+  return JSON.parse(fs.readFileSync(cleaned, 'utf8'))
+}
+
+export function writeGatewayState(gatewayStateFile, payload) {
+  const cleaned = path.resolve(gatewayStateFile)
+  fs.mkdirSync(path.dirname(cleaned), { recursive: true })
+  fs.writeFileSync(cleaned, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 })
+  fs.chmodSync(cleaned, 0o600)
+}
+
+function walkFiles(dirPath, out) {
+  if (!fs.existsSync(dirPath)) {
+    return
+  }
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const entryPath = path.join(dirPath, entry.name)
+    if (entry.isDirectory()) {
+      walkFiles(entryPath, out)
+      continue
+    }
+    if (!entry.isFile()) {
+      continue
+    }
+    if (!['.mjs', '.json'].includes(path.extname(entry.name))) {
+      continue
+    }
+    out.push(entryPath)
+  }
+}
+
+function walkGatewayStateFiles(dirPath, out, depth = 0, maxDepth = 4) {
+  if (!fs.existsSync(dirPath) || depth > maxDepth) {
+    return
+  }
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const entryPath = path.join(dirPath, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.git') {
+        continue
+      }
+      walkGatewayStateFiles(entryPath, out, depth + 1, maxDepth)
+      continue
+    }
+    if (!entry.isFile()) {
+      continue
+    }
+    if (entry.name !== 'gateway.json') {
+      continue
+    }
+    out.push(entryPath)
+  }
+}
+
+export function currentRuntimeRevision() {
+  const hash = crypto.createHash('sha256')
+  const files = []
+  for (const filePath of REVISION_FILE_PATHS) {
+    if (fs.existsSync(filePath)) {
+      files.push(filePath)
+    }
+  }
+  for (const dirPath of REVISION_DIR_PATHS) {
+    walkFiles(dirPath, files)
+  }
+  files.sort()
+  for (const filePath of files) {
+    hash.update(path.relative(RUNTIME_GATEWAY_ROOT, filePath))
+    hash.update('\n')
+    hash.update(fs.readFileSync(filePath))
+    hash.update('\n')
+  }
+  return hash.digest('hex').slice(0, 16)
+}
+
+function buildInitRequiredMessage({ stateFile, currentRevision, expectedRevision, reason }) {
+  const parts = [
+    'The local AgentSquared gateway must be re-initialized before reuse.',
+    reason,
+    `gatewayStateFile=${stateFile}`,
+    `expectedRuntimeRevision=${expectedRevision}`,
+    `stateRuntimeRevision=${currentRevision || 'missing'}`,
+    'Restart the shared gateway from the current @agentsquared/cli checkout with `a2-cli gateway --agent-id <fullName> --key-file <runtime-key-file>` and then retry the current task.'
+  ]
+  return parts.join(' ')
+}
+
+export function assertGatewayStateFresh(state, stateFile) {
+  const expectedRevision = currentRuntimeRevision()
+  const currentRevision = `${state?.runtimeRevision ?? ''}`.trim()
+  if (!state) {
+    return { expectedRevision, currentRevision: '', stale: false }
+  }
+  if (!currentRevision) {
+    throw new Error(buildInitRequiredMessage({
+      stateFile,
+      currentRevision,
+      expectedRevision,
+      reason: 'The discovered gateway state was written by an older runtime that does not record runtimeRevision metadata.'
+    }))
+  }
+  if (currentRevision !== expectedRevision) {
+    throw new Error(buildInitRequiredMessage({
+      stateFile,
+      currentRevision,
+      expectedRevision,
+      reason: 'The discovered gateway was started from older shared runtime code than the current @agentsquared/cli checkout.'
+    }))
+  }
+  return { expectedRevision, currentRevision, stale: false }
+}
+
+export function resolveGatewayBase({ gatewayBase = '', keyFile = '', agentId = '', gatewayStateFile = '' } = {}) {
+  const explicit = `${gatewayBase}`.trim()
+  if (explicit) {
+    return explicit
+  }
+  const envValue = `${process.env.AGENTSQUARED_GATEWAY_BASE ?? ''}`.trim()
+  if (envValue) {
+    return envValue
+  }
+  const stateFile = `${gatewayStateFile}`.trim() || (keyFile && agentId ? defaultGatewayStateFile(keyFile, agentId) : '')
+  if (!stateFile) {
+    throw new Error('gatewayBase was not provided. Pass --gateway-base or provide --agent-id and --key-file so the local gateway state file can be discovered.')
+  }
+  const state = readGatewayState(stateFile)
+  assertGatewayStateFresh(state, stateFile)
+  const discovered = `${state?.gatewayBase ?? ''}`.trim()
+  if (!discovered) {
+    throw new Error(`gateway state file does not contain a gatewayBase: ${stateFile}`)
+  }
+  return discovered
+}
+
+export function discoverGatewayStateFiles(searchRoots = []) {
+  const files = []
+  const seen = new Set()
+  for (const root of searchRoots) {
+    const resolved = `${root ?? ''}`.trim() ? path.resolve(root) : ''
+    if (!resolved || seen.has(resolved)) {
+      continue
+    }
+    seen.add(resolved)
+    walkGatewayStateFiles(resolved, files)
+  }
+  return Array.from(new Set(files)).sort()
+}

package/lib/routing/agent_router.mjs

@@ -0,0 +1,511 @@
+import { normalizeConversationControl, resolveInboundConversationIdentity } from '../conversation/policy.mjs'
+
+function clean(value) {
+  return `${value ?? ''}`.trim()
+}
+
+function extractConversationMetadata(item = null) {
+  const metadata = item?.request?.params?.metadata
+  return metadata && typeof metadata === 'object' ? metadata : {}
+}
+
+function synthesizeRuntimeUnavailableExecution({
+  item,
+  selectedSkill,
+  defaultSkill,
+  mailboxKey,
+  reject
+} = {}) {
+  const finalSkill = clean(defaultSkill) || clean(selectedSkill) || DEFAULT_ROUTER_DEFAULT_SKILL
+  const remoteAgentId = clean(item?.remoteAgentId) || 'the remote agent'
+  const metadata = extractConversationMetadata(item)
+  const conversation = normalizeConversationControl(metadata, {
+    defaultTurnIndex: 1,
+    defaultDecision: 'done',
+    defaultStopReason: 'receiver-runtime-unavailable',
+    defaultFinalize: true
+  })
+  const conversationKey = clean(metadata.conversationKey)
+  const peerReplyText = 'My local AI runtime is temporarily unavailable right now, so I cannot continue this AgentSquared conversation. Please try again later.'
+  return {
+    peerResponse: {
+      message: {
+        kind: 'message',
+        role: 'agent',
+        parts: [{ kind: 'text', text: peerReplyText }]
+      },
+      metadata: {
+        selectedSkill: finalSkill,
+        mailboxKey: clean(mailboxKey),
+        conversationKey,
+        turnIndex: conversation.turnIndex,
+        decision: 'done',
+        stopReason: 'receiver-runtime-unavailable',
+        finalize: true
+      }
+    },
+    ownerReport: {
+      title: '**🅰️✌️ AgentSquared local runtime unavailable**',
+      summary: `AgentSquared replied to ${remoteAgentId} with a temporary runtime-unavailable message because the local AI runtime failed.`,
+      message: [
+        '**Runtime status**',
+        `- Remote Agent: ${remoteAgentId}`,
+        `- Local Skill Used: ${finalSkill}`,
+        ...(conversationKey ? [`- Conversation Key: ${conversationKey}`] : []),
+        `- Conversation Turns: ${conversation.turnIndex}`,
+        '- Stop Reason: receiver-runtime-unavailable',
+        '',
+        '**What happened**',
+        '> The local AI runtime failed while handling this inbound AgentSquared message, so AgentSquared sent a polite temporary-unavailable reply instead of leaving the peer hanging.',
+        '',
+        '**Error detail**',
+        `> ${clean(reject?.message) || 'local runtime execution failed'}`,
+        '',
+        'You can retry later after the local runtime is healthy again.'
+      ].join('\n'),
+      selectedSkill: finalSkill,
+      runtimeAdapter: 'fallback',
+      conversationKey,
+      turnIndex: conversation.turnIndex,
+      decision: 'done',
+      stopReason: 'receiver-runtime-unavailable',
+      finalize: true,
+      error: clean(reject?.message)
+    }
+  }
+}
+
+export const DEFAULT_ROUTER_DEFAULT_SKILL = 'friend-im'
+export const DEFAULT_ROUTER_SKILLS = ['friend-im', 'agent-mutual-learning']
+
+export function normalizeRouterSkills(skills = DEFAULT_ROUTER_SKILLS) {
+  const seen = new Set()
+  const out = []
+  for (const value of skills) {
+    const skill = clean(value)
+    if (!skill || seen.has(skill)) {
+      continue
+    }
+    seen.add(skill)
+    out.push(skill)
+  }
+  return out.length > 0 ? out : [...DEFAULT_ROUTER_SKILLS]
+}
+
+export function extractInboundText(item) {
+  const parts = item?.request?.params?.message?.parts ?? []
+  const texts = parts
+    .filter((part) => clean(part?.kind) === 'text')
+    .map((part) => clean(part?.text))
+    .filter(Boolean)
+  return texts.join('\n').trim()
+}
+
+function buildStartNoticeConversation(item) {
+  const metadata = extractConversationMetadata(item)
+  return normalizeConversationControl({
+    conversationKey: clean(metadata.conversationKey),
+    turnIndex: Number.parseInt(`${metadata.turnIndex ?? 1}`, 10) || 1,
+    decision: clean(metadata.decision),
+    stopReason: clean(metadata.stopReason),
+    finalize: Boolean(metadata.finalize)
+  }, {
+    defaultTurnIndex: 1,
+    defaultDecision: 'continue',
+    defaultStopReason: '',
+    defaultFinalize: false
+  })
+}
+
+export function resolveMailboxKey(item) {
+  return resolveInboundConversationIdentity(item).mailboxKey
+}
+
+export function resolveConversationLockKey(item) {
+  return resolveInboundConversationIdentity(item).conversationKey
+}
+
+export function chooseInboundSkill(item, {
+  routerSkills = DEFAULT_ROUTER_SKILLS,
+  defaultSkill = DEFAULT_ROUTER_DEFAULT_SKILL
+} = {}) {
+  const knownSkills = normalizeRouterSkills(routerSkills)
+  const knownSkillSet = new Set(knownSkills)
+  const suggestedSkill = clean(item?.suggestedSkill)
+  const requestDefaultSkill = clean(item?.defaultSkill)
+  const localDefaultSkill = clean(defaultSkill) || DEFAULT_ROUTER_DEFAULT_SKILL
+
+  const candidates = [
+    suggestedSkill,
+    requestDefaultSkill,
+    localDefaultSkill,
+    DEFAULT_ROUTER_DEFAULT_SKILL
+  ]
+
+  for (const candidate of candidates) {
+    if (candidate && knownSkillSet.has(candidate)) {
+      return candidate
+    }
+  }
+  return ''
+}
+
+export function createMailboxScheduler({
+  maxActiveMailboxes = 8,
+  mailboxKeyForItem = resolveMailboxKey,
+  conversationKeyForItem = resolveConversationLockKey,
+  conversationLockMs = 5 * 60 * 1000,
+  handleItem
+} = {}) {
+  if (typeof handleItem !== 'function') {
+    throw new Error('handleItem is required')
+  }
+
+  const mailboxes = new Map()
+  const idleWaiters = []
+  let activeMailboxes = 0
+  let activeConversation = null
+
+  function clearConversationLock() {
+    if (activeConversation?.timer) {
+      clearTimeout(activeConversation.timer)
+    }
+    activeConversation = null
+  }
+
+  function refreshConversationLock(conversationKey) {
+    const normalizedConversationKey = clean(conversationKey)
+    if (!normalizedConversationKey) {
+      return
+    }
+    const expiresAt = Date.now() + conversationLockMs
+    if (!activeConversation || activeConversation.conversationKey !== normalizedConversationKey) {
+      clearConversationLock()
+      activeConversation = {
+        conversationKey: normalizedConversationKey,
+        expiresAt,
+        timer: null
+      }
+    } else {
+      activeConversation.expiresAt = expiresAt
+      if (activeConversation.timer) {
+        clearTimeout(activeConversation.timer)
+      }
+    }
+    activeConversation.timer = setTimeout(() => {
+      if (activeConversation?.conversationKey === normalizedConversationKey && Date.now() >= activeConversation.expiresAt) {
+        clearConversationLock()
+        pump()
+        flushIdleWaitersIfNeeded()
+      }
+    }, Math.max(1, conversationLockMs))
+  }
+
+  function isConversationLockAvailable(conversationKey) {
+    if (!activeConversation) {
+      return true
+    }
+    if (Date.now() >= activeConversation.expiresAt) {
+      clearConversationLock()
+      return true
+    }
+    return clean(conversationKey) === clean(activeConversation.conversationKey)
+  }
+
+  function pendingCount() {
+    let count = 0
+    for (const mailbox of mailboxes.values()) {
+      count += mailbox.queue.length
+      if (mailbox.running) {
+        count += 1
+      }
+    }
+    if (activeConversation) {
+      count += 1
+    }
+    return count
+  }
+
+  function flushIdleWaitersIfNeeded() {
+    if (activeMailboxes !== 0 || pendingCount() !== 0) {
+      return
+    }
+    while (idleWaiters.length > 0) {
+      const resolve = idleWaiters.shift()
+      resolve?.()
+    }
+  }
+
+  function runMailbox(mailboxKey, mailbox) {
+    const mailboxConversationKey = clean(mailbox?.conversationKey)
+    if (
+      mailbox.running
+      || mailbox.queue.length === 0
+      || activeMailboxes >= maxActiveMailboxes
+      || !isConversationLockAvailable(mailboxConversationKey)
+    ) {
+      return
+    }
+    refreshConversationLock(mailboxConversationKey)
+    mailbox.running = true
+    activeMailboxes += 1
+
+    const loop = async () => {
+      try {
+        while (mailbox.queue.length > 0) {
+          const entry = mailbox.queue.shift()
+          try {
+            const result = await handleItem(entry.item, { mailboxKey, conversationKey: mailboxConversationKey })
+            entry.resolve(result)
+            refreshConversationLock(mailboxConversationKey)
+            const shouldReleaseConversationLock = result?.releaseConversationLock !== false
+            if (shouldReleaseConversationLock && activeConversation?.conversationKey === mailboxConversationKey && mailbox.queue.length === 0) {
+              clearConversationLock()
+            }
+          } catch (error) {
+            entry.reject(error)
+            if (activeConversation?.conversationKey === mailboxConversationKey && mailbox.queue.length === 0) {
+              clearConversationLock()
+            }
+          }
+        }
+      } finally {
+        mailbox.running = false
+        activeMailboxes = Math.max(0, activeMailboxes - 1)
+        if (mailbox.queue.length === 0) {
+          mailboxes.delete(mailboxKey)
+        }
+        pump()
+        flushIdleWaitersIfNeeded()
+      }
+    }
+
+    loop().catch(() => {})
+  }
+
+  function pump() {
+    for (const [mailboxKey, mailbox] of mailboxes.entries()) {
+      if (activeMailboxes >= maxActiveMailboxes) {
+        return
+      }
+      runMailbox(mailboxKey, mailbox)
+    }
+  }
+
+  function enqueue(item) {
+    let mailboxKey
+    let conversationKey
+    try {
+      mailboxKey = mailboxKeyForItem(item)
+      conversationKey = conversationKeyForItem(item)
+    } catch (error) {
+      return Promise.reject(error)
+    }
+    if (!mailboxes.has(mailboxKey)) {
+      mailboxes.set(mailboxKey, { running: false, queue: [], conversationKey })
+    }
+    const mailbox = mailboxes.get(mailboxKey)
+    mailbox.conversationKey = conversationKey
+    return new Promise((resolve, reject) => {
+      mailbox.queue.push({ item, resolve, reject })
+      pump()
+    })
+  }
+
+  function whenIdle() {
+    if (activeMailboxes === 0 && pendingCount() === 0) {
+      return Promise.resolve()
+    }
+    return new Promise((resolve) => {
+      idleWaiters.push(resolve)
+    })
+  }
+
+  return {
+    enqueue,
+    whenIdle,
+    snapshot() {
+      return {
+        activeMailboxes,
+        activeConversationKey: activeConversation?.conversationKey ?? '',
+        pendingItems: pendingCount(),
+        mailboxes: [...mailboxes.entries()].map(([mailboxKey, mailbox]) => ({
+          mailboxKey,
+          conversationKey: mailbox.conversationKey,
+          running: mailbox.running,
+          queued: mailbox.queue.length
+        }))
+      }
+    }
+  }
+}
+
+export function createAgentRouter({
+  maxActiveMailboxes = 8,
+  routerSkills = DEFAULT_ROUTER_SKILLS,
+  defaultSkill = DEFAULT_ROUTER_DEFAULT_SKILL,
+  executeInbound,
+  notifyOwner = null,
+  onRespond,
+  onReject
+} = {}) {
+  if (typeof executeInbound !== 'function') {
+    throw new Error('executeInbound is required')
+  }
+  if (typeof onRespond !== 'function') {
+    throw new Error('onRespond is required')
+  }
+  if (typeof onReject !== 'function') {
+    throw new Error('onReject is required')
+  }
+
+  const normalizedRouterSkills = normalizeRouterSkills(routerSkills)
+  const normalizedDefaultSkill = clean(defaultSkill) || DEFAULT_ROUTER_DEFAULT_SKILL
+
+  function shouldFallbackToDefaultSkill(reject = null) {
+    const code = Number.parseInt(`${reject?.code ?? 0}`, 10) || 0
+    if (code >= 500) {
+      return true
+    }
+    return false
+  }
+
+  const scheduler = createMailboxScheduler({
+    maxActiveMailboxes,
+    async handleItem(item, { mailboxKey, conversationKey }) {
+      const startConversation = buildStartNoticeConversation(item)
+      const selectedSkill = chooseInboundSkill(item, {
+        routerSkills: normalizedRouterSkills,
+        defaultSkill: normalizedDefaultSkill
+      })
+      if (!selectedSkill) {
+        await onReject(item, {
+          code: 409,
+          message: `no supported local skill could handle inbound request for mailbox ${mailboxKey}`
+        })
+        return { selectedSkill: '', rejected: true, releaseConversationLock: true }
+      }
+
+      let execution
+      try {
+        execution = await executeInbound({
+          item,
+          selectedSkill,
+          mailboxKey
+        })
+      } catch (error) {
+        execution = {
+          reject: {
+            code: Number.parseInt(`${error?.code ?? 500}`, 10) || 500,
+            message: clean(error?.message) || 'local runtime execution failed'
+          }
+        }
+      }
+
+      const canFallbackToDefault = selectedSkill !== normalizedDefaultSkill
+        && normalizedRouterSkills.includes(normalizedDefaultSkill)
+        && execution?.reject
+        && shouldFallbackToDefaultSkill(execution.reject)
+
+      if (canFallbackToDefault) {
+        try {
+          execution = await executeInbound({
+            item: {
+              ...item,
+              fallbackFromSkill: selectedSkill,
+              fallbackToSkill: normalizedDefaultSkill
+            },
+            selectedSkill: normalizedDefaultSkill,
+            mailboxKey
+          })
+        } catch (error) {
+          execution = {
+            reject: {
+              code: Number.parseInt(`${error?.code ?? 500}`, 10) || 500,
+              message: clean(error?.message) || 'local runtime execution failed'
+            }
+          }
+        }
+      }
+
+      if (execution?.reject) {
+        if (shouldFallbackToDefaultSkill(execution.reject)) {
+          execution = synthesizeRuntimeUnavailableExecution({
+            item,
+            selectedSkill,
+            defaultSkill: normalizedDefaultSkill,
+            mailboxKey,
+            reject: execution.reject
+          })
+        }
+      }
+
+      if (execution?.reject) {
+        await onReject(item, execution.reject)
+        return { selectedSkill, rejected: true, releaseConversationLock: true }
+      }
+
+      if (execution?.ownerReport != null && typeof notifyOwner === 'function') {
+        const rawConversation = execution?.peerResponse?.metadata && typeof execution.peerResponse.metadata === 'object'
+          ? execution.peerResponse.metadata
+          : {}
+        const conversation = normalizeConversationControl(rawConversation, {
+          defaultTurnIndex: 1,
+          defaultDecision: 'done',
+          defaultStopReason: 'single-turn',
+          defaultFinalize: true
+        })
+        await notifyOwner({
+          item,
+          selectedSkill,
+          mailboxKey,
+          ownerReport: execution.ownerReport,
+          peerResponse: execution.peerResponse,
+          conversation: {
+            ...rawConversation,
+            ...conversation
+          },
+          notifyOwnerNow: Boolean(conversation.finalize || conversation.decision === 'done' || conversation.decision === 'handoff')
+        })
+      }
+
+      await onRespond(item, execution.peerResponse)
+      const rawConversation = execution?.peerResponse?.metadata && typeof execution.peerResponse.metadata === 'object'
+        ? execution.peerResponse.metadata
+        : {}
+      const conversation = normalizeConversationControl(rawConversation, {
+        defaultTurnIndex: 1,
+        defaultDecision: 'done',
+        defaultStopReason: 'single-turn',
+        defaultFinalize: true
+      })
+      return {
+        selectedSkill: canFallbackToDefault ? normalizedDefaultSkill : selectedSkill,
+        rejected: false,
+        ownerReportDelivered: execution?.ownerReport != null && typeof notifyOwner === 'function',
+        releaseConversationLock: Boolean(conversation.finalize || conversation.decision === 'done' || conversation.decision === 'handoff'),
+        conversationKey: clean(rawConversation.conversationKey) || clean(conversationKey)
+      }
+    }
+  })
+
+  return {
+    routerSkills: normalizedRouterSkills,
+    defaultSkill: normalizedDefaultSkill,
+    enqueue(item) {
+      return scheduler.enqueue(item)
+    },
+    whenIdle() {
+      return scheduler.whenIdle()
+    },
+    snapshot() {
+      return {
+        routerSkills: normalizedRouterSkills,
+        defaultSkill: normalizedDefaultSkill,
+        executorMode: `${executeInbound?.mode ?? 'custom'}`.trim() || 'custom',
+        ownerNotifyMode: `${notifyOwner?.mode ?? 'custom'}`.trim() || 'custom',
+        scheduler: scheduler.snapshot()
+      }
+    }
+  }
+}