@cursor/july 0.1.113 → 0.2.0

package/docs/reference/subagents.md

@@ -6,16 +6,15 @@ description: "Specialist child agents the model delegates to mid-turn, each its
 # Subagents
 
 A subagent is a specialist child agent the model can delegate to
-mid-turn. Each one is its own directory under `agent/subagents/<id>/`,
-with the same `agent.ts` + `instructions.md` shape as the root. On the
-Cursor harness, subagents run as SDK custom subagents: the parent model
-delegates through the harness `task` tool, and the stream records
-`subagent.called` and `subagent.completed`.
+mid-turn. Each one lives under `agent/subagents/<id>/` with a required
+`agent.ts`. Add `instructions.md` or inline `instructions` in `agent.ts`
+for a custom prompt. The parent model delegates through the `task` tool,
+and the stream records `subagent.called` and `subagent.completed`.
 
 ```text
 agent/subagents/researcher/
 ├── agent.ts            # description (required), model (optional)
-└── instructions.md     # the subagent's own system prompt
+└── instructions.md     # optional custom system prompt
 ```
 
 ```ts
@@ -31,44 +30,35 @@ export default defineAgent({
 
 ## Subagent rules
 
-`description` is required. It's the only thing the parent model reads
-when deciding whether to delegate, so write it as a routing rule
-("Background research: …"), the same discipline as a
-[skill](./skills.md) description. `model` is optional; omit it to
-inherit the parent's model, or set it to run the specialist on a
-different one.
+`description` is required. The parent model uses it to decide whether
+to delegate, so write it as a routing rule ("Background research: …"),
+following the same discipline as a [skill](./skills.md) description.
+`model` is optional; omit it to inherit the parent's model, or set it
+to run the specialist on a different model.
 
 Subagents inherit the parent's execution surface. Every per-subagent
 capability directory is reported as a warning and ignored: `tools/`,
-`skills/`, `mcp-connections/` (and the legacy `connections/` alias),
-`host-connections/`, `channels/`, `schedules/`, `hooks/`, `sandbox/`,
-and nested `subagents/`.
+`skills/`, `extensions/`, `mcp-connections/`, `host-connections/`,
+`channels/`, `schedules/`, `reminders/`, `hooks/`, `sandbox/`, and
+nested `subagents/`.
 
 Delegation needs both halves: the description makes it possible, and the
 parent's [instructions](./instructions.md) make it happen. "When a
 request needs background research, delegate to the `researcher`
-subagent."
+subagent." The parent routes; the specialist executes.
 
-## Subagent or peer?
+## Subagents and peers
 
 Subagents split one job into roles inside a single agent. When the
 specialist is independently useful, with its own tools, sessions, and
 playground, make it a full agent. See
 [Peer agents](../guides/agent-to-agent.md#peer-or-subagent).
 
-## Patterns
-
-Fan-out reviews: a PR-approval agent can delegate to two review
-subagents that read a host-prepared `pr/` evidence tree and report
-prioritized findings, which the parent embeds in its approval comment.
-
-Keep the parent lean: a subagent with focused instructions usually
-works better than a longer parent prompt with conditional sections. The
-parent routes; the specialist executes.
-
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Skills](./skills.md): when a procedure is enough and a child agent
   is overkill
+- [Peer agents](../guides/agent-to-agent.md): independently useful
+  specialists
+- [Agent config](./agent-config.md#harness-tools): `"task"` on the
+  parent's tool allowlist

package/docs/reference/tools.md

@@ -8,18 +8,16 @@ description: "Define typed actions the model can call, gate the sensitive ones o
 A tool is a typed action the model can call: hit an API, run a query,
 write a file. Each file in `agent/tools/` defines one tool, and the
 filename becomes the tool name the model sees. Tools come in two
-execution flavors: server tools run in-process on the serve host, and
+execution flavors: server tools run on the serving host, and
 agent tools run as scripts where the agent runs. Every server tool can
 also be called directly, with no model turn.
 
 ## Define a server tool
 
-By default, `execute` runs in-process on the serving host with full
-access to `process.env` and your `agent/lib/` code. Local turns call
-server tools as SDK custom tools. Cloud turns reach them over
-authenticated HTTP MCP back to the serve host when `--public-url` or
-`--cloud-tools-url` is set; without either, the server warns at startup
-and cloud turns omit them.
+By default, `execute` runs on the serving host with full access to
+`process.env` and your `agent/lib/` code. Set `--public-url` or
+`--cloud-tools-url` to make server tools available to cloud turns;
+without either, startup warns and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts
@@ -178,7 +176,7 @@ check nothing.
 ## Define an agent tool
 
 Set `execution: "agent"` and the tool materializes as a shell script
-that runs where the Cursor agent runs: the local harness workspace or
+that runs where the Cursor agent runs: the local session workspace or
 the cloud VM. The script receives JSON arguments on stdin and prints its
 result on stdout. Use this flavor when the tool must run next to the
 checkout the agent works in; on cloud, server tools stay available too
@@ -201,23 +199,16 @@ printf '%s\\n' "$message"
 ```
 
 On the local runtime, scripts land in the session workspace with a
-catalog in `AGENTS.md`. On cloud, the catalog and script bodies travel
-on the first prompt.
+catalog in `AGENTS.md`.
 
 ## Tools from an MCP connection, advertised by name
 
-Authored `agent/tools/` files are one catalog for every session. When
-the tools should come from an MCP server, including per-tenant toolsets
-resolved at runtime, declare the connection with
-`advertiseTools: true` (plus per-session `auth` when the credential
-depends on who the session is for) and the engine synthesizes named 1:1
-passthrough server tools from the connection's live `listTools` on every
-local turn. See
-[MCP Connections](connections.md#advertise-tools).
-Advertised tools ride the same execution path as authored server tools,
-and [direct tool calls](#call-a-tool-without-a-model-turn) address them
-by the same model-facing names: the call's session identity resolves the
-advertised listing when the authored lookup misses.
+Set `advertiseTools: true` on a connection to expose its MCP tools by
+name. Add per-session `auth` when credentials depend on the caller.
+Model calls and [direct tool calls](#call-a-tool-without-a-model-turn)
+use the same exposed names. See
+[MCP connections](./connections.md#advertise-tools) for the full
+contract.
 
 ## Gate a tool on human approval
 
@@ -248,8 +239,8 @@ runtime only, and parked calls don't survive a host restart.
 ## Call a tool without a model turn
 
 Server tools can be called deterministically. You pick the tool and the
-input. Validation and execution behave exactly as they would for a
-model-initiated call, and no Cursor API key is needed.
+input. Validation and execution match a model-initiated call, and no
+Cursor API key is needed.
 
 Over HTTP, with the same auth chain as the session API:
 
@@ -275,51 +266,43 @@ agent-sdk call inspect_pr \
 Programmatically, `callTool(toolName, input, options?)` is available on
 the serve handle, on channel route handlers and `onStart` args, and on
 schedule `run` handlers, so a channel can mix deterministic calls with
-model turns, fetching PR metadata deterministically and then `send()`ing
-the review prompt:
+model turns:
 
 ```ts
 const outcome = await handle.callTool("inspect_pr", {
   prUrl: "https://github.com/acme/checkout/pull/42",
 });
+if (outcome.isError) {
+  return outcome;
+}
 // { toolName, callId, isError, result, durationMs }
 ```
 
-By default the call runs against an ephemeral workspace and is removed
-when the call returns. Pass a `sessionId` (a body field over
-HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
-run inside an existing session instead: the tool sees that session's
-workspace, and the call is recorded on the session's event stream.
-While a model turn is running, a session-bound call is admitted by its
-effect: a read-effect call (a declared `effect: "read"`, or an advertised
-MCP tool whose server annotates it read-only) runs alongside the turn,
-reading the workspace as the turn has left it, and is recorded under its
-own per-call `turnId` so trajectories keep it apart from the turn's own
-calls; a write-effect call — including an undeclared tool, which counts
-as a write — returns `409 session_busy` until the turn finishes, because
-a running turn owns the workspace. When the
-session's harness cwd cannot be materialized, a read-effect call runs
-in a scratch workspace instead and the outcome carries
-`scratchWorkspace: true`; a write-effect call fails with
-`workspace_unavailable`.
-
-A session can also be addressed by its continuation token: an optional
-`continuationToken` (`<channelId>:<key>`, as `/v1/sessions` lists it;
-mutually exclusive with `sessionId`). A token that maps to a live
-session behaves exactly like passing that session's id — same ownership
-check, same busy semantics, same event recording. A token with no
-session behind it runs the call scratch-bound with the token's channel
-id and continuation key as the call's session identity, so a deployment
-whose tools resolve state from the continuation key can serve it with
-no live session. Malformed tokens are rejected with
-`400 invalid_continuation_token`.
-
-The error semantics match the model path. Unknown tools are rejected
-with the available names, agent-execution tools cannot be called on the
-host (`400`), schema-invalid input is a `400` before the tool body runs
-(Zod validates; plain JSON Schema passes through unvalidated), and a
-tool body that throws reports `isError: true` in the same envelope the
-model would see.
+Omit both identifiers to run against an ephemeral workspace that is
+removed when the call returns. Pass `sessionId` (HTTP body, `--session`,
+or `options.sessionId`) or `continuationToken` (`<channelId>:<key>` as
+`/v1/sessions` lists it) to bind the call. The two are mutually
+exclusive.
+
+| Rule | What happens |
+| --- | --- |
+| Existing `sessionId`, or a token that maps to an existing session | Session workspace, owner check, and event recording |
+| Token with no matching session | Scratch workspace; the token's channel id and key are the call identity |
+| Busy session, `effect: "read"` (or an advertised MCP tool marked read-only) | Runs alongside the turn, reading the workspace as the turn left it; recorded under its own `turnId` |
+| Busy session, write or undeclared | `409 session_busy` until the turn finishes |
+| Session workspace cannot be created, read | Scratch workspace; the outcome has `scratchWorkspace: true` |
+| Session workspace cannot be created, write | `500 workspace_unavailable` |
+
+| Error | When |
+| --- | --- |
+| `404 unknown_tool` | Name is not a callable server tool; the response lists available names |
+| `400 tool_not_callable` | Agent-execution tools cannot run on the host |
+| `400 invalid_tool_input` | Zod rejected the input before `execute`. Plain JSON Schema is forwarded unvalidated |
+| `400 invalid_continuation_token` | Malformed token, or passed together with `sessionId` |
+| `404 session_not_found` | `sessionId` does not exist |
+| `409 session_busy` | Write-effect call while a model turn is running |
+| `500 workspace_unavailable` | Write-effect call when the session workspace cannot be created |
+| `isError: true` | The tool body threw; same envelope the model would see |
 
 ## Design habits
 
@@ -337,9 +320,7 @@ wrong, no instruction change fixes it.
 Gate side effects with `needsApproval`. Declare each tool's `effect` so
 dry-run sessions can execute reads and stub writes.
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [MCP connections](./connections.md): tools that come from MCP servers
   instead

package/docs/troubleshooting.md

@@ -32,7 +32,7 @@ Match the visible symptom below. If `agent-sdk` is not on `PATH`, use
 | File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
 | The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `agent-sdk login`. |
 | Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
-| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](./reference/agent-config.md#choose-a-runtime). |
+| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](./reference/agent-config.md#runtime). |
 
 ## A turn behaves unexpectedly
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.113",
+  "version": "0.2.0",
   "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": {

package/src/channels/slack/inbound.ts

@@ -218,6 +218,30 @@ export function parseAssistantThreadStarted(
   };
 }
 
+/**
+ * The receiving app's own bot user id from an Events API envelope. Slack
+ * stamps `authorizations[]` on every `event_callback` with the installed
+ * bot user the delivery is for, so a hosted guest learns its identity from
+ * the verified body without an `auth.test` round trip.
+ */
+export function parseEventBodyBotUserId(body: unknown): string | undefined {
+  const root = asRecord(body);
+  if (root === null || root.type !== "event_callback") {
+    return undefined;
+  }
+  if (!Array.isArray(root.authorizations)) {
+    return undefined;
+  }
+  for (const entry of root.authorizations) {
+    const authorization = asRecord(entry);
+    const userId = asString(authorization?.user_id);
+    if (userId !== undefined && userId !== "") {
+      return userId;
+    }
+  }
+  return undefined;
+}
+
 /**
  * Parse DM / IM messages. More generous than a strict channel_type check:
  * accepts `channel_type === "im"` or channel ids starting with `D`, and

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

@@ -25,10 +25,12 @@ import {
 } from "../../internal/continuation-identity.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "../../internal/cursor-relay-core.js";
 import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import type { HostedAdmissionPlatformHandoff } from "../../internal/hosted-delivery-protocol.js";
 import type {
   ArtifactsApi,
   ChannelDefinition,
   ChannelEventHandlers,
+  ChannelHandlerArgs,
   HostContext,
   JsonValue,
   ReceiveInput,
@@ -68,6 +70,10 @@ import {
   slackWakeChannelState,
 } from "./dispatch.js";
 import { createEventIdDedupe, type EventIdDedupe } from "./event-id-dedupe.js";
+import {
+  parseChannelMessageEvent,
+  parseEventBodyBotUserId,
+} from "./inbound.js";
 import {
   dispatchBlockAction,
   dispatchInteractiveFromPayload,
@@ -245,6 +251,113 @@ export function slackChannel(
   let channelWatch: ChannelPostWatcher | undefined;
   let botMentionGate: SlackBotMentionGate | undefined;
 
+  // Hosted admission never runs the Socket Mode branch of `onStart`, so the
+  // channel watch is built per delivery there. The allowlist and its `#name`
+  // resolution are shared across the pod; the bot's identity comes from the
+  // verified envelope.
+  let hostedAllowlist: SlackChannelAllowlist | undefined;
+  let hostedAllowlistReady: Promise<void> | undefined;
+
+  async function resolveHostedAllowlistNames(
+    allowlist: SlackChannelAllowlist
+  ): Promise<void> {
+    const names = allowlist.unresolvedNames();
+    if (names.length === 0) {
+      return;
+    }
+    try {
+      const botToken = await tryResolveBotToken(credentials);
+      if (botToken === undefined) {
+        getLog().error("channel watch setup degraded", {
+          error: "no bot token; #name entries stay unresolved",
+        });
+        return;
+      }
+      const { WebClient } = await import("@slack/web-api");
+      allowlist.applyResolvedNames(
+        await resolveChannelNames(new WebClient(botToken), names, getLog())
+      );
+    } catch (error) {
+      getLog().error("channel watch setup degraded", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Only a channel post needs the watcher, so mentions and DMs never wait on
+   * it, and a channel already matched by id never waits on `#name` resolution.
+   */
+  async function hostedChannelWatch(
+    payload: unknown,
+    args: ChannelHandlerArgs,
+    platformHandoff: HostedAdmissionPlatformHandoff | undefined
+  ): Promise<ChannelPostWatcher | undefined> {
+    if (channelPosts === undefined) {
+      return undefined;
+    }
+    const channelEvent = parseChannelMessageEvent(payload, {
+      includeBotAuthored: true,
+    });
+    if (channelEvent === null || channelEvent.kind === "deleted") {
+      return undefined;
+    }
+    hostedAllowlist ??= new SlackChannelAllowlist(channelPosts.allow);
+    if (
+      !hostedAllowlist.matches(channelEvent.message.channelId) &&
+      hostedAllowlist.unresolvedNames().length > 0
+    ) {
+      hostedAllowlistReady ??= resolveHostedAllowlistNames(hostedAllowlist);
+      await hostedAllowlistReady;
+    }
+    const botUserId = parseEventBodyBotUserId(payload);
+    return createChannelPostWatcher({
+      // Admission answers before a debounce timer could fire; edits arrive
+      // as their own deliveries and the edge drops them.
+      options: { ...channelPosts, debounceMs: 0 },
+      allowlist: hostedAllowlist,
+      getBotUserId: () => botUserId,
+      log: getLog(),
+      dispatch: (message, eventId) => {
+        args.waitUntil(
+          dispatchInboundMessage({
+            kind: "channel_post",
+            message,
+            handler: onChannelPost,
+            propagateHandlerErrors: true,
+            send: args.send,
+            credentials,
+            host: args.host,
+            artifacts: args.artifacts,
+            log: getLog(),
+            evalCommandsEnabled,
+            followUpStatus,
+            ack: reply.ack,
+            blockExternals,
+            continuation: options.continuation,
+            ...(args.hasContinuationSession === undefined
+              ? {}
+              : { hasContinuationSession: args.hasContinuationSession }),
+            ...(args.isContinuationBusy === undefined
+              ? {}
+              : { isContinuationBusy: args.isContinuationBusy }),
+            ...(args.getContinuationLastBotMessageTs === undefined
+              ? {}
+              : {
+                  getContinuationLastBotMessageTs:
+                    args.getContinuationLastBotMessageTs,
+                }),
+            ...(args.interruptContinuation === undefined
+              ? {}
+              : { interruptContinuation: args.interruptContinuation }),
+            ...(eventId === undefined ? {} : { eventId }),
+            ...(platformHandoff === undefined ? {} : { platformHandoff }),
+          })
+        );
+      },
+    });
+  }
+
   function inboundDeps(args: {
     send: SendMessageFn;
     waitUntil: (promise: Promise<unknown>) => void;
@@ -260,7 +373,10 @@ export function slackChannel(
     ) => Promise<string | undefined>;
     interruptContinuation?: (continuationToken: string) => Promise<boolean>;
     platformHandoff?: SlackInboundDispatchDeps["platformHandoff"];
+    /** Per-delivery watcher (hosted); the Socket Mode watcher otherwise. */
+    channelWatch?: ChannelPostWatcher;
   }): SlackInboundDispatchDeps {
+    const watch = args.channelWatch ?? channelWatch;
     return {
       send: args.send,
       continuation: options.continuation,
@@ -299,7 +415,7 @@ export function slackChannel(
       ...(args.interruptContinuation === undefined
         ? {}
         : { interruptContinuation: args.interruptContinuation }),
-      ...(channelWatch === undefined ? {} : { channelWatch }),
+      ...(watch === undefined ? {} : { channelWatch: watch }),
       ...(botMentionGate === undefined ? {} : { botMentionGate }),
       suggestedPrompts: options.suggestedPrompts,
       suggestedPromptsTitle: options.suggestedPromptsTitle,
@@ -661,6 +777,11 @@ export function slackChannel(
     // would otherwise swallow the control plane's own retry of a delivery
     // that failed after the id was marked handled.
     dispatch: async ({ payload, args, platformHandoff }) => {
+      const hostedWatch = await hostedChannelWatch(
+        payload,
+        args,
+        platformHandoff
+      );
       const dispatched = dispatchInboundFromEventBody(
         payload,
         inboundDeps({
@@ -675,6 +796,7 @@ export function slackChannel(
           getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
           interruptContinuation: args.interruptContinuation,
           ...(platformHandoff === undefined ? {} : { platformHandoff }),
+          ...(hostedWatch === undefined ? {} : { channelWatch: hostedWatch }),
         })
       );
       return skipped(dispatched ? "not_engaged" : "not_dispatchable");

package/src/internal/cli-deploy.ts

@@ -1658,11 +1658,18 @@ export async function cmdStop(
   }
   const cancellation =
     "cancellation" in accepted ? accepted.cancellation : undefined;
+  // The backend escalates a publisher's stop of a multi-tenant app to the
+  // application-level suspension; say so, and how to undo it.
+  const stoppedGlobally = "scope" in accepted && accepted.scope === "global";
   if (ctx.noWait) {
     if (ctx.json) {
       ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
     } else {
-      ctx.out(`Stop accepted for ${slug} (status: ${accepted.status}).\n`);
+      ctx.out(
+        stoppedGlobally
+          ? `Stop accepted for ${slug} across all tenants (status: ${accepted.status}).\n`
+          : `Stop accepted for ${slug} (status: ${accepted.status}).\n`
+      );
     }
     return cancellation?.failed === 0 || cancellation === undefined ? 0 : 1;
   }
@@ -1681,6 +1688,10 @@ export async function cmdStop(
   }
   if (ctx.json) {
     ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+  } else if (stoppedGlobally) {
+    ctx.out(
+      `Stopped ${slug} across all tenants (team ${ctx.teamId}); resume with \`${CLI} start ${slug} --global\`.\n`
+    );
   } else {
     ctx.out(`Stopped ${slug} (team ${ctx.teamId}).\n`);
   }

package/src/internal/deploy-client.ts

@@ -295,6 +295,12 @@ export interface AgentkitStopAccepted {
   applicationId: string;
   releaseId: string;
   status: string;
+  /**
+   * `"global"` when the backend escalated the stop to the application-level
+   * suspension — the default for a multi-tenant app stopped by its
+   * publisher. Resume needs `start <slug> --global`.
+   */
+  scope?: "global";
   cancellation?: AgentkitCancelRunsResult;
 }
 
@@ -471,6 +477,9 @@ const agentkitStopAcceptedSchema = z
     applicationId: z.string().min(1),
     releaseId: z.string().min(1),
     status: z.string(),
+    // Tolerate scope values a newer backend may add: parse only "global",
+    // drop anything else rather than failing the stop response.
+    scope: z.literal("global").optional().catch(undefined),
     cancellation: agentkitCancelRunsResultSchema.optional(),
   })
   .passthrough();

package/src/internal/discovery/agent-config.ts

@@ -33,16 +33,18 @@ export function runtimeArchitectureCompatibilityError(agent: {
     : undefined;
 }
 
+/** Author-facing default when {@link AgentConfig.architecture} is omitted. */
+export const DEFAULT_AGENT_ARCHITECTURE: AgentArchitecture = "v2";
+
 export function resolveArchitecture(
   ctx: DiscoveryContext,
   agentDir: string,
   architecture: AgentArchitecture | undefined
 ): AgentArchitecture | undefined {
-  if (
-    architecture === undefined ||
-    architecture === "v1" ||
-    architecture === "v2"
-  ) {
+  if (architecture === undefined) {
+    return DEFAULT_AGENT_ARCHITECTURE;
+  }
+  if (architecture === "v1" || architecture === "v2") {
     return architecture;
   }
   ctx.diagnostics.push({
@@ -55,7 +57,7 @@ export function resolveArchitecture(
 
 /**
  * `persistent: true` selects the long-lived-pod hosting mode of v2. It has
- * no meaning on v1 (resident engine) or when the architecture is unset.
+ * no meaning on v1 (resident engine).
  */
 export function resolvePersistent(
   ctx: DiscoveryContext,

package/src/internal/framework-storage-selection.ts

@@ -66,7 +66,7 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
   readonly authored: StorageDefinition | undefined;
-  /** {@link AgentConfig.architecture}; omitted means v1. */
+  /** {@link AgentConfig.architecture}; discovery fills `"v2"` when omitted. */
   readonly architecture?: AgentArchitecture | undefined;
   /** Environment override for tests; defaults to `process.env`. */
   readonly env?: Record<string, string | undefined>;

package/src/internal/platform-timers.ts

@@ -236,6 +236,28 @@ async function timedWorkJsonFetch(
   });
 }
 
+const CP_ERROR_BODY_LIMIT = 512;
+
+/**
+ * Read failures carry status and a bounded body: the guest logs them once
+ * per process, and a 405 body names the route the caller should be on.
+ */
+async function reminderCpReadError(
+  what: string,
+  response: Response
+): Promise<Error> {
+  let body = "";
+  try {
+    body = (await response.text()).trim();
+  } catch {
+    // Status-only detail.
+  }
+  const detail = body === "" ? "" : ` ${body.slice(0, CP_ERROR_BODY_LIMIT)}`;
+  return new Error(
+    `reminder CP ${what} failed: HTTP ${response.status}${detail}`
+  );
+}
+
 /**
  * Cursor-hosted HTTP ReminderControlPlane for architecture v2.
  * Speaks factory `/internal/agentsdk/reminders` (ELB → factory ECS).
@@ -275,7 +297,7 @@ export function createCursorHostedReminderControlPlane(
         return undefined;
       }
       if (!response.ok) {
-        throw new Error(`reminder CP get failed: HTTP ${response.status}`);
+        throw await reminderCpReadError("get", response);
       }
       const parsed: unknown = await response.json();
       return isReminderRecord(parsed) ? parsed : undefined;
@@ -287,7 +309,7 @@ export function createCursorHostedReminderControlPlane(
         `${AGENTSDK_REMINDERS_PREFIX}/reminders`
       );
       if (!response.ok) {
-        throw new Error(`reminder CP list failed: HTTP ${response.status}`);
+        throw await reminderCpReadError("list", response);
       }
       const parsed: unknown = await response.json();
       if (