Operations: jobs

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.

Generated from the operation catalog: src/lib/ops/public-catalog.json in publicsummerengine at 0d85f61e2b and the summer-engine npm package 4.0.0 for engine and local operations. If something here is wrong, the operation’s definition is wrong.

Operation	What it does	Asks you first
`jobs.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`	Read one job once: its state (queued, running, awaiting_approval, done, failed…), progress and, when done, its result.	Never
`jobs.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 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.

Input JSON schema

{
  "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"
  ]
}

Result JSON schema

{
  "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
}

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

{
  "name": "summer_call",
  "arguments": {
    "op": "jobs.cancel",
    "input": {
      "jobId": "apr:g_123:goa_01J"
    }
  }
}

summer jobs cancel --job-id apr:g_123:goa_01J

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.

Input JSON schema

{
  "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"
  ]
}

Result JSON schema

{
  "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
}

Example: Is the 3D model done?

{
  "name": "summer_jobs_get",
  "arguments": {
    "jobId": "gen:4821"
  }
}

summer jobs get --job-id gen:4821

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.

Input JSON schema

{
  "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}$"
    }
  }
}

Result JSON schema

{
  "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
}

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

{
  "name": "summer_call",
  "arguments": {
    "op": "jobs.list",
    "input": {
      "gameId": "g_123",
      "state": "running"
    }
  }
}

summer jobs list --game-id g_123 --state running

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.

Input JSON schema

{
  "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"
  ]
}

Result JSON schema

{
  "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
}

Example: Wait for a 3D job.

{
  "name": "summer_jobs_wait",
  "arguments": {
    "jobId": "gen:4821",
    "timeoutSeconds": 30
  }
}

summer jobs wait --job-id gen:4821 --timeout-seconds 30

Overview

Operations

HTTP API

GDScript API

Migration and extensions

MCP

cancel

get

list

wait

​cancel

​get

​list

​wait

cancel

get

list

wait