openbot 0.3.6 → 0.4.2

package/src/{services/storage.ts → plugins/storage/service.ts}

@@ -1,13 +1,15 @@
+import { ORCHESTRATOR_AGENT_ID, STATE_AGENT_ID } from '../../app/agent-ids.js';
 import {
   DEFAULT_PLUGINS_DIR,
   DEFAULT_AGENTS_DIR,
   DEFAULT_BASE_DIR,
   DEFAULT_CHANNELS_DIR,
+  getDefaultChannelCwd,
   loadConfig,
   resolvePath,
   StoredVariable,
   VARIABLES_FILE,
-} from '../app/config.js';
+} from '../../app/config.js';
 import fs from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -22,14 +24,18 @@ import {
   PluginDescriptor,
   Thread,
   ThreadDetails,
-} from '../bus/types.js';
-import type { PluginRef } from '../bus/plugin.js';
-import { aiSdkPlugin } from '../plugins/ai-sdk/index.js';
-import { AI_SDK_SYSTEM_PROMPT } from '../plugins/ai-sdk/system-prompt.js';
-import { listBuiltInPlugins, parsePluginModule } from '../registry/plugins.js';
-import { OpenBotEvent, OpenBotState } from '../app/types.js';
-import { processService } from '../harness/process.js';
-import { memoryService } from './memory.js';
+} from '../../services/plugins/domain.js';
+import type { PluginRef } from '../../services/plugins/types.js';
+import { openbotPlugin } from '../openbot/index.js';
+import { listBuiltInPlugins, parsePluginModule } from '../../services/plugins/registry.js';
+import { OpenBotEvent, OpenBotState } from '../../app/types.js';
+import { processService } from '../../services/process.js';
+import { memoryService } from '../memory/service.js';
+import {
+  guessMimeType,
+  resolveChannelFile,
+  statChannelFile,
+} from './files.js';
 
 const resolveBaseDir = () => {
   const config = loadConfig();
@@ -49,7 +55,10 @@ function getBundledSystemAgentImage(): string | undefined {
   if (bundledSystemAgentImageLoaded) return bundledSystemAgentImage;
   bundledSystemAgentImageLoaded = true;
   try {
-    const iconPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../assets/icon.svg');
+    const iconPath = path.join(
+      path.dirname(fileURLToPath(import.meta.url)),
+      '../../assets/icon.svg',
+    );
     const trimmed = readFileSync(iconPath, 'utf-8').trim();
     if (!trimmed.startsWith('<svg')) return undefined;
     bundledSystemAgentImage = toSvgDataUrl(trimmed);
@@ -103,27 +112,37 @@ const getConversationDir = (channelId: string, threadId?: string) => {
 };
 
 /** Built-in orchestrator agent id. Not creatable as a normal disk agent. */
-const SYSTEM_AGENT_ID = 'system';
+const SYSTEM_AGENT_ID = ORCHESTRATOR_AGENT_ID;
 
 const SYSTEM_DEFAULT_PLUGINS: PluginRef[] = [
-  { id: 'ai-sdk', config: { model: 'openai/gpt-5.4-nano' } },
-  { id: 'storage-tools' },
-  // { id: 'mcp' },
-  { id: 'shell' },
-  { id: 'todo' },
-  // { id: 'ui' },
-  { id: 'approval' },
-  { id: 'memory' },
+  {
+    id: 'openbot',
+    config: {
+      model: 'openai/gpt-5.4-mini',
+      approval: {
+        actions: ['action:bash', 'action:create_channel', 'action:delete_channel'],
+      },
+    },
+  },
 ];
 
+/** No `openbot` / `bash` — storage-side effects and infra plugins only. */
+const STATE_DEFAULT_PLUGINS: PluginRef[] = [
+  { id: 'storage' },
+  { id: 'plugin-manager' },
+];
+
+const STATE_AGENT_INSTRUCTIONS =
+  'Built-in infra agent for deterministic state reads. No conversational model is attached; handle storage, approvals, memory, and plugin marketplace events.';
+
 function getSystemAgentDetails(overrides?: Partial<AgentDetails>): AgentDetails {
   const defaults: AgentDetails = {
     id: SYSTEM_AGENT_ID,
     name: 'OpenBot',
     image: getBundledSystemAgentImage(),
     description:
-      'First-party orchestration agent for OpenBot. Coordinates other agents via handoff.',
-    instructions: AI_SDK_SYSTEM_PROMPT,
+      'First-party orchestration agent for OpenBot.',
+    instructions: '',
     plugins: SYSTEM_DEFAULT_PLUGINS.map((ref) => ref.id),
     pluginRefs: SYSTEM_DEFAULT_PLUGINS,
     createdAt: new Date(),
@@ -136,10 +155,15 @@ function getSystemAgentDetails(overrides?: Partial<AgentDetails>): AgentDetails
     ? overrides.pluginRefs
     : defaults.pluginRefs;
 
+  const diskInstructions = overrides.instructions?.trim();
+  const instructions =
+    diskInstructions && diskInstructions.length > 0 ? diskInstructions : defaults.instructions;
+
   return {
     ...defaults,
     ...overrides,
     id: SYSTEM_AGENT_ID,
+    instructions,
     image: overrides.image || defaults.image,
     plugins: refs.map((ref) => ref.id),
     pluginRefs: refs,
@@ -147,18 +171,65 @@ function getSystemAgentDetails(overrides?: Partial<AgentDetails>): AgentDetails
   };
 }
 
-// Suppress unused warning until system agent customization re-uses aiSdkPlugin metadata.
-void aiSdkPlugin;
+function getStateAgentDetails(overrides?: Partial<AgentDetails>): AgentDetails {
+  const defaults: AgentDetails = {
+    id: STATE_AGENT_ID,
+    name: 'State',
+    image: getBundledSystemAgentImage(),
+    description: 'Infrastructure agent for OpenBot — storage and hooks without an LLM.',
+    instructions: STATE_AGENT_INSTRUCTIONS,
+    plugins: STATE_DEFAULT_PLUGINS.map((ref) => ref.id),
+    pluginRefs: STATE_DEFAULT_PLUGINS,
+    hidden: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  if (!overrides) return defaults;
+
+  const refs = overrides.pluginRefs && overrides.pluginRefs.length > 0
+    ? overrides.pluginRefs
+    : defaults.pluginRefs;
+
+  const diskInstructions = overrides.instructions?.trim();
+  const instructions =
+    diskInstructions && diskInstructions.length > 0 ? diskInstructions : defaults.instructions;
 
-const RESERVED_DISK_AGENT_IDS = new Set([SYSTEM_AGENT_ID]);
+  return {
+    ...defaults,
+    ...overrides,
+    id: STATE_AGENT_ID,
+    instructions,
+    image: overrides.image || defaults.image,
+    hidden: overrides.hidden !== undefined ? overrides.hidden : defaults.hidden,
+    plugins: refs.map((ref) => ref.id),
+    pluginRefs: refs,
+    updatedAt: new Date(),
+  };
+}
 
-const assertValidDiskAgentId = (agentId: string): void => {
+const agentSummaryFromDetails = (details: AgentDetails): Agent => ({
+  id: details.id,
+  name: details.name || details.id,
+  description: details.description || '',
+  image: details.image,
+  plugins: details.plugins,
+  hidden: details.hidden,
+  createdAt: details.createdAt,
+  updatedAt: details.updatedAt,
+});
+
+// Suppress unused warning until system agent customization re-uses openbotPlugin metadata.
+void openbotPlugin;
+
+/** Built-in agents may persist optional `agents/<id>/AGENT.md` overlays; read path merges them with defaults. */
+const isBuiltinOverlayAgentId = (agentId: string): boolean =>
+  agentId === SYSTEM_AGENT_ID || agentId === STATE_AGENT_ID;
+
+const assertAgentIdFormat = (agentId: string): void => {
   if (!agentId || typeof agentId !== 'string') {
     throw new Error('agentId is required');
   }
-  if (RESERVED_DISK_AGENT_IDS.has(agentId)) {
-    throw new Error(`Agent id "${agentId}" is reserved`);
-  }
   if (!/^[a-zA-Z0-9_-]+$/.test(agentId)) {
     throw new Error('agentId must contain only letters, digits, underscores, and hyphens');
   }
@@ -169,14 +240,31 @@ const getAgentsRootDir = () => path.join(resolveBaseDir(), DEFAULT_AGENTS_DIR);
 const getLastReadFilePath = () =>
   path.join(resolvePath(resolveBaseDir() + '/' + DEFAULT_CHANNELS_DIR), '_meta', 'last-read.json');
 
+/** Sentinel key for channel-root events (no threadId). */
+export const ROOT_THREAD_KEY = '__root__';
+
+export type LastReadMap = Record<string, Record<string, string>>;
+
+const readLastReadMap = async (): Promise<LastReadMap> => {
+  const raw = await readJsonFile<Record<string, any>>(getLastReadFilePath(), {});
+  const map: LastReadMap = {};
+  for (const [channelId, value] of Object.entries(raw)) {
+    if (typeof value === 'string') {
+      // Migrate old format
+      map[channelId] = { [ROOT_THREAD_KEY]: value };
+    } else if (value && typeof value === 'object') {
+      map[channelId] = value as Record<string, string>;
+    }
+  }
+  return map;
+};
+
 const THREAD_TITLE_MAX_LENGTH = 80;
 
 const buildThreadTitleFromEvent = (event: OpenBotEvent): string | undefined => {
   let rawContent = '';
 
-  if (event.type === 'user:input' && typeof event.data?.content === 'string') {
-    rawContent = event.data.content;
-  } else if (
+  if (
     event.type === 'agent:invoke' &&
     event.data?.role === 'user' &&
     typeof event.data.content === 'string'
@@ -196,9 +284,12 @@ const buildThreadTitleFromEvent = (event: OpenBotEvent): string | undefined => {
 
 const readJsonFile = async <T>(filePath: string, fallback: T): Promise<T> => {
   try {
-    return JSON.parse(await fs.readFile(filePath, 'utf-8')) as T;
+    const content = (await fs.readFile(filePath, 'utf-8')).trim();
+    if (!content) return fallback;
+    return JSON.parse(content) as T;
   } catch (e: unknown) {
     if ((e as { code?: string })?.code === 'ENOENT') return fallback;
+    if (e instanceof SyntaxError) return fallback;
     throw e;
   }
 };
@@ -339,6 +430,12 @@ const readChannelStateFileFields = (
  * Parse the `plugins:` array from AGENT.md frontmatter. Each entry must have an
  * `id`; `config` is optional. Strings are accepted as a shorthand for `{ id }`.
  */
+const parseHiddenFlag = (raw: unknown): boolean | undefined => {
+  if (raw === true) return true;
+  if (raw === false) return false;
+  return undefined;
+};
+
 const parsePluginRefs = (raw: unknown): PluginRef[] => {
   if (!Array.isArray(raw)) return [];
   const refs: PluginRef[] = [];
@@ -359,22 +456,27 @@ const serializePluginRefs = (refs: PluginRef[]): unknown[] =>
   refs.map((ref) => (ref.config ? { id: ref.id, config: ref.config } : { id: ref.id }));
 
 export const storageService = {
-  getLastReadByChannel: async (): Promise<Record<string, string>> => {
-    return readJsonFile(getLastReadFilePath(), {});
+  getLastReadMap: async (): Promise<LastReadMap> => {
+    return readLastReadMap();
   },
 
-  setLastReadForChannel: async ({
+  setLastRead: async ({
     channelId,
+    threadId,
     lastReadEventId,
   }: {
     channelId: string;
+    threadId?: string;
     lastReadEventId: string;
   }): Promise<void> => {
     const p = getLastReadFilePath();
     await fs.mkdir(path.dirname(p), { recursive: true });
-    const map = await readJsonFile<Record<string, string>>(p, {});
-    map[channelId] = lastReadEventId;
-    await fs.writeFile(p, JSON.stringify(map, null, 2), 'utf-8');
+    const map = await readLastReadMap();
+    if (!map[channelId]) map[channelId] = {};
+    map[channelId][threadId || ROOT_THREAD_KEY] = lastReadEventId;
+    const tmp = `${p}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(map, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
   },
 
   getChannels: async (): Promise<Channel[]> => {
@@ -388,11 +490,12 @@ export const storageService = {
     const channelNames = (await fs.readdir(channelsDir)).filter(
       (name) => !name.startsWith('.') && name !== '_meta',
     );
-    const lastReadByChannel = await storageService.getLastReadByChannel();
+    const lastReadMap = await storageService.getLastReadMap();
 
     const channels = await Promise.all(
       channelNames.map(async (name) => {
         const channelDir = getConversationDir(name);
+        const stats = await fs.stat(channelDir);
         const statePath = path.join(channelDir, 'state.json');
         let cwd: string | undefined;
         let displayName = name;
@@ -415,24 +518,28 @@ export const storageService = {
           description: '',
           cwd,
           participants,
-          createdAt: new Date(),
-          updatedAt: new Date(),
+          createdAt: stats.birthtime,
+          updatedAt: stats.mtime,
         };
-        const rid = lastReadByChannel[name];
-        try {
-          const events = await storageService.getEvents({ channelId: name });
-          const latestId = events[events.length - 1]?.id;
-          channel.hasUnseenMessages = !!(latestId && latestId !== rid);
-        } catch {
-          channel.hasUnseenMessages = false;
-        }
 
+        const channelLastRead = lastReadMap[name] || {};
+        
         try {
+          // Check root unread
+          const rootEvents = await storageService.getEvents({ channelId: name });
+          const rootLatestId = rootEvents[rootEvents.length - 1]?.id;
+          const rootUnseen = !!(rootLatestId && rootLatestId !== channelLastRead[ROOT_THREAD_KEY]);
+
+          // Check threads unread
           const allThreads = await storageService.getThreads({ channelId: name });
           channel.recentThreads = allThreads
             .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime())
             .slice(0, 5);
+          
+          const threadsUnseen = allThreads.some(t => t.hasUnseenMessages);
+          channel.hasUnseenMessages = rootUnseen || threadsUnseen;
         } catch {
+          channel.hasUnseenMessages = false;
           channel.recentThreads = [];
         }
 
@@ -440,7 +547,7 @@ export const storageService = {
       }),
     );
 
-    return channels;
+    return channels.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
   },
   createChannel: async ({
     channelId,
@@ -472,22 +579,63 @@ export const storageService = {
       }
     }
 
-    const finalState = {
+    const finalState: Record<string, unknown> = {
       ...(initialState || {}),
     };
 
-    if (cwd) {
-      (finalState as Record<string, unknown>).cwd = cwd;
-    }
+    const rawCwd =
+      (typeof cwd === 'string' && cwd.trim()) ||
+      (typeof finalState.cwd === 'string' && finalState.cwd.trim()) ||
+      getDefaultChannelCwd(normalizedChannelId);
 
+    const resolvedCwd = resolvePath(rawCwd);
+    finalState.cwd = resolvedCwd;
+    await fs.mkdir(resolvedCwd, { recursive: true });
     await fs.mkdir(channelDir, { recursive: true });
     await fs.writeFile(
       specPath,
       spec?.trim() ||
-      `# ${normalizedChannelId}\n\nDefine the goals and rules for this channel here.\n`,
+      `# ${normalizedChannelId}\n\n`,
     );
     await fs.writeFile(statePath, JSON.stringify(finalState, null, 2));
   },
+  deleteChannel: async ({ channelId }: { channelId: string }): Promise<void> => {
+    const normalizedChannelId = channelId.trim();
+    if (!normalizedChannelId) {
+      throw new Error('channelId is required');
+    }
+    if (normalizedChannelId === '_meta') {
+      throw new Error('Cannot delete reserved channel path');
+    }
+
+    const channelDir = getConversationDir(normalizedChannelId);
+    try {
+      await fs.access(channelDir);
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+        const err = new Error(`Channel "${normalizedChannelId}" does not exist.`);
+        (err as Error & { code?: string }).code = 'CHANNEL_NOT_FOUND';
+        throw err;
+      }
+      throw error;
+    }
+
+    await fs.rm(channelDir, { recursive: true, force: true });
+
+    try {
+      const lastReadPath = getLastReadFilePath();
+      const map = await readJsonFile<Record<string, string>>(lastReadPath, {});
+      if (normalizedChannelId in map) {
+        delete map[normalizedChannelId];
+        await fs.mkdir(path.dirname(lastReadPath), { recursive: true });
+        const tmp = `${lastReadPath}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(map, null, 2), 'utf-8');
+        await fs.rename(tmp, lastReadPath);
+      }
+    } catch {
+      // ignore last-read cleanup failures
+    }
+  },
   createThread: async ({
     channelId,
     threadId,
@@ -522,7 +670,7 @@ export const storageService = {
 
     const baseState: Record<string, unknown> = { ...(initialState || {}) };
     if (threadTitle?.trim()) {
-      baseState.generatedName = threadTitle.trim();
+      baseState.name = threadTitle.trim();
     }
 
     await fs.mkdir(threadDir, { recursive: true });
@@ -538,6 +686,8 @@ export const storageService = {
       return [];
     }
 
+    const lastReadMap = await storageService.getLastReadMap();
+    const channelLastRead = lastReadMap[channelId] || {};
     const threadNames = (await fs.readdir(threadsDir)).filter((name) => !name.startsWith('.'));
 
     const threads = await Promise.all(
@@ -550,10 +700,10 @@ export const storageService = {
         try {
           const threadStateRaw = await fs.readFile(threadStatePath, 'utf-8');
           const threadState = JSON.parse(threadStateRaw) as Record<string, unknown>;
-          const generatedName =
-            typeof threadState.generatedName === 'string' ? threadState.generatedName.trim() : '';
-          if (generatedName) {
-            threadDisplayName = generatedName;
+          const threadName =
+            typeof threadState.name === 'string' ? threadState.name.trim() : '';
+          if (threadName) {
+            threadDisplayName = threadName;
           }
         } catch (error: unknown) {
           if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
@@ -564,12 +714,22 @@ export const storageService = {
           }
         }
 
+        let hasUnseen = false;
+        try {
+          const events = await storageService.getEvents({ channelId, threadId: name });
+          const latestId = events[events.length - 1]?.id;
+          hasUnseen = !!(latestId && latestId !== channelLastRead[name]);
+        } catch {
+          // ignore
+        }
+
         return {
           id: name,
           name: threadDisplayName,
           channelId,
           createdAt: stats.birthtime,
           updatedAt: stats.mtime,
+          hasUnseenMessages: hasUnseen,
         };
       }),
     );
@@ -599,14 +759,14 @@ export const storageService = {
       }
     }
 
-    const generatedName =
-      isRecord(state) && typeof state.generatedName === 'string'
-        ? state.generatedName.trim()
+    const threadName =
+      isRecord(state) && typeof state.name === 'string'
+        ? state.name.trim()
         : '';
 
     return {
       id: threadId,
-      name: generatedName || threadId,
+      name: threadName || threadId,
       channelId,
       state,
     };
@@ -741,15 +901,7 @@ export const storageService = {
       agentIds.map(async (id) => {
         try {
           const details = await storageService.getAgentDetails({ agentId: id });
-          return {
-            id,
-            name: details.name || id,
-            description: details.description || '',
-            image: details.image,
-            plugins: details.plugins,
-            createdAt: details.createdAt,
-            updatedAt: details.updatedAt,
-          } satisfies Agent;
+          return agentSummaryFromDetails(details);
         } catch {
           return {
             id,
@@ -764,23 +916,19 @@ export const storageService = {
     );
 
     const system = await storageService.getAgentDetails({ agentId: SYSTEM_AGENT_ID });
-    const builtInSystemAgent: Agent = {
-      id: system.id,
-      name: system.name,
-      description: system.description || '',
-      image: system.image,
-      plugins: system.plugins,
-      createdAt: system.createdAt,
-      updatedAt: system.updatedAt,
-    };
+    const builtInSystemAgent = agentSummaryFromDetails(system);
+
+    const builtInStateRow = await storageService.getAgentDetails({ agentId: STATE_AGENT_ID });
+    const builtInStateAgent = agentSummaryFromDetails(builtInStateRow);
 
     const deduped = new Map<string, Agent>();
     deduped.set(builtInSystemAgent.id, builtInSystemAgent);
+    deduped.set(builtInStateAgent.id, builtInStateAgent);
     for (const agent of agents) {
       if (!deduped.has(agent.id)) deduped.set(agent.id, agent);
     }
 
-    return Array.from(deduped.values());
+    return Array.from(deduped.values()).filter((agent) => !agent.hidden);
   },
   getPlugins: async (): Promise<PluginDescriptor[]> => {
     const [builtIn, fromDisk] = await Promise.all([
@@ -824,16 +972,17 @@ export const storageService = {
         pluginRefs,
         description: typeof data.description === 'string' ? data.description : '',
         image: frontmatterImage || discoveredImage || undefined,
+        hidden: parseHiddenFlag(data.hidden),
         createdAt: stats.birthtime,
         updatedAt: stats.mtime,
       };
     } catch (error) {
-      if (agentId !== SYSTEM_AGENT_ID) {
+      if (agentId !== SYSTEM_AGENT_ID && agentId !== STATE_AGENT_ID) {
         const err = new Error(`Agent "${agentId}" does not exist.`);
         (err as Error & { code?: string }).code = 'AGENT_NOT_FOUND';
         throw err;
       }
-      // swallow: system agent has on-disk overrides optional
+      // swallow: built-in agents have optional `agents/<id>/AGENT.md` overrides
       void error;
     }
 
@@ -841,6 +990,10 @@ export const storageService = {
       return getSystemAgentDetails(diskDetails);
     }
 
+    if (agentId === STATE_AGENT_ID) {
+      return getStateAgentDetails(diskDetails);
+    }
+
     if (!diskDetails) {
       const error = new Error(`Agent "${agentId}" does not exist.`);
       (error as Error & { code?: string }).code = 'AGENT_NOT_FOUND';
@@ -854,6 +1007,7 @@ export const storageService = {
     name,
     description = '',
     image,
+    hidden,
     instructions,
     plugins,
   }: {
@@ -861,10 +1015,11 @@ export const storageService = {
     name: string;
     description?: string;
     image?: string;
+    hidden?: boolean;
     instructions: string;
     plugins: PluginRef[];
   }): Promise<void> => {
-    assertValidDiskAgentId(agentId);
+    assertAgentIdFormat(agentId);
     const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
     const agentMdPath = path.join(agentDir, 'AGENT.md');
 
@@ -892,6 +1047,9 @@ export const storageService = {
     if (typeof image === 'string' && image.trim() !== '') {
       data.image = image.trim();
     }
+    if (hidden === true) {
+      data.hidden = true;
+    }
 
     const body = matter.stringify(`${instructions.trim()}\n`, data);
     await fs.writeFile(agentMdPath, body, 'utf-8');
@@ -901,6 +1059,7 @@ export const storageService = {
     name,
     description,
     image,
+    hidden,
     instructions,
     plugins,
   }: {
@@ -908,10 +1067,11 @@ export const storageService = {
     name?: string;
     description?: string;
     image?: string;
+    hidden?: boolean;
     instructions?: string;
     plugins?: PluginRef[];
   }): Promise<void> => {
-    assertValidDiskAgentId(agentId);
+    assertAgentIdFormat(agentId);
     const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
     const agentMdPath = path.join(agentDir, 'AGENT.md');
 
@@ -920,14 +1080,18 @@ export const storageService = {
       raw = await fs.readFile(agentMdPath, 'utf-8');
     } catch (error: unknown) {
       if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
-        const err = new Error(`Agent "${agentId}" does not exist.`);
-        (err as Error & { code?: string }).code = 'AGENT_NOT_FOUND';
-        throw err;
+        if (!isBuiltinOverlayAgentId(agentId)) {
+          const err = new Error(`Agent "${agentId}" does not exist.`);
+          (err as Error & { code?: string }).code = 'AGENT_NOT_FOUND';
+          throw err;
+        }
+        raw = '';
+      } else {
+        throw error;
       }
-      throw error;
     }
 
-    const parsed = matter(raw);
+    const parsed = raw === '' ? { data: {}, content: '' } : matter(raw);
     const nextData: Record<string, unknown> = { ...parsed.data };
     if (name !== undefined) nextData.name = name;
     if (description !== undefined) nextData.description = description;
@@ -939,17 +1103,84 @@ export const storageService = {
         delete nextData.image;
       }
     }
+    if (hidden !== undefined) {
+      if (hidden) {
+        nextData.hidden = true;
+      } else {
+        delete nextData.hidden;
+      }
+    }
+
+    let nextContent = instructions !== undefined ? instructions : parsed.content;
+
+    // Built-in agents merge disk overlays with code defaults on read; on write, partial
+    // updates (e.g. plugins-only) must still persist a complete AGENT.md.
+    if (isBuiltinOverlayAgentId(agentId)) {
+      const pluginRefs =
+        plugins ??
+        (nextData.plugins !== undefined ? parsePluginRefs(nextData.plugins) : undefined);
+      const diskOverrides: Partial<AgentDetails> = {};
+      if (typeof nextData.name === 'string' && nextData.name.trim() !== '') {
+        diskOverrides.name = nextData.name;
+      }
+      if (typeof nextData.description === 'string') {
+        diskOverrides.description = nextData.description;
+      }
+      const trimmedContent = String(nextContent).trim();
+      if (trimmedContent) {
+        diskOverrides.instructions = trimmedContent;
+      }
+      if (pluginRefs && pluginRefs.length > 0) {
+        diskOverrides.pluginRefs = pluginRefs;
+      }
+
+      const effective =
+        agentId === SYSTEM_AGENT_ID
+          ? getSystemAgentDetails(diskOverrides)
+          : getStateAgentDetails(diskOverrides);
+
+      if (name === undefined) nextData.name = effective.name;
+      if (description === undefined) nextData.description = effective.description;
+      if (instructions === undefined && !String(nextContent).trim()) {
+        nextContent = effective.instructions;
+      }
+    }
 
-    const nextContent = instructions !== undefined ? instructions : parsed.content;
     const body = matter.stringify(`${String(nextContent).trim()}\n`, nextData);
+    await fs.mkdir(path.dirname(agentMdPath), { recursive: true });
     await fs.writeFile(agentMdPath, body, 'utf-8');
   },
   deleteAgent: async ({ agentId }: { agentId: string }): Promise<void> => {
-    assertValidDiskAgentId(agentId);
+    assertAgentIdFormat(agentId);
     const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
     const agentMdPath = path.join(agentDir, 'AGENT.md');
     const packageJsonPath = path.join(agentDir, 'package.json');
 
+    if (isBuiltinOverlayAgentId(agentId)) {
+      try {
+        await fs.access(agentMdPath);
+      } catch (error: unknown) {
+        if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+          const err = new Error(
+            `Agent "${agentId}" has no AGENT.md on disk; nothing to remove (defaults already apply).`,
+          );
+          (err as Error & { code?: string }).code = 'AGENT_NOT_FOUND';
+          throw err;
+        }
+        throw error;
+      }
+      await fs.unlink(agentMdPath);
+      try {
+        const remaining = await fs.readdir(agentDir);
+        if (remaining.length === 0) {
+          await fs.rmdir(agentDir);
+        }
+      } catch {
+        // ignore cleanup failures
+      }
+      return;
+    }
+
     try {
       await fs.access(agentDir);
     } catch (error: unknown) {
@@ -1060,8 +1291,10 @@ export const storageService = {
     try {
       const threadDir = getConversationDir(channelId, threadId);
       if (threadId) {
+        let exists = false;
         try {
           await fs.access(threadDir);
+          exists = true;
         } catch (error: unknown) {
           if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
             const threadTitle = buildThreadTitleFromEvent(event);
@@ -1074,6 +1307,23 @@ export const storageService = {
             throw error;
           }
         }
+
+        if (exists) {
+          // If the thread already exists, check if it has a name.
+          // This handles threads created via action:create_thread without a title.
+          const threadDetails = await storageService.getThreadDetails({ channelId, threadId });
+          const currentState = (threadDetails.state as Record<string, unknown>) || {};
+          if (!currentState.name) {
+            const threadTitle = buildThreadTitleFromEvent(event);
+            if (threadTitle) {
+              await storageService.patchThreadState({
+                channelId,
+                threadId,
+                state: { name: threadTitle },
+              });
+            }
+          }
+        }
       } else {
         await fs.mkdir(threadDir, { recursive: true });
       }
@@ -1200,12 +1450,9 @@ export const storageService = {
       throw new Error('Channel has no CWD configured');
     }
 
-    const resolvedBase = path.resolve(baseCwd);
-    const targetDir = path.resolve(resolvedBase, subPath);
-
-    if (!targetDir.startsWith(resolvedBase)) {
-      throw new Error('Access denied: directory escape');
-    }
+    const targetDir = subPath
+      ? resolveChannelFile(baseCwd, subPath)
+      : resolvePath(baseCwd);
 
     const entries = await fs.readdir(targetDir, { withFileTypes: true });
     return entries
@@ -1230,14 +1477,142 @@ export const storageService = {
       throw new Error('Channel has no CWD configured');
     }
 
-    const resolvedBase = path.resolve(baseCwd);
-    const targetFile = path.resolve(resolvedBase, filePath);
+    const targetFile = resolveChannelFile(baseCwd, filePath);
+    return fs.readFile(targetFile, 'utf-8');
+  },
 
-    if (!targetFile.startsWith(resolvedBase)) {
-      throw new Error('Access denied: directory escape');
+  readChannelFile: async ({
+    channelId,
+    path: filePath,
+    encoding = 'utf8',
+  }: {
+    channelId: string;
+    path: string;
+    encoding?: 'utf8' | 'base64';
+  }): Promise<{ content: string; mimeType: string; size: number }> => {
+    const details = await storageService.getChannelDetails({ channelId });
+    const baseCwd = details.cwd;
+
+    if (!baseCwd) {
+      throw new Error('Channel has no CWD configured');
     }
 
-    return fs.readFile(targetFile, 'utf-8');
+    const targetFile = resolveChannelFile(baseCwd, filePath);
+    const buf = await fs.readFile(targetFile);
+    const content =
+      encoding === 'base64' ? buf.toString('base64') : buf.toString('utf-8');
+
+    return {
+      content,
+      mimeType: guessMimeType(targetFile),
+      size: buf.length,
+    };
+  },
+
+  writeChannelFile: async ({
+    channelId,
+    path: filePath,
+    content,
+    encoding = 'utf8',
+    overwrite = false,
+  }: {
+    channelId: string;
+    path: string;
+    content: string;
+    encoding?: 'utf8' | 'base64';
+    overwrite?: boolean;
+  }): Promise<{ path: string; size: number; mimeType: string }> => {
+    const details = await storageService.getChannelDetails({ channelId });
+    const baseCwd = details.cwd;
+
+    if (!baseCwd) {
+      throw new Error('Channel has no CWD configured');
+    }
+
+    const abs = resolveChannelFile(baseCwd, filePath);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+
+    if (!overwrite) {
+      try {
+        await fs.access(abs);
+        throw new Error('File already exists');
+      } catch (error: unknown) {
+        const code = (error as NodeJS.ErrnoException)?.code;
+        if (code !== 'ENOENT') {
+          throw error;
+        }
+      }
+    }
+
+    const buf =
+      encoding === 'base64' ? Buffer.from(content, 'base64') : Buffer.from(content, 'utf8');
+    await fs.writeFile(abs, buf);
+
+    return {
+      path: filePath,
+      size: buf.length,
+      mimeType: guessMimeType(abs),
+    };
+  },
+
+  uploadChannelFile: async ({
+    channelId,
+    path: filePath,
+    body,
+    overwrite = false,
+  }: {
+    channelId: string;
+    path: string;
+    body: Buffer;
+    overwrite?: boolean;
+  }): Promise<{ path: string; size: number; mimeType: string }> => {
+    const details = await storageService.getChannelDetails({ channelId });
+    const baseCwd = details.cwd;
+
+    if (!baseCwd) {
+      throw new Error('Channel has no CWD configured');
+    }
+
+    const abs = resolveChannelFile(baseCwd, filePath);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+
+    if (!overwrite) {
+      try {
+        await fs.access(abs);
+        throw new Error('File already exists');
+      } catch (error: unknown) {
+        const code = (error as NodeJS.ErrnoException)?.code;
+        if (code !== 'ENOENT') {
+          throw error;
+        }
+      }
+    }
+
+    await fs.writeFile(abs, body);
+
+    return {
+      path: filePath,
+      size: body.length,
+      mimeType: guessMimeType(abs),
+    };
+  },
+
+  getChannelFileStat: async ({
+    channelId,
+    path: filePath,
+  }: {
+    channelId: string;
+    path: string;
+  }): Promise<{ abs: string; size: number; mimeType: string }> => {
+    const details = await storageService.getChannelDetails({ channelId });
+    const baseCwd = details.cwd;
+
+    if (!baseCwd) {
+      throw new Error('Channel has no CWD configured');
+    }
+
+    const { abs, size } = await statChannelFile(baseCwd, filePath);
+    return { abs, size, mimeType: guessMimeType(abs) };
   },
 
   appendMemory: memoryService.appendMemory,
@@ -1286,12 +1661,17 @@ export const storageService = {
       }
     }
 
+    const threadState = (threadDetails?.state as Record<string, unknown>) || {};
+
     return {
       runId,
       agentId,
       channelId,
       threadId,
       triggerEvent: event,
+      pendingToolCallIds: Array.isArray(threadState.pendingToolCallIds)
+        ? (threadState.pendingToolCallIds as string[])
+        : undefined,
       agentDetails: {
         id: agentDetails.id,
         name: agentDetails.name,