@cursor/july 0.1.1 → 0.1.2

package/docs/storage.md

@@ -0,0 +1,98 @@
+---
+title: "Storage"
+description: "Point agentkit's durable storage at a backend you own with defineStorage."
+---
+
+# Storage
+
+agentkit owns durable storage for sessions, continuation tokens,
+reminders, playground eval history, and live A/B samples. It chooses the
+keys (under `agentkit/v1/`), when to read and write, and how to restore
+after restart.
+
+Keys have bounded length: caller-controlled segments (channel ids,
+continuation tokens) are URI-encoded, and any segment past 256 encoded
+bytes is replaced by its `sha256:…` digest — deterministically, so writes
+and lookups always agree. Backends can rely on this instead of imposing
+their own key-length caps (which would silently drop writes, since a
+throwing `put` is at-most-once).
+
+By default that storage lives under `--state-root` on local disk. Fine
+for one machine; it does not survive replacing the host.
+
+To keep the same framework storage across hosts, plug in a key-value
+backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
+`list`. agentkit does the rest.
+
+```ts
+// agent/storage.ts
+import { defineStorage } from "@cursor/july/storage";
+
+export default defineStorage({
+  put: (key, value) => db.upsert(key, value),
+  get: (key) => db.get(key),
+  delete: (key) => db.delete(key),
+  list: (prefix) => db.listByPrefix(prefix), // [{ key, value }], key order
+});
+```
+
+> [!NOTE]
+> Import paths here use `@cursor/july/storage`. On projects still
+> using `@anysphere/agent-serve`, swap the import. See
+> [Run the CLI](./README.md#run-the-cli) for the full rename table.
+
+## Which methods to provide
+
+| Method | Required | Role |
+| --- | --- | --- |
+| `put` | Yes | Write or update a value |
+| `get` | For restore | Look up one key |
+| `list` | For restore | Return entries under a prefix, in key order |
+| `delete` | For cleanup | Remove a key |
+
+A throwing `put` is logged and dropped. It never fails a turn. When
+resolving a missing continuation token, a throwing `get` fails the
+follow-up so a store outage does not open a new session. Return
+`undefined` only for a real miss.
+
+## Policy
+
+Two knobs change behavior:
+
+```ts
+export default defineStorage({
+  policy: {
+    // Batch event writes while the session is busy (default: once per turn)
+    debounceMs: 30_000,
+    // Cap how much loads at serve start, or "off" to restore on demand
+    restore: { maxSessions: 500 },
+  },
+  // put / get / delete / list …
+});
+```
+
+| Knob | Default | Meaning |
+| --- | --- | --- |
+| `debounceMs` | unset (once per turn) | Wait this long after activity before writing event batches |
+| `restore` | caps below | How much to load at serve start |
+| `restore.maxSessions` | `1000` | Max sessions loaded at serve start |
+| `restore.maxAgeMs` | 30 days | Skip older sessions at serve start |
+| `restore.maxTotalBytes` | 1 GiB | Stop loading once this budget is reached |
+
+Set `restore: "off"` on high-traffic hosts. Sessions then load when a
+follow-up arrives instead of at startup.
+
+## Restore after restart
+
+With `get` and `list`, serve can rebuild local state from your store:
+
+- At startup, agentkit loads recent sessions up to the restore caps.
+  Local disk wins when both sides have the same session. Reminders
+  hydrate the same way into `--state-root/reminders`.
+- On demand, a missing continuation token resolves through the store
+  and resumes that session.
+- Playground eval history and A/B aggregates can load from the same
+  sink.
+
+A turn in flight at crash time is not replayed. The next follow-up
+resumes from the last flushed state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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": {
@@ -117,6 +117,13 @@
       "import": "./dist/ab.js",
       "default": "./dist/ab.js"
     },
+    "./storage": {
+      "anysphere-source": "./src/storage.ts",
+      "bun": "./src/storage.ts",
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js",
+      "default": "./dist/storage.js"
+    },
     "./package.json": {
       "anysphere-source": "./package.json",
       "bun": "./package.json",

package/skills/github/SKILL.md

@@ -20,7 +20,8 @@ import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channel
 
 export default githubChannel({
   botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
-  credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+  cursorAccount: { repos: ["owner/repo"] }, // permissions?: "read" | "pr-write" | "contents-write"
+
   onPullRequest: (ctx, pr) =>
     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
   onCheckSuite: (ctx, suite) =>
@@ -44,6 +45,13 @@ the model should reason about the event.
 
 ## Auth modes
 
+- **`cursorAccount`** → the signed-in Cursor principal supplies both the SCM
+  event stream and a short-lived, repo-scoped GitHub credential. It works in
+  local dev (`agentkit login`) and hosted deployments (`CURSOR_API_KEY`).
+  `ctx.github`, `ctx.host.github`, and child `gh` commands share the lease.
+  Use `{ repos: ["owner/repo"] }`, or `true` with `serve --cursor-events
+  --repo owner/repo`. One host credential covers up to 20 repositories under
+  one GitHub owner; it cannot span owners.
 - **Secret set** → route auth is `allowAll()` + `X-Hub-Signature-256`
   verification before parsing; the HMAC becomes the request principal.
 - **No secret** → `localDevStrict()` (loopback only) — except under

package/src/bin/agent-serve.ts

@@ -31,6 +31,18 @@ import {
   cmdRun,
   cmdTrajectory,
 } from "../internal/cli-ax.js";
+import {
+  cmdDeploy,
+  cmdDeploymentStatus,
+  cmdDeployments,
+  cmdRotatePodCredential,
+  cmdRotateToken,
+  cmdSecretsList,
+  cmdSecretsSet,
+  cmdSecretsUnset,
+  cmdStop,
+  type DeployCliOptions,
+} from "../internal/cli-deploy.js";
 import { CLI_COMMAND_NAME as CLI } from "../internal/distribution.js";
 import { runSession } from "../internal/run-client.js";
 import { formatTrajectoryText } from "../internal/trajectory.js";
@@ -60,6 +72,17 @@ Usage:
   ${CLI} login       [--api-key <key>] [--key-name <name>]
   ${CLI} logout
   ${CLI} whoami      [--json]
+  ${CLI} deploy      [--dir <path>] [--slug <slug>] [--team <id>] [--json]
+                          [--no-wait] [--repo <url>] [--ref <ref>]
+                          [--path <agentPath>] [--cursor-events-repo <owner/name>]...
+                          [--allow-domain <domain>]...
+  ${CLI} deployments [--team <id>] [--json]
+  ${CLI} deployment  <slug> [--team <id>] [--json]
+  ${CLI} stop        <slug> [--team <id>] [--json] [--no-wait]
+  ${CLI} rotate-token <slug> [--team <id>]
+  ${CLI} rotate-pod-credential <slug> [--team <id>]
+  ${CLI} secrets     set <slug> NAME[=VALUE]... | list <slug> | unset <slug> NAME
+                          [--team <id>] [--json]
   ${CLI} slack       <subcommand> …
   ${CLI} github      <subcommand> …
 
@@ -86,6 +109,20 @@ Commands:
               inference, cloud runtime, and cursorAccount MCP connections.
   logout      Remove the stored Cursor credentials.
   whoami      Show which Cursor account powers this host (and why).
+  deploy      Deploy onto Cursor's managed agent-serve hosting, then wait for
+              the engine to come up. First deploy of a slug prints the alias
+              token exactly once — save it.
+  deployments List the team's deployments (slug, status, generation, kind).
+  deployment  Show one deployment in full (status, lastError, engine info).
+  stop        Stop a deployment and wait until it reports stopped.
+  rotate-token Mint a new alias token for a deployment (shown once); the old
+              token stops working immediately.
+  rotate-pod-credential
+              Rotate a deployment's pod credential (prints the masked key);
+              the running pod keeps the old one until the next deploy.
+  secrets     Manage deployment secrets: set (upsert by name; NAMEs without
+              =VALUE are prompted for with hidden input, or read from piped
+              stdin), list (names + createdAt; never values), unset.
   slack       Slack channel pack: init, manifests, doctor (see slack help).
   github      GitHub webhook pack: forward live deliveries, events, doctor
               (wraps \`gh webhook forward\`; see github help).
@@ -120,6 +157,10 @@ Options:
                      connections (defineConnection({ agent })) on cloud-runtime
                      turns; local turns always use loopback.
   --no-schedules     Disable the cron runner outside dev mode.
+  --team             deploy/deployments/deployment/stop/rotate-token: Cursor
+                     team id. Defaults to the account's team when it has one.
+  --no-wait          deploy/stop: return right after the request is accepted
+                     instead of polling until a terminal status.
   --no-playground    Disable the bundled web playground at /playground (also skips
                      auto-build / HMR).
   --no-docs          Disable the documentation site at /docs (also skips its
@@ -150,6 +191,15 @@ Options:
   --repo             serve --cursor-events: repo to subscribe to (repeatable).
                      github forward: owner/repo to forward from (inferred from
                      the git remote when omitted; last wins).
+                     deploy: https git repo URL the control plane builds from.
+  --ref              deploy: git ref to build (defaults to the repo's default
+                     branch server-side).
+  --path             deploy: agent directory relative to the repo root.
+  --cursor-events-repo  deploy: repo (owner/name) whose SCM events the
+                     deployed engine pulls (repeatable).
+  --allow-domain     deploy: egress domain the engine pod may reach
+                     (repeatable; unioned with hosting.egressDomains from the
+                     agent manifest). Repo-backed deploys only.
   --org              github forward: organization login (org-level hooks).
   --channel          github: select one channel id when several are declared.
   --secret           github forward: webhook signing secret (defaults to
@@ -233,6 +283,12 @@ async function main(argv: string[]): Promise<number> {
       comment: { type: "string" },
       "dry-run": { type: "boolean", default: false },
       out: { type: "string" },
+      team: { type: "string" },
+      "no-wait": { type: "boolean", default: false },
+      ref: { type: "string" },
+      path: { type: "string" },
+      "cursor-events-repo": { type: "string", multiple: true },
+      "allow-domain": { type: "string", multiple: true },
     },
   });
   const dir = values.dir ?? ".";
@@ -317,6 +373,69 @@ async function main(argv: string[]): Promise<number> {
       return cmdWhoami({ json: values.json });
     }
 
+    case "deploy": {
+      // `--repo` is repeatable for `serve --cursor-events`; deploy targets a
+      // single source repo, so the last one wins.
+      const repo = values.repo?.at(-1);
+      return cmdDeploy({
+        ...deployOptionsFromValues(values),
+        dir,
+        ...(values.slug === undefined ? {} : { slug: values.slug }),
+        ...(repo === undefined ? {} : { repo }),
+        ...(values.ref === undefined ? {} : { ref: values.ref }),
+        ...(values.path === undefined ? {} : { path: values.path }),
+        ...(values["cursor-events-repo"] === undefined
+          ? {}
+          : { cursorEventsRepos: values["cursor-events-repo"] }),
+        ...(values["allow-domain"] === undefined
+          ? {}
+          : { allowDomains: values["allow-domain"] }),
+      });
+    }
+
+    case "deployments": {
+      return cmdDeployments(deployOptionsFromValues(values));
+    }
+
+    case "deployment": {
+      return cmdDeploymentStatus(
+        positionals[0],
+        deployOptionsFromValues(values)
+      );
+    }
+
+    case "stop": {
+      return cmdStop(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "rotate-token": {
+      return cmdRotateToken(positionals[0], deployOptionsFromValues(values));
+    }
+
+    case "rotate-pod-credential": {
+      return cmdRotatePodCredential(
+        positionals[0],
+        deployOptionsFromValues(values)
+      );
+    }
+
+    case "secrets": {
+      const base = deployOptionsFromValues(values);
+      switch (positionals[0]) {
+        case "set":
+          return cmdSecretsSet(positionals[1], positionals.slice(2), base);
+        case "list":
+          return cmdSecretsList(positionals[1], base);
+        case "unset":
+          return cmdSecretsUnset(positionals[1], positionals[2], base);
+        default:
+          process.stderr.write(
+            `Usage: ${CLI} secrets <set|list|unset> <slug> ... [--team <id>] [--json]\n`
+          );
+          return 1;
+      }
+    }
+
     case "run": {
       const messages = await loadMessages(
         values.message,
@@ -511,6 +630,12 @@ async function main(argv: string[]): Promise<number> {
         )
       );
       lines.push(section("hooks", info.hooks));
+      lines.push(
+        section("hosting egress domains", info.hosting?.egressDomains ?? [])
+      );
+      lines.push(
+        section("hosting secret names", info.hosting?.secretNames ?? [])
+      );
       if (info.diagnostics.length > 0) {
         lines.push(`\ndiagnostics:\n${formatDiagnostics(info.diagnostics)}`);
       }
@@ -646,6 +771,20 @@ async function main(argv: string[]): Promise<number> {
   }
 }
 
+function deployOptionsFromValues(values: {
+  team?: string;
+  json?: boolean;
+  "no-wait"?: boolean;
+  "api-key"?: string;
+}): DeployCliOptions {
+  return {
+    ...(values.team === undefined ? {} : { team: values.team }),
+    json: values.json === true,
+    noWait: values["no-wait"] === true,
+    ...(values["api-key"] === undefined ? {} : { apiKey: values["api-key"] }),
+  };
+}
+
 function axFromOptions(
   partial: Partial<AxCliOptions> & { dir: string }
 ): AxCliOptions {

package/src/channels/github/api.ts

@@ -17,6 +17,10 @@ import {
   resolveGitHubInstallationId,
   resolveGitHubPrivateKey,
 } from "./auth.js";
+import {
+  type CursorAccountGithubTokenResolver,
+  isCursorAccountGithubTokenResolver,
+} from "./cursor-account.js";
 import type { GitHubChannelCredentials } from "./types.js";
 
 export type GitHubJsonObject = Record<string, unknown>;
@@ -91,19 +95,31 @@ export async function createGitHubOctokit(input: {
   credentials?: GitHubChannelCredentials;
   installationId?: number;
 }): Promise<Octokit> {
-  const requestOptions =
-    input.api?.fetch === undefined ? undefined : { fetch: input.api.fetch };
-  const baseUrl = input.api?.apiBaseUrl;
+  const transport = githubOctokitTransport(input.api);
+
+  const dynamicToken: CursorAccountGithubTokenResolver | undefined =
+    isCursorAccountGithubTokenResolver(input.credentials?.token)
+      ? input.credentials.token
+      : isCursorAccountGithubTokenResolver(input.credentials?.installationToken)
+        ? input.credentials.installationToken
+        : undefined;
+  if (dynamicToken !== undefined) {
+    const octokit = new Octokit(transport);
+    octokit.hook.before("request", async (request) => {
+      const token = await resolveCredentialValue(dynamicToken);
+      if (token === undefined) {
+        throw new Error("githubChannel: dynamic GitHub token is unavailable.");
+      }
+      request.headers.authorization = `Bearer ${token}`;
+    });
+    return octokit;
+  }
 
   const explicit =
     (await resolveCredentialValue(input.credentials?.token)) ??
     (await resolveCredentialValue(input.credentials?.installationToken));
   if (explicit !== undefined) {
-    return new Octokit({
-      auth: explicit,
-      ...(baseUrl === undefined ? {} : { baseUrl }),
-      ...(requestOptions === undefined ? {} : { request: requestOptions }),
-    });
+    return new Octokit({ ...transport, auth: explicit });
   }
 
   const installationId = await resolveGitHubInstallationId(
@@ -118,26 +134,34 @@ export async function createGitHubOctokit(input: {
       input.credentials?.privateKey
     );
     return new Octokit({
+      ...transport,
       authStrategy: createAppAuth,
       auth: {
         appId,
         privateKey,
         installationId,
       },
-      ...(baseUrl === undefined ? {} : { baseUrl }),
-      ...(requestOptions === undefined ? {} : { request: requestOptions }),
     });
   }
 
   // Local testing: ambient PAT / `gh auth token` when App creds are unset.
-  const token = await resolveGitHubAccessToken(input);
   return new Octokit({
-    auth: token,
-    ...(baseUrl === undefined ? {} : { baseUrl }),
-    ...(requestOptions === undefined ? {} : { request: requestOptions }),
+    ...transport,
+    auth: await resolveGitHubAccessToken(input),
   });
 }
 
+/** Shared `baseUrl` / custom `fetch` for every Octokit constructed here. */
+function githubOctokitTransport(api: GitHubApiOptions | undefined): {
+  baseUrl?: string;
+  request?: { fetch: typeof fetch };
+} {
+  return {
+    baseUrl: api?.apiBaseUrl,
+    request: api?.fetch === undefined ? undefined : { fetch: api.fetch },
+  };
+}
+
 /**
  * Call a GitHub REST path with channel auth. Prefer typed Octokit methods via
  * {@link createGitHubOctokit} / `ctx.github.getOctokit()` when possible.
@@ -152,15 +176,10 @@ export async function callGitHubApi<T = unknown>(input: {
   options?: { auth?: boolean; headers?: Readonly<Record<string, string>> };
 }): Promise<GitHubApiResponse<T>> {
   if (input.options?.auth === false) {
-    const octokit = new Octokit({
-      ...(input.api?.apiBaseUrl === undefined
-        ? {}
-        : { baseUrl: input.api.apiBaseUrl }),
-      ...(input.api?.fetch === undefined
-        ? {}
-        : { request: { fetch: input.api.fetch } }),
-    });
-    return requestWithOctokit(octokit, input);
+    return requestWithOctokit(
+      new Octokit(githubOctokitTransport(input.api)),
+      input
+    );
   }
 
   const octokit = await createGitHubOctokit({

package/src/channels/github/cursor-account.ts

@@ -0,0 +1,165 @@
+/**
+ * Cursor-account mode for GitHub channels.
+ *
+ * The channel declares the intent at definition time. The serve host binds
+ * this placeholder to its signed-in Cursor account after it resolves the
+ * repository scope into private runtime metadata (never by rewriting the
+ * authored `cursorAccount` options object).
+ */
+
+import type { GitHubChannelOptions } from "./types.js";
+
+export const CURSOR_GITHUB_MAX_REPOS = 20;
+const CURSOR_GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const cursorAccountTokenResolvers = new WeakSet<object>();
+
+/** Least → most privilege. Host mints one lease at the max requested tier. */
+export const CURSOR_GITHUB_PERMISSIONS = [
+  "read",
+  "pr-write",
+  "contents-write",
+] as const;
+
+export type CursorGithubPermissions =
+  (typeof CURSOR_GITHUB_PERMISSIONS)[number];
+
+export interface CursorGithubRepoScope {
+  owner: string;
+  repos: readonly string[];
+  permissions: CursorGithubPermissions;
+}
+
+export type CursorAccountGithubTokenResolver = () => Promise<string>;
+
+export interface PendingCursorGithubCredentials {
+  bind(getToken: () => Promise<string>): void;
+  getToken(): Promise<string>;
+}
+
+export interface GithubCursorAccountRuntime {
+  /** Authored channel options (not rewritten). */
+  options: GitHubChannelOptions;
+  credentials: PendingCursorGithubCredentials;
+  /**
+   * Normalized repo + permissions scope when `cursorAccount` is an object.
+   * Absent for `cursorAccount: true` (scope comes from serve `--repo`).
+   */
+  scope: CursorGithubRepoScope | undefined;
+}
+
+const runtimeByDefinition = new WeakMap<object, GithubCursorAccountRuntime>();
+
+export function parseCursorGithubPermissions(
+  value: unknown,
+  fallback: CursorGithubPermissions = "pr-write"
+): CursorGithubPermissions {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (value === "read" || value === "pr-write" || value === "contents-write") {
+    return value;
+  }
+  throw new Error(
+    'Cursor account GitHub permissions must be "read", "pr-write", or "contents-write".'
+  );
+}
+
+export function parseCursorGithubRepoScope(
+  values: readonly string[],
+  permissions: CursorGithubPermissions = "pr-write"
+): CursorGithubRepoScope {
+  const repos = [
+    ...new Set(values.map((repo) => repo.trim().toLowerCase()).filter(Boolean)),
+  ];
+  if (repos.length === 0) {
+    throw new Error(
+      "Cursor account GitHub credentials require at least one repository."
+    );
+  }
+  if (repos.length > CURSOR_GITHUB_MAX_REPOS) {
+    throw new Error(
+      `Cursor account GitHub credentials support at most ${CURSOR_GITHUB_MAX_REPOS} repositories.`
+    );
+  }
+  for (const repo of repos) {
+    if (!CURSOR_GITHUB_REPO_PATTERN.test(repo) || repo.includes("..")) {
+      throw new Error(
+        `Invalid Cursor account GitHub repository "${repo}"; expected owner/repo.`
+      );
+    }
+  }
+  const owner = repos[0]?.split("/", 1)[0];
+  if (owner === undefined) {
+    throw new Error("Cursor account GitHub repository owner is missing.");
+  }
+  if (repos.some((repo) => repo.split("/", 1)[0] !== owner)) {
+    throw new Error(
+      "Cursor account GitHub repositories must share one owner for a single installation token."
+    );
+  }
+  return {
+    owner,
+    repos,
+    permissions: parseCursorGithubPermissions(permissions),
+  };
+}
+
+/** One host credential: the most privileged requested tier wins. */
+export function resolveCursorGithubPermissions(
+  values: readonly CursorGithubPermissions[]
+): CursorGithubPermissions {
+  let max: CursorGithubPermissions = "read";
+  for (const value of values) {
+    if (
+      CURSOR_GITHUB_PERMISSIONS.indexOf(value) >
+      CURSOR_GITHUB_PERMISSIONS.indexOf(max)
+    ) {
+      max = value;
+    }
+  }
+  return values.length === 0 ? "pr-write" : max;
+}
+
+export function createCursorAccountGithubTokenResolver(
+  getToken: () => Promise<string>
+): CursorAccountGithubTokenResolver {
+  const resolver = () => getToken();
+  cursorAccountTokenResolvers.add(resolver);
+  return resolver;
+}
+
+export function isCursorAccountGithubTokenResolver(
+  value: unknown
+): value is CursorAccountGithubTokenResolver {
+  return typeof value === "function" && cursorAccountTokenResolvers.has(value);
+}
+
+export function createPendingCursorGithubCredentials(): PendingCursorGithubCredentials {
+  let getBoundToken: (() => Promise<string>) | undefined;
+  return {
+    bind(getToken) {
+      getBoundToken = getToken;
+    },
+    getToken() {
+      if (getBoundToken === undefined) {
+        throw new Error(
+          "githubChannel({ cursorAccount: true }) has not been bound to a signed-in Cursor host."
+        );
+      }
+      return getBoundToken();
+    },
+  };
+}
+
+export function registerGithubCursorAccountRuntime(
+  definition: object,
+  runtime: GithubCursorAccountRuntime
+): void {
+  runtimeByDefinition.set(definition, runtime);
+}
+
+export function getGithubCursorAccountRuntime(
+  definition: object
+): GithubCursorAccountRuntime | undefined {
+  return runtimeByDefinition.get(definition);
+}