feat: add managed jobs surface

Author: MajorTal

AGENTS.md

@@ -68,7 +68,7 @@ When adding a new tool/command, add it to the `SURFACE` array **and** `SDK_BY_CA
 ## Architecture
 
 ```
-@run402/sdk  (typed TypeScript kernel — 20 namespaces, ~100 methods)
+@run402/sdk  (typed TypeScript kernel — 21 namespaces, ~100 methods)
    │
    │   /index.ts    (isomorphic: Node + sandbox)
    │   /node        (Node-only: keystore + allowance + x402-wrapped fetch + fileSetFromDir)
@@ -93,9 +93,9 @@ The SDK is the canonical kernel — a single typed client with a `CredentialsPro
 - **`kernel.ts`** — Request function, `Client` interface. Only place that calls `globalThis.fetch`.
 - **`errors.ts`** — `Run402Error` hierarchy: `PaymentRequired`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `Run402DeployError` (the v1.34+ structured envelope from the deploy state machine). Never calls `process.exit`.
 - **`credentials.ts`** — `CredentialsProvider` interface. Required: `getAuth`, `getProject`. Optional: `saveProject`, `updateProject`, `removeProject`, `setActiveProject`, `getActiveProject`, `readAllowance`, `saveAllowance`, `createAllowance`, `getAllowancePath`.
-- **`namespaces/*.ts`** — One class per resource group (projects, assets, functions, email, CI/OIDC, …). Namespaces hold a `Client` and expose typed methods. The canonical apply primitive lives at **`namespaces/deploy.ts`** (the file kept its historical name; the public-facing symbol is `r.project(id).apply`, with `r.deploy` retired in v2.0 in favor of an internal `_applyEngine`). Shared types in `deploy.types.ts` — see "Unified Apply" below.
+- **`namespaces/*.ts`** — One class per resource group (projects, assets, functions, jobs, email, CI/OIDC, …). Namespaces hold a `Client` and expose typed methods. The canonical apply primitive lives at **`namespaces/deploy.ts`** (the file kept its historical name; the public-facing symbol is `r.project(id).apply`, with `r.deploy` retired in v2.0 in favor of an internal `_applyEngine`). Shared types in `deploy.types.ts` — see "Unified Apply" below.
 - **`node/*.ts`** — Node-only entry point (`@run402/sdk/node`). Wraps `core/` keystore + allowance into `NodeCredentialsProvider`. Sets up x402-wrapped fetch via `createLazyPaidFetch()`. Adds `fileSetFromDir(path)` for filesystem byte sources and the deploy manifest adapter (`loadDeployManifest(path)`, `normalizeDeployManifest(input)`) for CLI/MCP-compatible JSON.
-- **`scoped.ts`** — `ScopedRun402` sub-client. Returned by `r.project(id?)` and `r.useProject(id)`. Wraps every project-id-bearing namespace method with the id pre-bound, so `p.apply({ site })` (no `project`), `p.functions.list()`, `p.assets.put(key, src)` all "just work" once the scope is set. Caller-supplied `project_id` / `project` still wins (override-friendly). The unwrapped namespaces (`r.assets`, `r.functions`, …) keep their required-id signatures unchanged — scoped is sugar, not a replacement. The apply primitive is only exposed via the scoped client (`r.project(id).apply(spec)`); there is no public `r.deploy` since v2.0.
+- **`scoped.ts`** — `ScopedRun402` sub-client. Returned by `r.project(id?)` and `r.useProject(id)`. Wraps every project-id-bearing namespace method with the id pre-bound, so `p.apply({ site })` (no `project`), `p.functions.list()`, `p.jobs.get(jobId)`, `p.assets.put(key, src)` all "just work" once the scope is set. Caller-supplied `project_id` / `project` still wins (override-friendly). The unwrapped namespaces (`r.assets`, `r.functions`, `r.jobs`, …) keep their required-id signatures unchanged — scoped is sugar, not a replacement. The apply primitive is only exposed via the scoped client (`r.project(id).apply(spec)`); there is no public `r.deploy` since v2.0.
 
 ### Project-scoped sub-client (`r.project(id?)`)
 

README.md

@@ -294,7 +294,7 @@ const p = await r.project(project.project_id);
 await p.assets.put("hello.txt", { content: "hi" });
 ```
 
-The SDK is organised as 20 namespaces: `projects`, `assets`, `ci`, `sites`, `functions`, `secrets`, `subdomains`, `domains`, `email` (+ `webhooks`), `senderDomain`, `auth`, `apps`, `tier`, `billing`, `contracts`, `ai`, `allowance`, `service`, `admin`, plus the `r.project(id).apply` hero for atomic mixed writes (release slices + assets slice via `/apply/v1/*`). Every operation throws a typed `Run402Error` subclass on failure: `PaymentRequired`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `LocalError`, `Run402DeployError`. `apply()` automatically re-plans safe current-base `BASE_RELEASE_CONFLICT` races and emits `apply.retry` progress events. See [`sdk/README.md`](./sdk/README.md).
+The SDK is organised as 21 namespaces: `projects`, `assets`, `ci`, `sites`, `functions`, `jobs`, `secrets`, `subdomains`, `domains`, `email` (+ `webhooks`), `senderDomain`, `auth`, `apps`, `tier`, `billing`, `contracts`, `ai`, `allowance`, `service`, `admin`, plus the `r.project(id).apply` hero for atomic mixed writes (release slices + assets slice via `/apply/v1/*`). Every operation throws a typed `Run402Error` subclass on failure: `PaymentRequired`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `LocalError`, `Run402DeployError`. `apply()` automatically re-plans safe current-base `BASE_RELEASE_CONFLICT` races and emits `apply.retry` progress events. See [`sdk/README.md`](./sdk/README.md).
 
 ## CLI — `run402`
 
@@ -441,6 +441,7 @@ The full MCP surface — every tool is a thin shim over an SDK call.
 | `update_function` | Update schedule / timeout / memory without redeploying code. |
 | `list_functions` / `delete_function` | List / remove functions. |
 | `set_secret` / `list_secrets` / `delete_secret` | Manage `process.env` secrets injected into all functions. Values are write-only; list returns keys and timestamps only. |
+| `jobs_submit` / `jobs_get` / `jobs_logs` / `jobs_cancel` | Submit and inspect fixed platform-managed jobs. Requests use the gateway jobs shape; the SDK supplies the required idempotency header. |
 
 ### Auth & email
 

SKILL.md

@@ -316,6 +316,7 @@ No `route_scopes` means no CI route-declaration authority. With route scopes, CI
 - **`update_function`** — change schedule / timeout / memory without redeploying code.
 - **`list_functions`** / **`delete_function`** — list / remove.
 - **`set_secret`** / **`list_secrets`** / **`delete_secret`** — `process.env` secrets injected into every function. Values are write-only; `list_secrets` returns keys and timestamps only. Deploy specs use `secrets.require[]` as a dependency gate, not as a value carrier or per-function allowlist.
+- **`jobs_submit`** / **`jobs_get`** / **`jobs_logs`** / **`jobs_cancel`** — fixed platform-managed jobs. Submit the gateway-shaped request with `job_type`, `input["input.json"]`, and `max_cost_usd_micros`; this is not arbitrary Docker execution.
 
 Function authoring limits per tier: prototype 10s / 128 MB / 1 scheduled fn / 15 min, hobby 30s / 256 MB / 3 / 5 min, team 60s / 512 MB / 10 / 1 min. Deploy preflights literal unified-deploy function values before plan/upload and returns structured `BAD_FIELD` details.
 

cli-help.test.mjs

@@ -68,6 +68,7 @@ const MATRIX = {
     specific: ["deploy", "invoke", "logs", "update", "list", "delete"],
   },
   secrets: { shared: [], specific: ["set", "list", "delete"] },
+  jobs: { shared: [], specific: ["submit", "get", "logs", "cancel"] },
   assets: {
     shared: [],
     specific: ["put", "get", "ls", "rm", "sign"],

cli/README.md

@@ -143,6 +143,17 @@ run402 deploy apply --manifest run402.deploy.json   # manifest uses secrets.requ
 
 Secret values are write-only. `list` returns keys and timestamps only; deploy manifests should declare dependencies with `secrets.require` and never contain values.
 
+### Jobs
+
+```bash
+run402 jobs submit --file job.json --project prj_...
+run402 jobs get job_abc123 --project prj_...
+run402 jobs logs job_abc123 --project prj_... --tail 100
+run402 jobs cancel job_abc123 --project prj_...
+```
+
+Jobs are fixed platform-managed runners, not arbitrary Docker execution. Submit the gateway-shaped JSON request (`job_type`, `input["input.json"]`, `max_cost_usd_micros`) and the CLI handles the required idempotency header through the SDK.
+
 ### Email
 
 ```bash

cli/cli.mjs

@@ -27,6 +27,7 @@ Commands:
   projects    Manage projects (provision, list, query, inspect, delete)
   deploy      Unified deploy operations (requires active tier)
   ci          Link GitHub Actions OIDC deploy bindings
+  jobs        Submit and inspect fixed platform-managed jobs
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
   secrets     Manage project secrets (set, list, delete)
   assets      Direct-to-S3 asset storage (put, get, ls, rm, sign, diagnose) — up to 5 TiB
@@ -52,6 +53,7 @@ Examples:
   run402 allowance create
   run402 allowance fund
   run402 deploy apply --manifest app.json
+  run402 jobs submit --file job.json
   run402 projects list
   run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
   run402 functions deploy <project_id> my-fn --file handler.ts
@@ -129,6 +131,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "jobs": {
+    const { run } = await import("./lib/jobs.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "functions": {
     const { run } = await import("./lib/functions.mjs");
     await run(sub, rest);