Extension project management

Manage code projects, fixed snapshots and versioned configuration.

downcity extension manages code extensions as projects. The project root must contain exactly one downcity.ts or downcity.js entry and may use relative imports. Adding or reloading copies source, prepares dependencies and compiles the entry.

Without a running host for the data root, commands only prepare snapshots and return pending; they do not execute the entry or start City. When CLI City or Desktop is already running normally, commands use that host's management channel to load background capabilities. A fully loaded project returns ready. An unreachable host causes an error instead of an offline write that bypasses it.

A Power instance can declare its browser entry and UI slots. The host compiles browser code separately and publishes pages only after complete initialization. CLI does not execute browser entries. Desktop pages and backend Actions use the same Power identity. Reload remounts the current generation, and old resource addresses and page calls expire.

Active model streams and managed Power work prevent replacement or removal. Finish or stop that work through its existing controls before retrying.

Prepare and inspect

downcity extension add ./my-extension --json
downcity extension add ./my-extension/downcity.ts --json
downcity extension list --json
downcity extension show <extension_id> --json
downcity extension reload <extension_id> --json

The directory and its entry resolve to the same project identity. Adding an existing source returns its registered project without reading new source. Reload explicitly prepares a new snapshot. Preparation failures retain the previously accepted target.

The default data root is ~/.downcity. DC_PLATFORM_ROOT and an explicit --root <path> are supported. Display names do not identify projects: use the returned extension_id for operations.

downcity extension add ./my-extension --root /path/to/data --json

Ordinary configuration and removal

downcity extension configure <extension_id> --configuration-file ./configuration.json --json
downcity extension reload <extension_id> --json
downcity extension remove <extension_id> --json

Configuration files submit ordinary configuration and must not contain secrets. In an interactive terminal, configure prompts for the fields requested by the entry and hides secret input. Automation can submit a JSON object of requested secret fields through --secrets-stdin; do not put credentials in command arguments.

# Pipe JSON from your credential tool; values are not echoed
credential-tool export-json | downcity extension configure <extension_id> --secrets-stdin --json

Entry functions read ordinary values from context.config and secrets with await context.secrets.get("field_name"). Request required fields using context.require_configuration([{ name, description, secret }]).

Changes are saved as an independent staged version and require an explicit reload. Until then, the current runtime and restart recovery keep the confirmed snapshot's configuration and secret versions. Secret versions live in a private directory owned by the current user. Configuration queries expose only which secret fields are saved, never their values. Input file contents are not printed.

Removal preserves author source, project data, and source identity records. Adding the same source restores its project ID. It does not create Agents.

Power work pages

// downcity.ts
import { Power } from "@downcity/city/power";

class NotesPower extends Power {
  readonly name = "notes";
  readonly title = "Notes";
  readonly renderer = {
    entry: "./ui/notes.tsx",
    sidebar: true,
    mainview: true,
    config: false,
  };
}

export default { powers: [new NotesPower()] };

The browser entry default exports a standard PowerRendererDefinition. Declare sidebar and mainview together; a configuration page can be declared on its own. Actual exported slots must match the Power binding. Use define_power_renderer from @downcity/city/power/react and the host-injected power / ui according to the custom Power contract.

Relative imports, JSON, CSS, images, and fonts compile from the fixed project snapshot. React, React DOM, JSX runtimes, and the Power React SDK use the host's instances. Declared SDK/React version ranges must accept the host versions. Do not import Node modules or another extension's managed directories.

UI resources are bound to the project and runtime generation. Only actual compiler output is served, not arbitrary source, dependency files, or directories. Compiled asset addresses and page Actions expire when the generation is replaced or removed.

Agent definitions and connections

# Inspect behavior and connection catalogs published by the host
downcity extension definitions --json
downcity extension connections --json

# Create independent Agent identities from one definition
downcity agent create --name "Reviewer one" --definition-id <definition_id>
downcity agent create --name "Reviewer two" --definition-id <definition_id>

# Explicitly select or disconnect a connection
downcity extension select-connection <entry_id> --json
downcity extension select-connection none --json

Catalog and selection operations require an already running host. Adding a project does not create Agents or switch connections. Reloading a definition updates existing Agents while preserving their IDs and history; reopen old Session runtime handles before executing. After removal, history remains readable and execution reports that its source is unavailable.

An Agent definition's behavior supports instruction, tools, hooks, session_class, session_composer, and model. A supplied composer must remain stateless according to the SDK contract.

The selected Federation entry ID is persistent. A current binding, active request, queue execution, maintenance task, or explicitly retained handle prevents removing its project. Switch or disconnect explicitly and wait for work to settle. Recovery preserves an unavailable selection instead of silently choosing a different connection.

Desktop entry points

The plus button at the end of the Navbar capsule opens Add extension. Enter a Git source or choose a local project or entry file. The window explains that loading executes code on this machine. Closing it after submission does not cancel the main-process operation.

Settings → Extensions shows projects and errors for the same data root, with Reload, Remove, and known configuration fields. Save ordinary and private input, then explicitly reload to apply it. Projects added through CLI appear in the same list. The Agent creation page can select a loaded behavior definition. Extension settings also list connections with explicit Select and Disconnect actions.

Automation results

Results include extension_id, operation_id, source, status, active_snapshot, pending_snapshot, capability_counts, and error. Offline preparation returns null for both active_snapshot and capability_counts.

Use --operation-id <id> to supply an idempotency key for a write operation. Inspect an accepted operation using the command below. An operation ID cannot be reused with different input.

downcity extension operation <operation_id> --json

--json never waits for interactive input and writes one final JSON value to stdout. Check the exit code, status, and error together: a successful pending result still means the project has not been loaded.