Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

6.3 KB
Raw Blame

Third-party plugin development

Handbook · Tools and capabilities · Reading extensions

Official module wheels share DeepTutor's interpreter and version. Third-party plugins have a separate manifest, approval and lifecycle contract. Start with the runnable Learning Echo example, which declares a tool, capability, HTTP route and static page without external Python dependencies.

Manifest and registration

A package ships static deeptutor.plugin.json using schema deeptutor.plugin/v1. Read manifest.py and the example manifest for the exact fields. It declares identity/version, DeepTutor/API compatibility, permission disclosure, dependency closure and typed extensions. Unknown fields and invalid paths are rejected.

Extension Runtime contract
tool, capability Host entry-point protocol or approved managed JSON worker
loop_capability Existing shared-loop extension protocol
reading_extension Server-verified Reading context and bounded result types
visualizer Typed packaged visualizer declaration
http_route Managed worker endpoint under the host plugin namespace
frontend_page Declared static assets served with restrictive sandbox CSP
persistence_schema, app_connector Approved declaration/introspection; no general migration or connector execution API

Built-in IDs take precedence. Each extension retains its own typed protocol. Existing Python entry-point groups honor root-manifest approval when one is present; new packages should not rely on the legacy manifest-free path. Discovery reads metadata without importing third-party code. The registry distinguishes available, approval-required, enabled, disabled, incompatible, broken and deprecated state.

Installation and approval

Use deeptutor plugin --help for lifecycle commands. Managed installation accepts a local wheel or resolves a reviewed entry from the vendored catalog.json. Catalog browsing/version resolution is offline; explicit installation downloads the pinned artifact. There is no arbitrary URL installer or automatic background upgrade.

Catalog artifacts bind an HTTPS wheel URL, SHA-256, size and platform metadata. Downloads reject redirects and size/digest mismatches before pip. The local lifecycle validates the manifest from the wheel before importing code, creates a version-private environment, and installs an explicit wheel-only dependency closure. It does not mutate the host interpreter.

Approval binds the normalized manifest and artifact identity. Inspect the current snapshot before approving. Installation, upgrade, same-version reinstall and rollback clear prior approval. Approval does not automatically enable a locally disabled plugin. Failed installations preserve the previous usable state; retained versions support rollback. External host-installed plugin upgrades need restart to replace already imported Python modules.

The owner is lifecycle.py, with state under runtime data/user/settings/plugins.json. API lifecycle mutations need administrator authorization. Plugin tests cover manifest, artifact, transaction, recovery and approval boundaries.

Worker protocol and cancellation

runtime.py launches a worker module using the plugin environment's Python. Worker declarations cannot exceed the approved manifest. Legacy workers exchange one JSON request and response on stdin/stdout.

A capability can advertise "transport": "ndjson-v1" in its description. It then emits JSON lines with {"kind":"event","event":{...}}, followed by {"kind":"complete"}. Events enter the normal durable turn stream; workers do not own a parallel public stream. EOF before completion and malformed frames fail the run. Requests, frames, output, stderr and execution have bounds; queues apply backpressure. Cancellation closes the process group and waits for cleanup. The example supports both streaming and legacy modes.

HTTP and static pages

Managed HTTP routes use /api/plugins/{plugin-id}{path} and cannot replace built-in routes. The host resolves approved, enabled, compatible managed state and authenticates before starting a worker. With host authentication enabled, even a plugin route declared public requires a host session: it does not bypass the host account boundary. The admin policy adds an administrator check. Unavailable plugin routes return 404.

Workers receive declared method/path, normalized query values and a bounded JSON body, not host cookies, bearer tokens or authentication headers. Responses have validated JSON status/body and restricted Cache-Control; redirects and authentication responses belong to the host. See API tests.

A static page declares schema deeptutor.plugin-frontend-page/v1, one entry and an explicit asset closure. Only approved regular package files may be served; symlinks and undeclared assets are rejected. The canonical URL is /api/plugins/{plugin-id}/pages/{extension-id}/. Keep the trailing slash for relative assets.

Pages run in a sandboxed browser context with restrictive CSP, including connect-src 'none'; they do not inject React/Next code into the host bundle or arbitrarily fetch host APIs. See frontend.py, frontend tests, and the example page manifest.

Trust limits and validation

Permission declarations and approval are not an OS sandbox. Host entry-point extensions execute in the host interpreter; managed workers isolate Python dependencies but retain host operating-system access. Review actual packages and dependencies. Packaged browser pages have their own browser sandbox. Direct Chrome extension reuse is unsupported.

Validate the manifest, build a wheel, exercise approval/enablement, the worker and page, then disable/revoke and cancel a run. Use a disposable runtime home. See Testing and the separate Reading extension context/result rules.