@cursor/july 0.1.1

package/src/channels.ts

@@ -0,0 +1,385 @@
+/**
+ * `defineChannel` and the built-in HTTP channel — authored at
+ * `agent/channels/<name>.ts`.
+ *
+ * A channel is the surface an agent lives on. The built-in HTTP channel
+ * (session create / follow-up / NDJSON stream routes under `/v1/session*`)
+ * is always mounted; author `agent/channels/http.ts` with `httpChannel()`
+ * only to override its defaults. Custom channels declare their own routes
+ * and are mounted under `/v1/channels/<name>`:
+ *
+ * ```ts
+ * import { defineChannel, POST } from "@anysphere/agent-serve/channels";
+ * import { z } from "zod";
+ *
+ * export default defineChannel({
+ *   routes: [
+ *     POST("/message", {
+ *       bodySchema: z.object({
+ *         message: z.string(),
+ *         token: z.string().optional(),
+ *       }),
+ *       handler: async (_req, { send, body }) => {
+ *         const { message, token } = body as {
+ *           message: string;
+ *           token?: string;
+ *         };
+ *         const session = await send(message, {
+ *           continuationToken: token,
+ *         });
+ *         return Response.json({ sessionId: session.id });
+ *       },
+ *     }),
+ *   ],
+ *   events: {
+ *     "message.completed"(event, channel, ctx) {
+ *       // deliver completed messages back to the surface that owns this
+ *       // channel (post to a webhook, reply in a thread, ...)
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * Route helpers are typed so HTTP channels must declare **Zod** schemas at
+ * compile time: `GET` requires `querySchema`, `POST`/`PUT`/`PATCH` require
+ * `bodySchema`. Plain JSON Schema objects will not type-check. Use
+ * `z.object({})` / `z.unknown()` when the surface is intentionally open.
+ * Handlers receive `args.body` / `args.query` inferred from those schemas.
+ */
+
+import { Buffer } from "node:buffer";
+import { timingSafeEqual } from "node:crypto";
+import { brandDefinition } from "./internal/brand.js";
+import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
+import type {
+  AuthContext,
+  AuthPolicy,
+  ChannelBodyRouteSpec,
+  ChannelConfig,
+  ChannelDefinition,
+  ChannelDeleteRouteSpec,
+  ChannelGetRouteSpec,
+  ChannelRoute,
+  ChannelRouteHandler,
+  ChannelRouteSchema,
+  HttpChannelConfig,
+  HttpChannelDefinition,
+  JsonValue,
+  RouteMethod,
+} from "./types.js";
+
+export type {
+  AuthContext,
+  AuthPolicy,
+  ChannelBodyRouteSpec,
+  ChannelConfig,
+  ChannelDefinition,
+  ChannelDeleteRouteSpec,
+  ChannelEventContext,
+  ChannelEventHandler,
+  ChannelEventHandlers,
+  ChannelGetRouteSpec,
+  ChannelHandlerArgs,
+  ChannelHandlerArgsWithBody,
+  ChannelHandlerArgsWithBodyAndQuery,
+  ChannelHandlerArgsWithQuery,
+  ChannelRoute,
+  ChannelRouteHandler,
+  ChannelRouteSchema,
+  ChannelRouteSpec,
+  ChannelSession,
+  ChannelStartArgs,
+  HttpChannelConfig,
+  HttpChannelDefinition,
+  ReceiveInput,
+  RouteMethod,
+  SendMessageFn,
+  SendMessageOptions,
+} from "./types.js";
+
+/** Define a custom channel. */
+export function defineChannel<TState = JsonValue>(
+  config: ChannelConfig<TState>
+): ChannelDefinition<TState> {
+  return brandDefinition("channel", config);
+}
+
+/**
+ * Configure the built-in HTTP session channel. Only meaningful as the
+ * default export of `agent/channels/http.ts`.
+ */
+export function httpChannel(
+  config: HttpChannelConfig = {}
+): HttpChannelDefinition {
+  return brandDefinition("http-channel", config);
+}
+
+// ============================================================================
+// Route verbs
+// ============================================================================
+
+function route(
+  method: RouteMethod,
+  path: string,
+  spec: {
+    description?: string;
+    bodySchema?: ChannelRouteSchema;
+    querySchema?: ChannelRouteSchema;
+    handler: ChannelRouteHandler;
+  }
+): ChannelRoute {
+  if (!path.startsWith("/")) {
+    throw new Error(`Channel route path must start with "/": ${path}`);
+  }
+  const result: ChannelRoute = {
+    method,
+    path,
+    handler: spec.handler,
+  };
+  if (spec.description !== undefined) {
+    result.description = spec.description;
+  }
+  if (spec.bodySchema !== undefined) {
+    result.bodySchema = spec.bodySchema;
+  }
+  if (spec.querySchema !== undefined) {
+    result.querySchema = spec.querySchema;
+  }
+  return result;
+}
+
+/** GET — Zod `querySchema` is required (use `z.object({})` when unused). */
+export function GET<TQuery extends ChannelRouteSchema>(
+  path: string,
+  spec: ChannelGetRouteSpec<TQuery>
+): ChannelRoute {
+  return route("GET", path, {
+    description: spec.description,
+    querySchema: spec.querySchema,
+    handler: spec.handler as ChannelRouteHandler,
+  });
+}
+
+/** POST — Zod `bodySchema` is required. */
+export function POST<
+  TBody extends ChannelRouteSchema,
+  TQuery extends ChannelRouteSchema | undefined = undefined,
+>(path: string, spec: ChannelBodyRouteSpec<TBody, TQuery>): ChannelRoute {
+  return route("POST", path, {
+    description: spec.description,
+    bodySchema: spec.bodySchema,
+    querySchema: spec.querySchema,
+    handler: spec.handler as ChannelRouteHandler,
+  });
+}
+
+/** PUT — Zod `bodySchema` is required. */
+export function PUT<
+  TBody extends ChannelRouteSchema,
+  TQuery extends ChannelRouteSchema | undefined = undefined,
+>(path: string, spec: ChannelBodyRouteSpec<TBody, TQuery>): ChannelRoute {
+  return route("PUT", path, {
+    description: spec.description,
+    bodySchema: spec.bodySchema,
+    querySchema: spec.querySchema,
+    handler: spec.handler as ChannelRouteHandler,
+  });
+}
+
+/** PATCH — Zod `bodySchema` is required. */
+export function PATCH<
+  TBody extends ChannelRouteSchema,
+  TQuery extends ChannelRouteSchema | undefined = undefined,
+>(path: string, spec: ChannelBodyRouteSpec<TBody, TQuery>): ChannelRoute {
+  return route("PATCH", path, {
+    description: spec.description,
+    bodySchema: spec.bodySchema,
+    querySchema: spec.querySchema,
+    handler: spec.handler as ChannelRouteHandler,
+  });
+}
+
+/** DELETE — Zod schemas optional. */
+export function DELETE<
+  TBody extends ChannelRouteSchema | undefined = undefined,
+  TQuery extends ChannelRouteSchema | undefined = undefined,
+>(path: string, spec: ChannelDeleteRouteSpec<TBody, TQuery>): ChannelRoute {
+  return route("DELETE", path, {
+    description: spec.description,
+    bodySchema: spec.bodySchema,
+    querySchema: spec.querySchema,
+    handler: spec.handler,
+  });
+}
+
+// ============================================================================
+// Auth policies
+// ============================================================================
+
+/**
+ * Admit requests that arrive over the loopback interface with no proxy
+ * forwarding headers. The default route policy: local tooling works out of
+ * the box while remote (or reverse-proxied) callers are rejected until you
+ * wire real auth (e.g. {@link bearerAuth}).
+ *
+ * Requests carrying `X-Forwarded-For`, `X-Real-IP`, `Forwarded`, or
+ * `X-Forwarded-Host` are denied even when the TCP peer is 127.0.0.1 — that
+ * pattern is how tunnels and same-host reverse proxies re-expose loopback.
+ */
+export function localDev(): AuthPolicy {
+  return (request, info) => {
+    if (hasProxyForwardingHeaders(request)) {
+      return null;
+    }
+    if (info.requestIp !== null && isLoopbackAddress(info.requestIp)) {
+      return {
+        authenticator: "local-dev",
+        principalId: "local",
+        principalType: "user",
+      };
+    }
+    return null;
+  };
+}
+
+/**
+ * Like {@link localDev} but also requires the request URL hostname to be
+ * loopback. Rejects DNS-rebinding callers that reach 127.0.0.1 with a remote
+ * `Host` header (e.g. attacker.example after rebinding to localhost).
+ */
+export function localDevStrict(): AuthPolicy {
+  return (request, info) => {
+    if (localDev()(request, info) === null) {
+      return null;
+    }
+    let hostname: string;
+    try {
+      hostname = new URL(request.url).hostname;
+    } catch {
+      return null;
+    }
+    if (!isLoopbackHostname(hostname)) {
+      return null;
+    }
+    return {
+      authenticator: "local-dev-strict",
+      principalId: "local",
+      principalType: "user",
+    };
+  };
+}
+
+/**
+ * Admit requests whose TCP peer is loopback, ignoring `Host` and
+ * proxy-forwarding headers. The peer address (`req.socket.remoteAddress`) is
+ * the real boundary: a loopback-bound server only accepts local processes, and
+ * a LAN caller's peer IP is non-loopback and rejected. Unlike {@link localDev},
+ * this does not veto on `X-Forwarded-*` headers — so it admits loopback clients
+ * that legitimately relay them, e.g. `gh webhook forward`, which forwards
+ * GitHub's edge `X-Forwarded-For` / `X-Real-Ip`. Intended for dev-only relaxed
+ * auth where remote exposure is still refused.
+ */
+export function loopbackOnly(): AuthPolicy {
+  return (_request, info) => {
+    if (info.requestIp !== null && isLoopbackAddress(info.requestIp)) {
+      return {
+        authenticator: "loopback-only",
+        principalId: "local",
+        principalType: "user",
+      };
+    }
+    return null;
+  };
+}
+
+function hasGitHubWebhookDeliveryHeaders(request: Request): boolean {
+  const event = request.headers.get("x-github-event");
+  return event !== null && event.trim() !== "";
+}
+
+/**
+ * Dev-only GitHub channel auth without a webhook secret: loopback peer
+ * required. Plain local fixtures (no proxy headers) are admitted; deliveries
+ * relayed through `gh webhook forward` carry GitHub's `X-Forwarded-*` headers
+ * and are admitted only when `X-GitHub-Event` is present (GitHub deliveries
+ * always include it). Loopback tunnels that relay arbitrary remote traffic
+ * without those delivery headers stay rejected.
+ */
+export function loopbackGitHubDev(): AuthPolicy {
+  return (request, info) => {
+    if (info.requestIp === null || !isLoopbackAddress(info.requestIp)) {
+      return null;
+    }
+    if (
+      hasProxyForwardingHeaders(request) &&
+      !hasGitHubWebhookDeliveryHeaders(request)
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "loopback-github-dev",
+      principalId: "local",
+      principalType: "user",
+    };
+  };
+}
+
+function hasProxyForwardingHeaders(request: Request): boolean {
+  return (
+    request.headers.has("x-forwarded-for") ||
+    request.headers.has("x-forwarded-host") ||
+    request.headers.has("x-real-ip") ||
+    request.headers.has("forwarded")
+  );
+}
+
+/**
+ * Admit requests carrying `Authorization: Bearer <token>`. Pass the expected
+ * token (compared in constant time) or a verifier that maps a presented
+ * token to an {@link AuthContext}.
+ */
+export function bearerAuth(
+  tokenOrVerify:
+    | string
+    | ((token: string) => AuthContext | null | Promise<AuthContext | null>)
+): AuthPolicy {
+  return async (request) => {
+    const header = request.headers.get("authorization");
+    if (header === null || !header.toLowerCase().startsWith("bearer ")) {
+      return null;
+    }
+    const presented = header.slice("bearer ".length).trim();
+    if (typeof tokenOrVerify === "function") {
+      return await tokenOrVerify(presented);
+    }
+    if (tokenOrVerify !== "" && constantTimeEquals(presented, tokenOrVerify)) {
+      return {
+        authenticator: "bearer",
+        principalId: "bearer",
+        principalType: "service",
+      };
+    }
+    return null;
+  };
+}
+
+function constantTimeEquals(a: string, b: string): boolean {
+  const aBytes = Buffer.from(a);
+  const bBytes = Buffer.from(b);
+  if (aBytes.length !== bBytes.length) {
+    return false;
+  }
+  return timingSafeEqual(aBytes, bBytes);
+}
+
+/**
+ * Admit every request as an anonymous principal. Only for surfaces that are
+ * intentionally public or protected upstream.
+ */
+export function allowAll(): AuthPolicy {
+  return () => ({
+    authenticator: "allow-all",
+    principalId: "anonymous",
+    principalType: "user",
+  });
+}

package/src/connections.ts

@@ -0,0 +1,89 @@
+/**
+ * `defineConnection` — authored at `agent/mcp-connections/<name>.ts`.
+ *
+ * A connection gives tools from an external MCP server. The filename
+ * becomes the connection (server) name. Every connection is always
+ * available in three places:
+ * - the Cursor agent (local harness or cloud), via SDK `mcpServers`
+ * - the agent-serve host, via `ctx.host.mcp` on in-process tools
+ * - channel / schedule handlers, via `args.host.mcp`
+ *
+ * ```ts
+ * import { defineConnection } from "@anysphere/agent-serve/connections";
+ *
+ * export default defineConnection({
+ *   url: "https://mcp.linear.app/mcp",
+ *   headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
+ * });
+ * ```
+ *
+ * A **Cursor account MCP connection** exposes the MCP connectors the operator
+ * already authorized in their Cursor account (dashboard → MCP). Every tool
+ * executes **on the Cursor backend** with the account's stored OAuth
+ * credentials, so the agent gets Linear / Notion / Slack / … tools with
+ * zero token plumbing and no OAuth secrets on this host. Requires the host
+ * to be signed in (`agent-serve login` or `CURSOR_API_KEY`):
+ *
+ * ```ts
+ * // agent/mcp-connections/cursor.ts — every connected server
+ * export default defineConnection({ cursorAccount: true });
+ *
+ * // or restrict to specific connectors by name
+ * export default defineConnection({ cursorAccount: true, servers: ["Linear"] });
+ * ```
+ *
+ * A **peer MCP connection** addresses another agent mounted on the same serve
+ * host by slug — every mounted agent is itself an MCP server at
+ * `/<slug>/v1/mcp` (tools: `ask`, `check`, and `call_tool` when it has
+ * server tools), so the model can delegate work to the peer, which runs
+ * in its own sessions with its own tools and context:
+ *
+ * ```ts
+ * export default defineConnection({
+ *   agent: "weather-agent",
+ *   description: "Delegate weather questions to the weather agent.",
+ * });
+ * ```
+ *
+ * Peer URLs resolve when the server starts: loopback for local-runtime
+ * turns and host-side calls, the serve `--public-url` for cloud-runtime
+ * turns (a cloud VM cannot reach this host's loopback address).
+ *
+ * Server tools can call the same connection:
+ *
+ * ```ts
+ * async execute(input, ctx) {
+ *   return ctx.host.mcp.callTool("linear", "list_issues", { query: input.q });
+ * }
+ * ```
+ *
+ * So can webhook / channel route handlers (deterministic, no agent loop):
+ *
+ * ```ts
+ * POST("/sync", {
+ *   bodySchema: z.object({}),
+ *   handler: async (_req, { host }) => {
+ *     const result = await host.mcp.callTool("linear", "list_issues", {});
+ *     return Response.json(result);
+ *   },
+ * });
+ * ```
+ */
+
+import { brandDefinition } from "./internal/brand.js";
+import type { ConnectionConfig, ConnectionDefinition } from "./types.js";
+
+export type {
+  ConnectionConfig,
+  ConnectionDefinition,
+  ConnectionTransport,
+  HostMcpCallResult,
+  HostMcpRegistry,
+  HostMcpToolInfo,
+} from "./types.js";
+
+export function defineConnection(
+  config: ConnectionConfig
+): ConnectionDefinition {
+  return brandDefinition("connection", config);
+}