@nijaru/pi-search 0.0.1

package/src/contracts.ts

@@ -0,0 +1,644 @@
+/**
+ * Provider-neutral contracts for pi-search.
+ *
+ * These types are the foundation of the extension. They are intentionally
+ * agnostic of how a provider fulfills a request — whether by a direct HTTP
+ * search endpoint (Brave, Exa, or Parallel) or by a model-mediated grounding
+ * call (OpenAI/Codex, Gemini, or xAI). See `docs/DESIGN.md` for the shipped
+ * boundary.
+ *
+ * Nothing here performs I/O or depends on Pi runtime APIs, so it can be
+ * unit-tested deterministically and offline. Provider adapters build on these
+ * contracts and keep their transport and payload handling in separate modules.
+ */
+
+// ─── Common ────────────────────────────────────────────────────────────────
+
+/**
+ * A normalized, canonical URL string (already resolved against redirects,
+ * with fragment and tracking-noise stripped where a provider exposes it).
+ * The original URL the user/agent supplied is preserved separately as
+ * `source_url` when it differs.
+ */
+export type Url = string;
+
+/**
+ * ISO-8601 timestamp string when a result was published, fetched, or
+ * indexed. Omitted when the provider does not surface one.
+ */
+export type IsoTimestamp = string;
+
+/**
+ * Opaque identifier a provider returns for a single search call, useful for
+ * debugging, cost attribution, and provider-side replay. Optional.
+ */
+export type RequestId = string;
+
+/** Pi's header override contract: null deletes a provider/default header. */
+export type ProviderHeaders = Readonly<Record<string, string | null>>;
+/**
+ * The immutable subset of Pi's active model needed by model-mediated
+ * providers. Keeping this structural avoids coupling provider adapters to Pi's
+ * runtime types while still making the routing and auth boundary explicit.
+ */
+export interface ProviderModel {
+	readonly id: string;
+	readonly provider: string;
+	readonly api: string;
+	readonly baseUrl: string;
+	readonly headers?: ProviderHeaders;
+}
+
+/** The result of resolving credentials through Pi's model registry. */
+export type ProviderAuthResult =
+	| {
+			readonly ok: true;
+			readonly apiKey?: string;
+			readonly headers?: ProviderHeaders;
+		}
+	| {
+			readonly ok: false;
+			readonly error: string;
+		};
+
+/**
+ * The narrow model-auth surface needed by model-mediated providers. The tool
+ * boundary binds this function to Pi's model registry, so adapters can resolve
+ * the active model or a same-provider execution model without reading Pi auth
+ * state or environment credentials globally.
+ */
+export interface ProviderModelRegistry {
+	readonly getApiKeyAndHeaders: (model: ProviderModel) => Promise<ProviderAuthResult>;
+	/** Available authenticated-model metadata for adapters that need a provider-compatible execution model. */
+	readonly getModels?: () => readonly ProviderModel[];
+}
+
+/**
+ * Runtime services supplied by the Pi tool boundary to a provider adapter.
+ * Direct HTTP providers may ignore this context; model-mediated providers
+ * must use `modelRegistry` rather than reading Pi credentials globally.
+ */
+export interface ProviderContext {
+	readonly model?: ProviderModel;
+	readonly modelRegistry?: ProviderModelRegistry;
+}
+
+/**
+ * Operational information used by the router for bounded provider selection.
+ * Estimates are advisory; actual usage belongs in `SearchResponse.usage`.
+ */
+export interface ProviderProfile {
+	readonly typicalLatencyMs?: number;
+	readonly estimatedCostUsd?: number;
+	readonly costModel: "free" | "per-request" | "usage-based" | "unknown";
+	readonly auth: "none" | "environment" | "modelRegistry";
+}
+
+/** A single provider-reported quota or rate-limit window. */
+export interface ProviderRateLimitWindow {
+	/** Maximum calls in this window, when the provider reports it. */
+	readonly limit?: number;
+	/** Calls remaining in this window, when the provider reports it. */
+	readonly remaining?: number;
+	/** Absolute reset time, when the provider reports one. */
+	readonly resetAt?: IsoTimestamp;
+	/** Relative reset delay, when the provider reports one. */
+	readonly resetAfterMs?: number;
+	/** Provider-defined scope such as `second` or `month`. */
+	readonly scope?: string;
+}
+
+/** Provider-reported rate-limit metadata. It is observational, never a budget reservation. */
+export interface ProviderRateLimitInfo {
+	readonly windows: readonly ProviderRateLimitWindow[];
+	readonly retryAfterMs?: number;
+}
+
+/**
+ * Provider-reported billing and capacity information when available.
+ */
+export interface ProviderUsage {
+	readonly costUsd?: number;
+	readonly billedUnits?: number;
+	readonly billedUnit?: string;
+	/** Number of provider-side search queries when exposed separately from token usage. */
+	readonly searchQueries?: number;
+	/** Provider-reported input/prompt token count, when available. */
+	readonly inputTokens?: number;
+	/** Provider-reported output/completion token count, when available. */
+	readonly outputTokens?: number;
+	/** Provider-reported total token count, when available. */
+	readonly totalTokens?: number;
+	readonly rateLimits?: ProviderRateLimitInfo;
+}
+
+/**
+ * Free-form capability flags describing what a provider can do. The router
+ * uses these to select a provider by task rather than by a fixed vendor
+ * ranking (D3).
+ */
+export interface ProviderCapabilities {
+	/** Classic keyword / exact-match retrieval. */
+	readonly keyword?: boolean;
+	/** Freshness-sensitive retrieval. */
+	readonly freshness?: boolean;
+	/** Semantic or natural-language retrieval. */
+	readonly semantic?: boolean;
+	/** Returns source excerpts alongside the URL. */
+	readonly excerpts?: boolean;
+	/** Supports domain include/exclude filters. */
+	readonly domainFilter?: boolean;
+	/** Supports provider-enforced date ranges. */
+	readonly dateFilter?: boolean;
+	/** Searches social sources such as X. */
+	readonly social?: boolean;
+	/** Supports provider-enforced social-handle filters. */
+	readonly handleFilter?: boolean;
+	/** Supports provider-side image/video understanding during search. */
+	readonly mediaUnderstanding?: boolean;
+	/** Uses a model's native grounding/search tool. */
+	readonly nativeGrounding?: boolean;
+	/** Supports provider-native search context sizing. */
+	readonly searchContextSize?: boolean;
+	/** Supports provider-native returned-token budgets. */
+	readonly returnTokenBudget?: boolean;
+	/** Supports live/cache-only search selection. */
+	readonly externalWebAccess?: boolean;
+	/** Supports approximate user location. */
+	readonly userLocation?: boolean;
+	/** Supports provider-native content-type selection. */
+	readonly searchContentTypes?: boolean;
+	/** Supports image result settings. */
+	readonly imageSettings?: boolean;
+}
+
+// ─── Search ────────────────────────────────────────────────────────────────
+
+/**
+ * How results should be ranked/retrieved. Mirrors the capability axes so the
+ * router can pick a provider whose capabilities match the requested mode.
+ */
+export type SearchMode = "auto" | "keyword" | "fresh";
+
+/**
+ * Domain filter: restrict or exclude specific hosts.
+ *
+ * Empty by default. An entry in `include` restricts results to those hosts;
+ * an entry in `exclude` removes them. A host should not appear in both.
+ */
+export interface DomainFilter {
+	readonly include?: readonly string[];
+	readonly exclude?: readonly string[];
+}
+
+/** Provider-enforced temporal bounds for providers that support them. */
+export interface SearchDateRange {
+	readonly from?: string;
+	readonly to?: string;
+}
+
+/** Provider-enforced social/X constraints. */
+export interface SocialSearchOptions {
+	readonly includeHandles?: readonly string[];
+	readonly excludeHandles?: readonly string[];
+	readonly understandImages?: boolean;
+	readonly understandVideos?: boolean;
+}
+
+export type SearchContextSize = "low" | "medium" | "high";
+export type SearchReturnTokenBudget = "default" | "unlimited";
+export type SearchContentType = "text" | "image";
+
+export interface SearchUserLocation {
+	readonly type: "approximate";
+	readonly country?: string;
+	readonly region?: string;
+	readonly city?: string;
+	readonly timezone?: string;
+}
+
+export interface SearchImageSettings {
+	readonly maxResults?: number;
+	readonly caption?: boolean;
+}
+
+/**
+ * Provider-neutral search request. Every field is optional except `query`
+ * so that a caller can start with a bare string and refine as needed.
+ *
+ * Adapters map this to their provider-specific payload. Unsupported options
+ * must be surfaced in `SearchResponse.warnings`; hard constraints must never
+ * disappear silently.
+ */
+export type SearchAnswerMode = "auto" | "evidence";
+
+export interface SearchRequest {
+	/** Natural-language or keyword query. Required. */
+	readonly query: string;
+	/** Retrieval bias; default `auto`. */
+	readonly mode?: SearchMode;
+	/** Maximum results to return. Adapters may return fewer. */
+	readonly maxResults?: number;
+	/** Restrict/exclude hosts. */
+	readonly domains?: DomainFilter;
+	/** Provider-enforced date range, when supported. */
+	readonly dateRange?: SearchDateRange;
+	/** Provider-enforced social/X constraints, when supported. */
+	readonly social?: SocialSearchOptions;
+	/** Select a model-mediated execution model; requires a compatible provider hint when cross-provider. */
+	readonly executionModel?: string;
+	/** Include a provider-grounded answer when the backend supplies one. */
+	readonly answerMode?: SearchAnswerMode;
+	/** Provider-native amount of search context supplied to the model. */
+	readonly searchContextSize?: SearchContextSize;
+	/** Provider-native returned-token budget for long research runs. */
+	readonly returnTokenBudget?: SearchReturnTokenBudget;
+	/** Whether provider search may use live internet access. */
+	readonly externalWebAccess?: boolean;
+	/** Approximate location used to localize provider search results. */
+	readonly userLocation?: SearchUserLocation;
+	/** Provider-native content types to retrieve. */
+	readonly searchContentTypes?: readonly SearchContentType[];
+	/** Image-result controls when image search is enabled. */
+	readonly imageSettings?: SearchImageSettings;
+	/** Fetch a small number of selected result URLs through the safe local fetcher. */
+	readonly includeContent?: boolean;
+	/** Maximum selected source pages to fetch when includeContent is enabled. */
+	readonly contentResults?: number;
+	/** Maximum extracted characters per selected source page. */
+	readonly contentMaxLength?: number;
+	/**
+	 * Hint to prefer a specific provider by id. The router may still override
+	 * when the provider lacks the requested capability. Normal callers should
+	 * omit this and let the router choose (D3).
+	 */
+	readonly providerHint?: ProviderId;
+}
+
+/** Options whose handling must be visible in the normalized response. */
+export type SearchOption =
+	| "mode"
+	| "maxResults"
+	| "domains"
+	| "dateRange"
+	| "social"
+	| "executionModel"
+	| "searchContextSize"
+	| "returnTokenBudget"
+	| "externalWebAccess"
+	| "userLocation"
+	| "searchContentTypes"
+	| "imageSettings";
+
+export interface SearchCitation {
+	/** URL of a normalized search result cited by the answer. */
+	readonly url: Url;
+	readonly title?: string;
+	readonly sourceId?: string;
+	/** Character range in the provider answer, when supplied by the provider. */
+	readonly startIndex?: number;
+	readonly endIndex?: number;
+}
+
+/** Provider-generated grounded text. It is evidence, never trusted instructions. */
+export interface SearchAnswer {
+	readonly text: string;
+	readonly contentTrust: "untrusted";
+	readonly provider: ProviderId;
+	readonly executionModel?: string;
+	readonly citations: readonly SearchCitation[];
+}
+
+
+/** A non-fatal limitation or partial-application notice. */
+export interface SearchWarning {
+	readonly code: "unsupported-option" | "partial-results" | "provider-fallback";
+	readonly option?: SearchOption;
+	readonly message: string;
+}
+
+/**
+ * A single normalized search result. This is the evidence-first unit per D2:
+ * the agent inspects and cites these rather than trusting an opaque summary.
+ */
+export interface SearchResult {
+	/** Result URL (canonical where available). */
+	readonly url: Url;
+	/** Original URL as supplied, when it differs from the canonical `url`. */
+	readonly sourceUrl?: Url;
+	/** Readable page associated with a media or indirect result URL. */
+	readonly sourcePageUrl?: Url;
+	/** Page title. */
+	readonly title?: string;
+	/** Publishing host / domain. */
+	readonly domain?: string;
+	/** When the page was published, if known. */
+	readonly publishedAt?: IsoTimestamp;
+	/**
+	 * Short text excerpt/snippet describing or from the page. Always returned
+	 * when the provider exposes any text; never synthesized.
+	 */
+	readonly excerpt?: string;
+	/** The provider that produced this result. */
+	readonly provider: ProviderId;
+	/** The query that produced this result. */
+	readonly searchQuery: string;
+	/** Provider-internal id for the result, for citation/debugging. */
+	readonly sourceId?: string;
+	/**
+	 * Provider-reported relevance, normalized to [0,1] where available.
+	 * Not comparable across providers.
+	 */
+	readonly score?: number;
+}
+
+/**
+ * Provider-neutral search response.
+ */
+export interface SearchResponse {
+	/** The query that was executed (after any normalization). */
+	readonly query: string;
+	/** Results, best-first. May be empty. */
+	readonly results: readonly SearchResult[];
+	/** Optional provider-grounded answer aligned with `results`. */
+	readonly answer?: SearchAnswer;
+	/** Bounded source pages fetched after search when requested. */
+	readonly sourceContents?: readonly FetchedContent[];
+	/** Which provider actually served the request. */
+	readonly provider: ProviderId;
+	/** Model used by a model-mediated provider, when available. */
+	readonly executionModel?: string;
+	/** Providers attempted by bounded automatic routing, in order. */
+	readonly attemptedProviders?: readonly ProviderId[];
+	/** Options the provider applied, including post-filtered constraints. */
+	readonly appliedOptions: readonly SearchOption[];
+	/** Explicit warnings for options that were unsupported or only partial. */
+	readonly warnings: readonly SearchWarning[];
+	/** Provider request id for debugging/attribution. */
+	readonly requestId?: RequestId;
+	/** Wall-clock latency in milliseconds. */
+	readonly latencyMs?: number;
+	/** Provider-reported billing information, when available. */
+	readonly usage?: ProviderUsage;
+}
+
+// ─── Research ──────────────────────────────────────────────────────────────
+
+/**
+ * Required limits for the multi-step research tool. The orchestrator must
+ * reject invalid budgets before making a provider call and stop at every
+ * limit, including the cost limit when usage is reported.
+ */
+export interface ResearchBudget {
+	readonly maxSteps: number;
+	readonly maxProviderCalls: number;
+	readonly maxFetches: number;
+	readonly timeoutMs: number;
+	readonly maxOutputChars: number;
+	readonly maxCostUsd?: number;
+}
+
+export interface ResearchRequest {
+	readonly question: string;
+	/** The caller supplies the query plan; defaults to [question]. */
+	readonly queries?: readonly string[];
+	readonly budget: ResearchBudget;
+	/** Select one provider strictly for the whole invocation. */
+	readonly provider?: "native" | SearchProviderHintId;
+	/** Explicit model id for a model-mediated provider. */
+	readonly executionModel?: string;
+	/** Number of result URLs to fetch after search, bounded by budget.maxFetches. */
+	readonly fetchResults?: number;
+}
+
+export type ResearchStopReason = "completed" | "partial" | "budget" | "deadline" | "canceled" | "provider-error";
+
+export interface ResearchResponse {
+	readonly question: string;
+	/** The single provider selected for the whole research invocation. */
+	readonly provider: ProviderId;
+	/** Model used when the selected provider is model-mediated. */
+	readonly executionModel?: string;
+	readonly results: readonly SearchResult[];
+	readonly fetched: readonly FetchedContent[];
+	readonly stepsCompleted: number;
+	readonly providerCalls: number;
+	readonly fetchesCompleted: number;
+	readonly fetchAttempts: number;
+	readonly stopReason: ResearchStopReason;
+	readonly usage?: ProviderUsage;
+	readonly warnings: readonly SearchWarning[];
+}
+
+/** Validate the hard limits before the research orchestrator starts. */
+export function validateResearchBudget(budget: ResearchBudget): void {
+	if (!Number.isInteger(budget.maxSteps) || budget.maxSteps < 1) {
+		throw new Error("Research budget maxSteps must be a positive integer");
+	}
+	if (!Number.isInteger(budget.maxProviderCalls) || budget.maxProviderCalls < 1) {
+		throw new Error("Research budget maxProviderCalls must be a positive integer");
+	}
+	if (!Number.isInteger(budget.maxFetches) || budget.maxFetches < 0) {
+		throw new Error("Research budget maxFetches must be a non-negative integer");
+	}
+	if (!Number.isFinite(budget.timeoutMs) || budget.timeoutMs <= 0) {
+		throw new Error("Research budget timeoutMs must be positive");
+	}
+	if (!Number.isInteger(budget.maxOutputChars) || budget.maxOutputChars < 1) {
+		throw new Error("Research budget maxOutputChars must be a positive integer");
+	}
+	if (budget.maxCostUsd !== undefined && (!Number.isFinite(budget.maxCostUsd) || budget.maxCostUsd < 0)) {
+		throw new Error("Research budget maxCostUsd must be non-negative");
+	}
+}
+
+// ─── Fetch ─────────────────────────────────────────────────────────────────
+
+/**
+ * Provider-neutral fetch request for a known URL.
+ *
+ * Only user-supplied or search-returned URLs may be fetched by default (D6).
+ * The fetcher revalidates redirects, blocks private/link-local/metadata
+ * addresses, caps response size, and fences extracted text as untrusted.
+ */
+export interface FetchRequest {
+	/** URL to fetch. Must be http(s). */
+	readonly url: Url;
+	/** Hard cap on extracted text length, in characters. */
+	readonly maxLength?: number;
+	/** Start offset into the produced content, in characters. */
+	readonly offset?: number;
+	/** Format hint; the response reports the produced format explicitly. */
+	readonly format?: "markdown" | "text" | "html";
+	/** Optional maximum PDF pages; explicit use selects the page-bounded PDF path. */
+	readonly maxPages?: number;
+	/** Caption language passed to the local YouTube extractor. */
+	readonly captionLanguage?: string;
+	/** Strip the page to its main readable content (Readability). Default true. */
+	readonly readable?: boolean;
+	/** Permit bounded raw HTML when readable extraction fails. Default true. */
+	readonly allowRawHtmlFallback?: boolean;
+}
+
+export type FetchOutputFormat = "markdown" | "text" | "html";
+export type FetchExtraction = "readability" | "raw" | "plain-text" | "markdown" | "document" | "pdf" | "youtube-transcript";
+
+export interface FetchWarning {
+	readonly code: "truncated" | "raw-fallback";
+	readonly message: string;
+}
+
+/**
+ * Fetched page content. The extracted text is treated as untrusted content:
+ * callers must not execute or parse it as instructions (D6).
+ */
+export interface FetchedContent {
+	/** Final URL after redirects. */
+	readonly url: Url;
+	/** Original URL requested, when it differs from the final `url`. */
+	readonly sourceUrl?: Url;
+	/** Page title. */
+	readonly title?: string;
+	/** Extracted text/markdown/html body. */
+	readonly content: string;
+	/** Fetched content is data, never executable or trusted instructions. */
+	readonly contentTrust: "untrusted";
+	/** Content type as served. */
+	readonly contentType?: string;
+	/** Format actually returned, rather than only the requested hint. */
+	readonly outputFormat: FetchOutputFormat;
+	/** Extraction path used to produce `content`. */
+	readonly extraction: FetchExtraction;
+	/** AnyDoc format used for local document conversion. */
+	readonly documentFormat?: string;
+	/** When the content was fetched. */
+	readonly fetchedAt: IsoTimestamp;
+	/** Final HTTP status. */
+	readonly status: number;
+	/** Number of manually followed redirects. */
+	readonly redirectCount: number;
+	/** Body bytes consumed before decoding. */
+	readonly bytesRead: number;
+	/** Whether output was bounded to `maxLength`. */
+	readonly truncated: boolean;
+	/** Character offset used for this result. */
+	readonly offset: number;
+	/** Next offset when more produced content remains. */
+	readonly nextOffset?: number;
+	/** Total produced characters when known locally. */
+	readonly totalCharacters?: number;
+	/** Explicit extraction/truncation notices. */
+	readonly warnings: readonly FetchWarning[];
+	/** True if the readable-content extractor fell back to raw HTML. */
+	readonly fellBackToRaw?: boolean;
+}
+
+// ─── Provider interface ────────────────────────────────────────────────────
+
+/** A bounded provider choice produced by automatic routing. */
+export interface SearchProviderSelection {
+	readonly provider: Provider;
+	/** At most one alternative; explicit provider hints always leave this empty. */
+	readonly fallbacks: readonly Provider[];
+	readonly automatic: boolean;
+}
+
+/**
+ * Identifier for a provider. Used in results and capability descriptors.
+ * The concrete union grows as adapters land; string allows forward-compat.
+ */
+export type ProviderId =
+	| "native"
+	| "openai"
+	| "openai-codex"
+	| "gemini"
+	| "brave"
+	| "exa"
+	| "parallel"
+	| "parallel-responses"
+	| "brave-answers"
+	| "x"
+	| "xai"
+	| "xai-x"
+	| "anthropic"
+	| "meta"
+	| (string & {});
+
+/** Concrete providers accepted as an explicit `provider` hint (no `native` alias). */
+export const SEARCH_PROVIDER_HINT_IDS = [
+	"openai",
+	"openai-codex",
+	"gemini",
+	"brave",
+	"exa",
+	"parallel",
+	"parallel-responses",
+	"brave-answers",
+	"x",
+	"xai",
+	"xai-x",
+	"anthropic",
+	"meta",
+] as const;
+export type SearchProviderHintId = (typeof SEARCH_PROVIDER_HINT_IDS)[number];
+
+/**
+ * A normalized error from a provider call. Carries enough to route retries
+ * or report to the agent without leaking provider-specific payload shapes.
+ */
+export interface ProviderError extends Error {
+	readonly provider: ProviderId;
+	/** Network failure, auth failure, rate limit, bad request, or availability. */
+	readonly kind:
+		| "network"
+		| "auth"
+		| "rateLimit"
+		| "badRequest"
+		| "malformed"
+		| "unsupported"
+		| "timeout"
+		| "canceled"
+		| "http"
+		| "unavailable"
+		| "unknown";
+	/** HTTP status if applicable. */
+	readonly status?: number;
+	/** Provider request identifier when one exists. */
+	readonly requestId?: RequestId;
+	/** Provider-advised delay before another call. */
+	readonly retryAfterMs?: number;
+	/** Provider-reported quota metadata. */
+	readonly rateLimits?: ProviderRateLimitInfo;
+	/** Whether retrying the same provider could help. */
+	readonly retryable: boolean;
+}
+
+/**
+ * The provider-neutral adapter contract. Both adapter families (D10) implement
+ * this: a direct search API maps the request to an HTTP call and parses the
+ * response; a model-mediated grounding provider maps it to a grounded model
+ * call. The contract is identical to the caller.
+ *
+ * `fetch` is optional because not every search provider also fetches pages;
+ * direct HTTP fetch is handled separately in the `web_fetch` tool.
+ */
+export interface Provider {
+	readonly id: ProviderId;
+	readonly capabilities: ProviderCapabilities;
+	readonly profile: ProviderProfile;
+	/**
+	 * Execute a search. Adapters must:
+	 * - apply supported options and list them in `appliedOptions`;
+	 * - report unsupported options in `warnings` or throw `ProviderError` with
+	 *   kind `unsupported`;
+	 * - normalize results to {@link SearchResult};
+	 * - preserve `url`, `excerpt`, `publishedAt`, `provider`, `searchQuery`;
+	 * - return evidence and, when supplied by the backend, a typed untrusted
+	 *   answer whose citations align with returned result URLs.
+	 */
+	readonly search: (
+		request: SearchRequest,
+		signal: AbortSignal,
+		context: ProviderContext,
+	) => Promise<SearchResponse>;
+}