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

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/targets/cloudflare/build.ts

@@ -731,6 +731,22 @@ export class AgentKitConversationStore extends DurableObject {
       return this.getMessages(url.searchParams.get("conversationId"));
     }
 
+    if (request.method === "GET" && url.pathname === "/conversations") {
+      return this.listConversations();
+    }
+
+    const conversationTraceMatch = url.pathname.match(/^\\/conversations\\/([^/]+)\\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return this.getConversationTrace(decodeURIComponent(conversationTraceMatch[1] || ""));
+    }
+
+    const conversationMatch = url.pathname.match(/^\\/conversations\\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      return this.getConversation(decodeURIComponent(conversationMatch[1] || ""));
+    }
+
     return Response.json({ error: { code: "not_found", message: "Unknown Durable Object route." } }, { status: 404 });
   }
 
@@ -754,6 +770,128 @@ export class AgentKitConversationStore extends DurableObject {
     });
   }
 
+  listConversations() {
+    const rows = this.sql.exec(\`
+      SELECT conversations.id, conversations.agent_name, conversations.title, conversations.created_at, conversations.updated_at, COUNT(messages.id) AS message_count
+      FROM conversations
+      LEFT JOIN messages ON messages.conversation_id = conversations.id
+      GROUP BY conversations.id, conversations.agent_name, conversations.title, conversations.created_at, conversations.updated_at
+      ORDER BY conversations.updated_at DESC
+    \`).toArray();
+
+    return Response.json({
+      conversations: rows.map((row) => ({
+        id: String(row.id),
+        agentName: String(row.agent_name),
+        title: row.title === null || row.title === undefined ? null : String(row.title),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        messageCount: Number(row.message_count || 0),
+      })),
+    });
+  }
+
+  getConversation(conversationId) {
+    const conversation = this.readConversation(conversationId);
+
+    if (!conversation) {
+      return Response.json(
+        { error: { code: "conversation_not_found", message: \`Conversation "\${conversationId}" was not found.\` } },
+        { status: 404 },
+      );
+    }
+
+    return Response.json(conversation);
+  }
+
+  getConversationTrace(conversationId) {
+    const conversation = this.readConversation(conversationId);
+
+    if (!conversation) {
+      return Response.json(
+        { error: { code: "conversation_not_found", message: \`Conversation "\${conversationId}" was not found.\` } },
+        { status: 404 },
+      );
+    }
+
+    const runs = this.sql.exec(
+      "SELECT id, conversation_id, provider, model, status, error_code, error_message, created_at, completed_at FROM runs WHERE conversation_id = ? ORDER BY rowid ASC",
+      conversationId,
+    ).toArray();
+
+    return Response.json({
+      ...conversation,
+      runs: runs.map((run) => ({
+        id: String(run.id),
+        conversationId: String(run.conversation_id),
+        provider: String(run.provider),
+        model: String(run.model),
+        status: String(run.status),
+        errorCode: run.error_code === null || run.error_code === undefined ? null : String(run.error_code),
+        errorMessage: run.error_message === null || run.error_message === undefined ? null : String(run.error_message),
+        startedAt: String(run.created_at),
+        completedAt: run.completed_at === null || run.completed_at === undefined ? null : String(run.completed_at),
+        toolCalls: this.readToolCalls(String(run.id)),
+      })),
+    });
+  }
+
+  readConversation(conversationId) {
+    if (!conversationId) {
+      return null;
+    }
+
+    const row = this.sql.exec(
+      "SELECT id, agent_name, title, created_at, updated_at FROM conversations WHERE id = ?",
+      conversationId,
+    ).one();
+
+    if (!row) {
+      return null;
+    }
+
+    const messages = this.sql.exec(
+      "SELECT id, conversation_id, role, content, created_at FROM messages WHERE conversation_id = ? ORDER BY rowid ASC",
+      conversationId,
+    ).toArray();
+
+    return {
+      id: String(row.id),
+      agentName: String(row.agent_name),
+      title: row.title === null || row.title === undefined ? null : String(row.title),
+      createdAt: String(row.created_at),
+      updatedAt: String(row.updated_at),
+      messages: messages.map((message) => ({
+        id: String(message.id),
+        conversationId: String(message.conversation_id),
+        role: String(message.role),
+        content: String(message.content),
+        createdAt: String(message.created_at),
+      })),
+    };
+  }
+
+  readToolCalls(runId) {
+    const rows = this.sql.exec(
+      "SELECT id, run_id, conversation_id, tool_name, visibility, status, input_json, output_json, error_message, created_at, completed_at FROM tool_calls WHERE run_id = ? ORDER BY rowid ASC",
+      runId,
+    ).toArray();
+
+    return rows.map((row) => ({
+      id: String(row.id),
+      runId: String(row.run_id),
+      conversationId: String(row.conversation_id),
+      name: String(row.tool_name),
+      visibility: String(row.visibility),
+      status: String(row.status),
+      input: parseStoredJson(row.input_json, {}),
+      output: row.output_json === null || row.output_json === undefined ? undefined : parseStoredJson(row.output_json, null),
+      errorMessage: row.error_message === null || row.error_message === undefined ? null : String(row.error_message),
+      createdAt: String(row.created_at),
+      completedAt: row.completed_at === null || row.completed_at === undefined ? null : String(row.completed_at),
+    }));
+  }
+
   persistMessages(input) {
     const now = new Date().toISOString();
     const conversationId = String(input.conversationId || crypto.randomUUID());
@@ -887,6 +1025,22 @@ export default {
       return handleChat(request, env);
     }
 
+    if (request.method === "GET" && (url.pathname === "/conversations" || url.pathname === "/v1/conversations")) {
+      return handleConversationRead(request, env, "list");
+    }
+
+    const conversationTraceMatch = url.pathname.match(/^\\/(?:v1\\/)?conversations\\/([^/]+)\\/trace$/);
+
+    if (request.method === "GET" && conversationTraceMatch) {
+      return handleConversationRead(request, env, "trace", decodeURIComponent(conversationTraceMatch[1] || ""));
+    }
+
+    const conversationMatch = url.pathname.match(/^\\/(?:v1\\/)?conversations\\/([^/]+)$/);
+
+    if (request.method === "GET" && conversationMatch) {
+      return handleConversationRead(request, env, "show", decodeURIComponent(conversationMatch[1] || ""));
+    }
+
     if (request.method === "POST" && url.pathname.startsWith("/tools/")) {
       return handleTool(request, env, decodeURIComponent(url.pathname.slice("/tools/".length)));
     }
@@ -1233,6 +1387,39 @@ async function handleChat(request, env) {
   });
 }
 
+async function handleConversationRead(request, env, action, conversationId) {
+  const auth = await authorizeChat(request, env, {});
+
+  if (auth) {
+    return auth;
+  }
+
+  if (!env.AGENTKIT_CONVERSATIONS) {
+    return Response.json({ error: { code: "conversations_not_configured", message: "Hosted conversation storage is not configured." } }, { status: 503 });
+  }
+
+  if (action === "list") {
+    const stub = hostedConversationStore(env);
+    return stub.fetch("https://agentkit.internal/conversations");
+  }
+
+  if (!conversationId) {
+    return Response.json({ error: { code: "validation_error", message: "Missing conversation id." } }, { status: 400 });
+  }
+
+  const stub = hostedConversationStore(env);
+  const suffix = action === "trace" ? "/trace" : "";
+  const path = \`/conversations/\${encodeURIComponent(conversationId)}\${suffix}\`;
+  const response = await stub.fetch(\`https://agentkit.internal\${path}\`);
+
+  if (response.status !== 404) {
+    return response;
+  }
+
+  const legacyStub = legacyConversationStore(env, conversationId);
+  return legacyStub.fetch(\`https://agentkit.internal\${path}\`);
+}
+
 function readChatMessage(body) {
   if (typeof body.message === "string") {
     return body.message.trim();
@@ -2276,8 +2463,7 @@ async function persist(env, input) {
     return {};
   }
 
-  const id = env.AGENTKIT_CONVERSATIONS.idFromName(input.conversationId);
-  const stub = env.AGENTKIT_CONVERSATIONS.get(id);
+  const stub = hostedConversationStore(env);
   const response = await stub.fetch("https://agentkit.internal/messages", {
     method: "POST",
     body: JSON.stringify(input),
@@ -2295,8 +2481,7 @@ async function loadConversationMessages(env, conversationId) {
     return [];
   }
 
-  const id = env.AGENTKIT_CONVERSATIONS.idFromName(conversationId);
-  const stub = env.AGENTKIT_CONVERSATIONS.get(id);
+  const stub = hostedConversationStore(env);
   const response = await stub.fetch(
     \`https://agentkit.internal/messages?conversationId=\${encodeURIComponent(conversationId)}\`,
   );
@@ -2306,7 +2491,7 @@ async function loadConversationMessages(env, conversationId) {
   }
 
   const payload = await response.json();
-  return Array.isArray(payload.messages)
+  const messages = Array.isArray(payload.messages)
     ? payload.messages.filter((message) =>
         message &&
         typeof message === "object" &&
@@ -2314,6 +2499,39 @@ async function loadConversationMessages(env, conversationId) {
         typeof message.content === "string"
       )
     : [];
+
+  if (messages.length > 0) {
+    return messages;
+  }
+
+  const legacyStub = legacyConversationStore(env, conversationId);
+  const legacyResponse = await legacyStub.fetch(
+    \`https://agentkit.internal/messages?conversationId=\${encodeURIComponent(conversationId)}\`,
+  );
+
+  if (!legacyResponse.ok) {
+    return [];
+  }
+
+  const legacyPayload = await legacyResponse.json();
+  return Array.isArray(legacyPayload.messages)
+    ? legacyPayload.messages.filter((message) =>
+        message &&
+        typeof message === "object" &&
+        (message.role === "user" || message.role === "assistant") &&
+        typeof message.content === "string"
+      )
+    : [];
+}
+
+function hostedConversationStore(env) {
+  const id = env.AGENTKIT_CONVERSATIONS.idFromName("agentkit-conversations");
+  return env.AGENTKIT_CONVERSATIONS.get(id);
+}
+
+function legacyConversationStore(env, conversationId) {
+  const id = env.AGENTKIT_CONVERSATIONS.idFromName(conversationId);
+  return env.AGENTKIT_CONVERSATIONS.get(id);
 }
 
 function normalizeConversationId(value) {
@@ -2590,6 +2808,18 @@ function titleFromMessage(content) {
   const compact = content.split(/\\r?\\n/, 1)[0].replace(/\\s+/g, " ").trim();
   return compact.length <= 80 ? compact : \`\${compact.slice(0, 77)}...\`;
 }
+
+function parseStoredJson(value, fallback) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
 `;
 }
 

package/src/templates/skills/agentkit-integrations/SKILL.md

@@ -26,8 +26,13 @@ export default defineAgent({
       toolkits: ["gmail", "googlecalendar"],
       tools: {
         gmail: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
-        googlecalendar: ["GOOGLECALENDAR_CREATE_EVENT"],
+        googlecalendar: [
+          "GOOGLECALENDAR_EVENTS_LIST",
+          "GOOGLECALENDAR_CREATE_EVENT",
+          "GOOGLECALENDAR_UPDATE_EVENT",
+        ],
       },
+      confirmExternalWrites: true,
     }),
   ],
 });
@@ -35,13 +40,17 @@ export default defineAgent({
 
 Keep the action list explicit. Do not expose the whole Composio catalog by default.
 
+For Google Calendar, do not configure create-only access. Include `GOOGLECALENDAR_EVENTS_LIST` so the agent can inspect availability before writing. For `GOOGLECALENDAR_CREATE_EVENT`, pass UTC `start_datetime` and explicit `event_duration_minutes` or `event_duration_hour`; AgentKit blocks Composio's implicit 30-minute duration default.
+
+Managed Composio write actions require tool input `confirmed: true` by default. Set it only after the owner/user confirms the exact external change. Use `confirmExternalWrites: false` only when the capsule implements an equivalent confirmation guard elsewhere.
+
 ## Commands
 
 ```sh
 npm run agentkit -- inspect
 npm run agentkit -- deploy doctor
 npm run agentkit -- deploy
-npm run agentkit -- integrations status
+npm run agentkit -- integrations status --toolkit googlecalendar
 npm run agentkit -- integrations connect composio --toolkit gmail
 ```