@gajae-code/coding-agent 0.7.1 → 0.7.3

package/dist/types/notifications/operator-runtime.d.ts

@@ -0,0 +1,52 @@
+export interface NotificationOperatorTimerDeps {
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+}
+export interface NotificationOperatorRuntimeState {
+    running: boolean;
+    stopRequested: boolean;
+    activeAbort: boolean;
+}
+export interface OperatorBackoffOptions {
+    initialMs: number;
+    maxMs: number;
+    factor?: number;
+}
+export declare class OperatorBackoffPolicy {
+    #private;
+    constructor(opts: OperatorBackoffOptions);
+    next(): number;
+    reset(): void;
+    get currentMs(): number;
+}
+export interface OperatorRoute<TContext> {
+    name: string;
+    matches(event: Record<string, unknown>): boolean;
+    handle(context: TContext, event: Record<string, unknown>): Promise<void> | void;
+}
+export declare class OperatorEventRouter<TContext> {
+    readonly routes: OperatorRoute<TContext>[];
+    add(input: OperatorRoute<TContext>): this;
+    dispatch(context: TContext, event: Record<string, unknown>): Promise<boolean>;
+}
+export declare class NotificationOperatorRuntime {
+    #private;
+    constructor(deps?: NotificationOperatorTimerDeps);
+    get state(): NotificationOperatorRuntimeState;
+    start(): void;
+    stop(): void;
+    requestStop(): void;
+    get running(): boolean;
+    get stopRequested(): boolean;
+    createAbortController(): AbortController;
+    clearAbortController(controller: AbortController): void;
+    startInterval(name: string, intervalMs: number, tick: () => void): void;
+    stopInterval(name: string): void;
+    stopAllIntervals(): void;
+    runExclusive(name: string, fn: () => Promise<void>): Promise<void>;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    now(): number;
+}

package/dist/types/notifications/telegram-daemon.d.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import type { Settings } from "../config/settings";
 import type { DaemonRuntimeInfo } from "../daemon/control-types";
+import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute, type PendingAsk } from "./telegram-reference";
 export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled";
 export interface DaemonState {
@@ -146,6 +147,40 @@ export interface BotApi {
         signal?: AbortSignal;
     }): Promise<unknown>;
 }
+export interface TelegramTransportOptions {
+    botToken: string;
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+    setTimeoutImpl?: typeof setTimeout;
+}
+/** Telegram Bot API transport: HTTP JSON/multipart details stay out of daemon orchestration. */
+export declare class TelegramBotTransport implements BotApi {
+    #private;
+    constructor(opts: TelegramTransportOptions);
+    call(method: string, body: unknown, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface TelegramUpdatePollerOptions {
+    botApi: BotApi;
+    runtime: NotificationOperatorRuntime;
+    backoff: OperatorBackoffPolicy;
+    processUpdate: (update: unknown) => Promise<void>;
+}
+/** Owns getUpdates offset, conflict backoff, and per-update error isolation. */
+export declare class TelegramUpdatePoller {
+    #private;
+    constructor(opts: TelegramUpdatePollerOptions);
+    pollOnce(signal?: AbortSignal): Promise<number>;
+}
+/** Mutable dispatch state shared by session frames and inbound Telegram updates. */
+export declare class TelegramEventDispatchState {
+    readonly busy: Set<string>;
+    readonly inboundReactions: Map<number, {
+        messageId: number;
+    }>;
+    readonly seenUpdateIds: Set<number>;
+}
 /**
  * Cooperative control seam for the daemon run loop. Implemented by the
  * daemon-internal CLI / controller against the owner-scoped control-request
@@ -199,27 +234,31 @@ export declare class TelegramNotificationDaemon {
     readonly aliasTable: AliasTable;
     readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
     readonly sessions: Map<string, SessionSocket>;
+    private readonly runtime;
+    private readonly sessionRouter;
+    private readonly pollConflictBackoff;
+    private readonly loopBackoff;
     private running;
-    private offset;
     private readonly fsImpl;
     private readonly botApi;
     private readonly topics;
     private readonly pool;
-    private readonly seenUpdateIds;
-    private flushTimer;
-    private scanTimer;
-    private scanning;
-    private typingTimer;
+    private readonly poller;
+    private readonly dispatchState;
+    /** Identity-bearing sessions by repo/branch surface, used to avoid transient duplicate topics. */
+    private readonly topicOwnerByIdentity;
+    /** Non-identity frames held until identity creates the correct thread. */
+    private readonly pendingThreadedFrames;
+    /** True once the daemon has nudged the user to enable Threaded Mode. */
+    private threadedFallbackNoticeSent;
+    /** Sessions whose identity header was already sent flat (Threaded Mode off). */
+    private readonly flatIdentitySent;
+    /** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
+    private pairedChatPrivate;
     /** Sessions whose agent loop is currently busy (drives the typing indicator). */
-    private readonly busy;
+    private get busy();
     /** Inbound update id → originating Telegram message, for delivery reactions. */
-    private readonly inboundReactions;
-    /** AbortController for the in-flight long poll; aborted by requestStop() to wake the loop. */
-    private activePoll;
-    /** Set when a cooperative stop has been requested (signal or control request). */
-    private stopRequested;
-    /** Current bounded backoff after a Telegram getUpdates 409 conflict (0 when healthy). */
-    private pollConflictBackoffMs;
+    private get inboundReactions();
     /**
      * Cooperatively stop the daemon: set the stop flag and abort the in-flight
      * long poll so the run loop wakes immediately instead of waiting out the
@@ -227,6 +266,7 @@ export declare class TelegramNotificationDaemon {
      */
     requestStop(_reason?: "reload" | "stop" | "signal"): void;
     constructor(opts: TelegramDaemonOptions);
+    private createSessionRouter;
     loadAliases(): Promise<void>;
     persistAliases(): Promise<void>;
     scanRoots(): Promise<void>;
@@ -248,10 +288,29 @@ export declare class TelegramNotificationDaemon {
     private dropSession;
     private static readonly THREADED_FRAMES;
     private topicNameFor;
+    private topicIdentityKey;
+    private topicIdentityBase;
+    private topicOwnerForIdentity;
+    private submitThreadedFrame;
+    private rememberPendingThreadedFrame;
+    private flushPendingThreadedFrames;
     private ensureTopic;
     private persistTopics;
     loadTopics(): Promise<void>;
+    private downloadTelegramFile;
+    /**
+     * Per-session private temp directories (mode 0700) holding inbound non-image
+     * attachments. Keyed by session id and reused across transient reconnects;
+     * removed when the daemon stops (see {@link cleanupAllAttachmentDirs}).
+     */
+    private readonly attachmentDirs;
+    private ensureAttachmentDir;
+    private cleanupAllAttachmentDirs;
+    private resolveInboundAttachment;
     private flushPool;
+    private deliverFlatFallback;
+    private pairedChatIsPrivate;
+    private notifyThreadedFallback;
     private startFlushTimer;
     private stopFlushTimer;
     private runScan;
@@ -266,8 +325,6 @@ export declare class TelegramNotificationDaemon {
     private sendStaleGuidance;
     handleTelegramUpdate(update: unknown): Promise<void>;
     pollOnce(signal?: AbortSignal): Promise<number>;
-    /** Abortable sleep honoring the injected timer; resolves early on abort. */
-    private sleep;
     /** Sync the bot's Telegram command menu to what the daemon actually handles. */
     registerBotCommands(): Promise<void>;
     run(): Promise<void>;

package/dist/types/notifications/threaded-inbound.d.ts

@@ -20,12 +20,30 @@ export interface InboundUpdate {
     message?: {
         message_id?: unknown;
         text?: unknown;
+        caption?: unknown;
+        photo?: unknown;
+        document?: unknown;
+        video?: unknown;
+        audio?: unknown;
+        voice?: unknown;
+        animation?: unknown;
         chat?: {
             id?: unknown;
         };
         message_thread_id?: unknown;
     };
 }
+/** A downloadable media attachment referenced by an inbound message. */
+export interface InboundAttachment {
+    /** Telegram file_id to resolve via getFile. */
+    fileId: string;
+    /** Source media kind; "photo" is always an image. */
+    kind: "photo" | "document" | "video" | "audio" | "voice" | "animation";
+    /** MIME type when Telegram provides one. */
+    mime?: string;
+    /** Original file name when provided. */
+    fileName?: string;
+}
 /** Context for {@link decideThreadedInbound}. All lookups are injected. */
 export interface ThreadedInboundCtx {
     /** The single paired chat id (string-compared). */
@@ -43,6 +61,7 @@ export type ThreadedInboundDecision = {
     updateId: number;
     threadId: string;
     messageId?: number;
+    attachment?: InboundAttachment;
 } | {
     kind: "duplicate";
     updateId: number;

package/dist/types/notifications/threaded-render.d.ts

@@ -11,15 +11,19 @@
 import type { RateLimitLane } from "./rate-limit-pool";
 /** A Telegram send derived from a threaded frame (topic id is applied by the daemon). */
 export interface ThreadedSend {
-    method: "sendMessage" | "sendPhoto";
+    method: "sendMessage" | "sendPhoto" | "sendDocument";
     /** Rate-limit lane for prioritisation/fairness. */
     lane: RateLimitLane;
     /** Message text (sendMessage) or photo caption (sendPhoto). */
     text?: string;
     /** Base64 image bytes for sendPhoto. */
     photoBase64?: string;
+    /** Base64 file bytes for sendDocument. */
+    documentBase64?: string;
     /** Image MIME type for sendPhoto. */
     mime?: string;
+    /** Suggested document filename. */
+    fileName?: string;
     /** Coalesce key for live edits (same key collapses to the latest). */
     coalesceKey?: string;
     /** True for the one-time identity header (the daemon pins it once). */
@@ -45,6 +49,7 @@ interface ThreadedFrame {
     data?: unknown;
     mime?: unknown;
     caption?: unknown;
+    name?: unknown;
     verbosity?: unknown;
     redact?: unknown;
 }

package/dist/types/notifications/topic-registry.d.ts

@@ -45,6 +45,8 @@ export declare class TopicRegistry {
     load(state: TopicRegistryState): void;
     /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
     sessionForTopic(topicId: string): string | undefined;
+    /** All session ids with a persisted topic record. */
+    sessionIds(): string[];
     /** The existing topic record for a session, if any. */
     get(sessionId: string): TopicRecord | undefined;
     /**

package/dist/types/session/agent-session.d.ts

@@ -81,6 +81,7 @@ import type { BranchSummaryEntry, NewSessionOptions, SessionContext, SessionMana
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
 /** Session-specific events that extend the core AgentEvent */
+export type AutoCompactionContinuationSkipReason = "auto_continue_disabled_non_resumable_tail";
 export type AgentSessionEvent = AgentEvent | {
     type: "auto_compaction_start";
     reason: "threshold" | "overflow" | "idle";
@@ -94,6 +95,7 @@ export type AgentSessionEvent = AgentEvent | {
     errorMessage?: string;
     /** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
     skipped?: boolean;
+    continuationSkipReason?: AutoCompactionContinuationSkipReason;
 } | {
     type: "auto_retry_start";
     attempt: number;

package/dist/types/tools/composer-bash-policy.d.ts

@@ -0,0 +1,14 @@
+export declare const COMPOSER_BASH_POLICY_ERROR = "Composer bash policy blocked repository file I/O. Use find, search, read, and edit tools for file discovery, file inspection, and file mutation.";
+type ComposerBashPolicyResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    message: string;
+};
+export declare function isComposerBashPolicyModel(modelId: string | undefined): boolean;
+export declare function checkComposerBashPolicy(input: {
+    modelId?: string;
+    commands: readonly string[];
+}): ComposerBashPolicyResult;
+export {};

package/dist/types/tools/fetch.d.ts

@@ -1,8 +1,10 @@
 import type { AgentToolResult } from "@gajae-code/agent-core";
 import { type Component } from "@gajae-code/tui";
+import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
+import type { RenderResult } from "../web/scrapers/types";
 import { type OutputMeta } from "./output-meta";
 export declare function isReadableUrlPath(value: string): boolean;
 export interface ParsedReadUrlTarget {
@@ -16,6 +18,27 @@ interface FetchImagePayload {
     data: string;
     mimeType: string;
 }
+type FetchRenderResult = RenderResult & {
+    image?: FetchImagePayload;
+};
+/**
+ * Opt-in insane-search fallback for blocked / degraded public URL reads.
+ *
+ * Returns a finalized `method: "insane"` result on success, or null (so the
+ * caller continues with its normal degraded behavior). Fail-closed: no note,
+ * guard DNS, dependency probe, or subprocess when raw mode or the opt-in
+ * setting is off. The public-URL guard runs BEFORE any probe/spawn.
+ */
+export declare function tryInsaneFallback(args: {
+    url: string;
+    finalUrl: string;
+    timeout: number;
+    raw: boolean;
+    settings: Settings;
+    signal: AbortSignal | undefined;
+    fetchedAt: string;
+    notes: string[];
+}): Promise<FetchRenderResult | null>;
 export interface ReadUrlToolDetails {
     kind: "url";
     url: string;

package/dist/types/tools/index.d.ts

@@ -55,6 +55,7 @@ export * from "./search-tool-bm25";
 export * from "./skill";
 export * from "./ssh";
 export * from "./subagent";
+export * from "./telegram-send";
 export * from "./todo-write";
 export * from "./vim";
 export * from "./write";

package/dist/types/tools/telegram-send.d.ts

@@ -0,0 +1,32 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import { z } from "zod/v4";
+import type { ToolSession } from "./index";
+declare const telegramSendSchema: z.ZodObject<{
+    path: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TelegramSendParams = z.infer<typeof telegramSendSchema>;
+interface TelegramSendDetails {
+    path: string;
+    caption?: string;
+    ok: boolean;
+    error?: string;
+}
+export declare class TelegramSendTool implements AgentTool<typeof telegramSendSchema, TelegramSendDetails> {
+    private readonly session;
+    readonly name = "telegram_send";
+    readonly label = "TelegramSend";
+    readonly summary = "Send a workspace file to Telegram";
+    readonly loadMode = "discoverable";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        path: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): TelegramSendTool | null;
+    private resolveContainedFile;
+    execute(_toolCallId: string, params: TelegramSendParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<TelegramSendDetails>, _context?: AgentToolContext): Promise<AgentToolResult<TelegramSendDetails>>;
+}
+export {};

package/dist/types/web/insane/bridge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Bridge from TypeScript to the vendored insane-search Python engine.
+ *
+ * Invokes `python3 -m engine "<url>" --json` per fallback attempt (cwd + PYTHONPATH
+ * pointed at the vendored engine), validates the JSON envelope, and maps it onto a
+ * discriminated result. Hardened: clamped timeout, AbortSignal propagation that
+ * kills+reaps the child, bounded stdout/stderr capture, and a per-process
+ * concurrency cap so blocked reads cannot fork-storm.
+ *
+ * Fail-closed: missing dependencies / bad output / auth-required never throw past
+ * the caller and never auto-install anything; they return ok:false with a stable,
+ * bounded note so `read` can continue with its normal degraded result.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+/** packages/coding-agent/vendor/insane-search */
+export declare const INSANE_VENDOR_DIR: string;
+/** Stable note prefixes — tests assert on these without depending on full stderr. */
+export declare const INSANE_NOTES: {
+    readonly guardBlocked: (reason: string) => string;
+    readonly vendorMissing: `insane fallback unavailable: vendor engine missing at packages/coding-agent/vendor/insane-search`;
+    readonly noPython: `insane fallback unavailable: python3 not found; install python3 and curl_cffi, then retry with web.insaneFallback=true`;
+    readonly noCurlCffi: `insane fallback unavailable: python3 cannot import curl_cffi; install curl_cffi for Phase 0-2`;
+    readonly noBrowser: `insane fallback unavailable: node/playwright/stealth dependencies missing for Phase 3; install dependencies under packages/coding-agent/vendor/insane-search/engine/templates`;
+    readonly timeout: (seconds: number) => string;
+    readonly invalidJson: `insane fallback failed: engine returned invalid JSON`;
+    readonly authRequired: `insane fallback stopped: authentication required`;
+    readonly verdict: (verdict: string) => string;
+    readonly untried: (routes: string) => string;
+    readonly mustBrowserMcp: `insane fallback requires browser MCP/manual phase: must_invoke_playwright_mcp=true`;
+    readonly concurrency: `insane fallback skipped: max concurrent engine attempts reached`;
+    readonly emptyContent: `insane fallback failed: engine reported ok but returned no content`;
+};
+/** Raw JSON envelope produced by `python3 -m engine --json`. */
+export interface InsaneFetchResultRaw {
+    ok?: boolean;
+    verdict?: string;
+    content?: string;
+    profile_used?: string;
+    trace?: unknown;
+    untried_routes?: string[];
+    must_invoke_playwright_mcp?: boolean;
+}
+export interface InsaneSuccess {
+    ok: true;
+    content: string;
+    profileUsed?: string;
+    notes: string[];
+}
+export interface InsaneFailure {
+    ok: false;
+    reason: string;
+    verdict?: string;
+    notes: string[];
+}
+export type InsaneBridgeResult = InsaneSuccess | InsaneFailure;
+export interface EngineInvocation {
+    url: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+export interface EngineRawOutput {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    aborted: boolean;
+}
+/** Seam: run the engine subprocess. Default spawns python3. */
+export type EngineRunner = (inv: EngineInvocation) => Promise<EngineRawOutput>;
+export interface InsaneDependencyStatus {
+    vendorPresent: boolean;
+    python: boolean;
+    curlCffi: boolean;
+    browser: boolean;
+}
+/** Seam: probe dependencies. Default probes the real environment (cached). */
+export type DependencyProber = () => Promise<InsaneDependencyStatus>;
+type SpawnImpl = typeof nodeSpawn;
+/** Real engine runner: `python3 -m engine "<url>" --json`. */
+export declare function runEngineSubprocess(inv: EngineInvocation, options?: {
+    spawnImpl?: SpawnImpl;
+}): Promise<EngineRawOutput>;
+/** Reset the probe cache between tests so probe state never leaks. */
+export declare function resetInsaneProbeCacheForTest(): void;
+/** Probe (and cache) the insane-search runtime dependencies. */
+export declare function probeInsaneDependencies(): Promise<InsaneDependencyStatus>;
+export declare function resetInsaneConcurrencyForTest(): void;
+export interface TryInsaneFetchOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    concurrencyLimit?: number;
+    /** Seam: dependency prober (default real, cached). */
+    prober?: DependencyProber;
+    /** Seam: engine runner (default real subprocess). */
+    runner?: EngineRunner;
+}
+/**
+ * Attempt to read `url` through the insane-search engine. The caller is
+ * responsible for the opt-in gate, raw-mode skip, and the public-URL guard
+ * (which MUST run before this is called). Never throws; always returns a result.
+ */
+export declare function tryInsaneFetch(url: string, options?: TryInsaneFetchOptions): Promise<InsaneBridgeResult>;
+export {};

package/dist/types/web/insane/url-guard.d.ts

@@ -0,0 +1,25 @@
+export interface PublicUrlAccepted {
+    ok: true;
+    url: URL;
+    addresses: string[];
+}
+export interface PublicUrlRejected {
+    ok: false;
+    reason: string;
+}
+export type PublicUrlResult = PublicUrlAccepted | PublicUrlRejected;
+/** Resolver seam so tests can inject DNS results without real lookups. */
+export type AddressResolver = (hostname: string) => Promise<string[]>;
+/** True for any address that is not a routable public unicast address. */
+export declare function isPrivateOrSpecialAddress(address: string): boolean;
+/**
+ * Validate that `rawUrl` is a public http/https target. Resolves DNS names and
+ * rejects any that map to a private/special address. Never throws; returns a
+ * discriminated result.
+ */
+export declare function validatePublicHttpUrl(rawUrl: string, options?: {
+    resolver?: AddressResolver;
+}): Promise<PublicUrlResult>;
+export declare function validatePublicHttpUrlForInsane(rawUrl: string, options?: {
+    resolver?: AddressResolver;
+}): Promise<PublicUrlResult>;

package/dist/types/web/scrapers/types.d.ts

@@ -1,4 +1,5 @@
 import type { AgentStorage } from "../../session/agent-storage";
+import type { AddressResolver } from "../insane/url-guard";
 export { formatNumber } from "@gajae-code/utils";
 export interface RenderResult {
     url: string;
@@ -27,6 +28,9 @@ export interface LoadPageOptions {
     body?: string;
     maxBytes?: number;
     signal?: AbortSignal;
+    publicUrlGuard?: boolean;
+    resolver?: AddressResolver;
+    maxRedirects?: number;
 }
 export interface LoadPageResult {
     content: string;
@@ -34,6 +38,7 @@ export interface LoadPageResult {
     finalUrl: string;
     ok: boolean;
     status?: number;
+    error?: string;
 }
 /**
  * Fetch a page with timeout and size limit

package/dist/types/web/scrapers/utils.d.ts

@@ -1,5 +1,6 @@
 import { isRecord } from "@gajae-code/utils";
 export { isRecord };
+import type { AddressResolver } from "../insane/url-guard";
 export declare function asRecord(value: unknown): Record<string, unknown> | null;
 export declare function asString(value: unknown): string | null;
 export declare function asNumber(value: unknown): number | null;
@@ -12,10 +13,15 @@ export type BinaryFetchResult = BinaryFetchSuccess | {
     ok: false;
     error?: string;
 };
+export interface FetchBinaryOptions {
+    publicUrlGuard?: boolean;
+    resolver?: AddressResolver;
+    maxRedirects?: number;
+}
 /**
  * Fetch binary content from a URL
  */
-export declare function fetchBinary(url: string, timeout?: number, signal?: AbortSignal): Promise<BinaryFetchResult>;
+export declare function fetchBinary(url: string, timeout?: number, signal?: AbortSignal, options?: FetchBinaryOptions): Promise<BinaryFetchResult>;
 /**
  * Convert binary content to markdown using markit.
  */

package/dist/types/web/search/provider.d.ts

@@ -20,5 +20,22 @@ export declare function looksHostedModelId(modelId: string | undefined): boolean
 export declare function isLocalBaseUrl(baseUrl: string | undefined): boolean;
 export declare function inferNativeProviderFromModel(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined;
 export declare function canUseGenericCredentials(authStorage: AuthStorage, ctx: ActiveSearchModelContext | undefined, sessionId?: string, signal?: AbortSignal): Promise<boolean>;
-export declare function shouldTryGenericOpenAICompat(authStorage: AuthStorage, ctx: ActiveSearchModelContext | undefined, sessionId?: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Native web-search provider to attempt by reusing the ACTIVE model's own
+ * credentials + baseUrl, dispatched by the model's wire protocol.
+ *
+ * This is the "native search over a proxy" path: when a model is served through
+ * a proxy/custom endpoint, its canonical search credentials (e.g. a dedicated
+ * `anthropic` key, or ChatGPT OAuth for `codex`) are usually absent, but the
+ * credential that authenticates the model itself — stored under the active
+ * provider id and aimed at `ctx.baseUrl` — can drive native web search just as
+ * well. Each provider's `search()` falls back to those active credentials when
+ * its canonical ones are missing.
+ *
+ * Returned ids are matched purely from the wire `api` (+ model-id family where a
+ * native tool only makes sense for that family); the providers themselves fail
+ * closed (and the chain falls through to DuckDuckGo) if the endpoint does not
+ * actually support web search.
+ */
+export declare function activeContextNativeId(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined;
 export declare function resolveProviderChain(options: ResolveProviderChainOptions): Promise<SearchProvider[]>;

package/dist/types/web/search/providers/insane.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Insane Search Provider
+ *
+ * Native TypeScript, fail-closed adaptation of the MIT-licensed upstream
+ * fivetaku/insane-search public-route strategy. This ports only safe Phase 0
+ * concepts: deterministic no-auth public endpoints plus route-attempt tracing.
+ *
+ * Deliberately excluded from upstream: TLS impersonation, browser/cookie warming,
+ * CAPTCHA/paywall/login bypasses, credential storage, Playwright automation, and
+ * auto dependency installation. Unsupported or terminal auth/paywall/block states
+ * throw instead of pretending a shallow fetch succeeded.
+ */
+import type { AuthStorage } from "@gajae-code/ai";
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface InsaneRouteAttempt {
+    platform: InsanePlatform;
+    route: string;
+    ok: boolean;
+    status: number;
+    bytes: number;
+    note?: string;
+}
+type InsanePlatform = "reddit" | "x" | "youtube" | "hackernews";
+interface RouteSuccess {
+    platform: InsanePlatform;
+    route: string;
+    finalUrl: string;
+    sources: SearchSource[];
+    attempts: InsaneRouteAttempt[];
+}
+interface RouteFailure {
+    platform: InsanePlatform;
+    attempts: InsaneRouteAttempt[];
+}
+type RouteResult = RouteSuccess | RouteFailure | null;
+export declare function routeInsanePublicUrl(rawUrl: string, signal?: AbortSignal): Promise<RouteResult>;
+/** Execute safe Insane Search public-route discovery. */
+export declare function searchInsane(params: {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Keyless provider that ports safe upstream public-route fallbacks only. */
+export declare class InsaneProvider extends SearchProvider {
+    readonly id = "insane";
+    readonly label = "Insane";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/providers/text-citations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Inline citation extraction shared by native web-search providers.
+ *
+ * Web-search-capable models sometimes return a genuinely grounded answer whose
+ * sources are written inline (markdown links or bare URLs) instead of as
+ * structured citation annotations. When a provider has independent proof that a
+ * web search actually ran, these helpers recover sources from the answer text so
+ * the result is not discarded.
+ */
+import type { SearchSource } from "../types";
+/** Append a source, de-duplicating by URL. */
+export declare function addSource(sources: SearchSource[], source: SearchSource): void;
+/**
+ * Strips prose punctuation and unmatched closing delimiters from extracted URLs.
+ * Models often return links embedded in markdown or sentence text.
+ */
+export declare function normalizeExtractedUrl(candidate: string): string | null;
+/**
+ * Extracts citation sources from markdown links and bare URLs in answer text.
+ * Used only as a fallback when a provider confirms a search ran but omits
+ * structured citation annotations.
+ */
+export declare function extractTextSources(text: string): SearchSource[];