@superblocksteam/sdk-api 0.0.15-mcp.2 → 0.0.16-agentcore.0

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/base/decode-worker-binary-response.test.ts

@@ -43,6 +43,20 @@ describe("decodeWorkerBinaryResponse", () => {
     expect(result.byteLength).toBe(0);
   });
 
+  it("decodes a multi-megabyte base64 payload without overflowing the stack", () => {
+    const byteLength = 6 * 1024 * 1024;
+    const payload = Buffer.alloc(byteLength, 7).toString("base64");
+
+    const result = decodeWorkerBinaryResponse({
+      type: "Buffer",
+      data: payload,
+    });
+
+    expect(result.byteLength).toBe(byteLength);
+    expect(result[0]).toBe(7);
+    expect(result[byteLength - 1]).toBe(7);
+  });
+
   it("decodes an empty base64 string to a zero-length Uint8Array", () => {
     const result = decodeWorkerBinaryResponse({ type: "Buffer", data: "" });
 
@@ -62,7 +76,7 @@ describe("decodeWorkerBinaryResponse", () => {
     ).toThrow(RestApiValidationError);
   });
 
-  it.each(["@@@@", "A=BC", "====", "QUI"])(
+  it.each(["@@@@", "A=BC", "====", "QUI", "A===", "AAAA=", "AA==AAAA"])(
     "rejects non-base64 string data %j",
     (data) => {
       expect(() =>

package/src/integrations/base/decode-worker-binary-response.ts

@@ -9,11 +9,16 @@ export { REDACTED_BINARY_RESPONSE_DATA };
 
 // Node's decoder accepts missing and misplaced padding. A worker payload is
 // a canonical padded string, so reject anything else before decoding.
-const BASE64 =
-  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+// A grouped `{4}` repeat overflows V8's regexp backtrack stack around 4MB
+// of base64. A flat class plus a length check accepts the same strings.
+const BASE64_ALPHABET = /^[A-Za-z0-9+/]*={0,2}$/;
+
+function isCanonicalBase64(data: string): boolean {
+  return data.length % 4 === 0 && BASE64_ALPHABET.test(data);
+}
 
 function decodeBase64(data: string): Uint8Array | undefined {
-  if (!BASE64.test(data)) {
+  if (!isCanonicalBase64(data)) {
     return undefined;
   }
   return new Uint8Array(Buffer.from(data, "base64"));

package/src/integrations/base/graphql-integration-client.ts

@@ -6,7 +6,7 @@
  */
 
 import type { PartialMessage } from "@bufbuild/protobuf";
-import { z } from "zod";
+import type { z } from "zod";
 
 import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
 

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

@@ -4,7 +4,7 @@ import { z } from "zod";
 import type { ActionResponseType } from "@superblocksteam/shared";
 
 import { RestApiValidationError } from "../../errors.js";
-import { REST_API_RESPONSE_TYPES } from "../base/types.js";
+import type { REST_API_RESPONSE_TYPES } from "../base/types.js";
 import type { IntegrationConfig } from "../types.js";
 import { RestApiIntegrationPluginClientImpl } from "./client.js";