@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/session-links.ts

@@ -1,84 +0,0 @@
-import { parseGitHubPrRef } from "../channels/github/replay.js";
-import { slackThreadPermalink } from "../channels/slack/links.js";
-import { extractGithubPrRef } from "../channels/slack/pr-ref.js";
-import type { AgentCloudOptions, AuthContext } from "../types.js";
-
-export type SessionExternalLinks = {
-  slack: string | undefined;
-  github: string | undefined;
-};
-
-type SessionLinkSource = {
-  auth: AuthContext | null;
-  title?: string;
-  continuationKey: string | null;
-  cloudOverride?: AgentCloudOptions;
-};
-
-const SLACK_TITLE = /^slack:([CGD][A-Z0-9]+):(\d+\.\d+)$/i;
-const SLACK_CONTINUATION = /^([CGD][A-Z0-9]+):(\d+\.\d+)$/i;
-
-export function sessionExternalLinks(record: SessionLinkSource): SessionExternalLinks {
-  return {
-    slack: slackUrl(record),
-    github: githubUrl(record),
-  };
-}
-
-function slackUrl(record: SessionLinkSource): string | undefined {
-  const auth = record.auth;
-  if (auth !== null && auth.authenticator === "slack") {
-    const fromAuth = slackThreadPermalink({
-      channelId: auth.attributes?.channel_id ?? "",
-      threadTs: auth.attributes?.thread_ts ?? "",
-      teamId: auth.attributes?.team_id,
-    });
-    if (fromAuth !== null) {
-      return fromAuth;
-    }
-  }
-  const fromTitle = (record.title ?? "").trim().match(SLACK_TITLE);
-  if (fromTitle !== null) {
-    return (
-      slackThreadPermalink({
-        channelId: fromTitle[1] as string,
-        threadTs: fromTitle[2] as string,
-      }) ?? undefined
-    );
-  }
-  const fromKey = (record.continuationKey ?? "").trim().match(SLACK_CONTINUATION);
-  if (fromKey === null) {
-    return undefined;
-  }
-  return (
-    slackThreadPermalink({
-      channelId: fromKey[1] as string,
-      threadTs: fromKey[2] as string,
-    }) ?? undefined
-  );
-}
-
-function githubUrl(record: SessionLinkSource): string | undefined {
-  const fromTitle = extractGithubPrRef(record.title ?? "");
-  if (fromTitle !== undefined) {
-    return fromTitle.url;
-  }
-  const key = record.continuationKey ?? "";
-  if (key.startsWith("github-pr:")) {
-    return parseGitHubPrRef(key.slice("github-pr:".length))?.url;
-  }
-  const repos = record.cloudOverride?.repos;
-  if (repos === undefined) {
-    return undefined;
-  }
-  for (const repo of repos) {
-    if (repo.prUrl === undefined) {
-      continue;
-    }
-    const parsed = parseGitHubPrRef(repo.prUrl);
-    if (parsed !== undefined) {
-      return parsed.url;
-    }
-  }
-  return undefined;
-}

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

@@ -1,535 +0,0 @@
-/**
- * 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.
- *
- * Same flush moments as `hosted-execution.json` and the start.log tee —
- * see `hosted-execution-flush.ts`. Keys:
- * {@link agentSdkStorageKeys.sessionRun}.
- */
-
-import type { FileSink } from "../files.js";
-import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
-import { agentSdkStorageKeys } from "../storage-protocol.js";
-import type { AgentProject } from "../types.js";
-import { resolveApiKeySync } from "./cursor/credentials.js";
-import { describeError } from "./describe-error.js";
-import type { HostedExecutionDiagAbortReason } from "./hosted-execution-diag.js";
-import { isRecord } from "./is-record.js";
-import type { LogRingEntry } from "./log-ring.js";
-import { resolveAgentV2Hosting } from "./v2-hosting.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 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 = agentSdkStorageKeys.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 = agentSdkStorageKeys.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 {
-  const hosting = resolveAgentV2Hosting({
-    architecture: input.project.agent.architecture,
-    env: input.env as NodeJS.ProcessEnv | undefined,
-  });
-  if (hosting.kind !== "cursor-managed") {
-    return undefined;
-  }
-  return createSessionRunLogStore({
-    sink: cursorHostedFiles({
-      resolveStoreSourceId: () => hosting.resolveStoreIds().frameworkStoreSourceId,
-      resolveApiKey: () => resolveApiKeySync()?.apiKey,
-    }),
-    agentName: input.project.name,
-    logger: input.logger,
-    ...(input.snapshotLogs === undefined ? {} : { snapshotLogs: input.snapshotLogs }),
-  });
-}