pipeline-moe 0.1.0

package/src/custom-tools/web-search.ts

@@ -0,0 +1,144 @@
+// web_search — SearXNG tool definition
+// Wraps a SearXNG instance (SEARXNG_URL env var — self-hosted or public).
+// Returns formatted results as text content.
+
+import { Type } from "typebox"
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent"
+
+// Minimal text content type (mirrors pi-ai TextContent — not re-exported).
+interface TextContent {
+  type: "text"
+  text: string
+}
+
+const SearxngResult = Type.Object({
+  title: Type.String(),
+  url: Type.String(),
+  content: Type.Optional(Type.String()),
+})
+
+const SearxngResponse = Type.Object({
+  results: Type.Array(SearxngResult),
+  query: Type.Optional(Type.String()),
+})
+
+const webSearchSchema = Type.Object({
+  query: Type.String({
+    description: "The search query",
+  }),
+  limit: Type.Optional(
+    Type.Number({
+      default: 5,
+      minimum: 1,
+      maximum: 20,
+      description: "Maximum number of results to return (1-20, default 5)",
+    }),
+  ),
+  categories: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "SearXNG categories to search: general, it, science, news, images, videos, academic",
+    }),
+  ),
+})
+
+// Read per call so tests (and long-lived processes) see env changes.
+const searxngUrl = () => process.env.SEARXNG_URL ?? ""
+const TIMEOUT_MS = 15_000
+
+async function searchSearxng(
+  query: string,
+  limit: number,
+  categories?: string[],
+): Promise<AgentToolResult<undefined>> {
+  const base = searxngUrl()
+  if (!base) {
+    return {
+      content: [{
+        type: "text",
+        text: "web_search error: SEARXNG_URL is not configured. Set it in .env to your SearXNG instance (self-hosted or public, JSON format enabled).",
+      }],
+      details: undefined,
+    }
+  }
+  const url = new URL("/search", base)
+  url.searchParams.set("q", query)
+  url.searchParams.set("format", "json")
+  url.searchParams.set("limit", String(limit))
+  if (categories && categories.length > 0) {
+    url.searchParams.set("categories", categories.join(","))
+  }
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    const response = await fetch(url.toString(), {
+      signal: controller.signal,
+      headers: { "Accept": "application/json" },
+    })
+
+    if (!response.ok) {
+      throw new Error(`SearXNG returned ${response.status} ${response.statusText}`)
+    }
+
+    const body = await response.json()
+    const results = (body as { results: Array<{ title: string; url: string; content?: string }> }).results ?? []
+
+    if (results.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `No results found for: "${query}"`,
+        }],
+        details: undefined,
+      }
+    }
+
+    // Format results as structured text.
+    const lines = [`Search results for "${query}" (${results.length} results):`]
+    for (let i = 0; i < results.length; i++) {
+      const r = results[i]
+      lines.push(`\n${i + 1}. ${r.title}`)
+      lines.push(`   URL: ${r.url}`)
+      if (r.content) {
+        // Truncate long snippets to avoid context bloat.
+        const snippet = r.content.length > 200 ? r.content.slice(0, 200) + "…" : r.content
+        lines.push(`   ${snippet}`)
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: undefined,
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      content: [{
+        type: "text",
+        text: `web_search error: ${msg}. Ensure your SearXNG instance is reachable at ${base}.`,
+      }],
+      details: undefined,
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export function createWebSearchToolDefinition(): ToolDefinition<typeof webSearchSchema, undefined> {
+  return {
+    name: "web_search",
+    label: "Web Search",
+    description:
+      "Search the web via SearXNG. Returns titles, URLs, and snippets for each result. " +
+      "Use this to find current information, verify facts, or discover resources outside the workspace.",
+    parameters: webSearchSchema,
+    execute: async (_toolCallId, params) => {
+      const query = params.query
+      const limit = Math.min(params.limit ?? 5, 20)
+      const categories = params.categories
+      return searchSearxng(query, limit, categories)
+    },
+  }
+}

package/src/custom-tools/youcom-search.ts

@@ -0,0 +1,230 @@
+// youcom_search — You.com enriched web search tool definition
+// Two modes: "search" (fast snippets) and "research" (autonomous synthesis).
+// API key from ~/.config/you.com/credentials.json — never exposed in results.
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { Type } from "typebox"
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent"
+
+// Minimal text content type.
+interface TextContent {
+  type: "text"
+  text: string
+}
+
+const youcomSearchSchema = Type.Object({
+  query: Type.String({
+    description: "Search query (supports operators: site:, filetype:, +term, -term)",
+  }),
+  mode: Type.Optional(
+    Type.Enum({ search: "search", research: "research" }, {
+      default: "search",
+      description: "search = fast snippets, research = autonomous synthesis with citations",
+    })
+  ),
+  count: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 20,
+      default: 5,
+      description: "Number of results for search mode (1-20, default 5)",
+    })
+  ),
+  freshness: Type.Optional(
+    Type.Enum({ day: "day", week: "week", month: "month", year: "year" }, {
+      description: "Freshness filter for search mode",
+    })
+  ),
+})
+
+const YDC_API = "https://ydc-index.io"
+const API_KEY_FILE = join(homedir(), ".config", "you.com", "credentials.json")
+const TIMEOUT_SEARCH_MS = 15_000
+const TIMEOUT_RESEARCH_MS = 60_000
+const MAX_CONTENT_LENGTH = 8000
+
+import { readFileSync } from "node:fs"
+
+// Read API key from file — cached at module level after first read.
+let apiKeyCache: { key: string | null; error: string | null } | null = null
+
+function readApiKey(): { key: string | null; error: string | null } {
+  if (apiKeyCache) return apiKeyCache
+
+  try {
+    const raw = readFileSync(API_KEY_FILE, "utf-8")
+    const parsed = JSON.parse(raw) as { api_key?: string }
+    if (!parsed.api_key) {
+      apiKeyCache = { key: null, error: "No api_key field in credentials file" }
+    } else {
+      apiKeyCache = { key: parsed.api_key, error: null }
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    apiKeyCache = { key: null, error: `Failed to read ${API_KEY_FILE}: ${msg}` }
+  }
+
+  return apiKeyCache
+}
+
+async function searchMode(query: string, count: number, freshness?: string): Promise<AgentToolResult<undefined>> {
+  const { key, error } = readApiKey()
+  if (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `youcom_search error: ${error}. Check that ${API_KEY_FILE} exists and contains an api_key field.`,
+      }],
+      details: undefined,
+    }
+  }
+
+  const params = new URLSearchParams({
+    query,
+    count: String(count),
+  })
+  if (freshness) params.set("freshness", freshness)
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_SEARCH_MS)
+  try {
+    const response = await fetch(`${YDC_API}/v1/search?${params}`, {
+      signal: controller.signal,
+      headers: { "X-API-Key": key! },
+    })
+
+    if (!response.ok) {
+      throw new Error(`You.com API returned ${response.status} ${response.statusText}`)
+    }
+
+    const body = await response.json() as { hits?: Array<{ title?: string; url?: string; snippet?: string }> }
+    const hits = body.hits ?? []
+
+    if (hits.length === 0) {
+      return {
+        content: [{ type: "text", text: `No results found for: "${query}"` }],
+        details: undefined,
+      }
+    }
+
+    const results = hits.map((hit, i) => {
+      const lines: string[] = []
+      lines.push(`${i + 1}. ${hit.title ?? "No title"}`)
+      if (hit.url) lines.push(`   URL: ${hit.url}`)
+      if (hit.snippet) lines.push(`   ${hit.snippet}`)
+      return lines.join("\n")
+    })
+
+    const header = `You.com search results for "${query}" (${results.length} results)`
+    return {
+      content: [{ type: "text", text: header + "\n\n" + results.join("\n\n") }],
+      details: undefined,
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      content: [{
+        type: "text",
+        text: `youcom_search error: ${msg}. Ensure You.com API is reachable at ${YDC_API}.`,
+      }],
+      details: undefined,
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+async function researchMode(query: string): Promise<AgentToolResult<undefined>> {
+  const { key, error } = readApiKey()
+  if (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `youcom_search error: ${error}. Check that ${API_KEY_FILE} exists and contains an api_key field.`,
+      }],
+      details: undefined,
+    }
+  }
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_RESEARCH_MS)
+  try {
+    const response = await fetch(`${YDC_API}/v1/research`, {
+      signal: controller.signal,
+      method: "POST",
+      headers: {
+        "X-API-Key": key!,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ query, effort: "standard" }),
+    })
+
+    if (!response.ok) {
+      throw new Error(`You.com API returned ${response.status} ${response.statusText}`)
+    }
+
+    const body = await response.json() as { answer?: string; sources?: Array<{ title?: string; url?: string }> }
+    const answer = body.answer ?? "No answer provided"
+    const sources = body.sources ?? []
+
+    const content = answer.length > MAX_CONTENT_LENGTH
+      ? answer.slice(0, MAX_CONTENT_LENGTH) + "\n\n[research truncated — " + answer.length + " chars total]"
+      : answer
+
+    const lines: string[] = [
+      `You.com research answer for "${query}"`,
+      "",
+      content,
+    ]
+
+    if (sources.length > 0) {
+      lines.push("")
+      lines.push("Sources:")
+      sources.forEach((src, i) => {
+        lines.push(`  ${i + 1}. ${src.title ?? "No title"} — ${src.url ?? "No URL"}`)
+      })
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: undefined,
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      content: [{
+        type: "text",
+        text: `youcom_search error: ${msg}. Ensure You.com API is reachable at ${YDC_API}.`,
+      }],
+      details: undefined,
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export function createYoucomSearchToolDefinition(): ToolDefinition<typeof youcomSearchSchema, undefined> {
+  return {
+    name: "youcom_search",
+    label: "You.com Search",
+    description:
+      "Enriched web search via You.com API. " +
+      "mode='search' for fast snippets with domain/freshness filtering. " +
+      "mode='research' for autonomous synthesis with citations (standard effort, ~$0.05/query). " +
+      "Supports query operators: site:, filetype:, +term, -term.",
+    parameters: youcomSearchSchema,
+    execute: async (_toolCallId, params) => {
+      const query = params.query
+      const mode = params.mode ?? "search"
+      const count = params.count ?? 5
+      const freshness = params.freshness
+
+      if (mode === "research") {
+        return researchMode(query)
+      }
+      return searchMode(query, count, freshness)
+    },
+  }
+}

package/src/custom-tools/youtube-transcript.ts

@@ -0,0 +1,124 @@
+// youtube_transcript — YouTube transcript tool definition
+// Fetches timestamped transcripts from YouTube videos.
+// Uses youtube-transcript-plus package.
+
+import { Type } from "typebox"
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent"
+import { YoutubeTranscript } from "youtube-transcript-plus"
+
+// Minimal text content type (mirrors pi-ai TextContent — not re-exported).
+interface TextContent {
+  type: "text"
+  text: string
+}
+
+const youtubeTranscriptSchema = Type.Object({
+  video: Type.String({
+    description: "YouTube video ID (11 chars) or full URL (youtube.com/watch?v=... or youtu.be/...)",
+  }),
+})
+
+const MAX_CONTENT_LENGTH = 8000
+
+// Extract video ID from various YouTube URL formats.
+function extractVideoId(input: string): string {
+  // Already a bare ID (11 chars, alphanumeric + _ -)
+  if (/^[a-zA-Z0-9_-]{11}$/.test(input.trim())) {
+    return input.trim()
+  }
+
+  // youtube.com/watch?v=VIDEO_ID
+  const watchMatch = input.match(/[?&]v=([a-zA-Z0-9_-]{11})/)
+  if (watchMatch) return watchMatch[1]
+
+  // youtu.be/VIDEO_ID
+  const shortMatch = input.match(/youtu\.be\/([a-zA-Z0-9_-]{11})/)
+  if (shortMatch) return shortMatch[1]
+
+  // youtube.com/embed/VIDEO_ID
+  const embedMatch = input.match(/embed\/([a-zA-Z0-9_-]{11})/)
+  if (embedMatch) return embedMatch[1]
+
+  throw new Error(`Could not extract video ID from: ${input}`)
+}
+
+// Format seconds as MM:SS.
+function formatTime(seconds: number): string {
+  const m = Math.floor(seconds / 60)
+  const s = Math.floor(seconds % 60)
+  return `${m}:${s.toString().padStart(2, "0")}`
+}
+
+async function fetchTranscript(videoInput: string): Promise<AgentToolResult<undefined>> {
+  let videoId: string
+  try {
+    videoId = extractVideoId(videoInput)
+  } catch (err) {
+    return {
+      content: [{
+        type: "text",
+        text: `youtube_transcript error: ${(err as Error).message}.`,
+      }],
+      details: undefined,
+    }
+  }
+
+  try {
+    const segments = await YoutubeTranscript.fetchTranscript(videoId)
+
+    if (!segments || segments.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `No transcript available for video ${videoId}. The video may not have captions or they may be disabled.`,
+        }],
+        details: undefined,
+      }
+    }
+
+    // Format as timestamped text.
+    const lines = segments.map((seg) => {
+      const time = formatTime(seg.offset)
+      return `[${time}] ${seg.text}`
+    })
+
+    const content = lines.join("\n")
+
+    // Truncate to avoid context explosion.
+    const text = content.length > MAX_CONTENT_LENGTH
+      ? content.slice(0, MAX_CONTENT_LENGTH) + "\n\n[transcript truncated — " + content.length + " chars total]"
+      : content
+
+    return {
+      content: [{ type: "text", text }],
+      details: undefined,
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      content: [{
+        type: "text",
+        text: `youtube_transcript error: ${msg}.`,
+      }],
+      details: undefined,
+    }
+  }
+}
+
+export function createYoutubeTranscriptToolDefinition(): ToolDefinition<typeof youtubeTranscriptSchema, undefined> {
+  return {
+    name: "youtube_transcript",
+    label: "YouTube Transcript",
+    description:
+      "Fetch timestamped transcript from a YouTube video. " +
+      "Accepts video ID (11 chars) or full URL (youtube.com/watch?v=... or youtu.be/...). " +
+      "Returns text formatted as [MM:SS] text. " +
+      "Truncated to ~8000 chars to avoid context explosion.",
+    parameters: youtubeTranscriptSchema,
+    execute: async (_toolCallId, params) => {
+      const video = params.video
+      return fetchTranscript(video)
+    },
+  }
+}

package/src/local-model-lock.ts

@@ -0,0 +1,52 @@
+// LocalModelLock — process-global semaphore(1) for llama-server inference.
+//
+// llama-server runs with --parallel 1: only one inference slot. When multiple
+// rooms are active, local-model agents must be serialized. Cloud agents bypass
+// this lock entirely (they hit independent endpoints).
+//
+// The lock is held by RoomManager and injected into each Room at creation.
+// Room.executeAgent() acquires before inference, releases in `finally`.
+
+/** Async semaphore with capacity 1 for serializing local-model inference. */
+export class LocalModelLock {
+  private held = false
+  private readonly queue: Array<() => void> = []
+
+  /**
+   * Acquire the lock. Resolves immediately if free; otherwise queues and waits
+   * until the current holder calls release().
+   */
+  async acquire(): Promise<void> {
+    if (!this.held) {
+      this.held = true
+      return
+    }
+    return new Promise<void>((resolve) => {
+      this.queue.push(resolve)
+    })
+  }
+
+  /**
+   * Release the lock. If there are waiting callers, the next one is unblocked.
+   * Calling release() when nothing was acquired is a no-op (safe).
+   */
+  release(): void {
+    const next = this.queue.shift()
+    if (next) {
+      // Hand ownership directly to the next waiter — held stays true.
+      next()
+    } else {
+      this.held = false
+    }
+  }
+
+  /** Whether the lock is currently held (useful for testing). */
+  get isHeld(): boolean {
+    return this.held
+  }
+
+  /** Number of callers waiting to acquire (useful for testing). */
+  get waitCount(): number {
+    return this.queue.length
+  }
+}

package/src/model.ts

@@ -0,0 +1,131 @@
+// Resolve the shared model registry / auth storage and pick a model once at
+// startup. All participants reuse these so we don't re-scan providers per agent.
+
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent"
+import { config } from "./config.js"
+
+export interface ResolvedModel {
+  authStorage: AuthStorage
+  modelRegistry: ModelRegistry
+  /** undefined → let createAgentSession use pi's default resolution. */
+  model: Awaited<ReturnType<ModelRegistry["getAvailable"]>>[number] | undefined
+}
+
+export async function resolveModel(): Promise<ResolvedModel> {
+  const authStorage = AuthStorage.create()
+  const modelRegistry = ModelRegistry.create(authStorage)
+
+  let model: ResolvedModel["model"]
+
+  if (config.modelOverride) {
+    const slash = config.modelOverride.indexOf("/")
+    const provider = slash >= 0 ? config.modelOverride.slice(0, slash) : ""
+    const id = slash >= 0 ? config.modelOverride.slice(slash + 1) : config.modelOverride
+    model = (modelRegistry.find(provider, id) as ResolvedModel["model"]) ?? undefined
+    if (!model) {
+      console.warn(`[model] override "${config.modelOverride}" not found; falling back to default`)
+    }
+  }
+
+  if (!model) {
+    const available = await modelRegistry.getAvailable()
+    // This stack is local-only by policy: always prefer the `local` provider
+    // (llama-server :5000) over any cloud model that happens to have a key.
+    model = available.find((m) => m.provider === "local") ?? available[0]
+  }
+
+  if (model && model.provider !== "local") {
+    console.warn(
+      `[model] WARNING: resolved a non-local model (${model.provider}/${model.id}). ` +
+        `This stack is meant to be local-only. Set PIPELINE_MODEL=local/<id> or check ~/.pi/agent/models.json.`,
+    )
+  }
+
+  console.log(
+    model
+      ? `[model] using ${model.provider}/${model.id}`
+      : `[model] no explicit model resolved; relying on pi defaults`,
+  )
+
+  return { authStorage, modelRegistry, model }
+}
+
+/** A model the UI can offer for per-agent selection. */
+export interface ModelInfo {
+  provider: string
+  id: string
+  /** "provider/id" — the value stored on a persona. */
+  ref: string
+  name: string
+  local: boolean
+}
+
+/** Parse a "provider/id" ref into its parts. */
+function splitRef(ref: string): { provider: string; id: string } {
+  const slash = ref.indexOf("/")
+  return slash >= 0
+    ? { provider: ref.slice(0, slash), id: ref.slice(slash + 1) }
+    : { provider: "", id: ref }
+}
+
+/** Models offered for per-agent selection: those with auth configured, filtered
+ *  to local unless cloud is explicitly allowed, or the provider has been
+ *  explicitly enabled by the user via /api/providers. */
+export function listModels(resolved: ResolvedModel, allowCloud: boolean, explicitlyEnabled?: Set<string>): ModelInfo[] {
+  return resolved.modelRegistry
+    .getAvailable()
+    .filter((m) =>
+      allowCloud || m.provider === "local" || (explicitlyEnabled?.has(m.provider) ?? false),
+    )
+    .map((m) => ({
+      provider: m.provider,
+      id: m.id,
+      ref: `${m.provider}/${m.id}`,
+      name: (m as { name?: string }).name ?? m.id,
+      local: m.provider === "local",
+    }))
+}
+
+/** True if a "provider/id" ref is a model the UI is allowed to assign. */
+export function isAllowedModel(resolved: ResolvedModel, allowCloud: boolean, ref: string, explicitlyEnabled?: Set<string>): boolean {
+  return listModels(resolved, allowCloud, explicitlyEnabled).some((m) => m.ref === ref)
+}
+
+/** Downgrade preset personas whose model isn't currently available to the
+ *  process default (model → undefined) instead of blocking the whole load.
+ *  Mutates `personas` in place and returns what was downgraded so the caller can
+ *  surface it. Mirrors resolveModelRef's runtime fallback — a stale cloud id or a
+ *  swapped local quant degrades gracefully rather than bricking every preset. */
+export function downgradeUnavailableModels(
+  personas: Array<{ name: string; model?: string }>,
+  isAllowed: (ref: string) => boolean,
+): Array<{ agent: string; model: string }> {
+  const downgraded: Array<{ agent: string; model: string }> = []
+  for (const p of personas) {
+    if (p.model && !isAllowed(p.model)) {
+      downgraded.push({ agent: p.name, model: p.model })
+      p.model = undefined
+    }
+  }
+  return downgraded
+}
+
+/** Resolve a persona's "provider/id" ref to a concrete model. Enforces the
+ *  local-only policy: a non-local ref (or an unknown one) falls back to the
+ *  process default rather than silently reaching the cloud. */
+export function resolveModelRef(resolved: ResolvedModel, allowCloud: boolean, ref?: string): ResolvedModel["model"] {
+  if (!ref) return resolved.model
+  const { provider, id } = splitRef(ref)
+  if (provider !== "local" && !allowCloud) {
+    console.warn(
+      `[model] persona model "${ref}" is non-local and cloud is disabled — using default instead.`,
+    )
+    return resolved.model
+  }
+  const found = resolved.modelRegistry.find(provider, id) as ResolvedModel["model"]
+  if (!found) {
+    console.warn(`[model] persona model "${ref}" not found — using default.`)
+    return resolved.model
+  }
+  return found
+}