@swarmclawai/swarmclaw 0.7.7 → 0.8.0

package/src/lib/server/workspace-context.ts

@@ -0,0 +1,111 @@
+/**
+ * Workspace context injection — injects workspace files into the agent's system prompt.
+ *
+ * Inspired by OpenClaw's pattern of injecting HEARTBEAT.md, IDENTITY.md, AGENTS.md,
+ * SOUL.md, TOOLS.md, USER.md, and BOOTSTRAP.md into every agent turn.
+ *
+ * This gives agents self-awareness, goals, and context about their operating environment
+ * without requiring the user to manually configure everything.
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { WORKSPACE_DIR } from './data-dir'
+
+/**
+ * Workspace files to inject, in priority order.
+ * Higher-priority files are injected first and get more budget.
+ */
+const WORKSPACE_FILES = [
+  { name: 'HEARTBEAT.md', maxChars: 2000, section: 'Active Tasks & Heartbeat' },
+  { name: 'IDENTITY.md', maxChars: 800, section: 'Agent Identity' },
+  { name: 'AGENTS.md', maxChars: 2000, section: 'Agent Directory' },
+  { name: 'BOOTSTRAP.md', maxChars: 1500, section: 'Bootstrap Instructions' },
+  { name: 'TOOLS.md', maxChars: 1000, section: 'Tool Configuration' },
+  { name: 'USER.md', maxChars: 500, section: 'User Preferences' },
+] as const
+
+const TOTAL_MAX_CHARS = 8000
+
+interface WorkspaceContextOptions {
+  /** Session working directory (overrides global workspace) */
+  cwd?: string | null
+  /** Maximum total characters for all workspace files */
+  maxTotalChars?: number
+}
+
+interface InjectedFile {
+  name: string
+  chars: number
+  truncated: boolean
+}
+
+interface WorkspaceContextResult {
+  /** The assembled context block to inject into the system prompt */
+  block: string
+  /** Which files were injected and their sizes */
+  files: InjectedFile[]
+}
+
+function readFileSafe(filePath: string): string | null {
+  try {
+    if (!fs.existsSync(filePath)) return null
+    const stat = fs.statSync(filePath)
+    // Skip files over 50KB
+    if (stat.size > 50_000) return null
+    return fs.readFileSync(filePath, 'utf-8').trim()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check if content is effectively empty (only headers, empty list items, whitespace).
+ */
+function isEffectivelyEmpty(content: string): boolean {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    if (/^#+(\s|$)/.test(trimmed)) continue
+    if (/^[-*+]\s*(\[[\sXx]?\]\s*)?$/.test(trimmed)) continue
+    return false
+  }
+  return true
+}
+
+/**
+ * Build workspace context for injection into the agent's system prompt.
+ * Reads workspace files and assembles them into a single context block.
+ */
+export function buildWorkspaceContext(opts: WorkspaceContextOptions = {}): WorkspaceContextResult {
+  const workspaceDir = opts.cwd || WORKSPACE_DIR
+  const maxTotal = opts.maxTotalChars || TOTAL_MAX_CHARS
+  const files: InjectedFile[] = []
+  const sections: string[] = []
+  let totalChars = 0
+
+  for (const spec of WORKSPACE_FILES) {
+    if (totalChars >= maxTotal) break
+
+    const filePath = path.join(workspaceDir, spec.name)
+    const content = readFileSafe(filePath)
+    if (!content || isEffectivelyEmpty(content)) continue
+
+    const budget = Math.min(spec.maxChars, maxTotal - totalChars)
+    if (budget <= 0) break
+
+    const truncated = content.length > budget
+    const injected = truncated ? content.slice(0, budget) + '\n[...truncated]' : content
+
+    sections.push(`## ${spec.section}\n_Source: ${spec.name}_\n${injected}`)
+    files.push({ name: spec.name, chars: injected.length, truncated })
+    totalChars += injected.length
+  }
+
+  if (sections.length === 0) {
+    return { block: '', files: [] }
+  }
+
+  const block = `# Workspace Context\n${sections.join('\n\n')}`
+  return { block, files }
+}

package/src/lib/skill-save-payload.test.ts

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { buildSkillSavePayload } from './skill-save-payload'
+
+test('buildSkillSavePayload preserves imported skill metadata when saving', () => {
+  const payload = buildSkillSavePayload({
+    name: 'GitHub Sync',
+    filename: 'github-sync.md',
+    description: 'Sync GitHub issues into tasks.',
+    content: '# Sync issues',
+    scope: 'agent',
+    agentIds: ['agent-1'],
+  }, {
+    sourceUrl: 'https://example.com/SKILL.md',
+    sourceFormat: 'openclaw',
+    author: 'Codex',
+    tags: ['github', 'tasks'],
+    version: '1.2.3',
+    homepage: 'https://example.com/github-sync',
+    primaryEnv: 'GITHUB_TOKEN',
+    skillKey: 'github-sync',
+    always: true,
+    installOptions: [{ kind: 'brew', label: 'gh', bins: ['gh'] }],
+    skillRequirements: { env: ['GITHUB_TOKEN'] },
+    detectedEnvVars: ['GITHUB_TOKEN'],
+    security: { level: 'medium', notes: ['Review install steps.'] },
+    frontmatter: { name: 'github-sync', metadata: { openclaw: { primaryEnv: 'GITHUB_TOKEN' } } },
+  })
+
+  assert.equal(payload.sourceFormat, 'openclaw')
+  assert.equal(payload.version, '1.2.3')
+  assert.equal(payload.primaryEnv, 'GITHUB_TOKEN')
+  assert.equal(payload.skillKey, 'github-sync')
+  assert.deepEqual(payload.agentIds, ['agent-1'])
+  assert.deepEqual(payload.skillRequirements, { env: ['GITHUB_TOKEN'] })
+  assert.deepEqual(payload.security, { level: 'medium', notes: ['Review install steps.'] })
+  assert.deepEqual(payload.frontmatter, { name: 'github-sync', metadata: { openclaw: { primaryEnv: 'GITHUB_TOKEN' } } })
+})

package/src/lib/skill-save-payload.ts

@@ -0,0 +1,37 @@
+import type { Skill } from '@/types'
+
+export type SkillScope = 'global' | 'agent'
+
+export interface SkillDraftInput {
+  name: string
+  filename: string
+  description: string
+  content: string
+  scope: SkillScope
+  agentIds: string[]
+}
+
+export function buildSkillSavePayload(draft: SkillDraftInput, metadataPreview?: Partial<Skill> | null) {
+  return {
+    name: draft.name.trim() || 'Unnamed Skill',
+    filename: draft.filename.trim() || `${draft.name.trim().toLowerCase().replace(/\s+/g, '-')}.md`,
+    description: draft.description,
+    content: draft.content,
+    scope: draft.scope,
+    agentIds: draft.scope === 'agent' ? draft.agentIds : [],
+    sourceUrl: metadataPreview?.sourceUrl,
+    sourceFormat: metadataPreview?.sourceFormat,
+    author: metadataPreview?.author,
+    tags: metadataPreview?.tags,
+    version: metadataPreview?.version,
+    homepage: metadataPreview?.homepage,
+    primaryEnv: metadataPreview?.primaryEnv,
+    skillKey: metadataPreview?.skillKey,
+    always: metadataPreview?.always,
+    installOptions: metadataPreview?.installOptions,
+    skillRequirements: metadataPreview?.skillRequirements,
+    detectedEnvVars: metadataPreview?.detectedEnvVars,
+    security: metadataPreview?.security,
+    frontmatter: metadataPreview?.frontmatter,
+  }
+}

package/src/lib/tasks.ts

@@ -4,6 +4,31 @@ import type { BoardTask } from '../types'
 export const fetchTasks = (includeArchived = false) =>
   api<Record<string, BoardTask>>('GET', `/tasks${includeArchived ? '?includeArchived=true' : ''}`)
 
+export interface GitHubIssueImportRequest {
+  repo: string
+  token?: string
+  state?: 'open' | 'closed' | 'all'
+  limit?: number
+  labels?: string[]
+  projectId?: string | null
+  agentId?: string | null
+}
+
+export interface GitHubIssueImportItem {
+  taskId?: string
+  number: number
+  title: string
+  url: string | null
+}
+
+export interface GitHubIssueImportResult {
+  repo: string
+  state: 'open' | 'closed' | 'all'
+  fetched: number
+  created: GitHubIssueImportItem[]
+  skipped: GitHubIssueImportItem[]
+}
+
 export const createTask = (data: {
   title: string
   description: string
@@ -27,3 +52,6 @@ export const unarchiveTask = (id: string) =>
 
 export const bulkUpdateTasks = (ids: string[], data: { status?: string; agentId?: string | null; projectId?: string | null }) =>
   api<{ updated: number; ids: string[] }>('POST', '/tasks/bulk', { ids, ...data })
+
+export const importGitHubIssues = (data: GitHubIssueImportRequest) =>
+  api<GitHubIssueImportResult>('POST', '/tasks/import/github', data, { timeoutMs: 30_000 })

package/src/lib/tool-definitions.ts

@@ -36,7 +36,8 @@ export const AVAILABLE_TOOLS: ToolDefinition[] = [
  * Granular CRUD tools are now unified under 'manage_platform'.
  */
 export const PLATFORM_TOOLS: ToolDefinition[] = [
-  { id: 'manage_platform', label: 'Platform', description: 'Unified management of agents, tasks, schedules, skills, documents, and secrets' },
+  { id: 'manage_platform', label: 'Platform', description: 'Unified management of agents, projects, tasks, schedules, skills, documents, and secrets' },
+  { id: 'manage_projects', label: 'Projects', description: 'Manage durable project context: objectives, priorities, heartbeat plans, credential needs, and linked resources' },
   { id: 'manage_connectors', label: 'Connectors', description: 'Manage chat platform bridges and send outbound messages' },
   { id: 'manage_chatrooms', label: 'Chatrooms', description: 'Manage SwarmClaw routing rules and multi-agent chatrooms' },
   { id: 'delegate_to_agent', label: 'Assign Agent', description: 'Delegate a task to another specific agent' },

package/src/lib/tool-event-summary.test.ts

@@ -0,0 +1,30 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { buildToolEventAssistantSummary } from './tool-event-summary'
+
+describe('buildToolEventAssistantSummary', () => {
+  it('summarizes completed tool-only runs', () => {
+    const summary = buildToolEventAssistantSummary([
+      { name: 'browser', input: '{"action":"screenshot"}', output: '/api/uploads/wiki.png' },
+      { name: 'send_file', input: '{"filePath":"wiki.png"}', output: '[wiki](/api/uploads/wiki.png)' },
+    ])
+
+    assert.equal(
+      summary,
+      'Used 2 tool calls (`browser`, `send_file`). See tool output above for details.',
+    )
+  })
+
+  it('summarizes interrupted in-flight tool runs', () => {
+    const summary = buildToolEventAssistantSummary(
+      [{ name: 'browser', input: '{"action":"navigate"}' }],
+      { interrupted: true },
+    )
+
+    assert.equal(
+      summary,
+      'Started 1 tool call (`browser`). Progress was interrupted before completion.',
+    )
+  })
+})

package/src/lib/tool-event-summary.ts

@@ -0,0 +1,37 @@
+import type { MessageToolEvent } from '@/types'
+
+interface ToolEventAssistantSummaryOptions {
+  interrupted?: boolean
+}
+
+export function buildToolEventAssistantSummary(
+  toolEvents: MessageToolEvent[] | undefined,
+  options: ToolEventAssistantSummaryOptions = {},
+): string {
+  const events = Array.isArray(toolEvents)
+    ? toolEvents.filter((event) => typeof event?.name === 'string' && event.name.trim().length > 0)
+    : []
+  if (events.length === 0) return ''
+
+  const uniqueNames = [...new Set(events.map((event) => event.name.trim()))]
+  const visibleNames = uniqueNames.slice(0, 4).map((name) => `\`${name}\``).join(', ')
+  const hiddenCount = Math.max(0, uniqueNames.length - 4)
+  const pendingCount = events.filter((event) => !event.output).length
+  const errorCount = events.filter((event) => event.error === true).length
+  const toolWord = events.length === 1 ? 'tool call' : 'tool calls'
+  const interrupted = options.interrupted === true
+
+  const namesLabel = hiddenCount > 0
+    ? `${visibleNames}, +${hiddenCount} more`
+    : visibleNames
+
+  if (interrupted || pendingCount > 0) {
+    return `Started ${events.length} ${toolWord} (${namesLabel}). Progress was interrupted before completion.`
+  }
+
+  if (errorCount > 0) {
+    return `Used ${events.length} ${toolWord} (${namesLabel}). ${errorCount} ${errorCount === 1 ? 'call reported an error' : 'calls reported errors'}. See tool output above for details.`
+  }
+
+  return `Used ${events.length} ${toolWord} (${namesLabel}). See tool output above for details.`
+}

package/src/lib/validation/schemas.ts

@@ -43,6 +43,7 @@ export const AgentCreateSchema = z.object({
   thinkingLevel: z.string().optional(),
   soul: z.string().optional(),
   identityState: z.record(z.string(), z.unknown()).nullable().optional().default(null),
+  disabled: z.boolean().optional().default(false),
   heartbeatEnabled: z.boolean().optional().default(false),
   heartbeatInterval: z.union([z.string(), z.number()]).nullable().optional().default(null),
   heartbeatIntervalSec: z.number().int().nonnegative().nullable().optional().default(null),

package/src/lib/wallet-transactions.test.ts

@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import type { WalletTransaction } from '@/types'
+
+import {
+  filterWalletTransactions,
+  getWalletTransactionStatusGroup,
+  matchesWalletTransactionFilter,
+  matchesWalletTransactionQuery,
+} from './wallet-transactions'
+
+function buildTransaction(overrides: Partial<WalletTransaction> = {}): WalletTransaction {
+  return {
+    id: 'tx-1',
+    walletId: 'wallet-1',
+    agentId: 'agent-1',
+    chain: 'ethereum',
+    type: 'swap',
+    signature: '0xabc123',
+    fromAddress: '0xfrom000000000000000000000000000000000001',
+    toAddress: '0xto0000000000000000000000000000000000002',
+    amountAtomic: '1000000',
+    status: 'confirmed',
+    memo: 'Swapped 1 USDC to ETH',
+    timestamp: 1,
+    ...overrides,
+  }
+}
+
+describe('wallet transaction filters', () => {
+  it('groups pending and pending_approval together', () => {
+    assert.equal(getWalletTransactionStatusGroup('pending'), 'pending')
+    assert.equal(getWalletTransactionStatusGroup('pending_approval'), 'pending')
+    assert.equal(getWalletTransactionStatusGroup('confirmed'), 'confirmed')
+    assert.equal(getWalletTransactionStatusGroup('failed'), 'failed')
+    assert.equal(getWalletTransactionStatusGroup('denied'), 'failed')
+  })
+
+  it('matches filters by type and status group', () => {
+    assert.equal(matchesWalletTransactionFilter(buildTransaction({ type: 'swap' }), 'swap'), true)
+    assert.equal(matchesWalletTransactionFilter(buildTransaction({ type: 'send' }), 'send'), true)
+    assert.equal(matchesWalletTransactionFilter(buildTransaction({ status: 'pending_approval' }), 'pending'), true)
+    assert.equal(matchesWalletTransactionFilter(buildTransaction({ status: 'denied' }), 'failed'), true)
+  })
+
+  it('matches search queries against signature, memo, and addresses', () => {
+    const tx = buildTransaction()
+    assert.equal(matchesWalletTransactionQuery(tx, 'usdc'), true)
+    assert.equal(matchesWalletTransactionQuery(tx, '0xabc123'), true)
+    assert.equal(matchesWalletTransactionQuery(tx, '0xfrom0000'), true)
+    assert.equal(matchesWalletTransactionQuery(tx, 'missing-text'), false)
+  })
+
+  it('filters transactions by combined status/type and search query', () => {
+    const transactions = [
+      buildTransaction({ id: 'tx-confirmed', status: 'confirmed', memo: 'Swap USDC to ETH' }),
+      buildTransaction({ id: 'tx-pending', status: 'pending_approval', memo: 'Awaiting approval' }),
+      buildTransaction({ id: 'tx-send', type: 'send', status: 'confirmed', memo: 'Send ETH to treasury' }),
+    ]
+
+    assert.deepEqual(
+      filterWalletTransactions(transactions, { filter: 'pending' }).map((tx) => tx.id),
+      ['tx-pending'],
+    )
+    assert.deepEqual(
+      filterWalletTransactions(transactions, { filter: 'send', query: 'treasury' }).map((tx) => tx.id),
+      ['tx-send'],
+    )
+    assert.deepEqual(
+      filterWalletTransactions(transactions, { filter: 'confirmed', query: 'usdc' }).map((tx) => tx.id),
+      ['tx-confirmed'],
+    )
+  })
+})

package/src/lib/wallet-transactions.ts

@@ -0,0 +1,43 @@
+import type { WalletTransaction, WalletTransactionStatus } from '@/types'
+
+export type WalletTransactionFilter = 'all' | 'confirmed' | 'pending' | 'failed' | 'send' | 'receive' | 'swap'
+
+export function getWalletTransactionStatusGroup(status: WalletTransactionStatus): 'confirmed' | 'pending' | 'failed' {
+  if (status === 'confirmed') return 'confirmed'
+  if (status === 'pending' || status === 'pending_approval') return 'pending'
+  return 'failed'
+}
+
+export function matchesWalletTransactionFilter(tx: WalletTransaction, filter: WalletTransactionFilter): boolean {
+  if (filter === 'all') return true
+  if (filter === 'send' || filter === 'receive' || filter === 'swap') return tx.type === filter
+  return getWalletTransactionStatusGroup(tx.status) === filter
+}
+
+export function matchesWalletTransactionQuery(tx: WalletTransaction, query: string): boolean {
+  const normalized = query.trim().toLowerCase()
+  if (!normalized) return true
+  const haystack = [
+    tx.id,
+    tx.signature,
+    tx.memo || '',
+    tx.fromAddress,
+    tx.toAddress,
+    tx.status,
+    tx.type,
+    tx.tokenMint || '',
+    tx.approvedBy || '',
+  ]
+    .join(' ')
+    .toLowerCase()
+  return haystack.includes(normalized)
+}
+
+export function filterWalletTransactions(
+  transactions: WalletTransaction[],
+  options?: { filter?: WalletTransactionFilter; query?: string },
+): WalletTransaction[] {
+  const filter = options?.filter || 'all'
+  const query = options?.query || ''
+  return transactions.filter((tx) => matchesWalletTransactionFilter(tx, filter) && matchesWalletTransactionQuery(tx, query))
+}

package/src/lib/wallet.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { getWalletChainOrDefault, parseDisplayAmountToAtomic } from './wallet'
+
+describe('wallet helpers', () => {
+  it('rejects unsupported wallet chain aliases instead of silently remapping them', () => {
+    assert.throws(() => getWalletChainOrDefault('base'), /Unsupported wallet chain or provider: base/)
+    assert.throws(() => getWalletChainOrDefault('ethereun'), /Unsupported wallet chain or provider: ethereun/)
+    assert.equal(getWalletChainOrDefault(undefined), 'solana')
+  })
+
+  it('parses tiny ETH amounts from either strings or numbers', () => {
+    assert.equal(parseDisplayAmountToAtomic('0.000000000000000001', 18), '1')
+    assert.equal(parseDisplayAmountToAtomic(0.000000000000000001, 18), '1')
+  })
+})

package/src/lib/wallet.ts

@@ -0,0 +1,183 @@
+import type { WalletChain } from '@/types'
+
+export const SUPPORTED_WALLET_CHAINS = ['solana', 'ethereum'] as const
+
+export interface WalletChainMeta {
+  chain: WalletChain
+  label: string
+  symbol: string
+  decimals: number
+  defaultPerTxAtomic: string
+  defaultDailyAtomic: string
+  addressExplorerBaseUrl: string
+  transactionExplorerBaseUrl: string
+  createDescription: string
+  fundingInstructions: string[]
+}
+
+const WALLET_CHAIN_META: Record<WalletChain, WalletChainMeta> = {
+  solana: {
+    chain: 'solana',
+    label: 'Solana',
+    symbol: 'SOL',
+    decimals: 9,
+    defaultPerTxAtomic: '100000000',
+    defaultDailyAtomic: '1000000000',
+    addressExplorerBaseUrl: 'https://solscan.io/account/',
+    transactionExplorerBaseUrl: 'https://solscan.io/tx/',
+    createDescription: 'Create a Solana wallet for agents that need SOL-native transfers and Solana ecosystem access.',
+    fundingInstructions: [
+      'Send SOL to this wallet address from any Solana wallet or exchange.',
+      'Make sure you are sending real SOL on Solana mainnet.',
+    ],
+  },
+  ethereum: {
+    chain: 'ethereum',
+    label: 'Ethereum',
+    symbol: 'ETH',
+    decimals: 18,
+    defaultPerTxAtomic: '10000000000000000',
+    defaultDailyAtomic: '50000000000000000',
+    addressExplorerBaseUrl: 'https://etherscan.io/address/',
+    transactionExplorerBaseUrl: 'https://etherscan.io/tx/',
+    createDescription: 'Create an Ethereum-compatible EVM wallet for ETH-native transfers, exchange auth, and EVM ecosystem access.',
+    fundingInstructions: [
+      'Send ETH to this wallet address from any Ethereum-compatible wallet or exchange.',
+      'Make sure the sending network matches the wallet network you intend to use before transferring funds.',
+    ],
+  },
+}
+
+export function getWalletChainMeta(chain: WalletChain): WalletChainMeta {
+  return WALLET_CHAIN_META[chain] || WALLET_CHAIN_META.solana
+}
+
+export function normalizeWalletChainInput(value: unknown): WalletChain | null {
+  const normalized = String(value || '').trim().toLowerCase()
+  if (!normalized) return null
+  if (normalized === 'sol' || normalized === 'solana') return 'solana'
+  if (normalized === 'eth' || normalized === 'ethereum' || normalized === 'evm') {
+    return 'ethereum'
+  }
+  return null
+}
+
+export function getWalletChainOrDefault(value: unknown, fallback: WalletChain = 'solana'): WalletChain {
+  const normalized = normalizeWalletChainInput(value)
+  if (normalized) return normalized
+  const raw = String(value ?? '').trim()
+  if (raw) {
+    throw new Error(`Unsupported wallet chain or provider: ${raw}`)
+  }
+  return fallback
+}
+
+export function getWalletDefaultLimitAtomic(chain: WalletChain, limit: 'perTx' | 'daily'): string {
+  const meta = getWalletChainMeta(chain)
+  return limit === 'perTx' ? meta.defaultPerTxAtomic : meta.defaultDailyAtomic
+}
+
+export function normalizeAtomicString(value: unknown, fallback = '0'): string {
+  if (typeof value === 'bigint') return value >= BigInt(0) ? value.toString() : fallback
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return Math.floor(value).toString()
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (/^\d+$/.test(trimmed)) return trimmed.replace(/^0+(?=\d)/, '') || '0'
+  }
+  return fallback
+}
+
+export function parseDisplayAmountToAtomic(value: string | number, decimals: number): string {
+  const raw = typeof value === 'number'
+    ? value.toLocaleString('en-US', {
+      useGrouping: false,
+      maximumFractionDigits: decimals,
+    }).trim()
+    : String(value ?? '').trim()
+  if (!raw) throw new Error('Amount is required')
+  if (!/^\d+(\.\d+)?$/.test(raw)) throw new Error('Amount must be a positive decimal number')
+
+  const [whole, fraction = ''] = raw.split('.')
+  if (fraction.length > decimals) {
+    throw new Error(`Amount supports up to ${decimals} decimal places`)
+  }
+
+  const wholePart = BigInt(whole || '0')
+  const fractionPadded = `${fraction}${'0'.repeat(decimals)}`.slice(0, decimals)
+  const fractionPart = BigInt(fractionPadded || '0')
+  const scale = BigInt(10) ** BigInt(decimals)
+  return ((wholePart * scale) + fractionPart).toString()
+}
+
+export function formatAtomicAmount(
+  atomicValue: string | number | bigint,
+  decimals: number,
+  opts?: { minFractionDigits?: number; maxFractionDigits?: number }
+): string {
+  const atomic = BigInt(normalizeAtomicString(atomicValue, '0'))
+  const scale = BigInt(10) ** BigInt(decimals)
+  const whole = atomic / scale
+  const fraction = atomic % scale
+  const maxFractionDigits = Math.max(0, Math.min(decimals, opts?.maxFractionDigits ?? decimals))
+  const minFractionDigits = Math.max(0, Math.min(maxFractionDigits, opts?.minFractionDigits ?? 0))
+
+  if (maxFractionDigits === 0) return whole.toString()
+
+  let fractionText = fraction.toString().padStart(decimals, '0').slice(0, maxFractionDigits)
+  if (fractionText.length < minFractionDigits) fractionText = fractionText.padEnd(minFractionDigits, '0')
+  if (fractionText.length > minFractionDigits) fractionText = fractionText.replace(/0+$/, '')
+  if (fractionText.length < minFractionDigits) fractionText = fractionText.padEnd(minFractionDigits, '0')
+
+  return fractionText.length > 0 ? `${whole.toString()}.${fractionText}` : whole.toString()
+}
+
+export function formatWalletAmount(
+  chain: WalletChain,
+  atomicValue: string | number | bigint,
+  opts?: { minFractionDigits?: number; maxFractionDigits?: number }
+): string {
+  return formatAtomicAmount(atomicValue, getWalletChainMeta(chain).decimals, opts)
+}
+
+export function getWalletExplorerUrl(chain: WalletChain, kind: 'address' | 'transaction', value: string): string {
+  const meta = getWalletChainMeta(chain)
+  const base = kind === 'address' ? meta.addressExplorerBaseUrl : meta.transactionExplorerBaseUrl
+  return `${base}${value}`
+}
+
+export function getWalletAssetSymbol(chain: WalletChain): string {
+  return getWalletChainMeta(chain).symbol
+}
+
+export function getWalletAtomicAmount(value: { amountAtomic?: string; amountLamports?: number } | null | undefined): string {
+  if (!value) return '0'
+  return normalizeAtomicString(value.amountAtomic, normalizeAtomicString(value.amountLamports, '0'))
+}
+
+export function getWalletFeeAtomicAmount(value: { feeAtomic?: string; feeLamports?: number } | null | undefined): string {
+  if (!value) return '0'
+  return normalizeAtomicString(value.feeAtomic, normalizeAtomicString(value.feeLamports, '0'))
+}
+
+export function getWalletLimitAtomic(
+  wallet: { chain: WalletChain; spendingLimitAtomic?: string; spendingLimitLamports?: number; dailyLimitAtomic?: string; dailyLimitLamports?: number },
+  limit: 'perTx' | 'daily',
+): string {
+  if (limit === 'perTx') {
+    return normalizeAtomicString(
+      wallet.spendingLimitAtomic,
+      normalizeAtomicString(wallet.spendingLimitLamports, getWalletDefaultLimitAtomic(wallet.chain, 'perTx')),
+    )
+  }
+  return normalizeAtomicString(
+    wallet.dailyLimitAtomic,
+    normalizeAtomicString(wallet.dailyLimitLamports, getWalletDefaultLimitAtomic(wallet.chain, 'daily')),
+  )
+}
+
+export function getWalletBalanceAtomic(
+  wallet: { balanceAtomic?: string; balanceLamports?: number | null } | null | undefined,
+): string {
+  if (!wallet) return '0'
+  return normalizeAtomicString(wallet.balanceAtomic, normalizeAtomicString(wallet.balanceLamports, '0'))
+}

package/src/proxy.test.ts

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict'
+import { afterEach, describe, it } from 'node:test'
+
+import { NextRequest } from 'next/server'
+
+import { proxy } from './proxy'
+
+const originalAccessKey = process.env.ACCESS_KEY
+
+afterEach(() => {
+  if (originalAccessKey === undefined) delete process.env.ACCESS_KEY
+  else process.env.ACCESS_KEY = originalAccessKey
+})
+
+describe('proxy', () => {
+  it('keeps CORS headers on plugin-install auth failures for allowed origins', () => {
+    process.env.ACCESS_KEY = 'top-secret'
+
+    const request = new NextRequest('http://localhost/api/plugins/install', {
+      method: 'POST',
+      headers: {
+        origin: 'https://swarmclaw.ai',
+      },
+    })
+
+    const response = proxy(request)
+    assert.equal(response.status, 401)
+    assert.equal(response.headers.get('access-control-allow-origin'), 'https://swarmclaw.ai')
+    assert.equal(response.headers.get('vary'), 'Origin')
+  })
+})