@andreprado/agentkit 0.1.0-alpha.17 → 0.1.0-alpha.19

package/src/runtime/inspect.ts

@@ -203,6 +203,7 @@ export function buildInspectState(
       toolkits: integration.toolkits,
       tools: integration.allowedTools,
       userId: integration.userId,
+      confirmExternalWrites: integration.confirmExternalWrites !== false,
     })),
     channels: (capsule.config.channels ?? []).map((channel) => ({
       name: channel.name,

package/src/runtime/integrations/composio.ts

@@ -20,6 +20,7 @@ export type ManagedComposioResolutionOptions = {
 type ManagedComposioToolInput = {
   toolSlug: string;
   arguments: Record<string, unknown>;
+  confirmed?: boolean;
 };
 
 type ManagedComposioToolOutput = {
@@ -32,6 +33,13 @@ type ManagedComposioToolOutput = {
   userId: string;
 };
 
+type ComposioActionGuide = {
+  summary: string;
+  argumentNotes: string[];
+  dangerousDefaults?: string[];
+  examples?: Array<Record<string, unknown>>;
+};
+
 export function resolveManagedComposioIntegrations(
   config: Pick<AgentConfig, "name" | "integrations">,
   options: ManagedComposioResolutionOptions = {},
@@ -74,8 +82,13 @@ export function createManagedComposioTools(
 
     const tool: AgentTool<ManagedComposioToolInput, ManagedComposioToolOutput> = {
       name: MANAGED_COMPOSIO_TOOL_NAME,
-      description:
+      description: [
         "Executes one explicitly allowed AgentKit-managed Composio action for this deployed agent. Use only for configured connected apps.",
+        integration.confirmExternalWrites === false
+          ? "External write confirmation is disabled for this integration by agentkit.config.ts."
+          : "For write actions, pass confirmed: true only after the user confirms the exact external change.",
+        describeAllowedComposioActions(integration.allowedTools),
+      ].join("\n\n"),
       visibility: "user",
       secrets: [MANAGED_COMPOSIO_API_KEY_SECRET],
       permissions: integration.allowedTools.map((toolName) => `composio:${toolName.toLowerCase()}`),
@@ -91,7 +104,13 @@ export function createManagedComposioTools(
           arguments: {
             type: "object",
             additionalProperties: true,
-            description: "Structured arguments for the selected Composio action.",
+            description:
+              "Structured arguments for the selected Composio action. Use the action notes in the tool description; do not rely on Composio defaults for dates, times, durations, recipients, or write behavior.",
+          },
+          confirmed: {
+            type: "boolean",
+            description:
+              "Set true only after explicit user confirmation for external write actions such as create, update, delete, send, patch, move, insert, clear, remove, import, or quick add.",
           },
         },
         required: ["toolSlug", "arguments"],
@@ -121,6 +140,9 @@ export function createManagedComposioTools(
           );
         }
 
+        validateComposioArguments(input.toolSlug, input.arguments);
+        validateComposioConfirmation(input.toolSlug, input.confirmed, integration);
+
         const result = await executeComposioTool({
           apiKey: ctx.secrets[MANAGED_COMPOSIO_API_KEY_SECRET],
           userId: integration.userId,
@@ -173,6 +195,150 @@ function allowedComposioTools(integration: ComposioManagedIntegration): string[]
   return Array.from(new Set(Object.values(integration.tools ?? {}).flat())).sort();
 }
 
+function describeAllowedComposioActions(actions: string[]): string {
+  const lines = ["Allowed Composio actions:"];
+
+  for (const action of actions) {
+    const guide = COMPOSIO_ACTION_GUIDES[action];
+
+    if (!guide) {
+      lines.push(`- ${action}: Pass explicit arguments from the current Composio action schema. Do not invent fields or rely on hidden defaults.`);
+      continue;
+    }
+
+    lines.push(`- ${action}: ${guide.summary}`);
+
+    for (const note of guide.argumentNotes) {
+      lines.push(`  - ${note}`);
+    }
+
+    for (const warning of guide.dangerousDefaults ?? []) {
+      lines.push(`  - Dangerous default: ${warning}`);
+    }
+
+    for (const example of guide.examples ?? []) {
+      lines.push(`  - Example arguments: ${JSON.stringify(example)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function validateComposioArguments(toolSlug: string, args: Record<string, unknown>): void {
+  if (toolSlug !== "GOOGLECALENDAR_CREATE_EVENT") {
+    return;
+  }
+
+  const start = args.start_datetime;
+
+  if (typeof start !== "string" || !isUtcDateTime(start)) {
+    throw new AgentKitError(
+      "composio_argument_invalid",
+      "GOOGLECALENDAR_CREATE_EVENT requires start_datetime as an explicit UTC RFC3339 timestamp ending in Z or +00:00. Convert user-local times using the runtime time zone before calling Composio.",
+    );
+  }
+
+  const minutes = args.event_duration_minutes;
+  const hours = args.event_duration_hour;
+
+  if (!isPositiveNumber(minutes) && !isPositiveNumber(hours)) {
+    throw new AgentKitError(
+      "composio_argument_required",
+      "GOOGLECALENDAR_CREATE_EVENT requires explicit event_duration_minutes or event_duration_hour. Composio defaults event_duration_minutes to 30, so AgentKit blocks implicit duration.",
+    );
+  }
+}
+
+function validateComposioConfirmation(
+  toolSlug: string,
+  confirmed: boolean | undefined,
+  integration: ComposioManagedIntegration,
+): void {
+  if (integration.confirmExternalWrites === false || !isComposioWriteAction(toolSlug)) {
+    return;
+  }
+
+  if (confirmed !== true) {
+    throw new AgentKitError(
+      "composio_confirmation_required",
+      `Composio action ${toolSlug} changes an external system. Ask the user to confirm the exact action and call again with confirmed: true.`,
+    );
+  }
+}
+
+function isComposioWriteAction(toolSlug: string): boolean {
+  return /_(?:BATCH|CLEAR|CREATE|DELETE|DUPLICATE|IMPORT|INSERT|MOVE|PATCH|QUICK_ADD|REMOVE|REVOKE|SEND|UPDATE)(?:_|$)/.test(
+    toolSlug,
+  );
+}
+
+function isUtcDateTime(value: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|\+00:00)$/.test(value);
+}
+
+function isPositiveNumber(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+const COMPOSIO_ACTION_GUIDES: Record<string, ComposioActionGuide> = {
+  GOOGLECALENDAR_EVENTS_LIST: {
+    summary: "List events from a calendar before answering schedule/availability questions.",
+    argumentNotes: [
+      "calendarId is required by Composio; use primary unless the user selected a different calendar.",
+      "Use explicit timeMin and timeMax RFC3339 bounds for the requested window.",
+      "Pass timeZone when the user or business timezone matters.",
+    ],
+    examples: [
+      {
+        calendarId: "primary",
+        timeMin: "2026-06-03T00:00:00-03:00",
+        timeMax: "2026-06-04T00:00:00-03:00",
+        singleEvents: true,
+        orderBy: "startTime",
+        timeZone: "America/Sao_Paulo",
+      },
+    ],
+  },
+  GOOGLECALENDAR_CREATE_EVENT: {
+    summary: "Create an event only after confirming the exact title, date, start time, duration, timezone, and attendees/location when relevant.",
+    argumentNotes: [
+      "start_datetime is required and must be UTC RFC3339, for example 2026-06-03T15:00:00Z for 12:00 in America/Sao_Paulo.",
+      "calendar_id defaults to primary; pass it explicitly when known.",
+      "event_duration_minutes or event_duration_hour must be explicit.",
+      "Set timezone to the user/business IANA timezone when known.",
+    ],
+    dangerousDefaults: [
+      "event_duration_minutes defaults to 30 if omitted.",
+      "calendar_id defaults to primary if omitted.",
+    ],
+    examples: [
+      {
+        calendar_id: "primary",
+        summary: "Client call",
+        start_datetime: "2026-06-03T15:00:00Z",
+        event_duration_minutes: 60,
+        timezone: "America/Sao_Paulo",
+      },
+    ],
+  },
+  GOOGLECALENDAR_UPDATE_EVENT: {
+    summary: "Update an existing event only after identifying the event and confirming the exact change.",
+    argumentNotes: [
+      "Read or find the event first so event_id/calendar_id are correct.",
+      "When changing time, use explicit UTC RFC3339 values and preserve duration unless the user changed it.",
+      "Do not infer cancellation/deletion from vague wording.",
+    ],
+  },
+  GMAIL_FETCH_EMAILS: {
+    summary: "Fetch emails for read/search requests.",
+    argumentNotes: ["Use narrow query/window arguments when available; do not fetch broad mailbox history unnecessarily."],
+  },
+  GMAIL_SEND_EMAIL: {
+    summary: "Send email only after confirming recipients, subject, body, and attachments/links.",
+    argumentNotes: ["Pass recipient fields explicitly and avoid using draft-like placeholders in production sends."],
+  },
+};
+
 async function executeComposioTool(input: {
   apiKey: string | undefined;
   userId: string;

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/runtime-contract.ts

@@ -35,6 +35,60 @@ export async function assertRuntimeContract(
   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: withHeaders({ "content-type": "application/json" }, options.auth?.chat),