import { randomUUID } from "node:crypto";

import { ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER } from "../action-ui.js";
import { AgentActionStopError, type ActionRunContext } from "../action.js";
import type { ActionEntry } from "../agent/production-agent.js";
import type { AgentChatAttachment } from "../agent/types.js";
import { writeAppState } from "../application-state/script-helpers.js";
import { getDbExec, isPostgres } from "../db/client.js";
import { readResource } from "../resources/script-helpers.js";
import {
  getRequestOrgId,
  getRequestRunContext,
  getRequestUserEmail,
} from "../server/request-context.js";
import { resolveAccess } from "../sharing/access.js";
import {
  readWorkspaceFile,
  type WorkspaceFilesScope,
} from "../workspace-files/store.js";
import { ExtensionContentEditError } from "./content-patch.js";
import type {
  ExtensionContentEdit,
  ExtensionLegacyPatch,
} from "./content-patch.js";
import {
  getLocalExtension,
  isLocalExtensionRow,
  listLocalExtensions,
  type LocalExtensionRow,
} from "./local.js";
import { extensionPath } from "./path.js";
import {
  addExtensionSlotTarget,
  installExtensionSlot,
  uninstallExtensionSlot,
  listExtensionsForSlot,
  listSlotsForExtension,
} from "./slots/store.js";
import {
  createExtension,
  deleteExtension,
  ensureExtensionsTables,
  findRecentDuplicateExtension,
  getHiddenExtensionIdsForCurrentUser,
  getExtension,
  getExtensionHistoryVersion,
  globalHideExtension,
  globalUnhideExtension,
  hideExtension,
  listExtensionHistory,
  listExtensions,
  notifyExtensionChangeForResource,
  restoreExtensionHistoryVersion,
  unhideExtension,
  updateExtension,
  updateExtensionContent,
  type ExtensionHistoryDetail,
  type ExtensionHistoryEntry,
  type ExtensionRow,
} from "./store.js";

// A 200k extension body containing JSON-sensitive HTML/JS characters (quotes,
// backslashes, and newlines) expands to about 400k characters when pretty-JSON
// serialized by the agent loop. A history detail can carry the current and
// previous bodies plus both bodies again in its line diff (about 1.6M chars in
// the same worst-common-case fixture). These caps add roughly 25% headroom for
// the surrounding metadata and indentation while still bounding tool context.
const GET_EXTENSION_MAX_RESULT_CHARS = 500_000;
const GET_EXTENSION_HISTORY_MAX_RESULT_CHARS = 2_000_000;

export function createExtensionActionEntries(): Record<string, ActionEntry> {
  return {
    "list-extensions": {
      tool: {
        description:
          "List extensions visible in the current user's Extensions list/sidebar. Use this for browsing or when you only know a display name. If <current-screen> or <current-url> already contains extensionId for the current extension, use get-extension or update-extension with that id directly instead of listing. Do not query the legacy tools table directly for extension management.",
        parameters: {
          type: "object",
          properties: {
            search: {
              type: "string",
              description:
                "Optional case-insensitive filter matched against id, name, description, and owner email. Example: Connect Zoom.",
            },
            includeHidden: {
              type: "boolean",
              description:
                "Include extensions the current user has hidden from their list. Defaults to false.",
            },
            includeGloballyHidden: {
              type: "boolean",
              description:
                "Include extensions an admin/owner has globally hidden from everyone (via global-hide-extension). Defaults to false. Use this to find ids to unhide for everyone.",
            },
            includeContent: {
              type: "boolean",
              description:
                "Include full Alpine.js content. Defaults to false to keep results concise.",
            },
            limit: {
              type: "number",
              description: "Maximum results to return. Defaults to 100.",
            },
          },
        },
      },
      run: async (args) => {
        const includeHidden = coerceBoolean(args?.includeHidden);
        const includeGloballyHidden = coerceBoolean(
          args?.includeGloballyHidden,
        );
        const includeContent = coerceBoolean(args?.includeContent);
        const search = String(args?.search ?? "")
          .trim()
          .toLowerCase();
        const limit = coerceLimit(args?.limit);
        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();

        let rows: Array<ExtensionRow | LocalExtensionRow> =
          await listExtensions({
            includeHidden,
            includeGloballyHidden,
          });
        const localRows = await listLocalExtensions();
        const allRows: Array<ExtensionRow | LocalExtensionRow> = [
          ...rows,
          ...localRows,
        ];
        if (search) {
          rows = allRows.filter((row) =>
            [row.id, row.name, row.description, row.ownerEmail]
              .join("\n")
              .toLowerCase()
              .includes(search),
          );
        } else {
          rows = allRows;
        }

        rows = rows.slice(0, limit);
        const extensions = await Promise.all(
          rows.map((row) => summarizeExtension(row, hiddenIds, includeContent)),
        );
        return {
          ok: true,
          count: extensions.length,
          extensions,
        };
      },
      readOnly: true,
    },

    "get-extension": {
      tool: {
        description:
          "Get one existing extension by id. Use this when <current-screen> or <current-url> contains extensionId for the current extension; do not call list-extensions just to rediscover that id. Defaults to including the full Alpine.js content once per run so you can make a targeted update-extension edit; repeated unchanged reads return compact metadata unless forceContent=true.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description:
                "Extension id to read. Prefer the extensionId from <current-screen> or <current-url> when the user refers to the current extension.",
            },
            includeContent: {
              type: "boolean",
              description:
                "Include full Alpine.js content. Defaults to true for targeted edits.",
            },
            forceContent: {
              type: "boolean",
              description:
                "Return full content even if this run already read the same unchanged body. Use sparingly; prefer update-extension edits after the first read.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const includeContent =
          args?.includeContent === undefined
            ? true
            : coerceBoolean(args.includeContent);
        const forceContent = coerceBoolean(args?.forceContent);
        const localExtension = await getLocalExtension(id);
        if (localExtension) {
          return {
            ok: true,
            extension: await summarizeExtensionForAgentRead(
              localExtension,
              new Set(),
              includeContent,
              forceContent,
            ),
          };
        }
        const extension = await getExtension(id);
        if (!extension) return `Error: extension not found: ${id}`;
        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
        return {
          ok: true,
          extension: await summarizeExtensionForAgentRead(
            extension,
            hiddenIds,
            includeContent,
            forceContent,
          ),
        };
      },
      // Result is JSON including the full Alpine content; account for JSON
      // escaping and envelope metadata instead of matching the source cap.
      maxResultChars: GET_EXTENSION_MAX_RESULT_CHARS,
      readOnly: true,
    },

    "list-extension-history": {
      tool: {
        description:
          "List saved history snapshots for one extension. Use this when the user asks what changed, wants a changelog, or wants to pick an older version to restore. If the user is viewing the extension, use the extensionId from <current-screen> or <current-url>.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "Extension id whose history should be listed.",
            },
            limit: {
              type: "number",
              description: "Maximum versions to return. Defaults to 50.",
            },
            includeContent: {
              type: "boolean",
              description:
                "Include full HTML content for each version. Defaults to false.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionReadonlyHistoryMessage(id);
        if (localMessage) return localMessage;
        const history = await listExtensionHistory(id, {
          limit:
            args?.limit === undefined ? undefined : coerceLimit(args.limit),
          includeContent: coerceBoolean(args?.includeContent),
        });
        return {
          ok: true,
          count: history.length,
          history,
        };
      },
      readOnly: true,
    },

    "get-extension-history-version": {
      tool: {
        description:
          "Get one extension history version with its previous-version diff. Use after list-extension-history when the user wants to inspect exactly what changed. Full HTML bodies are omitted by default; set includeContent=true only when restoring or manually comparing full source.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "Extension id whose history version should be read.",
            },
            version: {
              type: "number",
              description: "History version number to inspect.",
            },
            includeContent: {
              type: "boolean",
              description:
                "Include full HTML for the current and previous versions. Defaults to false to keep agent context compact.",
            },
          },
          required: ["id", "version"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionReadonlyHistoryMessage(id);
        if (localMessage) return localMessage;
        const version = Number(args?.version);
        if (!Number.isInteger(version) || version < 1) {
          return "Error: version must be a positive integer.";
        }
        const detail = await getExtensionHistoryVersion(id, version);
        if (!detail) {
          return `Error: extension history version not found: ${id}#${version}`;
        }
        return {
          ok: true,
          ...compactExtensionHistoryDetail(
            detail,
            coerceBoolean(args?.includeContent),
          ),
        };
      },
      // With includeContent, history can contain current + previous source and
      // repeat both in the diff, so it needs more headroom than get-extension.
      maxResultChars: GET_EXTENSION_HISTORY_MAX_RESULT_CHARS,
      readOnly: true,
    },

    "render-inline-extension": {
      tool: {
        description:
          "Render a one-time, transient sandboxed Alpine.js mini-app directly inside the chat. Use this for generated UI that should answer the current turn inline without saving anything to the Extensions view: calculators, adjustable controls, knobs, pickers, visualizers, temporary dashboards, and interactive results. The content must be a self-contained Alpine.js HTML body snippet that can use appAction(), appFetch(), dbQuery(), extensionFetch(), extensionData, agentNative.ui.output(value, opts?), and agentNative.chat.send()/sendToAgentChat(). Use appAction() or extensionData for writes; dbQuery() is for read-only inspection of known app SQL tables. Use agentNative.ui.output for passive current values from knobs, sliders, and selections; it writes application state at inline-ui:<inline extension id>:output, which the agent can read later with readAppState when the user says to use that value. Use agentNative.chat.send for visible submit/apply actions. For transient UIs, extensionData is browser-local throwaway state; use application_state/appFetch, appAction, ui.output, or chat.send for anything the agent or app must observe. Use semantic Tailwind colors (bg-background, text-foreground, bg-primary, etc.) so it inherits the parent app theme. Use create-extension instead when the user wants the UI saved or reusable.",
        parameters: {
          type: "object",
          properties: {
            name: {
              type: "string",
              description: "Short display name for the inline UI.",
            },
            description: {
              type: "string",
              description: "One-sentence summary of what the inline UI does.",
            },
            content: {
              type: "string",
              description:
                "Self-contained Alpine.js HTML body snippet. Do not include a full app build, React code, or source files. Required unless contentFromAttachment is set.",
            },
            contentFromAttachment: {
              type: "string",
              description:
                'Render a pasted/attached HTML file verbatim without re-typing it. Set to an attachment name or "latest".',
            },
            context: {
              type: "string",
              description:
                "Optional JSON object passed to the iframe as slotContext for initial inputs from chat.",
            },
            initialHeight: {
              type: "number",
              description:
                "Optional initial iframe height in pixels before auto-resize reports. Defaults to 260.",
            },
          },
          required: ["name"],
        },
      },
      chatUI: {
        renderer: ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER,
        title: "Inline extension",
      },
      maxResultChars: 220_000,
      readOnly: true,
      run: async (args, ctx) => {
        const name = String(args?.name ?? "").trim();
        if (!name) return "Error: name is required.";
        const resolved = resolveExtensionContent(args, ctx);
        if ("error" in resolved) return resolved.error;
        const content = resolved.content.trim();
        if (!content) return "Error: content is required.";
        const description = String(args?.description ?? "").trim();
        const id = `inline-${Date.now().toString(36)}-${Math.random()
          .toString(36)
          .slice(2, 8)}`;
        return {
          ok: true,
          inlineExtension: {
            mode: "transient",
            id,
            name,
            description,
            content,
            context: parseInlineContext(args?.context),
            initialHeight: coerceInlineHeight(args?.initialHeight),
          },
          next: "Rendered inline in chat only. It is not saved in the Extensions view.",
        };
      },
    },

    "show-extension-inline": {
      tool: {
        description:
          "Render an existing saved extension inline in the chat. Use this when the user asks to load, reopen, reuse, or show a saved extension/widget/dashboard/calculator/mini-app in the conversation. Inline extensions can expose passive current values through agentNative.ui.output(value, opts?), which writes application state at inline-ui:<extension id>:output for the agent to read later with readAppState. Pass id when known; otherwise pass a search string and the action will use the best visible extension match.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "Extension id to render inline.",
            },
            search: {
              type: "string",
              description:
                "Fallback search matched against id, name, description, and owner email when id is unknown.",
            },
            context: {
              type: "string",
              description:
                "Optional JSON object passed to the iframe as slotContext for chat-provided inputs.",
            },
            initialHeight: {
              type: "number",
              description:
                "Optional initial iframe height in pixels before auto-resize reports. Defaults to 260.",
            },
          },
        },
      },
      chatUI: {
        renderer: ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER,
        title: "Inline extension",
      },
      readOnly: true,
      run: async (args) => {
        let id = String(args?.id ?? "").trim();
        const search = String(args?.search ?? "")
          .trim()
          .toLowerCase();

        if (!id && search) {
          const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
          const rows: Array<ExtensionRow | LocalExtensionRow> = [
            ...(await listExtensions({
              includeHidden: false,
              includeGloballyHidden: false,
            })),
            ...(await listLocalExtensions()),
          ];
          const match = rows.find((row) =>
            [row.id, row.name, row.description, row.ownerEmail]
              .join("\n")
              .toLowerCase()
              .includes(search),
          );
          if (match) {
            id = match.id;
          } else {
            return {
              ok: false,
              error: `No extension matched "${args?.search}".`,
              available: await Promise.all(
                rows
                  .slice(0, 10)
                  .map((row) => summarizeExtension(row, hiddenIds, false)),
              ),
            };
          }
        }

        if (!id) return "Error: provide id or search.";

        const localExtension = await getLocalExtension(id);
        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
        if (localExtension) {
          const summary = await summarizeExtension(
            localExtension,
            hiddenIds,
            false,
          );
          return {
            ok: true,
            inlineExtension: {
              mode: "persisted",
              id: summary.id,
              name: summary.name,
              description: summary.description,
              path: summary.path,
              updatedAt: summary.updatedAt,
              context: parseInlineContext(args?.context),
              initialHeight: coerceInlineHeight(args?.initialHeight),
            },
          };
        }

        const extension = await getExtension(id);
        if (!extension) return `Error: extension not found: ${id}`;
        const summary = await summarizeExtension(extension, hiddenIds, false);
        return {
          ok: true,
          inlineExtension: {
            mode: "persisted",
            id: summary.id,
            name: summary.name,
            description: summary.description,
            path: summary.path,
            updatedAt: summary.updatedAt,
            context: parseInlineContext(args?.context),
            initialHeight: coerceInlineHeight(args?.initialHeight),
          },
        };
      },
    },

    "create-extension": {
      tool: {
        description:
          'Create a persisted sandboxed Alpine.js mini-app extension and render it inline in the chat. Use this when the user wants generated UI that should be saved, reusable, or visible in the Extensions view: extensions, widgets, dashboards, calculators, mini-apps, and reusable interactive utilities. For one-time chat-only UI, use render-inline-extension instead. The content must be a self-contained Alpine.js HTML body snippet that can use appAction(), appFetch(), dbQuery(), extensionFetch(), extensionData, agentNative.ui.output(value, opts?), and agentNative.chat.send()/sendToAgentChat(). Use appAction() for app data writes and extensionData for extension-owned persisted UI state; dbQuery() is for read-only inspection of known app SQL tables. Use agentNative.ui.output for passive current values from knobs, sliders, and selections; it writes application state at inline-ui:<extension id>:output, which the agent can read later with readAppState when the user says to use that value. Use agentNative.chat.send for visible submit/apply actions. Persist reusable user-edited state with extensionData: if the extension has checkboxes, todos, notes, filters, preferences, or any control whose value should survive reload/reopen, load that state on init and save changes with extensionData, usually at user scope, instead of keeping it only in Alpine state. IMPORTANT — hosting a pasted file: if the user pasted a large HTML/Alpine file (it appears in your context as an <attachment name="pasted-text-…"> block) and asked you to host it as-is, do NOT copy that file into `content`. Instead leave `content` empty and pass `contentFromAttachment` set to that attachment\'s name (or the literal "latest" for the most recent pasted block) — the server reads the file verbatim. Re-emitting a large pasted file as `content` regularly gets cut off mid-stream and stalls the turn. IMPORTANT — cloning a large extension that lives as a workspace resource (not a chat attachment): leave `content` empty and pass `contentFromWorkspaceFile` set to the resource path (e.g. "intuit-analytics-extension.html"); the server reads the full file. Do NOT try to reconstruct the body with run-code or route create-extension through run-code (mutating actions are not callable there). Prefer appAction(name, params) for app data and actions, including read actions mounted as GET; do not call template /api/* routes from appFetch because the extension bridge only allows framework /_agent-native/* paths. Parse JSON string action results before aggregating; use dbQuery() only for known existing SQL tables and never for writes. Keep the initial create-extension payload compact and working; for complex extensions, create a useful v1 first, then use focused update-extension edits for refinements rather than assembling one enormous initial tool input. For any non-trivial component (more than a couple of state fields, any methods, any string formatting, any branching) put the component in a <script> block via Alpine.data(\'name\', () => ({...})) and reference it with x-data="name" — do NOT cram methods, template literals, or branching logic into an inline x-data="{...}" attribute (HTML parser pitfalls cause ReferenceError failures). Define every variable referenced from x-text/x-show/x-if/x-for on the data object\'s initial state. If the extension\'s value depends on an LLM call, require a real key via \\${keys.OPENAI_API_KEY}/\\${keys.ANTHROPIC_API_KEY} (and tell the user to add it in the Dispatch Vault, or in app Settings → API Keys & Connections for standalone apps, if missing) or route the AI work to the agent chat — never ship a stubbed analysis step that renders a placeholder/boolean as the result.',
        parameters: {
          type: "object",
          properties: {
            name: {
              type: "string",
              description:
                'Short display name for the extension. Do not include "app" — e.g. name a todo app "Todos", a weather app "Weather".',
            },
            description: {
              type: "string",
              description: "One-sentence summary of what the extension does.",
            },
            content: {
              type: "string",
              description:
                "Self-contained Alpine.js HTML body snippet. The iframe canvas already has modest default padding, so avoid duplicate outer padding unless the design needs it. Use semantic Tailwind colors (bg-background, text-foreground, bg-primary, etc.) for native theming. Do not include a full app build, React code, or source files. Required UNLESS you pass contentFromAttachment instead.",
            },
            contentFromAttachment: {
              type: "string",
              description:
                'Host a pasted/attached file verbatim WITHOUT re-typing it. Set this to the name of an attachment on the current turn (e.g. "pasted-text-1718000000000-ab12cd.txt") or the literal "latest" for the most recent pasted block; the server resolves it into the extension content. Use this instead of `content` whenever the user pasted a large file to host — it avoids re-emitting thousands of tokens. When set, leave `content` empty.',
            },
            contentFromWorkspaceFile: {
              type: "string",
              description:
                'Host a workspace/shared resource file verbatim WITHOUT re-typing it. Set this to the resource path (e.g. "intuit-analytics-extension.html"); the server reads the full file and uses it as the extension content. Use this — NOT run-code or contentFromAttachment — when cloning a large extension body that already exists as a workspace resource. When set, leave `content` empty.',
            },
            icon: {
              type: "string",
              description: "Optional icon name or short label.",
            },
          },
          required: ["name"],
        },
      },
      chatUI: {
        renderer: ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER,
        title: "Extension",
      },
      run: async (args, ctx) => {
        const name = String(args?.name ?? "").trim();
        if (!name) return "Error: name is required.";
        const resolved = await resolveExtensionContentAsync(args, ctx);
        if ("error" in resolved) return resolved.error;
        const content = resolved.content.trim();
        if (!content) return "Error: content is required.";
        const description = String(args?.description ?? "").trim();
        const icon = args?.icon ? String(args.icon) : undefined;

        // Idempotency: if an identical extension was created in the last 5
        // minutes (e.g. a connection drop caused the agent to retry this tool
        // call), return the existing one instead of creating a duplicate.
        // Keyed on the FULL create inputs (name + content + description + icon),
        // so two creates that differ in ANY of them are treated as distinct
        // rather than silently collapsed — only a byte-identical re-create (the
        // retry case) recovers the existing row.
        const existing = await findRecentDuplicateExtension({
          name,
          content,
          description,
          icon,
        });
        if (existing) {
          const existingPath = extensionPath(existing.id, existing.name);
          try {
            await writeAppState("navigate", {
              view: "extensions",
              extensionId: existing.id,
              path: existingPath,
              _writeId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
            });
          } catch {
            // Non-fatal — agent can still mention the path in its reply.
          }
          const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
          return {
            ok: true,
            // Compact summary (contentLength + contentHash, no full body). Echoing
            // the whole HTML back is pure token waste — the agent just supplied it.
            extension: await summarizeExtension(existing, hiddenIds, false),
            path: existingPath,
            next: `Extension was already created in this session (recovered from a connection retry). The user is being navigated to it — no further navigation tool calls needed.`,
          };
        }

        const extension = await createExtension({
          name,
          description,
          content,
          icon,
        });
        const path = extensionPath(extension.id, extension.name);

        // Auto-navigate so the user lands on the new extension instead of
        // having to read the JSON response and click a link. Writes a
        // one-shot `navigate` app-state command the UI consumes and clears.
        try {
          await writeAppState("navigate", {
            view: "extensions",
            extensionId: extension.id,
            path,
            // Unique-per-write token so the UI's `use-navigation-state` hook
            // can dedup race-driven re-reads of the same command.
            _writeId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
          });
        } catch {
          // Non-fatal — agent can still mention the path in its reply.
        }

        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
        return {
          ok: true,
          // Compact summary (contentLength + contentHash, no full body). Echoing
          // the whole HTML back is pure token waste — the agent just supplied it.
          extension: await summarizeExtension(extension, hiddenIds, false),
          path,
          next: `Created. The user is being navigated to the new extension automatically — no further navigation tool calls needed.`,
        };
      },
    },

    "update-extension": {
      tool: {
        description:
          'Update an existing sandboxed Alpine.js mini-app extension. Pass exactly three fields: `id`, `operation`, and `payloadJson`. `payloadJson` is a JSON object encoded as a string so model gateways cannot fill its optional members with invalid empty placeholders. For operation="edit", pass {"edits":[...]} or {"patches":[...]} and optional format=true. For operation="replace", pass exactly one of content, contentFromAttachment, or contentFromWorkspaceFile; use this operation only for a user-requested broad visual rewrite or complete replacement body. For operation="metadata", pass name, description, or icon. Change sharing through set-resource-visibility instead. If the user is viewing the extension, use the extensionId from <current-screen> or <current-url> directly.',
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description:
                "Extension id to update. Prefer the extensionId from <current-screen> or <current-url> for the current extension.",
            },
            operation: {
              type: "string",
              enum: ["edit", "replace", "metadata"],
              description:
                'The single update mode: "edit" for focused patches/edits, "replace" for an explicitly authorized complete body replacement, or "metadata" for name/description/icon.',
            },
            payloadJson: {
              type: "string",
              minLength: 2,
              description:
                'A non-empty JSON object encoded as a string. edit example: {"edits":[{"op":"replace","find":"old","replace":"new"}],"format":true}. replace example: {"contentFromAttachment":"latest"}. metadata example: {"name":"New name"}.',
            },
          },
          required: ["id", "operation", "payloadJson"],
          additionalProperties: false,
        },
      },
      run: async (args, ctx) => {
        const normalizedUpdate = normalizeUpdateExtensionArgs(args);
        if ("error" in normalizedUpdate) return normalizedUpdate.error;
        args = normalizedUpdate.args;
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        if (
          args?.name !== undefined &&
          (typeof args.name !== "string" || args.name.trim().length === 0)
        ) {
          return "Error: extension name must be a non-empty string. No changes were applied.";
        }
        const localMessage = await localExtensionEditMessage(id);
        if (localMessage) return localMessage;

        if (
          typeof args?.visibility === "string" &&
          args.visibility.trim().toLowerCase() === "public"
        ) {
          const message =
            "Public extension sharing is not supported. Use visibility=private or visibility=org. No content changes were applied; do not retry visibility=public.";
          throw new AgentActionStopError(message, {
            errorCode: "extension_public_visibility_unsupported",
            toolResult: JSON.stringify(
              {
                error: "extension_public_visibility_unsupported",
                message,
                recoverable: false,
                next: "Retry only with visibility=private or visibility=org.",
              },
              null,
              2,
            ),
          });
        }

        const attachmentRef =
          typeof args?.contentFromAttachment === "string"
            ? args.contentFromAttachment.trim()
            : "";
        const workspaceFileRef =
          typeof args?.contentFromWorkspaceFile === "string"
            ? args.contentFromWorkspaceFile.trim()
            : "";
        const fullReplacementRequested =
          (typeof args?.content === "string" &&
            args.content.trim().length > 0) ||
          attachmentRef.length > 0 ||
          workspaceFileRef.length > 0;
        if (
          fullReplacementRequested &&
          !coerceBoolean(args?.allowFullReplacement)
        ) {
          const message =
            "Full extension-body replacement requires allowFullReplacement=true. No changes were applied. If the user's request includes a broad visual rewrite such as changing layout, compactness, visible sections, naming, or padding, retry once with allowFullReplacement=true; otherwise read the current extension and use focused patches/edits for a data-only repair. Do not retry unchanged arguments.";
          throw new ExtensionContentEditError(message);
        }

        // Full-replacement content can come inline (`content`) or by reference
        // (`contentFromAttachment`) so the model never has to re-type a large
        // pasted file. Inline wins only when NON-EMPTY — the docstring tells
        // callers to leave `content` empty when using `contentFromAttachment`,
        // so an empty/blank `content` must fall through to the attachment
        // instead of blanking the extension (mirrors resolveExtensionContent).
        let replacementContent =
          typeof args?.content === "string" && args.content.trim().length > 0
            ? args.content
            : undefined;
        if (
          replacementContent === undefined &&
          (attachmentRef.length > 0 || workspaceFileRef.length > 0)
        ) {
          const resolved = await resolveExtensionContentAsync(args, ctx);
          if ("error" in resolved) return resolved.error;
          replacementContent = resolved.content;
        }

        let result = null;
        const patches = parsePatches((args as any).patches);
        if (args?.patches !== undefined && !patches) {
          return "Error: patches must be a JSON array of { find, replace } objects.";
        }
        const edits = parseEdits((args as any).edits);
        if (args?.edits !== undefined && !edits) {
          return "Error: edits must be a JSON array of supported extension edit operations.";
        }
        const hasContentUpdate =
          replacementContent !== undefined ||
          (patches?.length ?? 0) > 0 ||
          (edits?.length ?? 0) > 0 ||
          coerceBoolean(args?.format);
        if (hasContentUpdate) {
          try {
            result = await updateExtensionContent(id, {
              content: replacementContent,
              allowFullReplacement: coerceBoolean(args?.allowFullReplacement),
              patches,
              edits,
              format: coerceBoolean(args?.format),
            });
          } catch (error) {
            if (!(error instanceof ExtensionContentEditError)) throw error;
            const message =
              `The extension edit was not applied: ${error.message} ` +
              "Do not retry the same arguments. Read the current extension and submit one focused patch or edit with an exact target.";
            throw new AgentActionStopError(message, {
              errorCode: "extension_content_edit_failed",
              toolResult: JSON.stringify(
                {
                  error: "extension_content_edit_failed",
                  message: error.message,
                  recoverable: false,
                  next: "Read the current extension with get-extension, then make one focused update-extension patches/edits call. Do not retry unchanged arguments.",
                },
                null,
                2,
              ),
            });
          }
        }

        const meta: Record<string, string> = {};
        if (args?.name !== undefined) meta.name = String(args.name).trim();
        if (args?.description !== undefined) {
          meta.description = String(args.description).trim();
        }
        if (args?.icon !== undefined) meta.icon = String(args.icon);
        if (args?.visibility !== undefined)
          meta.visibility = String(args.visibility);
        if (Object.keys(meta).length > 0) {
          result = await updateExtension(id, meta as any);
        }

        if (!result && !hasContentUpdate && Object.keys(meta).length === 0) {
          return "Error: update-extension received no actual changes. Choose one operation and provide a non-empty payloadJson object; empty placeholder fields are not an update.";
        }
        if (!result) result = await getExtension(id);
        if (!result) return `Error: extension not found: ${id}`;
        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
        return {
          ok: true,
          extension: await summarizeExtension(result, hiddenIds, false),
        };
      },
    },

    "extension-data-set": {
      tool: {
        description:
          "Write a value to an extension's extensionData store (the tool_data table) from the agent side. Use this when the agent needs to update or seed data that an extension reads via extensionData.get() at render time. Requires editor access to the extension.",
        parameters: {
          type: "object",
          properties: {
            extensionId: {
              type: "string",
              description: "Extension id whose data store to write to.",
            },
            collection: {
              type: "string",
              description: "Collection name within the extension's data store.",
            },
            itemId: {
              type: "string",
              description:
                "Item id within the collection. Upserts if it already exists.",
            },
            data: {
              description:
                "The data value to store. Objects are JSON-serialized automatically.",
            },
            scope: {
              type: "string",
              enum: ["user", "org"],
              description:
                "Storage scope. 'user' (default) is private to the current user; 'org' is shared across the organization.",
            },
          },
          required: ["extensionId", "collection", "itemId", "data"],
        },
      },
      run: async (args) => {
        const extensionId = String(args?.extensionId ?? "").trim();
        const collection = String(args?.collection ?? "").trim();
        const itemId = String(args?.itemId ?? "").trim();
        if (!extensionId || !collection || !itemId)
          return "Error: extensionId, collection, and itemId are required.";
        if (args?.data === undefined) return "Error: data is required.";

        await ensureExtensionsTables();
        const access = await resolveAccess("extension", extensionId);
        if (
          !access ||
          (access.resource as ExtensionRow | undefined)?.archivedAt ||
          access.role === "viewer"
        )
          return `Error: editor access required for extension ${extensionId}.`;

        const userEmail = getRequestUserEmail()?.toLowerCase() ?? "";
        const scope = args?.scope === "org" ? "org" : "user";
        const orgId = getRequestOrgId();
        if (scope === "org" && !orgId)
          return "Error: org context required for scope=org.";

        const data =
          typeof args.data === "string" ? args.data : JSON.stringify(args.data);
        const MAX_BYTES = 1024 * 1024;
        if (Buffer.byteLength(data, "utf8") > MAX_BYTES)
          return `Error: data exceeds ${MAX_BYTES} byte limit. Store large payloads in file storage instead.`;

        const now = new Date().toISOString();
        const scopeKey = scope === "org" ? `org:${orgId}` : userEmail;
        const client = getDbExec();
        const pg = isPostgres();
        const conflictClause = pg
          ? `ON CONFLICT (tool_id, collection, scope_key, item_id)
             DO UPDATE SET data = EXCLUDED.data, updated_at = EXCLUDED.updated_at`
          : `ON CONFLICT (tool_id, collection, scope_key, item_id)
             DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`;

        await client.execute({
          sql: `UPDATE tools SET updated_at = ? WHERE id = ?`,
          args: [now, extensionId],
        });
        await client.execute({
          sql: `INSERT INTO tool_data (id, tool_id, collection, item_id, data, owner_email, scope, org_id, scope_key, created_at, updated_at)
           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
           ${conflictClause}`,
          args: [
            randomUUID(),
            extensionId,
            collection,
            itemId,
            data,
            userEmail,
            scope,
            scope === "org" ? orgId! : null,
            scopeKey,
            now,
            now,
          ],
        });
        await notifyExtensionChangeForResource(extensionId);

        return {
          ok: true,
          id: itemId,
          extensionId,
          collection,
          scope,
          updatedAt: now,
        };
      },
    },

    "extension-data-get": {
      tool: {
        description:
          "Read items from an extension's extensionData store (the tool_data table) from the agent side. Use this to inspect what data an extension currently has stored, or to verify a write succeeded. Requires viewer access to the extension.",
        parameters: {
          type: "object",
          properties: {
            extensionId: {
              type: "string",
              description: "Extension id whose data store to read from.",
            },
            collection: {
              type: "string",
              description: "Collection name within the extension's data store.",
            },
            itemId: {
              type: "string",
              description:
                "Optional specific item id. If omitted, lists all items in the collection.",
            },
            scope: {
              type: "string",
              enum: ["user", "org", "all"],
              description:
                "Storage scope to read. 'user' (default) reads the current user's items; 'org' reads organization-shared items; 'all' reads both.",
            },
            limit: {
              type: "number",
              description:
                "Maximum items to return when listing (default 100, max 1000).",
            },
          },
          required: ["extensionId", "collection"],
        },
      },
      run: async (args) => {
        const extensionId = String(args?.extensionId ?? "").trim();
        const collection = String(args?.collection ?? "").trim();
        if (!extensionId || !collection)
          return "Error: extensionId and collection are required.";

        await ensureExtensionsTables();
        const access = await resolveAccess("extension", extensionId);
        if (
          !access ||
          (access.resource as ExtensionRow | undefined)?.archivedAt
        )
          return `Error: no access to extension ${extensionId}.`;

        const userEmail = getRequestUserEmail()?.toLowerCase() ?? "";
        const scope = args?.scope ?? "user";
        const orgId = getRequestOrgId();
        if ((scope === "org" || scope === "all") && !orgId)
          return "Error: org context required for scope=org or scope=all.";
        const itemId = args?.itemId ? String(args.itemId).trim() : null;
        const limit = Math.min(Math.max(1, Number(args?.limit) || 100), 1000);
        const client = getDbExec();

        if (itemId) {
          const scopeClause =
            scope === "org"
              ? `AND scope = 'org' AND org_id = ?`
              : scope === "all"
                ? `AND ((scope = 'user' AND lower(owner_email) = ?) OR (scope = 'org' AND org_id = ?))`
                : `AND scope = 'user' AND lower(owner_email) = ?`;
          const scopeArgs =
            scope === "org"
              ? [orgId ?? ""]
              : scope === "all"
                ? [userEmail, orgId ?? ""]
                : [userEmail];

          const result = await client.execute({
            sql: `SELECT COALESCE(item_id, id) AS id, data, scope, owner_email, updated_at
              FROM tool_data
              WHERE tool_id = ? AND collection = ? AND COALESCE(item_id, id) = ? ${scopeClause}`,
            args: [extensionId, collection, itemId, ...scopeArgs],
          });
          const row = result.rows?.[0];
          if (!row) return { found: false, extensionId, collection, itemId };
          return { found: true, ...row };
        }

        const scopeClause =
          scope === "org"
            ? `AND scope = 'org' AND org_id = ?`
            : scope === "all"
              ? `AND ((scope = 'user' AND lower(owner_email) = ?) OR (scope = 'org' AND org_id = ?))`
              : `AND scope = 'user' AND lower(owner_email) = ?`;
        const scopeArgs =
          scope === "org"
            ? [orgId ?? ""]
            : scope === "all"
              ? [userEmail, orgId ?? ""]
              : [userEmail];

        const result = await client.execute({
          sql: `SELECT COALESCE(item_id, id) AS id, data, scope, owner_email, updated_at
            FROM tool_data
            WHERE tool_id = ? AND collection = ? ${scopeClause}
            ORDER BY updated_at DESC
            LIMIT ?`,
          args: [extensionId, collection, ...scopeArgs, limit],
        });
        return {
          extensionId,
          collection,
          scope,
          count: result.rows?.length ?? 0,
          items: result.rows ?? [],
        };
      },
    },

    "delete-extension": {
      tool: {
        description:
          "Archive an extension everywhere it is shared. Archiving is a soft delete: the extension and its history, data, sharing, and slot configuration are retained, but it disappears from normal lists. Requires owner/admin access. If the user only wants a shared extension removed from their own sidebar/list, use hide-extension instead.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description:
                "Extension id to archive. Use list-extensions first if you only know the display name.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionEditMessage(id);
        if (localMessage) return localMessage;
        const extension = await getExtension(id);
        if (!extension) return `Error: extension not found: ${id}`;

        try {
          const ok = await deleteExtension(id);
          if (!ok) return `Error: extension not found: ${id}`;
          return { ok: true, archived: summarizeDeletedExtension(extension) };
        } catch (err: any) {
          return {
            ok: false,
            error: err?.message ?? String(err),
            next: "If the user wants this gone only from their own view, call hide-extension with the same id.",
          };
        }
      },
    },

    "restore-extension-history-version": {
      tool: {
        description:
          "Restore an extension's name, description, icon, and HTML content from a saved history version. Requires editor access. This does not restore sharing visibility or ownership.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "Extension id to restore.",
            },
            version: {
              type: "number",
              description:
                "Saved history version number to restore. Use list-extension-history first if unsure.",
            },
          },
          required: ["id", "version"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionReadonlyHistoryMessage(id);
        if (localMessage) return localMessage;
        const version = Number(args?.version);
        if (!Number.isInteger(version) || version < 1) {
          return "Error: version must be a positive integer.";
        }
        const result = await restoreExtensionHistoryVersion(id, version);
        if (!result) {
          return `Error: extension history version not found: ${id}#${version}`;
        }
        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
        return {
          ok: true,
          restoredVersion: version,
          extension: await summarizeExtension(result, hiddenIds, false),
        };
      },
    },

    "hide-extension": {
      tool: {
        description:
          "Hide an accessible extension from the current user's Extensions list/sidebar without deleting it for anyone else. Use this when the user says to remove a shared extension from their view, or when delete-extension reports that the current user is not owner/admin.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description:
                "Extension id to hide for the current user. Use list-extensions first if you only know the display name.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionEditMessage(id);
        if (localMessage) return localMessage;
        const extension = await getExtension(id);
        if (!extension) return `Error: extension not found: ${id}`;

        await hideExtension(id);
        return { ok: true, hidden: summarizeDeletedExtension(extension) };
      },
    },

    "unhide-extension": {
      tool: {
        description:
          "Restore an extension the current user previously hid so it appears in their Extensions list/sidebar again. Use list-extensions with includeHidden=true to find hidden ids.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "Extension id to restore for the current user.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionEditMessage(id);
        if (localMessage) return localMessage;
        await unhideExtension(id);
        return { ok: true, id };
      },
    },

    "global-hide-extension": {
      tool: {
        description:
          "Globally hide an extension from EVERYONE's Extensions list/sidebar (not just the current user) by stamping it hidden. Requires owner/admin access. Use this for an admin takedown of a shared/org extension. The extension is not deleted and stays accessible by id; use global-unhide-extension to reverse. For removing an extension only from your own view, use hide-extension instead.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description:
                "Extension id to hide for everyone. Use list-extensions first if you only know the display name.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionEditMessage(id);
        if (localMessage) return localMessage;
        const extension = await getExtension(id);
        if (!extension) return `Error: extension not found: ${id}`;

        await globalHideExtension(id);
        return {
          ok: true,
          globallyHidden: summarizeDeletedExtension(extension),
        };
      },
    },

    "global-unhide-extension": {
      tool: {
        description:
          "Reverse a global hide so the extension reappears in everyone's Extensions list/sidebar again. Requires owner/admin access. Use list-extensions with includeGloballyHidden=true to find globally-hidden ids.",
        parameters: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "Extension id to unhide for everyone.",
            },
          },
          required: ["id"],
        },
      },
      run: async (args) => {
        const id = String(args?.id ?? "").trim();
        if (!id) return "Error: id is required.";
        const localMessage = await localExtensionEditMessage(id);
        if (localMessage) return localMessage;
        await globalUnhideExtension(id);
        return { ok: true, id };
      },
    },

    "add-extension-slot-target": {
      tool: {
        description:
          'Declare that an extension can render in a UI extension-point slot of an app (e.g. "mail.contact-sidebar.bottom"). Apps drop ExtensionSlot components in their UI; this action registers an extension as installable into one of those slots. Slot IDs follow the convention <app>.<area>.<position>. Caller must have editor access to the extension.',
        parameters: {
          type: "object",
          properties: {
            extensionId: { type: "string", description: "Extension id." },
            slotId: {
              type: "string",
              description:
                'Slot identifier — e.g. "mail.contact-sidebar.bottom".',
            },
            config: {
              type: "string",
              description:
                "Optional JSON string with slot-specific config (defaults, hints, etc.).",
            },
          },
          required: ["extensionId", "slotId"],
        },
      },
      run: async (args) => {
        const extensionId = String(args?.extensionId ?? "").trim();
        const slotId = String(args?.slotId ?? "").trim();
        if (!extensionId) return "Error: extensionId is required.";
        if (!slotId) return "Error: slotId is required.";
        const localMessage = await localExtensionEditMessage(extensionId);
        if (localMessage) return localMessage;
        const row = await addExtensionSlotTarget(
          extensionId,
          slotId,
          args?.config ? String(args.config) : undefined,
        );
        return { ok: true, slot: row };
      },
    },

    "install-extension": {
      tool: {
        description:
          "Install an extension as a widget in an extension-point slot for the current user. The extension must already declare the slot via add-extension-slot-target. Per-user installation — only affects the calling user's view. Use after creating an extension that targets a slot, or when the user asks to add an existing widget to a slot.",
        parameters: {
          type: "object",
          properties: {
            extensionId: {
              type: "string",
              description: "Extension id to install.",
            },
            slotId: {
              type: "string",
              description:
                'Slot identifier — e.g. "mail.contact-sidebar.bottom".',
            },
            position: {
              type: "number",
              description:
                "Optional integer position within the slot (lower = earlier). Defaults to end.",
            },
            config: {
              type: "string",
              description:
                "Optional JSON string with per-install config (overrides, settings).",
            },
          },
          required: ["extensionId", "slotId"],
        },
      },
      run: async (args) => {
        const extensionId = String(args?.extensionId ?? "").trim();
        const slotId = String(args?.slotId ?? "").trim();
        if (!extensionId) return "Error: extensionId is required.";
        if (!slotId) return "Error: slotId is required.";
        const localMessage = await localExtensionEditMessage(extensionId);
        if (localMessage) return localMessage;
        const position =
          args?.position !== undefined && args.position !== null
            ? Number(args.position)
            : undefined;
        const row = await installExtensionSlot(extensionId, slotId, {
          position: Number.isFinite(position as number) ? position : undefined,
          config: args?.config ? String(args.config) : undefined,
        });
        return { ok: true, install: row };
      },
    },

    "uninstall-extension": {
      tool: {
        description:
          "Remove an extension from an extension-point slot for the current user. Does not delete the extension itself.",
        parameters: {
          type: "object",
          properties: {
            extensionId: { type: "string", description: "Extension id." },
            slotId: { type: "string", description: "Slot identifier." },
          },
          required: ["extensionId", "slotId"],
        },
      },
      run: async (args) => {
        const extensionId = String(args?.extensionId ?? "").trim();
        const slotId = String(args?.slotId ?? "").trim();
        if (!extensionId) return "Error: extensionId is required.";
        if (!slotId) return "Error: slotId is required.";
        const localMessage = await localExtensionEditMessage(extensionId);
        if (localMessage) return localMessage;
        await uninstallExtensionSlot(extensionId, slotId);
        return { ok: true };
      },
    },

    "list-extensions-for-slot": {
      tool: {
        description:
          "List extensions the current user has access to that declare a given extension-point slot. Use to discover what's available to install into a slot the user mentioned.",
        parameters: {
          type: "object",
          properties: {
            slotId: { type: "string", description: "Slot identifier." },
          },
          required: ["slotId"],
        },
      },
      run: async (args) => {
        const slotId = String(args?.slotId ?? "").trim();
        if (!slotId) return "Error: slotId is required.";
        return { extensions: await listExtensionsForSlot(slotId) };
      },
      readOnly: true,
    },

    "list-extension-slots": {
      tool: {
        description:
          "List the extension-point slots a specific extension declares it can render in. Caller must have viewer access to the extension.",
        parameters: {
          type: "object",
          properties: {
            extensionId: { type: "string", description: "Extension id." },
          },
          required: ["extensionId"],
        },
      },
      run: async (args) => {
        const extensionId = String(args?.extensionId ?? "").trim();
        if (!extensionId) return "Error: extensionId is required.";
        return { slots: await listSlotsForExtension(extensionId) };
      },
      readOnly: true,
    },
  };
}

async function summarizeExtension(
  row: ExtensionRow | LocalExtensionRow,
  hiddenIds: Set<string>,
  includeContent: boolean,
) {
  const local = isLocalExtensionRow(row);
  const access = local
    ? ({ role: "viewer" } as const)
    : await resolveAccess("extension", row.id).catch(() => null);
  return {
    id: row.id,
    name: row.name,
    path: extensionPath(row.id, row.name),
    description: row.description,
    icon: row.icon,
    ownerEmail: row.ownerEmail,
    visibility: row.visibility,
    role: access?.role ?? null,
    canEdit: access
      ? ["owner", "admin", "editor"].includes(access.role)
      : false,
    canDelete: access ? ["owner", "admin"].includes(access.role) : false,
    hidden: hiddenIds.has(row.id),
    globallyHidden: row.hiddenAt != null,
    hiddenAt: row.hiddenAt,
    hiddenBy: row.hiddenBy,
    createdAt: row.createdAt,
    updatedAt: row.updatedAt,
    contentLength: row.content.length,
    contentHash: contentFingerprint(row.content),
    ...(local ? { source: row.source } : {}),
    ...(includeContent ? { content: row.content } : {}),
  };
}

async function summarizeExtensionForAgentRead(
  row: ExtensionRow | LocalExtensionRow,
  hiddenIds: Set<string>,
  includeContent: boolean,
  forceContent: boolean,
) {
  if (!includeContent) {
    return summarizeExtension(row, hiddenIds, false);
  }

  const fingerprint = contentFingerprint(row.content);
  const runCtx = getRequestRunContext();
  const reads = runCtx ? (runCtx.extensionContentReads ??= {}) : undefined;
  const alreadySent = !forceContent && reads?.[row.id] === fingerprint;
  if (!alreadySent && reads) {
    reads[row.id] = fingerprint;
  }

  const summary = await summarizeExtension(row, hiddenIds, !alreadySent);
  if (!alreadySent) return summary;

  return {
    ...summary,
    contentOmitted: {
      reason: "unchanged-content-already-returned-this-run",
      contentHash: fingerprint,
      contentLength: row.content.length,
      next: 'Use the content already returned earlier in this run and call update-extension with operation="edit" plus focused edits/patches inside payloadJson. Set forceContent=true only if you truly need the full body again.',
    },
  };
}

function compactExtensionHistoryDetail(
  detail: ExtensionHistoryDetail,
  includeContent: boolean,
): ExtensionHistoryDetail & {
  diffOmitted?: { omittedLines: number; maxLines: number };
} {
  const diffMaxLines = 400;
  const fullDiff = detail.diff ?? [];
  const diff =
    fullDiff.length > diffMaxLines
      ? [...fullDiff.slice(0, 200), ...fullDiff.slice(fullDiff.length - 200)]
      : fullDiff;
  return {
    ...detail,
    entry: compactHistoryEntry(detail.entry, includeContent),
    previous: detail.previous
      ? compactHistoryEntry(detail.previous, includeContent)
      : null,
    diff,
    ...(fullDiff.length > diff.length
      ? {
          diffOmitted: {
            omittedLines: fullDiff.length - diff.length,
            maxLines: diffMaxLines,
          },
        }
      : {}),
  };
}

function compactHistoryEntry(
  entry: ExtensionHistoryEntry,
  includeContent: boolean,
): ExtensionHistoryEntry & { contentHash?: string } {
  const content = entry.content ?? "";
  const withHash = {
    ...entry,
    ...(content ? { contentHash: contentFingerprint(content) } : {}),
  };
  if (includeContent) return withHash;
  const { content: _content, ...withoutContent } = withHash;
  return withoutContent;
}

function contentFingerprint(content: string): string {
  let hash = 5381;
  for (let i = 0; i < content.length; i++) {
    hash = (hash * 33) ^ content.charCodeAt(i);
  }
  return `${content.length.toString(36)}-${(hash >>> 0).toString(36)}`;
}

async function localExtensionEditMessage(id: string): Promise<string | null> {
  const localExtension = await getLocalExtension(id);
  if (!localExtension) return null;
  return `Error: extension "${id}" is backed by local files at ${localExtension.source.entryPath}. Edit that file or ${localExtension.source.manifestPath} in the workspace instead of using SQL-backed extension actions.`;
}

async function localExtensionReadonlyHistoryMessage(
  id: string,
): Promise<string | null> {
  const localExtension = await getLocalExtension(id);
  if (!localExtension) return null;
  return `Error: extension "${id}" is backed by local files at ${localExtension.source.entryPath}. Use Git or your editor's file history for versions.`;
}

function summarizeDeletedExtension(row: ExtensionRow) {
  return {
    id: row.id,
    name: row.name,
    ownerEmail: row.ownerEmail,
    visibility: row.visibility,
  };
}

/**
 * Filename prefix the composer stamps on a "Pasted text" attachment chip
 * (`createPastedTextFile` in `client/composer/pasted-text.ts`). The agent sees
 * these as `<attachment name="pasted-text-…">` blocks, so a model hosting a
 * pasted file can reference it by that name via `contentFromAttachment`.
 */
const PASTED_TEXT_ATTACHMENT_PREFIX = "pasted-text-";

/** Keyword refs that mean "use the most recent pasted block above". */
const LATEST_ATTACHMENT_KEYWORDS = new Set([
  "latest",
  "last",
  "paste",
  "pasted",
  "pasted-text",
  "attachment",
  "above",
]);

/** Strip the `<attachment …>\n…\n</attachment>` wrapper if one is present. */
function unwrapAttachmentEnvelope(text: string): string {
  const match = text.match(/^<attachment\b[^>]*>\n([\s\S]*)\n<\/attachment>$/);
  return match ? match[1] : text;
}

/**
 * Resolve the HTML body for create/update-extension from either the inline
 * `content` argument or a `contentFromAttachment` handle pointing at a pasted /
 * uploaded text attachment on the current turn. The by-reference path lets the
 * model host a large pasted file without re-emitting it as a tool argument —
 * which frequently gets cut off mid-stream and triggers a continuation loop.
 *
 * Resolution is forgiving: an exact attachment-name match wins, then a keyword
 * ("latest"/"pasted"/…) or a near-miss name falls back to the most recent
 * pasted-text attachment (or the only text attachment).
 */
function resolveExtensionContent(
  args: Record<string, string> | undefined,
  ctx: ActionRunContext | undefined,
): { content: string } | { error: string } {
  const inline = args?.content !== undefined ? String(args.content) : undefined;
  if (inline !== undefined && inline.trim().length > 0) {
    return { content: inline };
  }

  const ref =
    args?.contentFromAttachment !== undefined
      ? String(args.contentFromAttachment).trim()
      : "";
  if (!ref) {
    return {
      error:
        "Error: provide either content (inline Alpine.js HTML) or contentFromAttachment (the name of a pasted/attached file to host verbatim).",
    };
  }

  const textAttachments = (ctx?.attachments ?? []).filter(
    (att): att is AgentChatAttachment & { text: string } =>
      typeof att.text === "string" && att.text.trim().length > 0,
  );
  if (textAttachments.length === 0) {
    return {
      error:
        "Error: contentFromAttachment was set but this turn has no readable text attachment. Re-send the file as an attachment, or pass the HTML inline via content.",
    };
  }

  const lower = ref.toLowerCase();
  let match = textAttachments.find(
    (att) => (att.name ?? "").trim().toLowerCase() === lower,
  );
  if (!match) {
    const pasted = textAttachments.filter((att) =>
      (att.name ?? "").startsWith(PASTED_TEXT_ATTACHMENT_PREFIX),
    );
    const pool = pasted.length > 0 ? pasted : textAttachments;
    if (
      LATEST_ATTACHMENT_KEYWORDS.has(lower) ||
      pasted.length === 1 ||
      textAttachments.length === 1
    ) {
      match = pool[pool.length - 1];
    }
  }

  if (!match) {
    const names = textAttachments
      .map((att) => att.name || "(unnamed)")
      .join(", ");
    return {
      error: `Error: no attachment matched contentFromAttachment="${ref}". Available text attachments: ${names}. Pass one of those names exactly, or "latest" for the most recent pasted block.`,
    };
  }

  const resolved = unwrapAttachmentEnvelope(match.text);
  // Fail fast instead of hosting corrupted content. The client caps an
  // outbound attachment at MAX_OUTBOUND_ATTACHMENT_CHARS (200k) and appends a
  // trailing notice ending "...omitted from the submitted attachment.]" (see
  // truncateOutboundAttachment in agent-chat-adapter.ts). Hosting that verbatim
  // would bake a half file + the notice into the extension body; reject it with
  // an actionable message so the user shrinks/splits the file instead.
  if (/omitted from the submitted attachment\.\]\s*$/.test(resolved)) {
    return {
      error:
        "Error: the pasted file is too large to host verbatim (it was truncated above 200,000 characters before reaching the server, so hosting it would corrupt the extension). Reduce the file or split it into smaller extensions, then try again.",
    };
  }
  return { content: resolved };
}

/**
 * Resolve the workspace-files bridge scope exactly the way run-code's
 * workspaceRead/workspaceWrite do: org-preferred (org → shared owner) with the
 * requesting user's email as the solo fallback. Kept in lockstep with
 * `resolveScope` in `workspace-files/tool.ts`.
 */
function workspaceFilesBridgeScope(): WorkspaceFilesScope | null {
  const orgId = getRequestOrgId();
  if (orgId) return { scope: "org", scopeId: orgId };
  const email = getRequestUserEmail();
  if (email) return { scope: "user", scopeId: email };
  return null;
}

/**
 * Read a workspace/shared/personal resource file's FULL content by path.
 *
 * Precedence (single, documented rule so this never silently resolves a
 * different file than the agent inspected):
 *   1. The run-code `workspace-files` bridge scope (org → shared owner, else the
 *      user's email). This is the SAME owner/scope `workspaceRead` /
 *      `workspaceWrite` use, so a body the agent staged via `workspaceWrite` is
 *      resolved here verbatim — the two paths cannot diverge.
 *   2. User-managed Resources (personal override → org/shared → workspace
 *      default) as a fallback, for pre-built resources that were created in the
 *      Resources panel rather than staged through the bridge.
 *
 * Unlike attachments, resource content is not capped/truncated on the way in, so
 * this is the correct path for cloning a large extension body that already
 * exists as a workspace resource (e.g. a per-customer dashboard).
 */
async function readWorkspaceFileContent(path: string): Promise<string | null> {
  const trimmed = path.trim();
  if (!trimmed) return null;
  // 1) Bridge parity — resolve exactly the file workspaceRead/workspaceWrite see.
  const bridgeScope = workspaceFilesBridgeScope();
  if (bridgeScope) {
    let bridgeFile: Awaited<ReturnType<typeof readWorkspaceFile>>;
    try {
      bridgeFile = await readWorkspaceFile(bridgeScope, trimmed);
    } catch {
      // A THROW here is a transient store error or invalid path — NOT a
      // definitive "not found". Fail closed rather than silently hosting a
      // possibly-different same-path Resources body than workspaceRead
      // inspected. A retry re-runs this read cleanly.
      return null;
    }
    // A null result means the file genuinely does not exist in the bridge scope;
    // fall through to user-managed Resources for pre-built resource-panel files.
    if (bridgeFile && typeof bridgeFile.content === "string") {
      return bridgeFile.content;
    }
  }
  // 2) Fallback — user-managed Resources by scope precedence.
  for (const scope of ["personal", "shared", "workspace"] as const) {
    try {
      const content = await readResource(trimmed, { scope });
      if (typeof content === "string") return content;
    } catch {
      // A given scope can throw (e.g. `personal` when no user identity is
      // resolvable in this context). Don't let one scope abort the lookup —
      // fall through and try the next one.
    }
  }
  return null;
}

/**
 * Resolve the extension HTML body from (in priority order) inline `content`, a
 * `contentFromWorkspaceFile` resource path, or a `contentFromAttachment` handle.
 *
 * The workspace-file path exists because a large extension body frequently lives
 * as a workspace resource (not a chat attachment). Without it the model has no
 * viable route — inline is too large to shuttle reliably, contentFromAttachment
 * only sees chat attachments, and mutating actions cannot run from run-code — so
 * it loops and the run aborts with no_progress.
 */
async function resolveExtensionContentAsync(
  args: Record<string, string> | undefined,
  ctx: ActionRunContext | undefined,
): Promise<{ content: string } | { error: string }> {
  const inline = args?.content !== undefined ? String(args.content) : undefined;
  if (inline !== undefined && inline.trim().length > 0) {
    return { content: inline };
  }

  const wsRef =
    args?.contentFromWorkspaceFile !== undefined
      ? String(args.contentFromWorkspaceFile).trim()
      : "";
  if (wsRef) {
    const content = await readWorkspaceFileContent(wsRef);
    if (content === null) {
      return {
        error: `Error: contentFromWorkspaceFile="${wsRef}" did not match any readable workspace/shared/personal resource file. Check the exact path (e.g. "intuit-analytics-extension.html"), or pass the HTML inline via content.`,
      };
    }
    if (content.trim().length === 0) {
      return {
        error: `Error: workspace file "${wsRef}" is empty. Pass non-empty HTML inline via content, or point contentFromWorkspaceFile at a file with content.`,
      };
    }
    return { content };
  }

  return resolveExtensionContent(args, ctx);
}

function coerceBoolean(value: unknown): boolean {
  return value === true || value === "true";
}

function normalizeUpdateExtensionArgs(
  args: any,
): { args: Record<string, unknown> } | { error: string } {
  const hasCompactContract =
    args?.operation !== undefined || args?.payloadJson !== undefined;
  if (!hasCompactContract) {
    const legacyArgs = { ...((args ?? {}) as Record<string, unknown>) };
    const hasInvalidPlaceholderSignal =
      (typeof legacyArgs.visibility === "string" &&
        legacyArgs.visibility.trim().length === 0) ||
      [legacyArgs.patches, legacyArgs.edits].some(
        (value) =>
          value !== null &&
          typeof value === "object" &&
          (Array.isArray(value)
            ? value.length > 0 &&
              value.every(
                (item) =>
                  item !== null &&
                  typeof item === "object" &&
                  !Array.isArray(item) &&
                  Object.keys(item).length === 0,
              )
            : Object.keys(value).length === 0),
      );
    if (hasInvalidPlaceholderSignal) {
      for (const [key, value] of Object.entries(legacyArgs)) {
        if (key === "id") continue;
        const empty =
          value === false ||
          value === null ||
          (typeof value === "string" && value.trim().length === 0) ||
          (Array.isArray(value) &&
            (value.length === 0 ||
              value.every(
                (item) =>
                  item !== null &&
                  typeof item === "object" &&
                  !Array.isArray(item) &&
                  Object.keys(item).length === 0,
              ))) ||
          (typeof value === "object" &&
            value !== null &&
            !Array.isArray(value) &&
            Object.keys(value).length === 0);
        if (empty) delete legacyArgs[key];
      }
      delete legacyArgs.visibility;
    }
    return { args: legacyArgs };
  }

  const operation = String(args?.operation ?? "").trim();
  if (!(["edit", "replace", "metadata"] as const).includes(operation as any)) {
    return {
      error:
        'Error: operation must be "edit", "replace", or "metadata". No changes were applied.',
    };
  }

  let payload: unknown;
  try {
    payload = JSON.parse(String(args?.payloadJson ?? ""));
  } catch {
    return {
      error:
        "Error: payloadJson must be a valid JSON object encoded as a string. No changes were applied.",
    };
  }
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
    return {
      error:
        "Error: payloadJson must decode to a non-empty JSON object. No changes were applied.",
    };
  }

  const payloadRecord = payload as Record<string, unknown>;
  const allowedByOperation: Record<string, Set<string>> = {
    edit: new Set(["patches", "edits", "format"]),
    replace: new Set([
      "content",
      "contentFromAttachment",
      "contentFromWorkspaceFile",
      "format",
    ]),
    metadata: new Set(["name", "description", "icon"]),
  };
  const unexpected = Object.keys(payloadRecord).filter(
    (key) => !allowedByOperation[operation].has(key),
  );
  if (unexpected.length > 0) {
    return {
      error: `Error: operation=${operation} does not accept ${unexpected.join(", ")}. No changes were applied.`,
    };
  }

  if (operation === "edit") {
    const patches = parsePatches(payloadRecord.patches);
    const edits = parseEdits(payloadRecord.edits);
    const hasEdit =
      (patches?.length ?? 0) > 0 ||
      (edits?.length ?? 0) > 0 ||
      coerceBoolean(payloadRecord.format);
    if (!hasEdit) {
      return {
        error:
          "Error: operation=edit requires at least one valid patch/edit or format=true. No changes were applied.",
      };
    }
  }

  if (operation === "replace") {
    const replacementSources = [
      payloadRecord.content,
      payloadRecord.contentFromAttachment,
      payloadRecord.contentFromWorkspaceFile,
    ].filter((value) => typeof value === "string" && value.trim().length > 0);
    if (replacementSources.length !== 1) {
      return {
        error:
          "Error: operation=replace requires exactly one non-empty content, contentFromAttachment, or contentFromWorkspaceFile value. No changes were applied.",
      };
    }
  }

  if (operation === "metadata") {
    const keys = Object.keys(payloadRecord);
    if (keys.length === 0) {
      return {
        error:
          "Error: operation=metadata requires name, description, or icon. No changes were applied.",
      };
    }
    if (
      payloadRecord.name !== undefined &&
      (typeof payloadRecord.name !== "string" ||
        payloadRecord.name.trim().length === 0)
    ) {
      return {
        error:
          "Error: extension name must be a non-empty string. No changes were applied.",
      };
    }
  }

  return {
    args: {
      id: String(args?.id ?? "").trim(),
      ...payloadRecord,
      ...(operation === "replace" ? { allowFullReplacement: true } : {}),
    },
  };
}

function parseInlineContext(
  value: unknown,
): Record<string, unknown> | undefined {
  if (value === undefined || value === null || value === "") return undefined;
  const parsed =
    typeof value === "string"
      ? (() => {
          try {
            return JSON.parse(value);
          } catch {
            return undefined;
          }
        })()
      : value;
  return parsed && typeof parsed === "object" && !Array.isArray(parsed)
    ? (parsed as Record<string, unknown>)
    : undefined;
}

function coerceInlineHeight(value: unknown): number | undefined {
  if (value === undefined || value === null || value === "") return undefined;
  const height = Number(value);
  if (!Number.isFinite(height) || height <= 0) return undefined;
  return Math.min(Math.max(Math.round(height), 120), 1000);
}

function coerceLimit(value: unknown): number {
  const limit = Number(value ?? 100);
  if (!Number.isFinite(limit)) return 100;
  return Math.min(Math.max(1, Math.floor(limit)), 500);
}

function parsePatches(value: unknown): ExtensionLegacyPatch[] | undefined {
  if (value === undefined) return undefined;
  const parsed = parseJsonArray(value);
  if (!Array.isArray(parsed)) return undefined;
  if (
    parsed.some(
      (patch) =>
        !patch ||
        typeof patch.find !== "string" ||
        typeof patch.replace !== "string",
    )
  ) {
    return undefined;
  }
  return parsed;
}

function parseEdits(value: unknown): ExtensionContentEdit[] | undefined {
  if (value === undefined) return undefined;
  const parsed = parseJsonArray(value);
  if (!Array.isArray(parsed)) return undefined;
  return parsed.every(isValidContentEdit)
    ? (parsed as ExtensionContentEdit[])
    : undefined;
}

function parseJsonArray(value: unknown): unknown {
  if (typeof value !== "string") return value;
  try {
    return JSON.parse(value);
  } catch {
    return undefined;
  }
}

function isValidContentEdit(value: unknown): boolean {
  if (!value || typeof value !== "object") return false;
  const edit = value as Record<string, unknown>;
  const op = edit.op ?? "replace";
  if (typeof op !== "string") return false;

  switch (op) {
    case "replace":
      return typeof edit.find === "string" && typeof edit.replace === "string";
    case "insert-before":
    case "insert-after":
      return (
        typeof edit.marker === "string" && typeof edit.content === "string"
      );
    case "replace-between":
      return (
        typeof edit.start === "string" &&
        typeof edit.end === "string" &&
        typeof edit.content === "string"
      );
    case "replace-section":
      return (
        typeof edit.section === "string" && typeof edit.content === "string"
      );
    case "wrap-section":
      return (
        typeof edit.section === "string" &&
        typeof edit.before === "string" &&
        typeof edit.after === "string"
      );
    case "remove-section":
      return typeof edit.section === "string";
    case "regex-replace":
      return (
        typeof edit.pattern === "string" && typeof edit.replace === "string"
      );
    default:
      return false;
  }
}