@downcity/city/workspace

Project resources, file tools, environment, and Shell.

@downcity/city/workspace provides the Workspace implementation used by an Agent; common constructors are also exported from @downcity/city. A Workspace owns the project path, rooted file access, file and search tools, environment variables, and an optional Shell. It does not own Agent identity, Powers, Sessions, storage, or model calls.

pnpm add @downcity/city @downcity/sandbox-microsandbox
import { Agent, City, Shell, Workspace } from "@downcity/city";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";

const workspace = new Workspace({
  id: "project",
  path: process.cwd(),
  env: { NODE_ENV: "development" },
  shell: new Shell({
    sandbox_provider: new MicrosandboxProvider(),
  }),
});

const city = new City({
  workspaces: [workspace],
});
const agent = new Agent({ id: "repo-helper", model });
city.agents.add(agent);
const session = await agent.sessions.create({ workspace });

A Session determines its workspace_id at creation. Releasing or restoring Workspace resources does not change that ownership; restoration accepts only the same ID. History remains readable while the original resources are unavailable, and execution requires the original Workspace. Cross-Workspace parent and Child delegations retain independent ownership.

Ownership

  • Workspace owns project resources and the optional Shell.
  • Shell owns its Sandbox Provider, persistent Workspace Sandbox, and Shell Sessions.
  • City owns registered Workspaces without understanding their execution backend.
  • Agent owns identity, instruction, model, custom tools, and Sessions; City owns Powers.
  • AgentSessions owns Sessions. A Workspace is only a resource that a Session may use.
  • Shell is a Workspace capability. There is no separate @downcity/shell package.

An Agent can create Sessions with multiple Workspace resources. A Workspace may be registered in a City or managed by the host outside City. Agent-private Sessions and City-allocated Agent/Power execution data remain isolated.

After an atomic file commit, the structured write and edit tools report a workspace.file_mutation through WorkspaceToolActionResult.effects. Effects are not sent to the model as Tool output. The Agent Session collects them only for the current Turn and projects file mutations into an Assistant data part when the Turn closes. Shell and external edits do not produce this effect.

Storage

City provides a domain-neutral Storage Provider. The default is in-memory; a host can inject a local file provider when persistence is needed. With a local provider, runtime state is centralized outside project directories:

~/.downcity/agents/<agent_id>/
├── sessions/
└── powers/

StorageProvider is intentionally domain-neutral. Agent runtime interprets Session data, while the City Power runtime interprets Power data. Workspace does not own or create this storage. Project File/Search tools remain rooted at the real project path and cannot read this private state.

Edge adapters should import WorkspaceRuntime and protocol types from @downcity/type/workspace so they do not load Node.js filesystem, PTY, or local Shell implementations.

SSH Workspace

pnpm add @downcity/workspace-ssh
import { SshWorkspace } from "@downcity/workspace-ssh";

const workspace = new SshWorkspace({
  id: "remote-project",
  host: "build-server",
  root_path: "/srv/project",
  name: "Remote project",
});
await workspace.validate();
city.workspaces.add(workspace);
const session = await agent.sessions.create({ workspace });

SshWorkspace implements WorkspaceRuntime using system OpenSSH configuration and strict known_hosts verification. Construction does not connect; validate() explicitly checks Linux/macOS, Python 3.8+, ripgrep, POSIX ps and directory access, and loads the remote environment. SDK calls reject unknown hosts by default. Independently verify host identity first; Desktop provides an explicit fingerprint-confirmation flow. The adapter does not save passwords, upload private keys, install remote software or start a persistent service.

SshDirectoryBrowser provides explicit, read-only browsing before registration. Call await SshDirectoryBrowser.create(host, signal), then read_directory({}, { signal }) to obtain the remote user's Home, or pass { path, cursor } to navigate and paginate. SshDirectoryPage returns the canonical path, nullable parent_path, folder entries (including directory links), and nullable next_cursor. Pass the canonical path to registration; never trim folder names. Pages contain at most 100 folders and 64 KiB, scanning at most 20,000 entries. Always call dispose() in finally; it terminates channels and removes the temporary configuration snapshot. Unknown hosts fail unless a trusted host UI explicitly confirms the exact SshHostKeyError.challenge.prompt. Browsing disables configured LocalCommand, RemoteCommand and KnownHostsCommand, and rejects configurations with Match exec, custom ProxyCommand or dynamic Includes before starting SSH. Static configuration and ProxyJump are supported. Browsing never registers a Workspace.

path is an ssh:// logical address; files.root_path is the remote POSIX directory. Never pass remote paths to local fs. File capabilities include bounded UTF-8/UTF-16 reads, version cursors, atomic writes, unique-match edits, directory operations and ripgrep search, with symbolic-link escape protection. Shell provides remote commands and PTY sessions with remote-user permissions, without local Sandbox isolation or Desktop host execution. Closing the channel cleans up the supervised process group; commands that deliberately detach require separate remote management.

The current City keeps Agent and Session storage locally. Explicitly read small images and PDFs become Session attachment snapshots. Text tools return at most 64 KiB, with a default of 500 lines and a maximum of 2000; writes are limited to 1 MiB and explicit media to 2 MiB. Writes and commands are never automatically replayed after failure. Inspect remote state after a disconnection following submission. City owns Workspace disposal; independent callers must call dispose(). Remote refresh is host-driven rather than local live file watching.