Tools and Powers

Configure Agent Tools and provide Powers through City

Tools and Powers both participate in Session execution, but ownership differs: Agent owns custom Tools; City owns unique Power instances, configuration projection, and lifecycle.

Custom Tools

A local Agent directly receives custom Tools:

const agent = new Agent({
  id: "repo-helper",
  tools: {
    my_tool,
  },
});

They are merged with the Tools of the Workspace selected by the Session. Name conflicts throw instead of silently replacing a Tool.

Model result disclosure

The Session runtime reserves lookup for reading saved results. Power tools, Workspace tools, and custom model-bound tools share one result boundary: execute once, save the complete canonical Tool Part, then return the business value unchanged when its final UTF-8 JSON is at most 16 KiB. Larger results return a head-and-tail preview, omitted Unicode character count, result_ref, and next_cursor; the entire packet fits within 16 KiB. Use lookup({ result_ref, cursor?, limit? }) to read the immutable result, with a default of 100 lines and a maximum of 200. Pages are byte-bounded and long lines can span opaque cursors. Reading does not repeat effects or UI delivery. Direct SDK calls still return complete business data. See Messages and Parts for persisted output and replay semantics.

Workspace and Shell

Workspace provides grep, find, read, write, and edit. Configure Shell explicitly when command execution is required:

import { Agent } from "@downcity/agent";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";
import { Shell, Workspace } from "@downcity/city";

const agent = new Agent({ id: "repo-helper" });
const workspace = new Workspace({
  id: "project",
  path: "/path/to/project",
  shell: new Shell({
    sandbox_provider: new MicrosandboxProvider(),
  }),
  runtime_path: "/path/to/downcity-runtime/project",
});

Shell adds shell_exec and shell_session. Project file access follows Workspace path policy. read can also use the Session's read-only attachment capability for attachments registered as owned by the current Session. A path alone is not authorization and grants no access to private files of other Sessions or Agents. write, edit, grep, and find remain restricted by project policy. Approvals and asynchronous questions belong to a specific Session and use session.interactions() and session.respond(...).

Reading text and media

Attachments always retain path and metadata references. Static PNG, JPEG, and WebP images verified from file headers may also be included automatically: at most 2 MiB per image, 4 MiB for all request media, and within the remaining model input budget. Recent images take priority without changing output order; current and historical attachments use the same rules. PDFs and other files remain references until the Agent calls read. An automatic image omitted for budget retains its reference. Use these parameters for explicit reads:

ParameterMeaning and limits
file_pathFile allowed by project policy or attachment registered as owned by the current Session
rangeOptional text range; choose one of the two forms below
range.type: "lines"Line range with optional offset (zero-based, default 0), limit (default 500, maximum 2000), and expected_version
range.type: "bytes"Byte range with required offset (raw file byte position, including 0) and optional expected_version

The top-level object accepts only file_path and optional range. Each range object strictly accepts only the fields for its selected type. Use only { file_path } for images, PDFs, and the default first text read. For a specific text line range:

{ "file_path": "notes.txt", "range": { "type": "lines", "offset": 0, "limit": 100 } }

A text read returns at most 64 KiB and supports UTF-8 / UTF-16. A long line can return a prefix and next_byte_offset. For example, where result is the previous read result, use the corresponding returned cursor when available:

const byte_continuation = {
  file_path: "notes.txt",
  range: {
    type: "bytes",
    offset: result.next_byte_offset,
    expected_version: result.file_version,
  },
};
const line_continuation = {
  file_path: "notes.txt",
  range: {
    type: "lines",
    offset: result.next_offset,
    expected_version: result.file_version,
  },
};

Byte mode can continue a partially returned line. range.expected_version is optional, but always returning the previous file_version unchanged is recommended for continuation. It is a version value, not a path; do not invent it for the first read. Version validation rejects continuation if the file changes. Without a complete file scan, the total line count is null and sha256 may be absent. The 64 KiB cap applies to the file read result. Model-visible tool results still pass through the 16 KiB disclosure boundary described above; use lookup to read folded content.

Explicit image and PDF reads have a 2 MiB raw per-file limit and a 4 MiB raw request total. Parallel reads share a reservation. Native media enters the next model Step through a trusted internal tool message, subject to model capability and remaining request budget. Delivery revalidates file versions, real path boundaries, and the actual media total; changed files require another read. A path or metadata alone does not mean media has been delivered. Oversized files return media_too_large and explicitly report no delivery. Other binary files return metadata only. read provides no image conversion, PDF pagination, OCR, or Office parsing.

Native image encoding bytes count toward transfer limits, not body text tokens. Automatic images and explicit read use the same local dimension estimate: 1,024 tokens per 512×512 pixel tile plus 2,048, with a minimum of 8,192 per image. Unknown dimensions or native URL images reserve 32,768. This heuristic is neither a Provider billing formula nor a strict upper bound for every model. Encoded strings in body text, tool arguments, or ordinary JSON still use text estimation; PDFs and other media retain conservative accounting. Byte limits, output reserves, safety margins, and request budget protection remain independent.

Data URLs are used only for drafts and transport; saved files use canonical paths. Remote URL references do not trigger implicit downloads, and one missing attachment does not block the entire Session.

City provides Powers

The Agent constructor does not accept Powers. Once registrations are provided to City, every Agent receives them automatically:

import { Agent } from "@downcity/agent";
import { City } from "@downcity/city";
import { create_builtin_power_registrations } from "@downcity/powers";
import { Workspace } from "@downcity/city";

const workspace = new Workspace({
  id: "project",
  path: "/path/to/project",
});
const agent = new Agent({ id: "repo-helper", model });
const city = new City({
  workspaces: [workspace],
  powers: create_builtin_power_registrations(),
});

city.agents.add(agent);

City automatically exposes every registered Power to every Agent. A running City can update the collection through city.powers.add() and city.powers.remove().

Each Power ID identifies one instance inside a City with a City-level initialize/dispose lifecycle. Agents and Workspaces provide call context; they do not own Power lifecycle.

City-level configuration

The host provides one Config store for each Power. Configuration does not enter Agent or determine instance count:

const city = new City({
  power_host: {
    config: (power_id) => open_power_config_store(power_id),
  },
});

Each Power ID has one configuration inside a City. A Power models its own account collection and selection rules when needed; City does not provide a generic named-configuration layer. After saving Config, the Power refreshes any affected long-lived resources.

Calling Powers

Host code calls Actions and Hooks through an Agent/Workspace execution entry:


const result = await city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id }).run_action({
  power: "memory",
  action: "search",
  payload: { query: "project conventions" },
});

const enriched = await city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id }).pipeline("chat.enrich_message", input);
await city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id }).guard("review.require_checked", enriched);

When a Power declares Actions, the host pushes one AgentTool named after that Power. The model calls it with { action, args }, or omits action to read the action index with each schema. Power system() text is contributed at the session.system_context checkpoint.

Direct communication through PowerContext

Power author APIs come from @downcity/city/power. Action, Hook, System, and Availability receive a PowerContext with restricted city, agent, workspace, session, turn, config, and storage handles.

context.session and context.agent.sessions are directly callable in-process objects; a Power does not need to retain only session_id and query the host again. Use context.workspace.files for Workspace files and context.storage.files for private Power files.

HTTP

A Power may declare structured HTTP routes. City mounts and authenticates them and injects the request-specific PowerContext. Powers do not create independent servers.

See also