@andreprado/agentkit 0.1.0-alpha.10

package/src/runtime/tools.ts

@@ -0,0 +1,470 @@
+import type { AgentTool, JsonSchema, ToolContext, ToolRenderResult, ToolRuntimeContext } from "../index";
+import type { SqliteAgentKitStore } from "../storage/sqlite";
+import { createLocalDatabaseRunner } from "./database";
+import { AgentKitError } from "./errors";
+
+export type ToolCallRequest = {
+  name: string;
+  input?: unknown;
+};
+
+export type ToolCallResult = {
+  id: string;
+  name: string;
+  visibility: "user" | "internal";
+  input: unknown;
+  output: unknown;
+  rendered?: ToolRenderResult;
+};
+
+export type ToolRuntime = {
+  definitions: AgentTool[];
+  execute(request: ToolCallRequest): Promise<ToolCallResult>;
+};
+
+export type ToolRuntimeOptions = {
+  tools: AgentTool[];
+  store: SqliteAgentKitStore;
+  runId: string;
+  conversationId: string;
+  env?: Record<string, string | undefined>;
+  signal?: AbortSignal;
+  defaultTimeoutMs?: number;
+  runtime: ToolRuntimeContext;
+};
+
+const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+
+export function createToolRuntime(options: ToolRuntimeOptions): ToolRuntime {
+  const toolsByName = new Map<string, AgentTool>();
+
+  for (const tool of options.tools) {
+    if (toolsByName.has(tool.name)) {
+      throw new AgentKitError("invalid_config", `Duplicate tool name "${tool.name}" in agentkit.config.ts.`);
+    }
+
+    toolsByName.set(tool.name, tool);
+  }
+
+  return {
+    definitions: options.tools,
+    execute(request) {
+      return executeToolCall(request, toolsByName, options);
+    },
+  };
+}
+
+async function executeToolCall(
+  request: ToolCallRequest,
+  toolsByName: Map<string, AgentTool>,
+  options: ToolRuntimeOptions,
+): Promise<ToolCallResult> {
+  let input: unknown = request.input ?? {};
+  const tool = toolsByName.get(request.name);
+  const preliminarySecretValues = collectConfiguredSecretValues(tool, options.env ?? process.env);
+  const toolCall = options.store.createToolCall({
+    runId: options.runId,
+    conversationId: options.conversationId,
+    toolName: request.name,
+    visibility: tool?.visibility ?? "user",
+    permissions: tool?.permissions ?? [],
+    input,
+    secretValues: preliminarySecretValues,
+  });
+
+  try {
+    if (!tool) {
+      throw new AgentKitError("tool_not_found", `Tool "${request.name}" is not declared in agentkit.config.ts.`);
+    }
+
+    input = normalizeOptionalNulls(input, tool.inputSchema);
+    validateSchema(input, tool.inputSchema, `tool "${tool.name}" input`);
+
+    const { secrets, secretValues } = resolveToolSecrets(tool, options.env ?? process.env);
+    const database = createLocalDatabaseRunner(options.store);
+    const output = await runToolWithTimeout(
+      tool,
+      input,
+      {
+        secrets,
+        database,
+        runtime: options.runtime,
+        signal: options.signal,
+      },
+      tool.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS,
+    );
+
+    if (tool.outputSchema) {
+      validateSchema(output, tool.outputSchema, `tool "${tool.name}" output`);
+    }
+
+    const rendered = renderToolOutput(tool, input, output, options.runtime);
+
+    options.store.completeToolCall({
+      toolCallId: toolCall.id,
+      status: "completed",
+      output,
+      rendered,
+      secretValues,
+    });
+
+    return {
+      id: toolCall.id,
+      name: tool.name,
+      visibility: tool.visibility ?? "user",
+      input,
+      output,
+      ...(rendered ? { rendered } : {}),
+    };
+  } catch (error) {
+    const secretValues = collectConfiguredSecretValues(tool, options.env ?? process.env);
+
+    options.store.completeToolCall({
+      toolCallId: toolCall.id,
+      status: "failed",
+      errorMessage: error instanceof Error ? error.message : String(error),
+      secretValues,
+    });
+
+    throw error;
+  }
+}
+
+function renderToolOutput(
+  tool: AgentTool,
+  input: unknown,
+  output: unknown,
+  runtime: ToolRuntimeContext,
+): ToolRenderResult | undefined {
+  if (!tool.render) {
+    return undefined;
+  }
+
+  const rendered = tool.render(output, {
+    input,
+    runtime,
+  });
+
+  if (typeof rendered === "string") {
+    return { text: rendered };
+  }
+
+  if (!isRecord(rendered) || typeof rendered.text !== "string" || rendered.text.trim().length === 0) {
+    throw new 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 new 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: unknown, label: string): void {
+  if (!isRecord(block)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an object.`);
+  }
+
+  if (block.type === "text") {
+    if (typeof block.text !== "string" || block.text.trim().length === 0) {
+      throw new 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 new 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 new AgentKitError("tool_validation_error", `${label}.type must be "text" or "card".`);
+}
+
+function validateRenderFields(value: unknown, label: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an array when provided.`);
+  }
+
+  for (const [index, field] of value.entries()) {
+    if (!isRecord(field)) {
+      throw new 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: unknown, label: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an array when provided.`);
+  }
+
+  for (const [index, action] of value.entries()) {
+    if (!isRecord(action)) {
+      throw new 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: unknown, label: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new AgentKitError("tool_validation_error", `${label} must be a non-empty string.`);
+  }
+}
+
+function validateOptionalString(value: unknown, label: string): void {
+  if (value !== undefined && typeof value !== "string") {
+    throw new AgentKitError("tool_validation_error", `${label} must be a string when provided.`);
+  }
+}
+
+function resolveToolSecrets(
+  tool: AgentTool,
+  env: Record<string, string | undefined>,
+): { secrets: Record<string, string>; secretValues: string[] } {
+  const secrets: Record<string, string> = {};
+
+  for (const secretName of tool.secrets ?? []) {
+    const value = env[secretName];
+
+    if (!value) {
+      throw new AgentKitError("tool_secret_missing", `Tool "${tool.name}" requires missing secret "${secretName}".`);
+    }
+
+    secrets[secretName] = value;
+  }
+
+  return { secrets, secretValues: Object.values(secrets) };
+}
+
+function collectConfiguredSecretValues(tool: AgentTool | undefined, env: Record<string, string | undefined>): string[] {
+  if (!tool) {
+    return [];
+  }
+
+  return (tool.secrets ?? []).flatMap((secretName) => {
+    const value = env[secretName];
+    return value ? [value] : [];
+  });
+}
+
+async function runToolWithTimeout(
+  tool: AgentTool,
+  input: unknown,
+  context: Pick<ToolContext, "secrets" | "database" | "runtime"> & { signal?: AbortSignal },
+  timeoutMs: number,
+): Promise<unknown> {
+  const controller = new AbortController();
+  const parentSignal = context.signal;
+
+  if (parentSignal?.aborted) {
+    throw new AgentKitError("runtime_aborted", `Tool "${tool.name}" was aborted before it started.`);
+  }
+
+  const abortFromParent = () => controller.abort(parentSignal?.reason);
+  parentSignal?.addEventListener("abort", abortFromParent, { once: true });
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeout = setTimeout(() => {
+        controller.abort();
+        reject(new AgentKitError("tool_timeout", `Tool "${tool.name}" timed out after ${timeoutMs}ms.`));
+      }, timeoutMs);
+    });
+
+    const execution = Promise.resolve().then(() =>
+      tool.execute(input, {
+        secrets: context.secrets,
+        signal: controller.signal,
+        runtime: context.runtime,
+        database: context.database,
+        db: context.database,
+        storage: {
+          sql: context.database,
+        },
+      }),
+    );
+
+    return await Promise.race([execution, timeoutPromise]);
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+
+    parentSignal?.removeEventListener("abort", abortFromParent);
+  }
+}
+
+function validateSchema(value: unknown, schema: JsonSchema, label: string): void {
+  const error = validateValue(value, schema, "$");
+
+  if (error) {
+    throw new AgentKitError("tool_validation_error", `${label} failed schema validation: ${error}`);
+  }
+}
+
+function validateValue(value: unknown, schema: JsonSchema, path: string): string | null {
+  if (Array.isArray(schema.enum) && !schema.enum.some((item) => Object.is(item, value))) {
+    return `${path} must be one of ${JSON.stringify(schema.enum)}.`;
+  }
+
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const errors = types.map((type) => validateValueForType(value, schema, type, path)).filter((error) => error !== null);
+
+  if (errors.length < types.length) {
+    return null;
+  }
+
+  if (types.length > 1) {
+    return `${path} must match one of these schema types: ${types.join(", ")}.`;
+  }
+
+  return errors[0] ?? null;
+}
+
+function validateValueForType(value: unknown, schema: JsonSchema, type: string, path: string): string | null {
+  switch (type) {
+    case "object":
+      return validateObject(value, schema, path);
+    case "array":
+      return validateArray(value, schema, path);
+    case "string":
+      return typeof value === "string" ? null : `${path} must be a string.`;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value) ? null : `${path} must be a number.`;
+    case "integer":
+      return Number.isInteger(value) ? null : `${path} must be an integer.`;
+    case "boolean":
+      return typeof value === "boolean" ? null : `${path} must be a boolean.`;
+    case "null":
+      return value === null ? null : `${path} must be null.`;
+    default:
+      return `${path} has unsupported schema type "${type}".`;
+  }
+}
+
+function validateObject(value: unknown, schema: JsonSchema, path: string): string | null {
+  if (!isRecord(value)) {
+    return `${path} must be an object.`;
+  }
+
+  for (const property of schema.required ?? []) {
+    if (!(property in value)) {
+      return `${path}.${property} is required.`;
+    }
+  }
+
+  for (const [property, propertySchema] of Object.entries(schema.properties ?? {})) {
+    if (property in value) {
+      const error = validateValue(value[property], propertySchema, `${path}.${property}`);
+
+      if (error) {
+        return error;
+      }
+    }
+  }
+
+  if (schema.additionalProperties === false) {
+    const allowedProperties = new Set(Object.keys(schema.properties ?? {}));
+
+    for (const property of Object.keys(value)) {
+      if (!allowedProperties.has(property)) {
+        return `${path}.${property} is not allowed.`;
+      }
+    }
+  }
+
+  return null;
+}
+
+function validateArray(value: unknown, schema: JsonSchema, path: string): string | null {
+  if (!Array.isArray(value)) {
+    return `${path} must be an array.`;
+  }
+
+  if (!schema.items) {
+    return null;
+  }
+
+  for (const [index, item] of value.entries()) {
+    const error = validateValue(item, schema.items, `${path}[${index}]`);
+
+    if (error) {
+      return error;
+    }
+  }
+
+  return null;
+}
+
+function normalizeOptionalNulls(value: unknown, schema: JsonSchema): unknown {
+  const types = schemaTypes(schema);
+
+  if (types.includes("object") && isRecord(value)) {
+    const required = new Set(schema.required ?? []);
+    const properties = schema.properties ?? {};
+    const normalized: Record<string, unknown> = { ...value };
+
+    for (const [property, propertySchema] of Object.entries(properties)) {
+      if (!(property in normalized)) {
+        continue;
+      }
+
+      if (normalized[property] === null && !required.has(property) && !allowsNull(propertySchema)) {
+        delete normalized[property];
+        continue;
+      }
+
+      normalized[property] = normalizeOptionalNulls(normalized[property], propertySchema);
+    }
+
+    return normalized;
+  }
+
+  if (types.includes("array") && Array.isArray(value) && schema.items) {
+    return value.map((item) => normalizeOptionalNulls(item, schema.items as JsonSchema));
+  }
+
+  return value;
+}
+
+function schemaTypes(schema: JsonSchema): string[] {
+  return Array.isArray(schema.type) ? schema.type : [schema.type];
+}
+
+function allowsNull(schema: JsonSchema): boolean {
+  return schemaTypes(schema).includes("null") || (Array.isArray(schema.enum) && schema.enum.some((item) => item === null));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/traces.ts

@@ -0,0 +1,41 @@
+import type { ConversationRecord, StoredRun, StoredToolCall } from "../storage/sqlite";
+import { openCapsuleStore } from "../storage/sqlite";
+import { loadAgentCapsule } from "./config";
+import { AgentKitError } from "./errors";
+
+export type ConversationTrace = ConversationRecord & {
+  runs: ConversationTraceRun[];
+};
+
+export type ConversationTraceRun = StoredRun & {
+  toolCalls: StoredToolCall[];
+};
+
+export async function getConversationTraceFromCwd(cwd: string, conversationId: string): Promise<ConversationTrace> {
+  if (!conversationId) {
+    throw new AgentKitError("validation_error", "Missing conversation id.");
+  }
+
+  const capsule = await loadAgentCapsule(cwd);
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    const conversation = store.getConversation(conversationId);
+
+    if (!conversation) {
+      throw new AgentKitError("conversation_not_found", `Conversation "${conversationId}" was not found.`);
+    }
+
+    const runs = store.listRunsForConversation(conversation.id).map((run) => ({
+      ...run,
+      toolCalls: store.listToolCallsForRun(run.id),
+    }));
+
+    return {
+      ...conversation,
+      runs,
+    };
+  } finally {
+    store.close();
+  }
+}