feat(jobs): surface optional callback_url on job submit

Mirror the gateway add-job-completion-callback change across the consumer
surfaces: @run402/sdk ManagedJobSubmitRequest.callback_url, the MCP
submit_managed_job tool input, and the CLI `jobs submit` help. Optional
HTTPS URL pushed once on terminal job state (durable, unsigned, dedupe on
Run402-Webhook-Id, re-fetch via get before acting).

- sdk: callback_url on ManagedJobSubmitRequest, forwarded by submit()
- mcp tool: callback_url in managedJobSubmitRequestSchema + handler
- cli: documented in `jobs submit` help/example (flows via --file/--stdin body)
- tests: sdk (2) + mcp tool (1) forward-through cases

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: volinskey

cli/lib/jobs.mjs

@@ -51,8 +51,14 @@ Example request:
   {
     "job_type": "kysigned.fflonk_prove.v0_17_0",
     "input": { "input.json": {} },
-    "max_cost_usd_micros": 50000
+    "max_cost_usd_micros": 50000,
+    "callback_url": "https://hooks.example.com/jobs"
   }
+
+  callback_url (optional) is an HTTPS URL pushed once on terminal state
+  (completed/failed/cancelled), so you need not poll. Durable + unsigned:
+  dedupe on the Run402-Webhook-Id header and re-fetch with 'jobs get'
+  before acting.
 `,
   get: `run402 jobs get — Get a managed job run
 

sdk/src/namespaces/jobs.test.ts

@@ -79,6 +79,47 @@ describe("jobs", () => {
     assert.deepEqual(JSON.parse(calls[0]!.body as string), submitRequest());
   });
 
+  it("submit forwards an optional callback_url verbatim", async () => {
+    const { fetch, calls } = mockFetch(() =>
+      json(
+        {
+          job_id: "job_cb",
+          job_type: "kysigned.fflonk_prove.v0_17_0",
+          status: "queued",
+          created_at: "2026-05-18T00:00:00.000Z",
+        },
+        202,
+      ),
+    );
+
+    await sdk(fetch).jobs.submit("prj_k", {
+      ...submitRequest(),
+      callback_url: "https://hooks.example.com/jobs",
+    });
+
+    const body = JSON.parse(calls[0]!.body as string);
+    assert.equal(body.callback_url, "https://hooks.example.com/jobs");
+  });
+
+  it("submit omits callback_url from the body when not provided", async () => {
+    const { fetch, calls } = mockFetch(() =>
+      json(
+        {
+          job_id: "job_nocb",
+          job_type: "kysigned.fflonk_prove.v0_17_0",
+          status: "queued",
+          created_at: "2026-05-18T00:00:00.000Z",
+        },
+        202,
+      ),
+    );
+
+    await sdk(fetch).jobs.submit("prj_k", submitRequest());
+
+    const body = JSON.parse(calls[0]!.body as string);
+    assert.equal("callback_url" in body, false);
+  });
+
   it("get reads a job run by id", async () => {
     const { fetch, calls } = mockFetch(() =>
       json({

sdk/src/namespaces/jobs.ts

@@ -21,6 +21,14 @@ export interface ManagedJobSubmitRequest {
     "input.json": Record<string, unknown>;
   };
   max_cost_usd_micros: number;
+  /**
+   * Optional HTTPS URL pushed once when the job reaches a terminal state
+   * (completed/failed/cancelled), so you need not poll. Delivery is durable
+   * (at-least-once, retried) and unsigned: dedupe on the `Run402-Webhook-Id`
+   * header and re-fetch authoritative state with `get()` before acting — the
+   * callback is a trigger, not the source of truth.
+   */
+  callback_url?: string;
 }
 
 export interface ManagedJobError {

src/tools/jobs.test.ts

@@ -74,6 +74,35 @@ describe("jobs MCP tools", () => {
     assert.match(calls[0]!.headers["Idempotency-Key"], /^job-/);
   });
 
+  it("forwards an optional callback_url in the POST body", async () => {
+    let capturedBody: string | undefined;
+    globalThis.fetch = (async (_input, init) => {
+      capturedBody = init?.body as string | undefined;
+      return new Response(
+        JSON.stringify({
+          job_id: "job_cb",
+          job_type: "kysigned.fflonk_prove.v0_17_0",
+          status: "queued",
+          created_at: "2026-05-18T00:00:00.000Z",
+        }),
+        { status: 202, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    await handleJobsSubmit({
+      project_id: "prj_k",
+      request: {
+        job_type: "kysigned.fflonk_prove.v0_17_0",
+        input: { "input.json": { envelopeId: "env_1" } },
+        max_cost_usd_micros: 50_000,
+        callback_url: "https://hooks.example.com/jobs",
+      },
+    });
+
+    assert.ok(capturedBody, "expected a request body");
+    assert.equal(JSON.parse(capturedBody!).callback_url, "https://hooks.example.com/jobs");
+  });
+
   it("gets a job and reads logs", async () => {
     const urls: string[] = [];
     globalThis.fetch = (async (input) => {

src/tools/jobs.ts

@@ -21,6 +21,13 @@ const managedJobSubmitRequestSchema = z
       .int()
       .nonnegative()
       .describe("Hard customer charge ceiling in micro-USD"),
+    callback_url: z
+      .string()
+      .url()
+      .optional()
+      .describe(
+        "Optional HTTPS URL pushed once on terminal state (completed/failed/cancelled), so you need not poll. Durable at-least-once + unsigned: dedupe on the Run402-Webhook-Id header and re-fetch with get_managed_job before acting.",
+      ),
   })
   .strict();
 
@@ -63,6 +70,7 @@ export async function handleJobsSubmit(args: {
     job_type: "kysigned.fflonk_prove.v0_17_0";
     input: { "input.json": Record<string, unknown> };
     max_cost_usd_micros: number;
+    callback_url?: string;
   };
 }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   try {