mattpocock

sandcastle

Orchestrate sandboxed coding agents in TypeScript with sandcastle.run()

by mattpocock

TypeScript

TypeScript99.1%
Shell0.5%
JavaScript0.3%
Dockerfile0.1%

Commit activity

Last 12 weeks · 715 commits

Full graph →

Community health

2 of 6 standards met

Community profile →
42
✓README✓License○Contributing○Code of Conduct○Issue Template○PR Template

Recent PRs & issues

Active · Last activity 5m ago
See all on GitHub →
mattpocock

Size: about 80 lines of source, 430 of tests and test helpers. Reading order: (the fix), (the new fake), , then the preflight (, , ). Summary Found in a live run against a private repo. Every ticket failed to start with , so the spec ended in round 0. A bundled task's branch checkout fetched its base from with no in its env. The clone's credential helper reads , so it sent an empty password. Public repos fetch anonymously, which is why the fakes never caught it. Audit: every git network call in that runs on the host's side Merge's , the merge itself and the rest are local to the clone, so they need no token. The new fake world exercises every row: a whole run (two tickets, merges, the integration PR, a review and the fix round) now runs against a private remote. The fake private remote. puts a git remote helper () on the sandbox's PATH. It asks git's configured credential helpers for a password, as does, and refuses the operation unless the password is the token. So a clone, fetch, push or that runs without fails exactly as it did live. It logs each operation, so the tests also prove that none was refused and that pushes went through it. preflight. Daytona's default image has no , and the tasks use it. They now reject before they clone, push or spawn anything, in the same way checks for : checks first, before it pushes the integration branch. Otherwise each ticket's would fail as "couldn't start" and the spec would be spent. , , and from a pull request number check in , through a new internal (why the task needs it). from a branch and don't check. now says what the sandbox needs: , , the agent's CLI and . Deliberately left out Installing in the sandbox, or baking it into an image. Failing / loudly when one clone or checkout error hits every ticket, rather than marking each ticket stuck. Today one infrastructure error still sticks every ready ticket. That's a separate change. Cleaning up the integration branch a spec leaves on the remote. A documented pattern for orchestrators that the sandbox can't reach with a finish report. Evidence Before (fix reverted, new test): After: 3/3 pass. The same error the live run hit is now reproduced in the fakes and fixed. Before (preflight removed): has 4 of 5 failing: implementSpec, implement, review and merge-from-PR don't reject. After: 5/5 pass. : clean. : 127 files and 3399 tests pass. One timing flake in ("kills everything … at its kill time", off by 1 ms) failed once under load, then passed on 3 reruns and a full rerun. On clean , 125 files and 3391 tests pass. : the same two ratchet failures as on clean , and nothing new: effect/asyncFunction and test-outside-tests. The typecheck ratchet stays at 3 violations ("none new"). Merge Danger Door: two-way. It adds a token to one command's env and adds one probe before the tasks that use . Blast Radius: small. A caller whose image has no now gets a clear rejection at rather than a failure partway through. Only , , and from a PR are affected, and they all needed already. The token reaches one more command's env in the sandbox, the same one the clone and session already get. It never lands in argv or config. 🤖 Generated with Claude Code

mattpocock · 4m ago
mattpocock

Size: +1284 / -93 over 20 files: about 440 net lines of , the rest tests, a guide and the API report. Reading order: (the end of the spec), (the PR and its body), (where the rounds hand over to it), and (state and result), then , then . Summary This finishes . When the chooser has nothing left and at least one ticket has merged, now opens the integration branch's PR against the default branch. It reviews that PR once with the bundled task. After it runs one round 2 on the integration branch. Then it returns the result. The PR is never merged. The PR body comes from a template. It lists the merged, stuck and skipped tickets, with a line for each merged ticket. The spec's own line goes in only when every ticket merged. gains and . is true when the fix round reported or . When the review or the fix round fails, the says why. State gains , and . gains and , and types them for . The detached loop now ends → () → . There is one detach and one finish report per round, all on one sandbox id. Docs: a new has an section. It covers the detached webhook loop (store , verify with , reattach with env passed again, , close on ) and the held form. It also covers , vendor caps and the options. Both examples live in , so checks them against the package, and a test keeps the page and those files the same. New exported types and . The API report is regenerated, and there is a changeset. The boundary rule in now lets import and . Those are public bundled-task modules, as already is. Evidence New , on the fake sandbox with a local bare repo and a stub (added to 's stub bin): When all tickets merge, one runs, with every line, then one , and the result is . On no fix round runs, and is unchanged. After , exactly one runs, with the comments in its prompt. Its commit lands on the integration branch, and there is no second review or second PR. When the fix round ends , the result has and the reason. When the review session fails, there is no verdict and the summary says why. With a stuck ticket the result is , and the body leaves out and the stuck and skipped tickets' lines. When nothing merged, is never called and the result is . When every ticket needed no changes, no PR is opened. The three-ticket spec runs fully detached. The rounds are , with seven reports, seven distinct s and one sandbox id. The result equals the held 's (ignoring branch name and summary), and no stored state contains the token. The existing expectations now include the round. (*) On the clean base worktree, two legacy Docker-isolated tests timed out at 5 s while ran next to them (one in and one isolated-provider sync test). They pass on this branch's run, and this PR doesn't touch them. The lint failures on both are effect/asyncFunction 2 -> 5 and test-outside-tests 0 -> 1, both already on release/v1. Every file is under the 300-line cap. Left out, deliberately No real Daytona run yet. This PR is tested on fakes only. One detached run on a test repo still has to happen before release: ticket rounds, merges, the integration PR, the review and an optional fix, with a reattach between rounds, and the integration PR left unmerged. No retries for the review or the fix round. A deadline-stopped or ends the spec with the reason in , and there is no . Tickets keep their one retry. No PR when the chooser says blocked, even if some tickets merged before that. The result is , and the branch is still there. The spec's line is left out when any ticket is skipped, as well as when one is stuck. A skipped ticket is unbuilt work too. The guide is a new page, not a page. is the published v0 docs, and it has no v1 pages yet. A ticket whose reference is would clash with the fix round's session name (). Merge Danger Door: two-way The change only adds to the pre-release entry point. Nothing outside changes behaviour. Blast Radius: Callers of on release/v1 now get a PR opened against their default branch, and a review session, at the end of a spec. Neither happened before. It never merges anything. 🤖 Generated with Claude Code

mattpocock · 1h ago
mattpocock

Size: about 930 lines of source in 6 new files under , plus a 2-line export block, about 560 lines of tests, a dependency-cruiser rule, the API report and a changeset. Reading order: (the public shapes), then (, , , ), (what spawns between rounds), (pure: what a round's results do to the state), (reading results from a finish report or a held session), . Then . Summary is a new bundled task. It builds a whole spec's tickets onto one integration branch, in rounds on one sandbox. It uses only the public API: the handle, a chooser, , and . A new dependency-cruiser rule enforces that: may import only , the modules that export the tasks it uses, and type-only imports from the modules the entry points re-export types from. The is plain JSON with no token: the integration branch, the round, how many times the chooser has run, the round's sessions, each ticket's status, and the merge queue. takes the same input again, so the token and agent are passed on every step. The provisional has . Decisions that differ from the plan, or that it left open: One merge per round. The plan says merges run one at a time "within a round". A detached round's sessions must all spawn before the detach, so sequential merges can't share one detached round. Each merge is therefore its own round: . A held looks the same. Retry names. A start that reuses a finished session's name fails at , because that directory already exists. So a retry is named . and each get one retry. Skipped. The chooser knows the blocking edges and doesn't. When the chooser returns no , its tickets are marked skipped. The room check uses the public with the handle's 5-minute report margin. It runs before the chooser and before every round, against (90). A session missing from the report counts as a failed session, so its ticket is stuck. For example, one that ended before the detach call. A ticket that needs no changes is listed in . Evidence Before: there was no export. After: passes (8 tests) on the fake sandbox. It uses a local bare repo, a stub that answers each session by name, and a function chooser over : and pass. fails only on the two ratchet failures already on ( effect/asyncFunction and test-outside-tests). Nothing new. Deliberately left out: The integration PR against the default branch. The round, the fix round, and / in the result. . The chooser ticket shipped instead. User docs. doesn't cover v1 yet. A real run on a provider. Merge Danger Door: two-way All of it is new code behind the pre-release entry point. Nothing that exists today changes behaviour. Blast Radius:** contained The only shared files touched are (new exports) and (a new rule scoped to ). 🤖 Generated with Claude Code

mattpocock · 1h ago
mattpocock

Size: about 300 changed lines of source (half of it moved, not new), plus a 260-line test file and the API report. Reading order: and (the new rule), and (where it runs), the three tasks (, , ) for and , then . and are code moved out of and , unchanged except for the flag. Summary Several bundled tasks can now run side by side on one sandbox handle. Every task's input takes an optional , defaulting to the task's name, which names the session, its record and its key in the finish report. takes the same name. Each start clones into its own directory, and a start rejects a name that's already running before it clones anything. The check lives in the shared start contract, so every bundled task gets it, included (merged in from ; already took , and now passes it as the session name): , and key their definitions by the name. Left out, they keep today's keys. , and take a type parameter that defaults to today's key. "Running" means started on this handle and not yet ended for its caller. The host keeps a name a little past , until the session supervisor's answer is over, so the host now marks a session once it has ended. Without that, starting the same task again right after was refused (the existing test caught it). A start that is still cloning holds its name, so two starts of one name made at once can't both clone. The handle keeps one task deadline, and the last sets it, as before. Deliberately left out: Clearing an old clone. A start whose name matches an earlier, finished session's still fails at , because the directory exists. That's how a second default-named start behaves today too. Removing someone's directory felt like a decision for whoever needs retries. Shared-clone worktrees. Each start makes its own clone and runs its own . Names from raw calls on other handles. Each handle checks only its own sessions. Evidence Before: , 6 of 6 failed. was ignored, both starts cloned into , and the second spawn collided. After: 8 of 8 pass: two starts named and run at once, each in its own clone on its own branch, and both validate through with the named a start whose name is already running (a session) rejects before any clone (the working directory stays empty) of two same-named starts made at once, one rejects, and only one clone exists , , , and are rejected before any clone , and take the same way (a named merge clones into , and a duplicate running name rejects) Full suite after merging : , . The existing task tests pass unchanged, so leaving out changes nothing. passes. shows no new violations. It fails only on the two ratchet entries already failing on ( effect/asyncFunction, test-outside-tests). Merge Danger Door: two-way The new API is additive and optional, and the moved code is unchanged. Blast Radius: small It touches every bundled task's , through the shared contract. Session names that aren't plain directory names (, a leading or ) are now rejected by task starts. Raw / names are unchanged. 🤖 Generated with Claude Code

mattpocock · 2h ago
Structured data for AI agents

Repository: mattpocock/sandcastle. Description: Orchestrate sandboxed coding agents in TypeScript with sandcastle.run() Stars: 9133, Forks: 985. Primary language: TypeScript. Languages: TypeScript (99.1%), Shell (0.5%), JavaScript (0.3%), Dockerfile (0.1%). License: MIT. Latest release: v0.14.0 (2w ago). Open PRs: 30, open issues: 97. Last activity: 5m ago. Community health: 42%. Top contributors: mattpocock, sandcastle-agent[bot], github-actions[bot], dichioniccolo, bwcampbell9, jerome-benoit, kuLm1Fs, mellson, claude, lautarosegura and others.