@cursor/july 0.1.1

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * @anysphere/agent-serve
+ *
+ * Filesystem-first framework for Cursor agents: define an agent as markdown
+ * and TypeScript files under an `agent/` directory, and serve it over
+ * channels with the Cursor SDK as the execution harness.
+ *
+ * ```ts
+ * import { serve } from "@anysphere/agent-serve";
+ *
+ * const handle = await serve(".", { port: 3000 });
+ * console.log(`agent listening on ${handle.url}`);
+ * ```
+ */
+
+import { registerAuthoredModuleLoaders } from "./internal/authored-loaders.js";
+import { brandDefinition } from "./internal/brand.js";
+import { setDevMode } from "./internal/dev-mode.js";
+import {
+  type LoadAgentProjectOptions,
+  resolveAgentMounts,
+} from "./internal/discovery.js";
+import { type AgentMount, startServer } from "./internal/server.js";
+import type {
+  AgentConfig,
+  AgentConfigDefinition,
+  AgentProject,
+  AgentServeHandle,
+  InstructionsConfig,
+  InstructionsDefinition,
+  ServeOptions,
+} from "./types.js";
+
+export { defineAB } from "./ab.js";
+// Authoring helpers (also available on their focused subpath exports).
+export {
+  allowAll,
+  bearerAuth,
+  DELETE,
+  defineChannel,
+  GET,
+  httpChannel,
+  localDev,
+  localDevStrict,
+  loopbackGitHubDev,
+  loopbackOnly,
+  PATCH,
+  POST,
+  PUT,
+} from "./channels.js";
+export { defineConnection } from "./connections.js";
+export { defineHook } from "./hooks.js";
+export type { LoadAgentProjectOptions } from "./internal/discovery.js";
+export {
+  formatDiagnostics,
+  hasErrorDiagnostics,
+  isAgentProjectDir,
+  loadAgentProject,
+  loadAgentProjects,
+  projectInfo,
+  resolveAgentMounts,
+} from "./internal/discovery.js";
+export type {
+  AgentServeGitHubTriggerEvent,
+  AgentServeGitHubTriggerTarget,
+  AgentServeTriggerEvent,
+  AgentServeTriggerResult,
+  AgentServeTriggerTargetResult,
+} from "./internal/handleAgentServeTrigger.js";
+export {
+  collectGitHubTriggerTargets,
+  handleAgentServeTrigger,
+} from "./internal/handleAgentServeTrigger.js";
+export {
+  MCP_CHANNEL_ID,
+  MCP_ENDPOINT_PATH,
+  mcpEndpointToolNames,
+} from "./internal/mcp-endpoint.js";
+export {
+  ReminderValidationError,
+  UnknownReminderError,
+} from "./internal/reminder-runner.js";
+export type { AgentMount } from "./internal/server.js";
+export {
+  SessionBusyError,
+  ToolInputError,
+  ToolNotDirectlyCallableError,
+  UnknownChannelError,
+  UnknownSessionError,
+  UnknownToolError,
+} from "./internal/session-engine.js";
+export type {
+  ReminderBusyPolicy,
+  ReminderCreateInput,
+  ReminderFireContext,
+  ReminderFireResult,
+  ReminderHostApi,
+  ReminderInfo,
+  ReminderReschedule,
+  ReminderScheduleKind,
+  ReminderStatus,
+  ReminderTarget,
+  ReminderUntilContext,
+} from "./reminders.js";
+export { defineSchedule } from "./schedules.js";
+export { defineSkill } from "./skills.js";
+export { defineTool } from "./tools.js";
+export type * from "./types.js";
+export {
+  DEFAULT_MODEL,
+  DIRECT_TOOL_CALL_CHANNEL_ID,
+  isCursorAccountTransport,
+  isPeerConnectionTransport,
+  isSymbolicConnectionTransport,
+} from "./types.js";
+
+/**
+ * Runtime config for an agent — authored at `agent/agent.ts` (the root
+ * agent) or `agent/subagents/<id>/agent.ts` (a subagent).
+ */
+export function defineAgent(config: AgentConfig): AgentConfigDefinition {
+  return brandDefinition("agent", config);
+}
+
+/**
+ * Programmatic instructions — authored at `agent/instructions.ts` when the
+ * system prompt needs to be generated rather than written as markdown.
+ */
+export function defineInstructions(
+  config: InstructionsConfig
+): InstructionsDefinition {
+  return brandDefinition("instructions", config);
+}
+
+/**
+ * Discover and serve one or more agents over HTTP.
+ *
+ * Defaults to multi-agent layout: each agent is mounted under `/<slug>/v1/*`
+ * and `/<slug>/playground`, with an index at `/`.
+ *
+ * - Given a directory that is itself an agent project, mounts it under its
+ *   directory name as the slug.
+ * - Given a directory whose immediate children are agent projects, mounts
+ *   each under its directory name.
+ * - Pass `mode: "single"` (or an {@link AgentProject}) for the unslugged
+ *   `/v1/*` surface.
+ *
+ * The built-in session channel lives under `/v1/session*`, custom channels
+ * under `/v1/channels/<id>`, plus `/v1/health` and `/v1/info`. Schedules run
+ * on their cron cadence unless dev mode or `schedules: false` disables them.
+ */
+export async function serve(
+  projectOrDir: string | AgentProject,
+  options: ServeOptions & {
+    discovery?: LoadAgentProjectOptions;
+    /**
+     * Mount layout. Defaults to `"multi"` (slugged routes + index).
+     * `"single"` serves one agent at `/v1/*` with an empty slug. Ignored when
+     * an {@link AgentProject} is passed (always single-mount).
+     */
+    mode?: "single" | "multi";
+  } = {}
+): Promise<AgentServeHandle> {
+  const { discovery, mode, ...serveOptions } = options;
+
+  // Programmatic embedders get the same authored-TypeScript loading as the
+  // CLI (idempotent; the bin registers earlier, source runs are a no-op).
+  await registerAuthoredModuleLoaders();
+
+  // Set before discovery so channel factories (constructed at import time) can
+  // relax dev-only defaults — e.g. the GitHub channel accepting unsigned
+  // loopback-forwarded deliveries. No-op outside dev.
+  setDevMode(serveOptions.dev === true);
+
+  if (typeof projectOrDir !== "string") {
+    return startServer([{ slug: "", project: projectOrDir }], serveOptions);
+  }
+
+  const mounts: AgentMount[] = await resolveAgentMounts(projectOrDir, {
+    ...discovery,
+    ...(mode === undefined ? {} : { mode }),
+  });
+  return startServer(mounts, serveOptions);
+}

package/src/internal/ab-collector.ts

@@ -0,0 +1,210 @@
+/**
+ * Stream-native collector for {@link defineAB} experiments.
+ *
+ * Pure fold over the session event log:
+ * - sticky arm = last `ab.assigned` for that experiment
+ * - metrics accumulate from the stream; `onSample` on turn complete/fail
+ *
+ * Enrollment is written by the engine at session creation (not here).
+ * In-memory state is a cache: on cold start (or after park eviction) the
+ * collector replays `events.ndjson` so counters survive restart.
+ *
+ * Hydration note: the engine appends before dispatch, so the first-touch
+ * replay already includes the current event — after rebuild we return
+ * without folding it again (and without re-firing `onSample`).
+ */
+
+import {
+  type ABDefinition,
+  type ABSamplePersistence,
+  type ABSampleReason,
+  cloneABMetrics,
+} from "../ab.js";
+import type { DiscoveredAB, SessionEvent, SessionInfo } from "../types.js";
+import {
+  applyDeriveForEvent,
+  emptyFoldedABSession,
+  ensureArmAccum,
+  type FoldedABSession,
+  foldABEvent,
+} from "./ab-fold.js";
+import { describeError } from "./describe-error.js";
+
+export type { DiscoveredAB };
+
+export interface ABCollectorOptions {
+  projectRoot: string;
+  persistSamples?: ABSamplePersistence;
+}
+
+/** Drop cache after these — next event rehydrates from the durable log. */
+const EVICT_ON: ReadonlySet<SessionEvent["type"]> = new Set([
+  "session.waiting",
+  "session.completed",
+  "session.failed",
+]);
+
+export class ABCollector {
+  private readonly state = new Map<string, FoldedABSession>();
+  private readonly hydrated = new Set<string>();
+  private readonly projectRoot: string | undefined;
+  private readonly persistSamples: ABSamplePersistence | undefined;
+
+  constructor(
+    private readonly experiments: readonly DiscoveredAB[],
+    private readonly logger: (line: string) => void,
+    private readonly loadEvents: (sessionId: string) => Promise<SessionEvent[]>,
+    options?: ABCollectorOptions
+  ) {
+    this.projectRoot = options?.projectRoot;
+    this.persistSamples = options?.persistSamples;
+  }
+
+  get enabled(): boolean {
+    return this.experiments.length > 0;
+  }
+
+  /**
+   * Fold one live event. On first touch (or after eviction), replays the
+   * durable log first so enrollment + metrics match disk.
+   */
+  async onEvent(
+    event: SessionEvent,
+    sessionInfo: SessionInfo,
+    agentName: string
+  ): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    if (!this.hydrated.has(event.sessionId)) {
+      const history = await this.loadEvents(event.sessionId);
+      // Rebuild arms + metrics only — do not re-fire onSample for past turns.
+      // History already includes `event` (append-before-dispatch).
+      for (const past of history) {
+        await this.fold(past, sessionInfo, agentName, { emitSamples: false });
+      }
+      this.hydrated.add(event.sessionId);
+      if (EVICT_ON.has(event.type)) {
+        this.drop(event.sessionId);
+      }
+      return;
+    }
+
+    await this.fold(event, sessionInfo, agentName, { emitSamples: true });
+    if (EVICT_ON.has(event.type)) {
+      this.drop(event.sessionId);
+    }
+  }
+
+  private drop(sessionId: string): void {
+    this.state.delete(sessionId);
+    this.hydrated.delete(sessionId);
+  }
+
+  private async fold(
+    event: SessionEvent,
+    sessionInfo: SessionInfo,
+    agentName: string,
+    options: { emitSamples: boolean }
+  ): Promise<void> {
+    const session = this.sessionAccum(event.sessionId);
+
+    if (event.type === "ab.assigned") {
+      foldABEvent(session, event);
+      return;
+    }
+
+    if (session.arms.size === 0) {
+      return;
+    }
+
+    // Built-ins for every enrolled arm (shared fold).
+    foldABEvent(session, event);
+
+    for (const experiment of this.experiments) {
+      const variant = session.arms.get(experiment.name);
+      if (variant === undefined || variant === null) {
+        continue;
+      }
+      const def = experiment.definition as ABDefinition;
+      const accum = ensureArmAccum(session, experiment.name, variant);
+
+      if (def.derive !== undefined) {
+        await applyDeriveForEvent(
+          accum.metrics.custom,
+          def.derive,
+          event,
+          {
+            agent: { name: agentName },
+            channel: { id: sessionInfo.channelId },
+            session: sessionInfo,
+            experiment: experiment.name,
+            variant,
+          },
+          (key, error) => {
+            this.logger(
+              `[agent-serve] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`
+            );
+          }
+        );
+      }
+
+      if (!options.emitSamples) {
+        continue;
+      }
+      const reason = sampleReason(event);
+      if (reason !== undefined) {
+        const sample = {
+          experiment: experiment.name,
+          variant,
+          ...(def.variants[variant]?.label !== undefined
+            ? { variantLabel: def.variants[variant].label }
+            : {}),
+          sessionId: event.sessionId,
+          channelId: sessionInfo.channelId,
+          metrics: cloneABMetrics(accum.metrics),
+          reason,
+          at: event.at,
+        };
+        try {
+          await def.onSample(sample);
+        } catch (error) {
+          this.logger(
+            `[agent-serve] ab "${experiment.name}" onSample threw: ${describeError(error)}`
+          );
+        }
+        if (
+          this.persistSamples !== undefined &&
+          this.projectRoot !== undefined
+        ) {
+          try {
+            await this.persistSamples.save(sample, {
+              projectRoot: this.projectRoot,
+            });
+          } catch (error) {
+            this.logger(
+              `[agent-serve] ab persistSamples.save threw: ${describeError(error)}`
+            );
+          }
+        }
+      }
+    }
+  }
+
+  private sessionAccum(sessionId: string): FoldedABSession {
+    let session = this.state.get(sessionId);
+    if (session === undefined) {
+      session = emptyFoldedABSession();
+      this.state.set(sessionId, session);
+    }
+    return session;
+  }
+}
+
+function sampleReason(event: SessionEvent): ABSampleReason | undefined {
+  if (event.type === "turn.completed" || event.type === "turn.failed") {
+    return event.type;
+  }
+  return undefined;
+}

package/src/internal/ab-fold.ts

@@ -0,0 +1,228 @@
+/**
+ * Pure fold of a session event stream into A/B arms + cumulative metrics.
+ * Shared by {@link ABCollector} (live) and {@link buildABSnapshot} (read API).
+ */
+
+import {
+  type ABCollectContext,
+  type ABDefinition,
+  type ABMetrics,
+  cloneABMetrics,
+  emptyABMetrics,
+} from "../ab.js";
+import type { DiscoveredAB, SessionEvent, SessionInfo } from "../types.js";
+import { describeError } from "./describe-error.js";
+
+export interface ABArmAccum {
+  variant: string;
+  metrics: ABMetrics;
+  turnStartedAt: string | null;
+}
+
+export interface FoldedABSession {
+  /** experiment → variant key, or `null` for sticky skip */
+  arms: Map<string, string | null>;
+  /** experiment → metrics (only for enrolled arms) */
+  metrics: Map<string, ABArmAccum>;
+}
+
+export function emptyFoldedABSession(): FoldedABSession {
+  return { arms: new Map(), metrics: new Map() };
+}
+
+/** Ensure a metrics bucket exists for an enrolled arm. */
+export function ensureArmAccum(
+  state: FoldedABSession,
+  experiment: string,
+  variant: string
+): ABArmAccum {
+  let accum = state.metrics.get(experiment);
+  if (accum === undefined) {
+    accum = {
+      variant,
+      metrics: emptyABMetrics(),
+      turnStartedAt: null,
+    };
+    state.metrics.set(experiment, accum);
+  }
+  return accum;
+}
+
+/** Fold one event's built-in metrics + assignment. Does not run `derive`. */
+export function foldABEvent(state: FoldedABSession, event: SessionEvent): void {
+  if (event.type === "ab.assigned") {
+    const { experiment, variant } = event.data;
+    state.arms.set(experiment, variant);
+    if (variant === null) {
+      state.metrics.delete(experiment);
+    } else {
+      state.metrics.set(experiment, {
+        variant,
+        metrics: emptyABMetrics(),
+        turnStartedAt: null,
+      });
+    }
+    return;
+  }
+
+  if (state.arms.size === 0) {
+    return;
+  }
+
+  for (const [experiment, variant] of state.arms) {
+    if (variant === null) {
+      continue;
+    }
+    applyBuiltinMetrics(ensureArmAccum(state, experiment, variant), event);
+  }
+}
+
+export function foldABStream(events: readonly SessionEvent[]): FoldedABSession {
+  const state = emptyFoldedABSession();
+  for (const event of events) {
+    foldABEvent(state, event);
+  }
+  return state;
+}
+
+/**
+ * Apply `derive` extractors for one event into `custom` counters.
+ * Errors are reported via `onError` and skipped.
+ */
+export async function applyDeriveForEvent(
+  custom: Record<string, number>,
+  derive: NonNullable<ABDefinition["derive"]>,
+  event: SessionEvent,
+  collectCtx: ABCollectContext,
+  onError: (key: string, error: unknown) => void
+): Promise<void> {
+  for (const [key, extract] of Object.entries(derive)) {
+    try {
+      const delta = await extract(event, collectCtx);
+      if (typeof delta === "number" && Number.isFinite(delta)) {
+        custom[key] = (custom[key] ?? 0) + delta;
+      }
+    } catch (error) {
+      onError(key, error);
+    }
+  }
+}
+
+function collectContext(
+  experiment: string,
+  variant: string,
+  sessionInfo: SessionInfo,
+  agentName: string
+): ABCollectContext {
+  return {
+    agent: { name: agentName },
+    channel: { id: sessionInfo.channelId },
+    session: sessionInfo,
+    experiment,
+    variant,
+  };
+}
+
+/**
+ * Re-run `derive` extractors over the stream for enrolled arms.
+ * Mutates `state.metrics` in place. Errors are logged and skipped.
+ */
+export async function applyABDerive(
+  state: FoldedABSession,
+  events: readonly SessionEvent[],
+  experiments: readonly DiscoveredAB[],
+  sessionInfo: SessionInfo,
+  agentName: string,
+  logger: (line: string) => void
+): Promise<void> {
+  for (const experiment of experiments) {
+    const variant = state.arms.get(experiment.name);
+    if (variant === undefined || variant === null) {
+      continue;
+    }
+    const def = experiment.definition as ABDefinition;
+    if (def.derive === undefined) {
+      continue;
+    }
+    const accum = ensureArmAccum(state, experiment.name, variant);
+    // Reset custom so a re-fold is idempotent.
+    accum.metrics.custom = {};
+    const ctx = collectContext(
+      experiment.name,
+      variant,
+      sessionInfo,
+      agentName
+    );
+    for (const event of events) {
+      await applyDeriveForEvent(
+        accum.metrics.custom,
+        def.derive,
+        event,
+        ctx,
+        (key, error) => {
+          logger(
+            `[agent-serve] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`
+          );
+        }
+      );
+    }
+  }
+}
+
+export function applyBuiltinMetrics(
+  accum: ABArmAccum,
+  event: SessionEvent
+): void {
+  const m = accum.metrics;
+  switch (event.type) {
+    case "turn.started":
+      accum.turnStartedAt = event.at;
+      break;
+    case "turn.completed": {
+      m.turns += 1;
+      const usage = event.data.usage;
+      if (usage !== undefined) {
+        m.inputTokens += usage.inputTokens;
+        m.outputTokens += usage.outputTokens;
+        m.cacheReadTokens += usage.cacheReadTokens;
+        m.cacheWriteTokens += usage.cacheWriteTokens;
+      }
+      addWallTime(accum, event.at);
+      break;
+    }
+    case "turn.failed":
+      m.turns += 1;
+      m.turnFailures += 1;
+      addWallTime(accum, event.at);
+      break;
+    case "action.result":
+      m.toolCalls += 1;
+      if (event.data.isError) {
+        m.toolErrors += 1;
+      }
+      break;
+    default:
+      break;
+  }
+}
+
+function addWallTime(accum: ABArmAccum, endedAt: string): void {
+  if (accum.turnStartedAt === null) {
+    return;
+  }
+  const start = Date.parse(accum.turnStartedAt);
+  const end = Date.parse(endedAt);
+  accum.turnStartedAt = null;
+  if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+    accum.metrics.wallTimeMs += end - start;
+  }
+}
+
+export function cloneFoldedMetrics(
+  accum: ABArmAccum | undefined
+): ABMetrics | undefined {
+  if (accum === undefined) {
+    return undefined;
+  }
+  return cloneABMetrics(accum.metrics);
+}