@tuan_son.dinh/gsd 2.6.0

package/src/resources/extensions/remote-questions/slack-adapter.ts

@@ -0,0 +1,92 @@
+/**
+ * Remote Questions — Slack adapter
+ */
+
+import type { ChannelAdapter, RemotePrompt, RemoteDispatchResult, RemoteAnswer, RemotePromptRef } from "./types.js";
+import { formatForSlack, parseSlackReply } from "./format.js";
+
+const SLACK_API = "https://slack.com/api";
+const PER_REQUEST_TIMEOUT_MS = 15_000;
+
+export class SlackAdapter implements ChannelAdapter {
+  readonly name = "slack" as const;
+  private botUserId: string | null = null;
+  private readonly token: string;
+  private readonly channelId: string;
+
+  constructor(token: string, channelId: string) {
+    this.token = token;
+    this.channelId = channelId;
+  }
+
+  async validate(): Promise<void> {
+    const res = await this.slackApi("auth.test", {});
+    if (!res.ok) throw new Error(`Slack auth failed: ${res.error ?? "invalid token"}`);
+    this.botUserId = String(res.user_id ?? "");
+  }
+
+  async sendPrompt(prompt: RemotePrompt): Promise<RemoteDispatchResult> {
+    const res = await this.slackApi("chat.postMessage", {
+      channel: this.channelId,
+      text: "GSD needs your input",
+      blocks: formatForSlack(prompt),
+    });
+
+    if (!res.ok) throw new Error(`Slack postMessage failed: ${res.error ?? "unknown"}`);
+
+    const ts = String(res.ts);
+    const channel = String(res.channel);
+    return {
+      ref: {
+        id: prompt.id,
+        channel: "slack",
+        messageId: ts,
+        threadTs: ts,
+        channelId: channel,
+        threadUrl: `https://slack.com/archives/${channel}/p${ts.replace(".", "")}`,
+      },
+    };
+  }
+
+  async pollAnswer(prompt: RemotePrompt, ref: RemotePromptRef): Promise<RemoteAnswer | null> {
+    if (!this.botUserId) await this.validate();
+
+    const res = await this.slackApi("conversations.replies", {
+      channel: ref.channelId,
+      ts: ref.threadTs!,
+      limit: "20",
+    });
+
+    if (!res.ok) return null;
+
+    const messages = (res.messages ?? []) as Array<{ user?: string; text?: string; ts: string }>;
+    const userReplies = messages.filter((m) => m.ts !== ref.threadTs && m.user && m.user !== this.botUserId && m.text);
+    if (userReplies.length === 0) return null;
+
+    return parseSlackReply(String(userReplies[0].text), prompt.questions);
+  }
+
+  private async slackApi(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const url = `${SLACK_API}/${method}`;
+    const isGet = method === "conversations.replies" || method === "auth.test";
+
+    let response: Response;
+    if (isGet) {
+      const qs = new URLSearchParams(Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)]))).toString();
+      response = await fetch(`${url}?${qs}`, { method: "GET", headers: { Authorization: `Bearer ${this.token}` }, signal: AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS) });
+    } else {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": "application/json; charset=utf-8",
+        },
+        body: JSON.stringify(params),
+        signal: AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS),
+      });
+    }
+
+    if (!response.ok) throw new Error(`Slack API HTTP ${response.status}: ${response.statusText}`);
+    return (await response.json()) as Record<string, unknown>;
+  }
+}

package/src/resources/extensions/remote-questions/status.ts

@@ -0,0 +1,31 @@
+/**
+ * Remote Questions — status helpers
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readPromptRecord } from "./store.js";
+
+export interface LatestPromptSummary {
+  id: string;
+  status: string;
+  updatedAt: number;
+}
+
+export function getLatestPromptSummary(): LatestPromptSummary | null {
+  const runtimeDir = join(homedir(), ".gsd", "runtime", "remote-questions");
+  if (!existsSync(runtimeDir)) return null;
+  const files = readdirSync(runtimeDir).filter((f) => f.endsWith(".json"));
+  if (files.length === 0) return null;
+
+  let latest: LatestPromptSummary | null = null;
+  for (const file of files) {
+    const record = readPromptRecord(file.replace(/\.json$/, ""));
+    if (!record) continue;
+    if (!latest || record.updatedAt > latest.updatedAt) {
+      latest = { id: record.id, status: record.status, updatedAt: record.updatedAt };
+    }
+  }
+  return latest;
+}

package/src/resources/extensions/remote-questions/store.ts

@@ -0,0 +1,77 @@
+/**
+ * Remote Questions — durable prompt store
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { RemotePrompt, RemotePromptRecord, RemotePromptRef, RemoteAnswer, RemotePromptStatus } from "./types.js";
+
+function runtimeDir(): string {
+  return join(homedir(), ".gsd", "runtime", "remote-questions");
+}
+
+function recordPath(id: string): string {
+  return join(runtimeDir(), `${id}.json`);
+}
+
+export function createPromptRecord(prompt: RemotePrompt): RemotePromptRecord {
+  return {
+    version: 1,
+    id: prompt.id,
+    createdAt: prompt.createdAt,
+    updatedAt: Date.now(),
+    status: "pending",
+    channel: prompt.channel,
+    timeoutAt: prompt.timeoutAt,
+    pollIntervalMs: prompt.pollIntervalMs,
+    questions: prompt.questions,
+    context: prompt.context,
+  };
+}
+
+export function writePromptRecord(record: RemotePromptRecord): void {
+  mkdirSync(runtimeDir(), { recursive: true });
+  writeFileSync(recordPath(record.id), JSON.stringify(record, null, 2) + "\n", "utf-8");
+}
+
+export function readPromptRecord(id: string): RemotePromptRecord | null {
+  const path = recordPath(id);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as RemotePromptRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function updatePromptRecord(
+  id: string,
+  updates: Partial<RemotePromptRecord>,
+): RemotePromptRecord | null {
+  const current = readPromptRecord(id);
+  if (!current) return null;
+  const next: RemotePromptRecord = {
+    ...current,
+    ...updates,
+    updatedAt: Date.now(),
+  };
+  writePromptRecord(next);
+  return next;
+}
+
+export function markPromptDispatched(id: string, ref: RemotePromptRef): RemotePromptRecord | null {
+  return updatePromptRecord(id, { ref, status: "pending" });
+}
+
+export function markPromptAnswered(id: string, response: RemoteAnswer): RemotePromptRecord | null {
+  return updatePromptRecord(id, { response, status: "answered", lastPollAt: Date.now() });
+}
+
+export function markPromptStatus(id: string, status: RemotePromptStatus, lastError?: string): RemotePromptRecord | null {
+  return updatePromptRecord(id, {
+    status,
+    lastPollAt: Date.now(),
+    ...(lastError ? { lastError } : {}),
+  });
+}

package/src/resources/extensions/remote-questions/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Remote Questions — shared types
+ */
+
+export type RemoteChannel = "slack" | "discord";
+
+export interface RemoteQuestionOption {
+  label: string;
+  description: string;
+}
+
+export interface RemoteQuestion {
+  id: string;
+  header: string;
+  question: string;
+  options: RemoteQuestionOption[];
+  allowMultiple: boolean;
+}
+
+export interface RemotePrompt {
+  id: string;
+  channel: RemoteChannel;
+  createdAt: number;
+  timeoutAt: number;
+  pollIntervalMs: number;
+  questions: RemoteQuestion[];
+  context?: {
+    source: string;
+  };
+}
+
+export interface RemotePromptRef {
+  id: string;
+  channel: RemoteChannel;
+  messageId: string;
+  channelId: string;
+  threadTs?: string;
+  threadUrl?: string;
+}
+
+export interface RemoteAnswer {
+  answers: Record<string, { answers: string[]; user_note?: string }>;
+}
+
+export type RemotePromptStatus = "pending" | "answered" | "timed_out" | "failed" | "cancelled";
+
+export interface RemotePromptRecord {
+  version: 1;
+  id: string;
+  createdAt: number;
+  updatedAt: number;
+  status: RemotePromptStatus;
+  channel: RemoteChannel;
+  timeoutAt: number;
+  pollIntervalMs: number;
+  questions: RemoteQuestion[];
+  ref?: RemotePromptRef;
+  response?: RemoteAnswer;
+  lastPollAt?: number;
+  lastError?: string;
+  context?: {
+    source: string;
+  };
+}
+
+export interface RemoteDispatchResult {
+  ref: RemotePromptRef;
+}
+
+export interface ChannelAdapter {
+  readonly name: RemoteChannel;
+  validate(): Promise<void>;
+  sendPrompt(prompt: RemotePrompt): Promise<RemoteDispatchResult>;
+  pollAnswer(prompt: RemotePrompt, ref: RemotePromptRef): Promise<RemoteAnswer | null>;
+}

package/src/resources/extensions/search-the-web/cache.ts

@@ -0,0 +1,78 @@
+/**
+ * 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<V> {
+  private readonly max: number;
+  private readonly ttlMs: number;
+  private readonly store = new Map<string, { value: V; expiresAt: number }>();
+  private purgeTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: { max: number; ttlMs: number }) {
+    this.max = options.max;
+    this.ttlMs = options.ttlMs;
+  }
+
+  get(key: string): V | undefined {
+    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: string, value: V): void {
+    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: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  purgeStale(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) this.store.delete(key);
+    }
+  }
+
+  startPurgeInterval(intervalMs: number): void {
+    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 as NodeJS.Timeout).unref();
+    }
+  }
+
+  stopPurgeInterval(): void {
+    if (this.purgeTimer !== null) {
+      clearInterval(this.purgeTimer);
+      this.purgeTimer = null;
+    }
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+}

package/src/resources/extensions/search-the-web/command-search-provider.ts

@@ -0,0 +1,95 @@
+/**
+ * /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 type { ExtensionAPI } from '@mariozechner/pi-coding-agent'
+import type { AutocompleteItem } from '@mariozechner/pi-tui'
+import {
+  getTavilyApiKey,
+  getBraveApiKey,
+  getSearchProviderPreference,
+  setSearchProviderPreference,
+  resolveSearchProvider,
+  type SearchProviderPreference,
+} from './provider.ts'
+
+const VALID_PREFERENCES: SearchProviderPreference[] = ['tavily', 'brave', 'auto']
+
+function keyStatus(provider: 'tavily' | 'brave'): string {
+  if (provider === 'tavily') return getTavilyApiKey() ? '✓' : '✗'
+  return getBraveApiKey() ? '✓' : '✗'
+}
+
+function buildSelectOptions(): string[] {
+  return [
+    `tavily (key: ${keyStatus('tavily')})`,
+    `brave (key: ${keyStatus('brave')})`,
+    `auto`,
+  ]
+}
+
+function parseSelectChoice(choice: string): SearchProviderPreference {
+  if (choice.startsWith('tavily')) return 'tavily'
+  if (choice.startsWith('brave')) return 'brave'
+  return 'auto'
+}
+
+export function registerSearchProviderCommand(pi: ExtensionAPI): void {
+  pi.registerCommand('search-provider', {
+    description: 'Switch search provider (tavily, brave, auto)',
+
+    getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+      const trimmed = prefix.trim().toLowerCase()
+      return VALID_PREFERENCES
+        .filter((p) => p.startsWith(trimmed))
+        .map((p) => {
+          let description: string
+          if (p === 'auto') {
+            description = `Auto-select (tavily: ${keyStatus('tavily')}, brave: ${keyStatus('brave')})`
+          } else {
+            description = `key: ${keyStatus(p)}`
+          }
+          return { value: p, label: p, description }
+        })
+    },
+
+    async handler(args, ctx) {
+      const trimmed = args.trim().toLowerCase()
+
+      let chosen: SearchProviderPreference
+
+      if (trimmed && (VALID_PREFERENCES as string[]).includes(trimmed)) {
+        // Direct arg — apply immediately, no select UI
+        chosen = trimmed as SearchProviderPreference
+      } 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(result)
+      }
+
+      setSearchProviderPreference(chosen)
+      const effective = resolveSearchProvider()
+      ctx.ui.notify(
+        `Search provider set to ${chosen}. Effective provider: ${effective ?? 'none (no API keys)'}`,
+        'info',
+      )
+    },
+  })
+}

package/src/resources/extensions/search-the-web/format.ts

@@ -0,0 +1,258 @@
+/**
+ * Token-efficient output formatting for search results, page content,
+ * and LLM context responses.
+ */
+
+import { extractDomain } from "./url-utils";
+
+export interface SearchResultFormatted {
+  title: string;
+  url: string;
+  description: string;
+  age?: string;
+  extra_snippets?: string[];
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// 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: number): number {
+  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
+}
+
+// =============================================================================
+// Search Results Formatting
+// =============================================================================
+
+export interface FormatSearchOptions {
+  cached?: boolean;
+  summary?: string;
+  queryCorrected?: boolean;
+  originalQuery?: string;
+  correctedQuery?: string;
+  moreResultsAvailable?: boolean;
+}
+
+/**
+ * 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: string,
+  results: SearchResultFormatted[],
+  options: FormatSearchOptions = {}
+): string {
+  const parts: string[] = [];
+
+  // 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");
+}
+
+// =============================================================================
+// Page Content Formatting
+// =============================================================================
+
+export interface FormatPageOptions {
+  title?: string;
+  charCount: number;
+  truncated: boolean;
+  originalChars?: number;
+  hasMore?: boolean;
+  nextOffset?: number;
+}
+
+/**
+ * Format extracted page content with metadata header.
+ */
+export function formatPageContent(
+  url: string,
+  content: string,
+  options: FormatPageOptions
+): string {
+  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}`;
+}
+
+// =============================================================================
+// LLM Context Formatting
+// =============================================================================
+
+export interface LLMContextSnippet {
+  url: string;
+  title: string;
+  snippets: string[];
+}
+
+export interface LLMContextSource {
+  title: string;
+  hostname: string;
+  age: string[] | null;
+}
+
+/**
+ * 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: string,
+  grounding: LLMContextSnippet[],
+  sources: Record<string, LLMContextSource>,
+  options: { cached?: boolean; tokenCount?: number } = {}
+): string {
+  const parts: string[] = [];
+
+  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: Array<{
+    url: string;
+    title?: string;
+    content: string;
+    charCount: number;
+    error?: string;
+  }>
+): string {
+  const parts: string[] = [];
+
+  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");
+}