S3 Conditional Writes: Idempotent Agent Artifact Uploads With If-None-Match

// ❌ Blind put — retries and parallel turns clobber
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({});

export async function uploadPatch(sessionId: string, body: string) {
 await s3.send(
 new PutObjectCommand({
 Bucket: process.env.ARTIFACT_BUCKET!,
 Key: `sessions/${sessionId}/patch.diff`,
 Body: body,
 ContentType: "text/plain",
 })
 );
 return { ok: true, key: `sessions/${sessionId}/patch.diff` };
}

// ✅ Idempotent create for a unique artifact key
import {
 S3Client,
 PutObjectCommand,
 GetObjectCommand,
} from "@aws-sdk/client-s3";
import { createHash } from "node:crypto";

const s3 = new S3Client({});
const BUCKET = process.env.ARTIFACT_BUCKET!;

export async function putArtifactOnce(input: {
 key: string;
 body: Buffer | string;
 contentType: string;
 idempotencyKey: string;
}) {
 const bodyBuf = Buffer.isBuffer(input.body)
 ? input.body
 : Buffer.from(input.body, "utf8");
 const checksum = createHash("sha256").update(bodyBuf).digest("hex");

 try {
 const out = await s3.send(
 new PutObjectCommand({
 Bucket: BUCKET,
 Key: input.key,
 Body: bodyBuf,
 ContentType: input.contentType,
 IfNoneMatch: "*", // ✅ create-only
 Metadata: {
 idempotencykey: input.idempotencyKey,
 checksumsha256: checksum,
 },
 })
 );
 return { status: "created" as const, etag: out.ETag, checksum };
 } catch (e: any) {
 if (e?.name === "PreconditionFailed" || e?.$metadata?.httpStatusCode === 412) {
 // Object exists — verify same payload vs true conflict
 const existing = await s3.send(
 new GetObjectCommand({ Bucket: BUCKET, Key: input.key })
 );
 const existingMeta = existing.Metadata ?? {};
 if (
 existingMeta.idempotencykey === input.idempotencyKey ||
 existingMeta.checksumsha256 === checksum
 ) {
 return {
 status: "already_exists_same" as const,
 etag: existing.ETag,
 checksum,
 };
 }
 return {
 status: "conflict" as const,
 etag: existing.ETag,
 checksum,
 };
 }
 throw e;
 }
}

// ✅ Compare-and-swap update
import {
 GetObjectCommand,
 PutObjectCommand,
} from "@aws-sdk/client-s3";

export async function casLatestManifest(
 sessionId: string,
 next: object
): Promise<"ok" | "conflict"> {
 const key = `sessions/${sessionId}/latest.json`;
 const cur = await s3.send(
 new GetObjectCommand({ Bucket: BUCKET, Key: key })
 );
 const etag = cur.ETag;
 if (!etag) return "conflict";

 try {
 await s3.send(
 new PutObjectCommand({
 Bucket: BUCKET,
 Key: key,
 Body: Buffer.from(JSON.stringify(next), "utf8"),
 ContentType: "application/json",
 IfMatch: etag, // ✅ only if nobody else wrote
 })
 );
 return "ok";
 } catch (e: any) {
 if (e?.name === "PreconditionFailed" || e?.$metadata?.httpStatusCode === 412) {
 return "conflict";
 }
 throw e;
 }
}

export const uploadArtifactToolSchema = {
 name: "upload_artifact",
 description: "Upload a session artifact exactly once for this idempotencyKey",
 inputSchema: {
 type: "object",
 additionalProperties: false,
 required: ["sessionId", "kind", "content", "idempotencyKey"],
 properties: {
 sessionId: { type: "string", minLength: 8 },
 kind: { type: "string", enum: ["patch", "log", "build"] },
 content: { type: "string" },
 idempotencyKey: { type: "string", minLength: 8, maxLength: 128 },
 },
 },
} as const;