Vault, Events, and Context

An addon imports contracts from @mr-tick/sdk. The host provides product capabilities; it does not expose HostBridge or RxDB documents.

Vault with Explicit Scope

The vault uses the operating system keychain and belongs to the addon. Choose the scope on each call: { kind: 'workspace', workspaceId } or { kind: 'addon' }. UI navigation does not change the target. get, set, and delete return Either<AppError, T>.

const scope: AddonVaultScope = { kind: 'workspace', workspaceId }
const result = await context.host.vault.set(scope, 'channelId', channelId)
if (result.isFailure()) return result.forwardFailure()
const channel = await context.host.vault.get(scope, 'channelId')
if (channel.isFailure()) return channel.forwardFailure()

Existing workspace settings are preserved. Invalid data returns a failure without automatic overwriting.

Core Queries

• core.workspaces.list() and get(workspaceId) return identity, name, and state.
• core.connections.list(workspaceId) and get(scope) return identity, datasource, and state, without credentials.
• core.tasks.get({ workspaceId, connectionInstanceId, taskId }) uses the original source ID.
• core.tasks.list({ workspaceId, connectionInstanceId, limit, search? }) reads up to 100 tasks in ascending ID order.
• core.metadata.get(scope) reads activities and other locally available metadata.

All queries return Either. Reading does not call a remote provider, open storage, or start synchronization. An unavailable cache returns 503; a missing task returns 404. Dates are ISO 8601 strings. A successful local write does not confirm remote acceptance.

Readiness and Deactivation

activate(context: AddonContext): void {
  context.core.runtime.onStateChanged((state) => {
    console.log('Core:', state)
  })
  // Registre providers agora e retorne, sem aguardar ready.
}

States: starting, ready, restarting, closed. A listener immediately receives the current state. ready does not mean that pull has finished. After recovery, query the state again; when retrying a write, keep the same operation IDs.

The host cleans up contributions and listeners during deactivation or partially failed activation. The addon closes its own sockets and clients in deactivate. Switching workspaces does not automatically deactivate an addon.

Guaranteed Events

context.host.events.on('timer:start', (data) => console.log(data.taskId))
context.host.events.on('timer:stop', (data) => console.log(data.currentSeconds))
context.host.events.on('workspace:changed', (data) => console.log(data.currentWorkspaceId))

timer:pause, timer:resume, and timer:update are also available. These are transient projections, without replay or a guarantee of one tick per second. Time-entry and idle events are not part of the guaranteed contract.

Timer, Suggestions, and Notifications

Use timer.getActiveEntry(workspaceId) and timer methods with a workspace and LocalOperationIdentity. timeEntries.create / createSuggestion receive (workspaceId, input, operation), duration in seconds, and ISO dates. Reuse commandId and entryId only to retry the same operation.

notifications.info, success, warning, error, loading, and dismiss remain available for toasts.

Current addons run trusted code in the main process. These capabilities do not provide sandboxing or granular authorization.