From 3dde411c035dd0d01a40e65106f37f8c554a9f9b Mon Sep 17 00:00:00 2001 From: DavidG Date: Wed, 18 Nov 2026 12:08:05 +0100 Subject: [PATCH 1/2] docs: redraw the demo with the approval in lox run (#91) The demo's lox run terminal is now lockhub's own frames (scripts/demo-lox-run.json), fed the ticket lockfile makes of the plan; the agent side shows plan, pending, run and the answers as the CLI prints them. The README caption that said the demo predated lockhub is gone, and the alt text lists each step. Co-Authored-By: Claude Fable 5.2 --- README.md | 3 +- scripts/demo-lox-run.json | 142 ++++++++++++++++++ scripts/demo-svg.py | 306 +++++++++++++++++++++++-------------- site/assets/demo.svg | 307 +++++++++++++++++++------------------- site/index.html | 4 +- 5 files changed, 493 insertions(+), 269 deletions(-) create mode 100644 scripts/demo-lox-run.json diff --git a/README.md b/README.md index 9909956..d502cec 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,8 @@ signed, sandboxed plugins answer, and the agent only ever gets 1s and 0s.

- Demo: an agent (here Claude Code, left) asks three yes/no questions about an invoice. The plan is approved, signed plugins run sandboxed on the file, and only their answers, 1, 1 and 1, reach the agent. + Demo, step by step. 1: an agent (here Claude Code, left) runs lockfile plan with three yes/no plugins on an invoice and is told the plan is pending human approval. 2: the plan shows as a question in lox run (top right), the email address in its key masked. 3: you open the details, read each plugin's question, and press y to approve. 4: the agent runs the ticket; the lockfile console (bottom right) fetches the file and runs the three signed plugins in the sandbox. 5: only their answers, 1, 1 and 1, reach the agent.

-

An agent (here Claude Code, left) and the lockfile console (right). Drawn before approvals moved to lockhub: today you approve the plan in lox run.

Quick start · diff --git a/scripts/demo-lox-run.json b/scripts/demo-lox-run.json new file mode 100644 index 0000000..ea37de7 --- /dev/null +++ b/scripts/demo-lox-run.json @@ -0,0 +1,142 @@ +{ + "ticket": "01M7Q59FPPNANCVCD3M316B421", + "cols": 92, + "rows": 25, + "frames": { + "idle": [ + [["1", " lox run "], ["1;30;42", " AUTO "], ["2", " ~/Documents/billing"], ["", " "], ["32", "● hub up"], ["2", " · 1 lock"]], + [["2", " connected "], ["2", "none yet: a lock connects on its agent's first request"]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [["2", " no ticket yet: every ticket and decision of the hub shows here, masked by its lock"]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["", " "], ["1", "Shift+Tab"], ["2", " mode"], ["", " "], ["1", "a"], ["2", " audit"], ["", " "], ["1", "?"], ["2", " help"], ["", " "], ["1", "q"], ["2", " quit"]] + ], + "question": [ + [["1", " lox run "], ["1;30;42", " AUTO "], ["2", " ~/Documents/billing"], ["", " "], ["32", "● hub up"], ["2", " · 1 lock"], ["2", " · "], ["1;33", "1 waiting"]], + [["2", " connected "], ["2", "none yet: a lock connects on its agent's first request"]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["1;33", " ┌"], ["1;33", " ◆ QUESTION "], ["1", "read"], ["1", " on files "], ["1;33", "──────────────────────────────────────────────────────────────"], ["1;33", "┐"]], + [["1;33", " │ "], ["94;1", "dev-1"], ["2", " asks (unverified name)"], ["2", " · ▤ lockfile"], ["2", " · expires in 59m"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["1", "file plan · 3 answers"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["", " key invoices/"], ["2;3", "‹j***(20)›"], ["", "/2026-10.pdf "], ["1;33", "│"]], + [["1;33", " │ "], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["", " file.non-empty@1.0.0 (official) "], ["1;33", "│"]], + [["1;33", " │ "], ["", " ? Does the file contain at least one byte? 1 = size > 0 0 = the file is empty "], ["1;33", "│"]], + [["1;33", " │ "], ["2", " … 7 more lines: d for details"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["2;3", "personal data touched: email (masked)"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["2", "why asked: this lock's ticket does not name its kind (version 1): asked"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["32;1", "y"], ["2", " approve "], ["31;1", "n"], ["2", " deny "], ["1", "d"], ["2", " details"], ["1", " x"], ["2", " forget profile"], ["", " "], ["1;33", "│"]], + [["1;33", " └────────────────────────────────────────────────────────────────────────────────────────┘"]], + [], + [], + [], + [], + [], + [], + [], + [["", " "], ["2", "12:04:53"], ["", " "], ["94", "dev-1"], ["", " "], ["2", "▤ "], ["", "files "], ["2", "-"], ["", " read key invoices/"], ["2;3", "‹j***(20)›"], ["", "/202… "], ["1;33", "◆ ask:v1"], ["", " "]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["", " "], ["1", "Shift+Tab"], ["2", " mode"], ["", " "], ["1", "y/n"], ["2", " answer"], ["", " "], ["1", "d"], ["2", " details"], ["", " "], ["1", "a"], ["2", " audit"], ["", " "], ["1", "?"], ["2", " help"], ["", " "], ["1", "q"], ["2", " quit"]] + ], + "details": [ + [["1", " lox run "], ["1;30;42", " AUTO "], ["2", " ~/Documents/billing"], ["", " "], ["32", "● hub up"], ["2", " · 1 lock"], ["2", " · "], ["1;33", "1 waiting"]], + [["2", " connected "], ["2", "none yet: a lock connects on its agent's first request"]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["1;33", " ┌"], ["1;33", " ◆ QUESTION "], ["1", "read"], ["1", " on files "], ["1;33", "──────────────────────────────────────────────────────────────"], ["1;33", "┐"]], + [["1;33", " │ "], ["94;1", "dev-1"], ["2", " asks (unverified name)"], ["2", " · ▤ lockfile"], ["2", " · expires in 59m"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["1", "file plan · 3 answers"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["", " key invoices/"], ["2;3", "‹j***(20)›"], ["", "/2026-10.pdf "], ["1;33", "│"]], + [["1;33", " │ "], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["", " file.non-empty@1.0.0 (official) "], ["1;33", "│"]], + [["1;33", " │ "], ["", " ? Does the file contain at least one byte? 1 = size > 0 0 = the file is empty "], ["1;33", "│"]], + [["1;33", " │ "], ["", " pdf.parses@1.0.0 (official) "], ["1;33", "│"]], + [["1;33", " │ "], ["", " ? Does the file parse as a PDF without errors? 1 = pdfcpu reads and validates it…"], ["1;33", "│"]], + [["1;33", " │ "], ["", " pdf.has-blank-page@1.0.0 (official) "], ["1;33", "│"]], + [["1;33", " │ "], ["", " ? Does the PDF have at least one page that paints nothing visible? 1 = at least …"], ["1;33", "│"]], + [["1;33", " │ "], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["", " this plan reveals at most 3 answers about the file "], ["1;33", "│"]], + [["1;33", " │ "], ["", " sha256 6e3f0f55981e42acf8bc1d01ab98fcc9744cc0e8bb06cc9f6f7be104e9e8d071 · 686 bytes "], ["1;33", "│"]], + [["1;33", " │ "], ["2", "note (the agent's, untrusted): "], ["2", "invoice reported as blank"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["2;3", "personal data touched: email (masked)"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["2", "why asked: this lock's ticket does not name its kind (version 1): asked"], ["", " "], ["1;33", "│"]], + [["1;33", " │ "], ["32;1", "y"], ["2", " approve "], ["31;1", "n"], ["2", " deny "], ["1", "d"], ["2", " less"], ["1", " x"], ["2", " forget profile"], ["", " "], ["1;33", "│"]], + [["1;33", " └────────────────────────────────────────────────────────────────────────────────────────┘"]], + [["", " "], ["2", "12:04:53"], ["", " "], ["94", "dev-1"], ["", " "], ["2", "▤ "], ["", "files "], ["2", "-"], ["", " read key invoices/"], ["2;3", "‹j***(20)›"], ["", "/202… "], ["1;33", "◆ ask:v1"], ["", " "]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["", " "], ["1", "Shift+Tab"], ["2", " mode"], ["", " "], ["1", "y/n"], ["2", " answer"], ["", " "], ["1", "d"], ["2", " details"], ["", " "], ["1", "a"], ["2", " audit"], ["", " "], ["1", "?"], ["2", " help"], ["", " "], ["1", "q"], ["2", " quit"]] + ], + "approved": [ + [["1", " lox run "], ["1;30;42", " AUTO "], ["2", " ~/Documents/billing"], ["", " "], ["32", "● hub up"], ["2", " · 1 lock"]], + [["2", " connected "], ["2", "none yet: a lock connects on its agent's first request"]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [["", " "], ["2", "12:04:53"], ["", " "], ["94", "dev-1"], ["", " "], ["2", "▤ "], ["", "files "], ["2", "-"], ["", " read key invoices/"], ["2;3", "‹j***(20)›"], ["", "/202… "], ["32", "✔ you"], ["", " "]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["", " "], ["1", "Shift+Tab"], ["2", " mode"], ["", " "], ["1", "a"], ["2", " audit"], ["", " "], ["1", "?"], ["2", " help"], ["", " "], ["1", "q"], ["2", " quit"]] + ], + "ran": [ + [["1", " lox run "], ["1;30;42", " AUTO "], ["2", " ~/Documents/billing"], ["", " "], ["32", "● hub up"], ["2", " · 1 lock"]], + [["2", " connected "], ["2", "none yet: a lock connects on its agent's first request"]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [], + [["", " "], ["2", "12:04:53"], ["", " "], ["94", "dev-1"], ["", " "], ["2", "▤ "], ["", "files "], ["2", "-"], ["", " read key invoices/"], ["2;3", "‹j***(20)›"], ["", "/202… "], ["32", "✔ you"], ["32", " ✓"], ["", " "]], + [["2", "────────────────────────────────────────────────────────────────────────────────────────────"]], + [["", " "], ["1", "Shift+Tab"], ["2", " mode"], ["", " "], ["1", "a"], ["2", " audit"], ["", " "], ["1", "?"], ["2", " help"], ["", " "], ["1", "q"], ["2", " quit"]] + ] + } +} diff --git a/scripts/demo-svg.py b/scripts/demo-svg.py index 9151642..88c02db 100644 --- a/scripts/demo-svg.py +++ b/scripts/demo-svg.py @@ -2,20 +2,35 @@ """Generates site/assets/demo.svg: lockfile's value in one looping image. An agent asks three yes/no questions about an invoice it must never read. The -human approves the plan in the lockfile console, the console fetches the file -and runs three signed, sandboxed plugins on it, and only their answers cross -the socket back to the agent: 1, 1, 1. Pure SVG + CSS keyframes on one 14 s -clock, so it plays on GitHub, on the site and in any browser. - -Every command, flag and output line is the CLI's real text (cmd/lockfile, -internal/backend/screen.go, the marketplace manifests); the agent's closing -remark is the only prose. +plan goes to lockhub as a ticket, the human reads it and approves it in +`lox run`, the agent runs the ticket, the lockfile console fetches the file and +runs three signed, sandboxed plugins on it, and only their answers cross the +socket back to the agent: 1, 1, 1. Pure SVG + CSS keyframes on one clock, so it +plays on GitHub, on the site and in any browser. + +No on-screen text is invented: + +- the `lox run` terminal is scripts/demo-lox-run.json, frames drawn by + lockhub's own renderer (internal/loxrun, a Session at 92x25 fed the ticket + below; see the capture note in that pull request, DavidGodefroid/lockfile#91). + The ticket's screen is what internal/backend (planScreen, hubScreens) makes + of this plan with the official marketplace's manifests of the three plugins; +- the agent's commands are the CLI's (docs/usage.md, "The agent side"); the + pending line is lockkit's mcpkit.PendingText, the result lines are + cmd/lockfile resultLines, the handle has workspace.newHandle's shape; +- the sandbox line is docs/security-model.md's; the answers are those of the + three plugins run on the file whose sha256 and size the ticket shows. + +The agent's closing remark and the captions are the only prose. python3 scripts/demo-svg.py > site/assets/demo.svg """ -LOOP = 14.0 -END = 13.4 # everything fades out here, then the loop restarts +import json +import pathlib + +LOOP = 17.0 +END = 16.4 # everything fades out here, then the loop restarts # The Lock Family's terminal: warm carbon backgrounds (lockfamily assets/tokens.css, # --term-bg) and its dim text; the accents stay as they were. C = dict(crust="#1a1814", base="#221f1a", mantle="#2a2620", s0="#38332b", s1="#4a443a", @@ -24,6 +39,11 @@ FONT = "'JetBrains Mono','SF Mono',Menlo,Consolas,'DejaVu Sans Mono',monospace" SANS = "Inter,'Segoe UI',system-ui,-apple-system,Helvetica,Arial,sans-serif" +LOX = json.loads((pathlib.Path(__file__).parent / "demo-lox-run.json").read_text(encoding="utf-8")) +TICKET = LOX["ticket"] +KEY = "invoices/jane.doe@example.com/2026-10.pdf" +HANDLE = "f_G9Qf4otbDr" + css, body = [], [] n = 0 @@ -85,46 +105,57 @@ def label(x, y, s, col=C["ov"]): return text(x, y, s, size=13, col=col, weight=700, family=SANS) -W, H = 1200, 640 +W, H = 1200, 710 body.append(f'') # --- The agent's account (left) -------------------------------------------------------------- -AX, AY, AW, AH = 30, 96, 450, 444 -body.append(label(AX, 70, "YOUR AGENT · its own account")) +AX, AY, AW, AH = 30, 56, 420, 554 +AS, AL = 11.5, 19 # the agent terminal's font size and line height +body.append(label(AX, AY - 26, "YOUR AGENT · its own account")) body.append(f'') body.append(text(AX + 18, AY + 30, "✻ Claude Code", size=13, col=C["amber"])) +T_PLAN, T_ASK, T_DETAILS, T_YES, T_RUN, T_DONE = 0.3, 2.4, 4.6, 7.6, 8.2, 12.3 + cmd = [ - (0.3, [("> ", C["sub"]), ("lockfile plan \\", C["text"])]), - (0.5, [(" --key ", C["text"]), ("invoices/2026/10/abc123.pdf \\", C["teal"])]), - (0.7, [(" --plugin ", C["text"]), ("file.non-empty \\", C["blue"])]), - (0.9, [(" --plugin ", C["text"]), ("pdf.parses \\", C["blue"])]), - (1.1, [(" --plugin ", C["text"]), ("pdf.has-blank-page \\", C["blue"])]), - (1.3, [(" --intent ", C["text"]), ('"invoice reported as blank" \\', C["sub"])]), - (1.5, [(" --run", C["text"])]), + (0.0, [("> ", C["sub"]), ("lockfile plan \\", C["text"])]), + (0.2, [(" --key ", C["text"]), (KEY + " \\", C["teal"])]), + (0.4, [(" --plugin ", C["text"]), ("file.non-empty \\", C["blue"])]), + (0.6, [(" --plugin ", C["text"]), ("pdf.parses \\", C["blue"])]), + (0.8, [(" --plugin ", C["text"]), ("pdf.has-blank-page \\", C["blue"])]), + (1.0, [(" --intent ", C["text"]), ('"invoice reported as blank"', C["sub"])]), ] for i, (t, parts) in enumerate(cmd): - body.append(spans(AX + 18, AY + 66 + i * 22, parts, cls=show(t))) - -# The result: exactly what `lockfile plan --run` prints, one line per answer. -RY = AY + 238 + body.append(spans(AX + 18, AY + 62 + i * AL, parts, cls=show(T_PLAN + t), size=AS)) + +# What `lockfile plan` prints: one line, wrapped here as a terminal wraps it. +pending = ["Pending human approval: ticket", + f"{TICKET} on lockfile. Do not retry.", + "End your turn; you will be told when it is decided."] +for i, s in enumerate(pending): + body.append(text(AX + 18, AY + 186 + i * AL, s, cls=show(T_ASK + 0.1), size=AS, col=C["amber"])) + +# The ticket is run once decided: exactly what `lockfile run TICKET` prints. +RY = AY + 262 +body.append(spans(AX + 18, RY, [("> ", C["sub"]), ("lockfile run " + TICKET, C["text"])], + cls=show(T_RUN), size=AS)) result = [ - (8.5, [("handle ", C["sub"]), ("f_8Kq2xR", C["text"])]), - (8.7, [("file.non-empty@1.0.0: ", C["text"]), ("1", C["green"])]), - (8.9, [("pdf.parses@1.0.0: ", C["text"]), ("1", C["green"])]), - (9.1, [("pdf.has-blank-page@1.0.0: ", C["text"]), ("1", C["green"])]), + (0.0, [("handle ", C["sub"]), (HANDLE, C["text"])]), + (0.2, [("file.non-empty@1.0.0: ", C["text"]), ("1", C["green"])]), + (0.4, [("pdf.parses@1.0.0: ", C["text"]), ("1", C["green"])]), + (0.6, [("pdf.has-blank-page@1.0.0: ", C["text"]), ("1", C["green"])]), ] for i, (t, parts) in enumerate(result): - body.append(spans(AX + 18, RY + i * 22, parts, cls=show(t))) -body.append(text(AX + 18, RY + 104, "✻ It parses and has a blank page:", cls=show(9.8), - col=C["amber"])) -body.append(text(AX + 18, RY + 126, " the bug is in rendering, not the upload.", cls=show(9.8), - col=C["amber"])) + body.append(spans(AX + 18, RY + (i + 1) * AL, parts, cls=show(T_DONE + t), size=AS)) +body.append(text(AX + 18, RY + 116, "✻ It parses and has a blank page:", cls=show(13.4), + size=12.5, col=C["amber"])) +body.append(text(AX + 18, RY + 136, " the bug is in rendering, not the upload.", cls=show(13.4), + size=12.5, col=C["amber"])) # What never reaches the agent, struck out. never = ["bytes", "name", "size", "type", "path"] -g = [f'', +g = [f'', text(AX + 18, AY + AH - 46, "never sent to the agent:", size=12, col=C["ov"], family=SANS)] x = AX + 18 for s in never: @@ -138,109 +169,166 @@ def label(x, y, s, col=C["ov"]): g.append("") body.append("".join(g)) -# --- The socket between the two accounts ----------------------------------------------------- -SX = 510 +# --- The socket between the agent and the lock ----------------------------------------------- +SX = 466 body.append(f'') -body.append(text(SX, AY + 6, "socket", size=12, col=C["ov"], weight=700, family=SANS, +body.append(text(SX, AY - 10, "socket", size=12, col=C["ov"], weight=700, family=SANS, anchor="middle")) -# --- The lockfile account (right) ------------------------------------------------------------ -X0, Y0, X1, Y1 = 540, 96, 1170, 540 -wall = flash(4.6, C["teal"], base=C["deep"], hold=0.5) -body.append(f'') -body.append(f'') -body.append(text(X0 + 169, Y0 + 5, "lockfile account · your console", size=13, col=C["crust"], +# --- lox run, your terminal (top right): lockhub's own frames -------------------------------- +X0, X1 = 482, 1170 +TY, TS, CW, LH = AY, 11.5, 6.9, 14.4 +TH = 26 + LOX["rows"] * LH + 8 +TXT = X0 + (X1 - X0 - LOX["cols"] * CW) / 2 +body.append(f'') +body.append(f'') +body.append(text(X0 + 124, TY + 5, "lox run · your terminal", size=13, col=C["crust"], weight=700, family=SANS, anchor="middle")) -# The approval screen, as the console draws it. -QX, QY = X0 + 20, Y0 + 32 -body.append(f'') -B = C["s1"] -screen = [ - [("╭─ ", B), ("SAMPLES · file plan · 3 answers", C["text"]), (" ─────", B)], - [("│ ", B), ("requested by uid 1000 (alice) · pid 48211 · exe /usr/local/bin/lockfile", C["ov"])], - [("│ ", B), ("agent: invoice reported as blank", C["sub"])], - [("│ ", B), ("key ", C["sub"]), ("invoices/2026/10/abc123.pdf", C["teal"])], - [("│ ", B), ("file.non-empty@1.0.0 (official)", C["blue"])], - [("│ ", B), (" ? Does the file contain at least one byte? 1 = size > 0 0 = the…", C["text"])], - [("│ ", B), ("pdf.parses@1.0.0 (official)", C["blue"])], - [("│ ", B), (" ? Does the file parse as a PDF without errors? 1 = pdfcpu reads…", C["text"])], - [("│ ", B), ("pdf.has-blank-page@1.0.0 (official)", C["blue"])], - [("│ ", B), (" ? Does the PDF have at least one page that paints nothing visible?…", C["text"])], - [("│ ", B), ("this plan reveals at most 3 answers about the file", C["amber"])], -] -for i, parts in enumerate(screen): - body.append(spans(QX + 14, QY + 26 + i * 18, parts, cls=show(2.5 + i * 0.07), size=11.5)) -body.append(spans(QX + 14, QY + 26 + 11 * 18 + 4, - [("╰─ ", B), ("Approve? [y/N] ", C["text"])], cls=show(3.4), size=11.5)) -body.append(text(QX + 14 + 18 * 6.9, QY + 26 + 11 * 18 + 4, "y", cls=show(4.6), size=11.5, - col=C["green"], weight=700)) -body.append(f'' - + text(X1 - 95, QY + 227, "approved", size=12, col=C["crust"], weight=700, - family=SANS, anchor="middle") + "") - -# The source and the sandbox. -FY = Y0 + 284 -body.append(f'') -body.append(label(QX + 16, FY + 26, "SOURCE")) -body.append(text(QX + 16, FY + 52, "local", size=13)) -body.append(text(QX + 16, FY + 72, "/srv/samples", size=12, col=C["sub"])) -body.append(text(QX + 16, FY + 92, "s3 · sftp · local", size=11, col=C["ov"], family=SANS)) -# A document icon: the file, fetched once. +# The colours of lox run's SGR styles (lockhub internal/loxrun/style.go), on this palette. +FG = {"30": C["crust"], "31": C["red"], "32": C["green"], "33": C["amber"], "94": C["blue"]} +BG = {"42": C["green"]} +# Box-drawing characters as (left, right, up, down) half-strokes. +BOX = {"─": (1, 1, 0, 0), "│": (0, 0, 1, 1), "┌": (0, 1, 0, 1), "┐": (1, 0, 0, 1), + "└": (0, 1, 1, 0), "┘": (1, 0, 1, 0)} + + +def terminal(lines, cls): + out = [f''] + for row, segs in enumerate(lines): + y = TY + 36 + row * LH + col, parts = 0, [] + for sgr, s in segs: + codes = sgr.split(";") if sgr else [] + x = TXT + col * CW + col += len(s) + if not s.strip() and not any(c in BG for c in codes): + continue + fill = C["sub"] if "2" in codes else C["text"] + for c in codes: + fill = FG.get(c, fill) + # The frames and rules are drawn as lines, so they join whatever font is used. + if set(s) <= set(BOX) | {" "}: + cy, d = y - 10.5 + LH / 2, [] + if set(s) == {"─"}: # a rule: one stroke + d.append(f"M{x:.1f} {cy:.1f}h{len(s) * CW:.1f}") + s = "" + for i, ch in enumerate(s): + cx = x + (i + 0.5) * CW + le, ri, up, dn = BOX.get(ch, (0, 0, 0, 0)) + if le or ri: + d.append(f"M{cx - le * CW / 2:.1f} {cy:.1f}h{(le + ri) * CW / 2:.1f}") + if up or dn: + d.append(f"M{cx:.1f} {cy - up * LH / 2:.1f}v{(up + dn) * LH / 2:.1f}") + out.append(f'') + continue + for c in codes: + if c in BG: + out.append(f'') + attrs = f'x="{x:.1f}" fill="{fill}"' + if "1" in codes: + attrs += ' font-weight="700"' + if "3" in codes: + attrs += ' font-style="italic"' + parts.append(f'{esc(s)}') + if parts: + out.append(f'{"".join(parts)}') + out.append("") + return "".join(out) + + +frames = [("idle", 0.05, T_ASK), ("question", T_ASK, T_DETAILS), ("details", T_DETAILS, T_YES), + ("approved", T_YES, T_DONE), ("ran", T_DONE, END)] +for name, t0, t1 in frames: + body.append(terminal(LOX["frames"][name], show(t0, t1, fade=0.05))) + +# The keys you press, next to the terminal's name (lox run does not echo them). +for t, key, what in [(T_DETAILS, "d", "details"), (T_YES, "y", "approve")]: + body.append(f'' + f'' + + text(X1 - 98, TY - 23, f"you press {key}: {what}", size=12.5, col=C["crust"], + weight=700, family=SANS, anchor="middle") + "") + +# --- The lockfile console, in its own account (bottom right) --------------------------------- +Y0 = TY + TH + 24 +Y1 = AY + AH +body.append(f'') +body.append(f'') +body.append(text(X0 + 169, Y0 + 5, "lockfile console · its own account", size=13, col=C["text"], + weight=700, family=SANS, anchor="middle")) + +QX, FY, FH = X0 + 16, Y0 + 22, Y1 - Y0 - 34 +T_FETCH = T_RUN + 0.9 +body.append(f'') +body.append(label(QX + 14, FY + 22, "SOURCE")) +body.append(text(QX + 14, FY + 42, "local", size=12.5)) +body.append(text(QX + 14, FY + 60, "/srv/lockfile/samples", size=11.5, col=C["sub"])) +body.append(text(QX + 14, FY + 78, "s3 · sftp · local", size=11, col=C["ov"], family=SANS)) +# A document icon: the file, fetched for the run. doc = (f'' f'') -body.append(f'{doc}') +DX, DY = QX + 162, FY + 8 +body.append(f'{doc}') -SBX, SBW = QX + 196, X1 - X0 - 236 -body.append(f'') -body.append(label(SBX + 16, FY + 26, "SANDBOX", col=C["teal"])) -body.append(text(SBX + SBW - 16, FY + 26, "fd 3 read-only · no network · 3-byte stdout", +body.append(label(SBX + 14, FY + 22, "SANDBOX", col=C["teal"])) +body.append(text(SBX + SBW - 14, FY + 22, "fd 3 read-only · no network · 3-byte stdout", size=11, col=C["sub"], family=SANS, anchor="end")) -plugins = [("file.non-empty", 5.9), ("pdf.parses", 6.5), ("pdf.has-blank-page", 7.1)] -for i, (name, t) in enumerate(plugins): - y = FY + 56 + i * 28 - body.append(text(SBX + 16, y, name, size=13, col=C["blue"])) +plugins = [("file.non-empty", T_FETCH + 1.0), ("pdf.parses", T_FETCH + 1.6), + ("pdf.has-blank-page", T_FETCH + 2.2)] +PY = [FY + 44 + i * 21 for i in range(3)] +for (name, t), y in zip(plugins, PY): + body.append(text(SBX + 14, y, name, size=12.5, col=C["blue"])) body.append(f'' - + text(SBX + SBW - 30, y, "…", size=13, col=C["ov"], anchor="middle") + "") - body.append(f'' - + text(SBX + SBW - 30, y, "1", size=13, col=C["crust"], weight=700, + + text(SBX + SBW - 28, y, "…", size=13, col=C["ov"], anchor="middle") + "") + body.append(f'' + + text(SBX + SBW - 28, y, "1", size=12.5, col=C["crust"], weight=700, anchor="middle") + "") -# Packets: the plan goes in, the file goes into the sandbox, three bits come out. -body.append(f'') -body.append(f'' +# Packets: the plan goes out as a ticket, the run goes to the console, the file goes into +# the sandbox, three bits come out. +body.append(f'') +body.append(f'') +body.append(f'' f'{doc}') for i in range(3): - t0 = 7.7 + i * 0.15 + t0 = T_FETCH + 2.5 + i * 0.15 bit = (f'' + text(0, 5, "1", size=13, col=C["crust"], weight=700, anchor="middle")) - body.append(f'' + body.append(f'' f'{bit}') # Captions. -caps = [(0.0, 2.4, "Your agent asks yes/no questions about a file."), - (2.4, 5.0, "You approve every plan, in a console it cannot drive."), - (5.0, 7.6, "Signed plugins run sandboxed on the file."), - (7.6, END + 0.2, "The agent only ever sees 1s and 0s.")] +caps = [(0.0, T_ASK, "Your agent asks yes/no questions about a file."), + (T_ASK, T_RUN, "You read the plan and approve it in lox run."), + (T_RUN, T_FETCH + 2.5, "Signed plugins run sandboxed on the file."), + (T_FETCH + 2.5, END + 0.2, "The agent only ever sees 1s and 0s.")] for t0, t1, s in caps: - body.append(text(W / 2, 598, s, cls=show(t0 + 0.05, t1 - 0.2), size=26, weight=650, + body.append(text(W / 2, H - 44, s, cls=show(t0 + 0.05, t1 - 0.2), size=26, weight=650, family=SANS, anchor="middle")) print(f'') print("lockfile: your agent asks about the file, it never reads it") print("") print("\n".join(body)) print("") diff --git a/site/assets/demo.svg b/site/assets/demo.svg index efdb834..5151bae 100644 --- a/site/assets/demo.svg +++ b/site/assets/demo.svg @@ -1,159 +1,154 @@ - + lockfile: your agent asks about the file, it never reads it - - -YOUR AGENT · its own account - -✻ Claude Code -> lockfile plan \ - --key invoices/2026/10/abc123.pdf \ - --plugin file.non-empty \ - --plugin pdf.parses \ - --plugin pdf.has-blank-page \ - --intent "invoice reported as blank" \ - --run -handle f_8Kq2xR -file.non-empty@1.0.0: 1 -pdf.parses@1.0.0: 1 -pdf.has-blank-page@1.0.0: 1 -✻ It parses and has a blank page: - the bug is in rendering, not the upload. -never sent to the agent:bytesnamesizetypepath - -socket - - -lockfile account · your console - -╭─ SAMPLES · file plan · 3 answers ───── -│ requested by uid 1000 (alice) · pid 48211 · exe /usr/local/bin/lockfile -│ agent: invoice reported as blank -│ key invoices/2026/10/abc123.pdf -│ file.non-empty@1.0.0 (official) -│ ? Does the file contain at least one byte? 1 = size > 0 0 = the… -│ pdf.parses@1.0.0 (official) -│ ? Does the file parse as a PDF without errors? 1 = pdfcpu reads… -│ pdf.has-blank-page@1.0.0 (official) -│ ? Does the PDF have at least one page that paints nothing visible?… -│ this plan reveals at most 3 answers about the file -╰─ Approve? [y/N] -y -approved - -SOURCE -local -/srv/samples -s3 · sftp · local - - -SANDBOX -fd 3 read-only · no network · 3-byte stdout -file.non-empty -… -1 -pdf.parses -… -1 -pdf.has-blank-page -… -1 - - + + +YOUR AGENT · its own account + +✻ Claude Code +> lockfile plan \ + --key invoices/jane.doe@example.com/2026-10.pdf \ + --plugin file.non-empty \ + --plugin pdf.parses \ + --plugin pdf.has-blank-page \ + --intent "invoice reported as blank" +Pending human approval: ticket +01M7Q59FPPNANCVCD3M316B421 on lockfile. Do not retry. +End your turn; you will be told when it is decided. +> lockfile run 01M7Q59FPPNANCVCD3M316B421 +handle f_G9Qf4otbDr +file.non-empty@1.0.0: 1 +pdf.parses@1.0.0: 1 +pdf.has-blank-page@1.0.0: 1 +✻ It parses and has a blank page: + the bug is in rendering, not the upload. +never sent to the agent:bytesnamesizetypepath + +socket + + +lox run · your terminal + lox run AUTO ~/Documents/billing● hub up · 1 lock connected none yet: a lock connects on its agent's first request no ticket yet: every ticket and decision of the hub shows here, masked by its lockShift+Tab modea audit? helpq quit + lox run AUTO ~/Documents/billing● hub up · 1 lock · 1 waiting connected none yet: a lock connects on its agent's first request ◆ QUESTION read on files dev-1 asks (unverified name) · ▤ lockfile · expires in 59mfile plan · 3 answers key invoices/‹j***(20)›/2026-10.pdf file.non-empty@1.0.0 (official) ? Does the file contain at least one byte? 1 = size > 0 0 = the file is empty … 7 more lines: d for detailspersonal data touched: email (masked)why asked: this lock's ticket does not name its kind (version 1): askedy approve n deny d details x forget profile12:04:53dev-1▤ files - read key invoices/‹j***(20)›/202… ◆ ask:v1Shift+Tab modey/n answerd detailsa audit? helpq quit + lox run AUTO ~/Documents/billing● hub up · 1 lock · 1 waiting connected none yet: a lock connects on its agent's first request ◆ QUESTION read on files dev-1 asks (unverified name) · ▤ lockfile · expires in 59mfile plan · 3 answers key invoices/‹j***(20)›/2026-10.pdf file.non-empty@1.0.0 (official) ? Does the file contain at least one byte? 1 = size > 0 0 = the file is empty pdf.parses@1.0.0 (official) ? Does the file parse as a PDF without errors? 1 = pdfcpu reads and validates it… pdf.has-blank-page@1.0.0 (official) ? Does the PDF have at least one page that paints nothing visible? 1 = at least … this plan reveals at most 3 answers about the file sha256 6e3f0f55981e42acf8bc1d01ab98fcc9744cc0e8bb06cc9f6f7be104e9e8d071 · 686 bytes note (the agent's, untrusted): invoice reported as blankpersonal data touched: email (masked)why asked: this lock's ticket does not name its kind (version 1): askedy approve n deny d less x forget profile12:04:53dev-1▤ files - read key invoices/‹j***(20)›/202… ◆ ask:v1Shift+Tab modey/n answerd detailsa audit? helpq quit + lox run AUTO ~/Documents/billing● hub up · 1 lock connected none yet: a lock connects on its agent's first request12:04:53dev-1▤ files - read key invoices/‹j***(20)›/202… ✔ youShift+Tab modea audit? helpq quit + lox run AUTO ~/Documents/billing● hub up · 1 lock connected none yet: a lock connects on its agent's first request12:04:53dev-1▤ files - read key invoices/‹j***(20)›/202… ✔ you ✓Shift+Tab modea audit? helpq quit +you press d: details +you press y: approve + + +lockfile console · its own account + +SOURCE +local +/srv/lockfile/samples +s3 · sftp · local + + +SANDBOX +fd 3 read-only · no network · 3-byte stdout +file.non-empty +… +1 +pdf.parses +… +1 +pdf.has-blank-page +… +1 + + + +1 +1 1 -1 -1 -Your agent asks yes/no questions about a file. -You approve every plan, in a console it cannot drive. -Signed plugins run sandboxed on the file. -The agent only ever sees 1s and 0s. +Your agent asks yes/no questions about a file. +You read the plan and approve it in lox run. +Signed plugins run sandboxed on the file. +The agent only ever sees 1s and 0s. diff --git a/site/index.html b/site/index.html index 3a732ab..836b813 100644 --- a/site/index.html +++ b/site/index.html @@ -93,8 +93,8 @@

Your agent asks about the file. It never r

See it run

- An agent asks three yes/no questions about an invoice. The plan is approved, signed plugins run sandboxed on the file, and only their answers, 1, 1 and 1, reach the agent. -
An agent (here Claude Code, left, in its own account) asks three questions about an invoice. The lockfile console (right) fetches the file into the sandbox and sends back one bit per plugin. Drawn before approvals moved to lockhub: today you approve the plan in lox run.
+ Step by step. 1: an agent runs lockfile plan with three yes/no plugins on an invoice and is told the plan is pending human approval. 2: the plan shows as a question in lox run, the email address in its key masked. 3: you open the details, read each plugin's question, and press y to approve. 4: the agent runs the ticket; the lockfile console fetches the file and runs the three signed plugins in the sandbox. 5: only their answers, 1, 1 and 1, reach the agent. +
An agent (here Claude Code, left, in its own account) asks three questions about an invoice. You approve the plan in lox run (top right). The lockfile console (bottom right) fetches the file into the sandbox and sends back one bit per plugin.
From 249b8d89bff8da0bb927cc27e396dcdecadd0290 Mon Sep 17 00:00:00 2001 From: DavidG Date: Wed, 18 Nov 2026 12:36:41 +0100 Subject: [PATCH 2/2] docs: say in the repo how the demo's lox run frames were captured (#91) The capture note (lockhub commit, lockkit version, test harness, the header lines a live session adds) is in the generator's docstring and in the JSON's note key; the reduced-motion still is the approval card. Co-Authored-By: Claude Fable 5.2 --- scripts/demo-lox-run.json | 1 + scripts/demo-svg.py | 26 ++++++++++++++++++-------- site/assets/demo.svg | 2 +- 3 files changed, 20 insertions(+), 9 deletions(-) diff --git a/scripts/demo-lox-run.json b/scripts/demo-lox-run.json index ea37de7..cec5b27 100644 --- a/scripts/demo-lox-run.json +++ b/scripts/demo-lox-run.json @@ -1,4 +1,5 @@ { + "note": "Frames written by lockhub's lox run renderer (internal/loxrun at commit 4d94ef1, with lockkit v0.20.0): a Session on a 92x25 colour terminal in that package's test harness (hub queue in memory), fed one signed version-1 read_pii ticket of lock lockfile, instance files, agent dev-1, carrying the screen lockfile's internal/backend (planScreen, hubScreens) makes of the demo's plan. Keys sent: d, then y; then the hub state consumed. Not a live session: the harness follows no lock console, so the header lacks the 'locks ... serving' line and the tabs line a real lox run serving a lockfile console draws, and the ticket was built for the capture, not sent by a running console. Each segment is [SGR parameters, text].", "ticket": "01M7Q59FPPNANCVCD3M316B421", "cols": 92, "rows": 25, diff --git a/scripts/demo-svg.py b/scripts/demo-svg.py index 88c02db..bb198ad 100644 --- a/scripts/demo-svg.py +++ b/scripts/demo-svg.py @@ -8,13 +8,22 @@ socket back to the agent: 1, 1, 1. Pure SVG + CSS keyframes on one clock, so it plays on GitHub, on the site and in any browser. -No on-screen text is invented: - -- the `lox run` terminal is scripts/demo-lox-run.json, frames drawn by - lockhub's own renderer (internal/loxrun, a Session at 92x25 fed the ticket - below; see the capture note in that pull request, DavidGodefroid/lockfile#91). - The ticket's screen is what internal/backend (planScreen, hubScreens) makes - of this plan with the official marketplace's manifests of the three plugins; +No on-screen text is typed by hand, but this is not a recording of a live +session. Each screen is drawn by the code that draws it for real, run on the +demo's plan: + +- the `lox run` terminal is scripts/demo-lox-run.json: the frames lockhub's + own renderer wrote (internal/loxrun at 4d94ef1, lockkit v0.20.0), from a + Session on a 92x25 colour terminal in that package's test harness (a hub + queue in memory, a signed ticket), with the keys d then y, then the hub + state "consumed". Two limits follow. The harness follows no lock console, + so the header lacks the `locks … serving` line and the tabs line that a + real `lox run` serving a lockfile console draws. And the ticket was built + for the capture, as lockkit's console builds a plan's ticket (version 1, + read_pii, lock lockfile, instance files), not sent by a running console. + Its screen is what internal/backend (planScreen, hubScreens) makes of this + plan with the official marketplace's manifests of the three plugins. The + same note is in the JSON file's "note" key; - the agent's commands are the CLI's (docs/usage.md, "The agent side"); the pending line is lockkit's mcpkit.PendingText, the result lines are cmd/lockfile resultLines, the handle has workspace.newHandle's shape; @@ -327,8 +336,9 @@ def terminal(lines, cls): f'it in lox run; the agent runs the ticket, signed plugins run sandboxed on the file, ' f'and only their answers, 1, 1 and 1, reach the agent.">') print("lockfile: your agent asks about the file, it never reads it") +# Without motion: the still is the approval card, details open. print("") print("\n".join(body)) print("") diff --git a/site/assets/demo.svg b/site/assets/demo.svg index 5151bae..7357b9f 100644 --- a/site/assets/demo.svg +++ b/site/assets/demo.svg @@ -86,7 +86,7 @@ .k42{animation:k42 17.0s linear infinite} @keyframes k43{0.00%{opacity:0} 68.53%{opacity:0} 69.71%{opacity:1} 96.47%{opacity:1} 97.65%{opacity:0} 100.00%{opacity:0}} .k43{animation:k43 17.0s linear infinite} -@media (prefers-reduced-motion: reduce){*{animation-delay:-15s!important;animation-play-state:paused!important}} +@media (prefers-reduced-motion: reduce){*{animation-delay:-6s!important;animation-play-state:paused!important}} YOUR AGENT · its own account