@swarmclawai/swarmclaw 1.9.32 → 1.9.34

package/src/lib/server/storage-auth.ts

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import crypto from 'crypto'
+import Database from 'better-sqlite3'
 
 import { DATA_DIR, IS_BUILD_BOOTSTRAP } from './data-dir'
 import { log } from '@/lib/server/logger'
@@ -11,25 +12,217 @@ const TAG = 'storage-auth'
 // because DATA_DIR is volume-mounted, unlike process.cwd()/.env.local.
 const GENERATED_ENV_PATH = path.join(DATA_DIR, '.env.generated')
 
+// Dedicated single-purpose file for the credential-encryption secret. Lives in
+// DATA_DIR so it survives both Docker volume mounts AND npm-global upgrades
+// (the latter changes process.cwd() per version, which made .env.local-only
+// persistence regenerate the secret every upgrade and orphan every credential
+// encrypted under the old value).
+const CREDENTIAL_SECRET_FILE = path.join(DATA_DIR, 'credential-secret')
+
 // --- .env loading ---
-function loadEnvFile(filePath: string): void {
-  if (!fs.existsSync(filePath)) return
+type LoadedEnvFile = Record<string, string>
+type CredentialSecretCandidate = {
+  secret: string
+  source: string
+  mtimeMs: number
+}
+
+function loadEnvFile(filePath: string): LoadedEnvFile {
+  const loaded: LoadedEnvFile = {}
+  if (!fs.existsSync(filePath)) return loaded
   fs.readFileSync(filePath, 'utf8').split(/\r?\n/).forEach(line => {
     const [k, ...v] = line.split('=')
-    if (k && v.length) process.env[k.trim()] = v.join('=').trim()
+    if (k && v.length) loaded[k.trim()] = v.join('=').trim()
   })
+  return loaded
 }
 
-function loadEnv() {
-  // Load fallback first so that .env.local values take precedence.
-  // .env.generated is auto-created in Docker where .env.local isn't writable.
-  loadEnvFile(GENERATED_ENV_PATH)
-  loadEnvFile(path.join(process.cwd(), '.env.local'))
+function cleanSecret(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
 }
-if (!IS_BUILD_BOOTSTRAP) {
-  loadEnv()
+
+function applyLoadedEnv(loaded: LoadedEnvFile, externalKeys: Set<string>, options?: { overwriteLoaded?: boolean }) {
+  for (const [key, value] of Object.entries(loaded)) {
+    if (externalKeys.has(key)) continue
+    if (options?.overwriteLoaded || process.env[key] === undefined || process.env[key] === '') {
+      process.env[key] = value
+    }
+  }
+}
+
+function loadEnv(): { generated: LoadedEnvFile; local: LoadedEnvFile } {
+  const externalKeys = new Set(
+    Object.entries(process.env)
+      .filter(([, value]) => typeof value === 'string' && value.length > 0)
+      .map(([key]) => key),
+  )
+  const generated = loadEnvFile(GENERATED_ENV_PATH)
+  const local = loadEnvFile(path.join(process.cwd(), '.env.local'))
+
+  applyLoadedEnv(generated, externalKeys)
+  applyLoadedEnv(local, externalKeys, { overwriteLoaded: true })
+  return { generated, local }
+}
+
+function appendCandidate(candidates: CredentialSecretCandidate[], seen: Set<string>, candidate: CredentialSecretCandidate): void {
+  const secret = cleanSecret(candidate.secret)
+  if (!secret || seen.has(secret)) return
+  seen.add(secret)
+  candidates.push({ ...candidate, secret })
+}
+
+function readEnvCandidate(filePath: string, source: string): CredentialSecretCandidate | null {
+  try {
+    if (!fs.existsSync(filePath)) return null
+    const secret = cleanSecret(loadEnvFile(filePath).CREDENTIAL_SECRET)
+    if (!secret) return null
+    return {
+      secret,
+      source,
+      mtimeMs: fs.statSync(filePath).mtimeMs,
+    }
+  } catch (err) {
+    log.debug(TAG, `Could not inspect legacy CREDENTIAL_SECRET candidate at ${filePath}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return null
+  }
+}
+
+function findStateHomeCandidates(): string[] {
+  const homes: string[] = []
+  const configuredHome = cleanSecret(process.env.SWARMCLAW_HOME)
+  if (configuredHome) homes.push(path.resolve(configuredHome))
+  if (path.basename(DATA_DIR) === 'data') homes.push(path.dirname(DATA_DIR))
+  return Array.from(new Set(homes))
+}
+
+function collectPreviousBuildSecretCandidates(seen: Set<string>): CredentialSecretCandidate[] {
+  const candidates: CredentialSecretCandidate[] = []
+  for (const home of findStateHomeCandidates()) {
+    const buildsDir = path.join(home, 'builds')
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(buildsDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith('package-')) continue
+      const buildRoot = path.join(buildsDir, entry.name)
+      const envPaths = [
+        path.join(buildRoot, '.env.local'),
+        path.join(buildRoot, '.env.local.bak'),
+        path.join(buildRoot, '.next', 'standalone', '.env.local'),
+        path.join(buildRoot, '.next', 'standalone', '.env.local.bak'),
+      ]
+      for (const envPath of envPaths) {
+        const candidate = readEnvCandidate(envPath, `previous build env ${envPath}`)
+        if (candidate) appendCandidate(candidates, seen, candidate)
+      }
+    }
+  }
+
+  return candidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
+}
+
+function readEncryptedCredentialKeysFromObject(value: unknown): string[] {
+  if (!value || typeof value !== 'object') return []
+  return Object.values(value as Record<string, unknown>)
+    .map((entry) => {
+      if (!entry || typeof entry !== 'object') return ''
+      return cleanSecret((entry as Record<string, unknown>).encryptedKey)
+    })
+    .filter(Boolean)
+}
+
+function readEncryptedCredentialKeys(): string[] {
+  const keys: string[] = []
+  const jsonPath = path.join(DATA_DIR, 'credentials.json')
+  try {
+    if (fs.existsSync(jsonPath)) {
+      keys.push(...readEncryptedCredentialKeysFromObject(JSON.parse(fs.readFileSync(jsonPath, 'utf8'))))
+    }
+  } catch (err) {
+    log.debug(TAG, `Could not inspect encrypted credentials in ${jsonPath}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  const dbPath = path.join(DATA_DIR, 'swarmclaw.db')
+  try {
+    if (fs.existsSync(dbPath)) {
+      const db = new Database(dbPath, { readonly: true, fileMustExist: true })
+      try {
+        const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'credentials'").get()
+        if (table) {
+          const rows = db.prepare('SELECT data FROM credentials LIMIT 500').all() as Array<{ data: string }>
+          const fromDb: Record<string, unknown> = {}
+          for (const [index, row] of rows.entries()) {
+            try {
+              fromDb[`row_${index}`] = JSON.parse(row.data)
+            } catch {
+              // Ignore malformed rows; storage normalization handles them later.
+            }
+          }
+          keys.push(...readEncryptedCredentialKeysFromObject(fromDb))
+        }
+      } finally {
+        db.close()
+      }
+    }
+  } catch (err) {
+    log.debug(TAG, `Could not inspect encrypted credentials in ${dbPath}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  return Array.from(new Set(keys))
 }
 
+function canDecryptCredential(encryptedKey: string, secret: string): boolean {
+  try {
+    const parts = encryptedKey.split(':')
+    if (parts.length !== 3) return false
+    const [ivHex, tagHex, encrypted] = parts
+    const key = Buffer.from(secret, 'hex')
+    if (key.length !== 32) return false
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(ivHex, 'hex'))
+    decipher.setAuthTag(Buffer.from(tagHex, 'hex'))
+    decipher.update(encrypted, 'hex', 'utf8')
+    decipher.final('utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+function countDecryptableCredentials(secret: string, encryptedKeys: string[]): number {
+  if (encryptedKeys.length === 0) return 0
+  return encryptedKeys.filter((encryptedKey) => canDecryptCredential(encryptedKey, secret)).length
+}
+
+function selectCredentialSecretCandidate(
+  candidates: CredentialSecretCandidate[],
+  encryptedKeys: string[],
+): CredentialSecretCandidate | null {
+  if (candidates.length === 0) return null
+  if (encryptedKeys.length === 0) return candidates[0]
+
+  let best: { candidate: CredentialSecretCandidate; count: number } | null = null
+  for (const candidate of candidates) {
+    const count = countDecryptableCredentials(candidate.secret, encryptedKeys)
+    if (count === 0) continue
+    if (!best || count > best.count) best = { candidate, count }
+  }
+  return best?.candidate ?? null
+}
+const externalCredentialSecret = process.env.CREDENTIAL_SECRET?.trim() || ''
+const loadedEnv: { generated: LoadedEnvFile; local: LoadedEnvFile } = !IS_BUILD_BOOTSTRAP
+  ? loadEnv()
+  : { generated: {}, local: {} }
+
 /** Append a key=value to a file only if the key doesn't already exist in it. */
 function appendEnvKeyIfMissing(envPath: string, key: string, value: string): void {
   const existing = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : ''
@@ -59,12 +252,112 @@ function persistEnvKey(key: string, value: string): void {
   }
 }
 
-// Auto-generate CREDENTIAL_SECRET if missing
-if (!IS_BUILD_BOOTSTRAP && !process.env.CREDENTIAL_SECRET) {
-  const secret = crypto.randomBytes(32).toString('hex')
-  process.env.CREDENTIAL_SECRET = secret
-  persistEnvKey('CREDENTIAL_SECRET', secret)
-  log.info(TAG, 'Generated CREDENTIAL_SECRET')
+/** Read CREDENTIAL_SECRET from the dedicated file in DATA_DIR.
+ *  Returns the trimmed contents, or empty string if absent / unreadable. */
+function readCredentialSecretFile(): string {
+  try {
+    if (!fs.existsSync(CREDENTIAL_SECRET_FILE)) return ''
+    return fs.readFileSync(CREDENTIAL_SECRET_FILE, 'utf-8').trim()
+  } catch (err) {
+    log.warn(TAG, `Could not read CREDENTIAL_SECRET from ${CREDENTIAL_SECRET_FILE}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return ''
+  }
+}
+
+/** Write CREDENTIAL_SECRET to the dedicated file with restrictive permissions. */
+function writeCredentialSecretFile(secret: string): boolean {
+  try {
+    fs.mkdirSync(path.dirname(CREDENTIAL_SECRET_FILE), { recursive: true })
+    fs.writeFileSync(CREDENTIAL_SECRET_FILE, secret, { encoding: 'utf-8', mode: 0o600 })
+    return true
+  } catch (err) {
+    log.warn(TAG, `Could not persist CREDENTIAL_SECRET to ${CREDENTIAL_SECRET_FILE}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return false
+  }
+}
+
+// Resolve CREDENTIAL_SECRET in this precedence order:
+//   1. process.env (already set externally, e.g. by orchestrator)
+//   2. DATA_DIR/credential-secret (the stable home — survives upgrades)
+//   3. .env files (legacy current cwd plus prior npm-global build env files)
+//   4. Generate new secret + persist to DATA_DIR/credential-secret
+//
+// Step 2 is the key change: previously the secret only lived in a per-version
+// .env.local (cwd changes on npm-global upgrade), so each upgrade
+// silently regenerated it and orphaned every encrypted credential. When
+// encrypted credentials already exist, validate candidate legacy secrets by
+// actually decrypting a stored credential before persisting the migration.
+if (!IS_BUILD_BOOTSTRAP) {
+  const encryptedCredentialKeys = readEncryptedCredentialKeys()
+  const candidateSeen = new Set<string>()
+  const legacyCandidates: CredentialSecretCandidate[] = []
+  appendCandidate(legacyCandidates, candidateSeen, {
+    secret: cleanSecret(loadedEnv.local.CREDENTIAL_SECRET),
+    source: `${path.join(process.cwd(), '.env.local')}`,
+    mtimeMs: 0,
+  })
+  appendCandidate(legacyCandidates, candidateSeen, {
+    secret: cleanSecret(loadedEnv.generated.CREDENTIAL_SECRET),
+    source: GENERATED_ENV_PATH,
+    mtimeMs: 0,
+  })
+  legacyCandidates.push(...collectPreviousBuildSecretCandidates(candidateSeen))
+
+  const legacyEnvSecret = legacyCandidates[0]?.secret || ''
+  const fileSecret = readCredentialSecretFile()
+  if (externalCredentialSecret) {
+    process.env.CREDENTIAL_SECRET = externalCredentialSecret
+    if (fileSecret && fileSecret !== externalCredentialSecret) {
+      log.warn(TAG, `CREDENTIAL_SECRET is set by the environment and differs from ${CREDENTIAL_SECRET_FILE}; using the environment value.`)
+    }
+  } else if (fileSecret) {
+    const fileDecryptsCredentials = encryptedCredentialKeys.length === 0
+      || countDecryptableCredentials(fileSecret, encryptedCredentialKeys) > 0
+    if (!fileDecryptsCredentials) {
+      const recovered = selectCredentialSecretCandidate(
+        legacyCandidates.filter((candidate) => candidate.secret !== fileSecret),
+        encryptedCredentialKeys,
+      )
+      if (recovered) {
+        process.env.CREDENTIAL_SECRET = recovered.secret
+        writeCredentialSecretFile(recovered.secret)
+        log.warn(TAG, `Recovered CREDENTIAL_SECRET from ${recovered.source} because ${CREDENTIAL_SECRET_FILE} could not decrypt existing credentials.`)
+      } else {
+        process.env.CREDENTIAL_SECRET = fileSecret
+        log.warn(TAG, `${CREDENTIAL_SECRET_FILE} could not decrypt existing credentials, and no recoverable previous-build CREDENTIAL_SECRET was found.`)
+      }
+    } else {
+      process.env.CREDENTIAL_SECRET = fileSecret
+      if (legacyEnvSecret && legacyEnvSecret !== fileSecret) {
+        // Both persisted locations exist and disagree. Trust DATA_DIR because it
+        // survives npm-global upgrades and Docker restarts.
+        log.warn(TAG, `CREDENTIAL_SECRET mismatch between legacy env files and ${CREDENTIAL_SECRET_FILE}; using the file value.`)
+      }
+    }
+  } else {
+    const recovered = selectCredentialSecretCandidate(legacyCandidates, encryptedCredentialKeys)
+    if (recovered) {
+      process.env.CREDENTIAL_SECRET = recovered.secret
+      if (writeCredentialSecretFile(recovered.secret)) {
+        log.info(TAG, `Migrated CREDENTIAL_SECRET from ${recovered.source} to ${CREDENTIAL_SECRET_FILE}`)
+      }
+    } else if (legacyEnvSecret) {
+      process.env.CREDENTIAL_SECRET = legacyEnvSecret
+      if (writeCredentialSecretFile(legacyEnvSecret)) {
+        log.info(TAG, `Migrated CREDENTIAL_SECRET from .env to ${CREDENTIAL_SECRET_FILE}`)
+      }
+    } else {
+      // First-ever launch on this DATA_DIR. Generate.
+      const secret = crypto.randomBytes(32).toString('hex')
+      process.env.CREDENTIAL_SECRET = secret
+      writeCredentialSecretFile(secret)
+      log.info(TAG, `Generated CREDENTIAL_SECRET and persisted to ${CREDENTIAL_SECRET_FILE}`)
+    }
+  }
 }
 
 // Auto-generate ACCESS_KEY if missing (used for simple auth)

package/src/lib/server/tasks/task-route-service.ts

@@ -290,6 +290,52 @@ export function updateTaskFromRoute(id: string, body: Record<string, unknown>):
   return serviceOk(tasks[id])
 }
 
+export function retryTaskFromRoute(id: string): ServiceResult<BoardTask> {
+  const tasks = loadTasks()
+  const task = tasks[id]
+  if (!task) return serviceFail(404, 'Task not found')
+  if (task.status !== 'failed') {
+    return serviceFail(409, 'Only failed tasks can be retried.')
+  }
+
+  const blockers = Array.isArray(task.blockedBy) ? task.blockedBy : []
+  const incompleteBlocker = blockers.find((bid: string) => tasks[bid] && tasks[bid].status !== 'completed')
+  if (incompleteBlocker) {
+    return serviceFail(409, 'Cannot retry: blocked by incomplete tasks')
+  }
+
+  const now = Date.now()
+  if (!task.comments) task.comments = []
+  task.comments.push({
+    id: genId(),
+    author: 'System',
+    text: 'Task retry requested by operator.',
+    createdAt: now,
+  })
+  task.status = 'queued'
+  task.attempts = 0
+  task.deadLetteredAt = null
+  task.retryScheduledAt = null
+  task.checkoutRunId = null
+  task.error = null
+  task.validation = null
+  task.startedAt = null
+  task.completedAt = null
+  task.queuedAt = now
+  task.updatedAt = now
+  task.liveness = computeTaskLiveness(task, tasks, { now })
+
+  saveTask(id, task)
+  enqueueTask(id)
+  logActivity({ entityType: 'task', entityId: id, action: 'queued', actor: 'user', summary: `Task retried: "${task.title}"` })
+  pushMainLoopEventToMainSessions({
+    type: 'task_queued',
+    text: `Task retried and queued: "${task.title}" (${id}).`,
+  })
+  notify('tasks')
+  return serviceOk(loadTask(id) || task)
+}
+
 export function decideTaskExecutionPolicyFromRoute(
   id: string,
   body: Record<string, unknown>,

package/src/lib/server/tasks/task-service.test.ts

@@ -154,6 +154,56 @@ describe('task-service assignment workflow transitions', () => {
     }
   })
 
+  it('auto-queues agent-created tasks delegated to a different agent', () => {
+    const prepared = prepareTaskCreation({
+      input: {
+        title: 'Build delegated client',
+        description: 'Hand this work to the builder.',
+        agentId: 'builder',
+      },
+      tasks: {},
+      now: 210,
+      creatorAgentId: 'coordinator',
+      autoQueueDelegatedTasks: true,
+    })
+
+    assert.equal(prepared.ok, true)
+    if (!prepared.ok) return
+    assert.equal(prepared.task.status, 'queued')
+    assert.equal(prepared.task.agentId, 'builder')
+  })
+
+  it('does not auto-queue self-assigned or explicitly backlogged tasks', () => {
+    const selfAssigned = prepareTaskCreation({
+      input: {
+        title: 'Self task',
+        description: '',
+        agentId: 'coordinator',
+      },
+      tasks: {},
+      now: 220,
+      creatorAgentId: 'coordinator',
+      autoQueueDelegatedTasks: true,
+    })
+    assert.equal(selfAssigned.ok, true)
+    if (selfAssigned.ok) assert.equal(selfAssigned.task.status, 'backlog')
+
+    const explicitBacklog = prepareTaskCreation({
+      input: {
+        title: 'Explicit backlog',
+        description: '',
+        agentId: 'builder',
+        status: 'backlog',
+      },
+      tasks: {},
+      now: 230,
+      creatorAgentId: 'coordinator',
+      autoQueueDelegatedTasks: true,
+    })
+    assert.equal(explicitBacklog.ok, true)
+    if (explicitBacklog.ok) assert.equal(explicitBacklog.task.status, 'backlog')
+  })
+
   it('leaves already-started workflow states alone', () => {
     const next = resolveAssignmentWorkflowStateTransition({
       previousAgentId: '',

package/src/lib/server/tasks/task-service.ts

@@ -171,6 +171,8 @@ export interface PrepareTaskCreationOptions {
   now: number
   settings?: AppSettings | Record<string, unknown> | null
   fallbackAgentId?: string | null
+  creatorAgentId?: string | null
+  autoQueueDelegatedTasks?: boolean
   defaultCwd?: string | null
   deriveTitleFromDescription?: boolean
   requireMeaningfulTitle?: boolean
@@ -194,11 +196,22 @@ export function prepareTaskCreation(options: PrepareTaskCreationOptions): Prepar
     return { ok: false, error: 'Error: manage_tasks create requires a specific title or a meaningful description.' }
   }
 
-  const normalizedStatus = normalizeTaskStatusInput(options.input.status) || 'backlog'
   const description = typeof options.input.description === 'string' ? options.input.description : ''
   const agentId = typeof options.input.agentId === 'string'
-    ? options.input.agentId
-    : (typeof options.fallbackAgentId === 'string' ? options.fallbackAgentId : '')
+    ? options.input.agentId.trim()
+    : (typeof options.fallbackAgentId === 'string' ? options.fallbackAgentId.trim() : '')
+  const explicitStatus = Object.prototype.hasOwnProperty.call(options.input, 'status')
+  let normalizedStatus = normalizeTaskStatusInput(options.input.status) || 'backlog'
+  const creatorAgentId = typeof options.creatorAgentId === 'string' ? options.creatorAgentId.trim() : ''
+  if (
+    !explicitStatus
+    && options.autoQueueDelegatedTasks === true
+    && creatorAgentId
+    && agentId
+    && agentId !== creatorAgentId
+  ) {
+    normalizedStatus = 'queued'
+  }
   const qualityGate = Object.prototype.hasOwnProperty.call(options.input, 'qualityGate')
     ? (options.input.qualityGate
       ? normalizeTaskQualityGate(options.input.qualityGate, options.settings || null)

package/src/lib/server/universal-tool-access.test.ts

@@ -24,6 +24,16 @@ function scoped(declared: string[] | null | undefined, universe: Set<string> = U
   return Array.from(new Set([...SCOPED_TOOL_BASELINE, ...picks]))
 }
 
+function scopedWithAttachedExtensions(
+  declared: string[] | null | undefined,
+  extraExtensions: string[] | null | undefined,
+  universe: Set<string> = UNIVERSAL_SAMPLE,
+): string[] {
+  const picks = normalize(declared).filter((t) => universe.has(t))
+  const attachedExternalExtensions = normalize(extraExtensions).filter((entry) => /\.(?:m?js)$/i.test(entry))
+  return Array.from(new Set([...SCOPED_TOOL_BASELINE, ...picks, ...attachedExternalExtensions]))
+}
+
 describe('scoped tool access algorithm', () => {
   it('intersects declared tools with the universe and keeps the baseline', () => {
     const out = scoped(['shell', 'files', 'edit_file', 'web'])
@@ -68,4 +78,10 @@ describe('scoped tool access algorithm', () => {
     assert.ok(out.includes('shell'))
     assert.ok(out.includes('files'))
   })
+
+  it('keeps explicitly attached external extensions in scoped mode', () => {
+    const out = scopedWithAttachedExtensions(['shell'], ['freedzhost-critic.js'])
+    assert.ok(out.includes('shell'))
+    assert.ok(out.includes('freedzhost-critic.js'))
+  })
 })

package/src/lib/server/universal-tool-access.ts

@@ -1,4 +1,5 @@
 import { dedup } from '@/lib/shared-utils'
+import { isExternalExtensionId } from '@/lib/capability-selection'
 import { getExtensionManager } from './extensions'
 
 const UNIVERSAL_CORE_EXTENSION_IDS = [
@@ -78,5 +79,6 @@ export function listScopedToolAccessExtensionIds(
   const universe = new Set(listUniversalToolAccessExtensionIds(extraExtensions))
   const declared = normalizeExtensionList(declaredTools)
   const scoped = declared.filter((tool) => universe.has(tool))
-  return dedup([...SCOPED_TOOL_BASELINE, ...scoped])
+  const explicitlyAttachedExternalExtensions = normalizeExtensionList(extraExtensions).filter(isExternalExtensionId)
+  return dedup([...SCOPED_TOOL_BASELINE, ...scoped, ...explicitlyAttachedExternalExtensions])
 }

package/src/lib/validation/schemas.ts

@@ -140,6 +140,18 @@ export const AgentCreateSchema = z.object({
   projectId: z.string().optional(),
   avatarSeed: z.string().optional(),
   avatarUrl: z.string().nullable().optional().default(null),
+  /** Per-agent working directory. Used as the cwd for execute tool calls and
+   *  as the root for workspace-scoped file operations. */
+  workspace: z.string().nullable().optional().default(null),
+  /** When 'workspace', the structured file tool's reads/writes are confined to
+   *  the agent's workspace directory; 'machine' allows the whole host. */
+  filesystemScope: z.enum(['workspace', 'machine']).nullable().optional().default(null),
+  /** Per-agent filesystem allow/block lists enforced by the file tool. Globs
+   *  are matched against fully-resolved absolute paths. */
+  fileAccessPolicy: z.object({
+    allowedPaths: z.array(z.string()).optional(),
+    blockedPaths: z.array(z.string()).optional(),
+  }).nullable().optional().default(null),
   sandboxConfig: AgentSandboxConfigSchema,
   executeConfig: AgentExecuteConfigSchema,
   autoRecovery: z.boolean().optional().default(false),

package/src/types/agent.ts

@@ -142,6 +142,7 @@ export interface Agent {
    */
   planningMode?: 'off' | 'strict' | null
   /** Controls whether file operations are confined to the workspace or allowed anywhere on the host. Default: 'workspace'. */
+  workspace?: string | null
   filesystemScope?: 'workspace' | 'machine' | null
   /** Per-agent filesystem restrictions. Globs matched against resolved paths. */
   fileAccessPolicy?: {