@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, Plugins, 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 });

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 Plugins.
  • 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/Plugin 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/
└── plugins/

StorageProvider is intentionally domain-neutral. Agent runtime interprets Session data, while the City Plugin runtime interprets Plugin 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.

Table of Contents

OwnershipStorage