@silicajs/assistant 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @silicajs/assistant
+
+Optional AI assistant for [Silica](https://github.com/agdevhq/silica) knowledge sites.
+
+The assistant answers reader questions from the site's original markdown files, cites the source pages it used, and supports multi-turn follow-ups. It is built on [core-ai](https://core-ai.dev) for provider-agnostic model access and uses an in-process, read-only shell sandbox ([just-bash](https://github.com/vercel-labs/just-bash)) for markdown exploration (`ls`, `grep`, `cat`, …).
+
+## Usage
+
+Install alongside the provider package for your model:
+
+```bash
+npm install @silicajs/assistant @core-ai/openai
+```
+
+Enable it in `silica.config.ts`:
+
+```typescript
+assistant: {
+  provider: "openai",
+  model: "gpt-5-mini",
+},
+```
+
+and set the provider API key (e.g. `OPENAI_API_KEY`) plus a server-only `SILICA_ASSISTANT_SECRET` in your environment. The Silica CLI generates the `/api/assistant` route and passes the assistant UI to the active theme.
+
+For providers without a Silica preset, configure the core-ai package and factory explicitly:
+
+```typescript
+assistant: {
+  provider: {
+    package: "@acme/core-ai-provider",
+    factory: "createAcme",
+    env: { baseURL: "ACME_BASE_URL" },
+    secrets: { apiKey: "ACME_API_KEY" },
+    options: { region: "eu" },
+  },
+  model: "acme-chat",
+},
+```
+
+Generated assistant routes include a 10 requests/minute rate limit keyed by `x-forwarded-for`. In `silica.config.ts`, set `assistant.rateLimit.trustedProxyHeaders` if your deployment proxy uses a different client-IP header, and only include headers your proxy sets or overwrites.
+
+## Entry points
+
+| Export                       | Contents                                                                     |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `@silicajs/assistant`        | Shared types (citations, transcript, stream events)                          |
+| `@silicajs/assistant/ui`     | Client components: `AssistantProvider`, `AssistantTrigger`, `AssistantPanel` |
+| `@silicajs/assistant/server` | Framework-agnostic runtime: handler, agent loop, sandbox, citations          |
+| `@silicajs/assistant/next`   | Route glue for the generated Silica Next.js app                              |
+
+See the [Silica docs](https://github.com/agdevhq/silica) for the full feature documentation.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { AssistantCitation, AssistantCitationResolver, AssistantRequest, AssistantSignedTranscriptMessage, AssistantSiteContext, AssistantStreamEvent, AssistantTranscriptMessage, AssistantUserTranscriptMessage, AssistantWikiLinkResolver } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/next.d.ts

@@ -0,0 +1,48 @@
+import { ChatModel } from '@core-ai/core-ai';
+import { ResolvedSilicaAssistantConfig } from '@silicajs/core/runtime';
+import { AssistantProviderModule } from './server/provider.js';
+
+type CreateChatModelOptions = {
+    assistant: ResolvedSilicaAssistantConfig;
+};
+type AssistantRateLimitOptions = {
+    /** Maximum assistant requests allowed per client in the configured window. */
+    maxRequests?: number;
+    /** Window size in milliseconds. Defaults to one minute. */
+    windowMs?: number;
+    /**
+     * Headers set or overwritten by the deployment proxy and used to derive the
+     * caller IP for the built-in rate limit. Defaults to `x-forwarded-for`.
+     */
+    trustedProxyHeaders?: readonly string[];
+    /**
+     * Custom bucket key. Prefer this for authenticated routes where a stable
+     * session or user id is available.
+     */
+    key?: (request: Request) => string | Promise<string>;
+};
+type AssistantRouteOptions = {
+    /**
+     * Provider package module imported by the generated route. Keeping this
+     * import static lets Next trace and bundle optional provider packages.
+     */
+    providerModule?: AssistantProviderModule;
+    /**
+     * Instantiates the configured chat model. Defaults to resolving the factory
+     * from `providerModule` and the resolved Silica assistant config.
+     */
+    createChatModel?: (options: CreateChatModelOptions) => ChatModel | Promise<ChatModel>;
+    /**
+     * Basic per-client request cap for assistant routes. Pass `false` only when
+     * another quota guard protects this endpoint.
+     */
+    rateLimit?: AssistantRateLimitOptions | false;
+};
+/**
+ * `POST` handler for the generated `/api/assistant` route. Reads the AI
+ * configuration and generated runtime content from the Silica build output
+ * and answers with a streamed, cited response.
+ */
+declare function createAssistantRouteHandler(options?: AssistantRouteOptions): (request: Request) => Promise<Response>;
+
+export { type AssistantRateLimitOptions, type AssistantRouteOptions, type CreateChatModelOptions, createAssistantRouteHandler };

package/dist/next.js

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  slugToHref
+} from "@silicajs/core/runtime";
+import {
+  getConfig,
+  getPage,
+  getPageBySourcePath,
+  getProjectRoot,
+  resolveWikiLinkFromDb
+} from "@silicajs/next/server-data";
+import {
+  AssistantUnavailableError,
+  createChatModelFromConfig,
+  createAssistantHandler
+} from "./server/index.js";
+const ASSISTANT_SECRET_ENV = "SILICA_ASSISTANT_SECRET";
+const DEFAULT_RATE_LIMIT_MAX_REQUESTS = 10;
+const DEFAULT_RATE_LIMIT_WINDOW_MS = 6e4;
+const DEFAULT_TRUSTED_PROXY_HEADERS = ["x-forwarded-for"];
+const MAX_RATE_LIMIT_BUCKETS = 1e4;
+const MAX_HOME_PAGE_EXCERPT_CHARS = 2e3;
+const rateLimitBuckets = /* @__PURE__ */ new Map();
+function createAssistantRouteHandler(options = {}) {
+  return createAssistantHandler({
+    authorizeRequest: async (request) => {
+      const assistantRateLimit = options.rateLimit !== void 0 ? options.rateLimit : getConfig().assistant?.rateLimit;
+      if (assistantRateLimit === false) return void 0;
+      return createRateLimitGuard(assistantRateLimit)(request);
+    },
+    resolve: async (requestContext) => {
+      const config = getConfig();
+      const assistant = config.assistant;
+      if (!assistant) {
+        throw new AssistantUnavailableError(
+          "The AI assistant is not enabled for this site."
+        );
+      }
+      const transcriptSigningSecret = process.env[ASSISTANT_SECRET_ENV];
+      if (!transcriptSigningSecret) {
+        throw new AssistantUnavailableError(
+          `The AI assistant is not configured: set the ${ASSISTANT_SECRET_ENV} environment variable.`
+        );
+      }
+      const createChatModel = options.createChatModel ?? ((modelOptions) => {
+        if (!options.providerModule) {
+          throw new AssistantUnavailableError(
+            "The AI assistant provider module is not configured."
+          );
+        }
+        return createChatModelFromConfig(
+          modelOptions.assistant,
+          options.providerModule
+        );
+      });
+      return {
+        model: await createChatModel({ assistant }),
+        site: loadSiteContext(config, requestContext),
+        transcriptSigningSecret
+      };
+    }
+  });
+}
+function createRateLimitGuard(options) {
+  const maxRequests = Math.max(
+    1,
+    options?.maxRequests ?? DEFAULT_RATE_LIMIT_MAX_REQUESTS
+  );
+  const windowMs = Math.max(
+    1,
+    options?.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS
+  );
+  const trustedProxyHeaders = options?.trustedProxyHeaders ?? DEFAULT_TRUSTED_PROXY_HEADERS;
+  return async (request) => {
+    const now = Date.now();
+    const key = await rateLimitKey(request, {
+      key: options?.key,
+      trustedProxyHeaders
+    });
+    const bucket = rateLimitBuckets.get(key);
+    if (!bucket || bucket.resetAt <= now) {
+      rateLimitBuckets.set(key, { count: 1, resetAt: now + windowMs });
+      pruneExpiredBuckets(now);
+      return void 0;
+    }
+    bucket.count += 1;
+    if (bucket.count <= maxRequests) return void 0;
+    return Response.json(
+      { error: "Too many assistant requests. Please try again shortly." },
+      {
+        status: 429,
+        headers: {
+          "retry-after": String(Math.ceil((bucket.resetAt - now) / 1e3))
+        }
+      }
+    );
+  };
+}
+async function rateLimitKey(request, options) {
+  const customKey = await options.key?.(request);
+  if (customKey?.trim()) return customKey.trim();
+  for (const header of options.trustedProxyHeaders ?? []) {
+    const value = rateLimitHeaderValue(header, request.headers.get(header));
+    if (value) return value;
+  }
+  return "anonymous";
+}
+function rateLimitHeaderValue(header, value) {
+  if (!value) return void 0;
+  const normalizedHeader = header.toLowerCase();
+  const candidate = normalizedHeader === "x-forwarded-for" ? value.split(",")[0] : value;
+  return candidate?.trim() || void 0;
+}
+function pruneExpiredBuckets(now) {
+  if (rateLimitBuckets.size <= MAX_RATE_LIMIT_BUCKETS) return;
+  for (const [key, bucket] of rateLimitBuckets) {
+    if (bucket.resetAt <= now) rateLimitBuckets.delete(key);
+  }
+}
+function loadSiteContext(config, requestContext) {
+  const contentRoot = path.join(getProjectRoot(), ".silica/content");
+  const homePage = loadHomePageContext(contentRoot);
+  const currentPage = loadCurrentPageContext(
+    contentRoot,
+    requestContext,
+    homePage?.sourcePath
+  );
+  return {
+    siteTitle: config.title,
+    siteDescription: config.description,
+    homePage,
+    currentPage,
+    contentRoot,
+    resolveCitation: (sourcePath) => {
+      const entry = getPageBySourcePath(sourcePath);
+      if (!entry) return void 0;
+      return {
+        slug: entry.slug,
+        title: entry.title,
+        href: slugToHref(entry.slug),
+        sourcePath: entry.sourcePath
+      };
+    },
+    resolveWikiLink: (currentSourcePath, target) => {
+      const currentEntry = getPageBySourcePath(currentSourcePath) ?? (homePage ? getPageBySourcePath(homePage.sourcePath) : void 0) ?? getPage("index");
+      if (!currentEntry) return void 0;
+      const resolvedSlug = resolveWikiLinkFromDb(
+        currentEntry.slug,
+        target,
+        config.wikilinks.strategy,
+        config.ordering
+      );
+      if (!resolvedSlug) return void 0;
+      const entry = getPage(resolvedSlug);
+      if (!entry) return void 0;
+      return {
+        slug: entry.slug,
+        title: entry.title,
+        href: slugToHref(entry.slug),
+        sourcePath: entry.sourcePath
+      };
+    }
+  };
+}
+function loadHomePageContext(contentRoot) {
+  const homePage = getPage("index");
+  if (!homePage) return void 0;
+  try {
+    const raw = fs.readFileSync(path.join(contentRoot, homePage.sourcePath), {
+      encoding: "utf8"
+    });
+    const excerpt = truncateHomePageExcerpt(stripFrontmatter(raw).trim());
+    if (!excerpt) return void 0;
+    return {
+      title: homePage.title,
+      sourcePath: homePage.sourcePath,
+      excerpt
+    };
+  } catch {
+    return void 0;
+  }
+}
+function loadCurrentPageContext(contentRoot, requestContext, fallbackSourcePath) {
+  const sourcePath = requestContext.currentSourcePath ?? sourcePathForSlug(requestContext.currentSlug) ?? fallbackSourcePath;
+  if (!sourcePath) return void 0;
+  const entry = getPageBySourcePath(sourcePath);
+  if (!entry) return void 0;
+  try {
+    const raw = fs.readFileSync(path.join(contentRoot, entry.sourcePath), {
+      encoding: "utf8"
+    });
+    const excerpt = truncateHomePageExcerpt(stripFrontmatter(raw).trim());
+    return {
+      title: entry.title,
+      slug: entry.slug,
+      sourcePath: entry.sourcePath,
+      excerpt
+    };
+  } catch {
+    return void 0;
+  }
+}
+function sourcePathForSlug(slug) {
+  if (!slug) return void 0;
+  return getPage(slug)?.sourcePath;
+}
+function stripFrontmatter(markdown) {
+  return markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+}
+function truncateHomePageExcerpt(markdown) {
+  const normalized = markdown.replace(/\s+/g, " ").trim();
+  if (normalized.length <= MAX_HOME_PAGE_EXCERPT_CHARS) return normalized;
+  return `${normalized.slice(0, MAX_HOME_PAGE_EXCERPT_CHARS).trimEnd()}...`;
+}
+export {
+  createAssistantRouteHandler
+};
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/next.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { ChatModel } from \"@core-ai/core-ai\";\nimport {\n  slugToHref,\n  type ResolvedSilicaAssistantConfig,\n  type ResolvedSilicaConfig,\n} from \"@silicajs/core/runtime\";\nimport {\n  getConfig,\n  getPage,\n  getPageBySourcePath,\n  getProjectRoot,\n  resolveWikiLinkFromDb,\n} from \"@silicajs/next/server-data\";\nimport {\n  AssistantUnavailableError,\n  type AssistantProviderModule,\n  createChatModelFromConfig,\n  createAssistantHandler,\n  type AssistantRequestContext,\n  type AssistantRuntime,\n} from \"./server/index.js\";\nimport type { AssistantSiteContext } from \"./types.js\";\n\nconst ASSISTANT_SECRET_ENV = \"SILICA_ASSISTANT_SECRET\";\nconst DEFAULT_RATE_LIMIT_MAX_REQUESTS = 10;\nconst DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;\nconst DEFAULT_TRUSTED_PROXY_HEADERS = [\"x-forwarded-for\"] as const;\nconst MAX_RATE_LIMIT_BUCKETS = 10_000;\nconst MAX_HOME_PAGE_EXCERPT_CHARS = 2_000;\n\nconst rateLimitBuckets = new Map<string, { count: number; resetAt: number }>();\n\nexport type CreateChatModelOptions = {\n  assistant: ResolvedSilicaAssistantConfig;\n};\n\nexport type AssistantRateLimitOptions = {\n  /** Maximum assistant requests allowed per client in the configured window. */\n  maxRequests?: number;\n  /** Window size in milliseconds. Defaults to one minute. */\n  windowMs?: number;\n  /**\n   * Headers set or overwritten by the deployment proxy and used to derive the\n   * caller IP for the built-in rate limit. Defaults to `x-forwarded-for`.\n   */\n  trustedProxyHeaders?: readonly string[];\n  /**\n   * Custom bucket key. Prefer this for authenticated routes where a stable\n   * session or user id is available.\n   */\n  key?: (request: Request) => string | Promise<string>;\n};\n\nexport type AssistantRouteOptions = {\n  /**\n   * Provider package module imported by the generated route. Keeping this\n   * import static lets Next trace and bundle optional provider packages.\n   */\n  providerModule?: AssistantProviderModule;\n  /**\n   * Instantiates the configured chat model. Defaults to resolving the factory\n   * from `providerModule` and the resolved Silica assistant config.\n   */\n  createChatModel?: (\n    options: CreateChatModelOptions,\n  ) => ChatModel | Promise<ChatModel>;\n  /**\n   * Basic per-client request cap for assistant routes. Pass `false` only when\n   * another quota guard protects this endpoint.\n   */\n  rateLimit?: AssistantRateLimitOptions | false;\n};\n\n/**\n * `POST` handler for the generated `/api/assistant` route. Reads the AI\n * configuration and generated runtime content from the Silica build output\n * and answers with a streamed, cited response.\n */\nexport function createAssistantRouteHandler(\n  options: AssistantRouteOptions = {},\n): (request: Request) => Promise<Response> {\n  return createAssistantHandler({\n    authorizeRequest: async (request) => {\n      const assistantRateLimit =\n        options.rateLimit !== undefined\n          ? options.rateLimit\n          : getConfig().assistant?.rateLimit;\n      if (assistantRateLimit === false) return undefined;\n      return createRateLimitGuard(assistantRateLimit)(request);\n    },\n    resolve: async (requestContext): Promise<AssistantRuntime> => {\n      const config = getConfig();\n      const assistant = config.assistant;\n      if (!assistant) {\n        throw new AssistantUnavailableError(\n          \"The AI assistant is not enabled for this site.\",\n        );\n      }\n\n      const transcriptSigningSecret = process.env[ASSISTANT_SECRET_ENV];\n      if (!transcriptSigningSecret) {\n        throw new AssistantUnavailableError(\n          `The AI assistant is not configured: set the ${ASSISTANT_SECRET_ENV} environment variable.`,\n        );\n      }\n      const createChatModel =\n        options.createChatModel ??\n        ((modelOptions: CreateChatModelOptions) => {\n          if (!options.providerModule) {\n            throw new AssistantUnavailableError(\n              \"The AI assistant provider module is not configured.\",\n            );\n          }\n          return createChatModelFromConfig(\n            modelOptions.assistant,\n            options.providerModule,\n          );\n        });\n\n      return {\n        model: await createChatModel({ assistant }),\n        site: loadSiteContext(config, requestContext),\n        transcriptSigningSecret,\n      };\n    },\n  });\n}\n\nfunction createRateLimitGuard(\n  options: AssistantRateLimitOptions | undefined,\n): (request: Request) => Promise<Response | undefined> {\n  const maxRequests = Math.max(\n    1,\n    options?.maxRequests ?? DEFAULT_RATE_LIMIT_MAX_REQUESTS,\n  );\n  const windowMs = Math.max(\n    1,\n    options?.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS,\n  );\n  const trustedProxyHeaders =\n    options?.trustedProxyHeaders ?? DEFAULT_TRUSTED_PROXY_HEADERS;\n\n  return async (request) => {\n    const now = Date.now();\n    const key = await rateLimitKey(request, {\n      key: options?.key,\n      trustedProxyHeaders,\n    });\n    const bucket = rateLimitBuckets.get(key);\n    if (!bucket || bucket.resetAt <= now) {\n      rateLimitBuckets.set(key, { count: 1, resetAt: now + windowMs });\n      pruneExpiredBuckets(now);\n      return undefined;\n    }\n\n    bucket.count += 1;\n    if (bucket.count <= maxRequests) return undefined;\n\n    return Response.json(\n      { error: \"Too many assistant requests. Please try again shortly.\" },\n      {\n        status: 429,\n        headers: {\n          \"retry-after\": String(Math.ceil((bucket.resetAt - now) / 1000)),\n        },\n      },\n    );\n  };\n}\n\nasync function rateLimitKey(\n  request: Request,\n  options: Pick<AssistantRateLimitOptions, \"key\" | \"trustedProxyHeaders\">,\n): Promise<string> {\n  const customKey = await options.key?.(request);\n  if (customKey?.trim()) return customKey.trim();\n\n  for (const header of options.trustedProxyHeaders ?? []) {\n    const value = rateLimitHeaderValue(header, request.headers.get(header));\n    if (value) return value;\n  }\n\n  return \"anonymous\";\n}\n\nfunction rateLimitHeaderValue(\n  header: string,\n  value: string | null,\n): string | undefined {\n  if (!value) return undefined;\n  const normalizedHeader = header.toLowerCase();\n  const candidate =\n    normalizedHeader === \"x-forwarded-for\" ? value.split(\",\")[0] : value;\n  return candidate?.trim() || undefined;\n}\n\nfunction pruneExpiredBuckets(now: number): void {\n  if (rateLimitBuckets.size <= MAX_RATE_LIMIT_BUCKETS) return;\n  for (const [key, bucket] of rateLimitBuckets) {\n    if (bucket.resetAt <= now) rateLimitBuckets.delete(key);\n  }\n}\n\nfunction loadSiteContext(\n  config: ResolvedSilicaConfig,\n  requestContext: AssistantRequestContext,\n): AssistantSiteContext {\n  const contentRoot = path.join(getProjectRoot(), \".silica/content\");\n  const homePage = loadHomePageContext(contentRoot);\n  const currentPage = loadCurrentPageContext(\n    contentRoot,\n    requestContext,\n    homePage?.sourcePath,\n  );\n  return {\n    siteTitle: config.title,\n    siteDescription: config.description,\n    homePage,\n    currentPage,\n    contentRoot,\n    resolveCitation: (sourcePath) => {\n      const entry = getPageBySourcePath(sourcePath);\n      if (!entry) return undefined;\n      return {\n        slug: entry.slug,\n        title: entry.title,\n        href: slugToHref(entry.slug),\n        sourcePath: entry.sourcePath,\n      };\n    },\n    resolveWikiLink: (currentSourcePath, target) => {\n      const currentEntry =\n        getPageBySourcePath(currentSourcePath) ??\n        (homePage ? getPageBySourcePath(homePage.sourcePath) : undefined) ??\n        getPage(\"index\");\n      if (!currentEntry) return undefined;\n\n      const resolvedSlug = resolveWikiLinkFromDb(\n        currentEntry.slug,\n        target,\n        config.wikilinks.strategy,\n        config.ordering,\n      );\n      if (!resolvedSlug) return undefined;\n\n      const entry = getPage(resolvedSlug);\n      if (!entry) return undefined;\n      return {\n        slug: entry.slug,\n        title: entry.title,\n        href: slugToHref(entry.slug),\n        sourcePath: entry.sourcePath,\n      };\n    },\n  };\n}\n\nfunction loadHomePageContext(\n  contentRoot: string,\n): AssistantSiteContext[\"homePage\"] {\n  const homePage = getPage(\"index\");\n  if (!homePage) return undefined;\n\n  try {\n    const raw = fs.readFileSync(path.join(contentRoot, homePage.sourcePath), {\n      encoding: \"utf8\",\n    });\n    const excerpt = truncateHomePageExcerpt(stripFrontmatter(raw).trim());\n    if (!excerpt) return undefined;\n    return {\n      title: homePage.title,\n      sourcePath: homePage.sourcePath,\n      excerpt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\nfunction loadCurrentPageContext(\n  contentRoot: string,\n  requestContext: AssistantRequestContext,\n  fallbackSourcePath: string | undefined,\n): AssistantSiteContext[\"currentPage\"] {\n  const sourcePath =\n    requestContext.currentSourcePath ??\n    sourcePathForSlug(requestContext.currentSlug) ??\n    fallbackSourcePath;\n  if (!sourcePath) return undefined;\n\n  const entry = getPageBySourcePath(sourcePath);\n  if (!entry) return undefined;\n\n  try {\n    const raw = fs.readFileSync(path.join(contentRoot, entry.sourcePath), {\n      encoding: \"utf8\",\n    });\n    const excerpt = truncateHomePageExcerpt(stripFrontmatter(raw).trim());\n    return {\n      title: entry.title,\n      slug: entry.slug,\n      sourcePath: entry.sourcePath,\n      excerpt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\nfunction sourcePathForSlug(slug: string | undefined): string | undefined {\n  if (!slug) return undefined;\n  return getPage(slug)?.sourcePath;\n}\n\nfunction stripFrontmatter(markdown: string): string {\n  return markdown.replace(/^---\\r?\\n[\\s\\S]*?\\r?\\n---\\r?\\n?/, \"\");\n}\n\nfunction truncateHomePageExcerpt(markdown: string): string {\n  const normalized = markdown.replace(/\\s+/g, \" \").trim();\n  if (normalized.length <= MAX_HOME_PAGE_EXCERPT_CHARS) return normalized;\n  return `${normalized.slice(0, MAX_HOME_PAGE_EXCERPT_CHARS).trimEnd()}...`;\n}\n"],"mappings":"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","names":[]}

package/dist/server/handler.d.ts

@@ -0,0 +1,39 @@
+import { AssistantSiteContext } from '../types.js';
+import { RunAssistantOptions } from './runtime.js';
+import '@core-ai/core-ai';
+import './tools.js';
+
+/**
+ * Thrown by `resolve` when the assistant cannot run (e.g. the API key
+ * environment variable is missing). Reported to the client as a 503 with
+ * the given message.
+ */
+declare class AssistantUnavailableError extends Error {
+}
+type AssistantRuntime = {
+    model: RunAssistantOptions["model"];
+    site: AssistantSiteContext;
+    /** Server-only secret used to sign client-held assistant transcript turns. */
+    transcriptSigningSecret: string;
+    maxToolTurns?: number;
+};
+type AssistantRequestContext = {
+    currentSourcePath?: string;
+    currentSlug?: string;
+};
+type AssistantHandlerOptions = {
+    /**
+     * Optional request gate for auth, quotas, or rate limits. Return a Response to
+     * reject before the body is parsed or runtime dependencies are resolved.
+     */
+    authorizeRequest?: (request: Request) => Response | undefined | Promise<Response | undefined>;
+    /** Resolves the model and site context for the current request. */
+    resolve: (context: AssistantRequestContext) => AssistantRuntime | Promise<AssistantRuntime>;
+};
+/**
+ * Creates a fetch-style `POST` handler that streams newline-delimited
+ * JSON `AssistantStreamEvent`s.
+ */
+declare function createAssistantHandler(options: AssistantHandlerOptions): (request: Request) => Promise<Response>;
+
+export { type AssistantHandlerOptions, type AssistantRequestContext, type AssistantRuntime, AssistantUnavailableError, createAssistantHandler };

package/dist/server/handler.js

@@ -0,0 +1,239 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { runAssistant } from "./runtime.js";
+const MAX_MESSAGES = 40;
+const MAX_MESSAGE_LENGTH = 8e3;
+const MAX_SIGNATURE_LENGTH = 256;
+const MAX_REQUEST_BODY_BYTES = 512 * 1024;
+const SIGNATURE_VERSION = "v1.";
+const SIGNATURE_CONTEXT = "silica.assistant.transcript.v1\n";
+const messageIdSchema = z.string().uuid();
+const previousMessageIdSchema = messageIdSchema.nullable();
+const messageContentSchema = z.string().min(1).max(MAX_MESSAGE_LENGTH);
+const requestSourcePathSchema = z.string().min(1).max(512).transform(normalizeRequestSourcePath).pipe(z.string().min(1).refine(isSafeRequestSourcePath));
+const requestSlugSchema = z.string().min(1).max(512).transform(normalizeRequestSlug).pipe(z.string().min(1).refine(isSafeRequestSlug));
+const requestSchema = z.object({
+  messages: z.array(
+    z.discriminatedUnion("role", [
+      z.object({
+        id: messageIdSchema,
+        previousMessageId: previousMessageIdSchema,
+        role: z.literal("user"),
+        content: messageContentSchema
+      }),
+      z.object({
+        id: messageIdSchema,
+        previousMessageId: previousMessageIdSchema,
+        role: z.literal("assistant"),
+        content: messageContentSchema,
+        signature: z.string().min(1).max(MAX_SIGNATURE_LENGTH)
+      })
+    ])
+  ).min(1).max(MAX_MESSAGES),
+  responseMessageId: messageIdSchema,
+  currentSourcePath: requestSourcePathSchema.optional(),
+  currentSlug: requestSlugSchema.optional()
+});
+class AssistantUnavailableError extends Error {
+}
+function createAssistantHandler(options) {
+  return async function POST(request) {
+    const authorizationResponse = await options.authorizeRequest?.(request);
+    if (authorizationResponse) return authorizationResponse;
+    const requestBody = await readRequestBody(request);
+    if (!requestBody.success) {
+      return jsonError("Assistant request body is too large.", 413);
+    }
+    const parsedJson = parseJson(requestBody.body);
+    const parsed = requestSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+      return jsonError("Invalid assistant request.", 400);
+    }
+    const transcript = parsed.data.messages;
+    if (transcript.at(-1)?.role !== "user") {
+      return jsonError("The last message must be a user message.", 400);
+    }
+    if (transcript.some((message) => message.id === parsed.data.responseMessageId)) {
+      return jsonError("Invalid assistant transcript.", 400);
+    }
+    let runtime;
+    try {
+      runtime = await options.resolve({
+        currentSourcePath: parsed.data.currentSourcePath,
+        currentSlug: parsed.data.currentSlug
+      });
+    } catch (error) {
+      if (error instanceof AssistantUnavailableError) {
+        return jsonError(error.message, 503);
+      }
+      throw error;
+    }
+    if (!runtime.transcriptSigningSecret) {
+      return jsonError(
+        "The AI assistant signing secret is not configured.",
+        503
+      );
+    }
+    if (!verifyTranscript(transcript, runtime.transcriptSigningSecret)) {
+      return jsonError("Invalid assistant transcript.", 400);
+    }
+    const assistantMessage = {
+      id: parsed.data.responseMessageId,
+      previousMessageId: transcript.at(-1).id,
+      role: "assistant"
+    };
+    const encoder = new TextEncoder();
+    const body = new ReadableStream({
+      async start(controller) {
+        const emit = (event) => {
+          controller.enqueue(encoder.encode(`${JSON.stringify(event)}
+`));
+        };
+        try {
+          const result = await runAssistant({
+            model: runtime.model,
+            site: runtime.site,
+            maxToolTurns: runtime.maxToolTurns,
+            transcript,
+            currentSourcePath: parsed.data.currentSourcePath,
+            emit,
+            signal: request.signal
+          });
+          if (!messageContentSchema.safeParse(result.answer).success) {
+            emit({
+              type: "error",
+              message: "The assistant returned an invalid answer. Please try again."
+            });
+            return;
+          }
+          emit({
+            type: "message-signature",
+            id: assistantMessage.id,
+            previousMessageId: assistantMessage.previousMessageId,
+            signature: signTranscript(
+              [...transcript, { ...assistantMessage, content: result.answer }],
+              runtime.transcriptSigningSecret
+            )
+          });
+          emit({ type: "done" });
+        } catch (error) {
+          if (!request.signal.aborted) {
+            console.error("[silica] assistant request failed:", error);
+            emit({
+              type: "error",
+              message: "The assistant failed to answer. Please try again."
+            });
+          }
+        } finally {
+          controller.close();
+        }
+      }
+    });
+    return new Response(body, {
+      headers: {
+        "content-type": "application/x-ndjson; charset=utf-8",
+        "cache-control": "no-store"
+      }
+    });
+  };
+}
+async function readRequestBody(request) {
+  const contentLength = Number(request.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > MAX_REQUEST_BODY_BYTES) {
+    return { success: false };
+  }
+  if (!request.body) return { success: true, body: "" };
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder();
+  let bytesRead = 0;
+  let body = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytesRead += value.byteLength;
+      if (bytesRead > MAX_REQUEST_BODY_BYTES) {
+        await reader.cancel().catch(() => void 0);
+        return { success: false };
+      }
+      body += decoder.decode(value, { stream: true });
+    }
+    body += decoder.decode();
+    return { success: true, body };
+  } catch {
+    return { success: true, body: "" };
+  }
+}
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function jsonError(message, status) {
+  return Response.json({ error: message }, { status });
+}
+function normalizeRequestSourcePath(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function isSafeRequestSourcePath(value) {
+  if (!/\.(md|markdown|mdx)$/i.test(value)) return false;
+  return isSafeContentPath(value);
+}
+function normalizeRequestSlug(value) {
+  const normalized = value.trim().replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  return normalized || "index";
+}
+function isSafeRequestSlug(value) {
+  return isSafeContentPath(value);
+}
+function isSafeContentPath(value) {
+  if (!value || value.startsWith("~") || /^[A-Za-z]:/.test(value)) {
+    return false;
+  }
+  if (value.includes("//")) return false;
+  return value.split("/").every((segment) => segment && segment !== "." && segment !== "..");
+}
+function verifyTranscript(transcript, secret) {
+  if (!verifyTranscriptChain(transcript)) return false;
+  return transcript.every((message, index) => {
+    if (message.role !== "assistant") return true;
+    return verifySignature(transcript.slice(0, index + 1), message, secret);
+  });
+}
+function verifyTranscriptChain(transcript) {
+  const seen = /* @__PURE__ */ new Set();
+  return transcript.every((message, index) => {
+    if (seen.has(message.id)) return false;
+    seen.add(message.id);
+    const previous = transcript[index - 1];
+    if (message.previousMessageId !== (previous?.id ?? null)) return false;
+    if (index % 2 === 0 && message.role !== "user") return false;
+    if (index % 2 === 1 && message.role !== "assistant") return false;
+    return true;
+  });
+}
+function verifySignature(transcriptPrefix, message, secret) {
+  if (!message.signature.startsWith(SIGNATURE_VERSION)) return false;
+  const expected = signTranscript(transcriptPrefix, secret);
+  const actualSignature = Buffer.from(message.signature);
+  const expectedSignature = Buffer.from(expected);
+  return actualSignature.byteLength === expectedSignature.byteLength && timingSafeEqual(actualSignature, expectedSignature);
+}
+function signTranscript(transcriptPrefix, secret) {
+  const payload = JSON.stringify(
+    transcriptPrefix.map((message) => ({
+      id: message.id,
+      previousMessageId: message.previousMessageId,
+      role: message.role,
+      content: message.content
+    }))
+  );
+  return SIGNATURE_VERSION + createHmac("sha256", secret).update(SIGNATURE_CONTEXT).update(payload).digest("base64url");
+}
+export {
+  AssistantUnavailableError,
+  createAssistantHandler
+};
+//# sourceMappingURL=handler.js.map