┌─────────────────────────────────────────────────────────────────┐
│ ./                                                              │
│   Manifest + Types + systemRole                                 │
│   ─ Pure data, no React, no Node-only deps.                     │
│   ─ Imported by: server (LLM tool spec), client (registries),   │
│     anyone who needs to know "what tools exist".                │
└─────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│ ./executionRuntime                                              │
│   src/ExecutionRuntime/index.ts                                 │
│   ─ Pure runtime logic. Accepts services via constructor —      │
│     never imports concrete services or stores directly.         │
│   ─ Imported by: server (BuiltinServerRuntimeOutput), tests,    │
│     and the client executor as a delegate.                      │
│   ─ Returns: BuiltinServerRuntimeOutput { content, state, … }   │
└─────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│ ./executor                                                      │
│   src/client/executor/index.ts                                  │
│   ─ BaseExecutor subclass. Wires Zustand stores and frontend    │
│     services into ExecutionRuntime, then funnels through        │
│     toResult() into BuiltinToolResult { content, state, error,  │
│     success }.                                                  │
│   ─ Imported by: src/store/tool/slices/builtin/executors/       │
│     index.ts (registered as a singleton).                       │
└─────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│ ./client                                                        │
│   src/client/{Inspector,Render,Placeholder,Streaming,           │
│              Intervention,Portal,components}/                   │
│   ─ React 'use client' surfaces. Read args + pluginState.       │
│   ─ Imported by: packages/builtin-tools/src/{inspectors,        │
│     renders,placeholders,streamings,interventions,portals}.ts.  │
└─────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│ Registry wiring                                                 │
│   packages/builtin-tools/src/*.ts                               │
│   src/store/tool/slices/builtin/executors/index.ts              │
│   ─ Aggregator maps: identifier → { apiName → component }.      │
└─────────────────────────────────────────────────────────────────┘

ExecutionRuntime
  ├─ accepts services via constructor (or `static create(opts)`)
  ├─ returns BuiltinServerRuntimeOutput (content + state + success)
  └─ no React, no Zustand, no `@/services/...` direct imports

client/executor
  ├─ extends BaseExecutor<typeof <Name>ApiName>
  ├─ holds a `runtime = new <Name>ExecutionRuntime(realService)` instance
  ├─ each ApiName method:
  │     1. resolve scope / pull defaults from BuiltinToolContext
  │     2. call runtime.<method>(args)
  │     3. funnel through toResult() → BuiltinToolResult
  └─ exported singleton: export const <name>Executor = new <Name>Executor()

export interface ILocalSystemService {
  readLocalFile: (params: any) => Promise<any>;
  writeFile: (params: any) => Promise<any>;
  /* … */
}

export class LocalSystemExecutionRuntime extends ComputerRuntime {
  constructor(private service: ILocalSystemService) {
    super();
  }
  /* methods delegate to this.service.* */
}

import { localFileService } from '@/services/electron/localFileService';
import { LocalSystemExecutionRuntime } from '../../ExecutionRuntime';

class LocalSystemExecutor extends BaseExecutor<typeof LocalSystemApiEnum> {
  private runtime = new LocalSystemExecutionRuntime(localFileService);
  /* … */
}

{
  content: string;        // the LLM-facing text — never undefined; default to error message
  state?: any;            // result-domain object the UI reads as pluginState
  success: boolean;       // mandatory
  error?: any;            // raw error; the executor will repackage
}

{
  success: boolean;
  content?: string;
  state?: any;
  error?: { type: string; message: string; body?: any };
  metadata?: Record<string, any>;   // rare; e.g. { agentCouncil: true }
  stop?: boolean;                   // rare; halt the orchestration step
}

private toResult(output: BuiltinServerRuntimeOutput): BuiltinToolResult {
  const errorMessage = typeof output.error?.message === 'string' ? output.error.message : undefined;
  const safeContent  = output.content || errorMessage || 'Tool execution failed';

  if (!output.success) {
    return {
      success: false,
      content: safeContent,
      state:   output.state,
      error:   output.error
        ? { type: 'PluginServerError', message: errorMessage ?? safeContent, body: output.error }
        : undefined,
    };
  }
  return { success: true, content: safeContent, state: output.state };
}

if (!this.hasApi(apiName)) return { error: { type: 'ApiNotFound', … }, success: false };
return (this as any)[apiName](params, ctx);   // method name MUST equal apiName value

{
  identifier: TaskManifest.identifier,
  manifest:   TaskManifest,
  type:       'builtin',
  hidden:        true,   // hide from chat-input Tools popover
  discoverable:  false,  // exclude from agent builder / skill discovery
}

packages/builtin-tool-<name>/
├── package.json                          # exports: ., ./client, ./executor, ./executionRuntime
└── src/
    ├── index.ts                          # export Manifest, Identifier, types, systemPrompt
    ├── manifest.ts                       # BuiltinToolManifest + Identifier const
    ├── types.ts                          # ApiName + Params/State per API
    ├── systemRole.ts                     # System prompt (multiple variants OK: systemRole.desktop.ts)
    ├── ExecutionRuntime/
    │   └── index.ts                      # <Name>ExecutionRuntime — pure runtime, service injection
    └── client/
        ├── index.ts                      # exports for the registries
        ├── executor/
        │   └── index.ts                  # <Name>Executor extends BaseExecutor; export <name>Executor
        ├── Inspector/
        │   ├── index.ts                  # <Name>Inspectors record
        │   └── <ApiName>/index.tsx       # one folder per API (or .tsx file when trivial)
        ├── Render/
        │   ├── index.ts                  # <Name>Renders record
        │   └── <ApiName>/                # rich renders → folder with subcomponents
        ├── Placeholder/
        │   ├── index.ts
        │   └── <ApiName>.tsx             # usually a single skeleton file
        ├── Streaming/
        │   ├── index.ts
        │   └── <ApiName>/                # live-output renderer
        ├── Intervention/
        │   ├── index.ts
        │   └── <ApiName>/                # approval / edit-before-run UI
        ├── Portal/
        │   ├── index.tsx                 # routing component (switch on apiName)
        │   └── <ApiName>/                # full-screen detail view
        └── components/                   # FileItem, EngineAvatar, etc. — shared subcomponents