@swarmclawai/swarmclaw 0.7.1 → 0.7.3

package/src/app/api/tasks/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server'
 import { genId } from '@/lib/id'
-import { loadTasks, saveTasks, loadSettings, loadAgents, logActivity } from '@/lib/server/storage'
+import { deleteTask, loadAgents, loadSettings, loadTasks, logActivity, upsertTask } from '@/lib/server/storage'
 import { TaskCreateSchema, formatZodError } from '@/lib/validation/schemas'
 import { z } from 'zod'
 import { enqueueTask, recoverStalledRunningTasks, validateCompletedTasksQueue } from '@/lib/server/queue'
@@ -13,6 +13,7 @@ import { resolveTaskAgentFromDescription } from '@/lib/server/task-mention'
 import { validateDag } from '@/lib/server/dag-validation'
 import { getPluginManager } from '@/lib/server/plugins'
 import { normalizeTaskQualityGate } from '@/lib/server/task-quality-gate'
+import '@/lib/server/builtin-plugins'
 
 export async function GET(req: Request) {
   // Keep completed queue integrity even if daemon is not running.
@@ -49,7 +50,6 @@ export async function DELETE(req: Request) {
     (filter === 'done' && (task.status === 'completed' || task.status === 'failed')) ||
     (!filter && task.status === 'archived')
 
-  const { deleteTask } = await import('@/lib/server/storage')
   for (const [id, task] of Object.entries(tasks)) {
     if (shouldRemove(task as { status: string; sourceType?: string })) {
       deleteTask(id)
@@ -169,7 +169,12 @@ export async function POST(req: Request) {
     if (validation.ok) {
       tasks[id].completedAt = Date.now()
       tasks[id].error = null
-      getPluginManager().runHook('onTaskComplete', { taskId: id, result: tasks[id].result })
+      const agentPlugins = resolvedAgentId ? (loadAgents()[resolvedAgentId]?.plugins || []) : []
+      getPluginManager().runHook(
+        'onTaskComplete',
+        { taskId: id, result: tasks[id].result },
+        { enabledIds: agentPlugins },
+      )
     } else {
       tasks[id].status = 'failed'
       tasks[id].completedAt = null
@@ -177,7 +182,7 @@ export async function POST(req: Request) {
     }
   }
 
-  saveTasks(tasks)
+  upsertTask(id, tasks[id])
   logActivity({ entityType: 'task', entityId: id, action: 'created', actor: 'user', summary: `Task created: "${tasks[id].title}"` })
   pushMainLoopEventToMainSessions({
     type: 'task_created',

package/src/app/api/usage/route.ts

@@ -50,6 +50,7 @@ export async function GET(req: Request) {
   let totalCost = 0
   const byAgent: Record<string, { name: string; cost: number; tokens: number; count: number }> = {}
   const byProvider: Record<string, { tokens: number; cost: number }> = {}
+  const byPlugin: Record<string, { definitionTokens: number; invocationTokens: number; invocations: number; estimatedCost: number }> = {}
   const bucketMap: Record<string, { tokens: number; cost: number }> = {}
 
   for (const r of records) {
@@ -75,6 +76,26 @@ export async function GET(req: Request) {
     byAgent[agentId].tokens += tokens
     byAgent[agentId].count += 1
 
+    // by plugin — definition costs (context overhead per LLM call)
+    if (Array.isArray(r.pluginDefinitionCosts)) {
+      for (const dc of r.pluginDefinitionCosts) {
+        if (!dc.pluginId) continue
+        if (!byPlugin[dc.pluginId]) byPlugin[dc.pluginId] = { definitionTokens: 0, invocationTokens: 0, invocations: 0, estimatedCost: 0 }
+        byPlugin[dc.pluginId].definitionTokens += dc.estimatedTokens || 0
+      }
+    }
+
+    // by plugin — invocation costs (actual tool calls)
+    if (Array.isArray(r.pluginInvocations)) {
+      for (const inv of r.pluginInvocations) {
+        if (!inv.pluginId) continue
+        if (!byPlugin[inv.pluginId]) byPlugin[inv.pluginId] = { definitionTokens: 0, invocationTokens: 0, invocations: 0, estimatedCost: 0 }
+        const p = byPlugin[inv.pluginId]
+        p.invocationTokens += (inv.inputTokens || 0) + (inv.outputTokens || 0)
+        p.invocations += 1
+      }
+    }
+
     // time series bucketing
     const bk = bucketKey(r.timestamp || now, range)
     if (!bucketMap[bk]) bucketMap[bk] = { tokens: 0, cost: 0 }
@@ -82,6 +103,14 @@ export async function GET(req: Request) {
     bucketMap[bk].cost += cost
   }
 
+  // Estimate per-plugin cost using the average input token rate from total usage
+  if (totalTokens > 0 && totalCost > 0) {
+    const avgCostPerToken = totalCost / totalTokens
+    for (const p of Object.values(byPlugin)) {
+      p.estimatedCost = Math.round((p.definitionTokens + p.invocationTokens) * avgCostPerToken * 10000) / 10000
+    }
+  }
+
   // Sort time series
   const timeSeries = Object.entries(bucketMap)
     .sort(([a], [b]) => a.localeCompare(b))
@@ -144,6 +173,7 @@ export async function GET(req: Request) {
     totalCost: Math.round(totalCost * 10000) / 10000,
     byAgent,
     byProvider,
+    byPlugin,
     timeSeries,
     providerHealth,
   })

package/src/app/api/webhooks/[id]/route.ts

@@ -8,6 +8,7 @@ import { enqueueSystemEvent } from '@/lib/server/system-events'
 import { requestHeartbeatNow } from '@/lib/server/heartbeat-wake'
 import { mutateItem, deleteItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
 import type { WebhookRetryEntry } from '@/types'
+import { triggerWebhookWatchJobs } from '@/lib/server/watch-jobs'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: loadWebhooks, save: saveWebhooks }
@@ -126,6 +127,12 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
     })
   }
 
+  triggerWebhookWatchJobs({
+    webhookId: id,
+    event: incomingEvent,
+    payloadPreview: rawBody,
+  })
+
   const agents = loadAgents()
   const agent = webhook.agentId ? agents[webhook.agentId] : null
   if (!agent) {
@@ -165,7 +172,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
       messages: [],
       createdAt: now,
       lastActiveAt: now,
-      sessionType: 'orchestrated',
+      sessionType: 'human',
       agentId: agent.id,
       parentSessionId: null,
       tools: agent.tools || [],

package/src/app/page.tsx

@@ -158,8 +158,15 @@ export default function Home() {
   const checkAuth = useCallback(async () => {
     const key = getStoredAccessKey()
     if (!key) {
-      setAuthChecked(true)
-      setAuthenticated(false)
+      try {
+        const res = await fetchWithTimeout('/api/auth', {}, AUTH_CHECK_TIMEOUT_MS)
+        const data = await res.json().catch(() => ({}))
+        setAuthenticated(data?.authenticated === true)
+      } catch {
+        setAuthenticated(false)
+      } finally {
+        setAuthChecked(true)
+      }
       return
     }
 

package/src/cli/index.js

@@ -120,6 +120,9 @@ const COMMAND_GROUPS = [
         defaultBody: { action: 'repair' },
       }),
       cmd('health', 'GET', '/connectors/:id/health', 'Get connector health status'),
+      cmd('doctor', 'GET', '/connectors/:id/doctor', 'Get connector doctor diagnostics'),
+      cmd('doctor-preview', 'POST', '/connectors/:id/doctor', 'Preview connector doctor diagnostics with temporary overrides', { expectsJsonBody: true }),
+      cmd('doctor-draft', 'POST', '/connectors/doctor', 'Preview connector doctor diagnostics before saving a connector', { expectsJsonBody: true }),
     ],
   },
   {
@@ -344,7 +347,10 @@ const COMMAND_GROUPS = [
       cmd('delete', 'DELETE', '/plugins', 'Delete an external plugin (use --query filename=plugin.js)'),
       cmd('update', 'PATCH', '/plugins', 'Update a plugin (use --query id=plugin.js or --query all=true)'),
       cmd('install', 'POST', '/plugins/install', 'Install plugin from URL', { expectsJsonBody: true }),
+      cmd('install-deps', 'POST', '/plugins/dependencies', 'Install or refresh plugin workspace dependencies', { expectsJsonBody: true }),
       cmd('marketplace', 'GET', '/plugins/marketplace', 'Get marketplace catalog'),
+      cmd('settings-get', 'GET', '/plugins/settings', 'Get plugin settings (use --query pluginId=plugin_name)'),
+      cmd('settings-set', 'PUT', '/plugins/settings', 'Set plugin settings (use --query pluginId=plugin_name and --data JSON)', { expectsJsonBody: true }),
       cmd('ui', 'GET', '/plugins/ui', 'List plugin UI extensions (use --query type=sidebar|header|chat_actions|connectors)'),
     ],
   },
@@ -369,7 +375,7 @@ const COMMAND_GROUPS = [
     name: 'search',
     description: 'Global search across app resources',
     commands: [
-      cmd('query', 'GET', '/search', 'Search agents/tasks/sessions/schedules/webhooks/skills (use --query q=term)'),
+      cmd('query', 'GET', '/search', 'Search agents/tasks/chats/schedules/webhooks/skills (use --query q=term)'),
     ],
   },
   {
@@ -404,56 +410,56 @@ const COMMAND_GROUPS = [
     ],
   },
   {
-    name: 'sessions',
-    description: 'Manage chat sessions and runtime controls',
+    name: 'chats',
+    description: 'Manage agent chats and runtime controls',
     commands: [
-      cmd('list', 'GET', '/sessions', 'List sessions'),
-      cmd('get', 'GET', '/sessions/:id', 'Get session by id', { virtual: true, clientGetRoute: '/sessions' }),
-      cmd('create', 'POST', '/sessions', 'Create session', { expectsJsonBody: true }),
-      cmd('update', 'PUT', '/sessions/:id', 'Update session', { expectsJsonBody: true }),
-      cmd('delete', 'DELETE', '/sessions/:id', 'Delete session'),
-      cmd('delete-many', 'DELETE', '/sessions', 'Delete multiple sessions (body: {"ids":[...]})', { expectsJsonBody: true }),
-      cmd('heartbeat-disable-all', 'POST', '/sessions/heartbeat', 'Disable all session heartbeats and cancel queued heartbeat runs', {
+      cmd('list', 'GET', '/chats', 'List chats'),
+      cmd('get', 'GET', '/chats/:id', 'Get chat by id', { virtual: true, clientGetRoute: '/chats' }),
+      cmd('create', 'POST', '/chats', 'Create chat', { expectsJsonBody: true }),
+      cmd('update', 'PUT', '/chats/:id', 'Update chat', { expectsJsonBody: true }),
+      cmd('delete', 'DELETE', '/chats/:id', 'Delete chat'),
+      cmd('delete-many', 'DELETE', '/chats', 'Delete multiple chats (body: {"ids":[...]})', { expectsJsonBody: true }),
+      cmd('heartbeat-disable-all', 'POST', '/chats/heartbeat', 'Disable all chat heartbeats and cancel queued heartbeat runs', {
         expectsJsonBody: true,
         defaultBody: { action: 'disable_all' },
       }),
-      cmd('messages', 'GET', '/sessions/:id/messages', 'Get session messages'),
-      cmd('messages-update', 'PUT', '/sessions/:id/messages', 'Update session message metadata (e.g. bookmark)', { expectsJsonBody: true }),
-      cmd('messages-send', 'POST', '/sessions/:id/messages', 'Append a user/system message to a session', { expectsJsonBody: true }),
-      cmd('messages-delete', 'DELETE', '/sessions/:id/messages', 'Delete a message from a session', { expectsJsonBody: true }),
-      cmd('fork', 'POST', '/sessions/:id/fork', 'Fork session from a specific message index', { expectsJsonBody: true }),
-      cmd('edit-resend', 'POST', '/sessions/:id/edit-resend', 'Edit and resend from a specific message index', { expectsJsonBody: true }),
-      cmd('main-loop', 'GET', '/sessions/:id/main-loop', 'Get main mission loop state'),
-      cmd('main-loop-action', 'POST', '/sessions/:id/main-loop', 'Control main mission loop (pause/resume/set_goal/set_mode/clear_events/nudge)', {
+      cmd('messages', 'GET', '/chats/:id/messages', 'Get chat messages'),
+      cmd('messages-update', 'PUT', '/chats/:id/messages', 'Update chat message metadata (e.g. bookmark)', { expectsJsonBody: true }),
+      cmd('messages-send', 'POST', '/chats/:id/messages', 'Append a user/system message to a chat', { expectsJsonBody: true }),
+      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', '/sessions/:id/chat', 'Send chat message (streaming)', {
+      cmd('chat', 'POST', '/chats/:id/chat', 'Send chat message (streaming)', {
         expectsJsonBody: true,
         responseType: 'sse',
       }),
-      cmd('stop', 'POST', '/sessions/:id/stop', 'Stop session run(s)'),
-      cmd('clear', 'POST', '/sessions/:id/clear', 'Clear session messages'),
-      cmd('browser-status', 'GET', '/sessions/:id/browser', 'Check browser status'),
-      cmd('browser-close', 'DELETE', '/sessions/:id/browser', 'Close browser session'),
-      cmd('mailbox', 'GET', '/sessions/:id/mailbox', 'List session mailbox envelopes'),
-      cmd('mailbox-action', 'POST', '/sessions/:id/mailbox', 'Send/ack/clear mailbox envelopes', { expectsJsonBody: true }),
-      cmd('retry', 'POST', '/sessions/:id/retry', 'Retry last assistant message'),
-      cmd('deploy', 'POST', '/sessions/:id/deploy', 'Deploy current session branch', { expectsJsonBody: true }),
-      cmd('devserver', 'POST', '/sessions/:id/devserver', 'Dev server action via JSON body', { expectsJsonBody: true }),
-      cmd('devserver-start', 'POST', '/sessions/:id/devserver', 'Start session dev server', {
+      cmd('stop', 'POST', '/chats/:id/stop', 'Stop chat run(s)'),
+      cmd('clear', 'POST', '/chats/:id/clear', 'Clear chat messages'),
+      cmd('browser-status', 'GET', '/chats/:id/browser', 'Check browser status'),
+      cmd('browser-close', 'DELETE', '/chats/:id/browser', 'Close browser'),
+      cmd('mailbox', 'GET', '/chats/:id/mailbox', 'List chat mailbox envelopes'),
+      cmd('mailbox-action', 'POST', '/chats/:id/mailbox', 'Send/ack/clear mailbox envelopes', { expectsJsonBody: true }),
+      cmd('retry', 'POST', '/chats/:id/retry', 'Retry last assistant message'),
+      cmd('deploy', 'POST', '/chats/:id/deploy', 'Deploy current chat branch', { expectsJsonBody: true }),
+      cmd('devserver', 'POST', '/chats/:id/devserver', 'Dev server action via JSON body', { expectsJsonBody: true }),
+      cmd('devserver-start', 'POST', '/chats/:id/devserver', 'Start chat dev server', {
         expectsJsonBody: true,
         defaultBody: { action: 'start' },
       }),
-      cmd('devserver-stop', 'POST', '/sessions/:id/devserver', 'Stop session dev server', {
+      cmd('devserver-stop', 'POST', '/chats/:id/devserver', 'Stop chat dev server', {
         expectsJsonBody: true,
         defaultBody: { action: 'stop' },
       }),
-      cmd('devserver-status', 'POST', '/sessions/:id/devserver', 'Check session dev server status', {
+      cmd('devserver-status', 'POST', '/chats/:id/devserver', 'Check chat dev server status', {
         expectsJsonBody: true,
         defaultBody: { action: 'status' },
       }),
-      cmd('checkpoints', 'GET', '/sessions/:id/checkpoints', 'List checkpoint history for a session'),
-      cmd('restore', 'POST', '/sessions/:id/restore', 'Restore session to a previous checkpoint', { expectsJsonBody: true }),
+      cmd('checkpoints', 'GET', '/chats/:id/checkpoints', 'List checkpoint history for a chat'),
+      cmd('restore', 'POST', '/chats/:id/restore', 'Restore chat to a previous checkpoint', { expectsJsonBody: true }),
     ],
   },
   {

package/src/cli/index.ts

@@ -17,7 +17,6 @@ interface CliContext {
 
 interface SetupAuthStatus {
   firstTime?: boolean
-  key?: string
 }
 
 interface SetupProviderCheckResponse {
@@ -208,19 +207,13 @@ async function resolveSetupAccessKey(ctx: CliContext): Promise<{
   }
 
   const status = await apiRequestWithAccessKey<SetupAuthStatus>(ctx, 'GET', '/auth', undefined)
-  const discoveredKey = typeof status?.key === 'string' ? status.key.trim() : ''
   const firstTime = status?.firstTime === true
 
-  if (!firstTime || !discoveredKey) {
-    throw new Error('No access key provided. Pass --key (or SWARMCLAW_ACCESS_KEY), or run setup on a fresh first-time instance.')
+  if (firstTime) {
+    throw new Error('No access key provided. Read the generated key from the launch terminal or .env.local, then pass --key (or SWARMCLAW_ACCESS_KEY).')
   }
 
-  await apiRequestWithAccessKey(ctx, 'POST', '/auth', discoveredKey, { key: discoveredKey })
-  return {
-    accessKey: discoveredKey,
-    firstTime: true,
-    autoDiscovered: true,
-  }
+  throw new Error('No access key provided. Pass --key (or SWARMCLAW_ACCESS_KEY).')
 }
 
 function printResult(value: unknown, rawOutput: boolean): void {
@@ -657,27 +650,28 @@ export function buildProgram(): Command {
       await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'GET', `/runs/${encodeURIComponent(id)}`))
     })
 
-  const sessions = program.command('sessions').description('Manage sessions')
+  const chats = program.command('chats').description('Manage chats')
+  program.command('sessions').description('Manage chats (alias)').action(() => chats.help())
 
-  sessions
+  chats
     .command('list')
-    .description('List sessions')
+    .description('List chats')
     .action(async function () {
-      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'GET', '/sessions'))
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'GET', '/chats'))
     })
 
-  sessions
+  chats
     .command('get')
-    .description('Get session by id')
-    .argument('<id>', 'Session id')
+    .description('Get chat by id')
+    .argument('<id>', 'Chat id')
     .action(async function (id: string) {
-      await runWithHandler(this as Command, (ctx) => resolveByIdFromCollection(ctx, '/sessions', id))
+      await runWithHandler(this as Command, (ctx) => resolveByIdFromCollection(ctx, '/chats', id))
     })
 
-  sessions
+  chats
     .command('create')
-    .description('Create session')
-    .option('--name <name>', 'Session name', 'New Session')
+    .description('Create chat')
+    .option('--name <name>', 'Chat name', 'New Chat')
     .option('--user <user>', 'User name')
     .option('--cwd <cwd>', 'Working directory')
     .option('--provider <provider>', 'Provider id')
@@ -706,7 +700,7 @@ export function buildProgram(): Command {
       if (opts.heartbeatIntervalSec && (!Number.isFinite(heartbeatIntervalSec) || heartbeatIntervalSec! < 0)) {
         throw new Error(`Invalid --heartbeat-interval-sec value: ${opts.heartbeatIntervalSec}`)
       }
-      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'POST', '/sessions', compactObject({
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'POST', '/chats', compactObject({
         name: opts.name,
         user: opts.user,
         cwd: opts.cwd,
@@ -720,14 +714,14 @@ export function buildProgram(): Command {
       })))
     })
 
-  sessions
+  chats
     .command('update')
-    .description('Update session')
-    .argument('<id>', 'Session id')
-    .option('--name <name>', 'Session name')
+    .description('Update chat')
+    .argument('<id>', 'Chat id')
+    .option('--name <name>', 'Chat name')
     .option('--cwd <cwd>', 'Working directory')
     .option('--agent-id <agentId>', 'Agent id')
-    .option('--tools <json>', 'Tools JSON array, e.g. ["shell","memory"]')
+    .option('--plugins <json>', 'Plugins JSON array, e.g. ["shell","memory"]')
     .option('--heartbeat-enabled <heartbeatEnabled>', 'Heartbeat enabled (true|false)')
     .option('--heartbeat-interval-sec <heartbeatIntervalSec>', 'Heartbeat interval seconds')
     .action(async function (
@@ -736,7 +730,7 @@ export function buildProgram(): Command {
         name?: string
         cwd?: string
         agentId?: string
-        tools?: string
+        plugins?: string
         heartbeatEnabled?: string
         heartbeatIntervalSec?: string
       },
@@ -748,40 +742,40 @@ export function buildProgram(): Command {
       if (opts.heartbeatIntervalSec && (!Number.isFinite(heartbeatIntervalSec) || heartbeatIntervalSec! < 0)) {
         throw new Error(`Invalid --heartbeat-interval-sec value: ${opts.heartbeatIntervalSec}`)
       }
-      const tools = parseJsonValue(opts.tools, '--tools')
-      if (tools !== undefined && !Array.isArray(tools)) {
-        throw new Error('--tools must be a JSON array')
+      const plugins = parseJsonValue(opts.plugins, '--plugins')
+      if (plugins !== undefined && !Array.isArray(plugins)) {
+        throw new Error('--plugins must be a JSON array')
       }
-      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'PUT', `/sessions/${encodeURIComponent(id)}`, compactObject({
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'PUT', `/chats/${encodeURIComponent(id)}`, compactObject({
         name: opts.name,
         cwd: opts.cwd,
         agentId: opts.agentId,
-        tools,
+        plugins,
         heartbeatEnabled: typeof opts.heartbeatEnabled === 'string' ? heartbeatEnabled : undefined,
         heartbeatIntervalSec,
       })))
     })
 
-  sessions
+  chats
     .command('delete')
-    .description('Delete session')
-    .argument('<id>', 'Session id')
+    .description('Delete chat')
+    .argument('<id>', 'Chat id')
     .action(async function (id: string) {
-      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'DELETE', `/sessions/${encodeURIComponent(id)}`))
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'DELETE', `/chats/${encodeURIComponent(id)}`))
     })
 
-  sessions
+  chats
     .command('history')
-    .description('Get session message history')
-    .argument('<id>', 'Session id')
+    .description('Get chat message history')
+    .argument('<id>', 'Chat id')
     .action(async function (id: string) {
-      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'GET', `/sessions/${encodeURIComponent(id)}/messages`))
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'GET', `/chats/${encodeURIComponent(id)}/messages`))
     })
 
-  sessions
+  chats
     .command('mailbox')
-    .description('List session mailbox envelopes')
-    .argument('<id>', 'Session id')
+    .description('List chat mailbox envelopes')
+    .argument('<id>', 'Chat id')
     .option('--limit <limit>', 'Max envelopes to return (default: 50)')
     .option('--include-acked', 'Include acknowledged envelopes')
     .action(async function (
@@ -799,16 +793,16 @@ export function buildProgram(): Command {
         const params = new URLSearchParams()
         if (typeof limit === 'number') params.set('limit', String(limit))
         if (opts.includeAcked) params.set('includeAcked', '1')
-        return apiRequest(ctx, 'GET', `/sessions/${encodeURIComponent(id)}/mailbox`, undefined, params)
+        return apiRequest(ctx, 'GET', `/chats/${encodeURIComponent(id)}/mailbox`, undefined, params)
       })
     })
 
-  sessions
+  chats
     .command('stop')
-    .description('Stop running work for a session')
-    .argument('<id>', 'Session id')
+    .description('Stop running work for a chat')
+    .argument('<id>', 'Chat id')
     .action(async function (id: string) {
-      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'POST', `/sessions/${encodeURIComponent(id)}/stop`))
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'POST', `/chats/${encodeURIComponent(id)}/stop`))
     })
 
   const memory = program.command('memory').description('Manage memory')

package/src/cli/spec.js

@@ -228,6 +228,8 @@ const COMMAND_GROUPS = {
       update: { description: 'Enable/disable plugin (body: {"filename":"x.js","enabled":true})', method: 'POST', path: '/plugins' },
       marketplace: { description: 'Get plugin marketplace registry', method: 'GET', path: '/plugins/marketplace' },
       install: { description: 'Install plugin by URL', method: 'POST', path: '/plugins/install' },
+      'settings-get': { description: 'Read plugin settings (supports --query pluginId=...)', method: 'GET', path: '/plugins/settings' },
+      'settings-set': { description: 'Write plugin settings (supports --query pluginId=... and --data JSON)', method: 'PUT', path: '/plugins/settings' },
     },
   },
   providers: {
@@ -249,7 +251,7 @@ const COMMAND_GROUPS = {
   search: {
     description: 'Global search across app resources',
     commands: {
-      query: { description: 'Search agents/tasks/sessions/schedules/webhooks/skills (supports --query q=term)', method: 'GET', path: '/search' },
+      query: { description: 'Search agents/tasks/chats/schedules/webhooks/skills (supports --query q=term)', method: 'GET', path: '/search' },
     },
   },
   schedules: {
@@ -273,33 +275,33 @@ const COMMAND_GROUPS = {
       delete: { description: 'Delete secret', method: 'DELETE', path: '/secrets/:id', params: ['id'] },
     },
   },
-  sessions: {
-    description: 'Interactive chat sessions',
+  chats: {
+    description: 'Agent chats',
     commands: {
-      list: { description: 'List sessions', method: 'GET', path: '/sessions' },
-      create: { description: 'Create session', method: 'POST', path: '/sessions' },
-      get: { description: 'Get session by id (from list)', virtualGet: true, collectionPath: '/sessions', params: ['id'] },
-      update: { description: 'Update session fields', method: 'PUT', path: '/sessions/:id', params: ['id'] },
-      delete: { description: 'Delete one session', method: 'DELETE', path: '/sessions/:id', params: ['id'] },
-      'delete-many': { description: 'Delete multiple sessions (body: {"ids":[...]})', method: 'DELETE', path: '/sessions' },
-      'heartbeat-disable-all': { description: 'Disable all session heartbeats and cancel queued heartbeat runs', method: 'POST', path: '/sessions/heartbeat' },
-      messages: { description: 'Get session message history', method: 'GET', path: '/sessions/:id/messages', params: ['id'] },
-      'messages-update': { description: 'Update session message metadata (e.g. bookmark)', method: 'PUT', path: '/sessions/:id/messages', params: ['id'] },
-      'messages-send': { description: 'Append a user/system message to a session', method: 'POST', path: '/sessions/:id/messages', params: ['id'] },
-      'messages-delete': { description: 'Delete a message from a session', method: 'DELETE', path: '/sessions/:id/messages', params: ['id'] },
-      fork: { description: 'Fork session from a specific message index', method: 'POST', path: '/sessions/:id/fork', params: ['id'] },
-      'edit-resend': { description: 'Edit and resend from a specific message index', method: 'POST', path: '/sessions/:id/edit-resend', params: ['id'] },
-      'main-loop': { description: 'Get main mission loop state for a session', method: 'GET', path: '/sessions/:id/main-loop', params: ['id'] },
-      'main-loop-action': { description: 'Control main mission loop (pause/resume/set_goal/set_mode/clear_events/nudge)', method: 'POST', path: '/sessions/:id/main-loop', params: ['id'] },
-      chat: { description: 'Send chat message (SSE stream)', method: 'POST', path: '/sessions/:id/chat', params: ['id'], stream: true, waitable: true },
-      stop: { description: 'Cancel active/running session work', method: 'POST', path: '/sessions/:id/stop', params: ['id'] },
-      clear: { description: 'Clear session history', method: 'POST', path: '/sessions/:id/clear', params: ['id'] },
-      mailbox: { description: 'List mailbox envelopes for a session', method: 'GET', path: '/sessions/:id/mailbox', params: ['id'] },
-      'mailbox-action': { description: 'Send/ack/clear mailbox envelopes', method: 'POST', path: '/sessions/:id/mailbox', params: ['id'] },
-      deploy: { description: 'Deploy session workspace git changes', method: 'POST', path: '/sessions/:id/deploy', params: ['id'] },
-      devserver: { description: 'Start/stop/status dev server (body: {"action":"start|stop|status"})', method: 'POST', path: '/sessions/:id/devserver', params: ['id'] },
-      browser: { description: 'Check browser runtime for session', method: 'GET', path: '/sessions/:id/browser', params: ['id'] },
-      'browser-clear': { description: 'Close browser runtime for session', method: 'DELETE', path: '/sessions/:id/browser', params: ['id'] },
+      list: { description: 'List chats', method: 'GET', path: '/chats' },
+      create: { description: 'Create chat', method: 'POST', path: '/chats' },
+      get: { description: 'Get chat by id (from list)', virtualGet: true, collectionPath: '/chats', params: ['id'] },
+      update: { description: 'Update chat fields', method: 'PUT', path: '/chats/:id', params: ['id'] },
+      delete: { description: 'Delete one chat', method: 'DELETE', path: '/chats/:id', params: ['id'] },
+      'delete-many': { description: 'Delete multiple chats (body: {"ids":[...]})', method: 'DELETE', path: '/chats' },
+      'heartbeat-disable-all': { description: 'Disable all chat heartbeats and cancel queued heartbeat runs', method: 'POST', path: '/chats/heartbeat' },
+      messages: { description: 'Get chat message history', method: 'GET', path: '/chats/:id/messages', params: ['id'] },
+      'messages-update': { description: 'Update chat message metadata (e.g. bookmark)', method: 'PUT', path: '/chats/:id/messages', params: ['id'] },
+      'messages-send': { description: 'Append a user/system message to a chat', method: 'POST', path: '/chats/:id/messages', params: ['id'] },
+      'messages-delete': { description: 'Delete a message from a chat', method: 'DELETE', path: '/chats/:id/messages', params: ['id'] },
+      fork: { description: 'Fork chat from a specific message index', method: 'POST', path: '/chats/:id/fork', params: ['id'] },
+      'edit-resend': { description: 'Edit and resend from a specific message index', method: 'POST', path: '/chats/:id/edit-resend', params: ['id'] },
+      'main-loop': { description: 'Get main mission loop state for a chat', method: 'GET', path: '/chats/:id/main-loop', params: ['id'] },
+      'main-loop-action': { description: 'Control main mission loop (pause/resume/set_goal/set_mode/clear_events/nudge)', method: 'POST', path: '/chats/:id/main-loop', params: ['id'] },
+      chat: { description: 'Send chat message (SSE stream)', method: 'POST', path: '/chats/:id/chat', params: ['id'], stream: true, waitable: true },
+      stop: { description: 'Cancel active/running chat work', method: 'POST', path: '/chats/:id/stop', params: ['id'] },
+      clear: { description: 'Clear chat history', method: 'POST', path: '/chats/:id/clear', params: ['id'] },
+      mailbox: { description: 'List mailbox envelopes for a chat', method: 'GET', path: '/chats/:id/mailbox', params: ['id'] },
+      'mailbox-action': { description: 'Send/ack/clear mailbox envelopes', method: 'POST', path: '/chats/:id/mailbox', params: ['id'] },
+      deploy: { description: 'Deploy chat workspace git changes', method: 'POST', path: '/chats/:id/deploy', params: ['id'] },
+      devserver: { description: 'Start/stop/status dev server (body: {"action":"start|stop|status"})', method: 'POST', path: '/chats/:id/devserver', params: ['id'] },
+      browser: { description: 'Check browser runtime for chat', method: 'GET', path: '/chats/:id/browser', params: ['id'] },
+      'browser-clear': { description: 'Close browser runtime for chat', method: 'DELETE', path: '/chats/:id/browser', params: ['id'] },
     },
   },
   settings: {