Skip to content

Commit 1b60a40

Browse files
authored
feat(cli): HF_TOOL_CONTEXT artifact events and project lock for agent harnesses (#5520)
* feat(cli): HF_TOOL_CONTEXT artifact events and project lock for agent harnesses * fix(cli): serialize stale project lock takeover Use a short-lived break lock so only one waiter can remove a dead holder's lock. Cover the contention path with six real processes. * fix(cli): hold snapshot lock through finalization Keep the project lock while contact sheets, artifact events, and frame descriptions read captured files so another snapshot cannot replace them. * fix(cli): recover a project lock after the breaker crashes A killed takeover left project.lock.break in place, so later commands waited out the timeout even though both holders were dead. Reclaim that file only when its recorded process is dead, and compare artifact paths after the platform resolves them. * fix(cli): accept a killed breaker process with no signal name Windows ends the process without reporting SIGKILL, so the regression was failing before it checked that the leftover breaker can be reclaimed. * fix(cli): leave a killed project-lock breaker in place Reclaiming a dead breaker unlinks a name another process may just have created, so two commands can hold the lock. The timeout names that file and its pid and says to delete it to continue.
1 parent b75fa6d commit 1b60a40

9 files changed

Lines changed: 744 additions & 133 deletions

File tree

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: "Running the CLI from an agent harness"
3+
description: "How an agent harness declares what it supports through HF_TOOL_CONTEXT, and what the CLI reports back."
4+
---
5+
6+
An agent harness (Claude Code, Codex, your own) runs `hyperframes` commands on the agent's behalf.
7+
`HF_TOOL_CONTEXT` lets the harness tell one invocation what it supports, so the CLI can do more for
8+
it: report the images it produced, or wait its turn instead of racing another command in the same
9+
project. Without the variable, every command behaves exactly as it does in a terminal.
10+
11+
```bash
12+
export HF_TOOL_CONTEXT='{"version":1,"capabilities":{
13+
"events": {"transport": {"type": "ndjson-file", "path": "/tmp/call-42/events.ndjson"}},
14+
"project-lock": {"waitMs": 90000}
15+
}}'
16+
npx hyperframes snapshot --at 1,3
17+
```
18+
19+
The harness sets the variable for one tool call, reads what the call produced, and removes its files.
20+
21+
## The declaration
22+
23+
| Field | Value |
24+
| --- | --- |
25+
| `version` | `1`. Any other version, or a value that is not JSON, is treated as no declaration. |
26+
| `capabilities` | An object keyed by capability name. Each value configures that capability. |
27+
28+
The CLI ignores capability names it does not know, and a known capability whose value is invalid, so
29+
a harness can declare capabilities newer than the CLI it runs. The variable carries data only: no
30+
capability runs code the harness names.
31+
32+
## `events`: what a command produced
33+
34+
```json
35+
{ "transport": { "type": "ndjson-file", "path": "/absolute/events.ndjson" } }
36+
```
37+
38+
The CLI appends one JSON object per line to `path`. It never creates the parent directory, and a
39+
write that fails prints a warning without failing the command. Read the file after the command
40+
exits; several commands in one shell call append to the same file.
41+
42+
Each line is an event:
43+
44+
```json
45+
{
46+
"version": 1,
47+
"type": "artifact.created",
48+
"command": "snapshot",
49+
"artifact": { "role": "contact-sheet", "path": "/project/snapshots/contact-sheet.jpg", "mediaType": "image/jpeg" }
50+
}
51+
```
52+
53+
| Command | `role` | What it is |
54+
| --- | --- | --- |
55+
| `snapshot` | `frame` | Each captured frame (PNG) |
56+
| `snapshot` | `contact-sheet` | Each page of the grid of frames made for review (JPEG) |
57+
| `check` | `frame` | Each frame the browser check captured |
58+
| `check` | `finding` | Each crop around a finding |
59+
60+
Paths are absolute and stay where the command saved them. What to do with an artifact is the
61+
harness's decision: attach the contact sheet to the tool result, or ignore it.
62+
Ignore event types and roles you do not know; new ones are added without a version change.
63+
64+
## `project-lock`: one browser command at a time
65+
66+
```json
67+
{ "waitMs": 90000 }
68+
```
69+
70+
`check` and `snapshot` take a lock on the project before they start a browser, and release it when
71+
they finish. A second command waits up to `waitMs` milliseconds for the lock, then fails, naming the
72+
command and process that hold it. A lock whose process has exited is taken over. A
73+
`project.lock.break` left by a killed process is not: the timeout names that file and its process
74+
id, and says to delete it to continue. The lock is the file `.hyperframes/project.lock`.
75+
76+
Choose `waitMs` below your tool call's own timeout, so a wait ends in the CLI's message rather than
77+
the harness killing the call.
78+
79+
## Hooks that run code
80+
81+
Running your own command before or after a CLI command is not a `HF_TOOL_CONTEXT` capability and
82+
never will be: anything that sets an environment variable could then run code. Such hooks, when they
83+
exist, come only from configuration the person controls.
84+
85+
## Conformance
86+
87+
`packages/cli/src/utils/toolContext.test.ts` and `projectLock.test.ts` pin the parsing, event and
88+
lock behavior above. A harness is correct when it sets the variable for each call it wants the
89+
behavior on, reads `events` only after the call exits, and works the same when the CLI ignores a
90+
capability.

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -960,6 +960,7 @@
960960
"developers/cli",
961961
"packages/cli",
962962
"developers/catalog-search",
963+
"developers/harness-tool-context",
963964
"packages/lint"
964965
]
965966
},

‎packages/cli/src/commands/check.test.ts‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import { runCommand } from "citty";
2-
import { readFileSync } from "node:fs";
2+
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
35
import { afterEach, describe, expect, it, vi } from "vitest";
46

57
const trackCheckReport = vi.fn();
@@ -530,6 +532,34 @@ it("threads --no-proxy into the browser check options", async () => {
530532
expect(runPipeline).toHaveBeenCalledWith(PROJECT, expect.objectContaining({ autoProxy: false }));
531533
});
532534

535+
it("waits for the project lock declared in HF_TOOL_CONTEXT before running the pipeline", async () => {
536+
const dir = mkdtempSync(join(tmpdir(), "hf-check-lock-"));
537+
const lock = join(dir, ".hyperframes", "project.lock");
538+
mkdirSync(join(dir, ".hyperframes"));
539+
writeFileSync(lock, JSON.stringify({ pid: process.pid, command: "snapshot", startedAt: 1 }));
540+
vi.stubEnv(
541+
"HF_TOOL_CONTEXT",
542+
JSON.stringify({ version: 1, capabilities: { "project-lock": { waitMs: 0 } } }),
543+
);
544+
const { report } = await runScenario(fakeDriver());
545+
const runPipeline = vi.fn(async () => report);
546+
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
547+
const command = createCheckCommand({
548+
resolveProject: () => ({ ...PROJECT, dir }),
549+
runPipeline,
550+
withMeta: (value) => value,
551+
});
552+
try {
553+
await runCommand(command, { rawArgs: ["--json"] });
554+
expect(runPipeline).not.toHaveBeenCalled();
555+
expect(consumeCommandResult().exitCode).toBe(1);
556+
expect(String(log.mock.calls[0]?.[0])).toContain("hyperframes snapshot");
557+
} finally {
558+
vi.unstubAllEnvs();
559+
rmSync(dir, { recursive: true, force: true });
560+
}
561+
});
562+
533563
it("rejects malformed caption-zone specs instead of silently disabling the gate", async () => {
534564
const { report } = await runScenario(fakeDriver());
535565
const runPipeline = vi.fn(async () => report);

‎packages/cli/src/commands/check.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1+
import { resolve } from "node:path";
12
import { formatFindingTimes } from "../utils/checkFindings.js";
3+
import { withProjectLock } from "../utils/projectLock.js";
4+
import { reportArtifacts } from "../utils/toolContext.js";
25
import { defineCommand, parseArgs } from "citty";
36
import type { ArgsDef } from "citty";
47
import type { Example } from "./_examples.js";
@@ -37,7 +40,13 @@ export interface CheckCommandDependencies {
3740

3841
const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = {
3942
resolveProject,
40-
runPipeline: runCheckPipeline,
43+
async runPipeline(project, options) {
44+
const report = await runCheckPipeline(project, options);
45+
const images = (files: readonly string[]) => files.map((file) => resolve(project.dir, file));
46+
reportArtifacts("check", "frame", images(report.snapshots.files));
47+
reportArtifacts("check", "finding", images(report.snapshots.findingFiles));
48+
return report;
49+
},
4150
withMeta,
4251
};
4352

@@ -158,7 +167,9 @@ export function createCheckCommand(
158167
if (!asJson) {
159168
console.log(`${c.accent("◆")} Checking ${c.accent(project.name)}`);
160169
}
161-
const report = await dependencies.runPipeline(project, options);
170+
const report = await withProjectLock(project.dir, "check", () =>
171+
dependencies.runPipeline(project, options),
172+
);
162173
if (asJson) {
163174
console.log(JSON.stringify(dependencies.withMeta(report), null, 2));
164175
} else {

0 commit comments

Comments
 (0)