@agentsquared/cli 1.0.0

package/bin/a2-cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runA2Cli } from '../a2_cli.mjs'
+
+runA2Cli(process.argv.slice(2)).catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})

package/lib/conversation/policy.mjs

@@ -0,0 +1,122 @@
+function clean(value) {
+  return `${value ?? ''}`.trim()
+}
+
+export const PLATFORM_MAX_TURNS = 20
+
+const DEFAULT_SKILL_MAX_TURNS = Object.freeze({
+  'friend-im': 1,
+  'agent-mutual-learning': 8
+})
+
+const VALID_DECISIONS = new Set(['continue', 'done', 'handoff'])
+
+const VALID_STOP_REASONS = new Set([
+  'goal-satisfied',
+  'no-new-information',
+  'receiver-budget-limit',
+  'safety-block',
+  'owner-approval-required',
+  'unsafe-or-sensitive',
+  'max-turns-reached',
+  'peer-requested-stop',
+  'timeout',
+  'single-turn',
+  'receiver-runtime-unavailable'
+])
+
+function parsePositiveInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value ?? ''}`, 10)
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback
+  }
+  return parsed
+}
+
+function extractFrontmatter(text = '') {
+  const match = `${text ?? ''}`.match(/^---\n([\s\S]*?)\n---/)
+  return match?.[1] ?? ''
+}
+
+function readFrontmatterValue(frontmatter = '', key = '') {
+  const match = `${frontmatter}`.match(new RegExp(`^\\s*${clean(key)}\\s*:\\s*(.+)\\s*$`, 'm'))
+  return clean(match?.[1] ?? '').replace(/^["']|["']$/g, '')
+}
+
+export function clampConversationMaxTurns(value, fallback = 1) {
+  const boundedFallback = Math.max(1, Math.min(PLATFORM_MAX_TURNS, parsePositiveInteger(fallback, 1) || 1))
+  const parsed = parsePositiveInteger(value, boundedFallback)
+  return Math.max(1, Math.min(PLATFORM_MAX_TURNS, parsed || boundedFallback))
+}
+
+export function parseSkillDocumentPolicy(text = '', {
+  fallbackName = ''
+} = {}) {
+  const frontmatter = extractFrontmatter(text)
+  const name = clean(readFrontmatterValue(frontmatter, 'name')) || clean(fallbackName)
+  const maxTurns = clampConversationMaxTurns(
+    readFrontmatterValue(frontmatter, 'maxTurns') || readFrontmatterValue(frontmatter, 'max_turns'),
+    DEFAULT_SKILL_MAX_TURNS[name] ?? 1
+  )
+  return {
+    name,
+    maxTurns
+  }
+}
+
+export function resolveSkillMaxTurns(skillName = '', sharedSkill = null) {
+  const normalizedSkill = clean(skillName).toLowerCase()
+  const sharedSkillName = clean(sharedSkill?.name).toLowerCase()
+  if (sharedSkillName && normalizedSkill && sharedSkillName === normalizedSkill) {
+    return clampConversationMaxTurns(sharedSkill?.maxTurns, DEFAULT_SKILL_MAX_TURNS[normalizedSkill] ?? 1)
+  }
+  if (normalizedSkill in DEFAULT_SKILL_MAX_TURNS) {
+    return clampConversationMaxTurns(DEFAULT_SKILL_MAX_TURNS[normalizedSkill], 1)
+  }
+  return 1
+}
+
+export function normalizeConversationControl(raw = {}, {
+  defaultTurnIndex = 1,
+  defaultDecision = 'done',
+  defaultStopReason = '',
+  defaultFinalize = null
+} = {}) {
+  const turnIndex = Math.max(1, parsePositiveInteger(raw?.turnIndex, defaultTurnIndex || 1) || 1)
+  const decision = VALID_DECISIONS.has(clean(raw?.decision).toLowerCase())
+    ? clean(raw?.decision).toLowerCase()
+    : clean(defaultDecision).toLowerCase() || 'done'
+  const stopReason = VALID_STOP_REASONS.has(clean(raw?.stopReason).toLowerCase())
+    ? clean(raw?.stopReason).toLowerCase()
+    : clean(defaultStopReason).toLowerCase()
+  const computedFinalize = typeof defaultFinalize === 'boolean'
+    ? defaultFinalize
+    : decision !== 'continue'
+  const finalize = typeof raw?.finalize === 'boolean'
+    ? raw.finalize
+    : computedFinalize
+  return {
+    turnIndex,
+    decision,
+    stopReason,
+    finalize: finalize || decision !== 'continue'
+  }
+}
+
+export function shouldContinueConversation(control = {}) {
+  const normalized = normalizeConversationControl(control)
+  return normalized.decision === 'continue' && !normalized.finalize
+}
+
+export function resolveInboundConversationIdentity(item = {}) {
+  const metadata = item?.request?.params?.metadata
+  const normalizedMetadata = metadata && typeof metadata === 'object' ? metadata : {}
+  const explicitConversationKey = clean(normalizedMetadata.conversationKey)
+  if (explicitConversationKey) {
+    return {
+      conversationKey: explicitConversationKey,
+      mailboxKey: `conversation:${explicitConversationKey}`
+    }
+  }
+  throw Object.assign(new Error('conversationKey is required for inbound AgentSquared conversations'), { code: 400 })
+}

package/lib/conversation/store.mjs

@@ -0,0 +1,223 @@
+import crypto from 'node:crypto'
+
+function clean(value) {
+  return `${value ?? ''}`.trim()
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function nowISO() {
+  return new Date().toISOString()
+}
+
+function stableTurnFingerprint({
+  turnIndex,
+  remoteAgentId,
+  inboundText,
+  replyText,
+  selectedSkill
+} = {}) {
+  const payload = JSON.stringify({
+    turnIndex: Number.parseInt(`${turnIndex ?? 1}`, 10) || 1,
+    remoteAgentId: clean(remoteAgentId).toLowerCase(),
+    inboundText: clean(inboundText).replace(/\s+/g, ' ').trim(),
+    replyText: clean(replyText).replace(/\s+/g, ' ').trim(),
+    selectedSkill: clean(selectedSkill)
+  })
+  return crypto.createHash('sha256').update(payload).digest('hex')
+}
+
+function excerpt(text, maxLength = 240) {
+  const compact = clean(text).replace(/\s+/g, ' ').trim()
+  if (!compact) {
+    return ''
+  }
+  return compact.length > maxLength ? `${compact.slice(0, maxLength - 3)}...` : compact
+}
+
+function formatTranscript(turns = []) {
+  if (!Array.isArray(turns) || turns.length === 0) {
+    return ''
+  }
+  return turns.map((turn) => {
+    const lines = [
+      `Turn ${turn.turnIndex}:`,
+      `- Remote message: ${excerpt(turn.inboundText, 400) || '(empty)'}`,
+      `- My reply: ${excerpt(turn.replyText, 400) || '(empty)'}`,
+      `- Decision: ${clean(turn.decision) || 'done'}`
+    ]
+    if (clean(turn.stopReason)) {
+      lines.push(`- Stop reason: ${clean(turn.stopReason)}`)
+    }
+    return lines.join('\n')
+  }).join('\n\n')
+}
+
+export function createLiveConversationStore() {
+  const conversations = new Map()
+
+  function resolveConversationKey({
+    conversationKey,
+    peerSessionId
+  } = {}) {
+    return clean(conversationKey) || clean(peerSessionId)
+  }
+
+  function ensureConversation({
+    conversationKey,
+    peerSessionId,
+    remoteAgentId,
+    selectedSkill
+  } = {}) {
+    const key = resolveConversationKey({ conversationKey, peerSessionId })
+    if (!key) {
+      throw new Error('conversationKey or peerSessionId is required for live conversation state')
+    }
+    const existing = conversations.get(key)
+    if (existing) {
+      return clone(existing)
+    }
+    const created = {
+      conversationKey: key,
+      peerSessionId: clean(peerSessionId),
+      remoteAgentId: clean(remoteAgentId),
+      selectedSkill: clean(selectedSkill) || 'friend-im',
+      createdAt: nowISO(),
+      updatedAt: nowISO(),
+      finalizedAt: '',
+      turns: [],
+      finalSummary: ''
+    }
+    conversations.set(key, created)
+    return clone(created)
+  }
+
+  function getConversation(conversationKey) {
+    const existing = conversations.get(clean(conversationKey))
+    return existing ? clone(existing) : null
+  }
+
+  function appendTurn({
+    conversationKey,
+    peerSessionId,
+    requestId = '',
+    remoteAgentId,
+    selectedSkill,
+    turnIndex,
+    inboundText,
+    replyText,
+    decision,
+    stopReason = '',
+    finalize = false,
+    ownerSummary = ''
+  } = {}) {
+    const key = resolveConversationKey({ conversationKey, peerSessionId })
+    const current = conversations.get(key) || ensureConversation({
+      conversationKey: key,
+      peerSessionId,
+      remoteAgentId,
+      selectedSkill
+    })
+    const normalizedRequestId = clean(requestId)
+    const normalizedTurnFingerprint = stableTurnFingerprint({
+      turnIndex,
+      remoteAgentId,
+      inboundText,
+      replyText,
+      selectedSkill
+    })
+    if (normalizedRequestId && Array.isArray(current.turns)) {
+      const duplicate = current.turns.find((turn) => clean(turn.requestId) === normalizedRequestId)
+      if (duplicate) {
+        return clone(current)
+      }
+    }
+    if (normalizedTurnFingerprint && Array.isArray(current.turns)) {
+      const duplicate = current.turns.find((turn) => clean(turn.turnFingerprint) === normalizedTurnFingerprint)
+      if (duplicate) {
+        return clone(current)
+      }
+    }
+    const normalized = {
+      ...current,
+      conversationKey: key,
+      peerSessionId: clean(peerSessionId) || clean(current.peerSessionId),
+      remoteAgentId: clean(remoteAgentId) || clean(current.remoteAgentId),
+      selectedSkill: clean(selectedSkill) || clean(current.selectedSkill) || 'friend-im',
+      updatedAt: nowISO(),
+      turns: [
+        ...(Array.isArray(current.turns) ? current.turns : []),
+        {
+          requestId: normalizedRequestId,
+          turnFingerprint: normalizedTurnFingerprint,
+          turnIndex: Number.parseInt(`${turnIndex ?? 1}`, 10) || 1,
+          inboundText: clean(inboundText),
+          replyText: clean(replyText),
+          decision: clean(decision),
+          stopReason: clean(stopReason),
+          finalize: Boolean(finalize),
+          ownerSummary: clean(ownerSummary),
+          createdAt: nowISO()
+        }
+      ]
+    }
+    if (finalize) {
+      normalized.finalizedAt = nowISO()
+      normalized.finalSummary = clean(ownerSummary)
+    }
+    conversations.set(key, normalized)
+    return clone(normalized)
+  }
+
+  function transcript(conversationKey) {
+    return formatTranscript(conversations.get(clean(conversationKey))?.turns ?? [])
+  }
+
+  function finalizeConversation(conversationKey, summary = '') {
+    const key = clean(conversationKey)
+    const current = conversations.get(key)
+    if (!current) {
+      return null
+    }
+    const updated = {
+      ...current,
+      updatedAt: nowISO(),
+      finalizedAt: nowISO(),
+      finalSummary: clean(summary) || clean(current.finalSummary)
+    }
+    conversations.set(key, updated)
+    return clone(updated)
+  }
+
+  function endConversation(conversationKey) {
+    const key = clean(conversationKey)
+    const existing = conversations.get(key)
+    if (!existing) {
+      return null
+    }
+    conversations.delete(key)
+    return clone(existing)
+  }
+
+  function reset() {
+    conversations.clear()
+  }
+
+  return {
+    ensureConversation,
+    getConversation,
+    appendTurn,
+    transcript,
+    finalizeConversation,
+    endConversation,
+    reset,
+    snapshot() {
+      return {
+        activeConversations: conversations.size,
+        conversations: [...conversations.values()].map((value) => clone(value))
+      }
+    }
+  }
+}