Power Development

Build a unified City Power module with @downcity/city/power.

Power author APIs live in @downcity/city/power. A Power is a long-lived instance owned by City; do not create one instance per Agent.

Execution instance

import { Power, create_action } from "@downcity/city/power";
import { z } from "zod";

class ExamplePower extends Power {
  readonly name = "example";
  readonly title = "Example";
  readonly description = "An example Power.";

  constructor(private readonly client: ExampleClient) {
    super();
  }

  readonly actions = {
    status: create_action({
      description: "Return the current scope.",
      input_schema: { zod: z.object({}) },
      execute: async ({ context }) => ({
        success: true,
        data: {
          agent_id: context.agent.id,
          workspace_id: context.workspace.id,
          session_id: context.session?.id ?? null,
          tool_call_id: context.call.tool_call_id ?? null,
        },
      }),
    }),
  };
}

Use context.workspace.files for user Workspace files and context.storage.files for private Power state. context.session and context.agent.sessions are directly callable restricted handles; a Power does not need to resolve objects from IDs alone.

Unified City module

export default new ExamplePower();

An SDK host places the instance in City and adds Agents:

const city = new City({ powers: [new ExamplePower()], workspaces: [workspace] });
city.agents.add(agent);

Lifecycle

initialize/dispose belong to City's unique Power instance. Agent and Workspace are dynamic call context, not lifecycle boundaries. Key long-lived resources by their actual domain owner and close all of them in dispose. Every asynchronous Action should propagate execution.abort_signal.

Inject domain callbacks when constructing a Power

A Power reports its own committed business changes. Memory tools, host management, direct Provider operations, and background Profile optimization share the same commit points:

const memory_power = new MemoryPower({
  platform_root_path,
  on_changed: (event) => {
    if (event.kind === "knowledge") {
      application.reload_memory(event.memory_id);
    } else {
      application.reload_profile(event.target, event.agent_id);
    }
  },
});

MemoryChange includes operation: written/deleted. Knowledge events carry a logical memory_id; Profile events carry target and agent_id (null for User). No content, file paths, or Action routing metadata is included. Each committed evidence record or projection reports separately. Later failure does not undo an earlier committed change. Missing-record deletion, duplicate Profile append, and edits with unchanged Profile content emit nothing.

Callbacks run after persistence succeeds. Synchronous exceptions and Promise rejections are isolated without changing the business result, and callback Promises are not awaited. Applications own refresh batching, IPC, and UI behavior. Task's on_changed reports definition and execution-state changes; Session retains its own on_created/on_removed lifecycle protocol.

There is no general action_hooks, PowerOptions, or SDK invalidate interface. Existing pipeline/guard/effect hooks control session checkpoints, and notifications.publish creates user-facing notifications. Domain callbacks are local to the instance without historical replay or reliable retry; external file changes do not automatically emit events. Other Powers require their own domain-specific commit points; Memory support does not imply that every Power already has live change callbacks.

Installable package

example-power/
├── power.json
├── package.json
├── README.md
├── dist/main.js
└── dist/renderer.js
{
  "schema_version": 1,
  "id": "example",
  "version": "1.0.0",
  "description": "A small example Power.",
  "readme": "./README.md",
  "main": "./dist/main.js",
  "renderer": {
    "entry": "./dist/renderer.js",
    "sidebar": true,
    "mainview": true,
    "config": false
  }
}

main default-exports a Power instance or { power, main }; there is no separate agent entry. A Renderer communicates only through the host action gateway and cannot access Node, Electron, Agent objects, or Power Config files directly.

To contribute an Agent Profile tab, declare agent_config: { id, label, component } in define_power_renderer(). The component receives { agent_id, power, ui }, with types exported from @downcity/city/power/react. Enabled Powers contribute their tabs automatically; the host namespaces each tab ID by Power. No power.json capability flag is needed. Use the Power business gateway for Agent-specific operations and validate their inputs in the owning Power. See Agent Profile tab development for the exact contract and an example.

To open resource details independently, declare views: [{ id, label?, component }] and call ui.open_view({ view_id, resource_key, title, input }). The host binds the owning Power and manages tabs; each view receives { input, power, ui } and reads its resource directly. Include Agent and scope identity in resource_key. Views require no power.json capability flag. See Independent resource views for the contract and example.

Testing focus

  • Multiple Agents using one City Power initialize one instance and read the same configuration.
  • Repeated calls receive fresh Context objects with the correct Agent and Workspace.
  • dispose waits for the final execution lease.
  • Concurrent main calls activate once, and shutdown fully deactivates it.
  • Action input, JSON results, and cancellation signals remain valid.