[CREDO23]

Summary

• Adds surfsense_plugin_sdk in plugins/core/sdk/, with no dependencies. python -m surfsense_plugin_sdk.run <plugin-dir> <action> --inputs <file> --data <dir> loads a plugin and calls its @action function with the user's inputs. An optional input left empty arrives as None, and an undeclared or unmarked action, a missing main.py, or one action marked twice is refused by name.
• A plugin reaches its own context with secret() and data(), SurfSense with document.add/list/update (typed results, provenance stamped, the app's own messages on refusal), and the internet with http.get/post/request: declared hosts only, every redirect checked, credentials dropped across hosts, one log line per request.
• The plugin's own folder and dependencies go after the standard library on the path, and a dependency's .pth file runs. Calls to the app skip the user's proxy; calls to sources use it.
• Strict pyright over the SDK, and a test that nothing public is typed Any except Response.json(). 37 tests run real plugin folders in their own process against stub servers; the contract tests against the real backend come with the harness.
• Renames a plugin's entry to its action across the manifest rules and the proposal, and adds what running in a workspace needs: a run stays in its workspace, the screen can find it again, and deleting a workspace stops its runs first.
• Adds a check-sdk job to the plugin checks, the SDK's commands to AGENTS.md, and a docstring to every function in both packages.

Follows #2070

High-level PR Summary

This PR introduces the plugin SDK (surfsense_plugin_sdk) that enables SurfSense plugins to run within the app. The SDK provides a typed interface for plugins to access their context (secrets, data folders), communicate with SurfSense's API (document operations), and make HTTP requests to declared hosts. The protocol between the app and plugins uses a command-line interface where each plugin action runs in its own process. The PR also updates the manifest schema to rename entries to actions, implements workspace-aware plugin runs, and establishes strict type-checking requirements across all plugin code.

⏱️ Estimated Review Time: 30-90 minutes

💡 Review Order Suggestion

Order	File Path
1	docs/proposals/plugins/01-protocol.md
2	docs/proposals/plugins/02-extending.md
3	docs/proposals/plugins/03-lifecycle.md
4	docs/proposals/plugins/README.md
5	plugins/core/manifest/surfsense_plugin_manifest/manifest.py
6	plugins/core/manifest/surfsense_plugin_manifest/__init__.py
7	plugins/core/sdk/pyproject.toml
8	plugins/core/sdk/surfsense_plugin_sdk/__init__.py
9	plugins/core/sdk/surfsense_plugin_sdk/action.py
10	plugins/core/sdk/surfsense_plugin_sdk/secret.py
11	plugins/core/sdk/surfsense_plugin_sdk/data.py
12	plugins/core/sdk/surfsense_plugin_sdk/run/plugin_manifest.py
13	plugins/core/sdk/surfsense_plugin_sdk/run/current_run.py
14	plugins/core/sdk/surfsense_plugin_sdk/run/load_plugin.py
15	plugins/core/sdk/surfsense_plugin_sdk/run/call_action.py
16	plugins/core/sdk/surfsense_plugin_sdk/run/__main__.py
17	plugins/core/sdk/surfsense_plugin_sdk/http/declared_hosts.py
18	plugins/core/sdk/surfsense_plugin_sdk/http/headers.py
19	plugins/core/sdk/surfsense_plugin_sdk/http/response.py
20	plugins/core/sdk/surfsense_plugin_sdk/http/redirects.py
21	plugins/core/sdk/surfsense_plugin_sdk/http/sending.py
22	plugins/core/sdk/surfsense_plugin_sdk/http/__init__.py
23	plugins/core/sdk/surfsense_plugin_sdk/app/context.py
24	plugins/core/sdk/surfsense_plugin_sdk/app/client.py
25	plugins/core/sdk/surfsense_plugin_sdk/app/document.py
26	plugins/core/sdk/tests/conftest.py
27	plugins/core/sdk/tests/unit/test_run_command.py
28	plugins/core/sdk/tests/unit/test_secret.py
29	plugins/core/sdk/tests/unit/test_data.py
30	plugins/core/sdk/tests/unit/test_http.py
31	plugins/core/sdk/tests/unit/test_document.py
32	plugins/core/sdk/tests/unit/test_public_surface.py
33	docs/proposals/plugins/app/01-api.md
34	docs/proposals/plugins/app/02-screen.md
35	docs/proposals/plugins/python/01-interpreter.md
36	docs/proposals/plugins/runtime/01-process.md
37	docs/proposals/plugins/sdk/01-library-and-harness.md
38	docs/proposals/plugins/release/02-pull-request-checks.md
39	.github/workflows/plugins-pull-request-checks.yml
40	AGENTS.md

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: da32574f-d835-4316-9362-59e4a217345a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
surf-sense-frontend	Building	Preview	Sep 30, 2026 11:02am UTC