@swarmclawai/swarmclaw 1.9.2 → 1.9.4

package/src/lib/server/tasks/task-execution-workspace.test.ts

@@ -66,10 +66,24 @@ describe('task execution workspaces', () => {
     assert.match(patch.executionWorkspace.path, /task-alpha-launch-qa-preview/)
     assert.equal(fs.existsSync(patch.executionWorkspace.path), true)
     assert.equal(fs.existsSync(patch.executionWorkspace.readmePath || ''), true)
+    assert.equal(fs.existsSync(patch.executionWorkspace.contextPath || ''), true)
+    assert.equal(fs.existsSync(patch.executionWorkspace.envPath || ''), true)
     assert.equal(patch.executionWorkspace.sourceCwd, '/repo/source')
+    assert.equal(patch.executionWorkspace.context?.taskId, 'task-alpha')
+    assert.equal(patch.executionWorkspace.context?.workspacePath, patch.executionWorkspace.path)
+    assert.equal(patch.executionWorkspace.envHints?.some((hint) => hint.key === 'WORKSPACE_CWD'), true)
+    assert.equal(patch.executionWorkspace.envHints?.some((hint) => hint.key === 'KANBAN_TASK_ID'), true)
     assert.equal(patch.executionWorkspace.previewLinks[0]?.label, 'Local preview')
     assert.equal(patch.previewLinks[0]?.url, 'http://127.0.0.1:3456')
     assert.equal(patch.runtimeServices[0]?.status, 'planned')
+
+    const context = JSON.parse(fs.readFileSync(patch.executionWorkspace.contextPath || '', 'utf8'))
+    assert.equal(context.taskId, 'task-alpha')
+    assert.equal(context.previewLinks[0]?.url, 'http://127.0.0.1:3456')
+    const envFile = fs.readFileSync(patch.executionWorkspace.envPath || '', 'utf8')
+    assert.equal(envFile.includes('SWARMCLAW_TASK_ID="task-alpha"'), true)
+    assert.equal(envFile.includes('WORKSPACE_SOURCE="/repo/source"'), true)
+    assert.equal(envFile.includes('KANBAN_WORKSPACE='), true)
   })
 
   it('deduplicates preview URLs and computes blocked, stale, and retrying liveness', () => {

package/src/lib/server/tasks/task-execution-workspace.ts

@@ -7,6 +7,8 @@ import type {
   TaskExecutionWorkspace,
   TaskLivenessSnapshot,
   TaskPreviewLink,
+  TaskRuntimeContextPacket,
+  TaskRuntimeEnvHint,
   TaskRuntimeService,
 } from '@/types'
 
@@ -182,11 +184,106 @@ function writeWorkspaceReadme(task: BoardTask, workspacePath: string, now: numbe
   ]
   if (task.projectId) lines.push(`Project ID: ${task.projectId}`)
   if (task.cwd) lines.push(`Source cwd: ${task.cwd}`)
-  lines.push('', 'Use this directory for task-local notes, generated artifacts, and preview handoff files.')
+  lines.push(
+    '',
+    'Runtime context: ./context.json',
+    'Environment hints: ./.env.swarmclaw',
+    '',
+    'Use this directory for task-local notes, generated artifacts, and preview handoff files.',
+  )
   fs.writeFileSync(readmePath, `${lines.join('\n')}\n`, 'utf8')
   return readmePath
 }
 
+function addEnvHint(out: TaskRuntimeEnvHint[], key: string, value: unknown, description?: string) {
+  if (typeof value !== 'string' || !value) return
+  out.push({ key, value, ...(description ? { description } : {}) })
+}
+
+function buildRuntimeEnvHints(params: {
+  task: BoardTask
+  workspacePath: string
+  sourceCwd?: string | null
+  mode: TaskExecutionWorkspace['mode']
+  contextPath: string
+  envPath: string
+}): TaskRuntimeEnvHint[] {
+  const { task, workspacePath, sourceCwd, mode, contextPath, envPath } = params
+  const hints: TaskRuntimeEnvHint[] = []
+  const workspaceId = taskWorkspaceSlug(task)
+  addEnvHint(hints, 'SWARMCLAW_TASK_ID', task.id, 'SwarmClaw task id')
+  addEnvHint(hints, 'SWARMCLAW_TASK_TITLE', task.title || 'Task', 'SwarmClaw task title')
+  addEnvHint(hints, 'SWARMCLAW_TASK_STATUS', task.status, 'SwarmClaw task status')
+  addEnvHint(hints, 'SWARMCLAW_TASK_AGENT_ID', task.agentId, 'Assigned SwarmClaw agent id')
+  addEnvHint(hints, 'SWARMCLAW_WORKSPACE_ID', workspaceId, 'Stable task workspace id')
+  addEnvHint(hints, 'SWARMCLAW_WORKSPACE_CWD', workspacePath, 'Task workspace directory')
+  addEnvHint(hints, 'SWARMCLAW_WORKSPACE_MODE', mode, 'Task workspace mode')
+  addEnvHint(hints, 'SWARMCLAW_WORKSPACE_CONTEXT', contextPath, 'Runtime context packet path')
+  addEnvHint(hints, 'SWARMCLAW_WORKSPACE_ENV', envPath, 'Reusable runtime env file')
+  addEnvHint(hints, 'SWARMCLAW_PROJECT_ID', task.projectId || '', 'SwarmClaw project id')
+  addEnvHint(hints, 'SWARMCLAW_SOURCE_CWD', sourceCwd || '', 'Original source directory')
+  addEnvHint(hints, 'AGENT_HOME', workspacePath, 'Agent-local home directory')
+  addEnvHint(hints, 'TASK_ID', task.id, 'Portable task id')
+  addEnvHint(hints, 'TASK_TITLE', task.title || 'Task', 'Portable task title')
+  addEnvHint(hints, 'WORKSPACE_ID', workspaceId, 'Portable workspace id')
+  addEnvHint(hints, 'WORKSPACE_CWD', workspacePath, 'Portable workspace cwd')
+  addEnvHint(hints, 'WORKSPACE_SOURCE', sourceCwd || workspacePath, 'Portable source path')
+  addEnvHint(
+    hints,
+    'WORKSPACE_STRATEGY',
+    mode === 'project' ? 'project-task-workspace' : 'task-workspace',
+    'Portable workspace strategy',
+  )
+  addEnvHint(hints, 'KANBAN_TASK_ID', task.id, 'Portable board task id')
+  addEnvHint(hints, 'KANBAN_WORKSPACE', workspacePath, 'Portable board workspace path')
+  return hints
+}
+
+function envLine(hint: TaskRuntimeEnvHint): string {
+  return `${hint.key}=${JSON.stringify(hint.value)}`
+}
+
+function writeWorkspaceEnv(envPath: string, hints: TaskRuntimeEnvHint[]) {
+  const lines = [
+    '# Generated by SwarmClaw. Contains task context only, not secrets.',
+    ...hints.map(envLine),
+  ]
+  fs.writeFileSync(envPath, `${lines.join('\n')}\n`, 'utf8')
+}
+
+function buildTaskRuntimeContext(params: {
+  task: BoardTask
+  executionWorkspace: Omit<TaskExecutionWorkspace, 'context'>
+  previewLinks: TaskPreviewLink[]
+  runtimeServices: TaskRuntimeService[]
+  generatedAt: number
+}): TaskRuntimeContextPacket {
+  const { task, executionWorkspace, previewLinks, runtimeServices, generatedAt } = params
+  return {
+    taskId: task.id,
+    title: task.title || 'Task',
+    description: task.description || undefined,
+    status: task.status,
+    agentId: task.agentId,
+    projectId: executionWorkspace.projectId || null,
+    workspacePath: executionWorkspace.path,
+    sourceCwd: executionWorkspace.sourceCwd || null,
+    mode: executionWorkspace.mode,
+    preparedAt: executionWorkspace.preparedAt,
+    generatedAt,
+    previewLinks,
+    runtimeServices,
+    blockedBy: task.blockedBy,
+    blocks: task.blocks,
+    tags: task.tags,
+    upstreamResults: task.upstreamResults,
+  }
+}
+
+function writeWorkspaceContext(contextPath: string, context: TaskRuntimeContextPacket) {
+  fs.writeFileSync(contextPath, `${JSON.stringify(context, null, 2)}\n`, 'utf8')
+}
+
 export function computeTaskLiveness(
   task: BoardTask,
   tasks: Record<string, BoardTask> = {},
@@ -284,6 +381,8 @@ export function prepareTaskExecutionWorkspace(
   const existing = task.executionWorkspace || null
   const workspacePath = existing?.path || path.join(taskWorkspaceRoot(task, workspaceRoot), taskWorkspaceSlug(task))
   fs.mkdirSync(workspacePath, { recursive: true })
+  const contextPath = path.join(workspacePath, 'context.json')
+  const envPath = path.join(workspacePath, '.env.swarmclaw')
   const readmePath = writeWorkspaceReadme(task, workspacePath, now)
   const previewLinks = normalizeTaskPreviewLinks(
     task.previewLinks || existing?.previewLinks,
@@ -295,17 +394,45 @@ export function prepareTaskExecutionWorkspace(
     options.runtimeServices,
     now,
   )
-  const executionWorkspace: TaskExecutionWorkspace = {
+  const mode: TaskExecutionWorkspace['mode'] = task.projectId ? 'project' : 'task'
+  const sourceCwd = task.cwd || existing?.sourceCwd || null
+  const projectId = task.projectId || existing?.projectId || null
+  const preparedAt = existing?.preparedAt || now
+  const envHints = buildRuntimeEnvHints({
+    task,
+    workspacePath,
+    sourceCwd,
+    mode,
+    contextPath,
+    envPath,
+  })
+  const executionWorkspaceBase: Omit<TaskExecutionWorkspace, 'context'> = {
     path: workspacePath,
-    mode: task.projectId ? 'project' : 'task',
-    sourceCwd: task.cwd || existing?.sourceCwd || null,
-    projectId: task.projectId || existing?.projectId || null,
-    preparedAt: existing?.preparedAt || now,
+    mode,
+    sourceCwd,
+    projectId,
+    preparedAt,
     preparedBy: options.actor || existing?.preparedBy || null,
     readmePath,
+    contextPath,
+    envPath,
+    envHints,
     previewLinks,
     runtimeServices,
   }
+  const context = buildTaskRuntimeContext({
+    task,
+    executionWorkspace: executionWorkspaceBase,
+    previewLinks,
+    runtimeServices,
+    generatedAt: now,
+  })
+  writeWorkspaceContext(contextPath, context)
+  writeWorkspaceEnv(envPath, envHints)
+  const executionWorkspace: TaskExecutionWorkspace = {
+    ...executionWorkspaceBase,
+    context,
+  }
   const taskForLiveness = {
     ...task,
     executionWorkspace,

package/src/types/agent.ts

@@ -2,6 +2,7 @@ import type { ProviderId, ProviderType, OllamaMode } from './provider'
 import type { SessionResetMode, IdentityContinuityState } from './session'
 import type { SkillAllowlistMode } from './skill'
 import type { DreamConfig } from './dream'
+import type { ExtensionManagedResourceMarker } from './extension'
 
 // --- SwarmFeed Heartbeat ---
 
@@ -237,6 +238,7 @@ export interface Agent {
   swarmfeedLastAutoPostAt?: number | null
   origin?: 'swarmdock' | 'swarmfeed' | 'swarmclaw' | 'external'
   swarmfeedHeartbeat?: SwarmFeedHeartbeatConfig | null
+  managedByExtension?: ExtensionManagedResourceMarker | null
 
   // SwarmDock (marketplace integration)
   swarmdockEnabled?: boolean

package/src/types/app-settings.ts

@@ -1,4 +1,5 @@
 import type { SessionResetMode } from './session'
+import type { ExtensionManagedLocalFolderDeclaration } from './extension'
 
 // --- App Settings ---
 export type LoopMode = 'bounded' | 'ongoing'
@@ -150,6 +151,13 @@ export interface AppSettings {
   toolLoopCircuitBreaker?: number
   // Per-extension settings (keyed by extensionId)
   extensionSettings?: Record<string, Record<string, unknown>>
+  // Extension-managed resource settings such as trusted local folder roots.
+  extensionManagedResources?: Record<string, {
+    localFolders?: Record<string, ExtensionManagedLocalFolderDeclaration & {
+      path?: string | null
+      updatedAt?: number
+    }>
+  }>
   // Approval policies — opt-in governance gates for sensitive operations
   approvalPolicies?: {
     requireApprovalForAgentCreate?: boolean

package/src/types/extension.ts

@@ -251,6 +251,125 @@ export interface ExtensionUIDefinition {
   }>
 }
 
+export type ExtensionManagedResourceKind = 'agent' | 'schedule' | 'local_folder'
+
+export interface ExtensionManagedResourceRef {
+  extensionId?: string
+  resourceKind: 'agent' | 'schedule'
+  resourceKey: string
+}
+
+export interface ExtensionManagedResourceMarker {
+  extensionId: string
+  extensionName?: string | null
+  resourceKind: ExtensionManagedResourceKind
+  resourceKey: string
+  declarationHash?: string | null
+  reconciledAt: number
+}
+
+export interface ExtensionManagedAgentDeclaration {
+  agentKey: string
+  displayName: string
+  description?: string | null
+  systemPrompt?: string | null
+  instructions?: {
+    content?: string | null
+    entryFile?: string | null
+    assetPath?: string | null
+  } | null
+  provider?: ProviderId | string | null
+  model?: string | null
+  apiEndpoint?: string | null
+  credentialId?: string | null
+  fallbackCredentialIds?: string[]
+  gatewayProfileId?: string | null
+  preferredGatewayTags?: string[]
+  preferredGatewayUseCase?: string | null
+  capabilities?: string[] | string | null
+  tools?: string[]
+  extensions?: string[]
+  skills?: string[]
+  skillIds?: string[]
+  mcpServerIds?: string[]
+  monthlyBudget?: number | null
+  dailyBudget?: number | null
+  hourlyBudget?: number | null
+  disabled?: boolean
+  heartbeatEnabled?: boolean
+  planningMode?: 'off' | 'strict' | null
+}
+
+export interface ExtensionManagedScheduleTrigger {
+  kind?: 'schedule' | 'api' | 'webhook'
+  label?: string | null
+  enabled?: boolean
+  cronExpression?: string | null
+  timezone?: string | null
+}
+
+export interface ExtensionManagedScheduleDeclaration {
+  scheduleKey?: string
+  routineKey?: string
+  displayName?: string
+  title?: string
+  description?: string | null
+  taskPrompt?: string | null
+  message?: string | null
+  taskMode?: 'task' | 'wake_only' | 'protocol'
+  agentId?: string | null
+  agentRef?: ExtensionManagedResourceRef | null
+  assigneeRef?: ExtensionManagedResourceRef | null
+  scheduleType?: 'cron' | 'interval' | 'once'
+  cron?: string | null
+  intervalMs?: number | null
+  runAt?: number | null
+  timezone?: string | null
+  status?: 'active' | 'paused' | 'completed' | 'failed' | 'archived'
+  priority?: string | null
+  triggers?: ExtensionManagedScheduleTrigger[]
+}
+
+export interface ExtensionManagedLocalFolderDeclaration {
+  folderKey: string
+  displayName: string
+  description?: string | null
+  access?: 'read' | 'readWrite'
+  requiredDirectories?: string[]
+  requiredFiles?: string[]
+}
+
+export interface ExtensionGatewayPlatformDeclaration {
+  platformKey: string
+  displayName: string
+  description?: string | null
+  transport?: 'http' | 'ws' | 'stdio' | 'cli' | 'gateway' | 'custom'
+  endpoint?: string | null
+  authMode?: 'none' | 'bearer' | 'api_key' | 'oauth' | 'custom'
+  setupCheckKey?: string | null
+  capabilities?: string[]
+}
+
+export interface ExtensionSetupCheckDeclaration {
+  checkKey: string
+  displayName: string
+  description?: string | null
+  kind: 'env' | 'command' | 'url' | 'manual'
+  target?: string | null
+  required?: boolean
+}
+
+export interface ExtensionManagedResources {
+  agents?: ExtensionManagedAgentDeclaration[]
+  schedules?: ExtensionManagedScheduleDeclaration[]
+  /** Paperclip-compatible alias. SwarmClaw reconciles routines as managed schedules. */
+  routines?: ExtensionManagedScheduleDeclaration[]
+  localFolders?: ExtensionManagedLocalFolderDeclaration[]
+  /** Hermes-style gateway/platform declaration metadata for setup and diagnostics surfaces. */
+  gatewayPlatforms?: ExtensionGatewayPlatformDeclaration[]
+  setupChecks?: ExtensionSetupCheckDeclaration[]
+}
+
 export interface ExtensionProviderDefinition {
   id: string
   name: string
@@ -300,6 +419,14 @@ export interface Extension {
   ui?: ExtensionUIDefinition
   providers?: ExtensionProviderDefinition[]
   connectors?: ExtensionConnectorDefinition[]
+  managedResources?: ExtensionManagedResources
+  /** Paperclip-compatible top-level aliases. Prefer managedResources for new SwarmClaw extensions. */
+  agents?: ExtensionManagedAgentDeclaration[]
+  schedules?: ExtensionManagedScheduleDeclaration[]
+  routines?: ExtensionManagedScheduleDeclaration[]
+  localFolders?: ExtensionManagedLocalFolderDeclaration[]
+  gatewayPlatforms?: ExtensionGatewayPlatformDeclaration[]
+  setupChecks?: ExtensionSetupCheckDeclaration[]
 }
 
 export interface ExtensionMeta {
@@ -325,6 +452,11 @@ export interface ExtensionMeta {
   hasUI?: boolean
   providerCount?: number
   connectorCount?: number
+  managedAgentCount?: number
+  managedScheduleCount?: number
+  localFolderCount?: number
+  gatewayPlatformCount?: number
+  setupCheckCount?: number
   createdByAgentId?: string | null
   settingsFields?: ExtensionSettingsField[]
   hasDependencyManifest?: boolean

package/src/types/misc.ts

@@ -672,6 +672,8 @@ export interface OpenClawGatewayStats {
   externalRuntimeCount?: number
   sessionCount?: number
   presenceCount?: number
+  environmentCount?: number
+  availableEnvironmentCount?: number
   lastTopologyCheckedAt?: number
   lastTopologyErrorCount?: number
   lastTopologyError?: string | null
@@ -803,7 +805,19 @@ export interface OpenClawGatewayPresenceEntry {
   updatedAt?: number | null
 }
 
+export type OpenClawEnvironmentStatus = 'available' | 'unavailable' | 'starting' | 'stopping' | 'error'
+
+export interface OpenClawEnvironmentSummary {
+  id: string
+  type: string
+  label?: string | null
+  status: OpenClawEnvironmentStatus
+  capabilities?: string[]
+}
+
 export interface OpenClawGatewayTopologyStats extends OpenClawGatewayStats {
+  environmentCount: number
+  availableEnvironmentCount: number
   pendingPairingCount: number
   hasErrors: boolean
 }
@@ -819,6 +833,23 @@ export interface OpenClawGatewayTopology {
   pairedDevices: OpenClawPairedDevice[]
   sessions: OpenClawGatewaySession[]
   presence: OpenClawGatewayPresenceEntry[]
+  environments: OpenClawEnvironmentSummary[]
+  errors: OpenClawGatewayRpcError[]
+}
+
+export interface OpenClawGatewayEnvironmentList {
+  profile: GatewayProfile
+  connected: boolean
+  refreshedAt: number
+  environments: OpenClawEnvironmentSummary[]
+  errors: OpenClawGatewayRpcError[]
+}
+
+export interface OpenClawGatewayEnvironmentStatusSnapshot {
+  profile: GatewayProfile
+  connected: boolean
+  refreshedAt: number
+  environment: OpenClawEnvironmentSummary | null
   errors: OpenClawGatewayRpcError[]
 }
 

package/src/types/schedule.ts

@@ -1,3 +1,5 @@
+import type { ExtensionManagedResourceMarker } from './extension'
+
 export type ScheduleType = 'cron' | 'interval' | 'once'
 export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'failed' | 'archived'
 export type ScheduleTaskMode = 'task' | 'wake_only' | 'protocol'
@@ -54,6 +56,7 @@ export interface Schedule {
   followupThreadId?: string | null
   followupSenderId?: string | null
   followupSenderName?: string | null
+  managedByExtension?: ExtensionManagedResourceMarker | null
   createdAt: number
   updatedAt?: number
 }

package/src/types/task.ts

@@ -43,6 +43,32 @@ export interface TaskRuntimeService {
   updatedAt: number
 }
 
+export interface TaskRuntimeEnvHint {
+  key: string
+  value: string
+  description?: string
+}
+
+export interface TaskRuntimeContextPacket {
+  taskId: string
+  title: string
+  description?: string
+  status: BoardTaskStatus
+  agentId: string
+  projectId?: string | null
+  workspacePath: string
+  sourceCwd?: string | null
+  mode: TaskExecutionWorkspaceMode
+  preparedAt: number
+  generatedAt: number
+  previewLinks: TaskPreviewLink[]
+  runtimeServices: TaskRuntimeService[]
+  blockedBy?: string[]
+  blocks?: string[]
+  tags?: string[]
+  upstreamResults?: BoardTask['upstreamResults']
+}
+
 export interface TaskExecutionWorkspace {
   path: string
   mode: TaskExecutionWorkspaceMode
@@ -51,6 +77,10 @@ export interface TaskExecutionWorkspace {
   preparedAt: number
   preparedBy?: string | null
   readmePath?: string | null
+  contextPath?: string | null
+  envPath?: string | null
+  envHints?: TaskRuntimeEnvHint[]
+  context?: TaskRuntimeContextPacket
   previewLinks: TaskPreviewLink[]
   runtimeServices: TaskRuntimeService[]
 }