Custom Power
Build, package, and configure an installable Downcity Power
One directory defines one Power. The Power ID is its install directory, City catalog key, and runtime identity. There is no separate Extension identity.
Two optional entries
Power
├── main provides City instances, lifecycle, management logic, and actions
└── renderer declares workspace, Config, Agent Profile, independent views, or message contentEach entry is optional, but at least one is required. A Power may provide only City runtime capabilities, only a Sidebar + Mainview workspace, only Config, or the complete experience.
Recommended development layout:
github-power/
├── power.json
├── package.json
├── README.md
├── assets/icon.svg
├── src/
│ ├── power.ts
│ ├── main.ts
│ └── renderer.tsx
└── dist/
├── main.js
└── renderer.jsBoth entries use ESM. main.js must be self-contained. renderer.js is a single-file browser bundle that default-exports a Renderer definition with optional sidebar + mainview, config, agent_config, views, activity, input, and view slots. Downcity does not install dependencies or run build scripts.
Direct SDK usage
SDK users can construct a CityPowerRegistration directly without power.json:
const registration = {
id: "github",
title: "GitHub",
description: "GitHub integration",
readme: "/absolute/path/README.md",
has_config: false,
has_sidebar: false,
has_mainview: false,
power: new GithubPower(),
};
const city = new City({
powers: [registration],
workspaces: [workspace],
});
city.agents.add(agent);The following entry protocol is only needed when CLI or Desktop must install, discover, and manage the Power.
Power definition
{
"schema_version": 1,
"id": "github",
"version": "1.0.0",
"title": "GitHub",
"description": "GitHub integration",
"readme": "./README.md",
"icon": "./assets/icon.svg",
"main": "./dist/main.js",
"renderer": {
"entry": "./dist/renderer.js",
"sidebar": true,
"mainview": true,
"config": true
}
}renderer.sidebar and renderer.mainview must both be true or both be false; renderer.config is independent. The actual default export must exactly match these three static capabilities. package.json must declare "type": "module". readme must point to a .md user document inside the Power root. Desktop safely renders that file in the Power Overview; its name and subdirectory are up to the author, and it should describe purpose, configuration, and required credentials. The icon may be an HTTP(S) URL or a file relative to the Power root and is used in Power navigation and the Overview.
Unified Power entry
The main file default-exports one Power instance. There is no separate agent entry or second
main lifecycle. During initialize(), power.action() registers Sidebar/Mainview Actions and
power.config_action() registers Config Actions:
import { Power, type PowerLifecycleContext } from "@downcity/city/power";
class GithubPower extends Power {
readonly name = "github";
readonly title = "GitHub";
readonly description = "GitHub integration";
initialize({ power, notifications }: PowerLifecycleContext) {
power.config_action({
id: "config.read",
run: async (_input, context) => {
const config = context.config.get();
return { api_url: config.api_url, token_configured: Boolean(config.token) };
},
});
power.config_action({
id: "config.save",
run: async (input, context) => {
const current = context.config.get();
const config = validate_and_restore_secret(input, current);
await context.config.set(config);
return { saved: true };
},
});
void notifications.publish({
topic_key: "sync:repository",
event_id: "sync-run-123",
kind: "update",
scope: "inbox",
outcome: "success",
title: "Repository sync completed",
route: { repository: "downcity", view: "activity" },
});
}
}
export default new GithubPower();One Power ID maps to one instance, one lifecycle, and one configuration per City. City injects the
unique Config store into Config actions, while the execution instance reads its current snapshot from
PowerContext.config.
notifications.publish() and notifications.dismiss() are bound to the current Power and trusted Agent scope, and delivered to the City's single Notification Power. route stays inside the publishing Power's workspace. A publisher cannot impersonate another Power or select arbitrary Desktop pages. topic_key identifies the matter, and event_id identifies the original event. Successive syncs for one repository update the same matter; a new event or changed content becomes unread, while repeating the original event preserves read state. Explicitly provide kind (reply / update), scope (session / inbox), and outcome (success / failure / info). A title alone cannot express failure. Inbox displays inbox scope. The badge counts respondable original requests plus unread inbox failure matters; success/info updates retain unread dots without increasing the number, and ordinary conversation replies use session scope. Power supplies pending_request_count, unread_update_count, unread_failure_count, and final badge_count in one snapshot. Inbox read and clear shortcuts match ordinary update IDs and created_at versions without changing original Interactions or business history. Withdrawal removes the notification without changing business state.
PowerLifecycleContext.system exposes only explicitly authorized City host capabilities. To append a background result to an existing Session, call append_agent_session_message({ agent_id, workspace_id, session_id, category, text }). All four identity fields must come from an explicit persisted target; a Power must not scan for or guess a Session.
For functional pages such as a Skill manager, system.list_workspaces() returns summaries of Workspaces registered by the host. A Power is trusted local Node.js code; it must validate action inputs and own its file, network, and long-lived resource behavior.
Renderer entry
The Renderer declares UI slots in one bundle. sidebar and mainview form the Power workspace, must be declared together, share a host-owned JSON route, and cause the host to add a dynamic top-level navigation entry. config is independent from the workspace and appears only on the Power Catalog detail page. Optional agent_config contributes one tab to Agent Profile; views declares independently opened resource views. These surfaces use host-provided UI Components:
import { useEffect, useState } from "react";
import { define_power_renderer } from "@downcity/city/power/react";
export default define_power_renderer({ config: function GithubConfig({ config, ui }) {
const { Button, Group, Input, LoadingState, Page, Row, Toolbar } = ui.components;
const [config_state, set_config_state] = useState<{ api_url: string }>();
useEffect(() => {
void config.invoke<{ api_url: string }>("config.read").then(set_config_state);
}, [config]);
if (!config_state) return <LoadingState label="Reading Config…" />;
return <Page>
<Toolbar title="GitHub" actions={<Button variant="primary" on_click={() => void config.invoke("config.save", config_state).then(() => ui.toast({ type: "success", message: "Saved" }))}>Save</Button>} />
<Group>
<Row label="API URL" trailing={<Input value={config_state.api_url} on_value_change={(api_url) => set_config_state({ ...config_state, api_url })} />} />
</Group>
</Page>;
} });The Renderer bundle must leave react and react/jsx-runtime as host externals mapped to downcity-power://runtime/react and downcity-power://runtime/react/jsx-runtime. Bundle other frontend dependencies into the single renderer.js file.
Desktop loads the Renderer in its host React tree. Sidebar and Mainview use power.invoke() for Power-level actions and coordinate through navigation; Config uses config.invoke() for the current Power's Config actions. Each slot receives only its required gateway and host UI—never the Desktop controller. Renderer is trusted local UI code, so install only trusted sources.
Standard SidebarItem rows provide actions and menu slots separate from the selection button. Put shortcuts in actions and the host ItemMenu in menu, keeping buttons out of label and description. Action controls sit beside the selection button and do not select the row when clicked. ItemMenu accepts an indicator that replaces the default ellipsis inside the menu button. An indicator keeps the button visible, and clicking still opens the menu. Include the state description in label for its tooltip and accessible name.
Sidebar and Mainview receive a read-only notifications array projected from Notification Power's shared snapshot and scoped to the current Power. Each item includes its complete notification_id, local topic_key, content, explicit outcome, route, and creation time. Entering a Power workspace does not mark all updates as read; Inbox offers list shortcuts as well as reading specific update details. Business entry points use the same notification.read action with notification_id and created_at to acknowledge only the displayed version. The host advances ui.revision through its existing Power data change channel. Renderers can coalesce refresh requests from that revision without persistent polling.
Use Sidebar's footer?: ReactNode to keep secondary entries such as Settings fixed at the bottom, actions for header actions, and toolbar for top filters.
When a Sidebar needs a creation entry in its header, pass the host-provided SidebarCreateMenu through the Sidebar component's actions prop. The host owns the header, plus button, and dropdown presentation; the Power declares only the creation types and the business navigation for each selection.
Use SidebarTreeItem for a tree Sidebar: depth expresses hierarchy, kind distinguishes branch and leaf, parents own expansion through expanded and on_toggle, and on_select updates the Mainview through shared navigation. When leading is omitted, the host supplies consistent default icons for branches and leaves. A branch with no children can omit on_toggle and will not show a disclosure button. History and other deeper navigation should remain in this tree instead of consuming Mainview space. Use ItemMenu for row actions and the host-safe Markdown for Markdown content. After a mutation, call ui.invalidate(); the host increments the shared ui.revision for that Power across Sidebar, Mainview, Config, Agent Profile tabs, and independent views. Reload snapshots in place, retaining existing data during background refresh; reset Agent-specific state when agent_id changes. Keep refresh state out of the route.
Agent Profile tab
Desktop uses shared BayBar section navigation. A Power section mounts on its first visit and then retains state across section switches, tab switches, and panel collapse. Hidden content cannot provide header actions or receive focus. Loading preserves a requested target and honors the latest user choice; a target still missing when loading finishes falls back to the first section. Removing a Power, changing its Renderer version, or deleting the Agent releases the corresponding content. A Power loading error does not block core settings. Component subscriptions continue while content is retained.
Declare agent_config: { id, label, component } to contribute one Agent Profile tab. id and label must be non-empty strings. The host collects declarations from enabled Powers and namespaces the tab ID by Power. Catalog refreshes preserve the selected tab and mounted component while the same renderer registration remains available. No additional power.json capability flag is required, and the slot can be declared independently of Sidebar, Mainview, and Config.
import { define_power_renderer } from "@downcity/city/power/react";
import type { PowerAgentConfigComponentProps } from "@downcity/city/power/react";
function AgentSettings({ agent_id, ui }: PowerAgentConfigComponentProps) {
const { Page, Row } = ui.components;
return <Page><Row label="Agent" trailing={agent_id} /></Page>;
}
export default define_power_renderer({
agent_config: { id: "settings", label: "Settings", component: AgentSettings },
});The component receives exactly { agent_id, power, ui }. agent_id identifies the Agent being configured. power.invoke(action_id, input) uses the owning Power's business action gateway, as in Mainview; it does not use the Config gateway. The Power validates the target Agent and action inputs. The slot receives no navigation or notifications props.
PowerAgentConfigDefinition, PowerAgentConfigComponent, and PowerAgentConfigComponentProps are exported from @downcity/city/power/react. Use ui.components for layout and ui.invalidate() after mutations; the host advances the Power's ui.revision so its surfaces can reload. The built-in Skill Power uses this generic slot for Agent Profile → Skills, including skill links and MCP assignments.
Independent resource views
Desktop captures a JSON request snapshot and identifies the tab by its Power, view ID, and resource_key. Reopening it activates existing content and refreshes its label; the content keeps the initial request. Resource tabs retain state while hidden or collapsed. Closing a resource returns to the tab that first opened it when available, then to the right neighbor or the left neighbor.
Declare views: [{ id, label?, component }] in the Renderer and call ui.open_view({ view_id, resource_key, title, input }) to open one resource in a host-managed tab. View IDs must be non-empty and unique within the Power, and every view must provide a component. Views need no additional power.json capability flag and can be declared independently.
The component receives exactly { input, power, ui }. The host binds the owning Power, looks up the declared view, and owns tab selection, reuse and closing. Business code supplies a stable resource_key that includes the Agent and any relevant scope or Workspace, a user-visible title, and JSON input for reading the resource. The view uses its Power business gateway directly; it receives no Mainview or Config route.
import { useEffect, useState } from "react";
import type { PowerJsonObject } from "@downcity/city/power";
import { define_power_renderer } from "@downcity/city/power/react";
export default define_power_renderer({
views: [{
id: "note_detail",
component: function note_detail({ input, power, ui }) {
const { Page, Markdown, Callout, LoadingState } = ui.components;
const [note, set_note] = useState<PowerJsonObject>();
const [error, set_error] = useState("");
useEffect(() => {
let disposed = false;
void power.invoke<PowerJsonObject>("notes.read", input).then((value) => {
if (!disposed) { set_note(value); set_error(""); }
}).catch((reason) => {
if (!disposed) set_error(String(reason));
});
return () => { disposed = true; };
}, [input, power, ui.revision]);
return <Page>{error ? <Callout tone="danger">{error}</Callout>
: note ? <Markdown text={String(note.content ?? "")} />
: <LoadingState label="Reading note…" />}</Page>;
},
}],
});From a list in the same Power:
ui.open_view({
view_id: "note_detail",
resource_key: JSON.stringify([agent_id, workspace_id, note_id]),
title: note_title,
input: { agent_id, workspace_id, note_id },
});PowerViewDefinition, PowerViewComponent, PowerViewComponentProps, and PowerOpenViewInput are exported from @downcity/city/power/react. Read the selected resource directly rather than requesting a list to reconstruct its identity. After deleting a resource, show its deleted state in the current view; the host manages closing the tab. Use ui.invalidate() to refresh other surfaces of the same Power.
Config interaction
Open the Powers Catalog and select a Power
→ edit the Power's unique configuration in Config
→ save and let the Power refresh affected long-lived resourcesEach Power ID has one Config, independent from Sidebar/Mainview. The host only persists it and does not interpret fields or generate a form from JSON Schema. Structure, validation, defaults, Secret behavior, and resource refresh after save belong to the Power.
Configuration is stored under ~/.downcity/powers/<power_id>/config.toml with directory mode 0700 and file mode 0600. The current store uses TOML, so values must be a TOML-compatible JSON object. agent.json stores no Power references; City automatically provides every Power and the same configuration to every Agent.
Install
city power install ./github-power
# Configure GitHub on its detail page in Desktop Powers
city power config github --set '{"api_url":"https://api.github.com"}'
city power update github
city power uninstall githubThe installer copies only power.json, package.json, the Markdown file declared by readme, runtime entries, and an optional local icon. It never runs dependency installation, build scripts, or any entry. Local paths cannot escape the Power root or use symlinks. Installed artifacts receive a SHA-256 integrity digest. Install only trusted sources.
Continue with: