Plugin-API-Referenz
Diese Seite beschreibt den Entwicklungsvertrag, der dem neuesten Release voraus sein kann. Die vollständige Referenz am Ende listet jede Fähigkeit mit ihrer Entwicklungsversion und ihrer Version im neuesten Release auf, inklusive der benötigten Berechtigung sowie der aufgelösten Signatur und Dokumentation jeder Methode. Der Capabilities Explorer bietet denselben Katalog interaktiv an. Die Typen des öffentlichen Plugin-Repositorys entsprechen dem neuesten Release.
Paket und Manifest
Ein Plugin enthält manifest.json und ein eigenständiges ES-Modul, normalerweise main.js. Halte Quelltext und benötigte Assets zur Prüfung im Paket.
| Feld | Bedeutung |
|---|---|
id, name, version | Stabiler Namespace, Anzeigename und Paketversion. Die ID entspricht dem Ordnernamen. |
schemaVersion | Positive Ganzzahl für das private Datenschema des Plugins, unabhängig von der Paketversion. |
requires | Fähigkeits-IDs und Semver-Bereiche, gruppiert in domains, contributions, services und schemas. |
permissions | Semantische Autorität, etwa library:read oder service:llm. |
settingsAccess | Getrennte Freigaben für discover, read und write, bezogen auf exakte Pfade oder ausdrücklich benannte Abschnittsgruppen. |
networkAccess | Erlaubte HTTP(S)-Ursprünge für Network 2.x; zusätzlich zu service:network erforderlich. |
minAppVersion | Optionaler Mindeststand der App, zusätzlich zu den Fähigkeitsanforderungen. |
main | Relatives Einstiegsmodul; Standard ist main.js. |
settings, schedules, themes, fonts | Vom Host interpretierte Deklarationen. |
services | Versionierte, typisierte Modul-Exporte für dienstübergreifende Plugin-Aufrufe. |
Es gibt kein Manifestfeld, das beliebigen Zugriff auf Dateisystem, SQL, DOM oder native IPC gewährt.
Kontext und Objektumfang
Der Host ruft activate(ctx) mit ctx.domains, ctx.contributions und ctx.services auf, zusammen mit Manifest, Sprache, App-Version, Lebenszyklusphase, Fähigkeitsversionen und unveränderlicher Buchfreigabe.
ctx.grants.book ist all, current oder ein bestimmtes book. Der Host wählt dies über Zustimmung aus. Lesen, Gedächtnis, Unterhaltungen, Befehle und Ressourcen behalten diesen Umfang über Aufrufe und Callbacks hinweg. Ein Wechsel des aktuellen Buchs kann ausstehende Lesevorgänge, Handles, Vorschläge und Beobachtungen ungültig machen.
Die Schreibberechtigung einer Domäne schließt Lesen ein. Einstellungsfreigaben bleiben nach Operation getrennt. Berechtigungspflichtige Namespaces oder Methoden können fehlen; Prüfungen auf Host-Seite laufen bei jedem Aufruf weiter. Verwende ctx.services.session.operationAvailability(...) für unterstützte Vorabprüfungen und behandle einen Ausführungsfehler auch nach einem positiven Ergebnis.
Domänen
| Domäne | Verfügbare Arbeit | Grenzen |
|---|---|---|
library | Bücher und Sammlungen, Inhaltsverzeichnisse, Suche nach exakten Positionen, Bereiche, Verweise und Bilder, Importe, Textaufgaben, Metadaten, Zusammenführen von Duplikaten und Entfernen. | Quellversionen, Buchumfang, begrenzte Lesevorgänge, akteureigene Aufgaben und getrennte Quittungen für Dateibereinigung. |
reading | Sitzungssnapshots, Navigation, Auswahl, Wiedergabe- und Modussteuerung, Fortschritt, Lesezeit und Erkenntnisse. | Sperren der aktuellen Sitzung, festgeschriebener gegenüber ausstehendem Zustand, Anbieter-Verfügbarkeit und Abbruch. |
annotations | Auflisten, Prüfen und Beobachten; Markierungen oder Notizen erstellen; bedingte Änderungs- und Lösch-Batches. | Verwende die Revision, die vor der Entscheidung der nutzenden Person beobachtet wurde. Erfasste Bereiche benötigen zusätzlich Library-Zugriff. |
conversations | Autorisierte Transkripte, gespeicherte Zusammenfassungen, Laufzeit- und Rundenanforderungszustand; Thread-Steuerung und vorgeschlagene Runden. | Host-Genehmigung startet eine vorgeschlagene Runde. Globale Thread-Operationen benötigen Zugriff auf alle Bücher. Plugins ersetzen die Chat-Laufzeit nicht. |
settings | Katalogsuche, aufgelöste Snapshots, Optionen, Modellmetadaten, Beobachtung, Aktualisierungen und Lesezurücksetzungen. | Exakte Pfade, Zielrichtlinien und zusätzliche Autorität für externe Anbieterarbeit. |
memory | Suche und Seiten, Prüfung, Korrektur/Vergessen, Profile, Entitäten, Klassifikation, Graphen und Aufgaben, Kontextarchive. | Buchfreigaben und bedingte Revisionen. Globale Identitäts-/Profiloperationen benötigen Zugriff auf alle Bücher; Generierung benötigt zusätzlich Modellautorität. |
Quelltext und Navigation
Verwende library.queries.books.searchLocations für navigierbare Quelltreffer und readRange für begrenzten Quelltext. Bewahre die zurückgegebene Quellversion und Position. Abgeleitete searchText-Treffer sind Vorschauen und keine austauschbaren Navigationsanker. Die explizite Textaufbereitung liefert eine Aufgabe, deren Fortschritt und Ergebnis beobachtet werden müssen.
Bedingte Schreibvorgänge
Prüfe das aktuelle Objekt und bewahre seine Revision, bevor du eine Bearbeitung anzeigst. Sende die bedingte Mutation gegen diese Revision. Bei einem Konflikt erneut lesen und die nutzende Person entscheiden lassen; ein stilles Ersetzen der erwarteten Revision würde eine andere Änderung überschreiben.
annotations.commands.applyChanges, Gedächtnismutationen, private Dokument-Commits und Transaktionsvorschauen haben jeweils einen eigenen typisierten Vertrag. Gewöhnliche Befehle sind nicht automatisch rückgängig machbar und keine verteilten Transaktionen.
Beobachtungen und Reaktionen
Verwende autorisierte Beobachtungen für den aktuellen Zustand und festgeschriebene Abonnements für Ereignisse. Eine Sequenznummer kann Zustellungen ordnen, ist aber weder ein Datenbankcursor noch eine Revision für bedingte Schreibvorgänge. Fehlgeschlagene Beobachtungen müssen von leeren Ergebnissen unterscheidbar bleiben.
Verwende ctx.withEvent(delivery) für automatische Folgearbeit und, wo erforderlich, stabile Regel-IDs bei kausalen Abonnements. Bewahre den gebundenen Kontext über asynchrone Aufrufe hinweg. Der Host weist kausale Zyklen und abgelaufene Zustellungen zurück; unabhängige Benutzeraktionen verwenden den ursprünglichen Kontext.
Contributions
| Contribution | Was das Plugin bereitstellt |
|---|---|
selectionActions, headerActions, contextActions, commands, uriHandlers | Aktionen an typisierten Host-Oberflächen, Palettenbefehle und Namespace-bezogene URI-Verarbeitung. |
settingsOptions | Dynamische Optionen für eine deklarierte Plugin-Einstellung. |
voiceProviders, contentProviders, readerModes | Audiosynthese, Inhalte virtueller Bücher und gebündelte Segmentierungsmodi des Readers. |
agentTools, agentContextProviders, agentRetrievalProviders | Werkzeuge, begrenzten Kontext pro Runde und durchsuchbare Plugin-eigene Quellen. |
memoryCandidateProviders | Gedächtniskandidaten zur Prüfung und Annahme durch den Host. |
themes, fonts | Im Manifest deklarierte Darstellungsauswahlen. |
syncTransports | Speicherung undurchsichtiger verschlüsselter Sync-Umschläge und Metadatenobjekte. |
Aktionen können, sofern unterstützt, ihren eigenen sichtbaren/aktivierten/markierten Zustand aktualisieren. Registrierungen und Disposables gehören zu einer Aktivierung. Die Rückgabe einer Ansicht verleiht dem Callback keine zusätzliche Domänenautorität.
Gedächtniskandidaten und direkte Memory-Befehle sind getrennte Wege: Kandidaten durchlaufen die Annahme durch den Host, während direkte Befehle die passende Memory-Freigabe und Revision benötigen. Keiner der Wege erlaubt das Einschleusen von Systemregeln oder das Ersetzen des Kernagenten.
Host-Dienste
| Dienst | Zweck | Wichtige Grenze |
|---|---|---|
storage | Privates KV, Dokumentsammlungen, bedingte Commits, Seiten, Beobachtungen und Nutzungsrichtlinien. | Plugin-Namespace und Kontingente; veraltete Cursor benötigen eine neue Ausgangsbasis. |
resources | Von Nutzenden ausgewählte Dateien/Verzeichnisse, versiegelte Byte-Handles, Exporte, Bilder und private Binär-Assets. | Keine Umgebungs-Pfade. Handles haben Besitzer, Grenzen und Lebenszeiten. |
secrets | Verschlüsselte, Plugin-private Zugangsdaten-Slots. | Kein Zugriff auf Geheimnisse anderer Plugins. |
network | Origin-begrenztes HTTP, begrenzte gepufferte Anfragen und Streaming. | Jede Weiterleitung wird geprüft; keine automatische Wiederholung beliebiger Schreibvorgänge. |
llm | Text- oder strukturierte Inferenz, Streaming, Bildressourcen, Anfragequittungen und Budgets. | Nutzerkonfiguration, Datenschutzregeln, Abbruch sowie Host-/Anbietergrenzen. |
clipboard | Text oder ein versiegeltes Bild schreiben. | Ausdrückliche Berechtigung und unterstützter Ressourcentyp. |
ui | Ansichten, Toasts, native Speichern-/Öffnen-Abläufe, Workspace- und Befehlsnavigation, Reader-Panels und Fenster. | Methodenspezifische Domänenfreigaben und Darstellung im Besitz des Hosts. |
session | Nicht sensible Umgebungsmetadaten und Verfügbarkeit von Operationen. | Kein altes Lesesitzungs-Abonnement; verwende die Reading-Domäne. |
schedules | Deklarierte wiederkehrende Handler und eigene aufgeschobene Anfragen. | Arbeit läuft bei geöffneter App; der Zeitpunkt ist nicht exakt. |
jobs | Unterstützte dauerhafte Pläne, Checkpoints, Beobachtung und Steuerung. | Typisierte Host-Operationen, keine beliebige JavaScript-Ausführung. |
changes | Eingegrenzte persistente Änderungscursor. | Hinweise zum Neuladen, kein rohes Ereignisprotokoll oder historische Werte. |
transactions | Vorschau, Commit, Quittungsabfrage und bedingte Rückgängig-Vorschau. | Unterstützte lokale Operationen und ursprüngliche Freigaben; unbekannte Ergebnisse benötigen Quittungsabfrage. |
plugins | Registrierungen prüfen, Änderungen beobachten sowie typisierte Plugin-Dienste entdecken und aufrufen. | Schnittmenge der Autorität von Aufrufer und Ziel, Umfang, Versionen und isolierte Dienstausführung. |
maintenance | Wartungsstatus prüfen und hosteigene Backup-, Verbindungstest-, Update- oder Einstellungsabläufe öffnen. | Der Host verwaltet Zugangsdaten, Dateidialoge und folgenreiche Bestätigung. |
sync | Autorisierten Sync-Status und Rückstand beobachten sowie hostverwaltete Konto- oder Sync-Abläufe anfordern. | Keine Verschlüsselungsschlüssel oder rohen Kontozugangsdaten. |
diagnostics, logging | Geprüfte Diagnoseexporte und begrenzte strukturierte Entwicklerereignisse. | Keine beliebigen Inhalte, Geheimnisse oder automatische Meldung über die Log-API. |
Netzwerk und Inferenz
Network 2.x benötigt sowohl eine semantische Berechtigung als auch explizite Ursprünge:
{
"requires": { "services": { "network": "^2.2.0" } },
"permissions": ["service:network"],
"networkAccess": { "origins": ["https://api.example.com"] }
}Ersetze den Beispielursprung durch den tatsächlich verwendeten Endpunkt. Ursprünge enthalten Schema, Host und Port; sie sind weder URL-Pfade noch Subdomain-Globs. Weiterleitungen müssen weiterhin autorisiert sein. Streaming-Aufrufer schließen eigene Streams nach Gebrauch. Optionale sichere Wiederholungen sind auf unterstützte Leseanfragen vor einer Antwort begrenzt; ein Abbruch macht eine externe Nebenwirkung nicht rückgängig.
Verwende für Inferenz readingContext für Buchkontext, damit der Host Datenschutz- und Umfangsregeln anwenden kann. Verwende versiegelte Ressourcen-IDs für unterstützte Bilder. Anfragemetadaten und Ausgabebudgets helfen bei der Arbeitssteuerung; sie sind weder eine Abrechnung noch eine Garantie für die Einhaltung durch den Anbieter.
Hintergrundarbeit und Transaktionen
Verwende einen Zeitplan für den Aufruf eines Handlers, eine eigene aufgeschobene Anfrage für spätere Arbeit während die App läuft und einen dauerhaften Job nur dann, wenn sein typisierter Plan die Operation unterstützt. Die Wiederherstellung nach einem Neustart kann Aufmerksamkeit erfordern, statt ein unsicheres externes Ergebnis blind zu wiederholen.
Transaktionen kombinieren unterstützte Einstellungen, private Dokument- und Domänenoperationen unter den ursprünglichen Freigaben. Die Vorschau friert die geplante Arbeit ein; der Commit verbraucht diese Vorschau. Frage nach einer unbekannten Antwort die Quittung ab, bevor du wiederholst. Rückgängigmachen ist davon abhängig, dass der Zustand weiterhin dem vorherigen Ergebnis entspricht.
Dienste zwischen Plugins
Deklariere Dienst-ID, Version, Scope, erforderliche Berechtigungen und Ein-/Ausgabeschemas im Provider-Manifest und exportiere den Handler im services-Objekt des Moduls. Entdecke und rufe ihn über den Plugins-Dienst auf. Der Host startet einen neuen isolierten Dienstraum mit der Schnittmenge der Autorität; er aktiviert für diesen Aufruf nicht die gewöhnliche UI-Laufzeit des Providers. Von einem Agenten stammende Aufrufe behalten ihre Genehmigungspflicht.
Ansichten, Einstellungen, Designs und Schriften
Plugins liefern deklarative Ansichtsdaten. Der Host rendert Listen, Formulare, Markdown, Details und unterstützte Block-Layouts. Verwende typisierte Ansichtsergebnisse und Live-Updates; halte Lade-, Konflikt-, Leer- und Fehlerzustände getrennt. Plugin-Code hat keinen Zugriff auf React, DOM, Iframe oder beliebiges CSS.
Einstellungsfelder werden vom Host gerendert. Geheimnisfelder schreiben in verschlüsselte Geheimnis-Slots und werden weder zu gewöhnlichen Formularwerten noch zu modellsichtbaren Einstellungen. Für das Anbieten eines Designs oder einer Schrift ist ui:themes erforderlich; die Auswahl verwendet die entsprechende Schreibfreigabe für Settings.
Lebenszyklus und Kompatibilität
- Aktivierung: unterstützte Lesevorgänge und Registrierungen; vorbereitete Contributions sind noch nicht sichtbar.
- Migration: nur privater Speicher, bevor ein geändertes Schema festgeschrieben wird.
- Aktiv: beförderte Handler dürfen freigegebene Fähigkeiten verwenden.
Der Host führt Gesundheitsprüfungen durch und befördert einen Kandidaten, wenn Aktivierung und jede Migration erfolgreich sind. Bei einem Fehler werden vorheriges Paket und vorherige Daten wiederhergestellt. Beim Entladen werden Registrierungen, Callbacks und eigene Ressourcen freigegeben; dauerhafte Daten folgen ihrem eigenen Aufbewahrungsvertrag. In der aktuellen Entwicklung entfernt die Deinstallation private Dokumentsammlungen und Binär-Assets, behält aber den definierten KV-/Secret-/Schema-Zustand für eine erneute Installation.
Deklariere jede verwendete Fähigkeit und jedes Schema unabhängig. Eine Versionsnummer belegt Vertragskompatibilität, aber nicht, dass jedes Betriebssystem, jeder Anbieter oder jeder Fehlerfall Ende-zu-Ende akzeptiert wurde. Prüfe den tatsächlichen Desktop-Ablauf, den du auslieferst.
Plugin erstellen · Capabilities Explorer · Veröffentlichen
Vollständige Referenz
Jede Fähigkeit des Entwicklungsvertrags, nach Familie gruppiert. Ein Plugin, das für die heute genutzte App bestimmt ist, sollte die für das neueste Release angegebene Version voraussetzen.
Domains
domains:library
Bücher, Quelltext, Inhaltsverzeichnisse, genaue Positionen, Bereiche, Bilder und Sammlungen prüfen; Textaufgaben importieren, ordnen und verwalten.
- Entwicklung: v1.35.0
- ReadAware 0.6.12: v1.35.0
- Berechtigung:
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; }): PluginDisposablectx.domains.library.events.observeEnrichment(bookId: string, handler: PluginObservationHandler<BookEnrichmentObservation>, options?: { ruleId?: string; }): PluginDisposablectx.domains.library.events.observeImportTask(taskId: string, handler: PluginObservationHandler<BookImportTaskSnapshot>, options?: { ruleId?: string; }): PluginDisposableInitial snapshot and coalesced monotonic revisions, including terminal failures.
ctx.domains.library.events.observeInvalidation(handler: PluginObservationHandler<ProjectionInvalidation>): PluginDisposableInitial 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; }): PluginDisposableLibrary 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; }): PluginDisposablectx.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
Lesesitzungen beobachten, Text navigieren und auswählen, Wiedergabe und Modi steuern sowie Fortschritt, Zeit und Erkenntnisse abfragen.
- Entwicklung: v2.24.0
- ReadAware 0.6.12: v2.24.0
- Berechtigung:
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>): PluginDisposablectx.domains.reading.events.observeSession(handler: (snapshot: ReadingSessionSnapshot, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposableImmediate 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; }): PluginDisposableImmediate 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; }): PluginDisposablectx.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
Markierungen und Notizen auflisten, prüfen und beobachten; sie erstellen oder revisionsgeprüft bearbeiten und löschen.
- Entwicklung: v2.2.0
- ReadAware 0.6.12: v2.2.0
- Berechtigung:
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>): PluginDisposableSince 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; }): PluginDisposablectx.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
Autorisierte Transkripte, Zusammenfassungen und Laufzeitstatus lesen; Züge vorschlagen, Threads verwalten und genehmigte Stop- oder Löschsteuerungen verwenden.
- Entwicklung: v1.7.0
- ReadAware 0.6.12: v1.7.0
- Berechtigung:
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>): PluginDisposablectx.domains.conversations.events.observeRuntime(handler: PluginObservationHandler<PluginConversationRuntimeSnapshot>, options?: { ruleId?: string; }): PluginDisposableConversations 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; }): PluginDisposablectx.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
Genaue Einstellungspfade und Optionen entdecken, stabile Snapshots lesen, Änderungen beobachten und unterstützte Ziele aktualisieren.
- Entwicklung: v1.11.0
- ReadAware 0.6.12: v1.11.0
- Berechtigung: keine
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; }): PluginDisposablectx.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>): PluginDisposableSettled 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
Erinnerungen suchen, seitenweise laden, prüfen und korrigieren; mit Profilen, Entitäten, Klassifizierung, Graphen und versionierten Kontextpaketen arbeiten.
- Entwicklung: v2.8.0
- ReadAware 0.6.12: v2.8.0
- Berechtigung:
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>): PluginDisposableInitial 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[]>
Beiträge
contributions:uriHandlers
Namespacespezifische ReadAware-URI-Aufrufe über eine registrierte Aktion verarbeiten.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
ctx.contributions.uriHandlers.register(handler: PluginUriHandler): PluginActionRegistration
contributions:selectionActions
Aktionen für erfasste Auswahl, Annotationen oder Navigator-Eingaben hinzufügen.
- Entwicklung: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Berechtigung: keine
ctx.contributions.selectionActions.register(action: PluginSelectionAction): PluginActionRegistration
contributions:headerActions
Reader-, Bibliotheks- oder Agent-Header-Aktionen mit vom Host gerenderten Ansichten hinzufügen.
- Entwicklung: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Berechtigung: keine
ctx.contributions.headerActions.register(action: PluginHeaderAction): PluginActionRegistration
contributions:contextActions
Typisierte Aktionen für unterstützte Buch- oder Sammlungskontextflächen hinzufügen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
ctx.contributions.contextActions.register(action: PluginContextAction): PluginActionRegistration
contributions:commands
Namespacespezifische Aktionen für die Befehlspalette hinzufügen und ihren eigenen Status aktualisieren.
- Entwicklung: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Berechtigung: keine
ctx.contributions.commands.register(command: PluginCommand): PluginActionRegistration
contributions:settingsOptions
Dynamische Auswahlmöglichkeiten für eine deklarierte Plugin-Einstellung auflösen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
ctx.contributions.settingsOptions.register(fieldId: string, provider: (values: PluginFormValues) => PluginSelectOption[] | Promise<PluginSelectOption[]>): PluginDisposable
contributions:settingsPage
Registriere eine deklarative Seite, die das Einstellungsformular des Plugin-Manifests im eigenen Bereich „Einstellungen“ ersetzt.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
ctx.contributions.settingsPage.register(page: { view(): PluginView | Promise<PluginView>; }): PluginDisposable
contributions:voiceProviders
Stimmenauswahl und kodiertes Audio für das Vorlesen bereitstellen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
ctx.contributions.voiceProviders.register(provider: PluginVoiceProvider): PluginDisposable
contributions:contentProviders
Abschnitte für virtuelle Bücher wie gespeicherte Feeds bereitstellen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
ctx.contributions.contentProviders.register(provider: { id: string; load(key: string): Promise<PluginBookContent>; }): PluginDisposable
contributions:agentTools
Namespacespezifische Tools registrieren, die der Leseassistent entdecken und aufrufen kann.
- Entwicklung: v1.3.0
- ReadAware 0.6.12: v1.3.0
- Berechtigung:
agent:tools
ctx.contributions.agentTools.register(tool: PluginToolDefinition): PluginActionRegistration
contributions:agentContextProviders
Begrenzte Referenzblöcke pro Zug und deklarierte Quellen für Leseabsichten liefern.
- Entwicklung: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Berechtigung:
agent:context
ctx.contributions.agentContextProviders.register(provider: PluginAgentContextProvider): PluginDisposable
contributions:agentRetrievalProviders
Durchsuchbare plugin-eigene Quellen für den Assistenten bereitstellen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung:
agent:retrieval
ctx.contributions.agentRetrievalProviders.register(provider: PluginAgentRetrievalProvider): PluginDisposable
contributions:memoryCandidateProviders
Fakten, Präferenzen, Erkenntnisse oder Zusammenfassungen zur Speicherannahme vorschlagen.
- Entwicklung: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Berechtigung:
agent:memory
ctx.contributions.memoryCandidateProviders.register(provider: PluginMemoryCandidateProvider): PluginDisposable
contributions:themes
Semantische App- und Reader-Theme-Auswahlen im Manifest deklarieren.
- Entwicklung: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Berechtigung:
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
Schriftmetadaten und gebündelte Schriftdateien deklarieren.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung:
ui:themes
Manifest-Deklaration
contributions:syncTransports
Undurchsichtige verschlüsselte Ereignisse, Blobs und Metadatenobjekte für Schlüsselmaterial auf einem alternativen Remote speichern und abrufen.
- Entwicklung: v2.0.0
- ReadAware 0.6.12: v2.0.0
- Berechtigung:
sync:transport
ctx.contributions.syncTransports.register(transport: PluginSyncTransport): PluginDisposable
Dienste
services:storage
Private KV- und Dokumentensammlungen, Seiten, Beobachtungen, bedingte Commits und Quotenrichtlinien verwenden.
- Entwicklung: v2.6.0
- ReadAware 0.6.12: v2.6.0
- Berechtigung: keine
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): PluginDocumentCollectionA 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/anchorare 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 | nullctx.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>>): PluginDisposableStorage 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; }): PluginDisposableFires 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
Zugangsdaten in verschlüsselten, plugin-eigenen Geheimnis-Slots lesen und schreiben.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
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
Ansichten veröffentlichen, Toasts anzeigen, Ressourcen speichern oder öffnen, Arbeitsbereiche und Befehle navigieren sowie unterstützte Reader-Panels und Fenster steuern.
- Entwicklung: v1.18.0
- ReadAware 0.6.12: v1.18.0
- Berechtigung: keine
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; }): PluginDisposableUI 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>): PluginDisposablePlugins 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>): PluginDisposablePlugins 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): voidctx.services.ui.window.control(request: HostWindowRequest): Promise<HostWindowReceipt>ctx.services.ui.window.observe(handler: PluginObservationHandler<HostWindowObservation>, options?: { ruleId?: string; }): PluginDisposableUI 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; }): PluginDisposableUI 1.16: use the separate reaction delivery even for null/retired snapshots.
ctx.services.ui.workspace.snapshot(query?: WorkspaceQuery): Promise<WorkspaceSnapshot>
services:schedules
Deklarierte wiederkehrende Handler binden, Zeitpläne prüfen und steuern sowie eigene verzögerte Anfragen verwalten.
- Entwicklung: v2.1.0
- ReadAware 0.6.12: v2.1.0
- Berechtigung: keine
ctx.services.schedules.bind(scheduleId: string, run: (context: PluginScheduleRun, delivery?: PluginReactionEvent) => void | Promise<void>): PluginDisposablectx.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
Dauerhafte Pläne aus unterstützten Host-Operationen starten, prüfen und steuern.
- Entwicklung: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Berechtigung: keine
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
Bereichsgebundene Änderungs-Cursor öffnen und lesen, die über Neustarts hinweg gespeichert werden können.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
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
Unterstützte lokale Änderungen in der Vorschau anzeigen und committen, Belege prüfen und bedingtes Rückgängigmachen vorschauen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
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
Umgebungsmetadaten lesen und die Verfügbarkeit unterstützter Operationen prüfen.
- Entwicklung: v2.18.0
- ReadAware 0.6.12: v2.18.0
- Berechtigung: keine
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; }): PluginDisposableSession 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
Installierte Plugins und Registrierungen prüfen, Änderungen beobachten sowie typisierte Plugin-Dienste entdecken oder aufrufen.
- Entwicklung: v1.10.0
- ReadAware 0.6.12: v1.10.0
- Berechtigung: keine
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; }): PluginDisposablePlugins 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
Wartungsstatus prüfen und host-eigene Backup-, Verbindungstest-, Update- oder Einstellungsvorgänge öffnen.
- Entwicklung: v1.5.0
- ReadAware 0.6.12: v1.5.0
- Berechtigung: keine
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; }): PluginDisposablectx.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
Unterstützte Abläufe für Diagnoseexport oder -berichte anfordern.
- Entwicklung: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Berechtigung:
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
Begrenzte strukturierte Entwicklerereignisse schreiben und die Protokollierungsrichtlinie prüfen.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
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
Dateien und Verzeichnisse auswählen, versiegelte Ressourcen lesen oder erstellen, Daten exportieren und private Binär-Assets speichern.
- Entwicklung: v1.6.0
- ReadAware 0.6.12: v1.6.0
- Berechtigung: keine
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
Synchronisierungsstatus und Rückstand beobachten, Synchronisierung anfordern und host-eigene Konto- oder Verbindungsabläufe öffnen.
- Entwicklung: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Berechtigung:
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; }): PluginDisposableDelivers 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, oralready-runningwhen 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 carrysync/*codes).ctx.services.sync.snapshot(): Promise<HostSyncSnapshot>Current sync state: backend, connection, progress, last cycle and last error code.
services:network
Ursprungsgebundene HTTP-Anfragen stellen oder begrenzte Streams mit optionalen sicheren Wiederholungen lesen.
- Entwicklung: v2.2.0
- ReadAware 0.6.12: v2.2.0
- Berechtigung:
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
Text-, strukturierte oder Streaming-Inferenz anfordern, versiegelte Bildressourcen verwenden und Anfragemetadaten sowie Budgets verfolgen.
- Entwicklung: v1.6.0
- ReadAware 0.6.12: v1.6.0
- Berechtigung:
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
Text oder ein unterstütztes versiegeltes Bild in die System-Zwischenablage schreiben.
- Entwicklung: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Berechtigung:
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>
Schemas
schemas:views
Vom Host gerenderte Listen, Formulare, Details, Markdown und unterstützte Blocklayouts beschreiben.
- Entwicklung: v1.12.0
- ReadAware 0.6.12: v1.12.0
- Berechtigung: keine
Manifest-Deklaration
schemas:settings
Typisierte Plugin-Einstellungen, bedingte Felder und dynamische Optionsreferenzen deklarieren.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung: keine
Manifest-Deklaration
schemas:themes
Semantische Paletten für Anwendung und Reader beschreiben.
- Entwicklung: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Berechtigung:
ui:themes
Manifest-Deklaration