exempclaw 0.4.0

package/dist/connectors/github/github-connector.d.ts

@@ -0,0 +1,52 @@
+import { type Connector, type ConnectorContext, type InboundEvent } from "../connector.js";
+import { type FetchLike } from "../http.js";
+import { type Tool } from "../../tools/tool.js";
+/**
+ * GitHub connector over the REST API. Tools cover issue/PR triage and
+ * commenting; inbound events come from polling the configured repos
+ * (GITHUB_REPOS) for recently-updated issues — webhooks need a public
+ * endpoint, polling doesn't.
+ *
+ * Works with a fine-grained PAT that has Issues read/write on the target
+ * repos (plus "Read access to metadata").
+ */
+interface GitHubIssue {
+    number: number;
+    title: string;
+    state: string;
+    body?: string | null;
+    user?: {
+        login: string;
+    } | null;
+    labels?: Array<{
+        name?: string;
+    } | string>;
+    comments?: number;
+    created_at: string;
+    updated_at: string;
+    html_url: string;
+    pull_request?: unknown;
+}
+export declare class GitHubConnector implements Connector {
+    private readonly fetchImpl?;
+    readonly id = "github";
+    private log;
+    private api;
+    private selfLogin;
+    private repos;
+    private pollMs;
+    /** repo#number → epoch ms of the agent's own last write, for loop suppression. */
+    private readonly selfActions;
+    constructor(fetchImpl?: FetchLike | undefined);
+    init(ctx: ConnectorContext): Promise<void>;
+    private resolveRepo;
+    tools(): Tool[];
+    /** Polls configured repos for updated issues and surfaces them as events. */
+    listen(onEvent: (event: InboundEvent) => void, signal: AbortSignal): Promise<void>;
+    /** Maps an updated issue to an InboundEvent, suppressing our own echoes. */
+    issueToInbound(repo: string, issue: GitHubIssue, since: string): InboundEvent | null;
+    private recordSelfAction;
+    /** True if the agent itself just wrote to this issue (poll echo window). */
+    isRecentSelfAction(repo: string, number: number, now?: number): boolean;
+}
+export {};

package/dist/connectors/github/github-connector.js

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import { sleep } from "../connector.js";
+import { HttpJson } from "../http.js";
+import { ConnectorError } from "../../core/errors.js";
+import { defineTool } from "../../tools/tool.js";
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+export class GitHubConnector {
+    fetchImpl;
+    id = "github";
+    log;
+    api;
+    selfLogin = "";
+    repos = [];
+    pollMs = 60_000;
+    /** repo#number → epoch ms of the agent's own last write, for loop suppression. */
+    selfActions = new Map();
+    constructor(fetchImpl) {
+        this.fetchImpl = fetchImpl;
+    }
+    async init(ctx) {
+        this.log = ctx.log.child({ scope: "connector", connector: this.id });
+        const token = ctx.config.token;
+        if (!token) {
+            throw new ConnectorError(this.id, "missing GITHUB_TOKEN (fine-grained PAT with Issues read/write)");
+        }
+        this.repos = (ctx.config.repos ?? "")
+            .split(",")
+            .map((r) => r.trim())
+            .filter(Boolean);
+        for (const repo of this.repos) {
+            if (!REPO_RE.test(repo))
+                throw new ConnectorError(this.id, `invalid repo in GITHUB_REPOS: "${repo}" (use owner/name)`);
+        }
+        const pollSeconds = Number(ctx.config.pollSeconds ?? 60);
+        this.pollMs = Math.max(15, pollSeconds) * 1000;
+        this.api = new HttpJson({
+            connector: this.id,
+            baseUrl: "https://api.github.com",
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+                "user-agent": "exempclaw",
+            },
+            fetchImpl: this.fetchImpl,
+        });
+        const me = await this.api.get("/user");
+        this.selfLogin = me.login;
+        this.log.info("github connected", { as: me.login, repos: this.repos.join(",") || "none" });
+    }
+    resolveRepo(repo) {
+        const resolved = repo ?? this.repos[0];
+        if (!resolved) {
+            throw new ConnectorError(this.id, "no repo given and GITHUB_REPOS is not configured");
+        }
+        if (!REPO_RE.test(resolved))
+            throw new ConnectorError(this.id, `invalid repo "${resolved}" (use owner/name)`);
+        return resolved;
+    }
+    tools() {
+        const listIssues = defineTool({
+            name: "github_list_issues",
+            description: "List recent issues in a repository, most recently updated first.",
+            schema: z.object({
+                repo: z.string().optional().describe("owner/name; defaults to the first configured repo."),
+                state: z.enum(["open", "closed", "all"]).default("open"),
+                limit: z.number().int().min(1).max(50).default(20),
+                includePullRequests: z.boolean().default(false),
+            }),
+            execute: async (input, ctx) => {
+                const repo = this.resolveRepo(input.repo);
+                const issues = await this.api.get(`/repos/${repo}/issues`, {
+                    query: { state: input.state, sort: "updated", direction: "desc", per_page: input.limit },
+                    signal: ctx.signal,
+                });
+                const filtered = issues.filter((i) => input.includePullRequests || !i.pull_request);
+                if (filtered.length === 0)
+                    return { content: `No ${input.state} issues in ${repo}.` };
+                return {
+                    content: filtered
+                        .map((i) => `#${i.number} [${i.state}]${i.pull_request ? " [PR]" : ""} ${i.title} (by ${i.user?.login ?? "?"}, updated ${i.updated_at})${renderLabels(i)}`)
+                        .join("\n"),
+                };
+            },
+        });
+        const readIssue = defineTool({
+            name: "github_read_issue",
+            description: "Read one issue or pull request, including its recent comments.",
+            schema: z.object({
+                repo: z.string().optional(),
+                number: z.number().int().min(1),
+            }),
+            execute: async (input, ctx) => {
+                const repo = this.resolveRepo(input.repo);
+                const issue = await this.api.get(`/repos/${repo}/issues/${input.number}`, {
+                    signal: ctx.signal,
+                });
+                const comments = await this.api.get(`/repos/${repo}/issues/${input.number}/comments`, {
+                    query: { per_page: 30 },
+                    signal: ctx.signal,
+                });
+                const lines = [
+                    `#${issue.number} [${issue.state}] ${issue.title}`,
+                    `by ${issue.user?.login ?? "?"} · created ${issue.created_at} · updated ${issue.updated_at}${renderLabels(issue)}`,
+                    issue.html_url,
+                    "",
+                    truncate(issue.body ?? "(no description)", 4000),
+                ];
+                if (comments.length > 0) {
+                    lines.push("", `--- comments (${comments.length}) ---`);
+                    for (const c of comments) {
+                        lines.push(`[${c.created_at}] ${c.user?.login ?? "?"}: ${truncate(c.body ?? "", 1500)}`);
+                    }
+                }
+                return { content: lines.join("\n") };
+            },
+        });
+        const comment = defineTool({
+            name: "github_comment",
+            description: "Comment on an issue or pull request. Acts outward; requires approval.",
+            outward: true,
+            schema: z.object({
+                repo: z.string().optional(),
+                number: z.number().int().min(1),
+                body: z.string().min(1),
+            }),
+            execute: async (input, ctx) => {
+                const repo = this.resolveRepo(input.repo);
+                const res = await this.api.post(`/repos/${repo}/issues/${input.number}/comments`, {
+                    body: { body: input.body },
+                    signal: ctx.signal,
+                });
+                this.recordSelfAction(repo, input.number);
+                return { content: `Commented on ${repo}#${input.number}: ${res.html_url}` };
+            },
+        });
+        const updateIssue = defineTool({
+            name: "github_update_issue",
+            description: "Close or reopen an issue, and/or add labels to it. Acts outward; requires approval.",
+            outward: true,
+            schema: z
+                .object({
+                repo: z.string().optional(),
+                number: z.number().int().min(1),
+                state: z.enum(["open", "closed"]).optional(),
+                addLabels: z.array(z.string()).default([]),
+            })
+                .refine((v) => v.state !== undefined || v.addLabels.length > 0, {
+                message: "give a state and/or labels to add",
+            }),
+            execute: async (input, ctx) => {
+                const repo = this.resolveRepo(input.repo);
+                const did = [];
+                if (input.state) {
+                    await this.api.patch(`/repos/${repo}/issues/${input.number}`, {
+                        body: { state: input.state },
+                        signal: ctx.signal,
+                    });
+                    did.push(input.state === "closed" ? "closed" : "reopened");
+                }
+                if (input.addLabels.length > 0) {
+                    await this.api.post(`/repos/${repo}/issues/${input.number}/labels`, {
+                        body: { labels: input.addLabels },
+                        signal: ctx.signal,
+                    });
+                    did.push(`labeled [${input.addLabels.join(", ")}]`);
+                }
+                this.recordSelfAction(repo, input.number);
+                return { content: `${repo}#${input.number}: ${did.join(", ")}.` };
+            },
+        });
+        const createIssue = defineTool({
+            name: "github_create_issue",
+            description: "Open a new issue. Acts outward; requires approval.",
+            outward: true,
+            schema: z.object({
+                repo: z.string().optional(),
+                title: z.string().min(1),
+                body: z.string().default(""),
+                labels: z.array(z.string()).default([]),
+            }),
+            execute: async (input, ctx) => {
+                const repo = this.resolveRepo(input.repo);
+                const res = await this.api.post(`/repos/${repo}/issues`, {
+                    body: { title: input.title, body: input.body, ...(input.labels.length ? { labels: input.labels } : {}) },
+                    signal: ctx.signal,
+                });
+                this.recordSelfAction(repo, res.number);
+                return { content: `Created ${repo}#${res.number}: ${res.html_url}` };
+            },
+        });
+        return [listIssues, readIssue, comment, updateIssue, createIssue];
+    }
+    /** Polls configured repos for updated issues and surfaces them as events. */
+    async listen(onEvent, signal) {
+        if (this.repos.length === 0) {
+            this.log.warn("GITHUB_REPOS not set — github inbound events disabled (tools still work)");
+            return;
+        }
+        // Start from "now": don't replay the backlog on every restart.
+        let since = new Date().toISOString();
+        this.log.info("github polling started", { repos: this.repos.join(","), everyMs: this.pollMs });
+        while (!signal.aborted) {
+            await sleep(this.pollMs, signal);
+            if (signal.aborted)
+                break;
+            const cycleStart = new Date().toISOString();
+            for (const repo of this.repos) {
+                try {
+                    const issues = await this.api.get(`/repos/${repo}/issues`, {
+                        query: { state: "all", sort: "updated", direction: "desc", per_page: 20, since },
+                        signal,
+                    });
+                    for (const issue of issues) {
+                        const event = this.issueToInbound(repo, issue, since);
+                        if (event)
+                            onEvent(event);
+                    }
+                }
+                catch (err) {
+                    if (signal.aborted)
+                        break;
+                    this.log.warn("github poll failed", { repo, error: err.message });
+                }
+            }
+            since = cycleStart;
+        }
+    }
+    /** Maps an updated issue to an InboundEvent, suppressing our own echoes. */
+    issueToInbound(repo, issue, since) {
+        if (this.isRecentSelfAction(repo, issue.number))
+            return null;
+        const isNew = issue.created_at >= since;
+        if (isNew && issue.user?.login === this.selfLogin)
+            return null;
+        return {
+            connector: this.id,
+            type: isNew ? "github.issue_opened" : "github.issue_updated",
+            eventId: `${repo}#${issue.number}@${issue.updated_at}`,
+            threadId: `${repo}#${issue.number}`,
+            summary: [
+                `${isNew ? "New" : "Updated"} ${issue.pull_request ? "pull request" : "issue"} ${repo}#${issue.number}: ${issue.title}`,
+                `state=${issue.state} author=${issue.user?.login ?? "?"} updated=${issue.updated_at}`,
+                `Read it with github_read_issue (repo="${repo}", number=${issue.number}) before deciding whether to act.`,
+                isNew && issue.body ? `\n${truncate(issue.body, 1500)}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n"),
+            payload: issue,
+            receivedAt: new Date().toISOString(),
+        };
+    }
+    recordSelfAction(repo, number) {
+        this.selfActions.set(`${repo}#${number}`, Date.now());
+    }
+    /** True if the agent itself just wrote to this issue (poll echo window). */
+    isRecentSelfAction(repo, number, now = Date.now()) {
+        const at = this.selfActions.get(`${repo}#${number}`);
+        return at !== undefined && now - at < 2 * this.pollMs;
+    }
+}
+function renderLabels(issue) {
+    const names = (issue.labels ?? [])
+        .map((l) => (typeof l === "string" ? l : (l.name ?? "")))
+        .filter(Boolean);
+    return names.length ? ` [${names.join(", ")}]` : "";
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+//# sourceMappingURL=github-connector.js.map

package/dist/connectors/github/github-connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-connector.js","sourceRoot":"","sources":["../../../src/connectors/github/github-connector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAA4D,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAkB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAa,MAAM,qBAAqB,CAAC;AAiC5D,MAAM,OAAO,GAAG,oBAAoB,CAAC;AAErC,MAAM,OAAO,eAAe;IAUG;IATpB,EAAE,GAAG,QAAQ,CAAC;IACf,GAAG,CAAU;IACb,GAAG,CAAY;IACf,SAAS,GAAG,EAAE,CAAC;IACf,KAAK,GAAa,EAAE,CAAC;IACrB,MAAM,GAAG,MAAM,CAAC;IACxB,kFAAkF;IACjE,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzD,YAA6B,SAAqB;QAArB,cAAS,GAAT,SAAS,CAAY;IAAG,CAAC;IAEtD,KAAK,CAAC,IAAI,CAAC,GAAqB;QAC9B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACrE,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;QAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,gEAAgE,CAAC,CAAC;QACtG,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;aAClC,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC,CAAC;QACnB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,kCAAkC,IAAI,oBAAoB,CAAC,CAAC;QACzH,CAAC;QACD,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;QAE/C,IAAI,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC;YACtB,SAAS,EAAE,IAAI,CAAC,EAAE;YAClB,OAAO,EAAE,wBAAwB;YACjC,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,MAAM,EAAE,6BAA6B;gBACrC,sBAAsB,EAAE,YAAY;gBACpC,YAAY,EAAE,WAAW;aAC1B;YACD,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC;QAEH,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAoB,OAAO,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;IAC7F,CAAC;IAEO,WAAW,CAAC,IAAa;QAC/B,MAAM,QAAQ,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,kDAAkD,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,iBAAiB,QAAQ,oBAAoB,CAAC,CAAC;QAC9G,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK;QACH,MAAM,UAAU,GAAG,UAAU,CAAC;YAC5B,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EAAE,kEAAkE;YAC/E,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;gBACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;gBAC1F,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;gBACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;gBAClD,mBAAmB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;aAChD,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAgB,UAAU,IAAI,SAAS,EAAE;oBACxE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE;oBACxF,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;gBACpF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC,KAAK,cAAc,IAAI,GAAG,EAAE,CAAC;gBACtF,OAAO;oBACL,OAAO,EAAE,QAAQ;yBACd,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI,GAAG,aAAa,CAAC,CAAC,UAAU,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CACjJ;yBACA,IAAI,CAAC,IAAI,CAAC;iBACd,CAAC;YACJ,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,UAAU,CAAC;YAC3B,IAAI,EAAE,mBAAmB;YACzB,WAAW,EAAE,gEAAgE;YAC7E,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;gBACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;aAChC,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAc,UAAU,IAAI,WAAW,KAAK,CAAC,MAAM,EAAE,EAAE;oBACrF,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAkB,UAAU,IAAI,WAAW,KAAK,CAAC,MAAM,WAAW,EAAE;oBACrG,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;oBACvB,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAC;gBACH,MAAM,KAAK,GAAG;oBACZ,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,EAAE;oBAClD,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,GAAG,cAAc,KAAK,CAAC,UAAU,cAAc,KAAK,CAAC,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,EAAE;oBAClH,KAAK,CAAC,QAAQ;oBACd,EAAE;oBACF,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,kBAAkB,EAAE,IAAI,CAAC;iBACjD,CAAC;gBACF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,iBAAiB,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC;oBACxD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;wBACzB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;oBAC3F,CAAC;gBACH,CAAC;gBACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,UAAU,CAAC;YACzB,IAAI,EAAE,gBAAgB;YACtB,WAAW,EAAE,uEAAuE;YACpF,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;gBACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;aACxB,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAuB,UAAU,IAAI,WAAW,KAAK,CAAC,MAAM,WAAW,EAAE;oBACtG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;oBAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAC;gBACH,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC1C,OAAO,EAAE,OAAO,EAAE,gBAAgB,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC9E,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG,UAAU,CAAC;YAC7B,IAAI,EAAE,qBAAqB;YAC3B,WAAW,EAAE,qFAAqF;YAClG,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,CAAC;iBACN,MAAM,CAAC;gBACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC/B,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE;gBAC5C,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;aAC3C,CAAC;iBACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE;gBAC9D,OAAO,EAAE,mCAAmC;aAC7C,CAAC;YACJ,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;gBACzB,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;oBAChB,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,WAAW,KAAK,CAAC,MAAM,EAAE,EAAE;wBAC5D,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;wBAC5B,MAAM,EAAE,GAAG,CAAC,MAAM;qBACnB,CAAC,CAAC;oBACH,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;gBAC7D,CAAC;gBACD,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC/B,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,WAAW,KAAK,CAAC,MAAM,SAAS,EAAE;wBAClE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE;wBACjC,MAAM,EAAE,GAAG,CAAC,MAAM;qBACnB,CAAC,CAAC;oBACH,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACtD,CAAC;gBACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC1C,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACpE,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG,UAAU,CAAC;YAC7B,IAAI,EAAE,qBAAqB;YAC3B,WAAW,EAAE,oDAAoD;YACjE,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;gBACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;gBACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;aACxC,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAuC,UAAU,IAAI,SAAS,EAAE;oBAC7F,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;oBACxG,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAC;gBACH,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;gBACxC,OAAO,EAAE,OAAO,EAAE,WAAW,IAAI,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;YACvE,CAAC;SACF,CAAC,CAAC;QAEH,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,MAAM,CAAC,OAAsC,EAAE,MAAmB;QACtE,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC;YAC1F,OAAO;QACT,CAAC;QACD,+DAA+D;QAC/D,IAAI,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAE/F,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACjC,IAAI,MAAM,CAAC,OAAO;gBAAE,MAAM;YAC1B,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC5C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC9B,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAgB,UAAU,IAAI,SAAS,EAAE;wBACxE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE;wBAChF,MAAM;qBACP,CAAC,CAAC;oBACH,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;wBAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;wBACtD,IAAI,KAAK;4BAAE,OAAO,CAAC,KAAK,CAAC,CAAC;oBAC5B,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,MAAM,CAAC,OAAO;wBAAE,MAAM;oBAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC/E,CAAC;YACH,CAAC;YACD,KAAK,GAAG,UAAU,CAAC;QACrB,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,cAAc,CAAC,IAAY,EAAE,KAAkB,EAAE,KAAa;QAC5D,IAAI,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC;QACxC,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC/D,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,EAAE;YAClB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,sBAAsB;YAC5D,OAAO,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE;YACtD,QAAQ,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE;YACnC,OAAO,EAAE;gBACP,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,KAAK,EAAE;gBACvH,SAAS,KAAK,CAAC,KAAK,WAAW,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,GAAG,YAAY,KAAK,CAAC,UAAU,EAAE;gBACrF,yCAAyC,IAAI,aAAa,KAAK,CAAC,MAAM,mCAAmC;gBACzG,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;aAC7D;iBACE,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,IAAI,CAAC;YACb,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACrC,CAAC;IACJ,CAAC;IAEO,gBAAgB,CAAC,IAAY,EAAE,MAAc;QACnD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,4EAA4E;IAC5E,kBAAkB,CAAC,IAAY,EAAE,MAAc,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC/D,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC;QACrD,OAAO,EAAE,KAAK,SAAS,IAAI,GAAG,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACxD,CAAC;CACF;AAED,SAAS,YAAY,CAAC,KAAkB;IACtC,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;SAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;SACxD,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,GAAW;IACzC,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC"}

package/dist/connectors/http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal JSON-over-HTTPS client shared by the fetch-based connectors
+ * (Slack, GitHub, Notion). Handles timeouts, 429/5xx retries with
+ * Retry-After, and maps failures to ConnectorError. The fetch implementation
+ * is injectable so connector logic is unit-testable without a network.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface HttpJsonOptions {
+    connector: string;
+    baseUrl: string;
+    headers?: Record<string, string>;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    /** Max retries on 429/5xx. Default 2. */
+    maxRetries?: number;
+}
+export interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export declare class HttpJson {
+    private readonly opts;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(opts: HttpJsonOptions);
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private buildUrl;
+}

package/dist/connectors/http.js

@@ -0,0 +1,78 @@
+import { ConnectorError } from "../core/errors.js";
+import { sleep } from "./connector.js";
+export class HttpJson {
+    opts;
+    fetchImpl;
+    timeoutMs;
+    maxRetries;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetchImpl = opts.fetchImpl ?? ((input, init) => fetch(input, init));
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+    }
+    get(path, options = {}) {
+        return this.request("GET", path, options);
+    }
+    post(path, options = {}) {
+        return this.request("POST", path, options);
+    }
+    patch(path, options = {}) {
+        return this.request("PATCH", path, options);
+    }
+    async request(method, path, options = {}) {
+        const url = this.buildUrl(path, options.query);
+        for (let attempt = 0;; attempt++) {
+            const signal = options.signal
+                ? AbortSignal.any([options.signal, AbortSignal.timeout(this.timeoutMs)])
+                : AbortSignal.timeout(this.timeoutMs);
+            let response;
+            try {
+                response = await this.fetchImpl(url, {
+                    method,
+                    headers: {
+                        accept: "application/json",
+                        ...(options.body !== undefined ? { "content-type": "application/json" } : {}),
+                        ...this.opts.headers,
+                        ...options.headers,
+                    },
+                    ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+                    signal,
+                });
+            }
+            catch (err) {
+                if (options.signal?.aborted)
+                    throw err;
+                throw new ConnectorError(this.opts.connector, `request to ${path} failed: ${err.message}`, {
+                    retryable: true,
+                    cause: err,
+                });
+            }
+            if (response.ok) {
+                const text = await response.text();
+                return (text ? JSON.parse(text) : undefined);
+            }
+            const retryable = response.status === 429 || response.status >= 500;
+            if (retryable && attempt < this.maxRetries) {
+                const retryAfter = Number(response.headers.get("retry-after"));
+                const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
+                await sleep(delayMs, options.signal);
+                if (options.signal?.aborted) {
+                    throw new ConnectorError(this.opts.connector, `request to ${path} aborted`, { retryable: false });
+                }
+                continue;
+            }
+            const detail = (await response.text().catch(() => "")).slice(0, 300);
+            throw new ConnectorError(this.opts.connector, `${method} ${path} → HTTP ${response.status}${detail ? `: ${detail}` : ""}`, { retryable });
+        }
+    }
+    buildUrl(path, query) {
+        const url = new URL(path.startsWith("http") ? path : `${this.opts.baseUrl}${path}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/connectors/http.js.map

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

package/dist/connectors/index.d.ts

@@ -0,0 +1,34 @@
+import type { Connector } from "./connector.js";
+export type { Connector, ConnectorContext, InboundEvent } from "./connector.js";
+export { renderEventInput } from "./connector.js";
+export interface ConnectorEnvKey {
+    /** Config field name handed to the connector. */
+    field: string;
+    /** Environment variable it is read from. */
+    env: string;
+    required: boolean;
+    note?: string;
+}
+export declare function availableConnectorIds(): string[];
+/** Registers a plugin-provided connector. Throws on id collision. */
+export declare function registerConnector(entry: {
+    id: string;
+    description: string;
+    envKeys: ConnectorEnvKey[];
+    make: () => Connector;
+}): void;
+export interface ConnectorStatus {
+    id: string;
+    description: string;
+    envKeys: Array<ConnectorEnvKey & {
+        set: boolean;
+    }>;
+    configured: boolean;
+}
+/** Reports each connector's env-var status for `exempclaw connectors`/`doctor`. */
+export declare function connectorStatuses(env?: NodeJS.ProcessEnv): ConnectorStatus[];
+/** Instantiates a connector by id and resolves its config from the environment. */
+export declare function createConnector(id: string, env?: NodeJS.ProcessEnv): {
+    connector: Connector;
+    config: Record<string, string>;
+};

package/dist/connectors/index.js

@@ -0,0 +1,86 @@
+import { EmailConnector } from "./email/email-connector.js";
+import { SlackConnector } from "./slack/slack-connector.js";
+import { NotionConnector } from "./notion/notion-connector.js";
+import { GitHubConnector } from "./github/github-connector.js";
+import { DemoConnector } from "../demo/demo-connector.js";
+export { renderEventInput } from "./connector.js";
+/** Maps a connector id to its constructor and the env vars it consumes. */
+const REGISTRY = {
+    email: {
+        make: () => new EmailConnector(),
+        description: "IMAP inbox (read + live events) and SMTP send.",
+        envKeys: [
+            { field: "user", env: "EMAIL_USER", required: true },
+            { field: "password", env: "EMAIL_PASSWORD", required: true, note: "app password for Gmail/Workspace" },
+            { field: "imapHost", env: "EMAIL_IMAP_HOST", required: false, note: "needed for reading + events" },
+            { field: "imapPort", env: "EMAIL_IMAP_PORT", required: false },
+            { field: "smtpHost", env: "EMAIL_SMTP_HOST", required: false, note: "needed for sending" },
+            { field: "smtpPort", env: "EMAIL_SMTP_PORT", required: false },
+            { field: "from", env: "EMAIL_FROM", required: false, note: "defaults to EMAIL_USER" },
+        ],
+    },
+    slack: {
+        make: () => new SlackConnector(),
+        description: "Slack Web API tools + Socket Mode mentions/DMs.",
+        envKeys: [
+            { field: "botToken", env: "SLACK_BOT_TOKEN", required: true, note: "xoxb-… bot token" },
+            { field: "appToken", env: "SLACK_APP_TOKEN", required: false, note: "xapp-… enables inbound events" },
+        ],
+    },
+    notion: {
+        make: () => new NotionConnector(),
+        description: "Notion search/read/write (share pages with the integration).",
+        envKeys: [{ field: "token", env: "NOTION_TOKEN", required: true, note: "internal integration secret" }],
+    },
+    github: {
+        make: () => new GitHubConnector(),
+        description: "GitHub issues/PRs; polls GITHUB_REPOS for inbound events.",
+        envKeys: [
+            { field: "token", env: "GITHUB_TOKEN", required: true, note: "fine-grained PAT, Issues read/write" },
+            { field: "repos", env: "GITHUB_REPOS", required: false, note: "comma-separated owner/name list" },
+            { field: "pollSeconds", env: "GITHUB_POLL_SECONDS", required: false, note: "default 60" },
+        ],
+    },
+    demo: {
+        make: () => new DemoConnector(),
+        description: "Fictional email+Slack workspace for demo mode and sandboxing. No credentials.",
+        envKeys: [],
+    },
+};
+export function availableConnectorIds() {
+    return Object.keys(REGISTRY);
+}
+/** Registers a plugin-provided connector. Throws on id collision. */
+export function registerConnector(entry) {
+    if (REGISTRY[entry.id]) {
+        throw new Error(`connector "${entry.id}" already registered`);
+    }
+    REGISTRY[entry.id] = { make: entry.make, envKeys: entry.envKeys, description: entry.description };
+}
+/** Reports each connector's env-var status for `exempclaw connectors`/`doctor`. */
+export function connectorStatuses(env = process.env) {
+    return Object.entries(REGISTRY).map(([id, entry]) => {
+        const envKeys = entry.envKeys.map((key) => ({ ...key, set: Boolean(env[key.env]) }));
+        return {
+            id,
+            description: entry.description,
+            envKeys,
+            configured: envKeys.filter((k) => k.required).every((k) => k.set),
+        };
+    });
+}
+/** Instantiates a connector by id and resolves its config from the environment. */
+export function createConnector(id, env = process.env) {
+    const entry = REGISTRY[id];
+    if (!entry) {
+        throw new Error(`unknown connector "${id}". Available: ${availableConnectorIds().join(", ")}`);
+    }
+    const config = {};
+    for (const key of entry.envKeys) {
+        const value = env[key.env];
+        if (value)
+            config[key.field] = value;
+    }
+    return { connector: entry.make(), config };
+}
+//# sourceMappingURL=index.js.map

package/dist/connectors/index.js.map

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

package/dist/connectors/notion/notion-connector.d.ts

@@ -0,0 +1,45 @@
+import type { Connector, ConnectorContext } from "../connector.js";
+import { type FetchLike } from "../http.js";
+import { type Tool } from "../../tools/tool.js";
+interface RichText {
+    plain_text?: string;
+}
+interface NotionBlock {
+    id: string;
+    type: string;
+    has_children?: boolean;
+    [key: string]: unknown;
+}
+interface SearchResult {
+    id: string;
+    object: "page" | "database";
+    last_edited_time?: string;
+    url?: string;
+    properties?: Record<string, {
+        type?: string;
+        title?: RichText[];
+    }>;
+    title?: RichText[];
+}
+export declare class NotionConnector implements Connector {
+    private readonly fetchImpl?;
+    readonly id = "notion";
+    private log;
+    private api;
+    constructor(fetchImpl?: FetchLike | undefined);
+    init(ctx: ConnectorContext): Promise<void>;
+    tools(): Tool[];
+}
+/** Accepts dashed/undashed UUIDs or a Notion URL; returns a dashed UUID. */
+export declare function normalizePageId(input: string): string | null;
+export declare function resultTitle(result: SearchResult): string;
+/** Renders one block to a plain-text line. Unknown types become markers. */
+export declare function renderBlock(block: NotionBlock): string;
+interface ParagraphBlock {
+    object: "block";
+    type: string;
+    [key: string]: unknown;
+}
+/** Converts simple markdown into Notion block objects. */
+export declare function markdownToBlocks(markdown: string): ParagraphBlock[];
+export {};