@gajae-code/coding-agent 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-06-24
+### Added
+
+- Added a keyless `insane` web search provider that safely ports upstream insane-search public-route fallbacks without TLS impersonation, browser/cookie bypasses, credential storage, or auto-installed dependencies (#1011).
+- `web_search` `auto` mode now drives native provider search over proxies/custom endpoints by reusing the active model's own credential + baseUrl when canonical native creds are absent: `activeContextNativeId()` matches the model's wire api (+ model-id family) to `anthropic` (anthropic-messages), `openai-compatible` (openai-responses/completions), or `gemini` (google-generative-ai Generative Language), each falling back to DuckDuckGo if the endpoint does not support web search.
+- Added built-in C# LSP detection for `csharp-ls`, with `omnisharp` preserved as a fallback when `csharp-ls` is unavailable (#1054).
+- Added Discord and Slack notification adapters alongside the existing Telegram surface, so action-needed signals and replies can be routed to those clients (#1043).
+- Telegram daemon now supports inbound and outbound photo/file attachments, forwarding agent images and accepting user-sent media (#1053).
+- `gjc` verifies Telegram Threaded Mode during notification setup and falls back to a flat private chat when topics are unavailable (#1029).
+
+### Fixed
+
+- Hardened context-overflow recovery so automatic maintenance clears the TUI loader, surfaces overflow completion/skip status, retries resumable tails safely, and falls back to the synthetic auto-continue prompt for non-resumable tails when enabled.
+- `web_search` native providers no longer discard genuinely grounded answers that omit structured `url_citation` annotations: when a search demonstrably ran — Responses `web_search_call` / `tool_usage.web_search`, a Chat Completions search request, or Anthropic `web_search_tool_result` / `server_tool_use` / `server_tool_use.web_search_requests` — sources are recovered from inline markdown links and bare URLs. Inline recovery is gated on that real-search signal so a stray prose URL in a non-search answer is never promoted to a citation, and Anthropic now fails closed to DuckDuckGo when Claude answers from stable knowledge without searching. Inline-citation helpers are shared via `providers/text-citations.ts`.
+- Preserve GJC-managed tmux sessions on attach/disconnect instead of tearing them down, and stop implicitly attaching on launch (#1063).
+- Corrected the auto-compaction output reserve so post-compaction responses keep adequate headroom (#1021).
+- Improved active-input shortcut hints and the busy-input queueing hint for clearer in-session guidance (#1022, #1024).
+
 ## [0.7.1] - 2026-06-23
 ### Fixed
 
@@ -136,6 +154,7 @@
 - Added an opt-in `gjc rlm` research mode (v1, interactive): a Jupyter-notebook-style research session over the existing agent loop, backed by the shared persistent Python kernel. It loads a distinct research system prompt, restricts the toolset to a hard-gated allowlist (`python` + `read` + `web_search`, asserted after tool-registry assembly — no `bash`/edit/arbitrary mutation), optionally loads a project-root `DATA.md` (overridable via `--data <path>`), aggregates every executed cell live into `.gjc/rlm/<session>/notebook.ipynb` (single-queue atomic temp-rename writes with post-write validation), and synthesizes `.gjc/rlm/<session>/report.md` on session exit. Autonomous goal-arg runs, `--resume`, managed per-workspace venv provisioning, and the optional `>=N` completion gate are deferred follow-ups.
 - Added an experimental opt-in `computer` desktop-control tool surface for local macOS screenshot/input coordination, backed by native `ComputerController`/`computerScreenshot` bindings and gated through settings/tool registration so it can continue stabilizing on `dev` outside the 0.5.4 patch release.
 - Dropped deprecated GitHub Actions Intel macOS (`macos-13` / `darwin-x64`) release-binary coverage after the runner pool repeatedly blocked v0.6.0 publish; Intel macOS users should install through npm/Bun or build from source.
+- Re-enabled GitHub Actions Intel macOS (`darwin-x64`) release-binary coverage using the `macos-15-intel` runner, so standalone `gjc-darwin-x64` binaries ship again alongside Apple Silicon.
 
 ## [0.5.4] - 2026-06-17
 

package/dist/types/cli/notify-cli.d.ts

@@ -17,6 +17,8 @@ export interface NotifyCommandDeps {
     pollIntervalMs?: number;
     setupChatId?: string;
     setupRedact?: boolean;
+    setupInteractive?: boolean;
+    threadedModePrompt?: (message: string) => Promise<string>;
 }
 export declare function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined;
 export declare function runNotifyCommand(cmd: NotifyCommandArgs, deps?: NotifyCommandDeps): Promise<void>;

package/dist/types/config/settings-schema.d.ts

@@ -130,6 +130,22 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "string";
         readonly default: undefined;
     };
+    readonly "notifications.discord.botToken": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.discord.channelId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.slack.botToken": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.slack.channelId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
     readonly "notifications.redact": {
         readonly type: "boolean";
         readonly default: false;
@@ -2469,6 +2485,15 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Allow the read tool to fetch and process URLs";
         };
     };
+    readonly "web.insaneFallback": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly ui: {
+            readonly tab: "tools";
+            readonly label: "Insane Search Fallback";
+            readonly description: "Opt in to the vendored insane-search escalation for blocked public URL reads (403/WAF/JS-gated). Off by default. Requires preinstalled python3 + curl_cffi (and node + playwright/stealth for the browser phase); changes network posture by enabling TLS/browser impersonation for public pages.";
+        };
+    };
     readonly "github.enabled": {
         readonly type: "boolean";
         readonly default: false;
@@ -2518,7 +2543,7 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "array";
         readonly default: string[];
         readonly items: {
-            readonly enum: readonly ["duckduckgo", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
+            readonly enum: readonly ["duckduckgo", "insane", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
         };
         readonly ui: {
             readonly tab: "tools";
@@ -3121,7 +3146,7 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "providers.webSearch": {
         readonly type: "enum";
-        readonly values: readonly ["auto", "duckduckgo", "exa", "brave", "jina", "kimi", "zai", "perplexity", "anthropic", "gemini", "codex", "xai", "tavily", "kagi", "synthetic", "parallel", "searxng"];
+        readonly values: readonly ["auto", "duckduckgo", "insane", "exa", "brave", "jina", "kimi", "zai", "perplexity", "anthropic", "gemini", "codex", "xai", "tavily", "kagi", "synthetic", "parallel", "searxng"];
         readonly default: "auto";
         readonly ui: {
             readonly tab: "providers";
@@ -3135,6 +3160,10 @@ export declare const SETTINGS_SCHEMA: {
                 readonly value: "duckduckgo";
                 readonly label: "DuckDuckGo";
                 readonly description: "Keyless default \u2014 no API key or OAuth required";
+            }, {
+                readonly value: "insane";
+                readonly label: "Insane";
+                readonly description: "Keyless safe public-route fallback inspired by upstream insane-search";
             }, {
                 readonly value: "exa";
                 readonly label: "Exa";
@@ -3574,6 +3603,14 @@ export interface NotificationsSettings {
         botToken: string | undefined;
         chatId: string | undefined;
     };
+    discord: {
+        botToken: string | undefined;
+        channelId: string | undefined;
+    };
+    slack: {
+        botToken: string | undefined;
+        channelId: string | undefined;
+    };
     redact: boolean;
     daemon: {
         idleTimeoutMs: number;

package/dist/types/extensibility/shared-events.d.ts

@@ -172,6 +172,7 @@ export interface AutoCompactionEndEvent {
     errorMessage?: string;
     /** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
     skipped?: boolean;
+    continuationSkipReason?: "auto_continue_disabled_non_resumable_tail";
 }
 /** Fired when auto-retry starts */
 export interface AutoRetryStartEvent {

package/dist/types/gjc-runtime/ralplan-runtime.d.ts

@@ -12,7 +12,7 @@
  *
  * 2. **Artifact write**: `gjc ralplan --write --stage <type> --stage_n <N> --artifact
  *    <path-or-string> [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
- *    / Critic / revision / ADR / final markdown under `.gjc/plans/ralplan/<run-id>/`, maintains
+ *    / Critic / revision / post-interview / ADR / final markdown under `.gjc/plans/ralplan/<run-id>/`, maintains
  *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
  *    the HUD chip to reflect the latest persisted stage.
  */

package/dist/types/lsp/types.d.ts

@@ -224,6 +224,8 @@ export interface ServerConfig {
     /** Per-server warmup timeout in milliseconds. Overrides the global WARMUP_TIMEOUT_MS for this server during startup. */
     warmupTimeoutMs?: number;
     capabilities?: ServerCapabilities;
+    /** Names of lower-precedence servers to drop when this server is available. */
+    supersedes?: string[];
     /** If true, this is a linter/formatter server (e.g., Biome) - used only for diagnostics/actions, not type intelligence */
     isLinter?: boolean;
     /** Resolved absolute path to the command binary (set during config loading) */

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

@@ -0,0 +1,17 @@
+/**
+ * Process-wide registry mapping a session id to a sink that delivers a local
+ * file to the session's connected Telegram chat as a document. Registered by
+ * the notifications extension; consumed by the telegram_send tool.
+ */
+/** Delivers a local file to the session's Telegram chat. */
+export type TelegramFileSink = (file: {
+    path: string;
+    caption?: string;
+}) => Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Register `sink` for `sessionId`. Returns a disposer that clears it. */
+export declare function registerTelegramFileSink(sessionId: string, sink: TelegramFileSink): () => void;
+/** The Telegram file sink for `sessionId`, if one is registered. */
+export declare function getTelegramFileSink(sessionId: string): TelegramFileSink | undefined;

package/dist/types/notifications/chat-adapters.d.ts

@@ -0,0 +1,9 @@
+import type { NotificationPresentationAdapter } from "./engine";
+type AdapterKind = "discord" | "slack";
+interface ChatAdapterOptions {
+    kind: AdapterKind;
+    channelId?: string;
+}
+export declare function createDiscordAdapter(opts?: Omit<ChatAdapterOptions, "kind">): NotificationPresentationAdapter;
+export declare function createSlackAdapter(opts?: Omit<ChatAdapterOptions, "kind">): NotificationPresentationAdapter;
+export {};

package/dist/types/notifications/config.d.ts

@@ -3,13 +3,21 @@ export interface NotificationConfig {
     enabled: boolean;
     botToken?: string;
     chatId?: string;
+    discord: {
+        botToken?: string;
+        channelId?: string;
+    };
+    slack: {
+        botToken?: string;
+        channelId?: string;
+    };
     redact: boolean;
     verbosity: "lean" | "verbose";
     idleTimeoutMs: number;
 }
 /** Read typed config from Settings. */
 export declare function getNotificationConfig(settings: Settings): NotificationConfig;
-/** Is global config sufficient for auto-on (enabled + botToken + chatId all present)? */
+/** Is global config sufficient for auto-on (enabled + at least one configured adapter)? */
 export declare function isGloballyConfigured(cfg: NotificationConfig): boolean;
 /** Resolve whether the notifications extension should be registered at SDK startup. */
 export declare function shouldRegisterNotificationsExtension(input: {

package/dist/types/notifications/engine.d.ts

@@ -0,0 +1,59 @@
+import { type RedactableAction } from "./config";
+export type NotificationEvent = ({
+    type: "action_needed";
+} & RedactableAction) | {
+    type: "action_resolved";
+    id: string;
+    sessionId: string;
+    resolvedBy?: string;
+} | {
+    type: "frame";
+    sessionId: string;
+    frame: Record<string, unknown>;
+};
+export interface NotificationReplyRoute {
+    sessionId: string;
+    actionId: string;
+    answer: number | string | {
+        selected?: Array<number | string>;
+        custom?: string;
+    };
+}
+export interface NotificationAdapterPayload {
+    adapter: string;
+    channelKey?: string;
+    body: unknown;
+    route?: Omit<NotificationReplyRoute, "answer">;
+}
+export interface NotificationPresentationAdapter {
+    readonly kind: "telegram" | "discord" | "slack";
+    render(event: NotificationEvent): NotificationAdapterPayload[];
+    mapInbound(input: unknown): NotificationReplyRoute | undefined;
+}
+export interface EngineSessionSink {
+    sendReply(route: NotificationReplyRoute): void;
+}
+export interface NotificationEngineOptions {
+    redact: boolean;
+    sessionTag: (sessionId: string) => string;
+}
+/**
+ * Shared presentation engine for managed notification clients.
+ *
+ * It owns fanout, redaction boundaries, pending-action routing, and reply
+ * delivery into session sinks. Transport adapters stay pure: render an internal
+ * event into a public-safe payload and map an inbound transport interaction
+ * back into a session/action answer.
+ */
+export declare class NotificationPresentationEngine {
+    private readonly opts;
+    readonly adapters: readonly NotificationPresentationAdapter[];
+    private readonly sessions;
+    private readonly pending;
+    constructor(adapters: readonly NotificationPresentationAdapter[], opts: NotificationEngineOptions);
+    connectSession(sessionId: string, sink: EngineSessionSink): void;
+    dropSession(sessionId: string): void;
+    fanout(event: NotificationEvent): NotificationAdapterPayload[];
+    routeInbound(adapterKind: NotificationPresentationAdapter["kind"], input: unknown): boolean;
+    private redactEvent;
+}

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

@@ -0,0 +1,48 @@
+import type { Settings } from "../config/settings";
+import { RateLimitPool } from "./rate-limit-pool";
+import { type ThreadedSend } from "./threaded-render";
+export interface ManagedNotificationDaemonFs {
+    readdir(path: string): Promise<string[]>;
+}
+export interface ManagedSessionSocket {
+    sessionId: string;
+    token: string;
+    ws: WebSocket;
+    pending: Map<string, {
+        sessionId: string;
+        actionId: string;
+    }>;
+    capable: boolean;
+    lastPongAt: number;
+    awaitingNonce: string | undefined;
+    pingTimer: ReturnType<typeof setInterval> | undefined;
+}
+export interface ManagedNotificationDaemonOptions {
+    settings: Settings;
+    fs: ManagedNotificationDaemonFs;
+    WebSocketImpl?: typeof WebSocket;
+    now?: () => number;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+    rateLimitPool?: RateLimitPool<{
+        send: ThreadedSend;
+        topicId?: string;
+    }>;
+}
+export declare abstract class ManagedNotificationDaemon {
+    protected readonly opts: ManagedNotificationDaemonOptions;
+    readonly sessions: Map<string, ManagedSessionSocket>;
+    readonly pool: RateLimitPool<{
+        send: ThreadedSend;
+        topicId?: string;
+    }>;
+    protected constructor(opts: ManagedNotificationDaemonOptions);
+    scanRoots(): Promise<void>;
+    connectSession(sessionId: string, url: string, token: string): ManagedSessionSocket;
+    protected handleSessionMessage(session: ManagedSessionSocket, msg: Record<string, unknown>): Promise<boolean>;
+    protected renderFrame(frame: Record<string, unknown>): ThreadedSend | undefined;
+    protected dropSession(session: ManagedSessionSocket): void;
+    protected abstract readRoots(): Promise<string[]>;
+    private sendHello;
+    private startLiveness;
+}

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

@@ -206,6 +206,12 @@ export declare class TelegramNotificationDaemon {
     private readonly topics;
     private readonly pool;
     private readonly seenUpdateIds;
+    /** 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;
     private flushTimer;
     private scanTimer;
     private scanning;
@@ -251,7 +257,20 @@ export declare class TelegramNotificationDaemon {
     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;

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/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/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,22 @@
+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 safe to hand to the
+ * insane-search engine. Resolves DNS names and rejects any that map to a
+ * private/special address. Never throws; returns a discriminated result.
+ */
+export declare function validatePublicHttpUrlForInsane(rawUrl: string, options?: {
+    resolver?: AddressResolver;
+}): Promise<PublicUrlResult>;