@cursor/bdk 0.2.1

package/src/internal/http-channel.ts

@@ -0,0 +1,669 @@
+/**
+ * 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";
+}