StagingService
StagingService writes files into a repo. A write has three steps. The caller starts an upload session, stages files, and commits the session. The commit runs as a job.
Content is public, except a draft and a Kit that an OAuth delegation creates. Those are private until the owner publishes them with KitService.SetVisibility. The account comes from the bearer token, never from the request. No RPC returns more than the inline Cat limit of content bytes. Conventions and error codes: see common.proto.
Staging totals count accepted versions, including replaced files. A replay returns the first answer for the same key and request digest. A changed request with that key is refused. Exact logical totals are checked at commit. The newest published version replaces an earlier file at the same path. Cross-call file/directory conflicts fail commit and name both conflicting paths. Per-request limits and the session allocation reservation apply during staging.
A write acts only in the caller's namespace. The server refuses a write with resource_exhausted and a PaymentChallenge when the account's storage is full or its paid term has ended.
Commit
/rpc/uno.kit.v1.StagingService/CommitStarts the commit job for a session. The server signs the commit with the account's key. The first commit creates the repo. The commit is public, unless CommitRequest.draft is true or the credential is an OAuth delegation. Then the repo is private from its first moment, and only the owner can make it public. Commit resolves exact-path replacements by publication order. It rejects file/directory conflicts with both paths and enforces exact aggregate limits. Maps the MCP tool uno_commit.
Header Parameters
Request Body
application/jsonstringThe commit message must contain a non-whitespace character. At most 65536 UTF-8 bytes; NUL is forbidden. Whitespace follows Unicode White_Space. Accepted text stays unchanged. Empty, whitespace-only or NUL text fails with invalid_argument before admission. Excess bytes fail with failed_precondition and one LimitExceeded detail.
stringThe commit id that the branch must have now. Empty requires that the branch does not exist. A mismatch fails with failed_precondition when the call runs and again when the job runs.
string[]Paths to remove from the tree of the current head. The session may also stage files. A path that is not in the tree fails with invalid_argument. Delete paths consume the same launch budgets as staged paths: 20000 unique non-root directories and 8388608 UTF-8 path bytes per commit. Exceeding a declared budget fails with failed_precondition and one LimitExceeded detail.
booleanTrue makes the commit a private draft. It is valid only when the commit creates the repo. A commit to a repo that exists fails with invalid_argument. The owner publishes the draft with one SetVisibility call. A commit with an OAuth delegation is always a private draft, whatever this field says.
Responses
stringThe status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
canceledunknowninvalid_argumentdeadline_exceedednot_foundstringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
FinalizeUpload
/rpc/uno.kit.v1.StagingService/FinalizeUploadCompletes the multipart upload from the parts that the server lists, and polls bounded manifest import steps. The caller sends no part list or ETag. Commit requires UPLOAD_STATE_COMPLETE for an uploaded body. A call before every part arrived fails with failed_precondition. Maps the MCP tool uno_upload_finalize.
Header Parameters
Request Body
application/jsonstringPoll with the same key. Retry with the same key to recover the original completion. A finalize before every part arrived fails with failed_precondition and leaves the session ready for the missing parts. Send them, then finalize again. The server lists the parts itself. Clients return no ETag.
Responses
stringUPLOAD_STATE_UNSPECIFIEDUPLOAD_STATE_PENDINGUPLOAD_STATE_COMPLETEUPLOAD_STATE_FAILEDinteger <int32>Files staged so far at this answer, including replaced versions. Exact logical totals are determined at commit. Replays return the first answer.
string <int64>Content bytes staged so far at this answer, including replaced versions. Exact logical totals are determined at commit. Replays return the first answer.
stringThe status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
canceledunknowninvalid_argumentdeadline_exceedednot_foundstringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
GetJobStatus
/rpc/uno.kit.v1.StagingService/GetJobStatusReads the state of a commit job or a remix job. Maps the MCP tool uno_job_status.
Header Parameters
Request Body
Responses
stringJOB_STATE_UNSPECIFIEDJOB_STATE_PACKINGJOB_STATE_UPLOADINGJOB_STATE_COMMITTEDJOB_STATE_FAILEDstringWhy the job failed or needs attention. Empty unless state is JOB_STATE_FAILED or JOB_STATE_NEEDS_ATTENTION.
objectThe error detail for a write that the server refuses until payment. The server sends it with the Connect code resource_exhausted.
stringThe status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
canceledunknowninvalid_argumentdeadline_exceedednot_foundstringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
StageFiles
/rpc/uno.kit.v1.StagingService/StageFilesStages small files from the request body. The files become public when the session is committed. Maps the MCP tool uno_stage_files.
Header Parameters
Request Body
application/jsonobject[]The request carries at most 1048576 decoded bytes of file content in total. TEXT, unspecified bytes, and BASE64 share this limit across all files. Base64 transport overhead does not count. Invalid base64 fails with invalid_argument. Excess decoded bytes fail with failed_precondition and a LimitExceeded detail. Both fail before an engine call. MCP tools retain their smaller context guard. Files must pass path and file/directory validation within this request. Aggregate limits apply exactly at commit after replacement resolution. Launch limits: 20000 unique non-root directories and 8388608 UTF-8 path bytes. A smaller StartUpload declaration also limits the exact commit totals. Per-request limits and the session allocation reservation still apply here.
Responses
integer <int32>Files staged so far at this answer, including replaced versions. Exact logical totals are determined at commit. Replays return the first answer.
string <int64>Content bytes staged so far at this answer, including replaced versions. Exact logical totals are determined at commit. Replays return the first answer.
stringThe status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
canceledunknowninvalid_argumentdeadline_exceedednot_foundstringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
StageUrl
/rpc/uno.kit.v1.StagingService/StageUrlMakes the server fetch a public URL into one path of the session. The file becomes public when the session is committed. The control plane guards the fetch: see StageUrlRequest.url. Maps the MCP tool uno_stage_url.
Header Parameters
Request Body
application/jsonstringA public https URL without credentials, at most 8192 bytes. The control plane
refuses a private, loopback, or link-local address, and a redirect to
such an address. It follows at most 5 redirects. A refused URL fails
with invalid_argument. A synchronous DNS fault fails with not_found.
A synchronous connection or certificate fault fails with failed_precondition.
The server waits up to 5 seconds inline for the fetch to finish.
A fetch still in progress returns PENDING. Repeat the identical request
with its idempotency_key until COMPLETE or FAILED. A background fault
returns FAILED with failure_reason. The control plane caps each fetch at
staging.session_bytes, at most 1073741824 bytes (1 GiB).
Legacy sessions also limit the fetch to their remaining declared room.
A synchronous size refusal fails with failed_precondition and a LimitExceeded detail.
A background refusal returns FAILED instead. An answer of type text/html
is refused unless path
ends in .html or .htm. Aggregate limits apply exactly at commit.
The fetch limit and session allocation reservation apply during staging.
stringOne of ENTRY_MODE_REGULAR or ENTRY_MODE_EXECUTABLE.
ENTRY_MODE_UNSPECIFIEDENTRY_MODE_REGULARENTRY_MODE_EXECUTABLEENTRY_MODE_SYMLINKENTRY_MODE_TREEResponses
integer <int32>Files staged so far at this answer, including replaced versions. Exact logical totals are determined at commit. Replays return the first answer.
string <int64>Content bytes staged so far at this answer, including replaced versions. Exact logical totals are determined at commit. Replays return the first answer.
stringThe Content-Type of the fetched response, as the server sent it. Empty when the server sent none.
stringPENDING means the fetch continues in the background. Repeat StageUrl with identical arguments and the same idempotency_key to poll it. COMPLETE permits Commit. UNSPECIFIED from an older server also means complete.
UPLOAD_STATE_UNSPECIFIEDUPLOAD_STATE_PENDINGUPLOAD_STATE_COMPLETEUPLOAD_STATE_FAILEDstringThe status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
canceledunknowninvalid_argumentdeadline_exceedednot_foundstringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
StartUpload
/rpc/uno.kit.v1.StagingService/StartUploadOpens an upload session for one branch. For an existing repo, the server checks only that storage has room. For a new repo, it checks declared_bytes. With default_declared_bytes, a new repo checks upload_bytes, or only that storage has room. Commit checks the exact added bytes against the quota. A full quota fails with resource_exhausted and a PaymentChallenge. A replay of an existing session is not checked again. Everything in the session becomes public when it is committed. Maps the MCP tool uno_upload_start.
Header Parameters
Request Body
application/jsonstring <int64>The control plane enforces the configured session ceiling, at most 1073741824 bytes (1 GiB). GetCapabilities reports it as staging.session_bytes. Exact logical totals are checked at commit. A declaration above that ceiling fails with failed_precondition and a LimitExceeded detail. A negative value fails with invalid_argument. Set default_declared_bytes instead to take the default ceiling.
integer <int32>The logical file ceiling, checked exactly at commit. At most 3000. A larger declaration fails with failed_precondition and a LimitExceeded detail. A negative value fails with invalid_argument.
integer | nullOptional logical directory ceiling, checked exactly at commit. Launch allows at most 20000 unique non-root directories per session. Omission uses the launch ceiling. A larger declaration fails with failed_precondition and a LimitExceeded detail. A negative declaration fails with invalid_argument.
string | nullOptional UTF-8 file path byte ceiling. Launch allows at most 8388608 bytes (8 MiB) per session. At commit, count distinct file paths, including separators. Replacement does not add path bytes. Omission uses the launch ceiling. A larger declaration fails with failed_precondition and a LimitExceeded detail. A negative declaration fails with invalid_argument.
stringUnspecified selects one file. Tar bodies contain relative folder paths.
UPLOAD_FORMAT_UNSPECIFIEDUPLOAD_FORMAT_FILEUPLOAD_FORMAT_TARstring | nullExact body size. Set it to request presigned part URLs. Omission issues none and makes no S3 call. Tar includes header and padding bytes. Each part URL signs its exact length. A tar body needs it. A file body must fit staging.session_bytes, at most 1073741824 bytes (1 GiB). A tar body must fit staging.upload_tar_bytes: the session ceiling plus 4194304 bytes (4 MiB). GetCapabilities reports both limits. A larger value fails with failed_precondition and a LimitExceeded detail. A tar body is checked against declared_bytes by its extracted size.
stringUnspecified selects regular. Only regular and executable are accepted.
ENTRY_MODE_UNSPECIFIEDENTRY_MODE_REGULARENTRY_MODE_EXECUTABLEENTRY_MODE_SYMLINKENTRY_MODE_TREEbooleanTrue takes the configured session ceiling, at most 1073741824 bytes (1 GiB). declared_bytes must be 0, or the call fails with invalid_argument. The start check covers upload_bytes, or nothing when upload_bytes is omitted. Exact aggregate limits apply at commit. Staging retains per-request limits and the session allocation reservation, including replaced versions. An agent that does not know the size of its content sets it.
Responses
object[]One presigned S3 UploadPart URL for each part that the server has not received yet. Empty without upload_bytes, and once every part arrived. A repeated StartUpload signs only the missing parts while the body is pending and the session is open. A completed, failed, committed, or expired replay returns no URL. Send each part with one PUT of exactly size_bytes, with no other header, then call FinalizeUpload.
string <int64>Unix seconds. Each part URL expires after at most 600 seconds, and never after the session. A URL that is expired or close to expiry needs another StartUpload for a fresh one.
string <int64>The server-selected size of every part except the last. Zero without upload_bytes. Part N starts at (N - 1) * upload_part_bytes. The last part holds the rest of the body. A body of at most this size has exactly one part, however small.
stringCurrent body state. Unspecified when the session has no uploaded body.
UPLOAD_STATE_UNSPECIFIEDUPLOAD_STATE_PENDINGUPLOAD_STATE_COMPLETEUPLOAD_STATE_FAILEDstringCurrent session state: open, committed, or expired. Committed takes precedence over expiry.
stringThe status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
canceledunknowninvalid_argumentdeadline_exceedednot_foundstringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.