Referencia de la API de plugins
Esta página explica el contrato de desarrollo, que puede adelantarse a la última versión. La referencia completa al final enumera cada capacidad con su versión de desarrollo y su versión en la última versión establecida, el permiso que necesita, y la firma resuelta y la documentación de cada método. El Explorador de Capacidades ofrece el mismo catálogo de forma interactiva. Los tipos del repositorio público de plugins coinciden con la última versión.
Paquete y manifiesto
Un plugin contiene manifest.json y un módulo ES autocontenido, normalmente main.js. Mantén el código fuente y los recursos necesarios dentro del paquete para su revisión.
| Campo | Significado |
|---|---|
id, name, version | Espacio de nombres estable, nombre visible y versión del paquete. El ID coincide con el nombre de la carpeta. |
schemaVersion | Entero positivo para el esquema de datos privado del plugin; es independiente de la versión del paquete. |
requires | IDs de capacidades y rangos semver, agrupados en domains, contributions, services y schemas. |
permissions | Autoridad semántica, como library:read o service:llm. |
settingsAccess | Concesiones independientes de discover, read y write para rutas exactas o grupos de secciones explícitos. |
networkAccess | Orígenes HTTP(S) permitidos para Network 2.x; es obligatorio junto con service:network. |
minAppVersion | Límite inferior opcional de la versión de la aplicación, además de los requisitos de capacidades. |
main | Módulo de entrada relativo; por defecto es main.js. |
settings, schedules, themes, fonts | Declaraciones interpretadas por el host. |
services | Exportaciones de servicios de módulos versionadas y tipadas para llamadas entre plugins. |
No existe ningún campo del manifiesto que conceda acceso arbitrario al sistema de archivos, SQL, DOM o IPC nativo.
Contexto y ámbito de los objetos
El host llama a activate(ctx) con ctx.domains, ctx.contributions y ctx.services, además del manifiesto, el idioma, la versión de la aplicación, la fase del ciclo de vida, las versiones de las capacidades y la concesión inmutable del libro.
ctx.grants.book es all, current o un book especificado. El host lo selecciona mediante consentimiento. La lectura, la memoria, las conversaciones, los comandos y los recursos conservan ese ámbito entre llamadas y callbacks. Un cambio de libro actual puede invalidar lecturas, identificadores, propuestas y observaciones pendientes.
El permiso de escritura de un dominio incluye la lectura. Las concesiones de Settings siguen siendo independientes según la operación. Los espacios de nombres o métodos protegidos por permisos pueden estar ausentes; aun así, las comprobaciones del host se ejecutan en cada llamada. Usa ctx.services.session.operationAvailability(...) para las consultas de preflight admitidas y gestiona el fallo de ejecución incluso después de un resultado positivo.
Dominios
| Dominio | Trabajo disponible | Límites |
|---|---|---|
library | Libros y colecciones, índices, búsqueda de ubicaciones exactas, rangos, referencias e imágenes, importaciones, tareas de texto, metadatos, fusiones de duplicados y eliminación. | Versiones de origen, ámbito del libro, lecturas acotadas, tareas propias del actor y comprobantes independientes de limpieza de archivos. |
reading | Instantáneas de sesión, navegación, selección, controles de reproducción y modo, progreso, tiempo de lectura e información de uso. | Protecciones de la sesión actual, estado asentado frente a pendiente, disponibilidad del proveedor y cancelación. |
annotations | Páginas, inspección y observaciones; crear destacados o notas; lotes condicionales de edición/eliminación. | Usa la revisión observada antes de la decisión del usuario. Los rangos capturados también requieren acceso a Library. |
conversations | Transcripciones autorizadas, resúmenes almacenados, estado de ejecución y de solicitudes de turnos; controles de hilos y turnos propuestos. | La aprobación del host inicia un turno propuesto. Las operaciones sobre hilos globales requieren acceso a todos los libros. Los plugins no sustituyen el runtime de chat. |
settings | Descubrimiento del catálogo, instantáneas resueltas, opciones, metadatos de modelos, observación, actualizaciones y reinicios de lectura. | Rutas exactas, política del objetivo y autoridad adicional para trabajar con proveedores externos. |
memory | Búsqueda y páginas, inspección, corrección/olvido, perfiles, entidades, clasificación, grafos y tareas, archivos de contexto. | Concesiones de libros y revisiones condicionales. Las operaciones de identidad/perfil globales requieren acceso a todos los libros; la generación también necesita autoridad sobre el modelo. |
Texto de origen y navegación
Usa library.queries.books.searchLocations para coincidencias navegables en el origen y readRange para obtener texto de origen acotado. Conserva la versión de origen y la ubicación devueltas. Las coincidencias derivadas de searchText son vistas previas, no anclas de navegación intercambiables. La preparación explícita de texto devuelve un trabajo cuyo progreso y resultado deben observarse.
Escrituras condicionales
Inspecciona el objeto actual y conserva su revisión antes de mostrar una edición. Envía la mutación condicional contra esa revisión. En caso de conflicto, vuelve a leer y deja que el usuario decida; sustituir silenciosamente la revisión esperada sobrescribiría otro cambio.
annotations.commands.applyChanges, las mutaciones de Memory, los commits de documentos privados y las vistas previas de transacciones tienen cada uno su propio contrato tipado. Los comandos ordinarios no se pueden deshacer automáticamente ni son transacciones distribuidas.
Observaciones y reacciones
Usa observaciones autorizadas para el estado actual y suscripciones confirmadas para los eventos. Un número de secuencia puede ordenar las entregas sin ser un cursor de base de datos ni una revisión de escritura condicional. Las observaciones fallidas deben poder distinguirse de los resultados vacíos.
Usa ctx.withEvent(delivery) para el trabajo de seguimiento automático y IDs de reglas estables en las suscripciones causales cuando sea necesario. Conserva el contexto vinculado durante las llamadas asíncronas. El host rechaza los ciclos causales y las entregas caducadas; las acciones de usuario independientes usan el contexto original.
Contribuciones
| Contribución | Lo que proporciona el plugin |
|---|---|
selectionActions, headerActions, contextActions, commands, uriHandlers | Acciones en superficies tipadas del host, comandos de la paleta y gestión de URI con espacios de nombres. |
settingsOptions | Opciones dinámicas para un ajuste declarado del plugin. |
voiceProviders, contentProviders, readerModes | Síntesis de audio, contenido de libros virtuales y modos de segmentación incluidos en el lector. |
agentTools, agentContextProviders, agentRetrievalProviders | Herramientas, contexto acotado por turno y fuentes propias del plugin que se pueden buscar. |
memoryCandidateProviders | Memorias candidatas para la validación y aceptación del host. |
themes, fonts | Opciones de apariencia declaradas en el manifiesto. |
syncTransports | Almacenamiento de sobres de sincronización cifrados opacos y objetos meta. |
Las acciones pueden actualizar su propio estado visible/habilitado/marcado cuando sea compatible. Los registros y los objetos descartables pertenecen a una activación. Devolver una vista no concede al callback autoridad adicional sobre los dominios.
Las memorias candidatas y los comandos directos de Memory son rutas distintas: las candidatas pasan por la aceptación del host, mientras que los comandos directos requieren la concesión de Memory y la revisión adecuadas. Ninguna de las dos permite inyectar reglas del sistema ni sustituir al agente principal.
Servicios del host
| Servicio | Úsalo para | Límite principal |
|---|---|---|
storage | KV privado, colecciones de documentos, commits condicionales, páginas, observaciones y políticas de uso. | Espacio de nombres y cuotas del plugin; los cursores obsoletos requieren una nueva línea base. |
resources | Archivos/directorios elegidos por el usuario, identificadores sellados de bytes, exportaciones, imágenes y recursos binarios privados. | No hay rutas ambientales. Los identificadores tienen propietarios, límites y ciclos de vida. |
secrets | Ranuras privadas de credenciales cifradas del plugin. | No hay acceso a los secretos de otro plugin. |
network | HTTP con ámbito de origen, solicitudes almacenadas en búfer y streaming acotados. | Se comprueba cada redirección; no se repiten automáticamente escrituras arbitrarias. |
llm | Inferencia de texto o estructurada, streaming, recursos de imagen, comprobantes de solicitudes y presupuestos. | Configuración del usuario, reglas de privacidad, cancelación y límites del host/proveedor. |
clipboard | Escribir texto o una imagen sellada. | Permiso explícito y tipo de recurso compatible. |
ui | Vistas, toast, flujos nativos de guardado/apertura, navegación por el espacio de trabajo y comandos, paneles del lector y ventanas. | Concesiones de dominio específicas del método y presentación propiedad del host. |
session | Metadatos del entorno no sensibles y disponibilidad de operaciones. | No hay suscripción a la antigua sesión de lectura; usa el dominio Reading. |
schedules | Handlers recurrentes declarados y solicitudes diferidas propias. | El trabajo se ejecuta mientras la aplicación está abierta; la hora no es exacta. |
jobs | Planes duraderos compatibles, checkpoints, observación y control. | Operaciones tipadas del host, no ejecución arbitraria de JavaScript. |
changes | Cursores de cambios persistentes con ámbito. | Indicaciones de recarga, no un registro de eventos sin procesar ni valores históricos. |
transactions | Vista previa, commit, consulta de comprobantes y vista previa de deshacer condicional. | Operaciones locales compatibles y concesiones originales; los resultados desconocidos requieren consultar el comprobante. |
plugins | Inspeccionar registros, observar cambios, descubrir e invocar servicios de plugins tipados. | Intersección de autoridad entre quien llama y quien recibe, ámbito, versiones y ejecución aislada del servicio. |
maintenance | Exportaciones de diagnóstico revisadas y flujos de estado, copia de seguridad, prueba de conexión y actualización gestionados por el host. | El host conserva las credenciales, los diálogos de archivos y las confirmaciones consecuentes. |
sync | Estado de sincronización autorizado, cola pendiente y flujos de cuenta o sincronización gestionados por el host. | No hay claves de cifrado ni credenciales de cuenta sin procesar. |
diagnostics, logging | Exportaciones de diagnóstico revisadas y eventos de desarrollador estructurados y acotados. | No hay contenido arbitrario, secretos ni informes automáticos mediante la API de logs. |
Red e inferencia
Network 2.x necesita tanto un permiso semántico como orígenes explícitos:
{
"requires": { "services": { "network": "^2.2.0" } },
"permissions": ["service:network"],
"networkAccess": { "origins": ["https://api.example.com"] }
}Sustituye el origen de ejemplo por el endpoint que realmente uses. Los orígenes incluyen esquema, host y puerto; no son rutas URL ni comodines de subdominio. Las redirecciones deben seguir estando autorizadas. Los llamadores de streaming cierran los streams propios cuando terminan. El reintento seguro opcional se limita a solicitudes de lectura compatibles antes de entregar una respuesta; la cancelación no revierte un efecto secundario remoto.
Para la inferencia, usa readingContext para el contexto del libro, de modo que el host pueda aplicar las reglas de privacidad y ámbito. Usa IDs de recursos sellados para las imágenes compatibles. Los metadatos de la solicitud y los presupuestos de salida ayudan a controlar el trabajo; no son un estado de facturación ni una garantía de cumplimiento del proveedor.
Trabajo en segundo plano y transacciones
Usa un schedule para organizar la invocación de un handler, una solicitud diferida propia para trabajo posterior mientras la aplicación se ejecuta y un job duradero solo cuando su plan tipado admita la operación. La recuperación tras un reinicio puede requerir atención en lugar de repetir a ciegas un resultado externo incierto.
Las transacciones combinan operaciones compatibles de Settings, documentos privados y dominios bajo las concesiones originales. La vista previa congela el trabajo propuesto; el commit consume esa vista previa. Después de una respuesta desconocida, consulta el comprobante antes de reintentar. Deshacer está condicionado a que el estado siga coincidiendo con el resultado anterior.
Servicios entre plugins
Declara en el manifiesto del proveedor el ID del servicio, la versión, el ámbito, los permisos necesarios y los esquemas de entrada/salida, y exporta su handler en el objeto services del módulo. Descúbrelo y llámalo mediante el servicio Plugins. El host ejecuta un nuevo realm de servicio aislado con autoridad intersectada; no activa el runtime de UI normal del proveedor para la llamada. Las llamadas originadas por el agente conservan su requisito de aprobación.
Vistas, ajustes, temas y fuentes
Los plugins devuelven datos de vista declarativos. El host renderiza listas, formularios, Markdown, detalles y diseños de bloques compatibles. Usa resultados de vista tipados y actualizaciones de vista en vivo; mantén diferenciados los estados de carga, conflicto, vacío y error. El código del plugin no dispone de React, DOM, iframe ni CSS arbitrario.
Los campos de Settings los renderiza el host. Los campos secretos escriben en ranuras de secretos cifradas y no se convierten en valores de formulario ordinarios ni en ajustes visibles para el modelo. Proporcionar un tema o una fuente requiere ui:themes; seleccionar uno usa la concesión de escritura de Settings correspondiente.
Ciclo de vida y compatibilidad
- Activando: lecturas y registros compatibles; las contribuciones en preparación todavía no son visibles.
- Migrando: solo almacenamiento privado, antes de confirmar un esquema modificado.
- Activo: los handlers promovidos pueden usar las capacidades concedidas.
El host comprueba el estado y promueve un candidato cuando la activación y cualquier migración terminan correctamente. Un fallo restaura el paquete y los datos anteriores. La descarga libera registros, callbacks y recursos propios; los datos duraderos siguen su contrato de retención independiente. En el desarrollo actual, la desinstalación elimina las colecciones de documentos privados y los recursos binarios, y conserva el estado definido de KV/secret/schema para la reinstalación.
Declara cada capacidad y esquema utilizados de forma independiente. Un número de versión demuestra compatibilidad del contrato, pero no que todos los sistemas operativos, proveedores o casos de fallo hayan superado la aceptación de extremo a extremo. Verifica el flujo real de escritorio que distribuyes.
Crear un plugin · Explorador de capacidades · Publicación
Referencia completa
Cada capacidad del contrato de desarrollo, agrupada por familia. Un plugin pensado para la app que la gente usa hoy debería requerir la versión indicada para la última versión publicada.
Dominios
domains:library
Inspeccionar libros, texto fuente, índices, ubicaciones exactas, rangos, imágenes y colecciones; importar, organizar y gestionar tareas de texto.
- Desarrollo: v1.35.0
- ReadAware 0.6.12: v1.35.0
- Autoridad:
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
Observar sesiones de lectura, navegar y seleccionar texto, controlar reproducción y modos, y consultar progreso, tiempo e información.
- Desarrollo: v2.24.0
- ReadAware 0.6.12: v2.24.0
- Autoridad:
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
Consultar, inspeccionar y observar resaltados y notas; crearlos o aplicar ediciones y eliminaciones con revisión de versión.
- Desarrollo: v2.2.0
- ReadAware 0.6.12: v2.2.0
- Autoridad:
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
Leer transcripciones, resúmenes y estado de ejecución autorizados; proponer turnos, gestionar hilos y usar controles aprobados de detener o limpiar.
- Desarrollo: v1.7.0
- ReadAware 0.6.12: v1.7.0
- Autoridad:
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
Descubrir rutas y opciones exactas, leer instantáneas asentadas, observar cambios y actualizar destinos compatibles.
- Desarrollo: v1.11.0
- ReadAware 0.6.12: v1.11.0
- Autoridad: ninguno
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
Buscar, paginar, inspeccionar y corregir memorias; trabajar con perfiles, entidades, clasificación, grafos y paquetes de contexto versionados.
- Desarrollo: v2.8.0
- ReadAware 0.6.12: v2.8.0
- Autoridad:
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[]>
Contribuciones
contributions:uriHandlers
Aportar la contribución de plugin uriHandlers mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
ctx.contributions.uriHandlers.register(handler: PluginUriHandler): PluginActionRegistration
contributions:selectionActions
Aportar la contribución de plugin selectionActions mediante el contrato público.
- Desarrollo: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Autoridad: ninguno
ctx.contributions.selectionActions.register(action: PluginSelectionAction): PluginActionRegistration
contributions:headerActions
Aportar la contribución de plugin headerActions mediante el contrato público.
- Desarrollo: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Autoridad: ninguno
ctx.contributions.headerActions.register(action: PluginHeaderAction): PluginActionRegistration
contributions:contextActions
Aportar la contribución de plugin contextActions mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
ctx.contributions.contextActions.register(action: PluginContextAction): PluginActionRegistration
contributions:commands
Aportar la contribución de plugin commands mediante el contrato público.
- Desarrollo: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Autoridad: ninguno
ctx.contributions.commands.register(command: PluginCommand): PluginActionRegistration
contributions:settingsOptions
Aportar la contribución de plugin settingsOptions mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
ctx.contributions.settingsOptions.register(fieldId: string, provider: (values: PluginFormValues) => PluginSelectOption[] | Promise<PluginSelectOption[]>): PluginDisposable
contributions:settingsPage
Registra una página declarativa que reemplaza el formulario de ajustes del manifiesto del plugin en su propia sección de Ajustes.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
ctx.contributions.settingsPage.register(page: { view(): PluginView | Promise<PluginView>; }): PluginDisposable
contributions:voiceProviders
Aportar la contribución de plugin voiceProviders mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
ctx.contributions.voiceProviders.register(provider: PluginVoiceProvider): PluginDisposable
contributions:contentProviders
Aportar la contribución de plugin contentProviders mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
ctx.contributions.contentProviders.register(provider: { id: string; load(key: string): Promise<PluginBookContent>; }): PluginDisposable
contributions:agentTools
Aportar la contribución de plugin agentTools mediante el contrato público.
- Desarrollo: v1.3.0
- ReadAware 0.6.12: v1.3.0
- Autoridad:
agent:tools
ctx.contributions.agentTools.register(tool: PluginToolDefinition): PluginActionRegistration
contributions:agentContextProviders
Aportar la contribución de plugin agentContextProviders mediante el contrato público.
- Desarrollo: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Autoridad:
agent:context
ctx.contributions.agentContextProviders.register(provider: PluginAgentContextProvider): PluginDisposable
contributions:agentRetrievalProviders
Aportar la contribución de plugin agentRetrievalProviders mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad:
agent:retrieval
ctx.contributions.agentRetrievalProviders.register(provider: PluginAgentRetrievalProvider): PluginDisposable
contributions:memoryCandidateProviders
Aportar la contribución de plugin memoryCandidateProviders mediante el contrato público.
- Desarrollo: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Autoridad:
agent:memory
ctx.contributions.memoryCandidateProviders.register(provider: PluginMemoryCandidateProvider): PluginDisposable
contributions:themes
Aportar la contribución de plugin themes mediante el contrato público.
- Desarrollo: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Autoridad:
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
Aportar la contribución de plugin fonts mediante el contrato público.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad:
ui:themes
Declaración del manifest
contributions:syncTransports
Aportar la contribución de plugin syncTransports mediante el contrato público.
- Desarrollo: v2.0.0
- ReadAware 0.6.12: v2.0.0
- Autoridad:
sync:transport
ctx.contributions.syncTransports.register(transport: PluginSyncTransport): PluginDisposable
Servicios
services:storage
Usar KV privado y colecciones de documentos, páginas, observaciones, commits condicionales y cuotas.
- Desarrollo: v2.6.0
- ReadAware 0.6.12: v2.6.0
- Autoridad: ninguno
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
Leer y escribir credenciales en slots cifrados privados del plugin.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
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
Publicar vistas, mostrar toasts, guardar o abrir recursos, navegar espacios de trabajo y comandos, y controlar paneles y ventanas compatibles.
- Desarrollo: v1.18.0
- ReadAware 0.6.12: v1.18.0
- Autoridad: ninguno
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
Vincular handlers recurrentes declarados, inspeccionar y controlar horarios y gestionar solicitudes diferidas propias.
- Desarrollo: v2.1.0
- ReadAware 0.6.12: v2.1.0
- Autoridad: ninguno
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
Iniciar, inspeccionar y controlar planes duraderos construidos con operaciones compatibles del host.
- Desarrollo: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Autoridad: ninguno
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
Abrir y leer cursores de cambios acotados que pueden persistir entre reinicios.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
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
Previsualizar y confirmar cambios locales compatibles, inspeccionar recibos y previsualizar deshacer condicional.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
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
Leer metadatos del entorno y comprobar la disponibilidad de operaciones compatibles.
- Desarrollo: v2.18.0
- ReadAware 0.6.12: v2.18.0
- Autoridad: ninguno
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
Inspeccionar plugins y registros instalados, observar cambios y descubrir o llamar servicios tipados de plugins.
- Desarrollo: v1.10.0
- ReadAware 0.6.12: v1.10.0
- Autoridad: ninguno
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
Inspeccionar el estado de mantenimiento y entrar en flujos de copia de seguridad, prueba de conexión, actualización o configuración del host.
- Desarrollo: v1.5.0
- ReadAware 0.6.12: v1.5.0
- Autoridad: ninguno
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
Solicitar exportaciones o flujos de informes de diagnóstico compatibles.
- Desarrollo: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Autoridad:
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
Escribir eventos de desarrollo estructurados y acotados e inspeccionar la política de registro.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
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
Elegir archivos y directorios, leer o crear recursos sellados, exportar datos y guardar activos binarios privados.
- Desarrollo: v1.6.0
- ReadAware 0.6.12: v1.6.0
- Autoridad: ninguno
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
Observar el estado y la cola de sincronización, solicitar sincronización y entrar en flujos de cuenta o conexión gestionados por el host.
- Desarrollo: v1.2.0
- ReadAware 0.6.12: v1.2.0
- Autoridad:
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
Realizar solicitudes HTTP con origen acotado o leer streams limitados, con reintentos seguros opcionales.
- Desarrollo: v2.2.0
- ReadAware 0.6.12: v2.2.0
- Autoridad:
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
Solicitar inferencia de texto, estructurada o en streaming, usar recursos de imagen sellados y seguir metadatos y presupuestos.
- Desarrollo: v1.6.0
- ReadAware 0.6.12: v1.6.0
- Autoridad:
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
Escribir texto o una imagen sellada compatible en el portapapeles del sistema.
- Desarrollo: v1.1.0
- ReadAware 0.6.12: v1.1.0
- Autoridad:
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>
Esquemas
schemas:views
Describir listas, formularios, detalles, markdown y diseños de bloques renderizados por el host.
- Desarrollo: v1.12.0
- ReadAware 0.6.12: v1.12.0
- Autoridad: ninguno
Declaración del manifest
schemas:settings
Declarar configuraciones tipadas de plugin, campos condicionales y referencias a opciones dinámicas.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad: ninguno
Declaración del manifest
schemas:themes
Describir paletas semánticas de la aplicación y del lector.
- Desarrollo: v1.0.0
- ReadAware 0.6.12: v1.0.0
- Autoridad:
ui:themes
Declaración del manifest