@folio-agent/handler 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @folio-agent/handler
+
+静的サイト向けポートフォリオ受付チャットボットのチャットハンドラ（Cloudflare Workers 上の LangGraph.js StateGraph）と、ビルド時に知識ファイルを生成する ingest CLI を提供する。知識源はビルド時にシステムプロンプトへ全量同梱する CAG 方式で、検索基盤を持たない。
+
+`@folio-agent/widget` とセットで使う。詳細（アーキテクチャ・設計判断・利用手順全体）はリポジトリの [README](https://github.com/yktsnet/folio-agent#readme) を参照。
+
+## Usage
+
+```bash
+npm install @folio-agent/handler
+
+# ビルド時: 知識ファイルの生成
+npx folio-agent-ingest folio-agent.config.json knowledge.json
+```
+
+```ts
+import { createChatHandler, createGeminiGenerator } from "@folio-agent/handler";
+import knowledgeDoc from "../knowledge.json";
+
+const knowledge = knowledgeDoc.pages.map((p) => `# ${p.url}\n\n${p.text}`).join("\n\n");
+
+export default {
+  fetch: (request: Request, env: { DB: D1Database; GEMINI_API_KEY: string }) =>
+    createChatHandler({
+      db: env.DB,
+      generateAnswer: createGeminiGenerator({ apiKey: env.GEMINI_API_KEY, knowledge }),
+    })(request),
+};
+```
+
+D1 スキーマは `migrations/0001_init.sql` を `wrangler d1 migrations apply` で適用する。

package/dist/chat/gemini.d.ts

@@ -0,0 +1,10 @@
+import type { ChatRoute } from "./types.js";
+export declare function buildSystemPrompt(knowledge: string, route: Exclude<ChatRoute, "rate_limited">, contactUrl?: string): string;
+export interface GeminiGeneratorConfig {
+    apiKey: string;
+    knowledge: string;
+    model?: string;
+    contactUrl?: string;
+}
+export type GenerateAnswerFn = (input: string, route: ChatRoute) => Promise<string>;
+export declare function createGeminiGenerator(config: GeminiGeneratorConfig): GenerateAnswerFn;

package/dist/chat/gemini.js

@@ -0,0 +1,39 @@
+import { GoogleGenAI } from "@google/genai";
+const COMMON_PREAMBLE = "あなたはポートフォリオサイト作者の代理として応対する受付エージェントです。" +
+    "丁寧だが簡潔で自然な口語で話し、「お問い合わせいただきありがとうございます」のような定型の前置き挨拶はしません。" +
+    "回答は原則3〜4文以内にまとめてください。\n\n" +
+    "以下の知識に書かれていることだけから答えてください。書かれていないことは推測・創作せず、" +
+    "「その点はサイトに記載がない」と伝えたうえでContactページを案内してください。" +
+    "用語の正式名称・展開形も、知識に書かれていなければ創作しないでください。\n\n" +
+    "Markdown記法（`**`・`#`・`-`のリストなど）は使わず、プレーンテキストで答えてください。";
+const ROUTE_INSTRUCTIONS = {
+    thoughts: "訪問者は作者の考え方について質問しています。知識の内容に沿って考え方を説明してください。",
+    works: "訪問者はWorks（作品）について質問しています。知識に書かれた内容から解説し、" +
+        "対応するZenn記事へのリンクが知識中にあれば案内してください。",
+    inquiry: "訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページへの問い合わせを案内してください。",
+};
+function buildInquiryInstruction(contactUrl) {
+    if (contactUrl) {
+        return `訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページ（${contactUrl}）への問い合わせを案内してください。`;
+    }
+    return ROUTE_INSTRUCTIONS.inquiry;
+}
+export function buildSystemPrompt(knowledge, route, contactUrl) {
+    const routeInstruction = route === "inquiry" ? buildInquiryInstruction(contactUrl) : ROUTE_INSTRUCTIONS[route];
+    return [COMMON_PREAMBLE, routeInstruction, "---- 知識 ----", knowledge].join("\n\n");
+}
+export function createGeminiGenerator(config) {
+    const client = new GoogleGenAI({ apiKey: config.apiKey });
+    const model = config.model ?? "gemini-3.1-flash-lite";
+    return async (input, route) => {
+        if (route === "rate_limited") {
+            throw new Error("generateAnswer should not be called for a rate-limited route");
+        }
+        const response = await client.models.generateContent({
+            model,
+            contents: input,
+            config: { systemInstruction: buildSystemPrompt(config.knowledge, route, config.contactUrl) },
+        });
+        return response.text ?? "";
+    };
+}

package/dist/chat/graph.d.ts

@@ -0,0 +1,41 @@
+import type { ChatGraphDeps, ChatRoute } from "./types.js";
+export declare function buildChatGraph(deps: ChatGraphDeps): import("@langchain/langgraph").CompiledStateGraph<{
+    input: string;
+    ip: string;
+    route: ChatRoute | undefined;
+    overLimit: boolean;
+    answer: string | undefined;
+}, {
+    input?: string | undefined;
+    ip?: string | undefined;
+    route?: ChatRoute | undefined;
+    overLimit?: boolean | undefined;
+    answer?: string | undefined;
+}, "__start__" | "input_guard" | "route_message" | "generate" | "log", {
+    input: import("@langchain/langgraph").LastValue<string>;
+    ip: import("@langchain/langgraph").LastValue<string>;
+    route: import("@langchain/langgraph").LastValue<ChatRoute | undefined>;
+    overLimit: import("@langchain/langgraph").LastValue<boolean>;
+    answer: import("@langchain/langgraph").LastValue<string | undefined>;
+}, {
+    input: import("@langchain/langgraph").LastValue<string>;
+    ip: import("@langchain/langgraph").LastValue<string>;
+    route: import("@langchain/langgraph").LastValue<ChatRoute | undefined>;
+    overLimit: import("@langchain/langgraph").LastValue<boolean>;
+    answer: import("@langchain/langgraph").LastValue<string | undefined>;
+}, import("@langchain/langgraph").StateDefinition, {
+    input_guard: {
+        overLimit: true;
+        answer: string;
+    } | {
+        overLimit: false;
+        answer?: undefined;
+    };
+    route_message: {
+        route: "thoughts" | "works" | "inquiry";
+    };
+    generate: {
+        answer: string;
+    };
+    log: {};
+}, unknown, unknown, []>;

package/dist/chat/graph.js

@@ -0,0 +1,53 @@
+import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
+import { classifyRoute } from "./route.js";
+const GENERATION_FAILED_MESSAGE = "本日の受付上限に達したか、一時的な不具合が発生しています。恐れ入りますがContactからお問い合わせください。";
+const ChatState = Annotation.Root({
+    input: Annotation(),
+    ip: Annotation(),
+    route: Annotation(),
+    overLimit: Annotation(),
+    answer: Annotation(),
+});
+export function buildChatGraph(deps) {
+    const graph = new StateGraph(ChatState)
+        .addNode("input_guard", async (state) => {
+        const result = await deps.checkRateLimit(state.ip);
+        if (!result.allowed) {
+            const reasonText = result.reason === "daily" ? "本日の上限" : "直近の質問数の上限";
+            return {
+                overLimit: true,
+                answer: `${reasonText}に達しました。お急ぎの場合はContactからお問い合わせください。`,
+            };
+        }
+        return { overLimit: false };
+    })
+        .addNode("route_message", async (state) => ({ route: classifyRoute(state.input) }))
+        .addNode("generate", async (state) => {
+        try {
+            return { answer: await deps.generateAnswer(state.input, state.route) };
+        }
+        catch (error) {
+            console.error("generateAnswer failed", error);
+            return { answer: GENERATION_FAILED_MESSAGE };
+        }
+    })
+        .addNode("log", async (state) => {
+        await deps.logChat({
+            ip: state.ip,
+            route: state.overLimit ? "rate_limited" : state.route,
+            message: state.input,
+            response: state.answer ?? "",
+            overLimit: state.overLimit,
+        });
+        return {};
+    })
+        .addEdge(START, "input_guard")
+        .addConditionalEdges("input_guard", (state) => (state.overLimit ? "log" : "route_message"), {
+        log: "log",
+        route_message: "route_message",
+    })
+        .addEdge("route_message", "generate")
+        .addEdge("generate", "log")
+        .addEdge("log", END);
+    return graph.compile();
+}

package/dist/chat/handler.d.ts

@@ -0,0 +1,8 @@
+import type { GenerateAnswerFn } from "./gemini.js";
+import type { RateLimitConfig } from "./types.js";
+export interface ChatHandlerConfig {
+    db: D1Database;
+    generateAnswer: GenerateAnswerFn;
+    rateLimitConfig?: RateLimitConfig;
+}
+export declare function createChatHandler(config: ChatHandlerConfig): (request: Request) => Promise<Response>;

package/dist/chat/handler.js

@@ -0,0 +1,31 @@
+import { buildChatGraph } from "./graph.js";
+import { logChat } from "./log.js";
+import { checkRateLimit } from "./rate-limit.js";
+import { DEFAULT_RATE_LIMIT_CONFIG } from "./types.js";
+const MAX_INPUT_LENGTH = 1000;
+export function createChatHandler(config) {
+    const graph = buildChatGraph({
+        checkRateLimit: (ip) => checkRateLimit(config.db, ip, new Date(), config.rateLimitConfig ?? DEFAULT_RATE_LIMIT_CONFIG),
+        generateAnswer: config.generateAnswer,
+        logChat: (entry) => logChat(config.db, entry),
+    });
+    return async (request) => {
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return Response.json({ error: "invalid JSON body" }, { status: 400 });
+        }
+        const message = body?.message;
+        if (typeof message !== "string" || message.trim().length === 0) {
+            return Response.json({ error: "message must be a non-empty string" }, { status: 400 });
+        }
+        if (message.length > MAX_INPUT_LENGTH) {
+            return Response.json({ error: `message must be at most ${MAX_INPUT_LENGTH} characters` }, { status: 400 });
+        }
+        const ip = request.headers.get("CF-Connecting-IP") ?? "unknown";
+        const result = await graph.invoke({ input: message, ip });
+        return Response.json({ answer: result.answer, route: result.route ?? "rate_limited" });
+    };
+}

package/dist/chat/log.d.ts

@@ -0,0 +1,2 @@
+import type { ChatLogEntry } from "./types.js";
+export declare function logChat(db: D1Database, entry: ChatLogEntry, now?: Date): Promise<void>;

package/dist/chat/log.js

@@ -0,0 +1,6 @@
+export async function logChat(db, entry, now = new Date()) {
+    await db
+        .prepare("INSERT INTO chat_logs (created_at, ip, route, message, response, over_limit) VALUES (?, ?, ?, ?, ?, ?)")
+        .bind(now.toISOString(), entry.ip, entry.route, entry.message, entry.response, entry.overLimit ? 1 : 0)
+        .run();
+}

package/dist/chat/rate-limit.d.ts

@@ -0,0 +1,2 @@
+import type { RateLimitConfig, RateLimitResult } from "./types.js";
+export declare function checkRateLimit(db: D1Database, ip: string, now?: Date, config?: RateLimitConfig): Promise<RateLimitResult>;

package/dist/chat/rate-limit.js

@@ -0,0 +1,23 @@
+import { DEFAULT_RATE_LIMIT_CONFIG } from "./types.js";
+const MINUTE_MS = 60_000;
+const DAY_MS = 24 * 60 * MINUTE_MS;
+async function countSince(db, ip, sinceIso) {
+    const row = await db
+        .prepare("SELECT COUNT(*) as count FROM chat_logs WHERE ip = ? AND created_at >= ? AND over_limit = 0")
+        .bind(ip, sinceIso)
+        .first();
+    return row?.count ?? 0;
+}
+export async function checkRateLimit(db, ip, now = new Date(), config = DEFAULT_RATE_LIMIT_CONFIG) {
+    const shortWindowStart = new Date(now.getTime() - config.shortWindowMinutes * MINUTE_MS).toISOString();
+    const shortCount = await countSince(db, ip, shortWindowStart);
+    if (shortCount >= config.shortWindowMax) {
+        return { allowed: false, reason: "short_window" };
+    }
+    const dailyStart = new Date(now.getTime() - DAY_MS).toISOString();
+    const dailyCount = await countSince(db, ip, dailyStart);
+    if (dailyCount >= config.dailyMax) {
+        return { allowed: false, reason: "daily" };
+    }
+    return { allowed: true };
+}

package/dist/chat/route.d.ts

@@ -0,0 +1,2 @@
+import type { ChatRoute } from "./types.js";
+export declare function classifyRoute(input: string): Exclude<ChatRoute, "rate_limited">;

package/dist/chat/route.js

@@ -0,0 +1,12 @@
+const INQUIRY_KEYWORDS = ["依頼", "相談", "見積", "発注", "案件", "お願いしたい"];
+const WORKS_KEYWORDS = ["works", "作品", "実績", "zenn", "記事"];
+export function classifyRoute(input) {
+    const lower = input.toLowerCase();
+    if (INQUIRY_KEYWORDS.some((keyword) => input.includes(keyword))) {
+        return "inquiry";
+    }
+    if (WORKS_KEYWORDS.some((keyword) => lower.includes(keyword))) {
+        return "works";
+    }
+    return "thoughts";
+}

package/dist/chat/types.d.ts

@@ -0,0 +1,24 @@
+export type ChatRoute = "thoughts" | "works" | "inquiry" | "rate_limited";
+export interface RateLimitConfig {
+    shortWindowMinutes: number;
+    shortWindowMax: number;
+    dailyMax: number;
+}
+export declare const DEFAULT_RATE_LIMIT_CONFIG: RateLimitConfig;
+export type RateLimitReason = "short_window" | "daily";
+export interface RateLimitResult {
+    allowed: boolean;
+    reason?: RateLimitReason;
+}
+export interface ChatLogEntry {
+    ip: string;
+    route: ChatRoute;
+    message: string;
+    response: string;
+    overLimit: boolean;
+}
+export interface ChatGraphDeps {
+    checkRateLimit: (ip: string) => Promise<RateLimitResult>;
+    generateAnswer: (input: string, route: ChatRoute) => Promise<string>;
+    logChat: (entry: ChatLogEntry) => Promise<void>;
+}

package/dist/chat/types.js

@@ -0,0 +1,5 @@
+export const DEFAULT_RATE_LIMIT_CONFIG = {
+    shortWindowMinutes: 10,
+    shortWindowMax: 3,
+    dailyMax: 10,
+};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { generateKnowledge } from "./ingest/generate.js";
+export { createUrlMatcher } from "./ingest/glob.js";
+export { htmlToText } from "./ingest/html-to-text.js";
+export type { IngestConfig, KnowledgeDocument, KnowledgePage, KnowledgeSource, ZennIngestConfig, } from "./ingest/types.js";
+export { createChatHandler } from "./chat/handler.js";
+export type { ChatHandlerConfig } from "./chat/handler.js";
+export { buildChatGraph } from "./chat/graph.js";
+export { checkRateLimit } from "./chat/rate-limit.js";
+export { createGeminiGenerator, buildSystemPrompt } from "./chat/gemini.js";
+export type { GenerateAnswerFn, GeminiGeneratorConfig } from "./chat/gemini.js";
+export { classifyRoute } from "./chat/route.js";
+export { logChat } from "./chat/log.js";
+export type { ChatRoute, ChatGraphDeps, ChatLogEntry, RateLimitConfig, RateLimitResult, RateLimitReason, } from "./chat/types.js";
+export { DEFAULT_RATE_LIMIT_CONFIG } from "./chat/types.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { generateKnowledge } from "./ingest/generate.js";
+export { createUrlMatcher } from "./ingest/glob.js";
+export { htmlToText } from "./ingest/html-to-text.js";
+export { createChatHandler } from "./chat/handler.js";
+export { buildChatGraph } from "./chat/graph.js";
+export { checkRateLimit } from "./chat/rate-limit.js";
+export { createGeminiGenerator, buildSystemPrompt } from "./chat/gemini.js";
+export { classifyRoute } from "./chat/route.js";
+export { logChat } from "./chat/log.js";
+export { DEFAULT_RATE_LIMIT_CONFIG } from "./chat/types.js";

package/dist/ingest/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/ingest/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { generateKnowledge } from "./generate.js";
+async function main() {
+    const configPath = process.argv[2];
+    const outputPath = process.argv[3];
+    if (!configPath || !outputPath) {
+        console.error("usage: folio-agent-ingest <config.json> <output.json>");
+        process.exitCode = 1;
+        return;
+    }
+    const config = JSON.parse(await readFile(configPath, "utf-8"));
+    const knowledge = await generateKnowledge(config);
+    await writeFile(outputPath, JSON.stringify(knowledge, null, 2));
+    console.log(`wrote ${knowledge.pages.length} page(s), ~${knowledge.estimatedTokens} tokens -> ${outputPath}`);
+    for (const warning of knowledge.warnings) {
+        console.warn(`warning: ${warning}`);
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/ingest/file-to-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Maps a file path relative to a content root (dist/ or knowledge/) to the
+ * URL path it represents, e.g. "works/foo/index.html" -> "/works/foo",
+ * "about.html" -> "/about", "index.html" -> "/".
+ */
+export declare function fileToUrlPath(relPath: string): string;

package/dist/ingest/file-to-url.js

@@ -0,0 +1,13 @@
+import { sep } from "node:path";
+/**
+ * Maps a file path relative to a content root (dist/ or knowledge/) to the
+ * URL path it represents, e.g. "works/foo/index.html" -> "/works/foo",
+ * "about.html" -> "/about", "index.html" -> "/".
+ */
+export function fileToUrlPath(relPath) {
+    const posixPath = relPath.split(sep).join("/");
+    const withoutExt = posixPath.replace(/\.[^/.]+$/, "");
+    const withoutIndex = withoutExt.replace(/(^|\/)index$/, "");
+    const urlPath = `/${withoutIndex}`.replace(/\/+/g, "/");
+    return urlPath === "" ? "/" : urlPath;
+}

package/dist/ingest/generate.d.ts

@@ -0,0 +1,2 @@
+import type { IngestConfig, KnowledgeDocument } from "./types.js";
+export declare function generateKnowledge(config: IngestConfig): Promise<KnowledgeDocument>;

package/dist/ingest/generate.js

@@ -0,0 +1,39 @@
+import { createUrlMatcher } from "./glob.js";
+import { htmlToText } from "./html-to-text.js";
+import { readTextFile, scanDist, scanKnowledgeDir } from "./scan-dist.js";
+import { DEFAULT_TOKEN_WARNING_THRESHOLD, estimateTokens } from "./token-count.js";
+import { scanZennArticles } from "./zenn.js";
+export async function generateKnowledge(config) {
+    const matchesUrl = createUrlMatcher(config);
+    const pages = [];
+    const distFiles = await scanDist(config.distDir);
+    for (const file of distFiles.filter((f) => matchesUrl(f.urlPath))) {
+        const html = await readTextFile(file.absolutePath);
+        const { title, text } = htmlToText(html);
+        pages.push({ url: file.urlPath, source: "dist", title, text });
+    }
+    if (config.knowledgeDir) {
+        const knowledgeFiles = await scanKnowledgeDir(config.knowledgeDir);
+        for (const file of knowledgeFiles) {
+            const text = (await readTextFile(file.absolutePath)).trim();
+            pages.push({ url: file.urlPath, source: "knowledge", title: file.urlPath, text });
+        }
+    }
+    if (config.zenn) {
+        pages.push(...(await scanZennArticles(config.zenn)));
+    }
+    pages.sort((a, b) => a.url.localeCompare(b.url));
+    const estimatedTokens = estimateTokens(pages.map((p) => p.text).join("\n"));
+    const threshold = config.tokenWarningThreshold ?? DEFAULT_TOKEN_WARNING_THRESHOLD;
+    const warnings = [];
+    if (estimatedTokens > threshold) {
+        warnings.push(`estimated knowledge size (${estimatedTokens} tokens) exceeds the warning threshold (${threshold}). ` +
+            "Consider narrowing include globs, or switching to a RAG-based approach.");
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        pages,
+        estimatedTokens,
+        warnings,
+    };
+}

package/dist/ingest/glob.d.ts

@@ -0,0 +1,2 @@
+import type { IngestConfig } from "./types.js";
+export declare function createUrlMatcher(config: Pick<IngestConfig, "include" | "exclude">): (urlPath: string) => boolean;

package/dist/ingest/glob.js

@@ -0,0 +1,6 @@
+import picomatch from "picomatch";
+export function createUrlMatcher(config) {
+    const isIncluded = picomatch(config.include);
+    const isExcluded = config.exclude && config.exclude.length > 0 ? picomatch(config.exclude) : () => false;
+    return (urlPath) => isIncluded(urlPath) && !isExcluded(urlPath);
+}

package/dist/ingest/html-to-text.d.ts

@@ -0,0 +1,5 @@
+export interface ExtractedHtml {
+    title: string;
+    text: string;
+}
+export declare function htmlToText(html: string): ExtractedHtml;

package/dist/ingest/html-to-text.js

@@ -0,0 +1,19 @@
+import { parse } from "node-html-parser";
+const NON_CONTENT_TAGS = ["script", "style", "noscript", "template"];
+export function htmlToText(html) {
+    const root = parse(html);
+    for (const tag of NON_CONTENT_TAGS) {
+        for (const el of root.querySelectorAll(tag)) {
+            el.remove();
+        }
+    }
+    const title = root.querySelector("title")?.text.trim() ?? "";
+    const bodyText = root.querySelector("body")?.text ?? root.text;
+    const text = bodyText
+        .replace(/[ \t]+/g, " ")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join("\n");
+    return { title, text };
+}

package/dist/ingest/scan-dist.d.ts

@@ -0,0 +1,7 @@
+export interface ScannedFile {
+    urlPath: string;
+    absolutePath: string;
+}
+export declare function scanDist(distDir: string): Promise<ScannedFile[]>;
+export declare function scanKnowledgeDir(knowledgeDir: string): Promise<ScannedFile[]>;
+export declare function readTextFile(absolutePath: string): Promise<string>;

package/dist/ingest/scan-dist.js

@@ -0,0 +1,38 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileToUrlPath } from "./file-to-url.js";
+async function walk(dir, root) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walk(fullPath, root)));
+        }
+        else {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+export async function scanDist(distDir) {
+    const allFiles = await walk(distDir, distDir);
+    return allFiles
+        .filter((absolutePath) => absolutePath.endsWith(".html"))
+        .map((absolutePath) => ({
+        urlPath: fileToUrlPath(relative(distDir, absolutePath)),
+        absolutePath,
+    }));
+}
+export async function scanKnowledgeDir(knowledgeDir) {
+    const allFiles = await walk(knowledgeDir, knowledgeDir);
+    return allFiles
+        .filter((absolutePath) => absolutePath.endsWith(".md"))
+        .map((absolutePath) => ({
+        urlPath: fileToUrlPath(relative(knowledgeDir, absolutePath)),
+        absolutePath,
+    }));
+}
+export async function readTextFile(absolutePath) {
+    return readFile(absolutePath, "utf-8");
+}

package/dist/ingest/token-count.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_TOKEN_WARNING_THRESHOLD = 100000;
+/** Rough token estimate (chars / 4), good enough for a build-time budget warning. */
+export declare function estimateTokens(text: string): number;

package/dist/ingest/token-count.js

@@ -0,0 +1,6 @@
+const CHARS_PER_TOKEN_ESTIMATE = 4;
+export const DEFAULT_TOKEN_WARNING_THRESHOLD = 100_000;
+/** Rough token estimate (chars / 4), good enough for a build-time budget warning. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE);
+}

package/dist/ingest/types.d.ts

@@ -0,0 +1,33 @@
+export interface IngestConfig {
+    /** Absolute or cwd-relative path to the built site (e.g. "dist"). */
+    distDir: string;
+    /** URL path globs to include, e.g. ["/", "/works/**", "/about"]. */
+    include: string[];
+    /** URL path globs to exclude, e.g. ["/works/draft-*"]. */
+    exclude?: string[];
+    /** Directory mirroring URL paths with supplementary Markdown, e.g. "knowledge". */
+    knowledgeDir?: string;
+    /** Zenn CLI articles/ ingestion. Omit to skip Zenn articles entirely. */
+    zenn?: ZennIngestConfig;
+    /** Token threshold above which the CLI warns that CAG may no longer fit. */
+    tokenWarningThreshold?: number;
+}
+export interface ZennIngestConfig {
+    /** Local path (absolute or cwd-relative) to the Zenn CLI articles/ directory. */
+    articlesDir: string;
+    /** Base used to build public article URLs, e.g. "https://zenn.dev/username/articles". No trailing slash. */
+    baseUrl: string;
+}
+export type KnowledgeSource = "dist" | "knowledge" | "zenn";
+export interface KnowledgePage {
+    url: string;
+    source: KnowledgeSource;
+    title: string;
+    text: string;
+}
+export interface KnowledgeDocument {
+    generatedAt: string;
+    pages: KnowledgePage[];
+    estimatedTokens: number;
+    warnings: string[];
+}

package/dist/ingest/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ingest/zenn.d.ts

@@ -0,0 +1,7 @@
+import type { KnowledgePage, ZennIngestConfig } from "./types.js";
+/**
+ * Reads published Zenn CLI articles from a local articles/ directory (no
+ * subdirectories expected) and maps them to KnowledgePage entries. Drafts
+ * (published: false) and files without a published field are excluded.
+ */
+export declare function scanZennArticles(config: ZennIngestConfig): Promise<KnowledgePage[]>;

package/dist/ingest/zenn.js

@@ -0,0 +1,39 @@
+import { readdir } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { readTextFile } from "./scan-dist.js";
+const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?/;
+const TITLE_PATTERN = /^title:\s*"?(.*?)"?\s*$/m;
+const PUBLISHED_PATTERN = /^published:\s*(true|false)\s*$/m;
+/**
+ * Reads published Zenn CLI articles from a local articles/ directory (no
+ * subdirectories expected) and maps them to KnowledgePage entries. Drafts
+ * (published: false) and files without a published field are excluded.
+ */
+export async function scanZennArticles(config) {
+    const entries = await readdir(config.articlesDir, { withFileTypes: true });
+    const pages = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const absolutePath = join(config.articlesDir, entry.name);
+        const content = await readTextFile(absolutePath);
+        const frontmatterMatch = content.match(FRONTMATTER_PATTERN);
+        if (!frontmatterMatch)
+            continue;
+        const frontmatter = frontmatterMatch[1];
+        const publishedMatch = frontmatter.match(PUBLISHED_PATTERN);
+        if (publishedMatch?.[1] !== "true")
+            continue;
+        const slug = basename(entry.name, extname(entry.name));
+        const titleMatch = frontmatter.match(TITLE_PATTERN);
+        const title = titleMatch ? titleMatch[1] : slug;
+        const text = content.slice(frontmatterMatch[0].length).trim();
+        pages.push({
+            url: `${config.baseUrl}/${slug}`,
+            source: "zenn",
+            title,
+            text,
+        });
+    }
+    return pages;
+}

package/migrations/0001_init.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS chat_logs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  created_at TEXT NOT NULL,
+  ip TEXT NOT NULL,
+  route TEXT NOT NULL,
+  message TEXT NOT NULL,
+  response TEXT NOT NULL,
+  over_limit INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_chat_logs_ip_created_at ON chat_logs (ip, created_at);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@folio-agent/handler",
+  "version": "0.1.0",
+  "description": "Chat handler (LangGraph.js on Cloudflare Workers) + knowledge ingestion CLI",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "bin": {
+    "folio-agent-ingest": "dist/ingest/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yktsnet/folio-agent.git",
+    "directory": "packages/handler"
+  },
+  "homepage": "https://github.com/yktsnet/folio-agent#readme",
+  "bugs": {
+    "url": "https://github.com/yktsnet/folio-agent/issues"
+  },
+  "keywords": [
+    "chatbot",
+    "cloudflare-workers",
+    "langgraph",
+    "gemini",
+    "cag"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@google/genai": "^2.10.0",
+    "@langchain/langgraph": "^1.4.7",
+    "node-html-parser": "^8.0.4",
+    "picomatch": "^4.0.5"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260705.1",
+    "@types/picomatch": "^4.0.2",
+    "wrangler": "^4.107.0"
+  }
+}