@controlflow-ai/daemon 0.1.2 → 0.1.4

package/README.md

@@ -15,6 +15,10 @@ The current preferred model is computer-first: provision a computer, start one d
 
 ## Quick Start
 
+The commands below work on Linux/macOS shells. For native Windows daemon setup,
+PowerShell examples, and Windows path notes, see
+[`docs/windows-daemon.md`](docs/windows-daemon.md).
+
 ### 1. Install Dependencies
 
 ```bash
@@ -27,6 +31,12 @@ For disposable local smoke tests, keep state isolated:
 export PAL_HOME=/tmp/pal-demo
 ```
 
+PowerShell equivalent:
+
+```powershell
+$env:PAL_HOME = "$env:TEMP\pal-demo"
+```
+
 ### 2. Start Server
 
 ```bash
@@ -39,6 +49,14 @@ Server listens on `http://127.0.0.1:4127/` by default. Change the bind address w
 PAL_HOST=0.0.0.0 PAL_PORT=4127 bun run server
 ```
 
+PowerShell equivalent:
+
+```powershell
+$env:PAL_HOST = "0.0.0.0"
+$env:PAL_PORT = "4127"
+bun run server
+```
+
 When clients or daemons connect through a non-default address, pass `--server <url>` or set `PAL_SERVER` / `LOCK_SERVER_URL` to the reachable URL.
 
 ### 3. Provision a Computer
@@ -49,6 +67,13 @@ curl -s -X POST http://127.0.0.1:4127/api/computers/provision \
   -d '{"name":"Local Demo","server_url":"http://127.0.0.1:4127"}'
 ```
 
+PowerShell equivalent:
+
+```powershell
+$body = @{ name = "Local Demo"; server_url = "http://127.0.0.1:4127" } | ConvertTo-Json
+Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:4127/api/computers/provision" -ContentType "application/json" -Body $body
+```
+
 The response includes a `computer.id`, an `api_key`, and a packaged daemon command. For a source checkout, start the local Bun daemon with the returned key:
 
 ```bash
@@ -84,10 +109,10 @@ curl -s -X POST http://127.0.0.1:4127/api/agents/codex/assignment \
 
 ```bash
 # Through the local daemon
-bun run cli -- send --room general --from alice --to codex "hello"
+bun run cli -- send --room general --from alice --mention codex "hello"
 
 # Directly to the server
-bun run console -- send --chat general --from alice --to codex "hello"
+bun run console -- send --chat general --from alice --mention codex "hello"
 ```
 
 ## Console Commands
@@ -112,6 +137,9 @@ bun run console -- agents update --key <agent-key> [--runtime neeko|coco|codex]
 bun run console -- agents update --key <agent-key> --lark-app-id <app-id> --lark-app-secret <app-secret> [--lark-label <name>] [--rebind-lark]
 bun run console -- agents update --key <agent-key> --unbind-lark
 bun run console -- agents update --interactive
+
+# Delete an agent and clean up its assignment, room memberships, subscriptions, Lark binding, and active deliveries
+bun run console -- agents delete --key <agent-key> --yes
 ```
 
 `codex` is the validated runtime for the current demo environment. Do not use `neeko` or `coco` until their binaries and adapters are available on the runtime host.
@@ -174,7 +202,7 @@ CLI connects through the local daemon. It is the surface used by coding agents a
 
 ```bash
 # Send a message
-bun run cli -- send --room general --from alice [--to codex] "Task completed"
+bun run cli -- send --room general --from alice [--mention codex ...] "Task completed"
 
 # Reply to an existing message
 bun run cli -- send --room general --from codex --parent 1 "Reply content"
@@ -189,6 +217,9 @@ bun run cli -- rooms members --room general [--json]
 # Invite an agent to a room with a delivery mode
 bun run cli -- rooms invite --room general --agent codex [--mode mentions|all|periodic|muted|off]
 
+# Restart the active runtime for an agent in a room
+bun run cli -- rooms restart-agent --room general --agent codex [--json]
+
 # Create a topic inside a room
 bun run cli -- topics create --room general "Investigation"
 
@@ -218,6 +249,7 @@ bun run cli -- chats [--json]
 bun run cli -- runs [--json]
 bun run cli -- run-action <run-id> kill
 bun run cli -- run-action <run-id> restart
+bun run cli -- rooms restart-agent --room general --agent codex
 ```
 
 ## Daemon Commands
@@ -242,7 +274,21 @@ bun run daemon -- --agent codex --computer-id hm-media-demo --computer-secret pa
 bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_... --once
 ```
 
-The daemon creates one local API for CLI calls, connects the computer to the server, heartbeats the connection, reconciles assigned agents, claims pending deliveries for currently assigned agents, and starts one runtime process per claimed delivery. It can stay online with no assigned agents. Runs have no default timeout; use run actions to kill or restart them.
+PowerShell equivalents:
+
+```powershell
+# Preferred computer-first startup
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_...
+
+# Equivalent env-var startup
+$env:PAL_API_KEY = "sk_machine_..."
+bun run daemon -- --server http://127.0.0.1:4127
+
+# Windows project checkout as runtime cwd
+bun run daemon -- --server http://127.0.0.1:4127 --api-key sk_machine_... --cwd C:\Projects\pal
+```
+
+The daemon creates one local API for CLI calls, connects the computer to the server, opens a delivery WebSocket at `/api/daemon/ws`, heartbeats the connection, reconciles assigned agents, claims pending deliveries for currently assigned agents, and starts one runtime process per claimed delivery. The WebSocket is a wakeup path, not the reliability boundary: deliveries are still durably recorded as `pending`, so messages can be sent while the daemon is offline or the network is unhealthy, and the daemon drains pending work when the socket reconnects. If the WebSocket is unavailable, the daemon falls back to processing pending deliveries during its heartbeat loop. It can stay online with no assigned agents. Runs have no default timeout; use run actions to kill or restart them.
 
 ## Environment Variables
 
@@ -275,7 +321,7 @@ bun run console -- lark-users delete --user-id <union-id>
 ## Runtime Semantics
 
 - Rooms are the primary conversation container; `chat` remains as a compatibility alias in several APIs.
-- Agents receive deliveries through room subscriptions, direct recipients, or Lark bot bindings.
+- Agents receive deliveries through room subscriptions, direct mentions, or Lark bot bindings.
 - A daemon starts one agent run for each claimed delivery.
 - Runs do not have a default timeout. Agents can work as long as needed.
 - A visible chat reply is just a message, not run completion.
@@ -294,6 +340,7 @@ Common read and room APIs:
 - `GET /api/rooms/<room-id-or-name>/members`
 - `GET /api/rooms/<room-id-or-name>/mentionables`
 - `POST /api/rooms/<room-id-or-name>/agents`
+- `POST /api/rooms/<room-id-or-name>/agents/<agent-key>/restart`
 - `POST /api/rooms/<room-id-or-name>/topics`
 - `GET /api/messages?chat=general&after=0&limit=50`
 - `GET /api/messages/<id>`
@@ -305,6 +352,7 @@ Computer, daemon, and delivery APIs:
 - `POST /api/computers/provision`
 - `POST /api/computers/connect`
 - `POST /api/computers/<computer-id>/heartbeat`
+- `GET /api/daemon/ws`
 - `POST /api/daemons`
 - `GET /api/deliveries?agent=codex&status=pending&limit=50`
 - `POST /api/deliveries`
@@ -343,7 +391,7 @@ Example message body:
 {
   "room": "general",
   "sender": "alice",
-  "recipient": "codex",
+  "mentions": ["codex"],
   "content": "hello"
 }
 ```

package/bin/daemon.js

@@ -1,2 +1,7 @@
 #!/usr/bin/env bun
-import '../src/daemon.ts';
+import { main } from '../src/daemon.ts';
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@controlflow-ai/daemon",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "scripts": {
     "server": "bun run src/server.ts",
+    "server:dev": "bun --watch src/server.ts",
     "daemon": "bun run src/daemon.ts",
+    "daemon:dev": "bun --watch src/daemon.ts",
     "cli": "bun run src/cli.ts",
     "console": "bun run src/console.ts",
     "web:dev": "vite --config web/app/vite.config.ts --host 127.0.0.1",

package/src/agent-avatar.ts

@@ -0,0 +1,30 @@
+const avatarKeys = [
+  'sage',
+  'teal',
+  'indigo',
+  'amber',
+  'rose',
+  'violet',
+  'slate',
+  'moss',
+] as const;
+
+export type AgentAvatar = typeof avatarKeys[number];
+
+function hashSeed(seed: string): number {
+  let hash = 2166136261;
+  for (const char of seed) {
+    hash ^= char.charCodeAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+export function generateAgentAvatar(agentKey: string, displayName = ''): AgentAvatar {
+  const seed = `${agentKey.trim().toLowerCase()}:${displayName.trim().toLowerCase()}`;
+  return avatarKeys[hashSeed(seed) % avatarKeys.length]!;
+}
+
+export function normalizeAgentAvatar(value: unknown, agentKey: string, displayName = ''): AgentAvatar {
+  return avatarKeys.includes(value as AgentAvatar) ? value as AgentAvatar : generateAgentAvatar(agentKey, displayName);
+}

package/src/agent-key.ts

@@ -0,0 +1,28 @@
+import type { MessageStore } from './db.js';
+
+export function agentKeyFromDisplayName(displayName: string): string {
+  const slug = displayName
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/['’]/g, '')
+    .replace(/[^\p{Letter}\p{Number}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+    .split('')
+    .slice(0, 64)
+    .join('')
+    .replace(/-+$/g, '');
+  return slug || 'agent';
+}
+
+export function uniqueAgentKeyFromDisplayName(displayName: string, store: Pick<MessageStore, 'getAgent'>): string {
+  const base = agentKeyFromDisplayName(displayName);
+  let candidate = base;
+  let suffix = 2;
+  while (store.getAgent(candidate)) {
+    candidate = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  return candidate;
+}

package/src/agent-permissions.ts

@@ -0,0 +1,359 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, normalize, relative, win32 } from 'node:path';
+import type { AgentRuntimeRunInput } from './agent-runtime.js';
+
+export type FilesystemPermissionMode = 'project-write' | 'scoped-write' | 'full-access';
+
+export interface RuntimeLaunchContext {
+  runtimeRoot: string;
+  agentHome: string;
+  projectRoot: string | null;
+}
+
+export interface AgentPermissionProfile {
+  filesystemMode: FilesystemPermissionMode;
+  extraWritableRoots: string[];
+}
+
+export interface PermissionValidationDiagnostic {
+  level: 'error' | 'warning';
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface PermissionValidationResult {
+  ok: boolean;
+  profile: AgentPermissionProfile;
+  diagnostics: PermissionValidationDiagnostic[];
+  warnings: PermissionValidationDiagnostic[];
+}
+
+export const defaultAgentPermissionProfile: AgentPermissionProfile = {
+  filesystemMode: 'project-write',
+  extraWritableRoots: [],
+};
+
+function isWindowsAbsolutePath(path: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(path) || /^\\\\[^\\]+\\[^\\]+/.test(path);
+}
+
+function isPortableAbsolutePath(path: string): boolean {
+  return isAbsolute(path) || isWindowsAbsolutePath(path);
+}
+
+function normalizeWindowsWritableRoot(path: string): string {
+  const normalized = win32.normalize(path.trim());
+  const root = win32.parse(normalized).root;
+  return normalized === root ? normalized : normalized.replace(/[\\/]+$/, '');
+}
+
+export function isFilesystemPermissionMode(value: unknown): value is FilesystemPermissionMode {
+  return value === 'project-write' || value === 'scoped-write' || value === 'full-access';
+}
+
+export function normalizeWritableRoot(path: string): string {
+  if (isWindowsAbsolutePath(path.trim())) return normalizeWindowsWritableRoot(path);
+  const normalized = normalize(path.trim());
+  return normalized === '/' ? normalized : normalized.replace(/\/+$/, '');
+}
+
+export function normalizeExtraWritableRoots(paths: unknown): string[] {
+  if (!Array.isArray(paths)) return [];
+  const seen = new Set<string>();
+  const roots: string[] = [];
+  for (const item of paths) {
+    if (typeof item !== 'string') continue;
+    const normalized = normalizeWritableRoot(item);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    roots.push(normalized);
+  }
+  return roots;
+}
+
+export function coerceAgentPermissionProfile(input: unknown): AgentPermissionProfile {
+  if (!input || typeof input !== 'object') return { ...defaultAgentPermissionProfile };
+  const record = input as Record<string, unknown>;
+  return {
+    filesystemMode: isFilesystemPermissionMode(record.filesystemMode) ? record.filesystemMode : defaultAgentPermissionProfile.filesystemMode,
+    extraWritableRoots: normalizeExtraWritableRoots(record.extraWritableRoots),
+  };
+}
+
+export function validateAgentPermissionProfile(input: unknown, options: { checkFilesystem?: boolean } = {}): PermissionValidationResult {
+  const raw = input && typeof input === 'object' ? input as Record<string, unknown> : {};
+  const diagnostics: PermissionValidationDiagnostic[] = [];
+  const filesystemMode = raw.filesystemMode;
+  if (filesystemMode !== undefined && !isFilesystemPermissionMode(filesystemMode)) {
+    diagnostics.push({ level: 'error', code: 'BAD_FILESYSTEM_MODE', message: 'filesystemMode must be project-write, scoped-write, or full-access' });
+  }
+
+  if ('extraWritableRoots' in raw && !Array.isArray(raw.extraWritableRoots)) {
+    diagnostics.push({ level: 'error', code: 'BAD_EXTRA_WRITABLE_ROOTS', message: 'extraWritableRoots must be an array of absolute paths' });
+  }
+
+  const seen = new Set<string>();
+  const roots: string[] = [];
+  if (Array.isArray(raw.extraWritableRoots)) {
+    for (const value of raw.extraWritableRoots) {
+      if (typeof value !== 'string') {
+        diagnostics.push({ level: 'error', code: 'BAD_EXTRA_WRITABLE_ROOT', message: 'extra writable root must be a string' });
+        continue;
+      }
+      const trimmed = value.trim();
+      if (!trimmed) {
+        diagnostics.push({ level: 'error', code: 'EMPTY_EXTRA_WRITABLE_ROOT', message: 'extra writable root cannot be empty' });
+        continue;
+      }
+      const normalized = normalizeWritableRoot(trimmed);
+      if (!isPortableAbsolutePath(normalized)) {
+        diagnostics.push({ level: 'error', code: 'EXTRA_WRITABLE_ROOT_NOT_ABSOLUTE', message: 'extra writable root must be an absolute path', path: value });
+        continue;
+      }
+      if (seen.has(normalized)) {
+        diagnostics.push({ level: 'error', code: 'DUPLICATE_EXTRA_WRITABLE_ROOT', message: 'extra writable roots cannot contain duplicates', path: normalized });
+        continue;
+      }
+      seen.add(normalized);
+      if (options.checkFilesystem) {
+        try {
+          const stat = statSync(normalized);
+          if (!stat.isDirectory()) diagnostics.push({ level: 'error', code: 'EXTRA_WRITABLE_ROOT_NOT_DIRECTORY', message: 'extra writable root must be a directory', path: normalized });
+        } catch {
+          diagnostics.push({ level: 'error', code: 'EXTRA_WRITABLE_ROOT_NOT_FOUND', message: 'extra writable root does not exist', path: normalized });
+        }
+      }
+      roots.push(normalized);
+    }
+  }
+
+  const profile: AgentPermissionProfile = {
+    filesystemMode: isFilesystemPermissionMode(filesystemMode) ? filesystemMode : defaultAgentPermissionProfile.filesystemMode,
+    extraWritableRoots: roots,
+  };
+
+  if (profile.filesystemMode === 'full-access') {
+    diagnostics.push({ level: 'warning', code: 'FULL_ACCESS_DANGEROUS', message: 'full-access disables filesystem sandboxing and should only be used for trusted agents' });
+  }
+
+  const warnings = diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+  return { ok: diagnostics.every((diagnostic) => diagnostic.level !== 'error'), profile, diagnostics, warnings };
+}
+
+export function runtimeStateHome(input: AgentRuntimeRunInput): string {
+  return input.launchContext?.agentHome ?? input.agentHome ?? input.cwd;
+}
+
+export function runtimeLaunchRoot(input: AgentRuntimeRunInput): string {
+  return input.launchContext?.runtimeRoot ?? input.agentHome ?? input.cwd;
+}
+
+export function buildRuntimeLaunchContext(input: AgentRuntimeRunInput): RuntimeLaunchContext {
+  const agentHome = input.agentHome ?? input.cwd;
+  const projectRoot = input.projectCwd ?? null;
+  return {
+    runtimeRoot: agentHome,
+    agentHome,
+    projectRoot,
+  };
+}
+
+export function effectivePermissionProfile(input: AgentRuntimeRunInput): AgentPermissionProfile {
+  return input.permissionProfile ?? defaultAgentPermissionProfile;
+}
+
+export function buildCodexPermissionArgs(profile: AgentPermissionProfile, context: RuntimeLaunchContext): string[] {
+  if (profile.filesystemMode === 'full-access') return ['--sandbox', 'danger-full-access'];
+  const args = ['--sandbox', 'workspace-write', '-c', 'sandbox_workspace_write.network_access=true'];
+  for (const root of writableRootsForProfile(profile, context)) {
+    if (normalizeWritableRoot(root) === normalizeWritableRoot(context.runtimeRoot)) continue;
+    args.push('--add-dir', root);
+  }
+  return args;
+}
+
+export function writableRootsForProfile(profile: AgentPermissionProfile, context: RuntimeLaunchContext): string[] {
+  if (profile.filesystemMode === 'full-access') return ['/'];
+  const roots = [context.runtimeRoot];
+  if (context.projectRoot) roots.push(context.projectRoot);
+  if (profile.filesystemMode === 'scoped-write') roots.push(...profile.extraWritableRoots);
+  return Array.from(new Set(roots.map(normalizeWritableRoot)));
+}
+
+export function buildCocoPermissionArgs(profile: AgentPermissionProfile, context: RuntimeLaunchContext): string[] {
+  if (profile.filesystemMode === 'full-access') return ['-y'];
+  return writableRootsForProfile(profile, context).flatMap((root) => ['--add-dir', root]);
+}
+
+function pathWithinRoot(path: string, root: string): boolean {
+  const normalizedPath = normalizeWritableRoot(path);
+  const normalizedRoot = normalizeWritableRoot(root);
+  if (normalizedRoot === '/') return true;
+  if (normalizedPath === normalizedRoot) return true;
+  if (isWindowsAbsolutePath(normalizedPath) || isWindowsAbsolutePath(normalizedRoot)) {
+    if (!isWindowsAbsolutePath(normalizedPath) || !isWindowsAbsolutePath(normalizedRoot)) return false;
+    const rel = win32.relative(normalizedRoot, normalizedPath);
+    return Boolean(rel) && !rel.startsWith('..') && !win32.isAbsolute(rel);
+  }
+  const rel = relative(normalizedRoot, normalizedPath);
+  return Boolean(rel) && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+function collectAbsolutePaths(value: unknown, paths: string[] = []): string[] {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (isPortableAbsolutePath(trimmed)) paths.push(normalizeWritableRoot(trimmed));
+    return paths;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectAbsolutePaths(item, paths);
+    return paths;
+  }
+  if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) collectAbsolutePaths(item, paths);
+  }
+  return paths;
+}
+
+function permissionOptionMatches(option: Record<string, unknown>, pattern: RegExp): boolean {
+  return pattern.test(String(option.name ?? option.optionId ?? option.description ?? option.kind ?? ''));
+}
+
+export function selectAcpPermissionOption(input: {
+  params?: Record<string, unknown>;
+  profile: AgentPermissionProfile;
+  context: RuntimeLaunchContext;
+}): string {
+  const options = Array.isArray(input.params?.options) ? input.params.options as Array<Record<string, unknown>> : [];
+  const fallback = String(options[0]?.optionId ?? 'allow');
+  const allowOption = options.find((option) => permissionOptionMatches(option, /allow|approve|yes/i));
+  const denyOption = options.find((option) => permissionOptionMatches(option, /deny|reject|no/i));
+
+  if (input.profile.filesystemMode === 'full-access') {
+    return String((allowOption ?? options[0])?.optionId ?? 'allow');
+  }
+
+  const paths = Array.from(new Set(collectAbsolutePaths(input.params)));
+  const roots = writableRootsForProfile(input.profile, input.context);
+  const hasOutsidePath = paths.some((path) => !roots.some((root) => pathWithinRoot(path, root)));
+  if (hasOutsidePath && denyOption) return String(denyOption.optionId ?? denyOption.name ?? fallback);
+  return String((allowOption ?? options[0])?.optionId ?? 'allow');
+}
+
+function directoryPattern(path: string): string {
+  const withoutTrailingSlash = path.replace(/\/+$/, '');
+  return `${withoutTrailingSlash}/**`;
+}
+
+const openCodeBuiltinAgentNames = ['build', 'plan', 'general', 'explore', 'scout'];
+
+function nonInteractiveOpenCodePermissions(): Record<string, unknown> {
+  return {
+    read: { '*': 'allow' },
+    list: 'allow',
+    glob: 'allow',
+    grep: 'allow',
+    edit: 'allow',
+    bash: 'allow',
+    task: 'allow',
+    skill: 'allow',
+    lsp: 'allow',
+    todoread: 'allow',
+    todowrite: 'allow',
+    webfetch: 'allow',
+    websearch: 'allow',
+    codesearch: 'allow',
+    ask: 'deny',
+    question: 'deny',
+    doom_loop: 'deny',
+  };
+}
+
+function nonInteractiveOpenCodeTools(): Record<string, boolean> {
+  return {
+    ask: false,
+    question: false,
+  };
+}
+
+function withPalOwnedOpenCodePermissions(baseConfig: Record<string, unknown>, permission: Record<string, unknown>): Record<string, unknown> {
+  const { agent: baseAgent, permission: _basePermission, tools: _baseTools, ...rest } = baseConfig;
+  const tools = nonInteractiveOpenCodeTools();
+  const config: Record<string, unknown> = {
+    ...rest,
+    '$schema': typeof baseConfig.$schema === 'string' ? baseConfig.$schema : 'https://opencode.ai/config.json',
+    permission,
+    tools,
+  };
+
+  const agentNames = new Set(openCodeBuiltinAgentNames);
+  if (baseAgent && typeof baseAgent === 'object' && !Array.isArray(baseAgent)) {
+    for (const name of Object.keys(baseAgent as Record<string, unknown>)) agentNames.add(name);
+  }
+
+  const agent: Record<string, unknown> = {};
+  for (const name of agentNames) {
+    const rawValue = baseAgent && typeof baseAgent === 'object' && !Array.isArray(baseAgent)
+      ? (baseAgent as Record<string, unknown>)[name]
+      : undefined;
+    if (rawValue !== undefined) {
+      if (!rawValue || typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+        agent[name] = rawValue;
+        continue;
+      }
+      const { permission: _agentPermission, tools: _agentTools, ...agentRest } = rawValue as Record<string, unknown>;
+      agent[name] = { ...agentRest, permission, tools };
+    } else {
+      agent[name] = { permission, tools };
+    }
+  }
+  config.agent = agent;
+
+  return config;
+}
+
+export function buildOpenCodePermissionConfig(profile: AgentPermissionProfile, context: RuntimeLaunchContext, baseConfig: Record<string, unknown> = {}): Record<string, unknown> {
+  if (profile.filesystemMode === 'full-access') {
+    return withPalOwnedOpenCodePermissions(baseConfig, {
+      ...nonInteractiveOpenCodePermissions(),
+      external_directory: 'allow',
+    });
+  }
+
+  const writableRoots = writableRootsForProfile(profile, context);
+  const externalDirectory: Record<string, 'allow' | 'deny'> = { '*': 'deny' };
+  for (const root of writableRoots) {
+    if (normalizeWritableRoot(root) !== normalizeWritableRoot(context.runtimeRoot)) {
+      externalDirectory[directoryPattern(root)] = 'allow';
+    }
+  }
+
+  return withPalOwnedOpenCodePermissions(baseConfig, {
+    ...nonInteractiveOpenCodePermissions(),
+    external_directory: externalDirectory,
+  });
+}
+
+function readProjectOpenCodeConfig(runtimeRoot: string): Record<string, unknown> {
+  const path = join(runtimeRoot, 'opencode.json');
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeGeneratedOpenCodeConfig(input: AgentRuntimeRunInput): string {
+  const context = input.launchContext ?? buildRuntimeLaunchContext(input);
+  const profile = effectivePermissionProfile(input);
+  const baseConfig = readProjectOpenCodeConfig(context.projectRoot ?? context.runtimeRoot);
+  const config = buildOpenCodePermissionConfig(profile, context, baseConfig);
+  const dir = join(context.agentHome, 'generated');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, 'opencode-pal-permissions.json');
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return path;
+}