Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
jev-use setup guide: scope and verification
Decision and ownership
Refs #3915; extend the existing draft PR #3916 and its canonical branch. The maintainer requested a step-by-step public guide under /docs and a fresh-agent setup test using that guide alone. Preserve the existing example authorship and acknowledgment. Do not implement or depend on the separate policy-head proposal in #3914.
Initial technical scope
The public guide now lives at docs/content/docs/cua-driver/guides/visual-regions.mdx and the example at libs/cua-driver/examples/jev-use/. Earlier entries below retain the historical paths and commit pins used when the work was still presented as typesafe-jev. The primary supported walkthrough is macOS with the existing Python example; TypeScript is an optional second route. Use the checked-in SDK dependency locks and existing fixture/runner. No changes to the Driver, permissions contract, installers, or model API are planned. Rehearsal failures later justified a small managed verification entry point beside the existing fixture; it does not change either agent's decisions or actions. Link the example README back to the complete setup guide.
The guide must explain the agent/driver boundary, host versus controller machine, human approvals, installation and PATH, Python provisioning, signed browser prerequisite, source checkout before the PR merges, credential handling without shell-history exposure, persistent MCP ownership, fixture readiness, mock versus live proofs, independent readback, failure handling, sequential execution, and cleanup. No dependency on private experiment files, remembered PIDs, old sessions, or conversation context is allowed.
Initial acceptance evidence
- Record the original guide's missing prerequisites as the initial failing documentation acceptance case.
- A new agent session receives only the candidate guide, a blank working directory, and documented human-provisioned prerequisites. No benchmark scripts or conversation history. It must clone the example, install dependencies, run the mock and live Python paths, and prove each exact submitted token through the fixture's independent
/stateendpoint. - Record the source SHA, guide hash, prerequisite inventory, agent transcript hash, commands/outcomes, and any intervention. A mock run alone is not a live Jev pass. Pre-existing OS grants or installations are not claimed as freshly reproduced.
- Run Python unit tests, TypeScript tests/typecheck, docs hygiene, internal links, applicable generator drift, and the docs production build. Keep logs private if they contain local paths; publish only sanitized evidence.
- Preserve the unrelated staged work in the original workspace. Keep PR #3916's description current and leave it draft if acceptance evidence is incomplete.
Initial implementation worklog
- Reviewed the existing guide and Python runner. The current guide cannot stand alone: it assumes Driver installation/PATH, uv and a suitable Python, browser availability, OS permissions, an unlocked desktop, and a source checkout that already contains an unmerged example. It also puts a placeholder secret in an export command and lacks exact expected results, readiness checks, and cleanup instructions.
- Searched GitHub for Jev/TypeSafe duplicates. Found active draft #3916 linked to assigned issue #3915; recorded this contribution's scope on the issue and checked out that existing branch in a separate worktree at
6bbeb001e60209eb6ce86bc88a2524947086a5ab. - Authenticated GitHub through the existing credential helper without exposing credentials. Verified canonical repository push access for
injaneity. No fork or competing PR is needed. - Host preflight: Cua Driver 0.23.2 is installed, its Accessibility and Screen Recording grants read true, and the desktop is currently unlocked. System Python is 3.9.6, so the guide must provision a compatible Python rather than assume
python3is sufficient. - The original guide's
maincheckout was independently checked: GitHub returned HTTP 404 for the unmerged example directory. This is the initial failing setup acceptance case, not a hypothetical missing prerequisite. - Candidate
1c4125c1acc7a29dab1895304882941f428ca1a2: a fresh Codex agent with no prior conversation verified the installed Driver, grants, and signed Chrome, then stopped at uv installation because the rehearsal sandbox denied macOS's per-user temp directory. No provider calls, fixture mutations, or success claim occurred. Its original transcript/report are retained privately. The next attempt explicitly permits normal dependency-install/temp/cache paths, and the guide now names those execution prerequisites. No host security settings or Cua policy were changed. - Documentation hygiene, internal links, Cua Driver generator drift, and the production build passed on the first candidate.
- Candidate
fbd5fb3b76d9c5e5c50beedb779171fdc62c9c50: the second fresh agent installed uv, cloned the public source using the PR fallback, provisioned Python 3.12, and passed all eight Python tests. It then stopped at optionalnpm ci: this host's global npm cache is root-owned. No live request or desktop proof was claimed. The guide and README now use a local npm cache under ignored.venv, without changing shared cache ownership, and explicitly sequence the optional route after the Python proof. A third fresh-agent attempt will use the revised guide. - Candidate
052fe231975099a3e48bde1cfcecb20ead875a1b: the third fresh agent passed Python setup/tests and fixture readiness, but its next shell call found the fixture gone. Thenohupchild did not survive the shell tool lifecycle, so the mock stopped before opening MCP or calling Jev. Controller-side inspection confirmed the fixture port was closed. Replaced the guide's background launch with an explicitly detached Python process session and documented a persistent-terminal alternative for environments that disallow detached children. Preserved the original failed run; a new agent must rerun the revised guide. - Candidate
98fc46ea21aa0dda48ad0a5e6caf24e2de981e32: the fourth fresh agent's detached fixture remained reachable, but the sandbox denied PID readiness checks and cross-call process management. The parent operator verified the exact recorded command and stopped only that retained fixture. No browser or provider verification occurred. This revealed that detached-process recipes still impose an unnecessary agent-harness dependency. - Architectural simplification: added
verify_setup.py, reusing the existingFixtureServerin a context-managed thread and the unmodified Python/TypeScript runners as child processes. One command now owns startup, independent HTTP verification, evidence, and cleanup. It defaults to mock, requires a key before unattended live execution, refuses existing output directories, and preserves an incomplete summary on failure. The guide no longer asks an agent to manage background PIDs across tool calls. - TDD: seven new real-process/HTTP checks first failed because the verifier did not exist, then passed. They cover cleanup on success/failure, exact state plus final-event requirements, false-positive rejection, child failure, and missing unattended credentials. All 15 Python tests passed. No Driver/product code or provider decision logic changed.
Initial fresh-agent verification
Tested candidate: bebe5e7692c6347b6a090336eac3c0ea4911ec59.
Guide SHA-256: c965092c02949f1ca28a285445a28eca92f0233b8c1d04cb583c342a13102541.
The fifth rehearsal used a new ephemeral Codex CLI 0.154.0 / gpt-6-astra
session, with user configuration and host skill discovery disabled. Its working
directory initially contained only the guide. The agent received no previous
conversation, benchmark scripts, private experiment paths, or fixes from earlier
attempts. It cloned the public repository, followed the guide's PR fallback,
and ran the checkout unchanged. The successful transcript contains no private
worklog access. There was no intervention during this attempt.
The human-provisioned prerequisites were the TypeSafe key in the execution environment, installed CuaDriver/Chrome, approved OS permissions, an unlocked desktop, and a shell sandbox with the documented dependency/temp/cache access. This is a zero-conversation-context setup proof on a provisioned Mac, not a claim to automate account creation, OS approval, or a factory-clean OS install. The earlier second agent performed the previously missing uv installation.
Successful-run environment: Cua Driver 0.23.2 in standard mode; signed system
Chrome; uv 0.12.15; CPython 3.12.14 in a fresh virtual environment;
typesafe-sdk 0.6.0; Node 26.8.1; npm 11.19.0. Node/npm are the versions observed
inside the verifier agent, not the parent shell's separate Node installation.
| Proof directory | Independently verified cases | Result |
|---|---|---|
proof-mock |
Python/mock | 1/1 |
proof-live |
Python/mock, Python/live | 2/2 |
proof-both |
Python/mock, Python/live, TypeScript/mock, TypeScript/live | 4/4 |
Every case had exactly two recorded decisions: type the value, then submit.
All seven runner logs ended with the expected verified event and exact token.
The verifier independently read each value from HTTP /state; all three
summaries reported complete: true. The three live cases are live service
proof, not mocked SDK responses. These logs do not establish exact HTTP retry
counts, resolved model version, token usage, or billing.
The agent and parent audit separately checked the summaries/logs, unchanged tracked source, and closure of all three fixture ports. The parent confirmed that the guide and executed example files match the candidate byte-for-byte, and that credential values are absent from all five attempt transcripts. Private evidence is retained rather than publishing host paths or raw logs.
Evidence fingerprints:
- Successful agent transcript:
0c54f16b0170445e4702cdb096a4855827329eebb9f342c788edea0c1a5bd117. - Fresh agent's final report:
7ad94c0a2479994bdca5200dde033bada6bd980d5e9ad190308c25d8d855ceca. - Python/live log in the four-case proof:
a3b9fda2f46b185a0a4dac5de315e55909bfdc0dc81c7bf70016f437ae6389a4. - TypeScript/live log:
4ff48370227dc80cae750806b2e93614a28213b6c2ebb02d5e8329609d19f2fa.
Checks passed:
- 15 Python tests, including seven new verifier boundary/lifecycle tests.
- 7 TypeScript tests and
tsc --noEmit. - Public docs hygiene, internal links, Cua Driver generator drift, and production build.
- Unrelated original-workspace staged diff preserved; phase baseline SHA-256
5b57ea71dbb7c83df2ae82fd7e435cf1f6ce3a5a7c1c9abc963c4f291787926f.
At c4e7307db52c6958a9abbd94e9fa728440e612b9, the only change after this
certified candidate was this evidence report. The later reader-first guide
revision below has separate validation.
No full Driver desktop matrix was repeated for this documentation/example-only
follow-up. The existing PR remains draft for its normal review, not because the
requested guide or fresh-agent verification is incomplete.
Non-blocking environment notices: the installed Driver advertises an update;
Node reports a deprecated module.register() path; npm reports unapproved
optional install scripts. The agent did not update the Driver, approve scripts,
or change policy, and both TypeScript runtime cases passed.
Reader-first revision
The maintainer's review found that the public guide exposed too much of the original conversation and verification process. The observable problems were an opening framed around what Jev is not, unrelated model/video terminology, PR-specific checkout instructions, raw diagram source in the local renderer, and extensive process/sandbox/audit details before a first useful result.
Scope: rewrite the same public page around a concrete first task (fill and submit a form), prerequisites, four short steps, expected results, and a small troubleshooting section. Keep detailed execution-environment and measurement notes in the example README and this contributor report. Preserve contributor acknowledgments in the README. Do not change the agent or verifier code.
At that revision, the checkout pinned the already-tested example revision
bebe5e7692c6347b6a090336eac3c0ea4911ec59; readers no longer need to understand
an unmerged PR to obtain runnable code. The guide revision and example revision
are deliberately distinct. New evidence must identify both.
Acceptance: a fresh reader can identify what they will build, what to install, which commands to run, and how to recognize success without knowing the prior conversation. The revision reduces the page from 2,193 to 958 whitespace-delimited words and removes the unrelated model/tool comparisons and PR-specific framing.
A sixth isolated agent followed guide candidate
ec42a58a8b61824ccf0bacf8460d2fc3996e541f without intervention. It downloaded the
pinned example, installed locked dependencies in a fresh checkout, and completed
runs/connection-check (1/1), runs/jev-example (2/2), and
runs/both-languages (4/4). Three of the seven cases used live Jev. All recorded
two real actions in the expected order and exact independently observed tokens.
The parent audit separately checked the seven retained logs, complete summaries,
closed fixture ports, unchanged tracked source, and absence of the credential
value from the transcript and report. Pre-provisioned host prerequisites remain
as described above; this was not a factory-clean installation test.
Bash-fence syntax, docs hygiene, internal links, Driver generator drift, and the production build passed. The revised local preview was loaded in a new isolated Chrome profile and captured from its exact native window. Native accessibility readback confirmed the guide title and absence of the old literal Mermaid block. No production-site rendering claim or visual-model inspection is implied.
| Retained artifact | SHA-256 |
|---|---|
| Revised guide | 73ffdd9bfea070d5180672214f70663cc93f7c65634e1d811e15588990a60608 |
| Fresh-agent transcript | 3b2bd7486fbfc76650eeb45d96f60a5a88f628f54eaae76203d7d967aca21866 |
| Fresh-agent report | c972f02eac6194f54167225391a40832be66ebb3f7f72e14e6656e99729b2159 |
| Local preview screenshot | eda3b4fea13b6a78d61e2e1b863d9dc56386463809bf5c427f33d59113b507b9 |
The final follow-up only records this evidence; the tested guide and executable
example are unchanged. The first parent audit used the wrong JSONL event name
(action instead of step); correcting that audit required no live rerun.
Existing Node/npm notices and Rust dead-code/linker warnings remained non-blocking.
No Driver runtime, dependency lock, installation policy, or security setting was
changed. Prior verification history stays in this report, outside the walkthrough.
Platform-neutral follow-up
The maintainer selected a shared walkthrough with platform-specific setup and
honest native validation status. The guide now separates macOS, Windows, and
Linux desktop prerequisites while keeping download, Python setup, connection
checks, live execution, and results common. Shell-specific npm installation is
in tabs; summary inspection uses uv run instead of .venv/bin/python. The
Wayland section links canonical compositor requirements. At the maintainer's
request, verification-status labels and coverage tables are omitted from the
walkthrough; actual coverage and blockers remain here and in the PR.
Launcher correction
The original verifier invoked npm directly with Python subprocess.run.
On Windows this raised FileNotFoundError: [WinError 2] because npm is a command
shim, not an executable resolved like node.exe. Extracted the existing runner
command construction and added real-process startup tests. The TypeScript test
reached the same native failure before the fix and reaches the real argument
validator afterward; it does not mock process creation or require a desktop.
The Python test invokes the actual runner's help path.
The fix uses the existing node --import tsx pattern already used by the npm
test script. It adds no dependency, shell evaluation, permission change, or
Driver runtime change. Optional Node checks skip only when Node/TypeScript
dependencies are absent; the recorded three-platform runs installed them and
had no skipped tests. Source commit decc10f6c37168e061d3973dfd9cd21d18da3f68
was moved with git cherry-pick -x, retaining contributor/coauthor credit.
At that phase, the guide pinned runnable revision
b0e4b6feb0064cedc4dcf04d70a0d270d0568b99.
| Native host | Python tests | TypeScript tests | Typechecking | Desktop/live evidence |
|---|---|---|---|---|
| macOS, Python 3.12.14, Node 22.20.0 | 17 passed | 7 passed | Passed | Prior real browser/live proof; revised-guide rehearsal recorded below |
| Windows, Python 3.12.8 | 17 passed | 7 passed | Passed | Blocked before browser actions; no live requests |
| Linux x86_64, Python 3.12.3, Node 22.20.0 | 17 passed | 7 passed | Passed | Stopped at desktop preflight; no live requests |
Windows native limitation
The existing interactive Session 1 desktop has Driver 0.19.3, whose preparation API requires a browser PID. It was not replaced or stopped. Official 0.23.2 and 0.28.2 Windows binaries were downloaded separately and checked against their component-release asset digests. Owned direct MCP processes exercised those runtimes without changing the shared daemon or its user policy.
Microsoft Edge 153.0.4234.32 has a valid Microsoft signature. The host's elevated token was correctly refused automatic protected-browser discovery. A restricted token, and subsequently a medium-integrity non-administrator token, passed attestation but the isolated Edge process did not expose a loopback DevTools endpoint before timeout, on both tested Driver versions. No policy, UAC, ACL, or browser-sandbox setting was weakened to force a pass.
All four managed attempts retained complete: false, no successful action
records, and closed fixture ports. The original daemon remained PID 8088 with
the same policy hash. The TypeSafe credential was not provisioned here and no
live provider request was attempted. This is an environment-specific unresolved
browser-startup result, not a claim that Windows cannot support the integration.
A usable non-elevated browser/Driver desktop run is still required.
Retained Windows evidence archive SHA-256:
6f49886a0619263f39c72950c96532f18acefc0bc1efc9863e7cd7937cfa1161.
Linux native limitation
The first existing Linux sandbox failed workspace preflight for insufficient free space. On the second, unprivileged dependency setup, both test suites, and typechecking passed. Its installed Driver is 0.4.2, no supported system Chromium browser is installed, and the existing XFCE desktop belongs to root. The test user has no usable top-level windows on the observed X11 display. Reading the other user's process environment was denied, and sudo requires a password. No authentication material was copied and no display authorization or host permission was weakened. Desktop verification stopped before any model call. A current Driver, trusted system browser, and accessible same-user desktop are required before claiming an X11 pass. No native Wayland run was attempted.
Workflow integrity
Environment switching resynchronized the managed Mac workspace's Git metadata and invalidated its sibling worktree reference. The guide files were compared with the canonical PR head before recovering that checkout as a standalone repository. The resynchronized original index was not reset or overwritten; its checksum changed through the tooling, so the earlier preserved-staging claim applies only to its original phase. This tooling issue, transfer limits, and all native setup blockers were recorded separately.
The initial Mac test invocation lacked optional npm dependencies and skipped the TypeScript launcher check. After the documented locked npm installation, all 17 Python tests and seven TypeScript tests passed with typechecking. That initial skip is not counted as launcher validation. The PR remains draft with Windows/Linux desktop acceptance explicitly incomplete.
Final macOS rehearsal and documentation checks
A seventh fresh, ephemeral agent followed guide candidate
a213d0acc731c8041199cdc944014bd05cddec09 against pinned example
b0e4b6feb0064cedc4dcf04d70a0d270d0568b99, without prior conversation, host skill
discovery, code edits, or intervention. All seven cases passed, including three
live Jev cases and both languages. The parent independently audited exact
submitted tokens, two actual actions per case, final outcomes, closed fixture
ports, unchanged executable sources/locks, and absence of the credential value
from retained transcripts and reports. This remains a provisioned-Mac proof,
not a new Windows/Linux desktop certification.
Final guide changes after that rehearsal clarify the already-tested Driver
version floor and remove the verification-status wording at the maintainer's
request. Every executable command is unchanged; the parent audit allows only
those exact prose changes. The final guide hash is
139ec94166234c91f8ca428eb620a404932e9175fe3f5946406134bcac1cfe9e.
- Tested guide hash:
dc44915168f1486ec64ccd8c04f3753d835b4ce58df0173f23f0927947279c84. - Fresh-agent transcript:
123abe5a3da301095b9fffea71ee77f16c5515b5d0bc94648ab28ba4e6889472. - Fresh-agent report:
138c22ebb41ac4f6b045cc5a68f585eb9fed0a5eba75a926d601447d1d52baf5.
Final docs hygiene, links, generated-contract drift, and production build passed. The recovered shallow checkout initially lacked release tags; fetching the component tags restored the generator's prerequisite without changing generated files. A supplementary preview automation did not establish its expected tab postcondition, so no successful interactive-tab screenshot check is claimed.
Evidence retention update
Sandbox re-entry replaced ignored files inside the managed Mac workspace as well as Git metadata. Earlier private launcher scripts and parent transcripts stored there were lost; their historical fingerprints above must not be read as a promise that all original raw files remain available. Surviving fresh-agent reports, guide snapshots, and per-case logs were recovered from their separate temporary checkouts. Desktop deliveries remain intact; the previously delivered gameplay video still matches its recorded hash. No local filesystem snapshot was available for broader recovery.
The latest fresh-agent transcript, report, seven case logs, audit, and harness are retained outside the resynchronized workspace in the standalone guide checkout. Native Windows/Linux evidence remains in their separate guest paths; the Windows archive was also preserved as encoded bytes in the tool transcript. No lost evidence was reconstructed or represented as retained.
Credential-free Linux workflow follow-up
The branch remains based on origin/main
aca1985ffc4061d580218f5f850ac57132d90e36. Exact executable candidate
545c52a27192906cfad6802646f18a025f309f8a passed credential-free workflow
CI: jev-use as GitHub Actions run 35238509486. Both unit jobs passed. The
Linux job built that exact Driver, verified its advertised MCP tools, ran the
Python and TypeScript mock agents through persistent MCP under X11, confirmed
both independent loopback /state postconditions, audited the redacted
evidence, and uploaded the proof artifact.
The candidate accepts the first bound tab when no tab is explicitly active,
matching the Driver contract's unknown-active-state behavior, while still
preferring an active tab when one is known. It applies the same selection to
Python and TypeScript. The workflow also gives the isolated bootstrap tab a
stable title and verifies that title over DevTools before starting the MCP
agents. Local verification passed 19 Python tests, nine TypeScript tests,
TypeScript typechecking, workflow YAML parsing, and git diff --check. No live
provider workflow was dispatched.
The current guide uses FETCH_HEAD after its single-ref shallow fetch so the
detached checkout does not depend on a remote-tracking ref that a default
single-branch clone may omit. Its shown JSON output now matches json.dumps
spacing. Current guide SHA-256:
dcdc2d8020a2aa296bef67d7058537db470b9504ca20ab6fb0cce86433ee7931.
Optional visual adapter follow-up
The Python and TypeScript examples now contain equivalent optional adapters for
the public cua.visual_regions_v1 result. They discover
parse_visual_regions from MCP tools/list, capture the selected window with
get_window_state, and call the visual parser only when Driver also advertises
the capture-bound click.capture_id input. Existing Driver versions and
installations without the complete contract continue through the DOM/semantic
path.
Two checked-in structured fixtures cover one unique Submit region and an
ambiguous pair. Focused tests prove equivalent candidate IDs in both languages,
reserved reobserve and abstain, immutable capture-bound arguments, rejection
of stale, malformed, out-of-bounds, duplicate, and ambiguous inputs, and the
continued independent fixture oracle. The fixtures contain no screenshots,
credentials, extension artifacts, or model dependencies. No live Jev or live
perception call was made for this follow-up.
Local verification passed 25 Python tests, 15 TypeScript tests, TypeScript
typechecking, and git diff --check. The managed mock verifier completed both
languages in two actions each and independently read back
{"submitted":"jev-guide-mock"} from the fixture. The installed Driver
advertised all six required MCP tools and did not advertise the optional visual
tool, exercising the documented semantic fallback rather than a live parse.
Independent review found that the first visual candidate used unbound
browser_click coordinates and that TypeScript treated JSON null differently
from Python while using locale-sensitive case conversion. The follow-up removes
that path. Visual candidates now exist only when MCP advertises both
parse_visual_regions and click.properties.capture_id; the complete click
arguments contain the exact capture ID, window target, screenshot-space point,
and delivery mode. Delayed-provider tests change the capture before dispatch,
require Driver's structured refusal, and prove there is no unbound retry.
A shared fixture covers nullable optional fields, ASCII SUBMIT, and Turkish-I
SUBMİT. Both languages accept the same nulls, apply the same ASCII-only case
normalization, select only the ASCII match, and preserve the capture-bound
arguments.
Final local verification passed 29 Python tests, 19 TypeScript tests,
TypeScript typechecking, and git diff --check. The managed mock verifier again
completed both languages in two actions each and independently read back
{"submitted":"jev-guide-mock"} from the fixture. The installed Driver did
not advertise the complete optional capture-bound visual contract, so this
proof exercised the unchanged semantic fallback. No live Jev or live perception
call was made.
External Jev adapter follow-up
The TypeSafe request code is now isolated in equivalent Python and TypeScript
Jev adapter modules. The runners supply the current semantic snapshot, optional
validated cua.visual_regions_v1 observation, immutable candidate table, and
recent history. The adapters send only candidate IDs with descriptions and a
compact observation; visual state includes typed region bounds and the exact
capture_id, without screenshot bytes or extension implementation details.
The mock path uses the same adapter boundary without a credential. Focused live
adapter tests use the official TypeSafe SDK request shape with a local fake
transport. They prove that a supplied visual candidate ID can round-trip, that
the request includes the matching capture and region IDs, and that an answer
outside the supplied table fails before Driver execution. The existing fixture
/state oracle remains the only source of a verified outcome.
Final focused verification passed 30 Python tests, 20 TypeScript tests,
TypeScript typechecking, and git diff --check. The managed credential-free
verifier completed the Python and TypeScript mock loops against installed Cua
Driver 0.23.2 and independently read back
{"submitted":"jev-guide-mock"} for both. That installed version did not
advertise the visual contract, so the desktop proof exercised the semantic
fallback; the typed visual/live Jev boundary is covered by the local SDK
contract tests without a live credential or perception model.
Bounded chooser process interface
The example now exposes python/choose_action.py as the required cross-platform
provider process and typescript/choose_action.ts as an equivalent Node path.
Both accept exactly one cua.jev_choice_request_v1 document containing a goal,
capture ID, compact typed regions, bounded history, and candidate IDs with
descriptions. They require reobserve and abstain, reject duplicate or
malformed IDs and forbidden tool, screenshot, or environment fields, and emit
only the cua.jev_choice_v1 response fields.
verify_choice_cli.py launches the Python interface with the active interpreter
and an absolute script path, passes JSON on stdin, and does not use a shell. The
credential-free workflow runs that verifier in mock mode; the separately
authorized candidate workflow also runs it in mock mode, and no GitHub Actions
workflow supplies the TypeSafe credential. The chooser itself relies on the
official SDK's environment handling and never reads, prints, or forwards the
key.
Final local verification passed 34 Python tests, 24 TypeScript tests,
TypeScript typechecking, both mock chooser commands, workflow YAML parsing, and
git diff --check. The SDK client tests cover live request/response shaping
with local fake transports; no live TypeSafe request was made locally.
Workflow credential boundary
No GitHub Actions workflow stores, references, or uses TYPESAFE_API_KEY. The
authorized workflows keep the exact-SHA trusted-branch gate, the immutable
signed-candidate verification, and the canonical Windows/Linux certification
checks, and they run the bounded mock chooser rows through the preinstalled
.venv/bin/python; they never run a live provider row or the chooser with a
credential. All third-party actions in the workflow are pinned to immutable
commits.
A focused workflow contract test enumerates every action reference and requires 40-character action commits, the preinstalled interpreter path, mock-only chooser invocations, and the complete absence of secret references. A separate repository-wide guard scans every Actions workflow so the credential name cannot be reintroduced through another workflow file.
Live TypeSafe validation is an out-of-band procedure: it runs only directly on a disposable Tahoe Lume guest, with the credential supplied from that guest's local Keychain to the bounded chooser process. That procedure is maintained privately and publishes hashes and outcomes only, never the key value or fleet details.
Final focused verification passed 36 Python tests, 24 TypeScript tests,
TypeScript typechecking, workflow YAML parsing, and git diff --check.