@a5c-ai/tasks-mux 5.0.1-staging.a2e883985f51

package/dist/backends/git-native.js

@@ -0,0 +1,324 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { generateBreakpointId, DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS, BREAKPOINTS_DIR, BreakpointSchema, BreakpointPublicAnswerSchema, ProvenBreakpointAnswerSchema, isProvenBreakpointAnswer, } from "../types.js";
+import { signAnswer, signAnswerWithKeyRecord } from "../proven/sign.js";
+import { verifyAnswer as verifyProvenAnswer } from "../proven/verify.js";
+import { selectBreakpointAnswer as selectPublicBreakpointAnswer } from "../backend.js";
+export class GitNativeBackend {
+    name = "git-native";
+    breakpointsDir;
+    defaultPollIntervalMs;
+    defaultTimeoutMs;
+    signingKeyPath;
+    constructor(options) {
+        this.breakpointsDir = options?.breakpointsDir
+            ?? path.resolve(process.cwd(), BREAKPOINTS_DIR);
+        this.defaultPollIntervalMs = options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.defaultTimeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.signingKeyPath = options?.signingKeyPath;
+    }
+    breakpointPath(id) {
+        return path.join(this.breakpointsDir, `${id}.json`);
+    }
+    answerPath(id) {
+        return path.join(this.breakpointsDir, `${id}.answer.json`);
+    }
+    provenPath(id) {
+        return path.join(this.breakpointsDir, `${id}.proven.json`);
+    }
+    /**
+     * Load the signing key from the configured signingKeyPath.
+     * Returns null if no signing key is configured or the file cannot be read.
+     */
+    async loadSigningKey() {
+        if (!this.signingKeyPath)
+            return null;
+        try {
+            const raw = await fs.readFile(this.signingKeyPath, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Load a proven answer file for a breakpoint, if it exists.
+     */
+    async loadProvenAnswer(id) {
+        try {
+            const raw = await fs.readFile(this.provenPath(id), "utf-8");
+            return ProvenBreakpointAnswerSchema.parse(JSON.parse(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+    async loadStoredAnswer(id) {
+        try {
+            const raw = await fs.readFile(this.answerPath(id), "utf-8");
+            return BreakpointPublicAnswerSchema.parse(JSON.parse(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+    async loadPublicAnswer(id) {
+        const [storedAnswer, provenAnswer] = await Promise.all([
+            this.loadStoredAnswer(id),
+            this.loadProvenAnswer(id),
+        ]);
+        return provenAnswer ?? storedAnswer;
+    }
+    async submitBreakpoint(params) {
+        await fs.mkdir(this.breakpointsDir, { recursive: true });
+        const id = generateBreakpointId();
+        const now = new Date().toISOString();
+        const timeoutMs = params.routing.timeoutMs || this.defaultTimeoutMs;
+        const breakpoint = {
+            id,
+            text: params.text,
+            context: params.context,
+            status: "pending",
+            routing: params.routing,
+            answers: [],
+            projectId: params.projectId,
+            repoId: params.repoId,
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: new Date(Date.now() + timeoutMs).toISOString(),
+        };
+        // Validate before writing
+        BreakpointSchema.parse(breakpoint);
+        await fs.writeFile(this.breakpointPath(id), JSON.stringify(breakpoint, null, 2) + "\n", "utf-8");
+        return breakpoint;
+    }
+    async getBreakpoint(id) {
+        const raw = await fs.readFile(this.breakpointPath(id), "utf-8");
+        const breakpoint = BreakpointSchema.parse(JSON.parse(raw));
+        const answer = await this.loadPublicAnswer(id);
+        if (answer) {
+            const existingIndex = breakpoint.answers.findIndex((candidate) => candidate.id === answer.id);
+            if (existingIndex === -1) {
+                breakpoint.answers.push(answer);
+            }
+            else {
+                breakpoint.answers[existingIndex] = answer;
+            }
+            if (breakpoint.status === "pending" || breakpoint.status === "claimed") {
+                breakpoint.status = "answered";
+            }
+        }
+        const selectedAnswer = selectPublicBreakpointAnswer(breakpoint);
+        if (selectedAnswer && isProvenBreakpointAnswer(selectedAnswer)) {
+            const verification = await this.verifyProvenFile(selectedAnswer);
+            // Attach verification result as metadata on the breakpoint
+            breakpoint
+                .provenVerification = verification;
+        }
+        return breakpoint;
+    }
+    async waitForAnswer(id, options) {
+        const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+        const pollIntervalMs = options?.pollIntervalMs ?? this.defaultPollIntervalMs;
+        const signal = options?.signal;
+        const startTime = Date.now();
+        while (true) {
+            if (signal?.aborted) {
+                const breakpoint = await this.getBreakpoint(id);
+                return {
+                    answered: false,
+                    breakpoint,
+                    allAnswers: breakpoint.answers,
+                    resolution: "aborted",
+                    elapsedMs: Date.now() - startTime,
+                };
+            }
+            // Check for answer file
+            try {
+                await fs.access(this.answerPath(id));
+                const breakpoint = await this.getBreakpoint(id);
+                const answer = selectPublicBreakpointAnswer(breakpoint);
+                return {
+                    answered: true,
+                    breakpoint: { ...breakpoint, status: "answered" },
+                    answer,
+                    allAnswers: breakpoint.answers,
+                    resolution: "answered",
+                    elapsedMs: Date.now() - startTime,
+                };
+            }
+            catch {
+                // No answer yet
+            }
+            // Check cancellation status
+            const breakpoint = await this.getBreakpoint(id);
+            if (breakpoint.status === "cancelled") {
+                return {
+                    answered: false,
+                    breakpoint,
+                    allAnswers: breakpoint.answers,
+                    resolution: "cancelled",
+                    elapsedMs: Date.now() - startTime,
+                };
+            }
+            if (Date.now() - startTime >= timeoutMs) {
+                return {
+                    answered: false,
+                    breakpoint,
+                    allAnswers: breakpoint.answers,
+                    resolution: "timeout",
+                    elapsedMs: Date.now() - startTime,
+                };
+            }
+            // Wait before next poll
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, pollIntervalMs);
+                if (signal) {
+                    const onAbort = () => {
+                        clearTimeout(timer);
+                        resolve();
+                    };
+                    signal.addEventListener("abort", onAbort, { once: true });
+                }
+            });
+        }
+    }
+    async listPendingBreakpoints(responderId) {
+        let files;
+        try {
+            files = await fs.readdir(this.breakpointsDir);
+        }
+        catch {
+            return [];
+        }
+        const pending = [];
+        for (const file of files) {
+            if (!file.endsWith(".json") || file.includes(".answer.") || file.includes(".proven.")) {
+                continue;
+            }
+            try {
+                const raw = await fs.readFile(path.join(this.breakpointsDir, file), "utf-8");
+                const bp = BreakpointSchema.parse(JSON.parse(raw));
+                if (bp.status !== "pending" && bp.status !== "routed")
+                    continue;
+                // Check expiration
+                if (new Date(bp.expiresAt) < new Date())
+                    continue;
+                // Filter by responder if specified
+                if (responderId && bp.routing.targetResponders.length > 0) {
+                    if (!bp.routing.targetResponders.includes(responderId))
+                        continue;
+                }
+                // Check if answer already exists
+                try {
+                    await fs.access(this.answerPath(bp.id));
+                    continue; // Already answered
+                }
+                catch {
+                    // No answer, include it
+                }
+                pending.push(bp);
+            }
+            catch {
+                // Skip malformed files
+            }
+        }
+        return pending;
+    }
+    async answerBreakpoint(id, answer) {
+        // Verify breakpoint exists
+        await this.getBreakpoint(id);
+        const answerId = generateBreakpointId();
+        const now = new Date().toISOString();
+        const breakpointAnswer = {
+            id: answerId,
+            breakpointId: id,
+            responderId: answer.responderId,
+            responderName: answer.responderName,
+            text: answer.text,
+            approved: answer.approved,
+            confidence: answer.confidence ?? 80,
+            references: answer.references ?? [],
+            followUpQuestions: answer.followUpQuestions ?? [],
+            answeredAt: now,
+            decisionMemory: answer.decisionMemory
+                ? { ...answer.decisionMemory, savedAt: now }
+                : undefined,
+        };
+        if (answer.sign === false && answer.keyFingerprint) {
+            throw new Error("keyFingerprint cannot be used when sign=false");
+        }
+        let publicAnswer = breakpointAnswer;
+        if (answer.keyFingerprint) {
+            publicAnswer = await signAnswer(breakpointAnswer, answer.keyFingerprint, this.breakpointsDir);
+        }
+        else if (answer.sign === true) {
+            const signingKey = await this.loadSigningKey();
+            if (!signingKey) {
+                throw new Error("answer_breakpoint.sign requested, but no signing key is configured");
+            }
+            publicAnswer = signAnswerWithKeyRecord(breakpointAnswer, signingKey);
+        }
+        else if (answer.sign !== false) {
+            const signingKey = await this.loadSigningKey();
+            if (signingKey) {
+                publicAnswer = signAnswerWithKeyRecord(breakpointAnswer, signingKey);
+            }
+        }
+        BreakpointPublicAnswerSchema.parse(publicAnswer);
+        await fs.writeFile(this.answerPath(id), JSON.stringify(publicAnswer, null, 2) + "\n", "utf-8");
+        if (isProvenBreakpointAnswer(publicAnswer)) {
+            await fs.writeFile(this.provenPath(id), JSON.stringify(publicAnswer, null, 2) + "\n", "utf-8");
+        }
+        else {
+            await fs.rm(this.provenPath(id), { force: true });
+        }
+        // Update the breakpoint status
+        const breakpoint = await this.getBreakpoint(id);
+        delete breakpoint.provenVerification;
+        breakpoint.status = "answered";
+        breakpoint.updatedAt = now;
+        await fs.writeFile(this.breakpointPath(id), JSON.stringify(breakpoint, null, 2) + "\n", "utf-8");
+        return publicAnswer;
+    }
+    async cancelBreakpoint(id) {
+        const breakpoint = await this.getBreakpoint(id);
+        delete breakpoint.provenVerification;
+        breakpoint.status = "cancelled";
+        breakpoint.updatedAt = new Date().toISOString();
+        await fs.writeFile(this.breakpointPath(id), JSON.stringify(breakpoint, null, 2) + "\n", "utf-8");
+    }
+    async claimBreakpoint(id, responderId) {
+        const breakpoint = await this.getBreakpoint(id);
+        delete breakpoint.provenVerification;
+        breakpoint.status = "claimed";
+        breakpoint.claimedByResponderId = responderId;
+        breakpoint.updatedAt = new Date().toISOString();
+        await fs.writeFile(this.breakpointPath(id), JSON.stringify(breakpoint, null, 2) + "\n", "utf-8");
+        return breakpoint;
+    }
+    /**
+     * Verify the selected public answer against trusted public keys.
+     */
+    async verifyAnswer(id) {
+        const breakpoint = await this.getBreakpoint(id);
+        const answer = selectPublicBreakpointAnswer(breakpoint);
+        if (!answer || !isProvenBreakpointAnswer(answer)) {
+            return {
+                valid: false,
+                reason: "No signed answer found",
+                verifiedAt: new Date().toISOString(),
+            };
+        }
+        return this.verifyProvenFile(answer);
+    }
+    /**
+     * Verify a loaded ProvenBreakpointAnswer against trusted keys in the
+     * breakpoints directory.
+     */
+    async verifyProvenFile(provenAnswer) {
+        // The proven/verify module's loadTrustedPublicKeys uses baseDir/.keys/trusted/
+        // Our breakpointsDir IS the .breakpoints directory, so we pass it as baseDir.
+        return verifyProvenAnswer(provenAnswer, this.breakpointsDir);
+    }
+}

package/dist/backends/github-issues.d.ts

@@ -0,0 +1,77 @@
+import type { BreakpointBackend, SubmitBreakpointParams, WaitForAnswerOptions, SubmitAnswerParams, ListRespondersParams } from "../backend.js";
+import type { Breakpoint, BreakpointAnswer, BreakpointWaitResult, ResponderProfile, GitHubIssuesBackendConfig } from "../types.js";
+interface ParsedAnswer {
+    text: string;
+    confidence?: number;
+    references?: string[];
+    responderId?: string;
+    responderName?: string;
+    breakpointId?: string;
+    answeredAt?: string;
+}
+/**
+ * Resolve a GitHub token by trying `gh auth token` first,
+ * then falling back to the GITHUB_TOKEN environment variable.
+ */
+export declare function getGitHubToken(): string;
+/**
+ * Parse an answer from a GitHub issue comment body.
+ * Looks for a hidden JSON payload block, a "## Answer" heading anywhere
+ * in the body, a JSON code block with an "answer" field, or a sufficiently
+ * long plain-text comment (for assigned responders handled upstream).
+ */
+export declare function parseAnswerFromComment(body: string, options?: {
+    isAssignedResponder?: boolean;
+}): ParsedAnswer | null;
+/**
+ * BreakpointBackend implementation backed by GitHub Issues.
+ *
+ * Each breakpoint maps to a GitHub issue; answers are detected
+ * from issue comments containing payload blocks, "## Answer" markers, or JSON blocks.
+ */
+export declare class GitHubIssuesBackend implements BreakpointBackend {
+    readonly name = "github-issues";
+    private owner;
+    private repo;
+    private labels;
+    private assignees;
+    private defaultPollIntervalMs;
+    private defaultTimeoutMs;
+    /**
+     * Maps breakpointId -> GitHub issue number.
+     *
+     * Used for legacy non-`gh-{number}` IDs within a single process.
+     * New breakpoints always use `gh-{number}` IDs and remain durable
+     * across backend restarts without this map.
+     */
+    private issueMap;
+    private tokenOverride?;
+    /**
+     * Resolve the GitHub issue number from a breakpoint ID.
+     * Checks the in-memory map first, then parses the `gh-{number}` format
+     * so that IDs survive across backend instances.
+     */
+    private resolveIssueNumber;
+    constructor(config: GitHubIssuesBackendConfig);
+    /**
+     * Override the token resolution for testing.
+     * @internal
+     */
+    setToken(token: string): void;
+    private getToken;
+    private githubFetch;
+    private repoPath;
+    private mapIssueToBreakpoint;
+    private buildAnswerFromComment;
+    private formatIssueBody;
+    submitBreakpoint(params: SubmitBreakpointParams): Promise<Breakpoint>;
+    getBreakpoint(id: string): Promise<Breakpoint>;
+    waitForAnswer(id: string, options?: WaitForAnswerOptions): Promise<BreakpointWaitResult>;
+    listResponders(_params?: ListRespondersParams): Promise<ResponderProfile[]>;
+    claimBreakpoint(id: string, responderId: string): Promise<Breakpoint>;
+    answerBreakpoint(id: string, answer: SubmitAnswerParams): Promise<BreakpointAnswer>;
+    listPendingBreakpoints(responderId?: string): Promise<Breakpoint[]>;
+    cancelBreakpoint(id: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=github-issues.d.ts.map

package/dist/backends/github-issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-issues.d.ts","sourceRoot":"","sources":["../../src/backends/github-issues.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EAKpB,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAwDrB,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA0LD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAevC;AAQD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1C,YAAY,GAAG,IAAI,CAwDrB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAC3D,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,gBAAgB,CAAS;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAA6B;IAE7C,OAAO,CAAC,aAAa,CAAC,CAAS;IAE/B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;gBAcd,MAAM,EAAE,yBAAyB;IAS7C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B,OAAO,CAAC,QAAQ;YAKF,WAAW;IA6CzB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,oBAAoB;IAsD5B,OAAO,CAAC,sBAAsB;IAuB9B,OAAO,CAAC,eAAe;IAgHjB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiCrE,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsC9C,aAAa,CACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,oBAAoB,CAAC;IAmG1B,cAAc,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAY3E,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA4BrE,gBAAgB,CACpB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,gBAAgB,CAAC;IAwEtB,sBAAsB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA0BnE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}