gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/dist/resources/extensions/remote-questions/telegram-adapter.js

@@ -0,0 +1,123 @@
+/**
+ * Remote Questions — Telegram adapter
+ */
+import { formatForTelegram, parseTelegramResponse } from "./format.js";
+import { apiRequest } from "./http-client.js";
+const TELEGRAM_API = "https://api.telegram.org";
+export class TelegramAdapter {
+    name = "telegram";
+    botUserId = null;
+    lastUpdateId = 0;
+    lastSentText = "";
+    token;
+    chatId;
+    constructor(token, chatId) {
+        this.token = token;
+        this.chatId = chatId;
+    }
+    async validate() {
+        const res = await this.telegramApi("getMe");
+        if (!res.ok || !res.result?.id)
+            throw new Error("Telegram auth failed: invalid bot token");
+        this.botUserId = res.result.id;
+    }
+    async sendPrompt(prompt) {
+        const payload = formatForTelegram(prompt);
+        this.lastSentText = payload.text;
+        const params = {
+            chat_id: this.chatId,
+            text: payload.text,
+            parse_mode: payload.parse_mode,
+        };
+        if (payload.reply_markup) {
+            params.reply_markup = payload.reply_markup;
+        }
+        const res = await this.telegramApi("sendMessage", params);
+        if (!res.ok || !res.result?.message_id) {
+            throw new Error(`Telegram sendMessage failed: ${JSON.stringify(res)}`);
+        }
+        const messageId = String(res.result.message_id);
+        const messageUrl = this.buildMessageUrl(this.chatId, messageId);
+        return {
+            ref: {
+                id: prompt.id,
+                channel: "telegram",
+                messageId,
+                channelId: this.chatId,
+                threadUrl: messageUrl,
+            },
+        };
+    }
+    async pollAnswer(prompt, ref) {
+        if (!this.botUserId)
+            await this.validate();
+        const res = await this.telegramApi("getUpdates", {
+            offset: this.lastUpdateId + 1,
+            timeout: 0,
+            allowed_updates: ["message", "callback_query"],
+        });
+        if (!res.ok || !Array.isArray(res.result))
+            return null;
+        for (const update of res.result) {
+            // Advance offset for all updates to prevent reprocessing
+            if (update.update_id > this.lastUpdateId) {
+                this.lastUpdateId = update.update_id;
+            }
+            // Handle callback_query (inline keyboard button press)
+            if (update.callback_query) {
+                const cq = update.callback_query;
+                const msg = cq.message;
+                if (msg &&
+                    String(msg.chat?.id) === ref.channelId &&
+                    String(msg.message_id) === ref.messageId &&
+                    cq.from?.id !== this.botUserId) {
+                    // Dismiss the loading spinner on the button
+                    try {
+                        await this.telegramApi("answerCallbackQuery", { callback_query_id: cq.id });
+                    }
+                    catch { /* best-effort */ }
+                    return parseTelegramResponse(cq.data ?? null, null, prompt.questions, prompt.id);
+                }
+            }
+            // Handle text reply (reply_to_message)
+            if (update.message) {
+                const msg = update.message;
+                if (String(msg.chat?.id) === ref.channelId &&
+                    msg.reply_to_message &&
+                    String(msg.reply_to_message.message_id) === ref.messageId &&
+                    msg.from?.id !== this.botUserId &&
+                    msg.text) {
+                    return parseTelegramResponse(null, msg.text, prompt.questions, prompt.id);
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Acknowledge receipt by editing the original message to append a checkmark.
+     * Best-effort — failures are silently ignored.
+     */
+    async acknowledgeAnswer(ref) {
+        try {
+            await this.telegramApi("editMessageText", {
+                chat_id: ref.channelId,
+                message_id: parseInt(ref.messageId, 10),
+                text: this.lastSentText + "\n\n✅ Answered",
+                parse_mode: "HTML",
+            });
+        }
+        catch {
+            // Best-effort — don't let acknowledgement failures affect the flow
+        }
+    }
+    buildMessageUrl(chatId, messageId) {
+        // Supergroups have chat IDs starting with -100
+        if (chatId.startsWith("-100")) {
+            return `https://t.me/c/${chatId.slice(4)}/${messageId}`;
+        }
+        return undefined;
+    }
+    async telegramApi(method, params) {
+        return apiRequest(`${TELEGRAM_API}/bot${this.token}/${method}`, "POST", params, { errorLabel: "Telegram API" });
+    }
+}

package/dist/resources/extensions/remote-questions/types.js

@@ -0,0 +1,5 @@
+/**
+ * Remote Questions — shared types
+ */
+/** Timeout applied to every outbound HTTP request across all channel adapters. */
+export const PER_REQUEST_TIMEOUT_MS = 15_000;

package/dist/resources/extensions/search-the-web/cache.js

@@ -0,0 +1,74 @@
+/**
+ * LRU cache with TTL — zero external dependencies.
+ *
+ * - max: maximum entries before oldest is evicted
+ * - ttlMs: time-to-live per entry
+ *
+ * Uses a Map (insertion-ordered) for O(1) LRU eviction:
+ * on every access the entry is deleted and re-inserted at the tail.
+ */
+export class LRUTTLCache {
+    max;
+    ttlMs;
+    store = new Map();
+    purgeTimer = null;
+    constructor(options) {
+        this.max = options.max;
+        this.ttlMs = options.ttlMs;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        // Refresh to tail (most-recently-used)
+        this.store.delete(key);
+        this.store.set(key, entry);
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.store.has(key)) {
+            this.store.delete(key);
+        }
+        else if (this.store.size >= this.max) {
+            const oldest = this.store.keys().next().value;
+            if (oldest !== undefined)
+                this.store.delete(oldest);
+        }
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    purgeStale() {
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (now > entry.expiresAt)
+                this.store.delete(key);
+        }
+    }
+    startPurgeInterval(intervalMs) {
+        if (this.purgeTimer !== null)
+            return;
+        this.purgeTimer = setInterval(() => this.purgeStale(), intervalMs);
+        // Don't keep the process alive just for cache cleanup
+        if (this.purgeTimer && typeof this.purgeTimer === "object" && "unref" in this.purgeTimer) {
+            this.purgeTimer.unref();
+        }
+    }
+    stopPurgeInterval() {
+        if (this.purgeTimer !== null) {
+            clearInterval(this.purgeTimer);
+            this.purgeTimer = null;
+        }
+    }
+    clear() {
+        this.store.clear();
+    }
+    get size() {
+        return this.store.size;
+    }
+}

package/dist/resources/extensions/search-the-web/command-search-provider.js

@@ -0,0 +1,79 @@
+/**
+ * /search-provider slash command.
+ *
+ * Lets users switch between tavily, brave, and auto search backends.
+ * Supports direct arg (`/search-provider tavily`) or interactive select UI.
+ * Tab completion provides the three valid options with key status.
+ *
+ * All provider logic lives in provider.ts (S01) — this is pure UI wiring.
+ */
+import { getTavilyApiKey, getBraveApiKey, getOllamaApiKey, getSearchProviderPreference, setSearchProviderPreference, resolveSearchProvider, } from './provider.js';
+const VALID_PREFERENCES = ['tavily', 'brave', 'ollama', 'auto'];
+function keyStatus(provider) {
+    if (provider === 'tavily')
+        return getTavilyApiKey() ? '✓' : '✗';
+    if (provider === 'ollama')
+        return getOllamaApiKey() ? '✓' : '✗';
+    return getBraveApiKey() ? '✓' : '✗';
+}
+function buildSelectOptions() {
+    return [
+        `tavily (key: ${keyStatus('tavily')})`,
+        `brave (key: ${keyStatus('brave')})`,
+        `ollama (key: ${keyStatus('ollama')})`,
+        `auto`,
+    ];
+}
+function parseSelectChoice(choice) {
+    if (choice.startsWith('tavily'))
+        return 'tavily';
+    if (choice.startsWith('brave'))
+        return 'brave';
+    if (choice.startsWith('ollama'))
+        return 'ollama';
+    return 'auto';
+}
+export function registerSearchProviderCommand(pi) {
+    pi.registerCommand('search-provider', {
+        description: 'Switch search provider (tavily, brave, ollama, auto)',
+        getArgumentCompletions(prefix) {
+            const trimmed = prefix.trim().toLowerCase();
+            return VALID_PREFERENCES
+                .filter((p) => p.startsWith(trimmed))
+                .map((p) => {
+                let description;
+                if (p === 'auto') {
+                    description = `Auto-select (tavily: ${keyStatus('tavily')}, brave: ${keyStatus('brave')}, ollama: ${keyStatus('ollama')})`;
+                }
+                else {
+                    description = `key: ${keyStatus(p)}`;
+                }
+                return { value: p, label: p, description };
+            });
+        },
+        async handler(args, ctx) {
+            const trimmed = args.trim().toLowerCase();
+            let chosen;
+            if (trimmed && VALID_PREFERENCES.includes(trimmed)) {
+                // Direct arg — apply immediately, no select UI
+                chosen = trimmed;
+            }
+            else {
+                // No arg or invalid arg — show interactive select
+                const current = getSearchProviderPreference();
+                const options = buildSelectOptions();
+                const result = await ctx.ui.select(`Search provider (current: ${current})`, options);
+                if (result === undefined) {
+                    // User cancelled — bail silently
+                    return;
+                }
+                chosen = parseSelectChoice(Array.isArray(result) ? result[0] : result);
+            }
+            setSearchProviderPreference(chosen);
+            const effective = resolveSearchProvider();
+            const isAnthropic = ctx.model?.provider === 'anthropic';
+            const nativeNote = isAnthropic ? '\nNote: Native Anthropic web search is also active (automatic, no API key needed).' : '';
+            ctx.ui.notify(`Search provider set to ${chosen}. Effective provider: ${effective ?? 'none (no API keys)'}${nativeNote}`, 'info');
+        },
+    });
+}

package/dist/resources/extensions/search-the-web/format.js

@@ -0,0 +1,161 @@
+/**
+ * Token-efficient output formatting for search results, page content,
+ * and LLM context responses.
+ */
+import { extractDomain } from "./url-utils.js";
+// =============================================================================
+// Adaptive Snippet Budget
+// =============================================================================
+/**
+ * Compute how many extra_snippets to show per result based on total count.
+ * Fewer results → more snippets each. More results → fewer snippets each.
+ *
+ * This keeps total output roughly constant regardless of result count.
+ */
+function snippetsPerResult(resultCount) {
+    if (resultCount <= 2)
+        return 5; // show all available
+    if (resultCount <= 4)
+        return 3;
+    if (resultCount <= 6)
+        return 2;
+    if (resultCount <= 8)
+        return 1;
+    return 0; // 9-10 results: descriptions only
+}
+/**
+ * Format search results in a compact, token-efficient format.
+ *
+ * Produces:
+ *   [1] Python Web Frameworks — example.com (2024-11)
+ *   Main snippet text...
+ *   + "additional excerpt 1"
+ *   + "additional excerpt 2"
+ *
+ * Snippet count per result adapts to total result count.
+ */
+export function formatSearchResults(query, results, options = {}) {
+    const parts = [];
+    // Header
+    const cacheTag = options.cached ? " (cached)" : "";
+    parts.push(`Search: "${query}"${cacheTag}`);
+    // Spellcheck/query correction notice
+    if (options.queryCorrected && options.correctedQuery) {
+        parts.push(`Note: Query was corrected to "${options.correctedQuery}" (original: "${options.originalQuery ?? query}")`);
+    }
+    parts.push(""); // blank line after header
+    // AI summary block if available (from Brave Summarizer)
+    if (options.summary) {
+        parts.push(`Summary: ${options.summary}\n`);
+    }
+    if (results.length === 0) {
+        parts.push("No results found.");
+        return parts.join("\n");
+    }
+    const maxSnippets = snippetsPerResult(results.length);
+    // Results
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const domain = extractDomain(r.url);
+        const age = r.age ? ` (${r.age})` : "";
+        // Compact header line: [N] Title — domain (age)
+        parts.push(`[${i + 1}] ${r.title} — ${domain}${age}`);
+        parts.push(r.url);
+        // Primary description
+        if (r.description) {
+            parts.push(r.description);
+        }
+        // Extra snippets — adaptive count based on total results
+        if (maxSnippets > 0 && r.extra_snippets && r.extra_snippets.length > 0) {
+            for (const snippet of r.extra_snippets.slice(0, maxSnippets)) {
+                const clean = snippet.replace(/\n/g, " ").trim();
+                if (clean)
+                    parts.push(`+ ${clean}`);
+            }
+        }
+        parts.push(""); // blank line between results
+    }
+    // Pagination hint
+    if (options.moreResultsAvailable) {
+        parts.push("[More results available — increase count or refine query]");
+    }
+    return parts.join("\n");
+}
+/**
+ * Format extracted page content with metadata header.
+ */
+export function formatPageContent(url, content, options) {
+    const domain = extractDomain(url);
+    const title = options.title ? ` — ${options.title}` : "";
+    const truncNote = options.truncated && options.originalChars
+        ? ` [truncated from ${options.originalChars.toLocaleString()} chars]`
+        : "";
+    const moreNote = options.hasMore && options.nextOffset
+        ? ` [use offset:${options.nextOffset} to continue reading]`
+        : "";
+    const header = `Page: ${domain}${title} (${options.charCount.toLocaleString()} chars)${truncNote}${moreNote}\n${url}\n---`;
+    return `${header}\n${content}`;
+}
+/**
+ * Format LLM Context API response in a compact, agent-optimized format.
+ *
+ * Output:
+ *   Context: "query" (N sources, ~Mk tokens)
+ *
+ *   [1] Page Title — domain.com (age)
+ *   url
+ *   Snippet text...
+ *   ---
+ *   Another snippet...
+ */
+export function formatLLMContext(query, grounding, sources, options = {}) {
+    const parts = [];
+    const cacheTag = options.cached ? " (cached)" : "";
+    const tokenTag = options.tokenCount ? ` (~${Math.round(options.tokenCount / 1000)}k tokens)` : "";
+    parts.push(`Context: "${query}" (${grounding.length} sources${tokenTag})${cacheTag}`);
+    parts.push("");
+    if (grounding.length === 0) {
+        parts.push("No relevant content found.");
+        return parts.join("\n");
+    }
+    for (let i = 0; i < grounding.length; i++) {
+        const g = grounding[i];
+        const source = sources[g.url];
+        const domain = source?.hostname || extractDomain(g.url);
+        const age = source?.age?.[2] ? ` (${source.age[2]})` : ""; // [2] is "N days ago" format
+        parts.push(`[${i + 1}] ${g.title || source?.title || "(untitled)"} — ${domain}${age}`);
+        parts.push(g.url);
+        // Join snippets with separator
+        for (const snippet of g.snippets) {
+            const clean = snippet.trim();
+            if (clean)
+                parts.push(clean);
+        }
+        parts.push(""); // blank line between sources
+    }
+    return parts.join("\n");
+}
+// =============================================================================
+// Multi-Page Formatting
+// =============================================================================
+/**
+ * Format multiple page extractions compactly.
+ */
+export function formatMultiplePages(pages) {
+    const parts = [];
+    for (const page of pages) {
+        const domain = extractDomain(page.url);
+        if (page.error) {
+            parts.push(`[✗] ${domain}: ${page.error}`);
+        }
+        else {
+            const title = page.title ? ` — ${page.title}` : "";
+            parts.push(`[✓] ${domain}${title} (${page.charCount.toLocaleString()} chars)`);
+            parts.push(page.url);
+            parts.push("---");
+            parts.push(page.content);
+        }
+        parts.push(""); // separator
+    }
+    return parts.join("\n");
+}

package/dist/resources/extensions/search-the-web/http.js

@@ -0,0 +1,178 @@
+/**
+ * HTTP utilities: retry with backoff, abort signal merging, error types, timing.
+ */
+// =============================================================================
+// Error Types
+// =============================================================================
+/** Structured error for non-2xx HTTP responses. */
+export class HttpError extends Error {
+    statusCode;
+    response;
+    constructor(message, statusCode, response) {
+        super(message);
+        this.name = "HttpError";
+        this.statusCode = statusCode;
+        this.response = response;
+        Object.setPrototypeOf(this, HttpError.prototype);
+    }
+}
+export function classifyError(err) {
+    if (err instanceof HttpError) {
+        const code = err.statusCode;
+        if (code === 401 || code === 403) {
+            return { kind: "auth_error", message: `HTTP ${code}: Invalid or missing API key. Check your API key with secure_env_collect.` };
+        }
+        if (code === 429) {
+            let retryAfterMs;
+            const retryAfter = err.response?.headers.get("Retry-After");
+            if (retryAfter) {
+                const seconds = parseFloat(retryAfter);
+                if (!isNaN(seconds))
+                    retryAfterMs = seconds * 1000;
+            }
+            return { kind: "rate_limited", message: `Rate limited (HTTP 429). ${retryAfterMs ? `Retry after ${Math.ceil(retryAfterMs / 1000)}s.` : "Wait before retrying."}`, retryAfterMs };
+        }
+        if (code === 400) {
+            return { kind: "invalid_request", message: `Bad request (HTTP 400): ${err.message}` };
+        }
+        if (code === 404)
+            return { kind: "not_found", message: `Not found (HTTP 404)` };
+        if (code >= 500)
+            return { kind: "server_error", message: `Server error (HTTP ${code}): ${err.message}` };
+        return { kind: "unknown", message: `HTTP ${code}: ${err.message}` };
+    }
+    if (err instanceof TypeError) {
+        return { kind: "network_error", message: `Network error: ${err.message}` };
+    }
+    const msg = err?.message ?? String(err);
+    if (msg.includes("abort") || msg.includes("timeout")) {
+        return { kind: "network_error", message: `Request timed out` };
+    }
+    return { kind: "unknown", message: msg };
+}
+/** Extract rate limit headers from a Brave API response. */
+export function extractRateLimitInfo(response) {
+    const remaining = response.headers.get("x-ratelimit-remaining");
+    const limit = response.headers.get("x-ratelimit-limit");
+    const reset = response.headers.get("x-ratelimit-reset");
+    if (!remaining && !limit)
+        return undefined;
+    return {
+        remaining: remaining ? parseInt(remaining, 10) : undefined,
+        limit: limit ? parseInt(limit, 10) : undefined,
+        reset: reset ? parseInt(reset, 10) : undefined,
+    };
+}
+// =============================================================================
+// Retry Logic
+// =============================================================================
+function isRetryable(error) {
+    if (error instanceof HttpError) {
+        return error.statusCode === 429 || error.statusCode >= 500;
+    }
+    if (error instanceof TypeError)
+        return true;
+    return false;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Merge multiple AbortSignals — aborts as soon as any fires. */
+export function anySignal(signals) {
+    const controller = new AbortController();
+    for (const sig of signals) {
+        if (sig.aborted) {
+            controller.abort(sig.reason);
+            break;
+        }
+        sig.addEventListener("abort", () => controller.abort(sig.reason), { once: true });
+    }
+    return controller.signal;
+}
+/**
+ * Fetch with automatic retry and full-jitter exponential backoff.
+ *
+ * - maxRetries: additional attempts after the first (total = maxRetries + 1)
+ * - Respects Retry-After header on 429 responses
+ * - Each attempt uses a 30-second AbortSignal timeout
+ * - Non-retryable errors thrown immediately
+ */
+export async function fetchWithRetry(url, options, maxRetries = 2) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const timeoutController = new AbortController();
+        const timeoutId = setTimeout(() => timeoutController.abort(), 30_000);
+        const callerSignal = options.signal;
+        const signal = callerSignal
+            ? anySignal([callerSignal, timeoutController.signal])
+            : timeoutController.signal;
+        try {
+            const response = await fetch(url, { ...options, signal });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new HttpError(`HTTP ${response.status}: ${response.statusText}`, response.status, response);
+            }
+            return response;
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            lastError = err;
+            if (!isRetryable(err))
+                throw err;
+            if (attempt < maxRetries) {
+                let delayMs;
+                if (err instanceof HttpError && err.statusCode === 429 && err.response) {
+                    const retryAfter = err.response.headers.get("Retry-After");
+                    if (retryAfter) {
+                        const seconds = parseFloat(retryAfter);
+                        delayMs = isNaN(seconds) ? 1000 : seconds * 1000;
+                    }
+                    else {
+                        delayMs = Math.random() * Math.min(32_000, 1_000 * 2 ** attempt);
+                    }
+                }
+                else {
+                    delayMs = Math.random() * Math.min(32_000, 1_000 * 2 ** attempt);
+                }
+                await sleep(delayMs);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Simple fetch with timeout, no retry. For content extraction where
+ * we want to fail fast.
+ */
+export async function fetchSimple(url, options = {}) {
+    const { timeoutMs = 15_000, ...fetchOpts } = options;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const callerSignal = fetchOpts.signal;
+    const signal = callerSignal
+        ? anySignal([callerSignal, controller.signal])
+        : controller.signal;
+    try {
+        const response = await fetch(url, { ...fetchOpts, signal });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            throw new HttpError(`HTTP ${response.status}: ${response.statusText}`, response.status, response);
+        }
+        return response;
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        throw err;
+    }
+}
+/**
+ * Fetch with retry AND timing/rate-limit extraction.
+ * Wraps fetchWithRetry and returns latency + rate limit info.
+ */
+export async function fetchWithRetryTimed(url, options, maxRetries = 2) {
+    const start = performance.now();
+    const response = await fetchWithRetry(url, options, maxRetries);
+    const latencyMs = Math.round(performance.now() - start);
+    const rateLimit = extractRateLimitInfo(response);
+    return { response, latencyMs, rateLimit };
+}

package/dist/resources/extensions/search-the-web/index.js

@@ -0,0 +1,41 @@
+/**
+ * Web Search Extension v4
+ *
+ * Native Anthropic hooks stay eager. Heavy tool registration is deferred in
+ * interactive mode so startup is not blocked on the full search tool stack.
+ */
+import { importExtensionModule } from "@gsd/pi-coding-agent";
+import { registerSearchProviderCommand } from "./command-search-provider.js";
+import { registerNativeSearchHooks } from "./native-search.js";
+let toolsPromise = null;
+async function registerSearchTools(pi) {
+    if (!toolsPromise) {
+        toolsPromise = (async () => {
+            const [{ registerSearchTool }, { registerFetchPageTool }, { registerLLMContextTool }] = await Promise.all([
+                importExtensionModule(import.meta.url, "./tool-search.js"),
+                importExtensionModule(import.meta.url, "./tool-fetch-page.js"),
+                importExtensionModule(import.meta.url, "./tool-llm-context.js"),
+            ]);
+            registerSearchTool(pi);
+            registerFetchPageTool(pi);
+            registerLLMContextTool(pi);
+        })().catch((error) => {
+            toolsPromise = null;
+            throw error;
+        });
+    }
+    return toolsPromise;
+}
+export default function (pi) {
+    registerSearchProviderCommand(pi);
+    registerNativeSearchHooks(pi);
+    pi.on("session_start", async (_event, ctx) => {
+        if (ctx.hasUI) {
+            void registerSearchTools(pi).catch((error) => {
+                ctx.ui.notify(`search-the-web failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            });
+            return;
+        }
+        await registerSearchTools(pi);
+    });
+}