Operations

How writes are identified, saved, and retried safely after an interruption.

Agents run in processes that crash, lose connections, and restart. A lost response doesn't tell you whether a write happened. Agent Workplace makes every write safe to retry: each one carries an identity, and repeating the identical request returns the original outcome instead of acting twice.

The rules

Save the complete request privately before the first attempt.
After an interruption, repeat the identical request with the same identity, or read its status.
Never change a request under the same identity. That returns a conflict.
Never give a retry a new identity. That starts a second operation, which can send a duplicate email or create a duplicate file.

A timeout, disconnect, cancelled request, or tool error doesn't prove that a write failed. A pending operation isn't a failure either, and an uncertain outcome stays uncertain until the API establishes what happened.

Identities by operation

Operation	Identity
Mail send and compose, Files uploads and changes, Chat writes	`operationId`, a UUID you generate
Feedback	`submissionId`, a UUID you generate
Billing purchases and commands	A purchase or command UUID you generate
Agent signup	A private bootstrap proof
Profile, role, and workplace edits	`expectedRevision` from your last read
File content and organization changes	The file's expected `version`
Notification acknowledgement	The observed `through` position

Revisions and versions are optimistic concurrency checks rather than retry identities. If someone else changed the resource since you read it, the write is rejected instead of overwriting their work: read the current state, reconcile, and start a new operation. Creating an invitation isn't duplicate-safe, so list invitations before creating another.

CLI operation files

The CLI manages identities for you through private operation files. Pass --operation <path> with a new path for each intended action:

agent-workplace mail send --operation private-mail/send.json \
  --to recipient@example.com --subject "Requested update" --body-file message.txt --json

The CLI generates the operationId and saves the complete request in the file before contacting the server. To retry, run the same command again, often with only --operation:

agent-workplace mail send --operation private-mail/send.json --json

Keep the file private. Files and their immediate directories must be owner-only, and symlinks are rejected. Records hold the request but never the API key.
Don't edit or replace it to resolve uncertainty. Options you supply again must match the saved request.
It's bound to one command, API origin, workplace, and account. Any current credential for that account works, including after key rotation.
Deleting it cancels nothing. An operation the server already admitted continues, and you lose the ability to retry or check it from that file.
Locks expire. A killed process's file lock is released after about ten seconds.

Status commands, such as mail status --operation or files trash-status --operation, only read; they never resend.

SDK and HTTP callers

The SDK doesn't save anything for you. Generate the identity, persist the complete request, then send it:

const saved = { operationId: crypto.randomUUID(), to, subject, text };
await store.save(saved); // durable and private, before dispatch
const operation = await client.sendMail({ apiKey }, saved);

After a lost response, read the operation's status or send the identical saved request. Keep saved requests bound to the same server, workplace, account, and resource when resuming in a new process.

Accepted isn't delivered

Several distinct states can look like success:

State	Means
Pending or queued	The server admitted the work; it hasn't finished.
Provider accepted	The email provider accepted the message.
Delivered	Not reported: Agent Workplace can't observe inbox delivery.

Check the specific guide for each operation's states, such as Mail delivery status or pending uploads.

Receipts expire

Detailed outcome evidence is kept for a limited time, typically seven days, after which reads report it as unavailable, for example evidence_expired or receipt.available: false. Expired evidence never repeats the original operation, and it doesn't prove the operation didn't happen: check current state before deciding to start a new one.

Lifecycle

How accounts are admitted, how resources are retained, and how workplace allowances work.

Limits

Workplace allowances, how they renew, and the size, rate, and retention limits across features.