Parent roadmap: #1439

Artifacts looks like the missing versioned handoff layer for Think workspaces and sessions: one repo per agent/session/task, forkable history, Git-compatible tooling, and short-lived repo-scoped tokens.

This issue tracks an integration spike and product/API design. It should start as an additive integration, not a replacement for Think's fast DO-local Workspace.

Why this fits Think

Think already gives an agent:

• durable chat execution and resumable streams
• Session-backed memory/history/branching
• a DO-local Workspace for fast file operations
• codemode / sandbox / browser / MCP integration points
• sub-agent composition and multi-chat parent/child patterns

Artifacts adds the missing versioned repository boundary:

• share a session's files with another user or tool
• fork work from a known point
• time-travel through file state and associated harness metadata
• hand work off to standard Git clients, Sandboxes, CI, or review systems
• isolate one agent/session/task per repo with repo-scoped tokens

Initial use cases

1. Session repo

Create one Artifacts repo per Think chat/session. Store the workspace tree in Git and attach harness metadata using Git notes or structured files.

Possible metadata:

• user prompt / task summary
• assistant summary
• model/provider info
• run IDs and request IDs
• branch/session IDs
• links back to Think Session messages or compaction summaries

Questions:

• When do we commit: after every turn, on demand, before handoff, or after workspace changes?
• Should message history live in Git notes, files, or stay in Session with only references in Artifacts?
• What is the minimal useful export format?

2. Forkable chat

When a Think conversation is forked, shared, or handed to another user/agent, fork the Artifacts repo too.

This should let us model:

• "try another approach from here"
• "send this session to a teammate"
• "spawn a reviewer agent from the current workspace state"
• "compare outputs from two branches or sub-agents"

Questions:

• How should Think Session branching map to Artifacts forks/branches?
• Is one repo per chat enough, or do branches/forks deserve separate repos?
• How do we keep branch metadata visible in the chat UI?

3. Sandbox handoff

Create or reuse an Artifacts repo, mint a short-lived write token, and pass an authenticated remote into Cloudflare Sandbox / ArtifactFS for Tier 4 execution.

Flow sketch:

1. Think commits current workspace state to Artifacts.
2. Think creates a short-lived write token.
3. Sandbox receives ARTIFACTS_GIT_REMOTE or header/token config.
4. Sandbox clones or mounts via ArtifactFS, runs heavyweight toolchains/tests, commits results, and pushes.
5. Think pulls/imports the result or records the remote/commit for user review.

Questions:

• What is the right Think API: tool, helper method, extension, or example-local pattern?
• Do we need a first-class createSandboxTools story first?
• How do we present pushed changes back in the Think chat/workspace UI?

Existing local building blocks

We likely do not need to start from scratch:

• @cloudflare/shell/git already wraps isomorphic-git for clone, status, add, commit, fetch, pull, push, etc.
• WorkspaceFileSystem adapts a Think/Workspace-like filesystem to the interface isomorphic-git expects.
• createWorkspaceStateBackend() already exposes Workspace as codemode state.*.
• Think's WorkspaceLike typing allows custom workspace implementations and proxies.
• examples/assistant already explores shared workspace ownership via a parent DO.

Design constraints

• Keep Think's DO-local Workspace as the fast Tier 0 filesystem for now.
• Treat Artifacts as versioned persistence and handoff first.
• Do not persist write tokens in chat history, Session context, Git notes, or workspace files.
• Mint short-lived repo-scoped tokens only after authorization.
• Prefer one repo per session/task/user unit over one hot shared repo.
• Include stable identifiers in repo names: user/directory ID, chat ID, task ID, or run ID.
• Define retention and cleanup up front. Repos persist until deleted.
• Consider namespace sharding for high-rate workloads.
• Treat ArtifactFS as a Sandbox/large-repo optimization, not a Workers/DO dependency.

Proposed first milestone

Build a narrow proof of concept in an example or test harness:

• Add an Artifacts binding to a Think example or focused experimental app.
• Create an Artifacts repo for a chat/session.
• Commit current Think workspace files using existing @cloudflare/shell/git primitives.
• Push to Artifacts with a short-lived write token.
• Fork the repo and show how a second Think session or Sandbox could consume it.
• Document what metadata belongs in Git notes/files vs what stays in Think Session.

Acceptance criteria for the spike

• A Think workspace can be exported to an Artifacts repo without leaking tokens.
• The export has a clear commit/metadata convention.
• A forked repo can be associated with a forked/new Think session.
• The design explains when to use DO-local Workspace, Artifacts, Sandbox, and ArtifactFS.
• The roadmap decides whether this remains an example/integration or becomes a first-class Think API.

References

• Roadmap umbrella: Project Think roadmap: durable agent platform preview to stable developer experience #1439
• Artifacts launch post: https://blog.cloudflare.com/artifacts-git-for-agents-beta/
• Artifacts docs: https://developers.cloudflare.com/artifacts/
• Best practices: https://developers.cloudflare.com/artifacts/concepts/best-practices/
• Workers binding: https://developers.cloudflare.com/artifacts/api/workers-binding/
• Git protocol: https://developers.cloudflare.com/artifacts/api/git-protocol/
• isomorphic-git example: https://developers.cloudflare.com/artifacts/examples/isomorphic-git/
• Sandbox SDK + Artifacts: https://developers.cloudflare.com/artifacts/examples/sandbox-sdk-artifacts/
• ArtifactFS: https://developers.cloudflare.com/artifacts/guides/artifact-fs/