@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/src/runtime/knowledge/embeddings.ts

@@ -5,8 +5,15 @@ import { AgentKitError } from "../errors";
 
 export type EmbeddingProvider = {
   embed(input: string): Promise<number[]>;
+  /** Embeds inputs in as few provider requests as possible; results keep input order. */
+  embedMany(inputs: string[]): Promise<number[][]>;
 };
 
+// Each valid input is at most 8,192 tokens; 36 inputs cannot exceed the
+// 300,000-token request limit, even for long CSV rows or dense text.
+// ponytail: conservative batches; add token-aware packing if throughput needs it.
+const OPENAI_EMBEDDING_BATCH_SIZE = Math.floor(300_000 / 8_192);
+
 export type CreateEmbeddingProviderOptions = {
   config: ResolvedKnowledgeConfig["embedding"];
   env?: Record<string, string | undefined>;
@@ -23,13 +30,26 @@ export function createEmbeddingProvider(options: CreateEmbeddingProviderOptions)
       async embed(input) {
         return fakeEmbedding(input, options.config.dimensions ?? 32);
       },
+      async embedMany(inputs) {
+        return inputs.map((input) => fakeEmbedding(input, options.config.dimensions ?? 32));
+      },
     };
   }
 
   if (options.config.provider === "openai") {
     return {
       async embed(input) {
-        return openAiEmbedding(input, options);
+        const [embedding] = await openAiEmbeddings([input], options);
+        return embedding;
+      },
+      async embedMany(inputs) {
+        const embeddings: number[][] = [];
+
+        for (let start = 0; start < inputs.length; start += OPENAI_EMBEDDING_BATCH_SIZE) {
+          embeddings.push(...(await openAiEmbeddings(inputs.slice(start, start + OPENAI_EMBEDDING_BATCH_SIZE), options)));
+        }
+
+        return embeddings;
       },
     };
   }
@@ -74,7 +94,7 @@ export function cosineSimilarity(left: number[], right: number[]): number {
   return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
 }
 
-async function openAiEmbedding(input: string, options: CreateEmbeddingProviderOptions): Promise<number[]> {
+async function openAiEmbeddings(inputs: string[], options: CreateEmbeddingProviderOptions): Promise<number[][]> {
   const secretName = options.config.secret ?? "OPENAI_API_KEY";
   const apiKey = options.env?.[secretName] ?? process.env[secretName];
 
@@ -94,7 +114,7 @@ async function openAiEmbedding(input: string, options: CreateEmbeddingProviderOp
     },
     body: JSON.stringify({
       model: options.config.model ?? "text-embedding-3-small",
-      input,
+      input: inputs,
       encoding_format: "float",
       ...(options.config.dimensions ? { dimensions: options.config.dimensions } : {}),
     }),
@@ -109,13 +129,31 @@ async function openAiEmbedding(input: string, options: CreateEmbeddingProviderOp
   }
 
   const payload = await response.json();
-  const embedding = payload?.data?.[0]?.embedding;
+  const data: unknown[] = Array.isArray(payload?.data) ? payload.data : [];
+  const embeddings: number[][] = new Array(inputs.length);
+
+  for (const [position, item] of data.entries()) {
+    const record = item as { index?: unknown; embedding?: unknown };
+    const index = typeof record.index === "number" ? record.index : position;
+    const embedding = record.embedding;
+
+    if (
+      index >= 0 &&
+      index < inputs.length &&
+      Array.isArray(embedding) &&
+      embedding.every((value) => typeof value === "number")
+    ) {
+      embeddings[index] = embedding;
+    }
+  }
 
-  if (!Array.isArray(embedding) || embedding.some((value) => typeof value !== "number")) {
-    throw new AgentKitError("knowledge_embedding_failed", "OpenAI embedding response did not contain a numeric vector.");
+  for (let index = 0; index < inputs.length; index += 1) {
+    if (!embeddings[index]) {
+      throw new AgentKitError("knowledge_embedding_failed", "OpenAI embedding response did not contain a numeric vector.");
+    }
   }
 
-  return embedding;
+  return embeddings;
 }
 
 function normalizeVector(values: number[]): number[] {

package/src/runtime/knowledge/ingest.ts

@@ -151,7 +151,9 @@ async function ingestKnowledgeSources(
       }
     }
 
-    await checkpointLocalKnowledgeDatabase(db);
+    if (results.some((result) => result.status === "indexed")) {
+      await checkpointLocalKnowledgeDatabase(db);
+    }
   } finally {
     store.close();
   }
@@ -304,13 +306,28 @@ async function ingestKnowledgeSource(
     id: string;
   }> = [];
 
-  for (const chunk of chunks) {
-    const embedding = embeddingProvider ? await embeddingProvider.embed(chunk.content) : null;
+  const chunkHashes = chunks.map((chunk) => sha256(chunk.content));
+  const embeddingsByHash = embeddingProvider
+    ? await loadReusableChunkEmbeddings(db, sourceId, resolvedKnowledge)
+    : new Map<string, number[]>();
+
+  if (embeddingProvider) {
+    const missingHashes = [...new Set(chunkHashes.filter((hash) => !embeddingsByHash.has(hash)))];
+
+    if (missingHashes.length > 0) {
+      const contentByHash = new Map(chunks.map((chunk, index) => [chunkHashes[index], chunk.content]));
+      const embeddings = await embeddingProvider.embedMany(missingHashes.map((hash) => contentByHash.get(hash)!));
+      missingHashes.forEach((hash, index) => embeddingsByHash.set(hash, embeddings[index]));
+    }
+  }
+
+  for (const [index, chunk] of chunks.entries()) {
+    const contentSha256 = chunkHashes[index];
     embeddedChunks.push({
       chunk,
-      embedding,
-      contentSha256: sha256(chunk.content),
-      id: stableId("kchk", `${sourceId}:${chunk.ordinal}:${sha256(chunk.content)}`),
+      embedding: embeddingProvider ? embeddingsByHash.get(contentSha256) ?? null : null,
+      contentSha256,
+      id: stableId("kchk", `${sourceId}:${chunk.ordinal}:${contentSha256}`),
     });
   }
 
@@ -491,6 +508,52 @@ function capsuleRelativePath(root: string, absolutePath: string): string {
   return relativePath.split("\\").join("/");
 }
 
+// Chunks whose text is unchanged keep their stored vector, so editing one part
+// of a file only pays for embedding the chunks that actually changed.
+async function loadReusableChunkEmbeddings(
+  db: DatabaseRunner,
+  sourceId: string,
+  knowledge: ReturnType<typeof resolveKnowledgeConfig>,
+): Promise<Map<string, number[]>> {
+  const result = await db.query(
+    `
+    SELECT content_sha256, embedding_json
+    FROM agentkit_knowledge_chunks
+    WHERE source_id = ?
+      AND embedding_json IS NOT NULL
+      AND embedding_provider = ?
+      AND embedding_model = ?
+      AND (? IS NULL OR embedding_dimensions = ?)
+  `,
+    [
+      sourceId,
+      knowledge.embedding.provider,
+      knowledge.embedding.model,
+      knowledge.embedding.dimensions,
+      knowledge.embedding.dimensions,
+    ],
+  );
+  const embeddings = new Map<string, number[]>();
+
+  for (const row of result.rows) {
+    if (typeof row.content_sha256 !== "string" || typeof row.embedding_json !== "string") {
+      continue;
+    }
+
+    try {
+      const embedding = JSON.parse(row.embedding_json);
+
+      if (Array.isArray(embedding) && embedding.every((value) => typeof value === "number")) {
+        embeddings.set(row.content_sha256, embedding);
+      }
+    } catch {
+      // A corrupt stored vector is simply re-embedded.
+    }
+  }
+
+  return embeddings;
+}
+
 async function findExistingSource(db: DatabaseRunner, sourceKey: string): Promise<DatabaseRow | undefined> {
   const result = await db.query(
     "SELECT id, content_sha256, status FROM agentkit_knowledge_sources WHERE source_key = ?",

package/src/runtime/knowledge/retrieve.ts

@@ -108,7 +108,25 @@ async function searchLexical(db: DatabaseRunner, query: string, limit: number):
 }
 
 async function searchLexicalFallback(db: DatabaseRunner, query: string, limit: number): Promise<KnowledgeSearchResult[]> {
-  const like = `%${query.toLowerCase()}%`;
+  const tokens = queryTokens(query);
+
+  if (tokens.length === 0) {
+    return [];
+  }
+
+  const conditions = tokens
+    .map(
+      () => `(
+        lower(c.content) LIKE ? ESCAPE '\\'
+        OR lower(COALESCE(c.title, '')) LIKE ? ESCAPE '\\'
+        OR lower(COALESCE(c.section, '')) LIKE ? ESCAPE '\\'
+      )`,
+    )
+    .join(" AND ");
+  const args = tokens.flatMap((token) => {
+    const like = likePattern(token);
+    return [like, like, like];
+  });
   const result = await db.query(
     `
     SELECT
@@ -121,13 +139,11 @@ async function searchLexicalFallback(db: DatabaseRunner, query: string, limit: n
       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 ?
+    WHERE ${conditions}
     ORDER BY c.created_at DESC, c.ordinal ASC
     LIMIT ?
   `,
-    [like, like, like, limit],
+    [...args, limit],
   );
 
   return result.rows.map((row, index) => knowledgeSearchResultFromRow(row, lexicalScore(index), null));
@@ -269,6 +285,10 @@ function queryTokens(query: string): string[] {
   return Array.from(new Set(query.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? [])).slice(0, 12);
 }
 
+function likePattern(token: string): string {
+  return `%${token.replace(/[\\%_]/g, (value) => `\\${value}`)}%`;
+}
+
 function parseEmbedding(value: unknown): number[] | null {
   if (typeof value !== "string") {
     return null;

package/src/runtime/knowledge/schema.ts

@@ -1,6 +1,12 @@
 export const KNOWLEDGE_MIGRATION_ID = "0006_create_knowledge_tables";
 
-export const KNOWLEDGE_SCHEMA_SQL = `
+type KnowledgeSchemaDatabase = {
+  exec(sql: string): unknown;
+};
+
+export type KnowledgeLexicalIndexMode = "fts5" | "fallback";
+
+export const KNOWLEDGE_BASE_SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS agentkit_knowledge_sources (
     id TEXT PRIMARY KEY,
     source_key TEXT NOT NULL UNIQUE,
@@ -43,7 +49,9 @@ export const KNOWLEDGE_SCHEMA_SQL = `
 
   CREATE INDEX IF NOT EXISTS agentkit_knowledge_chunks_source_ordinal_idx
     ON agentkit_knowledge_chunks(source_id, ordinal);
+`;
 
+export const KNOWLEDGE_FTS5_SCHEMA_SQL = `
   CREATE VIRTUAL TABLE IF NOT EXISTS agentkit_knowledge_fts
     USING fts5(
       chunk_id UNINDEXED,
@@ -54,3 +62,39 @@ export const KNOWLEDGE_SCHEMA_SQL = `
       tokenize='unicode61'
     );
 `;
+
+export const KNOWLEDGE_FTS_FALLBACK_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS agentkit_knowledge_fts (
+    chunk_id TEXT PRIMARY KEY,
+    source_id TEXT NOT NULL,
+    title TEXT,
+    section TEXT,
+    content TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS agentkit_knowledge_fts_source_idx
+    ON agentkit_knowledge_fts(source_id);
+`;
+
+export const KNOWLEDGE_SCHEMA_SQL = `${KNOWLEDGE_BASE_SCHEMA_SQL}\n${KNOWLEDGE_FTS5_SCHEMA_SQL}`;
+
+export function applyKnowledgeSchema(db: KnowledgeSchemaDatabase): KnowledgeLexicalIndexMode {
+  db.exec(KNOWLEDGE_BASE_SCHEMA_SQL);
+
+  try {
+    db.exec(KNOWLEDGE_FTS5_SCHEMA_SQL);
+    return "fts5";
+  } catch (error) {
+    if (!isMissingFts5ModuleError(error)) {
+      throw error;
+    }
+  }
+
+  db.exec(KNOWLEDGE_FTS_FALLBACK_SCHEMA_SQL);
+  return "fallback";
+}
+
+function isMissingFts5ModuleError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /no such module:\s*fts5/i.test(message) || /unknown module:\s*fts5/i.test(message);
+}

package/src/runtime/knowledge/vector.ts

@@ -2,7 +2,7 @@ import { access } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { createClient } from "@libsql/client";
+import { createClient, type InStatement } from "@libsql/client";
 
 import type { DatabaseRow } from "../../index";
 
@@ -48,32 +48,6 @@ export async function rebuildLocalKnowledgeVectorIndex(options: {
   const dimensions = options.dimensions;
 
   try {
-    await vectorClient.batch(
-      [
-        `DROP INDEX IF EXISTS ${KNOWLEDGE_VECTOR_INDEX}`,
-        `DROP INDEX IF EXISTS ${KNOWLEDGE_VECTOR_SOURCE_INDEX}`,
-        `DROP TABLE IF EXISTS ${KNOWLEDGE_VECTOR_TABLE}`,
-        `
-          CREATE TABLE ${KNOWLEDGE_VECTOR_TABLE} (
-            id INTEGER PRIMARY KEY,
-            chunk_id TEXT NOT NULL UNIQUE,
-            source_id TEXT NOT NULL,
-            source_key TEXT NOT NULL,
-            content TEXT NOT NULL,
-            title TEXT,
-            section TEXT,
-            locator TEXT,
-            embedding F32_BLOB(${dimensions}) NOT NULL,
-            embedding_hash TEXT NOT NULL,
-            created_at TEXT NOT NULL
-          )
-        `,
-        `CREATE INDEX ${KNOWLEDGE_VECTOR_SOURCE_INDEX} ON ${KNOWLEDGE_VECTOR_TABLE}(source_id)`,
-        `CREATE INDEX ${KNOWLEDGE_VECTOR_INDEX} ON ${KNOWLEDGE_VECTOR_TABLE}(libsql_vector_idx(embedding, 'metric=cosine'))`,
-      ],
-      "write",
-    );
-
     const rows = await mainClient.execute({
       sql: `
         SELECT
@@ -97,7 +71,31 @@ export async function rebuildLocalKnowledgeVectorIndex(options: {
       args: [dimensions],
     });
 
-    let chunksIndexed = 0;
+    // Drop, recreate, and refill in one write batch so a failed rebuild never
+    // leaves a half-populated index behind, and inserts share one transaction.
+    const schemaStatements: InStatement[] = [
+      `DROP INDEX IF EXISTS ${KNOWLEDGE_VECTOR_INDEX}`,
+      `DROP INDEX IF EXISTS ${KNOWLEDGE_VECTOR_SOURCE_INDEX}`,
+      `DROP TABLE IF EXISTS ${KNOWLEDGE_VECTOR_TABLE}`,
+      `
+        CREATE TABLE ${KNOWLEDGE_VECTOR_TABLE} (
+          id INTEGER PRIMARY KEY,
+          chunk_id TEXT NOT NULL UNIQUE,
+          source_id TEXT NOT NULL,
+          source_key TEXT NOT NULL,
+          content TEXT NOT NULL,
+          title TEXT,
+          section TEXT,
+          locator TEXT,
+          embedding F32_BLOB(${dimensions}) NOT NULL,
+          embedding_hash TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        )
+      `,
+      `CREATE INDEX ${KNOWLEDGE_VECTOR_SOURCE_INDEX} ON ${KNOWLEDGE_VECTOR_TABLE}(source_id)`,
+      `CREATE INDEX ${KNOWLEDGE_VECTOR_INDEX} ON ${KNOWLEDGE_VECTOR_TABLE}(libsql_vector_idx(embedding, 'metric=cosine'))`,
+    ];
+    const inserts: InStatement[] = [];
 
     for (const row of rows.rows) {
       const chunkId = readString(row, "chunk_id");
@@ -112,7 +110,7 @@ export async function rebuildLocalKnowledgeVectorIndex(options: {
         continue;
       }
 
-      await vectorClient.execute({
+      inserts.push({
         sql: `
           INSERT INTO ${KNOWLEDGE_VECTOR_TABLE} (
             chunk_id,
@@ -141,9 +139,11 @@ export async function rebuildLocalKnowledgeVectorIndex(options: {
           createdAt,
         ],
       });
-      chunksIndexed += 1;
     }
 
+    await vectorClient.batch([...schemaStatements, ...inserts], "write");
+    const chunksIndexed = inserts.length;
+
     await vectorClient.execute("PRAGMA wal_checkpoint(TRUNCATE)").catch(() => undefined);
 
     return {

package/src/runtime/prompt-context.ts

@@ -0,0 +1,141 @@
+export type RuntimePromptContextOptions = {
+  timeZone?: string | null;
+  env?: Record<string, string | undefined>;
+  now?: Date;
+  clock?: RuntimeClockContext;
+};
+
+export type RuntimePromptContext = {
+  isoTimestamp: string;
+  timeZone: string;
+  localDate: string;
+  localWeekday: string;
+  localDateTime: string;
+};
+
+export type RuntimeClockContext = RuntimePromptContext & {
+  now: Date;
+};
+
+const FALLBACK_TIME_ZONE = "UTC";
+const LOCALE = "en-US";
+
+export function appendRuntimePromptContext(
+  instructions: string,
+  options: RuntimePromptContextOptions = {},
+): string {
+  const context = options.clock ?? buildRuntimePromptContext(options);
+
+  return `${instructions.trimEnd()}
+
+Runtime context:
+- Current timestamp: ${context.isoTimestamp}
+- Time zone: ${context.timeZone}
+- Local date: ${context.localDate}
+- Local weekday: ${context.localWeekday}
+- Local date and time: ${context.localDateTime}
+
+Use this runtime context to interpret relative dates and times such as today, tomorrow, next Friday, and morning/afternoon. If a scheduling request depends on a different user or business time zone, ask for confirmation before booking.`;
+}
+
+export function buildRuntimePromptContext(options: RuntimePromptContextOptions = {}): RuntimePromptContext {
+  const clock = buildRuntimeClockContext(options);
+
+  return {
+    isoTimestamp: clock.isoTimestamp,
+    timeZone: clock.timeZone,
+    localDate: clock.localDate,
+    localWeekday: clock.localWeekday,
+    localDateTime: clock.localDateTime,
+  };
+}
+
+export function buildRuntimeClockContext(options: RuntimePromptContextOptions = {}): RuntimeClockContext {
+  if (options.clock) {
+    return options.clock;
+  }
+
+  const now = new Date((options.now ?? new Date()).getTime());
+
+  if (Number.isNaN(now.getTime())) {
+    throw new Error("runtime prompt context requires a valid Date.");
+  }
+
+  const timeZone = resolveRuntimeTimeZone(options);
+
+  return {
+    now,
+    isoTimestamp: now.toISOString(),
+    timeZone,
+    localDate: formatLocalDate(now, timeZone),
+    localWeekday: formatDateTime(now, timeZone, {
+      weekday: "long",
+    }),
+    localDateTime: formatDateTime(now, timeZone, {
+      weekday: "long",
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+      timeZoneName: "short",
+    }),
+  };
+}
+
+export function resolveRuntimeTimeZone(options: RuntimePromptContextOptions = {}): string {
+  if (options.timeZone?.trim()) {
+    return normalizeTimeZone(options.timeZone, "timeZone");
+  }
+
+  const explicitEnvTimeZone = options.env?.AGENTKIT_TIME_ZONE?.trim();
+
+  if (explicitEnvTimeZone) {
+    return normalizeTimeZone(explicitEnvTimeZone, "AGENTKIT_TIME_ZONE");
+  }
+
+  const processTimeZone = options.env?.TZ?.trim();
+
+  if (processTimeZone && isValidTimeZone(processTimeZone)) {
+    return processTimeZone;
+  }
+
+  return normalizeTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone || FALLBACK_TIME_ZONE, "runtime time zone");
+}
+
+export function isValidTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat(LOCALE, { timeZone: value }).format(new Date(0));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeTimeZone(value: string, source: string): string {
+  const timeZone = value.trim();
+
+  if (!isValidTimeZone(timeZone)) {
+    throw new Error(`${source} must be a valid IANA time zone such as "UTC" or "America/New_York".`);
+  }
+
+  return timeZone;
+}
+
+function formatLocalDate(date: Date, timeZone: string): string {
+  const parts = new Intl.DateTimeFormat(LOCALE, {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(date);
+  const byType = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+  return `${byType.year}-${byType.month}-${byType.day}`;
+}
+
+function formatDateTime(date: Date, timeZone: string, options: Intl.DateTimeFormatOptions): string {
+  return new Intl.DateTimeFormat(LOCALE, {
+    ...options,
+    timeZone,
+  }).format(date);
+}

package/src/runtime/runtime-contract.ts

@@ -7,6 +7,10 @@ export type RuntimeContractTarget = {
 
 export type RuntimeContractOptions = {
   expectedAgentName: string;
+  auth?: {
+    chat?: HeadersInit;
+    admin?: HeadersInit;
+  };
   tool: {
     name: string;
     input: unknown;
@@ -20,20 +24,74 @@ export async function assertRuntimeContract(
 ): Promise<void> {
   const baseUrl = target.baseUrl.replace(/\/$/, "");
 
-  const root = await fetch(`${baseUrl}/`);
+  const root = await fetch(`${baseUrl}/`, { headers: options.auth?.chat });
   expect(root.status).toBe(200);
 
   const health = await fetchJson(`${baseUrl}/health`);
   expect(health.status).toBe(200);
   expect(health.body).toMatchObject({ status: "ok" });
 
-  const inspect = await fetchJson(`${baseUrl}/_agentkit`);
+  const inspect = await fetchJson(`${baseUrl}/_agentkit`, { headers: options.auth?.admin });
   expect(inspect.status).toBe(200);
   expect(inspect.body).toMatchObject({ agent: options.expectedAgentName });
 
+  if (options.auth) {
+    const missingAdmin = await fetchJson(`${baseUrl}/_agentkit`);
+    expect(missingAdmin.status).toBe(401);
+    expect(missingAdmin.body.error.code).toBe("unauthorized");
+
+    const invalidAdmin = await fetchJson(`${baseUrl}/_agentkit`, {
+      headers: { Authorization: "Bearer invalid-admin-token" },
+    });
+    expect(invalidAdmin.status).toBe(401);
+    expect(invalidAdmin.body.error.code).toBe("unauthorized");
+
+    const missingChat = await fetchJson(`${baseUrl}/chat`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ message: "hello" }),
+    });
+    expect(missingChat.status).toBe(401);
+    expect(missingChat.body.error.code).toBe("unauthorized");
+
+    const invalidChat = await fetchJson(`${baseUrl}/chat`, {
+      method: "POST",
+      headers: { "content-type": "application/json", Authorization: "Bearer invalid-chat-token" },
+      body: JSON.stringify({ message: "hello" }),
+    });
+    expect(invalidChat.status).toBe(401);
+    expect(invalidChat.body.error.code).toBe("unauthorized");
+
+    const missingTool = await fetchJson(`${baseUrl}/tools/${encodeURIComponent(options.tool.name)}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ input: options.tool.input }),
+    });
+    expect(missingTool.status).toBe(401);
+    expect(missingTool.body.error.code).toBe("unauthorized");
+
+    const invalidTool = await fetchJson(`${baseUrl}/tools/${encodeURIComponent(options.tool.name)}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", Authorization: "Bearer invalid-admin-token" },
+      body: JSON.stringify({ input: options.tool.input }),
+    });
+    expect(invalidTool.status).toBe(401);
+    expect(invalidTool.body.error.code).toBe("unauthorized");
+
+    const missingConversations = await fetchJson(`${baseUrl}/v1/conversations`);
+    expect(missingConversations.status).toBe(401);
+    expect(missingConversations.body.error.code).toBe("unauthorized");
+
+    const invalidConversations = await fetchJson(`${baseUrl}/v1/conversations`, {
+      headers: { Authorization: "Bearer invalid-admin-token" },
+    });
+    expect(invalidConversations.status).toBe(401);
+    expect(invalidConversations.body.error.code).toBe("unauthorized");
+  }
+
   const unauthorized = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.chat),
     body: JSON.stringify({ message: { role: "assistant", content: "not allowed" } }),
   });
   expect(unauthorized.status).toBe(400);
@@ -41,7 +99,7 @@ export async function assertRuntimeContract(
 
   const chat = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.chat),
     body: JSON.stringify({ message: { role: "user", content: "my name is Ada" } }),
   });
   expect(chat.status).toBe(200);
@@ -55,7 +113,7 @@ export async function assertRuntimeContract(
 
   const continuedChat = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.chat),
     body: JSON.stringify({ message: "what is my name?", conversationId: chat.body.conversationId }),
   });
   expect(continuedChat.status).toBe(200);
@@ -69,7 +127,7 @@ export async function assertRuntimeContract(
 
   const tool = await fetchJson(`${baseUrl}/tools/${encodeURIComponent(options.tool.name)}`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: withHeaders({ "content-type": "application/json" }, options.auth?.admin),
     body: JSON.stringify({ input: options.tool.input }),
   });
   expect(tool.status).toBe(200);
@@ -78,7 +136,7 @@ export async function assertRuntimeContract(
     output: options.tool.expectedOutput,
   });
 
-  const conversations = await fetchJson(`${baseUrl}/v1/conversations`);
+  const conversations = await fetchJson(`${baseUrl}/v1/conversations`, { headers: options.auth?.admin });
   expect(conversations.status).toBe(200);
   expect(conversations.body.conversations.length).toBeGreaterThanOrEqual(1);
   expect(conversations.body.conversations.some((conversation: { id: string }) => conversation.id === chat.body.conversationId)).toBe(true);
@@ -91,3 +149,9 @@ async function fetchJson(url: string, init?: RequestInit): Promise<{ status: num
     body: await response.json(),
   };
 }
+
+function withHeaders(required: HeadersInit, extra: HeadersInit | undefined): Headers {
+  const headers = new Headers(extra);
+  new Headers(required).forEach((value, key) => headers.set(key, value));
+  return headers;
+}