Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli): HF_TOOL_CONTEXT artifact events and project lock for agent harnesses (#5520)
Xuanru Li1b60a40eff54
diff --git a/docs/developers/harness-tool-context.mdx b/docs/developers/harness-tool-context.mdxnew file mode 100644index 0000000000..8107d29a91--- /dev/null+++ b/docs/developers/harness-tool-context.mdx@@ -0,0 +1,90 @@+---+title: "Running the CLI from an agent harness"+description: "How an agent harness declares what it supports through HF_TOOL_CONTEXT, and what the CLI reports back."+---++An agent harness (Claude Code, Codex, your own) runs `hyperframes` commands on the agent's behalf.+`HF_TOOL_CONTEXT` lets the harness tell one invocation what it supports, so the CLI can do more for+it: report the images it produced, or wait its turn instead of racing another command in the same+project. Without the variable, every command behaves exactly as it does in a terminal.++```bash+export HF_TOOL_CONTEXT='{"version":1,"capabilities":{+ "events": {"transport": {"type": "ndjson-file", "path": "/tmp/call-42/events.ndjson"}},+ "project-lock": {"waitMs": 90000}+}}'+npx hyperframes snapshot --at 1,3+```++The harness sets the variable for one tool call, reads what the call produced, and removes its files.++## The declaration++| Field | Value |+| --- | --- |+| `version` | `1`. Any other version, or a value that is not JSON, is treated as no declaration. |+| `capabilities` | An object keyed by capability name. Each value configures that capability. |++The CLI ignores capability names it does not know, and a known capability whose value is invalid, so+a harness can declare capabilities newer than the CLI it runs. The variable carries data only: no+capability runs code the harness names.++## `events`: what a command produced++```json+{ "transport": { "type": "ndjson-file", "path": "/absolute/events.ndjson" } }+```++The CLI appends one JSON object per line to `path`. It never creates the parent directory, and a+write that fails prints a warning without failing the command. Read the file after the command+exits; several commands in one shell call append to the same file.++Each line is an event:++```json+{+ "version": 1,+ "type": "artifact.created",+ "command": "snapshot",+ "artifact": { "role": "contact-sheet", "path": "/project/snapshots/contact-sheet.jpg", "mediaType": "image/jpeg" }+}+```++| Command | `role` | What it is |+| --- | --- | --- |+| `snapshot` | `frame` | Each captured frame (PNG) |+| `snapshot` | `contact-sheet` | Each page of the grid of frames made for review (JPEG) |+| `check` | `frame` | Each frame the browser check captured |+| `check` | `finding` | Each crop around a finding |++Paths are absolute and stay where the command saved them. What to do with an artifact is the+harness's decision: attach the contact sheet to the tool result, or ignore it.+Ignore event types and roles you do not know; new ones are added without a version change.++## `project-lock`: one browser command at a time++```json+{ "waitMs": 90000 }+```++`check` and `snapshot` take a lock on the project before they start a browser, and release it when+they finish. A second command waits up to `waitMs` milliseconds for the lock, then fails, naming the+command and process that hold it. A lock whose process has exited is taken over. A+`project.lock.break` left by a killed process is not: the timeout names that file and its process+id, and says to delete it to continue. The lock is the file `.hyperframes/project.lock`.++Choose `waitMs` below your tool call's own timeout, so a wait ends in the CLI's message rather than+the harness killing the call.++## Hooks that run code++Running your own command before or after a CLI command is not a `HF_TOOL_CONTEXT` capability and+never will be: anything that sets an environment variable could then run code. Such hooks, when they+exist, come only from configuration the person controls.++## Conformance++`packages/cli/src/utils/toolContext.test.ts` and `projectLock.test.ts` pin the parsing, event and+lock behavior above. A harness is correct when it sets the variable for each call it wants the+behavior on, reads `events` only after the call exits, and works the same when the CLI ignores a+capability.diff --git a/docs/docs.json b/docs/docs.jsonindex 85b47012ff..72a6dc8b80 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -960,6 +960,7 @@"developers/cli","packages/cli","developers/catalog-search",+ "developers/harness-tool-context","packages/lint"]},diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.tsindex 902e269292..9f29272905 100644--- a/packages/cli/src/commands/check.test.ts+++ b/packages/cli/src/commands/check.test.ts@@ -1,5 +1,7 @@import { runCommand } from "citty";-import { readFileSync } from "node:fs";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";import { afterEach, describe, expect, it, vi } from "vitest";const trackCheckReport = vi.fn();@@ -530,6 +532,34 @@ it("threads --no-proxy into the browser check options", async () => {expect(runPipeline).toHaveBeenCalledWith(PROJECT, expect.objectContaining({ autoProxy: false }));});+it("waits for the project lock declared in HF_TOOL_CONTEXT before running the pipeline", async () => {+ const dir = mkdtempSync(join(tmpdir(), "hf-check-lock-"));+ const lock = join(dir, ".hyperframes", "project.lock");+ mkdirSync(join(dir, ".hyperframes"));+ writeFileSync(lock, JSON.stringify({ pid: process.pid, command: "snapshot", startedAt: 1 }));+ vi.stubEnv(+ "HF_TOOL_CONTEXT",+ JSON.stringify({ version: 1, capabilities: { "project-lock": { waitMs: 0 } } }),+ );+ const { report } = await runScenario(fakeDriver());+ const runPipeline = vi.fn(async () => report);+ const log = vi.spyOn(console, "log").mockImplementation(() => undefined);+ const command = createCheckCommand({+ resolveProject: () => ({ ...PROJECT, dir }),+ runPipeline,+ withMeta: (value) => value,+ });+ try {+ await runCommand(command, { rawArgs: ["--json"] });+ expect(runPipeline).not.toHaveBeenCalled();+ expect(consumeCommandResult().exitCode).toBe(1);+ expect(String(log.mock.calls[0]?.[0])).toContain("hyperframes snapshot");+ } finally {+ vi.unstubAllEnvs();+ rmSync(dir, { recursive: true, force: true });+ }+});+it("rejects malformed caption-zone specs instead of silently disabling the gate", async () => {const { report } = await runScenario(fakeDriver());const runPipeline = vi.fn(async () => report);diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.tsindex 01a8204254..7257fd762a 100644--- a/packages/cli/src/commands/check.ts+++ b/packages/cli/src/commands/check.ts@@ -1,4 +1,7 @@+import { resolve } from "node:path";import { formatFindingTimes } from "../utils/checkFindings.js";+import { withProjectLock } from "../utils/projectLock.js";+import { reportArtifacts } from "../utils/toolContext.js";import { defineCommand, parseArgs } from "citty";import type { ArgsDef } from "citty";import type { Example } from "./_examples.js";@@ -37,7 +40,13 @@ export interface CheckCommandDependencies {const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = {resolveProject,- runPipeline: runCheckPipeline,+ async runPipeline(project, options) {+ const report = await runCheckPipeline(project, options);+ const images = (files: readonly string[]) => files.map((file) => resolve(project.dir, file));+ reportArtifacts("check", "frame", images(report.snapshots.files));+ reportArtifacts("check", "finding", images(report.snapshots.findingFiles));+ return report;+ },withMeta,};@@ -158,7 +167,9 @@ export function createCheckCommand(if (!asJson) {console.log(`${c.accent("◆")} Checking ${c.accent(project.name)}`);}- const report = await dependencies.runPipeline(project, options);+ const report = await withProjectLock(project.dir, "check", () =>+ dependencies.runPipeline(project, options),+ );if (asJson) {console.log(JSON.stringify(dependencies.withMeta(report), null, 2));} else {diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.tsindex 9d50c8ae0a..ad6d75093b 100644--- a/packages/cli/src/commands/snapshot.ts+++ b/packages/cli/src/commands/snapshot.ts@@ -1,3 +1,5 @@+import { reportArtifacts } from "../utils/toolContext.js";+import { withProjectLock } from "../utils/projectLock.js";import {parseSnapshotRange,sampleSnapshotRange,@@ -1010,152 +1012,167 @@ export default defineCommand({const snapshotDir = args.output? resolve(String(args.output)): join(project.dir, "snapshots");- const paths = await captureSnapshots(project.dir, {- frames,- range,- composition,- timeout,- at: atTimestamps,- outputDir: snapshotDir,- angle: camera,- includeEnd: args.end !== false,- zoom: zoomTarget,- zoomScale,- autoProxy: args.proxy as boolean | undefined,- browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"] as boolean | undefined),- against,- });-- if (paths.length === 0) {- console.log(- `\n${c.error("✗")} Could not determine composition duration — no frames captured`,+ await withProjectLock(project.dir, "snapshot", async () => {+ const paths = await captureSnapshots(project.dir, {+ frames,+ range,+ composition,+ timeout,+ at: atTimestamps,+ outputDir: snapshotDir,+ angle: camera,+ includeEnd: args.end !== false,+ zoom: zoomTarget,+ zoomScale,+ autoProxy: args.proxy as boolean | undefined,+ browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"] as boolean | undefined),+ against,+ });+ reportArtifacts(+ "snapshot",+ "frame",+ paths.map((path) => resolve(project.dir, path)),);- failCommand();- }- console.log(- `\n${c.success("◇")} ${paths.length} snapshots saved to ${args.output ? snapshotDir : "snapshots/"}`,- );- for (const p of paths) {- console.log(` ${p}`);- }- if (against) {- console.log(- ` ${c.dim("ref-*.png + pair-*.jpg")} beside each frame (reference frame, render | reference sheet)`,- );- }+ if (paths.length === 0) {+ console.log(+ `\n${c.error("✗")} Could not determine composition duration — no frames captured`,+ );+ failCommand();+ }- // Generate contact sheet for quick AI review- try {- const { createSnapshotContactSheet } = await import("../capture/contactSheet.js");- const sheets = await createSnapshotContactSheet(- snapshotDir,- join(snapshotDir, "contact-sheet.jpg"),+ console.log(+ `\n${c.success("◇")} ${paths.length} snapshots saved to ${args.output ? snapshotDir : "snapshots/"}`,);- for (const sheet of sheets) {- console.log(` ${resolve(sheet)} (grid view for AI review)`);+ for (const p of paths) {+ console.log(` ${p}`);+ }+ if (against) {+ console.log(+ ` ${c.dim("ref-*.png + pair-*.jpg")} beside each frame (reference frame, render | reference sheet)`,+ );}- } catch (err) {- console.warn(- ` ${c.warn("⚠")} Contact sheet skipped: ${normalizeErrorMessage(err)}. Individual snapshot PNGs are still available.`,- );- }- // Gemini vision descriptions. Runs by default — see describeArg- // resolution above. `null` means the user explicitly opted out with- // `--describe false`; missing GEMINI_API_KEY logs a skip and continues.- if (describeArg !== null) {+ // Generate contact sheet for quick AI reviewtry {- const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;- if (!geminiKey) {- if (args.describe !== undefined)- console.log(` ${c.dim("--describe: GEMINI_API_KEY not set, skipping")}`);- } else if (paths.length > 0) {- console.log(` ${c.dim("Describing frames with Gemini vision...")}`);- const { GoogleGenAI } = await loadOptionalPackage("@google/genai", "--describe");- const ai = new GoogleGenAI({ apiKey: geminiKey });- const model = process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview";- const customQuestion =- describeArg === "true"- ? "Describe this video composition frame in 1-2 sentences. Be specific and factual: what elements are visible, what text appears, is the frame blank/black/loading, what is the composition. Flag any obvious problems."- : describeArg;+ const { createSnapshotContactSheet } = await import("../capture/contactSheet.js");+ const sheets = await createSnapshotContactSheet(+ snapshotDir,+ join(snapshotDir, "contact-sheet.jpg"),+ );+ reportArtifacts("snapshot", "contact-sheet", sheets);+ for (const sheet of sheets) {+ console.log(` ${resolve(sheet)} (grid view for AI review)`);+ }+ } catch (err) {+ console.warn(+ ` ${c.warn("⚠")} Contact sheet skipped: ${normalizeErrorMessage(err)}. Individual snapshot PNGs are still available.`,+ );+ }- const descriptions: string[] = [- `# Snapshot Frame Descriptions`,- ``,- `**Question asked:** ${customQuestion}`,- ``,- `Compare each description against your storyboard spec. A "black frame" or "loading screen" for a content beat is a bug.`,- ``,- ];+ // Gemini vision descriptions. Runs by default — see describeArg+ // resolution above. `null` means the user explicitly opted out with+ // `--describe false`; missing GEMINI_API_KEY logs a skip and continues.+ if (describeArg !== null) {+ try {+ const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;+ if (!geminiKey) {+ if (args.describe !== undefined)+ console.log(` ${c.dim("--describe: GEMINI_API_KEY not set, skipping")}`);+ } else if (paths.length > 0) {+ console.log(` ${c.dim("Describing frames with Gemini vision...")}`);+ const { GoogleGenAI } = await loadOptionalPackage("@google/genai", "--describe");+ const ai = new GoogleGenAI({ apiKey: geminiKey });+ const model = process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview";+ const customQuestion =+ describeArg === "true"+ ? "Describe this video composition frame in 1-2 sentences. Be specific and factual: what elements are visible, what text appears, is the frame blank/black/loading, what is the composition. Flag any obvious problems."+ : describeArg;- // Scale down PNGs before sending to stay under Gemini's 4 MB inline- // limit. Full 1920×1080 PNGs are typically 3-6 MB. Use sharp if- // available; otherwise skip files over the limit.- type SharpFn = (buf: Buffer) => {- resize: (w: number) => { jpeg: () => { toBuffer: () => Promise<Buffer> } };- };- let sharpFn: SharpFn | null = null;- try {- const s = await import("sharp");- sharpFn = (s.default ?? s) as unknown as SharpFn;- } catch {- /* sharp not installed — fall back to size check */- }+ const descriptions: string[] = [+ `# Snapshot Frame Descriptions`,+ ``,+ `**Question asked:** ${customQuestion}`,+ ``,+ `Compare each description against your storyboard spec. A "black frame" or "loading screen" for a content beat is a bug.`,+ ``,+ ];++ // Scale down PNGs before sending to stay under Gemini's 4 MB inline+ // limit. Full 1920×1080 PNGs are typically 3-6 MB. Use sharp if+ // available; otherwise skip files over the limit.+ type SharpFn = (buf: Buffer) => {+ resize: (w: number) => { jpeg: () => { toBuffer: () => Promise<Buffer> } };+ };+ let sharpFn: SharpFn | null = null;+ try {+ const s = await import("sharp");+ sharpFn = (s.default ?? s) as unknown as SharpFn;+ } catch {+ /* sharp not installed — fall back to size check */+ }++ const results = await Promise.allSettled(+ paths.map(async (p) => {+ const filename = basename(p);+ const filePath = join(snapshotDir, filename);+ if (!existsSync(filePath)) return { filename, desc: "file not found" };+ const raw = readFileSync(filePath);+ let imageData: Buffer;+ let mimeType = "image/png";+ if (sharpFn) {+ imageData = await sharpFn(raw).resize(960).jpeg().toBuffer();+ mimeType = "image/jpeg";+ } else {+ if (raw.length > 3_800_000)+ return {+ filename,+ desc: "file too large for Gemini — install sharp to enable auto-resize",+ };+ imageData = raw;+ }+ const base64 = imageData.toString("base64");+ const response = await ai.models.generateContent({+ model,+ contents: [+ {+ role: "user",+ parts: [+ { inlineData: { mimeType, data: base64 } },+ { text: customQuestion },+ ],+ },+ ],+ config: { maxOutputTokens: 250 },+ });+ return { filename, desc: response.text?.trim() || "no description" };+ }),+ );- const results = await Promise.allSettled(- paths.map(async (p) => {- const filename = basename(p);- const filePath = join(snapshotDir, filename);- if (!existsSync(filePath)) return { filename, desc: "file not found" };- const raw = readFileSync(filePath);- let imageData: Buffer;- let mimeType = "image/png";- if (sharpFn) {- imageData = await sharpFn(raw).resize(960).jpeg().toBuffer();- mimeType = "image/jpeg";+ for (const result of results) {+ if (result.status === "fulfilled") {+ descriptions.push(`## ${result.value.filename}`, `${result.value.desc}`, ``);} else {- if (raw.length > 3_800_000)- return {- filename,- desc: "file too large for Gemini — install sharp to enable auto-resize",- };- imageData = raw;+ // Log first failure so Gemini issues are visible rather than silent+ const errMsg = normalizeErrorMessage(result.reason);+ descriptions.push(+ `## (error)`,+ `Gemini call failed: ${errMsg.slice(0, 120)}`,+ ``,+ );}- const base64 = imageData.toString("base64");- const response = await ai.models.generateContent({- model,- contents: [- {- role: "user",- parts: [{ inlineData: { mimeType, data: base64 } }, { text: customQuestion }],- },- ],- config: { maxOutputTokens: 250 },- });- return { filename, desc: response.text?.trim() || "no description" };- }),- );-- for (const result of results) {- if (result.status === "fulfilled") {- descriptions.push(`## ${result.value.filename}`, `${result.value.desc}`, ``);- } else {- // Log first failure so Gemini issues are visible rather than silent- const errMsg = normalizeErrorMessage(result.reason);- descriptions.push(`## (error)`, `Gemini call failed: ${errMsg.slice(0, 120)}`, ``);}- }- const descPath = join(snapshotDir, "descriptions.md");- writeFileSync(descPath, descriptions.join("\n"));- console.log(` ${c.dim("descriptions.md")} (Gemini frame analysis)`);+ const descPath = join(snapshotDir, "descriptions.md");+ writeFileSync(descPath, descriptions.join("\n"));+ console.log(` ${c.dim("descriptions.md")} (Gemini frame analysis)`);+ }+ } catch (descErr) {+ const msg = normalizeErrorMessage(descErr);+ console.log(` ${c.dim(`--describe failed: ${msg}`)}`);}- } catch (descErr) {- const msg = normalizeErrorMessage(descErr);- console.log(` ${c.dim(`--describe failed: ${msg}`)}`);}- }+ });} catch (err) {const msg = normalizeErrorMessage(err);console.error(`\n${c.error("✗")} Snapshot failed: ${msg}`);diff --git a/packages/cli/src/utils/projectLock.test.ts b/packages/cli/src/utils/projectLock.test.tsnew file mode 100644index 0000000000..a955f7c384--- /dev/null+++ b/packages/cli/src/utils/projectLock.test.ts@@ -0,0 +1,161 @@+import { spawn } from "node:child_process";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { pathToFileURL } from "node:url";+import { afterEach, describe, expect, it } from "vitest";+import { ProjectLockTimeout, projectLockPath, withProjectLock } from "./projectLock.js";++const directories: string[] = [];+const project = () => {+ const directory = mkdtempSync(join(tmpdir(), "hf-project-lock-"));+ directories.push(directory);+ return directory;+};+afterEach(() => {+ for (const directory of directories.splice(0))+ rmSync(directory, { recursive: true, force: true });+});+const locked = (waitMs: number) => ({ projectLock: { waitMs } });+const hold = (dir: string, pid: number) => {+ mkdirSync(dirname(projectLockPath(dir)), { recursive: true });+ writeFileSync(projectLockPath(dir), JSON.stringify({ pid, command: "check", startedAt: 1 }));+};++describe("withProjectLock", () => {+ it("runs without a lock file when the capability is absent", async () => {+ const dir = project();+ expect(+ await withProjectLock(dir, "check", async () => existsSync(projectLockPath(dir)), {}),+ ).toBe(false);+ });++ it("holds the lock while running and releases it afterwards, even on failure", async () => {+ const dir = project();+ const seen = await withProjectLock(+ dir,+ "snapshot",+ async () => JSON.parse(readFileSync(projectLockPath(dir), "utf8")),+ locked(0),+ );+ expect(seen).toMatchObject({ pid: process.pid, command: "snapshot" });+ expect(existsSync(projectLockPath(dir))).toBe(false);+ await expect(+ withProjectLock(dir, "check", async () => Promise.reject(new Error("boom")), locked(0)),+ ).rejects.toThrow("boom");+ expect(existsSync(projectLockPath(dir))).toBe(false);+ });++ it("serializes concurrent holders in one project", async () => {+ const dir = project();+ const order: string[] = [];+ const task = (name: string) =>+ withProjectLock(+ dir,+ name,+ async () => {+ order.push(`${name}:start`);+ await new Promise((done) => setTimeout(done, 50));+ order.push(`${name}:end`);+ },+ locked(5000),+ );+ await Promise.all([task("check"), task("snapshot")]);+ expect(order).toEqual(["check:start", "check:end", "snapshot:start", "snapshot:end"]);+ });++ it("waits up to waitMs for a live holder, then refuses with who holds it", async () => {+ const dir = project();+ hold(dir, process.pid);+ const started = Date.now();+ await expect(withProjectLock(dir, "snapshot", async () => "ran", locked(300))).rejects.toThrow(+ ProjectLockTimeout,+ );+ expect(Date.now() - started).toBeGreaterThanOrEqual(300);+ await expect(withProjectLock(dir, "snapshot", async () => "ran", locked(0))).rejects.toThrow(+ `hyperframes check (pid ${process.pid}) is still using this project`,+ );+ });++ it("takes over a lock whose process has exited", async () => {+ const dir = project();+ hold(dir, 2 ** 22 + 12345);+ expect(await withProjectLock(dir, "check", async () => "ran", locked(0))).toBe("ran");+ });++ it("serializes processes that concurrently take over a dead holder", async () => {+ const dir = project();+ const events = join(dir, "events.ndjson");+ hold(dir, 2 ** 22 + 12345);+ const moduleUrl = pathToFileURL(join(import.meta.dirname, "projectLock.ts")).href;+ const source = `+ import { appendFileSync } from "node:fs";+ import { withProjectLock } from ${JSON.stringify(moduleUrl)};+ await withProjectLock(+ ${JSON.stringify(dir)},+ "check",+ async () => {+ appendFileSync(${JSON.stringify(events)}, JSON.stringify({ type: "start", pid: process.pid }) + "\\n");+ await new Promise((done) => setTimeout(done, 50));+ appendFileSync(${JSON.stringify(events)}, JSON.stringify({ type: "end", pid: process.pid }) + "\\n");+ },+ { projectLock: { waitMs: 5000 } },+ );+ `;+ const children = Array.from({ length: 6 }, () =>+ spawn(process.execPath, ["--import", "tsx", "--input-type=module", "--eval", source], {+ stdio: ["ignore", "ignore", "pipe"],+ }),+ );+ const outcomes = await Promise.all(+ children.map(+ (child) =>+ new Promise<{ code: number | null; error: string }>((resolve) => {+ let error = "";+ child.stderr.on("data", (chunk) => (error += String(chunk)));+ child.on("close", (code) => resolve({ code, error }));+ }),+ ),+ );+ expect(outcomes).toEqual(outcomes.map(() => ({ code: 0, error: "" })));+ const records = readFileSync(events, "utf8")+ .trim()+ .split("\n")+ .map((line) => JSON.parse(line) as { type: "start" | "end"; pid: number });+ let active = 0;+ for (const record of records) {+ active += record.type === "start" ? 1 : -1;+ expect(active).toBeLessThanOrEqual(1);+ }+ expect(active).toBe(0);+ });++ it("refuses a breaker left by a killed process and names the file", async () => {+ const dir = project();+ hold(dir, 2 ** 22 + 12345);+ const breakPath = `${projectLockPath(dir)}.break`;+ const source = `+ import { linkSync, writeFileSync } from "node:fs";+ const holder = { pid: process.pid, command: "check", startedAt: 1 };+ const draft = ${JSON.stringify(`${breakPath}.killed`)};+ writeFileSync(draft, JSON.stringify(holder), { flag: "wx" });+ linkSync(draft, ${JSON.stringify(breakPath)});+ process.kill(process.pid, "SIGKILL");+ `;+ const child = spawn(process.execPath, ["--input-type=module", "--eval", source], {+ stdio: "ignore",+ });+ const outcome = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(+ (resolve) => {+ child.on("close", (code, signal) => resolve({ code, signal }));+ },+ );+ expect(outcome.signal === "SIGKILL" || outcome.code !== 0).toBe(true);+ expect(existsSync(breakPath)).toBe(true);+ await expect(withProjectLock(dir, "check", async () => "ran", locked(0))).rejects.toThrow(+ `hyperframes left ${breakPath} (pid ${child.pid}); delete it to continue`,+ );+ expect(existsSync(breakPath)).toBe(true);+ expect(existsSync(projectLockPath(dir))).toBe(true);+ });+});diff --git a/packages/cli/src/utils/projectLock.ts b/packages/cli/src/utils/projectLock.tsnew file mode 100644index 0000000000..57276627d2--- /dev/null+++ b/packages/cli/src/utils/projectLock.ts@@ -0,0 +1,116 @@+import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";+import { dirname, join } from "node:path";+import { setTimeout as sleep } from "node:timers/promises";+import { readToolContext, type ToolContext } from "./toolContext.js";++export class ProjectLockTimeout extends Error {}++interface Holder {+ pid: number;+ command: string;+ startedAt: number;+}++const POLL_MS = 250;++export const projectLockPath = (projectDir: string) =>+ join(projectDir, ".hyperframes", "project.lock");++function readHolder(path: string): Holder | null {+ try {+ return JSON.parse(readFileSync(path, "utf8")) as Holder;+ } catch {+ return null;+ }+}++function alive(pid: number): boolean {+ try {+ process.kill(pid, 0);+ return true;+ } catch (error) {+ return (error as NodeJS.ErrnoException).code === "EPERM";+ }+}++const sameHolder = (a: Holder | null, b: Holder) =>+ a?.pid === b.pid && a.startedAt === b.startedAt && a.command === b.command;++function breakStaleHolder(path: string, current: Holder, holder: Holder): boolean {+ const breakPath = `${path}.break`;+ const breakDraft = `${breakPath}.${holder.pid}.${holder.startedAt}`;+ let acquired = false;+ writeFileSync(breakDraft, JSON.stringify(holder), { flag: "wx" });+ try {+ try {+ linkSync(breakDraft, breakPath);+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;+ throw error;+ }+ if (sameHolder(readHolder(path), current)) {+ try {+ unlinkSync(path);+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;+ }+ }+ acquired = tryAcquire(path, holder);+ } finally {+ unlinkSync(breakDraft);+ if (sameHolder(readHolder(breakPath), holder)) unlinkSync(breakPath);+ }+ return acquired;+}++function tryAcquire(path: string, holder: Holder): boolean {+ const draft = `${path}.${holder.pid}.${holder.startedAt}`;+ writeFileSync(draft, JSON.stringify(holder), { flag: "wx" });+ try {+ linkSync(draft, path);+ return true;+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;+ } finally {+ unlinkSync(draft);+ }+ const current = readHolder(path);+ if (current && !alive(current.pid)) return breakStaleHolder(path, current, holder);+ return false;+}++export async function withProjectLock<T>(+ projectDir: string,+ command: string,+ run: () => Promise<T>,+ context: ToolContext = readToolContext(),+): Promise<T> {+ if (!context.projectLock) return run();+ const path = projectLockPath(projectDir);+ mkdirSync(dirname(path), { recursive: true });+ const holder: Holder = { pid: process.pid, command, startedAt: Date.now() };+ const deadline = holder.startedAt + context.projectLock.waitMs;+ while (!tryAcquire(path, holder)) {+ const remaining = deadline - Date.now();+ if (remaining <= 0) {+ const current = readHolder(path);+ const breakPath = `${path}.break`;+ const breaker = readHolder(breakPath);+ if ((!current || !alive(current.pid)) && breaker && !alive(breaker.pid)) {+ throw new ProjectLockTimeout(+ `hyperframes left ${breakPath} (pid ${breaker.pid}); delete it to continue`,+ );+ }+ throw new ProjectLockTimeout(+ `hyperframes ${current?.command ?? "another command"} (pid ${current?.pid ?? "unknown"}) ` ++ `is still using this project after ${Math.round(context.projectLock.waitMs / 1000)}s`,+ );+ }+ await sleep(Math.min(POLL_MS, remaining));+ }+ try {+ return await run();+ } finally {+ if (sameHolder(readHolder(path), holder)) unlinkSync(path);+ }+}diff --git a/packages/cli/src/utils/toolContext.test.ts b/packages/cli/src/utils/toolContext.test.tsnew file mode 100644index 0000000000..d0e2108512--- /dev/null+++ b/packages/cli/src/utils/toolContext.test.ts@@ -0,0 +1,101 @@+import { mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join, resolve } from "node:path";+import { afterEach, describe, expect, it, vi } from "vitest";+import { readToolContext, reportArtifacts } from "./toolContext.js";++const directories: string[] = [];+const temporary = () => {+ const directory = mkdtempSync(join(tmpdir(), "hf-tool-context-"));+ directories.push(directory);+ return directory;+};+afterEach(() => {+ for (const directory of directories.splice(0))+ rmSync(directory, { recursive: true, force: true });+});++const context = (capabilities: unknown, version: unknown = 1) =>+ JSON.stringify({ version, capabilities });+const eventsAt = (path: string) => ({ transport: { type: "ndjson-file", path } });++describe("readToolContext", () => {+ it("is empty without a valid version 1 declaration", () => {+ for (const raw of [+ undefined,+ "",+ "not json",+ "[]",+ context({ events: eventsAt("/tmp/e") }, 2),+ context(["events"]),+ ])+ expect(readToolContext(raw)).toEqual({});+ });++ it("keeps each valid capability and ignores invalid or unknown ones", () => {+ const raw = context({+ events: eventsAt("/tmp/events.ndjson"),+ "project-lock": { waitMs: -1 },+ "future-capability": { anything: true },+ });+ expect(readToolContext(raw)).toEqual({ events: { path: "/tmp/events.ndjson" } });+ expect(readToolContext(context({ "project-lock": { waitMs: 500 } }))).toEqual({+ projectLock: { waitMs: 500 },+ });+ expect(readToolContext(context({ events: eventsAt("relative.ndjson") }))).toEqual({});+ expect(+ readToolContext(context({ events: { transport: { type: "http", path: "/x" } } })),+ ).toEqual({});+ });+});++describe("reportArtifacts", () => {+ it("appends one artifact.created line per path, with absolute paths and media types", () => {+ const path = join(temporary(), "events.ndjson");+ const events = { events: { path } };+ reportArtifacts("snapshot", "contact-sheet", ["/p/contact-sheet.jpg"], events);+ reportArtifacts("check", "finding", ["/p/crop.bin", "/p/crop.png"], events);+ const lines = readFileSync(path, "utf8")+ .trimEnd()+ .split("\n")+ .map((line) => JSON.parse(line));+ expect(lines).toEqual([+ {+ version: 1,+ type: "artifact.created",+ command: "snapshot",+ artifact: {+ role: "contact-sheet",+ path: resolve("/p/contact-sheet.jpg"),+ mediaType: "image/jpeg",+ },+ },+ {+ version: 1,+ type: "artifact.created",+ command: "check",+ artifact: {+ role: "finding",+ path: resolve("/p/crop.bin"),+ mediaType: "application/octet-stream",+ },+ },+ {+ version: 1,+ type: "artifact.created",+ command: "check",+ artifact: { role: "finding", path: resolve("/p/crop.png"), mediaType: "image/png" },+ },+ ]);+ });++ it("writes nothing without the events capability, and only warns when the file is unwritable", () => {+ expect(() => reportArtifacts("snapshot", "frame", ["/p/a.png"], {})).not.toThrow();+ const error = vi.spyOn(console, "error").mockImplementation(() => undefined);+ reportArtifacts("snapshot", "frame", ["/p/a.png"], {+ events: { path: join(temporary(), "missing", "events.ndjson") },+ });+ expect(error).toHaveBeenCalledOnce();+ error.mockRestore();+ });+});diff --git a/packages/cli/src/utils/toolContext.ts b/packages/cli/src/utils/toolContext.tsnew file mode 100644index 0000000000..ae872773ca--- /dev/null+++ b/packages/cli/src/utils/toolContext.ts@@ -0,0 +1,84 @@+import { appendFileSync } from "node:fs";+import { extname, isAbsolute, resolve } from "node:path";++const TOOL_CONTEXT_VERSION = 1;++export interface ToolContext {+ events?: { path: string };+ projectLock?: { waitMs: number };+}++export type ArtifactRole = "contact-sheet" | "frame" | "finding";++interface ArtifactCreatedEvent {+ version: typeof TOOL_CONTEXT_VERSION;+ type: "artifact.created";+ command: string;+ artifact: { role: ArtifactRole; path: string; mediaType: string };+}++const isRecord = (value: unknown): value is Record<string, unknown> =>+ typeof value === "object" && value !== null && !Array.isArray(value);++function parseEvents(value: unknown): ToolContext["events"] {+ if (!isRecord(value) || !isRecord(value.transport)) return undefined;+ const { type, path } = value.transport;+ if (type !== "ndjson-file" || typeof path !== "string" || !isAbsolute(path)) return undefined;+ return { path };+}++function parseProjectLock(value: unknown): ToolContext["projectLock"] {+ if (!isRecord(value)) return undefined;+ const { waitMs } = value;+ if (typeof waitMs !== "number" || !Number.isFinite(waitMs) || waitMs < 0) return undefined;+ return { waitMs };+}++export function readToolContext(raw = process.env.HF_TOOL_CONTEXT): ToolContext {+ if (!raw) return {};+ let value: unknown;+ try {+ value = JSON.parse(raw);+ } catch {+ return {};+ }+ if (!isRecord(value) || value.version !== TOOL_CONTEXT_VERSION || !isRecord(value.capabilities))+ return {};+ const events = parseEvents(value.capabilities.events);+ const projectLock = parseProjectLock(value.capabilities["project-lock"]);+ return { ...(events && { events }), ...(projectLock && { projectLock }) };+}++const MEDIA_TYPES: Record<string, string> = {+ ".png": "image/png",+ ".jpg": "image/jpeg",+ ".jpeg": "image/jpeg",+};++export function reportArtifacts(+ command: string,+ role: ArtifactRole,+ paths: readonly string[],+ context = readToolContext(),+): void {+ if (!context.events || paths.length === 0) return;+ const lines = paths.map((path) => {+ const absolute = resolve(path);+ const event: ArtifactCreatedEvent = {+ version: TOOL_CONTEXT_VERSION,+ type: "artifact.created",+ command,+ artifact: {+ role,+ path: absolute,+ mediaType: MEDIA_TYPES[extname(absolute).toLowerCase()] ?? "application/octet-stream",+ },+ };+ return JSON.stringify(event) + "\n";+ });+ try {+ appendFileSync(context.events.path, lines.join(""));+ } catch (error) {+ console.error(`HF_TOOL_CONTEXT events could not be written: ${(error as Error).message}`);+ }+}