Power Lifecycle
Understand City-owned Power instances, initialization cancellation, and retryable resource cleanup.
City owns Powers. city.powers.add(new MyPower()) registers one unique instance. A Power ID cannot
be registered twice in one City, and Agents do not store Power instances or Registries.
Two lifecycle checkpoints
initialize(context)runs once when the Power enters City. Register host Actions and initialize resources owned by the Power here.dispose(context)releases resources when the Power is removed, initialization fails, or City closes. Cleanup may be retried after failure: retain unfinished resource handles and skip completed release steps.
class ProviderPower extends Power {
readonly name = "provider";
async initialize({ storage, abort_signal }: PowerLifecycleContext) {
abort_signal.throwIfAborted();
await this.provider.open(storage.path, { signal: abort_signal });
abort_signal.throwIfAborted();
}
async dispose() {
await this.provider.close();
}
}Both methods receive the same stable PowerLifecycleContext. Agent, Session, and Workspace entry or
removal do not trigger Power lifecycle callbacks. There is no generic connect/disconnect protocol.
city.powers.add() explicitly rejects when initialization fails. The failed instance never enters the
execution Registry and cannot contribute Actions, Hooks, or System content. City retains an observable
status: "error" snapshot with last_error in city.powers.snapshots(). A host should isolate that
Power and continue starting other subjects instead of treating an optional Power as an application-wide
startup dependency. A successful retry for the same Power ID replaces the error snapshot with ready.
PowerLifecycleContext.abort_signal belongs to this initialization attempt. Calling
city.powers.cancel_initialization(power_id?) synchronously requests cancellation for one or all pending
initializations. Removal and City shutdown also request cancellation. The signal is delivered outside the
per-ID queue; removal and shutdown still await actual initialization and cleanup. Pass the signal to
cancellable I/O and check it between asynchronous stages. Detached Promises or a bare Promise.race
must not bypass cleanup. This mechanism cannot forcibly stop synchronous work or an extension that ignores the signal.
An instance whose cleanup fails remains cleanup_failed, cannot execute, and stays owned by City with its
storage context. Snapshots expose last_error and distinguish initialization_error from cleanup_error.
Retry remove() before adding the same ID again. A failed City shutdown retains unfinished resources;
the host should report the cause and retry city.close() before closing storage those resources still need.
Call context
City freshly projects a PowerContext for every Action, Hook, System, and Availability call. Its
agent, workspace, and optional session/turn handles can be used directly. Workspace is the project
resource for the current call; it is not a Power lifecycle boundary or a default resource-isolation key.
Long-lived connections, timers, schedulers, and workers must follow their actual domain ownership. A
browser Provider may be created lazily for an Agent, a chat channel may be keyed by account, and a
scheduler may follow task definitions. dispose must ultimately close every resource.
Revocation and resource release
Adding, refreshing, and removing one Power ID are serialized. Different Powers can initialize independently.
Removal first revokes capability for new calls, waits for accepted host Actions and initialization to settle,
and then calls dispose. Captured Steps and active Hooks do not create a global execution lease. The Power
owns stopping its long-running work, connections, timers, and workers and handling late callbacks.
city.close() stops Sessions and attempts cleanup for every Power. One failure does not prevent other
cleanup attempts, but shutdown reports failure and retains ownership of unfinished resources.