glasspane-harness 0.12.0 → 0.12.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -3
- package/README.zh-CN.md +86 -2
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -22,6 +22,25 @@
|
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
25
|
+
## Table of Contents
|
|
26
|
+
|
|
27
|
+
- [About This Project](#about-this-project)
|
|
28
|
+
- [The other half of the pair: GlassPane](#the-other-half-of-the-pair-glasspane)
|
|
29
|
+
- [This is a complete coding agent, not a stripped one](#this-is-a-complete-coding-agent-not-a-stripped-one)
|
|
30
|
+
- [Product surfaces](#product-surfaces)
|
|
31
|
+
- [Install](#install)
|
|
32
|
+
- [Quick start](#quick-start)
|
|
33
|
+
- [The `gp_*` tool surface](#the-gp-tool-surface)
|
|
34
|
+
- [The evidence discipline](#the-evidence-discipline)
|
|
35
|
+
- [Two-way integration with iterate-harness](#two-way-integration-with-iterate-harness)
|
|
36
|
+
- [Documentation](#documentation)
|
|
37
|
+
- [Development](#development)
|
|
38
|
+
- [License & attribution](#license-attribution)
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## About This Project
|
|
43
|
+
|
|
25
44
|
**The problem.** An AI agent driving a real macOS app cannot honestly say whether the UI
|
|
26
45
|
did what it asked. It sees its own tool output, guesses from prose, and reports success.
|
|
27
46
|
Screenshots don't help: they show *a* moment, not a *change*, and they cannot say whether
|
|
@@ -36,8 +55,37 @@ invents a verdict. Verified calls are appended to a hash-chained decision log, a
|
|
|
36
55
|
compaction hook re-injects the session's evidence anchors so summarising can never quietly
|
|
37
56
|
drop the audit chain.
|
|
38
57
|
|
|
39
|
-
The
|
|
40
|
-
|
|
58
|
+
### The other half of the pair: GlassPane
|
|
59
|
+
|
|
60
|
+
This repository is one half of a two-part product. The other half is
|
|
61
|
+
[**GlassPane**](https://github.com/jingzhao-l/GlassPane), the macOS runtime-verification
|
|
62
|
+
engine: a Swift daemon that measures an application's accessibility tree, pixel changes,
|
|
63
|
+
crashes and responsiveness, and exposes those measurements over MCP through `glasspane-mcp`.
|
|
64
|
+
|
|
65
|
+
The split is deliberate and asymmetric:
|
|
66
|
+
|
|
67
|
+
- **GlassPane decides what the application did.** It holds the Accessibility, Input
|
|
68
|
+
Monitoring and Screen Recording grants, performs the measurement, and reports its own
|
|
69
|
+
attribution. This harness is a client of that verdict, not a second opinion.
|
|
70
|
+
- **The harness transcribes.** It carries the same `gp_*` surface natively, appends verified
|
|
71
|
+
calls to a hash-chained decision log, and re-injects evidence anchors when a long session
|
|
72
|
+
is compacted. It never invents a verdict.
|
|
73
|
+
- **Neither reads the other's private API.** Both consume the same published contract layer
|
|
74
|
+
(`iterate-kernel`), so the formats that cross the boundary are one definition rather than
|
|
75
|
+
two files evolving apart.
|
|
76
|
+
|
|
77
|
+
Install the engine first — the harness is a client, not a substitute:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
# Engine (macOS 14+). When the permission panel opens, grant Accessibility,
|
|
81
|
+
# Input Monitoring and Screen Recording to `GlassPane Daemon`.
|
|
82
|
+
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/GlassPane/main/install.sh -o /tmp/gp-install.sh && sh /tmp/gp-install.sh
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Its README is the place for install channels, permissions, the evidence-pack format and the
|
|
86
|
+
update line: [jingzhao-l/GlassPane](https://github.com/jingzhao-l/GlassPane). The engine also
|
|
87
|
+
serves MCP hosts that are not this harness (Claude Desktop, Cursor, any MCP client), which is
|
|
88
|
+
what `glasspane-mcp` is for.
|
|
41
89
|
|
|
42
90
|
## This is a complete coding agent, not a stripped one
|
|
43
91
|
|
|
@@ -109,7 +157,7 @@ npm install -g glasspane-harness
|
|
|
109
157
|
bun add -g glasspane-harness
|
|
110
158
|
|
|
111
159
|
# or one-click (npm first, GitHub release asset as fallback)
|
|
112
|
-
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/glasspane-harness/v0.12.
|
|
160
|
+
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/glasspane-harness/v0.12.2/scripts/install.sh | bash
|
|
113
161
|
```
|
|
114
162
|
|
|
115
163
|
Two commands are installed: **`glasspane-harness`** and the short alias **`gp-harness`**.
|
|
@@ -180,6 +228,58 @@ is never hard-coded here, because it grows upstream of this file. Full reference
|
|
|
180
228
|
|
|
181
229
|
Details: [`docs/evidence.md`](docs/evidence.md).
|
|
182
230
|
|
|
231
|
+
## Two-way integration with iterate-harness
|
|
232
|
+
|
|
233
|
+
GlassPane Harness is one side of a second pair. The engine answers "did that operation really
|
|
234
|
+
take effect?"; [iterate-harness](https://github.com/jingzhao-l/iterate-harness) answers "is this
|
|
235
|
+
code right?". The two do not talk through a chat log — everything that crosses the boundary is
|
|
236
|
+
written by one side as a verifiable record and read by the other.
|
|
237
|
+
|
|
238
|
+
- **Same chain format, verified before quoting.** Every decision recorded from an evidence pack
|
|
239
|
+
is appended to a hash-chained ledger (`~/.local/share/glasspane-harness/decisions.jsonl`, or
|
|
240
|
+
wherever `GLASSPANE_DECISION_LOG` points). The review loop writes `.iterate/decision-log.jsonl`
|
|
241
|
+
in the project under review in the same chain format, so a claim quoted from the other side's
|
|
242
|
+
file is chain-verified first: a rewritten line is refused with the number of the line where the
|
|
243
|
+
chain stops. The production reader today is the loop's (`fix_proof`); this fork ships the same
|
|
244
|
+
verifier, and a fixed-point test pins that a chain written by the loop verifies here. A project
|
|
245
|
+
can name the loop's ledger as its fix-evidence source once, with
|
|
246
|
+
`ih iterate glasspane-ledger <absolute path>` — the link is written only after the whole chain
|
|
247
|
+
verifies, and it pins the chain's first entry, so a replaced ledger stops qualifying.
|
|
248
|
+
- **A review dimension travels with the call.** Five `gp_*` tools take an optional `dimension`
|
|
249
|
+
argument — `gp_act`, `gp_observe`, `gp_diagnose`, `gp_last_evidence`, `gp_attach` — and they are
|
|
250
|
+
the same five on both surfaces. The engine never sees the word: the declaration is stripped
|
|
251
|
+
before a request leaves, and this harness echoes it back. A decision that contradicts what was
|
|
252
|
+
already witnessed for that operation id is refused (`KERNEL_E_DIMENSION_CONTEST`).
|
|
253
|
+
- **A failed re-check goes back to the app.** When a round's invariant re-check fails, the loop
|
|
254
|
+
asks the running application again, read-only, through the host's MCP transport. It builds one
|
|
255
|
+
`gp_last_evidence` plus one `gp_diagnose` per recorded operation; the allow-list is the five
|
|
256
|
+
read-only tools, and a call that would mutate the app is refused by name.
|
|
257
|
+
- **Compaction knows what was reviewed.** The compaction hook re-injects the session's evidence
|
|
258
|
+
anchors (operation id, outcome, ledger line, entry hash). The run plan (`.iterate/run-plan.json`
|
|
259
|
+
or `GLASSPANE_RUN_PLAN`) decides which dimension history is dropped first, and declarations that
|
|
260
|
+
could not reach an anchor are counted rather than assumed.
|
|
261
|
+
- **A fix is not accepted on the agent's word.** Before advancing a repair recipe, the gate reads
|
|
262
|
+
this round's invariant verdict, the project's recipe (`GLASSPANE_RECIPE`), and a chain-verified
|
|
263
|
+
ledger line recording a passing outcome against an operation id. Anything absent or unmeasured
|
|
264
|
+
is refused by name (`RECIPE_GATE_E_*`). The answer is recorded in the project's ledger; a
|
|
265
|
+
contract refusal writes no ledger bytes. Both doors read it back: `ih iterate gate` in a
|
|
266
|
+
terminal, `/iterate gate` in a session.
|
|
267
|
+
- **Both tool surfaces speak one provider contract.** This fork and the MCP shell register the
|
|
268
|
+
same provider id and the same prerequisites per method, and a gate that runs both registrations
|
|
269
|
+
reddens when they diverge.
|
|
270
|
+
|
|
271
|
+
What stays where it belongs: the engine decides what the application did; neither harness judges
|
|
272
|
+
an interface on its own. The gate reports and withholds — it does not run the recipe, because
|
|
273
|
+
neither product ships a recipe executor. The formats above come from one published contract
|
|
274
|
+
layer, [`iterate-kernel`](https://www.npmjs.com/package/iterate-kernel), and the boundary is
|
|
275
|
+
stated honestly: whether the two implementations still agree on a case the corpus never wrote
|
|
276
|
+
down is answered by `scripts/diff_kernel_implementations.py`, an operator command rather than a
|
|
277
|
+
CI step. The exchange from the loop's side is documented in the iterate-harness README
|
|
278
|
+
([GlassPane integration](https://github.com/jingzhao-l/iterate-harness#-glasspane-integration)),
|
|
279
|
+
and from the engine's side in [GlassPane's two-way integration section](https://github.com/jingzhao-l/GlassPane#two-way-integration-with-the-review-loop).
|
|
280
|
+
Implementation detail: [`docs/kernel-integration.md`](docs/kernel-integration.md) and
|
|
281
|
+
[`docs/evidence.md`](docs/evidence.md).
|
|
282
|
+
|
|
183
283
|
## Documentation
|
|
184
284
|
|
|
185
285
|
- [`docs/install.md`](docs/install.md) — install paths, permissions, verification
|
package/README.zh-CN.md
CHANGED
|
@@ -22,6 +22,25 @@
|
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
25
|
+
## 目录
|
|
26
|
+
|
|
27
|
+
- [这项目是什么](#这项目是什么)
|
|
28
|
+
- [一对产品的另一半:GlassPane](#一对产品的另一半glasspane)
|
|
29
|
+
- [这是一个完整的编程 harness,不是被削过头的 fork](#这是一个完整的编程-harness不是被削过头的-fork)
|
|
30
|
+
- [产品面](#产品面)
|
|
31
|
+
- [安装](#安装)
|
|
32
|
+
- [上手](#上手)
|
|
33
|
+
- [`gp_*` 工具面](#gp-工具面)
|
|
34
|
+
- [证据纪律](#证据纪律)
|
|
35
|
+
- [与 iterate-harness 的双向集成](#与-iterate-harness-的双向集成)
|
|
36
|
+
- [文档](#文档)
|
|
37
|
+
- [开发](#开发)
|
|
38
|
+
- [许可与署名](#许可与署名)
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 这项目是什么
|
|
43
|
+
|
|
25
44
|
**问题。** 一个驱动真实 macOS 应用的 AI agent,没法诚实地说清界面到底有没有按它要求的动。
|
|
26
45
|
它只看得见自己的工具输出,于是靠散文猜测、报成功。截图也不解决问题:截图给的是**某个瞬间**,
|
|
27
46
|
不是**某次变化**,更说不清这次变化是不是那次点击造成的。
|
|
@@ -32,7 +51,32 @@
|
|
|
32
51
|
熔断级、pass / fail / inconclusive)。harness 只转录,不自己下结论。成包的验证调用进哈希链
|
|
33
52
|
决策日志;压缩钩子会把会话的证据锚点重新注入压缩提示词,摘要再长也丢不掉审计链。
|
|
34
53
|
|
|
35
|
-
|
|
54
|
+
### 一对产品的另一半:GlassPane
|
|
55
|
+
|
|
56
|
+
本仓库是一对产品里的一半。另一半是 [**GlassPane**](https://github.com/jingzhao-l/GlassPane),
|
|
57
|
+
macOS 上的运行时验证引擎:一个 Swift 后台服务,测量应用的无障碍树、像素变化、崩溃与响应性,
|
|
58
|
+
并通过 `glasspane-mcp` 经 MCP 把这套测量交出去。
|
|
59
|
+
|
|
60
|
+
这个分工是刻意且不对称的:
|
|
61
|
+
|
|
62
|
+
- **应用做了什么由 GlassPane 判定。** 它持有辅助功能、输入监控与屏幕录制授权,做测量,
|
|
63
|
+
给出自己的归因。这个 harness 是那份判定的客户端,不是第二种意见。
|
|
64
|
+
- **harness 只负责转写。** 它原生带着同一套 `gp_*` 面,把已验证的调用追加进哈希链决策账本,
|
|
65
|
+
并在长会话被压缩时重新注入证据锚点。它绝不自行发明判定。
|
|
66
|
+
- **两边都不读对方的私有 API。** 它们吃的是同一份公开发布的契约层(`iterate-kernel`),
|
|
67
|
+
所以跨越边界的格式只有一份定义,而不是两份各自演化的文件。
|
|
68
|
+
|
|
69
|
+
先把引擎装上——harness 是客户端,不是替代品:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# 引擎(macOS 14+)。权限面板弹出时,为 `GlassPane Daemon` 勾选辅助功能、
|
|
73
|
+
# 输入监控与屏幕录制。
|
|
74
|
+
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/GlassPane/main/install.sh -o /tmp/gp-install.sh && sh /tmp/gp-install.sh
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
安装渠道、权限、证据包格式与更新线都在它的 README:[jingzhao-l/GlassPane](https://github.com/jingzhao-l/GlassPane)。
|
|
78
|
+
引擎也服务不是这个 harness 的 MCP host(Claude Desktop、Cursor、任意 MCP 客户端),
|
|
79
|
+
`glasspane-mcp` 就是为此存在的。
|
|
36
80
|
|
|
37
81
|
## 这是一个完整的编程 harness,不是被削过头的 fork
|
|
38
82
|
|
|
@@ -91,7 +135,7 @@ Azure、OpenRouter 等等全在——几百个模型——每一个都用**你
|
|
|
91
135
|
```bash
|
|
92
136
|
npm install -g glasspane-harness # 推荐
|
|
93
137
|
bun add -g glasspane-harness
|
|
94
|
-
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/glasspane-harness/v0.12.
|
|
138
|
+
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/glasspane-harness/v0.12.2/scripts/install.sh | bash
|
|
95
139
|
```
|
|
96
140
|
|
|
97
141
|
会装出两个命令:**`glasspane-harness`** 与短别名 **`gp-harness`**。
|
|
@@ -151,6 +195,46 @@ glasspane-harness --help
|
|
|
151
195
|
|
|
152
196
|
细节:[`docs/evidence.md`](docs/evidence.md)。
|
|
153
197
|
|
|
198
|
+
## 与 iterate-harness 的双向集成
|
|
199
|
+
|
|
200
|
+
GlassPane Harness 是第二对产品里的一半。引擎回答"这次操作到底生效了吗";
|
|
201
|
+
[iterate-harness](https://github.com/jingzhao-l/iterate-harness) 回答"这段代码对不对"。
|
|
202
|
+
两边不靠聊天记录对接——跨越边界的东西都由一侧写成可核验的记录,另一侧读它。
|
|
203
|
+
|
|
204
|
+
- **同一种链格式,先验通再引用。** 每条从证据包记下的决定都追加进哈希链账本
|
|
205
|
+
(`~/.local/share/glasspane-harness/decisions.jsonl`,或由 `GLASSPANE_DECISION_LOG` 指到别处)。
|
|
206
|
+
审查回路把 `.iterate/decision-log.jsonl` 写进被审项目,用的是同一种链格式,所以从对方那本引来的
|
|
207
|
+
主张会先整链验通:被改过的行会被拒绝,并说清链断在第几行。今天在生产里跑这个读者的是回路这一侧
|
|
208
|
+
(`fix_proof`);本 fork 带的是同一个校验器,一条固定点测试钉住"那边写的链在这边验得过"。
|
|
209
|
+
一个项目可以一次性用 `ih iterate glasspane-ledger <绝对路径>` 把回路的账本记为自己的修复证据来源:
|
|
210
|
+
链接只在整链验通之后落笔,并钉住链的首条,被替换的账本因此不再够格。
|
|
211
|
+
- **审查维度跟着调用走。** 有 5 项 `gp_*` 工具接受可选的 `dimension` 参数——`gp_act`、`gp_observe`、
|
|
212
|
+
`gp_diagnose`、`gp_last_evidence`、`gp_attach`——两侧是同五项。引擎从不看见这个词:声明在请求
|
|
213
|
+
出网前就被剥掉,回显由本 harness 自己写。与同一 operationId 上已有见证矛盾的决定会被拒绝
|
|
214
|
+
(`KERNEL_E_DIMENSION_CONTEST`)。
|
|
215
|
+
- **复核不过,就回到应用本身。** 一轮的 invariant 复核失败时,回路通过宿主的 MCP 通道再次只读地问
|
|
216
|
+
那个正在跑的应用:每个已记录操作构造一条 `gp_last_evidence` 加一条 `gp_diagnose`;允许名单是
|
|
217
|
+
5 项只读工具,会改动应用的调用被点名拒绝。
|
|
218
|
+
- **压缩知道这次查了什么。** 压缩钩子会重新注入会话的证据锚点(operationId、结果、台账行号、
|
|
219
|
+
条目哈希)。运行计划(`.iterate/run-plan.json` 或 `GLASSPANE_RUN_PLAN`)决定先丢哪一维的历史;
|
|
220
|
+
声明了维度却进不了锚点的调用会被数出来,而不是假设它们还在。
|
|
221
|
+
- **修复不靠代理自称就算完成。** 推进修复配方之前,闸会读三件实测的东西:本轮 invariant 判定、
|
|
222
|
+
项目配方(`GLASSPANE_RECIPE`),以及一条链可验、按 operationId 记着通过结果的账本行。
|
|
223
|
+
缺任何一件或未量到都具名拒绝(`RECIPE_GATE_E_*`)。答案落进项目账本;契约拒绝一个字节都不写。
|
|
224
|
+
两扇门都读得回来:终端里 `ih iterate gate`,会话里 `/iterate gate`。
|
|
225
|
+
- **两个工具面说的是同一份 provider 契约。** 本 fork 与 MCP 层注册同一个 provider id 和每个方法
|
|
226
|
+
相同的先决条件;跑两侧注册代码的尺子一旦发现分叉就红。
|
|
227
|
+
|
|
228
|
+
各归各位:应用做了什么由引擎判定,两个 harness 都不自行给界面下结论。闸只报与拦,不执行配方——
|
|
229
|
+
两个产品都没有配方执行器。上面这些格式来自同一份发布出去的契约层
|
|
230
|
+
[`iterate-kernel`](https://www.npmjs.com/package/iterate-kernel),边界也说清楚:
|
|
231
|
+
"两份实现对语料没写过的案子还一致吗"由 `scripts/diff_kernel_implementations.py` 回答——它是给操作者
|
|
232
|
+
跑的命令,不在 CI 步骤里。回路那一侧的说明见 iterate-harness README 的
|
|
233
|
+
[GlassPane 集成](https://github.com/jingzhao-l/iterate-harness#-glasspane-integration),
|
|
234
|
+
引擎那一侧见 [GlassPane 的双向集成小节](https://github.com/jingzhao-l/GlassPane#two-way-integration-with-the-review-loop)。
|
|
235
|
+
实现细节:[`docs/kernel-integration.md`](docs/kernel-integration.md) 与
|
|
236
|
+
[`docs/evidence.md`](docs/evidence.md)。
|
|
237
|
+
|
|
154
238
|
## 文档
|
|
155
239
|
|
|
156
240
|
- [`docs/install.md`](docs/install.md) — 安装通道、权限、自检
|
package/package.json
CHANGED
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"scripts": {
|
|
26
26
|
"postinstall": "node ./postinstall.mjs"
|
|
27
27
|
},
|
|
28
|
-
"version": "0.12.
|
|
28
|
+
"version": "0.12.2",
|
|
29
29
|
"license": "MIT",
|
|
30
30
|
"os": [
|
|
31
31
|
"darwin"
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
},
|
|
45
45
|
"sideEffects": false,
|
|
46
46
|
"optionalDependencies": {
|
|
47
|
-
"glasspane-harness-darwin-arm64": "0.12.
|
|
48
|
-
"glasspane-harness-darwin-x64": "0.12.
|
|
47
|
+
"glasspane-harness-darwin-arm64": "0.12.2",
|
|
48
|
+
"glasspane-harness-darwin-x64": "0.12.2"
|
|
49
49
|
}
|
|
50
50
|
}
|