3lc-compute-plugin-sdk 0.3.2__tar.gz → 0.4.0__tar.gz

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/CHANGELOG.md

@@ -7,7 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-_Nothing yet._
+## [0.4.0] - 2026-09-10
+
+### Added
+- `ctx.identity`: a `JobIdentity` (`user_id`, `org_id`, `project_id` — canonical id strings,
+  `None` when the host did not know) saying who a job runs for. The host stamps it under the
+  host-owned top-level run-body key `_identity`; the worker pops it before `ctx.params` is built,
+  so a plugin never reads the key and never persists it with saved params. Every field is `None`
+  on a host that stamps nothing (an older host, or a keyless local one). Plugins read it for
+  attribution; a later credential API leases to this identity, never to a plugin.
+- Remote-worker hardening for TCP workers (opt-in; a local Unix-socket worker is unchanged):
+  - `python -m tlc_plugin_sdk.worker --token …` (default `$TLC_WORKER_TOKEN`) requires
+    `Authorization: Bearer <token>` on every HTTP route and on every websocket a plugin
+    declares (closed with 1008). `build_plugin_app(token=…)` carries the same knob. The worker
+    no longer serves generated OpenAPI/Swagger routes.
+  - `TLC_WORKER_STREAM_KEEPALIVE_S=<seconds>` makes the `/jobs/{id}/run` NDJSON stream emit
+    `{"event": "ping"}` between job events so HTTP proxies do not kill quiet streams during
+    long epochs.
+- Worker control routes `GET /busy` (`{"active_jobs": n}`) and `POST /jobs/cancel-all`. Both
+  are host-owned; plugins implement neither.
+- The worker applies the run body's top-level `_alias_overrides` around `run_job` (register
+  before, restore after), so a plugin needs no code for aliases the host re-points at staged
+  data. A plugin that applies the same overrides itself keeps working.
+- `PluginConfigStore.exists(config_id)` and `.directory`.
+- Manifest `[runtime] node_routes` documented: the custom routes that must run where the model
+  lives when a host with remote-node support runs the plugin on a remote worker; everything
+  else stays with the controller's worker. A host without that support ignores the key.
+- Run-body conventions for remote-ready plugins documented: inline `project_config`
+  (self-contained params, since a remote worker has no controller-local store), the
+  `_alias_overrides` shape, and `run_target` / `prepare_job_ids` as host-owned keys.
+- `plugin-api.d.ts`: optional `PLUGIN_API` members `getRunTarget`, `onRunTargetChange`,
+  `checkDataForRunTarget` and `hostChecksTableInputs` for frontends with remote-node support.
+  Absent elsewhere, so fragments feature-detect them.
+
+### Changed
+- A job stays registered on the worker for as long as its **thread** runs, not its event
+  stream, so a host that restarts mid-run can still cancel it. A cancel the job ignores for
+  `TLC_WORKER_CANCEL_GRACE_S` seconds (default 60; `0` disables) makes the worker exit with
+  status 3 when that job is the last live one; the supervisor spawns a fresh worker for the
+  next job.
+- Job ids must match `[A-Za-z0-9_-]{1,64}` (400 otherwise); a `/jobs/{id}/run` for an id
+  still live on the worker answers 409 rather than replacing the running job.
+- When the host's job stream disconnects the worker stops buffering that job's events (the
+  thread keeps running, cancellable), so a lost stream no longer grows memory for the rest of
+  a training run.
+- A plugin route handler on a reserved path (`/health`, `/ui`, `/compute`, `/busy`,
+  `/reclaim`, `/jobs/*`) is not mounted; the collision is logged as an error.
+- `PluginConfigStore` writes its directory `0700` and config files `0600` (they hold keys).
+
+## [0.3.3] - 2026-09-07
+
+### Changed
+- Requires `3lc>=3.3.0`. The SDK carries the `3lc[pandas]` data plane for every plugin venv, so
+  raising the floor here moves the whole plugin fleet onto the current 3lc release.
 
 ## [0.3.2] - 2026-08-31
 

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 3lc-compute-plugin-sdk
-Version: 0.3.2
+Version: 0.4.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
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: 3lc[pandas]<4.0.0,>=3.0.0
+Requires-Dist: 3lc[pandas]<4.0.0,>=3.3.0
 Requires-Dist: litestar<3.0.0,>=2.22.0
 Requires-Dist: uvicorn>=0.34.0
 Provides-Extra: shared

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/docs/api.md

@@ -12,6 +12,9 @@ package's own docstrings.
 .. autoclass:: tlc_plugin_sdk.JobContext
    :members:
 
+.. autoclass:: tlc_plugin_sdk.JobIdentity
+   :members:
+
 .. autodata:: tlc_plugin_sdk.SDK_CONTRACT_VERSION
 ```
 

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/docs/plugin-guide.md

@@ -126,6 +126,12 @@ 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"       # your plugin's dependency group: host runs `uv sync --extra <this>`
+# Custom routes that must run where the model lives when a host with remote-node support
+# runs this plugin on a remote worker (inference, model warm-up/status). Path prefixes
+# relative to your route root. Everything NOT listed stays with the controller's worker —
+# config stores, model catalogs, table reads — so saved configs have one history. A host
+# without remote-node support ignores the key.
+# node_routes = ["/preview", "/model-status"]
 # 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).
@@ -528,6 +534,7 @@ class MyGpuPlugin(ComputePlugin):
 | `ctx.params` | Job parameters (parsed request body / query). |
 | `ctx.cancelled` | `True` once cancel is requested — poll at checkpoints. |
 | `ctx.state_dir` | Writable per-plugin scratch dir (never write inside the package). |
+| `ctx.identity` | Who the job runs for: a `JobIdentity` with `user_id`, `org_id`, `project_id` (canonical id strings, or `None` when the host did not know). Read it for attribution; never set it. |
 | `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. |
@@ -543,10 +550,80 @@ The `progress` / `metric` / `result` calls above are what populate that generic
 translated to the frontend's plugin-agnostic schema by the host, so no plugin-specific
 field ever reaches the frontend.
 
+**A cancel always ends the job — poll `ctx.cancelled` so it ends cleanly.** Cancel is
+cooperative first: the worker sets `ctx.cancelled` and your loop returns at its next
+checkpoint (the host marks the job "cancelled"). A loop that never checks is not allowed
+to keep a GPU busy: after `TLC_WORKER_CANCEL_GRACE_S` seconds (default 60; `0` disables)
+the worker process exits with status 3 when the unresponsive job is the last one live in it,
+and the supervisor spawns a fresh worker for the next job — so an
+unhonoured cancel costs you the process, and any partial state you did not flush. The grace
+period includes your cleanup: flush checkpoints before you return from a cancel, not after.
+When other jobs are live in the same worker the unresponsive thread is left running (it ends
+with the process) and reported in the worker log; nothing else is interrupted.
+The worker keeps a job registered for as long as its **thread** runs, not its event
+stream: a host that restarts mid-run can still cancel the job afterwards
+(`POST /jobs/{id}/cancel`, or `POST /jobs/cancel-all` for everything still live), so a lost
+stream never leaves a training running for nobody. Job ids are chosen by the host and must
+match `[A-Za-z0-9_-]{1,64}`; a run for an id that is still live on the worker answers 409.
+
 **Start a job from the UI** with the generic run route — `POST /api/plugins/{id}/run`
 with the params as the JSON body; it returns `{job_id, status, namespace}`. The easiest
 way to consume it is `window.PluginJobs` (next section).
 
+### Run-body conventions for remote workers
+
+A host with remote-node support can run a `requires_gpu` job on a **remote worker** — a
+TCP worker on another machine — over the same stream contract. These conventions make a
+plugin remote-ready; all are optional locally and additive:
+
+- **Self-contained params (`project_config`).** A remote worker has none of the
+  controller's local state — in particular, nothing saved by a worker-local config or
+  project store exists on the node. If your `run_job` resolves an id against such a
+  store, also accept the frozen configuration inline (recommended key:
+  `project_config`) and prefer it when present; have your fragment always include it in
+  the run body (harmless locally, required remotely).
+- **`_alias_overrides` is applied by the worker.** When a table's data has been staged
+  somewhere else for this worker (a copy on a remote node), the host puts
+  `{"enabled": true, "overrides": [{"token": "MY_DATA", "path": "/staged/…"}]}` at the top
+  level of the run body (tokens are bare, no angle brackets). The worker registers those
+  aliases before `run_job` and restores them after, so the table resolves to the staged copy
+  with no code in the plugin. A plugin that persists its own alias overrides with its saved
+  config keeps applying those itself; a plugin that used to read the top-level key can drop
+  that code (applying the same override twice is a no-op).
+- **`run_target` is host-owned.** The run body may carry `run_target` (where to run); the
+  host consumes it before params reach the worker — never read or set it in a plugin. The
+  same goes for `prepare_job_ids` (the data-copy jobs a remote run waits for): the host pops
+  it, orders the run behind the copies, and delivers their result as `_alias_overrides`,
+  which the worker applies for you.
+- **`_identity` is host-owned and becomes `ctx.identity`.** The host stamps who the job runs
+  for (`{"user_id", "org_id", "project_id"}`, canonical id strings) under the top-level
+  `_identity` key; the worker pops it before `ctx.params` is built and exposes it as
+  `ctx.identity` (a `JobIdentity`; every field `None` when the host did not know it, as on a
+  keyless local host). A fragment never sets it — the host overwrites whatever the browser
+  sent — and a plugin never persists it with saved params. Read it for attribution; the
+  forthcoming credential API leases credentials to *this* identity, never to a plugin.
+- **Custom routes stay with the controller unless declared.** A host with remote-node
+  support forwards a custom route to the remote worker only if your manifest lists it under
+  `[runtime] node_routes` (e.g. sam3's `/preview`). Config/project stores, model catalogs
+  and table reads must NOT be listed: they are controller state, and the remote copy of your
+  worker starts with an empty store. Nothing to code; keep the list honest.
+- **Selection-time data notes.** A frontend with remote-node support exposes optional
+  `PLUGIN_API` members — `getRunTarget`, `onRunTargetChange`, `checkDataForRunTarget` (see
+  `plugin-api.d.ts`) — and may annotate every table input in a GPU fragment with the verdict
+  itself, announced by `PLUGIN_API.hostChecksTableInputs`; opt a field in or out with
+  `data-run-target-check="table"|"off"`. Feature-detect the members (frontends without
+  remote-node support have none of them) and call `checkDataForRunTarget` yourself only for
+  bespoke placement, skipping it when `hostChecksTableInputs` is true.
+
+Remote TCP workers run token-guarded (`--token` / `TLC_WORKER_TOKEN`: every request must
+carry `Authorization: Bearer <token>`) and may emit `{"event": "ping"}` keepalives on the
+job stream (`TLC_WORKER_STREAM_KEEPALIVE_S`) so provider proxies don't kill quiet
+streams; a host that enables keepalives filters the pings before events reach any
+consumer. Neither affects a local Unix-socket worker. Every worker also answers `GET /busy`
+(`{"active_jobs": n}`, read before a remote worker's machine is torn down) and
+`POST /jobs/cancel-all` (what a host calls after a restart it could not re-attach to);
+plugins implement neither.
+
 ---
 
 ## Real-Time Updates: `window.PluginJobs` + custom events
@@ -1027,3 +1104,21 @@ If your entry doesn't show up after that, check that the tester's compute-servic
 Agent-facing guidance for building a plugin end-to-end (reading order, step-by-step,
 code patterns, common mistakes, testing) lives in this repo's
 [`CLAUDE.md`](https://github.com/3lc-ai/3lc-compute-plugin-sdk/blob/main/CLAUDE.md).
+
+## Which 3LC project a job belongs to
+
+The Hub's project page shows a job in its **Queue & Progress** panel only when the host knows the job's
+3LC project. The host resolves it once, when the run starts, in this order — nothing comes from the browser
+address:
+
+1. `project_name` in the run body. The SDK's job starter sets it from the launch context; a plugin that knows
+   the project can set it explicitly, and an explicit value always wins.
+2. Any table or run URL in the body. The Object Service lays projects out as `…/projects/<project>/…`, so an
+   inline config with `train_table_url` names its project by itself.
+3. The plugin's saved project config. A body that carries only `project_id` refers to a record the plugin
+   serves at `GET /projects/{project_id}`; the host reads its `project_name` (the **3LC Project** field every
+   training form has). Keep that route and field if your plugin saves its configs.
+
+While the job runs, any event whose payload carries `project_name` (or a `run_url` under a project) also sets
+the project if it was still unknown. Emit `ctx.result(run_url)` as soon as the run exists and the panel
+catches up even when the start carried nothing.

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.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.3.2"
+version = "0.4.0"
 description = "Public Python SDK for building 3LC compute-service plugins."
 requires-python = ">=3.10"
 readme = "README.md"
@@ -43,7 +43,7 @@ classifiers = [
 dependencies = [
     "uvicorn>=0.34.0",
     "litestar>=2.22.0,<3.0.0",
-    "3lc[pandas]>=3.0.0,<4.0.0",
+    "3lc[pandas]>=3.3.0,<4.0.0",
 ]
 
 [project.urls]

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/src/tlc_plugin_sdk/__init__.py

@@ -25,7 +25,7 @@ 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
+from tlc_plugin_sdk.job_context import JobContext, JobFailed, JobIdentity
 
 # 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
@@ -39,4 +39,4 @@ try:
 except PackageNotFoundError:  # running from a raw checkout that was never installed
     SDK_CONTRACT_VERSION = "0.0.0"
 
-__all__ = ["SDK_CONTRACT_VERSION", "ComputePlugin", "JobContext", "JobFailed"]
+__all__ = ["SDK_CONTRACT_VERSION", "ComputePlugin", "JobContext", "JobFailed", "JobIdentity"]

3lc_compute_plugin_sdk-0.4.0/src/tlc_plugin_sdk/asgi_app.py

@@ -0,0 +1,194 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Build a plugin's HTTP surface as a Litestar ASGI app.
+
+This is the single route-authoring pattern: a plugin exposes its custom routes as
+relative Litestar route handlers via :meth:`ComputePlugin.get_route_handlers`, and
+the worker (``tlc_plugin_sdk.worker``) serves the app with uvicorn on a Unix socket
+(or TCP, for a remote worker); the host reverse-proxies to it.
+
+Because the worker runs a real Litestar app, a plugin's routes get a real router,
+request validation, multipart, and binary/streaming responses. Litestar runs
+``def`` handlers in a threadpool, so a synchronous, CPU-bound custom route (e.g.
+preview inference) does not block the event loop.
+
+The app also mounts the host-reserved generic routes (``/health``, ``/ui``,
+``/compute``) so the worker can answer them over the socket.
+
+Litestar is a base dependency of this SDK, but it is imported **here**, not in
+the import-light :mod:`tlc_plugin_sdk` package surface — so
+``import tlc_plugin_sdk`` stays cheap.
+"""
+
+from __future__ import annotations
+
+import logging
+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
+
+    from tlc_plugin_sdk.contract import ComputePlugin
+
+
+logger = logging.getLogger(__name__)
+
+
+def _generic_handlers(plugin: ComputePlugin) -> list[BaseRouteHandler]:
+    """The host-reserved generic routes, bound to ``plugin`` (served by the worker)."""
+
+    @get("/health", sync_to_thread=False)
+    def health() -> dict[str, Any]:
+        # ``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 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,
+        }
+
+    # 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:
+        # 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)
+        return plugin.compute(params)
+
+    return [health, ui, compute]
+
+
+def _bearer_guard(token: str) -> Any:
+    """An ASGI middleware factory rejecting requests without ``Authorization: Bearer <token>``.
+
+    Installed only when a token is configured — a worker on a Unix socket runs with no
+    token and never pays for this. Guards every HTTP route, ``/health`` included, and every
+    websocket a plugin declares (closed with code 1008 before accept). Callers that own the
+    token (the controller's supervisor, the node-agent) send it on probes too.
+
+    Litestar applies app middleware per matched route, so an unknown path still answers 404
+    and a wrong method 405 without the token: the guard protects content, not the route
+    table. ``lifespan`` scopes pass through.
+    """
+    import hmac
+
+    expected = f"Bearer {token}".encode()
+
+    def factory(app: Any) -> Any:
+        async def guard(scope: Any, receive: Any, send: Any) -> None:
+            kind = scope["type"]
+            if kind not in ("http", "websocket"):
+                await app(scope, receive, send)
+                return
+            auth = b""
+            for name, value in scope.get("headers", []):
+                if name == b"authorization":
+                    auth = value
+                    break
+            # Constant-time compare: a timing oracle on the token would defeat it.
+            if hmac.compare_digest(auth, expected):
+                await app(scope, receive, send)
+                return
+            if kind == "websocket":
+                # 1008 = policy violation; closing before accept makes the handshake fail.
+                await send({"type": "websocket.close", "code": 1008})
+                return
+            body = b'{"detail":"unauthorized"}'
+            await send({
+                "type": "http.response.start",
+                "status": 401,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(body)).encode()),
+                ],
+            })
+            await send({"type": "http.response.body", "body": body})
+
+        return guard
+
+    return factory
+
+
+def build_plugin_app(
+    plugin: ComputePlugin,
+    *,
+    extra_handlers: list[BaseRouteHandler] | None = None,
+    debug: bool = False,
+    token: str | None = None,
+) -> Litestar:
+    """Build the Litestar app serving ``plugin``'s HTTP surface.
+
+    Args:
+        plugin: The plugin instance whose behavior the routes invoke.
+        extra_handlers: The worker's job-channel handlers (the ``/jobs/{id}/run``
+            stream, ``/jobs/{id}/cancel``, and ``/reclaim``).
+        debug: Litestar debug flag.
+        token: When set, every request must carry ``Authorization: Bearer <token>``
+            (401 otherwise). Set for TCP workers on remote nodes; ``None`` (the
+            default) leaves local/UDS behavior untouched — no middleware installed.
+
+    Returns:
+        A Litestar app mounting, in trie-priority order: the plugin's own relative
+        route handlers (most specific), the generic reserved routes, and any
+        ``extra_handlers``.
+
+    """
+    handlers: list[Any] = [
+        *_without_reserved(plugin.get_route_handlers(), plugin),
+        *_generic_handlers(plugin),
+        *(extra_handlers or []),
+    ]
+    middleware: list[Any] = [_bearer_guard(token)] if token else []
+    # No generated OpenAPI/Swagger routes: a worker is an internal endpoint, and on a node the
+    # schema would describe the job channel to anyone who reached the port.
+    return Litestar(route_handlers=handlers, debug=debug, middleware=middleware, openapi_config=None)
+
+
+# Paths the host and the worker own. A plugin handler on one of them would shadow the
+# worker's (``/busy`` shadowed = a node-agent's self-destruct guard answers whatever the
+# plugin says). Plugins mount first for trie priority, so collisions are removed here.
+RESERVED_WORKER_PATHS: frozenset[str] = frozenset({"/health", "/ui", "/compute", "/busy", "/reclaim"})
+RESERVED_WORKER_PREFIXES: tuple[str, ...] = ("/jobs",)
+
+
+def _without_reserved(handlers: list[Any], plugin: ComputePlugin) -> list[Any]:
+    kept: list[Any] = []
+    for handler in handlers:
+        paths = {"/" + str(p).strip("/") for p in (getattr(handler, "paths", None) or ())}
+        clash = [
+            p
+            for p in paths
+            if p in RESERVED_WORKER_PATHS or any(p == r or p.startswith(r + "/") for r in RESERVED_WORKER_PREFIXES)
+        ]
+        if clash:
+            logger.error(
+                "Plugin %s declares reserved route(s) %s; the handler is not mounted (host-owned paths: %s, %s/*)",
+                getattr(plugin, "id", "?"),
+                ", ".join(sorted(clash)),
+                ", ".join(sorted(RESERVED_WORKER_PATHS)),
+                ", ".join(RESERVED_WORKER_PREFIXES),
+            )
+            continue
+        kept.append(handler)
+    return kept

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/src/tlc_plugin_sdk/contract/plugin-api.d.ts

@@ -298,6 +298,40 @@ export interface PluginApi {
    */
   computeFetch(path: string, options?: PluginFetchOptions, requiresGpu?: boolean): Promise<Response>;
 
+  /**
+   * Where jobs from this page currently execute: the host-owned "Run on:" choice.
+   * `{target: 'local', ready: true}` on hosts without remote GPU nodes, when
+   * "This machine" is selected, or on older frontends (feature-detect the member).
+   * `ready` is false while a chosen node's worker is still being prepared.
+   */
+  getRunTarget?(): { target: 'local' | 'node'; node_id?: string; ready: boolean };
+
+  /**
+   * Register a callback fired whenever the "Run on:" choice or its readiness
+   * changes — re-validate any selected data via `checkDataForRunTarget`.
+   * Listeners are cleared when the fragment unmounts.
+   */
+  onRunTargetChange?(callback: () => void): void;
+
+  /**
+   * Selection-time data verdict for the current run target: can this table work
+   * there, and what will happen to its data? `ok: false` means a node run WILL
+   * fail (e.g. rows carry local paths with no alias); `notes` are user-facing
+   * strings (upcoming copies, copy-vs-stream choices) to render next to the
+   * picker. Always `{ok: true, notes: []}` for the local target and on older
+   * hosts. Call it from the data picker's change handler — before Train.
+   */
+  checkDataForRunTarget?(tableUrl: string): Promise<{ ok: boolean; notes: string[] }>;
+
+  /**
+   * `true` when the host itself annotates every table input in the fragment with
+   * the `checkDataForRunTarget` verdict (fields whose value has a `/tables/` segment
+   * or whose id/name says "table"; `data-run-target-check="table"|"off"` opts a field
+   * in or out). A fragment that wires `checkDataForRunTarget` to its own inputs can
+   * skip that when this is set, so the note is not shown twice. Absent on older hosts.
+   */
+  hostChecksTableInputs?: boolean;
+
   /** Reference to `TlcApi.computeService` (currently only `getHealth()`). */
   compute: TlcComputeService;
 

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/src/tlc_plugin_sdk/contract.py

@@ -105,8 +105,10 @@ class ComputePlugin(ABC):
         plugin's own Litestar app in its worker, reverse-proxied by the host (see
         ``tlc_plugin_sdk/asgi_app.py``); Litestar runs ``def`` handlers in a threadpool,
         so a synchronous, blocking custom route does not block the event loop. The
-        reserved routes (``/run``, ``/health``, ``/ui``, ``/compute``, ``/jobs/*``,
-        and the host admin routes ``/provision`` ``/reload`` ``/venv`` ``/worker/stop``)
-        are host-owned — a plugin must not define them. Empty by default.
+        reserved routes (``/run``, ``/health``, ``/ui``, ``/compute``, ``/busy``,
+        ``/reclaim``, ``/jobs/*`` including ``/jobs/cancel-all``, and the host admin routes
+        ``/provision`` ``/reload`` ``/venv`` ``/worker/stop``) are host-owned — a plugin must
+        not define them; a handler on one of them is not mounted (logged as an error).
+        Empty by default.
         """
         return []

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/src/tlc_plugin_sdk/job_context.py

@@ -15,11 +15,70 @@ Import-light: stdlib only. Must not pull in the server stack.
 from __future__ import annotations
 
 import threading
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, NoReturn
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Callable, Mapping
+
+#: The host-owned top-level run-body key that carries :class:`JobIdentity` to the worker.
+#: The worker pops it before ``ctx.params`` is built; a plugin never reads or sets it.
+IDENTITY_KEY = "_identity"
+
+
+@dataclass(frozen=True)
+class JobIdentity:
+    """Who a job runs for: the tenant identity the host stamped when it started the job.
+
+    Every field is the canonical string form of the id the host's identity provider uses
+    (UUIDs in the hosted service) or ``None`` when the host did not know it — a keyless local
+    dev host knows no user, and no host knows a project id yet. Plugins read this for
+    attribution and for authorization decisions made on their behalf later (a credential
+    lease is issued to a *job's* identity, never to a plugin); they never set it.
+
+    Attributes:
+        user_id: The user who started the job.
+        org_id: The organization (tenant) the job belongs to.
+        project_id: The project the job belongs to, when the host resolved one.
+
+    """
+
+    user_id: str | None = None
+    org_id: str | None = None
+    project_id: str | None = None
+
+    @classmethod
+    def from_wire(cls, raw: object) -> JobIdentity:
+        """Build an identity from the run body's ``_identity`` value, tolerating anything.
+
+        Unknown keys are ignored and non-string values read as unknown, so a host of any
+        version can stamp whatever it knows and an old worker never fails a job over it.
+
+        Args:
+            raw: The value found under :data:`IDENTITY_KEY`, or ``None``.
+
+        Returns:
+            The identity; empty when ``raw`` is not a mapping.
+
+        """
+        if not isinstance(raw, dict):
+            return cls()
+        mapping: Mapping[str, object] = raw
+        return cls(
+            user_id=_str_or_none(mapping.get("user_id")),
+            org_id=_str_or_none(mapping.get("org_id")),
+            project_id=_str_or_none(mapping.get("project_id")),
+        )
+
+    @property
+    def known(self) -> bool:
+        """Whether the host stamped any identity at all."""
+        return any((self.user_id, self.org_id, self.project_id))
+
+
+def _str_or_none(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
 
 
 class JobFailed(Exception):
@@ -43,6 +102,7 @@ class JobContext:
             reinstall/reload (plugins must not write inside their package dir).
         sink: Callable invoked with each emitted event dict.
         cancel_event: Set by the host/worker to request cooperative cancellation.
+        identity: Who the job runs for (see :class:`JobIdentity`); empty when omitted.
 
     """
 
@@ -54,10 +114,12 @@ class JobContext:
         *,
         sink: Callable[[dict[str, Any]], None],
         cancel_event: threading.Event,
+        identity: JobIdentity | None = None,
     ) -> None:
         self.job_id = job_id
         self.params = params or {}
         self.state_dir = state_dir
+        self.identity = identity if identity is not None else JobIdentity()
         self._sink = sink
         self._cancel = cancel_event
 

{3lc_compute_plugin_sdk-0.3.2 → 3lc_compute_plugin_sdk-0.4.0}/src/tlc_plugin_sdk/shared/config_store.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import shutil
 import uuid
 from dataclasses import asdict, is_dataclass
@@ -61,7 +62,9 @@ class PluginConfigStore(Generic[T]):
             raise TypeError(msg)
         self._cls = config_cls
         self._dir = CONFIG_ROOT / plugin_id
+        # Configs hold provider keys and tokens: owner-only directory and files.
         self._dir.mkdir(parents=True, exist_ok=True)
+        _restrict(self._dir, 0o700)
         if legacy_dir is not None:
             self._migrate_legacy(Path(legacy_dir))
 
@@ -86,10 +89,17 @@ class PluginConfigStore(Generic[T]):
             config.id = str(uuid.uuid4())  # type: ignore[attr-defined]
         if not getattr(config, "created", ""):
             config.created = datetime.now(timezone.utc).isoformat()  # type: ignore[attr-defined]
-        with open(self._path(config.id), "w") as f:  # type: ignore[attr-defined]
+        path = self._path(config.id)  # type: ignore[attr-defined]
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
             json.dump(asdict(config), f, indent=2)  # type: ignore[call-overload]
+        _restrict(path, 0o600)  # an existing world-readable file is tightened too
         return config
 
+    def exists(self, config_id: str) -> bool:
+        """True when a config with ``config_id`` is saved (no read, no deserialisation)."""
+        return self._path(config_id).exists()
+
     def delete_config(self, config_id: str) -> bool:
         """Delete a config. Returns True if it existed."""
         path = self._path(config_id)
@@ -106,6 +116,11 @@ class PluginConfigStore(Generic[T]):
             self.save_config(config)
 
     # ── internals ────────────────────────────────────────────────────────
+    @property
+    def directory(self) -> Path:
+        """Where this plugin's configs live (read-only view for callers that need the path)."""
+        return self._dir
+
     def _path(self, config_id: str) -> Path:
         return self._dir / f"{config_id}.json"
 
@@ -138,3 +153,11 @@ class PluginConfigStore(Generic[T]):
                 moved += 1
         if moved:
             logger.info("Migrated %d config(s) from %s → %s", moved, legacy_dir, self._dir)
+
+
+def _restrict(path: Path, mode: int) -> None:
+    """Best-effort chmod: the store must keep working on filesystems without POSIX modes."""
+    try:
+        os.chmod(path, mode)
+    except OSError:
+        logger.debug("Could not chmod %s", path, exc_info=True)