Turtle
38c7a9fbf4
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| Create and enter a retained Git worktree under the calling Session file policy. | package-reference |
@deepseek-ai/dsh-experimental-worktree
English | 中文
Summary
Create an isolated checkout from a local commit and continue the same Session in it. Each operation creates a new named branch and leaves the source checkout intact. The existing sandbox governs all writes. Leaving the checkout retains its files and branch.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Mount the service alongside workingDirectory, fs, subprocess, sandbox, and sandboxPolicy providers. Add the tool package when models need the operation.
- name: '@deepseek-ai/dsh-experimental-worktree'
- name: '@deepseek-ai/dsh-experimental-tool-worktree'
ctx.worktrees.create(agent, { name?, from? }, signal?, onPhase?) creates a new branch and checkout, then enters the canonical checkout directory through ctx.workingDirectory.set. from resolves to a local commit before creation and defaults to HEAD; staged, unstaged, untracked, and ignored source files are not copied. baseCommit reports the resolved commit object name; repository-local replacement refs still apply to the checked-out content. Checkout disables configured Git clean, smudge, and process filters without changing repository configuration. An existing branch or checkout path is an error. The returned record contains path, branch, baseCommit, and repositoryRoot. An optional fourth argument, onPhase, receives prepare before validation, directory allocation, and branch creation, and checkout before the files are written and the checkout is entered; it must not throw.
ctx.worktrees.restore(agent, { path, branch, baseCommit, repositoryRoot }, signal?, onPhase?) checks a removed worktree out again at its recorded directory. It validates the recorded repository root, full commit object name, branch, and canonical target inside the configured pool before mutation. It removes only the missing target's unlocked registration with git worktree remove; other worktrees and locked registrations remain unchanged. It then checks out the branch when it still exists, or creates the branch again at baseCommit when it does not, and reports which happened as branchRecreated. An existing directory is an error. The calling Session's working directory does not change, and changes that were never committed are not recovered. Checkout disables filters as creation does. onPhase receives prepare before validation, target-registration cleanup, and branch creation, and checkout before the files are written; it must not throw.
The default checkout directory is <current checkout root>/.agents/worktrees/<name>. The returned repositoryRoot is the top-level directory of the caller’s current checkout; when it is a linked checkout, the pool is nested inside it. Omitted names join the dsh- prefix, the first eight hexadecimal digits of the UUID in the Session id, a hyphen, and four random hexadecimal digits, such as dsh-6b1f02c4-9a3e; a Session id without a UUID gets eight random hexadecimal digits after the prefix. generatedWorktreeName exports the same rule for callers that name a worktree before creating it. The service writes a .gitignore containing * and a trailing newline only when its allocation creates the pool; existing files and ignore rules are preserved. Relative directory, generated namePrefix, executable choices, and process limits are configurable in the configuration catalog.
Understand the implementation
Implementation internals — click to expand
Git and directory allocation run through the mounted subprocess and sandbox providers with the calling Session's existing file policy. Creation does not widen write access to the destination or shared Git administration directory. Directory creation claims the destination exclusively; cancellation and failed setup can leave retained artifacts, whose path appears in the error. Service disposal aborts pending operations and waits for their settlement.
| Source | Responsibility |
|---|---|
src/index.ts |
Resolve the source revision, create the checkout, and publish the new working directory |
src/process.ts |
Confine literal argv, cap output, and await process termination |
src/directory.ts |
Claim the destination and initialize a newly created pool's ignore file |
No runtime invariant companion is published: Git owns checkout registration and the working-directory service owns the Session directory; this package retains no independent projection of either.
Further Exploration
- Worktree subsystem — request, result, and service reference.
- Working directory — recorded Session directory and directory changes.
- Worktree tool — model-facing creation.
- Subprocess — process ownership and execution worlds.
- Creation decision — retained checkouts and existing write grants.
Model Experience
Indirectly, through the worktree tool's creation result and the working-directory service's recorded Session context.
KV Cache effect
This package contributes no prompt text. Its consumers own the appended tool result and recorded directory context.
Known Limitations and Deferred Work
- Retained artifacts — leaving a worktree keeps its branch and files. Setup failures can also retain partial artifacts; checkout removal and branch deletion belong to the user or another consumer.
- Local revisions only — creation does not fetch commits or missing partial-clone objects, initialize submodules, install dependencies, or copy uncommitted files. On Git that meets the execution requirements, missing local objects cause creation to fail.
- Filtered representations — checkout skips configured filters to avoid executing repository-configured programs or triggering implicit downloads. Git LFS pointers and encrypted blobs stay in their stored representation; hydration or decryption is a separate user-controlled operation.
- Execution requirements — the subprocess provider must offer Git and Node in the same execution world as the filesystem provider. Git must honor
GIT_NO_LAZY_FETCH, which Git 2.45 and the 2.39.4, 2.40.2, 2.41.1, 2.42.2, 2.43.4, and 2.44.1 maintenance releases do; older releases ignore it and proceed instead of failing, so creation can fetch missing partial-clone objects from a promisor remote. Thegit --no-lazy-fetchoption would reject these releases, but it exists only in Git 2.45 and later and also rejects the patched maintenance releases. The existing sandbox must permit all checkout and shared Git metadata writes.
Dev Note
Working context for maintainers — click to expand
The sandboxed Node child supplies exclusive directory creation, which the filesystem service does not expose, and identifies whether this service created the pool. The filesystem contract permits bare providers such as fs-local to ignore sandboxPolicy on writes; createIfAbsent protects a file but neither enforces permissions nor identifies who created its directory. Keeping directory allocation and ignore-file creation under the same process sandbox as Git preserves refusal of existing checkout paths and the condition for creating .gitignore.