@cursor/july 0.1.2 → 0.1.4

package/src/internal/playground-proxy.ts

@@ -0,0 +1,576 @@
+/**
+ * Loopback reverse proxy that injects engine / bearer auth so a normal
+ * browser can use the hosted (or remote) playground SPA.
+ *
+ * Hosted engines sit behind short-lived `engineAccess` headers that a
+ * browser cannot set; alias tokens are header-only too. This proxy binds
+ * `127.0.0.1` only and forwards every request upstream with those headers.
+ *
+ * Access is gated by a per-proxy `accessToken` (query on first hit → HttpOnly
+ * cookie): other local processes cannot upgrade to injected credentials just
+ * by knowing the port. Mutating requests also require Origin/Referer to match
+ * this proxy's own origin so another `http://127.0.0.1:<port>` page cannot
+ * CSRF the cookie (cookies are host-scoped across ports). Absolute-form
+ * request-targets are rejected so injected headers never leave the configured
+ * upstream.
+ *
+ * When `refreshUpstream` is provided (hosted `--prod`), credentials are
+ * re-minted shortly before `expiresAt` and once on upstream 401 so a long
+ * playground session does not require restarting the CLI.
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+  createServer,
+  request as httpRequest,
+  type IncomingMessage,
+  type RequestOptions,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { request as httpsRequest } from "node:https";
+import type { AddressInfo } from "node:net";
+import { URL } from "node:url";
+import { openBrowser } from "./open-browser.js";
+
+export { openBrowser };
+
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length",
+]);
+
+/** Re-mint when the port token is within this window of expiry. */
+const ACCESS_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
+
+const PROXY_COOKIE = "agentkit_playground_proxy";
+const PROXY_TOKEN_QUERY = "proxyToken";
+
+export interface PlaygroundProxyHandle {
+  /** e.g. `http://127.0.0.1:54321` (no trailing slash). */
+  localUrl: string;
+  port: number;
+  /** Random token required via query (first hit) or cookie thereafter. */
+  accessToken: string;
+  /**
+   * Build a browser entry URL for `/playground` that includes the access
+   * token (and optional sessionId).
+   */
+  playgroundUrl: (sessionId?: string) => string;
+  close: () => Promise<void>;
+}
+
+export interface PlaygroundUpstreamAccess {
+  upstreamUrl: string;
+  headers?: Record<string, string>;
+  expiresAt?: string;
+}
+
+export interface StartPlaygroundProxyArgs {
+  /** Upstream agent base URL (engineAccess or --url). */
+  upstreamUrl: string;
+  /** Headers injected on every upstream request (engine tokens, wake, …). */
+  headers?: Record<string, string>;
+  /** Optional bearer for local servers that require it. */
+  bearerToken?: string;
+  /** Initial engineAccess expiry (ISO); enables proactive refresh. */
+  expiresAt?: string;
+  /**
+   * Re-mint upstream URL + headers (hosted `--prod`). Single-flighted across
+   * concurrent browser requests; called near expiry and once on 401.
+   */
+  refreshUpstream?: () => Promise<PlaygroundUpstreamAccess>;
+  /** Bind port; `0` = ephemeral. */
+  port?: number;
+  /** Injected for tests. */
+  createServerImpl?: typeof createServer;
+  /** Injected clock for expiry tests. */
+  now?: () => number;
+  /** Injected token for tests (defaults to a random 32-byte value). */
+  accessToken?: string;
+}
+
+interface UpstreamState {
+  upstream: URL;
+  injectHeaders: Record<string, string>;
+  expiresAtMs: number | undefined;
+}
+
+/**
+ * Start a loopback proxy. Resolves once listening.
+ */
+export async function startPlaygroundProxy(
+  args: StartPlaygroundProxyArgs
+): Promise<PlaygroundProxyHandle> {
+  const upstream = parseUpstreamUrl(args.upstreamUrl);
+  const state: UpstreamState = {
+    upstream,
+    injectHeaders: buildInjectHeaders(args.headers, args.bearerToken),
+    expiresAtMs: parseExpiresAtMs(args.expiresAt),
+  };
+  const accessToken = args.accessToken ?? randomBytes(32).toString("base64url");
+  const now = args.now ?? Date.now;
+  let refreshInFlight: Promise<void> | undefined;
+  /** Set after listen; used for Origin CSRF checks. */
+  let proxyOrigin = "";
+
+  const ensureFreshAccess = async (force: boolean): Promise<void> => {
+    if (args.refreshUpstream === undefined) {
+      return;
+    }
+    const expired =
+      state.expiresAtMs !== undefined &&
+      now() >= state.expiresAtMs - ACCESS_EXPIRY_LEEWAY_MS;
+    if (!force && !expired) {
+      return;
+    }
+    if (refreshInFlight !== undefined) {
+      await refreshInFlight;
+      return;
+    }
+    refreshInFlight = (async () => {
+      const next = await args.refreshUpstream!();
+      state.upstream = parseUpstreamUrl(next.upstreamUrl);
+      state.injectHeaders = buildInjectHeaders(next.headers, args.bearerToken);
+      state.expiresAtMs = parseExpiresAtMs(next.expiresAt);
+    })().finally(() => {
+      refreshInFlight = undefined;
+    });
+    await refreshInFlight;
+  };
+
+  const create = args.createServerImpl ?? createServer;
+  const server: Server = create((req, res) => {
+    void handleProxyRequest({
+      req,
+      res,
+      getState: () => state,
+      ensureFreshAccess,
+      canRefresh: args.refreshUpstream !== undefined,
+      accessToken,
+      proxyOrigin: () => proxyOrigin,
+    }).catch((error: unknown) => {
+      if (res.headersSent) {
+        if (!res.writableEnded) {
+          res.end();
+        }
+        return;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+      res.end(`Playground proxy error: ${message}`);
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(args.port ?? 0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = server.address() as AddressInfo;
+  const localUrl = `http://127.0.0.1:${address.port}`;
+  proxyOrigin = localUrl;
+
+  return {
+    localUrl,
+    port: address.port,
+    accessToken,
+    playgroundUrl: (sessionId?: string) => {
+      const url = new URL(`${localUrl}/playground`);
+      url.searchParams.set(PROXY_TOKEN_QUERY, accessToken);
+      if (sessionId !== undefined && sessionId.trim() !== "") {
+        url.searchParams.set("sessionId", sessionId.trim());
+      }
+      return url.toString();
+    },
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        // Drop keep-alive / streamed playground connections so Ctrl-C
+        // does not hang waiting for active sockets.
+        server.closeAllConnections();
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      }),
+  };
+}
+
+function parseUpstreamUrl(raw: string): URL {
+  const upstream = new URL(raw.replace(/\/$/, ""));
+  if (upstream.protocol !== "http:" && upstream.protocol !== "https:") {
+    throw new Error(`Unsupported upstream protocol: ${upstream.protocol}`);
+  }
+  return upstream;
+}
+
+function parseExpiresAtMs(expiresAt: string | undefined): number | undefined {
+  if (expiresAt === undefined || expiresAt.trim() === "") {
+    return undefined;
+  }
+  const ms = Date.parse(expiresAt);
+  return Number.isFinite(ms) ? ms : undefined;
+}
+
+function buildInjectHeaders(
+  headers: Record<string, string> | undefined,
+  bearerToken: string | undefined
+): Record<string, string> {
+  const out: Record<string, string> = { ...(headers ?? {}) };
+  if (bearerToken !== undefined && bearerToken.trim() !== "") {
+    out.authorization = `Bearer ${bearerToken.trim()}`;
+  }
+  return out;
+}
+
+async function readRequestBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function handleProxyRequest(args: {
+  req: IncomingMessage;
+  res: ServerResponse;
+  getState: () => UpstreamState;
+  ensureFreshAccess: (force: boolean) => Promise<void>;
+  canRefresh: boolean;
+  accessToken: string;
+  proxyOrigin: () => string;
+}): Promise<void> {
+  const {
+    req,
+    res,
+    getState,
+    ensureFreshAccess,
+    canRefresh,
+    accessToken,
+    proxyOrigin,
+  } = args;
+  const pathWithQuery = req.url ?? "/";
+
+  const pathParse = parseProxyPath(pathWithQuery);
+  if (!pathParse.ok) {
+    res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+    res.end("Absolute-form request targets are not allowed");
+    return;
+  }
+
+  const auth = authorizeLocalRequest({
+    pathWithQuery: pathParse.path,
+    cookieHeader: req.headers.cookie,
+    accessToken,
+  });
+  if (auth.kind === "deny") {
+    res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
+    res.end("Playground proxy requires the session access token");
+    return;
+  }
+  if (auth.kind === "bootstrap") {
+    res.writeHead(302, {
+      location: auth.redirectPath,
+      "set-cookie": auth.setCookie,
+      "cache-control": "no-store",
+    });
+    res.end();
+    return;
+  }
+
+  const method = req.method ?? "GET";
+  if (
+    !isTrustedBrowserOrigin({
+      method,
+      origin: headerString(req.headers.origin),
+      referer: headerString(req.headers.referer),
+      secFetchSite: headerString(req.headers["sec-fetch-site"]),
+      proxyOrigin: proxyOrigin(),
+    })
+  ) {
+    res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+    res.end("Playground proxy rejected cross-origin request");
+    return;
+  }
+
+  let body: Buffer;
+  try {
+    body = await readRequestBody(req);
+  } catch {
+    if (!res.headersSent) {
+      res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Playground proxy failed to read request body");
+    }
+    return;
+  }
+
+  const forward = (
+    state: UpstreamState,
+    deferWriteOnUnauthorized: boolean
+  ): Promise<number> =>
+    forwardOnce({
+      method,
+      pathWithQuery: pathParse.path,
+      inboundHeaders: req.headers,
+      body,
+      state,
+      res,
+      deferWriteOnUnauthorized,
+    });
+
+  try {
+    await ensureFreshAccess(false);
+    let status = await forward(getState(), canRefresh);
+    if (status === 401 && canRefresh) {
+      await ensureFreshAccess(true);
+      // Retry once; always write this response (even if still 401).
+      status = await forward(getState(), false);
+    }
+    void status;
+  } catch (error) {
+    if (!res.headersSent) {
+      const message = error instanceof Error ? error.message : String(error);
+      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+      res.end(`Playground proxy upstream error: ${message}`);
+    } else if (!res.writableEnded) {
+      res.end();
+    }
+  }
+}
+
+/**
+ * Cookies are host-scoped across ports on 127.0.0.1, so SameSite=Strict alone
+ * does not stop CSRF from another loopback origin. Require the browser's
+ * Origin (or Referer / Sec-Fetch-Site: same-origin) to match this proxy for
+ * mutating methods. Safe methods stay cookie-gated only (no side effects).
+ */
+function isTrustedBrowserOrigin(args: {
+  method: string;
+  origin: string | undefined;
+  referer: string | undefined;
+  secFetchSite: string | undefined;
+  proxyOrigin: string;
+}): boolean {
+  const method = args.method.toUpperCase();
+  if (method === "GET" || method === "HEAD" || method === "OPTIONS") {
+    return true;
+  }
+  if (args.proxyOrigin === "") {
+    return false;
+  }
+  if (args.origin === args.proxyOrigin) {
+    return true;
+  }
+  if (
+    args.referer !== undefined &&
+    (args.referer === args.proxyOrigin ||
+      args.referer.startsWith(`${args.proxyOrigin}/`))
+  ) {
+    return true;
+  }
+  // Some same-origin fetches omit Origin; modern browsers still send this.
+  if (args.secFetchSite === "same-origin") {
+    return true;
+  }
+  return false;
+}
+
+function headerString(
+  value: string | string[] | undefined
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function authorizeLocalRequest(args: {
+  pathWithQuery: string;
+  cookieHeader: string | string[] | undefined;
+  accessToken: string;
+}):
+  | { kind: "allow" }
+  | { kind: "deny" }
+  | { kind: "bootstrap"; redirectPath: string; setCookie: string } {
+  const cookieToken = readCookie(args.cookieHeader, PROXY_COOKIE);
+  if (cookieToken === args.accessToken) {
+    return { kind: "allow" };
+  }
+
+  const url = new URL(args.pathWithQuery, "http://127.0.0.1");
+  const queryToken = url.searchParams.get(PROXY_TOKEN_QUERY);
+  if (queryToken === args.accessToken) {
+    url.searchParams.delete(PROXY_TOKEN_QUERY);
+    const redirectPath = `${url.pathname}${url.search}`;
+    return {
+      kind: "bootstrap",
+      redirectPath,
+      setCookie: `${PROXY_COOKIE}=${args.accessToken}; Path=/; HttpOnly; SameSite=Strict`,
+    };
+  }
+  return { kind: "deny" };
+}
+
+function readCookie(
+  header: string | string[] | undefined,
+  name: string
+): string | undefined {
+  if (header === undefined) {
+    return undefined;
+  }
+  const raw = Array.isArray(header) ? header.join("; ") : header;
+  for (const part of raw.split(";")) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    if (trimmed.slice(0, eq) === name) {
+      return trimmed.slice(eq + 1);
+    }
+  }
+  return undefined;
+}
+
+async function forwardOnce(args: {
+  method: string;
+  pathWithQuery: string;
+  inboundHeaders: IncomingMessage["headers"];
+  body: Buffer;
+  state: UpstreamState;
+  res: ServerResponse;
+  deferWriteOnUnauthorized: boolean;
+}): Promise<number> {
+  const { method, pathWithQuery, inboundHeaders, body, state, res } = args;
+  const target = buildTargetUrl(pathWithQuery, state.upstream);
+
+  const outboundHeaders: Record<string, string | string[] | undefined> = {};
+  for (const [name, value] of Object.entries(inboundHeaders)) {
+    if (value === undefined) continue;
+    const lower = name.toLowerCase();
+    if (HOP_BY_HOP.has(lower)) continue;
+    if (lower === "authorization") continue;
+    // Do not forward the loopback session cookie upstream.
+    if (lower === "cookie") continue;
+    outboundHeaders[name] = value;
+  }
+  for (const [name, value] of Object.entries(state.injectHeaders)) {
+    outboundHeaders[name] = value;
+  }
+  outboundHeaders.host = target.host;
+  outboundHeaders["content-length"] = String(body.byteLength);
+
+  const isHttps = target.protocol === "https:";
+  const requestFn = isHttps ? httpsRequest : httpRequest;
+  const options: RequestOptions = {
+    protocol: target.protocol,
+    hostname: target.hostname,
+    port: target.port === "" ? (isHttps ? 443 : 80) : Number(target.port),
+    method,
+    path: `${target.pathname}${target.search}`,
+    headers: outboundHeaders,
+  };
+
+  return await new Promise<number>((resolve, reject) => {
+    const upstreamReq = requestFn(options, (upstreamRes) => {
+      const status = upstreamRes.statusCode ?? 502;
+      if (status === 401 && args.deferWriteOnUnauthorized) {
+        // Drain so the socket can be reused; caller will refresh + retry.
+        upstreamRes.resume();
+        upstreamRes.on("end", () => resolve(status));
+        upstreamRes.on("error", () => resolve(status));
+        return;
+      }
+
+      const responseHeaders: Record<string, string | string[] | undefined> = {
+        ...upstreamRes.headers,
+      };
+      for (const hop of HOP_BY_HOP) {
+        delete responseHeaders[hop];
+      }
+      res.writeHead(status, responseHeaders);
+      upstreamRes.pipe(res);
+      upstreamRes.on("end", () => resolve(status));
+      upstreamRes.on("error", () => {
+        if (!res.writableEnded) {
+          res.end();
+        }
+        resolve(status);
+      });
+    });
+
+    upstreamReq.on("error", (error) => {
+      reject(error);
+    });
+
+    res.on("close", () => {
+      if (!res.writableEnded) {
+        upstreamReq.destroy();
+      }
+    });
+
+    upstreamReq.end(body);
+  });
+}
+
+/**
+ * Build an upstream URL that always keeps the configured host/port.
+ * Absolute-form or protocol-relative request-targets must not retarget
+ * outbound requests (injected engine/bearer credentials would follow).
+ */
+function buildTargetUrl(pathWithQuery: string, upstream: URL): URL {
+  const pathParse = parseProxyPath(pathWithQuery);
+  const relative = pathParse.ok ? pathParse.path : "/";
+  const target = new URL(relative, upstream);
+  // Force authority back onto the configured upstream even if `new URL`
+  // accepted an absolute/protocol-relative request-target.
+  target.protocol = upstream.protocol;
+  target.hostname = upstream.hostname;
+  target.port = upstream.port;
+  target.username = "";
+  target.password = "";
+
+  // Preserve upstream pathname prefix when the base URL has one
+  // (unusual for engineAccess; kept for `--url` mounts).
+  if (upstream.pathname !== "/" && upstream.pathname !== "") {
+    const basePath = upstream.pathname.replace(/\/$/, "");
+    if (!pathnameHasPrefix(target.pathname, basePath)) {
+      target.pathname =
+        target.pathname === "/"
+          ? `${basePath}/`
+          : `${basePath}${target.pathname}`;
+    }
+  }
+  return target;
+}
+
+/** Reject absolute / scheme-relative request-targets; keep path + query only. */
+function parseProxyPath(
+  pathWithQuery: string
+): { ok: true; path: string } | { ok: false } {
+  const raw = pathWithQuery.trim();
+  if (raw === "") {
+    return { ok: true, path: "/" };
+  }
+  // Absolute-form ("http://evil/…") or protocol-relative ("//evil/…").
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/u.test(raw) || raw.startsWith("//")) {
+    return { ok: false };
+  }
+  return { ok: true, path: raw.startsWith("/") ? raw : `/${raw}` };
+}
+
+function pathnameHasPrefix(pathname: string, basePath: string): boolean {
+  return pathname === basePath || pathname.startsWith(`${basePath}/`);
+}

package/src/internal/prompt-context.ts

@@ -0,0 +1,95 @@
+/**
+ * Framework-authored prompt context. Two pieces:
+ *
+ * 1. Identity section — static, appended to the agent's instructions (local
+ *    AGENTS.md and cloud first-turn preamble) so the model knows its own
+ *    name and how messages and sessions reach it.
+ * 2. Session context block — dynamic, prepended to the first turn's user
+ *    prompt only, telling the model which session/channel/environment it is
+ *    in plus a channel-appropriate presence line.
+ */
+
+import type { ResolvedAgent } from "../types.js";
+
+export const SCHEDULE_CHANNEL_PREFIX = "schedule:";
+
+export type PromptEnvironment = "hosted deployment" | "local dev server";
+
+export function buildIdentitySection(
+  agent: Pick<ResolvedAgent, "name" | "description">
+): string {
+  const description = agent.description?.trim().replace(/\.$/, "");
+  const intro =
+    description === undefined || description === ""
+      ? `You are "${agent.name}".`
+      : `You are "${agent.name}" — ${description}.`;
+  return [
+    "## About you",
+    "",
+    `${intro} You run as a persistent service: messages reach you through channels (such as Slack, GitHub, webhooks, or a web playground), and each conversation is a session that can continue across multiple turns.`,
+  ].join("\n");
+}
+
+export interface SessionContextInput {
+  sessionId: string;
+  channelId: string;
+  /**
+   * The channel pack's `meta.kind` (e.g. `"slack"`, `"github"`). Channel ids
+   * are file stems, so kind — not id — identifies what the channel is.
+   */
+  channelKind?: string;
+  environment: PromptEnvironment;
+  /** Injectable clock for tests; defaults to now. */
+  now?: Date;
+}
+
+export function buildSessionContextBlock(input: SessionContextInput): string {
+  const lines = [
+    "<agentkit_context>",
+    `session: ${input.sessionId}`,
+    `channel: ${input.channelId}`,
+    `environment: ${input.environment}`,
+    `time: ${(input.now ?? new Date()).toISOString()}`,
+    "</agentkit_context>",
+  ];
+  const presence = channelPresenceLine(input);
+  if (presence !== undefined) {
+    lines.push(presence);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * One line telling the model whether anyone is watching this session and
+ * where its output lands. Resolved from the channel pack's declared kind
+ * when present, falling back to the built-in channel ids. Unknown channels
+ * get no line rather than a guess.
+ */
+export function channelPresenceLine(
+  channel: Pick<SessionContextInput, "channelId" | "channelKind">
+): string | undefined {
+  const kind = channel.channelKind ?? builtinChannelKind(channel.channelId);
+  switch (kind) {
+    case "http":
+    case "mcp":
+      return "A user is interacting with you live and sees your replies as they stream.";
+    case "slack":
+      return "You are replying in a Slack thread; participants will read your messages.";
+    case "github":
+      return "You were triggered by a GitHub event. Deliver results through the actions available to you (comments, reviews, PRs); nobody sees your raw output otherwise.";
+    case "schedule":
+      return "This run was triggered automatically. No user is watching; complete the task autonomously and deliver results through your available tools/channels.";
+    default:
+      return undefined;
+  }
+}
+
+function builtinChannelKind(channelId: string): string | undefined {
+  if (channelId === "http" || channelId === "mcp") {
+    return channelId;
+  }
+  if (channelId.startsWith(SCHEDULE_CHANNEL_PREFIX)) {
+    return "schedule";
+  }
+  return undefined;
+}