@cursor/july 0.1.97 → 0.1.100

package/src/internal/hosted-execution-diag.ts

@@ -46,6 +46,8 @@ export type HostedExecutionDiag = {
   turnStatus: string;
   durationMs: number;
   message?: string;
+  /** First frames of a thrown Error; omitted on soft turn failures. */
+  stack?: string;
   signalAborted?: boolean;
   requestId?: string;
   abortReason?: HostedExecutionDiagAbortReason;
@@ -63,6 +65,7 @@ const DIAG_KEYS = new Set([
   "turnStatus",
   "durationMs",
   "message",
+  "stack",
   "signalAborted",
   "requestId",
   "abortReason",
@@ -86,6 +89,42 @@ function boundedOptionalString(
     : undefined;
 }
 
+/** First line + frames; factory `last_error` is 1024 chars with a TAS prefix. */
+export const HOSTED_ERROR_STACK_LINE_COUNT = 5;
+export const HOSTED_ERROR_SNIPPET_MAX_CHARS = 700;
+
+/**
+ * Bounded throw text for the hosted 500 body and the on-disk diag `stack`.
+ * Prefers `Error.stack` (message line + `at` frames) so `last_error` is not
+ * the generic "Internal server error." when the throw has a stack.
+ */
+export function hostedErrorStackSnippet(error: unknown): string {
+  if (error instanceof Error) {
+    const stack = error.stack?.trim();
+    if (stack !== undefined && stack.length > 0) {
+      const lines = stack
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0)
+        .slice(0, HOSTED_ERROR_STACK_LINE_COUNT);
+      const text = lines.join("\n");
+      return text.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
+        ? `${text.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
+        : text;
+    }
+    return error.message.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
+      ? `${error.message.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
+      : error.message;
+  }
+  const text = String(error);
+  if (text.length === 0) {
+    return "";
+  }
+  return text.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
+    ? `${text.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
+    : text;
+}
+
 export function hostedExecutionDiagPath(stateRoot: string): string {
   return join(stateRoot, HOSTED_EXECUTION_DIAG_FILENAME);
 }
@@ -147,6 +186,10 @@ export function parseHostedExecutionDiag(
     return undefined;
   }
   const message = boundedOptionalString(body.message, 1024);
+  const stack = boundedOptionalString(
+    body.stack,
+    HOSTED_ERROR_SNIPPET_MAX_CHARS
+  );
   const requestId = boundedOptionalString(body.requestId, 128);
   const abortReason =
     body.abortReason === undefined
@@ -173,6 +216,7 @@ export function parseHostedExecutionDiag(
     turnStatus: body.turnStatus,
     durationMs: body.durationMs,
     ...(message === undefined ? {} : { message }),
+    ...(stack === undefined ? {} : { stack }),
     ...(body.signalAborted === true ? { signalAborted: true } : {}),
     ...(requestId === undefined ? {} : { requestId }),
     ...(abortReason === undefined ? {} : { abortReason }),
@@ -196,6 +240,7 @@ export async function writeHostedExecutionDiag(
       serialized.length > HOSTED_EXECUTION_DIAG_MAX_BYTES
         ? JSON.stringify({
             ...diag,
+            stack: undefined,
             message: boundedOptionalString(diag.message, 256),
           })
         : serialized;

package/src/internal/http-channel.ts

@@ -95,6 +95,13 @@ export function buildHttpChannelRoutes(args: {
           "Expected a JSON body with a string `message`."
         );
       }
+      if (body.asOf !== undefined && typeof body.asOf !== "string") {
+        return errorResponse(
+          400,
+          "invalid_request",
+          "`asOf` must be an ISO-8601 instant with a timezone when provided."
+        );
+      }
       const message = await transformMessage(body.message, ctx.auth);
       const workspaceFiles = readWorkspaceFiles(body.workspaceFiles);
       // Per-session cloud attach (create only). Eval harness uses this to pin
@@ -105,6 +112,7 @@ export function buildHttpChannelRoutes(args: {
         ...(typeof body.title === "string" ? { title: body.title } : {}),
         ...(body.purpose === "eval" ? { purpose: "eval" as const } : {}),
         ...(body.dryRun === true ? { dryRun: true } : {}),
+        asOf: body.asOf,
         ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
         ...(cloud === undefined ? {} : { cloud }),
       });

package/src/internal/server.ts

@@ -50,6 +50,7 @@ import type {
   ReminderInfo,
   ServeOptions,
 } from "../types.js";
+import { InvalidAsOfError, VacuousTimeArgsError } from "./as-of.js";
 import { V2EngineError } from "./continuation-identity.js";
 import { selectConversationMirror } from "./conversation-mirror.js";
 import {
@@ -109,6 +110,7 @@ import {
 } from "./handleAgentServeTrigger.js";
 import { createHostPlatforms, warmupHostGitHubAuth } from "./host-platforms.js";
 import { registerHostedDeliveryRoute } from "./hosted-delivery.js";
+import { hostedErrorStackSnippet } from "./hosted-execution-diag.js";
 import {
   buildHttpChannelRoutes,
   errorResponse,
@@ -186,6 +188,11 @@ import {
   UnknownToolError,
   WorkspaceUnavailableError,
 } from "./session-engine.js";
+import {
+  registerSessionRunFatalFlush,
+  selectSessionRunLogStore,
+  unregisterSessionRunFatalFlush,
+} from "./session-run-log.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
 import { catalogDetailEntry, catalogListEntry } from "./tool-catalog.js";
 
@@ -247,6 +254,8 @@ export interface StartServerInternalOptions {
   runner?: AgentRunner;
   /** Test seam: bind the `--store` secrets client for on-demand MCP OAuth. */
   mcpOauthSecrets?: McpOauthSecretsTarget;
+  /** Test seam: persist hosted-execution run logs without a live store. */
+  sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
 }
 
 /**
@@ -532,6 +541,20 @@ export async function startServer(
     mounts.length === 1 && mounts[0] !== undefined
       ? selectConversationMirror({ project: mounts[0].project, logger })
       : undefined;
+  const sessionRunLog =
+    options.sessionRunLog ??
+    (mounts.length === 1 && mounts[0] !== undefined
+      ? selectSessionRunLogStore({
+          project: mounts[0].project,
+          logger,
+          snapshotLogs: () => logRing.since(),
+        })
+      : undefined);
+  if (sessionRunLog !== undefined) {
+    registerSessionRunFatalFlush((error) =>
+      sessionRunLog.flushProcessDeath("uncaught_exception", error)
+    );
+  }
   const sdkRunner =
     options.runner ??
     new CursorSdkRunner({
@@ -746,6 +769,7 @@ export async function startServer(
       logger,
       logRing,
       diagStateRoot: baseStateRoot,
+      sessionRunLog,
       ...(options.authToken === undefined
         ? {}
         : { authToken: options.authToken }),
@@ -1199,6 +1223,10 @@ export async function startServer(
       return runtime.engine.callTool(toolName, input, callOptions);
     },
     close: async () => {
+      if (sessionRunLog !== undefined) {
+        await sessionRunLog.flushProcessDeath("process_exit");
+        unregisterSessionRunFatalFlush();
+      }
       playgroundDev?.stop();
       await cursorDeploymentRelay?.stop();
       await cursorEventRelay?.stop();
@@ -1253,6 +1281,7 @@ function mountAgentRoutes(
     multi: boolean;
     logger: (line: string) => void;
     logRing: LogRing;
+    sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
     authToken?: string;
     allowAnonymous?: boolean;
     /** Cursor account bridge + this mount's account MCP connections, when authored. */
@@ -1266,7 +1295,15 @@ function mountAgentRoutes(
   }
 ): void {
   const { slug, project, engine, scheduleRunner, reminderRunner } = runtime;
-  const { dev, playground, noControlPlane, multi, logger, logRing } = args;
+  const {
+    dev,
+    playground,
+    noControlPlane,
+    multi,
+    logger,
+    logRing,
+    sessionRunLog,
+  } = args;
   // "" (single) -> "/v1/..."; "my-agent" (multi) -> "/my-agent/v1/...".
   const base = slug === "" ? "" : `/${slug}`;
 
@@ -1327,6 +1364,10 @@ function mountAgentRoutes(
       ...(args.diagStateRoot === undefined
         ? {}
         : { stateRoot: args.diagStateRoot }),
+      ...(sessionRunLog === undefined
+        ? {}
+        : { persistSessionRun: (document) => sessionRunLog.persist(document) }),
+      snapshotLogs: () => logRing.since(),
     });
   }
   // Playground lists/opens Slack (and other channel) sessions across
@@ -1433,6 +1474,51 @@ function mountAgentRoutes(
     },
   });
 
+  // v2 only: one session-level hosted-execution log on the framework
+  // store. Distinct from GET /v1/logs (process-wide ring). Keyed by the
+  // factory session public id so an execute_throw that never minted a
+  // July session is still readable after the pod parks.
+  if (isV2Project(project) && sessionRunLog !== undefined) {
+    router.add({
+      method: "GET",
+      pattern: `${base}/v1/session/:sessionId/runs`,
+      auth: httpAuth,
+      handler: async (_request, ctx) => {
+        const sessionId = ctx.params.sessionId ?? "";
+        if (sessionId.length === 0 || sessionId.includes("/")) {
+          return errorResponse(
+            400,
+            "invalid_request",
+            "Expected a session id."
+          );
+        }
+        const record = await engine.getOrRestoreSession(sessionId);
+        if (record === undefined) {
+          return errorResponse(
+            404,
+            "session_not_found",
+            `Unknown session ${sessionId}.`
+          );
+        }
+        const ownership = requireSessionOwner(record, ctx.auth, {
+          relax: relaxSessionReadAuth,
+          beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+          requestIp: ctx.requestIp,
+        });
+        if (ownership !== undefined) {
+          return ownership;
+        }
+        const document = await sessionRunLog.read(sessionId);
+        return jsonResponse({
+          sessionId,
+          updatedAt: document?.updatedAt,
+          lastFailure: document?.lastFailure ?? null,
+          executions: document?.executions ?? [],
+        });
+      },
+    });
+  }
+
   router.add({
     method: "GET",
     pattern: `${base}/v1/sessions`,
@@ -2829,6 +2915,11 @@ async function handleRequest(
       );
     } else if (error instanceof SessionAuthError) {
       response = errorResponse(403, "forbidden", error.message);
+    } else if (
+      error instanceof InvalidAsOfError ||
+      error instanceof VacuousTimeArgsError
+    ) {
+      response = errorResponse(400, "invalid_request", error.message);
     } else {
       logger(
         `[agent-sdk] request failed: ${
@@ -2837,7 +2928,14 @@ async function handleRequest(
             : String(error)
         }`
       );
-      response = errorResponse(500, "internal_error", "Internal server error.");
+      const snippet = hostedErrorStackSnippet(error);
+      response = errorResponse(
+        500,
+        "internal_error",
+        snippet.length > 0
+          ? `Internal server error: ${snippet}`
+          : "Internal server error."
+      );
     }
   }
 

package/src/internal/session-engine.ts

@@ -89,6 +89,7 @@ import {
 } from "./advertise-tools.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
+import { assertTimeArgs, normalizeAsOf, sessionClock } from "./as-of.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import {
@@ -1023,12 +1024,15 @@ export class SessionEngine {
     const now = new Date().toISOString();
     const channelState = this.initialChannelState(channelId, sendOptions.state);
     const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
+    const frozenAsOf = normalizeAsOf(sendOptions.asOf);
+    assertTimeArgs(this.project.agent.tools, frozenAsOf);
     let record: SessionRecord = {
       sessionId: sendOptions.hostedSessionId ?? newSessionId(),
       channelId,
       mode: sendOptions.mode ?? "chat",
       purpose,
       dryRun: sendOptions.dryRun === true ? true : undefined,
+      asOf: frozenAsOf,
       continuationKey: sendOptions.continuationToken ?? newContinuationKey(),
       auth,
       title: sendOptions.title,
@@ -2207,6 +2211,8 @@ export class SessionEngine {
         channelId: record.channelId,
         channelKind: this.channelsById.get(record.channelId)?.meta?.kind,
         environment: isDevMode() ? "local dev server" : "hosted deployment",
+        now:
+          record.asOf === undefined ? undefined : sessionClock(record.asOf)(),
       });
       turnPrompt = `${contextBlock}\n\n${prompt}`;
     }
@@ -2727,6 +2733,7 @@ export class SessionEngine {
       getSession: (channelId, sessionId) =>
         this.getChannelSession(channelId, sessionId),
       emit: args.emit,
+      now: sessionClock(args.record.asOf),
     };
     try {
       // Before the approval gate: a dry run is unattended, so parking a write
@@ -2744,6 +2751,8 @@ export class SessionEngine {
           : {}),
         dryRunResult: args.tool.definition.dryRunResult,
         input: validation.value,
+        asOf: args.record.asOf,
+        timeArgs: args.tool.definition.timeArgs,
       });
       if (decision.kind === "answer") {
         this.stubbedCallIds.get(args.record.sessionId)?.add(toolCallId);
@@ -2752,6 +2761,12 @@ export class SessionEngine {
         );
         return normalizeToolResult(decision.result);
       }
+      if (decision.kind === "unbounded") {
+        this.logger(
+          `[session] tool ${args.tool.name} refused, unbounded_time (${toolCallId})`
+        );
+        return toolErrorResult(decision.message);
+      }
       if (decision.kind === "refuse") {
         this.logger(
           `[session] tool ${args.tool.name} refused, effect unclassified (${toolCallId})`
@@ -3615,6 +3630,8 @@ export class SessionEngine {
         : {}),
       dryRunResult: tool.definition.dryRunResult,
       input: validation.value,
+      asOf: record?.asOf,
+      timeArgs: tool.definition.timeArgs,
     });
 
     const started = Date.now();
@@ -3633,7 +3650,13 @@ export class SessionEngine {
             }).catch(() => {});
           };
     try {
-      if (decision.kind === "refuse") {
+      if (decision.kind === "unbounded") {
+        this.logger(
+          `[session] tool ${toolName} refused, unbounded_time (direct ${callId})`
+        );
+        result = normalizeToolResult(toolErrorResult(decision.message));
+        isError = true;
+      } else if (decision.kind === "refuse") {
         this.logger(
           `[session] tool ${toolName} refused, effect unclassified (direct ${callId})`
         );
@@ -3676,6 +3699,7 @@ export class SessionEngine {
             getSession: (channelId, sessionId) =>
               this.getChannelSession(channelId, sessionId),
             emit,
+            now: sessionClock(record?.asOf),
           });
         result = normalizeToolResult(
           record !== undefined && emit !== undefined
@@ -3787,6 +3811,12 @@ export class SessionEngine {
     if (decision.kind === "run") {
       return { answered: false };
     }
+    if (decision.kind === "unbounded") {
+      this.logger(
+        `[session] bridged tool ${args.toolName} refused, unbounded_time (${args.sessionId})`
+      );
+      return { answered: true, result: toolErrorResult(decision.message) };
+    }
     if (decision.kind === "refuse") {
       this.logger(
         `[session] bridged tool ${args.toolName} refused, effect unclassified (${args.sessionId})`
@@ -4562,6 +4592,7 @@ export class SessionEngine {
       mode: record.mode,
       purpose: record.purpose === "eval" ? "eval" : "live",
       dryRun: record.dryRun === true ? true : undefined,
+      asOf: record.asOf,
       auth: record.auth,
       continuationKey: record.continuationKey,
       ...(record.abs === undefined ? {} : { abs: record.abs }),