@downcity/agent

Agent, AgentSessions, Session, and execution runtime.

@downcity/agent provides Agent, AgentSessions, Session, and the execution runtime. @downcity/city provides RemoteAgent and City. Agents do not own Powers. City owns unique Power instances, configuration projection, and lifecycle; Power author contracts live in @downcity/city/power. Workspace resources come from @downcity/city.

const city = new City({ workspaces: [workspace] });
const agent = new Agent({ id: "assistant" });
city.agents.add(agent);
const session = await agent.sessions.create({ workspace });
const turn = await session.prompt({ query: "Hello" });
const result = await turn.finished;

Provide Power instances through CityOptions.powers or city.powers.add() before use. city.agents.add() only registers an Agent; every City Power becomes available automatically.

Session origins and execution profiles

origin.category selects the chat or work category, and origin.type describes the business purpose. Callers define custom types and declare their category explicitly:

const session = await agent.sessions.create({
  origin: { category: "work", type: "research" },
});

Each Power defines its own business types. A type name labels the purpose; the actual execution configuration supplies tools, instructions and the model. Memory Power creates memory Sessions in the work category and selects its dedicated execution profile. Using the same type name alone grants neither Memory tools nor permission to commit Job results.

A Session bound to a dedicated profile persists its profile ID, version and model identity. Restoration must resolve that profile. An unavailable profile or mismatched model identity rejects execution without falling back to Agent defaults.

Read file changes for each turn

A Session bound to a Workspace persists file edits successfully committed by the built-in structured write and edit tools in the final Assistant Message. The diff comes directly from each atomic file-tool mutation instead of scanning the worktree before and after a turn, so changes made by shell commands, scripts, external editors, or other Sessions are excluded. Git is not required.

The data-session-turn-file-diff data part contains per-file status, line counts, and unified diff. Use the exported parser to read it safely:

import { read_session_turn_file_diff_data } from "@downcity/agent/session";

const page = await session.messages();
for (const message of page.items) {
  if (message.type !== "assistant") continue;
  for (const part of message.parts) {
    if (part.type !== "data") continue;
    const file_diff = read_session_turn_file_diff_data(part);
    if (file_diff) console.log(file_diff.files, file_diff.additions, file_diff.deletions);
  }
}

Group and GroupSession

Group is a collaborative subject with its own model, members, dispatch strategy, and GroupSession collection. A GroupSession persists shared messages and dispatch state under groups/<group_id>/sessions/<group_session_id>/.

After the first user message is persisted, the GroupSession uses Group.model to generate a short title asynchronously. The title is canonical metadata stored in meta.json; it is separate from preview_text, which remains the latest-message preview. Later messages do not replace the title. Subscribe to { type: "title", title } for live title changes, or call group_session.rename(title) to persist a manual title and prevent background generation from overwriting it.

const group_session = await group.sessions.create({ workspace });

group_session.subscribe((event) => {
  if (event.type === "title") console.log(event.title);
});

await group_session.prompt({ query: "Review the login flow" });
await group_session.rename("Login flow review");

const sessions = await group.sessions.list();
console.log(sessions[0].title, sessions[0].preview_text);