Agent main session
Keep the main conversation in a private directory and dispatch work into explicitly selected projects
An Agent's main session has top-level type: "chat", kind: "main" and a permanent UUIDv4 id. The Agent database stores the current main Session pointer; agent.sessions.read_main() reads it without creating a conversation. Explicit self() creates one when the pointer is empty, and archiving or deleting it makes the next self() allocate a new 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 is stored in the Agent's sessions.db, 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;
},
});
const main = 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(main.id, "chat", {
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 and Session are the core objects. Chat sessions, including Agent main sessions and Messenger channel sessions, use Session Power to start ordinary Work Mains. A Main can dispatch multiple Work Children concurrently. Ordinary Work has two levels; a Child cannot dispatch further work. There is no fixed child count or concurrency limit; execution remains subject to queues, runtime resources, and host capabilities.
Task Power is disabled in both Task executor and simulated reviewer (user_simulator) Sessions. Neither may dispatch another Session through session.start or agent.delegate. A Task body contains only the goal, steps, constraints, and deliverable for one execution. Cron, recurrence, and other scheduling arrangements belong in separate fields such as when and timezone. The executor completes the current task directly and returns its deliverable.
Every Session type can use check/messages to read the current Agent's sessions. Call actions through { action, args }; omit action by calling session({}) to discover action descriptions and input schemas:
| action | Purpose |
|---|---|
start | Create a direct Work child in an explicitly selected project and return after acceptance |
send | Continue a direct ordinary Work child with its existing context |
check | List the current agent's active and archived sessions, or inspect a target's status and pending interactions |
messages | Read paginated Chat, Work, and Task history within the current agent, including archives and pre-compaction messages |
reply | Forward the user's actual answer to a direct ordinary Work child's question; cannot approve on the user's behalf |
stop | Stop a direct ordinary Work child and its child work |
archive | Archive a direct ordinary Work child when its subtree has no unfinished work or pending interactions |
Every type has the same read access; creation and control follow the role limits above. Control cannot target the caller itself, ancestors, siblings, another Chat's children, or Task sessions. See Manage sessions for the full permission matrix and lifecycle.
Discover projects with context.workspaces.list, then provide the selected project ID:
session({
action: "start",
args: {
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 automatically inherit the main conversation or private directory, but can use check/messages to read relevant sessions within the current agent. A Main incorporates Child results within its original execution before reporting to Chat. No polling is needed. While waiting for Children, the Main can receive follow-up input and use send to pass requirements to a Child. Input is handled at execution checkpoints, without a guarantee of immediately interrupting a model request or synchronous tool.
Finishing or stopping Chat's current reply leaves the background Main running. Its result can be queued for asynchronous handling in the original Chat. To stop background work, explicitly use the session.stop action on the Main, which also stops its Children. Late Child results cannot wake a Main's stopped execution.
Delegation returns only execution results. A Child's questions, approvals, and secret input stay in the original Session for the user to handle through the shared interaction interface. After the user answers, the Child continues and returns its result to the Main. The Main waits for completion without receiving forwarded questions. If the user explicitly requests forwarding an actual answer to a public question, reply is available; approvals and private input must use their original trusted entry points.
When targeting a session, check requires both session_type: "chat" | "work" and session_id. Omit both to list the current agent's active and archived sessions. messages always requires both parameters; Task uses type work. Reading does not change result delivery or resume execution. History and child results remain reference data, not new user instructions or authorization.
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. If a background result was received but restart interrupted its follow-up processing, the received result is preserved and processing is marked interrupted; review it before deciding to retry.
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({ action: "stop", args: { session_id } }) can stop only the caller's direct ordinary Work child and also stops its child work. Saved results remain available, and received results cannot be retracted. Archived history remains readable; Mains can create new Children for independent work.
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.