npm - @cursor/july - Versions diffs - 0.1.61 → 0.1.68 - Mend

@cursor/july 0.1.61 → 0.1.68

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 (196) hide show

package/dist/bin/agent-serve.js +8 -0
package/dist/channels/github/github-channel.d.ts +1 -1
package/dist/channels/github/github-channel.d.ts.map +1 -1
package/dist/channels/github/github-channel.js +14 -1
package/dist/channels/github/types.d.ts +2 -0
package/dist/channels/github/types.d.ts.map +1 -1
package/dist/channels/slack/channel-watch.d.ts +2 -1
package/dist/channels/slack/channel-watch.d.ts.map +1 -1
package/dist/channels/slack/channel-watch.js +7 -3
package/dist/channels/slack/dispatch.d.ts +9 -0
package/dist/channels/slack/dispatch.d.ts.map +1 -1
package/dist/channels/slack/dispatch.js +41 -21
package/dist/channels/slack/manifest.d.ts.map +1 -1
package/dist/channels/slack/manifest.js +1 -0
package/dist/channels/slack/nudge-store.d.ts +16 -0
package/dist/channels/slack/nudge-store.d.ts.map +1 -1
package/dist/channels/slack/nudge-store.js +53 -0
package/dist/channels/slack/slack-channel.d.ts.map +1 -1
package/dist/channels/slack/slack-channel.js +4 -1
package/dist/channels/slack/types.d.ts +22 -5
package/dist/channels/slack/types.d.ts.map +1 -1
package/dist/docs/404.html +2 -2
package/dist/docs/ab.html +3 -3
package/dist/docs/assets/{app.CW3KJh72.js → app.C5XUTCw9.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.DvUR3lv9.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.Bk6EWpPj.js → VPLocalSearchBox.CGDTAYHY.js} +1 -1
package/dist/docs/assets/chunks/{theme.Bz9AodBA.js → theme.lPixh250.js} +2 -2
package/dist/docs/assets/{reference_connections.md.CSQiNzre.js → reference_connections.md.Bwswbm6H.js} +13 -3
package/dist/docs/assets/{reference_connections.md.CSQiNzre.lean.js → reference_connections.md.Bwswbm6H.lean.js} +1 -1
package/dist/docs/assets/{reference_tools.md.kJfJAP2m.js → reference_tools.md.Wmvb7Lob.js} +2 -2
package/dist/docs/assets/{reference_tools.md.kJfJAP2m.lean.js → reference_tools.md.Wmvb7Lob.lean.js} +1 -1
package/dist/docs/building-with-agents.html +3 -3
package/dist/docs/concepts.html +3 -3
package/dist/docs/deployment.html +3 -3
package/dist/docs/evals.html +3 -3
package/dist/docs/example-agents/approval-buddy.html +3 -3
package/dist/docs/example-agents/benny.html +3 -3
package/dist/docs/example-agents/bugbot.html +3 -3
package/dist/docs/example-agents/codebase-wiki.html +3 -3
package/dist/docs/example-agents/codeowners-review.html +3 -3
package/dist/docs/example-agents/concierge.html +3 -3
package/dist/docs/example-agents/fsd.html +3 -3
package/dist/docs/example-agents/index.html +3 -3
package/dist/docs/example-agents/knowledge-base.html +3 -3
package/dist/docs/example-agents/oncall.html +3 -3
package/dist/docs/example-agents/security-reviewer.html +3 -3
package/dist/docs/example-agents/slack-agent.html +3 -3
package/dist/docs/example-agents/weather-agent.html +3 -3
package/dist/docs/guides/agent-to-agent.html +3 -3
package/dist/docs/guides/cloud-runtime.html +3 -3
package/dist/docs/guides/convert-automation.html +3 -3
package/dist/docs/guides/github.html +3 -3
package/dist/docs/guides/human-in-the-loop.html +3 -3
package/dist/docs/guides/mcp-oauth.html +3 -3
package/dist/docs/guides/opentelemetry.html +3 -3
package/dist/docs/guides/slack.html +3 -3
package/dist/docs/guides/webhooks.html +3 -3
package/dist/docs/hashmap.json +1 -1
package/dist/docs/hillclimbing.html +3 -3
package/dist/docs/index.html +3 -3
package/dist/docs/quickstart.html +3 -3
package/dist/docs/reference/agent-config.html +3 -3
package/dist/docs/reference/artifacts.html +3 -3
package/dist/docs/reference/channels.html +3 -3
package/dist/docs/reference/cli.html +3 -3
package/dist/docs/reference/connections.html +15 -5
package/dist/docs/reference/hooks.html +3 -3
package/dist/docs/reference/http-api.html +3 -3
package/dist/docs/reference/instructions.html +3 -3
package/dist/docs/reference/playground.html +3 -3
package/dist/docs/reference/project-layout.html +3 -3
package/dist/docs/reference/prompt.html +3 -3
package/dist/docs/reference/schedules.html +3 -3
package/dist/docs/reference/sessions.html +3 -3
package/dist/docs/reference/skills.html +3 -3
package/dist/docs/reference/subagents.html +3 -3
package/dist/docs/reference/tools.html +5 -5
package/dist/docs/scaffolding-agents.html +3 -3
package/dist/docs/storage.html +3 -3
package/dist/docs/templates/agentic-owners.html +3 -3
package/dist/docs/templates/demo.html +3 -3
package/dist/docs/templates/pr-autofixer.html +3 -3
package/dist/docs/templates/security-reviewer.html +3 -3
package/dist/docs/templates/triage.html +3 -3
package/dist/docs/troubleshooting.html +3 -3
package/dist/files-backends/agent-store-presigned-url.js +1 -1
package/dist/index.d.ts +2 -2
package/dist/index.d.ts.map +1 -1
package/dist/index.js +1 -1
package/dist/internal/advertise-tools.d.ts +74 -0
package/dist/internal/advertise-tools.d.ts.map +1 -0
package/dist/internal/advertise-tools.js +152 -0
package/dist/internal/cli-deploy.d.ts.map +1 -1
package/dist/internal/cli-deploy.js +11 -3
package/dist/internal/cli-manifest.d.ts +19 -0
package/dist/internal/cli-manifest.d.ts.map +1 -0
package/dist/internal/cli-manifest.js +49 -0
package/dist/internal/cli-slack.d.ts.map +1 -1
package/dist/internal/cli-slack.js +9 -1
package/dist/internal/cursor-agent-template.d.ts +9 -0
package/dist/internal/cursor-agent-template.d.ts.map +1 -0
package/dist/internal/cursor-agent-template.js +37 -0
package/dist/internal/cursor-event-relay.d.ts +5 -1
package/dist/internal/cursor-event-relay.d.ts.map +1 -1
package/dist/internal/cursor-event-relay.js +5 -0
package/dist/internal/deploy-client.d.ts +8 -0
package/dist/internal/deploy-client.d.ts.map +1 -1
package/dist/internal/deploy-client.js +21 -3
package/dist/internal/deploy-manifest.d.ts +85 -0
package/dist/internal/deploy-manifest.d.ts.map +1 -0
package/dist/internal/deploy-manifest.js +106 -0
package/dist/internal/deployment-scm-event-stream.d.ts +113 -0
package/dist/internal/deployment-scm-event-stream.d.ts.map +1 -0
package/dist/internal/deployment-scm-event-stream.js +460 -0
package/dist/internal/discovery.d.ts.map +1 -1
package/dist/internal/discovery.js +69 -0
package/dist/internal/init-project.d.ts.map +1 -1
package/dist/internal/init-project.js +5 -17
package/dist/internal/mcp-host.d.ts +18 -0
package/dist/internal/mcp-host.d.ts.map +1 -1
package/dist/internal/mcp-host.js +41 -5
package/dist/internal/mcp-oauth.d.ts +0 -4
package/dist/internal/mcp-oauth.d.ts.map +1 -1
package/dist/internal/mcp-oauth.js +0 -4
package/dist/internal/sdk-runner.d.ts +1 -1
package/dist/internal/sdk-runner.d.ts.map +1 -1
package/dist/internal/sdk-runner.js +36 -13
package/dist/internal/server.d.ts.map +1 -1
package/dist/internal/server.js +20 -2
package/dist/internal/session-engine.d.ts +66 -0
package/dist/internal/session-engine.d.ts.map +1 -1
package/dist/internal/session-engine.js +430 -110
package/dist/internal/shallow-clone.d.ts +115 -0
package/dist/internal/shallow-clone.d.ts.map +1 -0
package/dist/internal/shallow-clone.js +292 -0
package/dist/internal/slack-provision-client.d.ts +2 -0
package/dist/internal/slack-provision-client.d.ts.map +1 -1
package/dist/internal/slack-provision-client.js +1 -0
package/dist/internal/turn-lease-store.d.ts +44 -0
package/dist/internal/turn-lease-store.d.ts.map +1 -0
package/dist/internal/turn-lease-store.js +139 -0
package/dist/internal/workspace.d.ts +12 -0
package/dist/internal/workspace.d.ts.map +1 -1
package/dist/internal/workspace.js +28 -0
package/dist/playground/assets/index-CoL7xCJl.css +1 -0
package/dist/playground/assets/index-yxs1heea.js +85 -0
package/dist/playground/index.html +2 -2
package/dist/storage-protocol.d.ts +122 -0
package/dist/storage-protocol.d.ts.map +1 -0
package/dist/storage-protocol.js +173 -0
package/dist/storage.d.ts +2 -72
package/dist/storage.d.ts.map +1 -1
package/dist/storage.js +2 -82
package/dist/types.d.ts +114 -4
package/dist/types.d.ts.map +1 -1
package/docs/reference/connections.md +80 -0
package/docs/reference/tools.md +14 -0
package/package.json +4 -2
package/skills/github/SKILL.md +2 -1
package/src/bin/agent-serve.ts +9 -0
package/src/channels/github/github-channel.ts +18 -2
package/src/channels/github/types.ts +2 -0
package/src/channels/slack/channel-watch.ts +6 -3
package/src/channels/slack/dispatch.ts +40 -3
package/src/channels/slack/manifest.ts +1 -0
package/src/channels/slack/nudge-store.ts +56 -0
package/src/channels/slack/slack-channel.ts +3 -0
package/src/channels/slack/types.ts +22 -5
package/src/index.ts +5 -0
package/src/internal/advertise-tools.ts +229 -0
package/src/internal/cli-deploy.ts +22 -1
package/src/internal/cli-manifest.ts +63 -0
package/src/internal/cli-slack.ts +10 -1
package/src/internal/cursor-agent-template.ts +46 -0
package/src/internal/cursor-event-relay.ts +8 -1
package/src/internal/deploy-client.ts +35 -6
package/src/internal/deploy-manifest.ts +167 -0
package/src/internal/deployment-scm-event-stream.ts +577 -0
package/src/internal/discovery.ts +85 -0
package/src/internal/init-project.ts +11 -20
package/src/internal/mcp-host.ts +66 -9
package/src/internal/mcp-oauth.ts +0 -4
package/src/internal/sdk-runner.ts +50 -11
package/src/internal/server.ts +21 -2
package/src/internal/session-engine.ts +385 -19
package/src/internal/shallow-clone.ts +407 -0
package/src/internal/slack-provision-client.ts +3 -0
package/src/internal/turn-lease-store.ts +147 -0
package/src/internal/workspace.ts +27 -0
package/src/storage-protocol.ts +247 -0
package/src/storage.ts +16 -110
package/src/types.ts +118 -4
package/templates/pr-autofixer/agent/lib/drive-schemas.ts +4 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.BuymfBAo.js +0 -1
package/dist/playground/assets/index-ClbuaLpm.css +0 -1
package/dist/playground/assets/index-SqkR13k_.js +0 -85

package/src/internal/shallow-clone.ts ADDED Viewed

@@ -0,0 +1,407 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, rmSync } from "node:fs";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Shallow GitHub PR checkout for SDK agents that review a PR's code.
+ *
+ * Mirrors Bugbot's `shallow_fetch` prefetch strategy
+ * (`backend/crates/napi_bugbot/src/temp_clone.rs`): instead of cloning the
+ * whole repository, run a single `git fetch --depth=1 --no-tags origin <head>
+ * <merge_base>` into a fresh checkout so the agents get the PR head working
+ * tree (plus the merge-base commit for `git diff baseSha headSha`) with one
+ * bounded network round-trip. Bugbot keeps a bare `--filter=tree:0` partial
+ * clone because its tools stream objects on demand; SDK agents read a real
+ * working tree, so we materialize the head checkout instead.
+ *
+ * Auth also mirrors Bugbot's provider model (`IGitProvider.getAccessToken`
+ * → token handed straight to git): the clone takes one explicit repo-scoped
+ * bearer token. The default source is the serve host's Cursor-account
+ * GitHub lease — the same backend `GithubAccessService` mint Bugbot uses —
+ * which `CursorGithubCredentialProvider` installs as `GH_TOKEN` for child
+ * processes. Where Bugbot embeds the token in the clone URL, this module
+ * serves it through an inline credential helper that reads a child-process
+ * env var, so the token never lands in argv or in `.git/config` inside a
+ * working tree that untrusted PR code later executes in.
+ *
+ * INTERNAL: first-party host plumbing shared by agents in `factory/*` (e.g.
+ * the security reviewer's `prepare_review` stage). Consumed via relative
+ * source imports, following `tenant-mcp/run-mcp-registry.ts`.
+ */
+export type ShallowPrCheckout = {
+  /** Directory containing the PR head working tree (detached at headSha). */
+  checkoutDir: string;
+  headSha: string;
+  /** True when the merge-base commit was also fetched (enables local diffs). */
+  baseFetched: boolean;
+  /** How the head commit was obtained. */
+  headSource: "sha_fetch" | "pr_ref_fetch";
+};
+/** Repo-scoped bearer for git-over-HTTPS (installation token or PAT). */
+export type ShallowCloneAuth = {
+  token: string;
+};
+/**
+ * Default clone credential: the serve host's Cursor-account GitHub lease.
+ * `CursorGithubCredentialProvider` mints it repo-scoped from the backend and
+ * keeps `GH_TOKEN` refreshed for child processes; `GITHUB_TOKEN` covers
+ * local/CI runs that export the conventional variable instead.
+ */
+export function serveHostGithubAuth(
+  env: NodeJS.ProcessEnv = process.env
+): ShallowCloneAuth | undefined {
+  const token = (env.GH_TOKEN ?? env.GITHUB_TOKEN ?? "").trim();
+  return token === "" ? undefined : { token };
+}
+function logShallowClone(
+  message: string,
+  fields: Record<string, string | number | boolean | undefined> = {}
+): void {
+  const suffix = Object.entries(fields)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `${key}=${String(value)}`)
+    .join(" ");
+  process.stderr.write(
+    `[shallow-clone] ${message}${suffix ? ` ${suffix}` : ""}\n`
+  );
+}
+function errorSummary(error: unknown): string {
+  return error instanceof Error
+    ? (error.message.split("\n")[0] ?? String(error))
+    : String(error);
+}
+/**
+ * Single-line git failure: the invoked git args (without the credential
+ * config noise) plus the first meaningful stderr line — the actual git
+ * diagnostic (auth, ref, network) — so fallback reasons surfaced to tool
+ * results say why, not just what ran.
+ */
+function gitError(args: string[], error: unknown): Error {
+  const stderr = (error as { stderr?: unknown }).stderr;
+  const detail =
+    typeof stderr === "string"
+      ? stderr
+          .split("\n")
+          .map((line) => line.trim())
+          .find((line) => line.length > 0)
+      : error instanceof Error
+        ? (error.message.split("\n")[0] ?? String(error))
+        : String(error);
+  return new Error(`git ${args.join(" ")} failed — ${detail}`);
+}
+/**
+ * The one credential helper git may use: serve the caller-provided token
+ * from the child process env at request time. The shell reads
+ * `$SHALLOW_CLONE_GIT_TOKEN` when git asks, keeping the token out of argv.
+ */
+const TOKEN_CREDENTIAL_HELPER =
+  '!f() { test "$1" = get && printf "username=x-access-token\\npassword=$SHALLOW_CLONE_GIT_TOKEN\\n"; }; f';
+async function git(
+  cwd: string,
+  args: string[],
+  auth?: ShallowCloneAuth
+): Promise<string> {
+  // Async on purpose: fetches/checkouts of large repos take minutes, and the
+  // serve host runs the clone in-process. A synchronous git call blocks the
+  // event loop for the whole clone, freezing /v1/health and session streams
+  // long enough for the platform's probe budget to replace the engine.
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      [
+        ...(auth === undefined
+          ? []
+          : ["-c", `credential.helper=${TOKEN_CREDENTIAL_HELPER}`]),
+        ...args,
+      ],
+      {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 32 * 1024 * 1024,
+        env: {
+          ...process.env,
+          // Hermetic git: ignore global/system config so host-provisioned
+          // credential rewrites (`url.https://x-access-token:<token>@github
+          // .com/.insteadOf` entries scoped to a *different* repo, as cloud
+          // VMs bake in) cannot hijack auth away from the explicit token,
+          // and no ambient credential helpers run against PR-author input.
+          GIT_CONFIG_GLOBAL: "/dev/null",
+          GIT_CONFIG_SYSTEM: "/dev/null",
+          GIT_TERMINAL_PROMPT: "0",
+          ...(auth === undefined
+            ? {}
+            : { SHALLOW_CLONE_GIT_TOKEN: auth.token }),
+        },
+      }
+    );
+    return stdout;
+  } catch (error) {
+    throw gitError(args, error);
+  }
+}
+async function revParse(cwd: string, rev: string): Promise<string | undefined> {
+  try {
+    const sha = (
+      await git(cwd, ["rev-parse", "--verify", `${rev}^{commit}`])
+    ).trim();
+    return sha === "" ? undefined : sha;
+  } catch {
+    return undefined;
+  }
+}
+const FETCH_ARGS = ["fetch", "--depth=1", "--no-tags", "--quiet", "origin"];
+/**
+ * Create a fresh shallow checkout of a GitHub PR head at `checkoutDir`.
+ *
+ * Fetch order (both single depth-1 round-trips):
+ * 1. Fetch `headSha` (and `baseSha` when known) directly — GitHub advertises
+ *    `allow-reachable-sha1-in-want`, and this pins the exact reviewed commit
+ *    the way Bugbot's `shallow_fetch` does.
+ * 2. Fall back to `refs/pull/<n>/head`, verifying it still resolves to
+ *    `headSha` so the working tree cannot silently drift from the pinned
+ *    patch in the review bundle.
+ *
+ * A missing merge-base commit is non-fatal (agents still have the pinned
+ * patch text in their prompt); a missing head checkout throws.
+ */
+export async function createShallowPrCheckout(args: {
+  /** `owner/name`. */
+  repo: string;
+  prNumber?: number | undefined;
+  headSha: string;
+  /** Merge-base SHA; fetched too so `git diff baseSha headSha` works locally. */
+  baseSha?: string | undefined;
+  checkoutDir: string;
+  /** Clone credential; required for GitHub remotes, unused for file fixtures. */
+  auth?: ShallowCloneAuth | undefined;
+  /** Test seam: clone from this URL instead of `https://github.com/<repo>.git`. */
+  remoteUrl?: string | undefined;
+}): Promise<ShallowPrCheckout> {
+  const { repo, prNumber, headSha, baseSha, checkoutDir, auth } = args;
+  const startedAt = Date.now();
+  logShallowClone("cloning PR head", { repo, prNumber, headSha, baseSha });
+  rmSync(checkoutDir, { recursive: true, force: true });
+  mkdirSync(checkoutDir, { recursive: true });
+  await git(checkoutDir, ["init", "--quiet"]);
+  await git(checkoutDir, [
+    "remote",
+    "add",
+    "origin",
+    args.remoteUrl ?? `https://github.com/${repo}.git`,
+  ]);
+  const shaFetch = async (): Promise<void> => {
+    const extraBase =
+      baseSha === undefined || baseSha === headSha ? [] : [baseSha];
+    try {
+      await git(checkoutDir, [...FETCH_ARGS, headSha, ...extraBase], auth);
+    } catch (error) {
+      if (extraBase.length === 0) {
+        throw error;
+      }
+      // The merge-base SHA may have aged out of reachability; the head commit
+      // is the part the review cannot proceed without, so retry it alone.
+      logShallowClone("combined sha fetch failed; retrying head sha alone", {
+        repo,
+        headSha,
+        baseSha,
+        error: errorSummary(error),
+      });
+      await git(checkoutDir, [...FETCH_ARGS, headSha], auth);
+    }
+  };
+  let headSource: ShallowPrCheckout["headSource"];
+  let shaFetchError: string | undefined;
+  try {
+    await shaFetch();
+    headSource = "sha_fetch";
+  } catch (error) {
+    shaFetchError = errorSummary(error);
+    if (prNumber === undefined) {
+      throw new Error(
+        `Shallow SHA fetch failed for ${repo}@${headSha} and no PR number is available for a ref fallback: ${shaFetchError}`
+      );
+    }
+    logShallowClone("sha fetch failed; falling back to PR head ref", {
+      repo,
+      prNumber,
+      headSha,
+      error: shaFetchError,
+    });
+    const prRef = `refs/pull/${prNumber}/head`;
+    await git(
+      checkoutDir,
+      [...FETCH_ARGS, `+${prRef}:refs/remotes/origin/pr/${prNumber}/head`],
+      auth
+    );
+    const fetchedSha = await revParse(
+      checkoutDir,
+      `refs/remotes/origin/pr/${prNumber}/head`
+    );
+    if (fetchedSha !== headSha) {
+      throw new Error(
+        `Shallow PR ref fetch for ${repo}#${prNumber} resolved to ${fetchedSha ?? "nothing"}, expected pinned head ${headSha} (sha fetch error: ${shaFetchError})`
+      );
+    }
+    headSource = "pr_ref_fetch";
+  }
+  if ((await revParse(checkoutDir, headSha)) === undefined) {
+    throw new Error(
+      `Shallow fetch completed but head commit ${headSha} is missing from ${checkoutDir}`
+    );
+  }
+  logShallowClone("fetch complete; materializing working tree", {
+    repo,
+    headSha,
+    fetchMs: Date.now() - startedAt,
+  });
+  await git(checkoutDir, ["checkout", "--quiet", "--detach", headSha]);
+  let baseFetched =
+    baseSha !== undefined &&
+    (await revParse(checkoutDir, baseSha)) !== undefined;
+  if (baseSha !== undefined && baseSha !== headSha && !baseFetched) {
+    // Best-effort: local diffs are nice-to-have, the pinned patch in the
+    // prompt is the authoritative delta either way.
+    try {
+      await git(checkoutDir, [...FETCH_ARGS, baseSha], auth);
+      baseFetched = (await revParse(checkoutDir, baseSha)) !== undefined;
+    } catch (error) {
+      logShallowClone("merge-base fetch failed; continuing without it", {
+        repo,
+        baseSha,
+        error: errorSummary(error),
+      });
+    }
+  }
+  logShallowClone("checkout ready", {
+    repo,
+    prNumber,
+    headSha,
+    baseSha,
+    headSource,
+    baseFetched,
+    durationMs: Date.now() - startedAt,
+    checkoutDir,
+  });
+  return { checkoutDir, headSha, baseFetched, headSource };
+}
+/** True for `https://github.com/<owner>/<repo>/pull/<n>` URLs. */
+export function isGithubPrUrl(prUrl: string): boolean {
+  try {
+    const url = new URL(prUrl);
+    const parts = url.pathname.split("/").filter(Boolean);
+    return (
+      url.hostname === "github.com" &&
+      parts.length >= 4 &&
+      parts[2] === "pull" &&
+      Number.isInteger(Number(parts[3]))
+    );
+  } catch {
+    return false;
+  }
+}
+export type TryShallowPrCheckoutOptions = {
+  /** PR URL; only GitHub PR URLs are cloned (others skip). */
+  prUrl: string;
+  /** `owner/name`. */
+  repo: string;
+  prNumber?: number | undefined;
+  /** Pinned head SHA; skipped (undefined result) when unknown. */
+  headSha?: string | undefined;
+  /** Merge-base SHA; fetched too so `git diff baseSha headSha` works locally. */
+  baseSha?: string | undefined;
+  checkoutDir: string;
+  /** Clone credential; defaults to {@link serveHostGithubAuth}. */
+  auth?: ShallowCloneAuth | undefined;
+  /** Test seam: clone from this URL instead of `https://github.com/<repo>.git`. */
+  remoteUrl?: string | undefined;
+};
+export type TryShallowPrCheckoutResult = {
+  /** Set when the shallow checkout succeeded. */
+  checkout?: ShallowPrCheckout;
+  /**
+   * Why there is no checkout: a skip gate or the clone failure's first error
+   * line. Callers surface this in their own results/logs so the reason is
+   * visible on hosts that do not capture this module's stderr.
+   */
+  fallbackReason?: string;
+};
+/**
+ * Best-effort shallow PR checkout for hosts whose SDK agents should read the
+ * reviewed repo instead of the host's own checkout.
+ *
+ * Returns no checkout — leaving the caller on its fallback working
+ * directory — when the PR is not on GitHub (e.g. Origin PRs, where the host
+ * checkout is the reviewed repo), when no head SHA is pinned, when no clone
+ * credential is available, or when the clone fails; `fallbackReason` says
+ * which. Failures are logged, never thrown: agents still have the pinned
+ * patch in their prompts, so a missing checkout degrades quality rather
+ * than the run.
+ */
+export async function tryCreateShallowPrCheckout(
+  options: TryShallowPrCheckoutOptions
+): Promise<TryShallowPrCheckoutResult> {
+  const { prUrl, repo, prNumber, headSha, baseSha, checkoutDir, remoteUrl } =
+    options;
+  if (remoteUrl === undefined && !isGithubPrUrl(prUrl)) {
+    logShallowClone("skipped: not a GitHub PR URL", { prUrl });
+    return { fallbackReason: "skipped: not a GitHub PR URL" };
+  }
+  if (headSha === undefined) {
+    logShallowClone("skipped: no pinned head SHA", { repo, prUrl });
+    return { fallbackReason: "skipped: no pinned head SHA" };
+  }
+  const auth = options.auth ?? serveHostGithubAuth();
+  if (remoteUrl === undefined && auth === undefined) {
+    // Fail fast instead of letting an unauthenticated fetch 404/hang: real
+    // GitHub clones need the serve host's lease (or an explicit token).
+    logShallowClone("skipped: no GitHub clone credential", { repo, prUrl });
+    return {
+      fallbackReason:
+        "skipped: no GitHub clone credential (serve host GH_TOKEN lease not installed)",
+    };
+  }
+  try {
+    return {
+      checkout: await createShallowPrCheckout({
+        repo,
+        prNumber,
+        headSha,
+        baseSha,
+        checkoutDir,
+        auth,
+        remoteUrl,
+      }),
+    };
+  } catch (error) {
+    const reason = errorSummary(error);
+    logShallowClone("failed; caller falls back to host checkout", {
+      repo,
+      prNumber,
+      headSha,
+      error: reason,
+    });
+    return { fallbackReason: `clone failed: ${reason}` };
+  }
+}

package/src/internal/slack-provision-client.ts CHANGED Viewed

@@ -192,6 +192,7 @@ const wizardPollResponseSchema = z
     status: z.string(),
     appId: z.string().optional(),
     oauthAuthorizeUrl: z.string().optional(),
+    approvalRequest: z.string().optional(),
     error: z.string().optional(),
     localEnv: z
       .object({
@@ -216,6 +217,8 @@ export interface SlackWizardPollResult {
   status: string;
   appId?: string;
   oauthAuthorizeUrl?: string;
+  /** "pending" means the admin-approval request is already in Slack's queue. */
+  approvalRequest?: string;
   error?: string;
   localEnv?: { botToken: string; appToken?: string };
   localEnvClaimed?: boolean;

package/src/internal/turn-lease-store.ts ADDED Viewed

@@ -0,0 +1,147 @@
+/**
+ * Durable per-session turn ownership: `activeTurns` is in-memory, so servers
+ * sharing a state root would otherwise both run the same session.
+ *
+ * Exclusion, staleness and liveness refresh come from `proper-lockfile`, which
+ * the monorepo already uses for the git cache. Hand-rolling them means
+ * inferring that a process died — timeouts, heartbeats, and a takeover path
+ * that has to stay atomic while removing another owner's claim. That is where
+ * the subtle races live, and none of it is specific to turns.
+ *
+ * Liveness is lock age, not pid: containers have separate PID namespaces.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import * as lockfile from "proper-lockfile";
+/** A held turn lease. Releasing is idempotent. */
+export interface TurnLease {
+  release(): Promise<void>;
+}
+/** Reject path traversal; session ids are opaque strings from the caller. */
+function safeKey(sessionId: string): string {
+  const sanitized = sessionId
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^\.+/, "")
+    .replace(/\.+/g, "_")
+    .slice(0, 180);
+  return sanitized === "" ? "_empty" : sanitized;
+}
+interface HeldLock {
+  release: () => Promise<void>;
+  /** The coalesce drain nests turns, so the same session is acquired twice. */
+  refs: number;
+}
+export class TurnLeaseStore {
+  private readonly dir: string;
+  private readonly staleMs: number;
+  /** Locks this process holds. Their release closures cannot live on disk. */
+  private readonly held = new Map<string, HeldLock>();
+  constructor(dir: string, options: { ttlMs?: number } = {}) {
+    this.dir = dir;
+    // Several refreshes, so a slow owner is not mistaken for a dead one.
+    this.staleMs = options.ttlMs ?? 30_000;
+  }
+  private path(sessionId: string): string {
+    return join(this.dir, `${safeKey(sessionId)}.lease`);
+  }
+  /**
+   * Undefined when another process holds this session and is still refreshing.
+   *
+   * `onCompromised` fires when the lock is lost mid-turn — the owner stalled
+   * past the stale window and a successor took over. No lease scheme can stop
+   * that; the callback is how the displaced turn learns to stand down instead
+   * of answering alongside its successor.
+   */
+  async acquire(
+    sessionId: string,
+    onCompromised?: () => void
+  ): Promise<TurnLease | undefined> {
+    const existing = this.held.get(sessionId);
+    if (existing !== undefined) {
+      existing.refs += 1;
+      return this.handle(sessionId);
+    }
+    await mkdir(this.dir, { recursive: true });
+    let release: () => Promise<void>;
+    try {
+      release = await lockfile.lock(this.path(sessionId), {
+        realpath: false,
+        retries: 0,
+        stale: this.staleMs,
+        // How often the library refreshes the lock's mtime while we hold it.
+        update: 5_000,
+        onCompromised: () => {
+          this.held.delete(sessionId);
+          onCompromised?.();
+        },
+      });
+    } catch {
+      // Held elsewhere, or the store is unusable. Either way this process must
+      // not run the turn: coalescing costs latency, two servers on one session
+      // costs the conversation.
+      return undefined;
+    }
+    this.held.set(sessionId, { release, refs: 1 });
+    return this.handle(sessionId);
+  }
+  private handle(sessionId: string): TurnLease {
+    let released = false;
+    return {
+      release: async () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        const lock = this.held.get(sessionId);
+        if (lock === undefined) {
+          return;
+        }
+        lock.refs -= 1;
+        if (lock.refs > 0) {
+          return;
+        }
+        this.held.delete(sessionId);
+        // Throws if the lock was already compromised, which is not our problem
+        // to solve here: the successor owns it.
+        await lock.release().catch(() => {});
+      },
+    };
+  }
+  /** Graceful shutdown: drop every claim so a successor need not wait it out. */
+  async releaseAll(): Promise<void> {
+    for (const [sessionId, lock] of [...this.held]) {
+      this.held.delete(sessionId);
+      await lock.release().catch(() => {});
+    }
+  }
+  /**
+   * The session is running in another server process. Mirrors the engine's
+   * in-memory `isTurnRunning`, which only ever sees this process.
+   */
+  async runningElsewhere(sessionId: string): Promise<boolean> {
+    if (this.held.has(sessionId)) {
+      return false;
+    }
+    try {
+      return await lockfile.check(this.path(sessionId), {
+        realpath: false,
+        stale: this.staleMs,
+      });
+    } catch {
+      return false;
+    }
+  }
+}

package/src/internal/workspace.ts CHANGED Viewed

@@ -7,6 +7,7 @@
  * all of this up natively through its project setting source.
  */
+import { execFile } from "node:child_process";
 import {
   chmod,
   copyFile,
@@ -19,6 +20,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
 import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
 import { MEMORY_DIR_NAME } from "../memory.js";
 import type {
@@ -29,6 +31,8 @@ import type {
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
 import { buildIdentitySection } from "./prompt-context.js";
+const execFileAsync = promisify(execFile);
 export interface MaterializeWorkspaceOptions {
   agent: ResolvedAgent;
   workspaceDir: string;
@@ -268,6 +272,29 @@ export async function isNestedInGitRepo(dir: string): Promise<boolean> {
   return false;
 }
+/**
+ * Give a session workspace its own git root so the harness roots *there*
+ * rather than at the enclosing repo (see {@link isNestedInGitRepo}). Without
+ * it the harness reads the outer repo's `.cursor/hooks.json`, rules, skills
+ * and `mcp.json`, and never sees the ones written into this workspace —
+ * instructions have an inline fallback, hooks have none.
+ *
+ * Best effort: a workspace that already has `.git` (a borrowed checkout or
+ * worktree) is left alone, and a failed `git init` leaves the harness where
+ * it already was.
+ */
+export async function ensureOwnGitRoot(dir: string): Promise<boolean> {
+  if (!(await isNestedInGitRepo(dir))) {
+    return false;
+  }
+  try {
+    await execFileAsync("git", ["init", "--quiet"], { cwd: dir });
+    return true;
+  } catch {
+    return false;
+  }
+}
 export async function materializeWorkspace(
   options: MaterializeWorkspaceOptions
 ): Promise<void> {