Agent main session

An Agent's main session has origin.type = "agent" and uses the Agent ID as its session ID. It keeps the ongoing conversation and can dispatch, inspect, reply to, and stop work sessions.

Private directory in Desktop

Desktop gives each Agent a fixed directory:

~/.downcity/agents/<agent_id>/main/

This is the main session's own Workspace, providing files, Shell, and Power execution. It is not a user project and does not appear in the Works project list. Switching projects or reopening the Agent does not change this directory. Conversation history remains under sessions/agent/<agent_id>/, separate from files in main.

Project tasks run in work sessions. Dispatch must explicitly select a project Workspace; work sessions do not inherit the main session's private directory.

SDK access and restoration

The SDK does not choose the directory location. The host creates and owns the Workspace instances:

const agent = new Agent({
  id: "coder",
  model,
  workspace: main_workspace,
  resolve_work_workspace: async (workspace_id) => {
    const workspace = project_workspaces.get(workspace_id);
    if (!workspace) throw new Error("Project Workspace not found");
    return workspace;
  },
});

await agent.sessions.self({ workspace: main_workspace });

// self uses its Workspace argument only for creation.
// Restore the instance explicitly when opening an existing session.
const session = await agent.sessions.get(agent.id, "agent", {
  workspace: main_workspace,
});
const turn = await session.prompt({ query: "Inspect project CI and dispatch a repair task." });
await turn.finished;

resolve_work_workspace resolves explicit project targets. It does not restore the main session or choose a default project. The host should reject unknown projects and the main session's private Workspace.

Only workspace_id is persisted. After restarting, the host must inject the Workspace instance again; a stored ID alone does not enable files or Shell. get() also applies the supplied instance when a cached session has not yet recovered its Workspace.

Dispatching work

Agent main sessions and Messenger channel sessions receive these tools. Work sessions do not dispatch recursively:

Discover projects with context.workspaces.list, then provide the selected project ID:

session_start({
  workspace_id: "project-workspace-id",
  query: "Fix the three failing CI tests and report the cause and validation results.",
  title: "Repair CI"
})

A work session receives the complete task text and target project Workspace. It does not inherit the main conversation or private directory. session_start returns session_id and delegation_id; the runtime binds the actual calling session and returns completion or failure to that session automatically. Use session_check when asked about progress or when responding to pending interactions.

Results enter the parent's existing prompt() queue as context tagged delegation_result. Stable request_id values deduplicate work and result inputs, including inputs merged into a running Turn. If an idempotent input is stopped before persistence or persistence fails, prompt() rejects submission and the result remains pending for retry. Delegated output is reference data, not new user instructions. If the parent is archived or unavailable, the result is retained without creating a replacement session.

Resuming delegations

After binding persistent storage and preparing Workspaces, Powers, and message subscriptions, SDK hosts call:

await agent.resume_work();

This starts unfinished work and retries pending delivery in the background; it does not wait for completion. Desktop calls it during startup. Standalone SDK storage is in memory; recovery across processes requires persistent storage supplied by City.

Recovery follows existing Session semantics: completed Turns reuse persisted results, unexecuted inputs can be submitted, and interrupted Turns with streaming output are finalized as interruption failures and returned to the parent. Previously executed tool operations are not automatically replayed.

Supply the main Workspace through the Agent's workspace option and restore projects through resolve_work_workspace. Hosts can provide an idempotent prepare_work_session(session) callback to restore session-specific models and message subscriptions before execution or result delivery. This callback prepares resources only; it must not submit model input.

session_stop persists cancellation before stopping execution and suppresses results that have not yet been submitted. Results already accepted by the parent cannot be retracted by stopping the child. Agent release suspends delivery and retains completed results for the next recovery.

agent.sessions.list() lists the work partition by default, keeping the main session out of project conversation lists. Archiving or deleting the main session allows it to be recreated on the next access; files in main remain separate from its conversation history.