@agentworkforce/sage 1.1.2 → 1.2.0

package/dist/integrations/provider-write-facade.js

@@ -0,0 +1,417 @@
+import { randomBytes, randomUUID } from "node:crypto";
+export const DEFAULT_WRITE_MODE = "sync";
+export const STATUS_RETENTION_MS = 300_000;
+class MissingProviderError extends Error {
+    constructor(provider, actionKind) {
+        super(`Write action "${actionKind}" requires a ${provider} provider`);
+        this.name = "MissingProviderError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function compactRecord(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined) {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+function requireString(action, key) {
+    const value = action[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Write action "${action.kind}" requires a non-empty ${String(key)}`);
+    }
+    return value;
+}
+function optionalString(action, key) {
+    const value = action[key];
+    return typeof value === "string" ? value : undefined;
+}
+function requireNumber(action, key) {
+    const value = action[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Write action "${action.kind}" requires a finite ${String(key)}`);
+    }
+    return value;
+}
+function encodePathSegment(value) {
+    return encodeURIComponent(String(value));
+}
+function buildSlackMessagePath(channel, ts) {
+    return `/slack/channels/${channel}/messages/${ts}.json`;
+}
+function buildSlackReactionPath(channel, timestamp, emoji) {
+    return `/slack/channels/${channel}/messages/${timestamp}/reactions/${emoji}.json`;
+}
+function buildGitHubIssueCommentPath(owner, repo, number, commentId) {
+    return `/github/repos/${encodePathSegment(owner)}/${encodePathSegment(repo)}/issues/${number}/comments/${encodePathSegment(commentId)}.json`;
+}
+function buildGitHubReviewPath(owner, repo, number, reviewId) {
+    return `/github/repos/${encodePathSegment(owner)}/${encodePathSegment(repo)}/pulls/${number}/reviews/${encodePathSegment(reviewId)}.json`;
+}
+function createUuidV4Fallback() {
+    const bytes = randomBytes(16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20),
+    ].join("-");
+}
+function createActionId() {
+    return typeof randomUUID === "function" ? randomUUID() : createUuidV4Fallback();
+}
+function createFailureResult(mode, actionId, providerPath, error) {
+    return {
+        mode,
+        ok: false,
+        error,
+        actionId,
+        providerPath,
+    };
+}
+function toWriteResult(mode, actionId, execution) {
+    if (!execution.ok) {
+        return createFailureResult(mode, actionId, execution.providerPath, execution.error ?? "Provider write failed");
+    }
+    return {
+        mode,
+        ok: true,
+        ...(execution.data ? { data: execution.data } : {}),
+        actionId,
+        providerPath: execution.providerPath,
+    };
+}
+function unwrapGitHubCreatedResource(response) {
+    const candidate = isRecord(response) && isRecord(response.data) ? response.data : response;
+    if (!isRecord(candidate)) {
+        throw new Error("GitHub write returned an invalid response");
+    }
+    const id = candidate.id;
+    const url = candidate.url;
+    if (typeof id !== "number" || !Number.isFinite(id) || typeof url !== "string") {
+        throw new Error("GitHub write returned an invalid created resource");
+    }
+    return { id, url };
+}
+function readReviewEvent(action) {
+    const event = action.event;
+    if (event === "APPROVE" || event === "REQUEST_CHANGES" || event === "COMMENT") {
+        return event;
+    }
+    return undefined;
+}
+export class ProviderWriteFacade {
+    slackEgress;
+    githubIntegration;
+    overlay;
+    defaultMode;
+    statuses = new Map();
+    constructor(options) {
+        this.slackEgress = options.slackEgress ?? null;
+        this.githubIntegration = options.githubIntegration ?? null;
+        this.overlay = options.overlay ?? null;
+        this.defaultMode = options.defaultMode ?? DEFAULT_WRITE_MODE;
+    }
+    async write(action, mode) {
+        const resolvedMode = mode ?? this.defaultMode;
+        const actionId = createActionId();
+        this.pruneCompletedStatuses();
+        const plan = this.createDispatchPlan(action, actionId);
+        if (resolvedMode === "fire-and-forget") {
+            return this.writeFireAndForget(plan, actionId, resolvedMode);
+        }
+        return this.writeSync(plan, actionId, resolvedMode);
+    }
+    getStatus(actionId) {
+        this.pruneCompletedStatuses();
+        const status = this.statuses.get(actionId);
+        if (!status) {
+            return null;
+        }
+        return {
+            actionId: status.actionId,
+            state: status.state,
+            ...(status.result ? { result: status.result } : {}),
+            createdAt: status.createdAt,
+        };
+    }
+    async writeSync(plan, actionId, mode) {
+        try {
+            const execution = await plan.execute();
+            const result = toWriteResult(mode, actionId, execution);
+            if (result.ok && execution.overlayData) {
+                this.recordOverlay(plan.provider, plan.overlayAction, execution.providerPath, execution.overlayData);
+            }
+            return result;
+        }
+        catch (error) {
+            return createFailureResult(mode, actionId, plan.speculativeProviderPath, toErrorMessage(error));
+        }
+    }
+    writeFireAndForget(plan, actionId, mode) {
+        const createdAt = Date.now();
+        this.statuses.set(actionId, {
+            actionId,
+            state: "pending",
+            createdAt,
+        });
+        this.recordOverlay(plan.provider, plan.overlayAction, plan.speculativeProviderPath, plan.speculativeOverlayData);
+        void plan.execute()
+            .then((execution) => {
+            const result = toWriteResult(mode, actionId, execution);
+            if (result.ok && execution.overlayData) {
+                // If the real path differs from the speculative path, remove the speculative entry and record the real one
+                if (execution.providerPath !== plan.speculativeProviderPath) {
+                    this.overlay?.remove(plan.speculativeProviderPath);
+                    this.recordOverlay(plan.provider, plan.overlayAction, execution.providerPath, execution.overlayData);
+                }
+                else {
+                    // Same-path write: upgrade the speculative entry to final state (remove pending flag)
+                    this.recordOverlay(plan.provider, plan.overlayAction, execution.providerPath, execution.overlayData);
+                }
+            }
+            else if (!result.ok) {
+                // Non-throwing failure (e.g. Slack { ok:false, error:"channel_not_found" }):
+                // drop the speculative overlay entry so readers don't see phantom pending data.
+                this.overlay?.remove(plan.speculativeProviderPath);
+            }
+            this.statuses.set(actionId, {
+                actionId,
+                state: result.ok ? "success" : "failed",
+                result,
+                createdAt,
+                completedAt: Date.now(),
+            });
+        })
+            .catch((error) => {
+            // On failure, remove the speculative overlay entry so phantom data isn't left behind
+            this.overlay?.remove(plan.speculativeProviderPath);
+            this.statuses.set(actionId, {
+                actionId,
+                state: "failed",
+                result: createFailureResult(mode, actionId, plan.speculativeProviderPath, toErrorMessage(error)),
+                createdAt,
+                completedAt: Date.now(),
+            });
+        });
+        return {
+            mode,
+            ok: true,
+            actionId,
+            providerPath: plan.speculativeProviderPath,
+        };
+    }
+    createDispatchPlan(action, actionId) {
+        switch (action.kind) {
+            case "slack:postMessage":
+                return this.createSlackPostMessagePlan(action, actionId);
+            case "slack:addReaction":
+                return this.createSlackAddReactionPlan(action, actionId);
+            case "github:createComment":
+                return this.createGitHubCreateCommentPlan(action, actionId);
+            case "github:createReview":
+                return this.createGitHubCreateReviewPlan(action, actionId);
+            default:
+                throw new Error(`Unsupported write action kind: ${action.kind}`);
+        }
+    }
+    createSlackPostMessagePlan(action, actionId) {
+        const slackEgress = this.requireSlackEgress(action.kind);
+        const channel = requireString(action, "channel");
+        const text = requireString(action, "text");
+        const threadTs = optionalString(action, "threadTs");
+        const placeholderTs = String(Date.now());
+        const speculativeProviderPath = buildSlackMessagePath(channel, placeholderTs);
+        const speculativeOverlayData = compactRecord({
+            channel,
+            text,
+            thread_ts: threadTs,
+            ts: placeholderTs,
+            pending: true,
+            actionId,
+        });
+        return {
+            provider: "slack",
+            overlayAction: "postMessage",
+            speculativeProviderPath,
+            speculativeOverlayData,
+            execute: async () => {
+                const response = await slackEgress.postMessage(channel, text, threadTs);
+                const ts = response.ts ?? placeholderTs;
+                const providerPath = buildSlackMessagePath(channel, ts);
+                if (!response.ok) {
+                    return {
+                        ok: false,
+                        error: response.error ?? "Slack postMessage failed",
+                        providerPath,
+                    };
+                }
+                return {
+                    ok: true,
+                    data: compactRecord({
+                        ok: response.ok,
+                        ts: response.ts,
+                        error: response.error,
+                    }),
+                    providerPath,
+                    overlayData: compactRecord({
+                        channel,
+                        text,
+                        thread_ts: threadTs,
+                        ts,
+                    }),
+                };
+            },
+        };
+    }
+    createSlackAddReactionPlan(action, actionId) {
+        const slackEgress = this.requireSlackEgress(action.kind);
+        const channel = requireString(action, "channel");
+        const timestamp = requireString(action, "threadTs");
+        const emoji = requireString(action, "emoji");
+        const providerPath = buildSlackReactionPath(channel, timestamp, emoji);
+        const overlayData = {
+            channel,
+            timestamp,
+            name: emoji,
+        };
+        return {
+            provider: "slack",
+            overlayAction: "addReaction",
+            speculativeProviderPath: providerPath,
+            speculativeOverlayData: {
+                ...overlayData,
+                pending: true,
+                actionId,
+            },
+            execute: async () => {
+                await slackEgress.addReaction(channel, timestamp, emoji);
+                return {
+                    ok: true,
+                    data: overlayData,
+                    providerPath,
+                    overlayData,
+                };
+            },
+        };
+    }
+    createGitHubCreateCommentPlan(action, actionId) {
+        const githubIntegration = this.requireGitHubIntegration(action.kind);
+        const owner = requireString(action, "owner");
+        const repo = requireString(action, "repo");
+        const number = requireNumber(action, "number");
+        const body = requireString(action, "body");
+        const placeholderCommentId = `pending-${actionId}`;
+        const speculativeProviderPath = buildGitHubIssueCommentPath(owner, repo, number, placeholderCommentId);
+        const speculativeOverlayData = {
+            body,
+            issue_number: number,
+            pending: true,
+            actionId,
+        };
+        return {
+            provider: "github",
+            overlayAction: "createComment",
+            speculativeProviderPath,
+            speculativeOverlayData,
+            execute: async () => {
+                const created = unwrapGitHubCreatedResource(await githubIntegration.createIssueComment(owner, repo, number, body));
+                const providerPath = buildGitHubIssueCommentPath(owner, repo, number, created.id);
+                const overlayData = {
+                    id: created.id,
+                    body,
+                    url: created.url,
+                    issue_number: number,
+                };
+                return {
+                    ok: true,
+                    data: { id: created.id, url: created.url },
+                    providerPath,
+                    overlayData,
+                };
+            },
+        };
+    }
+    createGitHubCreateReviewPlan(action, actionId) {
+        const githubIntegration = this.requireGitHubIntegration(action.kind);
+        const owner = requireString(action, "owner");
+        const repo = requireString(action, "repo");
+        const number = requireNumber(action, "number");
+        const body = requireString(action, "body");
+        const event = readReviewEvent(action) ?? "COMMENT";
+        const placeholderReviewId = `pending-${actionId}`;
+        const speculativeProviderPath = buildGitHubReviewPath(owner, repo, number, placeholderReviewId);
+        const speculativeOverlayData = {
+            body,
+            event,
+            pull_number: number,
+            pending: true,
+            actionId,
+        };
+        return {
+            provider: "github",
+            overlayAction: "createReview",
+            speculativeProviderPath,
+            speculativeOverlayData,
+            execute: async () => {
+                const created = unwrapGitHubCreatedResource(await githubIntegration.createPRReview(owner, repo, number, body, event));
+                const providerPath = buildGitHubReviewPath(owner, repo, number, created.id);
+                const overlayData = {
+                    id: created.id,
+                    body,
+                    event,
+                    url: created.url,
+                    pull_number: number,
+                };
+                return {
+                    ok: true,
+                    data: { id: created.id, url: created.url },
+                    providerPath,
+                    overlayData,
+                };
+            },
+        };
+    }
+    requireSlackEgress(actionKind) {
+        if (!this.slackEgress) {
+            throw new MissingProviderError("slack", actionKind);
+        }
+        return this.slackEgress;
+    }
+    requireGitHubIntegration(actionKind) {
+        if (!this.githubIntegration) {
+            throw new MissingProviderError("github", actionKind);
+        }
+        return this.githubIntegration;
+    }
+    recordOverlay(provider, action, path, data) {
+        this.overlay?.record({
+            path,
+            data,
+            provider,
+            action,
+        });
+    }
+    pruneCompletedStatuses(now = Date.now()) {
+        for (const [actionId, status] of this.statuses) {
+            if (status.completedAt !== undefined &&
+                now - status.completedAt > STATUS_RETENTION_MS) {
+                this.statuses.delete(actionId);
+            }
+        }
+    }
+}

package/dist/integrations/provider-write-facade.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider-write-facade.test.d.ts.map

package/dist/integrations/provider-write-facade.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-write-facade.test.d.ts","sourceRoot":"","sources":["../../src/integrations/provider-write-facade.test.ts"],"names":[],"mappings":""}

package/dist/integrations/provider-write-facade.test.js

@@ -0,0 +1,247 @@
+import { describe, expect, it } from "vitest";
+import { ProviderWriteFacade, } from "./provider-write-facade.js";
+import { RecentActionsOverlay } from "./recent-actions-overlay.js";
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((innerResolve, innerReject) => {
+        resolve = innerResolve;
+        reject = innerReject;
+    });
+    return { promise, resolve, reject };
+}
+async function flushAsyncWork() {
+    await new Promise((resolve) => {
+        setImmediate(resolve);
+    });
+}
+describe("ProviderWriteFacade", () => {
+    it("routes a sync slack action to slack egress and records an overlay on success", async () => {
+        const calls = [];
+        const overlay = new RecentActionsOverlay();
+        const slackEgress = {
+            postMessage: async (channel, text, threadTs) => {
+                calls.push({ provider: "slack", method: "postMessage", channel, text, threadTs });
+                return { ok: true, ts: "1700000000.000100" };
+            },
+            addReaction: async (channel, timestamp, emoji) => {
+                calls.push({ provider: "slack", method: "addReaction", channel, timestamp, emoji });
+            },
+        };
+        const githubIntegration = {
+            createIssueComment: async (owner, repo, number, body) => {
+                calls.push({ provider: "github", method: "createIssueComment", owner, repo, number, body });
+                return { id: 101, url: "https://github.example/comments/101" };
+            },
+            createPRReview: async (owner, repo, number, body, event) => {
+                calls.push({ provider: "github", method: "createPRReview", owner, repo, number, body, event });
+                return { id: 202, url: "https://github.example/reviews/202" };
+            },
+        };
+        const facade = new ProviderWriteFacade({ slackEgress, githubIntegration, overlay });
+        const result = await facade.write({
+            kind: "slack:postMessage",
+            channel: "C123",
+            threadTs: "1699999999.000001",
+            text: "Ship it",
+        }, "sync");
+        const providerPath = "/slack/channels/C123/messages/1700000000.000100.json";
+        expect(calls).toEqual([
+            {
+                provider: "slack",
+                method: "postMessage",
+                channel: "C123",
+                text: "Ship it",
+                threadTs: "1699999999.000001",
+            },
+        ]);
+        expect(result).toEqual({
+            mode: "sync",
+            ok: true,
+            data: { ok: true, ts: "1700000000.000100" },
+            actionId: expect.any(String),
+            providerPath,
+        });
+        expect(overlay.lookup(providerPath)).toMatchObject({
+            path: providerPath,
+            provider: "slack",
+            action: "postMessage",
+            data: {
+                channel: "C123",
+                thread_ts: "1699999999.000001",
+                text: "Ship it",
+                ts: "1700000000.000100",
+            },
+        });
+    });
+    it("surfaces sync provider errors without recording a success overlay", async () => {
+        const calls = [];
+        const overlay = new RecentActionsOverlay();
+        const slackEgress = {
+            postMessage: async (channel, text, threadTs) => {
+                calls.push({ provider: "slack", method: "postMessage", channel, text, threadTs });
+                return { ok: false, error: "not_in_channel" };
+            },
+            addReaction: async (channel, timestamp, emoji) => {
+                calls.push({ provider: "slack", method: "addReaction", channel, timestamp, emoji });
+            },
+        };
+        const githubIntegration = {
+            createIssueComment: async (owner, repo, number, body) => {
+                calls.push({ provider: "github", method: "createIssueComment", owner, repo, number, body });
+                return { id: 303, url: "https://github.example/comments/303" };
+            },
+            createPRReview: async (owner, repo, number, body, event) => {
+                calls.push({ provider: "github", method: "createPRReview", owner, repo, number, body, event });
+                return { id: 404, url: "https://github.example/reviews/404" };
+            },
+        };
+        const facade = new ProviderWriteFacade({ slackEgress, githubIntegration, overlay });
+        const result = await facade.write({
+            kind: "slack:postMessage",
+            channel: "C404",
+            text: "This should fail",
+        }, "sync");
+        expect(calls).toEqual([
+            {
+                provider: "slack",
+                method: "postMessage",
+                channel: "C404",
+                text: "This should fail",
+                threadTs: undefined,
+            },
+        ]);
+        expect(result).toMatchObject({
+            mode: "sync",
+            ok: false,
+            error: "not_in_channel",
+            actionId: expect.any(String),
+        });
+        expect(result.providerPath).toMatch(/^\/slack\/channels\/C404\/messages\/\d+\.json$/);
+        expect(overlay.size).toBe(0);
+    });
+    it("returns immediately for fire-and-forget writes and settles status asynchronously", async () => {
+        const calls = [];
+        const deferred = createDeferred();
+        const overlay = new RecentActionsOverlay();
+        const slackEgress = {
+            postMessage: (channel, text, threadTs) => {
+                calls.push({ provider: "slack", method: "postMessage", channel, text, threadTs });
+                return deferred.promise;
+            },
+            addReaction: async (channel, timestamp, emoji) => {
+                calls.push({ provider: "slack", method: "addReaction", channel, timestamp, emoji });
+            },
+        };
+        const githubIntegration = {
+            createIssueComment: async (owner, repo, number, body) => {
+                calls.push({ provider: "github", method: "createIssueComment", owner, repo, number, body });
+                return { id: 505, url: "https://github.example/comments/505" };
+            },
+            createPRReview: async (owner, repo, number, body, event) => {
+                calls.push({ provider: "github", method: "createPRReview", owner, repo, number, body, event });
+                return { id: 606, url: "https://github.example/reviews/606" };
+            },
+        };
+        const facade = new ProviderWriteFacade({ slackEgress, githubIntegration, overlay });
+        const result = await facade.write({
+            kind: "slack:postMessage",
+            channel: "CFF",
+            text: "Complete later",
+        }, "fire-and-forget");
+        expect(result).toMatchObject({
+            mode: "fire-and-forget",
+            ok: true,
+            actionId: expect.any(String),
+        });
+        expect(result.providerPath).toMatch(/^\/slack\/channels\/CFF\/messages\/\d+\.json$/);
+        expect(calls).toEqual([
+            {
+                provider: "slack",
+                method: "postMessage",
+                channel: "CFF",
+                text: "Complete later",
+                threadTs: undefined,
+            },
+        ]);
+        expect(facade.getStatus(result.actionId)).toMatchObject({
+            actionId: result.actionId,
+            state: "pending",
+            createdAt: expect.any(Number),
+        });
+        deferred.resolve({ ok: true, ts: "1700000000.000200" });
+        await flushAsyncWork();
+        expect(facade.getStatus(result.actionId)).toEqual({
+            actionId: result.actionId,
+            state: "success",
+            createdAt: expect.any(Number),
+            result: {
+                mode: "fire-and-forget",
+                ok: true,
+                data: { ok: true, ts: "1700000000.000200" },
+                actionId: result.actionId,
+                providerPath: "/slack/channels/CFF/messages/1700000000.000200.json",
+            },
+        });
+    });
+    it("populates overlay entries with the provider and provider path from github writes", async () => {
+        const calls = [];
+        const overlay = new RecentActionsOverlay();
+        const slackEgress = {
+            postMessage: async (channel, text, threadTs) => {
+                calls.push({ provider: "slack", method: "postMessage", channel, text, threadTs });
+                return { ok: true, ts: "1700000000.000300" };
+            },
+            addReaction: async (channel, timestamp, emoji) => {
+                calls.push({ provider: "slack", method: "addReaction", channel, timestamp, emoji });
+            },
+        };
+        const githubIntegration = {
+            createIssueComment: async (owner, repo, number, body) => {
+                calls.push({ provider: "github", method: "createIssueComment", owner, repo, number, body });
+                return { data: { id: 707, url: "https://github.example/comments/707" } };
+            },
+            createPRReview: async (owner, repo, number, body, event) => {
+                calls.push({ provider: "github", method: "createPRReview", owner, repo, number, body, event });
+                return { data: { id: 808, url: "https://github.example/reviews/808" } };
+            },
+        };
+        const facade = new ProviderWriteFacade({ slackEgress, githubIntegration, overlay });
+        const result = await facade.write({
+            kind: "github:createComment",
+            owner: "AgentWorkforce",
+            repo: "sage",
+            number: 42,
+            body: "Reviewed from tests",
+        }, "sync");
+        const providerPath = "/github/repos/AgentWorkforce/sage/issues/42/comments/707.json";
+        expect(calls).toEqual([
+            {
+                provider: "github",
+                method: "createIssueComment",
+                owner: "AgentWorkforce",
+                repo: "sage",
+                number: 42,
+                body: "Reviewed from tests",
+            },
+        ]);
+        expect(result).toMatchObject({
+            mode: "sync",
+            ok: true,
+            data: { id: 707, url: "https://github.example/comments/707" },
+            actionId: expect.any(String),
+            providerPath,
+        });
+        expect(overlay.lookup(providerPath)).toMatchObject({
+            path: providerPath,
+            provider: "github",
+            action: "createComment",
+            data: {
+                id: 707,
+                body: "Reviewed from tests",
+                url: "https://github.example/comments/707",
+                issue_number: 42,
+            },
+        });
+    });
+});

package/dist/integrations/read-your-writes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=read-your-writes.test.d.ts.map

package/dist/integrations/read-your-writes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-your-writes.test.d.ts","sourceRoot":"","sources":["../../src/integrations/read-your-writes.test.ts"],"names":[],"mappings":""}