@cursor/july 0.1.111 → 0.1.113

package/src/channels/slack/dispatch.ts

@@ -9,7 +9,9 @@ import {
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
 import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
+import type { HostedAdmissionPlatformHandoff } from "../../internal/hosted-delivery-protocol.js";
 import { routeLocalIngressContinuation } from "../../internal/local-ingress.js";
+import { mapThrownRequestError } from "../../internal/request-error-status.js";
 import { isSlackImChannel } from "../../internal/slack-thread-key.js";
 import { steeringEnabled } from "../../internal/steering.js";
 import type {
@@ -49,7 +51,12 @@ import {
 } from "./inbound.js";
 import { defaultSlackLog, type SlackLog } from "./log.js";
 import { paintTurnStart, retractTurnStart } from "./paint-start.js";
-import { startPlaceholder } from "./placeholder.js";
+import {
+  adoptPlaceholder,
+  retractPlaceholderMessage,
+  retractPlaceholderSlot,
+  startPlaceholder,
+} from "./placeholder.js";
 import { isWholeMessageStop } from "./stop.js";
 import {
   loadSlackThreadContextBlock,
@@ -219,9 +226,16 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    * Static replaceable first message. Fired with `send()`
    * locally, and on hosted admission when the continuation already
    * exists (warm / coalesced follow-up). Cold hosted posts it on
-   * `turn.started`. Overlay claims that slot.
+   * `turn.started` unless {@link platformHandoff} already seeded the
+   * slot from a control-plane post. Overlay claims that slot.
    */
   placeholder?: string;
+  /**
+   * Trusted control-plane handoff (Slack placeholder ts). Hosted
+   * admission passes this so the guest adopts the CP-posted message
+   * instead of posting a duplicate.
+   */
+  platformHandoff?: HostedAdmissionPlatformHandoff;
   /**
    * When false, skip the built-in `eval` directive. Defaults to true when
    * `host.evals` is present; only ever runs on mentions and DMs.
@@ -307,6 +321,7 @@ function scheduleInbound(
     handler: SlackMessageHandler;
     evalCommandsEnabled?: boolean;
     eventId?: string;
+    platformHandoff?: HostedAdmissionPlatformHandoff;
   }
 ): void {
   deps.waitUntil(
@@ -327,6 +342,9 @@ function scheduleInbound(
       blockExternals: deps.blockExternals,
       ...inboundContinuation(deps),
       ...(args.eventId === undefined ? {} : { eventId: args.eventId }),
+      ...(args.platformHandoff === undefined
+        ? {}
+        : { platformHandoff: args.platformHandoff }),
     })
   );
 }
@@ -388,6 +406,8 @@ export async function dispatchInboundMessage(args: {
   ack?: string;
   /** See {@link SlackInboundDispatchDeps.placeholder}. */
   placeholder?: string;
+  /** See {@link SlackInboundDispatchDeps.platformHandoff}. */
+  platformHandoff?: HostedAdmissionPlatformHandoff;
   /** See {@link SlackInboundDispatchDeps.propagateHandlerErrors}. */
   propagateHandlerErrors?: boolean;
 }): Promise<void> {
@@ -413,6 +433,69 @@ export async function dispatchInboundMessage(args: {
     team: message.teamId,
   });
 
+  const handoff = args.platformHandoff?.slackPlaceholder;
+  const handoffInThread =
+    kind !== "channel_post" &&
+    handoff !== undefined &&
+    handoff.channelId === message.channelId &&
+    handoff.threadTs === message.threadTs
+      ? handoff
+      : undefined;
+  const matchedHandoff =
+    args.placeholder !== undefined ? handoffInThread : undefined;
+  let adoptedPlaceholder = false;
+  let handoffRetracted = false;
+  const retractUnadoptedHandoff = async (): Promise<void> => {
+    if (matchedHandoff === undefined || handoffRetracted) {
+      return;
+    }
+    handoffRetracted = true;
+    await retractPlaceholderMessage({
+      botToken: args.credentials?.botToken,
+      channelId: matchedHandoff.channelId,
+      ts: matchedHandoff.messageTs,
+      streamed: matchedHandoff.streamed,
+      log,
+    });
+  };
+  const adoptMatchedHandoff = async (): Promise<void> => {
+    if (matchedHandoff === undefined) {
+      return;
+    }
+    const adoption = adoptPlaceholder({
+      channelId: matchedHandoff.channelId,
+      threadTs: matchedHandoff.threadTs,
+      ts: matchedHandoff.messageTs,
+      streamed: matchedHandoff.streamed,
+    });
+    if (adoption === "adopted") {
+      adoptedPlaceholder = true;
+      log.info("placeholder adopted from control-plane handoff", {
+        channel: message.channelId,
+        thread_ts: message.threadTs,
+        message_ts: matchedHandoff.messageTs,
+      });
+      return;
+    }
+    if (adoption === "occupied") {
+      // Another delivery owns this thread's slot. Remove only this delivery's
+      // redundant CP post.
+      await retractUnadoptedHandoff();
+    }
+  };
+  const retractAdoptedPlaceholder = async (): Promise<void> => {
+    if (!adoptedPlaceholder) {
+      return;
+    }
+    adoptedPlaceholder = false;
+    await retractPlaceholderSlot({
+      channelId: message.channelId,
+      threadTs: message.threadTs,
+      botToken: args.credentials?.botToken,
+      log,
+    });
+  };
+
   const userId = message.author?.userId ?? "";
   const teamId = message.teamId;
   let membership: Promise<boolean> | undefined;
@@ -425,6 +508,7 @@ export async function dispatchInboundMessage(args: {
         user: userId,
         event_id: args.eventId,
       });
+      await retractUnadoptedHandoff();
       return;
     }
     membership = isExternalSlackSender({
@@ -463,6 +547,7 @@ export async function dispatchInboundMessage(args: {
   ) {
     if (membership !== undefined && (await membership)) {
       dropExternal();
+      await retractUnadoptedHandoff();
       return;
     }
     log.info("stop directive", {
@@ -484,6 +569,7 @@ export async function dispatchInboundMessage(args: {
     } catch {
       // best-effort status
     }
+    await retractUnadoptedHandoff();
     return;
   }
 
@@ -501,6 +587,7 @@ export async function dispatchInboundMessage(args: {
   if (evalDirective !== null && args.host.evals !== undefined) {
     if (membership !== undefined && (await membership)) {
       dropExternal();
+      await retractUnadoptedHandoff();
       return;
     }
     log.info("eval directive", {
@@ -516,6 +603,7 @@ export async function dispatchInboundMessage(args: {
       evals: args.host.evals,
       binding,
     });
+    await retractUnadoptedHandoff();
     return;
   }
 
@@ -530,8 +618,12 @@ export async function dispatchInboundMessage(args: {
       event_id: args.eventId,
     });
     if (args.propagateHandlerErrors === true) {
+      if (mapThrownRequestError(error)?.retry !== "transient") {
+        await retractUnadoptedHandoff();
+      }
       throw error;
     }
+    await retractUnadoptedHandoff();
     return;
   }
   if (decision === null || decision === undefined) {
@@ -541,6 +633,7 @@ export async function dispatchInboundMessage(args: {
       thread_ts: message.threadTs,
       event_id: args.eventId,
     });
+    await retractUnadoptedHandoff();
     return;
   }
 
@@ -560,6 +653,8 @@ export async function dispatchInboundMessage(args: {
     return;
   }
 
+  await adoptMatchedHandoff();
+
   const painted =
     args.ack === undefined
       ? undefined
@@ -580,8 +675,12 @@ export async function dispatchInboundMessage(args: {
     });
   }
 
+  // A control-plane placeholder is turn scaffolding, not thread history: the
+  // guest posts the reply over that exact ts, so hydrating it would feed the
+  // model its own "still working" line as an already-sent reply.
   const excludeThreadTimestamps = [
     message.ts,
+    ...(handoffInThread === undefined ? [] : [handoffInThread.messageTs]),
     ...(decision.excludeThreadTimestamps ?? []),
   ];
   const mergeMessages = [triggeringMergeMessage(message)];
@@ -639,6 +738,7 @@ export async function dispatchInboundMessage(args: {
       });
     }
     await args.host.slackNudges?.releaseAsk(message.channelId, message.ts);
+    await retractAdoptedPlaceholder();
     return;
   }
   if (message.files !== undefined && message.files.length > 0) {
@@ -688,8 +788,10 @@ export async function dispatchInboundMessage(args: {
     hosted &&
     hasPlaceholder &&
     (message.ts !== message.threadTs || continuationExists);
+  // Adopted slots already exist in Slack; skip a second post. Cold hosted
+  // without a handoff still defers to `turn.started`.
   const placeholder =
-    hasPlaceholder && (!hosted || hostedFollowup)
+    !adoptedPlaceholder && hasPlaceholder && (!hosted || hostedFollowup)
       ? startPlaceholder({
           line: placeholderLine,
           botToken: args.credentials?.botToken,
@@ -700,7 +802,7 @@ export async function dispatchInboundMessage(args: {
           recipientTeamId: message.teamId,
         })
       : undefined;
-  const posted = placeholder !== undefined;
+  const posted = adoptedPlaceholder || placeholder !== undefined;
   const state = emptySlackChannelState({
     channelId: message.channelId,
     threadTs: message.threadTs,
@@ -811,6 +913,7 @@ export async function dispatchInboundMessage(args: {
     if (placeholder !== undefined) {
       await placeholder.retract();
     }
+    await retractAdoptedPlaceholder();
     if (painted !== undefined) {
       await painted;
       await retractTurnStart({
@@ -850,6 +953,21 @@ export function dispatchInboundFromEventBody(
 ): boolean {
   const log = deps.log ?? defaultSlackLog;
   let eventId: string | undefined;
+  const retractUnscheduledHandoff = (): void => {
+    const placeholder = deps.platformHandoff?.slackPlaceholder;
+    if (placeholder === undefined) {
+      return;
+    }
+    deps.waitUntil(
+      retractPlaceholderMessage({
+        botToken: deps.credentials?.botToken,
+        channelId: placeholder.channelId,
+        ts: placeholder.messageTs,
+        streamed: placeholder.streamed,
+        log,
+      })
+    );
+  };
 
   if (body !== null && typeof body === "object" && !Array.isArray(body)) {
     const root = body as { event_id?: unknown };
@@ -857,6 +975,7 @@ export function dispatchInboundFromEventBody(
       eventId = root.event_id;
       if (!deps.eventIds.tryHandle(root.event_id)) {
         log.debug("inbound dedupe drop", { event_id: eventId });
+        retractUnscheduledHandoff();
         return false;
       }
     }
@@ -868,6 +987,7 @@ export function dispatchInboundFromEventBody(
   if (mention !== null) {
     if (deps.mentionsEnabled === false) {
       log.debug("inbound ignored (mentions disabled)", { event_id: eventId });
+      retractUnscheduledHandoff();
       return false;
     }
     if (mention.author?.isBot === true) {
@@ -885,6 +1005,7 @@ export function dispatchInboundFromEventBody(
           from_bot: mention.author.botId ?? mention.author.userId,
           reason: verdict.reason,
         });
+        retractUnscheduledHandoff();
         return false;
       }
     }
@@ -894,6 +1015,7 @@ export function dispatchInboundFromEventBody(
       handler: deps.onAppMention,
       evalCommandsEnabled: deps.evalCommandsEnabled,
       eventId,
+      platformHandoff: deps.platformHandoff,
     });
     return true;
   }
@@ -904,6 +1026,7 @@ export function dispatchInboundFromEventBody(
       log.debug("inbound ignored (direct messages disabled)", {
         event_id: eventId,
       });
+      retractUnscheduledHandoff();
       return false;
     }
     scheduleInbound(deps, log, {
@@ -912,12 +1035,14 @@ export function dispatchInboundFromEventBody(
       handler: deps.onDirectMessage,
       evalCommandsEnabled: deps.evalCommandsEnabled,
       eventId,
+      platformHandoff: deps.platformHandoff,
     });
     return true;
   }
 
   const reaction = parseReactionAddedEvent(body);
   if (reaction !== null && deps.onReactionAdded !== undefined) {
+    retractUnscheduledHandoff();
     scheduleInbound(deps, log, {
       kind: "reaction_added",
       message: reaction,
@@ -982,6 +1107,7 @@ export function dispatchInboundFromEventBody(
       includeBotAuthored: true,
     });
     if (channelEvent !== null) {
+      retractUnscheduledHandoff();
       return deps.channelWatch.handle(channelEvent, eventId);
     }
   }
@@ -990,5 +1116,6 @@ export function dispatchInboundFromEventBody(
     ...describeSlackEventShape(body),
     event_id: eventId,
   });
+  retractUnscheduledHandoff();
   return false;
 }

package/src/channels/slack/placeholder.ts

@@ -122,6 +122,16 @@ async function retractKey(key: string, args: FinishArgs): Promise<void> {
   });
 }
 
+/** Retract only one thread's slot; admission cleanup must not sweep DM peers. */
+export async function retractPlaceholderSlot(args: {
+  channelId: string;
+  threadTs: string;
+  botToken: SlackBotToken | undefined;
+  log?: SlackLog;
+}): Promise<void> {
+  await retractKey(slotKey(args.channelId, args.threadTs), args);
+}
+
 export async function finishPlaceholder(args: {
   channelId: string;
   threadTs: string;
@@ -155,6 +165,47 @@ export function startPlaceholder(args: {
   };
 }
 
+/**
+ * Seed the in-process placeholder slot with a control-plane-posted message
+ * ts so the first agentic update overlays that exact Slack message.
+ */
+export type PlaceholderAdoption = "adopted" | "already_adopted" | "occupied";
+
+export function adoptPlaceholder(args: {
+  channelId: string;
+  threadTs: string;
+  ts: string;
+  streamed?: boolean;
+}): PlaceholderAdoption {
+  const key = slotKey(args.channelId, args.threadTs);
+  const existing = slots.get(key);
+  if (
+    existing !== undefined &&
+    !existing.claimed &&
+    existing.ts === args.ts &&
+    existing.streamed === (args.streamed === true)
+  ) {
+    return "already_adopted";
+  }
+  if (!openPlaceholder(key)) {
+    return "occupied";
+  }
+  return rememberPlaceholder(key, args.ts, args.streamed === true)
+    ? "adopted"
+    : "occupied";
+}
+
+/** Delete a control-plane placeholder that this process could not adopt. */
+export async function retractPlaceholderMessage(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  ts: string;
+  streamed: boolean;
+  log?: SlackLog;
+}): Promise<void> {
+  await retractPosted(args);
+}
+
 async function postPlaceholder(args: {
   line: string;
   botToken: SlackBotToken | undefined;

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

@@ -259,6 +259,7 @@ export function slackChannel(
       continuationToken: string
     ) => Promise<string | undefined>;
     interruptContinuation?: (continuationToken: string) => Promise<boolean>;
+    platformHandoff?: SlackInboundDispatchDeps["platformHandoff"];
   }): SlackInboundDispatchDeps {
     return {
       send: args.send,
@@ -280,6 +281,9 @@ export function slackChannel(
       ack: reply.ack,
       placeholder: reply.placeholder,
       blockExternals,
+      ...(args.platformHandoff === undefined
+        ? {}
+        : { platformHandoff: args.platformHandoff }),
       ...(args.hasContinuationSession === undefined
         ? {}
         : { hasContinuationSession: args.hasContinuationSession }),
@@ -319,7 +323,9 @@ export function slackChannel(
               ack: reply.ack ?? DEFAULT_ACK,
               ...(reply.placeholder === undefined
                 ? {}
-                : { placeholder: reply.placeholder }),
+                : {
+                    placeholder: reply.placeholder,
+                  }),
             },
           }
         : {}),
@@ -654,7 +660,7 @@ export function slackChannel(
     // claim already dedupes Slack retries, and on a warm pod the local set
     // would otherwise swallow the control plane's own retry of a delivery
     // that failed after the id was marked handled.
-    dispatch: async ({ payload, args }) => {
+    dispatch: async ({ payload, args, platformHandoff }) => {
       const dispatched = dispatchInboundFromEventBody(
         payload,
         inboundDeps({
@@ -668,6 +674,7 @@ export function slackChannel(
           isContinuationBusy: args.isContinuationBusy,
           getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
           interruptContinuation: args.interruptContinuation,
+          ...(platformHandoff === undefined ? {} : { platformHandoff }),
         })
       );
       return skipped(dispatched ? "not_engaged" : "not_dispatchable");

package/src/extensions/cursor-cloud-agents/skills/handoff.md

@@ -16,17 +16,13 @@ The result carries `agentId` (`bc-...`) and a `url`. Report both in full. Never
 
 ## Look an agent up by id
 
-Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, or `expired`), its `branch` and pull request `prUrl` once pushed, the `changes` it made so far (files and lines), a `summary` when one exists, and an `error` when it failed. A run takes minutes: check when asked or when you need the result, not in a tight loop. The final report itself comes from `dump`.
+Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, `expired`, or `unknown`), its `branch` and pull request `prUrl` once pushed, change counts, a `summary` when one exists, and an `error` when it failed. A run takes minutes: check when asked or when you need the result, not in a tight loop. The final report itself comes from `dump`.
 
 ## Read what it did
 
-To read the report or understand what was done, call `dump` with the `agent_id`. It writes the agent's whole conversation, every run, to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus the `finalMessage`. Each line is one JSON message with `role` (`user` or `assistant`) and, for assistant lines, `text`, `thinking`, and `toolCalls` (tool `name`, `args`, `content`, `error`). Read it with your file and shell tools, using the returned path:
+To read the report or understand what was done, call `dump` with the `agent_id`. Once a transcript exists, it writes the agent's whole conversation to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus `finalMessage`. Before any transcript exists, either value may be absent; wait for output instead of inventing a report.
 
-- `tail -n 1 <path>` gives the final report.
-- `grep '"toolCalls"' <path>` shows the commands and edits it made.
-- `grep '"role":"user"' <path>` shows every prompt it received, including replies.
-
-Use `dump` before summarizing an agent's work for a person, and to understand a failure before replying with a fix.
+Use `finalMessage` as the agent's report. Read the returned transcript path when you need its prompts, reasoning, or tool calls, then inspect the resulting branch or pull request before claiming exact code changes. The transcript is evidence of what the agent did, not a canonical diff.
 
 ## Reply
 

package/src/extensions/improve/extension.ts

@@ -3,7 +3,9 @@
  * 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.
+ * pull request. Durable behavior changes only after review, merge, and
+ * deployment. A cloud-runtime turn may edit its ephemeral checkout while
+ * preparing the pull request.
  *
  * ```ts
  * // agent/extensions/improve.ts
@@ -52,7 +54,7 @@ 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.",
+    "Propose changes to your own source through a branch and pull request; durable behavior changes after review and deployment.",
   config: z.object({
     repo: z.string().url(),
     path: z

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

@@ -29,7 +29,7 @@ Under \`${path}/agent/\`:
 ${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.
+Durable source changes happen on a branch from a clean checkout of ${repo} at \`${ref}\`, never by mutating a deployed local-runtime copy. When your own turn runs on a cloud VM with that repository checked out, its ephemeral tree 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\` instead of launching another.
 
 ## The brief
 

package/src/extensions/jev/extension.ts

@@ -0,0 +1,95 @@
+/**
+ * Jev decisions as an extension. Mount it and the agent can ask Jev for
+ * typed boolean, choice, and score answers, then call `decide` from your
+ * own channel hooks and tools before they start a turn or write.
+ *
+ * ```ts
+ * // agent/extensions/jev.ts
+ * import jev from "@cursor/july/extensions/jev";
+ *
+ * export default jev();
+ * ```
+ *
+ * Contributes `<namespace>__evaluate` plus the `questions` and
+ * `gated-write` skills (the namespace is the mount filename). Auth is
+ * `TYPESAFE_API_KEY`. The default model is `jev-latest`. Custom tools
+ * import `decide`, `above`, and `needsHuman` from this same module. Set
+ * `harnessTools` or `skills` to false when the agent should not see those
+ * contributions.
+ */
+
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import type { Extension } from "../../types.js";
+import { DEFAULT_EVALUATION_MODEL } from "./lib/evaluate.js";
+
+/** Mount options; every field is optional. */
+export interface JevOptions {
+  /** TypeSafe API key. Defaults to `TYPESAFE_API_KEY`. */
+  apiKey?: string;
+  /** TypeSafe model id. Defaults to `jev-latest`. */
+  model?: string;
+  /** Mount the namespaced `evaluate` harness tool. Defaults to true. */
+  harnessTools?: boolean;
+  /** Mount the `questions` and `gated-write` skills. Defaults to true. */
+  skills?: boolean;
+}
+
+/** {@link JevOptions} with defaults applied. */
+export interface JevConfig {
+  apiKey?: string;
+  model: string;
+  harnessTools: boolean;
+  skills: boolean;
+}
+
+const config: z.ZodType<JevConfig, z.ZodTypeDef, JevOptions | undefined> = z
+  .object({
+    apiKey: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    harnessTools: z.boolean().default(true),
+    skills: z.boolean().default(true),
+  })
+  .default({})
+  .transform(options => ({
+    apiKey: options.apiKey,
+    model: options.model ?? DEFAULT_EVALUATION_MODEL,
+    harnessTools: options.harnessTools,
+    skills: options.skills,
+  }));
+
+const jev: Extension<JevConfig, JevOptions | undefined> = defineExtension({
+  root: import.meta.dirname,
+  description: "Ask Jev for typed choice, score, and boolean answers.",
+  config,
+  contributions: options => ({
+    tools: options.harnessTools,
+    skills: options.skills,
+  }),
+});
+
+export type {
+  AnswersFor,
+  BooleanAnswer,
+  BooleanQuestion,
+  ChoiceAnswer,
+  ChoiceQuestion,
+  EvaluateArgs,
+  EvaluateResult,
+  EvaluationAnswer,
+  EvaluationQuestion,
+  EvaluationState,
+  QuestionMap,
+  ScoreAnswer,
+  ScoreQuestion,
+} from "./lib/evaluate.js";
+export {
+  above,
+  DEFAULT_EVALUATION_MODEL,
+  DEFAULT_HUMAN_THRESHOLD,
+  decide,
+  evaluate,
+  needsHuman,
+} from "./lib/evaluate.js";
+
+export default jev;