Skip to content

feat: ship the BirdsBirdBirds challenge - #12

Merged
theycallmeswift merged 13 commits into
mainfrom
claude/issue-7-birdsbirdbirds
Oct 16, 2026
Merged

theycallmeswift merged 13 commits into
mainfrom
claude/issue-7-birdsbirdbirds

Conversation

@theycallmeswift

@theycallmeswift theycallmeswift commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Adds birdsbirdbirds/, a 10-minute terminal challenge. Pi opens a local drawing page and the participant draws a bird; saving it prompts Pi to look at the drawing and ask about the bird. Pi then writes a CSS flight for the bird, which a checker gates, and the bird flies across the same page. It's published to the booth gallery only after a yes.

Closes #7

First checkpoint: passes. Pi 1.0.4's read tool sends a PNG to google/gemini-3.8-flash as an image. In the source:

  • read detects images by their magic bytes and returns an image content block.
  • pi-ai's model registry lists gemini-3.8-flash with input: ["text", "image"].
  • The Google provider sends the image as inlineData in functionResponse.parts.

A live run with GEMINI_API_KEY described a test PNG correctly. Caveats:

  • An animated PNG is read as text.
  • Images over 2000 px or 4.5 MB are resized.

Neither caveat applies to the page's 512×512 canvas export.

What's in the package:

  • check-bird.mjs validates bird.json, both as a CLI for Pi and as checkBird for the server. It uses a strict tokenizer and parser:

    • exactly one @keyframes fly_… block;
    • only transform (allowlisted functions, each with its own unit class), opacity, and animation-timing-function;
    • no url(, @import, other at-rules, escapes, quotes, <, or comments;
    • size caps on the file, the keyframes, and the labels;
    • no invisible or bidi control characters in labels (every Cf character except the joiners, plus line and paragraph separators, the Hangul fillers, and the braille blank).

    Errors tell Pi what to change, and never echo a raw control character. All 26 entries in BirdsBirdBirds' manifest.json pass once id and image are stripped.

  • server.mjs binds only to 127.0.0.1:4322. It checks Host (against DNS rebinding) and Origin, and sends a strict CSP with no 'unsafe-inline'. The checked keyframes reach the page through a constructed stylesheet.

    • POST /bird.png needs Content-Type: image/png, a PNG signature plus IHDR, and at most 2 MiB. The server writes bird.png atomically and nothing else.
    • GET /bird.json serves the entry only once it passes the checker.
    • Workspace reads refuse symlinks and FIFOs, and are capped.
  • extension.mjs and bird-watcher.mjs: a Pi extension declared in plugin.json, using Node built-ins only, so there is no install hook. It watches the workspace for a new bird.png, debounced and deduplicated by content hash. When one appears, it sends Pi a follow-up message, so Pi reads the drawing, describes it and reports draw-bird without being asked. It stops on session shutdown and never keeps Pi alive.

  • setup / cleanup.

    • setup starts the server in its own process group, with output to a log, and exits once /health returns this instance's hash. If the port is busy, it fails with a message naming the port.
    • cleanup stops the server with a token-authenticated POST /shutdown. It is idempotent and safe after a failed setup.
  • The page has two modes:

    • Draw mode has colours, pen sizes, an eraser, undo, clear, and a transparent canvas.
    • Sky mode uses the flight logic ported from BirdsBirdBirds' index.html. It injects the keyframes only after the server has checked them.

    Labels use textContent, and the page loads no external resources.

  • The skill opens the page with show_preview as its first action, without asking (standalone: it gives the URL at once). It reacts to the save message, writes and checks bird.json, offers one tweak, and asks the gallery question with the spec's wording. The intro, icon and README come with it. The README covers the standalone run, how steps advance, and the birds-v1 payload shape for the big-screen display.

Decide

  • Subdivision flag emoji (for example the Scotland flag) are refused in bird names, because they are built from tag characters. Recommend: accept it. If those flags matter, allow U+E0020 to U+E007F only right after U+1F3F4 in a follow-up.

  • Pi's "This project is not trusted" banner in boothstrap dev doesn't come from this package. hello-world shows it under the same conditions, and so does an empty workspace.

    • Cause: Pi 1.0.4 (dist/core/trust-manager.js, hasTrustRequiringProjectResources) flags any ancestor .agents/skills unless it is $HOME/.agents/skills.
    • Why the exception never applies: boothstrap runs Pi with a session HOME (packages/runtime/src/session/environment.ts). The workspace sits under the real home at ~/.boothstrap/dev/runs/…, so a real ~/.agents/skills doesn't match the session $HOME.
    • Why /trust can't clear it: --no-approve (packages/runtime/src/agent/pi-launch.ts, PI_ISOLATION_FLAGS) forces untrusted.

    The banner is harmless, because the ancestor skills stay ignored as intended. Recommend: fix it in boothstrap or upstream Pi, not in packages. Either keep session roots outside any tree that holds .agents/skills, or have Pi skip the banner when trust is explicitly overridden.

  • Opening the page without asking first is what the owner asked for, but boothstrap's base skill and the spec's show_preview row both say to ask. The Open preview dialog still collects consent. Recommend: relax those two texts in boothstrap.sh; no package change.

Ready gate

Step Evidence
Tests and lint npm run verify: ok for all three packages. npm test: 179 tests, 179 pass, 0 fail. npm run lint: 0 issues. CI is green on aecb0cc: run 38844551335. ✅
Red run Each review fix was test-first and failed before the fix. Examples:
• rotate(5) was accepted (expected at least one error).
• A symlinked bird.png got 200 (expected 422).
• A FIFO bird.json hung the server; that test now runs the server in a child process with a 5 s timeout.
• Tag characters, Hangul fillers and U+2800 passed in names.
• The CSP allowed 'unsafe-inline'.
• The watcher hashed a half-written bird.png as new content (the CI flake in run 38836595782); it now counts only a complete PNG.
✅
Sibling sweep hello-world and vibe-coding-mad-libs are unaffected (ok in verify). The intro.md lint ignore landed with them. The trust banner was reproduced with hello-world too. ✅
Docs and specs birdsbirdbirds/README.md: standalone run with --extension, how steps advance, the birds-v1 payload, and the checker rules. The root README's challenge index is left for the orchestrator's follow-up. ✅
Standalone run Pi 1.0.4, google/gemini-3.8-flash, standalone flow with --extension.
• Pi gave the URL at once.
• Saving a drawing in the browser prompted Pi, unasked, to read bird.png, describe it ("a sleek, minimalist geometric bird … like a modern origami crane") and mark draw-bird done.
• An earlier full run covered the animate, fly, tweak and cleanup steps: the checker passed on the first try, and Pi skipped the gallery standalone.
Not exercised: the inappropriate-content branch, and the in-boothstrap show_preview and publish_gallery_item calls.
✅
Editorial pass Reread against docs/style/. Removed CSS section-header comments, renamed single-letter test parameters, merged duplicate helpers, split a test that had two exercise phases, dropped a redundant bird.json notification, and wrapped README prose to 80 columns. ✅
Skipped tests None. ✅
Secrets, permissions No secrets. setup/cleanup are executable (100755). The shutdown token lives in a 0600 file in the workspace's .birdsbirdbirds/, and /health returns only its SHA-256. The extension reads only bird.png, through the capped reader that refuses symlinks. ✅

🤖 Generated with Claude Code

https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13

@theycallmeswift theycallmeswift left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent security-focused review of f1cbee8 against issue #7, the challenge spec, boothstrap's base skill, the upstream BirdsBirdBirds sources, and docs/style/, with an adversarial pass on the checker and a live smoke test of the server.

Verdict: clean. Three nits, which the owner wants addressed before handoff. The root README index is the orchestrator's follow-up, not this PR's.

Checked: npm run verify ok, npm test 99/99 (no model calls, no Python, no root dependency change), npm run lint 0 issues, no conflict with main, CI run 38818726988 green on this head. Checker: 130 crafted entries (comment-split tokens, CSS escapes, block escapes, nested and second at-rules, every dangerous property family, disallowed transform functions, unit mismatches, junk timing functions, HTML in values, fullwidth, zero-width, bidi, NUL, CRLF, name mismatches, out-of-range numbers, extra and __proto__ keys, duplicate JSON keys, inputs at and over every size cap) produced 0 bypasses and 0 false rejections; all 26 upstream manifest.json entries pass with id and image stripped. Server: bound only to 127.0.0.1, setup exits while the server keeps its process group, /health reveals only the token's hash, every path outside the page's four files 404s, foreign Host 421, foreign or null Origin 403, oversized or non-PNG uploads rejected, only bird.png is ever written and a pre-existing symlink there is replaced rather than followed, /bird.json serves only a checker-passing entry, /shutdown needs the token, busy port fails setup without touching the other listener, cleanup twice and after a failed setup exits 0 and leaves nothing listening. Page: no innerHTML or equivalents, no external resources, keyframes injected via textContent only from the server-checked entry, labels via textContent, the fly_ prefix keeps user keyframes off the page's own flap. icon.txt, intro.md, the skill, and the gallery payload all match the spec. The lint hunk is exactly the agreed two lines.


Generated by Claude Code

Comment thread birdsbirdbirds/server.mjs Resolved
Comment thread birdsbirdbirds/check-bird.mjs Resolved
Comment thread birdsbirdbirds/check-bird.mjs Resolved
…haracters

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13
@theycallmeswift
theycallmeswift marked this pull request as ready for review October 15, 2026 22:59
@theycallmeswift theycallmeswift self-assigned this Oct 15, 2026

@theycallmeswift theycallmeswift left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Opens with this message "This project is not trusted. Project .pi resources and packages are ignored. Use /trust to save a trust decision, then restart pi."
  • It's confusing to not have the browser open right away automatically
  • Clicking "save my bird" should trigger the next step via MCP, no?

@theycallmeswift
theycallmeswift marked this pull request as draft October 16, 2026 01:30

Copy link
Copy Markdown
Contributor Author

Taking all three. Back to draft while the worker addresses them:

  1. Trust prompt: being root-caused first against Pi 1.0.4's trust logic and boothstrap's Pi launcher. hello-world didn't report it, so the trigger is likely something this package writes or ships. If it turns out to be boothstrap-side, it comes back here as a finding rather than a workaround.
  2. Browser opens right away: the skill will call show_preview as its first action instead of asking.
  3. Save advances the step: the page can't reach report_step, but a Pi extension can watch the workspace for bird.png and nudge Pi the moment it lands, so Pi describes the drawing and reports draw-bird without being asked. Same mechanism for animate once bird.json passes the checker.

Generated by Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13
… is saved

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13

Copy link
Copy Markdown
Contributor Author

@theycallmeswift, on your review after the boothstrap dev run (0886982):

  1. "This project is not trusted": this banner doesn't come from this package. hello-world gets the same banner under the same conditions, and so does an empty workspace; I reproduced all three on Linux with boothstrap's Pi flags. Pi 1.0.4 (dist/core/trust-manager.js, hasTrustRequiringProjectResources) treats a workspace as untrusted when any ancestor folder holds .agents/skills, except $HOME/.agents/skills.
    • boothstrap gives Pi a session HOME (packages/runtime/src/session/environment.ts), but the workspace still lives under your real home at ~/.boothstrap/dev/runs/…. So a real ~/.agents/skills on your Mac doesn't match the exception, and Pi shows the banner.
    • --no-approve (pi-launch.ts, PI_ISOLATION_FLAGS) forces untrusted, so /trust can't clear it.
    • It's harmless: those ancestor skills stay ignored, as boothstrap intends, and the challenge's own skill and extension still load.
    • Could you confirm ~/.agents/skills exists there?
    • The fix belongs in boothstrap or upstream Pi: keep session roots out of any tree that holds .agents/skills, or have Pi skip the banner when trust is explicitly overridden. It's listed under Decide.
  2. Browser opens right away: the skill now calls show_preview on the page as Pi's first action, without asking first. Standalone, it gives the URL at once.
  3. Save advances the step: a new Pi extension (extension.mjs, declared in plugin.json, using Node built-ins only) watches the workspace. When Save my bird writes a new bird.png, it sends Pi a message. Pi then reads the drawing, describes it, checks it's appropriate and reports draw-bird straight away.
    • Repeated saves of the same drawing are deduplicated.
    • Pi still reports a step only when its condition holds, never on request.
    • I didn't add a notification for bird.json: Pi writes that file and runs the checker itself, so it already reports animate the moment the bird flies. fly still needs the participant's say-so.
    • Verified live: saving in the browser made Pi describe the bird and report draw-bird unprompted.
    • Tests cover the file appearing, a rewrite, no duplicates, a save through the server's temp-file-and-rename, a symlinked file, stop, and the extension's session start and shutdown.

npm run verify, npm test (120/120) and npm run lint all pass, and nothing is left listening on 4322. The skill, README and PR body are updated.


Generated by Claude Code

… never notifies Pi

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13

@theycallmeswift theycallmeswift left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent review of e5bca49, covering the round-two work since 981285f: the Pi extension and watcher, the skill change, and the owner's three asks.

Verdict: clean. Three nits for the worker, plus one boothstrap-side note below.

Checked: npm run verify ok for all three packages, npm test 179/179 (the birds file three times in a row, and the watcher and extension tests ten times under CPU load, with 0 failures), npm run lint 0 issues, no conflict with main, CI run 38836973473 green on this head. The extension loads through Pi 1.0.4's real loader with no errors; its sendMessage use (triggerTurn, deliverAs: 'followUp'), shutdown hook, unref'd timer, and stopped guard match the 1.0.4 typings, and stop is idempotent. The watcher handles the server's temp-file-and-rename save, never notifies on a half-written file (no IEND yet), dedupes identical rewrites by content hash, refuses a symlink, and has no busy loop. The earlier CI flake came from hashing the empty file between truncate and write; the fix removes that cause, and the test was not loosened. Standalone, the extension watches ctx.cwd, the same folder the hooks use, and the README's --extension line is right for 1.0.4.

Trust banner: the worker's analysis holds. Pi 1.0.4 checks any ancestor .agents/skills against $HOME/.agents/skills, $HOME is boothstrap's session home, and the session root under ~/.boothstrap/dev/runs/ sits beneath the real home, so a real ~/.agents/skills trips it; --no-approve sets the trust override to false, which beats the trust store, so /trust can't clear it. Nothing in this package writes .pi/* or .agents/skills. The fix is boothstrap-side: have doctor and dev flag a .agents/skills above the sessions directory, or keep session roots outside any home, or upstream, ask Pi not to show the banner when --no-approve decided trust.

Also boothstrap-side: "open the page without asking first" is what the owner asked for and the skill states it openly, but it conflicts with the base skill ("Call it only after the participant says yes") and the spec's show_preview row. The Open preview dialog still collects consent, so the fix is to relax those two texts in boothstrap.sh, not to change this package.


Generated by Claude Code

Comment thread test/birdsbirdbirds.test.mjs Resolved
Comment thread birdsbirdbirds/extension.mjs Resolved
Comment thread birdsbirdbirds/bird-watcher.mjs Resolved
…n resume

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EUjXNVUzfZEnojibRv8S13
@theycallmeswift
theycallmeswift marked this pull request as ready for review October 16, 2026 03:16
@theycallmeswift
theycallmeswift merged commit 12de78b into main Oct 16, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ship the BirdsBirdBirds challenge

2 participants