Prepare. Inspect. Commit.
Work SDK turns a provider mutation into a reviewable value before it becomes a side effect. Integrity, optimistic concurrency, and idempotency each protect a different failure boundary.
Why a protocol?
A direct API call combines intent, provider translation, authorization, and an irreversible effect. Agents are especially vulnerable to retry ambiguity and stale context. Work SDK separates decision time from mutation time.
Prepared plan anatomy
type PreparedWorkChange = {
id: string;
action: "create" | "update" | "comment";
provider: WorkProvider;
targetId?: string;
input: CreateWorkItemInput | UpdateWorkItemInput | AddCommentInput;
current?: WorkItem;
changes: WorkChangeField[];
warnings: WorkWarning[];
summary: string;
expectedRevision?: string;
preparedAt: string;
fingerprint: string;
};Plans are serializable and contain no credentials. The current snapshot explains the diff; expectedRevision makes the later commit conditional.
Integrity fingerprint
The fingerprint covers every signed plan field. If application code or an agent mutates the reviewed input, changes, warnings, target, or revision, commit rejects the plan before any provider request.
The fingerprint detects accidental mutation. It is not a user-authentication signature and should not be treated as one across untrusted boundaries.
Optimistic concurrency
Update and comment plans capture the item's opaque revision. Commit re-reads the item and fails closed if it changed. Adapters also use the provider's strongest available concurrency primitive, such as Azure DevOps' JSON Patch test /rev.
try {
await work.commit(change, { idempotencyKey });
} catch (error) {
if (error instanceof WorkConflictError) {
// Never patch the old plan or force the write.
const replacement = await work.prepareUpdate(change.targetId!, change.input);
return requestApproval(replacement);
}
throw error;
}Idempotency
The default memory store coordinates retries inside one process. Serverless, clustered, and job systems must supply a durable store. Keys should identify the business event, for example github:webhook:delivery-123:comment, not the attempt.
replayed: true.Warnings and approval
Warnings describe lossy mappings, ambiguous values, unsupported fields, or provider limitations. Commit requires acceptWarnings: true when warnings exist, forcing the caller to acknowledge them explicitly.
Acceptance means “the caller reviewed this risk.” It does not make an impossible provider operation possible; an adapter can still reject invalid or unsupported input.