@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/runtime/targets/cloudflare/build.ts

@@ -8,6 +8,8 @@ import { build as esbuild, type Plugin } from "esbuild";
 import { loadAgentCapsule, type LoadedAgentCapsule } from "../../config";
 import { buildSharedAgentManifest, type ManifestSchema, type SharedAgentManifest } from "../../core/manifest";
 import { AgentKitError } from "../../errors";
+import { resolveKnowledgeConfig } from "../../knowledge/config";
+import { KNOWLEDGE_SCHEMA_SQL } from "../../knowledge/schema";
 
 export type BuildTarget = "cloudflare";
 
@@ -30,10 +32,14 @@ export type AgentManifest = {
   runtime: "edge";
   target: "cloudflare";
   provider: SharedAgentManifest["provider"];
+  timeZone: SharedAgentManifest["timeZone"];
   prompt: SharedAgentManifest["prompt"];
   secrets: SharedAgentManifest["secrets"];
   tools: SharedAgentManifest["tools"];
+  integrations: SharedAgentManifest["integrations"];
   channels: SharedAgentManifest["channels"];
+  transcription: SharedAgentManifest["transcription"];
+  knowledge: SharedAgentManifest["knowledge"];
   access: SharedAgentManifest["access"];
   storage: {
     driver: "agentkit";
@@ -145,6 +151,14 @@ function validateCloudflareBuild(capsule: LoadedAgentCapsule): void {
     );
   }
 
+  const knowledge = resolveKnowledgeConfig(capsule.config);
+
+  if (knowledge.enabled && capsule.config.storage.database?.driver !== "turso") {
+    throw new AgentKitError(
+      "build_knowledge_database",
+      'Cloudflare Knowledge deploy requires storage.database.driver: "turso" so chunks and retrieval state are available to the hosted runtime.',
+    );
+  }
 }
 
 function buildWarnings(capsule: LoadedAgentCapsule): string[] {
@@ -181,10 +195,14 @@ function buildManifest(
     runtime: "edge",
     target: "cloudflare",
     provider: shared.provider,
+    timeZone: shared.timeZone,
     prompt: shared.prompt,
     secrets: shared.secrets,
     tools: shared.tools,
+    integrations: shared.integrations,
     channels: shared.channels,
+    transcription: shared.transcription,
+    knowledge: shared.knowledge,
     access: shared.access,
     storage: {
       driver: "agentkit",
@@ -210,12 +228,26 @@ function buildCloudflareFilesManifest(files: SharedAgentManifest["storage"]["fil
 
 async function loadTursoSchema(capsule: LoadedAgentCapsule): Promise<ManifestSchema | null> {
   const database = capsule.config.storage.database;
+  const knowledge = resolveKnowledgeConfig(capsule.config);
+  const sources: string[] = [];
+
+  if (!database || database.driver !== "turso") {
+    return null;
+  }
+
+  if (database.schema) {
+    sources.push(await readFile(resolve(capsule.root, database.schema), "utf8"));
+  }
+
+  if (knowledge.enabled) {
+    sources.push(KNOWLEDGE_SCHEMA_SQL);
+  }
 
-  if (!database || database.driver !== "turso" || !database.schema) {
+  if (sources.length === 0) {
     return null;
   }
 
-  const source = await readFile(resolve(capsule.root, database.schema), "utf8");
+  const source = sources.map((part) => part.trim()).filter(Boolean).join("\n\n") + "\n";
   const digest = sha256(source);
   return { source, sha256: digest };
 }
@@ -288,8 +320,8 @@ async function listSourceFiles(root: string): Promise<string[]> {
 function findImportSpecifiers(source: string): string[] {
   const specifiers: string[] = [];
   const patterns = [
-    /\bimport\s+(?:type\s+)?(?:[^"'()]*?\s+from\s+)?["']([^"']+)["']/g,
-    /\bexport\s+[^"'()]*?\s+from\s+["']([^"']+)["']/g,
+    /\bimport\s+(?!type\b)(?:[^"'()]*?\s+from\s+)?["']([^"']+)["']/g,
+    /\bexport\s+(?!type\b)[^"'()]*?\s+from\s+["']([^"']+)["']/g,
     /\brequire\(\s*["']([^"']+)["']\s*\)/g,
     /\bimport\(\s*["']([^"']+)["']\s*\)/g,
   ];
@@ -353,6 +385,26 @@ export function defineTool(tool) {
   return tool;
 }
 
+export function composioManaged(input) {
+  const name = normalizeIntegrationName(input.name ?? "composio", "composio integration name");
+  const toolkits = normalizeToolkitList(input.toolkits, "composioManaged.toolkits");
+  const tools = input.tools ? normalizeComposioToolMap(input.tools, toolkits) : undefined;
+  const tags = input.tags ? normalizeIntegrationTags(input.tags) : undefined;
+  const confirmExternalWrites =
+    input.confirmExternalWrites === undefined ? undefined : Boolean(input.confirmExternalWrites);
+
+  return {
+    type: "composio",
+    provider: "composio",
+    mode: "managed",
+    name,
+    toolkits,
+    ...(tools ? { tools } : {}),
+    ...(tags ? { tags } : {}),
+    ...(confirmExternalWrites === undefined ? {} : { confirmExternalWrites }),
+  };
+}
+
 export function websiteChannel(input) {
   return {
     type: "website",
@@ -361,6 +413,7 @@ export function websiteChannel(input) {
     access: input.access ?? { mode: "token" },
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
   };
 }
 
@@ -372,6 +425,7 @@ export function telegramChannel(input) {
     secrets: normalizeChannelSecrets(input.secrets ?? ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"], "telegram channel"),
     allowedUpdates: input.allowedUpdates ?? ["message"],
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
   };
 }
 
@@ -382,12 +436,35 @@ export function whatsappChannel(input) {
     name: input.name,
     secrets: normalizeChannelSecrets(input.secrets ?? defaultWhatsappChannelSecrets(input.provider), \`\${input.provider} whatsapp channel\`),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, \`\${input.provider} whatsapp channel\`) } : {}),
+  };
+}
+
+export function discordChannel(input) {
+  return {
+    type: "discord",
+    provider: "discord",
+    name: input.name,
+    secrets: normalizeChannelSecrets(input.secrets ?? ["DISCORD_PUBLIC_KEY"], "discord channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "discord channel") } : {}),
+  };
+}
+
+export function slackChannel(input) {
+  return {
+    type: "slack",
+    provider: "slack",
+    name: input.name,
+    secrets: normalizeChannelSecrets(input.secrets ?? ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"], "slack channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "slack channel") } : {}),
   };
 }
 
 function defaultWhatsappChannelSecrets(provider) {
   if (provider === "zapster") {
-    return ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"];
+    return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"];
   }
 
   return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
@@ -406,6 +483,135 @@ function normalizeChannelSecrets(secrets, context) {
 
   return Array.from(uniqueSecrets).sort();
 }
+
+function normalizeIntegrationName(value, context) {
+  const name = value.trim();
+
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error(\`\${context} must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.\`);
+  }
+
+  return name;
+}
+
+function normalizeToolkitList(values, context) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(\`\${context} must include at least one toolkit slug.\`);
+  }
+
+  const toolkits = new Set();
+
+  for (const value of values) {
+    if (typeof value !== "string") {
+      throw new Error(\`\${context} entries must be toolkit slug strings.\`);
+    }
+
+    const toolkit = value.trim().toLowerCase();
+
+    if (!/^[a-z][a-z0-9_-]*$/.test(toolkit)) {
+      throw new Error(\`\${context} entries must start with a letter and contain only letters, numbers, underscores, and hyphens.\`);
+    }
+
+    toolkits.add(toolkit);
+  }
+
+  return Array.from(toolkits).sort();
+}
+
+function normalizeComposioToolMap(values, toolkits) {
+  const toolkitSet = new Set(toolkits);
+  const normalized = {};
+
+  for (const [rawToolkit, rawTools] of Object.entries(values)) {
+    const toolkit = rawToolkit.trim().toLowerCase();
+
+    if (!toolkitSet.has(toolkit)) {
+      throw new Error(\`composioManaged.tools.\${rawToolkit} must reference a toolkit listed in composioManaged.toolkits.\`);
+    }
+
+    if (!Array.isArray(rawTools) || rawTools.length === 0) {
+      throw new Error(\`composioManaged.tools.\${rawToolkit} must include at least one Composio action slug.\`);
+    }
+
+    const tools = new Set();
+
+    for (const rawTool of rawTools) {
+      if (typeof rawTool !== "string") {
+        throw new Error(\`composioManaged.tools.\${rawToolkit} entries must be Composio action slug strings.\`);
+      }
+
+      const tool = rawTool.trim().toUpperCase();
+
+      if (!/^[A-Z][A-Z0-9_]*$/.test(tool)) {
+        throw new Error(\`composioManaged.tools.\${rawToolkit} entries must be uppercase Composio action slugs.\`);
+      }
+
+      tools.add(tool);
+    }
+
+    normalized[toolkit] = Array.from(tools).sort();
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function normalizeIntegrationTags(tags) {
+  const normalized = {};
+
+  if (tags.enable !== undefined) {
+    normalized.enable = normalizeTagList(tags.enable, "composioManaged.tags.enable");
+  }
+
+  if (tags.disable !== undefined) {
+    normalized.disable = normalizeTagList(tags.disable, "composioManaged.tags.disable");
+  }
+
+  return normalized;
+}
+
+function normalizeTagList(values, context) {
+  if (!Array.isArray(values)) {
+    throw new Error(\`\${context} must be an array of tag strings.\`);
+  }
+
+  return Array.from(new Set(values.map((value) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(\`\${context} entries must be non-empty strings.\`);
+    }
+
+    return value.trim();
+  }))).sort();
+}
+
+function normalizeChannelBuffer(input, context) {
+  if (input.mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.mode !== undefined && input.mode !== "debounce") {
+    throw new Error(\`\${context} buffer.mode must be "off" or "debounce".\`);
+  }
+
+  const buffer = {
+    mode: "debounce",
+    quietWindowMs: input.quietWindowMs ?? 2500,
+    maxWaitMs: input.maxWaitMs ?? 12000,
+    maxMessages: input.maxMessages ?? 20,
+    maxChars: input.maxChars ?? 8000,
+  };
+
+  for (const field of ["quietWindowMs", "maxWaitMs", "maxMessages", "maxChars"]) {
+    if (!Number.isInteger(buffer[field]) || buffer[field] <= 0) {
+      throw new Error(\`\${context} buffer.\${field} must be a positive integer.\`);
+    }
+  }
+
+  if (buffer.maxWaitMs < buffer.quietWindowMs) {
+    throw new Error(\`\${context} buffer.maxWaitMs must be greater than or equal to buffer.quietWindowMs.\`);
+  }
+
+  return buffer;
+}
 `;
 }
 
@@ -479,14 +685,18 @@ function renderCloudflareWorker(input: { manifest: AgentManifest; instructions:
   const instructionsJson = JSON.stringify(input.instructions);
   const configImportPath = JSON.stringify(input.configPath);
   const providerImportPath = JSON.stringify(resolve(moduleDir, "../../../providers/index.ts"));
+  const composioIntegrationImportPath = JSON.stringify(resolve(moduleDir, "../../integrations/composio.ts"));
+  const promptContextImportPath = JSON.stringify(resolve(moduleDir, "../../prompt-context.ts"));
 
   return `import { DurableObject } from "cloudflare:workers";
 import agentConfig from ${configImportPath};
 import { getProviderAdapter } from ${providerImportPath};
+import { MANAGED_COMPOSIO_USER_ID_BINDING, createManagedComposioTools } from ${composioIntegrationImportPath};
+import { appendRuntimePromptContext, buildRuntimeClockContext } from ${promptContextImportPath};
 
 const manifest = ${manifestJson};
 const instructions = ${instructionsJson};
-const hostedTools = agentConfig.tools ?? [];
+const hostedKnowledgeTool = manifest.knowledge.enabled ? createHostedKnowledgeSearchTool() : null;
 const DEFAULT_TOOL_TIMEOUT_MS = 30000;
 
 export class AgentKitConversationStore extends DurableObject {
@@ -516,6 +726,10 @@ export class AgentKitConversationStore extends DurableObject {
         status TEXT NOT NULL,
         error_code TEXT,
         error_message TEXT,
+        input_tokens INTEGER,
+        output_tokens INTEGER,
+        total_tokens INTEGER,
+        cost_json TEXT,
         created_at TEXT NOT NULL,
         completed_at TEXT
       );
@@ -528,11 +742,29 @@ export class AgentKitConversationStore extends DurableObject {
         status TEXT NOT NULL,
         input_json TEXT NOT NULL,
         output_json TEXT,
+        rendered_json TEXT,
         error_message TEXT,
         created_at TEXT NOT NULL,
         completed_at TEXT
       );
     \`);
+    try {
+      this.sql.exec("ALTER TABLE tool_calls ADD COLUMN rendered_json TEXT");
+    } catch {
+      // Existing Durable Object tables either already have this column or do not need migration.
+    }
+    for (const statement of [
+      "ALTER TABLE runs ADD COLUMN input_tokens INTEGER",
+      "ALTER TABLE runs ADD COLUMN output_tokens INTEGER",
+      "ALTER TABLE runs ADD COLUMN total_tokens INTEGER",
+      "ALTER TABLE runs ADD COLUMN cost_json TEXT",
+    ]) {
+      try {
+        this.sql.exec(statement);
+      } catch {
+        // Existing Durable Object tables either already have this column or do not need migration.
+      }
+    }
   }
 
   async fetch(request) {
@@ -542,9 +774,173 @@ export class AgentKitConversationStore extends DurableObject {
       return this.persistMessages(await request.json());
     }
 
+    if (request.method === "GET" && url.pathname === "/messages") {
+      return this.getMessages(url.searchParams.get("conversationId"));
+    }
+
+    if (request.method === "GET" && url.pathname === "/conversations") {
+      return this.listConversations();
+    }
+
+    const conversationTraceMatch = url.pathname.match(/^\\/conversations\\/([^/]+)\\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return this.getConversationTrace(decodeURIComponent(conversationTraceMatch[1] || ""));
+    }
+
+    const conversationMatch = url.pathname.match(/^\\/conversations\\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      return this.getConversation(decodeURIComponent(conversationMatch[1] || ""));
+    }
+
     return Response.json({ error: { code: "not_found", message: "Unknown Durable Object route." } }, { status: 404 });
   }
 
+  getMessages(conversationId) {
+    if (!conversationId) {
+      return Response.json({ messages: [] });
+    }
+
+    const rows = this.sql.exec(
+      "SELECT role, content FROM messages WHERE conversation_id = ? ORDER BY rowid ASC",
+      String(conversationId),
+    ).toArray();
+
+    return Response.json({
+      messages: rows
+        .filter((row) => row.role === "user" || row.role === "assistant")
+        .map((row) => ({
+          role: String(row.role),
+          content: String(row.content),
+        })),
+    });
+  }
+
+  listConversations() {
+    const rows = this.sql.exec(\`
+      SELECT conversations.id, conversations.agent_name, conversations.title, conversations.created_at, conversations.updated_at, COUNT(messages.id) AS message_count
+      FROM conversations
+      LEFT JOIN messages ON messages.conversation_id = conversations.id
+      GROUP BY conversations.id, conversations.agent_name, conversations.title, conversations.created_at, conversations.updated_at
+      ORDER BY conversations.updated_at DESC
+    \`).toArray();
+
+    return Response.json({
+      conversations: rows.map((row) => ({
+        id: String(row.id),
+        agentName: String(row.agent_name),
+        title: row.title === null || row.title === undefined ? null : String(row.title),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        messageCount: Number(row.message_count || 0),
+      })),
+    });
+  }
+
+  getConversation(conversationId) {
+    const conversation = this.readConversation(conversationId);
+
+    if (!conversation) {
+      return Response.json(
+        { error: { code: "conversation_not_found", message: \`Conversation "\${conversationId}" was not found.\` } },
+        { status: 404 },
+      );
+    }
+
+    return Response.json(conversation);
+  }
+
+  getConversationTrace(conversationId) {
+    const conversation = this.readConversation(conversationId);
+
+    if (!conversation) {
+      return Response.json(
+        { error: { code: "conversation_not_found", message: \`Conversation "\${conversationId}" was not found.\` } },
+        { status: 404 },
+      );
+    }
+
+    const runs = this.sql.exec(
+      "SELECT id, conversation_id, provider, model, status, error_code, error_message, input_tokens, output_tokens, total_tokens, cost_json, created_at, completed_at FROM runs WHERE conversation_id = ? ORDER BY rowid ASC",
+      conversationId,
+    ).toArray();
+
+    return Response.json({
+      ...conversation,
+      runs: runs.map((run) => ({
+        id: String(run.id),
+        conversationId: String(run.conversation_id),
+        provider: String(run.provider),
+        model: String(run.model),
+        status: String(run.status),
+        errorCode: run.error_code === null || run.error_code === undefined ? null : String(run.error_code),
+        errorMessage: run.error_message === null || run.error_message === undefined ? null : String(run.error_message),
+        usage: readStoredUsage(run),
+        startedAt: String(run.created_at),
+        completedAt: run.completed_at === null || run.completed_at === undefined ? null : String(run.completed_at),
+        toolCalls: this.readToolCalls(String(run.id)),
+      })),
+    });
+  }
+
+  readConversation(conversationId) {
+    if (!conversationId) {
+      return null;
+    }
+
+    const row = this.sql.exec(
+      "SELECT id, agent_name, title, created_at, updated_at FROM conversations WHERE id = ?",
+      conversationId,
+    ).one();
+
+    if (!row) {
+      return null;
+    }
+
+    const messages = this.sql.exec(
+      "SELECT id, conversation_id, role, content, created_at FROM messages WHERE conversation_id = ? ORDER BY rowid ASC",
+      conversationId,
+    ).toArray();
+
+    return {
+      id: String(row.id),
+      agentName: String(row.agent_name),
+      title: row.title === null || row.title === undefined ? null : String(row.title),
+      createdAt: String(row.created_at),
+      updatedAt: String(row.updated_at),
+      messages: messages.map((message) => ({
+        id: String(message.id),
+        conversationId: String(message.conversation_id),
+        role: String(message.role),
+        content: String(message.content),
+        createdAt: String(message.created_at),
+      })),
+    };
+  }
+
+  readToolCalls(runId) {
+    const rows = this.sql.exec(
+      "SELECT id, run_id, conversation_id, tool_name, visibility, status, input_json, output_json, rendered_json, error_message, created_at, completed_at FROM tool_calls WHERE run_id = ? ORDER BY rowid ASC",
+      runId,
+    ).toArray();
+
+    return rows.map((row) => ({
+      id: String(row.id),
+      runId: String(row.run_id),
+      conversationId: String(row.conversation_id),
+      name: String(row.tool_name),
+      visibility: String(row.visibility),
+      status: String(row.status),
+      input: parseStoredJson(row.input_json, {}),
+      output: row.output_json === null || row.output_json === undefined ? undefined : parseStoredJson(row.output_json, null),
+      rendered: row.rendered_json === null || row.rendered_json === undefined ? undefined : parseStoredJson(row.rendered_json, null),
+      errorMessage: row.error_message === null || row.error_message === undefined ? null : String(row.error_message),
+      createdAt: String(row.created_at),
+      completedAt: row.completed_at === null || row.completed_at === undefined ? null : String(row.completed_at),
+    }));
+  }
+
   persistMessages(input) {
     const now = new Date().toISOString();
     const conversationId = String(input.conversationId || crypto.randomUUID());
@@ -552,6 +948,7 @@ export class AgentKitConversationStore extends DurableObject {
     const userMessageId = crypto.randomUUID();
     const assistantMessageId = crypto.randomUUID();
     const title = titleFromMessage(String(input.userMessage || ""));
+    const usage = normalizeRuntimeUsage(input.usage);
 
     this.sql.exec(
       "INSERT OR IGNORE INTO conversations (id, agent_name, title, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
@@ -571,7 +968,7 @@ export class AgentKitConversationStore extends DurableObject {
       now,
     );
     this.sql.exec(
-      "INSERT INTO runs (id, conversation_id, provider, model, status, error_code, error_message, created_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      "INSERT INTO runs (id, conversation_id, provider, model, status, error_code, error_message, input_tokens, output_tokens, total_tokens, cost_json, created_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
       runId,
       conversationId,
       manifest.provider.name,
@@ -579,6 +976,10 @@ export class AgentKitConversationStore extends DurableObject {
       String(input.status || "completed"),
       input.errorCode ? String(input.errorCode) : null,
       input.errorMessage ? String(input.errorMessage) : null,
+      usage.inputTokens ?? null,
+      usage.outputTokens ?? null,
+      usage.totalTokens ?? null,
+      usage.cost && Object.keys(usage.cost).length > 0 ? JSON.stringify(usage.cost) : null,
       now,
       now,
     );
@@ -596,7 +997,7 @@ export class AgentKitConversationStore extends DurableObject {
 
     for (const toolCall of input.toolCalls || []) {
       this.sql.exec(
-        "INSERT INTO tool_calls (id, run_id, conversation_id, tool_name, visibility, status, input_json, output_json, error_message, created_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        "INSERT INTO tool_calls (id, run_id, conversation_id, tool_name, visibility, status, input_json, output_json, rendered_json, error_message, created_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
         String(toolCall.id || crypto.randomUUID()),
         runId,
         conversationId,
@@ -605,6 +1006,7 @@ export class AgentKitConversationStore extends DurableObject {
         String(toolCall.status || "completed"),
         JSON.stringify(toolCall.input ?? {}),
         toolCall.output === undefined ? null : JSON.stringify(toolCall.output),
+        toolCall.rendered === undefined ? null : JSON.stringify(toolCall.rendered),
         toolCall.errorMessage ? String(toolCall.errorMessage) : null,
         now,
         now,
@@ -621,7 +1023,7 @@ export class AgentKitConversationStore extends DurableObject {
 }
 
 export default {
-  async fetch(request, env) {
+  async fetch(request, env, ctx) {
     const url = new URL(request.url);
 
     if (request.method === "GET" && url.pathname === "/_agentkit") {
@@ -631,19 +1033,23 @@ export default {
         return auth;
       }
 
+      const hostedTools = createHostedTools(env);
+
       return Response.json({
         agent: manifest.name,
         runtime: manifest.runtime,
         target: manifest.target,
         provider: manifest.provider,
         prompt: manifest.prompt,
-        tools: manifest.tools.map((tool) => tool.name),
+        tools: hostedTools.map((tool) => tool.name),
+        integrations: hostedIntegrations(env),
         channels: manifest.channels.map((channel) => ({
           name: channel.name,
           type: channel.type,
           provider: channel.provider,
           secrets: channel.secrets,
         })),
+        knowledge: manifest.knowledge,
         access: manifest.access,
         storage: manifest.storage,
         database: inspectHostedDatabase(),
@@ -654,6 +1060,15 @@ export default {
     }
 
     if (request.method === "GET" && url.pathname === "/") {
+      const auth = await authorizeDeployAccess(request, env, {}, {
+        notConfiguredCode: "cloud_access_not_configured",
+        notConfiguredMessage: "Hosted AgentKit Cloud routes require a deploy access token gate.",
+      });
+
+      if (auth) {
+        return auth;
+      }
+
       return Response.json({
         agent: manifest.name,
         status: "ready",
@@ -662,20 +1077,45 @@ export default {
       });
     }
 
+    if (request.method === "GET" && url.pathname === "/health") {
+      const auth = await authorizeDeployAccess(request, env, {}, {
+        notConfiguredCode: "cloud_access_not_configured",
+        notConfiguredMessage: "Hosted AgentKit Cloud routes require a deploy access token gate.",
+      });
+
+      if (auth) {
+        return auth;
+      }
+
+      return Response.json({ ok: true });
+    }
+
+    if (isHostedChannelWebhookPath(url.pathname)) {
+      return forwardHostedChannelWebhook(request, env, url);
+    }
+
     if (request.method === "POST" && (url.pathname === "/chat" || url.pathname === "/v1/chat")) {
-      return handleChat(request, env);
+      return handleChat(request, env, ctx);
     }
 
-    if (request.method === "POST" && url.pathname.startsWith("/tools/")) {
-      return handleTool(request, env, decodeURIComponent(url.pathname.slice("/tools/".length)));
+    if (request.method === "GET" && (url.pathname === "/conversations" || url.pathname === "/v1/conversations")) {
+      return handleConversationRead(request, env, "list");
+    }
+
+    const conversationTraceMatch = url.pathname.match(/^\\/(?:v1\\/)?conversations\\/([^/]+)\\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return handleConversationRead(request, env, "trace", decodeURIComponent(conversationTraceMatch[1] || ""));
     }
 
-    if (request.method === "GET" && url.pathname === "/_agentkit/turso/health") {
-      return handleTursoHealth(request, env);
+    const conversationMatch = url.pathname.match(/^\\/(?:v1\\/)?conversations\\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      return handleConversationRead(request, env, "show", decodeURIComponent(conversationMatch[1] || ""));
     }
 
-    if (request.method === "POST" && url.pathname === "/_agentkit/turso/query") {
-      return handleTursoQuery(request, env);
+    if (request.method === "POST" && url.pathname.startsWith("/tools/")) {
+      return handleTool(request, env, decodeURIComponent(url.pathname.slice("/tools/".length)));
     }
 
     if (url.pathname.startsWith("/files/")) {
@@ -686,69 +1126,46 @@ export default {
   },
 };
 
-async function handleTursoHealth(request, env) {
-  const auth = authorizeAdmin(request, env);
-
-  if (auth) {
-    return auth;
-  }
-
-  const configError = requireTurso(env);
-
-  if (configError) {
-    return configError;
-  }
-
-  const response = await fetch(toTursoBaseUrl(env.TURSO_DATABASE_URL) + "/health", {
-    headers: {
-      Authorization: \`Bearer \${env.TURSO_AUTH_TOKEN}\`,
-    },
-  });
-
-  return Response.json({
-    driver: "turso",
-    ok: response.ok,
-    status: response.status,
-  }, { status: response.ok ? 200 : 502 });
+function isHostedChannelWebhookPath(pathname) {
+  return (
+    /^\\/channels\\/[^/]+\\/(?:website\\/agentkit|telegram\\/telegram|whatsapp\\/(?:zapster|meta)|discord\\/discord|slack\\/slack)\\/webhook$/.test(pathname) ||
+    /^\\/channels\\/[^/]+\\/(?:website|telegram|discord|slack)\\/webhook$/.test(pathname) ||
+    /^\\/channels\\/[^/]+\\/whatsapp\\/(?:zapster|meta)\\/webhook$/.test(pathname)
+  );
 }
 
-async function handleTursoQuery(request, env) {
-  const auth = authorizeAdmin(request, env);
-
-  if (auth) {
-    return auth;
-  }
-
-  const configError = requireTurso(env);
-
-  if (configError) {
-    return configError;
-  }
-
-  let body;
-
-  try {
-    body = await request.json();
-  } catch {
+async function forwardHostedChannelWebhook(request, env, url) {
+  if (!env.AGENTKIT_CLOUD_API_URL) {
     return Response.json(
-      { error: { code: "validation_error", message: "Expected JSON body with sql and optional args fields." } },
-      { status: 400 },
+      {
+        error: {
+          code: "channel_webhook_proxy_not_configured",
+          message: "Hosted channel webhooks require AGENTKIT_CLOUD_API_URL on the deployed Worker.",
+        },
+      },
+      { status: 501 },
     );
   }
 
-  const sql = String(body.sql || "").trim();
+  const target = new URL(\`\${url.pathname}\${url.search}\`, env.AGENTKIT_CLOUD_API_URL);
+  const headers = new Headers(request.headers);
+  headers.delete("host");
+  headers.delete("content-length");
 
-  if (!sql) {
-    return Response.json({ error: { code: "validation_error", message: "sql must be non-empty." } }, { status: 400 });
+  if (env.AGENTKIT_DEPLOY_ID) {
+    headers.set("X-AgentKit-Deploy-ID", env.AGENTKIT_DEPLOY_ID);
   }
 
-  const args = Array.isArray(body.args) ? body.args : [];
-  try {
-    const result = await executeTursoSql(env, sql, args);
-    return Response.json(result);
-  } catch (error) {
-    return hostedErrorResponse(error);
+  if (env.AGENTKIT_RUNTIME_GATE_TOKEN) {
+    headers.set("X-AgentKit-Runtime-Gate", env.AGENTKIT_RUNTIME_GATE_TOKEN);
   }
+
+  return fetch(target.href, {
+    method: request.method,
+    headers,
+    body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+    redirect: "manual",
+  });
 }
 
 async function handleFile(request, env, rawKey) {
@@ -878,13 +1295,14 @@ async function handleTool(request, env, toolName) {
       },
       input: result.input,
       output: result.output,
+      ...(result.rendered ? { rendered: result.rendered } : {}),
     });
   } catch (error) {
     return hostedErrorResponse(error);
   }
 }
 
-async function handleChat(request, env) {
+async function handleChat(request, env, ctx) {
   let body;
 
   try {
@@ -911,47 +1329,58 @@ async function handleChat(request, env) {
     );
   }
 
-  const conversationId = String(body.conversationId || crypto.randomUUID());
-  let content;
-  const toolCalls = [];
-
-  const toolRequest = parseToolRequest(message);
+  let conversationId;
 
-  if (toolRequest) {
-    try {
-      const toolResult = await executeHostedTool({
-        name: toolRequest.name,
-        input: toolRequest.input,
-        env,
-        signal: request.signal,
-        invocation: "chat",
-      });
-      toolCalls.push(toolResult);
-      content =
-        toolResult.visibility === "internal"
-          ? \`Tool \${toolResult.name}: completed\`
-          : \`Tool \${toolResult.name}: \${JSON.stringify(toolResult.output)}\`;
-    } catch (error) {
-      await persistFailure(env, conversationId, message, error);
-      return hostedErrorResponse(error);
-    }
+  try {
+    conversationId = normalizeConversationId(body.conversationId) ?? crypto.randomUUID();
+  } catch (error) {
+    return hostedErrorResponse(error);
   }
 
-  if (content === undefined) {
-    try {
-      content = await callHostedProvider(env, message, request.signal);
-    } catch (error) {
-      await persistFailure(env, conversationId, message, error);
-      return hostedErrorResponse(error);
-    }
+  const previousMessages = await loadConversationMessages(env, conversationId).catch(() => []);
+  let content;
+  let providerResult;
+  const toolCalls = [];
+
+  try {
+    providerResult = await callHostedProvider(env, [...previousMessages, { role: "user", content: message }], request.signal, toolCalls);
+    content = providerResult.content;
+  } catch (error) {
+    const persisted = await persistFailure(env, conversationId, message, error, toolCalls);
+    queueRuntimeUsage(ctx, sendRuntimeUsage(env, {
+      kind: "chat_run",
+      status: "failed",
+      conversationId,
+      runId: persisted?.runId,
+      provider: manifest.provider.name,
+      model: manifest.provider.model,
+      metadata: {
+        error_code: error && typeof error === "object" && "code" in error ? String(error.code) : "runtime_error",
+        tool_calls: toolCalls.length,
+      },
+    }));
+    return hostedErrorResponse(error);
   }
 
   const persisted = await persist(env, {
     conversationId,
     userMessage: message,
     assistantMessage: content,
+    usage: providerResult.usage,
     toolCalls,
   });
+  queueRuntimeUsage(ctx, sendRuntimeUsage(env, {
+    kind: "chat_run",
+    status: "succeeded",
+    conversationId: persisted.conversationId ?? conversationId,
+    runId: persisted.runId,
+    provider: manifest.provider.name,
+    model: manifest.provider.model,
+    usage: providerResult.usage,
+    metadata: {
+      tool_calls: toolCalls.length,
+    },
+  }));
 
   return Response.json({
     message: {
@@ -962,6 +1391,39 @@ async function handleChat(request, env) {
   });
 }
 
+async function handleConversationRead(request, env, action, conversationId) {
+  const auth = await authorizeConversationRead(request, env);
+
+  if (auth) {
+    return auth;
+  }
+
+  if (!env.AGENTKIT_CONVERSATIONS) {
+    return Response.json({ error: { code: "conversations_not_configured", message: "Hosted conversation storage is not configured." } }, { status: 503 });
+  }
+
+  if (action === "list") {
+    const stub = hostedConversationStore(env);
+    return stub.fetch("https://agentkit.internal/conversations");
+  }
+
+  if (!conversationId) {
+    return Response.json({ error: { code: "validation_error", message: "Missing conversation id." } }, { status: 400 });
+  }
+
+  const stub = hostedConversationStore(env);
+  const suffix = action === "trace" ? "/trace" : "";
+  const path = \`/conversations/\${encodeURIComponent(conversationId)}\${suffix}\`;
+  const response = await stub.fetch(\`https://agentkit.internal\${path}\`);
+
+  if (response.status !== 404) {
+    return response;
+  }
+
+  const legacyStub = legacyConversationStore(env, conversationId);
+  return legacyStub.fetch(\`https://agentkit.internal\${path}\`);
+}
+
 function readChatMessage(body) {
   if (typeof body.message === "string") {
     return body.message.trim();
@@ -978,26 +1440,53 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function callHostedProvider(env, message, signal) {
+async function callHostedProvider(env, messages, signal, toolCalls = []) {
   const adapter = getProviderAdapter(manifest.provider);
+  const hostedTools = createHostedTools(env);
+  const clock = buildRuntimeClockContext({
+    timeZone: manifest.timeZone,
+    env,
+  });
   const result = await adapter.run({
     agent: {
       name: manifest.name,
       runtime: manifest.runtime,
       provider: manifest.provider,
     },
-    instructions: withToolVisibilityInstructions(instructions, hostedTools),
-    messages: [{ role: "user", content: message }],
+    instructions: appendRuntimePromptContext(
+      withToolVisibilityInstructions(appendHostedKnowledgePromptPolicy(instructions), hostedTools),
+      {
+        clock,
+      },
+    ),
+    messages,
     tools: hostedTools,
-    toolRuntime: createHostedProviderToolRuntime(env, signal),
+    toolRuntime: createHostedProviderToolRuntime(env, signal, clock, toolCalls),
     env,
     signal,
   });
 
-  return result.message.content;
+  return {
+    content: result.message.content,
+    usage: result.usage,
+  };
 }
 
-function withToolVisibilityInstructions(baseInstructions, tools) {
+function appendHostedKnowledgePromptPolicy(baseInstructions) {
+  if (!manifest.knowledge.enabled) {
+    return baseInstructions;
+  }
+
+  return \`\${baseInstructions.trimEnd()}
+
+Knowledge rules:
+- Use agentkit_search_knowledge before answering business-specific factual questions about the user's documents, policies, prices, availability, services, procedures, or source-specific claims.
+- Do not invent prices, policies, legal/clinical claims, availability, or source-specific facts when Knowledge has not returned support for the answer.
+- Use retrieved Knowledge as context for the final answer, but do not expose raw retrieval JSON, scores, chunk IDs, or internal tool output objects to the user.
+\`;
+}
+
+function withToolVisibilityInstructions(baseInstructions, tools) {
   const internalTools = tools
     .filter((tool) => tool.visibility === "internal")
     .map((tool) => tool.name)
@@ -1016,36 +1505,407 @@ Tool visibility rules:
 \`;
 }
 
-async function persistFailure(env, conversationId, userMessage, error) {
-  await persist(env, {
-    conversationId,
-    userMessage,
-    status: "failed",
-    errorCode: error && typeof error === "object" && "code" in error ? String(error.code) : "runtime_error",
-    errorMessage: error instanceof Error ? error.message : String(error),
-    toolCalls: [],
-  }).catch(() => undefined);
+function createHostedKnowledgeSearchTool() {
+  return {
+    name: manifest.knowledge.internalTool || "agentkit_search_knowledge",
+    description: "Search the Agent Capsule's configured Knowledge sources for business-specific facts.",
+    visibility: "internal",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        topK: { type: "integer" },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        results: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              content: { type: "string" },
+              score: { type: "number" },
+              source: { type: "object" },
+            },
+            required: ["content", "score", "source"],
+          },
+        },
+      },
+      required: ["results"],
+      additionalProperties: false,
+    },
+    secrets: manifest.knowledge.embedding.secret ? [manifest.knowledge.embedding.secret] : [],
+    async execute(input, ctx) {
+      const query = typeof input?.query === "string" ? input.query : "";
+      const topK = normalizeKnowledgeTopK(input?.topK ?? manifest.knowledge.retrieval.topK);
+      const results = await searchHostedKnowledge(ctx.database, query, topK, ctx.secrets ?? {});
+
+      return {
+        results: results.map((result) => ({
+          content: result.content,
+          score: result.score,
+          source: result.source,
+        })),
+      };
+    },
+  };
 }
 
-function parseToolRequest(content) {
-  let parsed;
+async function searchHostedKnowledge(database, query, topK, secrets) {
+  const normalizedQuery = String(query || "").trim();
+
+  if (!normalizedQuery) {
+    throw agentKitError("knowledge_query_invalid", "Knowledge search query must be a non-empty string.");
+  }
+
+  const hasEmbeddingProvider = manifest.knowledge.embedding.provider !== "none";
+  const lexical =
+    manifest.knowledge.retrieval.hybrid || !hasEmbeddingProvider
+      ? await searchHostedKnowledgeLexical(database, normalizedQuery, Math.max(topK * 4, topK))
+      : [];
+  const semantic = hasEmbeddingProvider
+    ? await searchHostedKnowledgeSemantic(database, normalizedQuery, topK * 4, secrets)
+    : [];
+
+  return combineHostedKnowledgeResults(lexical, semantic, topK);
+}
+
+async function searchHostedKnowledgeLexical(database, query, limit) {
+  const tokens = hostedKnowledgeQueryTokens(query);
+
+  if (tokens.length === 0) {
+    return [];
+  }
 
   try {
-    parsed = JSON.parse(content);
+    const result = await database.query(
+      \`
+      SELECT
+        c.id AS chunk_id,
+        c.source_id AS source_id,
+        c.content AS content,
+        c.title AS title,
+        c.section AS section,
+        c.locator AS locator,
+        s.source_key AS source_key,
+        rank
+      FROM agentkit_knowledge_fts
+      JOIN agentkit_knowledge_chunks c ON c.id = agentkit_knowledge_fts.chunk_id
+      JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+      WHERE agentkit_knowledge_fts MATCH ?
+      ORDER BY rank ASC
+      LIMIT ?
+    \`,
+      [tokens.map((token) => \`"\${token.replace(/"/g, '""')}"\`).join(" OR "), limit],
+    );
+
+    return result.rows.map((row, index) => hostedKnowledgeResultFromRow(row, hostedLexicalScore(index), null));
   } catch {
-    return null;
+    return searchHostedKnowledgeLexicalFallback(database, query, limit);
+  }
+}
+
+async function searchHostedKnowledgeLexicalFallback(database, query, limit) {
+  const like = \`%\${query.toLowerCase()}%\`;
+  const result = await database.query(
+    \`
+    SELECT
+      c.id AS chunk_id,
+      c.source_id AS source_id,
+      c.content AS content,
+      c.title AS title,
+      c.section AS section,
+      c.locator AS locator,
+      s.source_key AS source_key
+    FROM agentkit_knowledge_chunks c
+    JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+    WHERE lower(c.content) LIKE ?
+      OR lower(COALESCE(c.title, '')) LIKE ?
+      OR lower(COALESCE(c.section, '')) LIKE ?
+    ORDER BY c.created_at DESC, c.ordinal ASC
+    LIMIT ?
+  \`,
+    [like, like, like, limit],
+  );
+
+  return result.rows.map((row, index) => hostedKnowledgeResultFromRow(row, hostedLexicalScore(index), null));
+}
+
+async function searchHostedKnowledgeSemantic(database, query, limit, secrets) {
+  const queryEmbedding = await createHostedKnowledgeEmbedding(query, secrets);
+
+  if (!queryEmbedding) {
+    return [];
   }
 
-  if (!isRecord(parsed) || typeof parsed.tool !== "string" || parsed.tool.length === 0) {
+  try {
+    return await searchHostedKnowledgeNativeVector(database, queryEmbedding, limit);
+  } catch {
+    return searchHostedKnowledgeSemanticFallback(database, queryEmbedding, limit);
+  }
+}
+
+async function searchHostedKnowledgeNativeVector(database, queryEmbedding, limit) {
+  const vector = JSON.stringify(queryEmbedding);
+  const result = await database.query(
+    \`
+    SELECT
+      c.id AS chunk_id,
+      c.source_id AS source_id,
+      c.content AS content,
+      c.title AS title,
+      c.section AS section,
+      c.locator AS locator,
+      s.source_key AS source_key,
+      vector_distance_cos(v.embedding, vector32(?)) AS vector_distance
+    FROM vector_top_k('agentkit_knowledge_vectors_embedding_idx', vector32(?), ?) nearest
+    JOIN agentkit_knowledge_vectors v ON v.id = nearest.id
+    JOIN agentkit_knowledge_chunks c ON c.id = v.chunk_id
+    JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+    ORDER BY vector_distance ASC
+  \`,
+    [vector, vector, limit],
+  );
+
+  return result.rows
+    .map((row) => {
+      const distance = Number(row.vector_distance);
+      const semantic = Number.isFinite(distance) ? 1 - distance : 0;
+      return hostedKnowledgeResultFromRow(row, 0, semantic);
+    })
+    .filter((result) => result.match.semantic !== null && result.match.semantic > 0)
+    .slice(0, limit);
+}
+
+async function searchHostedKnowledgeSemanticFallback(database, queryEmbedding, limit) {
+  const result = await database.query(
+    \`
+    SELECT
+      c.id AS chunk_id,
+      c.source_id AS source_id,
+      c.content AS content,
+      c.title AS title,
+      c.section AS section,
+      c.locator AS locator,
+      c.embedding_json AS embedding_json,
+      s.source_key AS source_key
+    FROM agentkit_knowledge_chunks c
+    JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+    WHERE c.embedding_json IS NOT NULL
+    ORDER BY c.created_at DESC, c.ordinal ASC
+  \`,
+  );
+
+  return result.rows
+    .map((row) => {
+      const embedding = parseHostedKnowledgeEmbedding(row.embedding_json);
+      const semantic = embedding ? hostedCosineSimilarity(queryEmbedding, embedding) : 0;
+      return hostedKnowledgeResultFromRow(row, 0, semantic);
+    })
+    .filter((result) => result.match.semantic !== null && result.match.semantic > 0)
+    .sort((left, right) => (right.match.semantic ?? 0) - (left.match.semantic ?? 0))
+    .slice(0, limit);
+}
+
+async function createHostedKnowledgeEmbedding(input, secrets) {
+  const provider = manifest.knowledge.embedding.provider;
+
+  if (provider === "none") {
     return null;
   }
 
+  if (provider === "test") {
+    return hostedFakeEmbedding(input, manifest.knowledge.embedding.dimensions || 32);
+  }
+
+  if (provider !== "openai") {
+    throw agentKitError("knowledge_embedding_provider_unsupported", "Unsupported knowledge embedding provider.");
+  }
+
+  const secretName = manifest.knowledge.embedding.secret || "OPENAI_API_KEY";
+  const apiKey = secrets[secretName];
+
+  if (!apiKey) {
+    throw agentKitError("knowledge_embedding_secret_missing", \`Knowledge embeddings require missing secret "\${secretName}".\`);
+  }
+
+  const response = await fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: \`Bearer \${apiKey}\`,
+    },
+    body: JSON.stringify({
+      model: manifest.knowledge.embedding.model || "text-embedding-3-small",
+      input,
+      encoding_format: "float",
+      ...(manifest.knowledge.embedding.dimensions ? { dimensions: manifest.knowledge.embedding.dimensions } : {}),
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw agentKitError(
+      "knowledge_embedding_failed",
+      \`OpenAI embedding request failed with HTTP \${response.status}.\${text ? " " + text.slice(0, 240) : ""}\`,
+    );
+  }
+
+  const payload = await response.json();
+  const embedding = payload?.data?.[0]?.embedding;
+
+  if (!Array.isArray(embedding) || embedding.some((value) => typeof value !== "number")) {
+    throw agentKitError("knowledge_embedding_failed", "OpenAI embedding response did not contain a numeric vector.");
+  }
+
+  return embedding;
+}
+
+function combineHostedKnowledgeResults(lexical, semantic, topK) {
+  const byChunk = new Map();
+
+  for (const result of lexical) {
+    byChunk.set(result.chunkId, result);
+  }
+
+  for (const result of semantic) {
+    const existing = byChunk.get(result.chunkId);
+
+    if (!existing) {
+      byChunk.set(result.chunkId, {
+        ...result,
+        score: hostedCombinedScore(0, result.match.semantic),
+      });
+      continue;
+    }
+
+    byChunk.set(result.chunkId, {
+      ...existing,
+      score: hostedCombinedScore(existing.match.lexical, result.match.semantic),
+      match: {
+        lexical: existing.match.lexical,
+        semantic: result.match.semantic,
+      },
+    });
+  }
+
+  return Array.from(byChunk.values())
+    .map((result) => ({
+      ...result,
+      score: result.score || hostedCombinedScore(result.match.lexical, result.match.semantic),
+    }))
+    .sort((left, right) => right.score - left.score || left.source.path.localeCompare(right.source.path))
+    .slice(0, topK);
+}
+
+function hostedKnowledgeResultFromRow(row, lexical, semantic) {
   return {
-    name: parsed.tool,
-    input: "input" in parsed ? parsed.input : {},
+    chunkId: String(row.chunk_id),
+    content: String(row.content),
+    score: hostedCombinedScore(lexical, semantic),
+    source: {
+      id: String(row.source_id),
+      path: String(row.source_key),
+      title: typeof row.title === "string" ? row.title : null,
+      section: typeof row.section === "string" ? row.section : null,
+      locator: typeof row.locator === "string" ? row.locator : null,
+    },
+    match: {
+      lexical,
+      semantic,
+    },
   };
 }
 
+function normalizeKnowledgeTopK(value) {
+  const topK = Number(value);
+
+  if (!Number.isInteger(topK) || topK <= 0 || topK > 50) {
+    throw agentKitError("knowledge_query_invalid", "Knowledge search topK must be a positive integer no larger than 50.");
+  }
+
+  return topK;
+}
+
+function hostedKnowledgeQueryTokens(query) {
+  return Array.from(new Set(String(query).toLowerCase().match(/[\\p{L}\\p{N}_-]+/gu) ?? [])).slice(0, 12);
+}
+
+function parseHostedKnowledgeEmbedding(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) && parsed.every((item) => typeof item === "number") ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function hostedCombinedScore(lexical, semantic) {
+  const semanticScore = semantic === null ? 0 : Math.max(0, (semantic + 1) / 2);
+  return Number((lexical * 0.6 + semanticScore * 0.4).toFixed(6));
+}
+
+function hostedLexicalScore(index) {
+  return Number((1 / (index + 1)).toFixed(6));
+}
+
+function hostedCosineSimilarity(left, right) {
+  if (left.length !== right.length || left.length === 0) {
+    return 0;
+  }
+
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+
+  for (let index = 0; index < left.length; index += 1) {
+    dot += left[index] * right[index];
+    leftNorm += left[index] * left[index];
+    rightNorm += right[index] * right[index];
+  }
+
+  if (leftNorm === 0 || rightNorm === 0) {
+    return 0;
+  }
+
+  return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+}
+
+async function hostedFakeEmbedding(input, dimensions) {
+  const values = Array.from({ length: dimensions }, () => 0);
+  const tokens = String(input).toLowerCase().match(/[\\p{L}\\p{N}_-]+/gu) ?? [];
+  const encoder = new TextEncoder();
+
+  for (const token of tokens) {
+    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token)));
+    const slot = hash[0] % dimensions;
+    const sign = hash[1] % 2 === 0 ? 1 : -1;
+    values[slot] += sign * (1 + (hash[2] % 7) / 10);
+  }
+
+  const norm = Math.sqrt(values.reduce((sum, value) => sum + value * value, 0));
+  return norm === 0 ? values : values.map((value) => Number((value / norm).toFixed(8)));
+}
+
+async function persistFailure(env, conversationId, userMessage, error, toolCalls = []) {
+  return persist(env, {
+    conversationId,
+    userMessage,
+    status: "failed",
+    errorCode: error && typeof error === "object" && "code" in error ? String(error.code) : "runtime_error",
+    errorMessage: error instanceof Error ? error.message : String(error),
+    toolCalls,
+  }).catch(() => undefined);
+}
+
 function inspectHostedDatabase() {
   const schema = manifest.storage.database.driver === "turso" ? manifest.storage.database.schema : null;
 
@@ -1064,29 +1924,69 @@ function inspectHostedDatabase() {
 }
 
 function hostedManagedSecrets() {
-  if (manifest.storage.database.driver !== "turso") {
-    return [];
+  const secrets = [];
+
+  if (manifest.storage.database.driver === "turso") {
+    secrets.push("TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL");
+  }
+
+  if (manifest.integrations.some((integration) => integration.provider === "composio" && integration.mode === "managed")) {
+    secrets.push("COMPOSIO_API_KEY");
+  }
+
+  return secrets.sort();
+}
+
+function createHostedTools(env) {
+  return [
+    ...(hostedKnowledgeTool ? [hostedKnowledgeTool] : []),
+    ...createManagedComposioTools(agentConfig, { userId: env[MANAGED_COMPOSIO_USER_ID_BINDING] }),
+    ...(agentConfig.tools ?? []),
+  ];
+}
+
+function hostedIntegrations(env) {
+  const userId = env[MANAGED_COMPOSIO_USER_ID_BINDING];
+
+  if (!userId) {
+    return manifest.integrations;
   }
 
-  return ["TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL"];
+  return manifest.integrations.map((integration) =>
+    integration.provider === "composio" && integration.mode === "managed"
+      ? { ...integration, userId }
+      : integration,
+  );
 }
 
-function createHostedProviderToolRuntime(env, signal) {
+function createHostedProviderToolRuntime(env, signal, clock, toolCalls) {
+  const hostedTools = createHostedTools(env);
+
   return {
     definitions: hostedTools,
-    execute(request) {
-      return executeHostedTool({
-        name: request.name,
-        input: request.input,
-        env,
-        signal,
-        invocation: "chat",
-      });
+    async execute(request) {
+      try {
+        const result = await executeHostedTool({
+          tools: hostedTools,
+          name: request.name,
+          input: request.input,
+          env,
+          signal,
+          invocation: "chat",
+          clock,
+        });
+        toolCalls?.push(result);
+        return result;
+      } catch (error) {
+        toolCalls?.push(failedHostedToolCall(hostedTools, request, error));
+        throw error;
+      }
     },
   };
 }
 
 async function executeHostedTool(request) {
+  const hostedTools = request.tools ?? createHostedTools(request.env);
   const tool = hostedTools.find((candidate) => candidate.name === request.name);
   const id = crypto.randomUUID();
 
@@ -1099,6 +1999,16 @@ async function executeHostedTool(request) {
 
   const secrets = resolveToolSecrets(tool, request.env);
   const database = createHostedDatabaseRunner(request.env);
+  const clock = request.clock ?? buildRuntimeClockContext({
+    timeZone: manifest.timeZone,
+    env: request.env,
+  });
+  const runtime = {
+    environment: "hosted",
+    invocation: request.invocation ?? "tool",
+    target: "cloudflare",
+    database: manifest.storage.database.driver === "turso" ? "turso" : "none",
+  };
   const output = await runToolWithTimeout(
     tool,
     input,
@@ -1106,12 +2016,8 @@ async function executeHostedTool(request) {
       secrets,
       database,
       signal: request.signal,
-      runtime: {
-        environment: "hosted",
-        invocation: request.invocation ?? "tool",
-        target: "cloudflare",
-        database: manifest.storage.database.driver === "turso" ? "turso" : "none",
-      },
+      clock,
+      runtime,
     },
     tool.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS,
   );
@@ -1120,6 +2026,8 @@ async function executeHostedTool(request) {
     validateSchema(output, tool.outputSchema, \`tool "\${tool.name}" output\`);
   }
 
+  const rendered = renderHostedToolOutput(tool, input, output, runtime, clock);
+
   return {
     id,
     name: tool.name,
@@ -1127,9 +2035,135 @@ async function executeHostedTool(request) {
     status: "completed",
     input,
     output,
+    ...(rendered ? { rendered } : {}),
+  };
+}
+
+function failedHostedToolCall(tools, request, error) {
+  const tool = tools.find((candidate) => candidate.name === request.name);
+
+  return {
+    id: crypto.randomUUID(),
+    name: String(request.name || ""),
+    visibility: tool?.visibility ?? "user",
+    status: "failed",
+    input: request.input ?? {},
+    errorMessage: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function renderHostedToolOutput(tool, input, output, runtime, clock) {
+  if (!tool.render) {
+    return undefined;
+  }
+
+  const rendered = tool.render(output, {
+    input,
+    runtime,
+    clock,
+  });
+
+  if (typeof rendered === "string") {
+    return { text: rendered };
+  }
+
+  if (!isRecord(rendered) || typeof rendered.text !== "string" || rendered.text.trim().length === 0) {
+    throw agentKitError("tool_validation_error", \`tool "\${tool.name}" render must return a non-empty text string.\`);
+  }
+
+  if (rendered.blocks !== undefined) {
+    if (!Array.isArray(rendered.blocks)) {
+      throw agentKitError("tool_validation_error", \`tool "\${tool.name}" render.blocks must be an array when provided.\`);
+    }
+
+    for (const [index, block] of rendered.blocks.entries()) {
+      validateRenderBlock(block, \`tool "\${tool.name}" render.blocks[\${index}]\`);
+    }
+  }
+
+  return {
+    text: rendered.text,
+    ...(rendered.blocks ? { blocks: rendered.blocks } : {}),
   };
 }
 
+function validateRenderBlock(block, label) {
+  if (!isRecord(block)) {
+    throw agentKitError("tool_validation_error", \`\${label} must be an object.\`);
+  }
+
+  if (block.type === "text") {
+    if (typeof block.text !== "string" || block.text.trim().length === 0) {
+      throw agentKitError("tool_validation_error", \`\${label}.text must be a non-empty string.\`);
+    }
+
+    return;
+  }
+
+  if (block.type === "card") {
+    if (typeof block.title !== "string" || block.title.trim().length === 0) {
+      throw agentKitError("tool_validation_error", \`\${label}.title must be a non-empty string.\`);
+    }
+
+    validateOptionalString(block.subtitle, \`\${label}.subtitle\`);
+    validateRenderFields(block.fields, \`\${label}.fields\`);
+    validateRenderActions(block.actions, \`\${label}.actions\`);
+    return;
+  }
+
+  throw agentKitError("tool_validation_error", \`\${label}.type must be "text" or "card".\`);
+}
+
+function validateRenderFields(value, label) {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw agentKitError("tool_validation_error", \`\${label} must be an array when provided.\`);
+  }
+
+  for (const [index, field] of value.entries()) {
+    if (!isRecord(field)) {
+      throw agentKitError("tool_validation_error", \`\${label}[\${index}] must be an object.\`);
+    }
+
+    validateRequiredString(field.label, \`\${label}[\${index}].label\`);
+    validateRequiredString(field.value, \`\${label}[\${index}].value\`);
+  }
+}
+
+function validateRenderActions(value, label) {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw agentKitError("tool_validation_error", \`\${label} must be an array when provided.\`);
+  }
+
+  for (const [index, action] of value.entries()) {
+    if (!isRecord(action)) {
+      throw agentKitError("tool_validation_error", \`\${label}[\${index}] must be an object.\`);
+    }
+
+    validateRequiredString(action.label, \`\${label}[\${index}].label\`);
+    validateOptionalString(action.href, \`\${label}[\${index}].href\`);
+  }
+}
+
+function validateRequiredString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw agentKitError("tool_validation_error", \`\${label} must be a non-empty string.\`);
+  }
+}
+
+function validateOptionalString(value, label) {
+  if (value !== undefined && typeof value !== "string") {
+    throw agentKitError("tool_validation_error", \`\${label} must be a string when provided.\`);
+  }
+}
+
 function resolveToolSecrets(tool, env) {
   const secrets = {};
 
@@ -1170,6 +2204,7 @@ async function runToolWithTimeout(tool, input, context, timeoutMs) {
         secrets: context.secrets,
         signal: controller.signal,
         runtime: context.runtime,
+        clock: context.clock,
         database: context.database,
         db: context.database,
         storage: {
@@ -1395,6 +2430,20 @@ function allowsNull(schema) {
 }
 
 async function authorizeChat(request, env, body) {
+  return authorizeDeployAccess(request, env, body, {
+    notConfiguredCode: "chat_access_not_configured",
+    notConfiguredMessage: "Hosted chat requires a deploy access token gate.",
+  });
+}
+
+async function authorizeConversationRead(request, env) {
+  return authorizeDeployAccess(request, env, {}, {
+    notConfiguredCode: "conversation_access_not_configured",
+    notConfiguredMessage: "Hosted conversation reads require a deploy access token gate.",
+  });
+}
+
+async function authorizeDeployAccess(request, env, body, options) {
   const runtimeGate = await authorizeRuntimeGate(request, env, body);
 
   if (runtimeGate) {
@@ -1405,52 +2454,28 @@ async function authorizeChat(request, env, body) {
     return runtimeGate;
   }
 
-  if (manifest.access.mode === "public") {
-    return null;
-  }
+  const token = deployAccessToken(request, body);
+  const acceptedTokens = [env.AGENTKIT_PRIVATE_TOKEN, env.AGENTKIT_ACCESS_TOKEN].filter(
+    (value) => typeof value === "string" && value.length > 0,
+  );
 
-  if (manifest.access.mode === "private") {
-    if (!env.AGENTKIT_PRIVATE_TOKEN) {
-      return Response.json(
-        {
-          error: {
-            code: "deploy_not_ready",
-            message: "Private deploy requires AGENTKIT_PRIVATE_TOKEN to be set as a Cloudflare secret.",
-          },
+  if (acceptedTokens.length === 0) {
+    return Response.json(
+      {
+        error: {
+          code: options.notConfiguredCode,
+          message: options.notConfiguredMessage,
         },
-        { status: 503 },
-      );
-    }
-
-    const expected = \`Bearer \${env.AGENTKIT_PRIVATE_TOKEN}\`;
-    if (request.headers.get("authorization") !== expected) {
-      return Response.json(
-        { error: { code: "unauthorized", message: "Missing or invalid deploy access token." } },
-        { status: 401 },
-      );
-    }
+      },
+      { status: 503 },
+    );
   }
 
-  if (manifest.access.mode === "token") {
-    if (!env.AGENTKIT_ACCESS_TOKEN) {
-      return Response.json(
-        {
-          error: {
-            code: "deploy_not_ready",
-            message: "Token deploy requires AGENTKIT_ACCESS_TOKEN to be set as a Cloudflare secret.",
-          },
-        },
-        { status: 503 },
-      );
-    }
-
-    const expected = \`Bearer \${env.AGENTKIT_ACCESS_TOKEN}\`;
-    if (request.headers.get("authorization") !== expected) {
-      return Response.json(
-        { error: { code: "unauthorized", message: "Missing or invalid deploy access token." } },
-        { status: 401 },
-      );
-    }
+  if (!token || !acceptedTokens.includes(token)) {
+    return Response.json(
+      { error: { code: "unauthorized", message: "Missing or invalid deploy access token." } },
+      { status: 401 },
+    );
   }
 
   return null;
@@ -1552,8 +2577,7 @@ async function persist(env, input) {
     return {};
   }
 
-  const id = env.AGENTKIT_CONVERSATIONS.idFromName(input.conversationId);
-  const stub = env.AGENTKIT_CONVERSATIONS.get(id);
+  const stub = hostedConversationStore(env);
   const response = await stub.fetch("https://agentkit.internal/messages", {
     method: "POST",
     body: JSON.stringify(input),
@@ -1566,6 +2590,148 @@ async function persist(env, input) {
   return response.json();
 }
 
+function queueRuntimeUsage(ctx, promise) {
+  const safePromise = promise.catch(() => undefined);
+
+  if (ctx && typeof ctx.waitUntil === "function") {
+    ctx.waitUntil(safePromise);
+    return;
+  }
+
+  void safePromise;
+}
+
+async function sendRuntimeUsage(env, input) {
+  if (!env.AGENTKIT_CLOUD_API_URL || !env.AGENTKIT_DEPLOY_ID || !env.AGENTKIT_RUNTIME_GATE_TOKEN) {
+    return;
+  }
+
+  const usage = normalizeRuntimeUsage(input.usage);
+  const metadata = isRecord(input.metadata) ? input.metadata : {};
+  const body = {
+    kind: input.kind || "chat_run",
+    status: input.status || "succeeded",
+    ...(input.runId ? { run_id: String(input.runId) } : {}),
+    ...(input.conversationId ? { conversation_id: String(input.conversationId) } : {}),
+    ...(input.provider ? { provider: String(input.provider) } : {}),
+    ...(input.model ? { model: String(input.model) } : {}),
+    ...(usage.inputTokens !== undefined ? { input_tokens: usage.inputTokens } : {}),
+    ...(usage.outputTokens !== undefined ? { output_tokens: usage.outputTokens } : {}),
+    ...(usage.totalTokens !== undefined ? { total_tokens: usage.totalTokens } : {}),
+    ...(usage.cost && Object.keys(usage.cost).length > 0 ? { cost: usage.cost } : {}),
+    ...(usage.cost?.total !== undefined ? { cost_usd: usage.cost.total } : {}),
+    metadata: sanitizeRuntimeUsageMetadata(metadata),
+  };
+
+  const url = new URL(
+    "/v1/runtime/deploys/" + encodeURIComponent(String(env.AGENTKIT_DEPLOY_ID)) + "/usage",
+    env.AGENTKIT_CLOUD_API_URL,
+  );
+  await fetch(url.href, {
+    method: "POST",
+    headers: {
+      Authorization: "Bearer " + env.AGENTKIT_RUNTIME_GATE_TOKEN,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+function sanitizeRuntimeUsageMetadata(value) {
+  const metadata = {};
+
+  for (const [key, raw] of Object.entries(value)) {
+    if (!/^[A-Za-z0-9_.:-]{1,80}$/.test(key)) {
+      continue;
+    }
+
+    if (typeof raw === "string") {
+      metadata[key] = raw.length > 160 ? raw.slice(0, 160) : raw;
+    } else if (typeof raw === "number" && Number.isFinite(raw)) {
+      metadata[key] = raw;
+    } else if (typeof raw === "boolean") {
+      metadata[key] = raw;
+    }
+  }
+
+  return metadata;
+}
+
+async function loadConversationMessages(env, conversationId) {
+  if (!env.AGENTKIT_CONVERSATIONS || !conversationId) {
+    return [];
+  }
+
+  const stub = hostedConversationStore(env);
+  const response = await stub.fetch(
+    \`https://agentkit.internal/messages?conversationId=\${encodeURIComponent(conversationId)}\`,
+  );
+
+  if (!response.ok) {
+    return [];
+  }
+
+  const payload = await response.json();
+  const messages = Array.isArray(payload.messages)
+    ? payload.messages.filter((message) =>
+        message &&
+        typeof message === "object" &&
+        (message.role === "user" || message.role === "assistant") &&
+        typeof message.content === "string"
+      )
+    : [];
+
+  if (messages.length > 0) {
+    return messages;
+  }
+
+  const legacyStub = legacyConversationStore(env, conversationId);
+  const legacyResponse = await legacyStub.fetch(
+    \`https://agentkit.internal/messages?conversationId=\${encodeURIComponent(conversationId)}\`,
+  );
+
+  if (!legacyResponse.ok) {
+    return [];
+  }
+
+  const legacyPayload = await legacyResponse.json();
+  return Array.isArray(legacyPayload.messages)
+    ? legacyPayload.messages.filter((message) =>
+        message &&
+        typeof message === "object" &&
+        (message.role === "user" || message.role === "assistant") &&
+        typeof message.content === "string"
+      )
+    : [];
+}
+
+function hostedConversationStore(env) {
+  const id = env.AGENTKIT_CONVERSATIONS.idFromName("agentkit-conversations");
+  return env.AGENTKIT_CONVERSATIONS.get(id);
+}
+
+function legacyConversationStore(env, conversationId) {
+  const id = env.AGENTKIT_CONVERSATIONS.idFromName(conversationId);
+  return env.AGENTKIT_CONVERSATIONS.get(id);
+}
+
+function normalizeConversationId(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  if (typeof value !== "string") {
+    throw agentKitError("validation_error", "conversationId must be a non-empty string when provided.");
+  }
+
+  const conversationId = value.trim();
+  if (!conversationId) {
+    throw agentKitError("validation_error", "conversationId must be a non-empty string when provided.");
+  }
+
+  return conversationId;
+}
+
 function agentKitError(code, message) {
   const error = new Error(message);
   error.code = code;
@@ -1823,6 +2989,80 @@ function titleFromMessage(content) {
   const compact = content.split(/\\r?\\n/, 1)[0].replace(/\\s+/g, " ").trim();
   return compact.length <= 80 ? compact : \`\${compact.slice(0, 77)}...\`;
 }
+
+function readStoredUsage(row) {
+  const usage = {};
+  const inputTokens = normalizeRuntimeInteger(row.input_tokens);
+  const outputTokens = normalizeRuntimeInteger(row.output_tokens);
+  const totalTokens = normalizeRuntimeInteger(row.total_tokens);
+  const cost = normalizeRuntimeCost(parseStoredJson(row.cost_json, {}));
+
+  if (inputTokens !== undefined) usage.inputTokens = inputTokens;
+  if (outputTokens !== undefined) usage.outputTokens = outputTokens;
+  if (totalTokens !== undefined) usage.totalTokens = totalTokens;
+  if (Object.keys(cost).length > 0) usage.cost = cost;
+
+  return usage;
+}
+
+function normalizeRuntimeUsage(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+
+  const usage = {};
+  const inputTokens = normalizeRuntimeInteger(value.inputTokens ?? value.input_tokens);
+  const outputTokens = normalizeRuntimeInteger(value.outputTokens ?? value.output_tokens);
+  const totalTokens = normalizeRuntimeInteger(value.totalTokens ?? value.total_tokens);
+  const cost = normalizeRuntimeCost(value.cost);
+
+  if (inputTokens !== undefined) usage.inputTokens = inputTokens;
+  if (outputTokens !== undefined) usage.outputTokens = outputTokens;
+  if (totalTokens !== undefined) usage.totalTokens = totalTokens;
+  if (Object.keys(cost).length > 0) usage.cost = cost;
+
+  return usage;
+}
+
+function normalizeRuntimeCost(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+
+  const cost = {};
+
+  for (const field of ["input", "output", "cacheRead", "cacheWrite", "total"]) {
+    const normalized = normalizeRuntimeNumber(value[field]);
+
+    if (normalized !== undefined) {
+      cost[field] = normalized;
+    }
+  }
+
+  return cost;
+}
+
+function normalizeRuntimeInteger(value) {
+  const normalized = normalizeRuntimeNumber(value);
+  return normalized !== undefined && Number.isInteger(normalized) ? normalized : undefined;
+}
+
+function normalizeRuntimeNumber(value) {
+  const parsed = typeof value === "string" && value.trim() ? Number(value) : value;
+  return typeof parsed === "number" && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function parseStoredJson(value, fallback) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
 `;
 }
 
@@ -1893,6 +3133,10 @@ CREATE TABLE IF NOT EXISTS runs (
   status TEXT NOT NULL,
   error_code TEXT,
   error_message TEXT,
+  input_tokens INTEGER,
+  output_tokens INTEGER,
+  total_tokens INTEGER,
+  cost_json TEXT,
   created_at TEXT NOT NULL,
   completed_at TEXT
 );
@@ -1906,6 +3150,7 @@ CREATE TABLE IF NOT EXISTS tool_calls (
   status TEXT NOT NULL,
   input_json TEXT NOT NULL,
   output_json TEXT,
+  rendered_json TEXT,
   error_message TEXT,
   created_at TEXT NOT NULL,
   completed_at TEXT