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

package/dist/testing/request.js

@@ -0,0 +1,140 @@
+import { createHash, timingSafeEqual, } from 'node:crypto';
+import { z } from 'zod';
+import { AGENTCORE_RUNTIME_SESSION_HEADER, EXECUTION_ASSERTION_HEADER, EXECUTION_HOST_LOCAL_TOKEN_HEADER, ExecutionHostConversationTurnRequestSchema, MCP_CAPABILITY_HEADER, MODEL_API_KEY_HEADER, RuntimeSessionIdSchema, } from '../contracts/index.js';
+const MAX_REQUEST_BODY_BYTES = 262_144;
+const REDACTED_HEADER_VALUE = '[REDACTED]';
+const SecretSchema = z.string().min(8).max(4_096);
+const AssertionSchema = z.string().min(32).max(4_096);
+const ErrorCodeSchema = z.string().min(1).max(128).regex(/^[a-z0-9_]+$/);
+export async function parseLocalExecutionHostRequest(request, expectedLocalToken, signal) {
+    const headers = takeInvocationHeaders(request);
+    assertInvocationRoute(request);
+    assertLocalToken(headers.localToken, expectedLocalToken);
+    const runtimeSessionId = parseRequestValue(RuntimeSessionIdSchema, headers.runtimeSessionId, 400, 'invalid_runtime_session');
+    parseRequestValue(AssertionSchema, headers.executionAssertion, 401, 'invalid_execution_identity');
+    parseRequestValue(SecretSchema, headers.modelApiKey, 401, 'invalid_model_credential');
+    const mcpCapability = headers.mcpCapability === undefined
+        ? undefined
+        : parseRequestValue(AssertionSchema, headers.mcpCapability, 401, 'invalid_mcp_capability');
+    const parsedRequest = parseRequestValue(ExecutionHostConversationTurnRequestSchema, await readJsonBody(request, signal), 400, 'invalid_request');
+    return {
+        request: parsedRequest,
+        runtimeSessionId,
+        mcpCapability,
+    };
+}
+export function writeLocalExecutionHostRejection(response, error) {
+    const rejection = error instanceof LocalExecutionHostRequestError
+        ? { status: error.status, code: error.code }
+        : { status: 500, code: 'fixture_internal_error' };
+    const safeCode = ErrorCodeSchema.parse(rejection.code);
+    const body = JSON.stringify({
+        error: {
+            code: safeCode,
+            message: 'Local Execution Host fixture rejected the request.',
+        },
+    });
+    response.writeHead(rejection.status, {
+        'Cache-Control': 'no-store',
+        'Content-Length': Buffer.byteLength(body),
+        'Content-Type': 'application/json; charset=utf-8',
+        'X-Content-Type-Options': 'nosniff',
+    });
+    response.end(body);
+}
+class LocalExecutionHostRequestError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+function takeInvocationHeaders(request) {
+    const extracted = {
+        localToken: extractSensitiveHeader(request, EXECUTION_HOST_LOCAL_TOKEN_HEADER),
+        runtimeSessionId: extractSensitiveHeader(request, AGENTCORE_RUNTIME_SESSION_HEADER),
+        executionAssertion: extractSensitiveHeader(request, EXECUTION_ASSERTION_HEADER),
+        mcpCapability: extractSensitiveHeader(request, MCP_CAPABILITY_HEADER),
+        modelApiKey: extractSensitiveHeader(request, MODEL_API_KEY_HEADER),
+    };
+    if (Object.values(extracted).some((header) => header.duplicate)) {
+        throw new LocalExecutionHostRequestError(400, 'duplicate_sensitive_header');
+    }
+    return Object.fromEntries(Object.entries(extracted).map(([name, header]) => [name, header.value]));
+}
+function extractSensitiveHeader(request, name) {
+    const occurrences = request.rawHeaders.reduce((count, headerName, index) => count
+        + (index % 2 === 0 && headerName.toLowerCase() === name ? 1 : 0), 0);
+    const value = request.headers[name];
+    request.headers[name] = value === undefined
+        ? undefined
+        : REDACTED_HEADER_VALUE;
+    for (let index = 0; index < request.rawHeaders.length; index += 2) {
+        if (request.rawHeaders[index]?.toLowerCase() === name) {
+            request.rawHeaders[index + 1] = REDACTED_HEADER_VALUE;
+        }
+    }
+    return {
+        value: Array.isArray(value) ? undefined : value,
+        duplicate: occurrences > 1 || Array.isArray(value),
+    };
+}
+function assertInvocationRoute(request) {
+    if (request.method !== 'POST') {
+        throw new LocalExecutionHostRequestError(405, 'method_not_allowed');
+    }
+    if (request.url !== '/invocations') {
+        throw new LocalExecutionHostRequestError(404, 'not_found');
+    }
+    const contentType = request.headers['content-type']
+        ?.split(';', 1)[0]
+        ?.trim()
+        .toLowerCase();
+    if (contentType !== 'application/json') {
+        throw new LocalExecutionHostRequestError(415, 'unsupported_media_type');
+    }
+}
+function assertLocalToken(actual, expected) {
+    if (!actual || !constantTimeEqual(actual, expected)) {
+        throw new LocalExecutionHostRequestError(401, 'invalid_local_token');
+    }
+}
+function constantTimeEqual(left, right) {
+    const leftHash = createHash('sha256').update(left).digest();
+    const rightHash = createHash('sha256').update(right).digest();
+    return timingSafeEqual(leftHash, rightHash);
+}
+async function readJsonBody(request, signal) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const rawChunk of request) {
+        signal.throwIfAborted();
+        const chunk = Buffer.isBuffer(rawChunk)
+            ? rawChunk
+            : Buffer.from(rawChunk);
+        totalBytes += chunk.byteLength;
+        if (totalBytes > MAX_REQUEST_BODY_BYTES) {
+            throw new LocalExecutionHostRequestError(413, 'request_too_large');
+        }
+        chunks.push(chunk);
+    }
+    if (totalBytes === 0) {
+        throw new LocalExecutionHostRequestError(400, 'invalid_request');
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks, totalBytes).toString('utf8'));
+    }
+    catch {
+        throw new LocalExecutionHostRequestError(400, 'invalid_request');
+    }
+}
+function parseRequestValue(schema, value, status, code) {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+        throw new LocalExecutionHostRequestError(status, code);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=request.js.map

package/dist/testing/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/testing/request.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  createHash,\n  timingSafeEqual,\n} from 'node:crypto';\nimport type {\n  IncomingMessage,\n  ServerResponse,\n} from 'node:http';\nimport { z } from 'zod';\nimport {\n  AGENTCORE_RUNTIME_SESSION_HEADER,\n  EXECUTION_ASSERTION_HEADER,\n  EXECUTION_HOST_LOCAL_TOKEN_HEADER,\n  ExecutionHostConversationTurnRequestSchema,\n  MCP_CAPABILITY_HEADER,\n  MODEL_API_KEY_HEADER,\n  RuntimeSessionIdSchema,\n  type ExecutionHostConversationTurnRequest,\n} from '../contracts/index.js';\n\nconst MAX_REQUEST_BODY_BYTES = 262_144;\nconst REDACTED_HEADER_VALUE = '[REDACTED]';\nconst SecretSchema = z.string().min(8).max(4_096);\nconst AssertionSchema = z.string().min(32).max(4_096);\nconst ErrorCodeSchema = z.string().min(1).max(128).regex(/^[a-z0-9_]+$/);\n\nexport type ParsedLocalExecutionHostRequest = {\n  request: ExecutionHostConversationTurnRequest;\n  runtimeSessionId: string;\n  mcpCapability?: string;\n};\n\nexport async function parseLocalExecutionHostRequest(\n  request: IncomingMessage,\n  expectedLocalToken: string,\n  signal: AbortSignal,\n): Promise<ParsedLocalExecutionHostRequest> {\n  const headers = takeInvocationHeaders(request);\n  assertInvocationRoute(request);\n  assertLocalToken(headers.localToken, expectedLocalToken);\n  const runtimeSessionId = parseRequestValue(\n    RuntimeSessionIdSchema,\n    headers.runtimeSessionId,\n    400,\n    'invalid_runtime_session',\n  );\n  parseRequestValue(\n    AssertionSchema,\n    headers.executionAssertion,\n    401,\n    'invalid_execution_identity',\n  );\n  parseRequestValue(\n    SecretSchema,\n    headers.modelApiKey,\n    401,\n    'invalid_model_credential',\n  );\n  const mcpCapability = headers.mcpCapability === undefined\n    ? undefined\n    : parseRequestValue(\n      AssertionSchema,\n      headers.mcpCapability,\n      401,\n      'invalid_mcp_capability',\n    );\n  const parsedRequest = parseRequestValue(\n    ExecutionHostConversationTurnRequestSchema,\n    await readJsonBody(request, signal),\n    400,\n    'invalid_request',\n  );\n  return {\n    request: parsedRequest,\n    runtimeSessionId,\n    mcpCapability,\n  };\n}\n\nexport function writeLocalExecutionHostRejection(\n  response: ServerResponse,\n  error: unknown,\n): void {\n  const rejection = error instanceof LocalExecutionHostRequestError\n    ? { status: error.status, code: error.code }\n    : { status: 500, code: 'fixture_internal_error' };\n  const safeCode = ErrorCodeSchema.parse(rejection.code);\n  const body = JSON.stringify({\n    error: {\n      code: safeCode,\n      message: 'Local Execution Host fixture rejected the request.',\n    },\n  });\n  response.writeHead(rejection.status, {\n    'Cache-Control': 'no-store',\n    'Content-Length': Buffer.byteLength(body),\n    'Content-Type': 'application/json; charset=utf-8',\n    'X-Content-Type-Options': 'nosniff',\n  });\n  response.end(body);\n}\n\ntype InvocationHeaders = {\n  localToken: string | undefined;\n  runtimeSessionId: string | undefined;\n  executionAssertion: string | undefined;\n  mcpCapability: string | undefined;\n  modelApiKey: string | undefined;\n};\n\nclass LocalExecutionHostRequestError extends Error {\n  constructor(\n    readonly status: number,\n    readonly code: string,\n  ) {\n    super(code);\n  }\n}\n\nfunction takeInvocationHeaders(request: IncomingMessage): InvocationHeaders {\n  const extracted = {\n    localToken: extractSensitiveHeader(\n      request,\n      EXECUTION_HOST_LOCAL_TOKEN_HEADER,\n    ),\n    runtimeSessionId: extractSensitiveHeader(\n      request,\n      AGENTCORE_RUNTIME_SESSION_HEADER,\n    ),\n    executionAssertion: extractSensitiveHeader(\n      request,\n      EXECUTION_ASSERTION_HEADER,\n    ),\n    mcpCapability: extractSensitiveHeader(request, MCP_CAPABILITY_HEADER),\n    modelApiKey: extractSensitiveHeader(request, MODEL_API_KEY_HEADER),\n  };\n  if (Object.values(extracted).some((header) => header.duplicate)) {\n    throw new LocalExecutionHostRequestError(\n      400,\n      'duplicate_sensitive_header',\n    );\n  }\n  return Object.fromEntries(\n    Object.entries(extracted).map(([name, header]) => [name, header.value]),\n  ) as InvocationHeaders;\n}\n\nfunction extractSensitiveHeader(\n  request: IncomingMessage,\n  name: string,\n): { value: string | undefined; duplicate: boolean } {\n  const occurrences = request.rawHeaders.reduce(\n    (count, headerName, index) => count\n      + (index % 2 === 0 && headerName.toLowerCase() === name ? 1 : 0),\n    0,\n  );\n  const value = request.headers[name];\n  request.headers[name] = value === undefined\n    ? undefined\n    : REDACTED_HEADER_VALUE;\n  for (let index = 0; index < request.rawHeaders.length; index += 2) {\n    if (request.rawHeaders[index]?.toLowerCase() === name) {\n      request.rawHeaders[index + 1] = REDACTED_HEADER_VALUE;\n    }\n  }\n  return {\n    value: Array.isArray(value) ? undefined : value,\n    duplicate: occurrences > 1 || Array.isArray(value),\n  };\n}\n\nfunction assertInvocationRoute(request: IncomingMessage): void {\n  if (request.method !== 'POST') {\n    throw new LocalExecutionHostRequestError(405, 'method_not_allowed');\n  }\n  if (request.url !== '/invocations') {\n    throw new LocalExecutionHostRequestError(404, 'not_found');\n  }\n  const contentType = request.headers['content-type']\n    ?.split(';', 1)[0]\n    ?.trim()\n    .toLowerCase();\n  if (contentType !== 'application/json') {\n    throw new LocalExecutionHostRequestError(\n      415,\n      'unsupported_media_type',\n    );\n  }\n}\n\nfunction assertLocalToken(actual: string | undefined, expected: string): void {\n  if (!actual || !constantTimeEqual(actual, expected)) {\n    throw new LocalExecutionHostRequestError(401, 'invalid_local_token');\n  }\n}\n\nfunction constantTimeEqual(left: string, right: string): boolean {\n  const leftHash = createHash('sha256').update(left).digest();\n  const rightHash = createHash('sha256').update(right).digest();\n  return timingSafeEqual(leftHash, rightHash);\n}\n\nasync function readJsonBody(\n  request: IncomingMessage,\n  signal: AbortSignal,\n): Promise<unknown> {\n  const chunks: Buffer[] = [];\n  let totalBytes = 0;\n  for await (const rawChunk of request) {\n    signal.throwIfAborted();\n    const chunk = Buffer.isBuffer(rawChunk)\n      ? rawChunk\n      : Buffer.from(rawChunk as Uint8Array);\n    totalBytes += chunk.byteLength;\n    if (totalBytes > MAX_REQUEST_BODY_BYTES) {\n      throw new LocalExecutionHostRequestError(413, 'request_too_large');\n    }\n    chunks.push(chunk);\n  }\n  if (totalBytes === 0) {\n    throw new LocalExecutionHostRequestError(400, 'invalid_request');\n  }\n  try {\n    return JSON.parse(Buffer.concat(chunks, totalBytes).toString('utf8'));\n  } catch {\n    throw new LocalExecutionHostRequestError(400, 'invalid_request');\n  }\n}\n\nfunction parseRequestValue<T>(\n  schema: z.ZodType<T>,\n  value: unknown,\n  status: number,\n  code: string,\n): T {\n  const parsed = schema.safeParse(value);\n  if (!parsed.success) {\n    throw new LocalExecutionHostRequestError(status, code);\n  }\n  return parsed.data;\n}\n"]}

package/dist/testing/types.d.ts

@@ -0,0 +1,42 @@
+import type { ExecutionHostConversationTurnRequest, RuntimePublicResult } from '../contracts/index.js';
+/**
+ * One locally admitted invocation. Credentials remain behind explicit methods
+ * so ordinary object inspection and JSON serialization cannot reveal them.
+ */
+export interface LocalExecutionHostInvocation {
+    readonly request: ExecutionHostConversationTurnRequest;
+    readonly runtimeSessionId: string;
+    readonly signal: AbortSignal;
+    mcpCapability(): string | undefined;
+    publishActivity(activity: unknown): Promise<void>;
+    toJSON(): LocalExecutionHostInvocationMetadata;
+}
+export type LocalExecutionHostInvocationMetadata = {
+    schemaVersion: 1;
+    kind: 'conversation-turn';
+    invocationId: string;
+    runtimeSessionId: string;
+};
+export type LocalExecutionHostTerminal = {
+    kind: 'result';
+    result: RuntimePublicResult;
+} | {
+    kind: 'cancelled';
+    reason: string;
+} | {
+    kind: 'error';
+    error: {
+        code: string;
+        message: string;
+    };
+} | {
+    /** End the SSE response without a terminal event to exercise recovery. */
+    kind: 'interrupted';
+};
+export type LocalExecutionHostExecutor = (invocation: LocalExecutionHostInvocation) => LocalExecutionHostTerminal | Promise<LocalExecutionHostTerminal>;
+export type LocalExecutionHostContractFixtureOptions = {
+    execute: LocalExecutionHostExecutor;
+    now?: () => Date;
+    createRunId?: () => string;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/testing/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,oCAAoC,CAAC;IACvD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,aAAa,IAAI,MAAM,GAAG,SAAS,CAAC;IACpC,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,IAAI,oCAAoC,CAAC;CAChD;AAED,MAAM,MAAM,oCAAoC,GAAG;IACjD,aAAa,EAAE,CAAC,CAAC;IACjB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAClC;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC;CAC7B,GACC;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,GACC;IACA,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,GACC;IACA,0EAA0E;IAC1E,IAAI,EAAE,aAAa,CAAC;CACrB,CAAC;AAEJ,MAAM,MAAM,0BAA0B,GAAG,CACvC,UAAU,EAAE,4BAA4B,KACrC,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;AAEtE,MAAM,MAAM,wCAAwC,GAAG;IACrD,OAAO,EAAE,0BAA0B,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B,CAAC"}

package/dist/testing/types.js

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

package/dist/testing/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/testing/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ExecutionHostConversationTurnRequest,\n  RuntimePublicResult,\n} from '../contracts/index.js';\n\n/**\n * One locally admitted invocation. Credentials remain behind explicit methods\n * so ordinary object inspection and JSON serialization cannot reveal them.\n */\nexport interface LocalExecutionHostInvocation {\n  readonly request: ExecutionHostConversationTurnRequest;\n  readonly runtimeSessionId: string;\n  readonly signal: AbortSignal;\n  mcpCapability(): string | undefined;\n  publishActivity(activity: unknown): Promise<void>;\n  toJSON(): LocalExecutionHostInvocationMetadata;\n}\n\nexport type LocalExecutionHostInvocationMetadata = {\n  schemaVersion: 1;\n  kind: 'conversation-turn';\n  invocationId: string;\n  runtimeSessionId: string;\n};\n\nexport type LocalExecutionHostTerminal =\n  | {\n    kind: 'result';\n    result: RuntimePublicResult;\n  }\n  | {\n    kind: 'cancelled';\n    reason: string;\n  }\n  | {\n    kind: 'error';\n    error: {\n      code: string;\n      message: string;\n    };\n  }\n  | {\n    /** End the SSE response without a terminal event to exercise recovery. */\n    kind: 'interrupted';\n  };\n\nexport type LocalExecutionHostExecutor = (\n  invocation: LocalExecutionHostInvocation,\n) => LocalExecutionHostTerminal | Promise<LocalExecutionHostTerminal>;\n\nexport type LocalExecutionHostContractFixtureOptions = {\n  execute: LocalExecutionHostExecutor;\n  now?: () => Date;\n  createRunId?: () => string;\n};\n"]}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@heddleagent/execution-host-client",
+  "version": "6.0.0-next.0",
+  "description": "Backend contracts, execution authority, lifecycle services, and clients for compatible Heddle Execution Hosts",
+  "author": "Jay / Fienna Liang <roackb2@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "next",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roackb2/heddle.git",
+    "directory": "packages/execution-host-client"
+  },
+  "homepage": "https://heddleagent.com",
+  "bugs": {
+    "url": "https://github.com/roackb2/heddle/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts/index.d.ts",
+      "import": "./dist/contracts/index.js"
+    },
+    "./authority": {
+      "types": "./dist/authority/index.d.ts",
+      "import": "./dist/authority/index.js"
+    },
+    "./conversation": {
+      "types": "./dist/conversation/index.d.ts",
+      "import": "./dist/conversation/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    },
+    "./mcp/node": {
+      "types": "./dist/mcp/node/index.d.ts",
+      "import": "./dist/mcp/node/index.js"
+    },
+    "./http-sse": {
+      "types": "./dist/http-sse/index.d.ts",
+      "import": "./dist/http-sse/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./spec/v1/openapi.json": "./spec/v1/openapi.json",
+    "./spec/v1/schema-bundle.json": "./spec/v1/schema-bundle.json",
+    "./spec/v1/fixtures/*": "./spec/v1/fixtures/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "spec",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "backend",
+    "execution-host",
+    "mcp",
+    "sdk",
+    "streaming"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dayjs": "^1.11.20",
+    "eventsource-parser": "^3.1.0",
+    "jose": "^6.2.8",
+    "zod": "^4.3.6"
+  }
+}

package/spec/v1/README.md

@@ -0,0 +1,101 @@
+# 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.
+
+## Artifacts
+
+- `openapi.json` describes the current HTTP/SSE invocation binding.
+- `schema-bundle.json` contains standalone JSON Schema Draft 2020-12
+  definitions for requests, events, JWT claims, protected JWT headers, results,
+  safe API errors, and the optional durable conversation-lifecycle profile.
+- `fixtures/` contains executable examples for valid and invalid requests,
+  complete and interrupted streams, cancellation, sequence validation, and
+  execution/MCP authority. `durable-conversation-lifecycle.json` supplies the
+  shared TypeScript/Python terminal and store-transition vectors.
+- `durable-hosted-conversation-lifecycle.md` defines persistence ordering,
+  transition fencing, safe projection, interruption, and reconciliation for a
+  product-owned lifecycle store.
+
+Generate checked-in artifacts from Heddle's runtime schemas:
+
+```bash
+yarn execution-host-client:contract:generate
+```
+
+CI and package builds use the non-writing drift check:
+
+```bash
+yarn execution-host-client:contract:verify
+```
+
+The checked-in JSON files are the candidate 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.
+
+## Semantic invariants
+
+JSON Schema validates one value at a time. A conforming implementation must
+also enforce these relationships:
+
+1. Credentials are headers, never request-body fields, prompt content, event
+   content, logs, or persisted product state.
+2. The first event is `accepted` with sequence `0`.
+3. Every later event has the same `invocationId` and `runId`, and sequence
+   numbers increase by exactly one.
+4. Exactly one `result`, `cancelled`, or `error` event is terminal and last.
+5. A terminal event is committed only after clean HTTP EOF. EOF without a
+   terminal is ambiguous interruption, never inferred success and never an
+   automatic retry.
+6. The execution assertion uses ES256 and
+   `typ=heddle-execution+jwt`; its `jti` equals `invocationId`.
+7. The optional MCP capability uses ES256 and
+   `typ=heddle-mcp-capability+jwt`; its `jti` is distinct from
+   `invocationId`.
+8. The host binds every duplicated adopter, tenant, subject, product session,
+   runtime session, invocation, and workflow claim across the request and both
+   credentials.
+9. The adopter MCP edge verifies the capability independently, derives scope
+   only from verified claims, rejects unsupported tools, and rechecks expiry
+   before each operation.
+10. `allowedTools` is unique, contains at most 16 collision-free names, and the
+    aggregate tool-name length is at most 512 characters.
+
+The optional durable profile adds control-plane semantics around this stream.
+It does not add a database endpoint to the Execution Host or make product
+records part of the execution plane. See
+[Durable hosted-conversation lifecycle](durable-hosted-conversation-lifecycle.md).
+
+## Deployment bindings
+
+The OpenAPI document names the actual v1 headers so implementations can
+interoperate with the current Execution Host. Two headers are explicitly
+binding-specific:
+
+- `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` carries the logical
+  `runtimeSessionId` in the AgentCore deployment. Another runtime adapter must
+  preserve the same logical value even if its provider uses a different wire
+  mechanism.
+- `X-Heddle-Execution-Host-Local-Token` is only for the direct loopback
+  development binding. Managed AgentCore ingress uses AWS authorization and
+  explicitly forwarded custom headers instead.
+
+The OpenAPI contract does not describe Terraform, image layout, SigV4 calls,
+AWS account identity, or provider lifecycle. Those remain deployment concerns,
+not adopter-domain contracts.
+
+## Compatibility and stop line
+
+Version 1 supports `conversation-turn`. New workflows, transports, or identity
+forms require an explicit contract version decision; they are not silently
+added to this surface.
+
+The repository deliberately stops after this schema, fixture set, the
+TypeScript implementation, and one Python clean-room reference pass. It does
+not promise a gateway, generated clients for every language, or a framework
+starter matrix. Additional adapters should be driven by a real adopter and a
+specific interoperability gap.

package/spec/v1/durable-hosted-conversation-lifecycle.md

@@ -0,0 +1,139 @@
+# Durable hosted-conversation lifecycle profile v1
+
+This optional profile defines the adopter-side state machine around one
+`conversation-turn` invocation. It is language-neutral even though the
+supported TypeScript SDK supplies the ready-made service. Other languages can
+implement the same behavior against their own database by using the versioned
+schemas and `fixtures/durable-conversation-lifecycle.json`.
+
+The profile does not move product data into Heddle. The adopter remains the
+owner of the record, database, authenticated scope, retention, history query,
+and UI. Heddle owns the correctness-sensitive transition and stream-ordering
+rules that should not be independently reinvented by every product.
+
+## Participants
+
+1. **Product admission** authenticates the caller and selects `tenantId`,
+   `subjectId`, `productSessionId`, `runtimeSessionId`, a unique
+   `invocationId`, prompt, and optional deadline.
+2. **Lifecycle service** persists safe checkpoints around an already-composed
+   conversation-turn runner.
+3. **Lifecycle store** implements atomic, scope-fenced transitions in the
+   adopter's database.
+4. **Execution runner** issues authority, invokes the Execution Host, and
+   returns the validated v1 event stream.
+
+Only the Execution Host imports the Heddle runtime in a separate-host
+deployment. The adopter lifecycle service is control-plane code and never
+receives the host workspace or Heddle's private trace state.
+
+## State machine
+
+```mermaid
+stateDiagram-v2
+  [*] --> requested: create unique invocation
+  requested --> running: accepted persisted
+  requested --> failed: dependency or protocol failure
+  requested --> interrupted: abort or ambiguous end
+  running --> completed: result done
+  running --> max_steps: result max_steps
+  running --> failed: error result or failure
+  running --> cancelled: explicit cancelled terminal
+  running --> interrupted: interruption or ambiguous end
+```
+
+`completed`, `max_steps`, `failed`, `cancelled`, and `interrupted` are terminal
+and immutable. A terminal write can be repeated only when every persisted
+field, including `settledAt`, is identical.
+
+### Store transition rules
+
+- `createTurn` rejects every duplicate `invocationId`, including an identical
+  request. This prevents a repeated product request from starting execution
+  twice.
+- Every later mutation is fenced by `invocationId` and the complete tenant,
+  subject, and product-session scope.
+- `recordAccepted` changes `requested` to `running`. An exact repeat with the
+  same `runId` and `acceptedAt` is idempotent while the row is running.
+- Before acceptance, only `failed` or `interrupted` can settle the row.
+- After acceptance, any defined terminal status can settle the row.
+- A wrong-scope, conflicting, or late transition fails atomically. It must not
+  silently update zero rows and report success.
+- Expiry reconciliation changes only open `requested` or `running` rows in the
+  supplied scope whose `deadlineAt` is earlier than `expiredBefore`. It records
+  `interrupted/deadline_elapsed` and never overwrites a terminal row.
+
+The candidate TypeScript conformance helper and Python reference tests execute
+these rules. A real adapter must run them against its actual transactional
+store, not only an in-memory substitute.
+
+## Persistence-before-delivery ordering
+
+The lifecycle service observes this order:
+
+1. validate normalized product input;
+2. persist `requested`;
+3. start the execution runner;
+4. persist `running` before releasing `accepted`;
+5. pass through bounded public activity without persisting it;
+6. project and persist a terminal before releasing that terminal; and
+7. settle an open row as interrupted when the stream throws, ends ambiguously,
+   or is closed by its consumer.
+
+If requested persistence fails, execution does not start. If accepted
+persistence fails, `accepted` is not released. If terminal persistence fails,
+the terminal is not released. A possibly committed write is not blindly
+retried or overwritten; an open row remains eligible for later reconciliation.
+
+The runner must emit one `accepted` event before activity or a terminal. A
+terminal is trustworthy only after the underlying v1 HTTP body reaches clean
+EOF. Duplicate acceptance, terminal-before-acceptance, missing terminal, and
+post-terminal data are protocol failures or ambiguous interruption, never
+success.
+
+## Terminal projection
+
+The durable projection uses the closed statuses and failure codes in the
+versioned schema bundle and golden fixture. Important distinctions are:
+
+- only an explicit `cancelled` terminal becomes `cancelled`;
+- request abort, client disconnect, server shutdown, task cancellation, and
+  local invocation cancellation become `interrupted/invocation_aborted`;
+- clean EOF without a terminal becomes
+  `interrupted/stream_ended_without_terminal`;
+- transport loss becomes `interrupted/stream_interrupted`;
+- arbitrary host error codes and messages become the fixed durable code
+  `execution_error`;
+- model failures map only through the fixed public model-code allowlist; and
+- unknown thrown errors become `failed/execution_failed` without storing their
+  messages or types.
+
+Summary bounds count Unicode code points, not UTF-8 bytes or UTF-16 code units.
+The exact same bounded summary is released live and sent to the store, so a
+reload cannot silently show different content from the live turn.
+
+## Data allowed across the store port
+
+The lifecycle store may receive only:
+
+- authorized tenant, subject, and product-session scope;
+- invocation ID, prompt, optional deadline, and lifecycle timestamps;
+- accepted run ID; and
+- bounded terminal summary and a closed failure code.
+
+It must never receive activity, tool arguments or results, hidden reasoning,
+raw errors, provider-selected error text, model credentials, execution
+assertions, MCP capabilities, JWTs, traces, or workspace contents.
+
+## Reconciliation and recovery limit
+
+Reconciliation needs a product deadline. A turn without `deadlineAt` is not
+expired by this profile because Heddle cannot invent the product's maximum run
+time. Adopters that require crash convergence should always supply a deadline
+and invoke scoped reconciliation while open rows are visible or from their
+existing scheduler.
+
+This profile deliberately does not define result lookup, stream reconnect,
+replay, automatic retry, billing, history-list limits, or UI polling. Ambiguous
+execution is recorded as interrupted and is never automatically rerun. A
+future lookup/reconnect protocol requires its own explicit contract decision.

package/spec/v1/fixtures/ambiguous-eof.sse

@@ -0,0 +1,9 @@
+id: 0
+event: accepted
+data: {"schemaVersion":1,"invocationId":"invocation-001","runId":"run-001","sequence":0,"timestamp":"2026-08-10T04:00:00.000Z","kind":"accepted"}
+
+id: 1
+event: activity
+data: {"schemaVersion":1,"invocationId":"invocation-001","runId":"run-001","sequence":1,"timestamp":"2026-08-10T04:00:00.000Z","kind":"activity","activity":{"type":"assistant_text_delta","text":"Working."}}
+
+: fixture-clean-eof

package/spec/v1/fixtures/authority.json

@@ -0,0 +1,70 @@
+{
+  "referenceTime": "2026-08-10T04:00:00.000Z",
+  "issuer": "https://api.example.test",
+  "keyId": "test-key-001",
+  "executionAudience": "urn:heddle-execution-host:example",
+  "mcpAudience": "urn:example:mcp",
+  "supportedTools": [
+    "read_snapshot"
+  ],
+  "expected": {
+    "executionClaims": {
+      "iss": "https://api.example.test",
+      "aud": "urn:heddle-execution-host:example",
+      "contractVersion": 1,
+      "adopterId": "example-adopter",
+      "tenantId": "tenant-a",
+      "productSessionId": "product-session-a",
+      "runtimeSessionId": "runtime-session:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "workflow": "conversation-turn",
+      "sub": "subject-a",
+      "jti": "invocation-001",
+      "iat": 1786334400,
+      "exp": 1786334700
+    },
+    "mcpClaims": {
+      "iss": "https://api.example.test",
+      "aud": "urn:example:mcp",
+      "contractVersion": 1,
+      "adopterId": "example-adopter",
+      "tenantId": "tenant-a",
+      "productSessionId": "product-session-a",
+      "runtimeSessionId": "runtime-session:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "workflow": "conversation-turn",
+      "sub": "subject-a",
+      "jti": "capability-001",
+      "iat": 1786334400,
+      "exp": 1786335000,
+      "invocationId": "invocation-001",
+      "serverId": "product_capabilities",
+      "allowedTools": [
+        "read_snapshot"
+      ]
+    }
+  },
+  "invalidMcpCases": [
+    {
+      "id": "expired",
+      "overrides": {
+        "exp": 1786334399
+      },
+      "expected": "invalid"
+    },
+    {
+      "id": "unsupported-tool",
+      "overrides": {
+        "allowedTools": [
+          "delete_workspace"
+        ]
+      },
+      "expected": "invalid"
+    },
+    {
+      "id": "swapped-runtime-session",
+      "overrides": {
+        "runtimeSessionId": "runtime-session:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+      },
+      "expected": "host_binding_invalid"
+    }
+  ]
+}

package/spec/v1/fixtures/cancelled.sse

@@ -0,0 +1,9 @@
+id: 0
+event: accepted
+data: {"schemaVersion":1,"invocationId":"invocation-001","runId":"run-001","sequence":0,"timestamp":"2026-08-10T04:00:00.000Z","kind":"accepted"}
+
+id: 1
+event: cancelled
+data: {"schemaVersion":1,"invocationId":"invocation-001","runId":"run-001","sequence":1,"timestamp":"2026-08-10T04:00:00.000Z","kind":"cancelled","reason":"product_cancelled"}
+
+: fixture-clean-eof