Bedrock Converse toolConfig: Idempotent Tool Results Under Retries

import {
 BedrockRuntimeClient,
 ConverseCommand,
 ToolConfiguration,
} from "@aws-sdk/client-bedrock-runtime";

const toolConfig: ToolConfiguration = {
 tools: [
 {
 toolSpec: {
 name: "apply_patch",
 description:
 "Apply a unified diff to a repo workspace. Safe under retries when idempotencyKey is stable.",
 inputSchema: {
 json: {
 type: "object",
 properties: {
 workspaceId: { type: "string" },
 unifiedDiff: { type: "string" },
 // ✅ Client/model must pass a stable key per logical mutation
 idempotencyKey: {
 type: "string",
 minLength: 8,
 maxLength: 128,
 description: "Stable key for this patch intent (UUID or hash)",
 },
 },
 required: ["workspaceId", "unifiedDiff", "idempotencyKey"],
 additionalProperties: false,
 },
 },
 },
 },
 ],
 toolChoice: { auto: {} },
};

import { createHash } from "crypto";
import {
 DynamoDBClient,
 PutItemCommand,
 GetItemCommand,
} from "@aws-sdk/client-dynamodb";

const ddb = new DynamoDBClient({});
const TABLE = process.env.TOOL_IDEMPOTENCY_TABLE!;

function argsHash(input: Record<string, unknown>): string {
 const { idempotencyKey: _k, ...rest } = input;
 return createHash("sha256").update(JSON.stringify(rest)).digest("hex").slice(0, 32);
}

export async function runApplyPatch(toolUseId: string, input: {
 workspaceId: string;
 unifiedDiff: string;
 idempotencyKey: string;
}) {
 const pk = `tool#apply_patch#${input.idempotencyKey}`;
 const hash = argsHash(input);

 // 1) Fast path: prior success
 const existing = await ddb.send(
 new GetItemCommand({
 TableName: TABLE,
 Key: { pk: { S: pk } },
 })
 );
 if (existing.Item?.status?.S === "SUCCEEDED") {
 if (existing.Item.argsHash?.S !== hash) {
 // ✅ Same key, different args = conflict, do not silently apply
 return {
 toolUseId,
 content: [
 {
 text: JSON.stringify({
 ok: false,
 error: "IdempotencyKeyConflict",
 message: "idempotencyKey reused with different arguments",
 }),
 },
 ],
 status: "error" as const,
 };
 }
 return {
 toolUseId,
 content: [{ json: JSON.parse(existing.Item.resultJson!.S!) }],
 status: "success" as const,
 };
 }

 // 2) Claim in-flight (conditional)
 try {
 await ddb.send(
 new PutItemCommand({
 TableName: TABLE,
 Item: {
 pk: { S: pk },
 status: { S: "IN_FLIGHT" },
 toolUseId: { S: toolUseId },
 argsHash: { S: hash },
 ttl: { N: String(Math.floor(Date.now() / 1000) + 86400) },
 },
 ConditionExpression:
 "attribute_not_exists(pk) OR #s = :failed OR (attribute_exists(ttl) AND ttl < :now)",
 ExpressionAttributeNames: { "#s": "status" },
 ExpressionAttributeValues: {
 ":failed": { S: "FAILED" },
 ":now": { N: String(Math.floor(Date.now() / 1000)) },
 },
 })
 );
 } catch (e: any) {
 if (e?.name === "ConditionalCheckFailedException") {
 // Another worker owns it — wait/poll or return in-progress error for model retry
 return {
 toolUseId,
 content: [{ text: JSON.stringify({ ok: false, error: "InFlight" }) }],
 status: "error" as const,
 };
 }
 throw e;
 }

 // 3) Side effect once
 try {
 const result = await applyDiffOnce(input.workspaceId, input.unifiedDiff);
 await ddb.send(
 new PutItemCommand({
 TableName: TABLE,
 Item: {
 pk: { S: pk },
 status: { S: "SUCCEEDED" },
 toolUseId: { S: toolUseId },
 argsHash: { S: hash },
 resultJson: { S: JSON.stringify(result) },
 ttl: { N: String(Math.floor(Date.now() / 1000) + 7 * 86400) },
 },
 })
 );
 return {
 toolUseId,
 content: [{ json: result }],
 status: "success" as const,
 };
 } catch (err: any) {
 await ddb.send(
 new PutItemCommand({
 TableName: TABLE,
 Item: {
 pk: { S: pk },
 status: { S: "FAILED" },
 toolUseId: { S: toolUseId },
 argsHash: { S: hash },
 error: { S: String(err?.message ?? err) },
 ttl: { N: String(Math.floor(Date.now() / 1000) + 3600) },
 },
 })
 );
 return {
 toolUseId,
 content: [{ text: JSON.stringify({ ok: false, error: "ApplyFailed" }) }],
 status: "error" as const,
 };
 }
}

async function applyDiffOnce(workspaceId: string, unifiedDiff: string) {
 // workspace FS / git apply — must itself be safe if partially applied
 return { workspaceId, filesTouched: 3, ok: true };
}

const bedrock = new BedrockRuntimeClient({});

async function turn(messages: any[]) {
 const res = await bedrock.send(
 new ConverseCommand({
 modelId: "anthropic.claude-3-5-sonnet-20241022-v2:0",
 messages,
 toolConfig,
 })
 );

 const out = res.output?.message;
 if (!out) return res;

 const toolUses = (out.content ?? []).filter((c: any) => c.toolUse);
 if (!toolUses.length) return res;

 const toolResults = [];
 for (const block of toolUses) {
 const tu = block.toolUse!;
 const result = await runApplyPatch(tu.toolUseId!, tu.input as any);
 toolResults.push({
 toolResult: {
 toolUseId: result.toolUseId,
 content: result.content,
 status: result.status,
 },
 });
 }

 // Continue conversation with tool results — same messages array, no duplicate applies
 return turn([
 ...messages,
 out,
 { role: "user", content: toolResults },
 ]);
}

{
 name: "read_file",
 inputSchema: {
 json: {
 type: "object",
 properties: {
 workspaceId: { type: "string" },
 path: { type: "string", maxLength: 512 },
 maxBytes: { type: "integer", minimum: 1, maximum: 100_000 },
 },
 required: ["workspaceId", "path"],
 additionalProperties: false,
 },
 },
}