denchclaw 2.4.6 → 2.5.0

package/extensions/dench-identity/composio-cheat-sheet.ts

@@ -0,0 +1,197 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Shape written by `apps/web/lib/composio-tool-index.ts` to
+ * `<workspace>/composio-tool-index.json`. Kept in the extension package so the
+ * agent runtime can format the cheat sheet without importing the Next app.
+ */
+export type ComposioToolIndexFile = {
+  generated_at: string;
+  connected_apps: Array<{
+    toolkit_slug: string;
+    toolkit_name: string;
+    account_count: number;
+    tools: Array<{
+      name: string;
+      title: string;
+      description_short: string;
+      required_args: string[];
+      arg_hints: Record<string, string>;
+      default_args?: Record<string, unknown>;
+      example_args?: Record<string, unknown>;
+      example_prompts?: string[];
+      input_schema?: Record<string, unknown>;
+    }>;
+    recipes: Record<string, string>;
+  }>;
+};
+
+type ComposioMcpStatusFile = {
+  summary?: {
+    verified?: boolean;
+    message?: string;
+  };
+  config?: {
+    status?: "pass" | "fail" | "unknown";
+  };
+  gatewayTools?: {
+    status?: "pass" | "fail" | "unknown";
+  };
+  liveAgent?: {
+    status?: "pass" | "fail" | "unknown";
+  };
+};
+
+function isComposioToolIndexFile(value: unknown): value is ComposioToolIndexFile {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const rec = value as Record<string, unknown>;
+  if (typeof rec.generated_at !== "string" || !Array.isArray(rec.connected_apps)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Build markdown for the identity system prompt from a parsed index file.
+ */
+export function formatComposioToolCheatSheetFromIndex(index: ComposioToolIndexFile): string {
+  return formatComposioToolCheatSheet(index, null);
+}
+
+function formatComposioToolCheatSheet(
+  index: ComposioToolIndexFile,
+  status: ComposioMcpStatusFile | null,
+): string {
+  const verified = status?.summary?.verified === true;
+  const summaryMessage = typeof status?.summary?.message === "string" ? status.summary.message : null;
+  const lines: string[] = [
+    "## Connected App Tools (via Composio MCP)",
+    "",
+    verified
+      ? "You have verified MCP tools available for these connected apps. Call them directly."
+      : "Composio MCP is the configured integration layer for these connected apps. If the MCP tools are missing in this session, stop and report the Composio MCP repair status instead of bypassing it.",
+    "",
+    "- Use `composio_resolve_tool` first when the exact Composio tool name or argument shape is not already obvious.",
+    "- Never use `gog`, shell CLIs, curl, or raw `/v1/composio/*` HTTP as a fallback for these connected apps.",
+    "- If a Composio tool fails because of argument shape, fix the JSON arguments and retry once.",
+    "",
+  ];
+  if (summaryMessage) {
+    lines.push(`Current verification status: ${summaryMessage}`, "");
+  }
+
+  for (const app of index.connected_apps) {
+    const title =
+      app.account_count > 1
+        ? `### ${app.toolkit_name} (${app.account_count} accounts connected)`
+        : `### ${app.toolkit_name} (1 account connected)`;
+    lines.push(title, "");
+    lines.push("| Intent | Tool | Key args |");
+    lines.push("|--------|------|----------|");
+
+    const recipeByTool = Object.fromEntries(
+      Object.entries(app.recipes).map(([intent, tool]) => [tool, intent]),
+    );
+
+    for (const tool of app.tools) {
+      const intent = recipeByTool[tool.name] ?? "—";
+      const keyParts: string[] = [];
+      for (const a of tool.required_args.slice(0, 4)) {
+        keyParts.push(a);
+      }
+      const hintSample = Object.entries(tool.arg_hints).slice(0, 2);
+      for (const [k, v] of hintSample) {
+        keyParts.push(`${k}: ${v}`);
+      }
+      if (tool.default_args && Object.keys(tool.default_args).length > 0) {
+        keyParts.push(`defaults: ${JSON.stringify(tool.default_args)}`);
+      }
+      const keyArgs = keyParts.length ? keyParts.join("; ") : "—";
+      lines.push(`| ${intent} | \`${tool.name}\` | ${keyArgs} |`);
+    }
+
+    const gotchas = Object.entries(
+      app.tools.reduce<Record<string, string>>((acc, t) => {
+        for (const [k, v] of Object.entries(t.arg_hints)) {
+          if (!acc[k]) {
+            acc[k] = v;
+          }
+        }
+        return acc;
+      }, {}),
+    );
+    if (gotchas.length > 0) {
+      lines.push("");
+      lines.push(
+        "**Known gotchas:**",
+        ...gotchas.map(([k, v]) => `- \`${k}\`: ${v}`),
+      );
+    }
+
+    const extraRecipes = Object.entries(app.recipes).filter(
+      ([, toolName]) => !app.tools.some((t) => t.name === toolName),
+    );
+    if (extraRecipes.length > 0) {
+      lines.push("");
+      lines.push("**More intents (tool may be outside the curated direct-tool list):**");
+      for (const [intent, toolName] of extraRecipes) {
+        lines.push(`- ${intent}: \`${toolName}\``);
+      }
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function readComposioToolIndex(workspaceDir: string): ComposioToolIndexFile | null {
+  const filePath = path.join(workspaceDir, "composio-tool-index.json");
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(filePath, "utf-8")) as unknown;
+    return isComposioToolIndexFile(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readComposioToolIndexFile(workspaceDir: string): ComposioToolIndexFile | null {
+  return readComposioToolIndex(workspaceDir);
+}
+
+function readComposioMcpStatus(workspaceDir: string): ComposioMcpStatusFile | null {
+  const filePath = path.join(workspaceDir, "composio-mcp-status.json");
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(filePath, "utf-8")) as unknown;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      return raw as ComposioMcpStatusFile;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function readComposioMcpStatusFile(workspaceDir: string): ComposioMcpStatusFile | null {
+  return readComposioMcpStatus(workspaceDir);
+}
+
+/**
+ * Loads and formats the cheat sheet, or returns null if no index file / invalid JSON.
+ */
+export function loadComposioToolCheatSheetMarkdown(workspaceDir: string): string | null {
+  const index = readComposioToolIndex(workspaceDir);
+  if (!index || index.connected_apps.length === 0) {
+    return null;
+  }
+  return formatComposioToolCheatSheet(index, readComposioMcpStatus(workspaceDir));
+}

package/extensions/dench-identity/index.test.ts

@@ -1,4 +1,6 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import os from "node:os";
 import { buildIdentityPrompt, resolveWorkspaceDir } from "./index.ts";
 import register from "./index.ts";
 import path from "node:path";
@@ -29,6 +31,52 @@ describe("buildIdentityPrompt", () => {
     );
   });
 
+  it("includes composio-apps skill path and MCP tool preference", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain(
+      path.join(workspaceDir, "skills", "composio-apps", "SKILL.md"),
+    );
+    expect(prompt).toContain("Composio MCP");
+    expect(prompt).toContain("Never");
+    expect(prompt).toContain("composio_resolve_tool");
+  });
+
+  it("teaches the agent to emit direct composio connect links for any app", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain("ANY third-party app or service");
+    expect(prompt).toContain("always call `composio_resolve_tool`");
+    expect(prompt).toContain("action_link_markdown");
+    expect(prompt).toContain("MUST end the assistant reply with that exact markdown link");
+    expect(prompt).toContain("dench://composio/connect");
+    expect(prompt).toContain("dench://composio/reconnect");
+    expect(prompt).toContain("connect_required");
+  });
+
+  it("includes enrichment guidance for Apollo and Exa", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain("default tool for enrichment requests");
+    expect(prompt).toContain('`action: "people"`');
+    expect(prompt).toContain('`action: "company"`');
+    expect(prompt).toContain('`action: "people_search"`');
+    expect(prompt).toContain("Use Apollo for structured CRM enrichment and Exa for broader web research");
+  });
+
+  it("prefers Composio over gog even without a generated tool index", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain("Composio is the default integration layer");
+    expect(prompt).toContain("Never use `gog`");
+    expect(prompt).toContain("If Composio MCP is unavailable in this session, stop");
+    expect(prompt).toContain("GMAIL_FETCH_EMAILS");
+  });
+
+  it("does not advertise the removed browser skill contract", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).not.toContain(
+      path.join(workspaceDir, "skills", "browser", "SKILL.md"),
+    );
+    expect(prompt).not.toContain("Browser Agent");
+  });
+
   it("includes exec approval policy (prevents agent stalling on exec confirmation)", () => {
     const prompt = buildIdentityPrompt(workspaceDir);
     expect(prompt).toContain("elevated: true");
@@ -42,6 +90,56 @@ describe("buildIdentityPrompt", () => {
   });
 });
 
+describe("buildIdentityPrompt composio-tool-index", () => {
+  let tmp: string;
+
+  afterEach(() => {
+    if (tmp) {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("includes Gmail tool names from composio-tool-index.json so the agent skips catalog discovery", () => {
+    tmp = path.join(
+      os.tmpdir(),
+      `dench-identity-composio-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(
+      path.join(tmp, "composio-tool-index.json"),
+      JSON.stringify({
+        generated_at: "2026-04-01T00:00:00.000Z",
+        connected_apps: [
+          {
+            toolkit_slug: "gmail",
+            toolkit_name: "Gmail",
+            account_count: 1,
+            tools: [
+              {
+                name: "GMAIL_FETCH_EMAILS",
+                title: "Fetch emails",
+                description_short: "List inbox messages.",
+                required_args: [],
+                arg_hints: {
+                  label_ids: 'Use ["INBOX"] as JSON array.',
+                },
+              },
+            ],
+            recipes: { "Read recent emails": "GMAIL_FETCH_EMAILS" },
+          },
+        ],
+      }),
+      "utf-8",
+    );
+
+    const prompt = buildIdentityPrompt(tmp);
+    expect(prompt).toContain("Connected App Tools (via Composio MCP)");
+    expect(prompt).toContain("GMAIL_FETCH_EMAILS");
+    expect(prompt).toContain("Read recent emails");
+    expect(prompt).toContain("label_ids");
+  });
+});
+
 describe("resolveWorkspaceDir", () => {
   it("returns workspace path when config is a valid string", () => {
     const api = { config: { agents: { defaults: { workspace: "/home/user/ws" } } } };
@@ -133,4 +231,131 @@ describe("register", () => {
     const result = handler({}, {});
     expect(result).toBeUndefined();
   });
+
+  it("registers the Composio resolver tool when the managed skill exists", () => {
+    const tmp = path.join(
+      os.tmpdir(),
+      `dench-identity-register-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(path.join(tmp, "skills", "composio-apps"), { recursive: true });
+    writeFileSync(
+      path.join(tmp, "skills", "composio-apps", "SKILL.md"),
+      "# Composio connected apps\n",
+      "utf-8",
+    );
+
+    const api = {
+      config: { plugins: { entries: {} }, agents: { defaults: { workspace: tmp } } },
+      on: vi.fn(),
+      registerTool: vi.fn(),
+    };
+
+    register(api as any);
+
+    expect(api.registerTool).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "composio_resolve_tool" }),
+    );
+
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("resolves recent GitHub PR requests through recipe-backed tools outside the direct tool slice", async () => {
+    const tmp = path.join(
+      os.tmpdir(),
+      `dench-identity-resolver-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(
+      path.join(tmp, "composio-tool-index.json"),
+      JSON.stringify({
+        generated_at: "2026-04-03T00:00:00.000Z",
+        connected_apps: [
+          {
+            toolkit_slug: "github",
+            toolkit_name: "GitHub",
+            account_count: 1,
+            tools: [
+              {
+                name: "GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER",
+                title: "List repositories",
+                description_short: "Lists repositories for the authenticated user.",
+                required_args: [],
+                arg_hints: {},
+              },
+            ],
+            recipes: {
+              "Find pull requests": "GITHUB_FIND_PULL_REQUESTS",
+            },
+          },
+        ],
+      }),
+      "utf-8",
+    );
+
+    const api = {
+      config: { plugins: { entries: {} }, agents: { defaults: { workspace: tmp } } },
+      on: vi.fn(),
+      registerTool: vi.fn(),
+    };
+
+    register(api as any);
+
+    const resolver = api.registerTool.mock.calls[0][0];
+    const result = await resolver.execute({
+      app: "github",
+      intent: "check my recent PRs",
+    });
+    const payload = JSON.parse(result.content[0].text);
+
+    expect(payload.tool).toBe("GITHUB_FIND_PULL_REQUESTS");
+    expect(payload.directly_callable).toBe(true);
+
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns a direct connect link when the requested app is not connected", async () => {
+    const tmp = path.join(
+      os.tmpdir(),
+      `dench-identity-resolver-missing-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(
+      path.join(tmp, "composio-tool-index.json"),
+      JSON.stringify({
+        generated_at: "2026-04-03T00:00:00.000Z",
+        connected_apps: [
+          {
+            toolkit_slug: "github",
+            toolkit_name: "GitHub",
+            account_count: 1,
+            tools: [],
+            recipes: {},
+          },
+        ],
+      }),
+      "utf-8",
+    );
+
+    const api = {
+      config: { plugins: { entries: {} }, agents: { defaults: { workspace: tmp } } },
+      on: vi.fn(),
+      registerTool: vi.fn(),
+    };
+
+    register(api as any);
+
+    const resolver = api.registerTool.mock.calls[0][0];
+    const result = await resolver.execute({
+      app: "slack",
+      intent: "check my slack",
+    });
+    const payload = JSON.parse(result.content[0].text);
+
+    expect(payload.availability).toBe("connect_required");
+    expect(payload.action_required).toBe("connect");
+    expect(payload.toolkit_slug).toBe("slack");
+    expect(payload.action_link_markdown).toBe("[Connect Slack](dench://composio/connect?toolkit=slack&name=Slack)");
+
+    rmSync(tmp, { recursive: true, force: true });
+  });
 });