freeturtle 0.1.0

package/dist/src/modules/github/client.js

@@ -0,0 +1,80 @@
+import { Octokit } from "@octokit/rest";
+export class GitHubClient {
+    octokit;
+    constructor(token) {
+        this.octokit = new Octokit({ auth: token });
+    }
+    parseRepo(repo) {
+        const [owner, name] = repo.split("/");
+        return { owner, repo: name };
+    }
+    async createIssue(repo, title, body) {
+        const { owner, repo: name } = this.parseRepo(repo);
+        const { data } = await this.octokit.issues.create({
+            owner,
+            repo: name,
+            title,
+            body,
+        });
+        return {
+            number: data.number,
+            title: data.title,
+            body: data.body ?? null,
+            state: data.state,
+            html_url: data.html_url,
+            created_at: data.created_at,
+            user: data.user?.login ?? "unknown",
+        };
+    }
+    async listIssues(repo, state = "open") {
+        const { owner, repo: name } = this.parseRepo(repo);
+        const { data } = await this.octokit.issues.listForRepo({
+            owner,
+            repo: name,
+            state,
+            per_page: 30,
+        });
+        return data.map((d) => ({
+            number: d.number,
+            title: d.title,
+            body: d.body ?? null,
+            state: d.state,
+            html_url: d.html_url,
+            created_at: d.created_at,
+            user: d.user?.login ?? "unknown",
+        }));
+    }
+    async commitFile(repo, path, content, message, branch) {
+        const { owner, repo: name } = this.parseRepo(repo);
+        // Check if file exists to get its SHA
+        let existingSha;
+        try {
+            const { data } = await this.octokit.repos.getContent({
+                owner,
+                repo: name,
+                path,
+                ...(branch ? { ref: branch } : {}),
+            });
+            if (!Array.isArray(data) && data.type === "file") {
+                existingSha = data.sha;
+            }
+        }
+        catch {
+            // File doesn't exist yet
+        }
+        const { data } = await this.octokit.repos.createOrUpdateFileContents({
+            owner,
+            repo: name,
+            path,
+            message,
+            content: Buffer.from(content).toString("base64"),
+            sha: existingSha,
+            ...(branch ? { branch } : {}),
+        });
+        return {
+            sha: data.commit.sha ?? "",
+            html_url: data.content?.html_url ?? "",
+        };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/modules/github/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/modules/github/client.ts"],"names":[],"mappings":"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"}

package/dist/src/modules/github/index.d.ts

@@ -0,0 +1,13 @@
+import type { FreeTurtleModule, ToolDefinition } from "../types.js";
+import type { PolicyConfig } from "../../policy.js";
+export declare class GitHubModule implements FreeTurtleModule {
+    name: string;
+    description: string;
+    private client;
+    private policy?;
+    initialize(_config: Record<string, unknown>, env: Record<string, string>, options?: {
+        policy?: PolicyConfig;
+    }): Promise<void>;
+    getTools(): ToolDefinition[];
+    executeTool(name: string, input: Record<string, unknown>): Promise<string>;
+}

package/dist/src/modules/github/index.js

@@ -0,0 +1,45 @@
+import { assertGithubRepoAllowed, assertGithubPathAllowed, } from "../../policy.js";
+import { withRetry } from "../../reliability.js";
+import { GitHubClient } from "./client.js";
+import { githubTools } from "./tools.js";
+export class GitHubModule {
+    name = "github";
+    description = "Create issues, list issues, and commit files to GitHub.";
+    client;
+    policy;
+    async initialize(_config, env, options) {
+        const token = env.GITHUB_TOKEN;
+        if (!token)
+            throw new Error("GitHub module requires GITHUB_TOKEN");
+        this.client = new GitHubClient(token);
+        this.policy = options?.policy;
+    }
+    getTools() {
+        return githubTools;
+    }
+    async executeTool(name, input) {
+        // Enforce repo allowlist on all GitHub operations
+        if (input.repo) {
+            assertGithubRepoAllowed(this.policy, input.repo);
+        }
+        switch (name) {
+            case "create_issue": {
+                const issue = await withRetry(() => this.client.createIssue(input.repo, input.title, input.body));
+                return JSON.stringify(issue);
+            }
+            case "list_issues": {
+                const issues = await withRetry(() => this.client.listIssues(input.repo, input.state ?? "open"));
+                return JSON.stringify(issues);
+            }
+            case "commit_file": {
+                // Enforce path allowlist for commits
+                assertGithubPathAllowed(this.policy, input.path);
+                const result = await withRetry(() => this.client.commitFile(input.repo, input.path, input.content, input.message, input.branch));
+                return JSON.stringify(result);
+            }
+            default:
+                throw new Error(`Unknown github tool: ${name}`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/modules/github/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/github/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,OAAO,YAAY;IACvB,IAAI,GAAG,QAAQ,CAAC;IAChB,WAAW,GAAG,yDAAyD,CAAC;IAEhE,MAAM,CAAgB;IACtB,MAAM,CAAgB;IAE9B,KAAK,CAAC,UAAU,CACd,OAAgC,EAChC,GAA2B,EAC3B,OAAmC;QAEnC,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC;QAC/B,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAChC,CAAC;IAED,QAAQ;QACN,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,WAAW,CACf,IAAY,EACZ,KAA8B;QAE9B,kDAAkD;QAClD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAc,CAAC,CAAC;QAC7D,CAAC;QAED,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CACjC,IAAI,CAAC,MAAM,CAAC,WAAW,CACrB,KAAK,CAAC,IAAc,EACpB,KAAK,CAAC,KAAe,EACrB,KAAK,CAAC,IAAc,CACrB,CACF,CAAC;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;YACD,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAClC,IAAI,CAAC,MAAM,CAAC,UAAU,CACpB,KAAK,CAAC,IAAc,EACnB,KAAK,CAAC,KAAmC,IAAI,MAAM,CACrD,CACF,CAAC;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;YACD,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,qCAAqC;gBACrC,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAc,CAAC,CAAC;gBAE3D,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAClC,IAAI,CAAC,MAAM,CAAC,UAAU,CACpB,KAAK,CAAC,IAAc,EACpB,KAAK,CAAC,IAAc,EACpB,KAAK,CAAC,OAAiB,EACvB,KAAK,CAAC,OAAiB,EACvB,KAAK,CAAC,MAA4B,CACnC,CACF,CAAC;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;YACD;gBACE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;CACF"}

package/dist/src/modules/github/tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare const githubTools: ToolDefinition[];

package/dist/src/modules/github/tools.js

@@ -0,0 +1,74 @@
+export const githubTools = [
+    {
+        name: "create_issue",
+        description: "Create a new issue on a GitHub repository.",
+        input_schema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Repository in owner/name format (e.g. 'tortoise-club/FreeTurtle')",
+                },
+                title: {
+                    type: "string",
+                    description: "Issue title",
+                },
+                body: {
+                    type: "string",
+                    description: "Issue body (markdown supported)",
+                },
+            },
+            required: ["repo", "title", "body"],
+        },
+    },
+    {
+        name: "list_issues",
+        description: "List issues for a GitHub repository.",
+        input_schema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Repository in owner/name format",
+                },
+                state: {
+                    type: "string",
+                    enum: ["open", "closed", "all"],
+                    description: "Filter by state (default: open)",
+                },
+            },
+            required: ["repo"],
+        },
+    },
+    {
+        name: "commit_file",
+        description: "Create or update a file in a GitHub repository via a commit. Writes to non-main branches are allowed if in scope. Writes to main require founder approval.",
+        input_schema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Repository in owner/name format",
+                },
+                path: {
+                    type: "string",
+                    description: "File path in the repo (e.g. 'strategy/2026-03-02.md')",
+                },
+                content: {
+                    type: "string",
+                    description: "The file content to write",
+                },
+                message: {
+                    type: "string",
+                    description: "Commit message",
+                },
+                branch: {
+                    type: "string",
+                    description: "Target branch (default: main). Non-main branches do not require approval.",
+                },
+            },
+            required: ["repo", "path", "content", "message"],
+        },
+    },
+];
+//# sourceMappingURL=tools.js.map

package/dist/src/modules/github/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../src/modules/github/tools.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,4CAA4C;QACzD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mEAAmE;iBACjF;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,aAAa;iBAC3B;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iCAAiC;iBAC/C;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;SACpC;KACF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iCAAiC;iBAC/C;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;oBAC/B,WAAW,EAAE,iCAAiC;iBAC/C;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,4JAA4J;QAC9J,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iCAAiC;iBAC/C;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uDAAuD;iBACrE;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2BAA2B;iBACzC;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gBAAgB;iBAC9B;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2EAA2E;iBACzF;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC;SACjD;KACF;CACF,CAAC"}

package/dist/src/modules/loader.d.ts

@@ -0,0 +1,5 @@
+import type { FreeTurtleConfig } from "../config.js";
+import type { PolicyConfig } from "../policy.js";
+import type { FreeTurtleModule } from "./types.js";
+import type { Logger } from "../logger.js";
+export declare function loadModules(config: FreeTurtleConfig, env: Record<string, string>, logger?: Logger, policy?: PolicyConfig): Promise<FreeTurtleModule[]>;

package/dist/src/modules/loader.js

@@ -0,0 +1,35 @@
+import { FarcasterModule } from "./farcaster/index.js";
+import { DatabaseModule } from "./database/index.js";
+import { GitHubModule } from "./github/index.js";
+import { OnchainModule } from "./onchain/index.js";
+import { XmtpModule } from "./xmtp/index.js";
+const MODULE_MAP = {
+    farcaster: FarcasterModule,
+    database: DatabaseModule,
+    github: GitHubModule,
+    onchain: OnchainModule,
+    xmtp: XmtpModule,
+};
+export async function loadModules(config, env, logger, policy) {
+    const modules = [];
+    for (const [name, moduleConfig] of Object.entries(config.modules)) {
+        if (!moduleConfig.enabled)
+            continue;
+        const ModuleClass = MODULE_MAP[name];
+        if (!ModuleClass) {
+            logger?.warn(`Unknown module: ${name} — skipping`);
+            continue;
+        }
+        try {
+            const mod = new ModuleClass();
+            await mod.initialize(moduleConfig, env, { policy });
+            modules.push(mod);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : "Unknown error";
+            logger?.error(`Module "${name}" failed to initialize: ${msg} — skipping`);
+        }
+    }
+    return modules;
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/modules/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/modules/loader.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,UAAU,GAA+C;IAC7D,SAAS,EAAE,eAAe;IAC1B,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,aAAa;IACtB,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAwB,EACxB,GAA2B,EAC3B,MAAe,EACf,MAAqB;IAErB,MAAM,OAAO,GAAuB,EAAE,CAAC;IAEvC,KAAK,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,YAAY,CAAC,OAAO;YAAE,SAAS;QAEpC,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,EAAE,IAAI,CAAC,mBAAmB,IAAI,aAAa,CAAC,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,MAAM,GAAG,CAAC,UAAU,CAClB,YAAkD,EAClD,GAAG,EACH,EAAE,MAAM,EAAE,CACX,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACjE,MAAM,EAAE,KAAK,CAAC,WAAW,IAAI,2BAA2B,GAAG,aAAa,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/modules/onchain/client.d.ts

@@ -0,0 +1,8 @@
+export declare class OnchainClient {
+    private client;
+    private basescanKey?;
+    constructor(rpcUrl: string, basescanKey?: string);
+    readContract(address: string, abi: unknown[], functionName: string, args?: unknown[]): Promise<unknown>;
+    getBalance(address: string): Promise<string>;
+    getTransactions(address: string, limit?: number): Promise<Record<string, unknown>[]>;
+}

package/dist/src/modules/onchain/client.js

@@ -0,0 +1,46 @@
+import { createPublicClient, http, formatEther } from "viem";
+import { base } from "viem/chains";
+export class OnchainClient {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client;
+    basescanKey;
+    constructor(rpcUrl, basescanKey) {
+        this.client = createPublicClient({
+            chain: base,
+            transport: http(rpcUrl),
+        });
+        this.basescanKey = basescanKey;
+    }
+    async readContract(address, abi, functionName, args) {
+        const result = await this.client.readContract({
+            address: address,
+            abi,
+            functionName,
+            args: args ?? [],
+        });
+        return result;
+    }
+    async getBalance(address) {
+        const balance = await this.client.getBalance({
+            address: address,
+        });
+        return formatEther(balance);
+    }
+    async getTransactions(address, limit = 10) {
+        if (!this.basescanKey) {
+            return [{ error: "BASESCAN_API_KEY not set, cannot fetch transactions" }];
+        }
+        const url = `https://api.basescan.org/api?module=account&action=txlist&address=${address}&startblock=0&endblock=99999999&page=1&offset=${limit}&sort=desc&apikey=${this.basescanKey}`;
+        const res = await fetch(url);
+        const data = (await res.json());
+        return (data.result ?? []).map((tx) => ({
+            hash: tx.hash,
+            from: tx.from,
+            to: tx.to,
+            value: tx.value,
+            timestamp: tx.timeStamp,
+            functionName: tx.functionName,
+        }));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/modules/onchain/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/modules/onchain/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,MAAM,OAAO,aAAa;IACxB,8DAA8D;IACtD,MAAM,CAAM;IACZ,WAAW,CAAU;IAE7B,YAAY,MAAc,EAAE,WAAoB;QAC9C,IAAI,CAAC,MAAM,GAAG,kBAAkB,CAAC;YAC/B,KAAK,EAAE,IAAI;YACX,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC;SACxB,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,OAAe,EACf,GAAc,EACd,YAAoB,EACpB,IAAgB;QAEhB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;YAC5C,OAAO,EAAE,OAAwB;YACjC,GAAG;YACH,YAAY;YACZ,IAAI,EAAE,IAAI,IAAI,EAAE;SACjB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAe;QAC9B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;YAC3C,OAAO,EAAE,OAAwB;SAClC,CAAC,CAAC;QACH,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,OAAe,EACf,KAAK,GAAG,EAAE;QAEV,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO,CAAC,EAAE,KAAK,EAAE,qDAAqD,EAAE,CAAC,CAAC;QAC5E,CAAC;QAED,MAAM,GAAG,GAAG,qEAAqE,OAAO,iDAAiD,KAAK,qBAAqB,IAAI,CAAC,WAAW,EAAE,CAAC;QACtL,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAE7B,CAAC;QAEF,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACtC,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,EAAE,EAAE,EAAE,CAAC,EAAE;YACT,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,YAAY,EAAE,EAAE,CAAC,YAAY;SAC9B,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/src/modules/onchain/index.d.ts

@@ -0,0 +1,13 @@
+import type { FreeTurtleModule, ToolDefinition } from "../types.js";
+import type { PolicyConfig } from "../../policy.js";
+export declare class OnchainModule implements FreeTurtleModule {
+    name: string;
+    description: string;
+    private client;
+    private policy?;
+    initialize(_config: Record<string, unknown>, env: Record<string, string>, options?: {
+        policy?: PolicyConfig;
+    }): Promise<void>;
+    getTools(): ToolDefinition[];
+    executeTool(name: string, input: Record<string, unknown>): Promise<string>;
+}

package/dist/src/modules/onchain/index.js

@@ -0,0 +1,40 @@
+import { assertOnchainScopeAllowed } from "../../policy.js";
+import { withRetry } from "../../reliability.js";
+import { OnchainClient } from "./client.js";
+import { onchainTools } from "./tools.js";
+export class OnchainModule {
+    name = "onchain";
+    description = "Read smart contracts, balances, and transactions on Base.";
+    client;
+    policy;
+    async initialize(_config, env, options) {
+        const rpcUrl = env.RPC_URL;
+        if (!rpcUrl)
+            throw new Error("Onchain module requires RPC_URL");
+        this.client = new OnchainClient(rpcUrl, env.BASESCAN_API_KEY);
+        this.policy = options?.policy;
+    }
+    getTools() {
+        return onchainTools;
+    }
+    async executeTool(name, input) {
+        switch (name) {
+            case "read_contract": {
+                assertOnchainScopeAllowed(this.policy, input.address, input.function_name);
+                const result = await withRetry(() => this.client.readContract(input.address, input.abi, input.function_name, input.args));
+                return JSON.stringify(result);
+            }
+            case "get_balance": {
+                const balance = await withRetry(() => this.client.getBalance(input.address));
+                return `${balance} ETH`;
+            }
+            case "get_transactions": {
+                const txs = await withRetry(() => this.client.getTransactions(input.address, input.limit ?? 10));
+                return JSON.stringify(txs);
+            }
+            default:
+                throw new Error(`Unknown onchain tool: ${name}`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/modules/onchain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/onchain/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,OAAO,aAAa;IACxB,IAAI,GAAG,SAAS,CAAC;IACjB,WAAW,GAAG,2DAA2D,CAAC;IAElE,MAAM,CAAiB;IACvB,MAAM,CAAgB;IAE9B,KAAK,CAAC,UAAU,CACd,OAAgC,EAChC,GAA2B,EAC3B,OAAmC;QAEnC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC;QAC3B,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAChC,CAAC;IAED,QAAQ;QACN,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,WAAW,CACf,IAAY,EACZ,KAA8B;QAE9B,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,yBAAyB,CACvB,IAAI,CAAC,MAAM,EACX,KAAK,CAAC,OAAiB,EACvB,KAAK,CAAC,aAAuB,CAC9B,CAAC;gBACF,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAClC,IAAI,CAAC,MAAM,CAAC,YAAY,CACtB,KAAK,CAAC,OAAiB,EACvB,KAAK,CAAC,GAAgB,EACtB,KAAK,CAAC,aAAuB,EAC7B,KAAK,CAAC,IAA6B,CACpC,CACF,CAAC;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;YACD,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CACnC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,OAAiB,CAAC,CAChD,CAAC;gBACF,OAAO,GAAG,OAAO,MAAM,CAAC;YAC1B,CAAC;YACD,KAAK,kBAAkB,CAAC,CAAC,CAAC;gBACxB,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAC/B,IAAI,CAAC,MAAM,CAAC,eAAe,CACzB,KAAK,CAAC,OAAiB,EACtB,KAAK,CAAC,KAAgB,IAAI,EAAE,CAC9B,CACF,CAAC;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD;gBACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF"}

package/dist/src/modules/onchain/tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare const onchainTools: ToolDefinition[];

package/dist/src/modules/onchain/tools.js

@@ -0,0 +1,61 @@
+export const onchainTools = [
+    {
+        name: "read_contract",
+        description: "Read data from a smart contract on Base. Requires the contract ABI for the function being called.",
+        input_schema: {
+            type: "object",
+            properties: {
+                address: {
+                    type: "string",
+                    description: "Contract address (0x...)",
+                },
+                abi: {
+                    type: "array",
+                    description: "ABI array containing at least the function definition",
+                },
+                function_name: {
+                    type: "string",
+                    description: "Name of the function to call",
+                },
+                args: {
+                    type: "array",
+                    description: "Function arguments (optional)",
+                },
+            },
+            required: ["address", "abi", "function_name"],
+        },
+    },
+    {
+        name: "get_balance",
+        description: "Get the ETH balance of an address on Base.",
+        input_schema: {
+            type: "object",
+            properties: {
+                address: {
+                    type: "string",
+                    description: "Wallet address (0x...)",
+                },
+            },
+            required: ["address"],
+        },
+    },
+    {
+        name: "get_transactions",
+        description: "Get recent transactions for an address on Base (requires BASESCAN_API_KEY).",
+        input_schema: {
+            type: "object",
+            properties: {
+                address: {
+                    type: "string",
+                    description: "Wallet address (0x...)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Number of transactions to return (default 10)",
+                },
+            },
+            required: ["address"],
+        },
+    },
+];
+//# sourceMappingURL=tools.js.map

package/dist/src/modules/onchain/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../src/modules/onchain/tools.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC5C;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,mGAAmG;QACrG,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0BAA0B;iBACxC;gBACD,GAAG,EAAE;oBACH,IAAI,EAAE,OAAO;oBACb,WAAW,EAAE,uDAAuD;iBACrE;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8BAA8B;iBAC5C;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,WAAW,EAAE,+BAA+B;iBAC7C;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC;SAC9C;KACF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,4CAA4C;QACzD,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wBAAwB;iBACtC;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;KACF;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,6EAA6E;QAC/E,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wBAAwB;iBACtC;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+CAA+C;iBAC7D;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;KACF;CACF,CAAC"}

package/dist/src/modules/types.d.ts

@@ -0,0 +1,24 @@
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResult {
+    tool_use_id: string;
+    content: string;
+}
+export type ToolExecutor = (call: ToolCall) => Promise<string>;
+export interface FreeTurtleModule {
+    name: string;
+    description: string;
+    initialize(config: Record<string, unknown>, env: Record<string, string>, options?: {
+        policy?: import("../policy.js").PolicyConfig;
+    }): Promise<void>;
+    getTools(): ToolDefinition[];
+    executeTool(name: string, input: Record<string, unknown>): Promise<string>;
+}

package/dist/src/modules/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/modules/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/types.ts"],"names":[],"mappings":""}

package/dist/src/modules/xmtp/index.d.ts

@@ -0,0 +1,8 @@
+import type { FreeTurtleModule, ToolDefinition } from "../types.js";
+export declare class XmtpModule implements FreeTurtleModule {
+    name: string;
+    description: string;
+    initialize(): Promise<void>;
+    getTools(): ToolDefinition[];
+    executeTool(name: string): Promise<string>;
+}

package/dist/src/modules/xmtp/index.js

@@ -0,0 +1,14 @@
+export class XmtpModule {
+    name = "xmtp";
+    description = "XMTP messaging (not yet implemented).";
+    async initialize() {
+        console.log("XMTP module not yet implemented");
+    }
+    getTools() {
+        return [];
+    }
+    async executeTool(name) {
+        throw new Error(`XMTP tool "${name}" not implemented`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/modules/xmtp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/xmtp/index.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,UAAU;IACrB,IAAI,GAAG,MAAM,CAAC;IACd,WAAW,GAAG,uCAAuC,CAAC;IAEtD,KAAK,CAAC,UAAU;QACd,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;IACjD,CAAC;IAED,QAAQ;QACN,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAAY;QAC5B,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,mBAAmB,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/src/policy.d.ts

@@ -0,0 +1,45 @@
+export interface PolicyConfig {
+    github: {
+        allowed_repos: string[];
+        allowed_paths: string[];
+        approval_required_branches: string[];
+    };
+    farcaster: {
+        allowed_channels: string[];
+    };
+    database: {
+        allowed_schemas: string[];
+        allowed_tables: string[];
+    };
+    onchain: {
+        allowed_contracts: string[];
+        allowed_read_functions: string[];
+    };
+    approvals: {
+        timeout_seconds: number;
+        fail_mode: "deny" | "allow";
+    };
+}
+export declare class PolicyDeniedError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function assertGithubRepoAllowed(policy: PolicyConfig | undefined, repo: string): void;
+export declare function assertGithubPathAllowed(policy: PolicyConfig | undefined, path: string): void;
+export declare function assertGithubBranchAllowed(policy: PolicyConfig | undefined, branch: string): void;
+export declare function assertFarcasterChannelAllowed(policy: PolicyConfig | undefined, channel: string): void;
+export declare function assertDatabaseScopeAllowed(policy: PolicyConfig | undefined, schema: string, table: string): void;
+export declare function assertOnchainScopeAllowed(policy: PolicyConfig | undefined, contract: string, fn?: string): void;
+/**
+ * Determines whether a tool call requires human approval before execution.
+ * - delete_cast => always true
+ * - commit_file => true if branch is in approval_required_branches (default ["main"])
+ * - everything else => false
+ */
+export declare function requiresApproval(policy: PolicyConfig | undefined, toolName: string, input: Record<string, unknown>): boolean;
+export declare function getDefaultPolicy(): PolicyConfig;
+/**
+ * Parse a raw config object (from the ## Policy section) into a PolicyConfig.
+ * Expects subsections like github.allowed_repos as comma-separated strings.
+ */
+export declare function parsePolicy(raw: Record<string, Record<string, string | boolean>>): PolicyConfig;