npm - @cursor/july - Versions diffs - 0.1.24 → 0.1.26 - Mend

@cursor/july 0.1.24 → 0.1.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (205) hide show

package/dist/bin/agent-serve.js +0 -0
package/dist/channels/github/instrument.d.ts +20 -0
package/dist/channels/github/instrument.d.ts.map +1 -0
package/dist/docs/404.html +1 -1
package/dist/docs/ab.html +2 -2
package/dist/docs/assets/{app.CvSGaAxk.js → app.DYcC9FY-.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.BQTzJjR_.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.J1jJbCvs.js → VPLocalSearchBox.o4N_knTV.js} +1 -1
package/dist/docs/assets/chunks/{theme.C7vfzr7h.js → theme.DQ-njyo0.js} +2 -2
package/dist/docs/building-with-agents.html +2 -2
package/dist/docs/concepts.html +2 -2
package/dist/docs/deployment.html +2 -2
package/dist/docs/evals.html +2 -2
package/dist/docs/example-agents/approval-buddy.html +2 -2
package/dist/docs/example-agents/benny.html +2 -2
package/dist/docs/example-agents/bugbot.html +2 -2
package/dist/docs/example-agents/codebase-wiki.html +2 -2
package/dist/docs/example-agents/codeowners-review.html +2 -2
package/dist/docs/example-agents/concierge.html +2 -2
package/dist/docs/example-agents/fsd.html +2 -2
package/dist/docs/example-agents/index.html +2 -2
package/dist/docs/example-agents/knowledge-base.html +2 -2
package/dist/docs/example-agents/oncall.html +2 -2
package/dist/docs/example-agents/security-reviewer.html +2 -2
package/dist/docs/example-agents/slack-agent.html +2 -2
package/dist/docs/example-agents/weather-agent.html +2 -2
package/dist/docs/guides/agent-to-agent.html +2 -2
package/dist/docs/guides/cloud-runtime.html +2 -2
package/dist/docs/guides/github.html +2 -2
package/dist/docs/guides/human-in-the-loop.html +2 -2
package/dist/docs/guides/mcp-oauth.html +2 -2
package/dist/docs/guides/slack.html +2 -2
package/dist/docs/guides/webhooks.html +2 -2
package/dist/docs/hillclimbing.html +2 -2
package/dist/docs/index.html +2 -2
package/dist/docs/quickstart.html +2 -2
package/dist/docs/reference/agent-config.html +2 -2
package/dist/docs/reference/channels.html +2 -2
package/dist/docs/reference/cli.html +2 -2
package/dist/docs/reference/connections.html +2 -2
package/dist/docs/reference/hooks.html +2 -2
package/dist/docs/reference/http-api.html +2 -2
package/dist/docs/reference/instructions.html +2 -2
package/dist/docs/reference/playground.html +2 -2
package/dist/docs/reference/project-layout.html +2 -2
package/dist/docs/reference/prompt.html +2 -2
package/dist/docs/reference/schedules.html +2 -2
package/dist/docs/reference/sessions.html +2 -2
package/dist/docs/reference/skills.html +2 -2
package/dist/docs/reference/subagents.html +2 -2
package/dist/docs/reference/tools.html +2 -2
package/dist/docs/scaffolding-agents.html +2 -2
package/dist/docs/storage.html +2 -2
package/dist/docs/troubleshooting.html +2 -2
package/dist/internal/json-dir-store.d.ts +32 -0
package/dist/internal/json-dir-store.d.ts.map +1 -0
package/dist/internal/json-dir-store.js +100 -0
package/dist/playground/assets/index-CjOQ4hN9.css +1 -0
package/dist/playground/assets/{index-DTG9OsPV.js → index-DqXdAFGa.js} +41 -41
package/dist/playground/index.html +2 -2
package/package.json +31 -24
package/src/artifacts.ts +78 -0
package/src/bin/agent-serve.version.test.ts +64 -0
package/src/channels/github/api.test.ts +64 -0
package/src/channels/github/auth.test.ts +105 -0
package/src/channels/github/cursor-account.test.ts +204 -0
package/src/channels/github/forward.test.ts +457 -0
package/src/channels/github/github-channel.ts +19 -2
package/src/channels/github/github.test.ts +985 -0
package/src/channels/github/replay.test.ts +179 -0
package/src/channels/github/types.ts +6 -0
package/src/channels/slack/api.post-message.test.ts +148 -0
package/src/channels/slack/api.ts +3 -1
package/src/channels/slack/approvals.test.ts +328 -0
package/src/channels/slack/block-actions.test.ts +469 -0
package/src/channels/slack/bot-mentions.test.ts +267 -0
package/src/channels/slack/channel-watch.test.ts +363 -0
package/src/channels/slack/cursor-account.test.ts +301 -0
package/src/channels/slack/cursor-account.ts +3 -1
package/src/channels/slack/defaults.final-post.test.ts +182 -0
package/src/channels/slack/dispatch.test.ts +875 -0
package/src/channels/slack/dispatch.ts +12 -1
package/src/channels/slack/eval-directive.test.ts +273 -0
package/src/channels/slack/interactive.ts +3 -0
package/src/channels/slack/message-body.test.ts +54 -0
package/src/channels/slack/nudge-store.test.ts +143 -0
package/src/channels/slack/slack-channel.ts +6 -0
package/src/channels/slack/slack.test.ts +391 -0
package/src/channels/slack/stop.test.ts +23 -0
package/src/channels/slack/thread-context.test.ts +202 -0
package/src/channels/slack/types.ts +6 -0
package/src/evals/assertions.test.ts +617 -0
package/src/evals/assertions.ts +37 -1
package/src/evals/expect.test.ts +144 -0
package/src/evals/judge.test.ts +181 -0
package/src/evals/loaders.test.ts +132 -0
package/src/evals/matchers.test.ts +95 -0
package/src/evals/reporters.test.ts +303 -0
package/src/evals/run-facts.test.ts +259 -0
package/src/evals.ts +1 -0
package/src/index.ts +1 -0
package/src/internal/ab-snapshot.test.ts +325 -0
package/src/internal/approval-gate.test.ts +49 -0
package/src/internal/approvals.integration.test.ts +383 -0
package/src/internal/artifacts-store.test.ts +283 -0
package/src/internal/artifacts-store.ts +290 -0
package/src/internal/authored-loaders.test.ts +31 -0
package/src/internal/builtin-tools/artifacts.test.ts +247 -0
package/src/internal/builtin-tools/artifacts.ts +74 -0
package/src/internal/builtin-tools/index.ts +21 -0
package/src/internal/builtin-tools/reminders.test.ts +201 -0
package/src/internal/channel-route-schema.test.ts +294 -0
package/src/internal/chat-attach.test.ts +262 -0
package/src/internal/cli-deploy.test.ts +1991 -0
package/src/internal/cli-docs.test.ts +161 -0
package/src/internal/cli-mcp.test.ts +789 -0
package/src/internal/cli-skills.test.ts +133 -0
package/src/internal/cli-slack.test.ts +1654 -0
package/src/internal/cli-slack.ts +13 -4
package/src/internal/cloud-merge.test.ts +74 -0
package/src/internal/cron.test.ts +22 -0
package/src/internal/cursor/account-mcp.test.ts +807 -0
package/src/internal/cursor/backend-client.test.ts +591 -0
package/src/internal/cursor/credentials.test.ts +351 -0
package/src/internal/cursor/github-credentials.test.ts +136 -0
package/src/internal/cursor-account-mcp-auth.test.ts +310 -0
package/src/internal/cursor-account.integration.test.ts +441 -0
package/src/internal/cursor-event-relay.test.ts +746 -0
package/src/internal/cursor-github-credentials.integration.test.ts +271 -0
package/src/internal/cursor-slack-relay.test.ts +525 -0
package/src/internal/deploy-source.test.ts +111 -0
package/src/internal/discovery.artifact-tool.test.ts +136 -0
package/src/internal/discovery.artifacts.test.ts +119 -0
package/src/internal/discovery.builtin-tools.test.ts +94 -0
package/src/internal/discovery.concurrency.test.ts +60 -0
package/src/internal/discovery.cursor-account.test.ts +133 -0
package/src/internal/discovery.cwd.test.ts +83 -0
package/src/internal/discovery.hosting.test.ts +80 -0
package/src/internal/discovery.identity.test.ts +44 -0
package/src/internal/discovery.ts +102 -1
package/src/internal/distribution.ts +1 -0
package/src/internal/docs-site.test.ts +66 -0
package/src/internal/duration.test.ts +29 -0
package/src/internal/eval-judge-model.test.ts +187 -0
package/src/internal/eval-run-store.cancel.test.ts +142 -0
package/src/internal/eval-run-store.storage.test.ts +211 -0
package/src/internal/eval-runner.http.test.ts +403 -0
package/src/internal/eval-runner.run.test.ts +928 -0
package/src/internal/evals-client.test.ts +307 -0
package/src/internal/event-mapper.test.ts +243 -0
package/src/internal/github-fanout.test.ts +213 -0
package/src/internal/handleAgentServeTrigger.test.ts +185 -0
package/src/internal/host-kv.test.ts +82 -0
package/src/internal/host-platforms.test.ts +126 -0
package/src/internal/http-channel.test.ts +402 -0
package/src/internal/init-project.test.ts +270 -0
package/src/internal/install-cursor-skills.test.ts +262 -0
package/src/internal/local-env.test.ts +120 -0
package/src/internal/log-ring.test.ts +31 -0
package/src/internal/logs-client.test.ts +350 -0
package/src/internal/mcp-endpoint.test.ts +436 -0
package/src/internal/mcp-host.test.ts +298 -0
package/src/internal/mcp-oauth.test.ts +148 -0
package/src/internal/net.test.ts +17 -0
package/src/internal/peer-connections.test.ts +128 -0
package/src/internal/peer-mcp.integration.test.ts +289 -0
package/src/internal/playground/toolchain.test.ts +53 -0
package/src/internal/playground-cli.test.ts +187 -0
package/src/internal/playground-proxy.test.ts +376 -0
package/src/internal/prompt-context.integration.test.ts +232 -0
package/src/internal/prompt-context.test.ts +127 -0
package/src/internal/reminder-runner.test.ts +432 -0
package/src/internal/reminder-runner.ts +1 -0
package/src/internal/reminder-store.test.ts +53 -0
package/src/internal/request-headers.test.ts +27 -0
package/src/internal/resolve-prod-target.test.ts +787 -0
package/src/internal/resolved-connections.test.ts +295 -0
package/src/internal/router.test.ts +57 -0
package/src/internal/schedule-runner.ts +1 -0
package/src/internal/sdk-runner.test.ts +290 -0
package/src/internal/server.artifacts.test.ts +334 -0
package/src/internal/server.ts +45 -0
package/src/internal/session-engine.artifacts.test.ts +293 -0
package/src/internal/session-engine.coalesce.test.ts +169 -0
package/src/internal/session-engine.concurrency.test.ts +250 -0
package/src/internal/session-engine.host-oauth-mcp.test.ts +110 -0
package/src/internal/session-engine.interrupt.test.ts +577 -0
package/src/internal/session-engine.storage.test.ts +547 -0
package/src/internal/session-engine.ts +129 -1
package/src/internal/session-urls.test.ts +28 -0
package/src/internal/sessions-client.test.ts +518 -0
package/src/internal/storage-coordinator.test.ts +517 -0
package/src/internal/storage-coordinator.ts +62 -0
package/src/internal/tool-call.test.ts +458 -0
package/src/internal/tool-result.test.ts +52 -0
package/src/internal/trajectory.approvals.test.ts +83 -0
package/src/internal/trajectory.subagents.test.ts +198 -0
package/src/internal/turn-governor.test.ts +137 -0
package/src/internal/update-check.test.ts +485 -0
package/src/internal/workspace.test.ts +207 -0
package/src/storage-backends/cursor-hosted.test.ts +121 -0
package/src/storage.ts +6 -0
package/src/types.ts +152 -2
package/dist/docs/assets/chunks/@localSearchIndexroot.CL2Y0Zmh.js +0 -1
package/dist/playground/assets/index-CidizGZv.css +0 -1

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-DTG9OsPV.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-CidizGZv.css">
+    <script type="module" crossorigin src="./assets/index-DqXdAFGa.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-CjOQ4hN9.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -147,6 +147,13 @@
       "import": "./dist/ab.js",
       "default": "./dist/ab.js"
     },
+    "./artifacts": {
+      "anysphere-source": "./src/artifacts.ts",
+      "bun": "./src/artifacts.ts",
+      "types": "./dist/artifacts.d.ts",
+      "import": "./dist/artifacts.js",
+      "default": "./dist/artifacts.js"
+    },
     "./storage": {
       "anysphere-source": "./src/storage.ts",
       "bun": "./src/storage.ts",
@@ -183,24 +190,6 @@
       "default": "./package.json"
     }
   },
-  "scripts": {
-    "build": "tsgo -p tsconfig.build.json && pnpm run build:playground && pnpm run docs:build",
-    "build:playground": "vite build --config playground/vite.config.ts",
-    "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
-    "dev:playground": "vite --config playground/vite.config.ts",
-    "check": "biome check src && tsgo --noEmit && tsgo --noEmit -p playground/tsconfig.json",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs",
-    "fix": "biome check --write --unsafe src",
-    "test": "vitest run --passWithNoTests",
-    "type-check": "tsgo --noEmit && tsgo --noEmit -p playground/tsconfig.json",
-    "build-dev": "echo noop",
-    "build-types": "tsgo -p tsconfig.build.json --emitDeclarationOnly",
-    "verify-publish": "node scripts/verify-publish-artifacts.mjs",
-    "smoke-publish": "node scripts/smoke-publish-artifact.mjs",
-    "publish-check": "pnpm run build && pnpm run verify-publish && pnpm run smoke-publish"
-  },
   "engines": {
     "node": ">=22.13"
   },
@@ -220,14 +209,13 @@
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
-    "@anysphere/ui": "workspace:*",
     "@base-ui/react": "1.4.0",
     "@stylexjs/stylex": "0.18.3",
     "@stylexswc/rs-compiler": "^0.16.4",
     "@tanstack/react-virtual": "3.13.23",
     "@types/js-yaml": "4.0.9",
     "@types/ms": "^2.1.0",
-    "@types/node": "catalog:",
+    "@types/node": "22.14.1",
     "@types/pg": "^8.16.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
@@ -240,10 +228,29 @@
     "react-markdown": "^10.1.0",
     "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
-    "typescript": "catalog:",
+    "typescript": "^5.8.0",
     "vite": "^7.3.0",
     "vitepress": "1.6.4",
     "vitest": "^4.0.18",
-    "zustand": "^5.0.9"
+    "zustand": "^5.0.9",
+    "@anysphere/ui": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json && pnpm run build:playground && pnpm run docs:build",
+    "build:playground": "vite build --config playground/vite.config.ts",
+    "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
+    "dev:playground": "vite --config playground/vite.config.ts",
+    "check": "biome check src && tsgo --noEmit && tsgo --noEmit -p playground/tsconfig.json",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "fix": "biome check --write --unsafe src",
+    "test": "vitest run --passWithNoTests",
+    "type-check": "tsgo --noEmit && tsgo --noEmit -p playground/tsconfig.json",
+    "build-dev": "echo noop",
+    "build-types": "tsgo -p tsconfig.build.json --emitDeclarationOnly",
+    "verify-publish": "node scripts/verify-publish-artifacts.mjs",
+    "smoke-publish": "node scripts/smoke-publish-artifact.mjs",
+    "publish-check": "pnpm run build && pnpm run verify-publish && pnpm run smoke-publish"
   }
-}
+}

package/src/artifacts.ts ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * `defineArtifacts` — authored at `agent/artifacts.ts`.
+ *
+ * Artifacts mark durable outputs the agent produced (reviewed PR URLs,
+ * reports, …) so they can be listed across sessions and rendered in the
+ * playground. Declare artifact *kinds* here; host code tags via
+ * `ctx.artifacts.tag(...)` (tools, hooks, and channel handlers all carry
+ * an {@link ArtifactsApi}), and `agentTool: true` exposes the model-facing
+ * `tag_artifact` built-in tool generated from the same kinds registry.
+ *
+ * ```ts
+ * import { z } from "zod";
+ * import { defineArtifacts } from "@anysphere/agent-serve/artifacts";
+ *
+ * export default defineArtifacts({
+ *   kinds: {
+ *     "reviewed-pr": {
+ *       description: "A pull request this agent reviewed.",
+ *       schema: z.object({ url: z.string(), verdict: z.string() }),
+ *     },
+ *     report: { description: "A generated report." },
+ *   },
+ *   agentTool: true,
+ * });
+ * ```
+ */
+// TODO(artifacts-files): file/blob payloads land on the Agent Stores mount
+// (any files, fuse-mounted everywhere, survives deploys) once it ships —
+// same migration as TODO(agent-stores). Serve via GET
+// /v1/artifacts/:id/content; cloud-runtime tags keep the VM-native
+// /opt/cursor/artifacts + cursor.com artifact URLs.
+import { brandDefinition } from "./internal/brand.js";
+import type { ArtifactsConfig, ArtifactsDefinition } from "./types.js";
+export type {
+  ArtifactKindConfig,
+  ArtifactListFilter,
+  ArtifactRecord,
+  ArtifactSource,
+  ArtifactsApi,
+  ArtifactsConfig,
+  ArtifactsDefinition,
+  ArtifactTagInput,
+} from "./types.js";
+/** Default {@link ArtifactsConfig.max} retention cap. */
+export const ARTIFACTS_DEFAULT_MAX = 1_000;
+export function defineArtifacts(config: ArtifactsConfig): ArtifactsDefinition {
+  for (const [kind, kindConfig] of Object.entries(config.kinds ?? {})) {
+    if (kind.trim() === "") {
+      throw new Error("defineArtifacts: kind names must be non-empty");
+    }
+    if (
+      typeof kindConfig.description !== "string" ||
+      kindConfig.description.trim() === ""
+    ) {
+      throw new Error(
+        `defineArtifacts: kinds.${kind}.description must be a non-empty string`
+      );
+    }
+  }
+  if (config.max !== undefined) {
+    if (!Number.isInteger(config.max) || config.max < 1) {
+      throw new Error("defineArtifacts: max must be a positive integer");
+    }
+  }
+  return brandDefinition("artifacts", config);
+}
+/** Effective retention cap for a config (default {@link ARTIFACTS_DEFAULT_MAX}). */
+export function resolveArtifactsMax(
+  config: ArtifactsConfig | undefined
+): number {
+  return config?.max ?? ARTIFACTS_DEFAULT_MAX;
+}

package/src/bin/agent-serve.version.test.ts ADDED Viewed

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+import { packageVersion } from "../internal/distribution.js";
+const execFileAsync = promisify(execFile);
+const packageRoot = join(import.meta.dirname, "..", "..");
+const tsxBin = join(packageRoot, "node_modules", ".bin", "tsx");
+const cliEntry = join(packageRoot, "src", "bin", "agent-serve.ts");
+async function runCli(
+  args: string[]
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      tsxBin,
+      [cliEntry, ...args],
+      {
+        cwd: packageRoot,
+        timeout: 25_000,
+        env: process.env,
+      }
+    );
+    return { stdout, stderr, code: 0 };
+  } catch (error) {
+    const err = error as {
+      stdout?: string;
+      stderr?: string;
+      code?: number;
+    };
+    return {
+      stdout: err.stdout ?? "",
+      stderr: err.stderr ?? "",
+      code: typeof err.code === "number" ? err.code : 1,
+    };
+  }
+}
+describe("agentkit --version", () => {
+  it("prints `<cli> <package.json version>` for --version, -V, and version", async () => {
+    const pkg = JSON.parse(
+      await readFile(join(packageRoot, "package.json"), "utf8")
+    ) as { version: string };
+    expect(packageVersion()).toBe(pkg.version);
+    for (const arg of ["--version", "-V", "version"] as const) {
+      const { stdout, stderr, code } = await runCli([arg]);
+      expect(code, arg).toBe(0);
+      expect(stderr, arg).toBe("");
+      expect(stdout.trim(), arg).toBe(`agentkit ${pkg.version}`);
+    }
+  }, 30_000);
+  it("mentions version in --help", async () => {
+    const { stdout, code } = await runCli(["--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--version, -V");
+    expect(stdout).toContain("agentkit version");
+    expect(stdout).toContain("agentkit docs");
+    expect(stdout).toContain("npx @cursor/july docs");
+  }, 30_000);
+});

package/src/channels/github/api.test.ts ADDED Viewed

@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createGitHubOctokit } from "./api.js";
+import {
+  createCursorAccountGithubTokenResolver,
+  createPendingCursorGithubCredentials,
+} from "./cursor-account.js";
+describe("createGitHubOctokit", () => {
+  afterEach(() => {
+    delete process.env.GITHUB_TOKEN;
+  });
+  it("resolves lazy credentials for every request on a long-lived client", async () => {
+    const authorizationHeaders: string[] = [];
+    const fetchImpl: typeof fetch = async (input, init) => {
+      const headers =
+        input instanceof Request ? input.headers : new Headers(init?.headers);
+      authorizationHeaders.push(headers.get("authorization") ?? "");
+      return Response.json({ login: "octocat" });
+    };
+    const getToken = vi
+      .fn<() => Promise<string>>()
+      .mockResolvedValueOnce("ghs_first")
+      .mockResolvedValueOnce("ghs_second");
+    const pending = createPendingCursorGithubCredentials();
+    pending.bind(getToken);
+    const octokit = await createGitHubOctokit({
+      api: { fetch: fetchImpl },
+      credentials: {
+        token: createCursorAccountGithubTokenResolver(() => pending.getToken()),
+      },
+    });
+    await octokit.request("GET /user");
+    await octokit.request("GET /user");
+    expect(getToken).toHaveBeenCalledTimes(2);
+    expect(authorizationHeaders).toEqual([
+      "Bearer ghs_first",
+      "Bearer ghs_second",
+    ]);
+  });
+  it("preserves ambient fallback for ordinary lazy credentials", async () => {
+    process.env.GITHUB_TOKEN = "ghp_fallback";
+    const authorizationHeaders: string[] = [];
+    const octokit = await createGitHubOctokit({
+      api: {
+        fetch: async (input, init) => {
+          const headers =
+            input instanceof Request
+              ? input.headers
+              : new Headers(init?.headers);
+          authorizationHeaders.push(headers.get("authorization") ?? "");
+          return Response.json({ login: "octocat" });
+        },
+      },
+      credentials: { token: async () => undefined },
+    });
+    await octokit.request("GET /user");
+    expect(authorizationHeaders).toEqual(["token ghp_fallback"]);
+  });
+});

package/src/channels/github/auth.test.ts ADDED Viewed

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+const execFileMock = vi.hoisted(() => vi.fn());
+const createAppAuthMock = vi.hoisted(() => vi.fn());
+vi.mock("node:child_process", () => ({
+  execFile: execFileMock,
+}));
+vi.mock("@octokit/auth-app", () => ({
+  createAppAuth: createAppAuthMock,
+}));
+import * as auth from "./auth.js";
+function clearAuthEnv(): void {
+  delete process.env.GITHUB_TOKEN;
+  delete process.env.GH_TOKEN;
+  delete process.env.GITHUB_APP_ID;
+  delete process.env.GITHUB_APP_PRIVATE_KEY;
+  delete process.env.GITHUB_APP_INSTALLATION_ID;
+}
+describe("resolveGitHubAccessToken", () => {
+  beforeEach(() => {
+    auth.clearGitHubAuthCaches();
+    execFileMock.mockReset();
+    createAppAuthMock.mockReset();
+    clearAuthEnv();
+  });
+  afterEach(() => {
+    auth.clearGitHubAuthCaches();
+    execFileMock.mockReset();
+    createAppAuthMock.mockReset();
+    clearAuthEnv();
+  });
+  it("prefers App installation tokens over ambient PAT when App creds are set", async () => {
+    process.env.GITHUB_TOKEN = "pat-should-not-win";
+    process.env.GITHUB_APP_ID = "123";
+    process.env.GITHUB_APP_PRIVATE_KEY =
+      "-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----";
+    createAppAuthMock.mockReturnValue(
+      async () => ({ token: "ghs_installation" }) as never
+    );
+    await expect(
+      auth.resolveGitHubAccessToken({ installationId: 42 })
+    ).resolves.toBe("ghs_installation");
+    expect(createAppAuthMock).toHaveBeenCalledOnce();
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+  it("falls back to PAT when App credentials are unset (local testing)", async () => {
+    process.env.GITHUB_TOKEN = "local-pat";
+    await expect(
+      auth.resolveGitHubAccessToken({ installationId: 42 })
+    ).resolves.toBe("local-pat");
+    expect(createAppAuthMock).not.toHaveBeenCalled();
+  });
+  it("uses GITHUB_APP_INSTALLATION_ID for host-scoped App auth", async () => {
+    process.env.GITHUB_APP_ID = "123";
+    process.env.GITHUB_APP_PRIVATE_KEY =
+      "-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----";
+    process.env.GITHUB_APP_INSTALLATION_ID = "99";
+    createAppAuthMock.mockReturnValue(
+      async () => ({ token: "ghs_host" }) as never
+    );
+    await expect(auth.resolveGitHubAccessToken({})).resolves.toBe("ghs_host");
+    expect(createAppAuthMock).toHaveBeenCalledOnce();
+  });
+});
+describe("ensureGhCliTokenEnv", () => {
+  beforeEach(() => {
+    auth.clearGitHubAuthCaches();
+    execFileMock.mockReset();
+    createAppAuthMock.mockReset();
+    clearAuthEnv();
+  });
+  afterEach(() => {
+    auth.clearGitHubAuthCaches();
+    execFileMock.mockReset();
+    createAppAuthMock.mockReset();
+    clearAuthEnv();
+  });
+  it("exports an App installation token as GH_TOKEN for gh CLI", async () => {
+    process.env.GITHUB_APP_ID = "123";
+    process.env.GITHUB_APP_PRIVATE_KEY =
+      "-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----";
+    process.env.GITHUB_APP_INSTALLATION_ID = "99";
+    createAppAuthMock.mockReturnValue(
+      async () => ({ token: "ghs_for_gh" }) as never
+    );
+    await expect(auth.ensureGhCliTokenEnv()).resolves.toBe(true);
+    expect(process.env.GH_TOKEN).toBe("ghs_for_gh");
+  });
+});

package/src/channels/github/cursor-account.test.ts ADDED Viewed

@@ -0,0 +1,204 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createGitHubOctokit } from "./api.js";
+import { resolveCredentialValue } from "./auth.js";
+import {
+  getGithubCursorAccountRuntime,
+  resolveCursorGithubPermissions,
+  resolveCursorGithubProxyUrl,
+} from "./cursor-account.js";
+import { getGitHubChannelOptions, githubChannel } from "./github-channel.js";
+describe("githubChannel({ cursorAccount })", () => {
+  it("binds outbound API auth without rewriting authored cursorAccount options", async () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["Acme/Widgets"], permissions: "read" },
+    });
+    const runtime = getGithubCursorAccountRuntime(definition);
+    expect(runtime?.options.cursorAccount).toEqual({
+      repos: ["Acme/Widgets"],
+      permissions: "read",
+    });
+    expect(runtime?.scope).toEqual({
+      owner: "acme",
+      repos: ["acme/widgets"],
+      permissions: "read",
+    });
+    expect(() => runtime?.credentials.getToken()).toThrow(/has not been bound/);
+    runtime?.credentials.bind(async () => "ghs_cursor_account");
+    await expect(
+      resolveCredentialValue(
+        getGitHubChannelOptions(definition)?.credentials?.token
+      )
+    ).resolves.toBe("ghs_cursor_account");
+  });
+  it("defaults permissions to pr-write on the private scope", () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["acme/widgets"] },
+    });
+    expect(getGithubCursorAccountRuntime(definition)?.scope).toEqual({
+      owner: "acme",
+      repos: ["acme/widgets"],
+      permissions: "pr-write",
+    });
+  });
+  it("allows a webhook secret but rejects separate outbound credentials", () => {
+    expect(() =>
+      githubChannel({
+        cursorAccount: true,
+        credentials: { webhookSecret: "signing-secret" },
+      })
+    ).not.toThrow();
+    expect(() =>
+      githubChannel({
+        cursorAccount: true,
+        credentials: { token: "ghp_dedicated" },
+      })
+    ).toThrow(/cannot be combined/);
+    expect(() =>
+      githubChannel({
+        cursorAccount: true,
+        credentials: { appId: 1, privateKey: "pem" },
+      })
+    ).toThrow(/cannot be combined/);
+  });
+  it("rejects an empty inline repository scope", () => {
+    expect(() => githubChannel({ cursorAccount: { repos: [] } })).toThrow(
+      /require at least one repository/
+    );
+  });
+  it.each([
+    [["acme/widgets", "other/tools"], /must share one owner/],
+    [["https://github.com/acme/widgets"], /expected owner\/repo/],
+    [
+      Array.from({ length: 21 }, (_, index) => `acme/repo-${index}`),
+      /at most 20 repositories/,
+    ],
+  ])("rejects an unsupported repository scope", (repos, error) => {
+    expect(() => githubChannel({ cursorAccount: { repos } })).toThrow(error);
+  });
+  it("treats cursorAccount false as disabled", () => {
+    expect(
+      getGithubCursorAccountRuntime(githubChannel({ cursorAccount: false }))
+    ).toBeUndefined();
+  });
+  it("accepts contents-write permissions on the private scope", () => {
+    const definition = githubChannel({
+      cursorAccount: {
+        repos: ["acme/widgets"],
+        permissions: "contents-write",
+      },
+    });
+    expect(getGithubCursorAccountRuntime(definition)?.scope?.permissions).toBe(
+      "contents-write"
+    );
+  });
+});
+describe("resolveCursorGithubPermissions", () => {
+  it("escalates to the most privileged requested tier", () => {
+    expect(resolveCursorGithubPermissions(["read", "pr-write"])).toBe(
+      "pr-write"
+    );
+    expect(
+      resolveCursorGithubPermissions(["read", "contents-write", "pr-write"])
+    ).toBe("contents-write");
+  });
+});
+describe("cursor-account GitHub proxy mode", () => {
+  afterEach(() => {
+    delete process.env.AGENT_SERVE_GITHUB_PROXY_URL;
+  });
+  function captureFetch(): {
+    fetchImpl: typeof fetch;
+    requests: { url: string; headers: Headers }[];
+  } {
+    const requests: { url: string; headers: Headers }[] = [];
+    const fetchImpl: typeof fetch = async (input, init) => {
+      requests.push({
+        url: input instanceof Request ? input.url : String(input),
+        headers:
+          input instanceof Request ? input.headers : new Headers(init?.headers),
+      });
+      return Response.json({ id: 1 });
+    };
+    return { fetchImpl, requests };
+  }
+  it("resolves the proxy URL from the backend base URL or env override", () => {
+    expect(resolveCursorGithubProxyUrl("https://api.cursor.com")).toBe(
+      "https://api.cursor.com/v0/github-proxy"
+    );
+    process.env.AGENT_SERVE_GITHUB_PROXY_URL =
+      "https://backend.local:8000/v0/github-proxy/";
+    expect(resolveCursorGithubProxyUrl("https://api.cursor.com")).toBe(
+      "https://backend.local:8000/v0/github-proxy"
+    );
+  });
+  it("routes channel Octokit calls to the bound proxy with scope headers", async () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["acme/widgets"], permissions: "pr-write" },
+    });
+    const runtime = getGithubCursorAccountRuntime(definition);
+    runtime?.credentials.bind(async () => "crsr_api_key");
+    runtime?.credentials.bindProxyTransport({
+      apiBaseUrl: "https://api.cursor.com/v0/github-proxy",
+      headers: {
+        "x-cursor-github-repos": "acme/widgets",
+        "x-cursor-github-permissions": "pr-write",
+      },
+    });
+    const { fetchImpl, requests } = captureFetch();
+    const octokit = await createGitHubOctokit({
+      api: { fetch: fetchImpl },
+      credentials: getGitHubChannelOptions(definition)?.credentials,
+    });
+    await octokit.request("GET /repos/{owner}/{repo}", {
+      owner: "acme",
+      repo: "widgets",
+    });
+    expect(requests).toHaveLength(1);
+    const { url, headers } = requests[0]!;
+    expect(url).toBe(
+      "https://api.cursor.com/v0/github-proxy/repos/acme/widgets"
+    );
+    expect(headers.get("authorization")).toBe("Bearer crsr_api_key");
+    expect(headers.get("x-cursor-github-repos")).toBe("acme/widgets");
+    expect(headers.get("x-cursor-github-permissions")).toBe("pr-write");
+  });
+  it("keeps raw-token mode when no proxy transport is bound", async () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["acme/widgets"] },
+    });
+    getGithubCursorAccountRuntime(definition)?.credentials.bind(
+      async () => "ghs_raw"
+    );
+    const { fetchImpl, requests } = captureFetch();
+    const octokit = await createGitHubOctokit({
+      api: { fetch: fetchImpl },
+      credentials: getGitHubChannelOptions(definition)?.credentials,
+    });
+    await octokit.request("GET /repos/{owner}/{repo}", {
+      owner: "acme",
+      repo: "widgets",
+    });
+    const { url, headers } = requests[0]!;
+    expect(url).toBe("https://api.github.com/repos/acme/widgets");
+    expect(headers.get("authorization")).toBe("Bearer ghs_raw");
+    expect(headers.get("x-cursor-github-repos")).toBeNull();
+  });
+});