ReadAware

Référence de l'API des plugins

Cette page décrit le contrat de développement, qui peut être en avance sur la dernière version publiée. La référence complète, en fin de page, recense chaque capacité avec sa version de développement et sa version dans la dernière publication, l'autorisation qu'elle requiert, ainsi que la signature résolue et la documentation de chaque méthode. L'explorateur de capacités propose le même catalogue de manière interactive. Les types du dépôt public de plugins correspondent à la dernière version publiée.

Paquet et manifeste

Un plugin contient manifest.json et un module ES autonome, généralement main.js. Gardez le code source et les ressources nécessaires dans le paquet afin de permettre la révision.

ChampSignification
id, name, versionEspace de noms stable, nom affiché et version du paquet. L’ID correspond au nom du dossier.
schemaVersionEntier positif du schéma de données privées du plugin, indépendant de la version du paquet.
requiresID de capacités et plages semver, regroupés en domains, contributions, services et schemas.
permissionsAutorité sémantique, par exemple library:read ou service:llm.
settingsAccessAutorisations séparées discover, read et write pour des chemins exacts ou des groupes de sections explicites.
networkAccessOrigines HTTP(S) autorisées pour Network 2.x ; obligatoire avec service:network.
minAppVersionPlancher facultatif de version de l’application, en plus des exigences de capacités.
mainModule d’entrée relatif ; sa valeur par défaut est main.js.
settings, schedules, themes, fontsDéclarations interprétées par l’hôte.
servicesExports de services de module typés et versionnés pour les appels entre plugins.

Aucun champ du manifeste n’accorde un accès arbitraire au système de fichiers, à SQL, au DOM ou à l’IPC natif.

Contexte et portée des objets

L’hôte appelle activate(ctx) avec ctx.domains, ctx.contributions et ctx.services, ainsi qu’avec le manifeste, la langue, la version de l’application, la phase du cycle de vie, les versions des capacités et l’autorisation de livre immuable.

ctx.grants.book vaut all, current ou un book donné. L’hôte le choisit lors du consentement. La lecture, la mémoire, les conversations, les commandes et les ressources conservent cette portée dans les appels et les callbacks. Un changement de livre courant peut invalider les lectures, handles, propositions et observations en cours.

La permission d’écriture d’un domaine inclut la lecture. Les autorisations de réglages restent séparées par opération. Les espaces de noms ou méthodes protégés par permission peuvent être absents ; les contrôles côté hôte s’exécutent tout de même à chaque appel. Utilisez ctx.services.session.operationAvailability(...) pour les vérifications préalables prises en charge et gérez l’échec d’exécution même après un résultat positif.

Domaines

DomaineTravail disponibleLimites
libraryLivres et collections, sommaires, recherche d’emplacements exacts, plages, références et images, importations, tâches de texte, métadonnées, fusion de doublons et suppression.Versions de source, portée du livre, lectures limitées, tâches appartenant à l’acteur et reçus distincts de nettoyage des fichiers.
readingInstantanés de session, navigation, sélection, contrôles de lecture et de mode, progression, temps de lecture et informations.Gardes de session actuelle, états stabilisés ou en attente, disponibilité des fournisseurs et annulation.
annotationsPages, inspection et observations ; création de surlignages ou de notes ; lots de modifications et suppressions conditionnelles.Utilisez la révision observée avant la décision de l’utilisateur. Les plages capturées exigent aussi l’accès à Library.
conversationsTranscriptions autorisées, résumés enregistrés, état d’exécution et des demandes de tour ; contrôles de fils et tours proposés.L’approbation de l’hôte démarre un tour proposé. Les opérations sur les fils globaux exigent l’accès à tous les livres. Les plugins ne remplacent pas le runtime de discussion.
settingsDécouverte du catalogue, instantanés résolus, options, métadonnées de modèles, observation, mises à jour et réinitialisations de lecture.Chemins exacts, politique de cible et autorité supplémentaire pour le travail d’un fournisseur externe.
memoryRecherche et pages, inspection, correction et oubli, profils, entités, classification, graphes et tâches, archives de contexte.Autorisations de livre et révisions conditionnelles. Les opérations d’identité et de profil globales exigent l’accès à tous les livres ; la génération exige aussi l’autorité du modèle.

Texte source et navigation

Utilisez library.queries.books.searchLocations pour les correspondances de source navigables et readRange pour le texte source limité. Conservez la version de source et l’emplacement renvoyés. Les résultats searchText dérivés sont des aperçus et ne remplacent pas les ancres de navigation. La préparation explicite du texte renvoie une tâche dont la progression et le résultat doivent être observés.

Écritures conditionnelles

Inspectez l’objet actuel et conservez sa révision avant d’afficher une modification. Soumettez la mutation conditionnelle avec cette révision. En cas de conflit, relisez l’objet et laissez l’utilisateur décider ; remplacer silencieusement la révision attendue écraserait une autre modification.

annotations.commands.applyChanges, les mutations Memory, les commits de documents privés et les prévisualisations de transactions ont chacun leur propre contrat typé. Les commandes ordinaires ne sont pas automatiquement annulables ni des transactions distribuées.

Observations et réactions

Utilisez les observations autorisées pour l’état actuel et les abonnements validés pour les événements. Un numéro de séquence peut ordonner les livraisons sans être un curseur de base de données ni une révision d’écriture conditionnelle. Les observations échouées doivent rester distinguables des résultats vides.

Utilisez ctx.withEvent(delivery) pour le travail de suivi automatique et des identifiants de règle stables sur les abonnements causaux lorsque cela est requis. Conservez le contexte lié dans les appels asynchrones. L’hôte rejette les cycles causaux et les livraisons expirées ; les actions utilisateur indépendantes utilisent le contexte d’origine.

Contributions

ContributionCe que fournit le plugin
selectionActions, headerActions, contextActions, commands, uriHandlersActions sur les surfaces typées de l’hôte, commandes de palette et gestion d’URI avec espace de noms.
settingsOptionsOptions dynamiques pour un réglage de plugin déclaré.
voiceProviders, contentProviders, readerModesSynthèse audio, contenu de livres virtuels et modes de segmentation du lecteur intégrés.
agentTools, agentContextProviders, agentRetrievalProvidersOutils, contexte limité par tour et sources de plugin consultables.
memoryCandidateProvidersMémoires candidates soumises à la validation et à l’acceptation de l’hôte.
themes, fontsChoix d’apparence déclarés dans le manifeste.
syncTransportsStockage d’enveloppes de synchronisation chiffrées opaques et d’objets méta.

Les actions peuvent mettre à jour leur état visible, activé ou coché lorsqu’il est pris en charge. Les enregistrements et les disposables appartiennent à une activation. Le retour d’une vue n’accorde pas au callback une autorité supplémentaire sur les domaines.

Les candidates de mémoire et les commandes Memory directes sont deux chemins distincts : les candidates passent par l’acceptation de l’hôte, tandis que les commandes directes exigent l’autorisation Memory et la révision correspondantes. Aucun de ces chemins ne permet d’injecter des règles système ni de remplacer l’agent principal.

Services hôte

ServiceUtilisationLimite principale
storageKV privé, collections de documents, commits conditionnels, pages, observations et politiques d’utilisation.Espace de noms et quotas du plugin ; les curseurs obsolètes exigent une nouvelle base.
resourcesFichiers et répertoires choisis par l’utilisateur, handles d’octets scellés, exports, images et ressources binaires privées.Aucun chemin ambiant. Les handles ont des propriétaires, des limites et une durée de vie.
secretsEmplacements d’identifiants chiffrés privés au plugin.Aucun accès aux secrets d’un autre plugin.
networkHTTP limité par origine, requêtes mises en mémoire tampon et flux.Chaque redirection est contrôlée ; aucune relecture automatique d’écritures arbitraires.
llmInférence textuelle ou structurée, streaming, ressources image, reçus de requête et budgets.Configuration utilisateur, règles de confidentialité, annulation et limites hôte/fournisseur.
clipboardÉcrire du texte ou une image scellée.Permission explicite et type de ressource pris en charge.
uiVues, notifications, flux natifs d’enregistrement/ouverture, navigation des espaces de travail et commandes, panneaux et fenêtres du lecteur.Autorisations de domaine propres aux méthodes et présentation gérée par l’hôte.
sessionMétadonnées d’environnement non sensibles et disponibilité des opérations.Aucun ancien abonnement à la session de lecture ; utilisez le domaine Reading.
schedulesGestionnaires récurrents déclarés et demandes différées possédées.Le travail s’exécute lorsque l’application est ouverte ; le minutage n’est pas exact.
jobsPlans durables pris en charge, points de contrôle, observation et contrôle.Opérations hôte typées, pas une exécution JavaScript arbitraire.
changesCurseurs persistants de changements limités.Indications de rechargement, pas journal brut d’événements ni valeurs historiques.
transactionsPrévisualisation, commit, recherche de reçus et prévisualisation d’annulation conditionnelle.Opérations locales prises en charge et autorisations d’origine ; les résultats inconnus exigent une recherche de reçu.
pluginsInspection des enregistrements, observation des changements, découverte et appel de services de plugins typés.Intersection des autorités appelant/appelé, portée, versions et exécution isolée du service.
maintenanceÉtat et flux hôte de sauvegarde, test de connexion et mise à jour.L’hôte conserve les identifiants, les dialogues de fichiers et les confirmations importantes.
syncÉtat de synchronisation autorisé, retard et flux de compte ou de synchronisation gérés par l’hôte.Aucune clé de chiffrement ni identifiant brut de compte.
diagnostics, loggingExports de diagnostics révisés et événements développeur structurés limités.Aucun contenu arbitraire, secret ou signalement automatique via l’API de journalisation.

Réseau et inférence

Network 2.x exige à la fois une permission sémantique et des origines explicites :

json
{
  "requires": { "services": { "network": "^2.2.0" } },
  "permissions": ["service:network"],
  "networkAccess": { "origins": ["https://api.example.com"] }
}

Remplacez l’origine d’exemple par l’endpoint réellement utilisé. Les origines comprennent le schéma, l’hôte et le port ; ce ne sont ni des chemins d’URL ni des jokers de sous-domaines. Les redirections doivent rester autorisées. Les appelants de flux ferment les flux dont ils sont propriétaires une fois leur utilisation terminée. La nouvelle tentative sûre facultative se limite aux requêtes de lecture prises en charge avant la livraison d’une réponse ; l’annulation n’annule pas un effet distant.

Pour l’inférence, utilisez readingContext pour le contexte du livre afin que l’hôte applique les règles de confidentialité et de portée. Utilisez les identifiants de ressources scellées pour les images prises en charge. Les métadonnées de requête et les budgets de sortie aident à contrôler le travail ; ils ne constituent ni un relevé de facturation ni une garantie du respect des règles par le fournisseur.

Travail en arrière-plan et transactions

Utilisez une planification pour organiser l’appel d’un gestionnaire, une demande différée possédée pour un travail ultérieur pendant que l’application s’exécute, et une tâche durable uniquement lorsque son plan typé prend l’opération en charge. La récupération après redémarrage peut exiger une intervention plutôt que répéter aveuglément un résultat externe incertain.

Les transactions combinent des opérations prises en charge de réglages, de documents privés et de domaines avec les autorisations d’origine. La prévisualisation fige le travail proposé ; le commit consomme cette prévisualisation. Après une réponse inconnue, consultez le reçu avant de réessayer. L’annulation est conditionnelle : l’état doit toujours correspondre au résultat précédent.

Services entre plugins

Déclarez dans le manifeste du fournisseur l’ID, la version, la portée, les permissions requises et les schémas d’entrée/sortie du service, puis exportez son gestionnaire dans l’objet services du module. Découvrez-le et appelez-le via le service Plugins. L’hôte exécute un nouveau domaine de service isolé avec l’autorité intersectée ; il n’active pas le runtime d’interface ordinaire du fournisseur pour cet appel. Les appels provenant de l’agent conservent leur exigence d’approbation.

Vues, réglages, thèmes et polices

Les plugins renvoient des données de vue déclaratives. L’hôte rend les listes, formulaires, markdown, détails et mises en page de blocs prises en charge. Utilisez des résultats de vue typés et des mises à jour de vue en direct ; gardez distincts les états de chargement, de conflit, vide et d’erreur. Le code du plugin n’a accès ni à React, ni au DOM, ni aux iframes, ni au CSS arbitraire.

Les champs de réglages sont rendus par l’hôte. Les champs secrets écrivent dans des emplacements chiffrés et ne deviennent ni des valeurs ordinaires de formulaire ni des réglages visibles par le modèle. Fournir un thème ou une police exige ui:themes ; en sélectionner un utilise l’autorisation d’écriture Settings correspondante.

Cycle de vie et compatibilité

  1. Activation : lectures et enregistrements pris en charge ; les contributions en attente ne sont pas encore visibles.
  2. Migration : stockage privé uniquement, avant la validation d’un schéma modifié.
  3. Actif : les gestionnaires promus peuvent utiliser les capacités accordées.

L’hôte vérifie la santé et promeut un candidat après la réussite de l’activation et de toute migration. En cas d’échec, il restaure le paquet et les données précédents. Le déchargement libère les enregistrements, callbacks et ressources possédées ; les données durables suivent leur propre contrat de conservation. Dans le développement actuel, la désinstallation supprime les collections de documents privés et les ressources binaires tout en conservant l’état KV/secret/schema défini pour la réinstallation.

Déclarez indépendamment chaque capacité et chaque schéma utilisés. Un numéro de version prouve la compatibilité du contrat, pas que chaque système d’exploitation, fournisseur ou scénario d’échec a été accepté de bout en bout. Vérifiez le workflow de bureau réel que vous livrez.

Créer un plugin · Explorateur de capacités · Publication

Référence complète

Chaque capacité du contrat de développement, regroupée par famille. Un plugin destiné à l'application que les gens utilisent aujourd'hui devrait exiger la version indiquée pour la dernière version publiée.

Domaines

domains:library

Inspecter les livres, le texte source, les sommaires, emplacements exacts, plages, images et collections ; importer, organiser et gérer les tâches de texte.

  • Développement : v1.35.0
  • ReadAware 0.6.12 : v1.35.0
  • Autorité: library:read / library:write
ctx.domains.library.commands.books.addVirtualBook
(input: { providerId: string; key: string; title: string; author?: string; }): Promise<BookSummary>
ctx.domains.library.commands.books.cancelImportTask
(taskId: string): Promise<BookImportTaskSnapshot>
ctx.domains.library.commands.books.cancelTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>

Cancels only this activation's request; shared work or dispatched writes may continue.

ctx.domains.library.commands.books.editMetadata
(bookId: string, patch: { title?: string; author?: string; }): Promise<void>
ctx.domains.library.commands.books.importBook
(input: { fileName: string; data: ArrayBuffer | Uint8Array; }, options?: PluginCallOptions): Promise<BookSummary>
ctx.domains.library.commands.books.importResource
(id: string, options?: PluginCallOptions): Promise<BookImportReceipt>

Library 1.19 adds per-call cancellation. Before the first durable write, cancellation prevents admission; afterward await the actual imported/duplicate receipt or failure. No whole-file transfer, opening or resource release.

ctx.domains.library.commands.books.invalidateVirtualBook
(input: { providerId: string; key: string; }): Promise<{ bookId: string; revision: string; }>

Announce already-saved source changes. Does not reload or move the reader. revision is a process-local invalidation fence, not a content hash. Library 1.15.

ctx.domains.library.commands.books.mergeDuplicates
(input: BookMergeRequest): Promise<BookMergeReceipt>

Conditional record merge with the host's deterministic keeper; not file deletion or undo.

ctx.domains.library.commands.books.pauseTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>
ctx.domains.library.commands.books.prepareText
(bookId: string, options?: BookTextPrepareOptions): Promise<BookTextTaskSnapshot>

Library 1.31: starts an actor-owned background request. A receipt is not completion. Current-book grants fence admission and the lease through pause/resume; switching books cancels only this request, without undoing accepted writes.

ctx.domains.library.commands.books.remove
(bookId: string): Promise<void>
ctx.domains.library.commands.books.removeMany
(bookIds: string[]): Promise<BookRemovalReceipt>

1-1000 IDs, deduplicated. Atomic record deletion; local file release is separately reported.

ctx.domains.library.commands.books.removeVirtualBook
(input: { providerId: string; key: string; expectedBookId?: string; }): Promise<void>
ctx.domains.library.commands.books.resumeTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>

Library 1.21: reacquires this paused request using saved checkpoints and the same handle.

ctx.domains.library.commands.books.retryEnrichment
(bookId: string): Promise<BookEnrichmentReceipt>

Retry unchecked covers and missing/filename-derived metadata using the shared queue, without forcing replacement or download.

ctx.domains.library.commands.books.retryRemovalCleanup
(bookIds: string[]): Promise<BookFileReleaseReceipt>

Retry file release only. Refuses any ID now present in the library; never deletes records.

ctx.domains.library.commands.books.setStarred
(bookId: string, starred: boolean): Promise<void>
ctx.domains.library.commands.books.setTextTaskPriority
(bookId: string, taskId: string, priority: BookTextPriority): Promise<BookTextTaskSnapshot>

Library 1.21: pauses only this request by releasing its lease; other consumers and dispatched I/O may continue.

ctx.domains.library.commands.books.startImport
(input: BookImportRequest, options?: PluginCallOptions): Promise<BookImportTaskSnapshot>

Start a task over owned sealed resources or <=64 MiB file bytes (wire limits still apply). Queued is not imported. options.signal cancels admission only; use cancelImportTask after the receipt. At most 2 physical task executions per activation, 4 in the app; direct imports/picker jobs are outside this task quota. Tasks do not resume after restart. Accepted writes finish despite cancellation.

ctx.domains.library.commands.collections.assignBooks
(bookIds: string[], collectionId: string | null): Promise<void>
ctx.domains.library.commands.collections.create
(name: string): Promise<CollectionSummary>
ctx.domains.library.commands.collections.remove
(collectionId: string): Promise<void>
ctx.domains.library.commands.collections.rename
(collectionId: string, name: string): Promise<void>
ctx.domains.library.events.observeContentState
(bookId: string, handler: PluginObservationHandler<BookContentObservation>, options?: { ruleId?: string; }): PluginDisposable
ctx.domains.library.events.observeEnrichment
(bookId: string, handler: PluginObservationHandler<BookEnrichmentObservation>, options?: { ruleId?: string; }): PluginDisposable
ctx.domains.library.events.observeImportTask
(taskId: string, handler: PluginObservationHandler<BookImportTaskSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Initial snapshot and coalesced monotonic revisions, including terminal failures.

ctx.domains.library.events.observeInvalidation
(handler: PluginObservationHandler<ProjectionInvalidation>): PluginDisposable

Initial and coalesced reload hints, including remote projection changes. Re-query authorized data; not an event log or a conditional-write token.

ctx.domains.library.events.observeTextTask
(bookId: string, taskId: string, handler: PluginObservationHandler<BookTextTaskSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Library 1.32: serial reaction deliveries retain task and history-write sources.

ctx.domains.library.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.library.queries.books.get
(bookId: string): Promise<BookSummary | null>
ctx.domains.library.queries.books.getChapterText
(bookId: string, chapterIndex: number): Promise<string | null>
ctx.domains.library.queries.books.getContentState
(bookId: string, options?: PluginCallOptions): Promise<BookContentState>

Source metadata only; never loads a provider or reveals reading state. Library 1.16.

ctx.domains.library.queries.books.getEnrichment
(bookId: string): Promise<BookEnrichmentSnapshot>

Library 1.9: local cover/source state and the latest process-local enrichment attempt.

ctx.domains.library.queries.books.getImportTask
(taskId: string, waitMs?: number, options?: PluginCallOptions): Promise<BookImportTaskSnapshot>

waitMs (0..30000) waits for terminal state or returns current progress at the deadline. Cancelling this query stops observation only.

ctx.domains.library.queries.books.getNavigationToc
(bookId: string, options?: PluginCallOptions): Promise<BookNavigationToc>
ctx.domains.library.queries.books.getTextState
(bookId: string): Promise<BookTextSnapshot>

Read-only derived-text state. Never starts parsing, fetching, or extraction.

ctx.domains.library.queries.books.getTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>
ctx.domains.library.queries.books.getToc
(bookId: string): Promise<ChapterRef[]>
ctx.domains.library.queries.books.inspectResource
(id: string, options?: PluginCallOptions): Promise<BookInspection>

Initialize this activation's sealed resource with the reader parser; no import.

ctx.domains.library.queries.books.list
(): Promise<BookSummary[]>
ctx.domains.library.queries.books.listDuplicates
(query?: DuplicateBookQuery): Promise<DuplicateBookPage>

Library 1.10: same-content groups; live offset pages, limit 1-50.

ctx.domains.library.queries.books.listFormats
(): Promise<BookFormatCapability[]>

Library 1.11: import routing hints; extensions alone do not prove readability.

ctx.domains.library.queries.books.listImages
(input: BookReferencesQuery, options?: PluginCallOptions): Promise<BookImagesPage>

Library 1.29: section-local img/SVG, srcset/authored CSS and PDF image candidates. No remote fetch; PDF operator inspection can decode objects.

ctx.domains.library.queries.books.listImportTasks
(): Promise<BookImportTaskSnapshot[]>
ctx.domains.library.queries.books.listNavigationTargets
(input: BookNavigationTargetsQuery, options?: PluginCallOptions): Promise<BookNavigationTargetsPage>

Library 1.14: bounded source-section or author-supplied page-label catalog; not screen page counts.

ctx.domains.library.queries.books.listReferences
(input: BookReferencesQuery, options?: PluginCallOptions): Promise<BookReferencesPage>

Library 1.12: versioned section references, not extracted chapter indices.

ctx.domains.library.queries.books.listRemovalCleanup
(query?: BookRemovalCleanupQuery): Promise<BookRemovalCleanupPage>

Durable device-local pending file cleanup, including after view/plugin restart. Live keyset page, limit 1-100 (default 50).

ctx.domains.library.queries.books.listTextTaskHistory
(bookId: string, query?: BookTextTaskHistoryQuery): Promise<BookTextTaskHistoryPage>
ctx.domains.library.queries.books.listTextTasks
(bookId: string): Promise<BookTextTaskSnapshot[]>
ctx.domains.library.queries.books.openImageResource
(input: BookImageQuery): Promise<BookImageResource>

Seal an embedded image as this activation's ResourceRef; does not display it or decode pixels.

ctx.domains.library.queries.books.previewMerge
(bookId: string): Promise<BookMergePreview | null>
ctx.domains.library.queries.books.readRange
(input: BookRangeQuery, options?: PluginCallOptions): Promise<BookRangePage>
ctx.domains.library.queries.books.readReference
(input: BookReferenceQuery, options?: PluginCallOptions): Promise<BookReferencePreview>

Plain-text preview and resolved navigation location; never fetches or opens an external URL.

ctx.domains.library.queries.books.resolveId
(bookId: string): Promise<string | null>

Current book ID or merge redirect, null if neither points to a living book.

ctx.domains.library.queries.books.searchLocations
(input: BookLocationSearch, options?: PluginCallOptions): Promise<BookLocationSearchPage>
ctx.domains.library.queries.books.searchText
(input: BookTextSearch, options?: PluginCallOptions): Promise<BookTextHit[]>

Multi-query derived prose search. Single-book may prepare text; shelf search never does. Results are not navigation locations.

ctx.domains.library.queries.collections.booksIn
(collectionId: string): Promise<string[]>
ctx.domains.library.queries.collections.list
(): Promise<CollectionSummary[]>

domains:reading

Observer les sessions de lecture, naviguer et sélectionner du texte, contrôler la lecture et les modes, et interroger la progression, le temps et les informations de lecture.

  • Développement : v2.24.0
  • ReadAware 0.6.12 : v2.24.0
  • Autorité: reading:read / reading:write
ctx.domains.reading.commands.back
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.clearSelection
(expectedId: string, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingSelectionReceipt>

Clears only the observed selection ID; a replacement selection is never silently cleared.

ctx.domains.reading.commands.close
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<void>
ctx.domains.reading.commands.configureMode
(input: ReadingModeConfiguration, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingModeReceipt>

Configure the host mode; modeKey guards the current provider, selectModeKey selects from session().mode.availableModes. Resolves after real indexing (ready/empty) or deactivation. Failed indexing rejects. Disabling the caller cancels an unfinished change; completed mode preferences remain.

ctx.domains.reading.commands.controlPlayback
(action: "start" | "stop", guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingPlaybackReceipt>

Start resolves on actual audio start. Stop is idempotent; disabling the initiating plugin stops its playback.

ctx.domains.reading.commands.forward
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.goTo
(target: ReadingTarget, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.openBook
(bookId: string, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.putEmphasis
(input: ReadingEmphasisWrite, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingEmphasisReceipt>

Temporary owned marks, not annotations. No navigation; replacement requires an observed revision.

ctx.domains.reading.commands.reload
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>

Reading 2.21: reopen source; virtual sections with identical stable identity/content preserve their location across reorder. Stale/legacy virtual locators restart at the beginning; files still restart. Whole-book contentVersion guards remain strict.

ctx.domains.reading.commands.removeEmphasis
(input: ReadingEmphasisRef, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingEmphasisRemoval>
ctx.domains.reading.commands.returnToMode
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>

Return to the versioned resting unit; wait for renderer navigation and unit restoration before committing history.

ctx.domains.reading.commands.selectRange
(range: BookTextRange, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingSelectionReceipt>

Requires this book to be open; validates its source range, navigates, then waits for the selection overlay commit.

ctx.domains.reading.commands.setControls
(visible: boolean, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingControlsReceipt>

Set reader chrome visibility; completes after UI commit. Does not alter panel preferences or playback.

ctx.domains.reading.commands.setFinished
(bookId: string, finished: boolean): Promise<void>
ctx.domains.reading.commands.step
(direction: ReadingStep, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>

Reading 2.12: page, source-section and book-boundary navigation; section/boundary jumps enter history.

ctx.domains.reading.commands.stepMode
(direction: "next" | "previous", guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingModeStepReceipt>

Step one configured text unit, across sections if necessary; reports book boundaries explicitly.

ctx.domains.reading.events.observeEmphasis
(handler: (snapshot: ReadingEmphasisSnapshot[], delivery?: PluginReactionEvent) => void | Promise<void>): PluginDisposable
ctx.domains.reading.events.observeSession
(handler: (snapshot: ReadingSessionSnapshot, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposable

Immediate and subsequent snapshots carry a live reaction lease. Use withEvent for automatic writes; keep the original context for later user actions. A stable ruleId can resume job causality across activations.

ctx.domains.reading.events.observeTime
(query: ReadingTimeQuery, handler: (event: ReadingTimeObservation, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposable

Immediate sample then a 1s minimum gap after each delivery. Errors are explicit; dispose stops further delivery. Reading 2.24: delivery retains sampling subscription ancestry across timers. It does not identify historical writers of the aggregate.

ctx.domains.reading.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.reading.queries.emphasis
(): Promise<ReadingEmphasisSnapshot[]>

This activation's temporary marks only; attached does not mean visible in the viewport.

ctx.domains.reading.queries.session
(): Promise<ReadingSessionSnapshot>
ctx.domains.reading.queries.stats.forBook
(bookId: string): Promise<BookStats | null>
ctx.domains.reading.queries.stats.insights
(query?: ReadingInsightsQuery): Promise<ReadingInsights>
ctx.domains.reading.queries.stats.list
(): Promise<BookStats[]>
ctx.domains.reading.queries.stats.overview
(): Promise<StatsOverview>
ctx.domains.reading.queries.stats.time
(query?: ReadingTimeQuery): Promise<ReadingTimeSnapshot>

Atomic settled + pending time, with native sampling clock. Reading >=2.7.

domains:annotations

Parcourir, inspecter et observer les surlignages et notes ; les créer ou appliquer des modifications et suppressions vérifiées par révision.

  • Développement : v2.2.0
  • ReadAware 0.6.12 : v2.2.0
  • Autorité: annotations:read / annotations:write
ctx.domains.annotations.commands.applyChanges
(changes: AnnotationMutation[]): Promise<AnnotationCommitResult>

Since 2.0 this is the only edit/delete entry. Use the revision observed before the user's decision; 1..100 distinct items, all commit or none.

ctx.domains.annotations.commands.createHighlight
(input: { range?: BookTextRange; bookId: string; text: string; anchor?: string | null; chapterHref?: string | null; color?: HighlightColor; style?: HighlightStyle; }): Promise<HighlightItem>

annotations >=2.1: range validates and preserves the captured source; requires library:read.

ctx.domains.annotations.commands.createNote
(input: { range?: BookTextRange; bookId: string; body: string; quotedText?: string; anchor?: string | null; chapterHref?: string | null; }): Promise<NoteItem>
ctx.domains.annotations.events.observe
(query: AnnotationObservationQuery, handler: PluginObservationHandler<AnnotationObservation>): PluginDisposable

Since 1.4. Initial authorized snapshot, then changed results/errors/recovery. Disposal ends delivery.

ctx.domains.annotations.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.annotations.queries.get
(annotationId: string): Promise<AnnotationItem | null>

annotations >=1.1.0. Missing IDs return null; read failures reject.

ctx.domains.annotations.queries.inspect
(annotationId: string): Promise<AnnotationSnapshot | null>

annotations >=1.3.0. Read an item and its conditional-write token atomically.

ctx.domains.annotations.queries.list
(filter?: { bookId?: string; kind?: "highlight" | "note" | "ask"; query?: string; }): Promise<AnnotationItem[]>
ctx.domains.annotations.queries.page
(input?: AnnotationPageQuery): Promise<AnnotationPage>

annotations >=1.2.0. Live keyset page, not a frozen snapshot across calls.

domains:conversations

Lire les transcriptions, résumés et états d’exécution autorisés ; proposer des tours, gérer les fils et utiliser les contrôles d’arrêt ou d’effacement approuvés.

  • Développement : v1.7.0
  • ReadAware 0.6.12 : v1.7.0
  • Autorité: conversations:read / conversations:write
ctx.domains.conversations.commands.cancelTurnRequest
(id: string): Promise<ConversationTurnRequestSnapshot>
ctx.domains.conversations.commands.clear
(target: ConversationTarget): Promise<ConversationControlReceipt>

Clears transcript/hidden thread state after draining turns, not long-term memory or event history.

ctx.domains.conversations.commands.createThread
(): Promise<ConversationControlReceipt & { draft: true; }>

Creates and selects a global draft; no transcript row until the first message. Does not navigate the app.

ctx.domains.conversations.commands.requestTurn
(request: ConversationTurnRequest): Promise<ConversationTurnRequestSnapshot>

Requires a mounted conversation. Only a host UI confirmation can adopt/send/retry; receipt is not a completed turn.

ctx.domains.conversations.commands.selectThread
(threadId: string): Promise<ConversationControlReceipt>
ctx.domains.conversations.commands.stop
(target: ConversationTarget): Promise<ConversationControlReceipt>

Stops live UI turns and waits for their final transcript writes. Does not undo tool effects.

ctx.domains.conversations.events.observeInvalidation
(handler: PluginObservationHandler<ProjectionInvalidation>): PluginDisposable
ctx.domains.conversations.events.observeRuntime
(handler: PluginObservationHandler<PluginConversationRuntimeSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Conversations 1.6: serial reaction deliveries, with an optional stable rule ID.

ctx.domains.conversations.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.conversations.queries.getBookThread
(bookId: string): Promise<ChatMessageSummary[]>
ctx.domains.conversations.queries.getInsights
(target: ConversationTarget): Promise<string | null>

Conversations 1.4: stored rolling summary of a book/global thread, or null. No generation, freshness guarantee, raw runtime state or summary writes.

ctx.domains.conversations.queries.getThread
(threadId: string): Promise<ChatMessageSummary[]>
ctx.domains.conversations.queries.listThreads
(): Promise<ThreadSummary[]>
ctx.domains.conversations.queries.runtime
(): Promise<PluginConversationRuntimeSnapshot>
ctx.domains.conversations.queries.turnRequests
(): Promise<ConversationTurnRequestSnapshot[]>

Up to 128 recently retained host requests, filtered to this actor; no text or other actors' requests.

domains:settings

Découvrir les chemins et options exacts des réglages, lire les instantanés stabilisés, observer les changements et mettre à jour les cibles prises en charge.

  • Développement : v1.11.0
  • ReadAware 0.6.12 : v1.11.0
  • Autorité: aucune
ctx.domains.settings.commands.refreshModelCatalog
(provider: string, options?: PluginCallOptions): Promise<ModelCatalogPage>

Settings 1.9: additionally requires service:network. Shared native refresh, not a connection test.

ctx.domains.settings.commands.resetReading
(request: ReadingSettingsReset): Promise<SettingsUpdateResult>

Settings 1.7: reset the whole reader-preference bundle; every reading path must be writable. defaults restores built-ins; inherit deletes active and remembered book overrides.

ctx.domains.settings.commands.update
(changes: SettingChange[]): Promise<SettingsUpdateResult>
ctx.domains.settings.events.subscribe
(handler: (event: SettingsChangedEvent & PluginReactionEvent) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.settings.queries.discover
(query?: SettingsQuery): Promise<SettingCatalogEntry[]>
ctx.domains.settings.queries.modelCatalog
(query: ModelCatalogQuery): Promise<ModelCatalogPage>

Settings 1.9: cached public model metadata; discover access to primaryModel or fastModel. No network.

ctx.domains.settings.queries.observe
(query: SettingsQuery, handler: PluginObservationHandler<SettingsObservation>): PluginDisposable

Settled snapshots after native, domain, remote, restore and catalog changes. Coalesces slow callbacks.

ctx.domains.settings.queries.options
(query: SettingsOptionsQuery): Promise<SettingsOptionsPage>

Settings 1.8: bounded options; same path grants as discover. Includes installed system families for reading/content fonts without font paths or bytes. Since 1.10, dynamicOptions fields invoke the registered owning provider with saved non-secret form values, never caller-supplied values. Network-enabled providers additionally require this caller's service:network permission. Results are cached for 60 seconds, at most 16 lists / 2000 options per list, 512 characters per label/value and 1 MiB of label/value JSON. Pages retain the returned revision; changed settings/provider or expiry require restart. Four provider loads host-wide, 10-second wait; already-started provider work is not cancelled by this deadline or caller retirement. No writes/synthesis. Plugin-owned option queries require the caller's active phase, not activation/migration. Empty results still allow manual values; provider failures remain failures.

ctx.domains.settings.queries.read
(path: string, target?: SettingsQueryTarget): Promise<SettingReadResult>
ctx.domains.settings.queries.snapshot
(query?: SettingsQuery): Promise<SettingsSnapshot>

Since settings 1.3: one host snapshot after prior queued writes settle, filtered by exact path grants.

domains:memory

Rechercher, parcourir, inspecter et corriger les mémoires ; travailler avec les profils, entités, classification, graphes et lots de contexte versionnés.

  • Développement : v2.8.0
  • ReadAware 0.6.12 : v2.8.0
  • Autorité: memory:read / memory:write
ctx.domains.memory.commands.cancelGraphTask
(bookId: string, taskId: string): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.commands.classify
(input: BookClassificationChange): Promise<BookClassificationReceipt>
ctx.domains.memory.commands.completeOnboarding
(input: OnboardingChange, options?: PluginCallOptions): Promise<OnboardingReceipt>

Memory 2.5: confirm the full summary AND seeds before calling. Reuse the same owner-local submissionId and exact candidate after a lost receipt; a different candidate requires a new id and renewed confirmation. Atomic, event-backed.

ctx.domains.memory.commands.context.capture
(selector: ContextBundleSelector, options?: PluginCallOptions): Promise<ContextBundleCaptureReceipt>
ctx.domains.memory.commands.decideEntity
(input: EntityDecision, options?: PluginCallOptions): Promise<EntityDecisionReceipt>

Memory 2.1: resolve an original member or merge known resolved classes using an observed entities1 revision. Present the exact change for confirmation first. Retains original definitions/aliases, may sync to other devices. No blind conflict retry. Cancellation prevents dispatch only; dispatched writes drain to their actual receipt. A transport timeout or lost Worker leaves the outcome unknown: reread, never retry blindly.

ctx.domains.memory.commands.mutate
(input: MemoryMutation): Promise<MemoryMutationReceipt>
ctx.domains.memory.commands.retryGraphTask
(bookId: string, taskId: string, options?: BookGraphTaskOptions): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.commands.startGraphTask
(bookId: string, mode: "catch-up" | "rebuild", options?: BookGraphTaskOptions): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.commands.updateProfile
(input: UserProfileChange): Promise<UserProfileReceipt>

Replace the event-backed summary using the observed profile2 revision. Present the complete candidate for user confirmation before calling. Empty text clears the summary, not memories or historical copies.

ctx.domains.memory.events.observe
(query: MemoryObservationQuery, handler: PluginObservationHandler<MemoryObservation>): PluginDisposable

Initial snapshot, then changed results/errors; re-read when the store announces a change, not an event log. Plugins 1.5 supplies a separate reaction delivery, including graph task updates.

ctx.domains.memory.queries.bookGraph
(bookId: string, query?: BookGraphQuery): Promise<BookGraphResult>

memory >=2.6 only exposes current-source digests; chapter results carry contentVersion for navigation.

ctx.domains.memory.queries.classification
(bookId: string): Promise<BookClassificationSnapshot | null>
ctx.domains.memory.queries.context.export
(query: ContextBundleReadQuery, options?: PluginCallOptions): Promise<ResourceRef>
ctx.domains.memory.queries.context.history
(query: ContextBundleHistoryQuery, options?: PluginCallOptions): Promise<ContextBundleHistoryPage>
ctx.domains.memory.queries.context.read
(query: ContextBundleReadQuery, options?: PluginCallOptions): Promise<ContextBundle | null>
ctx.domains.memory.queries.entities
(query?: EntityQuery, options?: PluginCallOptions): Promise<EntityPage>

Global explicit identities, not book-digest characters. Row-bounded, revision-pinned pages. Memory 2.2 adds canonicalDefinition from the same snapshot. Historical field sizes are not bounded. Aborted/retired callers receive no late page.

ctx.domains.memory.queries.getGraphTask
(bookId: string, taskId: string): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.queries.inspect
(id: string): Promise<MemorySnapshot | null>
ctx.domains.memory.queries.listGraphTasks
(bookId: string): Promise<BookGraphTaskSnapshot[]>
ctx.domains.memory.queries.page
(input: MemoryPageQuery): Promise<MemoryPage>
ctx.domains.memory.queries.profile
(query?: UserProfileQuery): Promise<UserProfilePage>

The event-backed summary projection; read grant, bounded revision-pinned pages.

ctx.domains.memory.queries.profileContext
(query?: ProfileInspectionQuery, options?: PluginCallOptions): Promise<ProfileInspectionPage>

Memory 2.3: inspect the generated summary and provenance, separately from curated profile(). Summary pages count UTF-16 units (4000 default, 16000 max); provenance pages count rows (25 default, 100 max; historical ID sizes are unbounded). Pin every page kind to pctx1. Stale text is inspectable, never current context. Invalid blocks expose no content. Current means source-consistent, not semantic verification or completed consolidation. entityEvidence IDs include proposed no-ops, not proof of emitted events. Read grant; no source text, transcripts, raw traits, registry writes or automatic inference.

ctx.domains.memory.queries.search
(input: MemoryQuery): Promise<MemoryRecord[]>

Contributions

contributions:uriHandlers

Gérer les invocations d’URI ReadAware avec espace de noms au moyen d’une action enregistrée.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.contributions.uriHandlers.register
(handler: PluginUriHandler): PluginActionRegistration

contributions:selectionActions

Ajouter des actions pour les sélections, annotations ou entrées du navigateur capturées.

  • Développement : v1.2.0
  • ReadAware 0.6.12 : v1.2.0
  • Autorité: aucune
ctx.contributions.selectionActions.register
(action: PluginSelectionAction): PluginActionRegistration

contributions:headerActions

Ajouter des actions d’en-tête du lecteur, de la bibliothèque ou de l’agent avec des vues rendues par l’hôte.

  • Développement : v1.2.0
  • ReadAware 0.6.12 : v1.2.0
  • Autorité: aucune
ctx.contributions.headerActions.register
(action: PluginHeaderAction): PluginActionRegistration

contributions:contextActions

Ajouter des actions typées aux surfaces de contexte prises en charge pour les livres ou collections.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.contributions.contextActions.register
(action: PluginContextAction): PluginActionRegistration

contributions:commands

Ajouter des actions d’espace de noms à la palette de commandes et mettre à jour leur état possédé.

  • Développement : v1.1.0
  • ReadAware 0.6.12 : v1.1.0
  • Autorité: aucune
ctx.contributions.commands.register
(command: PluginCommand): PluginActionRegistration

contributions:settingsOptions

Résoudre les choix dynamiques d’un réglage de plugin déclaré.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.contributions.settingsOptions.register
(fieldId: string, provider: (values: PluginFormValues) => PluginSelectOption[] | Promise<PluginSelectOption[]>): PluginDisposable

contributions:settingsPage

Enregistrez une page déclarative qui remplace le formulaire de paramètres du manifeste du plugin dans sa propre section Paramètres.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.contributions.settingsPage.register
(page: { view(): PluginView | Promise<PluginView>; }): PluginDisposable

contributions:voiceProviders

Fournir des choix de voix et de l’audio encodé pour la lecture à voix haute.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.contributions.voiceProviders.register
(provider: PluginVoiceProvider): PluginDisposable

contributions:contentProviders

Fournir des sections pour des livres virtuels tels que des flux enregistrés.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.contributions.contentProviders.register
(provider: { id: string; load(key: string): Promise<PluginBookContent>; }): PluginDisposable

contributions:agentTools

Enregistrer des outils avec espace de noms que l’assistant de lecture peut découvrir et appeler.

  • Développement : v1.3.0
  • ReadAware 0.6.12 : v1.3.0
  • Autorité: agent:tools
ctx.contributions.agentTools.register
(tool: PluginToolDefinition): PluginActionRegistration

contributions:agentContextProviders

Fournir des blocs de référence limités par tour et des sources déclarées d’intention de lecture.

  • Développement : v1.1.0
  • ReadAware 0.6.12 : v1.1.0
  • Autorité: agent:context
ctx.contributions.agentContextProviders.register
(provider: PluginAgentContextProvider): PluginDisposable

contributions:agentRetrievalProviders

Exposer à l’assistant des sources appartenant au plugin et consultables.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: agent:retrieval
ctx.contributions.agentRetrievalProviders.register
(provider: PluginAgentRetrievalProvider): PluginDisposable

contributions:memoryCandidateProviders

Proposer des faits, préférences, observations ou résumés pour acceptation par la mémoire.

  • Développement : v1.1.0
  • ReadAware 0.6.12 : v1.1.0
  • Autorité: agent:memory
ctx.contributions.memoryCandidateProviders.register
(provider: PluginMemoryCandidateProvider): PluginDisposable

contributions:themes

Déclarer dans le manifeste les choix de thème sémantique de l’application et du lecteur.

  • Développement : v1.2.0
  • ReadAware 0.6.12 : v1.2.0
  • Autorité: ui:themes
ctx.contributions.themes.readerBases
(): Promise<PluginReaderThemeBase[]>

Themes 1.2: built-in and active plugin reader bases, excluding image themes. Saved copies do not change when the original theme changes.

ctx.contributions.themes.register
(theme: PluginRuntimeTheme): Promise<PluginDisposable>

contributions:fonts

Déclarer les métadonnées des polices et les ressources de polices empaquetées.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: ui:themes

Déclaration du manifest

contributions:syncTransports

Stocker et récupérer sur un serveur distant alternatif des événements, blobs et objets méta de clés chiffrés opaques.

  • Développement : v2.0.0
  • ReadAware 0.6.12 : v2.0.0
  • Autorité: sync:transport
ctx.contributions.syncTransports.register
(transport: PluginSyncTransport): PluginDisposable

Services

services:storage

Utiliser le KV privé et les collections de documents, leurs pages et observations, les commits conditionnels et les politiques de quota.

  • Développement : v2.6.0
  • ReadAware 0.6.12 : v2.6.0
  • Autorité: aucune
ctx.services.storage.applyDocuments
(changes: PluginDocumentChange[]): Promise<PluginDocumentCommit>

Storage 2.1: atomically compare and apply 1..100 private document changes. Every expected revision is checked before any write. Does not include KV, core domain events, files, or another plugin's documents.

ctx.services.storage.collection
(name: string): PluginDocumentCollection

A named document collection — structured plugin-private data one tier above the KV (queryable, per-document, optionally book-anchored). Backed by the app's local store; lifecycle belongs to the plugin (uninstall clears it). bookId/anchor are provenance INDEXES, not ownership — documents survive the referenced book's deletion.

ctx.services.storage.documents(collection).delete
(id: string): Promise<void>
ctx.services.storage.documents(collection).get
<T>(id: string): Promise<PluginDocument<T> | null>
ctx.services.storage.documents(collection).list
<T>(filter?: { bookId?: string; limit?: number; oldestFirst?: boolean; }): Promise<PluginDocument<T>[]>

Newest-first by default.

ctx.services.storage.documents(collection).page
<T>(filter?: PluginDocumentPageFilter): Promise<PluginDocumentPage<T>>

Storage 2.1: 1..200 rows (default 50), 4 MiB JSON per page. Cursors bind namespace/filter/order and expire on any collection write. On stale-cursor restart rather than combining different snapshots.

ctx.services.storage.documents(collection).put
(id: string, data: unknown, options?: { bookId?: string; anchor?: string; }): Promise<void>
ctx.services.storage.flush
(): Promise<void>

Wait for outstanding writes in this plugin's namespace.

ctx.services.storage.get
<T>(key: string): T | null
ctx.services.storage.getDurable
<T>(key: string): Promise<T | null>

2.4: keys up to 1024 UTF-16 units, no NUL. Settle accepted writes, then read this private key from SQLite, not the optimistic mirror. Corrupt JSON rejects; null means absent or JSON null.

ctx.services.storage.observeDocuments
<T>(query: PluginDocumentObservationQuery, handler: PluginObservationHandler<PluginDocumentObservation<T>>): PluginDisposable

Storage 2.2: initial and changed private document query snapshots, including errors/recovery. At most 64 active observers per activation. The query is re-read when one of its documents is written (from any surface of this plugin on this device, or another process such as the CLI), and one callback settles before the next. Not a replayable write stream. Dispose or plugin retirement stops delivery; sequence is not CAS.

ctx.services.storage.onChange
(handler: PluginObservationHandler<{ kind: "changed"; }>, options?: { ruleId?: string; }): PluginDisposable

Fires when this plugin's namespace is written from OUTSIDE the plugin — its settings page, the reading agent, another surface editing the same object. Settings-key changes can also echo after own writes. Serial callbacks receive a reaction credential; use withEvent to preserve causes. No initial callback; intermediate changes coalesce. Use it to re-read (or re-derive from) settings you would otherwise have cached at activate().

ctx.services.storage.policy
(): Promise<PluginStoragePolicy>

Storage 2.5: own persisted usage and actual per-store policy. Null quota means no enforced total limit, not unlimited disk. Call flush first when awaiting this activation's pending writes. No names or secret values. Complete backup refers to full app backup, not reading/OPML exports.

ctx.services.storage.remove
(key: string): Promise<void>
ctx.services.storage.set
(key: string, value: unknown): Promise<void>

Reads update optimistically; resolve only after the write is durable.

services:secrets

Lire et écrire des identifiants dans les emplacements chiffrés privés du plugin.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.services.secrets.get
(key: string): Promise<string | null>
ctx.services.secrets.remove
(key: string): Promise<void>
ctx.services.secrets.set
(key: string, value: string): Promise<void>

services:ui

Publier des vues, afficher des notifications, enregistrer ou ouvrir des ressources, naviguer dans les espaces de travail et commandes, et contrôler les panneaux et fenêtres de lecteur pris en charge.

  • Développement : v1.18.0
  • ReadAware 0.6.12 : v1.18.0
  • Autorité: aucune
ctx.services.ui.commands.execute
(request: HostCommandRequest): Promise<HostCommandReceipt>

Library write plus each command's setting grant; opening/leaving a reader needs reading:write.

ctx.services.ui.commands.list
(): Promise<HostCommandSnapshot>
ctx.services.ui.commands.observe
(handler: PluginObservationHandler<HostCommandObservation>, options?: { ruleId?: string; }): PluginDisposable

UI 1.16: serial/coalesced snapshots with a reaction delivery and optional stable ruleId.

ctx.services.ui.exportFile
(file: PluginExportFile): Promise<boolean>
ctx.services.ui.openExternal
(url: string): Promise<void>

UI 1.7, requires service:network. Explicit user intent only; HTTP(S), no credentials or local schemes.

ctx.services.ui.publishView
(channel: PluginViewChannel, update: PluginViewUpdate): Promise<PluginViewUpdateReceipt>

Updates only this activation's visible frame. Revision is a nonnegative, increasing safe integer. Receipt confirms host acceptance, not paint; updates cannot navigate or replace the subscription.

ctx.services.ui.reader.closeReferencePreview
(id: string): Promise<ReaderReferenceCloseReceipt>

Only this activation's current preview ID; never closes a native or other owner's note.

ctx.services.ui.reader.focus
(target: ReaderFocusTarget, guard?: ReadingSessionGuard): Promise<ReaderFocusReceipt>

UI 1.14, reading:write. Focus an already visible semantic target, without opening or dismissing UI. not-focused is not success; close your own dialog before returning focus.

ctx.services.ui.reader.image.control
(request: ReaderImageRequest): Promise<ReaderImageReceipt>

reading:write; exact current viewer ID required. Pan deltas are fractions of its viewport.

ctx.services.ui.reader.image.observe
(handler: PluginObservationHandler<ReaderImageSnapshot | null>): PluginDisposable

Plugins 1.6 supplies a separate reaction delivery, including closed/null snapshots.

ctx.services.ui.reader.image.open
(query: BookImageQuery, guard?: ReadingSessionGuard): Promise<ReaderImageOpenReceipt>

UI 1.13: library read + reading write; opens an embedded image in the current book.

ctx.services.ui.reader.image.snapshot
(): Promise<ReaderImageSnapshot | null>
ctx.services.ui.reader.observe
(handler: PluginObservationHandler<ReaderPanelsSnapshot | null>): PluginDisposable

Plugins 1.6 supplies a separate reaction delivery; callbacks are serial and coalesced.

ctx.services.ui.reader.previewReference
(query: BookReferenceQuery, guard?: ReadingSessionGuard): Promise<ReaderReferencePreviewReceipt>

UI 1.8: also needs library:read. Open book only; resolved preview waits for DOM commit.

ctx.services.ui.reader.setPanel
(panel: ReaderPanel, open: boolean, guard?: ReadingSessionGuard): Promise<ReaderPanelReceipt>

Requires reading:write. Opening reveals controls; completion waits for persistence and DOM commit.

ctx.services.ui.reader.setWidth
(panel: ResizableReaderPanel, width: number, guard?: ReadingSessionGuard): Promise<ReaderPanelReceipt>

Persist a shared TOC/chat width (integer 240..640 CSS px); does not open it or focus.

ctx.services.ui.reader.snapshot
(): Promise<ReaderPanelsSnapshot | null>
ctx.services.ui.showToast
(message: PluginToast): void
ctx.services.ui.window.control
(request: HostWindowRequest): Promise<HostWindowReceipt>
ctx.services.ui.window.observe
(handler: PluginObservationHandler<HostWindowObservation>, options?: { ruleId?: string; }): PluginDisposable

UI 1.17: reaction delivery remains valid until the callback settles.

ctx.services.ui.window.snapshot
(): Promise<HostWindowSnapshot>
ctx.services.ui.workspace.navigate
(target: WorkspaceTarget, expectedRevision?: number): Promise<WorkspaceReceipt>

Library write grant; leaving an active reader additionally requires reading:write. UI 1.18: { surface: "annotations" } opens the highlights & notes page, which snapshots report.

ctx.services.ui.workspace.observe
(query: WorkspaceQuery, handler: PluginObservationHandler<WorkspaceSnapshot | null>, options?: { ruleId?: string; }): PluginDisposable

UI 1.16: use the separate reaction delivery even for null/retired snapshots.

ctx.services.ui.workspace.snapshot
(query?: WorkspaceQuery): Promise<WorkspaceSnapshot>

services:schedules

Lier des gestionnaires récurrents déclarés, inspecter et contrôler les planifications et gérer les demandes différées possédées.

  • Développement : v2.1.0
  • ReadAware 0.6.12 : v2.1.0
  • Autorité: aucune
ctx.services.schedules.bind
(scheduleId: string, run: (context: PluginScheduleRun, delivery?: PluginReactionEvent) => void | Promise<void>): PluginDisposable
ctx.services.schedules.cancelDeferred
(id: string, requestId: string, options?: PluginCallOptions): Promise<PluginDeferredReceipt>

Cancel exactly the queued ID, not an in-flight callback or a replacement request.

ctx.services.schedules.control
(id: string, action: "pause" | "resume" | "run"): Promise<PluginScheduleReceipt>

Pause/resume persist; run bypasses pause/cadence once. Neither pause nor cancellation undoes dispatched callback effects.

ctx.services.schedules.defer
(id: string, input: PluginDeferredRequest, options?: PluginCallOptions): Promise<PluginDeferredReceipt>

Schedules 2: enqueue one declared deferred task. Persists before acknowledgement. 1 second..7 days; idle means 5 seconds without host input. Never runs while closed. The most recent request ID is retained for retry; changed input conflicts, another queued ID is busy. A dispatched request is never automatically replayed after a crash. Inspect interrupted and decide explicitly.

ctx.services.schedules.list
(query?: Omit<PluginScheduleQuery, "pluginId">): Promise<PluginSchedulePage>

Bound schedules owned by this plugin only, with the latest persisted attempt/outcome.

ctx.services.schedules.observe
(query: Omit<PluginScheduleQuery, "pluginId">, handler: PluginObservationHandler<PluginSchedulePage>, options?: { ruleId?: string; }): PluginDisposable

services:jobs

Démarrer, inspecter et contrôler des plans durables construits à partir d’opérations hôte prises en charge.

  • Développement : v1.1.0
  • ReadAware 0.6.12 : v1.1.0
  • Autorité: aucune
ctx.services.jobs.control
(id: string, action: DurableJobControl, options?: PluginCallOptions): Promise<DurableJobSnapshot>
ctx.services.jobs.get
(id: string, options?: PluginCallOptions): Promise<DurableJobSnapshot>
ctx.services.jobs.list
(query?: { offset?: number; limit?: number; }, options?: PluginCallOptions): Promise<{ jobs: DurableJobSnapshot[]; nextOffset: number | null; }>
ctx.services.jobs.start
(plan: DurableJobPlan, options?: PluginCallOptions): Promise<DurableJobSnapshot>

jobs 1.1: event-bound starts preserve their source through restart. Every causal event subscription must have a stable ruleId. Unnamed reactions and isolated service invocations cannot create saved jobs.

services:changes

Ouvrir et lire des curseurs de changements limités pouvant être conservés entre les redémarrages.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.services.changes.open
(query: ChangesQuery, options?: PluginCallOptions): Promise<{ cursor: string; }>

Open before loading a baseline. Persist the returned cursor only after processing each page. Expired cursors require a new baseline. Notices are conservative reload hints, not events or values; settings hints cover the authorized requested paths in a shared storage namespace.

ctx.services.changes.read
(query: ChangesQuery, cursor: string, limit?: number, options?: PluginCallOptions): Promise<ChangesPage>

services:transactions

Prévisualiser et valider les changements locaux pris en charge, inspecter les reçus et prévisualiser une annulation conditionnelle.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.services.transactions.commit
(previewId: string, options?: PluginCallOptions): Promise<AtomicReceipt>
ctx.services.transactions.preview
(operations: AtomicOperation[], options?: PluginCallOptions): Promise<AtomicPreview>
ctx.services.transactions.previewUndo
(receiptId: string, options?: PluginCallOptions): Promise<AtomicPreview>
ctx.services.transactions.receipt
(receiptId: string, options?: PluginCallOptions): Promise<AtomicReceipt | null>

services:session

Lire les métadonnées d’environnement et vérifier la disponibilité des opérations prises en charge.

  • Développement : v2.18.0
  • ReadAware 0.6.12 : v2.18.0
  • Autorité: aucune
ctx.services.session.environment
(): Promise<HostEnvironmentSnapshot>

Fresh non-sensitive metadata; contains no reading or account state.

ctx.services.session.observeEnvironment
(handler: (snapshot: HostEnvironmentSnapshot, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposable

Session 2.7: locale effects retain their requester; other system facts keep independent sources.

ctx.services.session.operationAvailability
(query: OperationAvailabilityQuery, options?: PluginCallOptions): Promise<OperationAvailability>

Session 2.11: inspect host command permissions/workspace guards and plugin service contract/authority/capacity (Agent approval remains required), export metadata/save entry and clipboard/browser entry availability (no OS access probe), window support/capacity/target state, sync connection/credentials/provider, inference, book-targeted playback/mode, text preparation and graph prerequisites without executing or probing. Missing permission returns only the permission condition. Unknown remote health is not a local refusal or a success guarantee.

services:plugins

Inspecter les plugins et enregistrements installés, observer les changements et découvrir ou appeler des services de plugins typés.

  • Développement : v1.10.0
  • ReadAware 0.6.12 : v1.10.0
  • Autorité: aucune
ctx.services.plugins.callService
(request: PluginServiceCall, options?: PluginCallOptions): Promise<PluginServiceReceipt>

Executes one declared export in a fresh restricted Worker. No live-root closures, callbacks, binary handles, automatic retries, or resources surviving the call.

ctx.services.plugins.contributions
(query?: PluginContributionQuery): Promise<PluginContributionPage>

Registered identities across extension points, never provider callbacks, data, settings or a grant to invoke another plugin. Offset pages may change.

ctx.services.plugins.list
(query?: PluginDirectoryQuery): Promise<PluginDirectoryPage>

Public installed metadata only, no settings, paths, secrets or raw errors.

ctx.services.plugins.listServices
(query?: PluginServiceQuery, options?: PluginCallOptions): Promise<PluginServicePage>

Plugins 1.8: authorized service contracts; discovery does not execute providers.

ctx.services.plugins.observe
(query: PluginDirectoryQuery, handler: PluginObservationHandler<PluginDirectoryPage>, options?: { ruleId?: string; }): PluginDisposable

Plugins 1.10: serial reaction deliveries with stable rule IDs; reload offset pages after changes.

ctx.services.plugins.observeContributions
(query: PluginContributionQuery, handler: PluginObservationHandler<PluginContributionPage>, options?: { ruleId?: string; }): PluginDisposable

services:maintenance

Inspecter l’état de maintenance et accéder aux flux de sauvegarde, test de connexion, mise à jour ou réglages gérés par l’hôte.

  • Développement : v1.5.0
  • ReadAware 0.6.12 : v1.5.0
  • Autorité: aucune
ctx.services.maintenance.checkForUpdates
(): Promise<HostMaintenanceSnapshot>

Requires service:network. Uses the host release feed; no caller-supplied URL or silent installation.

ctx.services.maintenance.observe
(handler: PluginObservationHandler<HostMaintenanceSnapshot>, options?: { ruleId?: string; }): PluginDisposable
ctx.services.maintenance.openSettings
(surface: "updates" | "diagnostics" | "plugins" | "backup-import" | "backup-export" | "delete-data" | "ai-connection" | "data-location"): Promise<{ status: "opened"; surface: HostMaintenanceSurface; }>

Maintenance 1.4 adds data-location: shows the directory in host UI, never returns its path or opens the file manager. Also reveals updates/diagnostics/plugins/backup-import/backup-export/delete-data/ai-connection. Does not click controls, open file dialogs, approve installation or bypass typed DELETE.

ctx.services.maintenance.requestBackup
(action: BackupAction, options?: PluginCallOptions): Promise<BackupReceipt>

Reveals a host backup button and awaits the user's click and file dialog. Both directions use the complete encrypted archive (host-only password); import adds host review and confirmation, then reload. Retired v1 JSON library backups are rejected. No passwords, bytes or paths are returned.

ctx.services.maintenance.requestConnectionTest
(options?: PluginCallOptions): Promise<ConnectionTestReceipt>

Maintenance 1.3: reveal native AI test controls; only the user's click starts inference.

ctx.services.maintenance.snapshot
(): Promise<HostMaintenanceSnapshot>

services:diagnostics

Demander les flux pris en charge d’exportation ou de signalement de diagnostics.

  • Développement : v1.2.0
  • ReadAware 0.6.12 : v1.2.0
  • Autorité: service:diagnostics
ctx.services.diagnostics.requestProjectionRepair
(options?: PluginCallOptions): Promise<ProjectionRepairReceipt>

Diagnostics 1.2: opens host confirmation; a committed repair requires reload.

ctx.services.diagnostics.requestReport
(action: DiagnosticsReportAction, options?: PluginCallOptions): Promise<DiagnosticsReportReceipt>
ctx.services.diagnostics.verifyProjections
(options?: PluginCallOptions): Promise<ProjectionVerification>

services:logging

Écrire des événements développeur structurés et limités et inspecter la politique de journalisation.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune
ctx.services.logging.policy
(): Promise<{ levels: PluginLogEntry["level"][]; maxEntryChars: number; maxFields: number; perPluginLimit: number; appLimit: number; windowMs: number; delivery: "best-effort"; }>
ctx.services.logging.write
(entry: PluginLogEntry): Promise<PluginLogReceipt>

Logging 1.0: accepted means forwarded to the best-effort host logger, not durably stored or uploaded. Allowed during activation and migration. Debug is development-console-only. Retired activations cannot write.

services:resources

Sélectionner des fichiers et répertoires, lire ou créer des ressources scellées, exporter des données et stocker des ressources binaires privées.

  • Développement : v1.6.0
  • ReadAware 0.6.12 : v1.6.0
  • Autorité: aucune
ctx.services.resources.append
(id: string, offset: number, data: ArrayBuffer | Uint8Array<ArrayBufferLike>): Promise<ResourceRef>
ctx.services.resources.assets.delete
(key: string, expectedRevision: string, options?: PluginCallOptions): Promise<{ deleted: true; cleanupPending: boolean; }>
ctx.services.resources.assets.get
(key: string, options?: PluginCallOptions): Promise<PluginAsset | null>
ctx.services.resources.assets.list
(query?: PluginAssetQuery, options?: PluginCallOptions): Promise<PluginAssetPage>
ctx.services.resources.assets.open
(key: string, expectedRevision: string, options?: PluginCallOptions): Promise<ResourceRef>
ctx.services.resources.assets.policy
(options?: PluginCallOptions): Promise<PluginAssetPolicy>
ctx.services.resources.assets.store
(resourceId: string, input: PluginAssetWrite, options?: PluginCallOptions): Promise<PluginAssetReceipt>
ctx.services.resources.commit
(id: string): Promise<ResourceRef>
ctx.services.resources.create
(options: ResourceCreateOptions): Promise<ResourceRef>
ctx.services.resources.listDirectory
(id: string, query?: ResourceDirectoryQuery): Promise<ResourceDirectoryPage>
ctx.services.resources.openAssociated
(id: string, options?: PluginCallOptions): Promise<{ opened: boolean; }>

Resources 1.5: host confirmation then OS association for a temporary document/media copy. No edit-back, arbitrary program/path, or context bundles. True is dispatch, not rendering.

ctx.services.resources.openBook
(bookId: string): Promise<ResourceRef | null>

Requires library:read. Original local file only; no implicit remote download.

ctx.services.resources.openCover
(bookId: string): Promise<ResourceRef | null>

Resources 1.1; requires library:read. No extraction/download when the cover is unavailable.

ctx.services.resources.openDirectoryFile
(id: string, relativePath: string): Promise<ResourceRef>
ctx.services.resources.pick
(options?: ResourcePickOptions): Promise<{ cancelled: boolean; resources: ResourceRef[]; }>
ctx.services.resources.pickDirectory
(): Promise<{ cancelled: boolean; directory: ResourceDirectoryRef | null; }>

Resources 1.4: reader-selected, read-only directory grants; four per activation, one hour. No ambient paths. Listings are live; openDirectoryFile seals the current file bytes.

ctx.services.resources.read
(id: string, offset: number, length: number): Promise<ResourceChunk>
ctx.services.resources.release
(id: string): Promise<void>

Also aborts uncommitted writes.

ctx.services.resources.releaseDirectory
(id: string): Promise<void>
ctx.services.resources.save
(id: string, filename?: string): Promise<{ saved: boolean; }>
ctx.services.resources.stat
(id: string): Promise<ResourceRef>

services:sync

Observer l’état et le retard de synchronisation, demander une synchronisation et accéder aux flux de compte ou de connexion gérés par l’hôte.

  • Développement : v1.2.0
  • ReadAware 0.6.12 : v1.2.0
  • Autorité: service:sync
ctx.services.sync.account
(): Promise<HostSyncAccount | null>

Explicit remote read of the account's tier, usage and limits; null without an account. No email, account ID, keys, session or billing ticket.

ctx.services.sync.backlog
(): Promise<{ events: number; blobs: number; }>

Events and blobs waiting to be pushed.

ctx.services.sync.connectionOptions
(): Promise<{ ref: string; label: string; }[]>

Registered backend references and display labels, never endpoint credentials.

ctx.services.sync.observe
(handler: PluginObservationHandler<HostSyncSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Delivers each new sync snapshot (state, progress, completed cycles) while the handle lives.

ctx.services.sync.openSettings
(): Promise<{ status: "opened"; surface: "dataSync"; }>

Opens the host Data & Sync page; not a login, disconnect or purchase.

ctx.services.sync.requestFlow
(request: HostSyncFlowRequest, options?: PluginCallOptions): Promise<HostSyncFlowReceipt>

Host-owned connect, disconnect, account deletion, upgrade or billing flow. Waits for the final local outcome or external handoff; cancellation cannot undo a started operation.

ctx.services.sync.requestSync
(): Promise<HostSyncReceipt>

Runs one sync round on the configured backend (relay or a transport plugin such as WebDAV) and resolves when it has finished: completed, or already-running when a round was in progress (not queued again). Rejects with a coded error when no round can start (ui/unavailable) or the round fails (classified failures carry sync/* codes).

ctx.services.sync.snapshot
(): Promise<HostSyncSnapshot>

Current sync state: backend, connection, progress, last cycle and last error code.

services:network

Effectuer des requêtes HTTP limitées à une origine ou lire des flux limités, avec des tentatives sûres facultatives.

  • Développement : v2.2.0
  • ReadAware 0.6.12 : v2.2.0
  • Autorité: service:network
ctx.services.network.closeStream
(id: string): Promise<void>

Idempotent for this activation's released/unknown IDs. Aborts pending reads; does not undo remote effects or remove data already saved by the plugin.

ctx.services.network.fetch
(input: string | URL | Request, init?: RequestInit, options?: { retry?: "none" | "safe"; }): Promise<Response>

Native HTTP; Request/init semantics and cancellation survive the Worker bridge. Bodies are buffered up to 64 MiB per direction. Calls have a 120s deadline; an abort does not undo a remote side effect already committed by the server. Network 2.0 requires networkAccess for the initial URL and each redirect. HTTPS -> HTTP redirects are denied. At most 10 redirects; manual returns the 3xx response, error rejects. Cross-origin hops drop authorization, proxy-authorization, cookie and referer; custom secret headers are the plugin's responsibility (use redirect:error for authenticated endpoints). Host/content-length are transport-owned. No implicit retry or cookie jar. Network 2.2: options.retry="safe" opts GET/HEAD without a body into at most two retries across the whole redirect chain, before response headers are returned. Other methods and all body reads are never replayed. The original deadline includes backoff; Retry-After above 30s returns the HTTP response. Attempts/uploads/read chunks share per-owner and host cumulative quotas; reactivation does not reset owner debt. policy() reports exact limits. Transport failures carry plugin/network-failed; explicit deadlines carry plugin/network-timeout, aborts plugin/cancelled. Existing structured codes survive unchanged. Unclassified native errors are not guessed from prose. HTTP error statuses still return Response; the consumer decides success.

ctx.services.network.openStream
(input: string | URL | Request, init?: RequestInit, options?: { retry?: "none" | "safe"; }): Promise<PluginNetworkStream>

Network 2.1: headers first; download at most 1 GiB without buffering the whole response. Uploads remain capped at 64 MiB. 8 active requests per activation / 32 host-wide, shared with fetch; no hidden durable queue. Optional safe retry applies only before this opening receipt, as in fetch. init.signal cancels OPENING only; after receipt use closeStream to cancel. Close in finally if not reading to EOF. 120s absolute lifetime, including headers/redirects/reads; unload cancels and drains native resources.

ctx.services.network.policy
(): Promise<PluginNetworkAccess & { maxRedirects: number; maxBodyBytes: number; timeoutMs: number; maxStreamBytes: number; maxChunkBytes: number; maxConcurrentRequests: number; maxHostConcurrentRequests: number; cumulative: { windowMs: number; maxOwnerRequests: number; maxHostRequests: number; maxOwnerBytes: number; maxHostBytes: number; maxOwners: number; }; retry: { maxRetries: number; baseDelayMs: number; maxDelayMs: number; statuses: readonly number[]; }; }>

Network 2.0: this activation's immutable authorization and transport limits. All-origins authorization is ["*"], not a guarantee of endpoint reachability.

ctx.services.network.readStream
(id: string, offset: number, maxBytes?: number): Promise<PluginNetworkChunk>

Sequential, non-replayable reads. offset must equal bytes already delivered. One outstanding read per stream; maxBytes defaults to 64 KiB, max 1 MiB. A lost read receipt is not safely retryable: close and restart explicitly.

services:llm

Demander une inférence textuelle, structurée ou en streaming, utiliser des ressources image scellées et suivre les métadonnées et budgets de requête.

  • Développement : v1.6.0
  • ReadAware 0.6.12 : v1.6.0
  • Autorité: service:llm
ctx.services.llm.ask
(input: PluginInferenceInput & { schema?: never; onText?: (delta: string) => void; }): Promise<string>
(input: PluginInferenceInput & { schema: Record<string, unknown>; onText?: never; }): Promise<unknown>
ctx.services.llm.askDetailed
(input: PluginInferenceInput & { schema?: never; onText?: (delta: string) => void; }): Promise<InferenceResult<string>>
(input: PluginInferenceInput & { schema: Record<string, unknown>; onText?: never; }): Promise<InferenceResult<unknown>>

llm 1.3: same execution as ask, with per-attempt metadata on success. Includes structured retries; failure/cancellation rejects, not a billing receipt.

ctx.services.llm.cancelRequest
(requestId: string): Promise<InferenceRequestReceipt | null>

Requests cancellation independently of the ask RPC. The returned snapshot may still be running; query again for its outcome and provider settlement.

ctx.services.llm.getRequest
(requestId: string): Promise<InferenceRequestReceipt | null>

llm 1.6: last 64 named requests in this plugin's local private storage. Initial metadata commits before inference dispatch; no prompt/output is retained. Includes backup/rollback and uninstall cleanup, not roaming or billing history. requestAvailable identifies this activation's handle. An older unsettled record has interrupted=true: status is last observed, not proof it still runs remotely. No automatic retry/resume; historical IDs cannot control another activation. Late terminal usage is persisted; unknown/evicted IDs return null.

ctx.services.llm.listRequests
(): Promise<InferenceRequestReceipt[]>
ctx.services.llm.policy
(): Promise<{ defaultTimeoutMs: number; maxTimeoutMs: number; perPluginLimit: number; appLimit: number; maxOutputTokensLimit: number; maxImageCount: number; maxImageBytes: number; maxImageTotalBytes: number; maxTotalOutputTokensLimit: number; maxOutputCharsLimit: number; maxInputChars: number; }>

Plugin inference limits, not billing quotas. maxOutputTokensLimit since 1.3.

services:clipboard

Écrire du texte ou une image scellée prise en charge dans le presse-papiers système.

  • Développement : v1.1.0
  • ReadAware 0.6.12 : v1.1.0
  • Autorité: service:clipboard
ctx.services.clipboard.writeImage
(resourceId: string): Promise<ResourceImageReceipt>

Clipboard 1.1. This activation's sealed resource; raster decode stays in the host.

ctx.services.clipboard.writeText
(text: string): Promise<void>

Schémas

schemas:views

Décrire des listes, formulaires, détails, markdown et mises en page de blocs prises en charge et rendus par l’hôte.

  • Développement : v1.12.0
  • ReadAware 0.6.12 : v1.12.0
  • Autorité: aucune

Déclaration du manifest

schemas:settings

Déclarer des réglages de plugin typés, des champs conditionnels et des références d’options dynamiques.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: aucune

Déclaration du manifest

schemas:themes

Décrire les palettes sémantiques de l’application et du lecteur.

  • Développement : v1.0.0
  • ReadAware 0.6.12 : v1.0.0
  • Autorité: ui:themes

Déclaration du manifest