amalgm 0.0.0 → 0.0.32

package/runtime/scripts/amalgm-mcp/toolbox/store.js

@@ -0,0 +1,933 @@
+'use strict';
+
+/**
+ * Toolbox store — local capability database.
+ *
+ * The durable model has two core tables:
+ *   tools       → registered connector/provider records
+ *   tool_actions → LLM-callable actions materialized from each tool
+ *
+ * Secrets intentionally do not live here. Tool records may point at secret refs
+ * once auth wiring is added.
+ */
+
+const path = require('path');
+const { AMALGM_DIR, PORT } = require('../config');
+const { ensureDir, readJson, writeJsonAtomic } = require('../lib/storage');
+const { openLocalDb } = require('../state/db');
+const { insertStateEvent, publishStateEvent } = require('../state/events');
+
+const TOOLBOX_VERSION = 1;
+const TOOLBOX_DIR = path.join(AMALGM_DIR, 'toolbox');
+const TOOLBOX_FILE = path.join(TOOLBOX_DIR, 'toolbox.json');
+
+const TOOL_TYPES = new Set(['mcp', 'api', 'cli']);
+const TOOL_ORIGINS = new Set(['system', 'user', 'catalog']);
+const RECORD_STATUSES = new Set(['enabled', 'disabled', 'error']);
+const DISCOVERY_MODES = new Set(['dynamic', 'static', 'single']);
+const DEFAULT_TOOL_OWNER = 'amalgm';
+const MODEL_UNSUPPORTED_TOP_LEVEL_SCHEMA_KEYS = ['anyOf', 'oneOf', 'allOf', 'not', 'enum'];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value || {}, key);
+}
+
+function hasAnyOwn(value, keys) {
+  return keys.some((key) => hasOwn(value, key));
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function sanitizeId(value, fallback = 'tool') {
+  return String(value || fallback)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]+/g, '.')
+    .replace(/\.+/g, '.')
+    .replace(/^[._-]+|[._-]+$/g, '')
+    || fallback;
+}
+
+function sanitizeActionName(value, fallback = 'run') {
+  return String(value || fallback)
+    .trim()
+    .replace(/[^A-Za-z0-9_.-]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^[._-]+|[._-]+$/g, '')
+    || fallback;
+}
+
+function emptyToolbox() {
+  return {
+    version: TOOLBOX_VERSION,
+    tools: {},
+    toolActions: {},
+  };
+}
+
+function normalizeToolbox(raw) {
+  const parsed = isObject(raw) ? raw : {};
+  const tools = {};
+  if (isObject(parsed.tools)) {
+    for (const [toolId, tool] of Object.entries(parsed.tools)) {
+      if (!isObject(tool)) continue;
+      tools[toolId] = {
+        ...tool,
+        owner: normalizeOwner(tool.owner || tool.toolOwner || tool.ownership || tool.policy?.owner),
+      };
+    }
+  }
+
+  return {
+    version: TOOLBOX_VERSION,
+    tools,
+    toolActions: normalizeToolActions(parsed.toolActions),
+  };
+}
+
+function safeJsonParse(value, fallback = null) {
+  if (typeof value !== 'string' || !value) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+function anyObjectSchema(description) {
+  return {
+    type: 'object',
+    description,
+    additionalProperties: true,
+  };
+}
+
+function summarizeSchemaAlternatives(schema) {
+  const alternatives = [];
+  for (const key of ['anyOf', 'oneOf', 'allOf']) {
+    const entries = Array.isArray(schema?.[key]) ? schema[key] : [];
+    for (const entry of entries) {
+      if (!isObject(entry) || !Array.isArray(entry.required)) continue;
+      const required = entry.required
+        .map((value) => nonEmptyString(value))
+        .filter(Boolean);
+      if (required.length > 0) alternatives.push(required.join(', '));
+    }
+  }
+  return alternatives;
+}
+
+function normalizeInputSchema(inputSchema, description) {
+  if (!isObject(inputSchema)) return anyObjectSchema(description);
+
+  const alternatives = summarizeSchemaAlternatives(inputSchema);
+  const schema = { ...inputSchema };
+  for (const key of MODEL_UNSUPPORTED_TOP_LEVEL_SCHEMA_KEYS) {
+    delete schema[key];
+  }
+
+  if (schema.type !== 'object') {
+    return anyObjectSchema(schema.description || description);
+  }
+
+  if (!isObject(schema.properties)) schema.properties = {};
+  if (alternatives.length > 0) {
+    const hint = `Provide fields matching one of these alternatives: ${alternatives.join('; ')}.`;
+    schema.description = [nonEmptyString(schema.description), hint].filter(Boolean).join(' ');
+  }
+  return schema;
+}
+
+function normalizeToolActions(rawToolActions) {
+  const actions = {};
+  if (!isObject(rawToolActions)) return actions;
+  for (const [actionId, action] of Object.entries(rawToolActions)) {
+    if (!isObject(action)) continue;
+    actions[actionId] = {
+      ...action,
+      inputSchema: normalizeInputSchema(action.inputSchema, `Input for ${action.name || actionId}.`),
+    };
+  }
+  return actions;
+}
+
+function isInheritedHarnessTool(tool) {
+  return tool?.owner === 'codex' && tool?.origin === 'catalog';
+}
+
+function dropInheritedHarnessTools(toolbox) {
+  for (const [toolId, tool] of Object.entries(toolbox.tools || {})) {
+    if (!isInheritedHarnessTool(tool)) continue;
+    delete toolbox.tools[toolId];
+    for (const [actionId, action] of Object.entries(toolbox.toolActions || {})) {
+      if (action?.toolId === toolId) delete toolbox.toolActions[actionId];
+    }
+  }
+  return toolbox;
+}
+
+function cliRunInputSchema(source) {
+  const inputMode = nonEmptyString(source.inputMode) || 'json-stdin';
+  if (inputMode === 'argv') {
+    return {
+      type: 'object',
+      properties: {
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Arguments to append when running the command.',
+        },
+      },
+      required: ['args'],
+      additionalProperties: false,
+    };
+  }
+  if (inputMode === 'terminal') {
+    return {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: 'Terminal command or subcommand for this registered CLI surface.',
+        },
+      },
+      required: ['command'],
+      additionalProperties: false,
+    };
+  }
+  return anyObjectSchema('JSON payload passed to the CLI command on stdin.');
+}
+
+function normalizeGuide(input) {
+  if (!input) return undefined;
+  if (typeof input === 'string') {
+    const pathValue = nonEmptyString(input);
+    return pathValue ? { kind: 'skill', path: pathValue, appliesTo: 'tool' } : undefined;
+  }
+  if (!isObject(input)) return undefined;
+
+  const pathValue = nonEmptyString(input.path || input.skillPath || input.guidePath);
+  const text = nonEmptyString(input.text || input.instructions);
+  const kind = nonEmptyString(input.kind) || (pathValue ? 'skill' : 'text');
+  if (kind === 'skill' && pathValue) {
+    return {
+      kind: 'skill',
+      path: pathValue,
+      appliesTo: nonEmptyString(input.appliesTo) || 'tool',
+    };
+  }
+  if (text) {
+    return {
+      kind: kind === 'markdown' ? 'markdown' : 'text',
+      text,
+      appliesTo: nonEmptyString(input.appliesTo) || 'tool',
+    };
+  }
+  return undefined;
+}
+
+function normalizePolicy(policy) {
+  return isObject(policy) ? { ...policy } : undefined;
+}
+
+function normalizeOwner(owner) {
+  const value = nonEmptyString(owner);
+  return value || DEFAULT_TOOL_OWNER;
+}
+
+function normalizeDisplay(display) {
+  if (!isObject(display)) return undefined;
+  const out = {};
+  for (const key of ['icon', 'description', 'docsUrl']) {
+    const value = nonEmptyString(display[key]);
+    if (value) out[key] = value;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function normalizeSource(type, source = {}) {
+  const raw = isObject(source) ? source : {};
+  if (type === 'cli') {
+    const command = nonEmptyString(raw.command);
+    if (!command) throw new Error('CLI tools require source.command');
+    return {
+      command,
+      ...(Array.isArray(raw.args) ? { args: raw.args.map(String) } : {}),
+      ...(nonEmptyString(raw.cwd) ? { cwd: raw.cwd.trim() } : {}),
+      inputMode: ['json-stdin', 'argv', 'terminal', 'none'].includes(raw.inputMode)
+        ? raw.inputMode
+        : 'json-stdin',
+      outputMode: ['json', 'text'].includes(raw.outputMode) ? raw.outputMode : 'text',
+    };
+  }
+
+  if (type === 'mcp') {
+    const transport = ['http', 'sse', 'stdio', 'codex-app'].includes(raw.transport)
+      ? raw.transport
+      : 'http';
+    const url = nonEmptyString(raw.url);
+    const command = nonEmptyString(raw.command);
+    const connectorId = nonEmptyString(raw.connectorId);
+    const serverName = nonEmptyString(raw.serverName);
+    const toolNamespace = nonEmptyString(raw.toolNamespace);
+    if (transport === 'codex-app' && !connectorId && !toolNamespace) {
+      throw new Error('Codex app MCP tools require source.connectorId or source.toolNamespace');
+    }
+    if (transport === 'stdio' && !command) throw new Error('stdio MCP tools require source.command');
+    if (transport !== 'stdio' && transport !== 'codex-app' && !url) throw new Error('remote MCP tools require source.url');
+    return {
+      transport,
+      ...(url ? { url } : {}),
+      ...(command ? { command } : {}),
+      ...(connectorId ? { connectorId } : {}),
+      ...(serverName ? { serverName } : {}),
+      ...(toolNamespace ? { toolNamespace } : {}),
+      ...(Array.isArray(raw.args) ? { args: raw.args.map(String) } : {}),
+      ...(nonEmptyString(raw.cwd) ? { cwd: raw.cwd.trim() } : {}),
+    };
+  }
+
+  if (type === 'api') {
+    const endpoints = Array.isArray(raw.endpoints) ? raw.endpoints : undefined;
+    const baseUrl = nonEmptyString(raw.baseUrl);
+    const specUrl = nonEmptyString(raw.specUrl);
+    const specPath = nonEmptyString(raw.specPath);
+    if (!baseUrl && !specUrl && !specPath && !endpoints) {
+      throw new Error('API tools require source.baseUrl, source.specUrl, source.specPath, or source.endpoints');
+    }
+    return {
+      ...(baseUrl ? { baseUrl } : {}),
+      ...(specUrl ? { specUrl } : {}),
+      ...(specPath ? { specPath } : {}),
+      ...(endpoints ? { endpoints } : {}),
+    };
+  }
+
+  throw new Error(`Unsupported tool type: ${type}`);
+}
+
+function defaultDiscoveryMode(type, hasActions) {
+  if (hasActions) return 'static';
+  if (type === 'cli') return 'single';
+  return 'dynamic';
+}
+
+function normalizeDiscovery(type, discovery, hasActions) {
+  const raw = isObject(discovery) ? discovery : {};
+  const mode = DISCOVERY_MODES.has(raw.mode)
+    ? raw.mode
+    : defaultDiscoveryMode(type, hasActions);
+  return {
+    mode,
+    ...(nonEmptyString(raw.lastDiscoveredAt) ? { lastDiscoveredAt: raw.lastDiscoveredAt.trim() } : {}),
+  };
+}
+
+function normalizeTool(input, existing) {
+  if (!isObject(input)) throw new Error('tool must be an object');
+  const type = TOOL_TYPES.has(input.type) ? input.type : null;
+  if (!type) throw new Error('tool.type must be mcp, api, or cli');
+
+  const id = sanitizeId(input.id || input.name);
+  const name = nonEmptyString(input.name) || id;
+  const createdAt = existing?.createdAt || nowIso();
+  const guide = normalizeGuide(
+    input.guide || input.skill || input.skillPath || input.guidePath,
+  );
+  const display = normalizeDisplay(input.display);
+  const policy = normalizePolicy(input.policy);
+
+  return {
+    id,
+    name,
+    type,
+    owner: normalizeOwner(input.owner || input.toolOwner || input.ownership || input.policy?.owner),
+    origin: TOOL_ORIGINS.has(input.origin) ? input.origin : 'user',
+    status: RECORD_STATUSES.has(input.status) ? input.status : 'enabled',
+    source: normalizeSource(type, isObject(input.source) ? input.source : input),
+    discovery: normalizeDiscovery(type, input.discovery, Array.isArray(input.actions) && input.actions.length > 0),
+    ...(display ? { display } : {}),
+    ...(policy ? { policy } : {}),
+    ...(guide ? { guide } : {}),
+    createdAt,
+    updatedAt: nowIso(),
+  };
+}
+
+function normalizeAction(input, tool, existing) {
+  if (!isObject(input)) throw new Error('tool action must be an object');
+  const name = sanitizeActionName(input.name || input.actionName || 'run');
+  const id = sanitizeId(input.id || `${tool.id}.${name}`);
+  const createdAt = existing?.createdAt || nowIso();
+  const guide = normalizeGuide(
+    input.guide || input.skill || input.skillPath || input.guidePath,
+  );
+  const policy = normalizePolicy(input.policy);
+
+  return {
+    id,
+    toolId: tool.id,
+    name,
+    ...(nonEmptyString(input.displayName) ? { displayName: input.displayName.trim() } : {}),
+    ...(nonEmptyString(input.description) ? { description: input.description.trim() } : {}),
+    inputSchema: normalizeInputSchema(
+      input.inputSchema,
+      `Input for ${tool.name} ${name}.`,
+    ),
+    ...(isObject(input.outputSchema) ? { outputSchema: input.outputSchema } : {}),
+    status: RECORD_STATUSES.has(input.status) ? input.status : 'enabled',
+    ...(isObject(input.sourceAction) ? { sourceAction: input.sourceAction } : {}),
+    ...(policy ? { policy } : {}),
+    ...(guide ? { guide } : {}),
+    createdAt,
+    updatedAt: nowIso(),
+  };
+}
+
+function defaultCliAction(tool) {
+  return normalizeAction({
+    id: `${tool.id}.run`,
+    name: 'run',
+    displayName: 'Run',
+    description: `Run ${tool.name} using its registered CLI command.`,
+    inputSchema: cliRunInputSchema(tool.source),
+    sourceAction: { cliSubcommand: null },
+  }, tool);
+}
+
+function actionFromMcpTool(tool, mcpTool) {
+  return normalizeAction({
+    id: `${tool.id}.${mcpTool.name}`,
+    name: mcpTool.name,
+    displayName: mcpTool.name,
+    description: mcpTool.description,
+    inputSchema: isObject(mcpTool.inputSchema) ? mcpTool.inputSchema : { type: 'object', properties: {} },
+    sourceAction: { mcpToolName: mcpTool.name },
+  }, tool);
+}
+
+function systemAmalgmTool() {
+  return {
+    id: 'amalgm',
+    name: 'amalgm',
+    type: 'mcp',
+    owner: DEFAULT_TOOL_OWNER,
+    origin: 'system',
+    status: 'enabled',
+    source: {
+      transport: 'http',
+      url: `http://127.0.0.1:${PORT}/mcp`,
+    },
+    discovery: {
+      mode: 'dynamic',
+    },
+    display: {
+      icon: '/assets/images/amalgm_logo.svg',
+      description: 'Built-in Amalgm tools for tasks, events, agents, artifacts, browser, and notifications.',
+    },
+    policy: {
+      system: true,
+    },
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+}
+
+function seedSystemTools(toolbox) {
+  let changed = false;
+  const existing = toolbox.tools.amalgm;
+  const systemTool = {
+    ...systemAmalgmTool(),
+    createdAt: existing?.createdAt || nowIso(),
+    updatedAt: existing?.updatedAt || nowIso(),
+  };
+
+  if (!existing || JSON.stringify({ ...existing, updatedAt: undefined }) !== JSON.stringify({ ...systemTool, updatedAt: undefined })) {
+    toolbox.tools.amalgm = { ...existing, ...systemTool };
+    changed = true;
+  }
+
+  let toolsList = [];
+  try {
+    toolsList = require('../server/core-tools').CORE_TOOLS || [];
+  } catch {
+    toolsList = [];
+  }
+
+  for (const mcpTool of toolsList) {
+    if (!mcpTool?.name) continue;
+    const action = actionFromMcpTool(toolbox.tools.amalgm, mcpTool);
+    const existingAction = toolbox.toolActions[action.id];
+    if (!existingAction || JSON.stringify({
+      ...existingAction,
+      createdAt: undefined,
+      updatedAt: undefined,
+    }) !== JSON.stringify({
+      ...action,
+      createdAt: undefined,
+      updatedAt: undefined,
+    })) {
+      toolbox.toolActions[action.id] = {
+        ...existingAction,
+        ...action,
+        createdAt: existingAction?.createdAt || action.createdAt,
+      };
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+function readToolboxFromDb() {
+  const db = openLocalDb();
+  const tools = {};
+  const toolActions = {};
+
+  for (const row of db.prepare('SELECT tool_json FROM tools ORDER BY updated_at DESC, id ASC').all()) {
+    const tool = safeJsonParse(row.tool_json);
+    if (isObject(tool) && tool.id) tools[tool.id] = tool;
+  }
+
+  for (const row of db.prepare('SELECT action_json FROM tool_actions ORDER BY updated_at DESC, id ASC').all()) {
+    const action = safeJsonParse(row.action_json);
+    if (isObject(action) && action.id) toolActions[action.id] = action;
+  }
+
+  return normalizeToolbox({ tools, toolActions });
+}
+
+function toolboxRowCount(db = openLocalDb()) {
+  const row = db.prepare('SELECT COUNT(*) AS count FROM tools').get();
+  return Number(row?.count || 0);
+}
+
+function upsertToolRow(db, tool) {
+  db.prepare(`
+    INSERT INTO tools (
+      id,
+      name,
+      type,
+      owner,
+      origin,
+      status,
+      updated_at,
+      tool_json
+    )
+    VALUES (@id, @name, @type, @owner, @origin, @status, @updated_at, @tool_json)
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      type = excluded.type,
+      owner = excluded.owner,
+      origin = excluded.origin,
+      status = excluded.status,
+      updated_at = excluded.updated_at,
+      tool_json = excluded.tool_json
+  `).run({
+    id: tool.id,
+    name: tool.name,
+    type: tool.type,
+    owner: tool.owner || DEFAULT_TOOL_OWNER,
+    origin: tool.origin || 'user',
+    status: tool.status || 'enabled',
+    updated_at: tool.updatedAt || nowIso(),
+    tool_json: JSON.stringify(tool),
+  });
+}
+
+function upsertToolActionRow(db, action) {
+  db.prepare(`
+    INSERT INTO tool_actions (
+      id,
+      tool_id,
+      name,
+      status,
+      updated_at,
+      action_json
+    )
+    VALUES (@id, @tool_id, @name, @status, @updated_at, @action_json)
+    ON CONFLICT(id) DO UPDATE SET
+      tool_id = excluded.tool_id,
+      name = excluded.name,
+      status = excluded.status,
+      updated_at = excluded.updated_at,
+      action_json = excluded.action_json
+  `).run({
+    id: action.id,
+    tool_id: action.toolId,
+    name: action.name,
+    status: action.status || 'enabled',
+    updated_at: action.updatedAt || nowIso(),
+    action_json: JSON.stringify(action),
+  });
+}
+
+function writeToolboxToDb(toolbox, options = {}) {
+  const normalized = normalizeToolbox(toolbox);
+  const db = openLocalDb();
+  db.transaction(() => {
+    if (options.replace) {
+      db.prepare('DELETE FROM tool_actions').run();
+      db.prepare('DELETE FROM tools').run();
+    }
+
+    for (const tool of Object.values(normalized.tools)) {
+      upsertToolRow(db, tool);
+    }
+
+    for (const action of Object.values(normalized.toolActions)) {
+      if (!normalized.tools[action.toolId]) continue;
+      upsertToolActionRow(db, action);
+    }
+  })();
+  return normalized;
+}
+
+function exportToolboxJson(toolbox) {
+  ensureDir(TOOLBOX_DIR);
+  writeJsonAtomic(TOOLBOX_FILE, normalizeToolbox(toolbox));
+}
+
+function migrateLegacyToolboxFileIfNeeded() {
+  const db = openLocalDb();
+  if (toolboxRowCount(db) > 0) return;
+
+  const legacyToolbox = dropInheritedHarnessTools(normalizeToolbox(readJson(TOOLBOX_FILE, emptyToolbox())));
+  if (Object.keys(legacyToolbox.tools).length === 0 && Object.keys(legacyToolbox.toolActions).length === 0) return;
+  writeToolboxToDb(legacyToolbox, { replace: true });
+}
+
+function publishCommittedEvents(events) {
+  for (const event of events) publishStateEvent(event);
+}
+
+function insertToolEvent(db, op, tool, options = {}) {
+  return insertStateEvent(db, {
+    resource: 'tools',
+    op,
+    id: tool.id,
+    value: tool,
+    clientMutationId: options.clientMutationId,
+    source: options.source || 'toolbox',
+  });
+}
+
+function insertToolActionEvent(db, op, action, options = {}) {
+  return insertStateEvent(db, {
+    resource: 'tool_actions',
+    op,
+    id: action.id,
+    value: action,
+    clientMutationId: options.clientMutationId,
+    source: options.source || 'toolbox',
+  });
+}
+
+function readToolbox() {
+  migrateLegacyToolboxFileIfNeeded();
+  const toolbox = readToolboxFromDb();
+  const systemChanged = seedSystemTools(toolbox);
+  if (systemChanged) writeToolbox(toolbox);
+  return toolbox;
+}
+
+function writeToolbox(toolbox) {
+  const normalized = writeToolboxToDb(toolbox, { replace: true });
+  exportToolboxJson(normalized);
+  return normalized;
+}
+
+function toolActionsForTool(toolbox, toolId) {
+  return Object.values(toolbox.toolActions || {})
+    .filter((action) => action.toolId === toolId);
+}
+
+function getTool(id, options = {}) {
+  const idValue = nonEmptyString(id);
+  if (!idValue) throw new Error('id is required');
+  const toolbox = readToolbox();
+  const toolId = sanitizeId(idValue);
+  const tool = toolbox.tools[toolId];
+  if (!tool) throw new Error(`Unknown tool: ${toolId}`);
+  return {
+    tool,
+    ...(options.includeActions === false ? {} : { actions: toolActionsForTool(toolbox, toolId) }),
+  };
+}
+
+function getToolAction(id) {
+  const idValue = nonEmptyString(id);
+  if (!idValue) throw new Error('id is required');
+  const toolbox = readToolbox();
+  const actionId = sanitizeId(idValue);
+  const action = toolbox.toolActions[actionId];
+  if (!action) throw new Error(`Unknown tool action: ${actionId}`);
+  return { action };
+}
+
+function upsertTool(input) {
+  const toolbox = readToolbox();
+  const existing = input?.id ? toolbox.tools[sanitizeId(input.id)] : null;
+  const existingActionIds = new Set(Object.keys(toolbox.toolActions));
+  const tool = normalizeTool(input, existing);
+  toolbox.tools[tool.id] = tool;
+
+  const actions = [];
+  if (Array.isArray(input.actions) && input.actions.length > 0) {
+    for (const actionInput of input.actions) {
+      const action = normalizeAction(actionInput, tool, actionInput?.id ? toolbox.toolActions[sanitizeId(actionInput.id)] : null);
+      toolbox.toolActions[action.id] = action;
+      actions.push(action);
+    }
+  } else {
+    const existingToolActions = Object.values(toolbox.toolActions)
+      .filter((action) => action.toolId === tool.id);
+    const defaultActionId = `${tool.id}.run`;
+    if (tool.type === 'cli' && (existingToolActions.length === 0 || toolbox.toolActions[defaultActionId])) {
+      const defaultAction = defaultCliAction(tool);
+      const action = {
+        ...defaultAction,
+        ...(toolbox.toolActions[defaultActionId] || {}),
+        inputSchema: defaultAction.inputSchema,
+        sourceAction: defaultAction.sourceAction,
+        updatedAt: defaultAction.updatedAt,
+        createdAt: toolbox.toolActions[defaultActionId]?.createdAt || nowIso(),
+      };
+      toolbox.toolActions[action.id] = action;
+      actions.push(action);
+    }
+  }
+
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    const inserted = [];
+    upsertToolRow(db, tool);
+    inserted.push(insertToolEvent(db, existing ? 'update' : 'insert', tool, {
+      clientMutationId: input.clientMutationId,
+      source: 'toolbox:upsert-tool',
+    }));
+    for (const action of actions) {
+      upsertToolActionRow(db, action);
+      inserted.push(insertToolActionEvent(db, existingActionIds.has(action.id) ? 'update' : 'insert', action, {
+        clientMutationId: input.clientMutationId,
+        source: 'toolbox:upsert-tool',
+      }));
+    }
+    return inserted;
+  })();
+  publishCommittedEvents(events);
+  return { tool, actions };
+}
+
+function sourcePatchFromToolInput(input) {
+  const patch = isObject(input?.source) ? { ...input.source } : {};
+  for (const key of [
+    'command',
+    'args',
+    'cwd',
+    'inputMode',
+    'outputMode',
+    'transport',
+    'url',
+    'connectorId',
+    'serverName',
+    'toolNamespace',
+    'baseUrl',
+    'specUrl',
+    'specPath',
+    'endpoints',
+  ]) {
+    if (hasOwn(input, key)) patch[key] = input[key];
+  }
+  return Object.keys(patch).length ? patch : null;
+}
+
+function updateTool(input) {
+  if (!isObject(input)) throw new Error('tool update must be an object');
+  const idValue = nonEmptyString(input.id || input.toolId);
+  if (!idValue) throw new Error('id is required');
+
+  const toolbox = readToolbox();
+  const toolId = sanitizeId(idValue);
+  const existing = toolbox.tools[toolId];
+  if (!existing) throw new Error(`Unknown tool: ${toolId}`);
+  if (existing.origin === 'system') throw new Error('System tools cannot be modified');
+
+  const sourcePatch = sourcePatchFromToolInput(input);
+  const guideKeys = ['guide', 'skill', 'skillPath', 'guidePath'];
+  const nextInput = {
+    ...existing,
+    ...input,
+    id: existing.id,
+    name: hasOwn(input, 'name') ? input.name : existing.name,
+    type: hasOwn(input, 'type') ? input.type : existing.type,
+    owner: hasAnyOwn(input, ['owner', 'toolOwner', 'ownership'])
+      ? (input.owner || input.toolOwner || input.ownership)
+      : existing.owner,
+    origin: hasOwn(input, 'origin') ? input.origin : existing.origin,
+    status: hasOwn(input, 'status') ? input.status : existing.status,
+    source: sourcePatch ? { ...(isObject(existing.source) ? existing.source : {}), ...sourcePatch } : existing.source,
+    discovery: hasOwn(input, 'discovery') && isObject(input.discovery)
+      ? { ...(isObject(existing.discovery) ? existing.discovery : {}), ...input.discovery }
+      : existing.discovery,
+    display: hasOwn(input, 'display')
+      ? (input.display === null ? undefined : { ...(isObject(existing.display) ? existing.display : {}), ...(isObject(input.display) ? input.display : {}) })
+      : existing.display,
+    policy: hasOwn(input, 'policy')
+      ? (input.policy === null ? undefined : { ...(isObject(existing.policy) ? existing.policy : {}), ...(isObject(input.policy) ? input.policy : {}) })
+      : existing.policy,
+    guide: hasAnyOwn(input, guideKeys)
+      ? (input.guide || input.skill || input.skillPath || input.guidePath)
+      : existing.guide,
+  };
+
+  const tool = normalizeTool(nextInput, existing);
+  toolbox.tools[tool.id] = tool;
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    upsertToolRow(db, tool);
+    return [insertToolEvent(db, 'update', tool, {
+      clientMutationId: input.clientMutationId,
+      source: 'toolbox:update-tool',
+    })];
+  })();
+  publishCommittedEvents(events);
+  return { tool, actions: toolActionsForTool(toolbox, tool.id) };
+}
+
+function upsertToolAction(input) {
+  const toolbox = readToolbox();
+  const toolId = sanitizeId(input?.toolId || input?.providerId || input?.tool);
+  const tool = toolbox.tools[toolId];
+  if (!tool) throw new Error(`Unknown tool: ${toolId}`);
+  const existing = input?.id ? toolbox.toolActions[sanitizeId(input.id)] : null;
+  const action = normalizeAction(input, tool, existing);
+  toolbox.toolActions[action.id] = action;
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    upsertToolActionRow(db, action);
+    return [insertToolActionEvent(db, existing ? 'update' : 'insert', action, {
+      clientMutationId: input.clientMutationId,
+      source: 'toolbox:upsert-action',
+    })];
+  })();
+  publishCommittedEvents(events);
+  return action;
+}
+
+function updateToolAction(input) {
+  if (!isObject(input)) throw new Error('tool action update must be an object');
+  const idValue = nonEmptyString(input.id || input.actionId);
+  if (!idValue) throw new Error('id is required');
+
+  const toolbox = readToolbox();
+  const actionId = sanitizeId(idValue);
+  const existing = toolbox.toolActions[actionId];
+  if (!existing) throw new Error(`Unknown tool action: ${actionId}`);
+  const tool = toolbox.tools[existing.toolId];
+  if (!tool) throw new Error(`Unknown tool: ${existing.toolId}`);
+  if (tool.origin === 'system') throw new Error('System tool actions cannot be modified');
+
+  const guideKeys = ['guide', 'skill', 'skillPath', 'guidePath'];
+  const nextInput = {
+    ...existing,
+    ...input,
+    id: existing.id,
+    toolId: existing.toolId,
+    name: hasOwn(input, 'name') ? input.name : existing.name,
+    displayName: hasOwn(input, 'displayName') ? input.displayName : existing.displayName,
+    description: hasOwn(input, 'description') ? input.description : existing.description,
+    inputSchema: hasOwn(input, 'inputSchema') ? input.inputSchema : existing.inputSchema,
+    outputSchema: hasOwn(input, 'outputSchema') ? input.outputSchema : existing.outputSchema,
+    status: hasOwn(input, 'status') ? input.status : existing.status,
+    sourceAction: hasOwn(input, 'sourceAction')
+      ? (input.sourceAction === null ? undefined : { ...(isObject(existing.sourceAction) ? existing.sourceAction : {}), ...(isObject(input.sourceAction) ? input.sourceAction : {}) })
+      : existing.sourceAction,
+    policy: hasOwn(input, 'policy')
+      ? (input.policy === null ? undefined : { ...(isObject(existing.policy) ? existing.policy : {}), ...(isObject(input.policy) ? input.policy : {}) })
+      : existing.policy,
+    guide: hasAnyOwn(input, guideKeys)
+      ? (input.guide || input.skill || input.skillPath || input.guidePath)
+      : existing.guide,
+  };
+
+  const action = normalizeAction(nextInput, tool, existing);
+  toolbox.toolActions[action.id] = action;
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    upsertToolActionRow(db, action);
+    return [insertToolActionEvent(db, 'update', action, {
+      clientMutationId: input.clientMutationId,
+      source: 'toolbox:update-action',
+    })];
+  })();
+  publishCommittedEvents(events);
+  return action;
+}
+
+function deleteTool(id, options = {}) {
+  const toolbox = readToolbox();
+  const toolId = sanitizeId(id);
+  const tool = toolbox.tools[toolId];
+  if (!tool) return { ok: true, deleted: false };
+  if (tool.origin === 'system') throw new Error('System tools cannot be deleted');
+  const actions = Object.values(toolbox.toolActions).filter((action) => action.toolId === toolId);
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    const inserted = actions.map((action) => insertToolActionEvent(db, 'delete', action, {
+      clientMutationId: options.clientMutationId,
+      source: 'toolbox:delete-tool',
+    }));
+    db.prepare('DELETE FROM tool_actions WHERE tool_id = ?').run(toolId);
+    db.prepare('DELETE FROM tools WHERE id = ?').run(toolId);
+    inserted.push(insertToolEvent(db, 'delete', tool, {
+      clientMutationId: options.clientMutationId,
+      source: 'toolbox:delete-tool',
+    }));
+    return inserted;
+  })();
+  publishCommittedEvents(events);
+  return { ok: true, deleted: true };
+}
+
+function deleteToolAction(id, options = {}) {
+  const toolbox = readToolbox();
+  const actionId = sanitizeId(id);
+  const action = toolbox.toolActions[actionId];
+  if (!action) return { ok: true, deleted: false };
+  const tool = toolbox.tools[action.toolId];
+  if (tool?.origin === 'system') throw new Error('System tool actions cannot be deleted');
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    db.prepare('DELETE FROM tool_actions WHERE id = ?').run(actionId);
+    return [insertToolActionEvent(db, 'delete', action, {
+      clientMutationId: options.clientMutationId,
+      source: 'toolbox:delete-action',
+    })];
+  })();
+  publishCommittedEvents(events);
+  return { ok: true, deleted: true };
+}
+
+module.exports = {
+  TOOLBOX_FILE,
+  deleteTool,
+  deleteToolAction,
+  getTool,
+  getToolAction,
+  readToolbox,
+  updateTool,
+  updateToolAction,
+  upsertTool,
+  upsertToolAction,
+};