@cursor/july 0.1.1

package/src/internal/host-platforms.ts

@@ -0,0 +1,144 @@
+/**
+ * Host-side GitHub + Slack clients shared across tools, channel routes,
+ * schedules, and channel packs — same injection pattern as MCP.
+ */
+
+import { WebClient } from "@slack/web-api";
+import { createGitHubOctokit } from "../channels/github/api.js";
+import {
+  ensureGhCliTokenEnv,
+  hasGitHubAppCredentials,
+  resolveCredentialValue,
+  resolveGitHubInstallationId,
+  tryResolveGhAuthToken,
+} from "../channels/github/auth.js";
+import { tryResolveBotToken } from "../channels/slack/credentials.js";
+import type { HostGitHubClient, HostSlackClient } from "../types.js";
+
+export interface HostPlatforms {
+  github: HostGitHubClient;
+  slack: HostSlackClient;
+}
+
+/**
+ * How ambient host GitHub auth was resolved.
+ * `app` = GitHub App installation token (preferred in production).
+ * `env` / `gh` = local PAT / CLI fallbacks when App creds are unset.
+ */
+export type HostGitHubAuthSource = "app" | "env" | "gh" | "unavailable";
+
+/**
+ * Build host platforms from ambient credentials. Prefer App installation
+ * auth when configured; otherwise fall back to PAT / `gh auth` for local
+ * testing. Webhook-scoped calls should still prefer `ctx.github`.
+ */
+export function createHostPlatforms(): HostPlatforms {
+  let octokitPromise: ReturnType<HostGitHubClient["getOctokit"]> | undefined;
+  let slackPromise: ReturnType<HostSlackClient["getClient"]> | undefined;
+
+  return {
+    github: {
+      getOctokit: () => {
+        octokitPromise ??= createGitHubOctokit({});
+        return octokitPromise;
+      },
+    },
+    slack: {
+      getClient: async () => {
+        if (slackPromise === undefined) {
+          slackPromise = (async () => {
+            const token = await tryResolveBotToken(undefined);
+            if (token === undefined) {
+              throw new Error(
+                "No Slack bot token available (set SLACK_BOT_TOKEN or a channel envPrefix)."
+              );
+            }
+            return new WebClient(token);
+          })();
+        }
+        return slackPromise;
+      },
+    },
+  };
+}
+
+/**
+ * Detect ambient host GitHub auth without throwing.
+ * Order matches {@link createGitHubOctokit}: App installation, then
+ * `GITHUB_TOKEN` / `GH_TOKEN`, then `gh auth token`.
+ */
+export async function resolveHostGitHubAuthSource(): Promise<HostGitHubAuthSource> {
+  if (
+    (await hasGitHubAppCredentials()) &&
+    (await resolveGitHubInstallationId()) !== undefined
+  ) {
+    return "app";
+  }
+  const fromEnv =
+    (await resolveCredentialValue(process.env.GITHUB_TOKEN)) ??
+    (await resolveCredentialValue(process.env.GH_TOKEN));
+  if (fromEnv !== undefined) {
+    return "env";
+  }
+  const fromGh = await tryResolveGhAuthToken();
+  return fromGh === undefined ? "unavailable" : "gh";
+}
+
+/**
+ * Soft boot-time GitHub auth check: log the resolved source and optionally
+ * prime `github.getOctokit()` so the first request does not pay CLI latency.
+ * When auth is App-backed, also export an installation token as `GH_TOKEN`
+ * so tools that shell out to `gh` (a host-side `prepare_pr` tool, say)
+ * authenticate on corp hosts that have no PAT / `gh
+ * auth login`. Never fails serve — missing auth is logged as a warning.
+ */
+export async function warmupHostGitHubAuth(options: {
+  logger: (line: string) => void;
+  github?: HostGitHubClient;
+}): Promise<HostGitHubAuthSource> {
+  const source = await resolveHostGitHubAuthSource();
+  if (source === "unavailable") {
+    options.logger(
+      "[agent-serve] GitHub auth: unavailable (set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID, or GITHUB_TOKEN / GH_TOKEN, or run `gh auth login`)"
+    );
+    return source;
+  }
+
+  let exportedGhToken = false;
+  if (source === "app") {
+    try {
+      exportedGhToken = await ensureGhCliTokenEnv();
+    } catch (error) {
+      options.logger(
+        `[agent-serve] GitHub auth: failed to export GH_TOKEN for gh CLI: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  const label =
+    source === "app"
+      ? exportedGhToken
+        ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
+        : "GitHub App installation token"
+      : source === "env"
+        ? "GITHUB_TOKEN/GH_TOKEN"
+        : "gh auth token";
+  if (options.github === undefined) {
+    options.logger(`[agent-serve] GitHub auth: ${label}`);
+    return source;
+  }
+
+  try {
+    await options.github.getOctokit();
+    options.logger(`[agent-serve] GitHub auth: ${label}`);
+  } catch (error) {
+    options.logger(
+      `[agent-serve] GitHub auth: ${label} resolved but Octokit warmup failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+  return source;
+}

package/src/internal/http-channel.ts

@@ -0,0 +1,546 @@
+/**
+ * The built-in HTTP session channel: the default API that `curl`, SDK
+ * clients, and frontends talk to. Mounted at `/v1/session*` and enabled even
+ * when `agent/channels/http.ts` does not exist; author that file with
+ * `httpChannel({ ... })` to override auth or observe events.
+ *
+ * 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
+ * that session's channel + key; task sessions stay fire-and-forget.
+ */
+
+import type {
+  AuthContext,
+  AuthPolicy,
+  HttpChannelDefinition,
+  JsonValue,
+  SessionRecord,
+} from "../types.js";
+import { samePrincipal } from "./auth.js";
+import {
+  formatContinuationToken,
+  newContinuationKey,
+  parseContinuationToken,
+} from "./ids.js";
+import { isLoopbackAddress } from "./net.js";
+import type { ServerRoute } from "./router.js";
+import {
+  ApprovalInterruptedError,
+  ApprovalNotFoundError,
+  HTTP_CHANNEL_ID,
+  SessionAuthError,
+  SessionBusyError,
+  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`."
+        );
+      }
+      const message = await transformMessage(body.message, ctx.auth);
+      const workspaceFiles = readWorkspaceFiles(body.workspaceFiles);
+      const session = await engine.send(HTTP_CHANNEL_ID, message, {
+        auth: ctx.auth,
+        ...(body.state === undefined ? {} : { state: body.state as JsonValue }),
+        ...(typeof body.title === "string" ? { title: body.title } : {}),
+        ...(body.purpose === "eval" ? { purpose: "eval" as const } : {}),
+        ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
+      });
+      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.sessions.get(sessionId);
+      if (record === undefined) {
+        return errorResponse(
+          404,
+          "session_not_found",
+          `Unknown session ${sessionId}.`
+        );
+      }
+      // Playground (and other HTTP clients) may follow up on any chat
+      // session — including custom channels like `drive` — using that
+      // session's own continuation token. Task/schedule sessions stay
+      // fire-and-forget.
+      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 ||
+        presented.channelId !== record.channelId ||
+        record.continuationKey === null ||
+        presented.key !== record.continuationKey
+      ) {
+        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);
+      try {
+        // Continue as the session owner after the HTTP ownership gate so
+        // `--dev` relaxed reads can follow up on channel-owned sessions
+        // (drive/slack/…) without failing SessionAuthError.
+        await engine.send(record.channelId, message, {
+          auth: record.auth,
+          continuationToken: record.continuationKey,
+        });
+      } catch (error) {
+        if (error instanceof SessionBusyError) {
+          return errorResponse(
+            409,
+            "session_busy",
+            "A turn is already running; wait for session.waiting before sending a follow-up."
+          );
+        }
+        throw error;
+      }
+
+      // Rotate only after the message is accepted so a rejected send leaves
+      // the caller's token valid for retry.
+      const rotated = newContinuationKey();
+      await engine.setContinuationToken(sessionId, rotated);
+      return jsonResponse(
+        {
+          ok: true,
+          sessionId,
+          continuationToken: formatContinuationToken(record.channelId, 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.
+      const record = await engine.sessions.get(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.sessions.get(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);
+      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 listApprovals: ServerRoute = {
+    method: "GET",
+    pattern: `${base}/v1/session/:sessionId/approvals`,
+    auth,
+    handler: async (_request, ctx) => {
+      const sessionId = ctx.params.sessionId ?? "";
+      const record = await engine.sessions.get(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.sessions.get(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.sessions.get(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 } }
+      );
+    },
+  };
+
+  return [
+    createSession,
+    followUp,
+    stop,
+    stream,
+    events,
+    listApprovals,
+    resolveApproval,
+  ];
+}
+
+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;
+}
+
+export async function readJsonObject(
+  request: Request
+): Promise<Record<string, unknown> | 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;
+  }
+}