@databricks/appkit-ui 0.26.0 → 0.27.0

package/CLAUDE.md

@@ -48,6 +48,7 @@ npx @databricks/appkit docs <query>
 - [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
 - [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
 - [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
+- [Jobs plugin](./docs/plugins/jobs.md): Trigger and monitor Databricks Lakeflow Jobs from your AppKit application.
 - [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
 - [Model Serving plugin](./docs/plugins/model-serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
@@ -93,7 +94,11 @@ npx @databricks/appkit docs <query>
 - [Interface: FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md): Minimal user identity passed to the policy function.
 - [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
+- [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
+- [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
+- [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
+- [Interface: JobsConnectorConfig](./docs/api/appkit/Interface.JobsConnectorConfig.md): Properties
 - [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
 - [Interface: PluginManifest<TName>](./docs/api/appkit/Interface.PluginManifest.md): Plugin manifest that declares metadata and resource requirements.
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
@@ -111,6 +116,8 @@ npx @databricks/appkit docs <query>
 - [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
 - [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
+- [Type Alias: JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md): Job handle returned by appkit.jobs("etl").
+- [Type Alias: JobsExport()](./docs/api/appkit/TypeAlias.JobsExport.md): Public API shape of the jobs plugin.
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.

package/docs/api/appkit/Interface.BasePluginConfig.md

@@ -2,6 +2,10 @@
 
 Base configuration interface for AppKit plugins
 
+## Extended by[​](#extended-by "Direct link to Extended by")
+
+* [`IJobsConfig`](./docs/api/appkit/Interface.IJobsConfig.md)
+
 ## Indexable[​](#indexable "Direct link to Indexable")
 
 ```ts

package/docs/api/appkit/Interface.IJobsConfig.md

@@ -0,0 +1,86 @@
+# Interface: IJobsConfig
+
+Configuration for the Jobs plugin.
+
+## Extends[​](#extends "Direct link to Extends")
+
+* [`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md)
+
+## Indexable[​](#indexable "Direct link to Indexable")
+
+```ts
+[key: string]: unknown
+
+```
+
+## Properties[​](#properties "Direct link to Properties")
+
+### host?[​](#host "Direct link to host?")
+
+```ts
+optional host: string;
+
+```
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+[`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md).[`host`](./docs/api/appkit/Interface.BasePluginConfig.md#host)
+
+***
+
+### jobs?[​](#jobs "Direct link to jobs?")
+
+```ts
+optional jobs: Record<string, JobConfig>;
+
+```
+
+Named jobs to expose. Each key becomes a job accessor.
+
+***
+
+### name?[​](#name "Direct link to name?")
+
+```ts
+optional name: string;
+
+```
+
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+[`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md).[`name`](./docs/api/appkit/Interface.BasePluginConfig.md#name)
+
+***
+
+### pollIntervalMs?[​](#pollintervalms "Direct link to pollIntervalMs?")
+
+```ts
+optional pollIntervalMs: number;
+
+```
+
+Poll interval for waitForRun in milliseconds. Defaults to 5000.
+
+***
+
+### telemetry?[​](#telemetry "Direct link to telemetry?")
+
+```ts
+optional telemetry: TelemetryOptions;
+
+```
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+[`BasePluginConfig`](./docs/api/appkit/Interface.BasePluginConfig.md).[`telemetry`](./docs/api/appkit/Interface.BasePluginConfig.md#telemetry)
+
+***
+
+### timeout?[​](#timeout "Direct link to timeout?")
+
+```ts
+optional timeout: number;
+
+```
+
+Operation timeout in milliseconds. Defaults to 60000.

package/docs/api/appkit/Interface.JobAPI.md

@@ -0,0 +1,163 @@
+# Interface: JobAPI
+
+User-facing API for a single configured job.
+
+## Methods[​](#methods "Direct link to Methods")
+
+### cancelRun()[​](#cancelrun "Direct link to cancelRun()")
+
+```ts
+cancelRun(runId: number): Promise<ExecutionResult<void>>;
+
+```
+
+Cancel a specific run.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `runId`   | `number` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`void`>>
+
+***
+
+### getJob()[​](#getjob "Direct link to getJob()")
+
+```ts
+getJob(): Promise<ExecutionResult<Job>>;
+
+```
+
+Get the job definition.
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`Job`>>
+
+***
+
+### getRun()[​](#getrun "Direct link to getRun()")
+
+```ts
+getRun(runId: number): Promise<ExecutionResult<Run>>;
+
+```
+
+Get a specific run by ID.
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `runId`   | `number` |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`Run`>>
+
+***
+
+### getRunOutput()[​](#getrunoutput "Direct link to getRunOutput()")
+
+```ts
+getRunOutput(runId: number): Promise<ExecutionResult<RunOutput>>;
+
+```
+
+Get output of a specific run.
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `runId`   | `number` |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`RunOutput`>>
+
+***
+
+### lastRun()[​](#lastrun "Direct link to lastRun()")
+
+```ts
+lastRun(): Promise<ExecutionResult<BaseRun | undefined>>;
+
+```
+
+Get the most recent run for this job.
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`BaseRun` | `undefined`>>
+
+***
+
+### listRuns()[​](#listruns "Direct link to listRuns()")
+
+```ts
+listRuns(options?: {
+  limit?: number;
+}): Promise<ExecutionResult<BaseRun[]>>;
+
+```
+
+List runs for this job.
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter        | Type                    |
+| ---------------- | ----------------------- |
+| `options?`       | { `limit?`: `number`; } |
+| `options.limit?` | `number`                |
+
+#### Returns[​](#returns-5 "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`BaseRun`\[]>>
+
+***
+
+### runAndWait()[​](#runandwait "Direct link to runAndWait()")
+
+```ts
+runAndWait(params?: Record<string, unknown>, signal?: AbortSignal): AsyncGenerator<JobRunStatus, void, unknown>;
+
+```
+
+Trigger and poll until completion, yielding status updates.
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `params?` | `Record`<`string`, `unknown`> |
+| `signal?` | `AbortSignal`                 |
+
+#### Returns[​](#returns-6 "Direct link to Returns")
+
+`AsyncGenerator`<`JobRunStatus`, `void`, `unknown`>
+
+***
+
+### runNow()[​](#runnow "Direct link to runNow()")
+
+```ts
+runNow(params?: Record<string, unknown>): Promise<ExecutionResult<RunNowResponse>>;
+
+```
+
+Trigger the configured job with validated params. Returns the run response.
+
+#### Parameters[​](#parameters-5 "Direct link to Parameters")
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `params?` | `Record`<`string`, `unknown`> |
+
+#### Returns[​](#returns-7 "Direct link to Returns")
+
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`RunNowResponse`>>

package/docs/api/appkit/Interface.JobConfig.md

@@ -0,0 +1,36 @@
+# Interface: JobConfig
+
+Per-job configuration options.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### params?[​](#params "Direct link to params?")
+
+```ts
+optional params: ZodType<Record<string, unknown>, unknown, $ZodTypeInternals<Record<string, unknown>, unknown>>;
+
+```
+
+Optional Zod schema for validating job parameters at runtime.
+
+***
+
+### taskType?[​](#tasktype "Direct link to taskType?")
+
+```ts
+optional taskType: TaskType;
+
+```
+
+The type of task this job runs. Determines how params are mapped to the SDK request.
+
+***
+
+### waitTimeout?[​](#waittimeout "Direct link to waitTimeout?")
+
+```ts
+optional waitTimeout: number;
+
+```
+
+Maximum time (ms) to poll in runAndWait before giving up. Defaults to 600 000 (10 min).

package/docs/api/appkit/Interface.JobsConnectorConfig.md

@@ -0,0 +1,10 @@
+# Interface: JobsConnectorConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### telemetry?[​](#telemetry "Direct link to telemetry?")
+
+```ts
+optional telemetry: TelemetryOptions;
+
+```

package/docs/api/appkit/TypeAlias.JobHandle.md

@@ -0,0 +1,29 @@
+# Type Alias: JobHandle
+
+```ts
+type JobHandle = JobAPI & {
+  asUser: (req: IAppRequest) => JobAPI;
+};
+
+```
+
+Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`.
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+### asUser()[​](#asuser "Direct link to asUser()")
+
+```ts
+asUser: (req: IAppRequest) => JobAPI;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `req`     | `IAppRequest` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+[`JobAPI`](./docs/api/appkit/Interface.JobAPI.md)

package/docs/api/appkit/TypeAlias.JobsExport.md

@@ -0,0 +1,34 @@
+# Type Alias: JobsExport()
+
+```ts
+type JobsExport = (jobKey: string) => JobHandle;
+
+```
+
+Public API shape of the jobs plugin. Callable to select a job by key.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `jobKey`  | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`JobHandle`](./docs/api/appkit/TypeAlias.JobHandle.md)
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+// Trigger a configured job
+const { run_id } = await appkit.jobs("etl").runNow();
+
+// Trigger and poll until completion
+for await (const status of appkit.jobs("etl").runAndWait()) {
+  console.log(status.status, status.run);
+}
+
+// OBO access
+await appkit.jobs("etl").asUser(req).runNow();
+
+```

package/docs/api/appkit.md

@@ -37,7 +37,11 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 | [FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md)                                       | Minimal user identity passed to the policy function.                                                                                                                                                                                                            |
 | [FileResource](./docs/api/appkit/Interface.FileResource.md)                                           | Describes the file or directory being acted upon.                                                                                                                                                                                                               |
 | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                    |
+| [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md)                                             | Configuration for the Jobs plugin.                                                                                                                                                                                                                              |
 | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                     |
+| [JobAPI](./docs/api/appkit/Interface.JobAPI.md)                                                       | User-facing API for a single configured job.                                                                                                                                                                                                                    |
+| [JobConfig](./docs/api/appkit/Interface.JobConfig.md)                                                 | Per-job configuration options.                                                                                                                                                                                                                                  |
+| [JobsConnectorConfig](./docs/api/appkit/Interface.JobsConnectorConfig.md)                             | -                                                                                                                                                                                                                                                               |
 | [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                           |
 | [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md)                                       | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types.                                                                                |
 | [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md)                                     | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables                                                                                                                 |
@@ -60,6 +64,8 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 | [FileAction](./docs/api/appkit/TypeAlias.FileAction.md)                 | Every action the files plugin can perform.                                                                                 |
 | [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md)                 | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
 | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                 | Express router type for plugin route registration                                                                          |
+| [JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md)                   | Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`.                                       |
+| [JobsExport](./docs/api/appkit/TypeAlias.JobsExport.md)                 | Public API shape of the jobs plugin. Callable to select a job by key.                                                      |
 | [PluginData](./docs/api/appkit/TypeAlias.PluginData.md)                 | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.                              |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types.                                                         |
 | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)         | Factory function returned by `AppKit.serving`.                                                                             |

package/docs/plugins/jobs.md

@@ -0,0 +1,252 @@
+# Jobs plugin
+
+Trigger and monitor [Databricks Lakeflow Jobs](https://docs.databricks.com/en/jobs/index.html) from your AppKit application.
+
+**Key features:**
+
+* Multi-job support with named job keys
+* Auto-discovery of jobs from environment variables
+* Run-and-wait with SSE streaming status updates
+* Parameter validation with Zod schemas
+* Task-type-aware parameter mapping (notebook, python\_wheel, sql, etc.)
+* Optional on-behalf-of (OBO) user execution via `.asUser(req)`
+
+## Basic usage[​](#basic-usage "Direct link to Basic usage")
+
+```ts
+import { createApp, server, jobs } from "@databricks/appkit";
+
+await createApp({
+  plugins: [server(), jobs()],
+});
+
+```
+
+With no explicit `jobs` config, the plugin reads `DATABRICKS_JOB_ID` from the environment and registers it under the `default` key.
+
+## Configuration options[​](#configuration-options "Direct link to Configuration options")
+
+| Option           | Type                        | Default | Description                                           |
+| ---------------- | --------------------------- | ------- | ----------------------------------------------------- |
+| `timeout`        | `number`                    | `60000` | Default timeout for Jobs API calls in ms              |
+| `pollIntervalMs` | `number`                    | `5000`  | Poll interval for `runAndWait` in ms                  |
+| `jobs`           | `Record<string, JobConfig>` | —       | Named jobs to expose. Each key becomes a job accessor |
+
+### Per-job config (`JobConfig`)[​](#per-job-config-jobconfig "Direct link to per-job-config-jobconfig")
+
+| Option        | Type        | Default  | Description                                 |
+| ------------- | ----------- | -------- | ------------------------------------------- |
+| `waitTimeout` | `number`    | `600000` | Override the polling timeout for this job   |
+| `taskType`    | `TaskType`  | —        | Task type for automatic parameter mapping   |
+| `params`      | `z.ZodType` | —        | Zod schema for runtime parameter validation |
+
+## Environment variables[​](#environment-variables "Direct link to Environment variables")
+
+### Single-job mode[​](#single-job-mode "Direct link to Single-job mode")
+
+Set `DATABRICKS_JOB_ID` to expose one job under the `default` key:
+
+```env
+DATABRICKS_JOB_ID=123456
+
+```
+
+```ts
+const handle = AppKit.jobs("default");
+
+```
+
+### Multi-job mode[​](#multi-job-mode "Direct link to Multi-job mode")
+
+Set `DATABRICKS_JOB_<NAME>` for each job:
+
+```env
+DATABRICKS_JOB_ETL=123456
+DATABRICKS_JOB_ML=789012
+
+```
+
+```ts
+const etl = AppKit.jobs("etl");
+const ml  = AppKit.jobs("ml");
+
+```
+
+Environment variable names are uppercased; job keys are lowercased. Jobs discovered from the environment are merged with any explicit `jobs` config — explicit config wins.
+
+## Parameter validation[​](#parameter-validation "Direct link to Parameter validation")
+
+Use `params` to enforce a Zod schema at runtime. Invalid parameters are rejected with a `400` before the job is triggered:
+
+```ts
+import { z } from "zod";
+
+jobs({
+  jobs: {
+    etl: {
+      params: z.object({
+        startDate: z.string(),
+        endDate: z.string(),
+        dryRun: z.boolean().optional(),
+      }),
+    },
+  },
+})
+
+```
+
+## Task type mapping[​](#task-type-mapping "Direct link to Task type mapping")
+
+When `taskType` is set, the plugin maps validated parameters to the correct SDK request fields automatically:
+
+| Task type       | SDK field             | Parameter shape                                     |
+| --------------- | --------------------- | --------------------------------------------------- |
+| `notebook`      | `notebook_params`     | `Record<string, string>` — values coerced to string |
+| `python_wheel`  | `python_named_params` | `Record<string, string>` — values coerced to string |
+| `python_script` | `python_params`       | `{ args: string[] }` — positional args              |
+| `spark_jar`     | `jar_params`          | `{ args: string[] }` — positional args              |
+| `sql`           | `sql_params`          | `Record<string, string>` — values coerced to string |
+| `dbt`           | —                     | No parameters accepted                              |
+
+```ts
+jobs({
+  jobs: {
+    etl: {
+      taskType: "notebook",
+      params: z.object({
+        startDate: z.string(),
+        endDate: z.string(),
+      }),
+    },
+  },
+})
+
+```
+
+When `taskType` is omitted, parameters are passed through to the SDK as-is.
+
+## Execution context[​](#execution-context "Direct link to Execution context")
+
+HTTP routes run as the **app's service principal** by default. Jobs are typically shared infrastructure, and the app's resource binding (`databricks.yml`) grants `CAN_MANAGE_RUN` to the SP — so users trigger runs without needing individual grants.
+
+Per-run attribution in the Jobs UI will show the app's SP, not the human user. If you need user-level attribution (or want the Databricks permission check to use the user's grants), opt in to OBO explicitly in a custom handler via `.asUser(req)`:
+
+```ts
+// Default: runs as the app's service principal
+const result = await AppKit.jobs("etl").runNow({ startDate: "2025-01-01" });
+
+// Opt-in: runs as the logged-in user (requires `jobs.jobs` in
+// `databricks.yml` user_api_scopes AND the user's own CAN_MANAGE_RUN grant)
+const result = await AppKit.jobs("etl").asUser(req).runNow({ startDate: "2025-01-01" });
+
+```
+
+## HTTP endpoints[​](#http-endpoints "Direct link to HTTP endpoints")
+
+All routes are mounted under `/api/jobs`.
+
+### Trigger a run[​](#trigger-a-run "Direct link to Trigger a run")
+
+```text
+POST /api/jobs/:jobKey/run
+Content-Type: application/json
+
+{ "params": { "startDate": "2025-01-01" } }
+
+```
+
+Returns `{ "runId": 12345 }`.
+
+Add `?stream=true` to receive SSE status updates that poll until the run completes:
+
+```text
+POST /api/jobs/:jobKey/run?stream=true
+
+```
+
+Each SSE event contains `{ status, timestamp, run }`.
+
+### List runs[​](#list-runs "Direct link to List runs")
+
+```text
+GET /api/jobs/:jobKey/runs?limit=20
+
+```
+
+Returns `{ "runs": [...] }`. Limit is clamped to 1–100, default 20.
+
+### Get run details[​](#get-run-details "Direct link to Get run details")
+
+```text
+GET /api/jobs/:jobKey/runs/:runId
+
+```
+
+### Get latest status[​](#get-latest-status "Direct link to Get latest status")
+
+```text
+GET /api/jobs/:jobKey/status
+
+```
+
+Returns `{ "status": "TERMINATED", "run": { ... } }` for the most recent run.
+
+### Cancel a run[​](#cancel-a-run "Direct link to Cancel a run")
+
+```text
+DELETE /api/jobs/:jobKey/runs/:runId
+
+```
+
+Returns `204 No Content` on success.
+
+## Programmatic access[​](#programmatic-access "Direct link to Programmatic access")
+
+The plugin exports a callable that selects a job by key:
+
+```ts
+const AppKit = await createApp({
+  plugins: [
+    server(),
+    jobs({
+      jobs: {
+        etl: { taskType: "notebook" },
+      },
+    }),
+  ],
+});
+
+const etl = AppKit.jobs("etl");
+
+// Trigger a run
+const result = await etl.runNow({ startDate: "2025-01-01" });
+if (result.ok) {
+  console.log("Run ID:", result.data.run_id);
+}
+
+// Trigger and poll until completion
+for await (const status of etl.runAndWait({ startDate: "2025-01-01" })) {
+  console.log(status.status); // "PENDING", "RUNNING", "TERMINATED", etc.
+}
+
+// Read operations
+await etl.lastRun();
+await etl.listRuns({ limit: 10 });
+await etl.getRun(12345);
+await etl.getRunOutput(12345);
+await etl.getJob();
+
+// Cancel
+await etl.cancelRun(12345);
+
+```
+
+All methods return [`ExecutionResult<T>`](./docs/api/appkit/TypeAlias.ExecutionResult.md) — check `result.ok` before accessing `result.data`.
+
+## Execution defaults[​](#execution-defaults "Direct link to Execution defaults")
+
+| Tier   | Cache    | Retry                  | Timeout | Methods                                                   |
+| ------ | -------- | ---------------------- | ------- | --------------------------------------------------------- |
+| Read   | 60s TTL  | 3 attempts, 1s backoff | 30s     | `getRun`, `getJob`, `listRuns`, `lastRun`, `getRunOutput` |
+| Write  | Disabled | Disabled               | 120s    | `runNow`, `cancelRun`                                     |
+| Stream | Disabled | Disabled               | 600s    | `runAndWait` (SSE polling)                                |