> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations: jobs

> Long work and waiting for your approval: read, wait for, list and cancel jobs. For each operation: what it does, whether it asks you first, its inputs and an example call.

Long work and waiting for your approval: read, wait for, list and cancel jobs. 4 operations. How to call them, and what the answers mean: [Operations reference](/mcp/operations).

<Note>
  Generated from the `summer-engine` npm package `4.2.0`: its public operation catalog (`registry/operations/public-catalog.json`) and its engine and local operations. If something here is wrong, the operation's definition is wrong.
</Note>

| Operation | What it does | Asks you first |
| - | - | - |
| [`jobs.cancel`](#cancel) | Stop one of the person's jobs that has not finished: a plan agent request, a cloud build, or a publish request still waiting for the owner (its link stops working). | Not by default |
| [`jobs.get`](#get) | Read one job once: its state (queued, running, awaiting\_approval, done, failed...), progress and, when done, its result. | Never |
| [`jobs.list`](#list) | List the person's jobs, newest first: with planId, a plan's agent requests and cloud builds; else store uploads and publish requests, for one game or the five games changed last. | Never |
| [`jobs.wait`](#wait) | Wait up to timeoutSeconds (at most 50) for a job to finish, then return it. | Never |

***

### cancel

`jobs.cancel`: **Cancel a job**

Stop one of the person's jobs that has not finished: a plan agent request, a cloud build, or a publish request still waiting for the owner (its link stops working). Work already saved stays. Returns the job. Next: jobs.list.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "jobs.cancel"` |
| **CLI** | `summer jobs cancel` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |
| **3.x names** | `summer_board_agent_cancel`, `summer_board_build_cancel` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | A job id from any op that answered running or needs\_approval (3.x job ids work too). Length 1 to 260. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

<Accordion title="Input JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "jobId": {
        "description": "A job id from any op that answered running or needs_approval (3.x job ids work too).",
        "type": "string",
        "minLength": 1,
        "maxLength": 260
      },
      "dryRun": {
        "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
        "type": "boolean"
      },
      "idempotencyKey": {
        "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      }
    },
    "required": [
      "jobId"
    ]
  }
  ```
</Accordion>

<Accordion title="Result JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "awaiting_approval",
              "done",
              "failed",
              "cancelled",
              "declined",
              "expired",
              "stale"
            ]
          },
          "progress": {
            "type": "number"
          },
          "result": {
            "description": "The finished work: asset ids and URLs, or the approved change.",
            "type": "object",
            "additionalProperties": {}
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          },
          "message": {
            "type": "string"
          },
          "pollAfterSeconds": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "kind",
          "state"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "job"
    ],
    "additionalProperties": false
  }
  ```
</Accordion>

**Example:** Take back a publish request before the owner answers.

<CodeGroup>
  ```json MCP theme={null}
  {
    "name": "summer_call",
    "arguments": {
      "op": "jobs.cancel",
      "input": {
        "jobId": "apr:g_123:goa_01J"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  summer jobs cancel --job-id apr:g_123:goa_01J
  ```
</CodeGroup>

***

### get

`jobs.get`: **Check a job**

Read one job once: its state (queued, running, awaiting\_approval, done, failed...), progress and, when done, its result. Next: jobs.wait to wait for it.

| | |
| - | - |
| **MCP** | `summer_jobs_get`, a tool on the hosted MCP and the npm assets profile. Elsewhere: `summer_call` with `"op": "jobs.get"` |
| **CLI** | `summer jobs get` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |
| **3.x names** | `summer_check_job`, `summer_board_agent_task`, `summer_board_build_status` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | A job id from any op that answered running or needs\_approval (3.x job ids work too). Length 1 to 260. |

<Accordion title="Input JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "jobId": {
        "description": "A job id from any op that answered running or needs_approval (3.x job ids work too).",
        "type": "string",
        "minLength": 1,
        "maxLength": 260
      }
    },
    "required": [
      "jobId"
    ]
  }
  ```
</Accordion>

<Accordion title="Result JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "awaiting_approval",
              "done",
              "failed",
              "cancelled",
              "declined",
              "expired",
              "stale"
            ]
          },
          "progress": {
            "type": "number"
          },
          "result": {
            "description": "The finished work: asset ids and URLs, or the approved change.",
            "type": "object",
            "additionalProperties": {}
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          },
          "message": {
            "type": "string"
          },
          "pollAfterSeconds": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "kind",
          "state"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "job"
    ],
    "additionalProperties": false
  }
  ```
</Accordion>

**Example:** Is the 3D model done?

<CodeGroup>
  ```json MCP theme={null}
  {
    "name": "summer_jobs_get",
    "arguments": {
      "jobId": "gen:4821"
    }
  }
  ```

  ```bash CLI theme={null}
  summer jobs get --job-id gen:4821
  ```
</CodeGroup>

***

### list

`jobs.list`: **List my jobs**

List the person's jobs, newest first: with planId, a plan's agent requests and cloud builds; else store uploads and publish requests, for one game or the five games changed last. Next: jobs.wait or jobs.cancel.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "jobs.list"` |
| **CLI** | `summer jobs list` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |
| **3.x names** | `summer_board_agent_tasks` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `gameId` | string | No | One game (from games.list); else the five games changed last. |
| `planId` | string | No | One plan (from plans.list): its agent requests and cloud builds. |
| `kind` | "upload" \| "apr" \| "plan" \| "build" | No | upload: store uploads; apr: publish requests; plan: plan agent requests; build: cloud builds (plan and build need planId). |
| `state` | "queued" \| "running" \| "awaiting\_approval" \| "done" \| "failed" \| "cancelled" \| "declined" \| "expired" \| "stale" | No | |
| `limit` | integer | No | Default `10`. Range 1 to 50. |
| `cursor` | string | No | nextCursor from the previous page. |

<Accordion title="Input JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "gameId": {
        "description": "One game (from games.list); else the five games changed last.",
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,128}$"
      },
      "planId": {
        "description": "One plan (from plans.list): its agent requests and cloud builds.",
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "kind": {
        "description": "upload: store uploads; apr: publish requests; plan: plan agent requests; build: cloud builds (plan and build need planId).",
        "type": "string",
        "enum": [
          "upload",
          "apr",
          "plan",
          "build"
        ]
      },
      "state": {
        "type": "string",
        "enum": [
          "queued",
          "running",
          "awaiting_approval",
          "done",
          "failed",
          "cancelled",
          "declined",
          "expired",
          "stale"
        ]
      },
      "limit": {
        "default": 10,
        "type": "integer",
        "minimum": 1,
        "maximum": 50
      },
      "cursor": {
        "description": "nextCursor from the previous page.",
        "type": "string",
        "pattern": "^\\d{1,3}$"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Result JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "jobId": {
              "type": "string"
            },
            "kind": {
              "type": "string",
              "enum": [
                "upload",
                "apr",
                "plan",
                "build"
              ]
            },
            "op": {
              "description": "The op that started it.",
              "type": "string"
            },
            "state": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "awaiting_approval",
                "done",
                "failed",
                "cancelled",
                "declined",
                "expired",
                "stale"
              ]
            },
            "gameId": {
              "type": "string"
            },
            "planId": {
              "type": "string"
            },
            "what": {
              "description": "The upload, the publish request, the plan agent request or the build, in a few words.",
              "type": "string"
            },
            "createdAt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "jobId",
            "kind",
            "op",
            "state",
            "what",
            "createdAt"
          ],
          "additionalProperties": false
        }
      },
      "nextCursor": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "items",
      "nextCursor"
    ],
    "additionalProperties": false
  }
  ```
</Accordion>

**Example:** Which uploads of this game is Summer still checking?

<CodeGroup>
  ```json MCP theme={null}
  {
    "name": "summer_call",
    "arguments": {
      "op": "jobs.list",
      "input": {
        "gameId": "g_123",
        "state": "running"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  summer jobs list --game-id g_123 --state running
  ```
</CodeGroup>

***

### wait

`jobs.wait`: **Wait for a job**

Wait up to timeoutSeconds (at most 50) for a job to finish, then return it. If it is still not done, call again. Approvals wait for the person.

| | |
| - | - |
| **MCP** | `summer_jobs_wait`, a tool on the hosted MCP and the npm assets profile. Elsewhere: `summer_call` with `"op": "jobs.wait"` |
| **CLI** | `summer jobs wait` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | A job id from any op that answered running or needs\_approval (3.x job ids work too). Length 1 to 260. |
| `timeoutSeconds` | integer | No | Most seconds to wait in this call (1 to 50). Default `25`. Range 1 to 50. |

<Accordion title="Input JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "jobId": {
        "description": "A job id from any op that answered running or needs_approval (3.x job ids work too).",
        "type": "string",
        "minLength": 1,
        "maxLength": 260
      },
      "timeoutSeconds": {
        "description": "Most seconds to wait in this call (1 to 50).",
        "default": 25,
        "type": "integer",
        "minimum": 1,
        "maximum": 50
      }
    },
    "required": [
      "jobId"
    ]
  }
  ```
</Accordion>

<Accordion title="Result JSON schema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "awaiting_approval",
              "done",
              "failed",
              "cancelled",
              "declined",
              "expired",
              "stale"
            ]
          },
          "progress": {
            "type": "number"
          },
          "result": {
            "description": "The finished work: asset ids and URLs, or the approved change.",
            "type": "object",
            "additionalProperties": {}
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          },
          "message": {
            "type": "string"
          },
          "pollAfterSeconds": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "kind",
          "state"
        ],
        "additionalProperties": false
      },
      "finished": {
        "type": "boolean"
      },
      "waitedSeconds": {
        "type": "number"
      }
    },
    "required": [
      "job",
      "finished",
      "waitedSeconds"
    ],
    "additionalProperties": false
  }
  ```
</Accordion>

**Example:** Wait for a 3D job.

<CodeGroup>
  ```json MCP theme={null}
  {
    "name": "summer_jobs_wait",
    "arguments": {
      "jobId": "gen:4821",
      "timeoutSeconds": 30
    }
  }
  ```

  ```bash CLI theme={null}
  summer jobs wait --job-id gen:4821 --timeout-seconds 30
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.