Skip to content

Commit abe97f6

Browse files
authored
refactor(inspector)!: drop the predefined agent tools; harnesses define their own (#5570)
* refactor(inspector)!: drop the predefined agent tools; harnesses define their own * chore(ci): agree to the inspector's agent-tool file deletions * docs(inspector): describe the HTTP contract only, export the request types * fix(inspector): ship the HTTP server and give every refusal a stable code * fix(inspector): keep the server export in the subpath descriptor * fix(inspector): keep the HTTP server reusable after a large body * fix(inspector): start the npm bin when it is a symlink * fix(inspector): import the server test without a .ts extension * fix(inspector): ship the HTTP server without a second copy of the service
1 parent d77b03c commit abe97f6

16 files changed

Lines changed: 412 additions & 559 deletions

‎packages/inspector/INSPECT-TIMELINE.md‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

‎packages/inspector/README.md‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Recover original HTML/CSS/GSAP context for **known elements before an edit**. This is not a video check, screenshot, diff, or affected-component verifier. It combines the I002 runtime/compiler provenance approach with the I003 HF-owned service boundary. The agent adapter holds no DOM or animation state.
44

5-
This source-only experimental package is private. It does not modify the shared installation or register itself in a harness. Base: HF 0.8.127, commit `b3d2b82fe`.
5+
Published as `@hyperframes/inspector`. It does not modify the shared installation or register itself in a harness.
66

77
## Start
88

@@ -17,13 +17,9 @@ export HF_INSPECT_CHROME=/absolute/path/to/chrome
1717
bun packages/inspector/src/server.ts /absolute/video/project
1818
```
1919

20-
The service prints its loopback URL. Starting it does **not** start a browser. First inspection loads the project once. Configure the harness's MCP server to execute:
20+
The service prints its loopback URL. Starting it does **not** start a browser. First inspection loads the project once.
2121

22-
```sh
23-
HF_INSPECT_URL=http://127.0.0.1:PRINTED_PORT bun packages/inspector/src/mcp.ts
24-
```
25-
26-
Tool: `inspect_components`. Direct HTTP equivalent: `POST /inspect` with the same JSON. The service is bound to one project at startup, so no per-call project path is needed. `GET /info` returns project identity and startup/query counters. Stop with SIGINT/SIGTERM; the service disposes its own pages/browser.
22+
The package ships the capability, not agent tools: a harness defines its own tool names, descriptions and schemas, and calls `POST /inspect` with the JSON below. The service is bound to one project at startup, so no per-call project path is needed. `GET /info` returns project identity and startup/query counters. Stop with SIGINT/SIGTERM; the service disposes its own pages/browser.
2723

2824
## Input
2925

@@ -83,7 +79,25 @@ Code blocks are atomic. `omitted`, `omittedCount`, and `nextOffset` describe mis
8379

8480
`maxBytes` can be raised explicitly (2,048–256,000). A block larger than the budget is not cut in half: request that ID with a larger budget or read its file/range. Pagination can therefore remain at the same offset until the budget increases. Old-generation continuations are rejected.
8581

86-
Full runtime evidence is only available by an explicit HTTP request with `debug: true`; it is deliberately not part of the agent tool schema or its default output budget.
82+
Full runtime evidence is only available by an explicit HTTP request with `debug: true`; it is deliberately not part of the default request or its output budget.
83+
84+
## Timeline
85+
86+
`POST /timeline` answers which animations are scheduled when, from the same browser, page and generation as `/inspect`. It never seeks, renders or edits files.
87+
88+
```json
89+
{ "component": { "selector": "#title" }, "boundary": 7.9 }
90+
```
91+
92+
`component` is optional and resolves like an `/inspect` target; omit it for every registered HF timeline. Give at most one of `at`, `range: [start, end]` or `boundary`, in global seconds; omit all three for the schedule overview. Results are short text grouped by component, with event times, targets, properties and source locations; `generation` and `offset` page through them. Coverage is registered DOM-target GSAP animations and explicit HF items only; anything outside that, or past the expansion limits, is reported as incomplete coverage rather than guessed.
93+
94+
## Element map
95+
96+
`POST /element-map` returns the composition's element map from the same page. It reads no query fields. A project with no `index.html` answers `404` `{ "error": "no-composition", "code": "no-composition" }`.
97+
98+
## Errors
99+
100+
Every refusal is JSON `{ "error", "code" }`. `code` is the stable token (`no-composition`, `stale_generation`, `source_changed_during_query`, `request_too_large`); a sentence with no token is `invalid_request`. A missing browser is `503` `browser_unavailable`, and an unexpected failure is `500` `internal_error`. Importing the module does not listen; `createInspectorServer(project)` builds one. An unknown route is `404` `{ "error": "not_found", "code": "not_found" }`. `GET /info` adds `version`, this package's version. The process listens on `127.0.0.1` and refuses a `Host` that is not loopback, so a rebinding request cannot read the project path. Install the server with the package: `hyperframes-inspector <project> [port]`, or `node dist/server.js`.
87101

88102
## Lifecycle and overhead
89103

‎packages/inspector/build.mjs‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,23 @@ const node = { bundle: true, platform: "node", format: "esm", target: "node22",
2525
await Promise.all([
2626
build({ ...node, entryPoints: [at("./src/live.ts")], outfile: at("./dist/live.js") }),
2727
build({ ...node, entryPoints: [at("./src/service.ts")], outfile: at("./dist/service.js") }),
28-
build({ ...node, entryPoints: [at("./src/server.ts")], outfile: at("./dist/server.js") }),
29-
build({ ...node, entryPoints: [at("./src/mcp.ts")], outfile: at("./dist/mcp.js") }),
28+
build({
29+
...node,
30+
entryPoints: [at("./src/server.ts")],
31+
outfile: at("./dist/server.js"),
32+
banner: { js: `#!/usr/bin/env node\n${banner.js}` },
33+
plugins: [
34+
{
35+
name: "external-service",
36+
setup(build) {
37+
build.onResolve({ filter: /^\.\/service$/ }, () => ({
38+
path: "./service.js",
39+
external: true,
40+
}));
41+
},
42+
},
43+
],
44+
}),
3045
build({
3146
entryPoints: [at("./src/liveRuntime.ts")],
3247
outfile: at("./dist/inspection.js"),

‎packages/inspector/package-subpaths.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,14 @@
1515
},
1616
"types": "./dist/types/inspector/src/live.d.ts",
1717
"environments": ["node"]
18+
},
19+
"./server": {
20+
"source": "./src/server.ts",
21+
"runtime": {
22+
"default": "./dist/server.js"
23+
},
24+
"types": "./dist/types/inspector/src/server.d.ts",
25+
"environments": ["bun", "node"]
1826
}
1927
}
2028
}

‎packages/inspector/package.json‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@
66
"url": "https://github.com/heygen-com/hyperframes",
77
"directory": "packages/inspector"
88
},
9+
"bin": {
10+
"hyperframes-inspector": "./dist/server.js"
11+
},
912
"files": [
1013
"dist/service.js",
1114
"dist/live.js",
15+
"dist/server.js",
1216
"dist/inspection.js",
1317
"dist/types",
1418
"README.md"
@@ -24,6 +28,12 @@
2428
"./live": {
2529
"types": "./dist/types/inspector/src/live.d.ts",
2630
"default": "./dist/live.js"
31+
},
32+
"./server": {
33+
"bun": "./src/server.ts",
34+
"import": "./src/server.ts",
35+
"types": "./src/server.ts",
36+
"default": "./dist/server.js"
2737
}
2838
},
2939
"publishConfig": {
@@ -36,6 +46,10 @@
3646
"./live": {
3747
"types": "./dist/types/inspector/src/live.d.ts",
3848
"default": "./dist/live.js"
49+
},
50+
"./server": {
51+
"types": "./dist/types/inspector/src/server.d.ts",
52+
"default": "./dist/server.js"
3953
}
4054
}
4155
},
@@ -44,7 +58,6 @@
4458
"test": "vitest run",
4559
"typecheck": "tsc --noEmit",
4660
"serve": "bun run build && bun src/server.ts",
47-
"mcp": "bun run build && bun src/mcp.ts",
4861
"test:timeline": "bun tests/timeline.ts",
4962
"test:timeline-compositions": "bun tests/timelineCompositions.ts",
5063
"test:live": "bun run build && bun tests/live.ts",

‎packages/inspector/src/live.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,5 +100,11 @@ export function previewGeneration(runner: PageRunner): Promise<string | null> {
100100
}
101101

102102
export { fingerprint } from "./sources";
103-
export { componentsTool, timelineTool, toolContent, type InspectionTool } from "./tools";
104-
export type { ComponentReport, ElementMapReport, PageRunner, TimelineReport };
103+
export type {
104+
ComponentReport,
105+
ElementMapReport,
106+
InspectRequest,
107+
PageRunner,
108+
TimelineReport,
109+
TimelineRequest,
110+
};

‎packages/inspector/src/mcp.ts‎

Lines changed: 0 additions & 68 deletions
This file was deleted.

‎packages/inspector/src/outputSchemas.ts‎

Lines changed: 0 additions & 98 deletions
This file was deleted.

0 commit comments

Comments
 (0)