@cursor/july 0.1.1

package/src/internal/router.ts

@@ -0,0 +1,145 @@
+/**
+ * Tiny path router: literal segments, `:param` captures, and a trailing
+ * `*param` catch-all, compiled once at server startup.
+ */
+
+import type { AuthContext, AuthPolicy, RouteMethod } from "../types.js";
+
+export interface ServerRouteContext {
+  params: Record<string, string>;
+  requestIp: string | null;
+  /** Resolved by the route's auth chain ("none" routes see null). */
+  auth: AuthContext | null;
+}
+
+export type ServerRouteHandler = (
+  request: Request,
+  ctx: ServerRouteContext
+) => Response | Promise<Response>;
+
+export interface ServerRoute {
+  method: RouteMethod;
+  /** Path pattern, e.g. `/v1/session/:sessionId/stream`. */
+  pattern: string;
+  /** Auth chain for the route; "none" mounts the route unauthenticated. */
+  auth: AuthPolicy[] | "none";
+  handler: ServerRouteHandler;
+}
+
+type Segment =
+  | { kind: "literal"; value: string }
+  | { kind: "param"; name: string }
+  /** Trailing catch-all (`*name`): matches zero or more remaining segments. */
+  | { kind: "rest"; name: string };
+
+interface CompiledRoute {
+  route: ServerRoute;
+  segments: Segment[];
+}
+
+export interface RouteMatch {
+  route: ServerRoute;
+  params: Record<string, string>;
+}
+
+export class Router {
+  private readonly routes: CompiledRoute[] = [];
+
+  add(route: ServerRoute): void {
+    this.routes.push({ route, segments: compilePattern(route.pattern) });
+  }
+
+  match(method: string, pathname: string): RouteMatch | undefined {
+    const direct = this.matchExact(method, pathname);
+    if (direct !== undefined) {
+      return direct;
+    }
+    // HTTP: HEAD may be served by the corresponding GET handler (wget --spider,
+    // some load-balancer probes). Without this, GET-only routes return 405.
+    if (method === "HEAD") {
+      return this.matchExact("GET", pathname);
+    }
+    return undefined;
+  }
+
+  private matchExact(method: string, pathname: string): RouteMatch | undefined {
+    const pathSegments = splitPath(pathname);
+    for (const { route, segments } of this.routes) {
+      if (route.method !== method) {
+        continue;
+      }
+      const params = matchSegments(segments, pathSegments);
+      if (params !== undefined) {
+        return { route, params };
+      }
+    }
+    return undefined;
+  }
+
+  /** True when the path matches some route with a different method. */
+  hasPath(pathname: string): boolean {
+    const pathSegments = splitPath(pathname);
+    return this.routes.some(
+      ({ segments }) => matchSegments(segments, pathSegments) !== undefined
+    );
+  }
+}
+
+function compilePattern(pattern: string): Segment[] {
+  const segments: Segment[] = splitPath(pattern).map((part) =>
+    part.startsWith(":")
+      ? { kind: "param", name: part.slice(1) }
+      : part.startsWith("*")
+        ? { kind: "rest", name: part.slice(1) }
+        : { kind: "literal", value: part }
+  );
+  const restIndex = segments.findIndex((segment) => segment.kind === "rest");
+  if (restIndex !== -1 && restIndex !== segments.length - 1) {
+    throw new Error(
+      `Route pattern "${pattern}" may only use a catch-all (*name) as the last segment.`
+    );
+  }
+  return segments;
+}
+
+function splitPath(path: string): string[] {
+  return path.split("/").filter((part) => part !== "");
+}
+
+function matchSegments(
+  segments: Segment[],
+  pathSegments: string[]
+): Record<string, string> | undefined {
+  const last = segments[segments.length - 1];
+  const hasRest = last !== undefined && last.kind === "rest";
+  if (hasRest) {
+    if (pathSegments.length < segments.length - 1) {
+      return undefined;
+    }
+  } else if (segments.length !== pathSegments.length) {
+    return undefined;
+  }
+  const params: Record<string, string> = {};
+  const fixedCount = hasRest ? segments.length - 1 : segments.length;
+  for (let i = 0; i < fixedCount; i++) {
+    const segment = segments[i];
+    const value = pathSegments[i];
+    if (segment === undefined || value === undefined) {
+      return undefined;
+    }
+    if (segment.kind === "literal") {
+      if (segment.value !== value) {
+        return undefined;
+      }
+    } else if (segment.kind === "param") {
+      params[segment.name] = decodeURIComponent(value);
+    }
+  }
+  if (hasRest) {
+    params[last.name] = pathSegments
+      .slice(fixedCount)
+      .map((value) => decodeURIComponent(value))
+      .join("/");
+  }
+  return params;
+}

package/src/internal/run-client.ts

@@ -0,0 +1,320 @@
+/**
+ * Programmatic HTTP client for agent-serve sessions.
+ *
+ * Used by `agent-serve run` and `chat --json`: create/follow a
+ * session, collect the NDJSON stream until the turn parks, and return a
+ * compact {@link Trajectory} plus the continuation token for follow-ups.
+ */
+
+import type { SessionEvent, SessionPurpose } from "../types.js";
+import { buildTrajectory, type Trajectory } from "./trajectory.js";
+
+/** Thrown when a turn stream exceeds `timeoutMs`; carries the session id. */
+export class RunSessionTimeoutError extends Error {
+  constructor(
+    message: string,
+    readonly sessionId: string
+  ) {
+    super(message);
+    this.name = "RunSessionTimeoutError";
+  }
+}
+export interface RunClientOptions {
+  baseUrl: string;
+  bearerToken?: string;
+  /** Abort a hung turn. */
+  timeoutMs?: number;
+  /** Called for each stream event as it arrives (for CLI progress). */
+  onEvent?: (event: SessionEvent) => void;
+  /**
+   * Create-time session purpose. Pass `"eval"` from the eval harness so
+   * live `defineAB` enrollment is skipped. Default `"live"`.
+   */
+  purpose?: SessionPurpose;
+}
+
+export interface RunSessionResult {
+  sessionId: string;
+  continuationToken?: string;
+  baseUrl: string;
+  events: SessionEvent[];
+  trajectory: Trajectory;
+  ok: boolean;
+}
+
+const TERMINAL_TYPES = new Set([
+  "session.waiting",
+  "session.completed",
+  "session.failed",
+]);
+
+/**
+ * Run one or more messages against a live agent-serve base URL
+ * (e.g. `http://127.0.0.1:3000/weather-agent`).
+ */
+export async function runSession(
+  options: RunClientOptions & {
+    messages: string[];
+    sessionId?: string;
+    continuationToken?: string;
+    /** Applied only when creating a new session (first message). */
+    workspaceDir?: string;
+    /** Applied only when creating a new session (first message). */
+    workspaceFiles?: Record<string, string>;
+  }
+): Promise<RunSessionResult> {
+  if (options.messages.length === 0) {
+    throw new Error("runSession requires at least one message");
+  }
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  let sessionId = options.sessionId;
+  let continuationToken = options.continuationToken;
+  const allEvents: SessionEvent[] = [];
+  let nextEventIndex = 0;
+
+  for (const message of options.messages) {
+    const turn = await runOneTurn({
+      baseUrl,
+      message,
+      sessionId,
+      continuationToken,
+      startIndex: sessionId === undefined ? 0 : nextEventIndex,
+      bearerToken: options.bearerToken,
+      timeoutMs: options.timeoutMs,
+      onEvent: options.onEvent,
+      ...(sessionId === undefined && options.purpose !== undefined
+        ? { purpose: options.purpose }
+        : {}),
+      ...(sessionId === undefined && options.workspaceDir !== undefined
+        ? { workspaceDir: options.workspaceDir }
+        : {}),
+      ...(sessionId === undefined && options.workspaceFiles !== undefined
+        ? { workspaceFiles: options.workspaceFiles }
+        : {}),
+    });
+    sessionId = turn.sessionId;
+    continuationToken = turn.continuationToken;
+    allEvents.push(...turn.events);
+    if (turn.events.length > 0) {
+      const last = turn.events[turn.events.length - 1]!;
+      nextEventIndex = last.index + 1;
+    }
+    if (!turn.ok) {
+      break;
+    }
+  }
+
+  if (sessionId === undefined) {
+    throw new Error("server did not return a session id");
+  }
+
+  const trajectory = buildTrajectory(allEvents);
+  return {
+    sessionId,
+    ...(continuationToken === undefined ? {} : { continuationToken }),
+    baseUrl,
+    events: allEvents,
+    trajectory,
+    ok: trajectory.ok,
+  };
+}
+
+interface OneTurnArgs {
+  baseUrl: string;
+  message: string;
+  sessionId?: string;
+  continuationToken?: string;
+  purpose?: SessionPurpose;
+  workspaceDir?: string;
+  workspaceFiles?: Record<string, string>;
+  startIndex: number;
+  bearerToken?: string;
+  timeoutMs?: number;
+  onEvent?: (event: SessionEvent) => void;
+}
+
+interface OneTurnResult {
+  sessionId: string;
+  continuationToken?: string;
+  events: SessionEvent[];
+  ok: boolean;
+}
+
+async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
+  let sessionId = args.sessionId;
+  let continuationToken = args.continuationToken;
+
+  if (sessionId === undefined) {
+    const created = await postJson(
+      args.baseUrl,
+      "/v1/session",
+      {
+        message: args.message,
+        ...(args.purpose === undefined ? {} : { purpose: args.purpose }),
+        ...(args.workspaceDir === undefined
+          ? {}
+          : { workspaceDir: args.workspaceDir }),
+        ...(args.workspaceFiles === undefined
+          ? {}
+          : { workspaceFiles: args.workspaceFiles }),
+      },
+      args.bearerToken
+    );
+    if (created.status >= 400 || created.body.ok === false) {
+      throw new Error(
+        `POST /v1/session failed: ${str(created.body.error) ?? created.status} ${str(created.body.message) ?? ""}`.trim()
+      );
+    }
+    sessionId = str(created.body.sessionId);
+    continuationToken = str(created.body.continuationToken);
+  } else {
+    const resp = await postJson(
+      args.baseUrl,
+      `/v1/session/${sessionId}`,
+      { message: args.message, continuationToken },
+      args.bearerToken
+    );
+    if (resp.status >= 400 || resp.body.ok === false) {
+      throw new Error(
+        `follow-up failed: ${str(resp.body.error) ?? resp.status}: ${str(resp.body.message) ?? ""}`.trim()
+      );
+    }
+    continuationToken = str(resp.body.continuationToken) ?? continuationToken;
+  }
+
+  if (sessionId === undefined) {
+    throw new Error("server did not return a session id");
+  }
+
+  const events = await collectStream({
+    baseUrl: args.baseUrl,
+    sessionId,
+    startIndex: args.startIndex,
+    bearerToken: args.bearerToken,
+    timeoutMs: args.timeoutMs,
+    onEvent: args.onEvent,
+  });
+
+  const turnFailed = events.some((e) => e.type === "turn.failed");
+  const sessionFailed = events.some((e) => e.type === "session.failed");
+  return {
+    sessionId,
+    ...(continuationToken === undefined ? {} : { continuationToken }),
+    events,
+    ok: !turnFailed && !sessionFailed,
+  };
+}
+
+async function collectStream(args: {
+  baseUrl: string;
+  sessionId: string;
+  startIndex: number;
+  bearerToken?: string;
+  timeoutMs?: number;
+  onEvent?: (event: SessionEvent) => void;
+}): Promise<SessionEvent[]> {
+  const controller = new AbortController();
+  const timer =
+    args.timeoutMs === undefined
+      ? undefined
+      : setTimeout(() => controller.abort(), args.timeoutMs);
+
+  try {
+    const resp = await fetch(
+      `${args.baseUrl}/v1/session/${args.sessionId}/stream?startIndex=${args.startIndex}`,
+      {
+        headers: authHeaders(args.bearerToken),
+        signal: controller.signal,
+      }
+    );
+    if (!resp.ok || resp.body === null) {
+      throw new Error(`stream failed (${resp.status})`);
+    }
+
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const events: SessionEvent[] = [];
+
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) {
+        break;
+      }
+      buffer += decoder.decode(chunk.value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      let stop = false;
+      for (const line of lines) {
+        if (line.trim() === "") {
+          continue;
+        }
+        let event: SessionEvent;
+        try {
+          event = JSON.parse(line) as SessionEvent;
+        } catch {
+          continue;
+        }
+        events.push(event);
+        args.onEvent?.(event);
+        if (TERMINAL_TYPES.has(event.type)) {
+          stop = true;
+          break;
+        }
+      }
+      if (stop) {
+        break;
+      }
+    }
+    await reader.cancel().catch(() => {});
+    return events;
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new RunSessionTimeoutError(
+        `turn timed out after ${args.timeoutMs ?? "?"}ms (session ${args.sessionId})`,
+        args.sessionId
+      );
+    }
+    throw error;
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function authHeaders(bearerToken: string | undefined): Record<string, string> {
+  return bearerToken === undefined
+    ? {}
+    : { authorization: `Bearer ${bearerToken}` };
+}
+
+async function postJson(
+  baseUrl: string,
+  path: string,
+  body: unknown,
+  bearerToken?: string
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const resp = await fetch(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...authHeaders(bearerToken),
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await resp.text();
+  let parsed: Record<string, unknown> = {};
+  if (text) {
+    try {
+      parsed = JSON.parse(text) as Record<string, unknown>;
+    } catch {
+      parsed = { message: text };
+    }
+  }
+  return { status: resp.status, body: parsed };
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}

package/src/internal/schedule-runner.ts

@@ -0,0 +1,161 @@
+/**
+ * Cron dispatch for `agent/schedules/`. In production mode a minute-aligned
+ * ticker fires matching schedules (UTC evaluation); in dev mode nothing
+ * fires automatically and `POST /v1/dev/schedules/:scheduleId` dispatches a
+ * schedule by hand, exactly once, through the same path.
+ */
+
+import type {
+  AgentProject,
+  AuthContext,
+  ChannelSession,
+  ReceiveInput,
+} from "../types.js";
+import { type CronExpression, parseCron } from "./cron.js";
+import {
+  SCHEDULE_CHANNEL_PREFIX,
+  type SessionEngine,
+} from "./session-engine.js";
+
+export const APP_AUTH: AuthContext = {
+  authenticator: "app",
+  principalId: "agent-serve:app",
+  principalType: "runtime",
+};
+
+export class UnknownScheduleError extends Error {
+  constructor(
+    scheduleId: string,
+    readonly availableScheduleIds: string[]
+  ) {
+    super(`Unknown schedule "${scheduleId}"`);
+    this.name = "UnknownScheduleError";
+  }
+}
+
+interface PreparedSchedule {
+  name: string;
+  cron: CronExpression;
+  discovered: AgentProject["schedules"][number];
+}
+
+export class ScheduleRunner {
+  private readonly schedules: PreparedSchedule[];
+  private timer: NodeJS.Timeout | undefined;
+  private lastFiredMinute = -1;
+
+  constructor(
+    private readonly engine: SessionEngine,
+    project: AgentProject,
+    private readonly logger: (line: string) => void = () => {}
+  ) {
+    this.schedules = project.schedules.map((schedule) => ({
+      name: schedule.name,
+      cron: parseCron(schedule.cron),
+      discovered: schedule,
+    }));
+  }
+
+  get scheduleIds(): string[] {
+    return this.schedules.map((schedule) => schedule.name);
+  }
+
+  start(): void {
+    if (this.timer !== undefined || this.schedules.length === 0) {
+      return;
+    }
+    this.arm();
+  }
+
+  stop(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private arm(): void {
+    const now = Date.now();
+    const nextMinute = (Math.floor(now / 60_000) + 1) * 60_000;
+    this.timer = setTimeout(() => this.tick(), nextMinute - now + 250);
+    this.timer.unref?.();
+  }
+
+  private tick(): void {
+    const now = new Date();
+    const minute = Math.floor(now.getTime() / 60_000);
+    if (minute !== this.lastFiredMinute) {
+      this.lastFiredMinute = minute;
+      for (const schedule of this.schedules) {
+        if (schedule.cron.matches(now)) {
+          void this.dispatch(schedule.name).catch((error) => {
+            this.logger(
+              `[agent-serve] schedule "${schedule.name}" dispatch failed: ${
+                error instanceof Error ? error.message : String(error)
+              }`
+            );
+          });
+        }
+      }
+    }
+    this.arm();
+  }
+
+  /** Fire a schedule by name, exactly once. Returns the started sessions. */
+  async dispatch(scheduleId: string): Promise<{ sessionIds: string[] }> {
+    const schedule = this.schedules.find((s) => s.name === scheduleId);
+    if (schedule === undefined) {
+      throw new UnknownScheduleError(scheduleId, this.scheduleIds);
+    }
+    const definition = schedule.discovered.definition;
+    const channelId = `${SCHEDULE_CHANNEL_PREFIX}${schedule.name}`;
+
+    if (definition.markdown !== undefined) {
+      const { sessionId, done } = await this.engine.runTask({
+        channelId,
+        prompt: definition.markdown,
+        auth: APP_AUTH,
+        title: `Schedule ${schedule.name}`,
+      });
+      this.engine.trackBackground(done);
+      return { sessionIds: [sessionId] };
+    }
+
+    if (definition.run === undefined) {
+      throw new Error(`Schedule "${scheduleId}" has no markdown or run form`);
+    }
+
+    const sessionIds: string[] = [];
+    const receivePromises: Array<Promise<unknown>> = [];
+    const receive = (
+      channel: Parameters<SessionEngine["receive"]>[0],
+      input: ReceiveInput
+    ): Promise<ChannelSession> => {
+      const promise = this.engine.receive(channel, input).then((session) => {
+        sessionIds.push(session.id);
+        return session;
+      });
+      receivePromises.push(promise.catch(() => {}));
+      return promise;
+    };
+
+    await definition.run({
+      receive,
+      callTool: (toolName, input, callOptions) =>
+        this.engine.callTool(toolName, input, {
+          auth: APP_AUTH,
+          ...callOptions,
+        }),
+      waitUntil: (promise) => {
+        this.engine.trackBackground(promise);
+      },
+      appAuth: APP_AUTH,
+      host: this.engine.host,
+    });
+    // Collect ids from receive() calls the handler chose not to await
+    // (commonly wrapped in waitUntil); receive resolves at message accept,
+    // not turn completion, so this settles fast.
+    await Promise.allSettled(receivePromises);
+    return { sessionIds };
+  }
+}