@andreprado/agentkit 0.1.0-alpha.8 → 0.1.0

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/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;
+}

package/src/runtime/skills.ts

@@ -0,0 +1,95 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type DefaultSkillFile = {
+  path: string;
+  contents: string;
+};
+
+export type DefaultSkillStatus = {
+  status: "current" | "missing" | "outdated";
+  checked: number;
+  missing: string[];
+  outdated: string[];
+};
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export async function syncDefaultSkillFiles(projectPath: string): Promise<{ files: string[] }> {
+  const files = await loadDefaultSkillFiles();
+
+  for (const file of files) {
+    const absolutePath = join(projectPath, file.path);
+
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, file.contents);
+  }
+
+  return { files: files.map((file) => file.path) };
+}
+
+export async function checkDefaultSkillStatus(projectPath: string): Promise<DefaultSkillStatus> {
+  const files = await loadDefaultSkillFiles();
+  const missing: string[] = [];
+  const outdated: string[] = [];
+
+  for (const file of files) {
+    const absolutePath = join(projectPath, file.path);
+
+    if (!(await pathExists(absolutePath))) {
+      missing.push(file.path);
+      continue;
+    }
+
+    const current = await readFile(absolutePath, "utf8");
+    if (current !== file.contents) {
+      outdated.push(file.path);
+    }
+  }
+
+  return {
+    status: missing.length > 0 ? "missing" : outdated.length > 0 ? "outdated" : "current",
+    checked: files.length,
+    missing,
+    outdated,
+  };
+}
+
+export async function loadDefaultSkillFiles(): Promise<DefaultSkillFile[]> {
+  const sourceRoot = join(moduleDir, "..", "templates", "skills");
+  const sourceFiles = await listFiles(sourceRoot);
+
+  return Promise.all(
+    sourceFiles.map(async (sourcePath) => ({
+      path: join("skills", relative(sourceRoot, sourcePath)).replaceAll("\\", "/"),
+      contents: await readFile(sourcePath, "utf8"),
+    })),
+  );
+}
+
+async function listFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        return listFiles(path);
+      }
+
+      return entry.isFile() ? [path] : [];
+    }),
+  );
+
+  return files.flat().sort();
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}