deepseek-harness/packages/session/working-directory

description, kind

description	kind
Change one Session’s working directory while existing processes retain theirs. The selected directory survives replay and appears in user context. A missing directory restores the original project when it remains available.	package-reference

@deepseek-ai/dsh-working-directory

English | 中文

Summary

Change one Session’s working directory while existing processes retain theirs. The selected directory survives replay and appears in user context. A missing directory restores the original project when it remains available.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Mount alongside fs, sessionProjections, and systemPrompt. defaultDirectory selects an absolute fallback for Sessions without an original directory; omission uses the launch directory. See the configuration catalog.

- name: '@deepseek-ai/dsh-working-directory'

---

Directory validation and publication delegate through working-directory/access, so the owner of a directory being removed can hold ensure and set into that directory until its operation settles. A listener waits only for an operation on the requested or current path, honours the request's signal while waiting, and otherwise calls next() at once; a rejection fails that access and leaves the recorded directory unchanged, with no fallback. Existing subprocesses keep their own directories.

Understand the implementation

Implementation internals — click to expand

The Session projection owns the effective directory and exposes it in Session observations, so cold readers can use it without activating an Agent; the header continues to identify the original project. Changes serialize per Session, validate through the filesystem provider, check cancellation and Agent lifetime, commit an event, and queue a user-context notice. If notice queuing fails after commit, the operation returns the committed directory and logs a warning; the next request or resume still receives the required directory context. Prompt assembly validates the current directory before publishing its required context contribution. Existing processes and sandbox grants keep their independent ownership. The service implementation defines the API. Failures are WorkingDirectoryError instances: WORKING_DIRECTORY_INVALID for an empty or malformed path, WORKING_DIRECTORY_NOT_FOUND when a requested change names no existing directory, and WORKING_DIRECTORY_UNAVAILABLE when neither the current directory nor the original project exists or the service has been disposed.

No runtime invariant companion is published because the service reads its only directory state from the Session projection and checks filesystem validity at use.

---

Further Exploration

• Working directories — shared runtime behavior.
• Session group — durable Session services.
• Testing — composition and replay verification.

---

Model Experience

Working directory context

What the model sees

The current value is Current working directory: <JSON-quoted absolute path>. Each committed change, including automatic recovery, attempts to queue a user-context notice through the ordinary Agent inbox. Cancellation or disposal may discard unadmitted notices; the durable directory remains available to the next request. Directory context stays outside the system prompt and remains enabled when optional runtime context is disabled.

Token effect

The initial snapshot and changed values add user-context tokens; unchanged snapshots are not repeated.

KV Cache effect

Directory transitions append context without replacing the stable system-prompt prefix. A changed directory or recovery creates new context after retained history.

Known Limitations and Deferred Work

• Missing original project — when the current directory and the original project are both unavailable, prompt assembly rejects every model turn, including chat-only turns. The service does not choose or recreate a repository. Restore the original directory, or use SDK setWorkingDirectory (set_working_directory in Python) or ctx.workingDirectory.set to select an existing absolute directory before retrying. Existing shells retain their process-local directories.

Dev Note

Working context for maintainers — click to expand

None.