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.