@swarmclawai/swarmclaw 0.7.3 → 0.7.5

package/src/app/page.tsx

@@ -4,6 +4,7 @@ import { useEffect, useState, useCallback } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
 import { initAudioContext } from '@/lib/tts'
 import { getStoredAccessKey, clearStoredAccessKey, api } from '@/lib/api-client'
+import { safeStorageGet, safeStorageRemove, safeStorageSet } from '@/lib/safe-storage'
 import { connectWs, disconnectWs } from '@/lib/ws-client'
 import { fetchWithTimeout } from '@/lib/fetch-timeout'
 import { useWs } from '@/hooks/use-ws'
@@ -12,10 +13,17 @@ import { UserPicker } from '@/components/auth/user-picker'
 import { SetupWizard } from '@/components/auth/setup-wizard'
 import { AppLayout } from '@/components/layout/app-layout'
 import { useViewRouter } from '@/hooks/use-view-router'
+import type { Agent } from '@/types'
 
 const AUTH_CHECK_TIMEOUT_MS = 8_000
+const POST_AUTH_BOOTSTRAP_TIMEOUT_MS = 8_000
 
-function FullScreenLoader() {
+function FullScreenLoader(props: {
+  stage?: string | null
+  stalled?: boolean
+  onReload?: () => void
+  onReset?: () => void
+}) {
   return (
     <div className="h-full flex flex-col items-center justify-center bg-bg overflow-hidden select-none">
       {/* Animated orbital ring */}
@@ -106,6 +114,42 @@ function FullScreenLoader() {
         />
       </div>
 
+      {props.stage ? (
+        <p
+          className="mt-4 text-[12px] text-text-3"
+          style={{ animation: 'fade-up 0.6s var(--ease-spring) 0.4s both' }}
+        >
+          {props.stage}
+        </p>
+      ) : null}
+
+      {props.stalled ? (
+        <div
+          className="mt-6 max-w-[360px] px-4 text-center"
+          style={{ animation: 'fade-up 0.6s var(--ease-spring) 0.5s both' }}
+        >
+          <p className="text-[12px] text-text-2">
+            Startup is taking longer than expected. This usually means the browser kept stale local state while the dev server restarted.
+          </p>
+          <div className="mt-4 flex items-center justify-center gap-3">
+            <button
+              type="button"
+              onClick={props.onReload}
+              className="px-4 py-2 rounded-[12px] border border-white/[0.08] bg-surface text-[12px] text-text-2 transition-colors hover:bg-surface-2"
+            >
+              Reload
+            </button>
+            <button
+              type="button"
+              onClick={props.onReset}
+              className="px-4 py-2 rounded-[12px] border border-white/[0.08] bg-transparent text-[12px] text-text-3 transition-colors hover:bg-white/[0.04]"
+            >
+              Reset Local Session
+            </button>
+          </div>
+        </div>
+      ) : null}
+
       {/* Loading animation keyframes */}
       <style>{`
         @keyframes sc-orbit {
@@ -150,8 +194,9 @@ export default function Home() {
 
   const [authChecked, setAuthChecked] = useState(false)
   const [authenticated, setAuthenticated] = useState(false)
+  const [bootTimedOut, setBootTimedOut] = useState(false)
   const [setupDone, setSetupDone] = useState<boolean | null>(() => {
-    if (typeof window !== 'undefined' && localStorage.getItem('sc_setup_done') === '1') return true
+    if (safeStorageGet('sc_setup_done') === '1') return true
     return null
   })
 
@@ -183,7 +228,8 @@ export default function Home() {
         setAuthenticated(false)
       }
     } catch {
-      setAuthenticated(true)
+      clearStoredAccessKey()
+      setAuthenticated(false)
     } finally {
       setAuthChecked(true)
     }
@@ -193,7 +239,10 @@ export default function Home() {
   const syncUserFromServer = useCallback(async () => {
     if (currentUser) return // already have a name locally
     try {
-      const settings = await api<{ userName?: string }>('GET', '/settings')
+      const settings = await api<{ userName?: string }>('GET', '/settings', undefined, {
+        timeoutMs: POST_AUTH_BOOTSTRAP_TIMEOUT_MS,
+        retries: 0,
+      })
       if (settings.userName) {
         setUser(settings.userName)
       }
@@ -229,11 +278,14 @@ export default function Home() {
     let cancelled = false
     ;(async () => {
       try {
-        const state = useAppStore.getState()
-        await state.loadAgents()
+        const agents = await api<Record<string, Agent>>('GET', '/agents', undefined, {
+          timeoutMs: POST_AUTH_BOOTSTRAP_TIMEOUT_MS,
+          retries: 0,
+        })
         if (cancelled) return
+        useAppStore.setState({ agents })
 
-        const { agents, currentAgentId, appSettings } = useAppStore.getState()
+        const { currentAgentId, appSettings } = useAppStore.getState()
         // Priority: persisted agent > settings default > first agent
         const targetId = (currentAgentId && agents[currentAgentId])
           ? currentAgentId
@@ -256,14 +308,23 @@ export default function Home() {
     let cancelled = false
     ;(async () => {
       try {
-        const [settings, creds] = await Promise.all([
-          api<{ setupCompleted?: boolean }>('GET', '/settings'),
-          api<Record<string, unknown>>('GET', '/credentials'),
+        const [settingsResult, credsResult] = await Promise.allSettled([
+          api<{ setupCompleted?: boolean }>('GET', '/settings', undefined, {
+            timeoutMs: POST_AUTH_BOOTSTRAP_TIMEOUT_MS,
+            retries: 0,
+          }),
+          api<Record<string, unknown>>('GET', '/credentials', undefined, {
+            timeoutMs: POST_AUTH_BOOTSTRAP_TIMEOUT_MS,
+            retries: 0,
+          }),
         ])
         if (cancelled) return
+        const settings = settingsResult.status === 'fulfilled' ? settingsResult.value : {}
+        const creds = credsResult.status === 'fulfilled' ? credsResult.value : {}
+        const bothFailed = settingsResult.status === 'rejected' && credsResult.status === 'rejected'
         const hasCreds = Object.keys(creds).length > 0
-        const done = settings.setupCompleted === true || hasCreds
-        if (done) localStorage.setItem('sc_setup_done', '1')
+        const done = bothFailed ? true : settings.setupCompleted === true || hasCreds
+        if (done) safeStorageSet('sc_setup_done', '1')
         setSetupDone(done)
       } catch {
         if (!cancelled) setSetupDone(true) // on error, skip wizard
@@ -293,10 +354,60 @@ export default function Home() {
 
   useViewRouter()
 
-  if (!hydrated || !authChecked) return <FullScreenLoader />
+  const bootStage = !hydrated
+    ? 'Restoring local session'
+    : !authChecked
+      ? 'Checking access'
+      : authenticated && currentUser && setupDone === null
+        ? 'Loading setup state'
+        : authenticated && currentUser && !agentReady
+          ? 'Restoring agent workspace'
+          : null
+
+  useEffect(() => {
+    if (!bootStage) {
+      setBootTimedOut(false)
+      return
+    }
+    const timer = window.setTimeout(() => setBootTimedOut(true), 15_000)
+    return () => window.clearTimeout(timer)
+  }, [bootStage])
+
+  const reloadApp = useCallback(() => {
+    window.location.reload()
+  }, [])
+
+  const resetLocalSession = useCallback(() => {
+    clearStoredAccessKey()
+    disconnectWs()
+    safeStorageRemove('sc_user')
+    safeStorageRemove('sc_agent')
+    safeStorageRemove('sc_setup_done')
+    window.location.assign('/')
+  }, [])
+
+  if (!hydrated || !authChecked) {
+    return (
+      <FullScreenLoader
+        stage={bootStage}
+        stalled={bootTimedOut}
+        onReload={reloadApp}
+        onReset={resetLocalSession}
+      />
+    )
+  }
   if (!authenticated) return <AccessKeyGate onAuthenticated={() => setAuthenticated(true)} />
   if (!currentUser) return <UserPicker />
-  if (setupDone === null || !agentReady) return <FullScreenLoader />
-  if (!setupDone) return <SetupWizard onComplete={() => { localStorage.setItem('sc_setup_done', '1'); setSetupDone(true) }} />
+  if (setupDone === null || !agentReady) {
+    return (
+      <FullScreenLoader
+        stage={bootStage}
+        stalled={bootTimedOut}
+        onReload={reloadApp}
+        onReset={resetLocalSession}
+      />
+    )
+  }
+  if (!setupDone) return <SetupWizard onComplete={() => { safeStorageSet('sc_setup_done', '1'); setSetupDone(true) }} />
   return <AppLayout />
 }

package/src/cli/binary.test.js

@@ -0,0 +1,142 @@
+'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+const { buildLegacyTsCliArgs } = require('../../bin/swarmclaw.js')
+
+const CLI_BIN = path.join(__dirname, '..', '..', 'bin', 'swarmclaw.js')
+const PACKAGE_JSON = require('../../package.json')
+const APP_ROOT = path.join(__dirname, '..', '..')
+
+function runBinary(args, options = {}) {
+  return spawnSync(process.execPath, [CLI_BIN, ...args], {
+    cwd: options.cwd || APP_ROOT,
+    env: {
+      ...process.env,
+      ...options.env,
+    },
+    encoding: 'utf8',
+  })
+}
+
+function runWithMockedFetch(args, options = {}) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-binary-fetch-'))
+  const capturePath = path.join(tmpDir, 'capture.json')
+  const preloadPath = path.join(tmpDir, 'mock-fetch.cjs')
+
+  fs.writeFileSync(
+    preloadPath,
+    `
+const fs = require('node:fs')
+globalThis.fetch = async (url, init = {}) => {
+  const capture = {
+    url: String(url),
+    method: init.method || 'GET',
+    headers: init.headers || {},
+    body: typeof init.body === 'string'
+      ? init.body
+      : (Buffer.isBuffer(init.body) ? init.body.toString('utf8') : null),
+  }
+  fs.writeFileSync(process.env.SWARMCLAW_TEST_CAPTURE, JSON.stringify(capture), 'utf8')
+  return new Response(JSON.stringify([]), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+`,
+    'utf8',
+  )
+
+  const nodeOptions = [process.env.NODE_OPTIONS, `--require=${preloadPath}`]
+    .filter(Boolean)
+    .join(' ')
+
+  const result = runBinary(args, {
+    ...options,
+    env: {
+      ...options.env,
+      NODE_OPTIONS: nodeOptions,
+      SWARMCLAW_TEST_CAPTURE: capturePath,
+    },
+  })
+
+  const capture = fs.existsSync(capturePath)
+    ? JSON.parse(fs.readFileSync(capturePath, 'utf8'))
+    : null
+
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+  return { result, capture }
+}
+
+test('legacy-routed binary commands honor SWARMCLAW_API_KEY', () => {
+  const { result, capture } = runWithMockedFetch(
+    ['runs', 'list', '--raw', '--url', 'http://localhost:3456'],
+    {
+      env: {
+        SWARMCLAW_API_KEY: 'legacy-api-key',
+        SWARMCLAW_ACCESS_KEY: '',
+        SC_ACCESS_KEY: '',
+      },
+    },
+  )
+
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), '[]')
+  assert.equal(capture.headers['X-Access-Key'], 'legacy-api-key')
+})
+
+test('legacy-routed binary commands fall back to platform-api-key.txt', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-binary-keyfile-'))
+  fs.writeFileSync(path.join(tmpDir, 'platform-api-key.txt'), 'file-fallback-key\n', 'utf8')
+
+  const { result, capture } = runWithMockedFetch(
+    ['runs', 'list', '--raw', '--url', 'http://localhost:3456'],
+    {
+      cwd: tmpDir,
+      env: {
+        SWARMCLAW_API_KEY: '',
+        SWARMCLAW_ACCESS_KEY: '',
+        SC_ACCESS_KEY: '',
+      },
+    },
+  )
+
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), '[]')
+  assert.equal(capture.headers['X-Access-Key'], 'file-fallback-key')
+
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+test('binary server help exits successfully', () => {
+  const result = runBinary(['server', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw server/i)
+})
+
+test('binary update help exits successfully', () => {
+  const result = runBinary(['update', '--help'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Usage: swarmclaw update/i)
+})
+
+test('binary version output matches package version', () => {
+  const result = runBinary(['--version'])
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), `${PACKAGE_JSON.name} ${PACKAGE_JSON.version}`)
+})
+
+test('legacy TS launcher falls back to tsx import when strip-types is unavailable', () => {
+  const cliPath = path.join(APP_ROOT, 'src', 'cli', 'index.ts')
+  const args = buildLegacyTsCliArgs(cliPath, ['runs', 'list'], {
+    supportsStripTypes: false,
+    hasTsxRuntime: true,
+  })
+
+  assert.deepEqual(args, ['--no-warnings', '--import', 'tsx', cliPath, 'runs', 'list'])
+})

package/src/cli/index.js

@@ -181,6 +181,17 @@ const COMMAND_GROUPS = [
       cmd('suite', 'POST', '/eval/suite', 'Run a full eval suite against an agent', { expectsJsonBody: true }),
     ],
   },
+  {
+    name: 'external-agents',
+    description: 'Manage external agent runtimes',
+    commands: [
+      cmd('list', 'GET', '/external-agents', 'List external agent runtimes'),
+      cmd('create', 'POST', '/external-agents', 'Register an external agent runtime', { expectsJsonBody: true }),
+      cmd('update', 'PUT', '/external-agents/:id', 'Update an external agent runtime', { expectsJsonBody: true }),
+      cmd('delete', 'DELETE', '/external-agents/:id', 'Delete an external agent runtime'),
+      cmd('heartbeat', 'POST', '/external-agents/:id/heartbeat', 'Record an external agent heartbeat', { expectsJsonBody: true }),
+    ],
+  },
   {
     name: 'files',
     description: 'Serve and manage local files',
@@ -189,6 +200,17 @@ const COMMAND_GROUPS = [
       cmd('open', 'POST', '/files/open', 'Open a local file path via the host default app/browser', { expectsJsonBody: true }),
     ],
   },
+  {
+    name: 'gateways',
+    description: 'Manage named OpenClaw gateway profiles',
+    commands: [
+      cmd('list', 'GET', '/gateways', 'List configured gateway profiles'),
+      cmd('create', 'POST', '/gateways', 'Create a gateway profile', { expectsJsonBody: true }),
+      cmd('update', 'PUT', '/gateways/:id', 'Update a gateway profile', { expectsJsonBody: true }),
+      cmd('delete', 'DELETE', '/gateways/:id', 'Delete a gateway profile'),
+      cmd('health', 'GET', '/gateways/:id/health', 'Run a gateway health check'),
+    ],
+  },
   {
     name: 'ip',
     description: 'Get local IP/port metadata',
@@ -364,6 +386,7 @@ const COMMAND_GROUPS = [
       cmd('update', 'PUT', '/providers/:id', 'Update provider', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/providers/:id', 'Delete provider'),
       cmd('configs', 'GET', '/providers/configs', 'List saved provider configs'),
+      cmd('discover-models', 'GET', '/providers/:id/discover-models', 'Discover provider models via endpoint or credential checks'),
       cmd('ollama', 'GET', '/providers/ollama', 'List local Ollama models (use --query endpoint=http://localhost:11434)'),
       cmd('openclaw-health', 'GET', '/providers/openclaw/health', 'Probe OpenClaw endpoint/auth (use --query endpoint= --query credentialId= --query model=)'),
       cmd('models', 'GET', '/providers/:id/models', 'Get provider model overrides'),
@@ -429,10 +452,6 @@ const COMMAND_GROUPS = [
       cmd('messages-delete', 'DELETE', '/chats/:id/messages', 'Delete a message from a chat', { expectsJsonBody: true }),
       cmd('fork', 'POST', '/chats/:id/fork', 'Fork chat from a specific message index', { expectsJsonBody: true }),
       cmd('edit-resend', 'POST', '/chats/:id/edit-resend', 'Edit and resend from a specific message index', { expectsJsonBody: true }),
-      cmd('main-loop', 'GET', '/chats/:id/main-loop', 'Get main mission loop state'),
-      cmd('main-loop-action', 'POST', '/chats/:id/main-loop', 'Control main mission loop (pause/resume/set_goal/set_mode/clear_events/nudge)', {
-        expectsJsonBody: true,
-      }),
       cmd('chat', 'POST', '/chats/:id/chat', 'Send chat message (streaming)', {
         expectsJsonBody: true,
         responseType: 'sse',
@@ -677,7 +696,7 @@ function normalizeBaseUrl(raw) {
 
 function resolveAccessKey(opts, env, cwd) {
   if (opts.accessKey) return String(opts.accessKey).trim()
-  const envKey = env.SWARMCLAW_API_KEY || env.SC_ACCESS_KEY || ''
+  const envKey = env.SWARMCLAW_API_KEY || env.SC_ACCESS_KEY || env.SWARMCLAW_ACCESS_KEY || ''
   if (envKey) return String(envKey).trim()
 
   const keyFile = path.join(cwd, 'platform-api-key.txt')
@@ -927,9 +946,11 @@ async function consumeSse(body, stdout, stderr, jsonOutput) {
   const reader = body.getReader()
   const decoder = new TextDecoder()
   let buffer = ''
+  const eventBoundary = /\r?\n\r?\n/
 
   function flushChunk(rawChunk) {
     const lines = rawChunk
+      .replace(/\r\n/g, '\n')
       .split('\n')
       .map((line) => line.trimEnd())
       .filter(Boolean)
@@ -972,12 +993,14 @@ async function consumeSse(body, stdout, stderr, jsonOutput) {
     if (done) break
     buffer += decoder.decode(value, { stream: true })
 
-    let splitIndex = buffer.indexOf('\n\n')
-    while (splitIndex >= 0) {
+    let match = eventBoundary.exec(buffer)
+    while (match) {
+      const splitIndex = match.index
+      const delimiterLength = match[0].length
       const chunk = buffer.slice(0, splitIndex)
-      buffer = buffer.slice(splitIndex + 2)
+      buffer = buffer.slice(splitIndex + delimiterLength)
       flushChunk(chunk)
-      splitIndex = buffer.indexOf('\n\n')
+      match = eventBoundary.exec(buffer)
     }
   }
 
@@ -1090,7 +1113,7 @@ function renderGeneralHelp() {
     '',
     'Global options:',
     '  --base-url <url>       API base URL (default: http://localhost:3456)',
-    '  --access-key <key>     Access key override (else SWARMCLAW_API_KEY or platform-api-key.txt)',
+    '  --access-key <key>     Access key override (else SWARMCLAW_API_KEY/SWARMCLAW_ACCESS_KEY or platform-api-key.txt)',
     '  --data <json|@file|->  Request JSON body',
     '  --query key=value      Query parameter (repeatable)',
     '  --header key=value     Extra HTTP header (repeatable)',
@@ -1215,7 +1238,7 @@ async function runCli(argv, deps = {}) {
   }
 
   const accessKey = resolveAccessKey(parsed.opts, env, cwd)
-  const baseUrl = parsed.opts.baseUrl || env.SWARMCLAW_BASE_URL || 'http://localhost:3456'
+  const baseUrl = parsed.opts.baseUrl || env.SWARMCLAW_BASE_URL || env.SWARMCLAW_URL || 'http://localhost:3456'
 
   const headerEntries = []
   for (const raw of parsed.opts.headers) {

package/src/cli/index.test.js

@@ -163,6 +163,37 @@ test('runCli sends authenticated request and emits compact JSON when --json is s
   assert.equal(stderr.toString(), '')
 })
 
+test('runCli falls back to platform-api-key.txt when env key is missing', async () => {
+  const stdout = makeWritable()
+  const stderr = makeWritable()
+  const calls = []
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-cli-keyfile-'))
+  fs.writeFileSync(path.join(tmpDir, 'platform-api-key.txt'), 'file-key\n', 'utf8')
+
+  const fetchImpl = async (url, init) => {
+    calls.push({ url: String(url), init })
+    return jsonResponse({ ok: true })
+  }
+
+  const exitCode = await runCli(
+    ['runs', 'list', '--json'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: tmpDir,
+    }
+  )
+
+  assert.equal(exitCode, 0)
+  assert.equal(calls[0].init.headers['X-Access-Key'], 'file-key')
+  assert.equal(stderr.toString(), '')
+
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
 test('upload command sends binary body and x-filename header', async () => {
   const stdout = makeWritable()
   const stderr = makeWritable()
@@ -197,6 +228,32 @@ test('upload command sends binary body and x-filename header', async () => {
   fs.rmSync(tmpDir, { recursive: true, force: true })
 })
 
+test('binary responses require --out when stdout is a TTY', async () => {
+  const stdout = makeWritable()
+  stdout.isTTY = true
+  const stderr = makeWritable()
+
+  const fetchImpl = async () =>
+    new Response(Buffer.from('hello'), {
+      status: 200,
+      headers: { 'content-type': 'application/octet-stream' },
+    })
+
+  const exitCode = await runCli(
+    ['uploads', 'get', 'artifact.bin'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: process.cwd(),
+    }
+  )
+
+  assert.equal(exitCode, 1)
+  assert.match(stderr.toString(), /binary response requires --out <file>/i)
+})
+
 test('wait polls run endpoint until terminal state', async () => {
   const stdout = makeWritable()
   const stderr = makeWritable()
@@ -236,6 +293,144 @@ test('wait polls run endpoint until terminal state', async () => {
   assert.match(stdout.toString(), /"status": "completed"/)
 })
 
+test('runCli parses CRLF-delimited SSE events correctly', async () => {
+  const stdout = makeWritable()
+  const stderr = makeWritable()
+
+  const fetchImpl = async () => new Response(
+    'data: {"t":"md","text":"first"}\r\n\r\ndata: {"t":"md","text":"second"}\r\n\r\n',
+    {
+      status: 200,
+      headers: { 'content-type': 'text/event-stream' },
+    }
+  )
+
+  const exitCode = await runCli(
+    ['chatrooms', 'chat', 'room-1', '--data', '{}'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: process.cwd(),
+    }
+  )
+
+  assert.equal(exitCode, 0)
+  assert.equal(stdout.toString(), 'first\nsecond\n')
+  assert.equal(stderr.toString(), '')
+})
+
+test('binary responses require --out when stdout is a TTY', async () => {
+  const stdout = makeWritable()
+  stdout.isTTY = true
+  const stderr = makeWritable()
+
+  const fetchImpl = async () => new Response(Buffer.from('ok'), {
+    status: 200,
+    headers: { 'content-type': 'application/octet-stream' },
+  })
+
+  const exitCode = await runCli(
+    ['memory-images', 'get', 'image-1.png'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: process.cwd(),
+    }
+  )
+
+  assert.equal(exitCode, 1)
+  assert.equal(stdout.toString(), '')
+  assert.match(stderr.toString(), /binary response requires --out <file>/i)
+})
+
+test('client-side collection lookups fail cleanly when the entity is missing', async () => {
+  const stdout = makeWritable()
+  const stderr = makeWritable()
+
+  const fetchImpl = async () => jsonResponse([{ id: 'agent-2', name: 'Other Agent' }])
+
+  const exitCode = await runCli(
+    ['agents', 'get', 'agent-1'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: process.cwd(),
+    }
+  )
+
+  assert.equal(exitCode, 1)
+  assert.equal(stdout.toString(), '')
+  assert.match(stderr.toString(), /entity not found for id: agent-1/i)
+})
+
+test('runCli loads request JSON from @file inputs', async () => {
+  const stdout = makeWritable()
+  const stderr = makeWritable()
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-cli-data-'))
+  const dataPath = path.join(tmpDir, 'payload.json')
+  fs.writeFileSync(dataPath, JSON.stringify({ title: 'From file', status: 'backlog' }), 'utf8')
+
+  const calls = []
+  const fetchImpl = async (url, init) => {
+    calls.push({ url: String(url), init })
+    return jsonResponse({ ok: true })
+  }
+
+  const exitCode = await runCli(
+    ['tasks', 'create', '--data', `@${dataPath}`],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: process.cwd(),
+    }
+  )
+
+  assert.equal(exitCode, 0)
+  assert.equal(calls.length, 1)
+  assert.equal(calls[0].init.headers['Content-Type'], 'application/json')
+  assert.deepEqual(JSON.parse(calls[0].init.body), { title: 'From file', status: 'backlog' })
+
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+test('runCli falls back to platform-api-key.txt when no env key is provided', async () => {
+  const stdout = makeWritable()
+  const stderr = makeWritable()
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-cli-key-'))
+  fs.writeFileSync(path.join(tmpDir, 'platform-api-key.txt'), 'file-key\n', 'utf8')
+
+  const calls = []
+  const fetchImpl = async (url, init) => {
+    calls.push({ url: String(url), init })
+    return jsonResponse({ ok: true })
+  }
+
+  const exitCode = await runCli(
+    ['runs', 'list'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: tmpDir,
+    }
+  )
+
+  assert.equal(exitCode, 0)
+  assert.equal(calls.length, 1)
+  assert.equal(calls[0].init.headers['X-Access-Key'], 'file-key')
+
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
 test('all command definitions execute with a mocked API transport', async () => {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-cli-all-'))
   const uploadPath = path.join(tmpDir, 'upload.txt')