@cursor/july 0.1.96 → 0.1.99

package/src/internal/hosted-delivery.ts

@@ -1,10 +1,4 @@
 import { randomBytes } from "node:crypto";
-import {
-  dispatchGitHubWebhook,
-  getGitHubChannelOptions,
-  getGitHubDispatchOutcome,
-  withPropagatingGitHubBackgroundErrors,
-} from "../channels/github/github-channel.js";
 import type {
   AuthPolicy,
   ChannelHandlerArgs,
@@ -14,6 +8,10 @@ import {
   createDeferredChannelSession,
   DeferredChannelSessionError,
 } from "./deferred-channel-session.js";
+import {
+  getHostedAdmissionAdapter,
+  type HostedAdmissionAdapter,
+} from "./hosted-admission-adapter.js";
 import {
   HostedAdmissionLocalSendError,
   runDuringHostedAdmission,
@@ -27,9 +25,22 @@ import {
   parseHostedAdmission,
   parseHostedExecution,
 } from "./hosted-delivery-protocol.js";
+import {
+  abortReasonFromTurnStatus,
+  HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+  hostedErrorStackSnippet,
+  hostedExecutionDiagId,
+  writeHostedExecutionDiag,
+} from "./hosted-execution-diag.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { errorResponse, readJsonObject } from "./http-channel.js";
+import type { LogRingEntry } from "./log-ring.js";
 import type { Router } from "./router.js";
+import {
+  type SessionRunExecutionWrite,
+  serializeSessionRunError,
+  snapshotSessionRunLogs,
+} from "./session-run-log.js";
 
 type DispatchInput = {
   delivery: HostedAdmission;
@@ -109,17 +120,20 @@ function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
 }
 
 /**
- * Run authored admission without creating a framework session. V1 GitHub
+ * Run authored admission without creating a framework session. Authored
  * `task` callbacks execute as sessionless work; the first `send` is captured
  * and executed only after the control plane allocates `ses_…`. Capturing
  * does not terminate the caller — `send` returns an inert deferred handle so
  * a task body runs to completion before the admission response is computed.
+ *
+ * Dispatch is the adapter the mounted channel attached. Hosted delivery
+ * does not switch on `channelKind`.
  */
 export async function dispatchHostedAdmission(
   input: DispatchInput
 ): Promise<AdmissionDispatch> {
-  const github = getGitHubChannelOptions(input.definition);
-  if (github === undefined) {
+  const adapter = getHostedAdmissionAdapter(input.definition);
+  if (adapter === undefined || adapter.kind !== input.delivery.channelKind) {
     return {
       response: Response.json(
         { ok: false, error: "channel_kind_mismatch" },
@@ -129,16 +143,16 @@ export async function dispatchHostedAdmission(
   }
   // The admission window marker follows the async graph into task bodies so
   // the engine can refuse local sends that would bypass the capture stub.
-  return runDuringHostedAdmission(() => runAdmission(input, github));
+  return runDuringHostedAdmission(() => runAdmission(input, adapter));
 }
 
 async function runAdmission(
   input: DispatchInput,
-  github: NonNullable<ReturnType<typeof getGitHubChannelOptions>>
+  adapter: HostedAdmissionAdapter
 ): Promise<AdmissionDispatch> {
   const background: Promise<unknown>[] = [];
   let captured: { message: string; options: SendMessageOptions } | undefined;
-  const args = withPropagatingGitHubBackgroundErrors({
+  const capturingArgs: ChannelHandlerArgs = {
     ...input.args,
     send: async (message, options = {}) => {
       if (captured !== undefined) {
@@ -150,12 +164,12 @@ async function runAdmission(
     waitUntil: (promise) => {
       background.push(promise);
     },
-  });
+  };
+  const args = adapter.prepareArgs?.(capturingArgs) ?? capturingArgs;
   let dispatched: Response;
   try {
-    dispatched = await dispatchGitHubWebhook({
-      options: github,
-      eventName: input.delivery.eventType,
+    dispatched = await adapter.dispatch({
+      eventType: input.delivery.eventType,
       payload: input.delivery.payload,
       deliveryId: input.delivery.deliveryId,
       args,
@@ -206,7 +220,7 @@ async function runAdmission(
       },
     };
   }
-  const outcome = getGitHubDispatchOutcome(dispatched);
+  const outcome = adapter.getOutcome(dispatched);
   if (outcome === undefined) {
     return {
       response: Response.json(
@@ -252,6 +266,21 @@ export function registerHostedDeliveryRoute(input: {
    * the conversation on the next wake.
    */
   drainSessionDurability?(sessionId: string): Promise<void>;
+  /**
+   * Serve `--state-root` (not the per-slug SessionEngine dir). Hosted
+   * freeze is `/workspace/.agent-serve`; the Temporal host reads
+   * `hosted-execution.json` from that path after the POST returns.
+   */
+  stateRoot?: string;
+  /**
+   * Upsert this execution into the v2 session-level framework-store log.
+   * Called for the pre-turn `running` claim and every terminal outcome so
+   * a dead Node process still leaves a leftover. Soft-fail inside the
+   * store; this path still awaits so a parked pod cannot shed the write.
+   */
+  persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
+  /** Snapshot of the process log ring at persist time. */
+  snapshotLogs?(): LogRingEntry[];
 }): void {
   const pending = new Map<
     string,
@@ -383,39 +412,135 @@ export function registerHostedDeliveryRoute(input: {
       }
       admitted.sessionPublicId = execution.sessionPublicId;
       admitted.execution ??= (async (): Promise<ExecutionReply> => {
-        const args = input.buildHandlerArgs(
-          admitted.send.channelId,
-          execution.sessionPublicId
-        );
-        const session = await args.send(admitted.send.message, {
-          ...admitted.send.options,
-          mailboxContinuation: {
-            key: admitted.send.mailboxContinuationKey,
-          },
+        const startedAt = performance.now();
+        const executionId = hostedExecutionDiagId(execution.admissionToken);
+        const writeDiag = async (fields: {
+          sessionId: string;
+          turnStatus: string;
+          message?: string;
+          abortReason?:
+            | ReturnType<typeof abortReasonFromTurnStatus>
+            | "execute_throw";
+          error?: unknown;
+        }): Promise<void> => {
+          const durationMs = Math.max(
+            0,
+            Math.round(performance.now() - startedAt)
+          );
+          const message =
+            fields.message === undefined
+              ? undefined
+              : boundedMessage(fields.message);
+          const stack =
+            fields.error === undefined
+              ? undefined
+              : hostedErrorStackSnippet(fields.error);
+          if (input.stateRoot !== undefined) {
+            await writeHostedExecutionDiag(input.stateRoot, {
+              v: 1,
+              executionId,
+              writtenAt: new Date().toISOString(),
+              sessionPublicId: execution.sessionPublicId,
+              sessionId: fields.sessionId,
+              turnStatus: fields.turnStatus,
+              durationMs,
+              ...(message === undefined ? {} : { message }),
+              ...(stack === undefined || stack.length === 0 ? {} : { stack }),
+              ...(message !== undefined && /abort/i.test(message)
+                ? { signalAborted: true }
+                : {}),
+              ...(fields.abortReason === undefined
+                ? {}
+                : { abortReason: fields.abortReason }),
+            });
+          }
+          if (input.persistSessionRun === undefined) {
+            return;
+          }
+          const error =
+            fields.error === undefined
+              ? undefined
+              : serializeSessionRunError(fields.error);
+          try {
+            await input.persistSessionRun({
+              executionId,
+              writtenAt: new Date().toISOString(),
+              sessionPublicId: execution.sessionPublicId,
+              sessionId: fields.sessionId,
+              turnStatus: fields.turnStatus,
+              durationMs,
+              ...(fields.abortReason === undefined
+                ? {}
+                : { abortReason: fields.abortReason }),
+              ...(message === undefined ? {} : { message }),
+              ...(error === undefined ? {} : { error }),
+              logs: snapshotSessionRunLogs(input.snapshotLogs?.() ?? []),
+            });
+          } catch {
+            // Soft-fail: a store outage must not change the HTTP reply.
+          }
+        };
+        // Claim the file before the turn runs. The host reads it after its
+        // own POST returns, which for a 9-minute timeout is while this turn
+        // is still going; without this marker that read would surface the
+        // PREVIOUS delivery's terminal record as if it were this one's.
+        await writeDiag({
+          sessionId: "",
+          turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
         });
-        const outcome = await session.waitForCompletion();
-        // Failed turns drain too: their record/continuation updates must
-        // survive the park just like a finished turn's.
-        await input.drainSessionDurability?.(session.id);
-        if (outcome.status !== "finished") {
+        try {
+          const args = input.buildHandlerArgs(
+            admitted.send.channelId,
+            execution.sessionPublicId
+          );
+          const session = await args.send(admitted.send.message, {
+            ...admitted.send.options,
+            mailboxContinuation: {
+              key: admitted.send.mailboxContinuationKey,
+            },
+          });
+          const outcome = await session.waitForCompletion();
+          // Failed turns drain too: their record/continuation updates must
+          // survive the park just like a finished turn's.
+          await input.drainSessionDurability?.(session.id);
+          await writeDiag({
+            sessionId: session.id,
+            turnStatus: outcome.status,
+            message: outcome.errorMessage,
+            abortReason: abortReasonFromTurnStatus(
+              outcome.status,
+              outcome.errorMessage
+            ),
+          });
+          if (outcome.status !== "finished") {
+            return {
+              status: 503,
+              body: {
+                ok: false,
+                error: "turn_failed",
+                turnStatus: outcome.status,
+                message: outcome.errorMessage,
+              },
+            };
+          }
           return {
-            status: 503,
+            status: 200,
             body: {
-              ok: false,
-              error: "turn_failed",
-              turnStatus: outcome.status,
-              message: outcome.errorMessage,
+              ok: true,
+              v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+              outcome: "send",
             },
           };
+        } catch (error) {
+          await writeDiag({
+            sessionId: "",
+            turnStatus: "error",
+            message: error instanceof Error ? error.message : String(error),
+            abortReason: "execute_throw",
+            error,
+          });
+          throw error;
         }
-        return {
-          status: 200,
-          body: {
-            ok: true,
-            v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-            outcome: "send",
-          },
-        };
       })();
       const reply = await admitted.execution;
       return finish(Response.json(reply.body, { status: reply.status }));

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

@@ -0,0 +1,252 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { HOSTED_EXECUTION_DIAG_FILENAME } from "./hosted-delivery-protocol.js";
+
+export const HOSTED_EXECUTION_DIAG_VERSION = 1;
+/** Cap so a runaway message cannot fill the guest disk or the host log. */
+export const HOSTED_EXECUTION_DIAG_MAX_BYTES = 4096;
+
+/**
+ * Correlate the on-disk record with the execution that produced it. One pod
+ * serves many deliveries of a continuation session, and the file lives at a
+ * single fixed path, so without this the host can read a *previous*
+ * delivery's terminal record whenever July never reaches its own write —
+ * the 9-minute host POST timeout, a 409 on an expired admission token, or a
+ * replayed token that short-circuits on the memoized reply.
+ *
+ * Derived from the admission token (which both sides already hold) rather
+ * than carried on the wire. The digest is one-way, so the token itself never
+ * reaches the guest disk or the host logs.
+ */
+export function hostedExecutionDiagId(admissionToken: string): string {
+  return createHash("sha256").update(admissionToken).digest("hex").slice(0, 16);
+}
+
+export type HostedExecutionDiagAbortReason =
+  | "signal_abort"
+  | "runner_cancelled"
+  | "runner_error"
+  | "execute_throw";
+
+/**
+ * Bounded guest-side record of one hosted-execution attempt. No prompt,
+ * tool content, or API key — the host copies known keys onto the Temporal
+ * activity span for Datadog.
+ */
+export type HostedExecutionDiag = {
+  v: typeof HOSTED_EXECUTION_DIAG_VERSION;
+  /** {@link hostedExecutionDiagId} of the execution that wrote this record. */
+  executionId: string;
+  writtenAt: string;
+  sessionPublicId: string;
+  sessionId: string;
+  /** Terminal {@link TurnOutcome} status, or `running` before the turn ends. */
+  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;
+};
+
+/** Written before the turn starts so a stalled execution still has a record. */
+export const HOSTED_EXECUTION_DIAG_RUNNING_STATUS = "running";
+
+const DIAG_KEYS = new Set([
+  "v",
+  "executionId",
+  "writtenAt",
+  "sessionPublicId",
+  "sessionId",
+  "turnStatus",
+  "durationMs",
+  "message",
+  "stack",
+  "signalAborted",
+  "requestId",
+  "abortReason",
+]);
+
+const ABORT_REASONS = new Set<HostedExecutionDiagAbortReason>([
+  "signal_abort",
+  "runner_cancelled",
+  "runner_error",
+  "execute_throw",
+]);
+
+function boundedOptionalString(
+  value: unknown,
+  max: number
+): string | undefined {
+  return typeof value === "string" && value.length > 0
+    ? value.length > max
+      ? `${value.slice(0, max)}…`
+      : value
+    : 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);
+}
+
+export function abortReasonFromTurnStatus(
+  status: string,
+  message: string | undefined
+): HostedExecutionDiagAbortReason | undefined {
+  if (status === "finished") {
+    return undefined;
+  }
+  if (status === "cancelled") {
+    return message !== undefined && /abort/i.test(message)
+      ? "signal_abort"
+      : "runner_cancelled";
+  }
+  return "runner_error";
+}
+
+export function parseHostedExecutionDiag(
+  raw: string
+): HostedExecutionDiag | undefined {
+  if (raw.length === 0 || raw.length > HOSTED_EXECUTION_DIAG_MAX_BYTES) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return undefined;
+  }
+  const body = parsed as Record<string, unknown>;
+  if (Object.keys(body).some((key) => !DIAG_KEYS.has(key))) {
+    return undefined;
+  }
+  if (
+    body.v !== HOSTED_EXECUTION_DIAG_VERSION ||
+    typeof body.executionId !== "string" ||
+    body.executionId.length === 0 ||
+    body.executionId.length > 64 ||
+    typeof body.writtenAt !== "string" ||
+    body.writtenAt.length === 0 ||
+    body.writtenAt.length > 64 ||
+    typeof body.sessionPublicId !== "string" ||
+    body.sessionPublicId.length === 0 ||
+    body.sessionPublicId.length > 128 ||
+    typeof body.sessionId !== "string" ||
+    body.sessionId.length > 128 ||
+    typeof body.turnStatus !== "string" ||
+    body.turnStatus.length === 0 ||
+    body.turnStatus.length > 64 ||
+    typeof body.durationMs !== "number" ||
+    !Number.isFinite(body.durationMs) ||
+    body.durationMs < 0
+  ) {
+    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
+      ? undefined
+      : typeof body.abortReason === "string" &&
+          ABORT_REASONS.has(body.abortReason as HostedExecutionDiagAbortReason)
+        ? (body.abortReason as HostedExecutionDiagAbortReason)
+        : undefined;
+  if (body.abortReason !== undefined && abortReason === undefined) {
+    return undefined;
+  }
+  if (
+    body.signalAborted !== undefined &&
+    typeof body.signalAborted !== "boolean"
+  ) {
+    return undefined;
+  }
+  return {
+    v: HOSTED_EXECUTION_DIAG_VERSION,
+    executionId: body.executionId,
+    writtenAt: body.writtenAt,
+    sessionPublicId: body.sessionPublicId,
+    sessionId: body.sessionId,
+    turnStatus: body.turnStatus,
+    durationMs: body.durationMs,
+    ...(message === undefined ? {} : { message }),
+    ...(stack === undefined ? {} : { stack }),
+    ...(body.signalAborted === true ? { signalAborted: true } : {}),
+    ...(requestId === undefined ? {} : { requestId }),
+    ...(abortReason === undefined ? {} : { abortReason }),
+  };
+}
+
+/**
+ * Overwrite the per-execution diag file. Soft-fail: a write error must not
+ * change the hosted-execution HTTP reply.
+ */
+export async function writeHostedExecutionDiag(
+  stateRoot: string,
+  diag: HostedExecutionDiag
+): Promise<void> {
+  const path = hostedExecutionDiagPath(stateRoot);
+  const tmp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    await mkdir(stateRoot, { recursive: true });
+    const serialized = JSON.stringify(diag);
+    const body =
+      serialized.length > HOSTED_EXECUTION_DIAG_MAX_BYTES
+        ? JSON.stringify({
+            ...diag,
+            stack: undefined,
+            message: boundedOptionalString(diag.message, 256),
+          })
+        : serialized;
+    await writeFile(tmp, body, "utf8");
+    await rename(tmp, path);
+  } catch {
+    await unlink(tmp).catch(() => undefined);
+  }
+}

package/src/internal/http-channel.ts

@@ -25,6 +25,8 @@ import type { ServerRoute } from "./router.js";
 import {
   ApprovalInterruptedError,
   ApprovalNotFoundError,
+  AuthInterruptedError,
+  AuthNotFoundError,
   HTTP_CHANNEL_ID,
   SessionAuthError,
   type SessionEngine,
@@ -93,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
@@ -103,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 }),
       });
@@ -454,6 +464,101 @@ export function buildHttpChannelRoutes(args: {
     },
   };
 
+  const listAuths: ServerRoute = {
+    method: "GET",
+    pattern: `${base}/v1/session/:sessionId/auths`,
+    auth,
+    handler: async (_request, ctx) => {
+      const sessionId = ctx.params.sessionId ?? "";
+      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 pending = await engine.listPendingAuths(sessionId);
+      return jsonResponse({ ok: true, sessionId, pending });
+    },
+  };
+
+  const resolveAuth: ServerRoute = {
+    method: "POST",
+    pattern: `${base}/v1/session/:sessionId/auths/:callId`,
+    auth,
+    handler: async (request, ctx) => {
+      const sessionId = ctx.params.sessionId ?? "";
+      const callId = ctx.params.callId ?? "";
+      const record = await engine.getOrRestoreSession(sessionId);
+      if (record === undefined) {
+        return errorResponse(
+          404,
+          "session_not_found",
+          `Unknown session ${sessionId}.`
+        );
+      }
+      const bridgeSlackAuth =
+        relaxSessionApprovalAuth === true &&
+        record.auth?.authenticator === "slack" &&
+        (relaxSessionReadAuthBeyondLoopback === true ||
+          (typeof ctx.requestIp === "string" &&
+            isLoopbackAddress(ctx.requestIp)));
+      const ownership = requireSessionOwner(record, ctx.auth, {
+        relax: bridgeSlackAuth,
+        beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+        requestIp: ctx.requestIp,
+      });
+      if (ownership !== undefined) {
+        return ownership;
+      }
+      const body = await readJsonObject(request);
+      const decision = body?.decision;
+      if (decision !== "approve" && decision !== "deny") {
+        return errorResponse(
+          400,
+          "invalid_request",
+          'Expected a JSON body with `decision`: "approve" | "deny".'
+        );
+      }
+      try {
+        const pending = await engine.resolveAuth(
+          sessionId,
+          callId,
+          decision,
+          ctx.auth,
+          bridgeSlackAuth ? { asSessionOwner: true } : undefined
+        );
+        return jsonResponse({
+          ok: true,
+          sessionId,
+          callId,
+          decision,
+          connection: pending.connection,
+        });
+      } catch (error) {
+        if (error instanceof AuthNotFoundError) {
+          return errorResponse(404, "auth_not_found", error.message);
+        }
+        if (error instanceof AuthInterruptedError) {
+          return errorResponse(409, "auth_interrupted", error.message);
+        }
+        if (error instanceof SessionAuthError) {
+          return errorResponse(403, "forbidden", error.message);
+        }
+        throw error;
+      }
+    },
+  };
+
   return [
     createSession,
     followUp,
@@ -463,6 +568,8 @@ export function buildHttpChannelRoutes(args: {
     cost,
     listApprovals,
     resolveApproval,
+    listAuths,
+    resolveAuth,
   ];
 }