@cursor/july 0.1.1

package/src/internal/trajectory.ts

@@ -0,0 +1,306 @@
+/**
+ * Compact, agent-friendly views of a session's NDJSON event stream.
+ *
+ * Coding agents (and eval harnesses) want a stable JSON shape: user
+ * messages, assistant text, tool calls with args/results, and
+ * success/failure — not a firehose of streaming deltas.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { SessionEvent, TurnUsage } from "../types.js";
+
+export interface TrajectoryToolCall {
+  callId: string;
+  toolName: string;
+  args?: unknown;
+  output?: unknown;
+  isError: boolean;
+  /** Present when the tool required human approval before execute. */
+  approvalDecision?: "approve" | "deny";
+}
+
+export interface TrajectoryTurn {
+  turnId: string;
+  userMessage?: string;
+  assistantText: string;
+  reasoningText?: string;
+  toolCalls: TrajectoryToolCall[];
+  subagents: Array<{ callId: string; name?: string; description?: string }>;
+  usage?: TurnUsage;
+  result?: string;
+  failed: boolean;
+  error?: string;
+}
+
+export interface Trajectory {
+  sessionId: string;
+  sdkAgentId?: string;
+  agentUrl?: string;
+  channelId?: string;
+  ok: boolean;
+  finalText: string;
+  turnsFailed: number;
+  toolCallCount: number;
+  turns: TrajectoryTurn[];
+}
+
+/**
+ * Collapse a session event list into a trajectory. Streaming deltas are
+ * folded into final assistant / reasoning text per turn.
+ */
+export function buildTrajectory(events: SessionEvent[]): Trajectory {
+  let sessionId = "";
+  let sdkAgentId: string | undefined;
+  let agentUrl: string | undefined;
+  let channelId: string | undefined;
+  const turnsById = new Map<string, TrajectoryTurn>();
+  const turnOrder: string[] = [];
+  const pendingCalls = new Map<string, TrajectoryToolCall>();
+
+  const ensureTurn = (turnId: string): TrajectoryTurn => {
+    const existing = turnsById.get(turnId);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const turn: TrajectoryTurn = {
+      turnId,
+      assistantText: "",
+      toolCalls: [],
+      subagents: [],
+      failed: false,
+    };
+    turnsById.set(turnId, turn);
+    turnOrder.push(turnId);
+    return turn;
+  };
+
+  for (const event of events) {
+    if (sessionId === "" && typeof event.sessionId === "string") {
+      sessionId = event.sessionId;
+    }
+    switch (event.type) {
+      case "session.started": {
+        channelId = event.data.channelId;
+        break;
+      }
+      case "agent.bound": {
+        sdkAgentId = event.data.sdkAgentId;
+        agentUrl = event.data.url;
+        break;
+      }
+      case "message.received": {
+        if (event.turnId !== undefined) {
+          ensureTurn(event.turnId).userMessage = event.data.text;
+        }
+        break;
+      }
+      case "message.completed": {
+        if (event.turnId !== undefined && event.data.text !== "") {
+          ensureTurn(event.turnId).assistantText = event.data.text;
+        }
+        break;
+      }
+      case "reasoning.appended": {
+        if (event.turnId !== undefined) {
+          ensureTurn(event.turnId).reasoningText = event.data.text;
+        }
+        break;
+      }
+      case "actions.requested": {
+        if (event.turnId === undefined) {
+          break;
+        }
+        const turn = ensureTurn(event.turnId);
+        for (const call of event.data.calls) {
+          const entry: TrajectoryToolCall = {
+            callId: call.callId,
+            toolName: call.toolName,
+            isError: false,
+            ...(call.args === undefined ? {} : { args: call.args }),
+          };
+          pendingCalls.set(call.callId, entry);
+          turn.toolCalls.push(entry);
+        }
+        break;
+      }
+      case "action.approval_requested": {
+        // Traceability only — the call is already listed under actions.requested.
+        break;
+      }
+      case "action.approval_resolved": {
+        const pending = pendingCalls.get(event.data.callId);
+        if (pending !== undefined) {
+          pending.approvalDecision = event.data.decision;
+        }
+        break;
+      }
+      case "action.result": {
+        const pending = pendingCalls.get(event.data.callId);
+        if (pending !== undefined) {
+          pending.output = event.data.output;
+          pending.isError = event.data.isError;
+          pending.toolName = event.data.toolName;
+        } else if (event.turnId !== undefined) {
+          ensureTurn(event.turnId).toolCalls.push({
+            callId: event.data.callId,
+            toolName: event.data.toolName,
+            output: event.data.output,
+            isError: event.data.isError,
+          });
+        }
+        break;
+      }
+      case "subagent.called": {
+        if (event.turnId !== undefined) {
+          ensureTurn(event.turnId).subagents.push({
+            callId: event.data.callId,
+            ...(event.data.name === undefined ? {} : { name: event.data.name }),
+            ...(event.data.description === undefined
+              ? {}
+              : { description: event.data.description }),
+          });
+        }
+        break;
+      }
+      case "turn.completed": {
+        if (event.turnId === undefined) {
+          break;
+        }
+        const turn = ensureTurn(event.turnId);
+        turn.failed = false;
+        if (event.data.usage !== undefined) {
+          turn.usage = event.data.usage;
+        }
+        if (event.data.result !== undefined) {
+          turn.result = event.data.result;
+          if (turn.assistantText === "") {
+            turn.assistantText = event.data.result;
+          }
+        }
+        break;
+      }
+      case "turn.failed": {
+        if (event.turnId !== undefined) {
+          const turn = ensureTurn(event.turnId);
+          turn.failed = true;
+          turn.error = event.data.message;
+        }
+        break;
+      }
+      case "session.failed": {
+        if (event.turnId !== undefined) {
+          const turn = ensureTurn(event.turnId);
+          turn.failed = true;
+          turn.error = event.data.message;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const turns = turnOrder.map((id) => turnsById.get(id)!);
+  const turnsFailed = turns.filter((t) => t.failed).length;
+  const toolCallCount = turns.reduce((n, t) => n + t.toolCalls.length, 0);
+  const lastGood = [...turns].reverse().find((t) => t.assistantText !== "");
+  return {
+    sessionId,
+    ...(sdkAgentId === undefined ? {} : { sdkAgentId }),
+    ...(agentUrl === undefined ? {} : { agentUrl }),
+    ...(channelId === undefined ? {} : { channelId }),
+    ok: turnsFailed === 0 && turns.length > 0,
+    finalText: lastGood?.assistantText ?? "",
+    turnsFailed,
+    toolCallCount,
+    turns,
+  };
+}
+
+/** Parse an `events.ndjson` file (or any NDJSON blob of SessionEvents). */
+export function parseEventsNdjson(text: string): SessionEvent[] {
+  const events: SessionEvent[] = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") {
+      continue;
+    }
+    try {
+      events.push(JSON.parse(trimmed) as SessionEvent);
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return events;
+}
+
+/** Load and summarize a durable session event log. */
+export async function loadTrajectoryFromEventsFile(
+  path: string
+): Promise<Trajectory> {
+  const text = await readFile(path, "utf8");
+  return buildTrajectory(parseEventsNdjson(text));
+}
+
+/** Human-readable one-line-per-turn dump (for non-JSON CLI output). */
+export function formatTrajectoryText(trajectory: Trajectory): string {
+  const lines: string[] = [];
+  lines.push(
+    `session ${trajectory.sessionId || "(unknown)"}  ok=${trajectory.ok}`
+  );
+  if (trajectory.sdkAgentId !== undefined) {
+    lines.push(`sdkAgentId: ${trajectory.sdkAgentId}`);
+  }
+  if (trajectory.agentUrl !== undefined) {
+    lines.push(`url: ${trajectory.agentUrl}`);
+  }
+  lines.push(
+    `turns: ${trajectory.turns.length}  tools=${trajectory.toolCallCount}  failed: ${trajectory.turnsFailed}`
+  );
+  for (const turn of trajectory.turns) {
+    lines.push("");
+    lines.push(`── ${turn.turnId}${turn.failed ? " FAILED" : ""} ──`);
+    if (turn.userMessage !== undefined) {
+      lines.push(`  user: ${truncate(turn.userMessage, 200)}`);
+    }
+    for (const call of turn.toolCalls) {
+      const mark = call.isError ? "✗" : "→";
+      lines.push(`  ${mark} ${call.toolName}${formatArgs(call.args)}`);
+      if (call.output !== undefined) {
+        lines.push(`    ${truncate(stringify(call.output), 160)}`);
+      }
+    }
+    if (turn.assistantText.length > 0) {
+      lines.push(`  agent: ${truncate(turn.assistantText, 400)}`);
+    }
+    if (turn.error !== undefined) {
+      lines.push(`  error: ${turn.error}`);
+    }
+    if (turn.usage !== undefined) {
+      lines.push(
+        `  usage: in ${turn.usage.inputTokens} out ${turn.usage.outputTokens}`
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function stringify(value: unknown): string {
+  if (value === undefined || value === null) {
+    return "(no output)";
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+function formatArgs(args: unknown): string {
+  if (args === undefined || args === null) {
+    return "";
+  }
+  const text = typeof args === "string" ? args : JSON.stringify(args);
+  return text === "{}" ? "" : `(${truncate(text, 80)})`;
+}
+
+function truncate(text: string, max: number): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}

package/src/internal/workspace.ts

@@ -0,0 +1,223 @@
+/**
+ * Session workspace materialization. Each session gets its own working
+ * directory that the Cursor harness treats as the project: instructions land
+ * in `AGENTS.md`, skills land in `.cursor/skills/<name>/SKILL.md`,
+ * agent-side tools land in `.agent-serve/tools/<name>.sh`, and
+ * `agent/sandbox/workspace/**` seed files are mirrored in. The harness picks
+ * all of this up natively through its project setting source.
+ */
+
+import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import type {
+  DiscoveredSkill,
+  DiscoveredTool,
+  ResolvedAgent,
+} from "../types.js";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+
+export interface MaterializeWorkspaceOptions {
+  agent: ResolvedAgent;
+  workspaceDir: string;
+  /**
+   * When true (first turn), seed files are copied in. Instructions and
+   * skills are always rewritten so authored edits show up on the next turn.
+   */
+  seed: boolean;
+}
+
+/** Relative path of an agent-side tool script inside the session workspace. */
+export function agentToolScriptPath(toolName: string): string {
+  return `.agent-serve/tools/${toolName}.sh`;
+}
+
+/**
+ * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
+ *
+ * @param includeScripts — when true, embed full script bodies (cloud first prompt).
+ *   Local workspaces omit bodies because the files already exist on disk.
+ */
+export function buildAgentToolsCatalog(
+  tools: DiscoveredTool[],
+  options: { includeScripts: boolean } = { includeScripts: false }
+): string {
+  const agentTools = tools.filter((tool) => tool.execution === "agent");
+  if (agentTools.length === 0) {
+    return "";
+  }
+
+  const parts: string[] = [
+    "## Agent tools",
+    "",
+    "These tools run in the agent environment (not on the agent-serve host).",
+    "Pass a JSON object on stdin matching the input schema; read the result from stdout.",
+    "",
+  ];
+
+  for (const tool of agentTools) {
+    const rel = agentToolScriptPath(tool.name);
+    parts.push(`### \`${tool.name}\``);
+    parts.push("");
+    parts.push(tool.description.trim());
+    parts.push("");
+    parts.push(`Path: \`${rel}\``);
+    parts.push("");
+    parts.push("Input schema:");
+    parts.push("");
+    parts.push("```json");
+    parts.push(JSON.stringify(tool.inputSchema, null, 2));
+    parts.push("```");
+    parts.push("");
+    parts.push("Invoke:");
+    parts.push("");
+    parts.push("```bash");
+    parts.push(`printf '%s' '{"key":"value"}' | bash ${rel}`);
+    parts.push("```");
+    parts.push("");
+    if (options.includeScripts && tool.script !== undefined) {
+      parts.push("Script body (write to the path above if missing):");
+      parts.push("");
+      parts.push("```bash");
+      parts.push(normalizeScriptBody(tool.script));
+      parts.push("```");
+      parts.push("");
+    }
+  }
+
+  return `${parts.join("\n").trimEnd()}\n`;
+}
+
+export async function materializeWorkspace(
+  options: MaterializeWorkspaceOptions
+): Promise<void> {
+  const { agent, workspaceDir, seed } = options;
+  await mkdir(workspaceDir, { recursive: true });
+
+  const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
+    includeScripts: false,
+  });
+  const agentsMd = [agent.instructions?.trim() ?? "", agentToolsSection]
+    .filter((part) => part !== "")
+    .join("\n\n");
+  if (agentsMd !== "") {
+    await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
+  }
+
+  for (const tool of agent.tools) {
+    if (tool.execution !== "agent" || tool.script === undefined) {
+      continue;
+    }
+    await materializeAgentTool(workspaceDir, tool);
+  }
+
+  for (const skill of agent.skills) {
+    await materializeSkill(workspaceDir, skill);
+  }
+
+  if (seed) {
+    for (const seedFile of agent.seedFiles) {
+      const target = resolveInside(workspaceDir, seedFile.relativePath);
+      if (await exists(target)) {
+        continue;
+      }
+      await mkdir(dirname(target), { recursive: true });
+      await copyFile(seedFile.sourcePath, target);
+    }
+  }
+}
+
+async function materializeAgentTool(
+  workspaceDir: string,
+  tool: DiscoveredTool
+): Promise<void> {
+  if (tool.script === undefined) {
+    return;
+  }
+  const relativePath = agentToolScriptPath(tool.name);
+  const target = resolveInside(workspaceDir, relativePath);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, `${normalizeScriptBody(tool.script)}\n`, "utf8");
+  try {
+    await chmod(target, 0o755);
+  } catch {
+    // Best-effort on platforms that ignore mode bits.
+  }
+}
+
+async function materializeSkill(
+  workspaceDir: string,
+  skill: DiscoveredSkill
+): Promise<void> {
+  const skillDir = join(workspaceDir, ".cursor", "skills", skill.name);
+  await mkdir(skillDir, { recursive: true });
+  await writeFile(join(skillDir, "SKILL.md"), buildSkillMd(skill), "utf8");
+
+  for (const [relativePath, source] of Object.entries(skill.files)) {
+    const target = resolveInside(skillDir, relativePath);
+    await mkdir(dirname(target), { recursive: true });
+    if ("contents" in source) {
+      await writeFile(target, source.contents, "utf8");
+    } else {
+      await copyFile(source.sourcePath, target);
+    }
+  }
+}
+
+/**
+ * Ensure the script has a shebang. Catalog fences stay tidy without a
+ * trailing blank line inside the fence.
+ */
+function normalizeScriptBody(script: string): string {
+  const trimmed = script.replace(/\r\n/g, "\n").trimEnd();
+  if (trimmed.startsWith("#!")) {
+    return trimmed;
+  }
+  return `#!/usr/bin/env bash\n${trimmed}`;
+}
+
+/**
+ * Generate the SKILL.md the harness reads: `name` + `description`
+ * frontmatter (any authored frontmatter was already stripped at discovery)
+ * followed by the skill body.
+ */
+export function buildSkillMd(skill: DiscoveredSkill): string {
+  const { body } = parseFrontmatter(skill.markdown);
+  const frontmatter = serializeFrontmatter({
+    name: skill.name,
+    description: skill.description,
+  });
+  return `${frontmatter}\n${body.trim()}\n`;
+}
+
+/**
+ * Write relative path → contents under `workspaceDir`, refusing paths that
+ * escape the directory.
+ */
+export async function writeWorkspaceFiles(
+  workspaceDir: string,
+  files: Record<string, string>
+): Promise<void> {
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const target = resolveInside(workspaceDir, relativePath);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, contents, "utf8");
+  }
+}
+
+function resolveInside(baseDir: string, relativePath: string): string {
+  const target = resolve(baseDir, relativePath);
+  const rel = relative(baseDir, target);
+  if (rel.startsWith("..") || rel === "" || relativePath.includes("\0")) {
+    throw new Error(`Refusing to write outside the workspace: ${relativePath}`);
+  }
+  return target;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/reminders.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime reminders — per-session durable wakes.
+ *
+ * ```ts
+ * import type { ReminderCreateInput } from "@anysphere/agent-serve/reminders";
+ *
+ * // Recurring ≈ setInterval; one-shot ≈ setTimeout.
+ * await host.reminders?.create({
+ *   purpose: "ci_recheck",
+ *   channelId: session.channelId,
+ *   continuationToken: session.continuationKey!,
+ *   delay: "2h",
+ *   prompt: "Re-check CI. Only act if still failing.",
+ * });
+ * ```
+ *
+ * Distinct from `defineSchedule` (deploy-time global cron under
+ * `agent/schedules/`). Reminders are created at runtime and bound to a
+ * channel continuation. Prefer `run` + function `until` for host policy
+ * (silent ticks); agents use prompt-form create via tools.
+ */
+
+export type {
+  ReminderBusyPolicy,
+  ReminderCreateInput,
+  ReminderFireContext,
+  ReminderFireResult,
+  ReminderHostApi,
+  ReminderInfo,
+  ReminderReschedule,
+  ReminderScheduleKind,
+  ReminderStatus,
+  ReminderTarget,
+  ReminderUntilContext,
+} from "./types.js";

package/src/schedules.ts

@@ -0,0 +1,37 @@
+/**
+ * `defineSchedule` — authored at `agent/schedules/<name>.ts`.
+ *
+ * A schedule starts the agent on a cron cadence instead of waiting for an
+ * inbound message. The markdown form is fire-and-forget task mode; the
+ * handler form hands work off to a channel (and can call MCP via `args.host.mcp`):
+ *
+ * ```ts
+ * import { defineSchedule } from "@anysphere/agent-serve/schedules";
+ *
+ * export default defineSchedule({
+ *   cron: "0 9 * * 1-5",
+ *   markdown: "Summarize open incidents and post to the metrics endpoint.",
+ * });
+ * ```
+ *
+ * The same fire-and-forget form can be written as a plain markdown file with
+ * `cron:` frontmatter (`agent/schedules/<name>.md`).
+ */
+
+import { brandDefinition } from "./internal/brand.js";
+import type { ScheduleConfig, ScheduleDefinition } from "./types.js";
+
+export type {
+  ScheduleConfig,
+  ScheduleDefinition,
+  ScheduleHandlerArgs,
+} from "./types.js";
+
+export function defineSchedule(config: ScheduleConfig): ScheduleDefinition {
+  if ((config.markdown === undefined) === (config.run === undefined)) {
+    throw new Error(
+      "defineSchedule requires exactly one of `markdown` or `run`"
+    );
+  }
+  return brandDefinition("schedule", config);
+}

package/src/skills.ts

@@ -0,0 +1,27 @@
+/**
+ * `defineSkill` — authored at `agent/skills/<name>.ts`.
+ *
+ * Most skills are plain markdown files (`agent/skills/<name>.md`) or packaged
+ * directories (`agent/skills/<name>/SKILL.md` plus sibling files). Reach for
+ * `defineSkill` when markdown can't express what you need, such as generated
+ * content or inline sibling files:
+ *
+ * ```ts
+ * import { defineSkill } from "@anysphere/agent-serve/skills";
+ *
+ * export default defineSkill({
+ *   description: "Research unfamiliar topics before answering.",
+ *   markdown: "Gather evidence first, then answer with the key facts.",
+ *   files: { "references/checklist.md": "# Checklist\n\n- Find sources.\n" },
+ * });
+ * ```
+ */
+
+import { brandDefinition } from "./internal/brand.js";
+import type { SkillConfig, SkillDefinition } from "./types.js";
+
+export type { SkillConfig, SkillDefinition } from "./types.js";
+
+export function defineSkill(config: SkillConfig): SkillDefinition {
+  return brandDefinition("skill", config);
+}