opencode-lcm 0.11.0

package/src/options.ts

@@ -0,0 +1,297 @@
+import type {
+  AutomaticRetrievalOptions,
+  AutomaticRetrievalScopeBudgets,
+  AutomaticRetrievalStopOptions,
+  InteropOptions,
+  OpencodeLcmOptions,
+  PrivacyOptions,
+  RetentionPolicyOptions,
+  ScopeDefaults,
+  ScopeName,
+  ScopeProfile,
+} from './types.js';
+
+const DEFAULT_INTEROP: InteropOptions = {
+  contextMode: true,
+  neverOverrideCompactionPrompt: true,
+  ignoreToolPrefixes: ['ctx_'],
+};
+
+const DEFAULT_SCOPE_DEFAULTS: ScopeDefaults = {
+  grep: 'session',
+  describe: 'session',
+};
+
+const DEFAULT_RETENTION: RetentionPolicyOptions = {
+  staleSessionDays: undefined,
+  deletedSessionDays: 30,
+  orphanBlobDays: 14,
+};
+
+const DEFAULT_PRIVACY: PrivacyOptions = {
+  excludeToolPrefixes: [],
+  excludePathPatterns: [],
+  redactPatterns: [],
+};
+
+const DEFAULT_AUTOMATIC_RETRIEVAL: AutomaticRetrievalOptions = {
+  enabled: true,
+  maxChars: 900,
+  minTokens: 2,
+  maxMessageHits: 2,
+  maxSummaryHits: 1,
+  maxArtifactHits: 1,
+  scopeOrder: ['session', 'root', 'worktree'],
+  scopeBudgets: {
+    session: 16,
+    root: 12,
+    worktree: 8,
+    all: 6,
+  },
+  stop: {
+    targetHits: 3,
+    stopOnFirstScopeWithHits: false,
+  },
+};
+
+export const DEFAULT_OPTIONS: OpencodeLcmOptions = {
+  interop: DEFAULT_INTEROP,
+  scopeDefaults: DEFAULT_SCOPE_DEFAULTS,
+  scopeProfiles: [],
+  retention: DEFAULT_RETENTION,
+  privacy: DEFAULT_PRIVACY,
+  automaticRetrieval: DEFAULT_AUTOMATIC_RETRIEVAL,
+  compactContextLimit: 1200,
+  systemHint: true,
+  freshTailMessages: 10,
+  minMessagesForTransform: 16,
+  summaryCharBudget: 1500,
+  partCharBudget: 160,
+  largeContentThreshold: 1200,
+  artifactPreviewChars: 220,
+  artifactViewChars: 4000,
+  binaryPreviewProviders: [
+    'fingerprint',
+    'byte-peek',
+    'image-dimensions',
+    'pdf-metadata',
+    'zip-metadata',
+  ],
+  previewBytePeek: 16,
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function asNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function asNonNegativeNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function asOptionalNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function asStringArray(value: unknown, fallback: string[]): string[] {
+  if (!Array.isArray(value)) return fallback;
+  const next = value.filter((item): item is string => typeof item === 'string' && item.length > 0);
+  return next.length > 0 ? next : fallback;
+}
+
+function asScopeName(value: unknown, fallback: ScopeName): ScopeName {
+  return value === 'session' || value === 'root' || value === 'worktree' || value === 'all'
+    ? value
+    : fallback;
+}
+
+function asScopeNameArray(value: unknown, fallback: ScopeName[]): ScopeName[] {
+  if (!Array.isArray(value)) return fallback;
+  const result: ScopeName[] = [];
+
+  for (const item of value) {
+    if (item !== 'session' && item !== 'root' && item !== 'worktree' && item !== 'all') continue;
+    if (result.includes(item)) continue;
+    result.push(item);
+  }
+
+  return result.length > 0 ? result : fallback;
+}
+
+function asScopeDefaults(value: unknown, fallback: ScopeDefaults): ScopeDefaults {
+  const record = asRecord(value);
+  return {
+    grep: asScopeName(record?.grep, fallback.grep),
+    describe: asScopeName(record?.describe, fallback.describe),
+  };
+}
+
+function asScopeProfiles(value: unknown): ScopeProfile[] {
+  if (!Array.isArray(value)) return [];
+
+  const result: ScopeProfile[] = [];
+
+  for (const item of value) {
+    const record = asRecord(item);
+    const worktree =
+      typeof record?.worktree === 'string' && record.worktree.length > 0
+        ? record.worktree
+        : undefined;
+    if (!worktree) continue;
+
+    result.push({
+      worktree,
+      grep:
+        record?.grep === undefined
+          ? undefined
+          : asScopeName(record.grep, DEFAULT_SCOPE_DEFAULTS.grep),
+      describe:
+        record?.describe === undefined
+          ? undefined
+          : asScopeName(record.describe, DEFAULT_SCOPE_DEFAULTS.describe),
+    });
+  }
+
+  return result;
+}
+
+function asRetentionOptions(
+  value: unknown,
+  fallback: RetentionPolicyOptions,
+): RetentionPolicyOptions {
+  const record = asRecord(value);
+  return {
+    staleSessionDays:
+      record?.staleSessionDays === undefined
+        ? fallback.staleSessionDays
+        : asOptionalNumber(record.staleSessionDays),
+    deletedSessionDays:
+      record?.deletedSessionDays === undefined
+        ? fallback.deletedSessionDays
+        : asOptionalNumber(record.deletedSessionDays),
+    orphanBlobDays:
+      record?.orphanBlobDays === undefined
+        ? fallback.orphanBlobDays
+        : asOptionalNumber(record.orphanBlobDays),
+  };
+}
+
+function asPrivacyOptions(value: unknown, fallback: PrivacyOptions): PrivacyOptions {
+  const record = asRecord(value);
+  return {
+    excludeToolPrefixes: asStringArray(record?.excludeToolPrefixes, fallback.excludeToolPrefixes),
+    excludePathPatterns: asStringArray(record?.excludePathPatterns, fallback.excludePathPatterns),
+    redactPatterns: asStringArray(record?.redactPatterns, fallback.redactPatterns),
+  };
+}
+
+function asAutomaticRetrievalOptions(
+  value: unknown,
+  fallback: AutomaticRetrievalOptions,
+): AutomaticRetrievalOptions {
+  const record = asRecord(value);
+  return {
+    enabled: asBoolean(record?.enabled, fallback.enabled),
+    maxChars: asNumber(record?.maxChars, fallback.maxChars),
+    minTokens: asNumber(record?.minTokens, fallback.minTokens),
+    maxMessageHits: asNumber(record?.maxMessageHits, fallback.maxMessageHits),
+    maxSummaryHits: asNumber(record?.maxSummaryHits, fallback.maxSummaryHits),
+    maxArtifactHits: asNumber(record?.maxArtifactHits, fallback.maxArtifactHits),
+    scopeOrder: asScopeNameArray(record?.scopeOrder, fallback.scopeOrder),
+    scopeBudgets: asAutomaticRetrievalScopeBudgets(record?.scopeBudgets, fallback.scopeBudgets),
+    stop: asAutomaticRetrievalStopOptions(record?.stop, fallback.stop),
+  };
+}
+
+function asAutomaticRetrievalScopeBudgets(
+  value: unknown,
+  fallback: AutomaticRetrievalScopeBudgets,
+): AutomaticRetrievalScopeBudgets {
+  const record = asRecord(value);
+  return {
+    session: asNonNegativeNumber(record?.session, fallback.session),
+    root: asNonNegativeNumber(record?.root, fallback.root),
+    worktree: asNonNegativeNumber(record?.worktree, fallback.worktree),
+    all: asNonNegativeNumber(record?.all, fallback.all),
+  };
+}
+
+function asAutomaticRetrievalStopOptions(
+  value: unknown,
+  fallback: AutomaticRetrievalStopOptions,
+): AutomaticRetrievalStopOptions {
+  const record = asRecord(value);
+  return {
+    targetHits: asNonNegativeNumber(record?.targetHits, fallback.targetHits),
+    stopOnFirstScopeWithHits: asBoolean(
+      record?.stopOnFirstScopeWithHits,
+      fallback.stopOnFirstScopeWithHits,
+    ),
+  };
+}
+
+export function resolveOptions(raw: unknown): OpencodeLcmOptions {
+  const options = asRecord(raw);
+  const interop = asRecord(options?.interop);
+  const scopeDefaults = asScopeDefaults(options?.scopeDefaults, DEFAULT_SCOPE_DEFAULTS);
+
+  return {
+    interop: {
+      contextMode: asBoolean(interop?.contextMode, DEFAULT_INTEROP.contextMode),
+      neverOverrideCompactionPrompt: asBoolean(
+        interop?.neverOverrideCompactionPrompt,
+        DEFAULT_INTEROP.neverOverrideCompactionPrompt,
+      ),
+      ignoreToolPrefixes: asStringArray(
+        interop?.ignoreToolPrefixes,
+        DEFAULT_INTEROP.ignoreToolPrefixes,
+      ),
+    },
+    scopeDefaults,
+    scopeProfiles: asScopeProfiles(options?.scopeProfiles),
+    retention: asRetentionOptions(options?.retention, DEFAULT_RETENTION),
+    privacy: asPrivacyOptions(options?.privacy, DEFAULT_PRIVACY),
+    automaticRetrieval: asAutomaticRetrievalOptions(
+      options?.automaticRetrieval,
+      DEFAULT_AUTOMATIC_RETRIEVAL,
+    ),
+    compactContextLimit: asNumber(
+      options?.compactContextLimit,
+      DEFAULT_OPTIONS.compactContextLimit,
+    ),
+    systemHint: asBoolean(options?.systemHint, DEFAULT_OPTIONS.systemHint),
+    storeDir:
+      typeof options?.storeDir === 'string' && options.storeDir.length > 0
+        ? options.storeDir
+        : undefined,
+    freshTailMessages: asNumber(options?.freshTailMessages, DEFAULT_OPTIONS.freshTailMessages),
+    minMessagesForTransform: asNumber(
+      options?.minMessagesForTransform,
+      DEFAULT_OPTIONS.minMessagesForTransform,
+    ),
+    summaryCharBudget: asNumber(options?.summaryCharBudget, DEFAULT_OPTIONS.summaryCharBudget),
+    partCharBudget: asNumber(options?.partCharBudget, DEFAULT_OPTIONS.partCharBudget),
+    largeContentThreshold: asNumber(
+      options?.largeContentThreshold,
+      DEFAULT_OPTIONS.largeContentThreshold,
+    ),
+    artifactPreviewChars: asNumber(
+      options?.artifactPreviewChars,
+      DEFAULT_OPTIONS.artifactPreviewChars,
+    ),
+    artifactViewChars: asNumber(options?.artifactViewChars, DEFAULT_OPTIONS.artifactViewChars),
+    binaryPreviewProviders: asStringArray(
+      options?.binaryPreviewProviders,
+      DEFAULT_OPTIONS.binaryPreviewProviders,
+    ),
+    previewBytePeek: asNumber(options?.previewBytePeek, DEFAULT_OPTIONS.previewBytePeek),
+  };
+}

package/src/preview-providers.ts

@@ -0,0 +1,298 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import type { Part } from '@opencode-ai/sdk';
+
+import { getLogger } from './logging.js';
+import { resolveWorkspacePath } from './workspace-path.js';
+
+type FilePart = Extract<Part, { type: 'file' }>;
+
+type PreviewContext = {
+  workspaceDirectory: string;
+  file: FilePart;
+  category: string;
+  extension?: string;
+  mime?: string;
+  enabledProviders: string[];
+  bytePeek: number;
+};
+
+type PreviewOutput = {
+  metadata: Record<string, unknown>;
+  lines: string[];
+  summaryBits: string[];
+};
+
+type ProviderName =
+  | 'fingerprint'
+  | 'byte-peek'
+  | 'image-dimensions'
+  | 'pdf-metadata'
+  | 'zip-metadata';
+
+type Provider = {
+  name: ProviderName;
+  apply(context: PreviewContext, helpers: ProviderHelpers): PreviewOutput;
+};
+
+type ProviderHelpers = {
+  resolvePath(): string | undefined;
+  readBytes(): Buffer | undefined;
+};
+
+function inferLocalPath(workspaceDirectory: string, file: FilePart): string | undefined {
+  const sourcePath = file.source && 'path' in file.source ? file.source.path : undefined;
+  if (!sourcePath) return undefined;
+
+  try {
+    return resolveWorkspacePath(workspaceDirectory, sourcePath);
+  } catch (error) {
+    getLogger().debug('Failed to resolve workspace path', { sourcePath, error });
+    return undefined;
+  }
+}
+
+function toHexPreview(buffer: Buffer, bytes: number): string | undefined {
+  if (buffer.length === 0) return undefined;
+  return [...buffer.subarray(0, Math.max(1, bytes))]
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join(' ');
+}
+
+function parsePngDimensions(buffer: Buffer): { width: number; height: number } | undefined {
+  if (buffer.length < 24) return undefined;
+  if (!buffer.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+    return undefined;
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20),
+  };
+}
+
+function parseGifDimensions(buffer: Buffer): { width: number; height: number } | undefined {
+  if (buffer.length < 10) return undefined;
+  const header = buffer.subarray(0, 6).toString('ascii');
+  if (header !== 'GIF87a' && header !== 'GIF89a') return undefined;
+  return {
+    width: buffer.readUInt16LE(6),
+    height: buffer.readUInt16LE(8),
+  };
+}
+
+function parseJpegDimensions(buffer: Buffer): { width: number; height: number } | undefined {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return undefined;
+  let offset = 2;
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    const marker = buffer[offset + 1];
+    if (marker === 0xd9 || marker === 0xda) break;
+    const size = buffer.readUInt16BE(offset + 2);
+    if (size < 2 || offset + 2 + size > buffer.length) break;
+    if (
+      (marker >= 0xc0 && marker <= 0xc3) ||
+      (marker >= 0xc5 && marker <= 0xc7) ||
+      (marker >= 0xc9 && marker <= 0xcb) ||
+      (marker >= 0xcd && marker <= 0xcf)
+    ) {
+      return {
+        height: buffer.readUInt16BE(offset + 5),
+        width: buffer.readUInt16BE(offset + 7),
+      };
+    }
+    offset += 2 + size;
+  }
+  return undefined;
+}
+
+function estimatePdfPages(buffer: Buffer): number | undefined {
+  const text = buffer.toString('latin1');
+  const matches = text.match(/\/Type\s*\/Page([^s]|$)/g);
+  return matches && matches.length > 0 ? matches.length : undefined;
+}
+
+function estimateZipEntries(buffer: Buffer): number | undefined {
+  if (buffer.length < 4) return undefined;
+
+  const localFileHeaderSignature = 0x04034b50;
+  const endOfCentralDirectorySignature = 0x06054b50;
+  const firstSignature = buffer.readUInt32LE(0);
+  if (
+    firstSignature !== localFileHeaderSignature &&
+    firstSignature !== endOfCentralDirectorySignature
+  ) {
+    return undefined;
+  }
+
+  const searchStart = Math.max(0, buffer.length - 65557);
+  for (let offset = buffer.length - 22; offset >= searchStart; offset -= 1) {
+    if (buffer.readUInt32LE(offset) !== endOfCentralDirectorySignature) continue;
+    return buffer.readUInt16LE(offset + 10);
+  }
+
+  let entries = 0;
+  for (let offset = 0; offset <= buffer.length - 4; offset += 1) {
+    if (buffer.readUInt32LE(offset) === localFileHeaderSignature) entries += 1;
+  }
+  return entries > 0 ? entries : undefined;
+}
+
+const fingerprintProvider: Provider = {
+  name: 'fingerprint',
+  apply(_context, helpers) {
+    const filePath = helpers.resolvePath();
+    const bytes = helpers.readBytes();
+    if (!filePath || !bytes) return { metadata: {}, lines: [], summaryBits: [] };
+
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    const sizeBytes = bytes.length;
+    return {
+      metadata: {
+        previewLocalPath: filePath,
+        previewSha256: sha256,
+        previewSizeBytes: sizeBytes,
+      },
+      lines: [`Fingerprint: sha256 ${sha256} (${sizeBytes} bytes)`],
+      summaryBits: [`sha256 ${sha256.slice(0, 12)}`, `${sizeBytes} bytes`],
+    };
+  },
+};
+
+const bytePeekProvider: Provider = {
+  name: 'byte-peek',
+  apply(context, helpers) {
+    const bytes = helpers.readBytes();
+    const preview = bytes ? toHexPreview(bytes, context.bytePeek) : undefined;
+    if (!preview) return { metadata: {}, lines: [], summaryBits: [] };
+
+    return {
+      metadata: {
+        previewBytePeekHex: preview,
+      },
+      lines: [`Byte peek: ${preview}`],
+      summaryBits: [`peek ${preview}`],
+    };
+  },
+};
+
+const imageDimensionsProvider: Provider = {
+  name: 'image-dimensions',
+  apply(context, helpers) {
+    if (context.category !== 'image') return { metadata: {}, lines: [], summaryBits: [] };
+    const bytes = helpers.readBytes();
+    if (!bytes) return { metadata: {}, lines: [], summaryBits: [] };
+
+    const dimensions =
+      parsePngDimensions(bytes) ?? parseGifDimensions(bytes) ?? parseJpegDimensions(bytes);
+    if (!dimensions) return { metadata: {}, lines: [], summaryBits: [] };
+
+    return {
+      metadata: {
+        previewImageWidth: dimensions.width,
+        previewImageHeight: dimensions.height,
+      },
+      lines: [`Image dimensions: ${dimensions.width}x${dimensions.height}`],
+      summaryBits: [`${dimensions.width}x${dimensions.height}`],
+    };
+  },
+};
+
+const pdfMetadataProvider: Provider = {
+  name: 'pdf-metadata',
+  apply(context, helpers) {
+    if (context.category !== 'pdf') return { metadata: {}, lines: [], summaryBits: [] };
+    const bytes = helpers.readBytes();
+    if (!bytes) return { metadata: {}, lines: [], summaryBits: [] };
+    const pageEstimate = estimatePdfPages(bytes);
+    if (!pageEstimate) return { metadata: {}, lines: [], summaryBits: [] };
+
+    return {
+      metadata: {
+        previewPdfPageEstimate: pageEstimate,
+      },
+      lines: [`PDF page estimate: ${pageEstimate}`],
+      summaryBits: [`${pageEstimate} page${pageEstimate === 1 ? '' : 's'}`],
+    };
+  },
+};
+
+const zipMetadataProvider: Provider = {
+  name: 'zip-metadata',
+  apply(_context, helpers) {
+    const bytes = helpers.readBytes();
+    if (!bytes) return { metadata: {}, lines: [], summaryBits: [] };
+    const entryCount = estimateZipEntries(bytes);
+    if (entryCount === undefined) return { metadata: {}, lines: [], summaryBits: [] };
+
+    return {
+      metadata: {
+        previewZipEntryCount: entryCount,
+      },
+      lines: [`ZIP entries: ${entryCount}`],
+      summaryBits: [`${entryCount} entr${entryCount === 1 ? 'y' : 'ies'}`],
+    };
+  },
+};
+
+const PROVIDERS: Provider[] = [
+  fingerprintProvider,
+  bytePeekProvider,
+  imageDimensionsProvider,
+  pdfMetadataProvider,
+  zipMetadataProvider,
+];
+
+export async function runBinaryPreviewProviders(context: PreviewContext): Promise<PreviewOutput> {
+  const localPath = inferLocalPath(context.workspaceDirectory, context.file);
+  let resolvedPath: string | undefined;
+  let resolvedBytes: Buffer | undefined;
+
+  if (localPath) {
+    try {
+      resolvedBytes = await readFile(localPath);
+      resolvedPath = localPath;
+    } catch (error) {
+      getLogger().debug('Failed to read file bytes for preview', { filePath: localPath, error });
+    }
+  }
+
+  const helpers: ProviderHelpers = {
+    resolvePath() {
+      return resolvedPath;
+    },
+    readBytes() {
+      return resolvedBytes;
+    },
+  };
+
+  const enabled = new Set(context.enabledProviders);
+  const outputs = PROVIDERS.filter((provider) => enabled.has(provider.name)).map((provider) => ({
+    name: provider.name,
+    output: provider.apply(context, helpers),
+  }));
+
+  const metadata: Record<string, unknown> = {
+    previewProviders: outputs
+      .filter(
+        (entry) => Object.keys(entry.output.metadata).length > 0 || entry.output.lines.length > 0,
+      )
+      .map((entry) => entry.name),
+  };
+  const lines: string[] = [];
+  const summaryBits: string[] = [];
+
+  for (const entry of outputs) {
+    Object.assign(metadata, entry.output.metadata);
+    lines.push(...entry.output.lines);
+    summaryBits.push(...entry.output.summaryBits);
+  }
+
+  return {
+    metadata,
+    lines,
+    summaryBits,
+  };
+}

package/src/privacy.ts

@@ -0,0 +1,122 @@
+import type { PrivacyOptions } from './types.js';
+
+export const PRIVACY_REDACTION_TEXT = '[REDACTED]';
+export const PRIVACY_REDACTED_PATH_TEXT = '[REDACTED_PATH]';
+export const PRIVACY_EXCLUDED_TOOL_OUTPUT =
+  '[Excluded tool payload by opencode-lcm privacy policy.]';
+export const PRIVACY_EXCLUDED_FILE_CONTENT =
+  '[Excluded file content by opencode-lcm privacy policy.]';
+export const PRIVACY_EXCLUDED_FILE_REFERENCE =
+  '[Excluded file reference by opencode-lcm privacy policy.]';
+
+export type CompiledPrivacyOptions = {
+  excludeToolPrefixes: string[];
+  excludePathPatterns: RegExp[];
+  redactPatterns: RegExp[];
+};
+
+const EXEMPT_STRING_KEYS = new Set([
+  'agent',
+  'artifactID',
+  'callID',
+  'fieldName',
+  'id',
+  'messageID',
+  'mime',
+  'modelID',
+  'name',
+  'nodeID',
+  'parentID',
+  'parentSessionID',
+  'partID',
+  'projectID',
+  'providerID',
+  'role',
+  'rootSessionID',
+  'sessionID',
+  'status',
+  'tool',
+  'type',
+  'urlScheme',
+]);
+
+function compilePattern(source: string): RegExp | undefined {
+  try {
+    const probe = new RegExp(source, 'u');
+    if (probe.test('')) return undefined;
+    return new RegExp(source, 'gu');
+  } catch {
+    return undefined;
+  }
+}
+
+function applyPatterns(value: string, patterns: RegExp[], replacement: string): string {
+  let next = value;
+  for (const pattern of patterns) {
+    pattern.lastIndex = 0;
+    next = next.replace(pattern, replacement);
+  }
+  return next;
+}
+
+function matchesPattern(value: string, pattern: RegExp): boolean {
+  pattern.lastIndex = 0;
+  return pattern.test(value);
+}
+
+export function compilePrivacyOptions(options: PrivacyOptions): CompiledPrivacyOptions {
+  return {
+    excludeToolPrefixes: [
+      ...new Set(options.excludeToolPrefixes.filter((value) => value.length > 0)),
+    ],
+    excludePathPatterns: options.excludePathPatterns
+      .map((source) => compilePattern(source))
+      .filter((pattern): pattern is RegExp => Boolean(pattern)),
+    redactPatterns: options.redactPatterns
+      .map((source) => compilePattern(source))
+      .filter((pattern): pattern is RegExp => Boolean(pattern)),
+  };
+}
+
+export function redactText(value: string, privacy: CompiledPrivacyOptions): string {
+  const redacted = applyPatterns(value, privacy.redactPatterns, PRIVACY_REDACTION_TEXT);
+  return applyPatterns(redacted, privacy.excludePathPatterns, PRIVACY_REDACTED_PATH_TEXT);
+}
+
+export function redactStructuredValue<T>(
+  value: T,
+  privacy: CompiledPrivacyOptions,
+  currentKey?: string,
+): T {
+  if (typeof value === 'string') {
+    return (
+      currentKey && EXEMPT_STRING_KEYS.has(currentKey) ? value : redactText(value, privacy)
+    ) as T;
+  }
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactStructuredValue(entry, privacy, currentKey)) as T;
+  }
+
+  const entries = Object.entries(value).map(([key, entry]) => [
+    key,
+    redactStructuredValue(entry, privacy, key),
+  ]);
+  return Object.fromEntries(entries) as T;
+}
+
+export function isExcludedTool(toolName: string, privacy: CompiledPrivacyOptions): boolean {
+  return privacy.excludeToolPrefixes.some((prefix) => toolName.startsWith(prefix));
+}
+
+export function matchesExcludedPath(
+  candidates: Array<string | undefined>,
+  privacy: CompiledPrivacyOptions,
+): boolean {
+  return candidates.some(
+    (candidate) =>
+      typeof candidate === 'string' &&
+      candidate.length > 0 &&
+      privacy.excludePathPatterns.some((pattern) => matchesPattern(candidate, pattern)),
+  );
+}