@cursor/july 0.1.97 → 0.1.100

package/src/internal/session-run-log.ts

@@ -0,0 +1,579 @@
+/**
+ * Durable hosted-execution run log on the framework file store. **v2 only.**
+ *
+ * One JSON document per factory session (`ses_…`), with per-execution
+ * entries inside. The later customer UI is session-scoped ("why did this
+ * session fail?") so a single GET is the read path; continuations are FIFO
+ * so last-write-wins merge is safe. Guest-local `hosted-execution.json` and
+ * factorydb `last_error` are lossy: the on-disk diag dies with the pod, and
+ * the session row only keeps the first 1024 characters of a generic HTTP
+ * 500.
+ *
+ * Process death: persist `running` at turn start so SIGKILL / OOM still
+ * leaves a durable leftover. `uncaughtException` / SIGTERM flush the same
+ * session key with `processDeath: true` and the real throw. Soft-fail on
+ * persist so a store outage never changes the hosted-execution HTTP reply.
+ *
+ * Keys: {@link storageKeys.sessionRun}.
+ */
+
+import type { FileSink } from "../files.js";
+import {
+  cursorFrameworkStoreSourceId,
+  cursorHostedFiles,
+} from "../files-backends/cursor-hosted.js";
+import { storageKeys } from "../storage-protocol.js";
+import type { AgentProject } from "../types.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+import type { HostedExecutionDiagAbortReason } from "./hosted-execution-diag.js";
+import type { LogRingEntry } from "./log-ring.js";
+
+export const SESSION_RUN_LOG_VERSION = 1;
+/** Last N log-ring lines kept on each execution. */
+export const SESSION_RUN_LOG_MAX_ENTRIES = 200;
+/** Per-line cap so a runaway logger cannot blow the document. */
+export const SESSION_RUN_LOG_MAX_LINE_CHARS = 4096;
+/** Continuations are FIFO; keep a bounded history for the session UI. */
+export const SESSION_RUN_LOG_MAX_EXECUTIONS = 20;
+const MAX_ERROR_MESSAGE_CHARS = 4096;
+const MAX_ERROR_STACK_CHARS = 16_384;
+const MAX_DOCUMENT_CHARS = 512 * 1024;
+/** Crash-handler flush must not block `process.exit`. */
+export const SESSION_RUN_FATAL_FLUSH_TIMEOUT_MS = 2_000;
+
+export type SessionRunAbortReason =
+  | HostedExecutionDiagAbortReason
+  | "process_exit"
+  | "uncaught_exception"
+  | "unhandled_rejection";
+
+export type SessionRunLogError = {
+  name: string;
+  message: string;
+  stack?: string;
+};
+
+export type SessionRunExecution = {
+  executionId: string;
+  writtenAt: string;
+  sessionId: string;
+  turnStatus: string;
+  durationMs: number;
+  abortReason?: SessionRunAbortReason;
+  message?: string;
+  error?: SessionRunLogError;
+  /** True when this entry was flushed from a process-death handler. */
+  processDeath?: boolean;
+  logs: LogRingEntry[];
+};
+
+/**
+ * Latest non-success execution, including leftover `running` after the
+ * process died without a terminal persist (SIGKILL / OOM). Undefined when
+ * the latest execution `turnStatus` is `finished`.
+ */
+export type SessionRunLastFailure = {
+  executionId: string;
+  writtenAt: string;
+  turnStatus: string;
+  abortReason?: SessionRunAbortReason;
+  message?: string;
+  error?: SessionRunLogError;
+  processDeath?: boolean;
+};
+
+/** One document per factory session. The customer UI reads this object. */
+export type SessionRunLogDocument = {
+  v: typeof SESSION_RUN_LOG_VERSION;
+  sessionPublicId: string;
+  updatedAt: string;
+  lastFailure?: SessionRunLastFailure;
+  executions: SessionRunExecution[];
+};
+
+/** Persist input: one execution upserted into the session document. */
+export type SessionRunExecutionWrite = SessionRunExecution & {
+  sessionPublicId: string;
+};
+
+export interface SessionRunLogStore {
+  persist(write: SessionRunExecutionWrite): Promise<void>;
+  read(sessionPublicId: string): Promise<SessionRunLogDocument | undefined>;
+  /**
+   * Upgrade the in-flight `running` claim to a terminal process-death
+   * entry. No-op when no execution is active (already terminal, or never
+   * started). Soft-fail.
+   */
+  flushProcessDeath(
+    reason: Extract<
+      SessionRunAbortReason,
+      "process_exit" | "uncaught_exception" | "unhandled_rejection"
+    >,
+    error?: unknown
+  ): Promise<void>;
+}
+
+type ActiveExecution = {
+  sessionPublicId: string;
+  executionId: string;
+  sessionId: string;
+  startedAt: number;
+};
+
+let fatalFlush: ((error: unknown) => Promise<void>) | undefined;
+
+/**
+ * Install the crash-handler flush used by `bin/agent-serve` on
+ * `uncaughtException`. One process, one active hosted serve.
+ */
+export function registerSessionRunFatalFlush(
+  flush: (error: unknown) => Promise<void>
+): void {
+  fatalFlush = flush;
+}
+
+export function unregisterSessionRunFatalFlush(): void {
+  fatalFlush = undefined;
+}
+
+/**
+ * Await the registered crash flush, bounded so a hung store cannot prevent
+ * `process.exit`. Soft-fail.
+ */
+export async function flushSessionRunFatal(error: unknown): Promise<void> {
+  if (fatalFlush === undefined) {
+    return;
+  }
+  await Promise.race([
+    fatalFlush(error).catch(() => undefined),
+    new Promise<void>((resolve) => {
+      setTimeout(resolve, SESSION_RUN_FATAL_FLUSH_TIMEOUT_MS);
+    }),
+  ]);
+}
+
+function boundedText(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+function boundedOptionalText(
+  value: string | undefined,
+  max: number
+): string | undefined {
+  if (value === undefined || value.length === 0) {
+    return undefined;
+  }
+  return boundedText(value, max);
+}
+
+export function serializeSessionRunError(error: unknown): SessionRunLogError {
+  if (error instanceof Error) {
+    const stack = boundedOptionalText(error.stack, MAX_ERROR_STACK_CHARS);
+    return {
+      name: boundedText(error.name.length > 0 ? error.name : "Error", 128),
+      message: boundedText(error.message, MAX_ERROR_MESSAGE_CHARS),
+      ...(stack === undefined ? {} : { stack }),
+    };
+  }
+  return {
+    name: "Error",
+    message: boundedText(String(error), MAX_ERROR_MESSAGE_CHARS),
+  };
+}
+
+export function snapshotSessionRunLogs(
+  entries: readonly LogRingEntry[]
+): LogRingEntry[] {
+  const tail = entries.slice(-SESSION_RUN_LOG_MAX_ENTRIES);
+  return tail.map((entry) => ({
+    index: entry.index,
+    at: entry.at,
+    line: boundedText(entry.line, SESSION_RUN_LOG_MAX_LINE_CHARS),
+  }));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeSinkBody(body: Uint8Array | { body: Uint8Array }): Uint8Array {
+  return body instanceof Uint8Array ? body : body.body;
+}
+
+function parseError(value: unknown): SessionRunLogError | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const name = typeof value.name === "string" ? value.name : "";
+  const message = typeof value.message === "string" ? value.message : "";
+  const stack = typeof value.stack === "string" ? value.stack : undefined;
+  return {
+    name,
+    message,
+    ...(stack === undefined ? {} : { stack }),
+  };
+}
+
+function parseLogs(value: unknown): LogRingEntry[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const logs: LogRingEntry[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    if (
+      typeof entry.index !== "number" ||
+      typeof entry.at !== "string" ||
+      typeof entry.line !== "string"
+    ) {
+      continue;
+    }
+    logs.push({ index: entry.index, at: entry.at, line: entry.line });
+  }
+  return logs;
+}
+
+function parseExecution(value: unknown): SessionRunExecution | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const executionId =
+    typeof value.executionId === "string" ? value.executionId : undefined;
+  const writtenAt =
+    typeof value.writtenAt === "string" ? value.writtenAt : undefined;
+  const sessionId =
+    typeof value.sessionId === "string" ? value.sessionId : undefined;
+  const turnStatus =
+    typeof value.turnStatus === "string" ? value.turnStatus : undefined;
+  const durationMs =
+    typeof value.durationMs === "number" && Number.isFinite(value.durationMs)
+      ? value.durationMs
+      : undefined;
+  if (
+    executionId === undefined ||
+    executionId.length === 0 ||
+    writtenAt === undefined ||
+    sessionId === undefined ||
+    turnStatus === undefined ||
+    turnStatus.length === 0 ||
+    durationMs === undefined ||
+    durationMs < 0
+  ) {
+    return undefined;
+  }
+  const abortReason =
+    typeof value.abortReason === "string" ? value.abortReason : undefined;
+  const message = typeof value.message === "string" ? value.message : undefined;
+  const error = parseError(value.error);
+  return {
+    executionId,
+    writtenAt,
+    sessionId,
+    turnStatus,
+    durationMs,
+    ...(abortReason === undefined
+      ? {}
+      : { abortReason: abortReason as SessionRunAbortReason }),
+    ...(message === undefined ? {} : { message }),
+    ...(error === undefined ? {} : { error }),
+    ...(value.processDeath === true ? { processDeath: true } : {}),
+    logs: parseLogs(value.logs),
+  };
+}
+
+export function lastFailureFromExecutions(
+  executions: readonly SessionRunExecution[]
+): SessionRunLastFailure | undefined {
+  const latest = executions.at(-1);
+  if (latest === undefined || latest.turnStatus === "finished") {
+    return undefined;
+  }
+  return {
+    executionId: latest.executionId,
+    writtenAt: latest.writtenAt,
+    turnStatus: latest.turnStatus,
+    ...(latest.abortReason === undefined
+      ? {}
+      : { abortReason: latest.abortReason }),
+    ...(latest.message === undefined ? {} : { message: latest.message }),
+    ...(latest.error === undefined ? {} : { error: latest.error }),
+    ...(latest.processDeath === true ? { processDeath: true } : {}),
+  };
+}
+
+function boundExecution(write: SessionRunExecution): SessionRunExecution {
+  const error =
+    write.error === undefined
+      ? undefined
+      : {
+          name: boundedText(write.error.name, 128),
+          message: boundedText(write.error.message, MAX_ERROR_MESSAGE_CHARS),
+          ...(write.error.stack === undefined
+            ? {}
+            : {
+                stack: boundedText(write.error.stack, MAX_ERROR_STACK_CHARS),
+              }),
+        };
+  return {
+    executionId: write.executionId,
+    writtenAt: write.writtenAt,
+    sessionId: write.sessionId,
+    turnStatus: write.turnStatus,
+    durationMs: write.durationMs,
+    ...(write.abortReason === undefined
+      ? {}
+      : { abortReason: write.abortReason }),
+    ...(boundedOptionalText(write.message, MAX_ERROR_MESSAGE_CHARS) ===
+    undefined
+      ? {}
+      : {
+          message: boundedOptionalText(write.message, MAX_ERROR_MESSAGE_CHARS),
+        }),
+    ...(error === undefined ? {} : { error }),
+    ...(write.processDeath === true ? { processDeath: true } : {}),
+    logs: snapshotSessionRunLogs(write.logs),
+  };
+}
+
+function upsertExecution(
+  existing: readonly SessionRunExecution[],
+  next: SessionRunExecution
+): SessionRunExecution[] {
+  const executions = existing.filter(
+    (entry) => entry.executionId !== next.executionId
+  );
+  executions.push(next);
+  executions.sort((a, b) => a.writtenAt.localeCompare(b.writtenAt));
+  return executions.slice(-SESSION_RUN_LOG_MAX_EXECUTIONS);
+}
+
+function shrinkSessionDocument(
+  document: SessionRunLogDocument
+): SessionRunLogDocument {
+  let executions = document.executions;
+  let next: SessionRunLogDocument = {
+    ...document,
+    executions,
+    lastFailure: lastFailureFromExecutions(executions),
+  };
+  let serialized = JSON.stringify(next);
+  while (serialized.length > MAX_DOCUMENT_CHARS) {
+    const oldestWithLogs = executions.findIndex(
+      (entry) => entry.logs.length > 0
+    );
+    if (oldestWithLogs >= 0) {
+      const entry = executions[oldestWithLogs]!;
+      executions = executions.map((item, index) =>
+        index === oldestWithLogs
+          ? {
+              ...entry,
+              logs: entry.logs.slice(Math.ceil(entry.logs.length / 2)),
+            }
+          : item
+      );
+    } else if (executions.length > 1) {
+      executions = executions.slice(1);
+    } else {
+      break;
+    }
+    next = {
+      ...document,
+      executions,
+      lastFailure: lastFailureFromExecutions(executions),
+    };
+    serialized = JSON.stringify(next);
+  }
+  return next;
+}
+
+export function parseSessionRunLogDocument(
+  value: unknown
+): SessionRunLogDocument | undefined {
+  if (!isRecord(value) || value.v !== SESSION_RUN_LOG_VERSION) {
+    return undefined;
+  }
+  const sessionPublicId =
+    typeof value.sessionPublicId === "string"
+      ? value.sessionPublicId
+      : undefined;
+  const updatedAt =
+    typeof value.updatedAt === "string" ? value.updatedAt : undefined;
+  if (
+    sessionPublicId === undefined ||
+    sessionPublicId.length === 0 ||
+    updatedAt === undefined ||
+    !Array.isArray(value.executions)
+  ) {
+    return undefined;
+  }
+  const executions: SessionRunExecution[] = [];
+  for (const entry of value.executions) {
+    const parsed = parseExecution(entry);
+    if (parsed !== undefined) {
+      executions.push(parsed);
+    }
+  }
+  executions.sort((a, b) => a.writtenAt.localeCompare(b.writtenAt));
+  const lastFailure = lastFailureFromExecutions(executions);
+  return {
+    v: SESSION_RUN_LOG_VERSION,
+    sessionPublicId,
+    updatedAt,
+    ...(lastFailure === undefined ? {} : { lastFailure }),
+    executions,
+  };
+}
+
+export function createSessionRunLogStore(input: {
+  sink: FileSink;
+  agentName: string;
+  logger?: (line: string) => void;
+  snapshotLogs?: () => readonly LogRingEntry[];
+}): SessionRunLogStore {
+  const { sink, agentName } = input;
+  const logger = input.logger ?? (() => {});
+  let active: ActiveExecution | undefined;
+
+  const readDocument = async (
+    sessionPublicId: string
+  ): Promise<SessionRunLogDocument | undefined> => {
+    const key = storageKeys.sessionRun(agentName, sessionPublicId);
+    const body = await sink.get(key);
+    if (body === undefined) {
+      return undefined;
+    }
+    try {
+      return parseSessionRunLogDocument(
+        JSON.parse(new TextDecoder().decode(decodeSinkBody(body)))
+      );
+    } catch (error) {
+      logger(
+        `[agent-sdk] session-run log: skip unreadable ${key} (${describeError(error)})`
+      );
+      return undefined;
+    }
+  };
+
+  const persistWrite = async (
+    write: SessionRunExecutionWrite
+  ): Promise<void> => {
+    const fitted = boundExecution(write);
+    let existing: SessionRunLogDocument | undefined;
+    try {
+      existing = await readDocument(write.sessionPublicId);
+    } catch (error) {
+      logger(
+        `[agent-sdk] session-run log: persist failed for ${fitted.executionId} (${describeError(error)})`
+      );
+      return;
+    }
+    const executions = upsertExecution(existing?.executions ?? [], fitted);
+    const document = shrinkSessionDocument({
+      v: SESSION_RUN_LOG_VERSION,
+      sessionPublicId: write.sessionPublicId,
+      updatedAt: fitted.writtenAt,
+      executions,
+    });
+    const key = storageKeys.sessionRun(agentName, document.sessionPublicId);
+    try {
+      await sink.put(key, new TextEncoder().encode(JSON.stringify(document)));
+    } catch (error) {
+      logger(
+        `[agent-sdk] session-run log: persist failed for ${fitted.executionId} (${describeError(error)})`
+      );
+      return;
+    }
+    if (fitted.turnStatus === "running") {
+      active = {
+        sessionPublicId: write.sessionPublicId,
+        executionId: fitted.executionId,
+        sessionId: fitted.sessionId,
+        startedAt: Date.now(),
+      };
+      return;
+    }
+    if (active?.executionId === fitted.executionId) {
+      active = undefined;
+    }
+  };
+
+  return {
+    persist: persistWrite,
+
+    async read(sessionPublicId) {
+      try {
+        return await readDocument(sessionPublicId);
+      } catch (error) {
+        logger(
+          `[agent-sdk] session-run log: read failed for ${sessionPublicId} (${describeError(error)})`
+        );
+        return undefined;
+      }
+    },
+
+    async flushProcessDeath(reason, error) {
+      if (active === undefined) {
+        return;
+      }
+      const current = active;
+      const serialized =
+        error === undefined ? undefined : serializeSessionRunError(error);
+      const message =
+        error instanceof Error
+          ? error.message
+          : error !== undefined
+            ? String(error)
+            : "process died during hosted execution";
+      await persistWrite({
+        sessionPublicId: current.sessionPublicId,
+        executionId: current.executionId,
+        writtenAt: new Date().toISOString(),
+        sessionId: current.sessionId,
+        turnStatus: "error",
+        durationMs: Math.max(0, Date.now() - current.startedAt),
+        abortReason: reason,
+        processDeath: true,
+        message,
+        ...(serialized === undefined ? {} : { error: serialized }),
+        logs: snapshotSessionRunLogs(input.snapshotLogs?.() ?? []),
+      });
+    },
+  };
+}
+
+/**
+ * Same selection as the conversation mirror: architecture-v2 hosted
+ * engines (generation env set). Store ids resolve lazily from env or the
+ * task-bind files under `/run/cursor/secrets`. Self-hosted and v1 stay on
+ * local disk / today's behavior.
+ */
+export function selectSessionRunLogStore(input: {
+  project: AgentProject;
+  logger?: (line: string) => void;
+  env?: Record<string, string | undefined>;
+  snapshotLogs?: () => readonly LogRingEntry[];
+}): SessionRunLogStore | undefined {
+  if (input.project.agent.architecture !== "v2") {
+    return undefined;
+  }
+  const env = input.env ?? process.env;
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+    return undefined;
+  }
+  const envSnapshot = env as NodeJS.ProcessEnv;
+  return createSessionRunLogStore({
+    sink: cursorHostedFiles({
+      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveApiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+    agentName: input.project.name,
+    logger: input.logger,
+    ...(input.snapshotLogs === undefined
+      ? {}
+      : { snapshotLogs: input.snapshotLogs }),
+  });
+}

package/src/internal/tool-policy.ts

@@ -16,6 +16,7 @@ import type {
   ToolEffectDeclaration,
   ToolExecuteResult,
 } from "../types.js";
+import { timeArgViolation } from "./as-of.js";
 
 /** What the host does with one tool call. */
 export type ToolDecision =
@@ -24,12 +25,17 @@ export type ToolDecision =
   /** Do not run it; return this to the model instead. */
   | { kind: "answer"; result: ToolExecuteResult }
   /**
-   * Do not run it; fail the call with this message. Only ever produced in a
-   * dry run, for an MCP tool nothing classifies: stubbing it would let the
-   * run reach a confident conclusion from no data, and running it could leak
-   * a real write — refusing is the one failure that is loud.
+   * Do not run it; fail the call with this message. Only produced in a dry
+   * run, for an MCP tool nothing classifies: stubbing it would let the run
+   * reach a confident conclusion from no data, and running it could leak a
+   * real write — refusing is the one failure that is loud.
    */
-  | { kind: "refuse"; message: string };
+  | { kind: "refuse"; message: string }
+  /**
+   * Do not run it; the `asOf` session was asked to read without absolute
+   * bounds, which would read the present.
+   */
+  | { kind: "unbounded"; message: string };
 
 /** What a policy decision needs to know about the call. */
 export interface ToolCallFacts {
@@ -48,12 +54,16 @@ export interface ToolCallFacts {
   /** What a stubbed write should answer with, if the tool supplied one. */
   dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
   /**
-   * Validated input, as the tool body would receive it. Only read by a
-   * per-call `effect` predicate and by a `dryRunResult` function, so a caller
-   * with neither — a bridged MCP tool, which carries no declaration at all —
-   * can omit it.
+   * Validated input, as the tool body would receive it. Read by a per-call
+   * `effect` predicate, a `dryRunResult` function, and the {@link timeArgs}
+   * bound check, so a caller with none of those — a bridged MCP tool, which
+   * carries no declaration at all — can omit it.
    */
   input?: unknown;
+  /** The session's frozen instant, when it has one. */
+  asOf?: string;
+  /** The tool's declared time-bound argument names, if it made them. */
+  timeArgs?: readonly string[];
 }
 
 /**
@@ -147,6 +157,18 @@ function unclassifiedRefusal(toolName: string): string {
 
 /** Decide what to do with one tool call. Pure; no I/O, no session state. */
 export function decideToolCall(facts: ToolCallFacts): ToolDecision {
+  // Before the dry-run split: a frozen session bounds its reads whether or
+  // not its writes are stubbed.
+  if (
+    facts.asOf !== undefined &&
+    facts.timeArgs !== undefined &&
+    facts.timeArgs.length > 0
+  ) {
+    const violation = timeArgViolation(facts.input, facts.timeArgs, facts.asOf);
+    if (violation !== undefined) {
+      return { kind: "unbounded", message: violation };
+    }
+  }
   if (!facts.dryRun) {
     return { kind: "run" };
   }