3lc-compute-plugin-sdk 0.2.3__tar.gz → 0.3.0__tar.gz

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: release
     permissions:
-      contents: read
+      contents: write # create the GitHub Release (step below)
       id-token: write # OIDC token for PyPI Trusted Publishing
     steps:
       - uses: actions/checkout@v4
@@ -53,6 +53,32 @@ jobs:
       - name: Publish to PyPI
         run: uv publish --trusted-publishing always
 
+      # Publish the tagged version's changelog section as a GitHub Release (curated notes,
+      # not GitHub's commit list). The Release stays editable after publish for touch-up.
+      - name: Extract changelog section
+        id: changelog
+        run: |
+          VER="${GITHUB_REF_NAME#v}"
+          awk -v v="$VER" '$0 ~ "^## \\[" v "\\]" {f=1; next} /^## \[/ && f {exit} f' \
+            CHANGELOG.md > notes.md
+          echo "ver=$VER" >> "$GITHUB_OUTPUT"
+          { echo "notes<<EOF"; cat notes.md; echo EOF; } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body: |
+            ${{ steps.changelog.outputs.notes }}
+
+            ## Installation
+            ```bash
+            pip install 3lc-compute-plugin-sdk==${{ steps.changelog.outputs.ver }}
+            ```
+          draft: false
+          generate_release_notes: false
+
   # Manual (workflow_dispatch) runs → build-numbered prereleases to the legacy CloudRepo index.
   publish-cloudrepo-prerelease:
     if: github.event_name == 'workflow_dispatch'

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/CHANGELOG.md

@@ -9,6 +9,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing yet.
 
+## [0.3.0] - 2026-08-25
+
+A coordinated contract wave: breaking **for plugin authors** but **not on the wire** — the
+worker→host NDJSON events are unchanged, so a host keeps running a plugin venv still on 0.2.x
+(skew badge only). The whole first-party fleet re-pins `>=0.3.0,<0.4.0` in the same release.
+
+### Added
+- `JobContext.fail(message)` raises `JobFailed` (exported from `tlc_plugin_sdk`); the worker
+  reports it as the terminal `error` event with the **bare** message, while any other exception
+  keeps its `TypeName: …` prefix.
+- `PluginJobs.list(pluginId?)` — `GET {compute}/api/plugins/jobs`, filtered client-side by
+  `plugin_id`. Use it to **seed a fragment on mount** from the durable host job list (the
+  fragment is torn down on navigation and `job_update` is live-only). Declared in the `.d.ts`.
+- `PluginJobs.connect(namespace)` — warm the namespace socket on mount. `track()`/`on()`
+  connect lazily and SocketIO does not replay events to a not-yet-connected client, so a
+  fragment listening for custom events from the first second (or re-attaching to a job it did
+  not start) calls this first; `run()` already connects for you.
+- The host's `/ui` handler now **auto-injects** the `PluginJobs` client into every fragment; the
+  client is idempotent, so a plugin that still injects it by hand keeps working.
+- `ComputePlugin.compute()` ships a default (returns an error dict), so only `get_ui_fragment()`
+  stays abstract.
+- `.d.ts` truth pass: `PluginJobUpdate.error`, `PluginFetchOptions.allowErrorStatus`,
+  `PluginJobsApi.list`, `TlcLocationApi.rowsSpanLocations`/`shortLabel`, and a new
+  **Legacy globals** ambient block (`openTablePicker`/`closeTablePicker`/`CancelJob`/`cssVar`
+  and the injected `_tlc*` helpers).
+
+### Changed
+- **One contract axis.** `PY_CONTRACT` and `JS_CONTRACT` are removed; `SDK_CONTRACT_VERSION`
+  (the package version) is the whole contract, compared on `MAJOR.MINOR`. `/health` reports
+  `sdk_version` only (no `py_contract`/`js_contract`).
+- `JobContext.result` takes a **positional** `url` (`ctx.result(url)`); it opens the Open
+  button — a run *or* a table URL. The `run_url=` keyword is gone; the emitted `result` event
+  still carries `run_url` (wire unchanged).
+- `JobContext.progress` documents `percent=-1` as indeterminate.
+
+### Removed
+- `shared.modality.detect_modality_from_url` (zero users). `detect_modality_from_schema`,
+  `classify_metrics_columns`, `labels.candidate_label_paths`, and `labels.find_label_path`
+  are now internal (underscore-prefixed). Public alternatives: `detect_modality_from_table`
+  for modality; `get_label_map` / `get_label_names` / `find_label_column` for labels.
+  `classify_metrics_columns` was a plugin-specific column-name heuristic with no public
+  replacement — inline it (its one known user did).
+- The orphan `_ICON_SVG` constant; the dead `params.setdefault("url", "")` in the `/compute`
+  handler.
+
+### Migration
+- `ctx.result(run_url=x)` → `ctx.result(x)`.
+- Validation failures: raise, or `ctx.fail("message")` for a clean user-facing card.
+- Reading `tlc_plugin_sdk.PY_CONTRACT` / `JS_CONTRACT`, or a worker's `/health`
+  `py_contract`/`js_contract`: use `SDK_CONTRACT_VERSION` / `sdk_version` and compare on
+  `MAJOR.MINOR`.
+- `shared.modality.detect_modality_from_url(url)` → load the table yourself and call
+  `detect_modality_from_table(table)`. `classify_metrics_columns(columns)` → copy the
+  heuristic into your plugin.
+- A fragment that kept its own always-connected socket for custom events: switch to
+  `PluginJobs.on(namespace, event, handler)` and call `PluginJobs.connect(namespace)` on mount
+  so nothing emitted before the first `track()` is missed.
+- Fragments may delete their manual `inject_scripts(raw, job_tracker_script())` — the host
+  injects `PluginJobs` now (harmless to keep).
+- The manifest never declared the SocketIO namespace or `sdk_version`; both were dead and are
+  documented as such. The namespace is host-derived as `/<plugin-id>`.
+
 ## [0.2.3] - 2026-08-21
 
 ### Changed

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/CLAUDE.md

@@ -83,10 +83,11 @@ section is the condensed working order.
    - **Config + GPU job + SocketIO**: sam3, yolo, or timm
    - **Inline data display (no standalone page)**: `tlc_plugin_table_statistics`
    - **Action on selected resources**: `tlc_plugin_merger`
-3. Read `src/tlc_plugin_sdk/contract.py` — `ComputePlugin` is an `abc.ABC` with two abstract
-   methods (`get_ui_fragment()`, `compute()`) and an `id` attribute the host stamps from the
-   manifest. The optional hooks (`run_job`, `initialise_runtime`, `shutdown_runtime`,
-   `get_route_handlers`) ship as no-op defaults, so you override only what you need. There is
+3. Read `src/tlc_plugin_sdk/contract.py` — `ComputePlugin` is an `abc.ABC` with one abstract
+   method (`get_ui_fragment()`) and an `id` attribute the host stamps from the manifest.
+   `compute()` and the other hooks (`run_job`, `initialise_runtime`, `shutdown_runtime`,
+   `get_route_handlers`) ship as defaults (`compute()` reports that the plugin doesn't
+   implement it), so you override only what you need. There is
    no `register()` and **no** `get_active_jobs`/`cancel_job` — the host owns job listing and
    cancellation.
 4. Read `tlc_plugin_exporter`'s `plugin.toml` + `__init__.py` — the canonical manifest +
@@ -154,9 +155,11 @@ section is the condensed working order.
   form fills call `_tlcSyncAliasFromForm(prefix, projectId, folderId)`.
 
 **SocketIO** (if real-time updates are needed):
-- `socketio_namespace` is optional — it defaults to `/<plugin-id>`, which the host
-  auto-registers at startup; declare it in `[runtime]` only to override.
-- Prefer the `window.PluginJobs` client over a hand-rolled socket.
+- The namespace is host-derived as `/<plugin-id>` and auto-registered at startup; the manifest
+  does not (and never did) declare it.
+- Prefer the `window.PluginJobs` client over a hand-rolled socket. It connects a namespace
+  lazily; call `PluginJobs.connect('/<plugin-id>')` on mount if the fragment needs custom
+  events from the first second (`run()` connects for you).
 - Use `ctx.emit(name, payload)` only for telemetry the generic schema can't express
   (e.g. a loss curve); never re-emit the generic lifecycle by hand.
 

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 3lc-compute-plugin-sdk
-Version: 0.2.3
+Version: 0.3.0
 Summary: Public Python SDK for building 3LC compute-service plugins.
 Project-URL: Homepage, https://github.com/3lc-ai/3lc-compute-plugin-sdk
 Project-URL: Repository, https://github.com/3lc-ai/3lc-compute-plugin-sdk
@@ -44,9 +44,10 @@ pip install 3lc-compute-plugin-sdk          # import name: tlc_plugin_sdk
 
 ## What it gives you
 
-- **`ComputePlugin`** — the base class you subclass. Implement `compute` / `get_ui_fragment`;
-  job and lifecycle hooks ship as no-op defaults. There is no `register()` to call — a plugin's
-  metadata lives in its `[tool.tlc-compute]` manifest, and the Hub discovers it from there.
+- **`ComputePlugin`** — the base class you subclass. Implement `get_ui_fragment` (and `compute`
+  if you expose a synchronous endpoint); job and lifecycle hooks ship as safe defaults. There is
+  no `register()` to call — a plugin's metadata lives in its `plugin.toml` manifest (or a
+  `[tool.tlc-compute]` table in `pyproject.toml`), and the Hub discovers it from there.
 - **`JobContext`** — the surface a long-running job programs against: `progress` / `metric` /
   `log` / `result` for the generic job panel, `emit` for your plugin's own rich UI, and
   cooperative `cancelled`.
@@ -63,10 +64,10 @@ format, custom routes, the job model, UI fragment, checklist).
 
 ## The contract version
 
-`tlc_plugin_sdk.SDK_CONTRACT_VERSION` is this package's own version — one source of truth.
-A plugin pins the SDK (`3lc-compute-plugin-sdk>=X,<Y`) and declares the contract it targets via its
-manifest. The compute service implements a contract range, and the SDK version is the shared
-reference both sides agree on. Versions are SemVer; see **Status** below for the 0.x stability
+`tlc_plugin_sdk.SDK_CONTRACT_VERSION` is this package's own version — one source of truth, one
+contract axis (both the Python and the browser surface). A plugin pins the SDK
+(`3lc-compute-plugin-sdk>=X,<Y`); the compute service and frontend implement a range and compare
+compatibility on `MAJOR.MINOR`. Versions are SemVer; see **Status** below for the 0.x stability
 stance.
 
 ## How it fits
@@ -79,7 +80,9 @@ therefore portable across service versions and runs in its own isolated environm
 
 ## Status
 
-**0.2 is the released contract line.** Within 0.x the contract evolves **additively only**:
-symbols and schemas that exist keep working, and anything breaking waits for a major bump. In
+**0.3 is the current contract line.** Within 0.x the contract still evolves — mostly additively,
+but a coordinated breaking change may land on a MINOR bump while the fleet re-pins in lockstep (0.3
+did: `JobContext.result` took a positional `url`, and the `PY_CONTRACT`/`JS_CONTRACT` axes
+collapsed into `SDK_CONTRACT_VERSION`). Anything reshaping the core still waits for a major bump. In
 the browser bridge, `PLUGIN_API.libs.io` is a stable part of the contract; the other bundled
 libs are best-effort (see the guide).

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/README.md

@@ -18,9 +18,10 @@ pip install 3lc-compute-plugin-sdk          # import name: tlc_plugin_sdk
 
 ## What it gives you
 
-- **`ComputePlugin`** — the base class you subclass. Implement `compute` / `get_ui_fragment`;
-  job and lifecycle hooks ship as no-op defaults. There is no `register()` to call — a plugin's
-  metadata lives in its `[tool.tlc-compute]` manifest, and the Hub discovers it from there.
+- **`ComputePlugin`** — the base class you subclass. Implement `get_ui_fragment` (and `compute`
+  if you expose a synchronous endpoint); job and lifecycle hooks ship as safe defaults. There is
+  no `register()` to call — a plugin's metadata lives in its `plugin.toml` manifest (or a
+  `[tool.tlc-compute]` table in `pyproject.toml`), and the Hub discovers it from there.
 - **`JobContext`** — the surface a long-running job programs against: `progress` / `metric` /
   `log` / `result` for the generic job panel, `emit` for your plugin's own rich UI, and
   cooperative `cancelled`.
@@ -37,10 +38,10 @@ format, custom routes, the job model, UI fragment, checklist).
 
 ## The contract version
 
-`tlc_plugin_sdk.SDK_CONTRACT_VERSION` is this package's own version — one source of truth.
-A plugin pins the SDK (`3lc-compute-plugin-sdk>=X,<Y`) and declares the contract it targets via its
-manifest. The compute service implements a contract range, and the SDK version is the shared
-reference both sides agree on. Versions are SemVer; see **Status** below for the 0.x stability
+`tlc_plugin_sdk.SDK_CONTRACT_VERSION` is this package's own version — one source of truth, one
+contract axis (both the Python and the browser surface). A plugin pins the SDK
+(`3lc-compute-plugin-sdk>=X,<Y`); the compute service and frontend implement a range and compare
+compatibility on `MAJOR.MINOR`. Versions are SemVer; see **Status** below for the 0.x stability
 stance.
 
 ## How it fits
@@ -53,7 +54,9 @@ therefore portable across service versions and runs in its own isolated environm
 
 ## Status
 
-**0.2 is the released contract line.** Within 0.x the contract evolves **additively only**:
-symbols and schemas that exist keep working, and anything breaking waits for a major bump. In
+**0.3 is the current contract line.** Within 0.x the contract still evolves — mostly additively,
+but a coordinated breaking change may land on a MINOR bump while the fleet re-pins in lockstep (0.3
+did: `JobContext.result` took a positional `url`, and the `PY_CONTRACT`/`JS_CONTRACT` axes
+collapsed into `SDK_CONTRACT_VERSION`). Anything reshaping the core still waits for a major bump. In
 the browser bridge, `PLUGIN_API.libs.io` is a stable part of the contract; the other bundled
 libs are best-effort (see the guide).

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/docs/api.md

@@ -13,29 +13,23 @@ package's own docstrings.
    :members:
 
 .. autodata:: tlc_plugin_sdk.SDK_CONTRACT_VERSION
-
-.. autodata:: tlc_plugin_sdk.PY_CONTRACT
-
-.. autodata:: tlc_plugin_sdk.JS_CONTRACT
 ```
 
-`SDK_CONTRACT_VERSION` is the wheel/SemVer — the dependency *pin* a plugin resolves
-against (`3lc-compute-plugin-sdk>=X,<Y`). `PY_CONTRACT` and `JS_CONTRACT` are finer-grained
-**capability markers** for runtime feature-detection: `PY_CONTRACT` covers the Python
-surface (`ComputePlugin` / `JobContext`), `JS_CONTRACT` the browser surface
+`SDK_CONTRACT_VERSION` is the one contract axis: this package's own version — the
+dependency *pin* a plugin resolves against (`3lc-compute-plugin-sdk>=X,<Y`) and the version
+of both the Python surface (`ComputePlugin` / `JobContext`) and the browser surface
 (`PLUGIN_API` / `PluginJobs` / `TlcData`, declared in
-`tlc_plugin_sdk/contract/plugin-api.d.ts`). Both increment independently and are always
-`<=` the package version. See `docs/plugin-guide.md` → "Two version axes".
+`tlc_plugin_sdk/contract/plugin-api.d.ts`). The host and frontend implement a range and
+compare compatibility on `MAJOR.MINOR`. See `docs/plugin-guide.md` → "Version & Compatibility".
 
 The `.d.ts` ships in the wheel at
 `<site-packages>/tlc_plugin_sdk/contract/plugin-api.d.ts`; a plain-JS `ui.html` references
 it with `/// <reference types="3lc-compute-plugin-sdk/contract/plugin-api" />`.
 
-## The browser contract (`JS_CONTRACT`)
+## The browser contract
 
 The browser surface a plugin's `ui.html` programs against — `PLUGIN_API`, `PluginJobs`,
-and the `TlcData` helper — is declared in `plugin-api.d.ts`, the source of truth for
-`JS_CONTRACT`.
+and the `TlcData` helper — is declared in `plugin-api.d.ts`.
 
 ```{eval-rst}
 .. automodule documents every exported symbol in the file, so new contract

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/docs/plugin-guide.md

@@ -36,7 +36,7 @@ Browser                         Compute Service (port 5020)
                                │  │  + ComputePlugin subclass││
                                │  │  ComputePlugin (ABC)     ││
                                │  │  ├── get_ui_fragment()   ││ ← abstract
-                               │  │  ├── compute()           ││ ← abstract
+                               │  │  ├── compute()           ││ ← override (default)
                                │  │  ├── id                  ││ ← host-stamped
                                │  │  ├── run_job(ctx)        ││ ← override (default)
                                │  │  └── get_route_handlers()││ ← override (default)
@@ -106,7 +106,7 @@ description = "Analyzes table data quality."
 version = "1.0.0"
 min_service_version = "0.1.0"       # Minimum compute service version required
 icon = "🔍"                         # Fallback emoji
-# 16x16 SVG, inline in the manifest (no _ICON_SVG import anymore):
+# 16x16 SVG, inline in the manifest:
 icon_svg = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="8" cy="8" r="5"/><path d="M12 12l3 3"/></svg>'
 
 [ui]
@@ -126,12 +126,21 @@ isolation = "venv"                  # "venv" is the only value (and the default
 entrypoint = "tlc_plugin_my_plugin:MyPlugin"  # "pkg.module:ClassName"
 requires_gpu = false                # drives GPU vs CPU classification
 provision_extra = "my-plugin"       # umbrella extra the host provisions: `uv sync --extra <this>`
-# Optional SocketIO namespace for real-time updates. Defaults to "/<plugin-id>";
-# declare it only to override (the host registers it at startup so a UI can connect;
-# declaring it does NOT mean emitting custom events):
-# socketio_namespace = "/my-plugin"
+# The plugin's SocketIO namespace is host-derived as "/<plugin-id>" and registered at
+# startup — it is NOT declarable in the manifest (a plugin emits via ctx; the host owns
+# the transport).
 ```
 
+**Other keys the host reads** (all optional, read without importing the plugin):
+
+- `[runtime]`: `auth_exempt_paths` (relative subpaths served without auth, scoped to the
+  plugin's own subtree), `training` (marks a training plugin), `python` / `venv_python`
+  (pin the interpreter the plugin's venv is built with).
+- `[ui]`: `min_input_count` (minimum selected resources an `action` plugin needs — defaults to
+  `len(input_types)`; set `0` explicitly to require none), `action_param_names` (query params
+  passed through from the action launch), `quick_action_label` / `quick_action_description`
+  (dashboard quick-action copy).
+
 `runtime.provision_extra` is **required for every plugin distributed through an umbrella**:
 it names the extra the host installs with `uv sync --extra <that-value>`. For first-party
 plugins this is a per-plugin extra in the `3lc-compute-plugins` umbrella `pyproject.toml`.
@@ -145,11 +154,12 @@ on the CPU queue. Both are host-owned; the plugin never picks a queue or names a
 ### 3. Implement the plugin object
 
 A plugin is a **subclass of `ComputePlugin`** (imported from `tlc_plugin_sdk`) —
-there is no `register()` call. You must implement the two abstract methods,
-`get_ui_fragment()` and `compute()`; `id` is hydrated onto the instance from the manifest
-by the host. Optional behavior (custom routes, jobs, lifecycle hooks) ships as no-op
-defaults on the base, so you override only what you need and the host calls every hook
-directly.
+there is no `register()` call. You must implement the one abstract method,
+`get_ui_fragment()`; `id` is hydrated onto the instance from the manifest by the host.
+Everything else — `compute()`, custom routes, jobs, lifecycle hooks — ships as a safe
+default on the base, so you override only what you need and the host calls every hook
+directly. (`compute()`'s default returns an error dict; implement it only if you expose a
+synchronous `GET /compute` endpoint.)
 
 ```python
 """My Plugin — does something useful with tables."""
@@ -299,10 +309,10 @@ startup.
 > var API = window.PLUGIN_API;   // now typed
 > ```
 >
-> That file is the source of truth for **`JS_CONTRACT` (0.1)** — the browser-side contract.
-> The 3LC Hub frontend **implements** `PLUGIN_API` when it mounts a fragment;
-> `window.PluginJobs` **ships from this package** (it is layered on top of the bridge, not
-> part of it). See "Two version axes" below.
+> That file declares the browser-side contract — versioned by the single
+> `SDK_CONTRACT_VERSION` (see "Version & Compatibility" below). The 3LC Hub frontend
+> **implements** `PLUGIN_API` when it mounts a fragment; `window.PluginJobs` **ships from this
+> package** (auto-injected by the host, layered on top of the bridge, not part of it).
 
 ### How a fragment reaches the browser
 
@@ -351,7 +361,7 @@ PLUGIN_API = {
   objects: TlcApi.objectService,      // Object service methods
   authFetch: TlcApi.authFetch,        // fetch() with auth headers
   data: TlcData,                      // Cached data (projects, tables, runs)
-  location: TlcLocation,              // Location renderers (chips/labels for project roots) — JS_CONTRACT 0.2
+  location: TlcLocation,              // Location renderers (chips/labels for project roots) — SDK 0.2+
 
   computeFetch: TlcApi.computeFetch,  // authFetch joined to the compute-service base URL
 
@@ -388,7 +398,7 @@ PLUGIN_API = {
 - **`compute` / `objects` / `data` / `computeFetch` / `navigate` / `getIcon` / `container`** are
   part of the declared surface but rarely used directly by `ui.html` (plugins reach data through
   `authFetch`); they are documented in the `.d.ts` for completeness.
-- **`location`** (JS_CONTRACT 0.2) exposes the host's shared location renderers (`TlcLocationApi`):
+- **`location`** (SDK 0.2+) exposes the host's shared location renderers (`TlcLocationApi`):
   chips and labels for the project roots / scan URLs that tables, runs, and projects from
   `PLUGIN_API.data` resolve to (their `location` / `locations` fields, also 0.2). Every renderer
   returns `''` on single-root installs, so output can be concatenated unconditionally. Feature-detect
@@ -473,7 +483,7 @@ isolation = "venv"
 entrypoint = "tlc_plugin_my_gpu_plugin:MyGpuPlugin"
 requires_gpu = true                 # → routed through the shared GPU queue (1 at a time)
 provision_extra = "my-gpu-plugin"   # venv deps installed via `uv sync --extra <this>`
-# socketio_namespace defaults to "/my-gpu-plugin"; declare only to override
+# SocketIO namespace is host-derived as "/my-gpu-plugin" — not declarable here
 ```
 
 GPU jobs are serialized — only one runs at a time across every GPU plugin (YOLO, SAM3,
@@ -498,8 +508,9 @@ class MyGpuPlugin(ComputePlugin):
             ctx.progress(percent=100 * i / n, label=f"batch {i}/{n}")
             ctx.metric("loss", 0.042)             # key/value card on the generic panel
 
-        ctx.result(run_url=created_table_url)     # the one "open result" link
-        # Raise to fail the job — the host records the error and ends the stream.
+        ctx.result(created_table_url)             # the one "open result" link (run or table URL)
+        # Raise to fail the job (or ctx.fail("message") for a clean, user-facing message) —
+        # the host records the error and ends the stream.
 ```
 
 `JobContext` surface:
@@ -513,7 +524,8 @@ class MyGpuPlugin(ComputePlugin):
 | `ctx.progress(*, percent, label="", timing=None)` | Generic progress bar. `percent=-1` = indeterminate. `timing` = `{elapsed_s, eta_s, avg_step_s, step_label}`. |
 | `ctx.metric(label, value)` | Scalar metric card on the generic panel. |
 | `ctx.log(message)` | A log line for the job. |
-| `ctx.result(*, run_url)` | The canonical result link (last write wins). |
+| `ctx.result(url)` | The canonical result link the Open button opens — a run *or* a table URL (last write wins). |
+| `ctx.fail(message)` | Fail the job with a clean, user-facing message (raises `JobFailed`; reported verbatim, no type prefix). |
 | `ctx.emit(name, payload)` | A **custom** event for the plugin's OWN rich UI (see below). |
 
 **The host owns listing and cancellation — there is nothing to implement.** Because the
@@ -539,21 +551,21 @@ can be a second consumer of that same channel for a richer, tailored view — it
 bespoke events** for the generic lifecycle (queued → running → done, %, result link,
 metrics).
 
-**The `window.PluginJobs` client** is a global the plugin injects into its fragment in
-`get_ui_fragment()`, exactly like `alias_ui_script()` — pass `job_tracker_script()` (from
-`tlc_plugin_sdk.shared.job_tracker`) to `inject_scripts(raw, job_tracker_script())`
-(see `importer/__init__.py`). It starts a job and tracks it over the generic channel:
+**The `window.PluginJobs` client** is a global the **host auto-injects** into every fragment
+(its `/ui` handler prepends `job_tracker_script()`), so you can call it directly — no manual
+injection needed. It is idempotent (`if (window.PluginJobs) return;`), so an older plugin that
+still injects it by hand via `inject_scripts(raw, job_tracker_script())` keeps working. It
+starts a job and tracks it over the generic channel:
 
 ```javascript
-// The host registers the namespace automatically (default "/<plugin-id>");
-// declare socketio_namespace in plugin.toml only to override it.
+// The host registers the namespace automatically as "/<plugin-id>".
 PluginJobs.run('my-plugin', { table_url: url }, {
   onUpdate: function (job) {
     // generic schema: job.status, job.progress.percent/label, job.metrics[]
     setProgress(job.progress.percent, job.progress.label);
   },
   onDone: function (job) { showResult(job.run_url); },
-  onError: function (job) { showError(job.subtitle); },  // failure message rides subtitle
+  onError: function (job) { showError(job.error); },  // failure message on job.error
 });
 ```
 
@@ -562,6 +574,12 @@ the client subscribing still delivers its terminal event. (`PluginJobs.start/tra
 are the lower-level pieces.) The separate frontend's generic panel polls the same schema
 independently.
 
+One timing rule to know: `track()` and `on()` open the namespace socket **lazily**, on first
+use, and SocketIO does not replay server→client events to a client that was not yet
+connected. `run()` connects before it posts, so the common path is safe — but a fragment that
+listens for custom events from the first second, or re-attaches to a job it did not start
+(seed-on-mount), should warm the socket on mount: `PluginJobs.connect('/my-plugin')`.
+
 **Custom events** — `ctx.emit(name, payload)` is reserved for telemetry the generic schema
 **can't** express (e.g. a training plugin's per-epoch loss curve). The host relays it
 verbatim on the plugin's namespace; the generic panel ignores it. The name `job_update` is
@@ -585,6 +603,38 @@ socket.on('epoch_metrics', function (d) { lossChart.push(d.epoch, d.loss); });
 
 ---
 
+## The job page is a launcher — the Queue is the durable view
+
+A plugin fragment is **torn down on navigation**: the host remounts it via `innerHTML`, so
+its JS state and any live SocketIO subscription are gone the moment the user leaves and comes
+back. The generic **Queue & Progress** panel is the opposite — it is host-owned, polls
+`GET /api/plugins/jobs`, and survives navigation. So treat your fragment as the place a job is
+*launched and configured*, and the generic Queue card as the place a job is *watched*.
+
+Two obligations follow:
+
+**1. Seed on mount from the durable job list.** `job_update` is live-only — a long job already
+running when the fragment remounts has no event to catch until it next progresses, so the
+fragment would show an empty form over a job that is very much alive. On mount, ask the host
+what's running and render a compact running-state instead:
+
+```js
+PluginJobs.list('<id>').then(function (jobs) {
+  var live = jobs.filter(function (j) { return j.status === 'queued' || j.status === 'running'; });
+  if (live.length) renderRunningState(live[0]);   // compact "job running — watch it in the Queue"
+});
+```
+
+**2. Keep the generic card meaningful.** If you emit custom progress for your own rich UI
+(`ctx.emit`), keep `ctx.progress(percent, label, timing)` current *too* — the generic card is
+the durable view, and a job that only drives a custom channel looks stalled there. Report the
+one result the Open button opens with **`ctx.result(url)`** (a run or a table URL), and report
+failures by **raising** (or `ctx.fail("message")` for a clean, user-facing message — it lands
+on the card's `error`, without a `TypeError:`-style prefix). That is all the generic Queue
+needs to render a good, navigation-proof view.
+
+---
+
 ## CSS Conventions
 
 Plugin UI fragments inherit all CSS from `main.css` (via `base.html`) and `plugin-common.css` (via `plugin_host.html`). Use these shared patterns:
@@ -758,24 +808,21 @@ plugins are unaffected either way.
 
 All versions use **SemVer** (`MAJOR.MINOR.PATCH`).
 
-### Two version axes — never conflate them
+### Two kinds of version — never conflate them
 
 There are **two independent** kinds of "version" in play. Keep them separate:
 
-**(a) CONTRACT capability — what a plugin *programs against*.** Pinned at build/install time
-via the `3lc-compute-plugin-sdk` dependency. The SDK exposes three constants in `tlc_plugin_sdk`:
+**(a) CONTRACT — what a plugin *programs against*.** Pinned at build/install time via the
+`3lc-compute-plugin-sdk` dependency. There is **one contract axis**, `tlc_plugin_sdk.SDK_CONTRACT_VERSION`:
 
 | Constant | Covers | Value |
 |----------|--------|-------|
-| `SDK_CONTRACT_VERSION` | the wheel/SemVer — the actual dependency *pin* (`3lc-compute-plugin-sdk>=X,<Y`) | = package version (`0.1.0`) |
-| `PY_CONTRACT` | the Python surface: `ComputePlugin` / `JobContext` / `shared.*` | `0.1` |
-| `JS_CONTRACT` | the browser surface: `PLUGIN_API` / `PluginJobs` / `TlcData` (see `plugin-api.d.ts`) | `0.1` |
-
-`PY_CONTRACT` and `JS_CONTRACT` are **feature-detection markers** that increment *independently*
-as features are added to one side without the other. Both are always `<=` the package version (a
-capability can only exist in a shipped wheel). **Bump the package version when *either* moves.**
-A plugin that needs a newer capability raises its `3lc-compute-plugin-sdk` floor; it can also
-feature-detect at runtime by reading `tlc_plugin_sdk.PY_CONTRACT` / `JS_CONTRACT`.
+| `SDK_CONTRACT_VERSION` | the whole contract — the Python surface (`ComputePlugin` / `JobContext` / `shared.*`) *and* the browser surface (`PLUGIN_API` / `PluginJobs` / `TlcData`, see `plugin-api.d.ts`); also the dependency *pin* (`3lc-compute-plugin-sdk>=X,<Y`) | = package version (e.g. `0.3.0`) |
+
+It is this package's own version — one source of truth. A plugin that needs a newer capability
+raises its `3lc-compute-plugin-sdk` floor; the host and frontend implement a range and compare
+compatibility on `MAJOR.MINOR`. (Earlier 0.x lines split this into separate `PY_CONTRACT` /
+`JS_CONTRACT` markers; those were removed in 0.3 — there is one axis now.)
 
 **(b) SERVICE compatibility — what a plugin *runs against*.** Negotiated at *runtime*, not pinned.
 The compute-service and frontend version independently (separate repos); a plugin declares floors

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/pyproject.toml

@@ -7,7 +7,7 @@ name = "3lc-compute-plugin-sdk"
 # The plugin-contract (ABI) version. This IS tlc_plugin_sdk.SDK_CONTRACT_VERSION
 # (read back via importlib.metadata) — one source of truth. SemVer MAJOR.MINOR.PATCH;
 # the 0.x line is additive-only (see README → Status).
-version = "0.2.3"
+version = "0.3.0"
 description = "Public Python SDK for building 3LC compute-service plugins."
 requires-python = ">=3.10"
 readme = "README.md"

3lc_compute_plugin_sdk-0.3.0/src/tlc_plugin_sdk/__init__.py

@@ -0,0 +1,42 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Import-light plugin SDK — the contract surface a plugin programs against.
+
+This is the public import path for the plugin contract. Importing it must **not**
+pull in the heavy server stack (litestar, python-socketio, uvicorn, the queues,
+discovery): a ``venv``-mode plugin installs only this surface, not the full
+service. The ``tests/test_import_light.py`` test enforces the boundary.
+
+A plugin subclasses :class:`ComputePlugin` and implements at least
+``compute``/``get_ui_fragment``; the optional job/lifecycle hooks ship as no-op
+defaults. There is no ``register()`` to call — metadata lives in the plugin
+manifest, and the host discovers the plugin via its manifest ``entrypoint``.
+
+The contract is **defined here**, in :mod:`tlc_plugin_sdk.contract`, so it lives
+next to :class:`JobContext` and the venv worker on the import-light side of the SDK
+boundary — nothing in this package pulls in the server stack. This is the standalone
+public ``3lc-compute-plugin-sdk`` distribution: the light base a venv plugin installs (the
+host ``3lc-compute`` depends on it, never the reverse). See ``CLAUDE.md``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from tlc_plugin_sdk.contract import ComputePlugin
+from tlc_plugin_sdk.job_context import JobContext, JobFailed
+
+# The plugin contract version — one axis, one source of truth: this package's own
+# version (the ``[project] version`` in pyproject), read via importlib.metadata rather
+# than a separately maintained constant. It IS the contract a plugin programs against —
+# both the Python surface (``ComputePlugin`` / ``JobContext`` / ``shared.*``) and the
+# browser surface (``PLUGIN_API`` / ``PluginJobs`` / ``TlcData``, declared in
+# ``contract/plugin-api.d.ts``) — and the thing a plugin pins (``>=X,<Y``). The host and
+# frontend implement a range and compare compatibility on ``MAJOR.MINOR``.
+try:
+    SDK_CONTRACT_VERSION = _pkg_version("3lc-compute-plugin-sdk")
+except PackageNotFoundError:  # running from a raw checkout that was never installed
+    SDK_CONTRACT_VERSION = "0.0.0"
+
+__all__ = ["SDK_CONTRACT_VERSION", "ComputePlugin", "JobContext", "JobFailed"]

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.0}/src/tlc_plugin_sdk/asgi_app.py

@@ -26,6 +26,9 @@ from typing import TYPE_CHECKING, Any
 
 from litestar import Litestar, Request, get
 
+from tlc_plugin_sdk.shared.job_tracker import JOB_TRACKER_JS
+from tlc_plugin_sdk.shared.ui_inject import inject_scripts
+
 if TYPE_CHECKING:
     from litestar.handlers import BaseRouteHandler
 
@@ -37,31 +40,36 @@ def _generic_handlers(plugin: ComputePlugin) -> list[BaseRouteHandler]:
 
     @get("/health", sync_to_thread=False)
     def health() -> dict[str, Any]:
-        # The version fields are the worker half of a handshake: a venv worker imports its
+        # ``sdk_version`` is the worker half of a handshake: a venv worker imports its
         # *own* install of this SDK, so the host cannot know which contract is live inside
-        # the venv unless the worker says so. The host compares them against its own and
-        # flags skew on the plugin card. Reported from the same constants a plugin
-        # feature-detects against, so worker and plugin can never disagree.
-        from tlc_plugin_sdk import JS_CONTRACT, PY_CONTRACT, SDK_CONTRACT_VERSION
+        # the venv unless the worker says so. The host compares it against its own on
+        # MAJOR.MINOR and flags skew on the plugin card. One contract axis, one field.
+        from tlc_plugin_sdk import SDK_CONTRACT_VERSION
 
         return {
             "ok": True,
             "plugin": getattr(plugin, "id", "?"),
             "sdk_version": SDK_CONTRACT_VERSION,
-            "py_contract": PY_CONTRACT,
-            "js_contract": JS_CONTRACT,
         }
 
     # def + sync_to_thread: get_ui_fragment()/compute() are synchronous and may do
     # blocking work, so Litestar runs them in a threadpool, off the event loop.
     @get("/ui", media_type="text/html", sync_to_thread=True)
     def ui() -> str:
-        return plugin.get_ui_fragment()
+        # Auto-inject the PluginJobs client so every fragment can drive the generic job
+        # channel without a manual inject_scripts() call. The client is idempotent
+        # (``if (window.PluginJobs) return;``), so a plugin that still injects it by hand
+        # is harmless. A fragment with no inline <script> has nothing to drive PluginJobs
+        # from — inject_scripts() raises there, so serve it unchanged.
+        raw = plugin.get_ui_fragment()
+        try:
+            return inject_scripts(raw, JOB_TRACKER_JS)
+        except ValueError:
+            return raw
 
     @get("/compute", sync_to_thread=True)
     def compute(request: Request[Any, Any, Any]) -> dict[str, Any]:
         params: dict[str, Any] = dict(request.query_params)
-        params.setdefault("url", "")
         return plugin.compute(params)
 
     return [health, ui, compute]