deepspace 0.9.2 → 0.10.0

package/dist/server.js

@@ -475,7 +475,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",
@@ -484,12 +484,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;
   }
@@ -611,6 +611,270 @@ function createDeepSpaceAI(env, provider, options = {}) {
   }
 }
 
+// src/server/utils/agent.ts
+import {
+  stepCountIs,
+  streamText
+} from "ai";
+
+// src/shared/ai-models.ts
+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: 5,
+    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: ["docs_search", "docs_read"]
+  }
+};
+function getDeepSpaceAIModel(modelId) {
+  if (typeof modelId !== "string") return null;
+  return DEEPSPACE_AI_MODELS.find((model) => model.id === modelId) ?? null;
+}
+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/agent.ts
+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: {} };
@@ -1047,10 +1311,11 @@ function formatTranscript(messages) {
 }
 function makeDefaultSummarizer(env, options = {}) {
   return async (messages) => {
-    const anthropic = createDeepSpaceAI(env, "anthropic", { authToken: options.authToken });
+    const model = getDeepSpaceAIModel(DEEPSPACE_AI_DEFAULTS.summarization);
+    if (!model) throw new Error("DeepSpace summarization model is missing from the catalog");
+    const provider = createDeepSpaceAI(env, model.provider, { authToken: options.authToken });
     const { text } = await generateText({
-      // Stable alias — provider bug-fix snapshots roll forward without code change.
-      model: anthropic("claude-haiku-4-5"),
+      model: provider(model.id),
       // 2500 gives the model room to finish a sentence after hitting the
       // "under 2000 tokens" soft limit in the prompt.
       maxOutputTokens: 2500,
@@ -1062,7 +1327,7 @@ function makeDefaultSummarizer(env, options = {}) {
 }
 
 // src/server/utils/chat-history.ts
-async function executeTool(stub, userId, tool2, params) {
+async function executeTool(stub, userId, tool3, params) {
   const res = await stub.fetch(new Request("https://internal/api/tools/execute", {
     method: "POST",
     headers: {
@@ -1070,11 +1335,11 @@ async function executeTool(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;
 }
@@ -1186,6 +1451,1002 @@ async function appendMessage(stub, msg) {
   });
 }
 
+// src/server/utils/docs-assistant.ts
+import { tool as tool2 } from "ai";
+import { z } from "zod/v4";
+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 parseDocsCorpus(value) {
+  if (!Array.isArray(value)) throw new Error("Docs assistant index must be an array");
+  if (value.length > MAX_CHUNKS) {
+    throw new Error(`Docs 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(`Docs 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(`Docs assistant chunk ${index} has invalid required fields`);
+    }
+    if (chunk.text.length > MAX_CHUNK_CHARS) {
+      throw new Error(`Docs assistant chunk ${chunk.id} exceeds ${MAX_CHUNK_CHARS} characters`);
+    }
+    totalChars2 += chunk.text.length;
+    if (totalChars2 > MAX_CORPUS_CHARS) {
+      throw new Error(`Docs 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 searchDocsCorpus(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 readDocsRoute(corpus, route) {
+  const normalizedRoute = normalizeDocsRoute(route);
+  return corpus.filter((chunk) => chunk.route === normalizedRoute).slice(0, 12).map(({ route: chunkRoute, title, heading, text }) => ({
+    route: chunkRoute,
+    title,
+    ...heading ? { heading } : {},
+    text
+  }));
+}
+function buildDocsAssistantTools(corpus) {
+  return {
+    docs_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: searchDocsCorpus(corpus, query, limit ?? 6)
+      })
+    }),
+    docs_read: tool2({
+      description: "Read bounded source chunks for one exact documentation route returned by docs_search.",
+      inputSchema: z.object({ route: z.string().trim().startsWith("/").max(500) }),
+      execute: async ({ route }) => ({
+        route: normalizeDocsRoute(route),
+        chunks: readDocsRoute(corpus, route)
+      })
+    })
+  };
+}
+function buildDocsAssistantPrompt(appName, currentRoute) {
+  return [
+    `You are the public documentation assistant for "${appName}" on DeepSpace.`,
+    "Answer only from the documentation available through docs_search and docs_read.",
+    "Search before answering unless the user is only greeting you.",
+    "Use docs_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 ${normalizeDocsRoute(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 "docs";
+  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 normalizeDocsRoute(value) {
+  let route = `/${value}`.replace(/\/{2,}/g, "/");
+  if (route.length > 1) route = route.replace(/\/$/, "");
+  return route;
+}
+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/server/utils/docs-assistant-limiter.ts
+var WINDOW_MS = 6e4;
+var CLIENT_REQUESTS_PER_WINDOW = 12;
+var APP_REQUESTS_PER_WINDOW = 120;
+var MAX_CONCURRENT_REQUESTS = 4;
+var LEASE_TTL_MS = 2 * 6e4;
+var DocsAssistantLimiter = class {
+  sql;
+  constructor(state) {
+    this.sql = state.storage.sql;
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS request_windows (
+        scope TEXT NOT NULL,
+        client_key TEXT NOT NULL,
+        window INTEGER NOT NULL,
+        count INTEGER NOT NULL,
+        PRIMARY KEY (scope, client_key, window)
+      );
+      CREATE TABLE IF NOT EXISTS leases (
+        id TEXT PRIMARY KEY,
+        expires_at INTEGER NOT NULL
+      );
+    `);
+  }
+  async fetch(request) {
+    const url = new URL(request.url);
+    if (request.method !== "POST") return Response.json({ error: "method_not_allowed" }, { status: 405 });
+    if (url.pathname === "/acquire") return this.acquire(request);
+    if (url.pathname === "/release") return this.release(request);
+    return Response.json({ error: "not_found" }, { status: 404 });
+  }
+  async acquire(request) {
+    const body = await request.json().catch(() => null);
+    if (!body || typeof body.clientKey !== "string" || body.clientKey.length !== 64) {
+      return Response.json({ error: "invalid_client_key" }, { status: 400 });
+    }
+    const now = Date.now();
+    const window = Math.floor(now / WINDOW_MS);
+    this.sql.exec("DELETE FROM request_windows WHERE window < ?", window - 1);
+    this.sql.exec("DELETE FROM leases WHERE expires_at <= ?", now);
+    if (!this.consumeWindow("client", body.clientKey, window, CLIENT_REQUESTS_PER_WINDOW)) {
+      return Response.json({ ok: false, reason: "client_rate" }, { status: 429 });
+    }
+    if (!this.consumeWindow("app", "all", window, APP_REQUESTS_PER_WINDOW)) {
+      return Response.json({ ok: false, reason: "app_rate" }, { status: 429 });
+    }
+    const concurrent = this.sql.exec("SELECT COUNT(*) AS count FROM leases").one().count;
+    if (concurrent >= MAX_CONCURRENT_REQUESTS) {
+      return Response.json({ ok: false, reason: "app_concurrency" }, { status: 429 });
+    }
+    const leaseId = crypto.randomUUID();
+    this.sql.exec("INSERT INTO leases (id, expires_at) VALUES (?, ?)", leaseId, now + LEASE_TTL_MS);
+    return Response.json({ ok: true, leaseId });
+  }
+  async release(request) {
+    const body = await request.json().catch(() => null);
+    if (!body || typeof body.leaseId !== "string") {
+      return Response.json({ error: "invalid_lease_id" }, { status: 400 });
+    }
+    this.sql.exec("DELETE FROM leases WHERE id = ?", body.leaseId);
+    return Response.json({ ok: true });
+  }
+  consumeWindow(scope, clientKey, window, limit) {
+    const existing = this.sql.exec(
+      "SELECT count FROM request_windows WHERE scope = ? AND client_key = ? AND window = ?",
+      scope,
+      clientKey,
+      window
+    ).toArray()[0]?.count ?? 0;
+    if (existing >= limit) return false;
+    this.sql.exec(
+      `INSERT INTO request_windows (scope, client_key, window, count)
+       VALUES (?, ?, ?, 1)
+       ON CONFLICT(scope, client_key, window) DO UPDATE SET count = count + 1`,
+      scope,
+      clientKey,
+      window
+    );
+    return true;
+  }
+};
+
+// src/server/utils/docs-published-corpus.ts
+var cachedCorpus;
+async function loadDocsPublishedManifest(env, requestUrl = "https://assets.local/") {
+  const response = await env.ASSETS.fetch(new URL("/_docs/manifest.json", requestUrl).toString());
+  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);
+  if (typeof manifest.sourceHash !== "string" || typeof manifest.name !== "string" || !assistant) return null;
+  return {
+    sourceHash: manifest.sourceHash,
+    name: manifest.name,
+    assistant,
+    // Older docs artifacts did not carry an MCP policy. Fail closed until the
+    // docs bundle is rebuilt by an MCP-aware SDK release.
+    mcp: parseMcpPolicy(manifest.mcp) ?? { access: "disabled" }
+  };
+}
+async function loadDocsPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/") {
+  if (cachedCorpus?.sourceHash === sourceHash) return cachedCorpus.chunks;
+  const response = await env.ASSETS.fetch(
+    new URL("/_docs/assistant-index.json", requestUrl).toString()
+  );
+  if (!response.ok) throw new Error(`assistant-index.json returned ${response.status}`);
+  const chunks = parseDocsCorpus(await response.json());
+  cachedCorpus = { sourceHash, chunks };
+  return chunks;
+}
+async function resolveDocsPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/") {
+  try {
+    return { ok: true, chunks: await loadDocsPublishedCorpus(env, sourceHash, requestUrl) };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+async function readDocsPublishedPage(env, corpus, requestedRoute, requestUrl = "https://assets.local/") {
+  const route = normalizeDocsRoute(requestedRoute.split("#", 1)[0] ?? "/");
+  const firstChunk = corpus.find((chunk) => chunk.route === route);
+  if (!firstChunk) return null;
+  const pathname = route === "/" ? "/_docs/index.md" : `/_docs${route}.md`;
+  const response = await env.ASSETS.fetch(new URL(pathname, requestUrl).toString());
+  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/server/utils/docs-public-limiter.ts
+async function docsPublicClientKey(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 acquireDocsPublicLease(env, clientKey, logPrefix) {
+  if (!env.DOCS_ASSISTANT_LIMITER) return { ok: false, status: 503 };
+  const id = env.DOCS_ASSISTANT_LIMITER.idFromName(env.DEEPSPACE_APP_ID);
+  const stub = env.DOCS_ASSISTANT_LIMITER.get(id);
+  const response = await stub.fetch("https://docs-limiter/acquire", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ clientKey })
+  }).catch((error) => {
+    console.error(`[${logPrefix}] limiter unavailable:`, error);
+    return null;
+  });
+  if (!response?.ok) {
+    return { ok: false, status: response?.status === 429 ? 429 : 503 };
+  }
+  const body = await response.json().catch(() => null);
+  if (!body || typeof body.leaseId !== "string") return { ok: false, status: 503 };
+  return { ok: true, lease: { leaseId: body.leaseId, stub } };
+}
+async function releaseDocsPublicLease(lease, logPrefix) {
+  if (!lease) return;
+  await lease.stub.fetch("https://docs-limiter/release", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ leaseId: lease.leaseId })
+  }).catch((error) => console.error(`[${logPrefix}] limiter release failed:`, error));
+}
+
+// src/server/utils/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/server/utils/docs-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 registerDocsAssistantRoutes(app, resolveAuth) {
+  app.post("/api/ai/docs", async (c) => {
+    if (c.req.header("x-deepspace-surface") !== "docs") return c.notFound();
+    const manifest = await loadDocsPublishedManifest(c.env, c.req.url);
+    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 docsPublicClientKey(c.req.header("CF-Connecting-IP") ?? "unknown");
+    }
+    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 = normalizeDocsAssistantHistory(body?.messages);
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : "messages are invalid" }, 400);
+    }
+    const corpusResult = await resolveDocsPublishedCorpus(c.env, manifest.sourceHash, c.req.url);
+    if (!corpusResult.ok) {
+      console.error("[docs-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("[docs-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
+    };
+    if (publicClientKey && !c.env.DOCS_ASSISTANT_LIMITER) {
+      return c.json({ error: "Documentation assistant rate limiting is not configured" }, 503);
+    }
+    const leaseResult = publicClientKey ? await acquireDocsPublicLease(c.env, publicClientKey, "docs-assistant") : void 0;
+    if (leaseResult && !leaseResult.ok) {
+      return c.json(
+        {
+          error: leaseResult.status === 429 ? "Documentation assistant rate limit exceeded. Try again shortly." : "Documentation assistant is temporarily unavailable"
+        },
+        leaseResult.status,
+        leaseResult.status === 429 ? { "Retry-After": "60" } : void 0
+      );
+    }
+    const lease = leaseResult?.ok ? leaseResult.lease : void 0;
+    let released = false;
+    const releaseLease = async () => {
+      if (!lease || released) return;
+      released = true;
+      await releaseDocsPublicLease(lease, "docs-assistant");
+    };
+    let result;
+    try {
+      result = streamDeepSpaceAgent(c.env, {
+        profile: "documentation",
+        modelId: selectedModel.modelId,
+        ...authToken ? { authToken } : {},
+        system: buildDocsAssistantPrompt(manifest.name || c.env.APP_NAME, route),
+        messages: [...history, { role: "user", content: question }],
+        tools: buildDocsAssistantTools(corpus),
+        abortSignal: c.req.raw.signal,
+        onAbort: () => releaseLease(),
+        onFinish: releaseLease,
+        onError: ({ error }) => {
+          console.error(
+            `[docs-assistant] stream error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+          );
+          void releaseLease();
+        }
+      }).result;
+    } catch (error) {
+      console.error(
+        `[docs-assistant] agent unavailable: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+      );
+      await releaseLease();
+      return c.json({ error: "Documentation assistant is not configured" }, 503);
+    }
+    return result.toUIMessageStreamResponse({
+      sendReasoning: false,
+      onError: (error) => {
+        console.error(
+          `[docs-assistant] response error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+        );
+        void releaseLease();
+        return "The documentation assistant could not complete this response.";
+      }
+    });
+  });
+}
+var docsAssistantErrorSummary = deepSpaceAgentErrorSummary;
+function normalizeDocsAssistantHistory(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 registerDocsStaticRoutes(app) {
+  app.get("/_docs/*", async (c) => {
+    const pathname = new URL(c.req.url).pathname;
+    let response = await c.env.ASSETS.fetch(c.req.raw);
+    let status = response.status;
+    if (status === 404) {
+      const url = new URL(c.req.url);
+      url.pathname = "/_docs/404.html";
+      response = await c.env.ASSETS.fetch(new Request(url.toString(), c.req.raw));
+      status = 404;
+    }
+    return secureDocsResponse(response, status, pathname);
+  });
+}
+function secureDocsResponse(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/server/utils/docs-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 Docs",
+      title: "DeepSpace documentation",
+      version: MCP_SERVER_VERSION
+    },
+    instructions: "Search the published docs 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/server/utils/docs-mcp/tools.ts
+var DOCS_TOOLS = [
+  {
+    name: "docs_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: "docs_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 callDocsTool(rawRequest, request, corpus, env) {
+  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 === "docs_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 docs_search arguments");
+    }
+    const value = {
+      results: searchDocsCorpus(corpus, query, Number(limit)).map((result) => ({
+        ...result,
+        url: new URL(result.route, origin).toString()
+      }))
+    };
+    return toolResult(request.id, value);
+  }
+  if (name === "docs_read") {
+    const route = typeof args.route === "string" ? args.route.trim() : "";
+    if (!route.startsWith("/") || route.length > 500) {
+      return mcpError(request.id, -32602, "Invalid docs_read arguments");
+    }
+    try {
+      const page = await readDocsPublishedPage(env, corpus, route, rawRequest.url);
+      if (!page) return toolError(request.id, `No published documentation page exists at ${route}`);
+      return toolResult(request.id, {
+        ...page,
+        url: new URL(page.route, origin).toString()
+      });
+    } catch (error) {
+      console.error("[docs-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/server/utils/docs-mcp-routes.ts
+var MAX_REQUEST_CHARS = 64e3;
+var MAX_REQUEST_BYTES2 = MAX_REQUEST_CHARS * 4;
+var MAX_SKILL_CHARS = 256e3;
+function registerDocsMcpRoutes(app) {
+  app.get("/mcp", async (c) => {
+    if (!await publicManifest(c.req.raw, c.env)) return c.notFound();
+    return new Response(null, {
+      status: 405,
+      headers: { Allow: "POST", ...mcpSecurityHeaders() }
+    });
+  });
+  app.post("/mcp", async (c) => {
+    const manifest = await publicManifest(c.req.raw, c.env);
+    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: DOCS_TOOLS });
+    }
+    if (request.method === "resources/list") {
+      return mcpResult(requestId, { resources: [skillResource(c.req.raw, manifest)] });
+    }
+    if (request.method === "resources/read") {
+      return readSkillResource(c.req.raw, requestWithId, manifest, c.env);
+    }
+    if (request.method !== "tools/call") {
+      return mcpError(requestId, -32601, `Method not found: ${request.method}`);
+    }
+    const corpusResult = await resolveDocsPublishedCorpus(c.env, manifest.sourceHash, c.req.url);
+    if (!corpusResult.ok) {
+      console.error("[docs-mcp] corpus unavailable:", corpusResult.error);
+      return mcpError(requestId, -32002, "Documentation corpus is unavailable", 503);
+    }
+    const corpus = corpusResult.chunks;
+    const clientKey = await docsPublicClientKey(c.req.header("CF-Connecting-IP") ?? "unknown");
+    const leaseResult = await acquireDocsPublicLease(c.env, clientKey, "docs-mcp");
+    if (!leaseResult.ok) {
+      return mcpError(
+        requestId,
+        leaseResult.status === 429 ? -32029 : -32002,
+        leaseResult.status === 429 ? "Documentation tool rate limit exceeded. Try again shortly." : "Documentation tools are temporarily unavailable",
+        leaseResult.status,
+        leaseResult.status === 429 ? { "Retry-After": "60" } : void 0
+      );
+    }
+    try {
+      return await callDocsTool(c.req.raw, requestWithId, corpus, c.env);
+    } finally {
+      await releaseDocsPublicLease(leaseResult.lease, "docs-mcp");
+    }
+  });
+  for (const path of [
+    "/.well-known/mcp",
+    "/.well-known/mcp.json",
+    "/.well-known/mcp/server-card.json"
+  ]) {
+    app.get(path, async (c) => {
+      const manifest = await publicManifest(c.req.raw, c.env);
+      if (!manifest) return c.notFound();
+      return discoveryResponse(c.req.raw, manifest);
+    });
+  }
+  app.get("/.well-known/mcp/server-cards.json", async (c) => {
+    const manifest = await publicManifest(c.req.raw, c.env);
+    if (!manifest) return c.notFound();
+    return jsonResponse({ servers: [serverCard(c.req.raw, manifest)] }, 200, {
+      "Cache-Control": "public, max-age=300"
+    });
+  });
+}
+async function readSkillResource(rawRequest, request, manifest, env) {
+  const params = objectValue(request.params);
+  const requestedUri = typeof params?.uri === "string" ? params.uri : "";
+  const resource = skillResource(rawRequest, manifest);
+  if (requestedUri !== resource.uri) {
+    return mcpError(request.id, -32602, "Unknown documentation resource");
+  }
+  const assetUrl = new URL("/_docs/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) {
+  return {
+    uri: new URL("/skill.md", request.url).toString(),
+    name: `${manifest.name} documentation skill`,
+    title: `Use ${manifest.name}`,
+    description: `Agent instructions grounded in the published ${manifest.name} documentation.`,
+    mimeType: "text/markdown"
+  };
+}
+async function publicManifest(request, env) {
+  if (request.headers.get("x-deepspace-surface") !== "docs") return null;
+  const manifest = await loadDocsPublishedManifest(env, request.url);
+  return manifest?.mcp.access === "public" ? manifest : null;
+}
+function discoveryResponse(request, manifest) {
+  return jsonResponse(serverCard(request, manifest), 200, {
+    "Cache-Control": "public, max-age=300"
+  });
+}
+function serverCard(request, manifest) {
+  return {
+    name: manifest.name,
+    description: `Search and read the published ${manifest.name} documentation.`,
+    version: MCP_SERVER_VERSION,
+    protocolVersion: CURRENT_PROTOCOL_VERSION,
+    transport: {
+      type: "streamable-http",
+      url: new URL("/mcp", request.url).toString()
+    },
+    authentication: { required: false },
+    capabilities: {
+      tools: DOCS_TOOLS.map(({ name, title, description }) => ({ name, title, description })),
+      resources: [skillResource(request, manifest)]
+    }
+  };
+}
+
+// src/server/utils/docs-routes.ts
+function registerDeepSpaceDocs(app, options) {
+  registerDocsAssistantRoutes(app, options.resolveAuth);
+  registerDocsMcpRoutes(app);
+  registerDocsStaticRoutes(app);
+}
+function docsAssistantLimiterManifestEntry(className) {
+  return {
+    binding: "DOCS_ASSISTANT_LIMITER",
+    className,
+    sqlite: true
+  };
+}
+
 // src/server/utils/metering.ts
 function meterUsage(env, kind, fields = {}) {
   const ds = env.USAGE_EVENTS;
@@ -1629,6 +2890,16 @@ var MSG_YJS_SYNC = 22;
 var MSG_YJS_AWARENESS = 23;
 var ROLE_ANONYMOUS = "viewer";
 
+// src/shared/users-schema.ts
+var USERS_COLUMNS = [
+  { name: "email", storage: "text", interpretation: "plain" },
+  { name: "name", storage: "text", interpretation: "plain" },
+  { name: "imageUrl", storage: "text", interpretation: "plain" },
+  { name: "role", storage: "text", interpretation: "plain" },
+  { name: "createdAt", storage: "text", interpretation: { kind: "datetime" } },
+  { name: "lastSeenAt", storage: "text", interpretation: { kind: "datetime" } }
+];
+
 // src/server/schemas/registry.ts
 function collectionTableName(name) {
   return `c_${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
@@ -1829,14 +3100,6 @@ var SYSTEM_MANAGED_COLUMNS = /* @__PURE__ */ new Set([
   "createdAt",
   "lastSeenAt"
 ]);
-var USERS_COLUMNS = [
-  { name: "email", storage: "text", interpretation: "plain" },
-  { name: "name", storage: "text", interpretation: "plain" },
-  { name: "imageUrl", storage: "text", interpretation: "plain" },
-  { name: "role", storage: "text", interpretation: "plain" },
-  { name: "createdAt", storage: "text", interpretation: { kind: "datetime" } },
-  { name: "lastSeenAt", storage: "text", interpretation: { kind: "datetime" } }
-];
 var BASE_USERS_SCHEMA = {
   name: "users",
   columns: [...USERS_COLUMNS],
@@ -3063,11 +4326,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_HEADERS2 });
     }
-    return Response.json({ tool: tool2 }, { headers: CORS_HEADERS2 });
+    return Response.json({ tool: tool3 }, { headers: CORS_HEADERS2 });
   }
   if (path.startsWith("tools/execute") && request.method === "POST") {
     return handleToolExecute(ctx, request);
@@ -3084,8 +4347,8 @@ async function handleToolExecute(ctx, request) {
       { status: 400, headers: CORS_HEADERS2 }
     );
   }
-  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_HEADERS2 }
@@ -3102,8 +4365,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_HEADERS2 });
   }
@@ -3114,7 +4377,7 @@ async function handleToolExecute(ctx, request) {
     getPermissionContext: ctx.getPermissionContext,
     send: ctx.send
   };
-  const result = await executeTool2(recordCtx, tool2, params, userId, userRole, isAppAction);
+  const result = await executeTool2(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_HEADERS2 });
 }
@@ -7365,6 +8628,9 @@ export {
   DEFAULT_QUERY_LIMIT,
   DEPLOYED_APPS_DEFAULTS,
   DIRECTORY_SCHEMAS,
+  DeepSpaceAgentModelError,
+  DeepSpaceAgentProfileError,
+  DocsAssistantLimiter,
   GLOBAL_DO_TYPES,
   GLOBAL_DO_TYPE_NAMES,
   GameRoom,
@@ -7391,6 +8657,7 @@ export {
   VOTING_SCHEMAS,
   WORKSPACE_SCHEMAS,
   YjsRoom,
+  acquireDocsPublicLease,
   analyzePermissions,
   apiWorkerFetch,
   appendMessage,
@@ -7401,6 +8668,8 @@ export {
   broadcastChange,
   broadcastYjsUpdate,
   buildCronContext,
+  buildDocsAssistantPrompt,
+  buildDocsAssistantTools,
   buildTableSelect,
   buildUiParts,
   callRegistry,
@@ -7424,8 +8693,12 @@ export {
   createScopedR2Handler,
   dataToColumnValues,
   decodeJwtPayload,
+  deepSpaceAgentErrorSummary,
   deleteChatCascade,
   deleteRecord,
+  docsAssistantErrorSummary,
+  docsAssistantLimiterManifestEntry,
+  docsPublicClientKey,
   enqueueJob,
   executeQuery,
   getAllUsers,
@@ -7456,6 +8729,8 @@ export {
   isTestAccountEmail,
   isTestAccountTier,
   lintSchema,
+  loadDocsPublishedCorpus,
+  loadDocsPublishedManifest,
   loadMessages,
   makeDefaultSummarizer,
   matchOrigin,
@@ -7463,24 +8738,37 @@ export {
   meterUsage,
   meterVectorize,
   noopPermissionContext,
+  normalizeDocsAssistantHistory,
+  normalizeDocsRoute,
+  parseDocsCorpus,
   parseQuotaLimit,
   platformCorsPatterns,
   platformWorkerFetch,
   prepareMessagesWithCompaction,
   priceBindingUsageEvent,
   putRecord,
+  readDocsPublishedPage,
+  readDocsRoute,
   readRecord,
   recordMatchesSubscription,
   refundInvoice,
+  registerDeepSpaceDocs,
+  registerDocsAssistantRoutes,
+  registerDocsMcpRoutes,
+  registerDocsStaticRoutes,
   registerUser,
   registryErrorJson,
   registryStub,
+  releaseDocsPublicLease,
   requireSubscription,
   resolveAppName,
   resolveColumn,
+  resolveDocsPublishedCorpus,
   rowToData,
   runMigrations,
   saveYjsDoc,
+  searchDocsCorpus,
+  streamDeepSpaceAgent,
   timingSafeEqualHex,
   timingSafeEqualStrings,
   totalChars,