@daniel156161/prism 0.2.76 → 0.2.81

package/src/prism-extensions/integrations/ai-memory-system.ts

@@ -2,8 +2,10 @@ type ExtensionAPI = any
 
 import { Type } from "typebox"
 import { readSettings } from "../core/shared-config.js"
+import { formatApiFailure, formatDegradedNotice } from "./ai-memory-errors.js"
 import { renderCollapsibleTextResult } from "../ui/collapsed-text-rendering.js"
-import { formatBracketedToolCall, renderSingleLineToolCall, type ThemeLike } from "../ui/tool-call-rendering.js"
+import { obsidianOpenUrl } from "./obsidian-memory.js"
+import { ansiHyperlink, formatBracketedToolCall, renderSingleLineToolCall, type ThemeLike } from "../ui/tool-call-rendering.js"
 
 const DEFAULT_BASE_URL = "http://127.0.0.1:8765"
 const DEFAULT_LIMIT = 8
@@ -13,8 +15,10 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
 const DEFAULT_STATUS_TIMEOUT_MS = 1_500
 const DEFAULT_INJECT_TIMEOUT_MS = 1_200
 const DEFAULT_INJECT_CACHE_TTL_MS = 60_000
+const DEFAULT_ALWAYS_CONTEXT_CACHE_TTL_MS = 60_000
 
 const injectCache = new Map<string, { expiresAt: number; results: any[] }>()
+const alwaysContextCache = { expiresAt: 0, content: "" }
 
 function aiMemoryBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
   return (env.PRISM_AI_MEMORY_BASE_URL || env.AI_MEMORY_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "")
@@ -106,7 +110,59 @@ async function postJson<T>(path: string, body: unknown, timeoutMs = aiMemoryRequ
     signal: AbortSignal.timeout(timeoutMs),
   })
   const text = await response.text()
-  if (!response.ok) throw new Error(`AI Memory request failed: HTTP ${response.status} ${text.slice(0, 500)}`)
+  if (!response.ok) {
+    const payload = body as any
+    throw new Error(formatApiFailure(response.status, text, {
+      method: "POST",
+      path,
+      query: typeof payload?.query === "string" ? payload.query : undefined,
+      filters: payload?.filters,
+    }))
+  }
+  return JSON.parse(text) as T
+}
+
+async function putJson<T>(path: string, body: unknown, timeoutMs = aiMemoryRequestTimeoutMs()): Promise<T> {
+  const baseUrl = aiMemoryBaseUrl()
+  const response = await fetch(`${baseUrl}${path}`, {
+    method: "PUT",
+    headers: { "content-type": "application/json; charset=utf-8", accept: "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  const text = await response.text()
+  if (!response.ok) throw new Error(formatApiFailure(response.status, text, { method: "PUT", path }))
+  return JSON.parse(text) as T
+}
+
+async function deleteJson<T>(path: string, body: unknown, timeoutMs = aiMemoryRequestTimeoutMs()): Promise<T> {
+  const baseUrl = aiMemoryBaseUrl()
+  const response = await fetch(`${baseUrl}${path}`, {
+    method: "DELETE",
+    headers: { "content-type": "application/json; charset=utf-8", accept: "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  const text = await response.text()
+  if (!response.ok) throw new Error(formatApiFailure(response.status, text, { method: "DELETE", path }))
+  return JSON.parse(text) as T
+}
+
+async function methodJson<T>(
+  method: string,
+  path: string,
+  timeoutMs = aiMemoryRequestTimeoutMs(),
+  body?: unknown,
+): Promise<T> {
+  const baseUrl = aiMemoryBaseUrl()
+  const response = await fetch(`${baseUrl}${path}`, {
+    method,
+    headers: { accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json; charset=utf-8" }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  const text = await response.text()
+  if (!response.ok) throw new Error(formatApiFailure(response.status, text, { method, path }))
   return JSON.parse(text) as T
 }
 
@@ -117,7 +173,7 @@ async function getJson<T>(path: string, timeoutMs = aiMemoryStatusTimeoutMs()):
     signal: AbortSignal.timeout(timeoutMs),
   })
   const text = await response.text()
-  if (!response.ok) throw new Error(`AI Memory request failed: HTTP ${response.status} ${text.slice(0, 500)}`)
+  if (!response.ok) throw new Error(formatApiFailure(response.status, text, { method: "GET", path }))
   return JSON.parse(text) as T
 }
 
@@ -130,11 +186,19 @@ function formatSearchResults(results: any[]): string {
     const lexical = Number(row.lexical_score ?? 0).toFixed(4)
     const graph = Number(row.graph_score ?? 0).toFixed(1)
     const fact = Number(row.fact_score ?? 0).toFixed(1)
+    const feedback = Number(row.feedback_score ?? 0).toFixed(2)
+    const stale = Number(row.stale_score ?? 0).toFixed(2)
     const excerpt = String(row.text ?? "").replace(/\s+/g, " ").trim().slice(0, 700)
-    return `${index + 1}. score=${score} vector=${vector} keyword=${keyword} lexical=${lexical} graph=${graph} fact=${fact}\nsource=${row.source}:${row.path} > ${row.heading}\n${excerpt}`
+    return `${index + 1}. score=${score} vector=${vector} keyword=${keyword} lexical=${lexical} graph=${graph} fact=${fact} feedback=${feedback} stale=${stale}\nsource=${row.source}:${row.path} > ${row.heading}\n${excerpt}`
   }).join("\n\n")
 }
 
+export function formatSearchResponse(data: any): string {
+  const results = Array.isArray(data?.results) ? data.results : []
+  const notices = [formatDegradedNotice(data?.degraded), String(data?.hint ?? "").trim()].filter(Boolean)
+  return [...notices, formatSearchResults(results)].join("\n\n")
+}
+
 function formatReadResult(data: any): string {
   const source = String(data?.source ?? "unknown")
   const path = String(data?.path ?? "unknown")
@@ -175,6 +239,22 @@ async function loadAiMemoryInjectResults(query: string): Promise<any[]> {
   return results
 }
 
+async function loadAlwaysContext(): Promise<string> {
+  const now = Date.now()
+  if (alwaysContextCache.expiresAt > now) return alwaysContextCache.content
+
+  const data = await methodJson<{ content: string }>(
+    "CONTEXT",
+    `/vault`,
+    aiMemoryInjectTimeoutMs(),
+    {},
+  )
+  const content = String(data?.content ?? "")
+  alwaysContextCache.expiresAt = now + DEFAULT_ALWAYS_CONTEXT_CACHE_TTL_MS
+  alwaysContextCache.content = content
+  return content
+}
+
 export function buildAiMemoryContextMessage(results: any[]): any | undefined {
   const filtered = Array.isArray(results) ? results : []
   if (filtered.length === 0) return undefined
@@ -191,6 +271,21 @@ export function buildAiMemoryContextMessage(results: any[]): any | undefined {
   }
 }
 
+function buildAlwaysContextMessage(content: string): any | undefined {
+  const trimmed = String(content ?? "").trim()
+  if (!trimmed) return undefined
+  return {
+    customType: "ai-memory-always-context",
+    display: false,
+    content: [
+      "# Always-loaded context from 00 Kontext",
+      "Durable background from the user's Obsidian vault. Use it as context; do not mention it unless useful.",
+      "",
+      trimmed,
+    ].join("\n"),
+  }
+}
+
 function renderAiMemoryResult(result: any, options: { expanded?: boolean; isPartial?: boolean } = {}, theme: ThemeLike): { render(width: number): string[] } {
   return renderCollapsibleTextResult(result, options, theme, {
     partialLabel: "Searching AI Memory...",
@@ -200,9 +295,25 @@ function renderAiMemoryResult(result: any, options: { expanded?: boolean; isPart
   })
 }
 
-function formatAiMemoryToolCall(toolName: string, args: any, theme: ThemeLike): string {
+export function formatAiMemoryToolCall(toolName: string, args: any, theme: ThemeLike): string {
   const label = toolName.replace(/^ai_memory_/, "ai memory ").replace(/_/g, " ")
-  return formatBracketedToolCall(label, args?.query || args?.id || args?.path || args?.session || "", theme)
+  const rawValue = args?.query || args?.id || args?.path || args?.session || ""
+  const value = typeof rawValue === "string" && rawValue.trim() ? rawValue.trim() : "..."
+  const linksToVaultNote = ["ai_memory_vault_write", "ai_memory_vault_edit", "ai_memory_vault_delete"].includes(toolName)
+  if (linksToVaultNote && value !== "...") {
+    return `${theme.fg("toolTitle", theme.bold(label))} ${theme.fg("accent", ansiHyperlink(obsidianOpenUrl(value), value))}`
+  }
+  return formatBracketedToolCall(label, value, theme)
+}
+
+function formatVaultWriteResult(action: "Wrote" | "Edited", params: any, responsePath: unknown): string {
+  const path = String(responsePath ?? params.path ?? "")
+  const frontmatter = params.frontmatter === undefined ? "" : String(params.frontmatter).trim()
+  const heading = action === "Edited" ? `# ${String(params.heading ?? "").trim()}` : ""
+  const body = String(params.body ?? "")
+  const writtenContent = [frontmatter, heading, body].filter(Boolean).join("\n\n") || "(empty)"
+  const status = action === "Wrote" ? `Wrote: ${path}\n\n` : ""
+  return `${status}Write content:\n${writtenContent}`
 }
 
 export default function aiMemorySystemExtension(pi: ExtensionAPI): void {
@@ -228,12 +339,12 @@ export default function aiMemorySystemExtension(pi: ExtensionAPI): void {
       path: Type.Optional(Type.String({ description: "Path substring filter" })),
     }),
     async execute(_id: string, params: any) {
-      const data = await postJson<{ results: any[] }>("/search", {
+      const data = await postJson<{ results: any[]; degraded?: any; hint?: string }>("/search", {
         query: String(params.query ?? ""),
         limit: clampLimit(params.limit),
         filters: cleanFilters(params),
       })
-      return { content: [{ type: "text", text: formatSearchResults(data.results) }], details: { count: data.results?.length ?? 0, results: data.results } }
+      return { content: [{ type: "text", text: formatSearchResponse(data) }], details: { count: data.results?.length ?? 0, results: data.results, degraded: data.degraded, hint: data.hint } }
     },
     renderCall(args: any, theme: ThemeLike, context: any) {
       return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_search", args, theme), context)
@@ -292,6 +403,226 @@ export default function aiMemorySystemExtension(pi: ExtensionAPI): void {
     },
   })
 
+  pi.registerTool({
+    name: "ai_memory_rate_result",
+    label: "AI Memory Rate Result",
+    description: "Rate one retrieved memory result so future ranking learns from it.",
+    promptSnippet: "Use ai_memory_rate_result when a retrieved memory was clearly helpful, irrelevant, outdated, or wrong.",
+    promptGuidelines: [
+      "Rate the path exactly as returned by ai_memory_search.",
+      "Use 'outdated' or 'wrong' when the user corrects information that came from memory.",
+      "This changes ranking only; it never writes or deletes a note.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({ description: "Path of the rated result, e.g. 02 Projekte/Memory.md" }),
+      rating: Type.String({ description: "helpful, irrelevant, outdated, or wrong" }),
+      query: Type.Optional(Type.String({ description: "Search query that produced the result" })),
+      reason: Type.Optional(Type.String({ description: "Short reason in German" })),
+      source: Type.Optional(Type.String({ description: "obsidian or prism_session" })),
+      chunk_id: Type.Optional(Type.String({ description: "Exact chunk id if known" })),
+      session_id: Type.Optional(Type.String({ description: "Originating session id" })),
+    }),
+    async execute(_id: string, params: any) {
+      const data = await postJson<any>("/retrieval-feedback", {
+        path: String(params.path ?? ""),
+        rating: String(params.rating ?? ""),
+        query: String(params.query ?? ""),
+        reason: String(params.reason ?? ""),
+        source: String(params.source ?? ""),
+        chunk_id: String(params.chunk_id ?? ""),
+        session_id: String(params.session_id ?? ""),
+      })
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_rate_result", args, theme), context)
+    },
+  })
+
+  pi.registerTool({
+    name: "ai_memory_session_review",
+    label: "AI Memory Session Review",
+    description: "Review a Prism session for outcome evidence and human-approved durable lesson proposals.",
+    promptSnippet: "Review a completed session and return pending lessons; this does not approve them.",
+    parameters: Type.Object({
+      session: Type.Optional(Type.String({ description: "Session path/id or latest" })),
+      force: Type.Optional(Type.Boolean({ description: "Review an unchanged session again" })),
+    }),
+    async execute(_id: string, params: any) {
+      const data = await postJson<any>("/session-review", {
+        session: typeof params.session === "string" ? params.session : "latest",
+        force: params.force === true,
+      })
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_session_review", args, theme), context)
+    },
+  })
+
+  pi.registerTool({
+    name: "ai_memory_propose_lesson",
+    label: "AI Memory Propose Lesson",
+    description: "Create a pending durable lesson proposal. User approval is still required before writing memory.",
+    promptSnippet: "Propose a lesson from explicit user feedback without promoting it automatically.",
+    parameters: Type.Object({
+      category: Type.String({ description: "correction, decision, preference, workflow, or quality" }),
+      title: Type.String({ description: "Short German title" }),
+      rule: Type.String({ description: "Proposed durable rule in German" }),
+      rationale: Type.Optional(Type.String({ description: "Why the rule matters" })),
+      evidence: Type.String({ description: "Exact user feedback supporting the proposal" }),
+      session_id: Type.Optional(Type.String({ description: "Originating session id" })),
+      confidence: Type.Optional(Type.Number({ description: "Confidence from 0 to 1" })),
+    }),
+    async execute(_id: string, params: any) {
+      const data = await postJson<any>("/lessons", {
+        category: String(params.category ?? ""),
+        title: String(params.title ?? ""),
+        rule: String(params.rule ?? ""),
+        rationale: String(params.rationale ?? ""),
+        evidence: String(params.evidence ?? ""),
+        session_id: String(params.session_id ?? "manual"),
+        confidence: params.confidence === undefined ? 0.8 : Number(params.confidence),
+      })
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_propose_lesson", args, theme), context)
+    },
+  })
+
+  pi.registerTool({
+    name: "ai_memory_feedback",
+    label: "AI Memory Feedback",
+    description: "List pending lessons or approve/reject one proposal. Approval writes durable memory.",
+    promptSnippet: "Use only after explicit user approval to approve a proposed durable lesson.",
+    promptGuidelines: ["Never approve a lesson without explicit user approval in the current conversation."],
+    parameters: Type.Object({
+      action: Type.Optional(Type.String({ description: "list (default), approve, or reject" })),
+      proposal_id: Type.Optional(Type.String({ description: "Required for approve/reject" })),
+      status: Type.Optional(Type.String({ description: "List filter: pending, approved, or rejected" })),
+      session_id: Type.Optional(Type.String({ description: "Optional session filter for listing" })),
+    }),
+    async execute(_id: string, params: any) {
+      const action = String(params.action ?? "list")
+      let data: any
+      if (action === "list") {
+        const query = new URLSearchParams()
+        if (params.status) query.set("status", String(params.status))
+        if (params.session_id) query.set("session_id", String(params.session_id))
+        data = await getJson<any>(`/lessons${query.size ? `?${query}` : ""}`, aiMemoryRequestTimeoutMs())
+      } else {
+        if (!["approve", "reject"].includes(action) || !params.proposal_id) {
+          throw new Error("action must be list, approve, or reject; proposal_id is required for decisions")
+        }
+        data = await methodJson<any>("DECISION", "/lessons", aiMemoryRequestTimeoutMs(), {
+          proposal_id: String(params.proposal_id),
+          decision: action,
+        })
+      }
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_feedback", args, theme), context)
+    },
+  })
+
+  // ── File-backed vault ops (write/edit/list/delete) ──
+
+  pi.registerTool({
+    name: "ai_memory_vault_list",
+    label: "AI Memory Vault List",
+    description: "List Markdown files inside the configured Obsidian vault (codebase-local workspace by default).",
+    promptSnippet: "List vault Markdown notes [paths only]",
+    parameters: Type.Object({
+      subdir: Type.Optional(Type.String({ description: "Vault-relative directory to search (default: root)" })),
+      limit: Type.Optional(Type.Number({ description: "Maximum paths to return (default 100)" })),
+    }),
+    async execute(_id: string, params: any) {
+      const subdir = typeof params.subdir === "string" ? params.subdir : ""
+      const limit = params.limit === undefined ? 100 : Math.max(1, Math.min(500, Math.trunc(params.limit)))
+      const data = await methodJson<any>("LIST", `/vault`, aiMemoryInjectTimeoutMs(), { subdir, limit })
+      const files = Array.isArray(data.files) ? data.files : []
+      return { content: [{ type: "text", text: files.join("\n") || "No Markdown notes found." }], details: { files, count: files.length } }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_vault_list", args, theme), context)
+    },
+  })
+
+  pi.registerTool({
+    name: "ai_memory_vault_write",
+    label: "AI Memory Vault Write",
+    description: "Create/overwrite a Markdown file in the configured Obsidian vault.",
+    promptSnippet: "Write vault file [show path and written body/frontmatter]",
+    parameters: Type.Object({
+      path: Type.String({ description: "Vault-relative path, e.g. 02 Projekte/Test.md" }),
+      frontmatter: Type.Optional(Type.String({ description: "Optional YAML frontmatter including leading/trailing --- lines" })),
+      body: Type.String({ description: "Markdown body (without YAML frontmatter unless you include it in frontmatter)" }),
+    }),
+    async execute(_id: string, params: any) {
+      const data = await postJson<any>("/vault", {
+        path: String(params.path ?? ""),
+        frontmatter: params.frontmatter !== undefined ? String(params.frontmatter) : null,
+        body: String(params.body ?? ""),
+      })
+      return { content: [{ type: "text", text: formatVaultWriteResult("Wrote", params, data.path) }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_vault_write", args, theme), context)
+    },
+    renderResult(result: any, options: any, theme: ThemeLike) {
+      return renderAiMemoryResult(result, options, theme)
+    },
+  })
+
+  pi.registerTool({
+    name: "ai_memory_vault_edit",
+    label: "AI Memory Vault Edit",
+    description: "Replace the content block under a given heading in a Markdown file (or append if missing).",
+    promptSnippet: "Edit vault file section [show path, heading, and written body/frontmatter]",
+    parameters: Type.Object({
+      path: Type.String({ description: "Vault-relative path" }),
+      heading: Type.String({ description: "Heading text without leading #, e.g. 'Update 2026-01-01 — Thema'" }),
+      frontmatter: Type.Optional(Type.String({ description: "Optional YAML frontmatter including leading/trailing --- lines" })),
+      body: Type.String({ description: "Markdown body for that heading section (without '# Heading' line)" }),
+    }),
+    async execute(_id: string, params: any) {
+      const data = await putJson<any>("/vault", {
+        path: String(params.path ?? ""),
+        heading: String(params.heading ?? ""),
+        frontmatter: params.frontmatter !== undefined ? String(params.frontmatter) : null,
+        body: String(params.body ?? ""),
+      })
+      return { content: [{ type: "text", text: formatVaultWriteResult("Edited", params, data.path) }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_vault_edit", args, theme), context)
+    },
+    renderResult(result: any, options: any, theme: ThemeLike) {
+      return renderAiMemoryResult(result, options, theme)
+    },
+  })
+
+  pi.registerTool({
+    name: "ai_memory_vault_delete",
+    label: "AI Memory Vault Delete",
+    description: "Delete a Markdown file from the configured Obsidian vault.",
+    promptSnippet: "Delete vault file [path]",
+    parameters: Type.Object({
+      path: Type.String({ description: "Vault-relative path" }),
+    }),
+    async execute(_id: string, params: any) {
+      const data = await deleteJson<any>("/vault", {
+        path: String(params.path ?? ""),
+      })
+      return { content: [{ type: "text", text: `Deleted: ${data.path ?? params.path}` }], details: data }
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatAiMemoryToolCall("ai_memory_vault_delete", args, theme), context)
+    },
+  })
+
   pi.registerCommand("ai-memory", {
     description: "Search local AI Memory System: /ai-memory <query>",
     handler: async (args: string, ctx: any) => {
@@ -316,6 +647,24 @@ export default function aiMemorySystemExtension(pi: ExtensionAPI): void {
   })
 
   pi.on?.("before_agent_start", async (event: any) => {
+    // Always-loaded durable context (mapped from 00 Kontext) is injected as a
+    // system-prompt chunk so it remains in the cached prefix.
+    let alwaysBlock: string | undefined
+    try {
+      const alwaysContent = await loadAlwaysContext()
+      const alwaysMessage = buildAlwaysContextMessage(alwaysContent)
+      alwaysBlock = alwaysMessage?.content
+    } catch {
+      // Ignore — always-context is best-effort.
+    }
+
+    const prev = String(event?.systemPrompt ?? "")
+    if (alwaysBlock && alwaysBlock.trim()) {
+      const block = alwaysBlock.trim()
+      return { systemPrompt: `${prev}${prev ? "\n\n" : ""}${block}` }
+    }
+
+    // Query-specific candidates
     if (!shouldInjectAiMemoryCandidates()) return
     const query = String(event?.prompt ?? "").trim()
     if (!query) return

package/src/prism-extensions/integrations/research-tools.ts

@@ -5,6 +5,7 @@ import { fuzzyFilter } from "../core/fuzzy.js"
 import { clearPrismManifestRoutingTier, setPrismManifestRoutingTier } from "../core/manifest-routing.js"
 import { renderCollapsibleTextResult } from "../ui/collapsed-text-rendering.js"
 import { formatBracketedToolCall, renderSingleLineToolCall, type ThemeLike } from "../ui/tool-call-rendering.js"
+import { fetchYouTubeContent, isYouTubeUrl } from "./youtube.js"
 
 export function formatResearchToolCall(toolName: "web_search" | "web_fetch", args: any, theme: ThemeLike): string {
   const displayName = toolName === "web_search" ? "web search" : "web fetch"
@@ -331,6 +332,7 @@ export async function webSearch(query: string, limit = 10): Promise<string> {
 export async function webFetch(url: string, maxChars = 20_000): Promise<string> {
   const safeUrl = validateHttpUrl(url)
   const safeMaxChars = clampLimit(maxChars, 20_000, 1_000, 100_000)
+  if (isYouTubeUrl(safeUrl)) return fetchYouTubeContent(safeUrl)
   const response = await fetch(safeUrl, { headers: { "User-Agent": "Mozilla/5.0 (compatible; prism-research/1.0)" }, signal: AbortSignal.timeout(15_000) })
   const text = await response.text()
   if (!response.ok) throw new Error(`Fetch failed for ${safeUrl}: HTTP ${response.status}`)
@@ -390,8 +392,8 @@ export default function researchToolsExtension(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "web_fetch",
     label: "web fetch",
-    description: "Fetch readable text from a web page for citation-backed research.",
-    promptSnippet: "Fetch readable text from a web page.",
+    description: "Fetch readable text from a web page for citation-backed research. For YouTube URLs, extracts structured video metadata and the complete transcript without applying maxChars truncation.",
+    promptSnippet: "Fetch readable text from a web page. For YouTube URLs, extracts structured video metadata and the complete transcript without truncation.",
     parameters: Type.Object({ url: Type.String(), maxChars: Type.Optional(Type.Number()) }),
     async execute(_id: string, params: any) {
       return { content: [{ type: "text", text: await webFetch(params.url, params.maxChars || 20_000) }], details: { url: params.url } }