@superblocksteam/sdk-api 2.0.177 → 2.0.178-next.1

package/src/integrations/agentcore/client.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+
+import { RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type { IntegrationConfig } from "../types.js";
+import { AgentCoreClientImpl } from "./client.js";
+
+const TEST_CONFIG: IntegrationConfig = {
+  id: "agentcore-test-id",
+  name: "Triage",
+  pluginId: "agentcore",
+  configuration: {},
+};
+
+const harnessResult = {
+  text: "done",
+  toolCalls: [
+    { name: "lookup", toolUseId: "tool-1", result: "ok", failed: false },
+  ],
+  stopReason: "end_turn",
+};
+
+const replySchema = z.object({ reply: z.string() });
+
+function createClient(result: unknown) {
+  const executeQuery = vi.fn().mockResolvedValue(result);
+  return {
+    client: new AgentCoreClientImpl(TEST_CONFIG, executeQuery),
+    executeQuery,
+  };
+}
+
+describe("AgentCoreClientImpl", () => {
+  it("sends a harness prompt and returns the result without its kind tag", async () => {
+    const harness = createClient({ kind: "harness", ...harnessResult });
+    const result = await harness.client.invokeHarness("the ticket", {
+      sessionKey: "ticket-1",
+      label: "Triage",
+    });
+
+    expect(result).toEqual(harnessResult);
+    expect(harness.executeQuery).toHaveBeenCalledWith(
+      { prompt: "the ticket", sessionKey: "ticket-1" },
+      undefined,
+      { label: "Triage" },
+    );
+  });
+
+  it("rejects a harness result without the harness tag", async () => {
+    await expect(
+      createClient(harnessResult).client.invokeHarness("the ticket"),
+    ).rejects.toBeInstanceOf(RestApiValidationError);
+  });
+
+  it("rejects a blank prompt without calling the worker", async () => {
+    const harness = createClient({ kind: "harness", ...harnessResult });
+    await expect(harness.client.invokeHarness("  ")).rejects.toBeInstanceOf(
+      RestApiValidationError,
+    );
+    expect(harness.executeQuery).not.toHaveBeenCalled();
+  });
+
+  it("sends a runtime JSON payload and returns the validated response", async () => {
+    const runtime = createClient({
+      kind: "runtime",
+      response: { reply: "done" },
+    });
+    const reply = await runtime.client.invokeAgentRuntime(
+      { ticket: "the ticket" },
+      replySchema,
+      { contentType: "application/json", accept: "application/json" },
+    );
+
+    expect(reply).toEqual({ reply: "done" });
+    expect(runtime.executeQuery).toHaveBeenCalledWith(
+      {
+        payload: '{"ticket":"the ticket"}',
+        contentType: "application/json",
+        accept: "application/json",
+      },
+      undefined,
+      undefined,
+    );
+  });
+
+  it("rejects a runtime response that misses the schema", async () => {
+    await expect(
+      createClient({
+        kind: "runtime",
+        response: { reply: 1 },
+      }).client.invokeAgentRuntime({ ticket: "the ticket" }, replySchema),
+    ).rejects.toBeInstanceOf(RestApiValidationError);
+  });
+
+  it("rejects a runtime result without the runtime tag", async () => {
+    await expect(
+      createClient({ reply: "done" }).client.invokeAgentRuntime(
+        { ticket: "the ticket" },
+        replySchema,
+      ),
+    ).rejects.toBeInstanceOf(RestApiValidationError);
+  });
+
+  it("rejects a blank runtime payload without calling the worker", async () => {
+    const runtime = createClient({ kind: "runtime", response: {} });
+    await expect(
+      runtime.client.invokeAgentRuntime("  ", replySchema),
+    ).rejects.toBeInstanceOf(RestApiValidationError);
+    expect(runtime.executeQuery).not.toHaveBeenCalled();
+  });
+
+  it("rejects a payload JSON cannot encode without calling the worker", async () => {
+    const runtime = createClient({ kind: "runtime", response: {} });
+    await expect(
+      runtime.client.invokeAgentRuntime(() => "reply", replySchema),
+    ).rejects.toBeInstanceOf(RestApiValidationError);
+    expect(runtime.executeQuery).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    [
+      "a circular object",
+      (() => {
+        const payload: Record<string, unknown> = {};
+        payload.self = payload;
+        return payload;
+      })(),
+    ],
+    ["a BigInt", { count: BigInt(1) }],
+  ])("rejects %s without calling the worker", async (_, payload) => {
+    const runtime = createClient({ kind: "runtime", response: {} });
+    await expect(
+      runtime.client.invokeAgentRuntime(payload, replySchema),
+    ).rejects.toThrow(/Payload cannot be sent as JSON/);
+    await expect(
+      runtime.client.invokeAgentRuntime(payload, replySchema),
+    ).rejects.toBeInstanceOf(RestApiValidationError);
+    expect(runtime.executeQuery).not.toHaveBeenCalled();
+  });
+
+  it("wraps worker failures with the integration name and operation", async () => {
+    const cause = new Error("AccessDeniedException");
+    const executeQuery = vi.fn().mockRejectedValue(cause);
+    const client = new AgentCoreClientImpl(TEST_CONFIG, executeQuery);
+
+    await expect(client.invokeHarness("the ticket")).rejects.toMatchObject({
+      name: "IntegrationError",
+      integrationName: "Triage",
+      operation: "invokeHarness",
+    });
+    const error = await client
+      .invokeAgentRuntime({ ticket: "1" }, replySchema)
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(IntegrationError);
+    expect(error).toMatchObject({ operation: "invokeAgentRuntime" });
+  });
+
+  it("rethrows an IntegrationError from the worker unchanged", async () => {
+    const original = new IntegrationError("Triage", "execute");
+    const executeQuery = vi.fn().mockRejectedValue(original);
+    const client = new AgentCoreClientImpl(TEST_CONFIG, executeQuery);
+
+    await expect(client.invokeHarness("the ticket")).rejects.toBe(original);
+  });
+});

package/src/integrations/agentcore/client.ts

@@ -0,0 +1,168 @@
+/**
+ * Amazon Bedrock AgentCore client.
+ *
+ * The step fields match the worker plugin. They are declared here because the
+ * published types package does not include the plugin yet.
+ */
+
+import { z } from "zod";
+
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type {
+  AgentCoreClient,
+  AgentCoreInvokeAgentRuntimeOptions,
+  AgentCoreInvokeHarnessOptions,
+  AgentCoreInvokeHarnessResult,
+} from "./types.js";
+
+const HarnessResultSchema = z.object({
+  kind: z.literal("harness"),
+  text: z.string(),
+  toolCalls: z.array(
+    z.object({
+      name: z.string(),
+      toolUseId: z.string().optional(),
+      result: z.string(),
+      failed: z.boolean(),
+    }),
+  ),
+  stopReason: z.string(),
+});
+
+const RuntimeResultSchema = z.object({
+  kind: z.literal("runtime"),
+  response: z.unknown(),
+});
+
+function payloadText(payload: unknown): string {
+  if (typeof payload === "string") {
+    return payload;
+  }
+  if (payload === undefined) {
+    return "";
+  }
+  try {
+    return JSON.stringify(payload) ?? "";
+  } catch (error) {
+    throw new RestApiValidationError(
+      `Payload cannot be sent as JSON: ${error instanceof Error ? error.message : String(error)}`,
+      { data: payload, zodError: new z.ZodError([]) },
+    );
+  }
+}
+
+export class AgentCoreClientImpl
+  implements AgentCoreClient, IntegrationClientImpl
+{
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  async invokeHarness(
+    prompt: string,
+    options?: AgentCoreInvokeHarnessOptions,
+  ): Promise<AgentCoreInvokeHarnessResult> {
+    if (prompt.trim() === "") {
+      throw new RestApiValidationError("Prompt is required.", {
+        data: prompt,
+        zodError: new z.ZodError([]),
+      });
+    }
+    const result = await this.run(
+      "invokeHarness",
+      {
+        prompt,
+        ...(options?.sessionKey ? { sessionKey: options.sessionKey } : {}),
+      },
+      options?.label,
+    );
+    const parsed = HarnessResultSchema.safeParse(result);
+    if (!parsed.success) {
+      throw restApiValidationErrorFromZodError(
+        "AgentCore invokeHarness returned an unexpected result",
+        parsed.error,
+        result,
+      );
+    }
+    const { text, toolCalls, stopReason } = parsed.data;
+    return { text, toolCalls, stopReason };
+  }
+
+  async invokeAgentRuntime<T>(
+    payload: unknown,
+    schema: z.ZodType<T>,
+    options?: AgentCoreInvokeAgentRuntimeOptions,
+  ): Promise<T> {
+    const body = payloadText(payload);
+    if (body.trim() === "") {
+      throw new RestApiValidationError("Payload is required.", {
+        data: payload,
+        zodError: new z.ZodError([]),
+      });
+    }
+    const result = await this.run(
+      "invokeAgentRuntime",
+      {
+        payload: body,
+        ...(options?.contentType ? { contentType: options.contentType } : {}),
+        ...(options?.accept ? { accept: options.accept } : {}),
+        ...(options?.sessionKey ? { sessionKey: options.sessionKey } : {}),
+      },
+      options?.label,
+    );
+    const runtime = RuntimeResultSchema.safeParse(result);
+    if (!runtime.success) {
+      throw restApiValidationErrorFromZodError(
+        "AgentCore invokeAgentRuntime returned an unexpected result",
+        runtime.error,
+        result,
+      );
+    }
+    const parsed = schema.safeParse(runtime.data.response);
+    if (!parsed.success) {
+      throw restApiValidationErrorFromZodError(
+        "AgentCore runtime response failed validation",
+        parsed.error,
+        runtime.data.response,
+      );
+    }
+    return parsed.data;
+  }
+
+  private async run(
+    operation: string,
+    request: Record<string, unknown>,
+    label: string | undefined,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(request, undefined, trace(label));
+    } catch (error) {
+      if (error instanceof IntegrationError) {
+        throw error;
+      }
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+}
+
+function trace(label: string | undefined): TraceMetadata | undefined {
+  return label ? { label } : undefined;
+}

package/src/integrations/agentcore/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "agentcore",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/agentcore/index.ts

@@ -0,0 +1,8 @@
+export type {
+  AgentCoreClient,
+  AgentCoreInvokeAgentRuntimeOptions,
+  AgentCoreInvokeHarnessOptions,
+  AgentCoreInvokeHarnessResult,
+  AgentCoreToolCall,
+} from "./types.js";
+export { AgentCoreClientImpl } from "./client.js";

package/src/integrations/agentcore/types.ts

@@ -0,0 +1,56 @@
+import type { z } from "zod";
+
+import type { BaseIntegrationClient } from "../../types.js";
+
+/** One tool the harness ran while answering. */
+export interface AgentCoreToolCall {
+  name: string;
+  toolUseId?: string;
+  result: string;
+  failed: boolean;
+}
+
+/** What a harness call returns after the stream finishes. */
+export interface AgentCoreInvokeHarnessResult {
+  text: string;
+  toolCalls: AgentCoreToolCall[];
+  stopReason: string;
+}
+
+export interface AgentCoreInvokeHarnessOptions {
+  /** Stable key for this conversation. Omitted keys get a new session on each call. */
+  sessionKey?: string;
+  /** Shown in the Trace View. */
+  label?: string;
+}
+
+export interface AgentCoreInvokeAgentRuntimeOptions {
+  sessionKey?: string;
+  /** Defaults to application/json on the worker when omitted. */
+  contentType?: string;
+  /** Response content type to request. Defaults to application/json on the worker. */
+  accept?: string;
+  label?: string;
+}
+
+export interface AgentCoreClient extends BaseIntegrationClient {
+  /**
+   * Call a harness agent with a prompt.
+   * The integration's agent ARN must be a harness ARN.
+   */
+  invokeHarness(
+    prompt: string,
+    options?: AgentCoreInvokeHarnessOptions,
+  ): Promise<AgentCoreInvokeHarnessResult>;
+
+  /**
+   * Call a runtime agent with a payload and validate the response.
+   * Objects are sent as JSON. A string is sent unchanged.
+   * The integration's agent ARN must be a runtime ARN.
+   */
+  invokeAgentRuntime<T>(
+    payload: unknown,
+    schema: z.ZodType<T>,
+    options?: AgentCoreInvokeAgentRuntimeOptions,
+  ): Promise<T>;
+}

package/src/integrations/declarations.ts

@@ -31,6 +31,7 @@
  * ```
  */
 
+import type { AgentCoreClient } from "./agentcore/index.js";
 import type { AirtableClient } from "./airtable/index.js";
 import type { AnthropicClient } from "./anthropic/index.js";
 import type { AsanaClient } from "./asana/index.js";
@@ -339,6 +340,9 @@ export type SnowflakePostgresRef = IntegrationRef<
 /** Reference to an SMTP integration */
 export type SmtpRef = IntegrationRef<"smtp", SmtpClient>;
 
+/** Reference to an Amazon Bedrock AgentCore integration */
+export type AgentCoreRef = IntegrationRef<"agentcore", AgentCoreClient>;
+
 /** Reference to an MCP Server integration */
 export type McpIntegrationRef = IntegrationRef<"mcpintegration", McpClient>;
 
@@ -1043,6 +1047,18 @@ export function smtp<T extends string>(id: LiteralString<T>): SmtpRef {
   return createRef<"smtp", SmtpClient, T>("smtp", id);
 }
 
+/**
+ * Declare an Amazon Bedrock AgentCore integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function agentcore<T extends string>(
+  id: LiteralString<T>,
+): AgentCoreRef {
+  return createRef<"agentcore", AgentCoreClient, T>("agentcore", id);
+}
+
 /**
  * Declare an MCP Server integration.
  *

package/src/integrations/index.ts

@@ -65,6 +65,7 @@ export {
   bigquery,
   mongodb,
   dynamodb,
+  agentcore,
   cosmosdb,
   s3,
   gcs,
@@ -145,6 +146,7 @@ export {
   type LakebaseRef,
   type SnowflakePostgresRef,
   type SmtpRef,
+  type AgentCoreRef,
   type McpIntegrationRef,
   type RestApiIntegrationRef,
 } from "./declarations.js";
@@ -368,6 +370,14 @@ export type {
   DynamoDBScanOptions,
 } from "./dynamodb/index.js";
 export { DynamoDBClientImpl } from "./dynamodb/index.js";
+export type {
+  AgentCoreClient,
+  AgentCoreInvokeAgentRuntimeOptions,
+  AgentCoreInvokeHarnessOptions,
+  AgentCoreInvokeHarnessResult,
+  AgentCoreToolCall,
+} from "./agentcore/index.js";
+export { AgentCoreClientImpl } from "./agentcore/index.js";
 
 // CosmosDB client
 export type { CosmosDBClient, CosmosDBQueryOptions } from "./cosmosdb/index.js";

package/src/integrations/registry.ts

@@ -5,6 +5,7 @@
  * and provides factory functions for creating clients.
  */
 
+import { AgentCoreClientImpl } from "./agentcore/index.js";
 import { AirtableClientImpl } from "./airtable/index.js";
 import { AnthropicClientImpl } from "./anthropic/index.js";
 import { AsanaClientImpl } from "./asana/index.js";
@@ -127,6 +128,7 @@ export const SUPPORTED_PLUGINS = {
   // REST API integrations
   mongodb: "mongodb",
   dynamodb: "dynamodb",
+  agentcore: "agentcore",
   cosmosdb: "cosmosdb",
   s3: "s3",
   gcs: "gcs",
@@ -382,6 +384,9 @@ export function createClient(
     case SUPPORTED_PLUGINS.dynamodb:
       return new DynamoDBClientImpl(config, executeQuery);
 
+    case SUPPORTED_PLUGINS.agentcore:
+      return new AgentCoreClientImpl(config, executeQuery);
+
     case SUPPORTED_PLUGINS.cosmosdb:
       return new CosmosDBClientImpl(config, executeQuery);
 

package/src/integrations/restapiintegration/client.test.ts

@@ -471,11 +471,11 @@ describe("RestApiIntegrationPluginClientImpl", () => {
         workerBufferPayload(PDF_BYTES),
       );
 
-      // @ts-expect-error binary responses do not take a response schema
       const withResponse = binaryClient.apiRequest(
         {
           method: "GET",
           path: "/file.pdf",
+          // @ts-expect-error binary responses do not take a response schema
           responseType: "binary",
         },
         { response: z.instanceof(Uint8Array) },

package/src/integrations/snowflake/types.ts

@@ -6,7 +6,7 @@
 
 import type { z } from "zod";
 
-import type { BaseIntegrationClient } from "../../types";
+import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
 /**