openbot 0.2.14 → 0.3.1

package/src/services/storage.ts

@@ -1,8 +1,8 @@
 import {
+  DEFAULT_PLUGINS_DIR,
   DEFAULT_AGENTS_DIR,
   DEFAULT_BASE_DIR,
   DEFAULT_CHANNELS_DIR,
-  DEFAULT_PLUGINS_DIR,
   loadConfig,
   resolvePath,
   StoredVariable,
@@ -17,30 +17,19 @@ import {
   AgentDetails,
   Channel,
   ChannelDetails,
-  Plugin,
-  PluginKind,
+  PluginDescriptor,
   Thread,
   ThreadDetails,
-} from '../plugins/storage.js';
-import { getSystemAgentDetails } from '../agents/system.js';
+} 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';
 import { pathToFileURL } from 'node:url';
 
-const mapNameToPlugin = (
-  name: string,
-  description: string,
-  kind: PluginKind = 'tool',
-  image?: string,
-): Plugin => ({
-  id: name,
-  name,
-  description,
-  kind,
-  image,
-  createdAt: new Date(),
-  updatedAt: new Date(),
-});
-
 const resolveBaseDir = () => {
   const config = loadConfig();
   return resolvePath(config.baseDir || DEFAULT_BASE_DIR);
@@ -62,15 +51,6 @@ const tryReadSvgDataUrl = async (filePath: string): Promise<string | null> => {
   }
 };
 
-/**
- * Auto-discovers an entity SVG avatar and returns it as a data URL.
- *
- * Search order:
- * 1) <entity>/assets/avatar.svg|icon.svg|image.svg|logo.svg
- * 2) <entity>/avatar.svg|icon.svg|image.svg|logo.svg
- * 3) first *.svg in <entity>/assets
- * 4) first *.svg in <entity>
- */
 const resolveEntityImageDataUrl = async (entityDir: string): Promise<string | undefined> => {
   const preferredDirs = [path.join(entityDir, 'assets'), entityDir];
 
@@ -91,7 +71,7 @@ const resolveEntityImageDataUrl = async (entityDir: string): Promise<string | un
       const dataUrl = await tryReadSvgDataUrl(path.join(dir, firstSvg.name));
       if (dataUrl) return dataUrl;
     } catch {
-      // ignore missing/unreadable folders
+      // ignore
     }
   }
 
@@ -103,6 +83,70 @@ const getConversationDir = (channelId: string, threadId?: string) => {
   return threadId ? `${base}/threads/${threadId}` : base;
 };
 
+/** Built-in orchestrator agent id. Not creatable as a normal disk agent. */
+const SYSTEM_AGENT_ID = 'system';
+
+const SYSTEM_DEFAULT_PLUGINS: PluginRef[] = [
+  { id: 'ai-sdk', config: { model: 'openai/gpt-5.4-nano' } },
+  { id: 'storage-tools' },
+  // { id: 'mcp' },
+  { id: 'shell' },
+  { id: 'delegation' },
+  // { id: 'ui' },
+  { id: 'approval' },
+  { id: 'memory' },
+];
+
+function getSystemAgentDetails(overrides?: Partial<AgentDetails>): AgentDetails {
+  const defaults: AgentDetails = {
+    id: SYSTEM_AGENT_ID,
+    name: 'OpenBot',
+    image: undefined,
+    description:
+      'First-party orchestration agent for OpenBot. Coordinates other agents via handoff and delegation.',
+    instructions: AI_SDK_SYSTEM_PROMPT,
+    plugins: SYSTEM_DEFAULT_PLUGINS.map((ref) => ref.id),
+    pluginRefs: SYSTEM_DEFAULT_PLUGINS,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  if (!overrides) return defaults;
+
+  const refs = overrides.pluginRefs && overrides.pluginRefs.length > 0
+    ? overrides.pluginRefs
+    : defaults.pluginRefs;
+
+  return {
+    ...defaults,
+    ...overrides,
+    id: SYSTEM_AGENT_ID,
+    image: overrides.image || defaults.image,
+    plugins: refs.map((ref) => ref.id),
+    pluginRefs: refs,
+    updatedAt: new Date(),
+  };
+}
+
+// Suppress unused warning until system agent customization re-uses aiSdkPlugin metadata.
+void aiSdkPlugin;
+
+const RESERVED_DISK_AGENT_IDS = new Set([SYSTEM_AGENT_ID]);
+
+const assertValidDiskAgentId = (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');
+  }
+};
+
+const getAgentsRootDir = () => path.join(resolveBaseDir(), DEFAULT_AGENTS_DIR);
+
 const getLastReadFilePath = () =>
   path.join(resolvePath(resolveBaseDir() + '/' + DEFAULT_CHANNELS_DIR), '_meta', 'last-read.json');
 
@@ -145,7 +189,6 @@ const toVariablesRecord = (raw: unknown): Record<string, string> => {
     return {};
   }
 
-  // Current format: { version: number, variables: StoredVariable[] }
   if ('variables' in raw && Array.isArray((raw as { variables?: unknown }).variables)) {
     const entries = (raw as { variables: StoredVariable[] }).variables
       .filter((variable) => typeof variable?.key === 'string')
@@ -153,7 +196,6 @@ const toVariablesRecord = (raw: unknown): Record<string, string> => {
     return Object.fromEntries(entries);
   }
 
-  // Legacy format: { [key: string]: string }
   return Object.fromEntries(
     Object.entries(raw as Record<string, unknown>).map(([key, value]) => [
       key,
@@ -162,15 +204,59 @@ const toVariablesRecord = (raw: unknown): Record<string, string> => {
   );
 };
 
-const listBuiltInPlugins = async (): Promise<Plugin[]> => {
-  return [
-    mapNameToPlugin('storage', 'Built-in storage plugin'),
-    mapNameToPlugin('ai-sdk', 'Built-in AI SDK plugin', 'runtime'),
-    mapNameToPlugin('delegation', 'Built-in delegation plugin'),
-  ];
+const listBuiltInPluginDescriptors = async (): Promise<PluginDescriptor[]> => {
+  return listBuiltInPlugins().map((plugin) => ({
+    id: plugin.id,
+    name: plugin.name,
+    description: plugin.description,
+    builtIn: true,
+    image: plugin.image,
+    defaultInstructions: plugin.defaultInstructions,
+    configSchema: plugin.configSchema,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }));
 };
 
-const listPluginsFromDisk = async (): Promise<Plugin[]> => {
+/**
+ * Walk `plugins/` and yield candidate plugin ids (npm names). Includes scoped
+ * packages by recursing one level into directories starting with `@`.
+ */
+const listInstalledPluginIds = async (pluginsDir: string): Promise<string[]> => {
+  const out: string[] = [];
+  let topEntries;
+  try {
+    topEntries = await fs.readdir(pluginsDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of topEntries) {
+    if (entry.name.startsWith('.')) continue;
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+    if (entry.name.startsWith('@')) {
+      try {
+        const inner = await fs.readdir(path.join(pluginsDir, entry.name), { withFileTypes: true });
+        for (const sub of inner) {
+          if (sub.name.startsWith('.')) continue;
+          if (sub.isDirectory() || sub.isSymbolicLink()) {
+            out.push(`${entry.name}/${sub.name}`);
+          }
+        }
+      } catch {
+        // ignore
+      }
+      continue;
+    }
+
+    out.push(entry.name);
+  }
+
+  return out;
+};
+
+const listPluginsFromDisk = async (): Promise<PluginDescriptor[]> => {
   const pluginsDir = resolvePath(resolveBaseDir() + '/' + DEFAULT_PLUGINS_DIR);
   try {
     await fs.access(pluginsDir);
@@ -178,26 +264,64 @@ const listPluginsFromDisk = async (): Promise<Plugin[]> => {
     await fs.mkdir(pluginsDir, { recursive: true });
   }
 
-  const plugins = (await fs.readdir(pluginsDir, { withFileTypes: true }))
-    .filter(
-      (entry) => !entry.name.startsWith('.') && (entry.isDirectory() || entry.isSymbolicLink()),
-    )
-    .map(async (entry) => {
-      // get dist/index module and find inside module.plugin.description
-      const module = await import(pathToFileURL(`${pluginsDir}/${entry.name}/dist/index.js`).href);
-      const pluginDir = path.join(pluginsDir, entry.name);
-      const image = await resolveEntityImageDataUrl(pluginDir);
-      return mapNameToPlugin(
-        module.plugin.name || entry.name,
-        module.plugin.description || '',
-        module.plugin.kind || 'tool',
-        image,
-      );
-    });
+  const ids = await listInstalledPluginIds(pluginsDir);
+
+  const descriptors = await Promise.all(
+    ids.map(async (id): Promise<PluginDescriptor | null> => {
+      try {
+        const pluginDir = path.join(pluginsDir, id);
+        const distPath = path.join(pluginDir, 'dist', 'index.js');
+        const module = await import(pathToFileURL(distPath).href);
+        const parsed = parsePluginModule(module as Record<string, unknown>);
+        if (!parsed) return null;
+        const image = await resolveEntityImageDataUrl(pluginDir);
+        return {
+          id,
+          name: parsed.name || id,
+          description: parsed.description || '',
+          builtIn: false,
+          image: parsed.image || image,
+          defaultInstructions: parsed.defaultInstructions,
+          configSchema: parsed.configSchema,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        };
+      } catch (error) {
+        console.warn(`[storage] Failed to load plugin ${id}:`, error);
+        return null;
+      }
+    }),
+  );
+
+  return descriptors.filter((d): d is PluginDescriptor => d !== null);
+};
 
-  return Promise.all(plugins);
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * 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 parsePluginRefs = (raw: unknown): PluginRef[] => {
+  if (!Array.isArray(raw)) return [];
+  const refs: PluginRef[] = [];
+  for (const entry of raw) {
+    if (typeof entry === 'string' && entry.trim()) {
+      refs.push({ id: entry.trim() });
+      continue;
+    }
+    if (isRecord(entry) && typeof entry.id === 'string' && entry.id.trim()) {
+      const config = isRecord(entry.config) ? (entry.config as Record<string, unknown>) : undefined;
+      refs.push({ id: entry.id.trim(), ...(config ? { config } : {}) });
+    }
+  }
+  return refs;
 };
 
+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(), {});
@@ -241,7 +365,7 @@ export const storageService = {
           const state = JSON.parse(stateContent);
           cwd = typeof state.cwd === 'string' ? state.cwd : undefined;
         } catch {
-          // Ignore if state.json is missing or invalid
+          // ignore
         }
 
         const channel: Channel = {
@@ -262,7 +386,6 @@ export const storageService = {
         }
 
         try {
-          // Fetch up to 5 most recent threads for the sidebar
           const allThreads = await storageService.getThreads({ channelId: name });
           channel.recentThreads = allThreads
             .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime())
@@ -300,8 +423,9 @@ export const storageService = {
     try {
       await fs.access(channelDir);
       throw new Error(`Channel "${normalizedChannelId}" already exists`);
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      if (code !== 'ENOENT') {
         throw error;
       }
     }
@@ -311,7 +435,7 @@ export const storageService = {
     };
 
     if (cwd) {
-      finalState.cwd = cwd;
+      (finalState as Record<string, unknown>).cwd = cwd;
     }
 
     await fs.mkdir(channelDir, { recursive: true });
@@ -338,12 +462,8 @@ export const storageService = {
     const normalizedChannelId = channelId.trim();
     const normalizedThreadId = threadId.trim();
 
-    if (!normalizedChannelId) {
-      throw new Error('channelId is required');
-    }
-    if (!normalizedThreadId) {
-      throw new Error('threadId is required');
-    }
+    if (!normalizedChannelId) throw new Error('channelId is required');
+    if (!normalizedThreadId) throw new Error('threadId is required');
 
     const threadDir = getConversationDir(normalizedChannelId, normalizedThreadId);
     const specPath = `${threadDir}/SPEC.md`;
@@ -354,13 +474,14 @@ export const storageService = {
       throw new Error(
         `Thread "${normalizedThreadId}" already exists in channel "${normalizedChannelId}"`,
       );
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      if (code !== 'ENOENT') {
         throw error;
       }
     }
 
-    const baseState = { ...(initialState || {}) };
+    const baseState: Record<string, unknown> = { ...(initialState || {}) };
     if (threadTitle?.trim()) {
       baseState.generatedName = threadTitle.trim();
     }
@@ -400,8 +521,8 @@ export const storageService = {
           if (generatedName) {
             threadDisplayName = generatedName;
           }
-        } catch (error: any) {
-          if (error.code !== 'ENOENT') {
+        } catch (error: unknown) {
+          if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
             console.error(
               `Failed to read thread state for channel ${channelId} thread ${name}`,
               error,
@@ -435,8 +556,8 @@ export const storageService = {
     let spec = '';
     try {
       spec = await fs.readFile(specPath, 'utf-8');
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
         console.error(
           `Failed to read thread spec for channel ${channelId} thread ${threadId}`,
           error,
@@ -444,12 +565,12 @@ export const storageService = {
       }
     }
 
-    let state = {};
+    let state: unknown = {};
     try {
       const stateContent = await fs.readFile(statePath, 'utf-8');
       state = JSON.parse(stateContent);
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
         console.error(
           `Failed to read thread state for channel ${channelId} thread ${threadId}`,
           error,
@@ -458,8 +579,8 @@ export const storageService = {
     }
 
     const generatedName =
-      typeof (state as Record<string, unknown>).generatedName === 'string'
-        ? ((state as Record<string, unknown>).generatedName as string).trim()
+      isRecord(state) && typeof state.generatedName === 'string'
+        ? state.generatedName.trim()
         : '';
 
     return {
@@ -478,28 +599,30 @@ export const storageService = {
     let spec = '';
     try {
       spec = await fs.readFile(specPath, 'utf-8');
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
         console.error(`Failed to read spec file for channel ${channelId}`, error);
       }
     }
 
-    let state = {};
+    let state: unknown = {};
     try {
       const stateContent = await fs.readFile(statePath, 'utf-8');
       state = JSON.parse(stateContent);
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
         console.error(`Failed to read state file for channel ${channelId}`, error);
       }
     }
 
+    const cwd = isRecord(state) && typeof state.cwd === 'string' ? state.cwd : undefined;
+
     const details: ChannelDetails = {
       id: channelId,
       name: channelId,
       spec,
       state,
-      cwd: typeof (state as any).cwd === 'string' ? (state as any).cwd : undefined,
+      cwd,
     };
 
     details.threads = await storageService.getThreads({ channelId });
@@ -517,17 +640,14 @@ export const storageService = {
     const statePath = `${channelDir}/state.json`;
 
     try {
-      // 1. Fetch current details to get the existing state
       const currentDetails = await storageService.getChannelDetails({ channelId });
       const currentState = (currentDetails.state as Record<string, unknown>) || {};
 
-      // 2. Perform a shallow merge (patch)
       const newState = {
         ...currentState,
         ...(patch as Record<string, unknown>),
       };
 
-      // 3. Write back the merged state
       await fs.mkdir(channelDir, { recursive: true });
       await fs.writeFile(statePath, JSON.stringify(newState, null, 2));
     } catch (error) {
@@ -548,17 +668,14 @@ export const storageService = {
     const statePath = `${threadDir}/state.json`;
 
     try {
-      // 1. Fetch current details to get the existing state
       const currentDetails = await storageService.getThreadDetails({ channelId, threadId });
       const currentState = (currentDetails.state as Record<string, unknown>) || {};
 
-      // 2. Perform a shallow merge (patch)
       const newState = {
         ...currentState,
         ...(patch as Record<string, unknown>),
       };
 
-      // 3. Write back the merged state
       await fs.mkdir(threadDir, { recursive: true });
       await fs.writeFile(statePath, JSON.stringify(newState, null, 2));
     } catch (error) {
@@ -629,29 +746,30 @@ export const storageService = {
             name: details.name || id,
             description: details.description || '',
             image: details.image,
-            runtime: details.runtime,
+            plugins: details.plugins,
             createdAt: details.createdAt,
             updatedAt: details.updatedAt,
-          };
+          } satisfies Agent;
         } catch {
           return {
             id,
             name: id,
             description: '',
+            plugins: [],
             createdAt: new Date(),
             updatedAt: new Date(),
-          };
+          } satisfies Agent;
         }
       }),
     );
 
-    const system = await storageService.getAgentDetails({ agentId: 'system' });
+    const system = await storageService.getAgentDetails({ agentId: SYSTEM_AGENT_ID });
     const builtInSystemAgent: Agent = {
       id: system.id,
       name: system.name,
       description: system.description || '',
       image: system.image,
-      runtime: system.runtime,
+      plugins: system.plugins,
       createdAt: system.createdAt,
       updatedAt: system.updatedAt,
     };
@@ -664,20 +782,19 @@ export const storageService = {
 
     return Array.from(deduped.values());
   },
-  getPlugins: async (): Promise<Plugin[]> => {
-    const [builtInPlugins, diskPlugins] = await Promise.all([
-      listBuiltInPlugins(),
+  getPlugins: async (): Promise<PluginDescriptor[]> => {
+    const [builtIn, fromDisk] = await Promise.all([
+      listBuiltInPluginDescriptors(),
       listPluginsFromDisk(),
     ]);
 
-    const merged = [...builtInPlugins, ...diskPlugins];
-    const deduped = new Map<string, Plugin>();
+    const merged = [...builtIn, ...fromDisk];
+    const deduped = new Map<string, PluginDescriptor>();
     for (const plugin of merged) {
       if (!deduped.has(plugin.id)) {
         deduped.set(plugin.id, plugin);
       }
     }
-
     return Array.from(deduped.values());
   },
   getAgentDetails: async ({ agentId }: { agentId: string }): Promise<AgentDetails> => {
@@ -691,27 +808,32 @@ export const storageService = {
       const agentMd = await fs.readFile(agentMdPath, 'utf-8');
       const { data, content: instructions } = matter(agentMd);
       const discoveredImage = await resolveEntityImageDataUrl(agentDir);
+      const stats = await fs.stat(agentMdPath);
+
+      const pluginRefs = parsePluginRefs(data.plugins);
 
       diskDetails = {
         id: agentId,
-        name: data.name || agentId,
+        name: typeof data.name === 'string' ? data.name : agentId,
         instructions: instructions.trim(),
-        runtime: data.runtime,
-        plugins: data.plugins || [],
-        description: data.description || '',
+        plugins: pluginRefs.map((ref) => ref.id),
+        pluginRefs,
+        description: typeof data.description === 'string' ? data.description : '',
         image: discoveredImage || undefined,
-        createdAt: new Date(),
-        updatedAt: new Date(),
+        createdAt: stats.birthtime,
+        updatedAt: stats.mtime,
       };
     } catch (error) {
-      if (agentId !== 'system') {
+      if (agentId !== SYSTEM_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
+      void error;
     }
 
-    if (agentId === 'system') {
+    if (agentId === SYSTEM_AGENT_ID) {
       return getSystemAgentDetails(diskDetails);
     }
 
@@ -723,6 +845,132 @@ export const storageService = {
 
     return diskDetails as AgentDetails;
   },
+  createAgent: async ({
+    agentId,
+    name,
+    description = '',
+    instructions,
+    plugins,
+  }: {
+    agentId: string;
+    name: string;
+    description?: string;
+    instructions: string;
+    plugins: PluginRef[];
+  }): Promise<void> => {
+    assertValidDiskAgentId(agentId);
+    const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
+    const agentMdPath = path.join(agentDir, 'AGENT.md');
+
+    try {
+      await fs.access(agentMdPath);
+      throw new Error(`Agent "${agentId}" already exists`);
+    } catch (error: unknown) {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      if (code === 'ENOENT') {
+        // proceed
+      } else if (error instanceof Error && error.message.includes('already exists')) {
+        throw error;
+      } else {
+        throw error;
+      }
+    }
+
+    await fs.mkdir(agentDir, { recursive: true });
+
+    const data: Record<string, unknown> = {
+      name,
+      description,
+      plugins: serializePluginRefs(plugins),
+    };
+
+    const body = matter.stringify(`${instructions.trim()}\n`, data);
+    await fs.writeFile(agentMdPath, body, 'utf-8');
+  },
+  updateAgent: async ({
+    agentId,
+    name,
+    description,
+    instructions,
+    plugins,
+  }: {
+    agentId: string;
+    name?: string;
+    description?: string;
+    instructions?: string;
+    plugins?: PluginRef[];
+  }): Promise<void> => {
+    assertValidDiskAgentId(agentId);
+    const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
+    const agentMdPath = path.join(agentDir, 'AGENT.md');
+
+    let raw: string;
+    try {
+      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;
+      }
+      throw error;
+    }
+
+    const parsed = matter(raw);
+    const nextData: Record<string, unknown> = { ...parsed.data };
+    if (name !== undefined) nextData.name = name;
+    if (description !== undefined) nextData.description = description;
+    if (plugins !== undefined) nextData.plugins = serializePluginRefs(plugins);
+
+    const nextContent = instructions !== undefined ? instructions : parsed.content;
+    const body = matter.stringify(`${String(nextContent).trim()}\n`, nextData);
+    await fs.writeFile(agentMdPath, body, 'utf-8');
+  },
+  deleteAgent: async ({ agentId }: { agentId: string }): Promise<void> => {
+    assertValidDiskAgentId(agentId);
+    const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
+    const agentMdPath = path.join(agentDir, 'AGENT.md');
+    const packageJsonPath = path.join(agentDir, 'package.json');
+
+    try {
+      await fs.access(agentDir);
+    } 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;
+      }
+      throw error;
+    }
+
+    let hasPackage = false;
+    let hasAgentMd = false;
+    try {
+      await fs.access(packageJsonPath);
+      hasPackage = true;
+    } catch {
+      // ignore
+    }
+    try {
+      await fs.access(agentMdPath);
+      hasAgentMd = true;
+    } catch {
+      // ignore
+    }
+
+    if (hasPackage && !hasAgentMd) {
+      throw new Error(
+        `Cannot delete TypeScript agent package "${agentId}" through this action; remove the folder manually.`,
+      );
+    }
+    if (!hasAgentMd) {
+      throw new Error(
+        `Agent "${agentId}" has no AGENT.md and cannot be deleted through this action.`,
+      );
+    }
+
+    await fs.rm(agentDir, { recursive: true, force: true });
+  },
   getEvents: async ({
     channelId,
     threadId,
@@ -748,7 +996,6 @@ export const storageService = {
           return event;
         });
 
-      // If we are at the channel level (no threadId), check which events have threads
       if (!threadId) {
         const threadsDir = resolvePath(
           resolveBaseDir() + '/' + DEFAULT_CHANNELS_DIR + '/' + channelId + '/threads',
@@ -758,32 +1005,26 @@ export const storageService = {
           const threadSet = new Set(threadDirs);
 
           return events.map((event) => {
-            // Check if this event has a threadId associated with it
-            // The frontend provides the threadId, and it matches the directory name on disk
-            const threadId = event.id;
-
-            // If an explicit threadId exists and has a directory, use it
-            if (threadId && threadSet.has(threadId)) {
+            const eventThreadId = event.id;
+            if (eventThreadId && threadSet.has(eventThreadId)) {
               return {
                 ...event,
                 meta: {
-                  ...(event as any)?.meta,
+                  ...(event.meta || {}),
                   hasThread: true,
                 },
               };
             }
-
             return event;
           });
         } catch {
-          // No threads folder or other error, just return events as is
           return events;
         }
       }
 
       return events;
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
         console.error(`Failed to get events for channel ${channelId} thread ${threadId}`, error);
       }
       return [];
@@ -803,8 +1044,8 @@ export const storageService = {
       if (threadId) {
         try {
           await fs.access(threadDir);
-        } catch (error: any) {
-          if (error.code === 'ENOENT') {
+        } catch (error: unknown) {
+          if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
             const threadTitle = buildThreadTitleFromEvent(event);
             await storageService.createThread({
               channelId,
@@ -819,7 +1060,6 @@ export const storageService = {
         await fs.mkdir(threadDir, { recursive: true });
       }
 
-      // Ensure the event has a unique ID
       if (!event.id) {
         event.id = crypto.randomUUID();
       }
@@ -832,19 +1072,102 @@ export const storageService = {
   },
   getVariables: async (): Promise<Record<string, string | { value: string; secret: boolean }>> => {
     const variablesFilePath = resolvePath(resolveBaseDir() + '/' + VARIABLES_FILE);
-    const raw = await readJsonFile<any>(variablesFilePath, {});
-
-    if (raw && typeof raw === 'object' && 'variables' in raw && Array.isArray(raw.variables)) {
-      const entries = (raw.variables as StoredVariable[])
+    const raw = await readJsonFile<unknown>(variablesFilePath, {});
+
+    if (
+      raw &&
+      typeof raw === 'object' &&
+      'variables' in raw &&
+      Array.isArray((raw as { variables: unknown }).variables)
+    ) {
+      const entries = ((raw as { variables: StoredVariable[] }).variables)
         .filter((v) => typeof v?.key === 'string')
         .map((v) => [v.key, { value: String(v.value ?? ''), secret: !!v.secret }] as const);
       return Object.fromEntries(entries);
     }
 
-    // Legacy or simple format
     return toVariablesRecord(raw);
   },
 
+  createVariable: async ({
+    key,
+    value,
+    secret = false,
+  }: {
+    key: string;
+    value: string;
+    secret?: boolean;
+  }): Promise<void> => {
+    const variablesFilePath = resolvePath(resolveBaseDir() + '/' + VARIABLES_FILE);
+    const raw = await readJsonFile<unknown>(variablesFilePath, { version: 1, variables: [] });
+
+    let variables: StoredVariable[] = [];
+    if (
+      raw &&
+      typeof raw === 'object' &&
+      'variables' in raw &&
+      Array.isArray((raw as { variables: unknown }).variables)
+    ) {
+      variables = (raw as { variables: StoredVariable[] }).variables;
+    } else {
+      variables = Object.entries(toVariablesRecord(raw)).map(([k, v]) => ({
+        key: k,
+        value: v,
+        secret: false,
+      }));
+    }
+
+    const existingIndex = variables.findIndex((v) => v.key === key);
+    if (existingIndex !== -1) {
+      variables[existingIndex] = { key, value, secret };
+    } else {
+      variables.push({ key, value, secret });
+    }
+
+    await fs.mkdir(path.dirname(variablesFilePath), { recursive: true });
+    await fs.writeFile(
+      variablesFilePath,
+      JSON.stringify({ version: 1, variables }, null, 2),
+      'utf-8',
+    );
+    processService.syncWorkspaceVariablesToProcessEnv();
+  },
+
+  deleteVariable: async ({ key }: { key: string }): Promise<void> => {
+    const variablesFilePath = resolvePath(resolveBaseDir() + '/' + VARIABLES_FILE);
+    const raw = await readJsonFile<unknown>(variablesFilePath, { version: 1, variables: [] });
+
+    let variables: StoredVariable[] = [];
+    if (
+      raw &&
+      typeof raw === 'object' &&
+      'variables' in raw &&
+      Array.isArray((raw as { variables: unknown }).variables)
+    ) {
+      variables = (raw as { variables: StoredVariable[] }).variables;
+    } else {
+      variables = Object.entries(toVariablesRecord(raw)).map(([k, v]) => ({
+        key: k,
+        value: v,
+        secret: false,
+      }));
+    }
+
+    const newVariables = variables.filter((v) => v.key !== key);
+
+    if (newVariables.length === variables.length) {
+      return;
+    }
+
+    await fs.mkdir(path.dirname(variablesFilePath), { recursive: true });
+    await fs.writeFile(
+      variablesFilePath,
+      JSON.stringify({ version: 1, variables: newVariables }, null, 2),
+      'utf-8',
+    );
+    processService.syncWorkspaceVariablesToProcessEnv();
+  },
+
   listFiles: async ({
     channelId,
     path: subPath = '',
@@ -862,21 +1185,26 @@ export const storageService = {
     const resolvedBase = path.resolve(baseCwd);
     const targetDir = path.resolve(resolvedBase, subPath);
 
-    // Security check: ensure target is within baseCwd
     if (!targetDir.startsWith(resolvedBase)) {
       throw new Error('Access denied: directory escape');
     }
 
     const entries = await fs.readdir(targetDir, { withFileTypes: true });
     return entries
-      .filter((e) => !e.name.startsWith('.')) // Hide hidden files by default for MVP
+      .filter((e) => !e.name.startsWith('.'))
       .map((e) => ({
         name: e.name,
         isDirectory: e.isDirectory(),
       }));
   },
 
-  readFile: async ({ channelId, path: filePath }: { channelId: string; path: string }): Promise<string> => {
+  readFile: async ({
+    channelId,
+    path: filePath,
+  }: {
+    channelId: string;
+    path: string;
+  }): Promise<string> => {
     const details = await storageService.getChannelDetails({ channelId });
     const baseCwd = details.cwd;
 
@@ -887,7 +1215,6 @@ export const storageService = {
     const resolvedBase = path.resolve(baseCwd);
     const targetFile = path.resolve(resolvedBase, filePath);
 
-    // Security check: ensure target is within baseCwd
     if (!targetFile.startsWith(resolvedBase)) {
       throw new Error('Access denied: directory escape');
     }
@@ -895,6 +1222,11 @@ export const storageService = {
     return fs.readFile(targetFile, 'utf-8');
   },
 
+  appendMemory: memoryService.appendMemory,
+  listMemories: memoryService.listMemories,
+  deleteMemory: memoryService.deleteMemory,
+  updateMemory: memoryService.updateMemory,
+
   /**
    * Hydrates the full OpenBot state from disk/storage before a run.
    */
@@ -916,7 +1248,7 @@ export const storageService = {
     }
 
     let channelDetails;
-    if (channelId && channelId !== 'general') {
+    if (channelId) {
       try {
         channelDetails = await storageService.getChannelDetails({ channelId });
       } catch (error) {
@@ -946,10 +1278,13 @@ export const storageService = {
         id: agentDetails.id,
         name: agentDetails.name,
         description: agentDetails.description || '',
+        image: agentDetails.image,
         instructions: agentDetails.instructions || '',
-        runtime: agentDetails.runtime,
         plugins: agentDetails.plugins,
-      } as AgentDetails,
+        pluginRefs: agentDetails.pluginRefs,
+        createdAt: agentDetails.createdAt,
+        updatedAt: agentDetails.updatedAt,
+      } satisfies AgentDetails,
       channelDetails: channelDetails as ChannelDetails,
       threadDetails: threadDetails as ThreadDetails,
     };