gitclaw 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GitClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./gitclaw-logo.png" alt="GitClaw Logo" width="200" />
+</p>
+
 <p align="center">
   <img src="https://img.shields.io/npm/v/gitclaw?style=flat-square&color=blue" alt="npm version" />
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version" />
@@ -37,49 +41,57 @@ Most agent frameworks treat configuration as code scattered across your applicat
 
 Fork an agent. Branch a personality. `git log` your agent's memory. Diff its rules. This is **agents as repos**.
 
-## Quick Start
-
-### CLI
+## Install
 
 ```bash
 npm install -g gitclaw
+```
 
-# Set your API key
-export OPENAI_API_KEY="sk-..."
-# or: export ANTHROPIC_API_KEY="sk-ant-..."
+## Quick Start
+
+**Run your first agent in one line:**
 
-# Point gitclaw at any directory — it handles everything
-gitclaw --dir ~/my-project
+```bash
+export OPENAI_API_KEY="sk-..."
+gitclaw --dir ~/my-project "Explain this project and suggest improvements"
 ```
 
-That's it. Gitclaw auto-scaffolds everything on first run:
-- `git init` if not already a repo
-- Creates `agent.yaml`, `SOUL.md`, `memory/MEMORY.md`
-- Commits the scaffold
-- Drops you into the REPL
+That's it. Gitclaw auto-scaffolds everything on first run — `agent.yaml`, `SOUL.md`, `memory/` — and drops you into the agent.
 
-```
-? Repository path (. for current dir): ~/my-project
-Initializing git repository...
-Created agent.yaml (model: openai:gpt-4o-mini)
-my-project v0.1.0
-Model: openai:gpt-4o-mini
-Tools: cli, read, write, memory
-→ List all files and explain the project
+### Local Repo Mode
+
+Clone a GitHub repo, run an agent on it, auto-commit and push to a session branch:
+
+```bash
+gitclaw --repo https://github.com/org/repo --pat ghp_xxx "Fix the login bug"
 ```
 
-Or run without `--dir` and it will ask you interactively:
+Resume an existing session:
 
 ```bash
-gitclaw
+gitclaw --repo https://github.com/org/repo --pat ghp_xxx --session gitclaw/session-a1b2c3d4 "Continue"
 ```
 
-Single-shot mode:
+Token can come from env instead of `--pat`:
 
 ```bash
-gitclaw --dir ~/my-project -p "Create a hello world script"
+export GITHUB_TOKEN=ghp_xxx
+gitclaw --repo https://github.com/org/repo "Add unit tests"
 ```
 
+### CLI Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--dir <path>` | `-d` | Agent directory (default: cwd) |
+| `--repo <url>` | `-r` | GitHub repo URL to clone and work on |
+| `--pat <token>` | | GitHub PAT (or set `GITHUB_TOKEN` / `GIT_TOKEN`) |
+| `--session <branch>` | | Resume an existing session branch |
+| `--model <provider:model>` | `-m` | Override model (e.g. `anthropic:claude-sonnet-4-5-20250929`) |
+| `--sandbox` | `-s` | Run in sandbox VM |
+| `--prompt <text>` | `-p` | Single-shot prompt (skip REPL) |
+| `--env <name>` | `-e` | Environment config |
+
 ### SDK
 
 ```bash
@@ -87,7 +99,7 @@ npm install gitclaw
 ```
 
 ```typescript
-import { query, tool } from "gitclaw";
+import { query } from "gitclaw";
 
 // Simple query
 for await (const msg of query({
@@ -98,6 +110,18 @@ for await (const msg of query({
   if (msg.type === "delta") process.stdout.write(msg.content);
   if (msg.type === "assistant") console.log("\n\nDone.");
 }
+
+// Local repo mode via SDK
+for await (const msg of query({
+  prompt: "Fix the login bug",
+  model: "openai:gpt-4o-mini",
+  repo: {
+    url: "https://github.com/org/repo",
+    token: process.env.GITHUB_TOKEN!,
+  },
+})) {
+  if (msg.type === "delta") process.stdout.write(msg.content);
+}
 ```
 
 ## SDK
@@ -209,6 +233,8 @@ for await (const msg of query({
 | `replaceBuiltinTools` | `boolean` | Skip cli/read/write/memory |
 | `allowedTools` | `string[]` | Tool name allowlist |
 | `disallowedTools` | `string[]` | Tool name denylist |
+| `repo` | `LocalRepoOptions` | Clone a GitHub repo and work on a session branch |
+| `sandbox` | `SandboxOptions \| boolean` | Run in sandbox VM (mutually exclusive with `repo`) |
 | `hooks` | `GCHooks` | Programmatic lifecycle hooks |
 | `maxTurns` | `number` | Max agent turns |
 | `abortController` | `AbortController` | Cancellation signal |
@@ -433,8 +459,8 @@ Audit logs are written to `.gitagent/audit.jsonl` with full tool invocation trac
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request.
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT
+This project is licensed under the [MIT License](./LICENSE).

package/dist/composio/adapter.d.ts

@@ -0,0 +1,26 @@
+import type { GCToolDefinition } from "../sdk-types.js";
+import { type ComposioToolkit, type ComposioConnection } from "./client.js";
+interface ComposioAdapterOptions {
+    apiKey: string;
+    userId?: string;
+}
+export declare class ComposioAdapter {
+    private client;
+    private userId;
+    private cachedTools;
+    private cacheExpiry;
+    private static CACHE_TTL;
+    constructor(opts: ComposioAdapterOptions);
+    getTools(): Promise<GCToolDefinition[]>;
+    getToolsForQuery(query: string, limit?: number): Promise<GCToolDefinition[]>;
+    getConnectedToolkitSlugs(): Promise<string[]>;
+    getToolkits(): Promise<ComposioToolkit[]>;
+    connect(toolkit: string, redirectUrl?: string): Promise<{
+        connectionId: string;
+        redirectUrl: string;
+    }>;
+    getConnections(): Promise<ComposioConnection[]>;
+    disconnect(connectionId: string): Promise<void>;
+    private toGCTool;
+}
+export {};

package/dist/composio/adapter.js

@@ -0,0 +1,92 @@
+// Converts Composio tools into GCToolDefinition[] for injection into query()
+import { ComposioClient } from "./client.js";
+export class ComposioAdapter {
+    client;
+    userId;
+    cachedTools = null;
+    cacheExpiry = 0;
+    static CACHE_TTL = 30_000; // 30s
+    constructor(opts) {
+        this.client = new ComposioClient(opts.apiKey);
+        this.userId = opts.userId ?? "default";
+    }
+    // Core — returns all tools for connected toolkits (cached)
+    async getTools() {
+        const now = Date.now();
+        if (this.cachedTools && now < this.cacheExpiry)
+            return this.cachedTools;
+        const connections = await this.client.listConnections(this.userId);
+        if (connections.length === 0)
+            return [];
+        // Deduplicate toolkit slugs
+        const slugs = [...new Set(connections.map((c) => c.toolkitSlug))];
+        // Fetch tools for each connected toolkit in parallel
+        const toolsBySlug = await Promise.all(slugs.map((slug) => this.client.listTools(slug).catch(() => [])));
+        const tools = [];
+        for (const toolGroup of toolsBySlug) {
+            for (const t of toolGroup) {
+                tools.push(this.toGCTool(t));
+            }
+        }
+        this.cachedTools = tools;
+        this.cacheExpiry = now + ComposioAdapter.CACHE_TTL;
+        return tools;
+    }
+    // Dynamically fetch only the relevant tools for a user query (semantic search)
+    async getToolsForQuery(query, limit = 15) {
+        const connections = await this.client.listConnections(this.userId);
+        if (connections.length === 0)
+            return [];
+        const slugs = [...new Set(connections.map((c) => c.toolkitSlug))];
+        const tools = await this.client.searchTools(query, slugs, limit);
+        // Sort: direct-action tools first (SEND, CREATE, LIST), drafts last
+        tools.sort((a, b) => {
+            const aIsDraft = a.slug.includes("DRAFT");
+            const bIsDraft = b.slug.includes("DRAFT");
+            if (aIsDraft !== bIsDraft)
+                return aIsDraft ? 1 : -1;
+            return 0;
+        });
+        return tools.map((t) => this.toGCTool(t));
+    }
+    // Returns deduplicated slugs of all connected toolkits
+    async getConnectedToolkitSlugs() {
+        const connections = await this.client.listConnections(this.userId);
+        return [...new Set(connections.map((c) => c.toolkitSlug))];
+    }
+    // Management endpoints — proxied for server routes
+    async getToolkits() {
+        return this.client.listToolkits(this.userId);
+    }
+    async connect(toolkit, redirectUrl) {
+        return this.client.initiateConnection(toolkit, this.userId, redirectUrl);
+    }
+    async getConnections() {
+        return this.client.listConnections(this.userId);
+    }
+    async disconnect(connectionId) {
+        await this.client.deleteConnection(connectionId);
+        // Invalidate cache so tools refresh on next query
+        this.cachedTools = null;
+    }
+    // ── Private ────────────────────────────────────────────────────────
+    toGCTool(t) {
+        const safeName = `composio_${t.toolkitSlug}_${t.slug}`.replace(/[^a-zA-Z0-9_]/g, "_");
+        let description = `[Composio/${t.toolkitSlug}] ${t.description}`;
+        if (t.slug.includes("SEND_EMAIL")) {
+            description += " — USE THIS to send emails directly.";
+        }
+        else if (t.slug.includes("CREATE_EMAIL_DRAFT")) {
+            description += " — Only use when the user explicitly asks for a draft.";
+        }
+        return {
+            name: safeName,
+            description,
+            inputSchema: t.parameters,
+            handler: async (args) => {
+                const result = await this.client.executeTool(t.slug, this.userId, args);
+                return typeof result === "string" ? result : JSON.stringify(result);
+            },
+        };
+    }
+}

package/dist/composio/client.d.ts

@@ -0,0 +1,39 @@
+export interface ComposioToolkit {
+    slug: string;
+    name: string;
+    description: string;
+    logo: string;
+    authSchemes: string[];
+    noAuth: boolean;
+    connected: boolean;
+}
+export interface ComposioConnection {
+    id: string;
+    toolkitSlug: string;
+    status: string;
+    createdAt: string;
+}
+export interface ComposioTool {
+    name: string;
+    slug: string;
+    description: string;
+    toolkitSlug: string;
+    parameters: Record<string, any>;
+}
+export declare class ComposioClient {
+    private apiKey;
+    private authConfigCache;
+    constructor(apiKey: string);
+    listToolkits(userId?: string): Promise<ComposioToolkit[]>;
+    searchTools(query: string, toolkitSlugs?: string[], limit?: number): Promise<ComposioTool[]>;
+    listTools(toolkitSlug: string): Promise<ComposioTool[]>;
+    getOrCreateAuthConfig(toolkitSlug: string): Promise<string>;
+    initiateConnection(toolkitSlug: string, userId: string, redirectUrl?: string): Promise<{
+        connectionId: string;
+        redirectUrl: string;
+    }>;
+    listConnections(userId: string): Promise<ComposioConnection[]>;
+    deleteConnection(id: string): Promise<void>;
+    executeTool(toolSlug: string, userId: string, params: Record<string, any>, connectedAccountId?: string): Promise<any>;
+    private request;
+}

package/dist/composio/client.js

@@ -0,0 +1,170 @@
+// Composio REST API v3 client — zero dependencies, uses native fetch()
+const BASE_URL = "https://backend.composio.dev/api/v3";
+// ── Client ───────────────────────────────────────────────────────────
+export class ComposioClient {
+    apiKey;
+    // Cache auth config IDs so we don't recreate them every connect
+    authConfigCache = new Map();
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    // List available toolkits, optionally merging connection status for a user
+    async listToolkits(userId) {
+        const resp = await this.request("GET", "/toolkits");
+        const toolkits = Array.isArray(resp) ? resp : (resp.items ?? resp.toolkits ?? []);
+        let connectedSlugs = new Set();
+        if (userId) {
+            try {
+                const conns = await this.listConnections(userId);
+                connectedSlugs = new Set(conns.map((c) => c.toolkitSlug));
+            }
+            catch {
+                // If connections fail, just show all as disconnected
+            }
+        }
+        return toolkits.map((tk) => ({
+            slug: tk.slug ?? "",
+            name: tk.name ?? tk.slug ?? "",
+            description: tk.meta?.description ?? tk.description ?? "",
+            logo: tk.meta?.logo ?? tk.logo ?? "",
+            authSchemes: tk.auth_schemes ?? [],
+            noAuth: tk.no_auth ?? false,
+            connected: connectedSlugs.has(tk.slug ?? ""),
+        }));
+    }
+    // Search tools across connected toolkits by natural language query
+    // Makes parallel per-toolkit requests since the API doesn't support comma-separated toolkit_slug with query
+    async searchTools(query, toolkitSlugs, limit = 10) {
+        const mapTool = (t) => ({
+            name: t.name ?? t.enum ?? "",
+            slug: t.slug ?? t.enum ?? t.name ?? "",
+            description: t.description ?? "",
+            toolkitSlug: t.toolkit?.slug ?? t.toolkit_slug ?? "",
+            parameters: t.input_parameters ?? t.parameters ?? t.inputParameters ?? {},
+        });
+        if (!toolkitSlugs?.length) {
+            const params = new URLSearchParams({ query, limit: String(limit) });
+            const resp = await this.request("GET", `/tools?${params}`);
+            const tools = Array.isArray(resp) ? resp : (resp.items ?? resp.tools ?? []);
+            return tools.map(mapTool);
+        }
+        // Parallel per-toolkit search
+        const perToolkit = await Promise.all(toolkitSlugs.map(async (slug) => {
+            try {
+                const params = new URLSearchParams({ query, toolkit_slug: slug, limit: String(limit) });
+                const resp = await this.request("GET", `/tools?${params}`);
+                const tools = Array.isArray(resp) ? resp : (resp.items ?? resp.tools ?? []);
+                return tools.map(mapTool);
+            }
+            catch {
+                return [];
+            }
+        }));
+        return perToolkit.flat().slice(0, limit);
+    }
+    // List tools for a specific toolkit
+    async listTools(toolkitSlug) {
+        const resp = await this.request("GET", `/tools?toolkit_slug=${encodeURIComponent(toolkitSlug)}`);
+        const tools = Array.isArray(resp) ? resp : (resp.items ?? resp.tools ?? []);
+        return tools.map((t) => ({
+            name: t.name ?? t.enum ?? "",
+            slug: t.slug ?? t.enum ?? t.name ?? "",
+            description: t.description ?? "",
+            toolkitSlug,
+            parameters: t.input_parameters ?? t.parameters ?? t.inputParameters ?? {},
+        }));
+    }
+    // Get or create an auth config for a toolkit (needed before creating a connection)
+    async getOrCreateAuthConfig(toolkitSlug) {
+        // Check cache first
+        const cached = this.authConfigCache.get(toolkitSlug);
+        if (cached)
+            return cached;
+        // Check if one already exists
+        const existing = await this.request("GET", `/auth_configs?toolkit_slug=${encodeURIComponent(toolkitSlug)}`);
+        const items = existing.items ?? [];
+        if (items.length > 0) {
+            const id = items[0].id ?? items[0].auth_config?.id;
+            if (id) {
+                this.authConfigCache.set(toolkitSlug, id);
+                return id;
+            }
+        }
+        // Create a new one with Composio-managed auth
+        const created = await this.request("POST", "/auth_configs", {
+            toolkit: { slug: toolkitSlug },
+            auth_scheme: "OAUTH2",
+            use_composio_auth: true,
+        });
+        const id = created.auth_config?.id ?? created.id ?? "";
+        if (id)
+            this.authConfigCache.set(toolkitSlug, id);
+        return id;
+    }
+    // Start OAuth connection flow (two-step: ensure auth config, then create connection)
+    async initiateConnection(toolkitSlug, userId, redirectUrl) {
+        const authConfigId = await this.getOrCreateAuthConfig(toolkitSlug);
+        if (!authConfigId) {
+            throw new Error(`Failed to get auth config for toolkit: ${toolkitSlug}`);
+        }
+        const body = {
+            auth_config: { id: authConfigId },
+            connection: {
+                user_id: userId,
+                ...(redirectUrl ? { callback_url: redirectUrl } : {}),
+            },
+        };
+        const resp = await this.request("POST", "/connected_accounts", body);
+        return {
+            connectionId: resp.id ?? "",
+            redirectUrl: resp.redirect_url ?? resp.redirect_uri ?? resp.redirectUrl ?? resp.redirectUri ?? "",
+        };
+    }
+    // List active connections for a user
+    async listConnections(userId) {
+        const resp = await this.request("GET", `/connected_accounts?user_ids=${encodeURIComponent(userId)}&statuses=ACTIVE`);
+        const items = Array.isArray(resp) ? resp : (resp.items ?? resp.connections ?? []);
+        return items.map((c) => ({
+            id: c.id ?? "",
+            toolkitSlug: c.toolkit?.slug ?? c.toolkit_slug ?? c.appUniqueId ?? c.integrationId ?? "",
+            status: c.status ?? "ACTIVE",
+            createdAt: c.createdAt ?? c.created_at ?? "",
+        }));
+    }
+    // Delete a connection
+    async deleteConnection(id) {
+        await this.request("DELETE", `/connected_accounts/${encodeURIComponent(id)}`);
+    }
+    // Execute a tool action
+    async executeTool(toolSlug, userId, params, connectedAccountId) {
+        const body = {
+            arguments: params,
+            user_id: userId,
+        };
+        if (connectedAccountId)
+            body.connected_account_id = connectedAccountId;
+        return this.request("POST", `/tools/execute/${encodeURIComponent(toolSlug)}`, body);
+    }
+    // ── Private ────────────────────────────────────────────────────────
+    async request(method, path, body) {
+        const url = `${BASE_URL}${path}`;
+        const headers = {
+            "x-api-key": this.apiKey,
+            "Accept": "application/json",
+        };
+        if (body)
+            headers["Content-Type"] = "application/json";
+        const resp = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            throw new Error(`Composio API ${method} ${path} failed (${resp.status}): ${text}`);
+        }
+        if (resp.status === 204)
+            return undefined;
+        return resp.json();
+    }
+}

package/dist/composio/index.d.ts

@@ -0,0 +1,2 @@
+export { ComposioClient, type ComposioToolkit, type ComposioConnection, type ComposioTool } from "./client.js";
+export { ComposioAdapter } from "./adapter.js";

package/dist/composio/index.js

@@ -0,0 +1,2 @@
+export { ComposioClient } from "./client.js";
+export { ComposioAdapter } from "./adapter.js";

package/dist/context.d.ts

@@ -0,0 +1,20 @@
+export interface ContextSnapshot {
+    memory: string;
+    summary: string;
+    recentChat: string;
+    recentMood: string;
+}
+/** Read MEMORY.md + chat-summary + recent chat, returns raw content */
+export declare function getContextSnapshot(agentDir: string, branch: string): Promise<ContextSnapshot>;
+/**
+ * Returns context string for voice LLM system instructions.
+ * Includes: memory + conversation summary + recent chat history.
+ * Recent chat is critical — it survives page refreshes so the voice LLM
+ * knows what just happened even when the WebSocket reconnects.
+ */
+export declare function getVoiceContext(agentDir: string, branch: string): Promise<string>;
+/**
+ * Returns richer context for run_agent systemPromptSuffix.
+ * Includes: full memory + summary. Capped at ~2000 tokens.
+ */
+export declare function getAgentContext(agentDir: string, branch: string): Promise<string>;