@cursor/july 0.1.1 → 0.1.2

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 {