@actagent/diffs 2026.6.2

package/src/language-hints.ts

@@ -0,0 +1,159 @@
+// Diffs plugin module implements language hints behavior.
+import { resolveLanguage } from "@pierre/diffs";
+import type { FileContents, FileDiffMetadata, SupportedLanguages } from "@pierre/diffs";
+import {
+  bundledLanguagesBase,
+  bundledLanguagesInfo,
+  getBundledLanguageAliases,
+} from "./shiki-curated-languages.js";
+import type { DiffViewerPayload } from "./types.js";
+
+export const BASE_DIFF_VIEWER_LANGUAGE_HINTS = [
+  ...Object.keys(bundledLanguagesBase),
+  "text",
+  "ansi",
+] as const satisfies readonly SupportedLanguages[];
+export type DiffViewerBaseLanguage = (typeof BASE_DIFF_VIEWER_LANGUAGE_HINTS)[number];
+
+const BASE_LANGUAGE_HINTS = new Set<SupportedLanguages>(BASE_DIFF_VIEWER_LANGUAGE_HINTS);
+const BASE_LANGUAGE_ALIASES = new Map<string, SupportedLanguages>(
+  bundledLanguagesInfo.flatMap((language) =>
+    getBundledLanguageAliases(language).map((alias) => [alias, language.id as SupportedLanguages]),
+  ),
+);
+type DiffPayloadFile = FileContents | FileDiffMetadata;
+
+function normalizeOptionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export async function normalizeSupportedLanguageHint(
+  value?: string,
+  options: { languagePackAvailable?: boolean } = {},
+): Promise<SupportedLanguages | undefined> {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    return undefined;
+  }
+  const baseAlias = BASE_LANGUAGE_ALIASES.get(normalized);
+  if (baseAlias) {
+    return baseAlias;
+  }
+  if (BASE_LANGUAGE_HINTS.has(normalized as SupportedLanguages)) {
+    return normalized as SupportedLanguages;
+  }
+  if (!options.languagePackAvailable) {
+    return undefined;
+  }
+  try {
+    await resolveLanguage(normalized as Exclude<SupportedLanguages, "text" | "ansi">);
+    return normalized as SupportedLanguages;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function filterSupportedLanguageHints(
+  values: Iterable<string>,
+  options: { languagePackAvailable?: boolean } = {},
+): Promise<SupportedLanguages[]> {
+  return normalizeSupportedLanguageHints(values, { fallbackToText: true, ...options });
+}
+
+async function normalizeSupportedLanguageHints(
+  values: Iterable<string>,
+  options: { fallbackToText: boolean; languagePackAvailable?: boolean },
+): Promise<SupportedLanguages[]> {
+  const supported = new Set<SupportedLanguages>();
+  for (const value of values) {
+    const normalized = await normalizeSupportedLanguageHint(value, options);
+    if (!normalized) {
+      continue;
+    }
+    supported.add(normalized);
+  }
+  if (options.fallbackToText && supported.size === 0) {
+    supported.add("text");
+  }
+  return [...supported];
+}
+
+export function collectDiffPayloadLanguageHints(payload: {
+  fileDiff?: FileDiffMetadata;
+  oldFile?: FileContents;
+  newFile?: FileContents;
+}): SupportedLanguages[] {
+  const langs = new Set<SupportedLanguages>();
+  if (payload.fileDiff?.lang) {
+    langs.add(payload.fileDiff.lang);
+  }
+  if (payload.oldFile?.lang) {
+    langs.add(payload.oldFile.lang);
+  }
+  if (payload.newFile?.lang) {
+    langs.add(payload.newFile.lang);
+  }
+  return [...langs];
+}
+
+async function normalizeDiffPayloadFileLanguage(
+  file: DiffPayloadFile | undefined,
+  options: { languagePackAvailable?: boolean },
+): Promise<DiffPayloadFile | undefined> {
+  if (!file) {
+    return undefined;
+  }
+  if (typeof file.lang !== "string") {
+    return file;
+  }
+  const normalized = await normalizeSupportedLanguageHint(file.lang, options);
+  if (file.lang === normalized) {
+    return file;
+  }
+  if (!normalized) {
+    return {
+      ...file,
+      lang: "text",
+    };
+  }
+  return {
+    ...file,
+    lang: normalized,
+  };
+}
+
+export async function normalizeDiffViewerPayloadLanguages(
+  payload: DiffViewerPayload,
+  options: { languagePackAvailable?: boolean } = {},
+): Promise<DiffViewerPayload> {
+  const [fileDiff, oldFile, newFile, payloadLangs] = await Promise.all([
+    normalizeDiffPayloadFileLanguage(payload.fileDiff, options) as Promise<
+      FileDiffMetadata | undefined
+    >,
+    normalizeDiffPayloadFileLanguage(payload.oldFile, options) as Promise<FileContents | undefined>,
+    normalizeDiffPayloadFileLanguage(payload.newFile, options) as Promise<FileContents | undefined>,
+    normalizeSupportedLanguageHints(payload.langs, { fallbackToText: false, ...options }),
+  ]);
+  const langs = new Set<SupportedLanguages>(payloadLangs);
+  for (const lang of collectDiffPayloadLanguageHints({ fileDiff, oldFile, newFile })) {
+    langs.add(lang);
+  }
+  if (langs.size === 0) {
+    langs.add("text");
+  }
+  return {
+    ...payload,
+    fileDiff,
+    oldFile,
+    newFile,
+    langs: [...langs],
+  };
+}
+
+export function isBaseDiffViewerLanguage(lang: string): boolean {
+  return BASE_LANGUAGE_HINTS.has(lang as SupportedLanguages);
+}

package/src/manifest.test.ts

@@ -0,0 +1,17 @@
+// Diffs tests cover manifest plugin behavior.
+import fs from "node:fs";
+import { describe, expect, it } from "vitest";
+
+type DiffsPackageManifest = {
+  dependencies?: Record<string, string>;
+};
+
+describe("diffs package manifest", () => {
+  it("keeps runtime dependencies in the package manifest", () => {
+    const packageJson = JSON.parse(
+      fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    ) as DiffsPackageManifest;
+
+    expect(packageJson.dependencies).toHaveProperty("@pierre/diffs");
+  });
+});

package/src/pierre-themes.ts

@@ -0,0 +1,60 @@
+// Diffs plugin module implements pierre themes behavior.
+import { createRequire } from "node:module";
+import type { ThemeRegistrationResolved } from "@pierre/diffs";
+import { RegisteredCustomThemes, ResolvedThemes, ResolvingThemes } from "@pierre/diffs";
+import { readJsonFileWithFallback } from "actagent/plugin-sdk/json-store";
+
+type PierreThemeName = "pierre-dark" | "pierre-light";
+const themeRequire = createRequire(import.meta.url);
+const PIERRE_THEME_SPECS = [
+  ["pierre-dark", "@pierre/theme/themes/pierre-dark.json"],
+  ["pierre-light", "@pierre/theme/themes/pierre-light.json"],
+] as const satisfies ReadonlyArray<readonly [PierreThemeName, string]>;
+
+function createThemeLoader(
+  themeName: PierreThemeName,
+  themeSpecifier: string,
+): () => Promise<ThemeRegistrationResolved> {
+  let cachedTheme: ThemeRegistrationResolved | undefined;
+  return async () => {
+    if (cachedTheme) {
+      return cachedTheme;
+    }
+    const themePath = themeRequire.resolve(themeSpecifier);
+    const { value: theme } = await readJsonFileWithFallback<Record<string, unknown>>(themePath, {});
+    cachedTheme = {
+      ...theme,
+      name: themeName,
+    } as ThemeRegistrationResolved;
+    return cachedTheme;
+  };
+}
+
+const PIERRE_THEME_LOADERS = new Map(
+  PIERRE_THEME_SPECS.map(([themeName, themeSpecifier]) => [
+    themeName,
+    createThemeLoader(themeName, themeSpecifier),
+  ]),
+);
+
+export function ensurePierreThemesRegistered(): void {
+  let replacedThemeLoader = false;
+
+  for (const [themeName, loader] of PIERRE_THEME_LOADERS) {
+    if (RegisteredCustomThemes.get(themeName) !== loader) {
+      RegisteredCustomThemes.set(themeName, loader);
+      replacedThemeLoader = true;
+    }
+  }
+
+  if (!replacedThemeLoader) {
+    return;
+  }
+
+  // If another path swapped these loaders, clear the resolver caches so the
+  // next render rehydrates the highlighter with the Node-safe theme source.
+  for (const [themeName] of PIERRE_THEME_LOADERS) {
+    ResolvedThemes.delete(themeName);
+    ResolvingThemes.delete(themeName);
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,111 @@
+// Diffs plugin module implements plugin behavior.
+import fs from "node:fs";
+import path from "node:path";
+import { resolveLivePluginConfigObject } from "actagent/plugin-sdk/plugin-config-runtime";
+import {
+  resolvePreferredACTAgentTmpDir,
+  type ACTAgentConfig,
+  type ACTAgentPluginApi,
+} from "../api.js";
+import {
+  resolveDiffsPluginDefaults,
+  resolveDiffsPluginSecurity,
+  resolveDiffsPluginViewerBaseUrl,
+} from "./config.js";
+import { createDiffsHttpHandler } from "./http.js";
+import { DIFFS_AGENT_GUIDANCE } from "./prompt-guidance.js";
+import { DiffArtifactStore } from "./store.js";
+import { createDiffsTool } from "./tool.js";
+
+const DIFFS_LANGUAGE_PACK_PLUGIN_ID = "diffs-language-pack";
+
+export function registerDiffsPlugin(api: ACTAgentPluginApi): void {
+  const store = new DiffArtifactStore({
+    rootDir: path.join(resolvePreferredACTAgentTmpDir(), "actagent-diffs"),
+    logger: api.logger,
+  });
+  const resolveCurrentPluginConfig = () =>
+    resolveLivePluginConfigObject(
+      api.runtime.config?.current
+        ? () => api.runtime.config.current() as ACTAgentConfig
+        : undefined,
+      "diffs",
+      api.pluginConfig as Record<string, unknown>,
+    ) ?? {};
+  const resolveCurrentAccessConfig = () => {
+    const currentConfig = (api.runtime.config?.current?.() ?? api.config) as ACTAgentConfig;
+    const pluginConfig = resolveCurrentPluginConfig();
+    return {
+      allowRemoteViewer: resolveDiffsPluginSecurity(pluginConfig).allowRemoteViewer,
+      trustedProxies: currentConfig.gateway?.trustedProxies,
+      allowRealIpFallback: currentConfig.gateway?.allowRealIpFallback === true,
+    };
+  };
+  const initialAccessConfig = resolveCurrentAccessConfig();
+
+  api.registerTool(
+    (ctx) => {
+      const pluginConfig = resolveCurrentPluginConfig();
+      return createDiffsTool({
+        api,
+        store,
+        defaults: resolveDiffsPluginDefaults(pluginConfig),
+        viewerBaseUrl: resolveDiffsPluginViewerBaseUrl(pluginConfig),
+        languagePackAvailable: resolveDiffsLanguagePackAvailability(api),
+        context: ctx,
+      });
+    },
+    {
+      name: "diffs",
+    },
+  );
+  api.registerHttpRoute({
+    path: "/plugins/diffs",
+    auth: "plugin",
+    match: "prefix",
+    handler: createDiffsHttpHandler({
+      store,
+      logger: api.logger,
+      allowRemoteViewer: initialAccessConfig.allowRemoteViewer,
+      trustedProxies: initialAccessConfig.trustedProxies,
+      allowRealIpFallback: initialAccessConfig.allowRealIpFallback,
+      resolveAccessConfig: resolveCurrentAccessConfig,
+    }),
+  });
+  api.on("before_prompt_build", async () => ({
+    prependSystemContext: DIFFS_AGENT_GUIDANCE,
+  }));
+}
+
+export function resolveDiffsLanguagePackAvailability(api: ACTAgentPluginApi): boolean {
+  const currentConfig = (api.runtime.config?.current?.() ?? api.config) as ACTAgentConfig;
+  const plugins = currentConfig.plugins;
+  if (plugins?.enabled === false) {
+    return false;
+  }
+  if (plugins?.deny?.includes(DIFFS_LANGUAGE_PACK_PLUGIN_ID)) {
+    return false;
+  }
+  if (plugins?.allow && !plugins.allow.includes(DIFFS_LANGUAGE_PACK_PLUGIN_ID)) {
+    return false;
+  }
+  if (plugins?.entries?.[DIFFS_LANGUAGE_PACK_PLUGIN_ID]?.enabled === false) {
+    return false;
+  }
+  return hasSiblingLanguagePackRuntime(api.rootDir);
+}
+
+function hasSiblingLanguagePackRuntime(rootDir: string | undefined): boolean {
+  if (!rootDir) {
+    return false;
+  }
+  const languagePackRoot = path.join(path.dirname(rootDir), DIFFS_LANGUAGE_PACK_PLUGIN_ID);
+  const runtimePaths = [
+    path.join(languagePackRoot, "assets", "viewer-runtime.js"),
+    path.join(languagePackRoot, "dist", "assets", "viewer-runtime.js"),
+  ];
+  return (
+    fs.existsSync(path.join(languagePackRoot, "actagent.plugin.json")) &&
+    runtimePaths.some((runtimePath) => fs.existsSync(runtimePath))
+  );
+}

package/src/prompt-guidance.ts

@@ -0,0 +1,8 @@
+// Diffs plugin module implements prompt guidance behavior.
+export const DIFFS_AGENT_GUIDANCE = [
+  "When you need to show edits as a real diff, prefer the `diffs` tool instead of writing a manual summary.",
+  "It accepts either `before` + `after` text or a unified `patch`.",
+  "`mode=view` returns `details.viewerUrl` for canvas use; `mode=file` returns `details.filePath`; `mode=both` returns both.",
+  "If you need to send the rendered file, use the `message` tool with `path` or `filePath`.",
+  "Include `path` when you know the filename, and omit presentation overrides unless needed.",
+].join("\n");

package/src/render-target.test.ts

@@ -0,0 +1,133 @@
+// Diffs tests cover render target plugin behavior.
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { preloadFileDiffMock, preloadMultiFileDiffMock } = vi.hoisted(() => ({
+  preloadFileDiffMock: vi.fn(async ({ fileDiff }: { fileDiff: unknown }) => ({
+    prerenderedHTML: "<div>mock diff</div>",
+    fileDiff,
+  })),
+  preloadMultiFileDiffMock: vi.fn(
+    async ({ oldFile, newFile }: { oldFile: unknown; newFile: unknown }) => ({
+      prerenderedHTML: "<div>mock diff</div>",
+      oldFile,
+      newFile,
+    }),
+  ),
+}));
+
+vi.mock("@pierre/diffs/ssr", () => ({
+  preloadFileDiff: preloadFileDiffMock,
+  preloadMultiFileDiff: preloadMultiFileDiffMock,
+}));
+
+afterAll(() => {
+  vi.doUnmock("@pierre/diffs/ssr");
+  vi.resetModules();
+});
+
+import { DEFAULT_DIFFS_TOOL_DEFAULTS, resolveDiffImageRenderOptions } from "./config.js";
+import { renderDiffDocument } from "./render.js";
+import { parseViewerPayloadJson } from "./viewer-payload.js";
+
+function createRenderOptions() {
+  return {
+    presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+    image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+    expandUnchanged: false,
+  };
+}
+
+describe("renderDiffDocument render targets", () => {
+  beforeEach(() => {
+    preloadFileDiffMock.mockClear();
+    preloadMultiFileDiffMock.mockClear();
+  });
+
+  it("renders only the viewer variant for before/after viewer mode", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "one\n",
+        after: "two\n",
+      },
+      createRenderOptions(),
+      "viewer",
+    );
+
+    expect(rendered.html).toContain("mock diff");
+    expect(rendered.imageHtml).toBeUndefined();
+    expect(preloadMultiFileDiffMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders both variants for before/after both mode", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "one\n",
+        after: "two\n",
+      },
+      createRenderOptions(),
+      "both",
+    );
+
+    expect(rendered.html).toContain("mock diff");
+    expect(rendered.imageHtml).toContain("mock diff");
+    expect(preloadMultiFileDiffMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("renders only the image variant for patch image mode", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch: [
+          "diff --git a/a.ts b/a.ts",
+          "--- a/a.ts",
+          "+++ b/a.ts",
+          "@@ -1 +1 @@",
+          "-a",
+          "+b",
+        ].join("\n"),
+      },
+      createRenderOptions(),
+      "image",
+    );
+
+    expect(rendered.html).toBeUndefined();
+    expect(rendered.imageHtml).toContain("mock diff");
+    expect(preloadFileDiffMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes stale patch payload languages before serializing viewer output", async () => {
+    preloadFileDiffMock.mockResolvedValueOnce({
+      prerenderedHTML: "<div>mock diff</div>",
+      fileDiff: {
+        name: "a.ts",
+        lang: "not-a-real-language",
+      },
+    });
+
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch: [
+          "diff --git a/a.ts b/a.ts",
+          "--- a/a.ts",
+          "+++ b/a.ts",
+          "@@ -1 +1 @@",
+          "-a",
+          "+b",
+        ].join("\n"),
+      },
+      createRenderOptions(),
+      "viewer",
+    );
+
+    const payloads = [
+      ...(rendered.html ?? "").matchAll(/data-actagent-diff-payload>(.*?)<\/script>/g),
+    ].map((match) => parseViewerPayloadJson(match[1] ?? ""));
+
+    expect(payloads).toHaveLength(1);
+    expect(payloads[0]?.langs).toEqual(["text"]);
+    expect(payloads[0]?.fileDiff?.lang).toBe("text");
+  });
+});