@swarmclawai/swarmclaw 1.2.6 → 1.2.9

package/src/types/agent.ts

@@ -0,0 +1,264 @@
+import type { ProviderId, ProviderType, OllamaMode } from './provider'
+import type { SessionResetMode, IdentityContinuityState } from './session'
+import type { SkillAllowlistMode } from './skill'
+
+// --- Agent / Delegation ---
+
+export type AgentRole = 'worker' | 'coordinator'
+export type DelegationTargetMode = 'all' | 'selected'
+
+export interface AgentOrgChart {
+  parentId?: string | null
+  teamLabel?: string | null
+  teamColor?: string | null
+  x?: number | null
+  y?: number | null
+}
+
+export interface Agent {
+  id: string
+  name: string
+  openclawAgentId?: string | null
+  description: string
+  soul?: string
+  identityState?: IdentityContinuityState | null
+  emoji?: string
+  creature?: string
+  vibe?: string
+  theme?: string
+  avatar?: string
+  systemPrompt: string
+  provider: ProviderId
+  model: string
+  ollamaMode?: OllamaMode | null
+  credentialId?: string | null
+  fallbackCredentialIds?: string[]
+  apiEndpoint?: string | null
+  gatewayProfileId?: string | null
+  preferredGatewayTags?: string[]
+  preferredGatewayUseCase?: string | null
+  routingStrategy?: AgentRoutingStrategy | null
+  routingTargets?: AgentRoutingTarget[]
+  role?: AgentRole                // default 'worker' — coordinators get enhanced delegation prompts
+  delegationEnabled?: boolean
+  delegationTargetMode?: DelegationTargetMode
+  delegationTargetAgentIds?: string[]
+  tools?: string[]
+  extensions?: string[]
+  skills?: string[]             // e.g. ['frontend-design'] — pinned Claude Code skills to mention explicitly
+  skillIds?: string[]           // IDs of pinned managed skills to keep always-on for this agent
+  mcpServerIds?: string[]       // IDs of configured MCP servers to inject tools from
+  mcpDisabledTools?: string[]   // MCP tool names disabled for this agent (denylist)
+  orgChart?: AgentOrgChart | null
+  capabilities?: string[]       // e.g. ['frontend', 'screenshots', 'research', 'devops']
+  threadSessionId?: string | null  // persistent shortcut chat session for agent-centric UI
+  heartbeatEnabled?: boolean
+  heartbeatIntervalSec?: number | null
+  heartbeatInterval?: string | number | null
+  heartbeatPrompt?: string | null
+  heartbeatModel?: string | null
+  heartbeatAckMaxChars?: number | null
+  heartbeatShowOk?: boolean | null
+  heartbeatShowAlerts?: boolean | null
+  heartbeatTarget?: 'last' | 'none' | string | null
+  heartbeatGoal?: string | null
+  heartbeatNextAction?: string | null
+  heartbeatLightContext?: boolean | null
+  sessionResetMode?: SessionResetMode | null
+  sessionIdleTimeoutSec?: number | null
+  sessionMaxAgeSec?: number | null
+  sessionDailyResetAt?: string | null
+  sessionResetTimezone?: string | null
+  thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high'
+  memoryScopeMode?: 'auto' | 'all' | 'global' | 'agent' | 'session' | 'project' | null
+  memoryTierPreference?: 'working' | 'durable' | 'archive' | 'blended' | null
+  elevenLabsVoiceId?: string | null
+  projectId?: string
+  avatarSeed?: string
+  avatarUrl?: string | null
+  pinned?: boolean
+  lastUsedAt?: number
+  totalCost?: number
+  disabled?: boolean
+  trashedAt?: number
+  openclawSkillMode?: SkillAllowlistMode
+  openclawAllowedSkills?: string[]
+  responseStyle?: 'concise' | 'normal' | 'detailed' | null
+  responseMaxChars?: number | null
+  monthlyBudget?: number | null
+  dailyBudget?: number | null
+  hourlyBudget?: number | null
+  autoRecovery?: boolean
+  proactiveMemory?: boolean
+  /** Auto-refresh a reviewed skill draft from meaningful chat turns for this agent. */
+  autoDraftSkillSuggestions?: boolean
+  /** Controls whether file operations are confined to the workspace or allowed anywhere on the host. Default: 'workspace'. */
+  filesystemScope?: 'workspace' | 'machine' | null
+  /** Per-agent filesystem restrictions. Globs matched against resolved paths. */
+  fileAccessPolicy?: {
+    /** If set, only these paths (globs) are writable. Others are blocked. */
+    allowedPaths?: string[]
+    /** These paths (globs) are always blocked even if allowedPaths matches. */
+    blockedPaths?: string[]
+  } | null
+
+  /** Docker-backed browser sandbox settings and legacy execution sandbox compatibility fields. */
+  sandboxConfig?: {
+    enabled: boolean
+    mode?: 'off' | 'non-main' | 'all' // default: 'all' when enabled, modeled after OpenClaw
+    scope?: 'session' | 'agent'       // default: 'session'
+    workspaceAccess?: 'ro' | 'rw'     // default: 'rw'
+    image?: string               // default: 'node:22-slim'
+    network?: 'none' | 'bridge'  // default: 'none'
+    memoryMb?: number            // default: 512
+    cpus?: number                // default: 1.0
+    readonlyRoot?: boolean       // default: false
+    workdir?: string             // default: '/workspace'
+    containerPrefix?: string     // default: 'swarmclaw-sb-'
+    pidsLimit?: number           // default: 256
+    setupCommand?: string
+    browser?: {
+      enabled?: boolean
+      image?: string
+      containerPrefix?: string
+      network?: 'none' | 'bridge'
+      cdpPort?: number
+      vncPort?: number
+      noVncPort?: number
+      headless?: boolean
+      enableNoVnc?: boolean
+      mountUploads?: boolean
+      autoStartTimeoutMs?: number
+    } | null
+    prune?: {
+      idleHours?: number
+      maxAgeDays?: number
+    } | null
+  } | null
+
+  /** Configuration for the `execute` tool (just-bash sandbox or explicit host bash). */
+  executeConfig?: {
+    backend?: 'sandbox' | 'host'
+    network?: { enabled: boolean; allowedUrls?: string[] }
+    runtimes?: { python?: boolean; javascript?: boolean; sqlite?: boolean }
+    timeout?: number
+    credentials?: string[]
+  } | null
+
+  budgetAction?: 'warn' | 'block'
+  /** Runtime-enriched: current month's spend. Populated by GET /api/agents when monthlyBudget is set. */
+  monthlySpend?: number
+  /** Runtime-enriched: current day's spend. Populated by GET /api/agents when dailyBudget is set. */
+  dailySpend?: number
+  /** Runtime-enriched: trailing 1-hour spend. Populated by GET /api/agents when hourlyBudget is set. */
+  hourlySpend?: number
+  maxFollowupChain?: number
+
+  // Orchestrator Mode
+  orchestratorEnabled?: boolean
+  orchestratorMission?: string
+  orchestratorWakeInterval?: string | number | null
+  orchestratorGovernance?: 'autonomous' | 'approval-required' | 'notify-only'
+  orchestratorMaxCyclesPerDay?: number | null
+  orchestratorLastWakeAt?: number | null
+  orchestratorCycleCount?: number
+
+  createdAt: number
+  updatedAt: number
+}
+
+export type AgentTool = 'browser'
+
+export interface ClaudeSkill {
+  id: string
+  name: string
+  description: string
+}
+
+// --- Agent Routing / Packs ---
+
+export type AgentRoutingStrategy = 'single' | 'balanced' | 'economy' | 'premium' | 'reasoning'
+export type AgentRoutingTargetRole = 'primary' | 'economy' | 'premium' | 'reasoning' | 'backup'
+
+export interface AgentRoutingTarget {
+  id: string
+  label?: string
+  role?: AgentRoutingTargetRole
+  provider: ProviderId
+  model: string
+  ollamaMode?: OllamaMode | null
+  credentialId?: string | null
+  fallbackCredentialIds?: string[]
+  apiEndpoint?: string | null
+  gatewayProfileId?: string | null
+  preferredGatewayTags?: string[]
+  preferredGatewayUseCase?: string | null
+  priority?: number
+}
+
+export interface AgentPackEntry {
+  id: string
+  name: string
+  description?: string
+  provider: ProviderId
+  model: string
+  ollamaMode?: OllamaMode | null
+  credentialId?: string | null
+  fallbackCredentialIds?: string[]
+  apiEndpoint?: string | null
+  gatewayProfileId?: string | null
+  routingStrategy?: AgentRoutingStrategy | null
+  routingTargets?: AgentRoutingTarget[]
+  tools?: string[]
+  extensions?: string[]
+  capabilities?: string[]
+  elevenLabsVoiceId?: string | null
+  soul?: string
+  systemPrompt?: string
+}
+
+export interface AgentPackManifest {
+  schemaVersion: 1
+  kind: 'swarmclaw-agent-pack'
+  name: string
+  description?: string
+  exportedAt: number
+  recommendedProviders?: ProviderType[]
+  agents: AgentPackEntry[]
+}
+
+// --- External Agents ---
+
+export type ExternalAgentSourceType = 'codex' | 'claude' | 'opencode' | 'openclaw' | 'custom'
+export type ExternalAgentStatus = 'online' | 'idle' | 'offline' | 'stale'
+
+export interface ExternalAgentRuntime {
+  id: string
+  name: string
+  sourceType: ExternalAgentSourceType
+  status: ExternalAgentStatus
+  provider?: ProviderId | null
+  model?: string | null
+  workspace?: string | null
+  transport?: 'http' | 'ws' | 'cli' | 'gateway' | 'custom' | null
+  endpoint?: string | null
+  agentId?: string | null
+  gatewayProfileId?: string | null
+  capabilities?: string[]
+  labels?: string[]
+  lifecycleState?: 'active' | 'draining' | 'cordoned'
+  gatewayTags?: string[]
+  gatewayUseCase?: string | null
+  version?: string | null
+  lastHealthNote?: string | null
+  metadata?: Record<string, unknown> | null
+  tokenStats?: {
+    inputTokens?: number
+    outputTokens?: number
+    totalTokens?: number
+  } | null
+  lastHeartbeatAt?: number | null
+  lastSeenAt?: number | null
+  createdAt: number
+  updatedAt: number
+}

package/src/types/app-settings.ts

@@ -0,0 +1,173 @@
+import type { SessionResetMode } from './session'
+
+// --- App Settings ---
+export type LoopMode = 'bounded' | 'ongoing'
+export type AutonomyEstopLevel = 'none' | 'autonomy' | 'all'
+
+export interface GoalContract {
+  objective: string
+  constraints?: string[]
+  budgetUsd?: number | null
+  deadlineAt?: number | null
+  successMetric?: string | null
+}
+
+export interface WhatsAppApprovedContact {
+  id: string
+  label: string
+  phone: string
+}
+
+export interface AppSettings {
+  userPrompt?: string
+  userName?: string
+  setupCompleted?: boolean
+  embeddingProvider?: 'local' | 'openai' | 'ollama' | null
+  embeddingModel?: string | null
+  embeddingCredentialId?: string | null
+  embeddingEndpoint?: string | null
+  loopMode?: LoopMode
+  agentLoopRecursionLimit?: number
+  delegationMaxDepth?: number
+  ongoingLoopMaxIterations?: number
+  ongoingLoopMaxRuntimeMinutes?: number
+  maxFollowupChain?: number
+  shellCommandTimeoutSec?: number
+  claudeCodeTimeoutSec?: number
+  cliProcessTimeoutSec?: number
+  streamIdleStallSec?: number
+  requiredToolKickoffSec?: number
+  userAvatarSeed?: string
+  elevenLabsEnabled?: boolean
+  elevenLabsApiKey?: string | null
+  elevenLabsApiKeyConfigured?: boolean
+  elevenLabsVoiceId?: string | null
+  speechRecognitionLang?: string | null
+  tavilyApiKey?: string | null
+  tavilyApiKeyConfigured?: boolean
+  braveApiKey?: string | null
+  braveApiKeyConfigured?: boolean
+  heartbeatPrompt?: string | null
+  heartbeatIntervalSec?: number | null
+  heartbeatInterval?: string | number | null
+  heartbeatModel?: string | null
+  heartbeatAckMaxChars?: number | null
+  heartbeatShowOk?: boolean | null
+  heartbeatShowAlerts?: boolean | null
+  heartbeatTarget?: 'last' | 'none' | string | null
+  heartbeatActiveStart?: string | null
+  heartbeatActiveEnd?: string | null
+  heartbeatTimezone?: string | null
+  heartbeatLightContext?: boolean | null
+  sessionResetMode?: SessionResetMode | null
+  sessionIdleTimeoutSec?: number | null
+  sessionMaxAgeSec?: number | null
+  sessionDailyResetAt?: string | null
+  sessionResetTimezone?: string | null
+  untrustedContentGuardMode?: 'off' | 'warn' | 'block'
+  // Task resiliency and supervision
+  defaultTaskMaxAttempts?: number
+  taskRetryBackoffSec?: number
+  taskStallTimeoutMin?: number
+  // Safety rails
+  safetyRequireApprovalForOutbound?: boolean
+  safetyMaxDailySpendUsd?: number | null
+  safetyBlockedTools?: string[]
+  capabilityPolicyMode?: 'permissive' | 'balanced' | 'strict'
+  capabilityBlockedTools?: string[]
+  capabilityBlockedCategories?: string[]
+  capabilityAllowedTools?: string[]
+  taskManagementEnabled?: boolean
+  projectManagementEnabled?: boolean
+  // Memory governance
+  memoryWorkingTtlHours?: number
+  memoryDefaultConfidence?: number
+  memoryPruneEnabled?: boolean
+  memorySummaryEnabled?: boolean
+  // Capability router preferences
+  autonomyPreferredDelegates?: Array<'claude' | 'codex' | 'opencode'>
+  autonomyPreferToolRouting?: boolean
+  // Continuous eval
+  autonomyEvalEnabled?: boolean
+  autonomyEvalCron?: string | null
+  supervisorEnabled?: boolean
+  supervisorRuntimeScope?: 'chat' | 'task' | 'both'
+  supervisorNoProgressLimit?: number
+  supervisorRepeatedToolLimit?: number
+  autonomyResumeApprovalsEnabled?: boolean
+  reflectionEnabled?: boolean
+  reflectionAutoWriteMemory?: boolean
+  memoryReferenceDepth?: number
+  maxMemoriesPerLookup?: number
+  maxLinkedMemoriesExpanded?: number
+  memoryMaxDepth?: number
+  memoryMaxPerLookup?: number
+  // Chat UX
+  suggestionsEnabled?: boolean
+  runtimeSkillRetrievalMode?: 'keyword' | 'embedding'
+  runtimeSkillTopK?: number
+  // Globally approved WhatsApp contacts for connector DMs
+  whatsappApprovedContacts?: WhatsAppApprovedContact[]
+  // Voice conversation
+  voiceAutoSendDelaySec?: number
+  // Default agent for main chat on startup
+  defaultAgentId?: string | null
+  // Theme
+  themeHue?: string
+  // Web search provider
+  webSearchProvider?: 'duckduckgo' | 'google' | 'bing' | 'searxng' | 'tavily' | 'brave'
+  searxngUrl?: string
+  // Task custom field definitions
+  taskCustomFieldDefs?: Array<{ key: string; label: string; type: 'text' | 'number' | 'select'; options?: string[] }>
+  // OpenClaw sync settings
+  openclawWorkspacePath?: string | null
+  openclawAutoSyncMemory?: boolean
+  openclawAutoSyncSchedules?: boolean
+  // Outbound ops alert webhook
+  alertWebhookUrl?: string | null
+  alertWebhookType?: 'discord' | 'slack' | 'custom' | null
+  alertWebhookEvents?: ('error' | 'warning')[]
+  // Deterministic LLM response cache
+  responseCacheEnabled?: boolean
+  responseCacheTtlSec?: number
+  responseCacheMaxEntries?: number
+  // Task quality gate defaults
+  taskQualityGateEnabled?: boolean
+  taskQualityGateMinResultChars?: number
+  taskQualityGateMinEvidenceItems?: number
+  taskQualityGateRequireVerification?: boolean
+  taskQualityGateRequireArtifact?: boolean
+  taskQualityGateRequireReport?: boolean
+  // Integrity monitor
+  integrityMonitorEnabled?: boolean
+  // Background daemon
+  daemonAutostartEnabled?: boolean
+  // Tool loop detection thresholds
+  toolLoopFrequencyWarn?: number
+  toolLoopFrequencyCritical?: number
+  toolLoopCircuitBreaker?: number
+  // Per-extension settings (keyed by extensionId)
+  extensionSettings?: Record<string, Record<string, unknown>>
+}
+
+export interface EstopState {
+  level: AutonomyEstopLevel
+  reason?: string | null
+  engagedAt?: number | null
+  engagedBy?: string | null
+  resumeApprovalId?: string | null
+  updatedAt: number
+}
+
+export interface GuardianCheckpoint {
+  id: string
+  cwd: string
+  head: string
+  branch?: string | null
+  status: string
+  createdAt: number
+  createdBy: string
+  approvalId?: string | null
+  restorePreparedAt?: number | null
+  restoredAt?: number | null
+}

package/src/types/approval.ts

@@ -0,0 +1,25 @@
+// --- Approvals ---
+
+export type ApprovalCategory =
+  | 'tool_access'
+  | 'extension_scaffold'
+  | 'extension_install'
+  | 'task_tool'
+  | 'human_loop'
+  | 'connector_sender'
+
+export interface ApprovalRequest {
+  id: string
+  category: ApprovalCategory
+  agentId?: string | null
+  sessionId?: string | null
+  taskId?: string | null
+  title: string
+  description?: string
+  data: Record<string, unknown>
+  createdAt: number
+  updatedAt: number
+  status: 'pending' | 'approved' | 'rejected'
+}
+
+export type Approvals = Record<string, ApprovalRequest>

package/src/types/connector.ts

@@ -0,0 +1,188 @@
+import type { WhatsAppApprovedContact } from './app-settings'
+
+// --- Connector Health Events ---
+
+export type ConnectorHealthEventType = 'started' | 'stopped' | 'error' | 'reconnected' | 'disconnected'
+
+export interface ConnectorHealthEvent {
+  id: string
+  connectorId: string
+  event: ConnectorHealthEventType
+  message?: string
+  timestamp: string
+}
+
+// --- Connectors (Chat Platform Bridges) ---
+
+export type ConnectorPlatform =
+  | 'discord'
+  | 'telegram'
+  | 'slack'
+  | 'whatsapp'
+  | 'openclaw'
+  | 'bluebubbles'
+  | 'signal'
+  | 'teams'
+  | 'googlechat'
+  | 'matrix'
+  | 'email'
+  | 'webchat'
+  | 'mockmail'
+  | 'swarmdock'
+export type ConnectorStatus = 'stopped' | 'running' | 'error'
+
+export interface MessageSource {
+  platform: ConnectorPlatform
+  connectorId: string
+  connectorName: string
+  channelId?: string
+  senderId?: string
+  senderName?: string
+  messageId?: string
+  replyToMessageId?: string
+  threadId?: string
+  deliveryMode?: 'text' | 'voice_note'
+  deliveryTranscript?: string | null
+}
+
+export interface Connector {
+  id: string
+  name: string
+  platform: ConnectorPlatform
+  agentId?: string | null        // which agent handles incoming messages (optional if using chatroomId)
+  chatroomId?: string | null     // route to a chatroom instead of a single agent
+  credentialId?: string | null    // bot token stored as encrypted credential
+  config: Record<string, string>  // platform-specific settings
+  isEnabled: boolean
+  status: ConnectorStatus
+  lastError?: string | null
+  /** WhatsApp QR code data URL (runtime only) */
+  qrDataUrl?: string | null
+  /** WhatsApp authenticated/paired state (runtime only) */
+  authenticated?: boolean
+  /** WhatsApp has stored credentials from previous pairing (runtime only) */
+  hasCredentials?: boolean
+  /** Connector presence info (runtime only) */
+  presence?: { lastMessageAt?: number | null; channelId?: string | null }
+  createdAt: number
+  updatedAt: number
+}
+
+export type ConnectorDmAddressingMode = 'open' | 'addressed'
+
+export interface ConnectorAccessSenderStatus {
+  senderIds: string[]
+  isOwnerOverride: boolean
+  isBlocked: boolean
+  isApproved: boolean
+  isConfigAllowed: boolean
+  isStoredAllowed: boolean
+  isGlobalAllowed: boolean
+  isPending: boolean
+  pendingCode?: string | null
+  dmAddressingOverride: ConnectorDmAddressingMode | null
+  effectiveDmAddressingMode: ConnectorDmAddressingMode
+  requiresDirectAddress: boolean
+}
+
+export interface ConnectorAccessSnapshot {
+  connectorId: string
+  platform: ConnectorPlatform
+  dmPolicy: 'open' | 'allowlist' | 'pairing' | 'disabled'
+  dmAddressingMode: ConnectorDmAddressingMode
+  allowFrom: string[]
+  denyFrom: string[]
+  ownerSenderId: string | null
+  storedAllowedSenderIds: string[]
+  senderAddressingOverrides: Array<{
+    senderId: string
+    dmAddressingMode: ConnectorDmAddressingMode
+  }>
+  pendingPairingRequests: Array<{
+    code: string
+    senderId: string
+    senderName?: string
+    channelId?: string
+    createdAt: number
+    updatedAt: number
+  }>
+  globalWhatsAppApprovedContacts: WhatsAppApprovedContact[]
+  senderStatus?: ConnectorAccessSenderStatus | null
+}
+
+export type ConnectorAccessMutationAction =
+  | 'set_policy'
+  | 'set_dm_addressing_mode'
+  | 'allow_sender'
+  | 'remove_allowed_sender'
+  | 'block_sender'
+  | 'unblock_sender'
+  | 'approve_pairing'
+  | 'reject_pairing'
+  | 'set_owner'
+  | 'clear_owner'
+  | 'set_sender_dm_addressing'
+  | 'clear_sender_dm_addressing'
+
+export interface ConnectorAccessMutationResponse {
+  ok: boolean
+  snapshot: ConnectorAccessSnapshot
+}
+
+export type InboundMediaType = 'image' | 'video' | 'audio' | 'document' | 'file'
+
+export interface InboundThreadHistoryEntry {
+  role: 'user' | 'assistant'
+  senderName: string
+  text: string
+  messageId?: string
+}
+
+export interface InboundMedia {
+  type: InboundMediaType
+  fileName?: string
+  mimeType?: string
+  sizeBytes?: number
+  url?: string
+  localPath?: string
+}
+
+export interface InboundMessage {
+  platform: string
+  channelId: string
+  channelIdAlt?: string
+  channelName?: string
+  senderId: string
+  senderIdAlt?: string
+  senderName: string
+  senderAvatarUrl?: string
+  text: string
+  isGroup?: boolean
+  messageId?: string
+  imageUrl?: string
+  media?: InboundMedia[]
+  replyToMessageId?: string
+  threadId?: string
+  threadTitle?: string
+  threadStarterText?: string
+  threadStarterSenderName?: string
+  threadPersonaLabel?: string
+  threadParentChannelId?: string
+  threadParentChannelName?: string
+  threadHistory?: InboundThreadHistoryEntry[]
+  mentionsBot?: boolean
+  agentIdOverride?: string
+  isOwnerConversation?: boolean
+}
+
+export interface OutboundSendOptions {
+  imageUrl?: string
+  fileUrl?: string
+  mediaPath?: string
+  mimeType?: string
+  fileName?: string
+  caption?: string
+  ptt?: boolean
+  replyToMessageId?: string
+  threadId?: string
+}