Vault, settings and events
Save settings, protect private values and respond to app events.
An addon may need to remember preferences, store a private value or react when the timer starts. This guide explains where to keep each kind of information and how to receive these notifications.
The application manages credentials used to connect external accounts through core.connections. Use host.vault for other private addon values and for reading saved settings; do not create another store for the same account tokens.
Explicit scopes
{ kind: 'addon' }{ kind: 'workspace', workspaceId }{ kind: 'connection', workspaceId, connectionInstanceId }{ kind: 'capability', workspaceId, connectionInstanceId, capabilityId }
get(scope, key), set(scope, key, value) and delete(scope, key) return Either. A missing private string is null. Access to connection/capability scopes is validated by the host. The capability-scoped vault address is not a per-capability manifest descriptor. UI navigation never supplies an implicit target.
Declarative settings
Register schemas through contributions.settings.register(schema, { onApply }). Non-secret settings have a revisioned snapshot; read it with host.vault.getSettings(scope). onApply receives scope, revision, values, events and track for cleanup. Do not read normal settings from an arbitrary private vault key.
Runtime and cleanup
Register providers and return from activate; waiting for ready there can block bootstrap. core.runtime.onStateChanged immediately reports the current state, then transitions among starting, ready, restarting, closed. Readiness does not mean remote pull has completed.
The host cleans up contributions and tracked listeners on deactivation or failed activation. Close owned sockets, clients and jobs yourself. Switching workspace does not deactivate the addon.
Guaranteed events
timer:start, timer:pause, timer:resume, timer:stop, timer:update, workspace:changed.
These are transient projections without replay or guaranteed per-second ticks. Idle and arbitrary time-entry events are not guaranteed SDK APIs. Use context.core.timer and context.core.timeEntries for reads and writes with explicit workspace and operation IDs. For connection authentication, see authentication.