@heddleagent/execution-host-client 6.0.0-next.0 → 6.1.0

package/README.md

@@ -1,27 +1,27 @@
 # `@heddleagent/execution-host-client`
 
-`@heddleagent/execution-host-client` is the lightweight backend-side SDK for
+`@heddleagent/execution-host-client` is the backend-side SDK for
 products that invoke a separately deployed Heddle Execution Host. It lets an
 adopter keep its own language stack, authentication, database, product policy,
 MCP tools, and UI while reusing the security-sensitive v1 contract machinery.
 
-> **Current availability:** version `6.0.0-next.0` is an unpublished v6
-> prerelease candidate. Until it is published, the stable package remains
-> `@roackb2/heddle-adopter@5.13.0`. Heddle does not currently distribute
+> **Current availability:** stable version `6.1.0`. The former
+> `@roackb2/heddle-adopter@5.13.0` coordinate is deprecated and remains
+> installable only for existing consumers. Heddle does not currently distribute
 > the compatible Execution Host implementation or offer a hosted service. The
 > public surface documents and tests the adopter boundary without implying a
 > generally available deployment.
 
-After npm confirms the `next` dist-tag:
+Install the package:
 
 ```bash
-npm install @heddleagent/execution-host-client@next
+npm install @heddleagent/execution-host-client
 ```
 
-The package does **not** contain Heddle's agent loop, AgentCore deployment,
-Terraform, product MCP tools, or product logic. It uses the official MCP SDK,
-plus `jose`, `zod`, `dayjs`, and `eventsource-parser`, for its optional
-reference edges.
+The package does **not** contain Heddle's agent loop, AgentCore Runtime
+deployment, Terraform, product MCP tools, or product logic. It uses the
+modular AWS SDK for its AgentCore transport and the official MCP SDK, plus
+`jose`, `zod`, `dayjs`, and `eventsource-parser`, for its other edges.
 
 ## What it owns
 
@@ -33,10 +33,11 @@ reference edges.
 | `@heddleagent/execution-host-client/mcp` | Independent capability verification at the adopter's MCP edge |
 | `@heddleagent/execution-host-client/mcp/node` | Stateless official-SDK Streamable HTTP lifecycle around adopter-defined toolsets |
 | `@heddleagent/execution-host-client/http-sse` | Transport-neutral `ExecutionHost` port and strict direct-development HTTP/SSE client |
+| `@heddleagent/execution-host-client/agentcore` | Official AWS AgentCore/SigV4 implementation of the same `ExecutionHost` port |
 | `@heddleagent/execution-host-client/testing` | Node-only loopback v1 fixture plus durable-turn store conformance for real adapters |
 | `@heddleagent/execution-host-client/node` | Optional Node JWKS/conversation HTTP edge plus safe local signing-key helpers |
 
-Non-TypeScript adopters can consume the versioned candidate
+Non-TypeScript adopters can consume the versioned
 [`spec/v1`](spec/v1/README.md) OpenAPI 3.1.1 document, JSON Schema bundle, and
 golden conformance fixtures directly. The
 [`Python v1 conformance reference`](conformance/reference-adopters/python-v1/README.md)
@@ -53,7 +54,8 @@ The adopter still owns:
   allocation, the lifecycle-store implementation/schema/migrations, retention,
   and history queries;
 - implementing and hosting product MCP tools against its own APIs and data;
-- choosing an AgentCore/SigV4 transport, applying results, and rendering UI.
+- choosing and provisioning its AgentCore Runtime, applying results, and
+  rendering UI.
 
 ## Issue one invocation's authority
 
@@ -225,11 +227,32 @@ const productMcp = new NodeStreamableHttpMcpService({
 Use the lower-level `NodeMcpToolset` interface only when a tool needs custom MCP
 content or lifecycle semantics.
 
-## Invoke the direct development host
+## Invoke an Execution Host
 
-The direct client is useful for local and reviewed HTTPS deployments. A
-managed AgentCore deployment should supply a separate SigV4/AWS SDK transport
-which implements the same `ExecutionHost` port.
+Use the official AgentCore client for a Runtime deployed in the adopter's AWS
+account. It uses the normal AWS credential chain, signs the required Heddle
+authority headers, streams the response through the same strict protocol
+validation as the direct client, and deliberately makes only one ambiguous
+streaming attempt.
+
+```ts
+import {
+  AgentCoreExecutionHost,
+} from '@heddleagent/execution-host-client/agentcore'
+
+const host = new AgentCoreExecutionHost({
+  region: process.env.AWS_REGION!,
+  runtimeArn: process.env.AGENTCORE_RUNTIME_ARN!,
+  qualifier: process.env.AGENTCORE_RUNTIME_QUALIFIER,
+})
+```
+
+The product still owns the AWS account, Runtime deployment, IAM policy,
+configuration, and credentials environment. Heddle owns only the reusable
+invocation transport.
+
+For local development and reviewed direct HTTPS deployments, use the direct
+client:
 
 ```ts
 import { DirectHttpExecutionHost } from '@heddleagent/execution-host-client/http-sse'

package/dist/agentcore/agentcore-execution-host.d.ts

@@ -0,0 +1,16 @@
+import { type ExecutionHostStreamEvent } from '../contracts/index.js';
+import { type ExecutionHost, type ExecutionHostConversationTurn } from '../http-sse/index.js';
+import type { AgentCoreExecutionHostConfig } from './types.js';
+/**
+ * Invokes one compatible Heddle Execution Host through AWS AgentCore while
+ * reusing the package's strict request and SSE protocol validation.
+ */
+export declare class AgentCoreExecutionHost implements ExecutionHost {
+    #private;
+    constructor(config: AgentCoreExecutionHostConfig);
+    streamConversationTurn(input: ExecutionHostConversationTurn): AsyncIterable<ExecutionHostStreamEvent>;
+    close(): void;
+}
+export declare const AGENTCORE_FORWARDED_HEADER_NAMES: readonly ["x-heddle-execution-host-assertion", "x-heddle-execution-host-mcp-capability", "x-heddle-execution-host-model-api-key"];
+export declare const AGENTCORE_EXCLUDED_HEADER_NAMES: readonly ["x-heddle-execution-host-local-token"];
+//# sourceMappingURL=agentcore-execution-host.d.ts.map

package/dist/agentcore/agentcore-execution-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore-execution-host.d.ts","sourceRoot":"","sources":["../../src/agentcore/agentcore-execution-host.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,wBAAwB,EAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,6BAA6B,EACnC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,YAAY,CAAC;AAoBpB;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,aAAa;;gBAM9C,MAAM,EAAE,4BAA4B;IAgBhD,sBAAsB,CACpB,KAAK,EAAE,6BAA6B,GACnC,aAAa,CAAC,wBAAwB,CAAC;IAK1C,KAAK,IAAI,IAAI;CAiEd;AAsGD,eAAO,MAAM,gCAAgC,mIAIlC,CAAC;AAEZ,eAAO,MAAM,+BAA+B,kDAEjC,CAAC"}

package/dist/agentcore/agentcore-execution-host.js

@@ -0,0 +1,197 @@
+import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand, } from '@aws-sdk/client-bedrock-agentcore';
+import { HttpRequest } from '@smithy/protocol-http';
+import { AGENTCORE_RUNTIME_SESSION_HEADER, EXECUTION_ASSERTION_HEADER, EXECUTION_HOST_LOCAL_TOKEN_HEADER, MCP_CAPABILITY_HEADER, MODEL_API_KEY_HEADER, } from '../contracts/index.js';
+import { DirectHttpExecutionHost, } from '../http-sse/index.js';
+const CONTENT_TYPE = 'application/json';
+const ACCEPT = 'text/event-stream';
+const MIN_RUNTIME_SESSION_ID_LENGTH = 33;
+const MAX_RUNTIME_SESSION_ID_LENGTH = 256;
+const RUNTIME_SESSION_ID_PATTERN = /^[A-Za-z0-9](?:-*[A-Za-z0-9])+$/;
+const WIRE_BRIDGE_URL = new URL('http://127.0.0.1/agentcore-bridge');
+const NON_FORWARDED_LOCAL_TOKEN = 'agentcore-bridge-token-never-forwarded';
+const SERVICE_ERROR_CODES = new Map([
+    ['AccessDeniedException', 'access_denied'],
+    ['InternalServerException', 'runtime_internal'],
+    ['ResourceNotFoundException', 'runtime_not_found'],
+    ['RetryableConflictException', 'runtime_conflict'],
+    ['RuntimeClientError', 'runtime_client_error'],
+    ['ServiceQuotaExceededException', 'quota_exceeded'],
+    ['ThrottlingException', 'throttled'],
+    ['ValidationException', 'invalid_request'],
+]);
+/**
+ * Invokes one compatible Heddle Execution Host through AWS AgentCore while
+ * reusing the package's strict request and SSE protocol validation.
+ */
+export class AgentCoreExecutionHost {
+    #client;
+    #runtimeArn;
+    #qualifier;
+    #wire;
+    constructor(config) {
+        this.#runtimeArn = config.runtimeArn;
+        this.#qualifier = config.qualifier;
+        this.#client = config.client ?? new BedrockAgentCoreClient({
+            region: config.region,
+            // Invocation settlement is ambiguous after a transport interruption.
+            // Product policy, not the AWS client, decides whether a turn may retry.
+            maxAttempts: 1,
+        });
+        this.#wire = new DirectHttpExecutionHost({
+            baseUrl: WIRE_BRIDGE_URL,
+            localToken: NON_FORWARDED_LOCAL_TOKEN,
+            fetch: (_input, init) => this.#invoke(init),
+        });
+    }
+    streamConversationTurn(input) {
+        assertAgentCoreRuntimeSessionId(input.runtimeSessionId);
+        return this.#wire.streamConversationTurn(input);
+    }
+    close() {
+        this.#client.destroy?.();
+    }
+    async #invoke(init) {
+        if (init?.method !== 'POST' || typeof init.body !== 'string') {
+            throw new Error('AgentCore wire bridge received an invalid request.');
+        }
+        const headers = new Headers(init.headers);
+        const runtimeSessionId = requireHeader(headers, AGENTCORE_RUNTIME_SESSION_HEADER);
+        const customHeaders = Object.fromEntries([
+            [
+                EXECUTION_ASSERTION_HEADER,
+                requireHeader(headers, EXECUTION_ASSERTION_HEADER),
+            ],
+            [MODEL_API_KEY_HEADER, requireHeader(headers, MODEL_API_KEY_HEADER)],
+            ...(headers.has(MCP_CAPABILITY_HEADER)
+                ? [[MCP_CAPABILITY_HEADER, headers.get(MCP_CAPABILITY_HEADER)]]
+                : []),
+        ]);
+        const command = new InvokeAgentRuntimeCommand({
+            agentRuntimeArn: this.#runtimeArn,
+            runtimeSessionId,
+            qualifier: this.#qualifier,
+            contentType: CONTENT_TYPE,
+            accept: ACCEPT,
+            payload: new TextEncoder().encode(init.body),
+        });
+        addSignedCustomHeaders(command, customHeaders);
+        const signal = init.signal ?? undefined;
+        try {
+            const output = await this.#client.send(command, { abortSignal: signal });
+            return new Response(output.response ? toReadableStream(output.response) : null, {
+                status: output.statusCode ?? output.$metadata.httpStatusCode ?? 200,
+                headers: {
+                    'content-type': output.contentType ?? 'application/octet-stream',
+                },
+            });
+        }
+        catch (error) {
+            if (signal?.aborted) {
+                throw error;
+            }
+            const status = readServiceStatus(error);
+            if (!status) {
+                throw error;
+            }
+            const code = SERVICE_ERROR_CODES.get(readErrorName(error)) ?? 'unknown';
+            return new Response(JSON.stringify({
+                error: {
+                    code,
+                    message: 'AgentCore rejected the invocation.',
+                },
+            }), {
+                status,
+                headers: { 'content-type': CONTENT_TYPE },
+            });
+        }
+    }
+}
+function assertAgentCoreRuntimeSessionId(value) {
+    if (value.length < MIN_RUNTIME_SESSION_ID_LENGTH
+        || value.length > MAX_RUNTIME_SESSION_ID_LENGTH
+        || !RUNTIME_SESSION_ID_PATTERN.test(value)) {
+        throw new Error('AgentCore runtime session ID is not provider-compatible.');
+    }
+}
+function addSignedCustomHeaders(command, headers) {
+    command.middlewareStack.add((next) => async (args) => {
+        if (!HttpRequest.isInstance(args.request)) {
+            throw new Error('AgentCore invocation did not produce an HTTP request.');
+        }
+        Object.assign(args.request.headers, headers);
+        return await next(args);
+    }, {
+        step: 'build',
+        priority: 'low',
+        name: 'heddleAgentCoreCustomHeaders',
+    });
+}
+function requireHeader(headers, name) {
+    const value = headers.get(name);
+    if (!value) {
+        throw new Error('AgentCore wire bridge omitted required authority.');
+    }
+    return value;
+}
+function toReadableStream(source) {
+    if (source instanceof Blob) {
+        return source.stream();
+    }
+    if (source instanceof ReadableStream) {
+        return source;
+    }
+    if (!isAsyncIterable(source)) {
+        throw new Error('AgentCore returned an unsupported stream type.');
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const item = await iterator.next();
+                if (item.done) {
+                    controller.close();
+                    return;
+                }
+                if (!(item.value instanceof Uint8Array)) {
+                    throw new Error('AgentCore returned a non-binary stream chunk.');
+                }
+                controller.enqueue(item.value);
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        async cancel() {
+            await iterator.return?.();
+        },
+    });
+}
+function isAsyncIterable(value) {
+    return Boolean(value
+        && typeof value === 'object'
+        && Symbol.asyncIterator in value
+        && typeof value[Symbol.asyncIterator] === 'function');
+}
+function readServiceStatus(error) {
+    if (!error || typeof error !== 'object' || !('$metadata' in error)) {
+        return undefined;
+    }
+    const metadata = error
+        .$metadata;
+    const status = metadata?.httpStatusCode;
+    return typeof status === 'number' && status >= 400 && status <= 599
+        ? status
+        : undefined;
+}
+function readErrorName(error) {
+    return error instanceof Error ? error.name : '';
+}
+export const AGENTCORE_FORWARDED_HEADER_NAMES = Object.freeze([
+    EXECUTION_ASSERTION_HEADER,
+    MCP_CAPABILITY_HEADER,
+    MODEL_API_KEY_HEADER,
+]);
+export const AGENTCORE_EXCLUDED_HEADER_NAMES = Object.freeze([
+    EXECUTION_HOST_LOCAL_TOKEN_HEADER,
+]);
+//# sourceMappingURL=agentcore-execution-host.js.map

package/dist/agentcore/agentcore-execution-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore-execution-host.js","sourceRoot":"","sources":["../../src/agentcore/agentcore-execution-host.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BedrockAgentCoreClient,\n  InvokeAgentRuntimeCommand,\n  type InvokeAgentRuntimeCommandOutput,\n} from '@aws-sdk/client-bedrock-agentcore';\nimport { HttpRequest } from '@smithy/protocol-http';\nimport {\n  AGENTCORE_RUNTIME_SESSION_HEADER,\n  EXECUTION_ASSERTION_HEADER,\n  EXECUTION_HOST_LOCAL_TOKEN_HEADER,\n  MCP_CAPABILITY_HEADER,\n  MODEL_API_KEY_HEADER,\n  type ExecutionHostStreamEvent,\n} from '../contracts/index.js';\nimport {\n  DirectHttpExecutionHost,\n  type ExecutionHost,\n  type ExecutionHostConversationTurn,\n} from '../http-sse/index.js';\nimport type {\n  AgentCoreExecutionHostConfig,\n  AgentCoreRuntimeClient,\n} from './types.js';\n\nconst CONTENT_TYPE = 'application/json';\nconst ACCEPT = 'text/event-stream';\nconst MIN_RUNTIME_SESSION_ID_LENGTH = 33;\nconst MAX_RUNTIME_SESSION_ID_LENGTH = 256;\nconst RUNTIME_SESSION_ID_PATTERN = /^[A-Za-z0-9](?:-*[A-Za-z0-9])+$/;\nconst WIRE_BRIDGE_URL = new URL('http://127.0.0.1/agentcore-bridge');\nconst NON_FORWARDED_LOCAL_TOKEN = 'agentcore-bridge-token-never-forwarded';\nconst SERVICE_ERROR_CODES = new Map<string, string>([\n  ['AccessDeniedException', 'access_denied'],\n  ['InternalServerException', 'runtime_internal'],\n  ['ResourceNotFoundException', 'runtime_not_found'],\n  ['RetryableConflictException', 'runtime_conflict'],\n  ['RuntimeClientError', 'runtime_client_error'],\n  ['ServiceQuotaExceededException', 'quota_exceeded'],\n  ['ThrottlingException', 'throttled'],\n  ['ValidationException', 'invalid_request'],\n]);\n\n/**\n * Invokes one compatible Heddle Execution Host through AWS AgentCore while\n * reusing the package's strict request and SSE protocol validation.\n */\nexport class AgentCoreExecutionHost implements ExecutionHost {\n  readonly #client: AgentCoreRuntimeClient;\n  readonly #runtimeArn: string;\n  readonly #qualifier?: string;\n  readonly #wire: DirectHttpExecutionHost;\n\n  constructor(config: AgentCoreExecutionHostConfig) {\n    this.#runtimeArn = config.runtimeArn;\n    this.#qualifier = config.qualifier;\n    this.#client = config.client ?? new BedrockAgentCoreClient({\n      region: config.region,\n      // Invocation settlement is ambiguous after a transport interruption.\n      // Product policy, not the AWS client, decides whether a turn may retry.\n      maxAttempts: 1,\n    });\n    this.#wire = new DirectHttpExecutionHost({\n      baseUrl: WIRE_BRIDGE_URL,\n      localToken: NON_FORWARDED_LOCAL_TOKEN,\n      fetch: (_input, init) => this.#invoke(init),\n    });\n  }\n\n  streamConversationTurn(\n    input: ExecutionHostConversationTurn,\n  ): AsyncIterable<ExecutionHostStreamEvent> {\n    assertAgentCoreRuntimeSessionId(input.runtimeSessionId);\n    return this.#wire.streamConversationTurn(input);\n  }\n\n  close(): void {\n    this.#client.destroy?.();\n  }\n\n  async #invoke(init?: RequestInit): Promise<Response> {\n    if (init?.method !== 'POST' || typeof init.body !== 'string') {\n      throw new Error('AgentCore wire bridge received an invalid request.');\n    }\n    const headers = new Headers(init.headers);\n    const runtimeSessionId = requireHeader(\n      headers,\n      AGENTCORE_RUNTIME_SESSION_HEADER,\n    );\n    const customHeaders = Object.fromEntries([\n      [\n        EXECUTION_ASSERTION_HEADER,\n        requireHeader(headers, EXECUTION_ASSERTION_HEADER),\n      ],\n      [MODEL_API_KEY_HEADER, requireHeader(headers, MODEL_API_KEY_HEADER)],\n      ...(headers.has(MCP_CAPABILITY_HEADER)\n        ? [[MCP_CAPABILITY_HEADER, headers.get(MCP_CAPABILITY_HEADER)!]]\n        : []),\n    ]);\n    const command = new InvokeAgentRuntimeCommand({\n      agentRuntimeArn: this.#runtimeArn,\n      runtimeSessionId,\n      qualifier: this.#qualifier,\n      contentType: CONTENT_TYPE,\n      accept: ACCEPT,\n      payload: new TextEncoder().encode(init.body),\n    });\n    addSignedCustomHeaders(command, customHeaders);\n    const signal = init.signal ?? undefined;\n\n    try {\n      const output = await this.#client.send(command, { abortSignal: signal });\n      return new Response(\n        output.response ? toReadableStream(output.response) : null,\n        {\n          status: output.statusCode ?? output.$metadata.httpStatusCode ?? 200,\n          headers: {\n            'content-type': output.contentType ?? 'application/octet-stream',\n          },\n        },\n      );\n    } catch (error) {\n      if (signal?.aborted) {\n        throw error;\n      }\n      const status = readServiceStatus(error);\n      if (!status) {\n        throw error;\n      }\n      const code = SERVICE_ERROR_CODES.get(readErrorName(error)) ?? 'unknown';\n      return new Response(JSON.stringify({\n        error: {\n          code,\n          message: 'AgentCore rejected the invocation.',\n        },\n      }), {\n        status,\n        headers: { 'content-type': CONTENT_TYPE },\n      });\n    }\n  }\n}\n\nfunction assertAgentCoreRuntimeSessionId(value: string): void {\n  if (\n    value.length < MIN_RUNTIME_SESSION_ID_LENGTH\n    || value.length > MAX_RUNTIME_SESSION_ID_LENGTH\n    || !RUNTIME_SESSION_ID_PATTERN.test(value)\n  ) {\n    throw new Error('AgentCore runtime session ID is not provider-compatible.');\n  }\n}\n\nfunction addSignedCustomHeaders(\n  command: InvokeAgentRuntimeCommand,\n  headers: Readonly<Record<string, string>>,\n): void {\n  command.middlewareStack.add(\n    (next) => async (args) => {\n      if (!HttpRequest.isInstance(args.request)) {\n        throw new Error('AgentCore invocation did not produce an HTTP request.');\n      }\n      Object.assign(args.request.headers, headers);\n      return await next(args);\n    },\n    {\n      step: 'build',\n      priority: 'low',\n      name: 'heddleAgentCoreCustomHeaders',\n    },\n  );\n}\n\nfunction requireHeader(headers: Headers, name: string): string {\n  const value = headers.get(name);\n  if (!value) {\n    throw new Error('AgentCore wire bridge omitted required authority.');\n  }\n  return value;\n}\n\nfunction toReadableStream(\n  source: NonNullable<InvokeAgentRuntimeCommandOutput['response']>,\n): ReadableStream<Uint8Array> {\n  if (source instanceof Blob) {\n    return source.stream();\n  }\n  if (source instanceof ReadableStream) {\n    return source;\n  }\n  if (!isAsyncIterable(source)) {\n    throw new Error('AgentCore returned an unsupported stream type.');\n  }\n  const iterator = source[Symbol.asyncIterator]();\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        const item = await iterator.next();\n        if (item.done) {\n          controller.close();\n          return;\n        }\n        if (!(item.value instanceof Uint8Array)) {\n          throw new Error('AgentCore returned a non-binary stream chunk.');\n        }\n        controller.enqueue(item.value);\n      } catch (error) {\n        controller.error(error);\n      }\n    },\n    async cancel() {\n      await iterator.return?.();\n    },\n  });\n}\n\nfunction isAsyncIterable(\n  value: unknown,\n): value is AsyncIterable<Uint8Array> {\n  return Boolean(\n    value\n    && typeof value === 'object'\n    && Symbol.asyncIterator in value\n    && typeof value[Symbol.asyncIterator] === 'function',\n  );\n}\n\nfunction readServiceStatus(error: unknown): number | undefined {\n  if (!error || typeof error !== 'object' || !('$metadata' in error)) {\n    return undefined;\n  }\n  const metadata = (error as { $metadata?: { httpStatusCode?: unknown } })\n    .$metadata;\n  const status = metadata?.httpStatusCode;\n  return typeof status === 'number' && status >= 400 && status <= 599\n    ? status\n    : undefined;\n}\n\nfunction readErrorName(error: unknown): string {\n  return error instanceof Error ? error.name : '';\n}\n\nexport const AGENTCORE_FORWARDED_HEADER_NAMES = Object.freeze([\n  EXECUTION_ASSERTION_HEADER,\n  MCP_CAPABILITY_HEADER,\n  MODEL_API_KEY_HEADER,\n] as const);\n\nexport const AGENTCORE_EXCLUDED_HEADER_NAMES = Object.freeze([\n  EXECUTION_HOST_LOCAL_TOKEN_HEADER,\n] as const);\n"]}

package/dist/agentcore/index.d.ts

@@ -0,0 +1,3 @@
+export { AGENTCORE_EXCLUDED_HEADER_NAMES, AGENTCORE_FORWARDED_HEADER_NAMES, AgentCoreExecutionHost, } from './agentcore-execution-host.js';
+export type { AgentCoreExecutionHostConfig, AgentCoreRuntimeClient, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agentcore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agentcore/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,EAChC,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/agentcore/index.js

@@ -0,0 +1,2 @@
+export { AGENTCORE_EXCLUDED_HEADER_NAMES, AGENTCORE_FORWARDED_HEADER_NAMES, AgentCoreExecutionHost, } from './agentcore-execution-host.js';
+//# sourceMappingURL=index.js.map

package/dist/agentcore/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agentcore/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,EAChC,sBAAsB,GACvB,MAAM,+BAA+B,CAAC","sourcesContent":["export {\n  AGENTCORE_EXCLUDED_HEADER_NAMES,\n  AGENTCORE_FORWARDED_HEADER_NAMES,\n  AgentCoreExecutionHost,\n} from './agentcore-execution-host.js';\nexport type {\n  AgentCoreExecutionHostConfig,\n  AgentCoreRuntimeClient,\n} from './types.js';\n"]}

package/dist/agentcore/types.d.ts

@@ -0,0 +1,14 @@
+import type { InvokeAgentRuntimeCommand, InvokeAgentRuntimeCommandOutput } from '@aws-sdk/client-bedrock-agentcore';
+export interface AgentCoreRuntimeClient {
+    send(command: InvokeAgentRuntimeCommand, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<InvokeAgentRuntimeCommandOutput>;
+    destroy?(): void;
+}
+export type AgentCoreExecutionHostConfig = {
+    region: string;
+    runtimeArn: string;
+    qualifier?: string;
+    client?: AgentCoreRuntimeClient;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/agentcore/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agentcore/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,+BAA+B,EAChC,MAAM,mCAAmC,CAAC;AAE3C,MAAM,WAAW,sBAAsB;IACrC,IAAI,CACF,OAAO,EAAE,yBAAyB,EAClC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GACtC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,CAAC"}

package/dist/agentcore/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agentcore/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agentcore/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  InvokeAgentRuntimeCommand,\n  InvokeAgentRuntimeCommandOutput,\n} from '@aws-sdk/client-bedrock-agentcore';\n\nexport interface AgentCoreRuntimeClient {\n  send(\n    command: InvokeAgentRuntimeCommand,\n    options?: { abortSignal?: AbortSignal },\n  ): Promise<InvokeAgentRuntimeCommandOutput>;\n  destroy?(): void;\n}\n\nexport type AgentCoreExecutionHostConfig = {\n  region: string;\n  runtimeArn: string;\n  qualifier?: string;\n  client?: AgentCoreRuntimeClient;\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heddleagent/execution-host-client",
-  "version": "6.0.0-next.0",
+  "version": "6.1.0",
   "description": "Backend contracts, execution authority, lifecycle services, and clients for compatible Heddle Execution Hosts",
   "author": "Jay / Fienna Liang <roackb2@gmail.com>",
   "license": "MIT",
@@ -8,7 +8,7 @@
   "sideEffects": false,
   "publishConfig": {
     "access": "public",
-    "tag": "next",
+    "tag": "latest",
     "registry": "https://registry.npmjs.org/"
   },
   "repository": {
@@ -54,6 +54,10 @@
       "types": "./dist/http-sse/index.d.ts",
       "import": "./dist/http-sse/index.js"
     },
+    "./agentcore": {
+      "types": "./dist/agentcore/index.d.ts",
+      "import": "./dist/agentcore/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
@@ -83,7 +87,9 @@
     "streaming"
   ],
   "dependencies": {
+    "@aws-sdk/client-bedrock-agentcore": "^3.1107.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@smithy/protocol-http": "^5.5.16",
     "dayjs": "^1.11.20",
     "eventsource-parser": "^3.1.0",
     "jose": "^6.2.8",

package/spec/v1/README.md

@@ -1,10 +1,9 @@
 # Execution Host adopter contract v1
 
 This directory is the language-neutral contract for an adopter backend which
-invokes a Heddle-compatible Execution Host. It is included in
-the `@heddleagent/execution-host-client` candidate tarball, but consuming it
-does not require JavaScript or TypeScript. The candidate itself is not yet
-published on npm.
+invokes a Heddle-compatible Execution Host. It is included in the published
+`@heddleagent/execution-host-client` package, but consuming it does not require
+JavaScript or TypeScript.
 
 ## Artifacts
 
@@ -32,7 +31,7 @@ CI and package builds use the non-writing drift check:
 yarn execution-host-client:contract:verify
 ```
 
-The checked-in JSON files are the candidate interoperability artifacts. The
+The checked-in JSON files are the versioned interoperability artifacts. The
 TypeScript Zod schemas remain the reference implementation used to generate
 them. A non-TypeScript adopter should implement the JSON/SSE/JWT contract and
 run the golden fixtures; it should not port Heddle's agent loop.