sift-light 1.0.0

package/src/model-error.ts

@@ -0,0 +1,120 @@
+import { types } from "node:util";
+import {
+  boundedRequestContractDetails,
+  isSiftLightDiagnosticError,
+  MAX_REQUEST_RECOVERY_BYTES,
+} from "./request-contract.js";
+import type { SiftLightDiagnosticError } from "./errors.js";
+import type { RequestContractDetails } from "./request-contract.js";
+
+const MAX_RAW_ERROR_SCAN_CHARACTERS = 4_096;
+const MAX_MODEL_ERROR_CHARACTERS = 1_024;
+const MODEL_ERROR_PREFIX = "sift-light failed:";
+
+function errorMessage(error: unknown): string {
+  try {
+    if (types.isNativeError(error)) {
+      const message = Object.getOwnPropertyDescriptor(error, "message");
+      if (!message) return "unknown failure";
+      return typeof message.value === "string" ? message.value : "unreadable failure";
+    }
+    if (error === null) return "null";
+    switch (typeof error) {
+      case "string":
+        return error;
+      case "number":
+        return String(error);
+      case "boolean":
+        return error ? "true" : "false";
+      case "undefined":
+        return "undefined";
+      case "bigint":
+        return "bigint failure";
+      case "symbol":
+        return "symbol failure";
+      case "function":
+      case "object":
+        return "non-error failure";
+      default:
+        return "unreadable failure";
+    }
+  } catch {
+    return "unreadable failure";
+  }
+}
+
+/** One bounded model-facing diagnostic; never serialize causes, stacks, or repeated request text. */
+export function modelErrorText(error: unknown): string {
+  if (isSiftLightDiagnosticError(error)) return requestContractErrorText(error);
+  const raw = errorMessage(error);
+  const normalized = raw
+    .slice(0, MAX_RAW_ERROR_SCAN_CHARACTERS)
+    .toWellFormed()
+    .replace(/\s+/gu, " ")
+    .trim();
+  const message = normalized.replace(/^(?:sift-light failed:\s*)+/u, "") || "unknown failure";
+  const text = `${MODEL_ERROR_PREFIX} ${message}`;
+  if (text.length <= MAX_MODEL_ERROR_CHARACTERS) return text;
+  return `${text.slice(0, MAX_MODEL_ERROR_CHARACTERS - 1).toWellFormed()}…`;
+}
+
+/**
+ * Contract recovery is a copy protocol, so it must bypass the generic model
+ * error whitespace normalization and character truncation.  The contract
+ * builder omits oversized next requests instead of allowing a false exact
+ * retry to be emitted.
+ */
+export function requestContractErrorText(error: SiftLightDiagnosticError): string {
+  return requestContractProjection(error).text;
+}
+
+export interface RequestContractProjection {
+  details: RequestContractDetails;
+  text: string;
+}
+
+function projectRequestContract(
+  projected: RequestContractDetails,
+  serialized: string,
+  message: string,
+): string {
+  const prefix = `sift-light failed: request rejected [${projected.code}]: ${message}`;
+  const recovery = projected.recovery;
+  const next = recovery.nextRequest
+    ? "\nCopy the nested recovery.nextRequest object unchanged; do not repeat the original query."
+    : `\nRecovery action: ${recovery.action}. ${recovery.reason}`;
+  // Put the machine payload first so simple host adapters that locate the
+  // first `nextRequest` marker see the exact nested request object.
+  return `\nError details: ${serialized}\n${prefix}${next}`;
+}
+
+/** Build the one bounded contract projection consumed by structured and text hosts. */
+export function requestContractProjection(
+  error: SiftLightDiagnosticError,
+): RequestContractProjection {
+  const details = boundedRequestContractDetails(error.details);
+  const serializedDetails = JSON.stringify(details);
+  const boundedMessage = error.message.toWellFormed().slice(0, 1_024);
+  const result = projectRequestContract(details, serializedDetails, boundedMessage);
+  if (Buffer.byteLength(result) <= MAX_REQUEST_RECOVERY_BYTES) return { details, text: result };
+  const compact: RequestContractDetails = {
+    code: boundedMessage.length > 0 ? details.code : "E_REQUEST_CONTRACT_PAYLOAD",
+    ...(details.mode ? { mode: details.mode } : {}),
+    issues: [
+      {
+        field: "<payload>",
+        reason: "The visible request-contract error exceeded its bounded payload budget.",
+      },
+    ],
+    recovery: {
+      action: "manual" as const,
+      reason: "Exact recovery was omitted; correct the request explicitly.",
+    },
+  };
+  const compactText = projectRequestContract(
+    compact,
+    JSON.stringify(compact),
+    "The request-contract error exceeded the bounded payload budget; correct the request explicitly.",
+  );
+  return { details: compact, text: compactText };
+}

package/src/multi-term-search.ts

@@ -0,0 +1,122 @@
+import {
+  ANALYSIS_METADATA_RESERVE_BYTES,
+  MAX_ANY_OF_TERMS,
+  MAX_ANY_OF_TOTAL_TERMS,
+  MAX_ANALYSIS_RESULTS,
+  MAX_ANALYSIS_STORAGE_BYTES,
+  MAX_LITERAL_TERM_BYTES,
+  MIN_ANY_OF_TERMS,
+} from "./analysis-limits.js";
+import { sourceEvidence } from "./analysis-evidence.js";
+import type { AnalysisItem } from "./analysis-types.js";
+import { SiftLightError } from "./errors.js";
+import type { EvidenceCandidateFile } from "./evidence-candidates.js";
+import { literalOccurrences } from "./literal-search.js";
+
+export function validateAnyOf(value: string[] | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (
+    !Array.isArray(value) ||
+    value.length < MIN_ANY_OF_TERMS ||
+    value.length > MAX_ANY_OF_TOTAL_TERMS ||
+    value.some(
+      (term) =>
+        typeof term !== "string" ||
+        term.length === 0 ||
+        !term.isWellFormed() ||
+        /[\r\n\0]/.test(term) ||
+        Buffer.byteLength(term) > MAX_LITERAL_TERM_BYTES,
+    ) ||
+    new Set(value).size !== value.length
+  ) {
+    throw new SiftLightError(
+      `anyOf requires ${String(MIN_ANY_OF_TERMS)}–${String(MAX_ANY_OF_TOTAL_TERMS)} distinct, nonempty, well-formed, single-line literal terms of at most ${String(MAX_LITERAL_TERM_BYTES)} UTF-8 bytes; requests above ${String(MAX_ANY_OF_TERMS)} terms are safely chunked`,
+    );
+  }
+  return value;
+}
+
+export interface MultiTermExpansion {
+  items: AnalysisItem[];
+  partial: boolean;
+  reasons: string[];
+}
+
+/** Expands candidate files locally so alternation choice never hides an overlapping input term. */
+export function expandMultiTermCandidates(
+  files: readonly EvidenceCandidateFile[],
+  terms: readonly string[],
+  changedLinesOnly: boolean,
+): MultiTermExpansion {
+  const items: (AnalysisItem & { termIndex: number })[] = [];
+  const reasons = new Set<string>();
+  const orderedFiles = files.toSorted((left, right) =>
+    left.document.path.localeCompare(right.document.path),
+  );
+  for (const file of orderedFiles) {
+    if (!file.document.utf8) {
+      reasons.add(
+        `${file.document.path}: exact multi-term evidence requires lossless UTF-8 source`,
+      );
+    }
+  }
+  let serializedBytes = 0;
+  let exhausted = false;
+  for (let termIndex = 0; termIndex < terms.length && !exhausted; termIndex++) {
+    const term = terms[termIndex];
+    if (term === undefined) throw new Error("Missing validated anyOf term");
+    for (const file of orderedFiles) {
+      if (!file.document.utf8) continue;
+      const allowed = changedLinesOnly ? file.changedRanges : undefined;
+      for (const range of literalOccurrences(file.document, term, allowed)) {
+        const match = sourceEvidence(file.document, range);
+        const item: AnalysisItem & { termIndex: number } = {
+          path: file.document.path,
+          line: match.line,
+          label: `Exact literal occurrence for ${JSON.stringify(term)}`,
+          excerpt: match.excerpt,
+          source: file.document.reference,
+          range,
+          details: {
+            kind: "literal-term",
+            term,
+            termIndex,
+            excerptRange: match.excerptRange,
+            excerptTruncated: match.excerptTruncated,
+          },
+          termIndex,
+        };
+        const itemBytes = Buffer.byteLength(JSON.stringify(item)) + 1;
+        if (
+          items.length >= MAX_ANALYSIS_RESULTS ||
+          serializedBytes + itemBytes >=
+            MAX_ANALYSIS_STORAGE_BYTES - ANALYSIS_METADATA_RESERVE_BYTES
+        ) {
+          reasons.add("Exact multi-term retention reached the 50,000-item / 32 MiB analysis limit");
+          exhausted = true;
+          break;
+        }
+        items.push(item);
+        serializedBytes += itemBytes;
+      }
+      if (exhausted) break;
+    }
+  }
+  return {
+    items: items.map(({ termIndex: _termIndex, ...item }) => item),
+    partial: reasons.size > 0,
+    reasons: [...reasons],
+  };
+}
+
+export function retainedTermCounts(
+  terms: readonly string[],
+  items: readonly AnalysisItem[],
+): { term: string; retainedOccurrences: number }[] {
+  const counts = new Map(terms.map((term) => [term, 0]));
+  for (const item of items) {
+    const term = item.details?.term;
+    if (typeof term === "string" && counts.has(term)) counts.set(term, (counts.get(term) ?? 0) + 1);
+  }
+  return terms.map((term) => ({ term, retainedOccurrences: counts.get(term) ?? 0 }));
+}

package/src/omp-index.ts

@@ -0,0 +1,277 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_SEMANTIC_JUDGE_CONFIG,
+  normalizeSearchEnforcement,
+  readSiftLightConfigFile,
+  resolveSiftLightConfigPath,
+  SIFT_LIGHT_CONFIG_ENV,
+  type SiftLightConfig,
+} from "./config-reader.js";
+import { resolveContextBudget } from "./context-budget.js";
+import { createRipgrepRunner } from "./rg.js";
+import { createCtagsStructureProvider } from "./structure.js";
+import { SiftLightRuntime } from "./runtime.js";
+import { SESSION_STATUS_KEY } from "./session-summary.js";
+import { SiftLightService, type SiftLightInput } from "./service.js";
+import { siftLightPromptGuidelines } from "./prompt-guidelines.js";
+import {
+  renderSiftLightCall,
+  renderSiftLightResult,
+  type SiftLightToolResult,
+} from "./tui/renderers.js";
+import {
+  PREFERRED_SEARCH_GUIDANCE,
+  SEARCH_POLICY_GUIDANCE,
+  SearchPolicy,
+} from "./search-policy.js";
+import { siftLightSchema } from "./tool-schema.js";
+import { modelErrorText } from "./model-error.js";
+import { createSemanticJudgeIntegration } from "./semantic-judge.js";
+
+const SIFT_LIGHT_LABEL = "sift-light";
+const OMP_REPLACED_SEARCH_TOOLS = new Set(["grep", "glob"]);
+type OmpToolInput = SiftLightInput & { i?: unknown };
+
+function normalizeOmpToolInput(params: OmpToolInput): SiftLightInput {
+  if (!Object.hasOwn(params, "i")) return params;
+  const input = { ...params };
+  delete input.i;
+  return input;
+}
+
+interface OmpTheme {
+  bold(value: string): string;
+  fg(color: string, value: string): string;
+}
+
+interface OmpContextUsage {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}
+
+interface OmpExtensionContext {
+  cwd: string;
+  getContextUsage(): OmpContextUsage | undefined;
+  ui: {
+    setStatus(key: string, text: string | undefined): void;
+  };
+}
+
+interface OmpToolCallEvent {
+  toolName: string;
+  input: unknown;
+}
+
+interface OmpBeforeAgentStartEvent {
+  systemPrompt: string[];
+}
+
+interface OmpRenderOptions {
+  expanded: boolean;
+  isPartial: boolean;
+}
+
+interface OmpToolDefinition {
+  name: string;
+  label: string;
+  description: string;
+  approval?: "read" | "write" | "exec";
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: unknown;
+  execute(
+    toolCallId: string,
+    params: OmpToolInput,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: OmpExtensionContext,
+  ): Promise<SiftLightToolResult>;
+  renderCall?(
+    params: SiftLightInput,
+    options: unknown,
+    theme: OmpTheme,
+  ): ReturnType<typeof renderSiftLightCall>;
+  renderResult?(
+    result: SiftLightToolResult,
+    options: OmpRenderOptions,
+    theme: OmpTheme,
+    args?: SiftLightInput,
+  ): ReturnType<typeof renderSiftLightResult>;
+}
+
+interface OmpExtensionAPI {
+  registerTool(tool: OmpToolDefinition): void;
+  on(
+    event: "session_start",
+    handler: (event: unknown, ctx: OmpExtensionContext) => void | Promise<void>,
+  ): void;
+  on(
+    event: "before_agent_start",
+    handler: (
+      event: OmpBeforeAgentStartEvent,
+      ctx: OmpExtensionContext,
+    ) => void | { systemPrompt?: string[] } | Promise<void | { systemPrompt?: string[] }>,
+  ): void;
+  on(
+    event: "tool_call",
+    handler: (
+      event: OmpToolCallEvent,
+      ctx: OmpExtensionContext,
+    ) => void | { block: true; reason: string } | Promise<void | { block: true; reason: string }>,
+  ): void;
+  on(
+    event: "session_shutdown",
+    handler: (event: unknown, ctx: OmpExtensionContext) => void | Promise<void>,
+  ): void;
+  getActiveTools(): string[];
+  setActiveTools(toolNames: string[]): Promise<void>;
+}
+
+function expandTilde(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+function ompProfile(): string | undefined {
+  const value = process.env.OMP_PROFILE ?? process.env.PI_PROFILE;
+  if (value === undefined) return undefined;
+  const profile = value.trim();
+  if (!profile || profile === "default") return undefined;
+  // OMP validates this before loading extensions. Keep direct SDK imports safe
+  // as well, without allowing an environment value to escape the profile root.
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(profile) || profile.endsWith(".")) return undefined;
+  return profile;
+}
+
+/** Resolve the same profile-scoped config directory that OMP exposes to extensions. */
+function ompAgentDir(): string {
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (configured) return expandTilde(configured);
+  const configDir = process.env.PI_CONFIG_DIR || ".omp";
+  const profile = ompProfile();
+  return profile
+    ? join(homedir(), configDir, "profiles", profile, "agent")
+    : join(homedir(), configDir, "agent");
+}
+
+function selectSearchTools(pi: OmpExtensionAPI, replaceAlternatives: boolean): string[] {
+  const current = pi.getActiveTools();
+  const next = replaceAlternatives
+    ? current.filter((tool) => !OMP_REPLACED_SEARCH_TOOLS.has(tool))
+    : [...current];
+  if (!next.includes(SIFT_LIGHT_LABEL)) next.push(SIFT_LIGHT_LABEL);
+  return next;
+}
+
+function toolSelectionChanged(current: string[], next: string[]): boolean {
+  return current.length !== next.length || next.some((tool, index) => tool !== current[index]);
+}
+
+function resultOptions(
+  options: OmpRenderOptions,
+  result: SiftLightToolResult,
+): OmpRenderOptions & { isError: boolean } {
+  return { ...options, isError: result.isError === true };
+}
+
+export async function registerOmpSiftLightExtension(
+  pi: OmpExtensionAPI,
+  searchPolicyAssets = new URL("../plugins/sift-light/hooks/", import.meta.url),
+  config?: SiftLightConfig,
+): Promise<void> {
+  const policy = new SearchPolicy(searchPolicyAssets);
+  const resolvedConfig =
+    config ??
+    (await readSiftLightConfigFile(resolveSiftLightConfigPath(ompAgentDir()), {
+      missing: process.env[SIFT_LIGHT_CONFIG_ENV]?.trim() ? "error" : "defaults",
+    }));
+  const semanticJudge = createSemanticJudgeIntegration(
+    resolvedConfig.semanticJudge ?? DEFAULT_SEMANTIC_JUDGE_CONFIG,
+  );
+  const runtime = new SiftLightRuntime(
+    new SiftLightService({
+      runRipgrep: createRipgrepRunner(),
+      structure: createCtagsStructureProvider(),
+      semanticJudge,
+    }),
+  );
+  const { locale } = resolvedConfig;
+  const enforcement = normalizeSearchEnforcement(
+    resolvedConfig.enforceSearch,
+    "OMP extension config",
+  );
+  let selection = Promise.resolve();
+  const updateSelection = async (): Promise<void> => {
+    const current = pi.getActiveTools();
+    const next = selectSearchTools(pi, enforcement === "hard");
+    if (toolSelectionChanged(current, next)) await pi.setActiveTools(next);
+  };
+  const selectTools = (): Promise<void> => {
+    selection = selection.then(updateSelection);
+    return selection;
+  };
+
+  pi.registerTool({
+    name: SIFT_LIGHT_LABEL,
+    label: SIFT_LIGHT_LABEL,
+    description:
+      "Search and navigate code with bounded, verifiable evidence. Use pattern for content or mode=files with query for filenames.",
+    approval: "read",
+    promptSnippet: "Search file contents without flooding context",
+    promptGuidelines: siftLightPromptGuidelines(),
+    parameters: siftLightSchema,
+
+    renderCall(params, _options, theme) {
+      return renderSiftLightCall(params, locale, theme);
+    },
+
+    renderResult(result, options, theme) {
+      return renderSiftLightResult(result, resultOptions(options, result), locale, theme);
+    },
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      try {
+        const result = await runtime.search(
+          normalizeOmpToolInput(params),
+          ctx.cwd,
+          signal,
+          resolveContextBudget(ctx.getContextUsage()),
+        );
+        ctx.ui.setStatus(SESSION_STATUS_KEY, runtime.formatSessionStatus(locale));
+        return {
+          content: [{ type: "text", text: result.text }],
+          details: result.details,
+        };
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        runtime.recordFailure();
+        ctx.ui.setStatus(SESSION_STATUS_KEY, runtime.formatSessionStatus(locale));
+        // oxlint-disable-next-line preserve-caught-error -- the model boundary must not expose a recursive cause chain
+        throw new Error(modelErrorText(error));
+      }
+    },
+  });
+
+  if (enforcement !== "off") {
+    pi.on("session_start", selectTools);
+    pi.on("before_agent_start", async (event) => {
+      await selectTools();
+      const guidance = enforcement === "hard" ? SEARCH_POLICY_GUIDANCE : PREFERRED_SEARCH_GUIDANCE;
+      return { systemPrompt: [...event.systemPrompt, guidance] };
+    });
+    if (enforcement === "hard")
+      pi.on("tool_call", (event) => policy.check(event.toolName, event.input));
+  }
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await runtime.shutdown();
+    ctx.ui.setStatus(SESSION_STATUS_KEY, undefined);
+  });
+}
+
+export default async function siftLightOmpExtension(pi: OmpExtensionAPI): Promise<void> {
+  await registerOmpSiftLightExtension(pi);
+}

package/src/omp-marketplace-entry.ts

@@ -0,0 +1,7 @@
+import { registerOmpSiftLightExtension } from "./omp-index.js";
+
+export default async function marketplaceSiftLightExtension(
+  pi: Parameters<typeof registerOmpSiftLightExtension>[0],
+): Promise<void> {
+  await registerOmpSiftLightExtension(pi, new URL("./hooks/", import.meta.url));
+}