@cursor/july 0.1.1 → 0.1.3

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);
+}

package/src/channels/github/github-channel.ts

@@ -23,6 +23,13 @@ import {
   type GitHubBindingConfig,
   type GitHubBindingState,
 } from "./binding.js";
+import {
+  createCursorAccountGithubTokenResolver,
+  createPendingCursorGithubCredentials,
+  type PendingCursorGithubCredentials,
+  parseCursorGithubRepoScope,
+  registerGithubCursorAccountRuntime,
+} from "./cursor-account.js";
 import { buildDefaultGitHubEvents } from "./defaults.js";
 import { deriveGitHubWebhookEvents, GITHUB_CHANNEL_KIND } from "./events.js";
 import {
@@ -581,9 +588,36 @@ export function getGitHubChannelOptions(
 export function githubChannel(
   options: GitHubChannelOptions = {}
 ): ChannelDefinition<GitHubChannelState> {
+  const usesCursorAccount =
+    options.cursorAccount === true || typeof options.cursorAccount === "object";
+  // Normalized scope lives on the private runtime — never rewrite authored
+  // `cursorAccount` on the options object the author passed in.
+  const cursorScope =
+    typeof options.cursorAccount === "object"
+      ? parseCursorGithubRepoScope(
+          options.cursorAccount.repos,
+          options.cursorAccount.permissions
+        )
+      : undefined;
+
+  let cursorCredentials: PendingCursorGithubCredentials | undefined;
+  let credentials = options.credentials;
+  if (usesCursorAccount) {
+    if (hasDedicatedGitHubApiCredentials(options)) {
+      throw new Error(
+        "githubChannel({ cursorAccount: true }) cannot be combined with token or GitHub App credentials."
+      );
+    }
+    const pending = createPendingCursorGithubCredentials();
+    cursorCredentials = pending;
+    credentials = {
+      ...options.credentials,
+      token: createCursorAccountGithubTokenResolver(() => pending.getToken()),
+    };
+  }
+
   const routePath = options.path ?? "/";
-  const webhookSecret =
-    options.credentials?.webhookSecret ?? envWebhookSecret();
+  const webhookSecret = credentials?.webhookSecret ?? envWebhookSecret();
   // With a secret the HMAC is the request auth (allowAll). Without one, prod
   // stays loopback-strict; dev admits unsigned deliveries from a loopback peer
   // only (loopbackGitHubDev) — not the LAN. Admits `gh webhook forward`
@@ -607,8 +641,12 @@ export function githubChannel(
             ),
         ]);
 
+  const channelOptions: GitHubChannelOptions = {
+    ...options,
+    credentials,
+  };
   const events: ChannelEventHandlers<GitHubChannelState> = {
-    ...buildDefaultGitHubEvents({ ...options }),
+    ...buildDefaultGitHubEvents({ ...channelOptions }),
     ...options.events,
   };
 
@@ -618,7 +656,7 @@ export function githubChannel(
     events,
     meta: {
       kind: GITHUB_CHANNEL_KIND,
-      githubWebhookEvents: deriveGitHubWebhookEvents(options),
+      githubWebhookEvents: deriveGitHubWebhookEvents(channelOptions),
     },
     onStart: options.onStart,
     onStop: options.onStop,
@@ -630,14 +668,36 @@ export function githubChannel(
         bodySchema: z.unknown(),
         description: "GitHub webhook ingress",
         handler: async (request, args) =>
-          handleGitHubWebhookRequest({ options, request, args }),
+          handleGitHubWebhookRequest({
+            options: channelOptions,
+            request,
+            args,
+          }),
       }),
     ],
   });
-  githubChannelOptionsByDefinition.set(definition, options);
+  githubChannelOptionsByDefinition.set(definition, channelOptions);
+  if (cursorCredentials !== undefined) {
+    registerGithubCursorAccountRuntime(definition, {
+      options,
+      credentials: cursorCredentials,
+      scope: cursorScope,
+    });
+  }
   return definition;
 }
 
+function hasDedicatedGitHubApiCredentials(
+  options: GitHubChannelOptions
+): boolean {
+  return (
+    options.credentials?.token !== undefined ||
+    options.credentials?.installationToken !== undefined ||
+    options.credentials?.appId !== undefined ||
+    options.credentials?.privateKey !== undefined
+  );
+}
+
 async function handlePullRequest(input: {
   options: GitHubChannelOptions;
   bindingConfig: GitHubBindingConfig;

package/src/channels/github/index.ts

@@ -6,8 +6,8 @@
  *
  * export default githubChannel({
  *   botName: "my-agent",
- *   // API auth: App installation (preferred) → GITHUB_TOKEN / GH_TOKEN → `gh auth`
- *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+ *   // Reuses `agentkit login` for events, ctx.github, ctx.host.github, and gh.
+ *   cursorAccount: { repos: ["owner/repo"] },
  *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
  *   onPullRequest: (ctx, pr) =>
  *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,

package/src/channels/github/types.ts

@@ -421,6 +421,25 @@ export interface GitHubChannelOptions {
    * API calls prefer App installation tokens, then local PAT / `gh auth`.
    */
   credentials?: GitHubChannelCredentials;
+  /**
+   * Use the signed-in Cursor account's GitHub connection for inbound events
+   * and outbound API calls. `true` takes repository scope from
+   * `serve --cursor-events --repo`; `{ repos }` makes the channel self-contained.
+   * `permissions` chooses the minted token tier (`"pr-write"` default).
+   * Cannot be combined with explicit token or GitHub App credentials.
+   */
+  cursorAccount?:
+    | boolean
+    | {
+        repos: readonly string[];
+        /**
+         * Token capability tier:
+         * - `"read"` — PR/issue/status read
+         * - `"pr-write"` (default) — comments / PR+issue write, no `contents:write`
+         * - `"contents-write"` — also push code (host-held; prefer only when needed)
+         */
+        permissions?: "read" | "pr-write" | "contents-write";
+      };
   /** Optional GitHub API transport overrides (`apiBaseUrl`, `fetch`). */
   api?: GitHubApiOptions;
   /**

package/src/channels/slack/slack-channel.ts

@@ -54,13 +54,24 @@ import {
   startSlackSocketMode,
 } from "./socket-mode.js";
 import { buildToolApprovalEvents } from "./tool-approval-events.js";
-import type { SlackChannelOptions, SlackChannelState } from "./types.js";
+import {
+  assertSlackCursorAgentName,
+  type SlackChannelOptions,
+  type SlackChannelState,
+  type SlackCursorAgentName,
+} from "./types.js";
 
 /**
  * Create a Slack channel. Author as `agent/channels/slack.ts` default export.
+ *
+ * When `cursorAccount` is on, `agentName` must be a single token (no
+ * whitespace) — string literals with spaces fail at the type level;
+ * runtime values are still checked by {@link assertSlackCursorAgentName}.
  */
-export function slackChannel(
-  options: SlackChannelOptions = {}
+export function slackChannel<const Name extends string = string>(
+  options: Omit<SlackChannelOptions, "agentName"> & {
+    agentName?: SlackCursorAgentName<Name>;
+  } = {}
 ): ChannelDefinition<SlackChannelState> {
   const cursorAccount = options.cursorAccount === true;
   if (cursorAccount) {
@@ -71,6 +82,9 @@ export function slackChannel(
         "slackChannel({ cursorAccount: true }) uses the Cursor account's Slack connection — do not also set credentials/envPrefix. Author a second slack channel file for a dedicated Slack app."
       );
     }
+    if (options.agentName !== undefined) {
+      assertSlackCursorAgentName(options.agentName);
+    }
     // Channel watching is Socket Mode only — cursorAccount agents must be
     // explicitly addressed (@mention, DM, or claimed-thread reply).
     if (options.engagement?.channelPosts !== undefined) {

package/src/channels/slack/types.ts

@@ -210,6 +210,46 @@ export interface SlackEngagementOptions {
   channelPosts?: SlackChannelPostsOptions;
 }
 
+/**
+ * Whitespace forbidden in {@link SlackChannelOptions.agentName}. The Cursor
+ * Slack router matches on leading words; multi-word names collide with Named
+ * Agent shortened-prefix matching (`Approval …` stealing `ApprovalBuddy`).
+ */
+type SlackAgentNameWhitespace = " " | "\t" | "\n" | "\r" | "\f" | "\v";
+
+/**
+ * Single-token Cursor Slack handle for `cursorAccount` routing
+ * (`@Cursor <name> …`). String literals that contain whitespace become
+ * `never` (type error at the call site); plain `string` stays `string` and
+ * is still rejected at runtime by {@link assertSlackCursorAgentName}.
+ */
+export type SlackCursorAgentName<S extends string = string> = string extends S
+  ? string
+  : S extends `${string}${SlackAgentNameWhitespace}${string}`
+    ? never
+    : S;
+
+const SLACK_CURSOR_AGENT_NAME_WHITESPACE = /\s/;
+
+/**
+ * Runtime guard for {@link SlackChannelOptions.agentName}. Call from
+ * `slackChannel({ cursorAccount: true })` construction and serve-time
+ * name resolution so derived defaults cannot sneak spaces in.
+ */
+export function assertSlackCursorAgentName(name: string): void {
+  const trimmed = name.trim();
+  if (trimmed.length === 0) {
+    throw new Error(
+      'slackChannel({ cursorAccount: true }) agentName must be a non-empty single token (no whitespace), e.g. "ApprovalBuddy".'
+    );
+  }
+  if (SLACK_CURSOR_AGENT_NAME_WHITESPACE.test(trimmed)) {
+    throw new Error(
+      `slackChannel({ cursorAccount: true }) agentName must be a single token with no whitespace (got ${JSON.stringify(name)}). Use PascalCase like "ApprovalBuddy" — multi-word names break @Cursor routing.`
+    );
+  }
+}
+
 export interface SlackChannelOptions {
   credentials?: SlackCredentials;
   /**
@@ -242,12 +282,13 @@ export interface SlackChannelOptions {
    */
   cursorAccount?: boolean;
   /**
-   * Display name registered with the Cursor backend when
+   * Single-token display name registered with the Cursor backend when
    * {@link cursorAccount} is on: `@Cursor <agentName> …` routes here, and
-   * replies post under this username. Defaults to a name derived from the
+   * replies post under this username. **No whitespace** — prefer PascalCase
+   * (`ApprovalBuddy`). Defaults to a PascalCase name derived from the
    * agent's mount slug (or project name).
    */
-  agentName?: string;
+  agentName?: SlackCursorAgentName;
   /** Avatar for posts when {@link cursorAccount} is on. */
   agentIcon?: { url?: string; emoji?: string };
   /**

package/src/index.ts

@@ -104,6 +104,19 @@ export type {
 } from "./reminders.js";
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
+export type {
+  StorageConfig,
+  StorageContext,
+  StorageDefinition,
+  StorageEntry,
+  StoragePolicy,
+  StorageRestorePolicy,
+} from "./storage.js";
+export {
+  defineStorage,
+  STORAGE_KEY_ROOT,
+  storageKeys,
+} from "./storage.js";
 export { defineTool } from "./tools.js";
 export type * from "./types.js";
 export {