production_operation

What it does

• Writes
• Destructive
• Idempotent
• Account required

The addressable state of one production render or rendering bundle. It reports persisted progress in panels, estimates the rendering time left, accepts a cooperative cancellation request, and mints fresh short-lived download grants for a successful result without starting or charging the work again.

You can ask: “Reconnect to this production render and collect its finished result.”

There is deliberately no listing, Workflow-run lookup or diagnostics action, and no widget may call it directly.

Progress is reported twice over, in two units. progress.panelsCompleted and progress.panelsTotal count the panels you asked for, and progress.estimatedRemainingSeconds estimates the rendering left from the pace this operation is actually running at. progress.completed and progress.total count internal scheduling items — one per panel plus a bundle item plus a result item — so an eight-panel bundle is ten items. Report the panel numbers; the item counters are bookkeeping.

A full-resolution multi-panel render takes a few seconds per panel, so an eight-panel bundle is well over a minute. Each poll also returns a plain sentence beside the structured result, so an agent has something to tell you instead of leaving the wait unexplained.

Input

• actionstringrequired

  Read state, request cooperative cancellation, or obtain the terminal result.

  one ofgetcancelresult

• operationIdstringrequiredat least 1 character

  The opaque durable operation id returned by a production render.

Result

• okbooleanrequired

• countnumberoptional

• panelPresetIdstringoptional

• panelWidthnumberoptional

• panelHeightnumberoptional

• outputstringoptionalalways "urls"

• localestringoptional

• creditsobjectoptional

  Credits this call spent from the account wallet, the balance left afterwards, and when that wallet is next topped up (ISO 8601; absent when no further refill is scheduled). Renders cost per panel; reads, saves, uploads and deletes are free, as is bundling panels that were already rendered.

  • debitednumberrequired

  • remainingnumberrequired

  • refillAtstringoptional

• notestringoptional

  Free-text advisories about THIS call, joined into one string. Written when the server did something you did not literally ask for or could not have known: a look/version fallback, an output-mode downgrade, a device this server cannot render, a style.shotLook a look overrode, or placement set by hand where a style.layout template would have produced the same composition. Never an error — the call succeeded. Read it, and act on it next call.

• contractobjectrequired

  The versioned ShotOps result contract (#662): what ran, where, what it changed, what it cost, what it produced and — on a refusal — a typed failure over a closed code catalog. Structured content is authoritative; the prose beside it is a rendering of this block.

  • contractVersionstringrequired

    The version of THIS envelope, REPORTED. Compare it against the version you were written for. There is no version negotiation: no tool accepts a requested version, so this is never a refusal — it moves only when a field changes meaning, and additive fields never move it.

  • statusstringrequired

    one ofsucceededpartialfailedrefusedacceptedqueuedrunningcancel_requestedcancelled

  • terminalbooleanrequired

    false ⟹ this operation is still running and will be reported again (#666).

  • operationobjectrequired

    • idstringrequired

      Identity for THIS call, unique per invocation. Quote it in a bug report.

    • toolstringrequired

      The registered tool name that produced this result.

    • kindstringrequired

      one ofrenderbundlereadmutateuploaddeletestatus

    • durableobjectoptional

      #666 domain handle for addressable long-running work. Absent from synchronous calls.

      • operationIdstringrequired

      • pollWithstringoptional

  • executionobjectrequired

    • locationstringrequired

      Where the work RAN. local is the caller’s own machine over stdio.

      one oflocalhosted

    • inputModesarrayrequired

      Every way this door accepts screenshots and assets.

      each item

      string

      one ofinline_base64stored_refremote_urllocal_pathproject_stored

    • deliveryModesarrayrequired

      Every way this door can hand a result back.

      each item

      string

      one ofinline_base64signed_urllocal_pathshare_link

  • effectsobjectrequired

    What this call DID to the world, independent of what it returned. Every flag is stated on every result, false included: an absent flag would be indistinguishable from an effect nobody thought to declare.

    • networkFetchbooleanrequired

      This call fetched bytes from a host neither ShotOps nor the caller controls.

    • uploadbooleanrequired

      Caller bytes were uploaded into ShotOps storage.

    • retainedStoragebooleanrequired

      Something survives this call in ShotOps storage.

    • projectMutationbooleanrequired

      A saved project or its look history changed.

    • publicationbooleanrequired

      Something became reachable outside the account — a share link.

    • deletionbooleanrequired

      Something was permanently removed.

  • costobjectrequired

    • unitstringrequiredalways "credit"

      Public cloud credits — the same unit every ShotOps surface quotes.

    • modelstringrequired

      How this connection pays. unmetered is local stdio, which renders on the caller’s own machine; anonymous_allowance is the unsigned hosted taste.

      one ofmeteredanonymous_allowanceunmetered

    • estimatednumberoptional

      What the call was expected to cost, before it ran.

    • reservednumberoptional

      Held against the wallet for the duration of the call (#666).

    • releasednumberoptional

      Given back — an unused reservation or a refund after a post-charge failure (#666).

    • settlednumberoptional

      Actually taken. Absent when nothing was charged.

    • balanceAfternumberoptional

      The wallet’s public cloud credit balance once this call settled.

    • refillAtstringoptional

      ISO 8601. When the wallet is next topped up; absent when none is scheduled.

  • progressobjectoptional

    Persisted monotonic durable-operation progress. Never inferred from transient render metadata. Relay panelsCompleted/panelsTotal and the estimate to the waiting user; the item counters are internal bookkeeping and do not match what they asked for.

    • completedintegerrequiredmin 0

      Internal scheduling items done — panels PLUS the bundle and result items. Do not quote this to a person.

    • totalintegerrequiredmin 0

      Internal scheduling items in total. Larger than the panel count.

    • panelsCompletedintegeroptionalmin 0

      Panels finished, in the unit the caller asked in. THIS is the number to report.

    • panelsTotalintegeroptionalmin 0

      Panels this operation will produce — the count the user asked for.

    • attemptintegerrequiredmin 0

    • heartbeatAtstring or nulloptional

    • estimatedRemainingSecondsnumberoptionalmin 0

      Rough seconds of rendering left, from this operation’s own measured pace once a panel has landed. An estimate, not a deadline — say “about”. Absent when nothing is left to render.

  • resolvedInputobjectoptional

    #661 — what the server actually resolved the request to, before any pixel was produced.

    • snapshotIdstringoptional

      psi_ + the first 32 hex of the fingerprint. Quote it in a bug report.

    • fingerprintstringoptional

      sha256 over every resolved fact. Equal fingerprints ⟹ equal production input.

    • sourcesarrayoptional

      One entry per source cell, resolved or not. slot is the cell the bytes came FROM — a shot id and coordinate on a saved project, an ordered slot label on a direct render. Never a filename, a ref or a URL. origin is absent exactly when status is not resolved: there is nothing the cell came from.

      each item

      object

      • slotstringrequired

      • statusstringrequired

        one ofresolvedmissingambiguous

      • originstringoptional

        one ofinline_base64stored_refremote_urllocal_pathproject_stored

    • defaultsAppliedarrayoptional

      What the server chose because the caller said nothing.

      each item

      string

    • overridesarrayoptional

      What the caller said that changed the outcome.

      each item

      string

  • readinessobjectoptional

    #665 — the readiness verdict and any waiver receipt.

    • statestringoptional

      blocked ⟹ nothing was delivered. ready_with_findings ⟹ delivered, and here is what to know.

      one ofreadyready_with_findingswaivedblocked

    • policyVersionstringoptional

      The readiness policy this verdict was computed under. A waiver granted under another one is rejected.

    • findingsarrayoptional

      Every finding, with code, waivable and digest. A waiver names one id AND its digest; there is no wildcard and no code-level waiver.

      each item

      object

      • idstringrequired

        rf_ + 24 hex. Quote it in a waiver.

      • severitystringrequired

        one ofinfowarnblock

      • messagestringrequired

      • targetobjectrequired

        The exact shot, panel, locale, output or frames this finding is about.

        • shotIdstringoptional

        • panelIndexnumberoptional

        • localestringoptional

        • outputstringoptional

        • captionLayernumberoptional

        • framesarrayoptional

          each item

          number

      • evidenceobjectrequired

        Bounded redacted facts used to derive the finding and its digest.

    • waiversarrayoptional

      The waivers this call ACCEPTED. Pass these objects back verbatim to reuse them; a rebuilt one is rejected.

      each item

      object

      • findingIdstringrequired

      • findingDigeststringrequired

      • policyVersionstringrequired

      • waivedBystringrequired

      • waivedAtstringrequired

      • codestringrequired

        one ofsource_identity_ambiguousoutput_unsupportedoutput_omittedlook_exact_unavailableno_panelspanel_invalid_pngpanel_dimensions_invalidrenderer_failedinput_changed_during_runpanel_source_emptylocale_source_fallbackdevice_source_fallbackcaption_inheritedcaption_locale_fallbacklook_source_fallbackcaption_device_collisioncaption_caption_collisiondevice_device_collisioncaption_legibility_unresolvedscope_filteredlocale_not_live_on_applelook_hold_inactivecaption_text_empty

      • reasonstringoptional

  • artifactsarrayoptional

    each item

    object

    • idstringrequired

      The opaque asset id from the custody registry (#663) — or, for kind: "share", the link’s own token. Never a storage path, and never a signed URL.

    • kindstringrequired

      one ofpanelbundlescreenshotshareproject

    • deliveryobjectrequired

      • modestringrequired

        one ofinline_base64signed_urllocal_pathshare_link

      • urlstringoptional

        THE ONE FIELD a signed URL may appear in. Nothing else in this envelope carries one.

      • expiresAtstringoptional

        ISO 8601, when the grant above stops working.

    • bytesnumberoptional

    • retainedUntilstringoptional

      ISO 8601, when ShotOps stops keeping the artifact itself.

  • failureobjectoptional

    Present exactly when status is failed or refused.

    • codestringrequired

      The closed failure code. Branch on this, never on the sentence.

      one ofinvalid_inputunsupported_inputproject_not_foundproject_ambiguousno_projectsversion_not_foundresolution_incompletereadiness_requiredreadiness_unmetasset_not_foundasset_in_useauthentication_requiredplan_requiredtrial_choice_requiredquota_exhaustedanonymous_limit_reachedcapability_deniedbilling_unavailablerender_failedstorage_failedpersistence_failedupstream_unavailablepayload_too_largerate_limitedoperation_not_foundidempotency_conflictoperation_unavailableoperation_not_readycontract_version_unsupportedinternal_error

    • phasestringrequired

      How far the call got. input and authorization guarantee nothing was rendered, stored, written or charged.

      one ofinputauthorizationresolutionreservationexecutiondeliverypersistence

    • retryablebooleanrequired

      true ⟹ the identical call may succeed later with nothing changed.

    • nextActionstringrequired

      The one move that resolves this, machine-readable.

      one ofnonefix_inputchoose_projectupload_assetsreduce_scopesign_inchoose_planupgrade_planretrywait_and_retrypoll_operationupgrade_clientcontact_support

    • detailsobjectoptional

      Bounded, redacted, code-specific facts (the offending field name, the candidate project ids, the required plan). Never a credential, a signed URL or screenshot bytes.

• panelsarrayoptional

  each item

  one of 3 shapes

  1string

  2ref

  • refstringrequired

  • urlstringrequiredformat uri

  3position

  • positionintegerrequiredmin 1

  • contentIndexintegerrequiredmin 1

  • mimeTypestringrequiredalways "image/png"

  • deliverystringrequired

    one ofimageresource_link

  • refstringoptional

• filenamestringoptional

• bundleIdstringoptional

• panelCountnumberoptional

• zipUrlstringoptionalformat uri

• zipRefstringoptional

• operationIdstringoptional

• statusstringoptional

  one ofacceptedqueuedrunningcancel_requestedsucceededfailedcancelled

• progressobjectoptional

  • completednumberrequired

  • totalnumberrequired

  • panelsCompletednumberoptional

    Panels finished — the number to report to the user.

  • panelsTotalnumberoptional

    Panels this operation will produce.

  • attemptnumberrequired

  • heartbeatAtstring or nulloptional

  • estimatedRemainingSecondsnumberoptional

    About how many seconds of rendering are left. An estimate — say “about”.

• failureanyoptional

Example

That request maps to this call:

{
  "name": "production_operation",
  "arguments": {
    "action": "get",
    "operationId": "THE_OPERATION_ID"
  }
}

The same operation id, its persisted status, how many of your panels are finished with a rough estimate of the rendering left, and its reserved or settled cost.

Access and cost

• Needs an account — specifically the same signed-in ShotOps account that owns the operation.
• Reads and cancellation requests spend no cloud credits. The originating render owns reservation and settlement.

When it refuses

The id is absent, belongs to another account or its project access was revoked.

The same operation_not_found refusal is returned in every case.

The operation is still queued, running or cancelling.

The result action returns persisted state only; poll the same id later.

A retained final asset is no longer active.

Delivery fails without rerendering, restarting or charging again.

Where this fits

• Reconnect-safe production in automation

What the agent is told

The title and description the server publishes on tools/list — this is the copy a model chooses between, reproduced verbatim.