@cursor/bdk 0.2.3 → 0.2.5

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

@@ -1,291 +0,0 @@
-/**
- * Guest-local TAS diag (`hosted-execution.json`). Flushed with the durable
- * session-run document and the `start.log` tee by
- * `hosted-execution-flush.ts`.
- */
-
-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,
-  type HostedFailureClassification,
-  parseHostedFailureClassification,
-} 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. `errorCode` and `message` are logged ungated;
- * `stack` stays behind the internal-diag gate.
- */
-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;
-  failureCode?: string;
-  /** Runner/SDK code for the unfinished turn. Distinct from {@link failureCode}. */
-  errorCode?: string;
-  classification?: HostedFailureClassification;
-};
-
-/** 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",
-  "failureCode",
-  "errorCode",
-  "classification",
-]);
-
-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 on-disk diag `stack` (and non-hosted 500 bodies).
- * Prefers `Error.stack` (message line + `at` frames). Hosted HTTP `message`
- * uses {@link hostedErrorMessageOnly} so customer Datadog stays frame-free.
- */
-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;
-}
-
-/**
- * Guest throw text without `at` frames. Hosted 500 `message` is ungated on
- * TAS (`hostedGuestMessage` / `last_error`); stack frames stay on `stack`.
- */
-export function hostedErrorMessageOnly(error: unknown): string {
-  const text =
-    error instanceof Error && error.message.trim().length > 0
-      ? error.message.trim()
-      : String(error).trim();
-  if (text.length === 0) {
-    return "Internal server error.";
-  }
-  const firstFrame = text.search(/\n\s+at\s/);
-  const message = firstFrame === -1 ? text : text.slice(0, firstFrame).trimEnd();
-  if (message.length === 0) {
-    return "Internal server error.";
-  }
-  return message.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
-    ? `${message.slice(0, HOSTED_ERROR_SNIPPET_MAX_CHARS)}…`
-    : message;
-}
-
-export function hostedExecutionDiagPath(stateRoot: string): string {
-  return join(stateRoot, HOSTED_EXECUTION_DIAG_FILENAME);
-}
-
-export function abortReasonFromTurnStatus(
-  status: string,
-  cancellationReason: "signal" | "runner" | undefined,
-): HostedExecutionDiagAbortReason | undefined {
-  if (status === "finished") {
-    return undefined;
-  }
-  if (status === "cancelled") {
-    return cancellationReason === "signal" ? "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 failureCode = boundedOptionalString(body.failureCode, 64);
-  const errorCode = boundedOptionalString(body.errorCode, 64);
-  const classification =
-    body.classification === undefined
-      ? undefined
-      : parseHostedFailureClassification(body.classification);
-  if (body.classification !== undefined && classification === undefined) {
-    return undefined;
-  }
-  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 }),
-    ...(failureCode === undefined ? {} : { failureCode }),
-    ...(errorCode === undefined ? {} : { errorCode }),
-    ...(classification === undefined ? {} : { classification }),
-  };
-}
-
-/**
- * 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/hosted-execution-flush.ts

@@ -1,136 +0,0 @@
-/**
- * One hosted-execution flush. Two artifacts, same moments:
- *
- * - Guest-local `hosted-execution.json` — TAS failed-execute diag.
- * - Durable `session-runs/{ses_…}` plus the `start.log` tee — dashboard.
- *
- * Claim (`running`) → terminal → process-death. Process-death upgrades the
- * durable document and re-snapshots the tee; the local json stays `running`
- * so TAS does not treat a previous delivery's terminal record as this one.
- */
-
-import type { HostedFailureClassification } from "./hosted-delivery-protocol.js";
-import {
-  type HostedExecutionDiagAbortReason,
-  hostedErrorStackSnippet,
-  writeHostedExecutionDiag,
-} from "./hosted-execution-diag.js";
-import type { LogRingEntry } from "./log-ring.js";
-import {
-  type SessionRunAbortReason,
-  type SessionRunExecutionWrite,
-  serializeSessionRunError,
-  snapshotSessionRunLogs,
-} from "./session-run-log.js";
-
-const MAX_ERROR_MESSAGE_LENGTH = 1024;
-
-function boundedMessage(text: string): string {
-  return text.length > MAX_ERROR_MESSAGE_LENGTH
-    ? `${text.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
-    : text;
-}
-
-export type HostedExecutionFlushSinks = {
-  /** Serve `--state-root`. Omit to skip the guest-local TAS diag. */
-  stateRoot?: string;
-  persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
-  flushStartLog?(startLogId: string): Promise<void>;
-  snapshotLogs?(): LogRingEntry[];
-};
-
-export type HostedExecutionFlushFields = {
-  executionId: string;
-  sessionPublicId: string;
-  sessionId: string;
-  turnStatus: string;
-  durationMs: number;
-  message?: string;
-  abortReason?: HostedExecutionDiagAbortReason;
-  failureCode?: string;
-  errorCode?: string;
-  classification?: HostedFailureClassification;
-  error?: unknown;
-};
-
-/**
- * Write the local TAS diag and the durable session-run + tee together.
- * Soft-fail per sink so a store outage does not change hosted HTTP.
- */
-export async function flushHostedExecutionRecord(
-  sinks: HostedExecutionFlushSinks,
-  fields: HostedExecutionFlushFields,
-): Promise<void> {
-  const writtenAt = new Date().toISOString();
-  const message = fields.message === undefined ? undefined : boundedMessage(fields.message);
-  const stack = fields.error === undefined ? undefined : hostedErrorStackSnippet(fields.error);
-  if (sinks.stateRoot !== undefined) {
-    await writeHostedExecutionDiag(sinks.stateRoot, {
-      v: 1,
-      executionId: fields.executionId,
-      writtenAt,
-      sessionPublicId: fields.sessionPublicId,
-      sessionId: fields.sessionId,
-      turnStatus: fields.turnStatus,
-      durationMs: fields.durationMs,
-      ...(message === undefined ? {} : { message }),
-      ...(stack === undefined || stack.length === 0 ? {} : { stack }),
-      signalAborted: fields.abortReason === "signal_abort" ? true : undefined,
-      ...(fields.abortReason === undefined ? {} : { abortReason: fields.abortReason }),
-      failureCode: fields.failureCode,
-      ...(fields.errorCode === undefined ? {} : { errorCode: fields.errorCode }),
-      classification: fields.classification,
-    });
-  }
-  if (sinks.persistSessionRun !== undefined) {
-    const error = fields.error === undefined ? undefined : serializeSessionRunError(fields.error);
-    try {
-      await sinks.persistSessionRun({
-        executionId: fields.executionId,
-        writtenAt,
-        sessionPublicId: fields.sessionPublicId,
-        sessionId: fields.sessionId,
-        turnStatus: fields.turnStatus,
-        durationMs: fields.durationMs,
-        ...(fields.abortReason === undefined ? {} : { abortReason: fields.abortReason }),
-        ...(message === undefined ? {} : { message }),
-        ...(error === undefined ? {} : { error }),
-        logs: snapshotSessionRunLogs(sinks.snapshotLogs?.() ?? []),
-      });
-    } catch {
-      // Soft-fail: a store outage must not change the HTTP reply.
-    }
-  }
-  if (sinks.flushStartLog !== undefined) {
-    try {
-      await sinks.flushStartLog(fields.sessionPublicId);
-    } catch {
-      // Soft-fail: same posture as the session-run persist.
-    }
-  }
-}
-
-/**
- * Durable-only crash flush. Leaves `hosted-execution.json` at `running`.
- */
-export async function flushHostedExecutionProcessDeath(args: {
-  flushProcessDeath: (
-    reason: Extract<
-      SessionRunAbortReason,
-      "process_exit" | "uncaught_exception" | "unhandled_rejection"
-    >,
-    error?: unknown,
-  ) => Promise<void>;
-  flushStartLog?: (startLogId: string) => Promise<void>;
-  startLogId?: string;
-  reason: Extract<
-    SessionRunAbortReason,
-    "process_exit" | "uncaught_exception" | "unhandled_rejection"
-  >;
-  error?: unknown;
-}): Promise<void> {
-  await args.flushProcessDeath(args.reason, args.error);
-  if (args.startLogId !== undefined && args.flushStartLog !== undefined) {
-    await args.flushStartLog(args.startLogId);
-  }
-}