openbot 0.3.5 → 0.4.0

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

@@ -1,3 +1,4 @@
+import { ORCHESTRATOR_AGENT_ID, STATE_AGENT_ID } from '../../app/agent-ids.js';
 import {
   DEFAULT_PLUGINS_DIR,
   DEFAULT_AGENTS_DIR,
@@ -7,7 +8,7 @@ import {
   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 +23,14 @@ 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 { OPENBOT_SYSTEM_PROMPT } from '../openbot/system-prompt.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';
 
 const resolveBaseDir = () => {
   const config = loadConfig();
@@ -49,7 +50,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 +107,34 @@ 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: 'openbot', config: { model: 'openai/gpt-5.4-mini' } },
   { id: 'shell' },
-  { id: 'todo' },
-  // { id: 'ui' },
   { id: 'approval' },
   { id: 'memory' },
+  { id: 'delegation' },
+  { id: 'storage' },
+];
+
+/** No `openbot` / `shell` — 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: OPENBOT_SYSTEM_PROMPT,
     plugins: SYSTEM_DEFAULT_PLUGINS.map((ref) => ref.id),
     pluginRefs: SYSTEM_DEFAULT_PLUGINS,
     createdAt: new Date(),
@@ -136,10 +147,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 +163,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(),
+  };
 
-const RESERVED_DISK_AGENT_IDS = new Set([SYSTEM_AGENT_ID]);
+  if (!overrides) return defaults;
+
+  const refs = overrides.pluginRefs && overrides.pluginRefs.length > 0
+    ? overrides.pluginRefs
+    : defaults.pluginRefs;
 
-const assertValidDiskAgentId = (agentId: string): void => {
+  const diskInstructions = overrides.instructions?.trim();
+  const instructions =
+    diskInstructions && diskInstructions.length > 0 ? diskInstructions : defaults.instructions;
+
+  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 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');
   }
@@ -174,9 +237,7 @@ 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'
@@ -316,10 +377,35 @@ const listPluginsFromDisk = async (): Promise<PluginDescriptor[]> => {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   !!value && typeof value === 'object' && !Array.isArray(value);
 
+/** Display-oriented fields persisted in a channel's `state.json`. */
+const readChannelStateFileFields = (
+  parsed: unknown,
+): { name?: string; cwd?: string; participants: string[] } => {
+  if (!isRecord(parsed)) {
+    return { participants: [] };
+  }
+  const name =
+    typeof parsed.name === 'string' && parsed.name.trim() ? parsed.name.trim() : undefined;
+  const cwd = typeof parsed.cwd === 'string' ? parsed.cwd : undefined;
+  const participants: string[] = [];
+  if (Array.isArray(parsed.participants)) {
+    for (const x of parsed.participants) {
+      if (typeof x === 'string' && x.trim()) participants.push(x.trim());
+    }
+  }
+  return { name, cwd, participants };
+};
+
 /**
  * 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[] = [];
@@ -376,20 +462,26 @@ export const storageService = {
         const channelDir = getConversationDir(name);
         const statePath = path.join(channelDir, 'state.json');
         let cwd: string | undefined;
+        let displayName = name;
+        let participants: string[] = [];
 
         try {
           const stateContent = await fs.readFile(statePath, 'utf-8');
-          const state = JSON.parse(stateContent);
-          cwd = typeof state.cwd === 'string' ? state.cwd : undefined;
+          const parsed = JSON.parse(stateContent);
+          const fields = readChannelStateFileFields(parsed);
+          cwd = fields.cwd;
+          displayName = fields.name ?? name;
+          participants = fields.participants;
         } catch {
           // ignore
         }
 
         const channel: Channel = {
           id: name,
-          name: name,
+          name: displayName,
           description: '',
           cwd,
+          participants,
           createdAt: new Date(),
           updatedAt: new Date(),
         };
@@ -497,7 +589,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 });
@@ -525,10 +617,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') {
@@ -574,14 +666,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,
     };
@@ -610,14 +702,17 @@ export const storageService = {
       }
     }
 
-    const cwd = isRecord(state) && typeof state.cwd === 'string' ? state.cwd : undefined;
+    const diskFields = readChannelStateFileFields(state);
+    const cwd = diskFields.cwd;
+    const displayName = diskFields.name ?? channelId;
 
     const details: ChannelDetails = {
       id: channelId,
-      name: channelId,
+      name: displayName,
       spec,
       state,
       cwd,
+      participants: diskFields.participants,
     };
 
     details.threads = await storageService.getThreads({ channelId });
@@ -713,15 +808,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,
@@ -736,23 +823,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([
@@ -796,16 +879,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;
     }
 
@@ -813,6 +897,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';
@@ -826,6 +914,7 @@ export const storageService = {
     name,
     description = '',
     image,
+    hidden,
     instructions,
     plugins,
   }: {
@@ -833,10 +922,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');
 
@@ -864,6 +954,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');
@@ -873,6 +966,7 @@ export const storageService = {
     name,
     description,
     image,
+    hidden,
     instructions,
     plugins,
   }: {
@@ -880,10 +974,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,14 +987,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;
@@ -911,17 +1010,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) {
@@ -1032,8 +1198,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);
@@ -1046,6 +1214,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 });
       }

package/src/{bus/types.ts → services/plugins/domain.ts}

@@ -1,13 +1,13 @@
-import type { OpenBotEvent } from '../app/types.js';
-import type { PluginRef } from './plugin.js';
-import type { MemoryRecord, ListMemoriesArgs } from '../services/memory.js';
+import type { OpenBotEvent } from '../../app/types.js';
+import type { PluginRef } from './types.js';
+import type { MemoryRecord, ListMemoriesArgs } from '../../plugins/memory/service.js';
 
 /**
- * Public data types exposed by the OpenBot bus.
+ * Public data types exposed by the OpenBot platform.
  *
- * The bus is the platform layer that owns channels, threads, the agent registry,
- * and the event stream. Agents are composed entirely of Plugins (see
- * `bus/plugin.ts`); their internal implementation is opaque to the bus.
+ * The platform layer owns channels, threads, the agent registry, and the event
+ * stream. Agents are composed entirely of Plugins (see `./types.ts`); their
+ * internal implementation is opaque to the platform.
  */
 
 export type Agent = {
@@ -17,6 +17,8 @@ export type Agent = {
   image?: string;
   /** Plugin ids that compose this agent (mirrors AGENT.md `plugins[].id`). */
   plugins: string[];
+  /** When true, omitted from `action:storage:get-agents` (still available via get-agent-details). */
+  hidden?: boolean;
   createdAt: Date;
   updatedAt: Date;
 };
@@ -60,6 +62,8 @@ export type Channel = {
   name: string;
   description: string;
   cwd?: string;
+  /** Agent ids associated with this channel (from `state.json`). */
+  participants: string[];
   createdAt: Date;
   updatedAt: Date;
   hasUnseenMessages?: boolean;
@@ -87,6 +91,8 @@ export type ChannelDetails = {
   spec: string;
   state: unknown;
   cwd?: string;
+  /** Agent ids for this channel (from `state.json`). */
+  participants: string[];
   threads?: Thread[];
 };
 
@@ -106,27 +112,34 @@ export interface Storage {
   }) => Promise<void>;
   getThreads: (args: { channelId: string }) => Promise<Thread[]>;
   getThreadDetails: (args: { channelId: string; threadId: string }) => Promise<ThreadDetails>;
+  /** User-facing agent list; excludes agents with `hidden: true` (e.g. built-in `state`). */
   getAgents: () => Promise<Agent[]>;
   getPlugins: () => Promise<PluginDescriptor[]>;
   getAgentDetails: (args: { agentId: string }) => Promise<AgentDetails>;
+  /** Includes built-in `system` / `state` agents as optional AGENT.md overlays. */
   createAgent: (args: {
     agentId: string;
     name: string;
     description?: string;
     /** Avatar/logo URL or data URI; persisted in AGENT.md frontmatter. */
     image?: string;
+    /** When true, agent is omitted from `getAgents` / `action:storage:get-agents`. */
+    hidden?: boolean;
     instructions: string;
     plugins: PluginRef[];
   }) => Promise<void>;
+  /** Partial update; for `system` / `state`, creates overlay file if missing. */
   updateAgent: (args: {
     agentId: string;
     name?: string;
     description?: string;
     /** Omit to leave unchanged; empty string removes stored image. */
     image?: string;
+    hidden?: boolean;
     instructions?: string;
     plugins?: PluginRef[];
   }) => Promise<void>;
+  /** For `system` / `state`, removes only `AGENT.md` (reverts to code defaults). */
   deleteAgent: (args: { agentId: string }) => Promise<void>;
   getEvents: (args: { channelId: string; threadId?: string }) => Promise<OpenBotEvent[]>;
   getChannelDetails: (args: { channelId: string }) => Promise<ChannelDetails>;

package/src/services/plugins/plugin-cache.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from './types.js';
+
+/** Resolved plugins (built-in + community); shared with registry resolution. */
+export const resolvedPluginCache = new Map<string, Plugin>();
+
+/** Community plugin ids that have already been logged as loaded once. */
+export const loadedCommunityPlugins = new Set<string>();
+
+/** Drop a single id from the in-memory resolver cache (e.g. after install/uninstall). */
+export function invalidatePlugin(id: string): void {
+  resolvedPluginCache.delete(id);
+  loadedCommunityPlugins.delete(id);
+}