jev-decide 0.1.0__tar.gz

jev_decide-0.1.0/.agents/skills/jev-usage/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: jev-usage
+description: Decide when and how to call `jev decide` while driving a browser with `ziniao-cli`. Covers the call contract (page snapshot in, one typed operation + target out), the caller's execution mapping, per-call cost budget, retry policy, post-execution verification, and the anti-patterns measured on real store tasks. Use when driving a ZClaw/ziniao store browser step by step, when picking an element to click/type/scroll on an unfamiliar page, when the target can only be described semantically, or when judging whether a hard-coded selector is cheaper than a decision call.
+---
+
+# jev-usage
+
+`jev decide` 是**单步决策器**：喂一份 `ziniao-cli page snapshot`，拿回一个类型化操作 + 一个目标，执行由调用方负责。它不提效 —— 它只在**目标不明确**时把"猜选择器"这一步变成有置信度的判断。按下面的判据用它，否则直接写选择器更便宜。
+
+## 1. 该不该叫（速查）
+
+| 场景 | 叫 jev？ | 理由 |
+|---|---|---|
+| 首次进入陌生页面，找入口/目标元素 | **叫** | 元素表未知，猜选择器要试错 3–5 步 |
+| 目标只能用语义描述，且没有稳定唯一 ID | **叫** | 这是它唯一不可替代的能力 |
+| 候选多且相似（导航、图标按钮、多个下拉） | **叫** | 元素表里 40+ 候选，人挑易错 |
+| 需要在 `CLICK` / `WAIT` / `SCROLL` 之间判断（懒加载、列表刷新中） | **叫** | 操作类型本身是决策 |
+| 异常分支：登录墙、验证码、遮挡弹窗 | **叫**（期望 `BLOCKED`） | 早点停手比乱点便宜 |
+| 判断"是否已完成" | **叫**（`DONE`），但见 §5 | `DONE` 是模型判断，不是证据 |
+| 已知唯一 ID 的元素（`#rating-dropdown`） | **不叫** | 决策没有信息增量，纯开销 |
+| 固定流程的翻页 / 滚动 / 轮询循环 | **不叫** | 固化进脚本，别每轮问一遍 |
+| 数据抽取、正文解析、结构化输出 | **不叫** | jev 不产出内容，用 `page query` / `page exec` |
+| 需要多步规划 | **不叫** | 它只做单步，多次调用不会合成计划 |
+| 同一个 goal 刚问过且页面没变 | **不叫** | 结果一样 |
+
+## 2. 调用契约
+
+```bash
+ziniao-cli page snapshot --store-id "$STORE" --max-items 120 \
+  | jev decide --goal "把评价时间范围切换为最近 1 个月"
+# 或：jev decide --observation /tmp/obs.json --goal "..." --compact
+```
+
+- **观测源只能是 `page snapshot`**。`page content --content-format structured` 读起来更好，但它的 `selectorHint` 常常只是标签名、表单控件没有定位符，**不能驱动选择**。抽取用它，决策用 snapshot。
+- **退出码就是接口**：`0` 有决策 / `2` 观测不可用 / `3` 模型或凭据失败；stdout 永远是一份 JSON，直接解析。
+- **ref 会过期**：`ref` 绑定具体 store + tab + 页面，导航、重载、URL 变化后失效 → **每次决策前重新快照**，不要跨导航复用 ref。
+- **`--max-items` 要给足**：实测 `3` 和 `5` 都只回 10 个元素，`20` 才回 20；但它同时是成本旋钮（§4）。
+- `--history FILE` 可传前几步，用于同一目标下的连续决策。
+
+## 3. 执行映射（调用方负责，jev 不碰）
+
+| 决策 | 怎么执行 |
+|---|---|
+| `CLICK` | `ziniao-cli page click --store-id "$STORE" --ref <ref>`（或 `--selector`）。**原生 `<select>` 例外**：`page click` 驱动不了系统下拉，改为 `page exec` 置 `value` + 派发 `change`/`input` |
+| `TYPE_TEXT` | 文本由调用方从自己上下文提供：`page input --selector <selector> --text <value> --clear` |
+| `SELECT` | 按返回的 `selector` 置值（`page input` 没有 `--ref`） |
+| `SCROLL_DOWN` / `SCROLL_UP` | `page scroll --store-id "$STORE" --y ±560` |
+| `WAIT` | 不动作，重新观测 |
+| `DONE` / `BLOCKED` | 停手。`DONE` 必须自己验证（§5） |
+
+返回体里的 `elements` 是完整索引表（含每个目标的 `ref` + `selector`），可以直接拿它执行或复核，不必为了执行再快照一次。
+
+## 4. 成本与预算
+
+- 单次 `decide` ≈ **0.3–7k 未缓存输入**（随元素表大小线性涨）+ 0.3–0.5k 输出，耗时 0.8–5s。
+- 经验换算：**一次 `decide` 的账单量级 ≈ 一个 agent 推理步**。所以它**只有替代掉 ≥1 个 agent 步才不亏**；替代不了就是纯开销。
+- 每个决策都有固定开销：`快照(+1 调用) → decide → 执行 → 验证`。比"直接用选择器执行"**多 1 步**。已知 ID 的场合这就是净亏。
+- 省钱手段：`--max-items` 收到 60–120；别把 snapshot 当轮询；同一页面同一 goal 不要重复问。
+- 把决策落进产物做审计轨迹：`goal / operation / choice / selector / confidence / usage`。
+
+**实测基准**（亚马逊店铺任务，同工作区对照）：
+
+| 任务 | jev 调用 | 占任务 token | 占任务时间 | 省下的步数 |
+|---|---|---|---|---|
+| 30 天评论抓取 | 5 × `decide` + `doctor` | 1.26% | 2.1% | 0（每次 +1 步） |
+| 近半年差评报告 | 2 × `decide` + `doctor` | 0.61% | 3.3% | 0 |
+
+两次任务里 7 个成功决策有 4 个问的是同一个 `#rating-dropdown` —— 这就是"重复问"的浪费。
+
+## 5. 验证（不可省）
+
+- **`DONE` 不是证据。** 实测：模型给 `DONE` 后，真实完整性是靠外部事实确认的 —— 页面计数 `5 total ratings, 5 with feedback` 等于列表 5 条，且点 Next 无新条目。
+- 每次执行后**重新观测或读状态**确认页面真的变了，而不是假设点击生效。
+- 抓数任务要与页面自带统计**对账**（页面面板 vs 抓取条数，差额要能解释，例如被屏蔽条目）。
+- 尽量用**两条独立路径**交叉验证（例：DOM 翻页 vs 页面自身接口），逐条比对。
+- 决策落地失败也要记账：实测 1/6 次 `CLICK` 因 ref 随重渲染失效报 `ELEMENT_NOT_INTERACTABLE`，最后改用 JS 兜底。
+
+## 6. 失败与重试
+
+- 实测 **2/9 次 `decide` 报模型连接失败**：`{"status":"error","error":{"type":"model","message":"Model connection failed..."}}`，exit 3；同刻 `doctor` 的模型延迟从 1.0s 涨到 5.2s。
+- 处理：退避 3s，**只读的 `decide` 可重试 ≤2 次**；仍失败就停下报告，**不要改成"猜一个选择器硬点"**。
+- 故障区分：`jev doctor`（runtime / install / credentials / model 四项，含一次最小模型请求）能分清"服务不可达"与"凭据/模型错"；凭据问题给 exit 3 + `{"error":{"type":"credential"}}`。`doctor` 不回显密钥，只看来源和长度。
+- **mutation 不重试**：点击/输入/提交这类写操作的重试属于调用方的业务决策，不要因为"再问一次 jev"就重放。
+
+## 7. 反模式（全部来自实测）
+
+1. 每次切筛选都问一遍 jev（同一个下拉问了 4 次，零信息增量）。
+2. 对已知唯一 ID 的元素问 jev。
+3. 把 `page snapshot` 当页面轮询。
+4. 跨导航 / DOM 重渲染复用 `ref`。
+5. 假设 `CLICK` 一定能直接执行（原生 `<select>`、`hide-content` 的隐藏 anchor 都不行）。
+6. 用很小的 `--max-items` 来省 token（会隐藏目标，且不线性减少返回量）。
+7. 把 `DONE` 当成"任务完成"的证据。
+
+## 8. 最小循环骨架
+
+```bash
+STORE=...; GOAL=...
+
+ziniao-cli page snapshot --store-id "$STORE" --max-items 120 > /tmp/obs.json   # 1 观测
+jev decide --observation /tmp/obs.json --goal "$GOAL" --compact > /tmp/d.json  # 2 决策（失败退避重试 ≤2）
+# 3 按 §3 映射执行；写操作不重试
+# 4 验证：重新 snapshot / 读页面状态，别信 DONE
+# 5 审计：把 /tmp/d.json 的 operation/choice/selector/confidence/usage 追加进产物
+```
+
+先按 §1 判断"这一跳到底要不要问"：**能写死就写死，写不死才问 jev。**
+
+## 9. 边界
+
+- jev 只输出"单步操作 + 目标"，**不生成文本、不产出选择器、不做多步规划、不抽取数据**。
+- 本 skill 只规定调用侧行为，不改动 `jev-decide` 包本身：该包内不引入浏览器驱动、bridge 客户端或文本模型。

jev_decide-0.1.0/.env.example

@@ -0,0 +1,8 @@
+# Copy to ./.env, or to ~/.config/jev/.env so a CLI started by a daemon, a GUI, or
+# another agent finds it without a shell rc file (agents do not read ~/.bashrc).
+# The process environment always wins over both files.
+TYPESAFE_API_KEY=
+TYPESAFE_MODEL=jev-latest
+# Decision service endpoint. Leave empty to use the default:
+# https://api.typesafe.ai/v1/systemone
+TYPESAFE_BASE_URL=

jev_decide-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+dist/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/

jev_decide-0.1.0/AGENTS.md

@@ -0,0 +1,19 @@
+# jev-decide
+
+Read README.md before editing. This package is one thing: page state in, one typed
+operation and target out.
+
+- `jev` has exactly two commands: `decide`, the only one that decides, and `doctor`, which only diagnoses it. Keep `jev` with no arguments printing help and exiting 2.
+- `decide` observes nothing, executes nothing, and never generates text. Never add a browser driver, a bridge client, or a text model here — the caller owns all three.
+- `doctor` observes nothing and executes nothing either. It may make one minimal model request to prove the service answers, and it must never echo a credential — only its source and length.
+- The observation layer accepts raw `ziniao-cli page snapshot` output — `page` is a required subcommand. Keep normalization in observation.py, and keep executable locators (`ref` and `selector`) on every target. `page content --content-format structured` carries no `ref` and its `selectorHint` is usually a bare tag name, so it is not an observation source.
+- Targets must map to observed elements and supported operations. Never let the model emit selectors or executable code.
+- Exit codes are the interface: `0` a decision or a healthy `doctor`, `2` a bad observation or bad usage, `3` the model or its credential failed. Keep stdout parseable JSON on every path, including failures.
+- Credentials come from env.py: the process environment wins, then `./.env`, then `~/.config/jev/.env`. Never read a shell rc file.
+- Never retry a mutation — the caller performs those. A read that fails while a document settles may be retried.
+- Tests must not call paid APIs, open a browser, or open a ZClaw connection. Use the captured fixtures in tests/fixtures.
+- Reinstalling the CLI must never silently install older code. `uv tool install --force` can reuse a cached wheel: verify the installed copy, or install `--editable`/`--no-cache`.
+- This package owns the `jev` console script. Do not also declare it elsewhere.
+- Do not commit or push unless the user requests it.
+
+Checks: uv run ruff check ., uv run pytest, uv build.

jev_decide-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: jev-decide
+Version: 0.1.0
+Summary: The jev decision service: page state in, one typed operation and target out.
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx[http2]<1,>=0.28
+Description-Content-Type: text/markdown
+
+# jev-decide
+
+**One decision, no browser.** `jev decide` reads a page state and answers with a single
+typed operation and target that the caller executes. It observes nothing, executes
+nothing, and never generates text.
+
+It is built for an agent that already drives a browser: page state in, one action out.
+
+## Install
+
+```bash
+uv tool install --editable .     # tracks this checkout; right while developing
+uv tool install --no-cache .     # frozen copy of the current source
+```
+
+Pass `--no-cache` for a frozen copy: `uv tool install --force .` can reuse a cached wheel
+and silently install older code than the checkout.
+
+The only runtime dependency is `httpx`. There is no browser driver here.
+
+## Use
+
+Feed it the output of `ziniao-cli page snapshot` verbatim:
+
+```bash
+ziniao-cli page snapshot --store-id "$STORE" --max-items 200 \
+  | jev decide --goal "Open the orders page"
+```
+
+`page` is not optional and not implicit. The command is `ziniao-cli page snapshot`;
+`ziniao-cli snapshot` answers `unknown command "snapshot" for "ziniao-cli"`, and the store
+browser has to be open already.
+
+```json
+{
+  "status": "ok",
+  "operation": "CLICK",
+  "choice": "e30",
+  "target": {
+    "index": "13",
+    "ref": "e30",
+    "selector": "#nav-orders",
+    "role": "link",
+    "label": "Returns & Orders"
+  },
+  "needs_text": false,
+  "confidence": 0.99,
+  "operation_probabilities": {"CLICK": 1.0, "TYPE_TEXT": 0.0, "WAIT": 0.0, "DONE": 0.0, "SCROLL_DOWN": 0.0, "BLOCKED": 0.0},
+  "target_probabilities": {"13": 0.95, "11": 0.03, "12": 0.02},
+  "elements": [{"index": "13", "ref": "e30", "selector": "#nav-orders", "role": "link", "label": "Returns & Orders", "operations": ["CLICK"]}]
+}
+```
+
+That response is real, not illustrative: the captured `ziniao-cli page snapshot` of a
+public amazon.com page (`tests/fixtures/ziniao_page_snapshot.json`) with the goal *"Open
+the orders page"* — `jev-1.13.0`, 2724 input tokens, 935 ms. The fixture ships in this
+repo, so the shape above is reproducible offline.
+
+- `--observation FILE` reads a file instead of stdin; `--history FILE` passes previous
+  steps as a JSON list; `--compact` emits one line.
+- stdout is **always** JSON, including failures, so a caller parses one stream.
+- Exit codes: `0` a decision, `2` the observation was unusable, `3` the model or its
+  credential failed.
+
+Every response carries the whole `elements` index table with a `ref` and a `selector` for
+each target, so the caller can execute or re-check without re-snapshotting.
+
+### Execute the decision
+
+| Decision | How the caller runs it |
+| --- | --- |
+| `CLICK` | `ziniao-cli page click --store-id "$STORE" --ref <ref>` (or `--selector`) |
+| `TYPE_TEXT` | the caller writes the value, then `ziniao-cli page input --store-id "$STORE" --selector <selector> --text <value> --clear` |
+| `SELECT` | set the value at the returned `selector` (`page input` has no `--ref`) |
+| `SCROLL_DOWN` / `SCROLL_UP` | `ziniao-cli page scroll --store-id "$STORE" --y ±560` |
+| `WAIT` | observe again without acting |
+| `DONE` / `BLOCKED` | stop. `DONE` is the model's choice, not proof: verify the outcome yourself |
+
+**TYPE_TEXT never comes with text.** The service names the field and stops; the calling
+agent supplies the value from its own context. That is why this package needs no text
+model and no `TEXT_MODEL_API_KEY`.
+
+## The observation
+
+`page snapshot` is the only `ziniao-cli` page command that returns an indexed element
+table with both semantic identity (role, accessible name, context, geometry) **and**
+actionable locators. `page content --content-format structured` reads better but its
+`selectorHint` is often just a tag name and form controls carry no locator, so it cannot
+drive a choice.
+
+The current `ziniao-page` skill draws the same line from the other side: it treats
+`page snapshot` as a local fallback — for upload controls, custom or icon-only controls,
+and candidates that survive `page query` and open-shadow-DOM checks — and prefers
+`page content --content-format structured` for *understanding* a page. That preference is
+about reading, not about choosing: only the snapshot carries a `ref` and a real
+`selector`, so a decision still needs one. Take a snapshot when a decision is due; do not
+turn it into a page poll.
+
+- Supply `--max-items` generously. The cap is the observation, so a low cap hides targets —
+  and a small value is not a reliable way to keep the observation short: measured against a
+  live store, `--max-items 3` and `--max-items 5` both returned 10 elements while `20`
+  returned 20.
+- A `ref` belongs to one store, tab, and page, and expires on reload or any URL change.
+  Re-snapshot after a navigation instead of reusing `ref`; `--target-id` picks the tab in a
+  multi-tab store.
+- Off-canvas elements are dropped the same way the browser-side reader drops them. An
+  element hidden with `left:-9999px` has real width and height, so geometry is the only
+  signal; without it, "skip to content" links become targets.
+- A `<select>` is offered as a dropdown to open, because the snapshot names it without
+  listing its options. Add an `options` array to that element in a normalized observation
+  to get the `SELECT` operation.
+- A page snapshot carries no scroll position, so the service offers scrolling down only.
+  Add `scroll: {"y":…, "height":…, "viewport":…}` to make both directions exact.
+- Page text is synthesized from the element table when the caller supplies none; merge a
+  `text` field into the payload, or send a normalized observation, for real page prose.
+
+## Credentials
+
+`TYPESAFE_API_KEY` is required. The process environment wins, then files fill in what is
+missing, most specific first:
+
+| Order | Location |
+| --- | --- |
+| 1 | the process environment |
+| 2 | `./.env` |
+| 3 | `~/.config/jev/.env` (or `$XDG_CONFIG_HOME/jev/.env`) |
+
+The third location exists so a CLI started by a daemon, a GUI, or another agent finds its
+credentials without a shell rc file — **an agent process does not read `~/.bashrc`**.
+A missing key needs no separate check command: `decide` answers with exit `3` and a
+parseable `{"error":{"type":"credential"}}`.
+
+The decision endpoint is configuration, not a credential, but it resolves through the same
+three locations: `TYPESAFE_BASE_URL` overrides the default
+`https://api.typesafe.ai/v1/systemone`, and an empty value means the default. `doctor`
+reports the endpoint it would use in both the `credentials` and `model` checks.
+
+```bash
+mkdir -p ~/.config/jev && cp .env.example ~/.config/jev/.env
+```
+
+## Doctor
+
+```bash
+jev doctor
+```
+
+One read-only self-check for the whole install, and the fastest way to answer "why did
+`decide` exit 3?":
+
+| Check | What it reports |
+| --- | --- |
+| `runtime` | the interpreter actually running, and the version this package requires |
+| `install` | the version, and whether this is the editable checkout or a frozen install |
+| `credentials` | **where** the key came from (process environment, `./.env`, `~/.config/jev/.env`) and **how long** it is — never the key itself |
+| `model` | one minimal model request that proves the service answers |
+
+The last check is a real request on purpose: an unreachable service and a wrong decision
+look identical from the caller's side, so `doctor` asks a question, names the answer it
+expects, and fails if something else comes back — a reachable endpoint answering with the
+wrong model is a failure, not a pass. The request carries no page state and no goal and
+costs roughly 400 input tokens.
+
+The same run, one line per check, detail trimmed:
+
+```json
+{"status": "ok", "command": "doctor", "checks": [
+  {"name": "runtime", "status": "ok", "detail": {"python": "3.13.12", "required": "3.12"}},
+  {"name": "install", "status": "ok", "detail": {"version": "0.1.0", "mode": "editable"}},
+  {"name": "credentials", "status": "ok", "detail": {"source": "~/.config/jev/.env", "key": {"present": true, "length": 108}, "endpoint": "https://api.typesafe.ai/v1/systemone"}},
+  {"name": "model", "status": "ok", "detail": {"endpoint": "https://api.typesafe.ai/v1/systemone", "answer": "PONG", "model": "jev-1.13.0", "latency_ms": 1025}}
+], "summary": {"passed": 4, "failed": 0, "skipped": 0}}
+```
+
+Exit `0` when every check passes, `3` when this install cannot decide. Same rule as
+`decide`: stdout is always one parseable JSON document, and `--compact` emits it on one
+line. `doctor` never reads an observation, so it needs no stdin.
+
+## Development
+
+```bash
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+Tests are offline: they use a captured page snapshot and a fake model call. Nothing in
+`pytest` reaches the network, opens a browser, or spends money.

jev_decide-0.1.0/README.md

@@ -0,0 +1,188 @@
+# jev-decide
+
+**One decision, no browser.** `jev decide` reads a page state and answers with a single
+typed operation and target that the caller executes. It observes nothing, executes
+nothing, and never generates text.
+
+It is built for an agent that already drives a browser: page state in, one action out.
+
+## Install
+
+```bash
+uv tool install --editable .     # tracks this checkout; right while developing
+uv tool install --no-cache .     # frozen copy of the current source
+```
+
+Pass `--no-cache` for a frozen copy: `uv tool install --force .` can reuse a cached wheel
+and silently install older code than the checkout.
+
+The only runtime dependency is `httpx`. There is no browser driver here.
+
+## Use
+
+Feed it the output of `ziniao-cli page snapshot` verbatim:
+
+```bash
+ziniao-cli page snapshot --store-id "$STORE" --max-items 200 \
+  | jev decide --goal "Open the orders page"
+```
+
+`page` is not optional and not implicit. The command is `ziniao-cli page snapshot`;
+`ziniao-cli snapshot` answers `unknown command "snapshot" for "ziniao-cli"`, and the store
+browser has to be open already.
+
+```json
+{
+  "status": "ok",
+  "operation": "CLICK",
+  "choice": "e30",
+  "target": {
+    "index": "13",
+    "ref": "e30",
+    "selector": "#nav-orders",
+    "role": "link",
+    "label": "Returns & Orders"
+  },
+  "needs_text": false,
+  "confidence": 0.99,
+  "operation_probabilities": {"CLICK": 1.0, "TYPE_TEXT": 0.0, "WAIT": 0.0, "DONE": 0.0, "SCROLL_DOWN": 0.0, "BLOCKED": 0.0},
+  "target_probabilities": {"13": 0.95, "11": 0.03, "12": 0.02},
+  "elements": [{"index": "13", "ref": "e30", "selector": "#nav-orders", "role": "link", "label": "Returns & Orders", "operations": ["CLICK"]}]
+}
+```
+
+That response is real, not illustrative: the captured `ziniao-cli page snapshot` of a
+public amazon.com page (`tests/fixtures/ziniao_page_snapshot.json`) with the goal *"Open
+the orders page"* — `jev-1.13.0`, 2724 input tokens, 935 ms. The fixture ships in this
+repo, so the shape above is reproducible offline.
+
+- `--observation FILE` reads a file instead of stdin; `--history FILE` passes previous
+  steps as a JSON list; `--compact` emits one line.
+- stdout is **always** JSON, including failures, so a caller parses one stream.
+- Exit codes: `0` a decision, `2` the observation was unusable, `3` the model or its
+  credential failed.
+
+Every response carries the whole `elements` index table with a `ref` and a `selector` for
+each target, so the caller can execute or re-check without re-snapshotting.
+
+### Execute the decision
+
+| Decision | How the caller runs it |
+| --- | --- |
+| `CLICK` | `ziniao-cli page click --store-id "$STORE" --ref <ref>` (or `--selector`) |
+| `TYPE_TEXT` | the caller writes the value, then `ziniao-cli page input --store-id "$STORE" --selector <selector> --text <value> --clear` |
+| `SELECT` | set the value at the returned `selector` (`page input` has no `--ref`) |
+| `SCROLL_DOWN` / `SCROLL_UP` | `ziniao-cli page scroll --store-id "$STORE" --y ±560` |
+| `WAIT` | observe again without acting |
+| `DONE` / `BLOCKED` | stop. `DONE` is the model's choice, not proof: verify the outcome yourself |
+
+**TYPE_TEXT never comes with text.** The service names the field and stops; the calling
+agent supplies the value from its own context. That is why this package needs no text
+model and no `TEXT_MODEL_API_KEY`.
+
+## The observation
+
+`page snapshot` is the only `ziniao-cli` page command that returns an indexed element
+table with both semantic identity (role, accessible name, context, geometry) **and**
+actionable locators. `page content --content-format structured` reads better but its
+`selectorHint` is often just a tag name and form controls carry no locator, so it cannot
+drive a choice.
+
+The current `ziniao-page` skill draws the same line from the other side: it treats
+`page snapshot` as a local fallback — for upload controls, custom or icon-only controls,
+and candidates that survive `page query` and open-shadow-DOM checks — and prefers
+`page content --content-format structured` for *understanding* a page. That preference is
+about reading, not about choosing: only the snapshot carries a `ref` and a real
+`selector`, so a decision still needs one. Take a snapshot when a decision is due; do not
+turn it into a page poll.
+
+- Supply `--max-items` generously. The cap is the observation, so a low cap hides targets —
+  and a small value is not a reliable way to keep the observation short: measured against a
+  live store, `--max-items 3` and `--max-items 5` both returned 10 elements while `20`
+  returned 20.
+- A `ref` belongs to one store, tab, and page, and expires on reload or any URL change.
+  Re-snapshot after a navigation instead of reusing `ref`; `--target-id` picks the tab in a
+  multi-tab store.
+- Off-canvas elements are dropped the same way the browser-side reader drops them. An
+  element hidden with `left:-9999px` has real width and height, so geometry is the only
+  signal; without it, "skip to content" links become targets.
+- A `<select>` is offered as a dropdown to open, because the snapshot names it without
+  listing its options. Add an `options` array to that element in a normalized observation
+  to get the `SELECT` operation.
+- A page snapshot carries no scroll position, so the service offers scrolling down only.
+  Add `scroll: {"y":…, "height":…, "viewport":…}` to make both directions exact.
+- Page text is synthesized from the element table when the caller supplies none; merge a
+  `text` field into the payload, or send a normalized observation, for real page prose.
+
+## Credentials
+
+`TYPESAFE_API_KEY` is required. The process environment wins, then files fill in what is
+missing, most specific first:
+
+| Order | Location |
+| --- | --- |
+| 1 | the process environment |
+| 2 | `./.env` |
+| 3 | `~/.config/jev/.env` (or `$XDG_CONFIG_HOME/jev/.env`) |
+
+The third location exists so a CLI started by a daemon, a GUI, or another agent finds its
+credentials without a shell rc file — **an agent process does not read `~/.bashrc`**.
+A missing key needs no separate check command: `decide` answers with exit `3` and a
+parseable `{"error":{"type":"credential"}}`.
+
+The decision endpoint is configuration, not a credential, but it resolves through the same
+three locations: `TYPESAFE_BASE_URL` overrides the default
+`https://api.typesafe.ai/v1/systemone`, and an empty value means the default. `doctor`
+reports the endpoint it would use in both the `credentials` and `model` checks.
+
+```bash
+mkdir -p ~/.config/jev && cp .env.example ~/.config/jev/.env
+```
+
+## Doctor
+
+```bash
+jev doctor
+```
+
+One read-only self-check for the whole install, and the fastest way to answer "why did
+`decide` exit 3?":
+
+| Check | What it reports |
+| --- | --- |
+| `runtime` | the interpreter actually running, and the version this package requires |
+| `install` | the version, and whether this is the editable checkout or a frozen install |
+| `credentials` | **where** the key came from (process environment, `./.env`, `~/.config/jev/.env`) and **how long** it is — never the key itself |
+| `model` | one minimal model request that proves the service answers |
+
+The last check is a real request on purpose: an unreachable service and a wrong decision
+look identical from the caller's side, so `doctor` asks a question, names the answer it
+expects, and fails if something else comes back — a reachable endpoint answering with the
+wrong model is a failure, not a pass. The request carries no page state and no goal and
+costs roughly 400 input tokens.
+
+The same run, one line per check, detail trimmed:
+
+```json
+{"status": "ok", "command": "doctor", "checks": [
+  {"name": "runtime", "status": "ok", "detail": {"python": "3.13.12", "required": "3.12"}},
+  {"name": "install", "status": "ok", "detail": {"version": "0.1.0", "mode": "editable"}},
+  {"name": "credentials", "status": "ok", "detail": {"source": "~/.config/jev/.env", "key": {"present": true, "length": 108}, "endpoint": "https://api.typesafe.ai/v1/systemone"}},
+  {"name": "model", "status": "ok", "detail": {"endpoint": "https://api.typesafe.ai/v1/systemone", "answer": "PONG", "model": "jev-1.13.0", "latency_ms": 1025}}
+], "summary": {"passed": 4, "failed": 0, "skipped": 0}}
+```
+
+Exit `0` when every check passes, `3` when this install cannot decide. Same rule as
+`decide`: stdout is always one parseable JSON document, and `--compact` emits it on one
+line. `doctor` never reads an observation, so it needs no stdin.
+
+## Development
+
+```bash
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+Tests are offline: they use a captured page snapshot and a fake model call. Nothing in
+`pytest` reaches the network, opens a browser, or spends money.

jev_decide-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "jev-decide"
+version = "0.1.0"
+description = "The jev decision service: page state in, one typed operation and target out."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = ["httpx[http2]>=0.28,<1"]
+
+[project.scripts]
+jev = "jev_decide.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest>=8.4,<9", "ruff>=0.14,<1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jev_decide"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

jev_decide-0.1.0/src/jev_decide/__init__.py

@@ -0,0 +1,5 @@
+"""The jev decision service: page state in, one typed operation and target out.
+
+`jev decide` observes nothing, executes nothing, and never generates text. The caller
+drives the browser and executes the operation it returns.
+"""