@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/http-channel.ts

@@ -1,669 +0,0 @@
-/**
- * The built-in HTTP session channel: the default API that `curl`, SDK
- * clients, and frontends talk to. Mounted at `/v1/session*` even when no
- * channel override is present.
- *
- * Continuation semantics: `POST /v1/session` returns a `continuationToken`;
- * each accepted follow-up rotates it and returns the replacement, and a
- * stale token is rejected with 409. Follow-ups address any chat session by
- * id (including custom channels such as `drive`) when the token matches its
- * active HTTP follow-up key; task sessions stay fire-and-forget.
- */
-
-import type {
-  AgentCloudOptions,
-  AuthContext,
-  AuthPolicy,
-  HttpChannelDefinition,
-  SessionRecord,
-} from "../types.js";
-import { samePrincipal } from "./auth.js";
-import { formatContinuationToken, parseContinuationToken } from "./ids.js";
-import { isRecord } from "./is-record.js";
-import { isLoopbackAddress } from "./net.js";
-import type { ServerRoute } from "./router.js";
-import {
-  ApprovalInterruptedError,
-  ApprovalNotFoundError,
-  AuthInterruptedError,
-  AuthNotFoundError,
-  HTTP_CHANNEL_ID,
-  SessionAuthError,
-  type SessionEngine,
-} from "./session-engine.js";
-import { eventsUrlForSession, playgroundUrlForSession } from "./session-urls.js";
-
-const SESSION_ID_HEADER = "x-agent-serve-session-id";
-
-export function buildHttpChannelRoutes(args: {
-  engine: SessionEngine;
-  config: HttpChannelDefinition;
-  auth: AuthPolicy[];
-  /** Path prefix ("" single-agent, "/<slug>" multi-agent). */
-  basePath?: string;
-  /**
-   * When true (server `--dev` without bearer/custom auth), session
-   * stream/events/follow-up are readable without matching the creating
-   * principal — matching `GET /v1/sessions` includeAll so the playground
-   * can open every listed session. Still requires a loopback caller unless
-   * {@link relaxSessionReadAuthBeyondLoopback} is also set.
-   */
-  relaxSessionReadAuth?: boolean;
-  /**
-   * With {@link relaxSessionReadAuth}, skip the loopback IP check so remote
-   * callers (e.g. Tailscale + `--allow-anonymous`) can open listed sessions.
-   */
-  relaxSessionReadAuthBeyondLoopback?: boolean;
-  /**
-   * `--dev` bridge: allow playground / HTTP callers to Approve/Deny parked
-   * tools on Slack-owned sessions (Slack principals never match local /
-   * anonymous auth). Does not open approval writes on HTTP-owned sessions.
-   * Respects the same loopback / beyondLoopback gate as session reads.
-   */
-  relaxSessionApprovalAuth?: boolean;
-}): ServerRoute[] {
-  const { engine, config, auth } = args;
-  const base = args.basePath ?? "";
-  const relaxSessionReadAuth = args.relaxSessionReadAuth ?? false;
-  const relaxSessionReadAuthBeyondLoopback = args.relaxSessionReadAuthBeyondLoopback ?? false;
-  const relaxSessionApprovalAuth = args.relaxSessionApprovalAuth ?? false;
-
-  const transformMessage = async (
-    message: string,
-    authContext: AuthContext | null,
-  ): Promise<string> => {
-    if (config.onMessage === undefined) {
-      return message;
-    }
-    return config.onMessage(message, { auth: authContext });
-  };
-
-  const createSession: ServerRoute = {
-    method: "POST",
-    pattern: `${base}/v1/session`,
-    auth,
-    handler: async (request, ctx) => {
-      const body = await readJsonObject(request);
-      if (body === undefined || typeof body.message !== "string") {
-        return errorResponse(
-          400,
-          "invalid_request",
-          "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
-      // fixture repos without putting them on the agent's default cloud.repos.
-      const cloud = readCloudOptions(body.cloud);
-      const session = await engine.send(HTTP_CHANNEL_ID, message, {
-        auth: ctx.auth,
-        ...(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 }),
-      });
-      return jsonResponse(
-        {
-          ok: true,
-          sessionId: session.id,
-          continuationToken: formatContinuationToken(
-            HTTP_CHANNEL_ID,
-            session.continuationToken ?? "",
-          ),
-          playgroundUrl: playgroundUrlForSession(request, base, session.id),
-          traceUrl: eventsUrlForSession(request.url, base, session.id),
-        },
-        { headers: { [SESSION_ID_HEADER]: session.id } },
-      );
-    },
-  };
-
-  const followUp: ServerRoute = {
-    method: "POST",
-    pattern: `${base}/v1/session/:sessionId`,
-    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}.`);
-      }
-      // HTTP can follow any chat session. Its credential is separate from the
-      // owning channel's continuation key.
-      if (record.mode === "task") {
-        return errorResponse(
-          409,
-          "session_not_followable",
-          "Task sessions are fire-and-forget; they do not accept follow-ups.",
-        );
-      }
-      const ownership = requireSessionOwner(record, ctx.auth, {
-        relax: relaxSessionReadAuth,
-        beyondLoopback: relaxSessionReadAuthBeyondLoopback,
-        requestIp: ctx.requestIp,
-      });
-      if (ownership !== undefined) {
-        return ownership;
-      }
-      const body = await readJsonObject(request);
-      if (body === undefined || typeof body.message !== "string") {
-        return errorResponse(
-          400,
-          "invalid_request",
-          "Expected a JSON body with a string `message`.",
-        );
-      }
-      if (typeof body.continuationToken !== "string") {
-        return errorResponse(
-          400,
-          "invalid_request",
-          "Expected a `continuationToken` from the previous response.",
-        );
-      }
-      const presented = parseContinuationToken(body.continuationToken);
-      if (presented === null) {
-        return errorResponse(
-          409,
-          "stale_continuation_token",
-          "The continuation token does not address this session's active continuation.",
-        );
-      }
-
-      const message = await transformMessage(body.message, ctx.auth);
-      const rotated = await engine.followUpHttp(sessionId, presented, message);
-      if (rotated === undefined) {
-        return errorResponse(
-          409,
-          "stale_continuation_token",
-          "The continuation token does not address this session's active continuation.",
-        );
-      }
-      return jsonResponse(
-        {
-          ok: true,
-          sessionId,
-          continuationToken: formatContinuationToken(HTTP_CHANNEL_ID, rotated),
-        },
-        { headers: { [SESSION_ID_HEADER]: sessionId } },
-      );
-    },
-  };
-
-  const stream: ServerRoute = {
-    method: "GET",
-    pattern: `${base}/v1/session/:sessionId/stream`,
-    auth,
-    handler: async (request, ctx) => {
-      const sessionId = ctx.params.sessionId ?? "";
-      // The stream-and-inspect handle is runtime-owned: sessions started by
-      // custom channels or schedules are observable here too when the caller
-      // matches the session's stored principal (or `--dev` relax). Follow-ups
-      // use the same ownership gate plus the session's continuation token.
-      // Lazy-restore by id so playground Open-trace works after redeploy
-      // when the session is durable but not in the local state root yet.
-      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 url = new URL(request.url);
-      const rawStartIndex = url.searchParams.get("startIndex");
-      const startIndex = rawStartIndex === null ? 0 : Number.parseInt(rawStartIndex, 10);
-      if (Number.isNaN(startIndex) || startIndex < 0) {
-        return errorResponse(400, "invalid_request", "startIndex must be a non-negative integer.");
-      }
-      const body = await engine.eventStream(sessionId, startIndex);
-      return new Response(body, {
-        status: 200,
-        headers: {
-          "content-type": "application/x-ndjson; charset=utf-8",
-          "cache-control": "no-store",
-          [SESSION_ID_HEADER]: sessionId,
-        },
-      });
-    },
-  };
-
-  /** One-shot NDJSON (or JSON) dump of the session trace. */
-  const events: ServerRoute = {
-    method: "GET",
-    pattern: `${base}/v1/session/:sessionId/events`,
-    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 url = new URL(request.url);
-      const asJson = url.searchParams.get("format") === "json";
-      const snapshot = await engine.listEvents(sessionId, 0, {
-        backfillCloudCost: true,
-      });
-      if (asJson) {
-        return jsonResponse({
-          sessionId,
-          events: snapshot,
-          playgroundUrl: playgroundUrlForSession(request, base, sessionId),
-        });
-      }
-      const ndjson = `${snapshot.map(e => JSON.stringify(e)).join("\n")}${
-        snapshot.length > 0 ? "\n" : ""
-      }`;
-      return new Response(ndjson, {
-        status: 200,
-        headers: {
-          "content-type": "application/x-ndjson; charset=utf-8",
-          "cache-control": "no-store",
-          "content-disposition": `attachment; filename="${sessionId}.ndjson"`,
-          [SESSION_ID_HEADER]: sessionId,
-        },
-      });
-    },
-  };
-
-  const cost: ServerRoute = {
-    method: "GET",
-    pattern: `${base}/v1/session/:sessionId/cost`,
-    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 payload = await engine.sessionCost(sessionId);
-      return jsonResponse(payload, {
-        headers: { [SESSION_ID_HEADER]: sessionId },
-      });
-    },
-  };
-
-  const listApprovals: ServerRoute = {
-    method: "GET",
-    pattern: `${base}/v1/session/:sessionId/approvals`,
-    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.listPendingApprovals(sessionId);
-      return jsonResponse({ ok: true, sessionId, pending });
-    },
-  };
-
-  const resolveApproval: ServerRoute = {
-    method: "POST",
-    pattern: `${base}/v1/session/:sessionId/approvals/: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 bridgeSlackApproval =
-        relaxSessionApprovalAuth === true &&
-        record.auth?.authenticator === "slack" &&
-        (relaxSessionReadAuthBeyondLoopback === true ||
-          (typeof ctx.requestIp === "string" && isLoopbackAddress(ctx.requestIp)));
-      const ownership = requireSessionOwner(record, ctx.auth, {
-        // HTTP sessions stay strict. Slack sessions may use the --dev
-        // playground bridge (see relaxSessionApprovalAuth).
-        relax: bridgeSlackApproval,
-        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.resolveApproval(
-          sessionId,
-          callId,
-          decision,
-          ctx.auth,
-          bridgeSlackApproval ? { asSessionOwner: true } : undefined,
-        );
-        return jsonResponse({
-          ok: true,
-          sessionId,
-          callId,
-          decision,
-          toolName: pending.toolName,
-        });
-      } catch (error) {
-        if (error instanceof ApprovalNotFoundError) {
-          return errorResponse(404, "approval_not_found", error.message);
-        }
-        if (error instanceof ApprovalInterruptedError) {
-          return errorResponse(409, "approval_interrupted", error.message);
-        }
-        if (error instanceof SessionAuthError) {
-          return errorResponse(403, "forbidden", error.message);
-        }
-        throw error;
-      }
-    },
-  };
-
-  const stop: ServerRoute = {
-    method: "POST",
-    pattern: `${base}/v1/session/:sessionId/stop`,
-    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 interrupted = await engine.interrupt(sessionId);
-      return jsonResponse(
-        { ok: true, interrupted },
-        { headers: { [SESSION_ID_HEADER]: sessionId } },
-      );
-    },
-  };
-
-  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,
-    stop,
-    stream,
-    events,
-    cost,
-    listApprovals,
-    resolveApproval,
-    listAuths,
-    resolveAuth,
-  ];
-}
-
-export function requireSessionOwner(
-  record: SessionRecord,
-  caller: AuthContext | null,
-  options?: {
-    relax?: boolean;
-    beyondLoopback?: boolean;
-    requestIp?: string | null;
-  },
-): Response | undefined {
-  // Dev playground lists every session (`includeAll`); match that by
-  // allowing cross-principal read/follow-up. Loopback-only unless
-  // `--allow-anonymous` also opted into beyondLoopback.
-  const relaxOwnership =
-    options?.relax === true &&
-    (options.beyondLoopback === true ||
-      (typeof options.requestIp === "string" && isLoopbackAddress(options.requestIp)));
-  if (relaxOwnership || samePrincipal(record.auth, caller)) {
-    return undefined;
-  }
-  return errorResponse(403, "forbidden", "This session belongs to a different principal.");
-}
-
-export function jsonResponse(
-  data: unknown,
-  init: { status?: number; headers?: Record<string, string> } = {},
-): Response {
-  return new Response(JSON.stringify(data), {
-    status: init.status ?? 200,
-    headers: {
-      "content-type": "application/json; charset=utf-8",
-      ...init.headers,
-    },
-  });
-}
-
-export function errorResponse(status: number, code: string, message: string): Response {
-  return jsonResponse({ ok: false, error: code, message }, { status });
-}
-
-function readWorkspaceFiles(value: unknown): Record<string, string> | undefined {
-  if (value === undefined || value === null || typeof value !== "object") {
-    return undefined;
-  }
-  if (Array.isArray(value)) {
-    return undefined;
-  }
-  const files: Record<string, string> = {};
-  for (const [path, contents] of Object.entries(value as Record<string, unknown>)) {
-    if (typeof path !== "string" || path.trim() === "") {
-      continue;
-    }
-    if (typeof contents !== "string") {
-      continue;
-    }
-    files[path] = contents;
-  }
-  return Object.keys(files).length === 0 ? undefined : files;
-}
-
-/** Best-effort parse of {@link AgentCloudOptions} from a JSON body field. */
-function readCloudOptions(value: unknown): AgentCloudOptions | undefined {
-  if (!isRecord(value)) {
-    return undefined;
-  }
-  const cloud: AgentCloudOptions = {};
-
-  if (isRecord(value.env) && typeof value.env.type === "string") {
-    const name = typeof value.env.name === "string" ? value.env.name : undefined;
-    if (value.env.type === "cloud") {
-      cloud.env = name === undefined ? { type: "cloud" } : { type: "cloud", name };
-    } else if (value.env.type === "pool") {
-      cloud.env = name === undefined ? { type: "pool" } : { type: "pool", name };
-    } else if (value.env.type === "machine") {
-      cloud.env = name === undefined ? { type: "machine" } : { type: "machine", name };
-    }
-  }
-
-  if (Array.isArray(value.repos)) {
-    const repos: NonNullable<AgentCloudOptions["repos"]> = [];
-    for (const entry of value.repos) {
-      if (!isRecord(entry) || typeof entry.url !== "string" || entry.url === "") {
-        continue;
-      }
-      repos.push({
-        url: entry.url,
-        ...(typeof entry.startingRef === "string" ? { startingRef: entry.startingRef } : {}),
-        ...(typeof entry.prUrl === "string" ? { prUrl: entry.prUrl } : {}),
-      });
-    }
-    if (repos.length > 0) {
-      cloud.repos = repos;
-    }
-  }
-
-  if (typeof value.workOnCurrentBranch === "boolean") {
-    cloud.workOnCurrentBranch = value.workOnCurrentBranch;
-  }
-  if (typeof value.autoCreatePR === "boolean") {
-    cloud.autoCreatePR = value.autoCreatePR;
-  }
-  if (typeof value.skipReviewerRequest === "boolean") {
-    cloud.skipReviewerRequest = value.skipReviewerRequest;
-  }
-
-  if (isRecord(value.envVars)) {
-    const envVars: Record<string, string> = {};
-    for (const [key, envValue] of Object.entries(value.envVars)) {
-      if (typeof key === "string" && typeof envValue === "string") {
-        envVars[key] = envValue;
-      }
-    }
-    if (Object.keys(envVars).length > 0) {
-      cloud.envVars = envVars;
-    }
-  }
-
-  return Object.keys(cloud).length === 0 ? undefined : cloud;
-}
-
-/** Parse a JSON object body. Requires `application/json` (CORS-simple types do not parse). */
-export async function readJsonObject(
-  request: Request,
-): Promise<Record<string, unknown> | undefined> {
-  const contentType = request.headers.get("content-type");
-  if (contentType === null || !isApplicationJson(contentType)) {
-    return undefined;
-  }
-  try {
-    const parsed: unknown = await request.json();
-    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-      return parsed as Record<string, unknown>;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function isApplicationJson(contentType: string): boolean {
-  return contentType.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
-}