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

package/src/runtime/knowledge/vector.ts

@@ -0,0 +1,258 @@
+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 type { DatabaseRow } from "../../index";
+
+export const KNOWLEDGE_VECTOR_TABLE = "agentkit_knowledge_vectors";
+export const KNOWLEDGE_VECTOR_INDEX = "agentkit_knowledge_vectors_embedding_idx";
+const KNOWLEDGE_VECTOR_SOURCE_INDEX = "agentkit_knowledge_vectors_source_idx";
+
+export type LocalKnowledgeVectorStatus = {
+  enabled: boolean;
+  provider: "libsql" | "none" | "json_fallback";
+  chunksIndexed: number;
+  message: string;
+};
+
+export function localKnowledgeVectorDatabasePath(databasePath: string): string {
+  const extension = extname(databasePath);
+  const stem = extension ? basename(databasePath, extension) : basename(databasePath);
+  return join(dirname(databasePath), `${stem}.vectors.db`);
+}
+
+export async function localKnowledgeVectorDatabaseExists(databasePath: string): Promise<boolean> {
+  return access(localKnowledgeVectorDatabasePath(databasePath)).then(
+    () => true,
+    () => false,
+  );
+}
+
+export async function rebuildLocalKnowledgeVectorIndex(options: {
+  databasePath: string;
+  dimensions: number | null;
+}): Promise<LocalKnowledgeVectorStatus> {
+  if (!isPositiveInteger(options.dimensions)) {
+    return {
+      enabled: false,
+      provider: "none",
+      chunksIndexed: 0,
+      message: "Knowledge embeddings are disabled, so no local vector index was created.",
+    };
+  }
+
+  const mainClient = createClient({ url: pathToFileURL(options.databasePath).href });
+  const vectorClient = createClient({ url: pathToFileURL(localKnowledgeVectorDatabasePath(options.databasePath)).href });
+  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
+          c.id AS chunk_id,
+          c.source_id,
+          c.content,
+          c.title,
+          c.section,
+          c.locator,
+          c.embedding_json,
+          c.embedding_hash,
+          c.created_at,
+          s.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
+          AND c.embedding_hash IS NOT NULL
+          AND c.embedding_dimensions = ?
+        ORDER BY c.created_at DESC, c.ordinal ASC
+      `,
+      args: [dimensions],
+    });
+
+    let chunksIndexed = 0;
+
+    for (const row of rows.rows) {
+      const chunkId = readString(row, "chunk_id");
+      const sourceId = readString(row, "source_id");
+      const sourceKey = readString(row, "source_key");
+      const content = readString(row, "content");
+      const embeddingJson = readString(row, "embedding_json");
+      const embeddingHash = readString(row, "embedding_hash");
+      const createdAt = readString(row, "created_at");
+
+      if (!chunkId || !sourceId || !sourceKey || !content || !embeddingJson || !embeddingHash || !createdAt) {
+        continue;
+      }
+
+      await vectorClient.execute({
+        sql: `
+          INSERT INTO ${KNOWLEDGE_VECTOR_TABLE} (
+            chunk_id,
+            source_id,
+            source_key,
+            content,
+            title,
+            section,
+            locator,
+            embedding,
+            embedding_hash,
+            created_at
+          )
+          VALUES (?, ?, ?, ?, ?, ?, ?, vector32(?), ?, ?)
+        `,
+        args: [
+          chunkId,
+          sourceId,
+          sourceKey,
+          content,
+          readNullableString(row, "title"),
+          readNullableString(row, "section"),
+          readNullableString(row, "locator"),
+          embeddingJson,
+          embeddingHash,
+          createdAt,
+        ],
+      });
+      chunksIndexed += 1;
+    }
+
+    await vectorClient.execute("PRAGMA wal_checkpoint(TRUNCATE)").catch(() => undefined);
+
+    return {
+      enabled: true,
+      provider: "libsql",
+      chunksIndexed,
+      message: `Local libSQL vector database rebuilt with ${chunksIndexed} chunk${chunksIndexed === 1 ? "" : "s"}.`,
+    };
+  } catch (error) {
+    return {
+      enabled: false,
+      provider: "json_fallback",
+      chunksIndexed: 0,
+      message: `Local libSQL vector index unavailable; using JSON embedding fallback. ${formatVectorError(error)}`,
+    };
+  } finally {
+    mainClient.close();
+    vectorClient.close();
+  }
+}
+
+export async function searchLocalKnowledgeVectorRows(options: {
+  databasePath: string;
+  queryEmbedding: number[];
+  limit: number;
+}): Promise<DatabaseRow[]> {
+  const vectorDatabasePath = localKnowledgeVectorDatabasePath(options.databasePath);
+
+  await access(vectorDatabasePath);
+
+  const client = createClient({ url: pathToFileURL(vectorDatabasePath).href });
+  const vector = JSON.stringify(options.queryEmbedding);
+
+  try {
+    const result = await client.execute({
+      sql: `
+        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.source_key AS source_key,
+          vector_distance_cos(c.embedding, vector32(?)) AS vector_distance
+        FROM vector_top_k('${KNOWLEDGE_VECTOR_INDEX}', vector32(?), ?) nearest
+        JOIN ${KNOWLEDGE_VECTOR_TABLE} c ON c.id = nearest.id
+        ORDER BY vector_distance ASC
+      `,
+      args: [vector, vector, options.limit],
+    });
+
+    return result.rows.map(normalizeLibsqlRow);
+  } finally {
+    client.close();
+  }
+}
+
+function normalizeLibsqlRow(row: unknown): DatabaseRow {
+  const result: DatabaseRow = {};
+
+  if (!row || typeof row !== "object") {
+    return result;
+  }
+
+  for (const [key, value] of Object.entries(row)) {
+    if (key === "length" || /^\d+$/.test(key)) {
+      continue;
+    }
+
+    if (typeof value === "bigint") {
+      result[key] = Number.isSafeInteger(Number(value)) ? Number(value) : String(value);
+      continue;
+    }
+
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      result[key] = value;
+      continue;
+    }
+
+    result[key] = String(value);
+  }
+
+  return result;
+}
+
+function isPositiveInteger(value: number | null): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function readString(row: unknown, key: string): string | null {
+  if (!row || typeof row !== "object" || !(key in row)) {
+    return null;
+  }
+
+  const value = (row as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function readNullableString(row: unknown, key: string): string | null {
+  if (!row || typeof row !== "object" || !(key in row)) {
+    return null;
+  }
+
+  const value = (row as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : null;
+}
+
+function formatVectorError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.length <= 240 ? message : `${message.slice(0, 237)}...`;
+}

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,21 +99,35 @@ export async function assertRuntimeContract(
 
   const chat = await fetchJson(`${baseUrl}/chat`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ message: { role: "user", content: "contract hello" } }),
+    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);
   expect(chat.body).toMatchObject({
     message: {
       role: "assistant",
-      content: "Echo: contract hello",
+      content: "Echo: my name is Ada",
     },
   });
   expect(typeof chat.body.conversationId).toBe("string");
 
+  const continuedChat = await fetchJson(`${baseUrl}/chat`, {
+    method: "POST",
+    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);
+  expect(continuedChat.body).toMatchObject({
+    conversationId: chat.body.conversationId,
+    message: {
+      role: "assistant",
+      content: "Your name is Ada.",
+    },
+  });
+
   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);
@@ -64,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);
@@ -77,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;
+  }
+}