@cursor/july 0.1.1

package/dist/internal/trajectory.js

@@ -0,0 +1,248 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { readFile } from "node:fs/promises";
+/**
+ * Collapse a session event list into a trajectory. Streaming deltas are
+ * folded into final assistant / reasoning text per turn.
+ */
+export function buildTrajectory(events) {
+    var _a;
+    let sessionId = "";
+    let sdkAgentId;
+    let agentUrl;
+    let channelId;
+    const turnsById = new Map();
+    const turnOrder = [];
+    const pendingCalls = new Map();
+    const ensureTurn = (turnId) => {
+        const existing = turnsById.get(turnId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const turn = {
+            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 = Object.assign({ 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(Object.assign(Object.assign({ 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 Object.assign(Object.assign(Object.assign(Object.assign({ sessionId }, (sdkAgentId === undefined ? {} : { sdkAgentId })), (agentUrl === undefined ? {} : { agentUrl })), (channelId === undefined ? {} : { channelId })), { ok: turnsFailed === 0 && turns.length > 0, finalText: (_a = lastGood === null || lastGood === void 0 ? void 0 : lastGood.assistantText) !== null && _a !== void 0 ? _a : "", turnsFailed,
+        toolCallCount,
+        turns });
+}
+/** Parse an `events.ndjson` file (or any NDJSON blob of SessionEvents). */
+export function parseEventsNdjson(text) {
+    const events = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        try {
+            events.push(JSON.parse(trimmed));
+        }
+        catch (_a) {
+            // skip malformed lines
+        }
+    }
+    return events;
+}
+/** Load and summarize a durable session event log. */
+export function loadTrajectoryFromEventsFile(path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const text = yield readFile(path, "utf8");
+        return buildTrajectory(parseEventsNdjson(text));
+    });
+}
+/** Human-readable one-line-per-turn dump (for non-JSON CLI output). */
+export function formatTrajectoryText(trajectory) {
+    const lines = [];
+    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) {
+    if (value === undefined || value === null) {
+        return "(no output)";
+    }
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function formatArgs(args) {
+    if (args === undefined || args === null) {
+        return "";
+    }
+    const text = typeof args === "string" ? args : JSON.stringify(args);
+    return text === "{}" ? "" : `(${truncate(text, 80)})`;
+}
+function truncate(text, max) {
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}

package/dist/internal/workspace.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type { DiscoveredSkill, DiscoveredTool, ResolvedAgent } from "../types.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 declare function agentToolScriptPath(toolName: string): string;
+/**
+ * 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 declare function buildAgentToolsCatalog(tools: DiscoveredTool[], options?: {
+    includeScripts: boolean;
+}): string;
+export declare function materializeWorkspace(options: MaterializeWorkspaceOptions): Promise<void>;
+/**
+ * Generate the SKILL.md the harness reads: `name` + `description`
+ * frontmatter (any authored frontmatter was already stripped at discovery)
+ * followed by the skill body.
+ */
+export declare function buildSkillMd(skill: DiscoveredSkill): string;
+/**
+ * Write relative path → contents under `workspaceDir`, refusing paths that
+ * escape the directory.
+ */
+export declare function writeWorkspaceFiles(workspaceDir: string, files: Record<string, string>): Promise<void>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/internal/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAmCf;AAmDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/internal/workspace.js

@@ -0,0 +1,199 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+/** Relative path of an agent-side tool script inside the session workspace. */
+export function agentToolScriptPath(toolName) {
+    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, options = { includeScripts: false }) {
+    const agentTools = tools.filter((tool) => tool.execution === "agent");
+    if (agentTools.length === 0) {
+        return "";
+    }
+    const parts = [
+        "## 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 function materializeWorkspace(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
+        const { agent, workspaceDir, seed } = options;
+        yield mkdir(workspaceDir, { recursive: true });
+        const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
+            includeScripts: false,
+        });
+        const agentsMd = [(_b = (_a = agent.instructions) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "", agentToolsSection]
+            .filter((part) => part !== "")
+            .join("\n\n");
+        if (agentsMd !== "") {
+            yield writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
+        }
+        for (const tool of agent.tools) {
+            if (tool.execution !== "agent" || tool.script === undefined) {
+                continue;
+            }
+            yield materializeAgentTool(workspaceDir, tool);
+        }
+        for (const skill of agent.skills) {
+            yield materializeSkill(workspaceDir, skill);
+        }
+        if (seed) {
+            for (const seedFile of agent.seedFiles) {
+                const target = resolveInside(workspaceDir, seedFile.relativePath);
+                if (yield exists(target)) {
+                    continue;
+                }
+                yield mkdir(dirname(target), { recursive: true });
+                yield copyFile(seedFile.sourcePath, target);
+            }
+        }
+    });
+}
+function materializeAgentTool(workspaceDir, tool) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (tool.script === undefined) {
+            return;
+        }
+        const relativePath = agentToolScriptPath(tool.name);
+        const target = resolveInside(workspaceDir, relativePath);
+        yield mkdir(dirname(target), { recursive: true });
+        yield writeFile(target, `${normalizeScriptBody(tool.script)}\n`, "utf8");
+        try {
+            yield chmod(target, 0o755);
+        }
+        catch (_a) {
+            // Best-effort on platforms that ignore mode bits.
+        }
+    });
+}
+function materializeSkill(workspaceDir, skill) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const skillDir = join(workspaceDir, ".cursor", "skills", skill.name);
+        yield mkdir(skillDir, { recursive: true });
+        yield writeFile(join(skillDir, "SKILL.md"), buildSkillMd(skill), "utf8");
+        for (const [relativePath, source] of Object.entries(skill.files)) {
+            const target = resolveInside(skillDir, relativePath);
+            yield mkdir(dirname(target), { recursive: true });
+            if ("contents" in source) {
+                yield writeFile(target, source.contents, "utf8");
+            }
+            else {
+                yield 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) {
+    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) {
+    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 function writeWorkspaceFiles(workspaceDir, files) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const [relativePath, contents] of Object.entries(files)) {
+            const target = resolveInside(workspaceDir, relativePath);
+            yield mkdir(dirname(target), { recursive: true });
+            yield writeFile(target, contents, "utf8");
+        }
+    });
+}
+function resolveInside(baseDir, relativePath) {
+    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;
+}
+function exists(path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield stat(path);
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}