Repository navigation
State client facts and send reports with consent - #63
Draft
raghubetina wants to merge 11 commits into
Draft
raghubetina wants to merge 11 commits into
raghubetina wants to merge 11 commits into
Conversation
First Draft's next Rails target adopts foundation-rails-core main, which runs jobs, Cable, and the cache in-process and answers its health check at /up, under a new target profile. The Plan format stays sketch/0.23. plan init writes the new profile and artifact validation accepts only it, so a rails-sketch/2026-10 artifact now reports invalid_artifact. The ID is a working one until the release names the profile; it lives only in RAILS_TARGET_PROFILE, and the documentation test keeps the docs naming that constant's value. The plan status zero-gap digest covers the target, so it is recomputed with the Service's serialization, JSON.pretty_generate plus a newline, which reproduces the previous digest for the old profile.
After request_outcome_unknown from a push or a direct Compilation start, the CLI told the agent to stop until First Draft or an operator reconciled the Project. Testers now work on their own, so that left them with no way forward. The Service already makes one rerun safe. A repeated push with the saved ETag either succeeds or is refused with 412. A 412 says only that First Draft holds another Plan, from the first attempt or from another copy of the Project, so the advice is to continue from that copy or fork a new Project. A repeated Compile is refused with compilation_active while the first one runs, which leads into stuck-Compilation recovery; otherwise it starts a second Compilation whose only cost is service time and one of the day's Compilations. The rerun keeps the original options and environment: a first push has no pinned origin yet, and a bare rerun of plan compile would change its output mode. A fork names the old folder's origin for the same reason. Publication keeps its singleton rules.
raghubetina
force-pushed
the
invite/release-cli
branch
2 times, most recently
from
November 20, 2026 22:49
467776b to
58e0e9c
Compare
Testers invited back work alone, so old setups have to say they are old, and First Draft needs to learn what happens in their apps. Every request now carries FirstDraft-Client: the CLI version, the plugin version and agent name from FIRSTDRAFT_PLUGIN_VERSION and FIRSTDRAFT_AGENT (set by the plugin's launcher), and the operating system, in the grammar the Service parses. Login no longer sends the computer's hostname. The CLI reads FirstDraft-Latest-Plugin, FirstDraft-Minimum-Plugin, and FirstDraft-API-Contract on every response. An older plugin, or the CLI when no plugin version is set, gets one update line on stderr per command, just before its result, whether or not a terminal is attached: an agent runs the CLI without one and must pass the line on. Below the minimum or outside API 0.9.x, the CLI finishes handling that response, so an accepted push still saves its ETag, and sends nothing more. Only when that cut the command short does update_required or api_contract_unsupported replace its result, naming a Compilation that had already started. Otherwise the command keeps its result and any local recovery data, after one line naming the stop. A 429 from an account limit always reports rate_limited with retry_at. The range becomes >= 0.9.0, < 0.10.0, and as in npm ranges a prerelease contract is outside it. New commands: account reads whether reports are on; report progress and report failure print the exact report, send it to the Project's pinned origin, and treat reports_off as a message with exit 0 so the agent's work continues. Their routes and fields follow the Service's report endpoints, they print Sent. only on First Draft's 201 acknowledgment, and they find the Project from an adopted application root, where an agent runs its specs. Failure reports replace emails, absolute paths, assignments, credentials, and token-like strings, and keep only frames in the application. conversation send needs --person-agreed each time and prints the file's path, size, and digest before sending. The README's promise now names what each command sends and where the update line comes from.
raghubetina
force-pushed
the
invite/release-cli
branch
from
November 20, 2026 23:10
58e0e9c to
5c9f23d
Compare
Without FIRSTDRAFT_PLUGIN_VERSION the CLI compared its own version with the plugin's latest and minimum. The two packages are numbered separately (plugin 0.9.3 bundles CLI 0.9.0), so a direct npm installation, as in the Codespace and the laptop kit, would have printed the update line, or refused, for versions that were current. The Service now also names FirstDraft-Latest-CLI and FirstDraft-Minimum-CLI. A plugin is compared with the plugin pair and a bare CLI with the CLI pair; a Service that sends no CLI pair produces no line and no refusal. update_required names minimum_cli_version in the second case.
A fresh review of the whole branch found text that still left the computer in a failure report: JWTs whose segments were too short for the token rule, assignments quoted as a whole, paths directly under the root, and a quoted option with its path. The Service scrubs the same forms, but only after the CLI has printed and sent them. A report now counts as sent only when First Draft returns a UUID for it. A plugin version that is set but unreadable compares neither version pair, so a plugin never meets the CLI's minimum. A 429 is described as a limit, not the account's, because device login shares one across all CLIs. The fork advice after a 412 names the origin a first push used when it never pinned one, and reports run from the application root after adoption.
The second review round still found text that left the computer: a quoted assignment containing the other kind of quote, a quoted -I option whose drive letter was read as part of the option, and an unquoted path with an escaped space. A 429 with neither Retry-After nor a problem detail, as device login sends, now says to try again in a minute instead of "later", and the login reference names the refusals that can end it.
Each review round found another way a secret could slip past a pattern for what secrets look like: a multiline quoted assignment, a quoted path with an apostrophe, a masked assignment that swallowed the command after it. Patterns for secrets will keep missing cases. Each field now has a shape, and what does not fit is left out. rerun is an RSpec run of the app's specs after any leading assignments are dropped; error_class is a Ruby constant; frames are app paths with a line number; versions are numbers. message and fix_summary keep the first line's plain words, with quoted spans and any word that can carry a value replaced by a placeholder. The preview prints the shaped report and names what was left out. The Service applies the same shapes, so the two layers agree. The login reference now says a version stop replaces login's result only when it stops a request login still had to send.
Pairing quotes in a failure report's message or fix summary still let words through: a quote that closed on the next line or past the length limit, or an apostrophe in a word paired with one inside a quoted path. Quotes are no longer paired. From the word that holds the first quote character, the rest of the line is one placeholder; before it, words that can carry a value are replaced as before, and the length limit drops whole words.
The Service's shape for a rerun path is components of safe characters separated by single slashes, so bundle exec rspec spec/models/ was refused while the same run without the slash was accepted. The CLI now removes a trailing slash after a spec directory and uses the same component grammar, so it leaves out what the Service would refuse rather than sending it.
The CLI shapes each failure-report field and the service refuses what does not fit, so the two must agree on the same strings. A copy of the service's accepted and refused examples now drives a test: every accepted example passes through the CLI unchanged, and what the CLI builds from a refused one is a fixed point that is not itself refused, or the field is left out. The test found the CLI leaving out values the service accepts: an error class with a leading :: and versions such as 8.2.0.beta1 or 3.4.0-preview2. Line numbers, control characters, and the client facts' length now match the service's limits too. The fixture is kept byte for byte, so Prettier skips it.
A half version pair said nothing useful, so the update line and the minimum check now compare a pair only when both headers are readable. A set but unreadable plugin version, blank included, compares neither pair and says so in the one stderr line, since falling back to the CLI pair would judge the wrong install. Failure reports drop paths with a parent segment, end the first line at any Unicode line break, and name a message or fix summary that has no plain words left instead of sending it empty. Progress counts above the service's maximum are refused before anything is sent. The docs now word the API requirement as this development version's and say that plain words may still quote code.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The CLI side of the release that invites October's testers back. They work on their own, so old setups have to say
they are old, the product's own messages have to carry recovery, and First Draft asks before it learns anything
from their agents.
/v1and OAuth, carriesFirstDraft-Client: cli/<version>; plugin/<version>; agent/<name>; os/<platform>.pluginandagentcome fromFIRSTDRAFT_PLUGIN_VERSIONandFIRSTDRAFT_AGENT, which the plugin's launcher is to set; unknown or unsafe partsare left out. Login no longer sends the computer's hostname.
FirstDraft-Latest-Plugin,FirstDraft-Minimum-Plugin,FirstDraft-Latest-CLI,FirstDraft-Minimum-CLI, andFirstDraft-API-Contract. Aplugin is compared with the plugin pair and a bare CLI with the CLI pair; an older one gets one
First Draft:lineon stderr per command, with or without a terminal. Below the minimum or
outside API
>= 0.9.0, < 0.10.0, the CLI finishes handling that response (an accepted push still saves itsETag) and sends nothing more; when that cut the command short it reports
update_requiredorapi_contract_unsupported, naming a Compilation that had already started, and otherwise the command keeps itsresult after one line naming the update. A
429from a daily cap reportsrate_limitedwithretry_at.plan initwrites, and artifact validation accepts only, the working profilerails-sketch/2026-11, named once inRAILS_TARGET_PROFILE.accountprints whether reports are on.report progressandreport failureprint the exactJSON they send, then send it once to the Project's pinned origin, and print
Sent.only on First Draft's201acknowledgment;
reports_offis a message with exit 0. Routes and fields follow the Service's report endpoints,and the commands find the Project from an adopted application root. Failure report fields are shaped, not
redacted: an RSpec rerun, a Ruby constant, app frames with a line number, version numbers, and the plain words of
free text; what does not fit is left out and named in the preview.
conversation send <file> --person-agreedrefuses without the flag, prints the file's path, size, and SHA-256, and uploads the bytes unchanged. The Service
does not accept conversations yet, and the docs say so.
request_outcome_unknownfrom a push or a direct Compile, the handled details anddocs/errors.mdsay to rerun once with the same options, with the412andcompilation_activebranches,instead of stopping.
No version bump: the version pull request sets it with its changelog entry.
Docs: updated README.md (package promise), docs/commands.md (What the CLI sends, account, reports, conversation,
Service endpoints, profile, API range, add-a-command), and docs/errors.md (update and limit errors, report and
conversation errors, ambiguous-mutation recovery, error index).
Review: Codex, needs attention after 5 rounds of a fresh session over the whole branch (2 rejected and 1 deferred by decision, 2 new findings open), following an earlier 4-round session (30 fixed, 7 after its last round, 3 declined); Antigravity, 2 completed rounds (6 findings fixed), then stopped after two failed runs
Validation
npm audit: 0 vulnerabilitiesnpm run check: passes (326 tests, package allowlist, packed smoke); the same suite passes on Node 22.0.0