@autorag/librarian 2.9.0 → 2.10.1

package/dist/cloud/authorize.d.ts

@@ -0,0 +1,12 @@
+export interface AuthorizeUrlParams {
+    /** Server root, e.g. `https://api.dazziapp.com`. */
+    baseUrl: string;
+    /** Loopback redirect URI chosen by the login flow. */
+    redirectUri: string;
+    /** Random `state` echoed back on the redirect. */
+    state: string;
+    /** S256 code challenge derived from the PKCE verifier. */
+    codeChallenge: string;
+}
+/** Build the browser authorization URL for the PKCE authorization-code flow. */
+export declare function buildAuthorizeUrl(params: AuthorizeUrlParams): string;

package/dist/cloud/callback-server.d.ts

@@ -0,0 +1,33 @@
+/** Path the browser is redirected to on the loopback listener. */
+export declare const CALLBACK_PATH = "/callback";
+/** Loopback listeners are ephemeral; abandon a login nobody completes. */
+export declare const DEFAULT_LOGIN_TIMEOUT_MS: number;
+export interface CallbackServer {
+    /** `http://127.0.0.1:<ephemeral port>/callback`. */
+    redirectUri: string;
+    /** Resolves with the first callback's query parameters. */
+    waitForCallback(): Promise<URLSearchParams>;
+    /** Stop listening and abandon any pending wait. */
+    close(): void;
+}
+export interface CallbackServerOptions {
+    /** Loopback interface to bind. Defaults to `127.0.0.1`. */
+    host?: string;
+    /**
+     * Expected OAuth `state`. A browser callback is only accepted when it
+     * echoes this value, so a stray or forged request cannot win the race.
+     */
+    state: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onListening?: (redirectUri: string) => void;
+}
+/**
+ * Start a loopback HTTP listener for the OAuth redirect.
+ *
+ * The server closes itself as soon as the first valid callback — a request
+ * that echoes {@link CallbackServerOptions.state} and carries a `code` or
+ * `error` — arrives; malformed or forged requests get a `400` and are ignored.
+ * It also closes on abort and on timeout. Requests to other paths are ignored.
+ */
+export declare function startCallbackServer(options: CallbackServerOptions): Promise<CallbackServer>;

package/dist/cloud/callback.d.ts

@@ -0,0 +1,23 @@
+/** Authorization response extracted from either the loopback server or a manual paste. */
+export interface CallbackResult {
+    code?: string;
+    error?: string;
+    state?: string;
+}
+/** Read an authorization response out of query parameters. */
+export declare function parseCallbackQuery(params: URLSearchParams): CallbackResult;
+/**
+ * Parse what the user pasted when the browser could not reach the loopback
+ * server: a full redirect URL, a bare `code=...&state=...` query, or just the
+ * authorization code.
+ */
+export declare function parseCallbackInput(input: string): CallbackResult;
+/**
+ * Validate an authorization response against the expected `state` and return
+ * the authorization code. `state` is compared whenever the response carries
+ * one; a mismatch always aborts the login. A manual code paste carries no
+ * `state`, so there is nothing to compare there.
+ */
+export declare function requireAuthorizationCode(result: CallbackResult, expectedState: string): {
+    code: string;
+};

package/dist/cloud/config.d.ts

@@ -0,0 +1,41 @@
+/** Provider identity and endpoint configuration for the hosted AutoRAG (Dazzi) plan. */
+export declare const PROVIDER_ID = "autorag";
+export declare const PROVIDER_NAME = "AutoRAG";
+/** Server root, e.g. `https://api.dazziapp.com`. The API lives under `<root>/v1`. */
+export declare const DEFAULT_BASE_URL = "https://api.dazziapp.com";
+export declare const AUTORAG_BASE_URL_ENV = "AUTORAG_BASE_URL";
+export declare const AUTORAG_API_KEY_ENV = "AUTORAG_API_KEY";
+/** Server paths appended to the normalized server root. */
+export declare const API_PATH = "/v1";
+export declare const MODELS_PATH = "/v1/models";
+export declare const AUTHORIZE_PATH = "/desktop/authorize";
+export declare const TOKEN_PATH = "/api/desktop/token";
+/**
+ * Request limits of the hosted API, declared on every `autorag` model.
+ *
+ * The API is served from Vercel, which rejects a request body above about
+ * 4.49 MB with HTTP 413 before it reaches the model (measured against
+ * `POST /v1/responses`). pi resends every image a tool returned on each later
+ * turn, so a search that reads a few photos crosses that line. The transcript
+ * cap leaves headroom for the tool declarations and request framing the
+ * transcript size does not count; the resize cap keeps one image well below it.
+ */
+export declare const AUTORAG_INPUT_LIMITS: {
+    readonly maxRequestBytes: 3500000;
+    readonly images: {
+        readonly resize: {
+            readonly maxBytes: 1000000;
+        };
+    };
+};
+/** OAuth client identifier for the AutoRAG agent (Pi-compatible hosts use `pi`). */
+export declare const OAUTH_CLIENT_ID = "agent";
+/**
+ * Value used for `ProviderConfig.apiKey`. Pi resolves `$NAME` from the
+ * environment, so `AUTORAG_API_KEY` enables a headless, login-free setup.
+ */
+export declare const API_KEY_CONFIG_VALUE = "$AUTORAG_API_KEY";
+/** Trim whitespace and trailing slashes so path concatenation is unambiguous. */
+export declare function normalizeBaseUrl(value: string): string;
+/** Server root from `AUTORAG_BASE_URL`, falling back to {@link DEFAULT_BASE_URL}. */
+export declare function resolveBaseUrl(env: Record<string, string | undefined>): string;

package/dist/cloud/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Error types for the hosted AutoRAG (Dazzi) provider.
+ *
+ * Messages never contain credentials, authorization headers, or provider
+ * payloads; they are safe to surface in the CLI UI and in test assertions.
+ */
+/** Base class for every error raised by the AutoRAG provider. */
+export declare class AutoragError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Raised for OAuth/PKCE/callback failures. */
+export declare class AutoragOAuthError extends AutoragError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Raised when an HTTP call to AutoRAG fails.
+ *
+ * `status` is the HTTP status code, `code`/`type` come from the OpenAI-shaped
+ * error body when the server supplies them.
+ */
+export declare class AutoragHttpError extends AutoragError {
+    readonly status: number;
+    readonly code?: string;
+    readonly type?: string;
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        type?: string;
+        cause?: unknown;
+    });
+}
+export interface ErrorPayload {
+    message?: string;
+    code?: string;
+    type?: string;
+}
+/**
+ * Extract `{ message, code, type }` from an OpenAI-shaped error body:
+ * `{ "error": { "message": ..., "type": ..., "code": ... } }`.
+ * Also tolerates `{ "error": "message" }` and a bare `{ "message": ... }`.
+ */
+export declare function extractErrorPayload(body: unknown): ErrorPayload;

package/dist/cloud/index.d.ts

@@ -0,0 +1,12 @@
+export type { AuthorizeUrlParams } from "./authorize.js";
+export { buildAuthorizeUrl } from "./authorize.js";
+export type { CallbackResult } from "./callback.js";
+export { parseCallbackInput, parseCallbackQuery, requireAuthorizationCode } from "./callback.js";
+export { CALLBACK_PATH, type CallbackServer, type CallbackServerOptions, DEFAULT_LOGIN_TIMEOUT_MS, startCallbackServer, } from "./callback-server.js";
+export { API_KEY_CONFIG_VALUE, API_PATH, AUTHORIZE_PATH, AUTORAG_API_KEY_ENV, AUTORAG_BASE_URL_ENV, DEFAULT_BASE_URL, MODELS_PATH, normalizeBaseUrl, OAUTH_CLIENT_ID, PROVIDER_ID, PROVIDER_NAME, resolveBaseUrl, TOKEN_PATH, } from "./config.js";
+export { AutoragError, AutoragHttpError, AutoragOAuthError, type ErrorPayload, extractErrorPayload, } from "./errors.js";
+export { buildStoreEntry, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, type FetchModelsOptions, fetchModels, mapModelsError, mapServerModel, mapServerModels, modelsFromStore, resolveCredentialKey, } from "./models.js";
+export { type LoginOptions, loginAutorag, refreshAutoragCredentials } from "./oauth-login.js";
+export { base64UrlEncode, createCodeChallenge, createCodeVerifier, createPkcePair, createState, type PkcePair, } from "./pkce.js";
+export { type AutoragEnv, createAutoRAGProviderConfig, refreshAutoragModels, registerAutoRAGProvider, } from "./provider.js";
+export { type ExchangeCodeOptions, exchangeCodeForToken, mapTokenExchangeError, type TokenResponse } from "./token.js";

package/dist/cloud/jev-backend.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Jev backend for the hosted AutoRAG (Dazzi) plan.
+ *
+ * The server answers Jev's native dialect at `POST <root>/v1/jev` behind the
+ * account bearer key (`AUTORAG_API_KEY`), returning the same `answers` map the
+ * TypeSafe and OpenRouter backends do. `jev-use`'s package index does not
+ * export its native-dialect helpers, so the small mapping and the retrying JSON
+ * transport are reimplemented here against that documented dialect (covered by
+ * tests against a local HTTP server).
+ *
+ * Failures surface as `BackendError(name, "HTTP <status>: <message>", status)`
+ * so the engine degrades to an escalation with a readable hint instead of
+ * blocking the loop.
+ */
+import { type BackendRequest, type BackendResponse, type JevBackend, type Question, type RawAnswer, type State } from "jev-use";
+/** API path appended to the normalized server root. */
+export declare const JEV_PATH = "/v1/jev";
+/** Live Jev model id on the hosted AutoRAG plan. */
+export declare const AUTORAG_DEFAULT_JEV_MODEL = "jev-1.13";
+/** Options for {@link AutoragJevBackend}. */
+export interface AutoragJevBackendOptions {
+    /** Environment holding the bearer key and `AUTORAG_BASE_URL`. Default `process.env`. */
+    readonly env?: Record<string, string | undefined>;
+    /** Explicit bearer key; when omitted, read from `AUTORAG_API_KEY`. */
+    readonly apiKey?: string;
+    /** Override the server root (test seam); defaults to `resolveBaseUrl(env)`. */
+    readonly baseUrl?: string;
+    /** Model used when a call names none. @default AUTORAG_DEFAULT_JEV_MODEL */
+    readonly defaultModel?: string;
+    /** Abort one attempt after this long. @default 10_000 */
+    readonly timeoutMs?: number;
+    /** Retries on 408/429/5xx and network failures. @default 2 */
+    readonly maxRetries?: number;
+    /** Injection seam for tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+type NativeWireQuestion = {
+    type: "noul";
+    instructions: string;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+} | {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+} | {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+};
+interface NativeBody {
+    model: string;
+    state: string;
+    questions: Record<string, NativeWireQuestion>;
+}
+/**
+ * Jev backend served by the hosted AutoRAG (Dazzi) plan.
+ *
+ * The constructor throws a named error when no account key is configured — a
+ * missing credential must be loud, never a silent fake judgment — and the retry
+ * policy mirrors `jev-use`'s own remote backends (408/429/5xx, `Retry-After`).
+ */
+export declare class AutoragJevBackend implements JevBackend {
+    readonly name = "autorag";
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultModel;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options?: AutoragJevBackendOptions);
+    judge(request: BackendRequest): Promise<BackendResponse>;
+    /** POST JSON with a per-attempt timeout and jev-use's retry policy. */
+    private postJson;
+}
+/** Build the whole request body: model, a string state, and the questions by id. */
+export declare function toNativeBody(state: State, questions: (Question & {
+    id: string;
+})[], model: string): NativeBody;
+/**
+ * Read the provider's answer map back into raw answers, in question order.
+ * Anything missing or mistyped is a `BackendError` — a silently dropped answer
+ * would read as a low-confidence judgment.
+ */
+export declare function parseNativeAnswers(backend: string, answers: unknown, questions: (Question & {
+    id: string;
+})[]): RawAnswer[];
+export {};

package/dist/cloud/models.d.ts

@@ -0,0 +1,32 @@
+import type { Credential, ModelsStoreEntry } from "@earendil-works/pi-ai";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { AutoragHttpError } from "./errors.js";
+/** Used when the server omits `context_window` / `max_output_tokens`. */
+export declare const DEFAULT_CONTEXT_WINDOW = 128000;
+export declare const DEFAULT_MAX_TOKENS = 16384;
+export interface FetchModelsOptions {
+    /** Server root, e.g. `https://api.dazziapp.com`. */
+    baseUrl: string;
+    /** Bearer token resolved from OAuth credentials or `AUTORAG_API_KEY`. */
+    apiKey: string;
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}
+/** Pick the bearer token out of a stored Pi credential. */
+export declare function resolveCredentialKey(credential: Credential | undefined): string | undefined;
+/**
+ * `GET <root>/v1/models` -> Pi chat model definitions.
+ *
+ * Pricing is USD per million tokens, matching Pi's cost model directly.
+ */
+export declare function fetchModels(options: FetchModelsOptions): Promise<ProviderModelConfig[]>;
+/** Map a failed `/v1/models` response; 401 means the token is invalid or revoked. */
+export declare function mapModelsError(status: number, body: unknown): AutoragHttpError;
+/** Map an OpenAI-shaped `{ object: "list", data: [...] }` catalog body. */
+export declare function mapServerModels(payload: unknown): ProviderModelConfig[];
+/** Map a single AutoRAG model record; returns `undefined` when it has no usable id. */
+export declare function mapServerModel(entry: Record<string, unknown>): ProviderModelConfig | undefined;
+/** Snapshot the live catalog for offline startup. */
+export declare function buildStoreEntry(models: readonly ProviderModelConfig[], providerId: string, baseUrl: string): ModelsStoreEntry;
+/** Restore chat model definitions from a persisted catalog snapshot. */
+export declare function modelsFromStore(stored: ModelsStoreEntry | undefined): ProviderModelConfig[];

package/dist/cloud/oauth-login.d.ts

@@ -0,0 +1,22 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+export interface LoginOptions {
+    /** Server root, e.g. `https://api.dazziapp.com`. */
+    baseUrl: string;
+    /** Loopback wait budget; defaults to {@link DEFAULT_LOGIN_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * AutoRAG tokens are long-lived revocable API keys: there is no refresh token
+ * and no expiry, so a refresh returns the stored credentials unchanged.
+ */
+export declare function refreshAutoragCredentials(credentials: OAuthCredentials): OAuthCredentials;
+/**
+ * OAuth2 authorization-code + PKCE (S256) login for native apps.
+ *
+ * The browser is sent to `<root>/desktop/authorize` with a loopback redirect
+ * URI. When the browser cannot reach the loopback server, the user can paste
+ * the final redirect URL (or the bare code) into the prompt instead; both paths
+ * are raced and the first result wins.
+ */
+export declare function loginAutorag(callbacks: OAuthLoginCallbacks, options: LoginOptions): Promise<OAuthCredentials>;

package/dist/cloud/pkce.d.ts

@@ -0,0 +1,20 @@
+/** RFC 7636 base64url encoding (unpadded, `-`/`_` alphabet). */
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+/**
+ * `BASE64URL(SHA256(ASCII(code_verifier)))` — the S256 code challenge.
+ *
+ * RFC 7636 Appendix B reference vector: verifier
+ * `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk` yields challenge
+ * `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`.
+ */
+export declare function createCodeChallenge(verifier: string): string;
+/** Random high-entropy PKCE code verifier (43 chars for the default 32 bytes). */
+export declare function createCodeVerifier(byteLength?: number): string;
+/** Random `state` value used to detect CSRF on the OAuth redirect. */
+export declare function createState(byteLength?: number): string;
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/** Generate a verifier and its matching S256 challenge in one step. */
+export declare function createPkcePair(byteLength?: number): PkcePair;

package/dist/cloud/provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The hosted AutoRAG (Dazzi) plan as a first-class model provider named
+ * `autorag`.
+ *
+ * The server exposes an OpenAI Responses API surface under `<root>/v1`. Login
+ * is OAuth2 authorization-code + PKCE over a loopback redirect (or the headless
+ * `AUTORAG_API_KEY`), and the model catalog is discovered live from
+ * `GET <root>/v1/models` — no model id is ever hardcoded here. Streaming is
+ * delegated to Pi's built-in `openai-responses` API implementation.
+ */
+import type { RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ModelRuntime, ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+/** Injection seam for tests and hosts that resolve configuration themselves. */
+export type AutoragEnv = Record<string, string | undefined>;
+interface Endpoints {
+    /** Server root, used for OAuth endpoints. */
+    baseUrl: string;
+    /** API base (`<root>/v1`), used as the provider `baseUrl` and for model listing. */
+    apiBaseUrl: string;
+}
+/**
+ * Resolve the provider's model list.
+ *
+ * Called by Pi with the credential it resolved for this provider. Without a
+ * credential (or without network access) the last persisted catalog, if any,
+ * is restored; a failed fetch keeps the previous list instead of blanking it.
+ */
+export declare function refreshAutoragModels(context: RefreshModelsContext, endpoints: Endpoints): Promise<ProviderModelConfig[]>;
+/** Build the `ProviderConfig` handed to `ModelRuntime.registerProvider("autorag", ...)`. */
+export declare function createAutoRAGProviderConfig(env?: AutoragEnv): ProviderConfig;
+/**
+ * The single registration point: register `autorag` on a Pi `ModelRuntime`.
+ *
+ * Runs even when the user is not signed in, so `/login` lists AutoRAG. The
+ * awaited cache-only refresh loads the persisted catalog snapshot (offline and
+ * with `allowModelNetwork:false`); it makes no network call, so a signed-out
+ * provider contributes no models and nothing here reaches the network.
+ */
+export declare function registerAutoRAGProvider(runtime: ModelRuntime, env?: AutoragEnv): Promise<void>;
+export {};

package/dist/cloud/token.d.ts

@@ -0,0 +1,22 @@
+import { AutoragHttpError } from "./errors.js";
+export interface TokenResponse {
+    accessToken: string;
+    email?: string;
+}
+export interface ExchangeCodeOptions {
+    /** Server root, e.g. `https://api.dazziapp.com`. */
+    baseUrl: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}
+/** Map a failed token-exchange response to an error carrying the HTTP status and server code. */
+export declare function mapTokenExchangeError(status: number, body: unknown): AutoragHttpError;
+/**
+ * Trade a PKCE authorization code for a long-lived API key.
+ *
+ * `POST <root>/api/desktop/token` with `{ code, code_verifier, redirect_uri }`.
+ */
+export declare function exchangeCodeForToken(options: ExchangeCodeOptions): Promise<TokenResponse>;

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 import type { AutoRAGJikjiPrepareResult, AutoRAGRefreshOptions, AutoRAGRefreshResult, AutoRAGRefreshStatus, AutoRAGWatchRefreshHandle, AutoRAGWatchRefreshOptions } from "./agent/agent.js";
-import type { AutoRAGResultsDetails } from "./agent/emit-results-tool.js";
+import type { AutoRAGResultsDetails } from "./agent/results.js";
 import { type SearchDocumentsResponse } from "./agent/search-documents.js";
 import { type CliConfig, type ResolveConfigInput } from "./cli/config.js";
 import type { EverythingSearchRequest, EverythingSearchResult } from "./everything/index.js";
@@ -9,7 +9,7 @@ import type { MinSyncSyncResult } from "./minsync/types.js";
 import type { ParsedMirrorSyncResult } from "./mirror/sync.js";
 import type { RetrievalEngine } from "./retrieval/engine.js";
 import type { DatasourceCatalogEntry, RetrievalSelection } from "./retrieval/selection.js";
-import type { CuratedResult, RetrievalDiagnostic, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } from "./retrieval/types.js";
+import type { RetrievalDiagnostic, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } from "./retrieval/types.js";
 /** Input accepted by {@link createAutoRAGLite}. Flags keep CLI precedence intact. */
 export interface AutoRAGLiteOptions {
     readonly flags?: ResolveConfigInput["flags"];
@@ -23,7 +23,6 @@ export declare class AutoRAGLite {
     private readonly agent;
     private readonly retrievalEngine;
     private readonly memory;
-    private readonly sessions;
     constructor(config: CliConfig);
     /** Refresh parsed mirrors and configured indexes without constructing a model. */
     refresh(force?: boolean, options?: AutoRAGRefreshOptions): Promise<AutoRAGRefreshResult>;
@@ -82,8 +81,6 @@ export declare class AutoRAGLite {
     recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails): SearchDocumentsResponse;
     /** Generate a session id and persist a typed structured report. */
     recordReport(query: string, details: AutoRAGResultsDetails): SearchDocumentsResponse;
-    /** Return the opaque result registry associated with a persisted report. */
-    getResultRegistry(sessionId: string): ReadonlyMap<number, CuratedResult>;
     /** Return a detached snapshot of persisted evidence state. */
     getMemorySchema(): MemorySchema;
 }