Agent main session

Keep the main conversation in a private directory and dispatch work into explicitly selected projects

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,
  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

Only agent sessions receive these tools:

Tool	Purpose
`session_start`	Create work in an explicitly selected project and return immediately after acceptance
`session_check`	List work sessions or inspect one session's messages and pending interactions
`session_reply`	Answer a work session's approval or question
`session_stop`	Stop a work session

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. Users can keep talking to the main session while work runs, and the Agent can check progress with session_check.

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.