@cursor/july 0.1.105 → 0.1.108

package/src/channels/slack/live-delivery.ts

@@ -147,6 +147,7 @@ export function createStreamDeliveryStrategy(
     channel.state.streamTs = started.ts;
     channel.state.streamChannelId = started.channel;
     channel.state.streamFull = false;
+    channel.state.streamAppendedChunks = 0;
     channel.state.lastPostedText = openingText;
     channel.state.streamBlockText = openingText;
     log.info("chat.startStream ok", {
@@ -193,6 +194,21 @@ export function createStreamDeliveryStrategy(
       highlightCodeFences(text)
     );
 
+  /**
+   * The reply does not extend what the stream already holds, so there is no
+   * delta to append and the text on Slack is not the reply.
+   */
+  const rewound = (channel: SlackChannel, text: string): boolean =>
+    streamDelta(channel, text) === "" &&
+    !highlightCodeFences(text).startsWith(
+      highlightCodeFences(channel.state.streamBlockText ?? "")
+    );
+
+  const countAppended = (channel: SlackChannel, chunks: number): void => {
+    channel.state.streamAppendedChunks =
+      (channel.state.streamAppendedChunks ?? 0) + chunks;
+  };
+
   const stopWithSuffix = async (args: {
     channel: SlackChannel;
     channelId: string;
@@ -246,25 +262,25 @@ export function createStreamDeliveryStrategy(
   };
 
   /**
-   * The streamed message is full. Close it as it stands so it stops spinning
-   * and post the rest as a new thread message. Most of the answer is on Slack
-   * either way, so the reply counts as delivered even if that post fails: a
-   * duplicate would be worse than a lost tail.
+   * The open stream cannot carry the rest of the reply — it is full, or the
+   * reply no longer extends what it holds. Close it as it stands so it stops
+   * spinning and post the remainder as a new thread message.
    */
-  const continueOverflow = async (args: {
+  const continueInNewMessage = async (args: {
     channel: SlackChannel;
     channelId: string;
     ts: string;
     remainder: string;
+    reason: string;
     sessionId: string;
-  }): Promise<void> => {
-    const { channel, channelId, ts, remainder, sessionId } = args;
+  }): Promise<boolean> => {
+    const { channel, channelId, ts, remainder, reason, sessionId } = args;
     const log = getLog();
     await stopChatStream({ botToken, channel: channelId, ts });
     channel.state.streamTs = null;
     const threadTs = channel.state.threadTs;
     if (remainder === "" || threadTs === null || threadTs === "") {
-      return;
+      return true;
     }
     try {
       const posted = await postMessage({
@@ -275,19 +291,23 @@ export function createStreamDeliveryStrategy(
         plainText: remainder.length >= SLACK_MARKDOWN_TEXT_MAX_LEN,
       });
       channel.state.lastBotMessageTs = posted.ts;
-      log.info("reply overflowed the stream; continued in a new message", {
+      log.info("reply continued in a new message", {
+        reason,
         channel: channelId,
         stream_ts: ts,
         session: sessionId,
         continued_chars: remainder.length,
       });
+      return true;
     } catch (error) {
-      log.warn("stream overflow continuation failed", {
+      log.warn("stream continuation failed", {
+        reason,
         error: error instanceof Error ? error.message : String(error),
         channel: channelId,
         stream_ts: ts,
         session: sessionId,
       });
+      return false;
     }
   };
 
@@ -328,6 +348,7 @@ export function createStreamDeliveryStrategy(
         noteAppendFailure(channel, result);
         return;
       }
+      countAppended(channel, 1);
       channel.state.lastPostedText = text;
       channel.state.streamBlockText = text;
     },
@@ -364,8 +385,10 @@ export function createStreamDeliveryStrategy(
           chunks: chunks.length,
         });
         noteAppendFailure(channel, result);
+        return false;
       }
-      return result.ok;
+      countAppended(channel, chunks.length);
+      return true;
     },
 
     async finalize({ channel, channelId, text, sessionId }) {
@@ -381,6 +404,22 @@ export function createStreamDeliveryStrategy(
       }
       // Measured before the stop attempt mutates stream state.
       const remainder = streamDelta(channel, text);
+      // Nothing to append and the stream does not hold the reply: closing it
+      // here would leave the answer nowhere and report it as delivered.
+      if (rewound(channel, text)) {
+        const posted = await continueInNewMessage({
+          channel,
+          channelId,
+          ts,
+          remainder: text,
+          reason: "rewound",
+          sessionId,
+        });
+        if (posted) {
+          channel.state.lastPostedText = text;
+        }
+        return { delivered: posted };
+      }
       const stopped =
         channel.state.streamFull === true
           ? { ok: false, error: "msg_too_long" }
@@ -391,15 +430,17 @@ export function createStreamDeliveryStrategy(
           stream_ts: ts,
           session: sessionId,
           chars: text.length,
+          appends: channel.state.streamAppendedChunks ?? 0,
         });
         return { delivered: true };
       }
       if (stopped.error === "msg_too_long") {
-        await continueOverflow({
+        await continueInNewMessage({
           channel,
           channelId,
           ts,
           remainder,
+          reason: "msg_too_long",
           sessionId,
         });
         channel.state.lastPostedText = text;

package/src/channels/slack/types.ts

@@ -81,6 +81,8 @@ export interface SlackChannelState {
   streamingUnavailable?: boolean;
   /** The open stream hit Slack's size cap; appends stop until it closes. */
   streamFull?: boolean;
+  /** Chunks Slack accepted on the open stream, reported when it closes. */
+  streamAppendedChunks?: number;
   /** Editable progress message ts when `chat.startStream` is unavailable. */
   progressTs: string | null;
   /**
@@ -597,9 +599,8 @@ export interface SlackAccessPolicy {
 export interface SlackChannelOptions {
   credentials?: SlackCredentials;
   /**
-   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
-   * `"slack.thread/v1"` unless the agent set `architecture: "v2"` (then
-   * `"slack.thread/v2"`). Override with `"slack.none/v2"` for one-shot events.
+   * Continuation selector. Omit this to inherit the agent architecture's
+   * default. Set it explicitly only when migrating persisted identities.
    */
   continuation?: ContinuationIdentity;
   /** Defaults to `{ respondTo: "thread", blockExternals: true }`. */

package/src/channels.ts

@@ -64,9 +64,11 @@ export {
 } from "./channels/checks.js";
 
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { brandDefinition } from "./internal/brand.js";
 import { normalizeIdentity } from "./internal/continuation-identity.js";
+import { attachCatchAdmission } from "./internal/hosted-catch.js";
+import { attachHttpControlPlaneAdmission } from "./internal/http-control-plane-session.js";
 import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
 import type {
   AuthContext,
@@ -117,7 +119,16 @@ export type {
 export function defineChannel<TState = JsonValue>(
   config: ChannelConfig<TState>
 ): ChannelDefinition<TState> {
-  return brandDefinition("channel", config);
+  const definition = brandDefinition("channel", config);
+  if (config.routes !== undefined && config.routes.length > 0) {
+    // Hosted: the control plane catches declared routes and replays them
+    // here. Provider packs attach their own admission afterwards.
+    attachCatchAdmission(
+      definition as ChannelDefinition<unknown>,
+      config.routes
+    );
+  }
+  return definition;
 }
 
 /**
@@ -127,13 +138,15 @@ export function defineChannel<TState = JsonValue>(
 export function httpChannel(
   config: HttpChannelConfig = {}
 ): HttpChannelDefinition {
-  if (config.continuation !== undefined) {
-    return brandDefinition("http-channel", {
-      ...config,
-      continuation: normalizeIdentity(config.continuation, "http"),
-    });
-  }
-  return brandDefinition("http-channel", config);
+  const definition =
+    config.continuation !== undefined
+      ? brandDefinition("http-channel", {
+          ...config,
+          continuation: normalizeIdentity(config.continuation, "http"),
+        })
+      : brandDefinition("http-channel", config);
+  attachHttpControlPlaneAdmission(definition);
+  return definition;
 }
 
 // ============================================================================
@@ -432,7 +445,13 @@ export function publicEndpoint(): AuthPolicy {
     principalId: "anonymous",
     principalType: "user",
   });
-  return Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const });
+  // On the v2 control plane this also makes the channel's routes catchable
+  // with handler-side verification (the v1 alias posture): the CP admits
+  // every request on a declared route and the handler rejects bad ones.
+  return markCatchAuth(
+    Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const }),
+    { kind: "public" }
+  );
 }
 
 /** True when a policy was created by {@link publicEndpoint}. */
@@ -443,3 +462,131 @@ export function isPublicEndpointPolicy(policy: AuthPolicy): boolean {
     ] === true
   );
 }
+
+const CATCH_AUTH_MARKER = Symbol.for("agent-serve.catch-auth");
+
+/**
+ * What `deploy` extracts from a {@link sharedSecretAuth} /
+ * {@link hmacSignatureAuth} policy into the manifest: the control plane runs
+ * the same check with the deployment secret of the same name before any
+ * compute starts. `secret` is a name, never a value.
+ */
+export type CatchAuthDeclaration =
+  | { kind: "header"; header: string; secret: string }
+  | { kind: "hmac-sha256"; header: string; secret: string; prefix?: string }
+  /** `publicEndpoint()`: the handler verifies; the control plane only rate limits. */
+  | { kind: "public" };
+
+function markCatchAuth(
+  policy: AuthPolicy,
+  declaration: CatchAuthDeclaration
+): AuthPolicy {
+  return Object.assign(policy, { [CATCH_AUTH_MARKER]: declaration });
+}
+
+/** The catch declaration a policy carries, if it is a catch-capable policy. */
+export function catchAuthDeclaration(
+  policy: AuthPolicy
+): CatchAuthDeclaration | undefined {
+  const declaration = (policy as { [CATCH_AUTH_MARKER]?: unknown })[
+    CATCH_AUTH_MARKER
+  ];
+  return typeof declaration === "object" && declaration !== null
+    ? (declaration as CatchAuthDeclaration)
+    : undefined;
+}
+
+function presentedHeaderSecret(headerName: string, value: string): string {
+  if (
+    headerName === "authorization" &&
+    value.toLowerCase().startsWith("bearer ")
+  ) {
+    return value.slice("bearer ".length).trim();
+  }
+  return value.trim();
+}
+
+/**
+ * Admit requests whose `header` equals the secret named `secret` (an
+ * `Authorization: Bearer <secret>` header also matches). Locally the value
+ * is `process.env[secret]`; hosted, the deployment secret of that name. On
+ * Cursor hosting this ALSO declares the channel's routes reachable through
+ * the control-plane catch API, which runs the same comparison before any
+ * compute exists. An unset secret admits nothing.
+ */
+export function sharedSecretAuth(options: {
+  header: string;
+  secret: string;
+}): AuthPolicy {
+  const header = options.header.toLowerCase();
+  const policy: AuthPolicy = (request) => {
+    const expected = process.env[options.secret];
+    const presented = request.headers.get(header);
+    if (
+      expected === undefined ||
+      expected.length === 0 ||
+      presented === null ||
+      !constantTimeEquals(presentedHeaderSecret(header, presented), expected)
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "shared-secret",
+      principalId: "webhook",
+      principalType: "service",
+    };
+  };
+  return markCatchAuth(policy, {
+    kind: "header",
+    header,
+    secret: options.secret,
+  });
+}
+
+/**
+ * Admit requests whose `header` carries the hex HMAC-SHA256 of the raw body
+ * under the secret named `secret` (optionally behind a literal `prefix`
+ * such as `sha256=`). Same local / hosted / catch semantics as
+ * {@link sharedSecretAuth}.
+ */
+export function hmacSignatureAuth(options: {
+  header: string;
+  secret: string;
+  prefix?: string;
+}): AuthPolicy {
+  const header = options.header.toLowerCase();
+  const prefix = options.prefix ?? "";
+  const policy: AuthPolicy = async (request) => {
+    const secret = process.env[options.secret];
+    const presented = request.headers.get(header)?.trim();
+    if (
+      secret === undefined ||
+      secret.length === 0 ||
+      presented === undefined ||
+      !presented.startsWith(prefix)
+    ) {
+      return null;
+    }
+    const body = Buffer.from(await request.clone().arrayBuffer());
+    const expected = createHmac("sha256", secret).update(body).digest("hex");
+    if (
+      !constantTimeEquals(
+        presented.slice(prefix.length).toLowerCase(),
+        expected
+      )
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "hmac-signature",
+      principalId: "webhook",
+      principalType: "service",
+    };
+  };
+  return markCatchAuth(policy, {
+    kind: "hmac-sha256",
+    header,
+    secret: options.secret,
+    prefix: options.prefix,
+  });
+}

package/src/connections.ts

@@ -65,7 +65,8 @@
  * executes **on the Cursor backend** with the account's stored OAuth
  * credentials, so the agent gets Linear / Notion / Slack / … tools with
  * zero token plumbing and no OAuth secrets on this host. Requires the host
- * to be signed in (`agent-sdk login` or `CURSOR_API_KEY`):
+ * to be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
+ * `CURSOR_SERVICE_ACCOUNT_KEY`):
  *
  * ```ts
  * // agent/mcp-connections/account.ts — every connected server (no allowlist)

package/src/extensions/improve/extension.ts

@@ -0,0 +1,70 @@
+/**
+ * Self-improvement as an extension. An agent's behaviour is source in a
+ * repository, so changing how it behaves is a change to that source: a
+ * one-off Cursor cloud agent does the coding on a branch and opens a pull
+ * request, the agent that mounted this writes the brief and reports the
+ * pull request, and the tree it runs from is never edited.
+ *
+ * ```ts
+ * // agent/extensions/improve.ts
+ * import improve from "@cursor/july/extensions/improve";
+ *
+ * export default improve({
+ *   repo: "https://github.com/acme/agents",
+ *   path: "agents/concierge",
+ * });
+ * ```
+ *
+ * Contributes the `<namespace>__yourself` skill; mount it as `improve` so
+ * the skill reads `improve__yourself`. The coding goes through the
+ * cursor-cloud-agents extension, so mount that too, with `repo` among its
+ * `cloud.repos`. An agent whose own turns run on a cloud VM with the
+ * repository checked out needs no second mount: the skill has it work in
+ * that checkout.
+ */
+
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import type { Extension } from "../../types.js";
+
+export interface ImproveOptions {
+  /** Repository that holds the agent's source. One of the cloud agents mount's `cloud.repos`. */
+  repo: string;
+  /** The agent's directory in the repository, as `agent-sdk deploy --path` names it. */
+  path: string;
+  /** Ref the deployment tracks: branches start there and pull requests target it. Defaults to `main`. */
+  ref?: string;
+  /** What a coding agent must know about this tree beyond the Agent SDK layout, one line each. */
+  notes?: string[];
+  /** Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." */
+  deploy?: string;
+}
+
+/** {@link ImproveOptions} with defaults applied. */
+export interface ImproveConfig extends ImproveOptions {
+  ref: string;
+  notes: string[];
+  deploy: string;
+}
+
+const line = z.string().trim().min(1);
+
+const improve: Extension<ImproveConfig, ImproveOptions> = defineExtension({
+  root: import.meta.dirname,
+  description:
+    "Change your own source through a one-off cloud agent and a pull request, never the running tree.",
+  config: z.object({
+    repo: z.string().url(),
+    path: z
+      .string()
+      .regex(
+        /^[^\s/]+(\/[^\s/]+)*$/,
+        "Expected a repository-relative path like agents/concierge"
+      ),
+    ref: line.default("main"),
+    notes: z.array(line).default([]),
+    deploy: line.default("It takes effect at the next deploy."),
+  }),
+});
+
+export default improve;

package/src/extensions/improve/skills/yourself.ts

@@ -0,0 +1,50 @@
+import { defineSkill } from "../../../skills.js";
+import type { SkillDefinition } from "../../../types.js";
+import extension from "../extension.js";
+
+const { repo, path, ref, notes, deploy } = extension.config;
+
+const treeNotes =
+  notes.length === 0
+    ? ""
+    : `\nAbout this tree in particular; copy these into the brief verbatim:\n\n${notes.map((note) => `- ${note}`).join("\n")}\n`;
+
+const yourself: SkillDefinition = defineSkill({
+  description:
+    "Change your own source (instructions, skills, tools, channels, connections, model, deployment) through a one-off Cursor cloud agent and a pull request. Use whenever the ask is about how you yourself behave, including adding or editing a skill, so the change lands in the repository instead of the tree you happen to be running from.",
+  markdown: `# Improve yourself
+
+You are the Agent SDK agent at \`${path}\` in ${repo}, deployed from \`${ref}\`. A change to how you behave is a change to that source, and it goes through the repository like any other change: a branch, a pull request, review, a deploy. Nothing about it is special except that people describe it in the second person.
+
+## What changes where
+
+Under \`${path}/agent/\`:
+
+- \`instructions.md\` is the always-on system prompt: identity, tool-choice rules, the output contract.
+- \`skills/<name>.md\` is a procedure loaded on demand; a \`<name>/SKILL.md\` directory carries sibling files. The \`description\` frontmatter is the routing rule the model sees.
+- \`tools/<name>.ts\` is typed, executable behaviour: anything that must be right every time.
+- \`channels/\`, \`mcp-connections/\`, and \`host-connections/\` are the surfaces and connectors.
+- \`agent.ts\` is the model, its parameters, and the runtime.
+- \`extensions/<ns>.ts\` mounts an extension. This skill arrives through one.
+${treeNotes}
+## The change is made on a clean checkout
+
+Never edit the tree you run from: it is a deployed copy of \`${path}\`, and nothing changed there lasts. The change is made on a clean checkout of ${repo} at \`${ref}\`. When your own turn runs on a cloud VM with that repository checked out, that VM is the checkout: branch there. Otherwise hand the coding to a one-off Cursor cloud agent through the cloud agents extension, with \`launch\` under its mount namespace, \`repo\` set to ${repo}, and \`starting_ref\` to \`${ref}\`. One agent per change; steer it with \`reply\` rather than launching another.
+
+## The brief
+
+Whoever makes the change works from the same brief. For a cloud agent it is the whole handoff, because it cannot see this conversation:
+
+- Who and why. A change to the source of the Agent SDK agent at \`${path}\`, asked for by the person in front of you: the change in their words, and what you know about why they want it.
+- Where. Repository ${repo}, ref \`${ref}\`, directory \`${path}\`, the layout above, and the files you expect to change.
+- How. Follow the repository's own conventions (its \`AGENTS.md\` files and rules along the paths touched). Keep the diff to the change. Run the checks the repository defines for \`${path}\`. Open a pull request against \`${ref}\`; never merge it.
+- Report. The pull request URL, what changed, what was verified and how, and anything left unverified.
+
+## Report
+
+If you launched a cloud agent, give the person its URL with the full id, read its report with \`dump\` (\`get\` for status), and read the pull request before repeating its claims. Report the pull request, not that you delegated.
+
+A merged pull request changes nothing by itself. ${deploy} Never say you have already changed yourself. Editing your own source is still an edit: do it when asked, and stop at the pull request. Deploying is a separate authorization.`,
+});
+
+export default yourself;

package/src/index.ts

@@ -139,7 +139,9 @@ export {
   TOOL_MCP_ENDPOINT_PATH,
 } from "./internal/mcp-endpoint.js";
 export {
+  REMINDER_ARGS_MAX_BYTES,
   ReminderValidationError,
+  rejectAnonymousReminderHandlers,
   UnknownReminderError,
 } from "./internal/reminder-runner.js";
 export type { AgentMount } from "./internal/server.js";
@@ -169,8 +171,10 @@ export { prompt } from "./prompt.js";
 export type {
   ReminderBusyPolicy,
   ReminderCreateInput,
+  ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
+  ReminderHandlerConfig,
   ReminderHostApi,
   ReminderInfo,
   ReminderReschedule,
@@ -179,6 +183,7 @@ export type {
   ReminderTarget,
   ReminderUntilContext,
 } from "./reminders.js";
+export { defineReminder } from "./reminders.js";
 export { defineResult } from "./result.js";
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
@@ -226,9 +231,7 @@ export {
 
 /**
  * Runtime config for an agent — authored at `agent/agent.ts` (the root
- * agent) or `agent/subagents/<id>/agent.ts` (a subagent). Set
- * `architecture: "v2"` to deploy onto the v2 control plane; omitted
- * channel continuation then inherits kind `/v2` defaults.
+ * agent) or `agent/subagents/<id>/agent.ts` (a subagent).
  */
 export function defineAgent(config: AgentConfig): AgentConfigDefinition {
   return brandDefinition("agent", config);

package/src/internal/builtin-tools/artifacts.ts

@@ -30,7 +30,7 @@ function kindVariant(name: string, schema: z.ZodType | undefined) {
       .min(1)
       .optional()
       .describe(
-        "Stable upsert key: tagging the same key again updates the existing record instead of creating a new one."
+        "Stable key, unique across kinds. Reusing it replaces that record instead of adding a new one."
       ),
   });
 }
@@ -47,10 +47,9 @@ export function tagArtifactTool(config: ArtifactsConfig): ToolDefinition {
     );
   }
   const description = [
-    "Tag a durable artifact: a record of a notable output you produced, kept across sessions and listed for the people supervising this agent. Tag one whenever you finish something worth surfacing durably.",
+    "Tag a finished output as an artifact. Artifacts persist across sessions and are listed for the people supervising this agent.",
     "Kinds:",
     ...kinds.map(([name, kind]) => `- ${name}: ${kind.description}`),
-    "Same `key` upserts: tagging it again updates that record — use a stable key when re-tagging the same underlying thing (e.g. the same PR URL).",
   ].join("\n");
   return defineTool({
     description,

package/src/internal/channel-route-dispatch.ts

@@ -0,0 +1,66 @@
+import type { ChannelHandlerArgs, ChannelRoute } from "../types.js";
+import { jsonResponse } from "./http-channel.js";
+import { validateToolInput } from "./json-schema.js";
+
+/**
+ * Run one authored channel route: validate the declared Zod query / body
+ * schemas onto `handlerArgs`, then call the handler. Shared by the local
+ * router mount and hosted catch replay so a caught request meets exactly
+ * the same schema gate as a direct one.
+ */
+export async function invokeChannelRoute(input: {
+  route: ChannelRoute;
+  request: Request;
+  handlerArgs: ChannelHandlerArgs;
+}): Promise<Response> {
+  const { route, handlerArgs } = input;
+  let request = input.request;
+
+  if (route.querySchema !== undefined) {
+    const rawQuery = Object.fromEntries(
+      new URL(request.url).searchParams.entries()
+    );
+    const queryValidation = validateToolInput(route.querySchema, rawQuery);
+    if (!queryValidation.ok) {
+      return jsonResponse({ error: queryValidation.message }, { status: 400 });
+    }
+    handlerArgs.query = queryValidation.value;
+  }
+
+  if (route.bodySchema !== undefined) {
+    // Buffer once so handlers that need the raw body (e.g. GitHub HMAC) can
+    // still read `request.text()` / `request.json()`.
+    let bodyText: string;
+    try {
+      bodyText = await request.text();
+    } catch {
+      return jsonResponse(
+        { error: "Failed to read request body" },
+        { status: 400 }
+      );
+    }
+    let rawBody: unknown;
+    try {
+      rawBody = bodyText === "" ? {} : JSON.parse(bodyText);
+    } catch {
+      return jsonResponse(
+        { error: "Request body must be valid JSON" },
+        { status: 400 }
+      );
+    }
+    const bodyValidation = validateToolInput(route.bodySchema, rawBody);
+    if (!bodyValidation.ok) {
+      return jsonResponse({ error: bodyValidation.message }, { status: 400 });
+    }
+    handlerArgs.body = bodyValidation.value;
+    request = new Request(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: bodyText === "" ? undefined : bodyText,
+      // node: undici / fetch may require duplex for streamed bodies;
+      // a string body does not.
+    });
+  }
+
+  return route.handler(request, handlerArgs);
+}