diff --git a/changelog.d/agents-picture.md b/changelog.d/agents-picture.md new file mode 100644 index 00000000..b6bf72aa --- /dev/null +++ b/changelog.d/agents-picture.md @@ -0,0 +1,2 @@ +- A picture of where each coding agent can be stopped (`docs/assets/readme/v2/agents.png`), derived into + `agents.json` from the code; linked from `docs/adapters/README.md`. diff --git a/docs/adapters/README.md b/docs/adapters/README.md index 38fbf40d..470fe38e 100644 --- a/docs/adapters/README.md +++ b/docs/adapters/README.md @@ -2,6 +2,12 @@ Adapters map the agent-agnostic Chock core to agent-specific surfaces. +## Which agents, and how strongly + +

Where each coding agent can be stopped: one card per agent, in three dashed boxes (one plugin tested live, one plugin untested, git hook and CI). Every card has filled diamonds for the CI check and the commit hook, a hollow pre-tool chip labelled with its grade where the agent has its own hook (fails open; Cursor can fail closed), and a hollow AGENTS.md chip.

+ +The picture is derived from the code by `python docs/assets/readme/derive.py readme`, so a change to an agent moves it. + ## Agent-specific entry points Most agents read `AGENTS.md` directly and get **no wrapper file at all** — Cursor, Codex, diff --git a/docs/assets/readme/agents.json b/docs/assets/readme/agents.json new file mode 100644 index 00000000..5b198314 --- /dev/null +++ b/docs/assets/readme/agents.json @@ -0,0 +1,277 @@ +{ + "source": { + "file": "SURFACE_AGENTS, in_agent_grade, agentseam matrix, plugin warnings", + "chock": "1.2.0" + }, + "title": "Where each coding agent can be stopped", + "columns": [ + { + "id": "ci", + "label": "CI", + "hard": true + }, + { + "id": "git", + "label": "commit", + "hard": true + }, + { + "id": "hook", + "label": "pre-tool", + "hard": false + }, + { + "id": "rule", + "label": "AGENTS.md", + "hard": false + } + ], + "counts": { + "agents": 20, + "own_hook": 15, + "plugin_tested": 8, + "plugin_untested": 3 + }, + "groups": { + "tested live": "One plugin, tested live", + "untested": "One plugin, untested", + "": "Git hook and CI" + }, + "legend": [ + { + "hard": true, + "text": "filled: refuses here" + }, + { + "hard": false, + "text": "hollow: advice, or best effort" + }, + { + "hard": null, + "text": "fails open: if the agent's hook dies, the action goes ahead" + } + ], + "footer": "Read from Chock 1.2.0 with agentseam 0.4.1. Grades are capped by their evidence.", + "rows": [ + { + "id": "antigravity", + "name": "Antigravity CLI", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "claude", + "name": "Claude Code", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "codex", + "name": "Codex", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "copilot", + "name": "Copilot", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "cursor", + "name": "Cursor", + "ci": true, + "git": true, + "hook_grade": "enforceable", + "hook": "can fail closed", + "matrix_pre_tool": "enforceable", + "plugin": "tested live", + "rule": true + }, + { + "id": "devin", + "name": "Devin", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "goose", + "name": "goose", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "grok", + "name": "Grok", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "tested live", + "rule": true + }, + { + "id": "factory-droid", + "name": "Factory Droid", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "untested", + "rule": true + }, + { + "id": "kimi-code", + "name": "Kimi Code", + "ci": true, + "git": true, + "hook_grade": "none", + "hook": "", + "matrix_pre_tool": "best-effort", + "plugin": "untested", + "rule": true + }, + { + "id": "openhands", + "name": "OpenHands", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "untested", + "rule": true + }, + { + "id": "aider", + "name": "Aider", + "ci": true, + "git": true, + "hook_grade": "none", + "hook": "", + "matrix_pre_tool": "none", + "plugin": "", + "rule": true + }, + { + "id": "cline", + "name": "Cline", + "ci": true, + "git": true, + "hook_grade": "none", + "hook": "", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + }, + { + "id": "gemini", + "name": "Gemini", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + }, + { + "id": "junie", + "name": "Junie", + "ci": true, + "git": true, + "hook_grade": "none", + "hook": "", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + }, + { + "id": "mistral-vibe", + "name": "Mistral Vibe", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + }, + { + "id": "replit", + "name": "Replit", + "ci": true, + "git": true, + "hook_grade": "none", + "hook": "", + "matrix_pre_tool": "none", + "plugin": "", + "rule": true + }, + { + "id": "tabnine", + "name": "Tabnine", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + }, + { + "id": "vscode", + "name": "VS Code", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + }, + { + "id": "windsurf", + "name": "Windsurf", + "ci": true, + "git": true, + "hook_grade": "best-effort", + "hook": "fails open", + "matrix_pre_tool": "best-effort", + "plugin": "", + "rule": true + } + ] +} diff --git a/docs/assets/readme/agents.mjs b/docs/assets/readme/agents.mjs new file mode 100644 index 00000000..ebb2899a --- /dev/null +++ b/docs/assets/readme/agents.mjs @@ -0,0 +1,67 @@ +// The README "where can each agent be stopped" picture: one card per agent in dashed group boxes, one diamond chip per place a check can run. Every word and count comes from agents.json (agents_data.py); positions are computed here, and `layout` reports every shape so a test can check nothing overlaps. +import { DEFAULT_PALETTE } from './where-chock-sits.mjs'; + +const BW = 840, BP = 10, CG = 8, PER = 6.0, CHIP_H = 20, CHIP_G = 4, COLS = 2; +const CW = (BW - 2 * BP - (COLS - 1) * CG) / COLS; +const chipW = (text) => Math.ceil(text.length * PER + 26); + +// The chips of one agent, strongest first: those its row has, the hook labelled with its grade. +export const chipsOf = (W, r) => W.columns.filter((c) => r[c.id]).map((c) => ({ c, text: c.id === 'hook' ? `${c.label}: ${r.hook}` : c.label })); + +export const layout = (W) => { + const shapes = [], boxes = [], cards = []; + const add = (id, x, y, w, h) => shapes.push({ id, x, y, w, h }); + let y = 12; + [...new Set(W.rows.map((r) => r.plugin))].forEach((kind, bi) => { + const rows = W.rows.filter((r) => r.plugin === kind), top = y; + let cy = y + 30; + for (let i = 0; i < rows.length; i += COLS) { + rows.slice(i, i + COLS).forEach((r, j) => { + const card = { r, x: BP + j * (CW + CG), y: cy, w: CW, h: 36 + CHIP_H + 8, chips: chipsOf(W, r) }; + cards.push(card); + add(`card-${r.id}`, card.x, card.y, card.w, card.h); + }); + cy += 36 + CHIP_H + 8 + CG; + } + const h = cy - CG + BP - top; + boxes.push({ kind, x: 0, y: top, w: BW, h, label: W.groups[kind] }); + add(`box-${bi}`, 0, top, BW, h); + y = top + h + 30; + }); + const legendTop = y; + return { shapes, boxes, cards, legendTop, Ht: legendTop + 26 * W.legend.length + 36 }; +}; + +// Cards closer than their gap, boxes too close, names or one row of chips too wide for a card (chips are sized to their text by the browser; this is the conservative estimate). +export const crowded = (L) => { + const bad = [], near = (a, b, g = 2) => a.x < b.x + b.w + g && b.x < a.x + a.w + g && a.y < b.y + b.h + g && b.y < a.y + a.h + g; + L.shapes.filter((s) => s.id.startsWith('card-')).forEach((a, i, all) => all.slice(i + 1).forEach((b) => { if (near(a, b)) bad.push([a.id, b.id]); })); + L.cards.forEach((c) => { + if (c.r.name.length * 8.2 + 20 > c.w) bad.push([c.r.id, 'name-text']); + if (c.chips.reduce((n, k) => n + chipW(k.text) + CHIP_G, 0) > c.w - 20) bad.push([c.r.id, 'chips-too-wide']); + }); + L.boxes.forEach((b, i) => L.boxes.slice(i + 1).forEach((o) => { if (near(b, o, 12)) bad.push(['box', b.kind, o.kind]); })); + return bad; +}; + +export const where = (page, W, palette = DEFAULT_PALETTE) => { + const L = layout(W), bad = crowded(L); + if (bad.length) throw new Error(`figure shapes too close: ${JSON.stringify(bad)}`); + const { ink: INK, soft: SOFT, line: LINE, paper: PAPER, accent: ACCENT, grey: GREY, chip: CHIP, hollow: HOLLOW, fill: FILL } = palette; + const esc = (s) => s.replace(/&/g, '&').replace(/ `
${inner}
`; + const diamond = (hard, s = 10) => ``; + const tones = [FILL.context, FILL.subagents, FILL.tools], kinds = [...new Set(W.rows.map((r) => r.plugin))]; + const fill = Object.fromEntries(kinds.map((k, i) => [k, tones[i]])); + const boxes = L.boxes.map((b) => abs(b.x, b.y, b.w, b.h, `border:2px dashed ${LINE};border-radius:18px;box-sizing:border-box`, `
${esc(b.label)}
`)).join(''); + const cards = L.cards.map((c) => abs(c.x, c.y, c.w, c.h, `box-sizing:border-box;background:${fill[c.r.plugin]};border:1.5px solid ${LINE};border-radius:12px;padding:10px 8px`, `
${esc(c.r.name)}
`)).join(''); + const chip = (k) => `${diamond(k.c.hard)}${esc(k.text)}`; + const row = (c) => abs(c.x + 10, c.y + 36, c.w - 20, CHIP_H, `display:flex;gap:${CHIP_G}px`, c.chips.map(chip).join('')); + const key = W.legend.map((l, i) => abs(0, L.legendTop + i * 26, BW, 20, `font-size:13px;font-weight:600;color:${SOFT};display:flex;align-items:center;gap:12px;white-space:nowrap`, `${l.hard === null ? '' : diamond(l.hard)}${esc(l.text)}`)).join(''); + return page(`
+
${esc(W.title)}
+
+${boxes}${cards}${L.cards.map(row).join('')}${key} +
${esc(W.footer)}
+
`); +}; diff --git a/docs/assets/readme/agents_data.py b/docs/assets/readme/agents_data.py new file mode 100644 index 00000000..ec5cc591 --- /dev/null +++ b/docs/assets/readme/agents_data.py @@ -0,0 +1,119 @@ +"""Derive agents.json, the data behind the "Which agents, and how strongly Chock holds in each" picture. + +Every row, count and grade is read from chock's code: SURFACE_AGENTS, in_agent_grade, agentseam's matrix and +the plugin warnings data. Only display names and the plain words for a grade are written here. +""" + +from __future__ import annotations + +import json +from importlib.metadata import version +from pathlib import Path + +HERE = Path(__file__).resolve().parent +OUT = HERE / "agents.json" +NAMES = { + "aider": "Aider", + "antigravity": "Antigravity CLI", + "claude": "Claude Code", + "cline": "Cline", + "codex": "Codex", + "copilot": "Copilot", + "cursor": "Cursor", + "devin": "Devin", + "factory-droid": "Factory Droid", + "gemini": "Gemini", + "goose": "goose", + "grok": "Grok", + "junie": "Junie", + "kimi-code": "Kimi Code", + "mistral-vibe": "Mistral Vibe", + "openhands": "OpenHands", + "replit": "Replit", + "tabnine": "Tabnine", + "vscode": "VS Code", + "windsurf": "Windsurf", +} +PLUGIN_AGENT = {"claude-code": "claude"} +GRADE_WORDS = { + "enforced": "fails closed", + "enforceable": "can fail closed", + "fail-to-ask": "asks when it fails", + "best-effort": "fails open", + "detect": "sees it after the fact", + "none": "", +} +WORDS = { + "title": "Where each coding agent can be stopped", + "columns": [["ci", "CI", True], ["git", "commit", True], ["hook", "pre-tool", False], ["rule", "AGENTS.md", False]], + "groups": {"tested live": "One plugin, tested live", "untested": "One plugin, untested", "": "Git hook and CI"}, + "plugin": {"tested": "tested live", "untested": "untested"}, + "legend": [ + {"hard": True, "text": "filled: refuses here"}, + {"hard": False, "text": "hollow: advice, or best effort"}, + {"hard": None, "text": "fails open: if the agent's hook dies, the action goes ahead"}, + ], + "footer": "Read from Chock __CHOCK__ with agentseam __SEAM__. Grades are capped by their evidence.", +} + + +def derive() -> dict: + """The picture's data, read from the code as it is now.""" + import agentseam # noqa: PLC0415 -- chock and agentseam are needed only to derive + from agentseam import matrix # noqa: PLC0415 + + import chock.install # noqa: PLC0415 + from chock.compile.levels import in_agent_grade # noqa: PLC0415 + from chock.compile.surfaces import SURFACE_AGENTS, Surface # noqa: PLC0415 + from chock.vendors import CHOCK_AGENT # noqa: PLC0415 + + data_dir = Path(chock.install.__file__).parent / "data" + clients = json.loads((data_dir / "install.json").read_text(encoding="utf-8"))["clients"] + rules = json.loads((data_dir / "warnings.json").read_text(encoding="utf-8"))["rules"] + untested = {c for r in rules if r["kind"] == "client" and r["says"].startswith("Untested:") for c in r["clients"]} + plugin = {PLUGIN_AGENT.get(cid, cid): "untested" if cid in untested else "tested" for cid in clients} + rows = [] + for agent, surfaces in SURFACE_AGENTS.items(): + own = next((s for s in (Surface.PRE_TOOL_USE, Surface.AGENT_HOOKS) if s in surfaces), None) + grade = in_agent_grade(agent, own.value).level if own else "none" + rows.append( + { + "id": agent, + "name": NAMES[agent], + "ci": Surface.CI_GATE in surfaces, + "git": Surface.GIT_HOOK in surfaces, + "hook_grade": grade, + "hook": GRADE_WORDS[grade], + "matrix_pre_tool": matrix.enforcement_level(CHOCK_AGENT[agent], "pre_tool"), + "plugin": WORDS["plugin"].get(plugin.get(agent, ""), ""), + "rule": Surface.AMBIENT_RULE in surfaces, + } + ) + order = {"tested live": 0, "untested": 1, "": 2} + rows.sort(key=lambda r: (order[r["plugin"]], r["name"].lower())) + count = lambda key, value: sum(1 for r in rows if r[key] == value) # noqa: E731 + counts = { + "agents": len(rows), + "own_hook": sum(1 for r in rows if r["hook_grade"] != "none"), + "plugin_tested": count("plugin", "tested live"), + "plugin_untested": count("plugin", "untested"), + } + footer = WORDS["footer"].replace("__CHOCK__", version("chock")).replace("__SEAM__", agentseam.__version__) + return { + "source": { + "file": "SURFACE_AGENTS, in_agent_grade, agentseam matrix, plugin warnings", + "chock": version("chock"), + }, + "title": WORDS["title"], + "columns": [{"id": i, "label": label, "hard": hard} for i, label, hard in WORDS["columns"]], + "counts": counts, + "groups": WORDS["groups"], + "legend": WORDS["legend"], + "footer": footer, + "rows": rows, + } + + +def write() -> None: + """Rewrite agents.json from the code as it is now.""" + OUT.write_text(json.dumps(derive(), indent=2) + "\n", encoding="utf-8") diff --git a/docs/assets/readme/derive.py b/docs/assets/readme/derive.py index ff4414a6..fd124cd7 100644 --- a/docs/assets/readme/derive.py +++ b/docs/assets/readme/derive.py @@ -4,7 +4,7 @@ derive.py catalog derive.py agentseam derive.py repos (the public repo list, from repos.json) -derive.py readme (README.md's derive blocks, from data.json and chock's install and witness data) +derive.py readme (README.md's derive blocks, from data.json and chock's install and witness data, and agents.json) """ from __future__ import annotations @@ -237,6 +237,9 @@ def main(argv: list[str]) -> None: data.update(derive_agentseam(Path(argv[1]), argv[2])) elif argv[0] == "readme": README.write_text(render_readme(README.read_text(encoding="utf-8"), data), encoding="utf-8") + import agents_data # noqa: PLC0415 -- the picture's data, refreshed by the same command + + agents_data.write() return else: data.update(derive_repos()) diff --git a/docs/assets/readme/render.mjs b/docs/assets/readme/render.mjs index 29702131..e45dc4b4 100644 --- a/docs/assets/readme/render.mjs +++ b/docs/assets/readme/render.mjs @@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'; import path from 'node:path'; import { where, SITE_PALETTE } from './where-chock-sits.mjs'; import { where as sessionPath } from './session-path.mjs'; +import { where as agentsPicture } from './agents.mjs'; const HERE = path.dirname(fileURLToPath(import.meta.url)); const OUT = process.env.OUT_DIR || HERE; @@ -219,10 +220,11 @@ ${grid(3, 16, [[A.grades.enforced, 'matrix cells graded “enforced”: const FIGURE = JSON.parse(readFileSync(path.join(HERE, 'where-chock-sits.json'), 'utf8')); const WHERE = where(page, FIGURE), WHERE_SITE = where(page, FIGURE, SITE_PALETTE), SESSION_PATH = sessionPath(page, FIGURE); +const AGENTS = JSON.parse(readFileSync(path.join(HERE, 'agents.json'), 'utf8')), AGENTS_PNG = agentsPicture(page, AGENTS); const ALL_NEW = { layers: LAYERS, quickstart: QUICKSTART, matrix: MATRIX, catalog: CATALOG, family: FAMILY, honest: HONEST }; // README v2 panels go under v2/; the titled refusal, roles and contribute PNGs at the old paths stay frozen until RW-7b. -const V2 = { 'v2/refusal': REFUSAL, 'v2/roles': ROLES, 'v2/contribute': CONTRIBUTE, 'v2/where-chock-sits': WHERE, 'v2/where-chock-sits-site': WHERE_SITE, 'v2/session-path': SESSION_PATH }; +const V2 = { 'v2/refusal': REFUSAL, 'v2/roles': ROLES, 'v2/contribute': CONTRIBUTE, 'v2/where-chock-sits': WHERE, 'v2/where-chock-sits-site': WHERE_SITE, 'v2/session-path': SESSION_PATH, 'v2/agents': AGENTS_PNG }; // 1280x640 social preview banners: the same specs as the covers, laid out for the fixed canvas. const social = ({ repo, title, sub, chips, right }) => `