deepspace 0.10.1 → 0.10.2

package/dist/worker.js

@@ -2174,11 +2174,11 @@ async function handleToolsRequest(ctx, request, path) {
   }
   if (path.startsWith("tools/describe/")) {
     const toolName = path.replace("tools/describe/", "");
-    const tool2 = BUILT_IN_TOOLS.find((t) => t.name === toolName);
-    if (!tool2) {
+    const tool3 = BUILT_IN_TOOLS.find((t) => t.name === toolName);
+    if (!tool3) {
       return Response.json({ error: `Tool not found: ${toolName}` }, { status: 404, headers: CORS_HEADERS });
     }
-    return Response.json({ tool: tool2 }, { headers: CORS_HEADERS });
+    return Response.json({ tool: tool3 }, { headers: CORS_HEADERS });
   }
   if (path.startsWith("tools/execute") && request.method === "POST") {
     return handleToolExecute(ctx, request);
@@ -2195,8 +2195,8 @@ async function handleToolExecute(ctx, request) {
       { status: 400, headers: CORS_HEADERS }
     );
   }
-  const { tool: tool2, params = {} } = body;
-  if (!tool2) {
+  const { tool: tool3, params = {} } = body;
+  if (!tool3) {
     return Response.json(
       { success: false, error: 'Missing "tool" in request body' },
       { status: 400, headers: CORS_HEADERS }
@@ -2213,8 +2213,8 @@ async function handleToolExecute(ctx, request) {
       userRole = user.role;
     }
   }
-  if (tool2.startsWith("yjs.")) {
-    const result2 = executeYjsTool(ctx, tool2, params, userId, userRole);
+  if (tool3.startsWith("yjs.")) {
+    const result2 = executeYjsTool(ctx, tool3, params, userId, userRole);
     const status2 = result2.success ? 200 : result2.error?.includes("not found") ? 404 : 400;
     return Response.json(result2, { status: status2, headers: CORS_HEADERS });
   }
@@ -2225,7 +2225,7 @@ async function handleToolExecute(ctx, request) {
     getPermissionContext: ctx.getPermissionContext,
     send: ctx.send
   };
-  const result = await executeTool(recordCtx, tool2, params, userId, userRole, isAppAction);
+  const result = await executeTool(recordCtx, tool3, params, userId, userRole, isAppAction);
   const status = result.success ? 200 : result.error?.includes("not found") ? 404 : 400;
   return Response.json(result, { status, headers: CORS_HEADERS });
 }
@@ -5105,7 +5105,8 @@ var ALLOWED_BINDING_TYPES = /* @__PURE__ */ new Set([
   "queue",
   "browser_rendering",
   "analytics_engine",
-  "hyperdrive"
+  "hyperdrive",
+  "ratelimit"
 ]);
 var RESERVED_BINDING_NAMES = /* @__PURE__ */ new Set([
   "ASSETS",
@@ -5113,6 +5114,7 @@ var RESERVED_BINDING_NAMES = /* @__PURE__ */ new Set([
   "API_WORKER",
   "DEEPSPACE_APP_ID",
   "DEEPSPACE_RESOURCE_ID",
+  "DEEPSPACE_RELEASE_OPERATION_ID",
   "APP_NAME",
   "OWNER_USER_ID",
   "AUTH_JWT_PUBLIC_KEY",
@@ -5203,6 +5205,17 @@ function requiredFieldError(b) {
         return `hyperdrive binding "${b.name}": auto-provisioning not yet supported (provide a real id)`;
       }
       return null;
+    case "ratelimit":
+      if (!/^\d+$/u.test(b.namespace_id) || Number(b.namespace_id) <= 0) {
+        return `ratelimit binding "${b.name}" requires a positive integer namespace_id string`;
+      }
+      if (!Number.isInteger(b.simple?.limit) || b.simple.limit <= 0) {
+        return `ratelimit binding "${b.name}" requires simple.limit (positive integer)`;
+      }
+      if (b.simple.period !== 10 && b.simple.period !== 60) {
+        return `ratelimit binding "${b.name}" requires simple.period (10 or 60)`;
+      }
+      return null;
     case "ai":
     case "browser_rendering":
     case "analytics_engine":
@@ -5280,6 +5293,15 @@ function bindingManifestFromOutputConfig(outputConfig) {
     const id = pluckString(h, "id");
     if (name && id) out.push({ type: "hyperdrive", name, id });
   }
+  for (const r of asObjectArray(outputConfig.ratelimits)) {
+    const name = pluckString(r, "name");
+    const namespace_id = pluckString(r, "namespace_id");
+    const simple = isObject(r.simple) ? r.simple : null;
+    const limit = pluckNumber(simple, "limit");
+    const period = pluckNumber(simple, "period");
+    if (!name || !namespace_id || limit === null || period !== 10 && period !== 60) continue;
+    out.push({ type: "ratelimit", name, namespace_id, simple: { limit, period } });
+  }
   return out;
 }
 function isObject(v) {
@@ -6022,6 +6044,132 @@ function validateAppMigrationIds(value) {
   return { valid: true, ids };
 }
 
+// src/shared/ai-models.ts
+var DEEPSPACE_MODEL_CATALOG_PROVENANCE = {
+  version: "2026-08-04",
+  verifiedAt: "2026-08-04",
+  sources: {
+    anthropic: "https://platform.claude.com/docs/en/api/beta/models/list",
+    openai: "https://developers.openai.com/api/docs/models/all",
+    cerebras: "https://inference-docs.cerebras.ai/models/overview"
+  }
+};
+var MULTI_STEP_AGENT_PROFILES = ["application", "documentation"];
+function createMultiStepModelFactory(provider) {
+  return (model) => ({
+    ...model,
+    ...provider,
+    agentSupport: "multi-step",
+    agentProfiles: MULTI_STEP_AGENT_PROFILES
+  });
+}
+var anthropicModel = createMultiStepModelFactory({
+  provider: "anthropic",
+  providerLabel: "Anthropic",
+  transport: "messages"
+});
+var openAIModel = createMultiStepModelFactory({
+  provider: "openai",
+  providerLabel: "OpenAI",
+  transport: "chat-completions"
+});
+var DEEPSPACE_AI_MODELS = [
+  anthropicModel({
+    id: "claude-fable-5",
+    label: "Claude Fable 5",
+    family: "Claude 5",
+    recommendation: "frontier"
+  }),
+  anthropicModel({
+    id: "claude-opus-5",
+    label: "Claude Opus 5",
+    family: "Claude 5",
+    recommendation: "frontier"
+  }),
+  anthropicModel({
+    id: "claude-sonnet-5",
+    label: "Claude Sonnet 5",
+    family: "Claude 5",
+    recommendation: "balanced"
+  }),
+  anthropicModel({
+    id: "claude-haiku-4-5",
+    label: "Claude Haiku 4.5",
+    family: "Claude 4.5",
+    recommendation: "fast"
+  }),
+  openAIModel({
+    id: "gpt-5.6-sol",
+    label: "GPT-5.6 Sol",
+    family: "GPT-5.6",
+    recommendation: "frontier"
+  }),
+  openAIModel({
+    id: "gpt-5.6-terra",
+    label: "GPT-5.6 Terra",
+    family: "GPT-5.6",
+    recommendation: "balanced"
+  }),
+  openAIModel({
+    id: "gpt-5.6-luna",
+    label: "GPT-5.6 Luna",
+    family: "GPT-5.6",
+    recommendation: "fast"
+  }),
+  {
+    id: "gpt-oss-120b",
+    label: "GPT-OSS 120B",
+    provider: "cerebras",
+    providerLabel: "Cerebras",
+    family: "GPT-OSS",
+    agentSupport: "single-step",
+    agentProfiles: [],
+    transport: "chat-completions",
+    recommendation: "limited",
+    note: "Available for direct generation; the current proxy adapter has not passed multi-step tool-result continuation."
+  }
+];
+var DEEPSPACE_AI_DEFAULTS = {
+  agent: "claude-sonnet-5",
+  directGeneration: "claude-sonnet-5",
+  summarization: "claude-haiku-4-5"
+};
+var DEEPSPACE_AGENT_PROFILES = {
+  application: {
+    id: "application",
+    defaultModel: DEEPSPACE_AI_DEFAULTS.agent,
+    maxSteps: 21,
+    maxToolCalls: 20,
+    allowedTools: "application-defined"
+  },
+  documentation: {
+    id: "documentation",
+    defaultModel: DEEPSPACE_AI_DEFAULTS.agent,
+    // Permit up to twenty completed read-only tools plus one final synthesis
+    // step. The runner disables tools once the tool-call budget is exhausted.
+    maxSteps: 21,
+    maxToolCalls: 20,
+    allowedTools: ["documentation_search", "documentation_read"]
+  }
+};
+function getDeepSpaceAIModel(modelId) {
+  if (typeof modelId !== "string") return null;
+  return DEEPSPACE_AI_MODELS.find((model) => model.id === modelId) ?? null;
+}
+function listDeepSpaceAgentModels(profileId = "application") {
+  const defaultModel = DEEPSPACE_AGENT_PROFILES[profileId].defaultModel;
+  return DEEPSPACE_AI_MODELS.filter(
+    (model) => model.agentProfiles.includes(profileId)
+  ).sort((left, right) => Number(right.id === defaultModel) - Number(left.id === defaultModel));
+}
+function resolveDeepSpaceAgentModel(modelId, profileId = "application") {
+  const profile = DEEPSPACE_AGENT_PROFILES[profileId];
+  const resolvedId = modelId === void 0 ? profile.defaultModel : modelId;
+  const model = getDeepSpaceAIModel(resolvedId);
+  if (!model || !model.agentProfiles.includes(profileId)) return null;
+  return { modelId: model.id, provider: model.provider, model, profile };
+}
+
 // src/server/utils/cors.ts
 function matchOrigin(origin, patterns) {
   if (!origin) return null;
@@ -6393,7 +6541,7 @@ function authWorkerFetch(env, path, init) {
 function buildCronContext(env, ownerUserId, roomId = "default") {
   const roomIdObj = env.RECORD_ROOMS.idFromName(roomId);
   const room = env.RECORD_ROOMS.get(roomIdObj);
-  async function executeTool3(tool2, params) {
+  async function executeTool3(tool3, params) {
     const response = await room.fetch(
       new Request("https://internal/api/tools/execute", {
         method: "POST",
@@ -6402,12 +6550,12 @@ function buildCronContext(env, ownerUserId, roomId = "default") {
           "X-User-Id": ownerUserId,
           "X-App-Action": "true"
         },
-        body: JSON.stringify({ tool: tool2, params })
+        body: JSON.stringify({ tool: tool3, params })
       })
     );
     const result = await response.json();
     if (!result.success) {
-      throw new Error(`RecordRoom tool ${tool2} failed: ${result.error || "Unknown error"}`);
+      throw new Error(`RecordRoom tool ${tool3} failed: ${result.error || "Unknown error"}`);
     }
     return result.data;
   }
@@ -6529,6 +6677,162 @@ function createDeepSpaceAI(env, provider, options = {}) {
   }
 }
 
+// src/server/utils/agent.ts
+import {
+  stepCountIs,
+  streamText
+} from "ai";
+var DeepSpaceAgentModelError = class extends Error {
+  constructor(modelId, profile) {
+    super(
+      `Model ${typeof modelId === "string" ? JSON.stringify(modelId) : String(modelId)} is not compatible with the ${profile} agent profile`
+    );
+    this.modelId = modelId;
+    this.profile = profile;
+    this.name = "DeepSpaceAgentModelError";
+  }
+  code = "unsupported_agent_model";
+};
+var DeepSpaceAgentProfileError = class extends Error {
+  constructor(profile, toolName) {
+    super(`The ${profile} agent profile does not allow tool ${JSON.stringify(toolName)}`);
+    this.profile = profile;
+    this.toolName = toolName;
+    this.name = "DeepSpaceAgentProfileError";
+  }
+  code = "agent_profile_violation";
+};
+function streamDeepSpaceAgent(env, options) {
+  const { profile, modelId, authToken, ...streamOptions } = options;
+  const selection = resolveDeepSpaceAgentModel(modelId, profile);
+  if (!selection) throw new DeepSpaceAgentModelError(modelId, profile);
+  if (selection.profile.allowedTools !== "application-defined") {
+    const allowed = selection.profile.allowedTools;
+    for (const toolName of Object.keys(streamOptions.tools ?? {})) {
+      if (!allowed.includes(toolName)) {
+        throw new DeepSpaceAgentProfileError(profile, toolName);
+      }
+    }
+  }
+  const provider = createDeepSpaceAI(env, selection.provider, authToken ? { authToken } : {});
+  const { prepareStep, tools, ...remainingStreamOptions } = streamOptions;
+  const boundedTools = limitToolExecutions(tools, selection.profile.maxToolCalls);
+  const result = streamText({
+    ...remainingStreamOptions,
+    ...boundedTools ? { tools: boundedTools } : {},
+    model: provider(selection.modelId),
+    stopWhen: stepCountIs(selection.profile.maxSteps),
+    prepareStep: enforceToolCallLimit(prepareStep, selection.profile.maxToolCalls),
+    ...selection.provider === "openai" ? { providerOptions: { openai: { reasoningEffort: "none" } } } : {}
+  });
+  return { selection, result };
+}
+function enforceToolCallLimit(prepareStep, maxToolCalls) {
+  if (maxToolCalls === void 0) return prepareStep;
+  return async (context) => {
+    const prepared = await prepareStep?.(context);
+    const completedToolCalls = context.steps.reduce(
+      (count, step) => count + step.toolCalls.length,
+      0
+    );
+    if (completedToolCalls < maxToolCalls) return prepared;
+    return { ...prepared, activeTools: [], toolChoice: "none" };
+  };
+}
+function limitToolExecutions(tools, maxToolCalls) {
+  if (!tools || maxToolCalls === void 0) return tools;
+  let executions = 0;
+  return Object.fromEntries(
+    Object.entries(tools).map(([name, definition]) => {
+      if (typeof definition.execute !== "function") return [name, definition];
+      const execute = definition.execute;
+      return [
+        name,
+        {
+          ...definition,
+          execute: (...args) => {
+            if (executions >= maxToolCalls) {
+              return Promise.resolve({
+                error: `The agent tool-call limit of ${maxToolCalls} has been reached`
+              });
+            }
+            executions++;
+            return execute(...args);
+          }
+        }
+      ];
+    })
+  );
+}
+function deepSpaceAgentErrorSummary(error, context = {}) {
+  const details = [];
+  const contextFields = [
+    context.profile ? `profile=${context.profile}` : void 0,
+    context.provider ? `provider=${safeLogToken(context.provider)}` : void 0,
+    context.modelId ? `model=${safeLogToken(context.modelId)}` : void 0
+  ].filter((part) => Boolean(part));
+  if (contextFields.length > 0) details.push(contextFields.join(" "));
+  const pending = [error];
+  const visited = /* @__PURE__ */ new Set();
+  while (pending.length > 0 && details.length < 8) {
+    const current = pending.shift();
+    if (current == null || visited.has(current)) continue;
+    visited.add(current);
+    if (typeof current === "object") {
+      const record = current;
+      const parts = [
+        typeof record.name === "string" ? `name=${safeLogToken(record.name)}` : current instanceof Error ? `name=${safeLogToken(current.name)}` : void 0,
+        safeErrorMessage(current, record),
+        typeof record.statusCode === "number" ? `status=${record.statusCode}` : void 0,
+        typeof record.code === "string" ? `code=${safeLogToken(record.code)}` : void 0,
+        typeof record.requestId === "string" ? `requestId=${safeLogToken(record.requestId)}` : void 0,
+        ...safeProviderResponseMetadata(record.responseBody)
+      ].filter((part) => Boolean(part));
+      details.push(parts.join(" ") || Object.prototype.toString.call(current));
+      if (record.lastError != null) pending.push(record.lastError);
+      if (record.cause != null) pending.push(record.cause);
+      if (Array.isArray(record.errors)) pending.push(...record.errors);
+      continue;
+    }
+    details.push(String(current));
+  }
+  return details.join(" <- ") || "Unknown error";
+}
+function safeErrorMessage(current, record) {
+  if (record.responseBody !== void 0) return void 0;
+  const message = current instanceof Error ? current.message : record.message;
+  if (typeof message !== "string" || !message.trim()) return void 0;
+  return `message=${safeLogText(message)}`;
+}
+function safeProviderResponseMetadata(responseBody) {
+  if (typeof responseBody !== "string") return [];
+  try {
+    const parsed = JSON.parse(responseBody);
+    const error = parsed.error && typeof parsed.error === "object" ? parsed.error : void 0;
+    const code = typeof error?.code === "string" ? error.code : typeof error?.type === "string" ? error.type : void 0;
+    const requestId = typeof parsed.request_id === "string" ? parsed.request_id : void 0;
+    return [
+      code ? `upstreamCode=${safeLogToken(code)}` : void 0,
+      requestId ? `upstreamRequestId=${safeLogToken(requestId)}` : void 0
+    ].filter((part) => Boolean(part));
+  } catch {
+    return [];
+  }
+}
+function safeLogToken(value) {
+  return value.replace(/[^a-zA-Z0-9._:/-]/g, "_").slice(0, 120);
+}
+function safeLogText(value) {
+  const withoutControlCharacters = Array.from(value, (character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint === 127 ? " " : character;
+  }).join("");
+  return withoutControlCharacters.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]").replace(
+    /\b(api[_ -]?key|authorization|password|secret|token)\b\s*[:=]\s*\S+/gi,
+    "$1=[redacted]"
+  ).trim().slice(0, 300);
+}
+
 // src/server/utils/composio-tools.ts
 import { tool, jsonSchema } from "ai";
 var EMPTY_SCHEMA = { type: "object", properties: {} };
@@ -6980,7 +7284,7 @@ function makeDefaultSummarizer(env, options = {}) {
 }
 
 // src/server/utils/chat-history.ts
-async function executeTool2(stub, userId, tool2, params) {
+async function executeTool2(stub, userId, tool3, params) {
   const res = await stub.fetch(new Request("https://internal/api/tools/execute", {
     method: "POST",
     headers: {
@@ -6988,11 +7292,11 @@ async function executeTool2(stub, userId, tool2, params) {
       "X-User-Id": userId,
       "X-App-Action": "true"
     },
-    body: JSON.stringify({ tool: tool2, params })
+    body: JSON.stringify({ tool: tool3, params })
   }));
   const body = await res.json();
   if (!body.success) {
-    throw new Error(`chat-history ${tool2} failed: ${body.error ?? "unknown error"}`);
+    throw new Error(`chat-history ${tool3} failed: ${body.error ?? "unknown error"}`);
   }
   return body.data;
 }
@@ -7207,6 +7511,1109 @@ function splitStatements(sql) {
   return sql.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
 }
 
+// src/documentation/worker/routes.ts
+import { Hono } from "hono";
+
+// src/documentation/resource-path.ts
+function canonicalNativeDocumentationRequestPath(pathname) {
+  try {
+    return pathname.split("/").map((segment) => encodeURIComponent(decodeURIComponent(segment))).join("/");
+  } catch {
+    return null;
+  }
+}
+
+// src/documentation/worker/assistant.ts
+import { tool as tool2 } from "ai";
+import { z } from "zod/v4";
+
+// src/documentation/types.ts
+var DOCUMENTATION_MANIFEST_VERSION = 2;
+var DocumentationError = class extends Error {
+  code;
+  diagnostics;
+  constructor(message, code, diagnostics = []) {
+    super(message);
+    this.name = "DocumentationError";
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+};
+
+// src/documentation/routing.ts
+function collapseRoute(value) {
+  let route = `/${value}`.replace(/\/{2,}/g, "/");
+  if (route.length > 1) route = route.replace(/\/$/, "");
+  return route;
+}
+function normalizeRoute(value) {
+  assertSafeRoute(value);
+  let route = collapseRoute(value);
+  route = route.replace(/\.(?:md|mdx)$/i, "");
+  route = route.replace(/\/index$/i, "");
+  return route || "/";
+}
+function normalizeDocumentationBasePath(value) {
+  if (!value || value === "/") return "";
+  const normalized = normalizeRoute(value);
+  if (normalized === "/_documentation") {
+    throw new DocumentationError("The internal /_documentation namespace cannot be a public documentation base", "documentation_base_invalid");
+  }
+  return normalized;
+}
+function documentationPublicPath(basePath, path) {
+  const base = normalizeDocumentationBasePath(basePath);
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  if (suffix === "/") return base || "/";
+  return `${base}${suffix}`;
+}
+function assertSafeRoute(value) {
+  if (value.includes("\\") || value.includes("\0")) throw unsafeRoute(value);
+  let decoded = value;
+  for (let pass = 0; pass < 5; pass++) {
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      throw unsafeRoute(value);
+    }
+    if (next === decoded) break;
+    decoded = next;
+  }
+  if (decoded.includes("\\") || decoded.includes("\0") || decoded.split("/").some((segment) => segment === "." || segment === "..")) throw unsafeRoute(value);
+}
+function unsafeRoute(value) {
+  return new DocumentationError(
+    `Documentation route contains an unsafe path segment: ${value}`,
+    "documentation_route_invalid",
+    [{ code: "route_path_escape", message: value }]
+  );
+}
+
+// src/documentation/worker/assistant.ts
+var MAX_CHUNKS = 1e4;
+var MAX_CHUNK_CHARS = 2500;
+var MAX_CORPUS_CHARS = 12e6;
+var SEARCH_STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "about",
+  "an",
+  "and",
+  "are",
+  "can",
+  "could",
+  "do",
+  "does",
+  "for",
+  "from",
+  "has",
+  "have",
+  "how",
+  "i",
+  "in",
+  "is",
+  "it",
+  "me",
+  "my",
+  "of",
+  "on",
+  "or",
+  "our",
+  "should",
+  "the",
+  "this",
+  "to",
+  "was",
+  "we",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "will",
+  "with",
+  "would",
+  "you",
+  "your"
+]);
+var indexedChunkCache = /* @__PURE__ */ new WeakMap();
+function parseDocumentationCorpus(value) {
+  if (!Array.isArray(value)) throw new Error("Documentation assistant index must be an array");
+  if (value.length > MAX_CHUNKS) {
+    throw new Error(`Documentation assistant index exceeds ${MAX_CHUNKS} chunks`);
+  }
+  const chunks = [];
+  let totalChars2 = 0;
+  for (let index = 0; index < value.length; index++) {
+    const raw = value[index];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error(`Documentation assistant chunk ${index} must be an object`);
+    }
+    const chunk = raw;
+    if (typeof chunk.id !== "string" || !chunk.id || typeof chunk.route !== "string" || !chunk.route.startsWith("/") || typeof chunk.title !== "string" || !chunk.title || typeof chunk.text !== "string" || !chunk.text) {
+      throw new Error(`Documentation assistant chunk ${index} has invalid required fields`);
+    }
+    if (chunk.text.length > MAX_CHUNK_CHARS) {
+      throw new Error(`Documentation assistant chunk ${chunk.id} exceeds ${MAX_CHUNK_CHARS} characters`);
+    }
+    totalChars2 += chunk.text.length;
+    if (totalChars2 > MAX_CORPUS_CHARS) {
+      throw new Error(`Documentation assistant corpus exceeds ${MAX_CORPUS_CHARS} characters`);
+    }
+    chunks.push({
+      id: chunk.id,
+      route: chunk.route,
+      title: chunk.title,
+      ...typeof chunk.heading === "string" && chunk.heading ? { heading: chunk.heading } : {},
+      text: chunk.text
+    });
+  }
+  return chunks;
+}
+function searchDocumentationCorpus(corpus, query, limit = 6) {
+  const normalized = normalize(query);
+  const terms = [
+    ...new Set(
+      normalized.split(" ").filter((term) => term.length > 1 && !SEARCH_STOP_WORDS.has(term))
+    )
+  ];
+  if (!terms.length) return [];
+  const requiredTerms = new Set(terms);
+  return corpus.map((chunk) => {
+    const { text, textTerms, title, titleTerms } = indexChunk(chunk);
+    const textCounts = countTerms(textTerms, requiredTerms);
+    let score = 0;
+    if (title === normalized) score += 120;
+    else if (title.includes(normalized)) score += 55;
+    if (text.includes(normalized)) score += 30;
+    for (const term of terms) {
+      if (titleTerms.has(term)) score += 14;
+      score += Math.min(6, textCounts.get(term) ?? 0) * 3;
+    }
+    const matchedTerms = terms.filter(
+      (term) => titleTerms.has(term) || textCounts.has(term)
+    ).length;
+    score += matchedTerms * matchedTerms * 4;
+    score += proximityBonus([...titleTerms, ...textTerms], terms);
+    return {
+      route: chunk.route,
+      title: chunk.title,
+      ...chunk.heading ? { heading: chunk.heading } : {},
+      excerpt: excerpt(chunk.text, terms),
+      score
+    };
+  }).filter((result) => result.score > 0).sort((left, right) => right.score - left.score || left.route.localeCompare(right.route)).slice(0, Math.max(1, Math.min(limit, 10)));
+}
+function readDocumentationRoute(corpus, route) {
+  const normalizedRoute = collapseRoute(route);
+  return corpus.filter((chunk) => chunk.route === normalizedRoute).slice(0, 12).map(({ route: chunkRoute, title, heading, text }) => ({
+    route: chunkRoute,
+    title,
+    ...heading ? { heading } : {},
+    text
+  }));
+}
+function buildDocumentationAssistantTools(corpus, basePath = "/docs") {
+  return {
+    documentation_search: tool2({
+      description: "Search the current documentation. Use this before answering factual or how-to questions.",
+      inputSchema: z.object({
+        query: z.string().trim().min(2).max(300),
+        limit: z.number().int().min(1).max(10).optional()
+      }),
+      execute: async ({ query, limit }) => ({
+        results: searchDocumentationCorpus(corpus, query, limit ?? 6).map((result) => ({
+          ...result,
+          url: documentationPublicPath(basePath, result.route)
+        }))
+      })
+    }),
+    documentation_read: tool2({
+      description: "Read bounded source chunks for one exact documentation route returned by documentation_search.",
+      inputSchema: z.object({ route: z.string().trim().startsWith("/").max(500) }),
+      execute: async ({ route }) => ({
+        route: collapseRoute(route),
+        url: documentationPublicPath(basePath, route),
+        chunks: readDocumentationRoute(corpus, route)
+      })
+    })
+  };
+}
+function buildDocumentationAssistantPrompt(appName, currentRoute) {
+  return [
+    `You are the public documentation assistant for "${appName}" on DeepSpace.`,
+    "Answer only from the documentation available through documentation_search and documentation_read.",
+    "Search before answering unless the user is only greeting you.",
+    "Use documentation_read when search excerpts are insufficient or ambiguous.",
+    "Never claim access to application records, integrations, private data, or mutation tools.",
+    "If the documentation does not support an answer, say so plainly and suggest the closest documented page.",
+    "Cite factual answers with Markdown links to the exact documentation routes returned by tools.",
+    "Do not invent URLs, APIs, configuration keys, versions, or behavior.",
+    "Keep answers concise, practical, and explicit about uncertainty.",
+    ...currentRoute ? [`The reader is currently viewing ${collapseRoute(currentRoute)}.`] : []
+  ].join("\n");
+}
+function normalize(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(" ").filter(Boolean).map(canonicalSearchTerm).join(" ");
+}
+function canonicalSearchTerm(term) {
+  if (SEARCH_STOP_WORDS.has(term)) return term;
+  if (["doc", "docs", "document", "documents", "documentation"].includes(term)) return "documentation";
+  if (["builds", "building", "built", "compile", "compiled", "compiles", "compiling"].includes(term)) {
+    return "build";
+  }
+  return term.length > 3 && term.endsWith("s") && !term.endsWith("ss") ? term.slice(0, -1) : term;
+}
+function indexChunk(chunk) {
+  const cached = indexedChunkCache.get(chunk);
+  if (cached) return cached;
+  const title = normalize(`${chunk.title} ${chunk.heading ?? ""}`);
+  const text = normalize(chunk.text);
+  const indexed = {
+    text,
+    textTerms: text.split(" "),
+    title,
+    titleTerms: new Set(title.split(" "))
+  };
+  indexedChunkCache.set(chunk, indexed);
+  return indexed;
+}
+function countTerms(tokens, required) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    if (required.has(token)) counts.set(token, (counts.get(token) ?? 0) + 1);
+  }
+  return counts;
+}
+function proximityBonus(tokens, terms) {
+  const required = new Set(terms);
+  if (required.size < 2) return 0;
+  const counts = /* @__PURE__ */ new Map();
+  let matched = 0;
+  let start = 0;
+  let smallestWindow = Number.POSITIVE_INFINITY;
+  for (let end = 0; end < tokens.length; end++) {
+    const token = tokens[end] ?? "";
+    if (required.has(token)) {
+      const count = counts.get(token) ?? 0;
+      counts.set(token, count + 1);
+      if (count === 0) matched++;
+    }
+    while (matched === required.size && start <= end) {
+      smallestWindow = Math.min(smallestWindow, end - start + 1);
+      const first = tokens[start] ?? "";
+      if (required.has(first)) {
+        const count = counts.get(first) ?? 0;
+        counts.set(first, count - 1);
+        if (count === 1) matched--;
+      }
+      start++;
+    }
+  }
+  return Number.isFinite(smallestWindow) ? Math.max(0, 42 - smallestWindow * 2) : 0;
+}
+function excerpt(text, terms) {
+  const lower = text.toLowerCase();
+  const first = terms.map((term) => lower.indexOf(term)).filter((index) => index >= 0).sort((left, right) => left - right)[0] ?? 0;
+  const start = Math.max(0, first - 160);
+  const end = Math.min(text.length, start + 520);
+  return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).trim()}${end < text.length ? "\u2026" : ""}`;
+}
+
+// src/documentation/worker/published-corpus.ts
+var cachedCorpus;
+async function loadDocumentationPublishedManifest(env, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
+  const response = await env.ASSETS.fetch(
+    new Request(new URL(`${assetBasePath}/manifest.json`, requestUrl))
+  );
+  if (!response.ok) return null;
+  const value = await response.json().catch(() => null);
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const manifest = value;
+  const assistant = parseAssistantPolicy(manifest.assistant);
+  const mcp = parseMcpPolicy(manifest.mcp);
+  const routes = parsePublishedRoutes(manifest.routes);
+  const resources = parsePublishedPaths(manifest.resources, true);
+  if (manifest.version !== DOCUMENTATION_MANIFEST_VERSION || typeof manifest.sourceHash !== "string" || typeof manifest.name !== "string" || !assistant || !mcp || !routes || !resources)
+    return null;
+  return {
+    sourceHash: manifest.sourceHash,
+    name: manifest.name,
+    routes,
+    resources,
+    assistant,
+    mcp
+  };
+}
+function parsePublishedRoutes(value) {
+  return parsePublishedPaths(value, false);
+}
+function parsePublishedPaths(value, allowEmpty) {
+  if (!Array.isArray(value) || !allowEmpty && value.length === 0) return null;
+  if (value.some((path) => typeof path !== "string" || !path.startsWith("/"))) return null;
+  if (value.some((path) => canonicalNativeDocumentationRequestPath(path) !== path))
+    return null;
+  return [...new Set(value)];
+}
+async function loadDocumentationPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
+  if (cachedCorpus?.sourceHash === sourceHash) return cachedCorpus.chunks;
+  const response = await env.ASSETS.fetch(
+    new Request(new URL(`${assetBasePath}/assistant-index.json`, requestUrl))
+  );
+  if (!response.ok) throw new Error(`assistant-index.json returned ${response.status}`);
+  const chunks = parseDocumentationCorpus(await response.json());
+  cachedCorpus = { sourceHash, chunks };
+  return chunks;
+}
+async function resolveDocumentationPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
+  try {
+    return {
+      ok: true,
+      chunks: await loadDocumentationPublishedCorpus(env, sourceHash, requestUrl, assetBasePath)
+    };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+async function readDocumentationPublishedPage(env, corpus, requestedRoute, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
+  const route = collapseRoute(requestedRoute.split("#", 1)[0] ?? "/");
+  const firstChunk = corpus.find((chunk) => chunk.route === route);
+  if (!firstChunk) return null;
+  const pathname = route === "/" ? `${assetBasePath}/index.md` : `${assetBasePath}${route}.md`;
+  const response = await env.ASSETS.fetch(new Request(new URL(pathname, requestUrl)));
+  if (!response.ok) return null;
+  const markdown = await response.text();
+  if (markdown.length > 5e5) throw new Error("Documentation page exceeds 500000 characters");
+  return { route, title: firstChunk.title, markdown };
+}
+function parseAssistantPolicy(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const policy = value;
+  if (!["disabled", "public", "authenticated"].includes(String(policy.access))) return null;
+  return {
+    access: policy.access,
+    ...typeof policy.model === "string" ? { model: policy.model } : {}
+  };
+}
+function parseMcpPolicy(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const policy = value;
+  if (!["disabled", "public"].includes(String(policy.access))) return null;
+  return { access: policy.access };
+}
+
+// src/documentation/worker/public-limiter.ts
+async function documentationPublicClientKey(value) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function checkDocumentationPublicLimit(env, clientKey, logPrefix) {
+  const clientLimiter = env.DOCUMENTATION_CLIENT_RATE_LIMITER;
+  const appLimiter = env.DOCUMENTATION_APP_RATE_LIMITER;
+  if (!clientLimiter || !appLimiter) return { ok: false, status: 503 };
+  try {
+    const client = await clientLimiter.limit({ key: `${env.DEEPSPACE_APP_ID}:${clientKey}` });
+    if (!client.success) return { ok: false, status: 429 };
+    const app = await appLimiter.limit({ key: env.DEEPSPACE_APP_ID });
+    return app.success ? { ok: true } : { ok: false, status: 429 };
+  } catch (error) {
+    console.error(`[${logPrefix}] limiter unavailable: ${documentationLimiterErrorSummary(error)}`);
+    return { ok: false, status: 503 };
+  }
+}
+function documentationLimiterErrorSummary(error) {
+  if (!error || typeof error !== "object") return String(error);
+  const value = error;
+  return JSON.stringify({
+    name: typeof value.name === "string" ? value.name : void 0,
+    message: typeof value.message === "string" ? value.message : void 0,
+    retryable: value.retryable === true,
+    overloaded: value.overloaded === true,
+    cause: typeof value.cause === "string" ? value.cause : void 0
+  });
+}
+
+// src/documentation/worker/request-body.ts
+var RequestBodyTooLargeError = class extends Error {
+  constructor(maxBytes) {
+    super(`Request body exceeds ${maxBytes} bytes`);
+    this.maxBytes = maxBytes;
+    this.name = "RequestBodyTooLargeError";
+  }
+};
+async function readBoundedRequestText(request, maxBytes) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new TypeError("maxBytes must be a positive safe integer");
+  }
+  const declared = request.headers.get("content-length");
+  if (declared && /^\d+$/.test(declared.trim()) && Number(declared) > maxBytes) {
+    throw new RequestBodyTooLargeError(maxBytes);
+  }
+  if (!request.body) return "";
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let text = "";
+  while (true) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    bytes += chunk.value.byteLength;
+    if (bytes > maxBytes) {
+      await reader.cancel().catch(() => void 0);
+      throw new RequestBodyTooLargeError(maxBytes);
+    }
+    text += decoder.decode(chunk.value, { stream: true });
+  }
+  return text + decoder.decode();
+}
+
+// src/documentation/worker/assistant-routes.ts
+var MAX_QUESTION_CHARS = 4e3;
+var MAX_HISTORY_MESSAGES = 12;
+var MAX_HISTORY_CHARS = 2e4;
+var MAX_REQUEST_BYTES = 128 * 1024;
+function registerDocumentationAssistantRoutes(app, resolveAuth, publicBasePath = "/docs", assetBasePath = "/_documentation") {
+  app.post(`${publicBasePath}/api/ai`, async (c) => {
+    const manifest = await loadDocumentationPublishedManifest(c.env, c.req.url, assetBasePath);
+    if (!manifest || manifest.assistant.access === "disabled") return c.notFound();
+    let authToken;
+    let publicClientKey;
+    if (manifest.assistant.access === "authenticated") {
+      const auth = await resolveAuth(c.req.raw, c.env);
+      if (!auth) return c.json({ error: "Sign in required" }, 401);
+      const header = c.req.header("Authorization") ?? "";
+      if (!header.startsWith("Bearer ")) return c.json({ error: "Sign in required" }, 401);
+      authToken = header.slice(7);
+    } else {
+      if (!c.env.APP_OWNER_JWT) {
+        return c.json({ error: "Public documentation assistant billing is not configured" }, 503);
+      }
+      publicClientKey = await documentationPublicClientKey(
+        c.req.header("CF-Connecting-IP") ?? "unknown"
+      );
+    }
+    const limitResult = publicClientKey ? await checkDocumentationPublicLimit(c.env, publicClientKey, "documentation-assistant") : void 0;
+    if (limitResult && !limitResult.ok) {
+      return c.json(
+        {
+          error: limitResult.status === 429 ? "Documentation assistant rate limit exceeded. Try again shortly." : "Documentation assistant is temporarily unavailable"
+        },
+        limitResult.status,
+        limitResult.status === 429 ? { "Retry-After": "60" } : void 0
+      );
+    }
+    let body = null;
+    try {
+      const raw = await readBoundedRequestText(c.req.raw, MAX_REQUEST_BYTES);
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        body = parsed;
+      }
+    } catch (error) {
+      if (error instanceof RequestBodyTooLargeError) {
+        return c.json({ error: `request exceeds ${MAX_REQUEST_BYTES} bytes` }, 413);
+      }
+      return c.json({ error: "request body must be valid JSON" }, 400);
+    }
+    const question = typeof body?.question === "string" ? body.question.trim() : "";
+    if (!question) return c.json({ error: "question is required" }, 400);
+    if (question.length > MAX_QUESTION_CHARS) {
+      return c.json({ error: `question exceeds ${MAX_QUESTION_CHARS} characters` }, 413);
+    }
+    const route = typeof body?.route === "string" && body.route.startsWith("/") ? body.route.slice(0, 500) : void 0;
+    let history;
+    try {
+      history = normalizeDocumentationAssistantHistory(body?.messages);
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : "messages are invalid" }, 400);
+    }
+    const corpusResult = await resolveDocumentationPublishedCorpus(
+      c.env,
+      manifest.sourceHash,
+      c.req.url,
+      assetBasePath
+    );
+    if (!corpusResult.ok) {
+      console.error("[documentation-assistant] corpus unavailable:", corpusResult.error);
+      return c.json({ error: "Documentation corpus is unavailable" }, 503);
+    }
+    const corpus = corpusResult.chunks;
+    const selectedModel = resolveDeepSpaceAgentModel(manifest.assistant.model, "documentation");
+    if (!selectedModel) {
+      console.error(
+        "[documentation-assistant] unsupported configured model:",
+        manifest.assistant.model
+      );
+      return c.json({ error: "Documentation assistant model is not supported" }, 503);
+    }
+    const diagnosticContext = {
+      profile: "documentation",
+      provider: selectedModel.provider,
+      modelId: selectedModel.modelId
+    };
+    let result;
+    try {
+      result = streamDeepSpaceAgent(c.env, {
+        profile: "documentation",
+        modelId: selectedModel.modelId,
+        ...authToken ? { authToken } : {},
+        system: buildDocumentationAssistantPrompt(manifest.name || c.env.APP_NAME, route),
+        messages: [...history, { role: "user", content: question }],
+        tools: buildDocumentationAssistantTools(corpus, publicBasePath),
+        abortSignal: c.req.raw.signal,
+        onError: ({ error }) => {
+          console.error(
+            `[documentation-assistant] stream error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+          );
+        }
+      }).result;
+    } catch (error) {
+      console.error(
+        `[documentation-assistant] agent unavailable: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+      );
+      return c.json({ error: "Documentation assistant is not configured" }, 503);
+    }
+    return result.toUIMessageStreamResponse({
+      sendReasoning: false,
+      onError: (error) => {
+        console.error(
+          `[documentation-assistant] response error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+        );
+        return "The documentation assistant could not complete this response.";
+      }
+    });
+  });
+}
+function normalizeDocumentationAssistantHistory(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) throw new TypeError("messages must be an array");
+  if (value.length > MAX_HISTORY_MESSAGES) {
+    throw new TypeError(`messages exceeds ${MAX_HISTORY_MESSAGES} turns`);
+  }
+  const messages = [];
+  let totalChars2 = 0;
+  for (const [index, item] of value.entries()) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new TypeError(`messages[${index}] must be an object`);
+    }
+    const candidate = item;
+    const expectedRole = index % 2 === 0 ? "user" : "assistant";
+    if (candidate.role !== expectedRole) {
+      throw new TypeError(`messages[${index}].role must be ${expectedRole}`);
+    }
+    const content = typeof candidate.content === "string" ? candidate.content.trim() : "";
+    if (!content) throw new TypeError(`messages[${index}].content is required`);
+    if (content.length > MAX_QUESTION_CHARS) {
+      throw new TypeError(`messages[${index}].content exceeds ${MAX_QUESTION_CHARS} characters`);
+    }
+    totalChars2 += content.length;
+    if (totalChars2 > MAX_HISTORY_CHARS) {
+      throw new TypeError(`messages exceeds ${MAX_HISTORY_CHARS} characters`);
+    }
+    messages.push({ role: expectedRole, content });
+  }
+  if (messages.length % 2 !== 0) {
+    throw new TypeError("messages must end with a completed assistant response");
+  }
+  return messages;
+}
+function registerDocumentationStaticRoutes(app, publicBasePath = "/docs", assetBasePath = "/_documentation") {
+  const serve = async (c, next) => {
+    const manifest = await loadDocumentationPublishedManifest(c.env, c.req.url, assetBasePath);
+    if (!manifest) return next();
+    const requestUrl = new URL(c.req.url);
+    const pathname = requestUrl.pathname;
+    const publishedPath = documentationRequestPath(pathname, publicBasePath);
+    let response;
+    let status;
+    if (publishedPath && isPublishedDocumentationRequest(publishedPath, manifest.routes, manifest.resources)) {
+      requestUrl.pathname = documentationAssetPath(publishedPath, manifest.resources, assetBasePath);
+      response = await fetchDocumentationAsset(c.env, c.req.raw, requestUrl, assetBasePath);
+      status = response.status;
+    } else {
+      response = new Response(null, { status: 404 });
+      status = 404;
+    }
+    if (status === 404) {
+      const url = new URL(c.req.url);
+      url.pathname = `${assetBasePath}/404.html`;
+      response = await fetchDocumentationAsset(c.env, c.req.raw, url, assetBasePath);
+      status = 404;
+    }
+    return secureDocumentationResponse(response, status, pathname);
+  };
+  app.get(publicBasePath || "/", serve);
+  app.get(`${publicBasePath}/*`, serve);
+}
+function isPublishedDocumentationRequest(publishedPath, routes, resources) {
+  return routes.includes(publishedPath) || resources.includes(publishedPath);
+}
+function documentationRequestPath(pathname, publicBasePath) {
+  const logical = pathname === publicBasePath || !publicBasePath && pathname === "/" ? "/" : pathname.slice(publicBasePath.length) || "/";
+  const clean = logical === "/" ? "/" : logical.replace(/\/$/, "");
+  return canonicalNativeDocumentationRequestPath(clean);
+}
+async function fetchDocumentationAsset(env, request, initialUrl, assetBasePath) {
+  let url = initialUrl;
+  for (let redirects = 0; redirects < 3; redirects++) {
+    const response = await env.ASSETS.fetch(new Request(url, request));
+    const location = response.headers.get("Location");
+    if (response.status < 300 || response.status >= 400 || !location) return response;
+    const next = new URL(location, url);
+    if (next.origin !== url.origin || !next.pathname.startsWith(`${assetBasePath}/`)) {
+      return new Response("Invalid documentation asset redirect", { status: 502 });
+    }
+    await response.body?.cancel();
+    url = next;
+  }
+  return new Response("Documentation asset redirect loop", { status: 508 });
+}
+function documentationAssetPath(publishedPath, resources, assetBasePath) {
+  if (publishedPath === "/") return `${assetBasePath}/index.html`;
+  return resources.includes(publishedPath) ? `${assetBasePath}${publishedPath}` : `${assetBasePath}${publishedPath}/index.html`;
+}
+function secureDocumentationResponse(response, status, pathname) {
+  const headers = new Headers(response.headers);
+  if (status !== 404 && pathname.endsWith(".md")) {
+    headers.set("Content-Type", "text/markdown; charset=utf-8");
+  }
+  if (headers.get("Content-Type")?.toLowerCase().includes("text/html")) {
+    const cacheControl = headers.get("Cache-Control") ?? "public, max-age=0, must-revalidate";
+    if (!/(?:^|,)\s*no-transform(?:\s*,|$)/i.test(cacheControl)) {
+      headers.set("Cache-Control", `${cacheControl}, no-transform`);
+    }
+  }
+  headers.set("X-Content-Type-Options", "nosniff");
+  headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+  headers.set(
+    "Content-Security-Policy",
+    "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data: https:; connect-src 'self' https:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'"
+  );
+  return new Response(response.body, { status, headers });
+}
+
+// src/documentation/text.ts
+function documentationSubject(name) {
+  const normalized = name.trim();
+  if (!normalized || /^documentation$/i.test(normalized)) return "documentation";
+  return /(?:\bdocs?|documentation)$/i.test(normalized) ? normalized : `${normalized} documentation`;
+}
+
+// src/documentation/worker/mcp/protocol.ts
+var MCP_SERVER_VERSION = "1.0.0";
+var CURRENT_PROTOCOL_VERSION = "2025-11-25";
+var SUPPORTED_PROTOCOL_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PROTOCOL_VERSION, "2025-06-18", "2025-03-26"]);
+function initializeResponse(request) {
+  const params = objectValue(request.params);
+  const requested = typeof params?.protocolVersion === "string" ? params.protocolVersion : CURRENT_PROTOCOL_VERSION;
+  const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : CURRENT_PROTOCOL_VERSION;
+  return mcpResult(request.id, {
+    protocolVersion,
+    capabilities: {
+      tools: { listChanged: false },
+      resources: { subscribe: false, listChanged: false }
+    },
+    serverInfo: {
+      name: "DeepSpace Documentation",
+      title: "DeepSpace documentation",
+      version: MCP_SERVER_VERSION
+    },
+    instructions: "Search the published documentation before answering, then read exact pages when full context is needed."
+  });
+}
+function hasValidOrigin(request) {
+  const origin = request.headers.get("Origin");
+  if (!origin) return true;
+  try {
+    return new URL(origin).origin === new URL(request.url).origin;
+  } catch {
+    return false;
+  }
+}
+function parseRequest(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return { ok: false, message: "Invalid JSON" };
+  }
+  const candidate = objectValue(value);
+  if (!candidate || candidate.jsonrpc !== "2.0" || typeof candidate.method !== "string") {
+    return { ok: false, message: "Invalid JSON-RPC request" };
+  }
+  if (candidate.id !== void 0 && candidate.id !== null && typeof candidate.id !== "string" && typeof candidate.id !== "number")
+    return { ok: false, message: "Invalid JSON-RPC id" };
+  return {
+    ok: true,
+    request: {
+      jsonrpc: "2.0",
+      method: candidate.method,
+      ...candidate.id !== void 0 ? { id: candidate.id } : {},
+      ...candidate.params !== void 0 ? { params: candidate.params } : {}
+    }
+  };
+}
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function toolResult(id, value) {
+  return mcpResult(id, {
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    structuredContent: value,
+    isError: false
+  });
+}
+function toolError(id, message) {
+  return mcpResult(id, {
+    content: [{ type: "text", text: message }],
+    isError: true
+  });
+}
+function mcpResult(id, result) {
+  return jsonResponse({ jsonrpc: "2.0", id, result });
+}
+function mcpError(id, code, message, status = 200, headers) {
+  return jsonResponse({ jsonrpc: "2.0", id, error: { code, message } }, status, headers);
+}
+function jsonResponse(value, status = 200, headers) {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      ...mcpSecurityHeaders(),
+      ...headers
+    }
+  });
+}
+function mcpSecurityHeaders() {
+  return {
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer"
+  };
+}
+
+// src/documentation/worker/mcp/tools.ts
+var DOCUMENTATION_TOOLS = [
+  {
+    name: "documentation_search",
+    title: "Search documentation",
+    description: "Search the published documentation and return ranked, linked excerpts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", minLength: 2, maxLength: 300 },
+        limit: { type: "integer", minimum: 1, maximum: 10, default: 6 }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    outputSchema: {
+      type: "object",
+      properties: { results: { type: "array" } },
+      required: ["results"]
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
+  {
+    name: "documentation_read",
+    title: "Read documentation page",
+    description: "Read one complete published documentation page as Markdown.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        route: { type: "string", minLength: 1, maxLength: 500, pattern: "^/" }
+      },
+      required: ["route"],
+      additionalProperties: false
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        route: { type: "string" },
+        title: { type: "string" },
+        url: { type: "string" },
+        markdown: { type: "string" }
+      },
+      required: ["route", "title", "url", "markdown"]
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }
+];
+async function callDocumentationTool(rawRequest, request, corpus, env, basePath = "/docs", assetBasePath = "/_documentation") {
+  const params = objectValue(request.params);
+  const name = typeof params?.name === "string" ? params.name : "";
+  const args = objectValue(params?.arguments) ?? {};
+  const origin = new URL(rawRequest.url).origin;
+  if (name === "documentation_search") {
+    const query = typeof args.query === "string" ? args.query.trim() : "";
+    const limit = args.limit === void 0 ? 6 : args.limit;
+    if (query.length < 2 || query.length > 300 || !Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 10) {
+      return mcpError(request.id, -32602, "Invalid documentation_search arguments");
+    }
+    const value = {
+      results: searchDocumentationCorpus(corpus, query, Number(limit)).map((result) => ({
+        ...result,
+        url: new URL(documentationPublicPath(basePath, result.route), origin).toString()
+      }))
+    };
+    return toolResult(request.id, value);
+  }
+  if (name === "documentation_read") {
+    const route = typeof args.route === "string" ? args.route.trim() : "";
+    if (!route.startsWith("/") || route.length > 500) {
+      return mcpError(request.id, -32602, "Invalid documentation_read arguments");
+    }
+    try {
+      const page = await readDocumentationPublishedPage(
+        env,
+        corpus,
+        route,
+        rawRequest.url,
+        assetBasePath
+      );
+      if (!page) return toolError(request.id, `No published documentation page exists at ${route}`);
+      return toolResult(request.id, {
+        ...page,
+        url: new URL(documentationPublicPath(basePath, page.route), origin).toString()
+      });
+    } catch (error) {
+      console.error("[documentation-mcp] page unavailable:", error);
+      return toolError(request.id, "The documentation page could not be read");
+    }
+  }
+  return mcpError(request.id, -32602, `Unknown documentation tool: ${name || "<missing>"}`);
+}
+
+// src/documentation/worker/mcp-routes.ts
+var MAX_REQUEST_CHARS = 64e3;
+var MAX_REQUEST_BYTES2 = MAX_REQUEST_CHARS * 4;
+var MAX_SKILL_CHARS = 256e3;
+var DOCUMENTATION_BASE_PATH = "/docs";
+function registerDocumentationMcpRoutes(app, publicBasePath = DOCUMENTATION_BASE_PATH, assetBasePath = "/_documentation") {
+  const mcpPath = documentationPublicPath(publicBasePath, "/mcp");
+  app.get(mcpPath, async (c) => {
+    if (!await publicManifest(c.req.raw, c.env, assetBasePath)) return c.notFound();
+    return new Response(null, {
+      status: 405,
+      headers: { Allow: "POST", ...mcpSecurityHeaders() }
+    });
+  });
+  app.post(mcpPath, async (c) => {
+    const manifest = await publicManifest(c.req.raw, c.env, assetBasePath);
+    if (!manifest) return c.notFound();
+    if (!hasValidOrigin(c.req.raw)) {
+      return mcpError(null, -32e3, "Invalid Origin", 403);
+    }
+    let raw;
+    try {
+      raw = await readBoundedRequestText(c.req.raw, MAX_REQUEST_BYTES2);
+    } catch (error) {
+      if (error instanceof RequestBodyTooLargeError) {
+        return mcpError(null, -32600, `Request exceeds ${MAX_REQUEST_BYTES2} bytes`, 413);
+      }
+      return mcpError(null, -32700, "Unable to read request body", 400);
+    }
+    if (raw.length > MAX_REQUEST_CHARS) {
+      return mcpError(null, -32600, `Request exceeds ${MAX_REQUEST_CHARS} characters`, 413);
+    }
+    const parsed = parseRequest(raw);
+    if (!parsed.ok) return mcpError(null, -32700, parsed.message, 400);
+    const request = parsed.request;
+    if (request.method !== "initialize") {
+      const protocolVersion = c.req.header("MCP-Protocol-Version");
+      if (protocolVersion && !SUPPORTED_PROTOCOL_VERSIONS.has(protocolVersion)) {
+        return mcpError(request.id ?? null, -32600, "Unsupported MCP-Protocol-Version", 400);
+      }
+    }
+    const requestId = request.id;
+    if (requestId === void 0) return new Response(null, { status: 202 });
+    const requestWithId = { ...request, id: requestId };
+    if (request.method === "initialize") return initializeResponse(requestWithId);
+    if (request.method === "ping") return mcpResult(requestId, {});
+    if (request.method === "tools/list") {
+      return mcpResult(requestId, { tools: DOCUMENTATION_TOOLS });
+    }
+    if (request.method === "resources/list") {
+      return mcpResult(requestId, {
+        resources: [skillResource(c.req.raw, manifest, publicBasePath)]
+      });
+    }
+    if (request.method === "resources/read") {
+      return readSkillResource(
+        c.req.raw,
+        requestWithId,
+        manifest,
+        c.env,
+        publicBasePath,
+        assetBasePath
+      );
+    }
+    if (request.method !== "tools/call") {
+      return mcpError(requestId, -32601, `Method not found: ${request.method}`);
+    }
+    const clientKey = await documentationPublicClientKey(
+      c.req.header("CF-Connecting-IP") ?? "unknown"
+    );
+    const limitResult = await checkDocumentationPublicLimit(c.env, clientKey, "documentation-mcp");
+    if (!limitResult.ok) {
+      return mcpError(
+        requestId,
+        limitResult.status === 429 ? -32029 : -32002,
+        limitResult.status === 429 ? "Documentation tool rate limit exceeded. Try again shortly." : "Documentation tools are temporarily unavailable",
+        limitResult.status,
+        limitResult.status === 429 ? { "Retry-After": "60" } : void 0
+      );
+    }
+    const corpusResult = await resolveDocumentationPublishedCorpus(
+      c.env,
+      manifest.sourceHash,
+      c.req.url,
+      assetBasePath
+    );
+    if (!corpusResult.ok) {
+      console.error("[documentation-mcp] corpus unavailable:", corpusResult.error);
+      return mcpError(requestId, -32002, "Documentation corpus is unavailable", 503);
+    }
+    const corpus = corpusResult.chunks;
+    return callDocumentationTool(
+      c.req.raw,
+      requestWithId,
+      corpus,
+      c.env,
+      publicBasePath,
+      assetBasePath
+    );
+  });
+  for (const path of [
+    "/.well-known/mcp",
+    "/.well-known/mcp.json",
+    "/.well-known/mcp/server-card.json"
+  ]) {
+    app.get(documentationPublicPath(publicBasePath, path), async (c) => {
+      const manifest = await publicManifest(c.req.raw, c.env, assetBasePath);
+      if (!manifest) return c.notFound();
+      return discoveryResponse(c.req.raw, manifest, publicBasePath);
+    });
+  }
+  app.get(
+    documentationPublicPath(publicBasePath, "/.well-known/mcp/server-cards.json"),
+    async (c) => {
+      const manifest = await publicManifest(c.req.raw, c.env, assetBasePath);
+      if (!manifest) return c.notFound();
+      return jsonResponse({ servers: [serverCard(c.req.raw, manifest, publicBasePath)] }, 200, {
+        "Cache-Control": "public, max-age=300"
+      });
+    }
+  );
+}
+async function readSkillResource(rawRequest, request, manifest, env, publicBasePath, assetBasePath) {
+  const params = objectValue(request.params);
+  const requestedUri = typeof params?.uri === "string" ? params.uri : "";
+  const resource = skillResource(rawRequest, manifest, publicBasePath);
+  if (requestedUri !== resource.uri) {
+    return mcpError(request.id, -32602, "Unknown documentation resource");
+  }
+  const assetUrl = new URL(`${assetBasePath}/skill.md`, rawRequest.url);
+  const response = await env.ASSETS.fetch(new Request(assetUrl, { method: "GET" }));
+  if (!response.ok) return mcpError(request.id, -32002, "Documentation skill is unavailable", 503);
+  const text = await response.text();
+  if (text.length > MAX_SKILL_CHARS) {
+    return mcpError(request.id, -32002, "Documentation skill exceeds the published size limit", 503);
+  }
+  return mcpResult(request.id, {
+    contents: [{ uri: resource.uri, mimeType: resource.mimeType, text }]
+  });
+}
+function skillResource(request, manifest, publicBasePath) {
+  const subject = documentationSubject(manifest.name);
+  return {
+    uri: new URL(`${publicBasePath}/skill.md`, request.url).toString(),
+    name: `${subject} skill`,
+    title: `Use ${manifest.name}`,
+    description: `Agent instructions grounded in the published ${subject}.`,
+    mimeType: "text/markdown"
+  };
+}
+async function publicManifest(request, env, assetBasePath) {
+  const manifest = await loadDocumentationPublishedManifest(env, request.url, assetBasePath);
+  return manifest?.mcp.access === "public" ? manifest : null;
+}
+function discoveryResponse(request, manifest, publicBasePath) {
+  return jsonResponse(serverCard(request, manifest, publicBasePath), 200, {
+    "Cache-Control": "public, max-age=300"
+  });
+}
+function serverCard(request, manifest, publicBasePath) {
+  return {
+    name: manifest.name,
+    description: `Search and read the published ${documentationSubject(manifest.name)}.`,
+    version: MCP_SERVER_VERSION,
+    protocolVersion: CURRENT_PROTOCOL_VERSION,
+    transport: {
+      type: "streamable-http",
+      url: new URL(`${publicBasePath}/mcp`, request.url).toString()
+    },
+    authentication: { required: false },
+    capabilities: {
+      tools: DOCUMENTATION_TOOLS.map(({ name, title, description }) => ({
+        name,
+        title,
+        description
+      })),
+      resources: [skillResource(request, manifest, publicBasePath)]
+    }
+  };
+}
+
+// src/documentation/worker/routes.ts
+function registerDeepSpaceDocumentation(app, options) {
+  app.use(
+    "*",
+    async (c, next) => isPrivateDocumentationPath(new URL(c.req.url).pathname) ? c.notFound() : next()
+  );
+  const domains = new Set(
+    options.config?.domains?.map((domain) => domain.trim().toLowerCase()) ?? []
+  );
+  if (domains.size) {
+    const root = new Hono();
+    registerDocumentationAssistantRoutes(root, options.resolveAuth, "", "/_documentation-root");
+    registerDocumentationMcpRoutes(root, "", "/_documentation-root");
+    registerDocumentationStaticRoutes(root, "", "/_documentation-root");
+    app.all("*", (c, next) => {
+      const url = new URL(c.req.url);
+      if (!domains.has(url.hostname.toLowerCase()) || url.pathname === "/api/auth" || url.pathname.startsWith("/api/auth/"))
+        return next();
+      return root.fetch(c.req.raw, c.env);
+    });
+  }
+  registerDocumentationAssistantRoutes(app, options.resolveAuth);
+  registerDocumentationMcpRoutes(app);
+  registerDocumentationStaticRoutes(app);
+}
+function isPrivateDocumentationPath(pathname) {
+  let decoded = pathname;
+  for (let round = 0; round < 3; round += 1) {
+    const next = decoded.replace(
+      /%([0-9a-f]{2})/giu,
+      (_sequence, hex) => String.fromCharCode(Number.parseInt(hex, 16))
+    );
+    if (next === decoded) break;
+    decoded = next;
+  }
+  return /^\/_documentation(?:-root)?(?:\/|$)/u.test(decoded.replace(/\/{2,}/gu, "/"));
+}
+
 // src/server/auth/jwtVerifier.ts
 import { importSPKI, jwtVerify } from "jose";
 
@@ -7581,7 +8988,7 @@ function shouldThrottleClientError(now = Date.now()) {
   windowCount += 1;
   return windowCount > THROTTLE_MAX;
 }
-function jsonResponse(body, status) {
+function jsonResponse2(body, status) {
   return new Response(JSON.stringify(body), {
     status,
     headers: { "Content-Type": "application/json" }
@@ -7597,16 +9004,16 @@ async function handleClientErrorReport(request) {
   }
   const declared = Number(request.headers.get("content-length"));
   if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
-    return jsonResponse({ error: "payload_too_large" }, 413);
+    return jsonResponse2({ error: "payload_too_large" }, 413);
   }
   let body;
   try {
     body = await request.json();
   } catch {
-    return jsonResponse({ error: "invalid_json" }, 400);
+    return jsonResponse2({ error: "invalid_json" }, 400);
   }
   const report = normalizeClientErrorReport(body);
-  if (!report) return jsonResponse({ error: "invalid_report" }, 400);
+  if (!report) return jsonResponse2({ error: "invalid_report" }, 400);
   console.error(clientErrorToLogLine(report));
   return new Response(null, { status: 204 });
 }
@@ -7649,11 +9056,17 @@ export {
   COST_RATES,
   CanvasRoom,
   CronRoom,
+  DEEPSPACE_AGENT_PROFILES,
+  DEEPSPACE_AI_DEFAULTS,
+  DEEPSPACE_AI_MODELS,
+  DEEPSPACE_MODEL_CATALOG_PROVENANCE,
   DEFAULT_CONTEXT_CONFIG,
   DEFAULT_DO_MANIFEST,
   DEFAULT_QUERY_LIMIT,
   DEPLOYED_APPS_DEFAULTS,
   DIRECTORY_SCHEMAS,
+  DeepSpaceAgentModelError,
+  DeepSpaceAgentProfileError,
   GLOBAL_DO_TYPES,
   GLOBAL_DO_TYPE_NAMES,
   GameRoom,
@@ -7722,6 +9135,7 @@ export {
   createScopedR2Handler,
   dataToColumnValues,
   decodeJwtPayload,
+  deepSpaceAgentErrorSummary,
   deleteChatCascade,
   dispatch,
   encode,
@@ -7731,6 +9145,7 @@ export {
   encodeUpdate,
   enqueueJob,
   getChat,
+  getDeepSpaceAIModel,
   getGlobalDOSchemas,
   getGlobalDOType,
   getMessageType,
@@ -7745,6 +9160,7 @@ export {
   isTestAccountEmail,
   isTestAccountTier,
   lintSchema,
+  listDeepSpaceAgentModels,
   loadMessages,
   makeDefaultSummarizer,
   matchOrigin,
@@ -7760,13 +9176,16 @@ export {
   readVarUint,
   readVarUint8Array,
   registerClientErrorRoute,
+  registerDeepSpaceDocumentation,
   registryErrorJson,
   registryStub,
   resolveAppName,
   resolveColumn,
+  resolveDeepSpaceAgentModel,
   rowToData,
   runMigrations,
   serverBuild,
+  streamDeepSpaceAgent,
   timingSafeEqualHex,
   timingSafeEqualStrings,
   toUint8Array,