docs(wg): add Scratch RFC (session scratch directory) - #915
Merged
Conversation
Names a primitive the guide had only leaned on informally: the per-session, system-managed, ephemeral filesystem area where the agent does working I/O and where produced files (generated images/video, downloads, conversions) land by default — distinct from the durable workspace. States the scratch contract: host-owned and per-session (S1); ephemeral, with durability only by promotion out of scratch (S2); the default output sink (S3); reachable without per-operation approval yet inside sandbox containment (S4); and not the workspace — workspace edit contracts don't govern it (S5). Plus lifecycle, a bindings table for what hosts vary, and the implementor checklist. Reconciles the prior informal usage: binary.md's 'Scratch space for extraction' now defers the concept to this canonical page (its section is the archive- extraction application); vision.md's stage-to-scratch mention links here. Wires the page into the cluster hub. Grounded against codex (writable-roots + OS tmp, no managed dir), opencode (managed tmp + tool-output store, allowlist-reached), and sandbox products (/mnt/data-style per-session mounts); kept code- and product-agnostic per WG doctrine.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
5 Skipped Deployments
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
WalkthroughAdds a new ChangesAgent scratch filesystem spec
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9660794b68
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex P2 on #915: binary.md still offered a '<workspace>/.agent-scratch/' location with 'survives reboots' as a pro, which contradicts the new scratch contract — S2 (ephemeral, bounded lifetime) and S5 (not the workspace). Drop the workspace-resident row; keep OS-tempdir and sandbox-provided (both satisfy S2/S5), and frame the table as scratch's location bindings seen from the extraction case.
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
1 participant
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.
What
Adds a dedicated WG spec —
docs/wg/ai/agent/scratch.md— naming a primitive the guide had only leaned on informally (the stage-to-scratch perception path invision.md, the archive-extraction scratch inbinary.md): the per-session, system-managed, ephemeral filesystem area where the agent does working I/O and where produced files land by default, distinct from the durable workspace.Why now
Surfaced while planning the
generate_image/generate_videoagent tools: when the agent produces a file (a generation, a download, a conversion), there's nowhere for it to land — the strategic agent's only durable fs surface is the workspace, which is the wrong place for throwaway output. Scratch is that tool's placement target, so the contract lands first (the tool impl is deferred).The contract
Five invariants:
Plus lifecycle, a bindings table for what hosts vary (location, cleanup policy, reach mechanism, surface exposure), and the implementor checklist.
Reconciliation
binary.md's "Scratch space for extraction" now defers the concept to this canonical page (its section is the archive-extraction application — its location notes are this page's bindings seen from that use case). Link only, no behavioral edit.vision.md's stage-to-scratch mention now links here.index.mdPages table).Grounding
Primary-source: codex (writable roots = cwd + OS
/tmp/$TMPDIR, no managed dir), opencode (managed/tmp/opencode+ atool-output/store, reached via anexternal_directoryallowlist), and sandbox products (OpenAI/mnt/data, AgentCore/mnt/workspace, e2b — per-session managed mounts). Per WG doctrine the page stays code- and product-agnostic; the grounding informed confidence, not citations.Scope
Spec only. The
generate_*tool impl and any code (a binary-write primitive, the scratch manager, capability wiring) land when the impl issue is taken, after this RFC sets the contract.Summary by CodeRabbit