@ahkohd/yagami 0.1.2

package/src/mcp.ts

@@ -0,0 +1,337 @@
+import type { YagamiEngine } from "./engine.js";
+
+export type JsonObject = Record<string, unknown>;
+
+export const MCP_DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS = new Set<string>([MCP_DEFAULT_PROTOCOL_VERSION, "2025-03-26"]);
+
+export type McpToolContent = {
+  type: "text";
+  text: string;
+};
+
+export type McpToolCallResult = {
+  content: McpToolContent[];
+  structuredContent?: unknown;
+  isError?: boolean;
+};
+
+export type McpToolDefinition = {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: JsonObject;
+};
+
+export const MCP_TOOL_DEFINITIONS: McpToolDefinition[] = [
+  {
+    name: "web_search",
+    title: "Yagami Search",
+    description: "Search the web for any topic and get clean, ready-to-use content. Returns collated source content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Web search query",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_code_context",
+    title: "Yagami Code Search",
+    description:
+      "Find code examples, documentation, and programming solutions from sources like GitHub, Stack Overflow, and official docs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query for code context",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fetch_content",
+    title: "Yagami Fetch",
+    description: "Fetch and extract full content from a specific URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to crawl and extract content from",
+        },
+        maxCharacters: {
+          type: "number",
+          description: "Maximum characters to extract (default: 3000)",
+        },
+      },
+      required: ["url"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "company_research",
+    title: "Yagami Company Research",
+    description: "Research a company using Yagami's company-search mode.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        companyName: {
+          type: "string",
+          description: "Name of the company to research",
+        },
+      },
+      required: ["companyName"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "web_search_advanced",
+    title: "Yagami Advanced Search",
+    description: "Advanced web search with optional domain and category filtering.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query",
+        },
+        includeDomains: {
+          type: "array",
+          items: { type: "string" },
+          description: "Only include results from these domains",
+        },
+        excludeDomains: {
+          type: "array",
+          items: { type: "string" },
+          description: "Exclude results from these domains",
+        },
+        category: {
+          type: "string",
+          description: "Filter results to a specific category",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "find_similar",
+    title: "Yagami Similar",
+    description: "Find pages similar to a given URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to find similar pages for",
+        },
+      },
+      required: ["url"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "deep_research_start",
+    title: "Yagami Deep Research Start",
+    description: "Start an async deep research task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        instructions: {
+          type: "string",
+          description: "Complex research question or detailed instructions",
+        },
+        effort: {
+          type: "string",
+          enum: ["fast", "balanced", "thorough"],
+          description: "Research effort level",
+        },
+      },
+      required: ["instructions"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "deep_research_check",
+    title: "Yagami Deep Research Check",
+    description: "Check status and result of a deep research task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        researchId: {
+          type: "string",
+          description: "Research ID returned by deep_research_start",
+        },
+      },
+      required: ["researchId"],
+      additionalProperties: false,
+    },
+  },
+];
+
+function asObject(value: unknown): JsonObject {
+  return typeof value === "object" && value !== null ? (value as JsonObject) : {};
+}
+
+function getTrimmedString(value: unknown): string {
+  return String(value ?? "").trim();
+}
+
+function normalizeStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+
+  return value.map((entry) => String(entry ?? "").trim()).filter(Boolean);
+}
+
+function formatToolTextResult(result: unknown): string {
+  if (typeof result === "string") return result;
+
+  const obj = asObject(result);
+  if (typeof obj.answer === "string") return obj.answer;
+  if (typeof obj.text === "string") return obj.text;
+
+  return JSON.stringify(result, null, 2);
+}
+
+function toMcpToolResult(result: unknown): McpToolCallResult {
+  const payload: McpToolCallResult = {
+    content: [{ type: "text", text: formatToolTextResult(result) }],
+  };
+
+  if (typeof result === "object" && result !== null) {
+    payload.structuredContent = result;
+  }
+
+  return payload;
+}
+
+function defaultFindSimilarQuery(url: string): string {
+  return `Find web pages similar to ${url}. Focus on same product category, target users, and use-case overlap. Avoid dictionary/synonym pages.`;
+}
+
+function assertRequiredString(value: unknown, fieldName: string): string {
+  const normalized = getTrimmedString(value);
+  if (!normalized) {
+    throw new Error(`Missing required field: ${fieldName}`);
+  }
+  return normalized;
+}
+
+export async function executeMcpTool(
+  engine: YagamiEngine,
+  toolName: string,
+  rawArgs: unknown,
+): Promise<McpToolCallResult> {
+  const args = asObject(rawArgs);
+
+  switch (toolName) {
+    case "web_search": {
+      const query = assertRequiredString(args.query, "query");
+      const result = await engine.enqueueQuery(query, {});
+      return toMcpToolResult(result);
+    }
+
+    case "web_search_advanced": {
+      const query = assertRequiredString(args.query, "query");
+      const result = await engine.enqueueQuery(query, {
+        researchPolicy: args,
+      });
+      return toMcpToolResult(result);
+    }
+
+    case "get_code_context": {
+      const query = assertRequiredString(args.query, "query");
+      const result = await engine.enqueueQuery(query, {
+        researchPolicy: {
+          mode: "code",
+          ...args,
+        },
+      });
+      return toMcpToolResult(result);
+    }
+
+    case "fetch_content": {
+      const url = assertRequiredString(args.url, "url");
+      const result = await engine.enqueueOperation(() =>
+        engine.fetchContent(url, {
+          maxCharacters: args.maxCharacters,
+          noCache: args.noCache,
+        }),
+      );
+      return toMcpToolResult(result);
+    }
+
+    case "company_research": {
+      const companyName = assertRequiredString(args.companyName ?? args.query, "companyName");
+      const query = getTrimmedString(args.query || companyName);
+
+      const result = await engine.enqueueQuery(query, {
+        researchPolicy: {
+          mode: "company",
+          ...args,
+          companyName,
+        },
+      });
+      return toMcpToolResult(result);
+    }
+
+    case "find_similar": {
+      const url = assertRequiredString(args.url, "url");
+      const query = getTrimmedString(args.query || defaultFindSimilarQuery(url));
+      const seedUrls = [url, ...normalizeStringArray(args.seedUrls)];
+
+      const result = await engine.enqueueQuery(query, {
+        researchPolicy: {
+          mode: "similar",
+          ...args,
+          seedUrls,
+        },
+      });
+      return toMcpToolResult(result);
+    }
+
+    case "deep_research_start": {
+      const instructions = assertRequiredString(args.instructions, "instructions");
+
+      if (args.model !== undefined) {
+        throw new Error("Field 'model' has been removed. Use 'effort' (fast|balanced|thorough).");
+      }
+
+      const result = await engine.deepResearchStart(instructions, {
+        effort: args.effort,
+      });
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result,
+      };
+    }
+
+    case "deep_research_check": {
+      const researchId = assertRequiredString(args.researchId, "researchId");
+      const result = await engine.deepResearchCheck(researchId);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result,
+      };
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${toolName}`);
+  }
+}
+
+export function isKnownMcpTool(toolName: string): boolean {
+  return MCP_TOOL_DEFINITIONS.some((tool) => tool.name === toolName);
+}

package/src/shims-cli.d.ts

@@ -0,0 +1,3 @@
+declare module "cli-markdown" {
+  export default function cliMarkdown(markdown: string, options?: { width?: number }): string;
+}

package/src/types/cli.ts

@@ -0,0 +1,7 @@
+export interface ThemePreviewJson {
+  theme: string;
+  configFile: string;
+  overrides: Record<string, string>;
+  resolvedTokens: Record<string, string>;
+  samples: Record<string, string>;
+}

package/src/types/config.ts

@@ -0,0 +1,53 @@
+export type ThemeName = "ansi" | "none";
+
+export type ThemeTokenName = "domain" | "title" | "duration" | "error" | "dim" | "cyan" | "bold";
+
+export type ToolExecutionMode = "sequential" | "parallel";
+
+export type LlmApi = "openai-completions" | "anthropic-messages";
+
+export type SearchEnginePreset = "duckduckgo" | "bing" | "google" | "brave" | "custom";
+
+export interface RuntimeConfig {
+  runtimeDir: string;
+  configFile: string;
+  host: string;
+  port: number;
+  daemonUrl: string;
+
+  pidFile: string;
+  logFile: string;
+
+  llmApi: LlmApi;
+  llmBaseUrl: string;
+  llmApiKey: string;
+  llmModel: string;
+
+  searchEngine: SearchEnginePreset;
+  searchEngineUrlTemplate: string;
+
+  lightpandaCdpUrl: string;
+  lightpandaHost: string;
+  lightpandaPort: number;
+  lightpandaAutoStart: boolean;
+  lightpandaAutoStop: boolean;
+
+  browseLinkTimeoutMs: number;
+  queryTimeoutMs: number;
+
+  cacheTtlMs: number;
+  maxHtmlChars: number;
+  maxMarkdownChars: number;
+  maxDocuments: number;
+
+  operationConcurrency: number;
+  browseConcurrency: number;
+
+  researchMaxPages: number;
+  researchMaxHops: number;
+  researchSameDomainOnly: boolean;
+
+  toolExecutionMode: ToolExecutionMode;
+  theme: ThemeName;
+  themeTokens: Record<string, string>;
+}

package/src/types/daemon.ts

@@ -0,0 +1,22 @@
+export interface NdjsonStart {
+  type: "start";
+  pid: number;
+  startedAt: number;
+}
+
+export interface NdjsonProgress {
+  type: "progress";
+  event: Record<string, unknown>;
+}
+
+export interface NdjsonResult {
+  type: "result";
+  result: Record<string, unknown>;
+}
+
+export interface NdjsonError {
+  type: "error";
+  error: string;
+}
+
+export type NdjsonEvent = NdjsonStart | NdjsonProgress | NdjsonResult | NdjsonError;

package/src/types/engine.ts

@@ -0,0 +1,194 @@
+export type ProgressEventType =
+  | "query_start"
+  | "turn_start"
+  | "first_token"
+  | "assistant_delta"
+  | "tool_start"
+  | "tool_end"
+  | "turn_end"
+  | "query_end";
+
+export interface ProgressEventBase {
+  type: ProgressEventType;
+  timestamp?: number;
+}
+
+export interface AssistantDeltaProgressEvent extends ProgressEventBase {
+  type: "assistant_delta";
+  turn: number;
+  message: number;
+  delta: string;
+}
+
+export interface QueryResult {
+  query: string;
+  answer: string;
+  findings?: SearchResultEntry[];
+  citations: string[];
+  durationMs: number;
+  model: string;
+  createdAt?: string;
+}
+
+export interface DeepResearchStartResult {
+  success: true;
+  researchId: string;
+  effort: "fast" | "balanced" | "thorough";
+  status: "pending";
+  message: string;
+}
+
+export interface DeepResearchCheckResult {
+  success?: boolean;
+  status: "pending" | "running" | "completed" | "failed";
+  effort: "fast" | "balanced" | "thorough";
+  report?: string;
+  citations?: string[];
+  costDollars?: number;
+  durationMs?: number;
+  error?: string;
+  message?: string;
+}
+
+export type DeepEffort = "fast" | "balanced" | "thorough";
+
+export type ResearchMode = "general" | "code" | "company" | "similar" | "deep";
+
+export type RetrievalType = "auto" | "fast" | "neural";
+
+export type LivecrawlMode = "never" | "fallback" | "always" | "preferred";
+
+export type SearchCategory =
+  | "company"
+  | "research paper"
+  | "news"
+  | "pdf"
+  | "github"
+  | "tweet"
+  | "personal site"
+  | "people"
+  | "financial report";
+
+export interface RawResearchPolicy {
+  mode?: unknown;
+  type?: unknown;
+  livecrawl?: unknown;
+  category?: unknown;
+  country?: unknown;
+  includeDomains?: unknown;
+  excludeDomains?: unknown;
+  includeText?: unknown;
+  excludeText?: unknown;
+  preferredDomains?: unknown;
+  seedUrls?: unknown;
+  customInstruction?: unknown;
+  instructions?: unknown;
+  instruction?: unknown;
+  numResults?: unknown;
+  maxHops?: unknown;
+  startPublishedDate?: unknown;
+  endPublishedDate?: unknown;
+  sites?: unknown;
+  companyName?: unknown;
+  query?: unknown;
+  [key: string]: unknown;
+}
+
+export interface CountryProfile {
+  label: string;
+  domains: string[];
+  seedUrls: (query: string) => string[];
+}
+
+export interface CategoryProfile {
+  queryHint: string;
+  includeDomains: string[];
+  includeText: string[];
+}
+
+export interface NormalizedResearchPolicy {
+  advanced: boolean;
+  mode: ResearchMode;
+  type: RetrievalType;
+  livecrawl: LivecrawlMode;
+  category: string | null;
+  country: string | null;
+  countryLabel: string | null;
+  includeDomains: string[];
+  excludeDomains: string[];
+  includeText: string[];
+  excludeText: string[];
+  preferredDomains: string[];
+  seedUrls: string[];
+  customInstruction: string | null;
+  requestedResults: number;
+  requestedMaxPages: number | null;
+  requestedMaxHops: number | null;
+  startPublishedDate: string | null;
+  endPublishedDate: string | null;
+  startDate: Date | null;
+  endDate: Date | null;
+}
+
+export interface EngineResearchConfig {
+  researchMaxPages: number;
+  researchMaxHops: number;
+  researchSameDomainOnly: boolean;
+}
+
+export interface ResearchPlan {
+  maxPages: number;
+  maxHops: number;
+  sameDomainOnly: boolean;
+  seedUrls: string[];
+  seedHosts: Set<string>;
+  policy: NormalizedResearchPolicy;
+}
+
+export interface SearchResultEntry {
+  url: string;
+  title?: string;
+  snippet?: string;
+  author?: string;
+  published?: string;
+  content?: string;
+  wordCount?: number;
+  status?: number;
+  cache?: Record<string, unknown>;
+  rank?: number;
+  domain?: string;
+  error?: string;
+}
+
+export interface WebSearchLikeResult {
+  results: SearchResultEntry[];
+  [key: string]: unknown;
+}
+
+export type AgentThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export interface DeepEffortProfile {
+  numResults: number;
+  maxHops: number;
+  refinementPasses: number;
+  minPrimarySources: number;
+  thinkingLevel: AgentThinkingLevel;
+  queryTimeoutMs: number;
+  textMaxCharacters: number;
+  contextMaxCharacters: number;
+}
+
+export interface DeepResearchTaskRecord {
+  researchId: string;
+  status: "pending" | "running" | "completed" | "failed";
+  instructions: string;
+  effort: DeepEffort;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+  durationMs: number | null;
+  report: string | null;
+  citations: string[];
+  error: string | null;
+  costDollars: number;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmitOnError": true,
+    "sourceMap": true,
+    "declaration": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"],
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+}