@agentworkforce/sage 1.1.2 → 1.2.0

package/dist/observability.e2e.test.js

@@ -0,0 +1,411 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildHarness, makeGitHubPRComment, makeRelayfileSeedEntry, makeSlackMessage, } from "./e2e/e2e-harness.js";
+const POLL_INTERVAL_MS = 10;
+const POLL_TIMEOUT_MS = 2_000;
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function expectEnvelopeMeta(envelope, status, source) {
+    expect(envelope.status).toBe(status);
+    expect(envelope.source).toBe(source);
+    expect(envelope.asOf).toEqual(expect.any(Number));
+    expect(envelope.asOf).toBeGreaterThan(0);
+    expect(envelope.ageMs).toEqual(expect.any(Number));
+    expect(envelope.ageMs).toBeGreaterThanOrEqual(0);
+}
+describe("observability E2E", () => {
+    let harness;
+    beforeEach(async () => {
+        vi.useRealTimers();
+        harness = await buildHarness();
+    });
+    afterEach(async () => {
+        vi.useRealTimers();
+        await harness.teardown();
+    });
+    async function rebuildHarness(options) {
+        await harness.teardown();
+        harness = await buildHarness(options);
+    }
+    async function waitForSettledStatus(actionId, timeoutMs = POLL_TIMEOUT_MS) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < timeoutMs) {
+            const status = harness.facade.getStatus(actionId);
+            if (status && status.state !== "pending") {
+                return status;
+            }
+            await delay(POLL_INTERVAL_MS);
+        }
+        const status = harness.facade.getStatus(actionId);
+        throw new Error(`Timed out waiting for write status to settle: ${JSON.stringify(status)}`);
+    }
+    function replaceSlackEgress(slackEgress) {
+        harness.facade.slackEgress = slackEgress;
+    }
+    describe("happy paths", () => {
+        it("slack read-your-writes", async () => {
+            const msg = makeSlackMessage();
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                body: { ok: true, ts: "1234567890.000100" },
+            });
+            const writeResult = await harness.facade.write({
+                kind: "slack:postMessage",
+                channel: msg.channel,
+                text: msg.text,
+            });
+            expect(writeResult).toMatchObject({
+                ok: true,
+                mode: "sync",
+                providerPath: `/slack/channels/${msg.channel}/messages/1234567890.000100.json`,
+            });
+            expect(writeResult.data).toMatchObject({ ts: "1234567890.000100" });
+            const envelope = await harness.reader.readFileEnveloped(`/slack/channels/${msg.channel}/messages/1234567890.000100.json`);
+            expectEnvelopeMeta(envelope, "hit", "overlay");
+            expect(envelope.data).toEqual(expect.stringContaining(msg.text));
+            expect(envelope.data).toEqual(expect.stringContaining("1234567890.000100"));
+        });
+        it("github read-your-writes", async () => {
+            const comment = makeGitHubPRComment();
+            harness.mockCloudProxy.setGithubResponse(`/repos/${comment.owner}/${comment.repo}/issues/${comment.number}/comments`, { body: { id: 999, url: "https://github.com/test/999" } });
+            const writeResult = await harness.facade.write({
+                kind: "github:createComment",
+                owner: comment.owner,
+                repo: comment.repo,
+                number: comment.number,
+                body: comment.body,
+            });
+            expect(writeResult).toMatchObject({
+                ok: true,
+                mode: "sync",
+                providerPath: `/github/repos/${comment.owner}/${comment.repo}/issues/${comment.number}/comments/999.json`,
+            });
+            expect(writeResult.data).toMatchObject({ id: 999 });
+            const envelope = await harness.reader.readGitHubPREnveloped(comment.owner, comment.repo, comment.number);
+            expectEnvelopeMeta(envelope, "hit", "overlay");
+            expect(envelope.data).toEqual(expect.stringContaining(comment.body));
+            expect(envelope.data).toEqual(expect.stringContaining("999"));
+        });
+        it("relayfile hit passthrough", async () => {
+            const filePath = "/slack/channels/C-test/messages/ts1.json";
+            harness.mockRelayfile.seedFile(filePath, makeRelayfileSeedEntry(filePath, {
+                content: JSON.stringify({ text: "archived message" }),
+            }));
+            const envelope = await harness.reader.readFileEnveloped(filePath);
+            expectEnvelopeMeta(envelope, "hit", "relayfile");
+            expect(envelope.data).toEqual(expect.stringContaining("archived message"));
+        });
+    });
+    describe("staleness", () => {
+        it("TTL expiry falls through to relayfile", async () => {
+            await rebuildHarness({ overlayTtlMs: 50 });
+            const filePath = "/slack/channels/C1/messages/ts1.json";
+            harness.mockRelayfile.seedFile(filePath, makeRelayfileSeedEntry(filePath, {
+                content: JSON.stringify({ text: "relayfile data" }),
+            }));
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date("2026-04-15T12:00:00.000Z"));
+            harness.overlay.record({
+                path: filePath,
+                data: { text: "overlay data" },
+                provider: "slack",
+                action: "postMessage",
+            });
+            vi.advanceTimersByTime(100);
+            expect(harness.overlay.lookup(filePath)).toBeNull();
+            vi.useRealTimers();
+            const envelope = await harness.reader.readFileEnveloped(filePath);
+            expectEnvelopeMeta(envelope, "hit", "relayfile");
+            expect(envelope.data).toEqual(expect.stringContaining("relayfile data"));
+            expect(envelope.data).not.toEqual(expect.stringContaining("overlay data"));
+        });
+        it("overlay wins over stale relayfile", async () => {
+            const filePath = "/slack/channels/C1/messages/ts2.json";
+            harness.mockRelayfile.seedFile(filePath, makeRelayfileSeedEntry(filePath, {
+                content: JSON.stringify({ text: "old relayfile" }),
+            }));
+            harness.overlay.record({
+                path: filePath,
+                data: { text: "fresh overlay" },
+                provider: "slack",
+                action: "postMessage",
+            });
+            const envelope = await harness.reader.readFileEnveloped(filePath);
+            expectEnvelopeMeta(envelope, "hit", "overlay");
+            expect(envelope.data).toEqual(expect.stringContaining("fresh overlay"));
+            expect(envelope.data).not.toEqual(expect.stringContaining("old relayfile"));
+        });
+        it("LRU eviction under pressure", async () => {
+            await rebuildHarness({ overlayMaxEntries: 3 });
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date("2026-04-15T12:00:00.000Z"));
+            for (const path of ["/a", "/b", "/c", "/d"]) {
+                harness.overlay.record({
+                    path,
+                    data: { path },
+                    provider: "slack",
+                    action: "test",
+                });
+                vi.advanceTimersByTime(1);
+            }
+            expect(harness.overlay.size).toBeLessThanOrEqual(3);
+            expect(harness.overlay.lookup("/a")).toBeNull();
+            expect(harness.overlay.lookup("/d")).toMatchObject({
+                path: "/d",
+                data: { path: "/d" },
+            });
+            vi.useRealTimers();
+        });
+    });
+    describe("error distinguishability", () => {
+        it("relayfile 404 yields miss envelope", async () => {
+            const envelope = await harness.reader.readFileEnveloped("/nonexistent/path.json");
+            expectEnvelopeMeta(envelope, "miss", "relayfile");
+            expect(envelope.data).toBeNull();
+            expect(envelope.error).toBeUndefined();
+        });
+        it("relayfile 500 yields error envelope", async () => {
+            harness.mockRelayfile.setResponse("/failing/path.json", {
+                status: 500,
+                body: { code: "internal_error", message: "boom" },
+            });
+            const envelope = await harness.reader.readFileEnveloped("/failing/path.json");
+            expectEnvelopeMeta(envelope, "error", "relayfile");
+            expect(envelope.data).toBeNull();
+            expect(envelope.error).toEqual(expect.any(String));
+            expect(envelope.error?.length).toBeGreaterThan(0);
+        });
+        it("relayfile timeout yields error envelope", async () => {
+            harness.mockRelayfile.setResponse("/slow/path.json", { delayMs: 60_000 });
+            const envelope = await harness.reader.readFileEnveloped("/slow/path.json");
+            expectEnvelopeMeta(envelope, "error", "relayfile");
+            expect(envelope.data).toBeNull();
+            expect(envelope.error).toEqual(expect.any(String));
+            expect(envelope.error?.length).toBeGreaterThan(0);
+        }, 4_000);
+        it("overlay source is observable", async () => {
+            harness.overlay.record({
+                path: "/test/observable.json",
+                data: { key: "value" },
+                provider: "slack",
+                action: "postMessage",
+            });
+            const envelope = await harness.reader.readFileEnveloped("/test/observable.json");
+            expectEnvelopeMeta(envelope, "hit", "overlay");
+            expect(envelope.data).toEqual(expect.stringContaining("value"));
+        });
+    });
+    describe("write modes", () => {
+        it("sync write success populates overlay", async () => {
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                body: { ok: true, ts: "1111.2222" },
+            });
+            const result = await harness.facade.write({ kind: "slack:postMessage", channel: "C-sync", text: "sync test" }, "sync");
+            expect(result).toMatchObject({
+                ok: true,
+                mode: "sync",
+                providerPath: "/slack/channels/C-sync/messages/1111.2222.json",
+            });
+            const entry = harness.overlay.lookup("/slack/channels/C-sync/messages/1111.2222.json");
+            expect(entry).toMatchObject({
+                provider: "slack",
+                action: "postMessage",
+                data: {
+                    channel: "C-sync",
+                    text: "sync test",
+                    ts: "1111.2222",
+                },
+            });
+        });
+        it("sync write provider error skips overlay", async () => {
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                ok: false,
+                error: "channel_not_found",
+                status: 200,
+            });
+            const result = await harness.facade.write({ kind: "slack:postMessage", channel: "C-bad", text: "fail test" }, "sync");
+            expect(result).toMatchObject({
+                ok: false,
+                mode: "sync",
+                error: "channel_not_found",
+            });
+            expect(result.providerPath).toMatch(/^\/slack\/channels\/C-bad\/messages\/\d+\.json$/);
+            expect(harness.overlay.search({ provider: "slack", pathPrefix: "/slack/channels/C-bad/" })).toHaveLength(0);
+        });
+        it("fire-and-forget status transitions pending to settled", async () => {
+            vi.useRealTimers();
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                body: { ok: true, ts: "3333.4444" },
+                delayMs: 100,
+            });
+            const result = await harness.facade.write({ kind: "slack:postMessage", channel: "C-faf", text: "faf test" }, "fire-and-forget");
+            expect(result).toMatchObject({
+                ok: true,
+                mode: "fire-and-forget",
+                actionId: expect.any(String),
+            });
+            const pendingStatus = harness.facade.getStatus(result.actionId);
+            expect(pendingStatus).toMatchObject({
+                actionId: result.actionId,
+                state: "pending",
+            });
+            const settledStatus = await waitForSettledStatus(result.actionId);
+            expect(settledStatus).toMatchObject({
+                actionId: result.actionId,
+                state: "success",
+                result: {
+                    ok: true,
+                    mode: "fire-and-forget",
+                    providerPath: "/slack/channels/C-faf/messages/3333.4444.json",
+                },
+            });
+            expect(settledStatus.result?.data).toMatchObject({ ts: "3333.4444" });
+        });
+        it("fire-and-forget async failure surfaces in status", async () => {
+            vi.useRealTimers();
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                ok: false,
+                error: "network failure",
+                status: 500,
+            });
+            const result = await harness.facade.write({ kind: "slack:postMessage", channel: "C-faf-fail", text: "will fail" }, "fire-and-forget");
+            expect(result).toMatchObject({
+                ok: true,
+                mode: "fire-and-forget",
+            });
+            const settledStatus = await waitForSettledStatus(result.actionId);
+            expect(settledStatus.state).toBe("failed");
+            expect(settledStatus.result).toMatchObject({
+                ok: false,
+                mode: "fire-and-forget",
+            });
+            expect(settledStatus.result?.error).toEqual(expect.stringContaining("network failure"));
+        });
+    });
+    describe("concurrency", () => {
+        it("concurrent writes to same path last-write-wins", async () => {
+            vi.useRealTimers();
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                body: { ok: true, ts: "5555.6666" },
+                delayMs: 80,
+            });
+            const writes = await Promise.all([
+                harness.facade.write({ kind: "slack:postMessage", channel: "C-race", text: "write-1" }, "sync"),
+                (async () => {
+                    await delay(20);
+                    return harness.facade.write({ kind: "slack:postMessage", channel: "C-race", text: "write-2" }, "sync");
+                })(),
+            ]);
+            expect(writes).toEqual([
+                expect.objectContaining({ ok: true, providerPath: "/slack/channels/C-race/messages/5555.6666.json" }),
+                expect.objectContaining({ ok: true, providerPath: "/slack/channels/C-race/messages/5555.6666.json" }),
+            ]);
+            const entries = harness.overlay.search({
+                provider: "slack",
+                pathPrefix: "/slack/channels/C-race/messages/",
+            });
+            expect(entries).toHaveLength(1);
+            expect(entries[0]).toMatchObject({
+                path: "/slack/channels/C-race/messages/5555.6666.json",
+                data: {
+                    channel: "C-race",
+                    text: "write-2",
+                    ts: "5555.6666",
+                },
+            });
+            const requests = harness.mockCloudProxy
+                .getRequestLog()
+                .filter((entry) => entry.provider === "slack" && entry.endpoint === "/chat.postMessage");
+            expect(requests).toHaveLength(2);
+            expect(requests[0].timestamp).toBeLessThanOrEqual(requests[1].timestamp);
+            expect(entries[0].writtenAt).toBeGreaterThanOrEqual(requests[1].timestamp);
+        });
+        it("read during in-flight fire-and-forget", async () => {
+            vi.useRealTimers();
+            harness.mockCloudProxy.setSlackResponse("/chat.postMessage", {
+                body: { ok: true, ts: "7777.8888" },
+                delayMs: 200,
+            });
+            const writeResult = await harness.facade.write({ kind: "slack:postMessage", channel: "C-inflight", text: "in-flight" }, "fire-and-forget");
+            expect(writeResult).toMatchObject({
+                ok: true,
+                mode: "fire-and-forget",
+            });
+            const entries = harness.overlay.search({
+                provider: "slack",
+                pathPrefix: "/slack/channels/C-inflight/",
+            });
+            expect(entries.length).toBeGreaterThanOrEqual(1);
+            expect(entries[0].data).toMatchObject({
+                channel: "C-inflight",
+                text: "in-flight",
+                pending: true,
+            });
+            const settledStatus = await waitForSettledStatus(writeResult.actionId);
+            expect(settledStatus.state).toBe("success");
+            expect(settledStatus.result?.providerPath).toBe("/slack/channels/C-inflight/messages/7777.8888.json");
+        });
+        it("parallel reads of same overlay entry", async () => {
+            harness.overlay.record({
+                path: "/parallel/read.json",
+                data: { value: "shared" },
+                provider: "slack",
+                action: "test",
+            });
+            const results = await Promise.all([
+                harness.reader.readFileEnveloped("/parallel/read.json"),
+                harness.reader.readFileEnveloped("/parallel/read.json"),
+                harness.reader.readFileEnveloped("/parallel/read.json"),
+            ]);
+            for (const envelope of results) {
+                expectEnvelopeMeta(envelope, "hit", "overlay");
+                expect(envelope.data).toEqual(expect.stringContaining("shared"));
+            }
+        });
+    });
+    describe("graceful degradation", () => {
+        it("overlay lookup error yields error envelope", async () => {
+            harness.overlay.record({
+                path: "/poisoned/file.json",
+                data: { x: 1 },
+                provider: "slack",
+                action: "test",
+            });
+            const originalLookup = harness.overlay.lookup.bind(harness.overlay);
+            harness.overlay.lookup = () => {
+                throw new Error("overlay corrupted");
+            };
+            try {
+                const envelope = await harness.reader.readFileEnveloped("/poisoned/file.json");
+                expectEnvelopeMeta(envelope, "error", "overlay");
+                expect(envelope.data).toBeNull();
+                expect(envelope.error).toEqual(expect.stringContaining("overlay corrupted"));
+            }
+            finally {
+                harness.overlay.lookup = originalLookup;
+            }
+        });
+        it("fire-and-forget handler throw is captured", async () => {
+            vi.useRealTimers();
+            replaceSlackEgress({
+                postMessage: () => {
+                    throw new Error("sync kaboom");
+                },
+                addReaction: async () => undefined,
+            });
+            const result = await harness.facade.write({ kind: "slack:postMessage", channel: "C-throw", text: "boom" }, "fire-and-forget");
+            expect(result).toMatchObject({
+                ok: true,
+                mode: "fire-and-forget",
+            });
+            const status = await waitForSettledStatus(result.actionId);
+            expect(status.state).toBe("failed");
+            expect(status.result).toMatchObject({
+                ok: false,
+                mode: "fire-and-forget",
+            });
+            expect(status.result?.error).toEqual(expect.stringContaining("sync kaboom"));
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentworkforce/sage",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgentWorkforce/sage.git"
@@ -22,7 +22,7 @@
     "dev": "tsx watch --env-file=.env src/dev-server.ts",
     "clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\"",
     "build": "npm run clean && tsc -p tsconfig.build.json",
-    "test": "vitest run",
+    "test": "npm run build --workspace @agentworkforce/sage-client && vitest run --workspace vitest.workspace.ts",
     "prepack": "npm run build",
     "workflows:cli-mac": "node scripts/run-cli-mac-workflows.mjs",
     "workflows:cli-mac:dry": "node scripts/run-cli-mac-workflows.mjs --dry-run",
@@ -31,13 +31,16 @@
     "workflows:qa-meta-master": "agent-relay run workflows/v4/34-qa-meta-master-executor.ts"
   },
   "dependencies": {
-    "@agent-assistant/core": "^0.1.1",
-    "@agent-assistant/traits": "^0.1.1",
+    "@agent-assistant/core": "^0.2.0",
+    "@agent-assistant/surfaces": "^0.2.0",
+    "@agent-assistant/traits": "^0.2.0",
     "@agent-relay/memory": "^4.0.0",
     "@agent-relay/sdk": "^4.0.0",
     "@agentcron/sdk": "^0.1.0",
     "@nangohq/node": "^0.42.0",
     "@nangohq/types": "^0.69.48",
+    "@relayfile/adapter-linear": "^0.1.3",
+    "@relayfile/adapter-notion": "^0.1.2",
     "@relayfile/adapter-slack": "^0.1.3",
     "@relayfile/provider-nango": "^0.2.1",
     "agent-trajectories": "^0.5.0",
@@ -46,7 +49,9 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250408.0",
     "@hono/node-server": "^1.0.0",
+    "@types/express": "^5.0.6",
     "@types/node": "^20.0.0",
+    "express": "^5.2.1",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0",
     "vitest": "^2.0.0"