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

package/dist/conversation/durable-hosted-conversation-turn-service.js

@@ -0,0 +1,273 @@
+import dayjs from 'dayjs';
+import { z } from 'zod';
+import { isExecutionHostTerminalEvent, } from '../contracts/index.js';
+import { ExecutionHostInvocationCancelledError, ExecutionHostProtocolError, ExecutionHostRejectedError, ExecutionHostStreamInterruptedError, } from '../http-sse/index.js';
+import { HostedConversationAcceptedTurnSchema, HostedConversationExpiredTurnReconciliationSchema, HostedConversationRequestedTurnSchema, HostedConversationTurnSettlementSchema, } from './lifecycle-types.js';
+import { HostedConversationTurnInputSchema } from './types.js';
+const DEFAULT_MAX_SUMMARY_CHARACTERS = 100_000;
+const DEFAULT_EXPIRED_TURN_GRACE_MS = 60_000;
+const LifecycleOptionsSchema = z.object({
+    maxSummaryCharacters: z.number().int().positive().max(1_000_000),
+    expiredTurnGraceMs: z.number().int().nonnegative().max(86_400_000),
+}).strict();
+const MODEL_FAILURE_CODE = {
+    authentication: 'model_authentication',
+    permission: 'model_permission',
+    quota: 'model_quota',
+    rate_limit: 'model_rate_limit',
+    context_window: 'model_context_window',
+    request: 'model_request',
+    transport: 'model_transport',
+    empty_response: 'model_empty_response',
+    unknown: 'model_unknown',
+};
+/**
+ * Applies one reusable durable lifecycle around an Execution Host turn.
+ *
+ * Requested state is written before execution starts. Accepted and terminal
+ * writes complete before their corresponding public events are released. A
+ * persistence failure therefore fails closed instead of acknowledging state
+ * that the adopter cannot later recover.
+ */
+export class DurableHostedConversationTurnService {
+    #turns;
+    #store;
+    #maxSummaryCharacters;
+    #expiredTurnGraceMs;
+    #now;
+    constructor(config, options = {}) {
+        const lifecycle = LifecycleOptionsSchema.parse({
+            maxSummaryCharacters: config.maxSummaryCharacters
+                ?? DEFAULT_MAX_SUMMARY_CHARACTERS,
+            expiredTurnGraceMs: config.expiredTurnGraceMs
+                ?? DEFAULT_EXPIRED_TURN_GRACE_MS,
+        });
+        this.#turns = config.turns;
+        this.#store = config.store;
+        this.#maxSummaryCharacters = lifecycle.maxSummaryCharacters;
+        this.#expiredTurnGraceMs = lifecycle.expiredTurnGraceMs;
+        this.#now = options.now ?? (() => new Date());
+    }
+    async *streamTurn(rawInput) {
+        const input = HostedConversationTurnInputSchema.parse(rawInput);
+        const scope = Object.freeze({ ...input.scope });
+        const turn = { ...input, scope };
+        const identity = {
+            invocationId: turn.invocationId,
+            scope,
+        };
+        await this.#store.createTurn(HostedConversationRequestedTurnSchema.parse({
+            ...identity,
+            prompt: turn.prompt,
+            ...(turn.deadlineAt ? { deadlineAt: turn.deadlineAt } : {}),
+            requestedAt: this.#now().toISOString(),
+        }));
+        let persistenceState = 'open';
+        let streamAccepted = false;
+        const settle = async (settlement) => {
+            persistenceState = 'settling';
+            await this.#store.settleTurn(HostedConversationTurnSettlementSchema.parse({
+                ...identity,
+                ...settlement,
+            }));
+            persistenceState = 'settled';
+        };
+        try {
+            turn.signal?.throwIfAborted();
+            for await (const event of this.#turns.streamTurn(turn)) {
+                if (event.kind === 'accepted') {
+                    if (streamAccepted) {
+                        throw new ExecutionHostProtocolError('Hosted turn emitted more than one accepted event.');
+                    }
+                    try {
+                        await this.#store.recordAccepted(HostedConversationAcceptedTurnSchema.parse({
+                            ...identity,
+                            runId: event.runId,
+                            acceptedAt: event.timestamp,
+                        }));
+                    }
+                    catch (error) {
+                        persistenceState = 'write_failed';
+                        throw error;
+                    }
+                    streamAccepted = true;
+                    yield event;
+                    continue;
+                }
+                if (!streamAccepted) {
+                    throw new ExecutionHostProtocolError('Hosted turn emitted data before its accepted event.');
+                }
+                if (isExecutionHostTerminalEvent(event)) {
+                    const projection = projectTerminalEvent(event, this.#maxSummaryCharacters);
+                    await settle({
+                        ...projection.settlement,
+                        settledAt: event.timestamp,
+                    });
+                    yield projection.event;
+                    return;
+                }
+                yield event;
+            }
+            if (!streamAccepted) {
+                throw new ExecutionHostProtocolError('Hosted turn stream omitted its accepted event.');
+            }
+            if (persistenceState === 'open') {
+                await settle({
+                    status: 'interrupted',
+                    failureCode: 'stream_ended_without_terminal',
+                    settledAt: this.#now().toISOString(),
+                });
+            }
+        }
+        catch (error) {
+            if (persistenceState === 'open') {
+                await settle({
+                    ...projectThrownFailure(error, turn.signal),
+                    settledAt: this.#now().toISOString(),
+                });
+            }
+            throw error;
+        }
+        finally {
+            // Returning from a consumer closes an async generator without throwing.
+            // Settle that still-open invocation before releasing the managed stream.
+            if (persistenceState === 'open') {
+                await settle({
+                    status: 'interrupted',
+                    failureCode: 'stream_ended_without_terminal',
+                    settledAt: this.#now().toISOString(),
+                });
+            }
+        }
+    }
+    /** Reconciles only expired open turns within one already-authorized scope. */
+    interruptExpiredTurns(scope) {
+        return interruptExpiredHostedConversationTurns(this.#store, scope, {
+            expiredTurnGraceMs: this.#expiredTurnGraceMs,
+            now: this.#now,
+        });
+    }
+}
+export function interruptExpiredHostedConversationTurns(store, scope, options = {}) {
+    const { expiredTurnGraceMs } = LifecycleOptionsSchema.pick({
+        expiredTurnGraceMs: true,
+    }).parse({
+        expiredTurnGraceMs: options.expiredTurnGraceMs
+            ?? DEFAULT_EXPIRED_TURN_GRACE_MS,
+    });
+    const now = (options.now ?? (() => new Date()))();
+    return store.interruptExpiredTurns(HostedConversationExpiredTurnReconciliationSchema.parse({
+        scope: Object.freeze({ ...scope }),
+        expiredBefore: dayjs(now)
+            .subtract(expiredTurnGraceMs, 'millisecond')
+            .toISOString(),
+        settledAt: now.toISOString(),
+    }));
+}
+export function projectHostedConversationTerminalEvent(event, options = {}) {
+    const { maxSummaryCharacters } = LifecycleOptionsSchema.pick({
+        maxSummaryCharacters: true,
+    }).parse({
+        maxSummaryCharacters: options.maxSummaryCharacters
+            ?? DEFAULT_MAX_SUMMARY_CHARACTERS,
+    });
+    return projectTerminalEvent(event, maxSummaryCharacters);
+}
+function projectTerminalEvent(event, maxSummaryCharacters) {
+    if (event.kind === 'cancelled') {
+        return {
+            event,
+            settlement: {
+                status: 'cancelled',
+                failureCode: 'invocation_cancelled',
+            },
+        };
+    }
+    if (event.kind === 'error') {
+        return {
+            event,
+            settlement: {
+                status: 'failed',
+                failureCode: 'execution_error',
+            },
+        };
+    }
+    const summary = event.result.summary === undefined
+        ? undefined
+        : takeUnicodeCodePoints(event.result.summary, maxSummaryCharacters);
+    const projectedEvent = summary === event.result.summary
+        ? event
+        : {
+            ...event,
+            result: {
+                ...event.result,
+                summary,
+            },
+        };
+    if (event.result.outcome === 'done') {
+        return {
+            event: projectedEvent,
+            settlement: {
+                status: 'completed',
+                ...(summary !== undefined ? { summary } : {}),
+            },
+        };
+    }
+    if (event.result.outcome === 'max_steps') {
+        return {
+            event: projectedEvent,
+            settlement: {
+                status: 'max_steps',
+                ...(summary !== undefined ? { summary } : {}),
+            },
+        };
+    }
+    if (event.result.outcome === 'interrupted') {
+        return {
+            event: projectedEvent,
+            settlement: {
+                status: 'interrupted',
+                ...(summary !== undefined ? { summary } : {}),
+                failureCode: 'execution_interrupted',
+            },
+        };
+    }
+    return {
+        event: projectedEvent,
+        settlement: {
+            status: 'failed',
+            ...(summary !== undefined ? { summary } : {}),
+            failureCode: event.result.failure
+                ? MODEL_FAILURE_CODE[event.result.failure.code]
+                : 'execution_result_error',
+        },
+    };
+}
+function takeUnicodeCodePoints(value, maximum) {
+    let codePoints = 0;
+    let utf16End = 0;
+    for (const codePoint of value) {
+        codePoints += 1;
+        if (codePoints > maximum) {
+            return value.slice(0, utf16End);
+        }
+        utf16End += codePoint.length;
+    }
+    return value;
+}
+function projectThrownFailure(error, signal) {
+    if (error instanceof ExecutionHostStreamInterruptedError) {
+        return { status: 'interrupted', failureCode: 'stream_interrupted' };
+    }
+    if (signal?.aborted || error instanceof ExecutionHostInvocationCancelledError) {
+        return { status: 'interrupted', failureCode: 'invocation_aborted' };
+    }
+    if (error instanceof ExecutionHostProtocolError) {
+        return { status: 'failed', failureCode: 'host_protocol_error' };
+    }
+    if (error instanceof ExecutionHostRejectedError) {
+        return { status: 'failed', failureCode: 'host_rejected' };
+    }
+    return { status: 'failed', failureCode: 'execution_failed' };
+}
+//# sourceMappingURL=durable-hosted-conversation-turn-service.js.map

package/dist/conversation/durable-hosted-conversation-turn-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-hosted-conversation-turn-service.js","sourceRoot":"","sources":["../../src/conversation/durable-hosted-conversation-turn-service.ts"],"names":[],"mappings":"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","sourcesContent":["import dayjs from 'dayjs';\nimport { z } from 'zod';\nimport {\n  isExecutionHostTerminalEvent,\n  type ExecutionHostTerminalEvent,\n} from '../contracts/index.js';\nimport {\n  ExecutionHostInvocationCancelledError,\n  ExecutionHostProtocolError,\n  ExecutionHostRejectedError,\n  ExecutionHostStreamInterruptedError,\n} from '../http-sse/index.js';\nimport {\n  HostedConversationAcceptedTurnSchema,\n  HostedConversationExpiredTurnReconciliationSchema,\n  HostedConversationRequestedTurnSchema,\n  HostedConversationTurnSettlementSchema,\n  type DurableHostedConversationTurnServiceConfig,\n  type DurableHostedConversationTurnServiceOptions,\n  type HostedConversationFailureCode,\n  type HostedConversationPersistenceScope,\n  type HostedConversationTerminalProjection,\n  type HostedConversationTurnIdentity,\n  type HostedConversationTurnLifecycleStore,\n  type HostedConversationTurnReconciliationOptions,\n} from './lifecycle-types.js';\nimport type {\n  HostedConversationTurnRunner,\n} from './types.js';\nimport { HostedConversationTurnInputSchema } from './types.js';\n\nconst DEFAULT_MAX_SUMMARY_CHARACTERS = 100_000;\nconst DEFAULT_EXPIRED_TURN_GRACE_MS = 60_000;\nconst LifecycleOptionsSchema = z.object({\n  maxSummaryCharacters: z.number().int().positive().max(1_000_000),\n  expiredTurnGraceMs: z.number().int().nonnegative().max(86_400_000),\n}).strict();\nconst MODEL_FAILURE_CODE = {\n  authentication: 'model_authentication',\n  permission: 'model_permission',\n  quota: 'model_quota',\n  rate_limit: 'model_rate_limit',\n  context_window: 'model_context_window',\n  request: 'model_request',\n  transport: 'model_transport',\n  empty_response: 'model_empty_response',\n  unknown: 'model_unknown',\n} as const satisfies Record<string, HostedConversationFailureCode>;\ntype PersistenceState = 'open' | 'settling' | 'settled' | 'write_failed';\n\n/**\n * Applies one reusable durable lifecycle around an Execution Host turn.\n *\n * Requested state is written before execution starts. Accepted and terminal\n * writes complete before their corresponding public events are released. A\n * persistence failure therefore fails closed instead of acknowledging state\n * that the adopter cannot later recover.\n */\nexport class DurableHostedConversationTurnService\nimplements HostedConversationTurnRunner {\n  readonly #turns: HostedConversationTurnRunner;\n  readonly #store: DurableHostedConversationTurnServiceConfig['store'];\n  readonly #maxSummaryCharacters: number;\n  readonly #expiredTurnGraceMs: number;\n  readonly #now: () => Date;\n\n  constructor(\n    config: DurableHostedConversationTurnServiceConfig,\n    options: DurableHostedConversationTurnServiceOptions = {},\n  ) {\n    const lifecycle = LifecycleOptionsSchema.parse({\n      maxSummaryCharacters: config.maxSummaryCharacters\n        ?? DEFAULT_MAX_SUMMARY_CHARACTERS,\n      expiredTurnGraceMs: config.expiredTurnGraceMs\n        ?? DEFAULT_EXPIRED_TURN_GRACE_MS,\n    });\n    this.#turns = config.turns;\n    this.#store = config.store;\n    this.#maxSummaryCharacters = lifecycle.maxSummaryCharacters;\n    this.#expiredTurnGraceMs = lifecycle.expiredTurnGraceMs;\n    this.#now = options.now ?? (() => new Date());\n  }\n\n  async *streamTurn(\n    rawInput: Parameters<HostedConversationTurnRunner['streamTurn']>[0],\n  ): ReturnType<HostedConversationTurnRunner['streamTurn']> {\n    const input = HostedConversationTurnInputSchema.parse(rawInput);\n    const scope = Object.freeze({ ...input.scope });\n    const turn = { ...input, scope };\n    const identity: HostedConversationTurnIdentity = {\n      invocationId: turn.invocationId,\n      scope,\n    };\n    await this.#store.createTurn(HostedConversationRequestedTurnSchema.parse({\n      ...identity,\n      prompt: turn.prompt,\n      ...(turn.deadlineAt ? { deadlineAt: turn.deadlineAt } : {}),\n      requestedAt: this.#now().toISOString(),\n    }));\n\n    let persistenceState: PersistenceState = 'open';\n    let streamAccepted = false;\n    const settle = async (\n      settlement: HostedConversationTerminalProjection['settlement'] & {\n        settledAt: string;\n      },\n    ): Promise<void> => {\n      persistenceState = 'settling';\n      await this.#store.settleTurn(HostedConversationTurnSettlementSchema.parse({\n        ...identity,\n        ...settlement,\n      }));\n      persistenceState = 'settled';\n    };\n\n    try {\n      turn.signal?.throwIfAborted();\n      for await (const event of this.#turns.streamTurn(turn)) {\n        if (event.kind === 'accepted') {\n          if (streamAccepted) {\n            throw new ExecutionHostProtocolError(\n              'Hosted turn emitted more than one accepted event.',\n            );\n          }\n          try {\n            await this.#store.recordAccepted(\n              HostedConversationAcceptedTurnSchema.parse({\n                ...identity,\n                runId: event.runId,\n                acceptedAt: event.timestamp,\n              }),\n            );\n          } catch (error) {\n            persistenceState = 'write_failed';\n            throw error;\n          }\n          streamAccepted = true;\n          yield event;\n          continue;\n        }\n        if (!streamAccepted) {\n          throw new ExecutionHostProtocolError(\n            'Hosted turn emitted data before its accepted event.',\n          );\n        }\n        if (isExecutionHostTerminalEvent(event)) {\n          const projection = projectTerminalEvent(\n            event,\n            this.#maxSummaryCharacters,\n          );\n          await settle({\n            ...projection.settlement,\n            settledAt: event.timestamp,\n          });\n          yield projection.event;\n          return;\n        }\n        yield event;\n      }\n\n      if (!streamAccepted) {\n        throw new ExecutionHostProtocolError(\n          'Hosted turn stream omitted its accepted event.',\n        );\n      }\n      if (persistenceState === 'open') {\n        await settle({\n          status: 'interrupted',\n          failureCode: 'stream_ended_without_terminal',\n          settledAt: this.#now().toISOString(),\n        });\n      }\n    } catch (error) {\n      if (persistenceState === 'open') {\n        await settle({\n          ...projectThrownFailure(error, turn.signal),\n          settledAt: this.#now().toISOString(),\n        });\n      }\n      throw error;\n    } finally {\n      // Returning from a consumer closes an async generator without throwing.\n      // Settle that still-open invocation before releasing the managed stream.\n      if (persistenceState === 'open') {\n        await settle({\n          status: 'interrupted',\n          failureCode: 'stream_ended_without_terminal',\n          settledAt: this.#now().toISOString(),\n        });\n      }\n    }\n  }\n\n  /** Reconciles only expired open turns within one already-authorized scope. */\n  interruptExpiredTurns(\n    scope: HostedConversationPersistenceScope,\n  ): Promise<void> {\n    return interruptExpiredHostedConversationTurns(this.#store, scope, {\n      expiredTurnGraceMs: this.#expiredTurnGraceMs,\n      now: this.#now,\n    });\n  }\n}\n\nexport function interruptExpiredHostedConversationTurns(\n  store: HostedConversationTurnLifecycleStore,\n  scope: HostedConversationPersistenceScope,\n  options: HostedConversationTurnReconciliationOptions = {},\n): Promise<void> {\n  const { expiredTurnGraceMs } = LifecycleOptionsSchema.pick({\n    expiredTurnGraceMs: true,\n  }).parse({\n    expiredTurnGraceMs: options.expiredTurnGraceMs\n      ?? DEFAULT_EXPIRED_TURN_GRACE_MS,\n  });\n  const now = (options.now ?? (() => new Date()))();\n  return store.interruptExpiredTurns(\n    HostedConversationExpiredTurnReconciliationSchema.parse({\n      scope: Object.freeze({ ...scope }),\n      expiredBefore: dayjs(now)\n        .subtract(expiredTurnGraceMs, 'millisecond')\n        .toISOString(),\n      settledAt: now.toISOString(),\n    }),\n  );\n}\n\nexport function projectHostedConversationTerminalEvent(\n  event: ExecutionHostTerminalEvent,\n  options: { maxSummaryCharacters?: number } = {},\n): HostedConversationTerminalProjection {\n  const { maxSummaryCharacters } = LifecycleOptionsSchema.pick({\n    maxSummaryCharacters: true,\n  }).parse({\n    maxSummaryCharacters: options.maxSummaryCharacters\n      ?? DEFAULT_MAX_SUMMARY_CHARACTERS,\n  });\n  return projectTerminalEvent(event, maxSummaryCharacters);\n}\n\nfunction projectTerminalEvent(\n  event: ExecutionHostTerminalEvent,\n  maxSummaryCharacters: number,\n): HostedConversationTerminalProjection {\n  if (event.kind === 'cancelled') {\n    return {\n      event,\n      settlement: {\n        status: 'cancelled',\n        failureCode: 'invocation_cancelled',\n      },\n    };\n  }\n  if (event.kind === 'error') {\n    return {\n      event,\n      settlement: {\n        status: 'failed',\n        failureCode: 'execution_error',\n      },\n    };\n  }\n\n  const summary = event.result.summary === undefined\n    ? undefined\n    : takeUnicodeCodePoints(event.result.summary, maxSummaryCharacters);\n  const projectedEvent = summary === event.result.summary\n    ? event\n    : {\n        ...event,\n        result: {\n          ...event.result,\n          summary,\n        },\n      };\n  if (event.result.outcome === 'done') {\n    return {\n      event: projectedEvent,\n      settlement: {\n        status: 'completed',\n        ...(summary !== undefined ? { summary } : {}),\n      },\n    };\n  }\n  if (event.result.outcome === 'max_steps') {\n    return {\n      event: projectedEvent,\n      settlement: {\n        status: 'max_steps',\n        ...(summary !== undefined ? { summary } : {}),\n      },\n    };\n  }\n  if (event.result.outcome === 'interrupted') {\n    return {\n      event: projectedEvent,\n      settlement: {\n        status: 'interrupted',\n        ...(summary !== undefined ? { summary } : {}),\n        failureCode: 'execution_interrupted',\n      },\n    };\n  }\n  return {\n    event: projectedEvent,\n    settlement: {\n      status: 'failed',\n      ...(summary !== undefined ? { summary } : {}),\n      failureCode: event.result.failure\n        ? MODEL_FAILURE_CODE[event.result.failure.code]\n        : 'execution_result_error',\n    },\n  };\n}\n\nfunction takeUnicodeCodePoints(value: string, maximum: number): string {\n  let codePoints = 0;\n  let utf16End = 0;\n  for (const codePoint of value) {\n    codePoints += 1;\n    if (codePoints > maximum) {\n      return value.slice(0, utf16End);\n    }\n    utf16End += codePoint.length;\n  }\n  return value;\n}\n\nfunction projectThrownFailure(\n  error: unknown,\n  signal?: AbortSignal,\n): Extract<\n  HostedConversationTerminalProjection['settlement'],\n  { status: 'failed' | 'interrupted' }\n> {\n  if (error instanceof ExecutionHostStreamInterruptedError) {\n    return { status: 'interrupted', failureCode: 'stream_interrupted' };\n  }\n  if (signal?.aborted || error instanceof ExecutionHostInvocationCancelledError) {\n    return { status: 'interrupted', failureCode: 'invocation_aborted' };\n  }\n  if (error instanceof ExecutionHostProtocolError) {\n    return { status: 'failed', failureCode: 'host_protocol_error' };\n  }\n  if (error instanceof ExecutionHostRejectedError) {\n    return { status: 'failed', failureCode: 'host_rejected' };\n  }\n  return { status: 'failed', failureCode: 'execution_failed' };\n}\n"]}

package/dist/conversation/hosted-conversation-turn-service.d.ts

@@ -0,0 +1,17 @@
+import type { HostedConversationTurnRunner, HostedConversationTurnServiceConfig } from './types.js';
+export declare class HostedConversationConfigurationError extends Error {
+    readonly name = "HostedConversationConfigurationError";
+}
+/**
+ * Provider-neutral application service for one externally hosted turn.
+ *
+ * It binds authority, optional product-tool policy, model credentials, and the
+ * Execution Host stream while leaving product admission and settlement to the
+ * adopter.
+ */
+export declare class HostedConversationTurnService implements HostedConversationTurnRunner {
+    #private;
+    constructor(config: HostedConversationTurnServiceConfig);
+    streamTurn(rawInput: Parameters<HostedConversationTurnRunner['streamTurn']>[0]): ReturnType<HostedConversationTurnRunner['streamTurn']>;
+}
+//# sourceMappingURL=hosted-conversation-turn-service.d.ts.map

package/dist/conversation/hosted-conversation-turn-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-conversation-turn-service.d.ts","sourceRoot":"","sources":["../../src/conversation/hosted-conversation-turn-service.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,4BAA4B,EAC5B,mCAAmC,EACpC,MAAM,YAAY,CAAC;AAGpB,qBAAa,oCAAqC,SAAQ,KAAK;IAC7D,QAAQ,CAAC,IAAI,0CAA0C;CACxD;AAED;;;;;;GAMG;AACH,qBAAa,6BACb,YAAW,4BAA4B;;gBAQzB,MAAM,EAAE,mCAAmC;IAShD,UAAU,CACf,QAAQ,EAAE,UAAU,CAAC,4BAA4B,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAClE,UAAU,CAAC,4BAA4B,CAAC,YAAY,CAAC,CAAC;CAqC1D"}

package/dist/conversation/hosted-conversation-turn-service.js

@@ -0,0 +1,60 @@
+import { CONVERSATION_TURN_WORKFLOW, McpAllowedToolsSchema, } from '../contracts/index.js';
+import { HostedConversationTurnInputSchema } from './types.js';
+export class HostedConversationConfigurationError extends Error {
+    name = 'HostedConversationConfigurationError';
+}
+/**
+ * Provider-neutral application service for one externally hosted turn.
+ *
+ * It binds authority, optional product-tool policy, model credentials, and the
+ * Execution Host stream while leaving product admission and settlement to the
+ * adopter.
+ */
+export class HostedConversationTurnService {
+    #authority;
+    #executionHost;
+    #modelCredentials;
+    #allowedTools;
+    constructor(config) {
+        this.#authority = config.authority;
+        this.#executionHost = config.executionHost;
+        this.#modelCredentials = config.modelCredentials;
+        this.#allowedTools = config.mcp
+            ? Object.freeze(McpAllowedToolsSchema.parse(config.mcp.allowedTools))
+            : undefined;
+    }
+    async *streamTurn(rawInput) {
+        const input = HostedConversationTurnInputSchema.parse(rawInput);
+        input.signal?.throwIfAborted();
+        const issued = await this.#authority.issue({
+            scope: input.scope,
+            runtimeSessionId: input.runtimeSessionId,
+            invocationId: input.invocationId,
+            workflow: CONVERSATION_TURN_WORKFLOW,
+            ...(this.#allowedTools
+                ? { mcp: { allowedTools: this.#allowedTools } }
+                : {}),
+        });
+        const mcpCapability = issued.mcpCapability();
+        if (this.#allowedTools && !mcpCapability) {
+            throw new HostedConversationConfigurationError('Hosted conversation tool policy requires an MCP-capable execution authority.');
+        }
+        const modelApiKey = await this.#modelCredentials.resolveModelApiKey({
+            scope: input.scope,
+            invocationId: input.invocationId,
+            signal: input.signal,
+        });
+        input.signal?.throwIfAborted();
+        yield* this.#executionHost.streamConversationTurn({
+            invocationId: input.invocationId,
+            runtimeSessionId: input.runtimeSessionId,
+            prompt: input.prompt,
+            ...(input.deadlineAt ? { deadlineAt: input.deadlineAt } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+            executionAssertion: issued.executionAssertion(),
+            ...(mcpCapability ? { mcpCapability } : {}),
+            modelApiKey,
+        });
+    }
+}
+//# sourceMappingURL=hosted-conversation-turn-service.js.map

package/dist/conversation/hosted-conversation-turn-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-conversation-turn-service.js","sourceRoot":"","sources":["../../src/conversation/hosted-conversation-turn-service.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,OAAO,oCAAqC,SAAQ,KAAK;IACpD,IAAI,GAAG,sCAAsC,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,OAAO,6BAA6B;IAE/B,UAAU,CAAmD;IAC7D,cAAc,CAAuD;IACrE,iBAAiB,CAExB;IACO,aAAa,CAAgC;IAEtD,YAAY,MAA2C;QACrD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC,gBAAgB,CAAC;QACjD,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,GAAG;YAC7B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,qBAAqB,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACrE,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,CAAC,UAAU,CACf,QAAmE;QAEnE,MAAM,KAAK,GAAG,iCAAiC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChE,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;YACzC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,QAAQ,EAAE,0BAA0B;YACpC,GAAG,CAAC,IAAI,CAAC,aAAa;gBACpB,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE;gBAC/C,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,aAAa,IAAI,CAAC,aAAa,EAAE,CAAC;YACzC,MAAM,IAAI,oCAAoC,CAC5C,8EAA8E,CAC/E,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC;YAClE,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QAE/B,KAAK,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,sBAAsB,CAAC;YAChD,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,EAAE;YAC/C,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import {\n  CONVERSATION_TURN_WORKFLOW,\n  McpAllowedToolsSchema,\n} from '../contracts/index.js';\nimport type {\n  HostedConversationTurnRunner,\n  HostedConversationTurnServiceConfig,\n} from './types.js';\nimport { HostedConversationTurnInputSchema } from './types.js';\n\nexport class HostedConversationConfigurationError extends Error {\n  readonly name = 'HostedConversationConfigurationError';\n}\n\n/**\n * Provider-neutral application service for one externally hosted turn.\n *\n * It binds authority, optional product-tool policy, model credentials, and the\n * Execution Host stream while leaving product admission and settlement to the\n * adopter.\n */\nexport class HostedConversationTurnService\nimplements HostedConversationTurnRunner {\n  readonly #authority: HostedConversationTurnServiceConfig['authority'];\n  readonly #executionHost: HostedConversationTurnServiceConfig['executionHost'];\n  readonly #modelCredentials: HostedConversationTurnServiceConfig[\n    'modelCredentials'\n  ];\n  readonly #allowedTools: readonly string[] | undefined;\n\n  constructor(config: HostedConversationTurnServiceConfig) {\n    this.#authority = config.authority;\n    this.#executionHost = config.executionHost;\n    this.#modelCredentials = config.modelCredentials;\n    this.#allowedTools = config.mcp\n      ? Object.freeze(McpAllowedToolsSchema.parse(config.mcp.allowedTools))\n      : undefined;\n  }\n\n  async *streamTurn(\n    rawInput: Parameters<HostedConversationTurnRunner['streamTurn']>[0],\n  ): ReturnType<HostedConversationTurnRunner['streamTurn']> {\n    const input = HostedConversationTurnInputSchema.parse(rawInput);\n    input.signal?.throwIfAborted();\n    const issued = await this.#authority.issue({\n      scope: input.scope,\n      runtimeSessionId: input.runtimeSessionId,\n      invocationId: input.invocationId,\n      workflow: CONVERSATION_TURN_WORKFLOW,\n      ...(this.#allowedTools\n        ? { mcp: { allowedTools: this.#allowedTools } }\n        : {}),\n    });\n    const mcpCapability = issued.mcpCapability();\n    if (this.#allowedTools && !mcpCapability) {\n      throw new HostedConversationConfigurationError(\n        'Hosted conversation tool policy requires an MCP-capable execution authority.',\n      );\n    }\n\n    const modelApiKey = await this.#modelCredentials.resolveModelApiKey({\n      scope: input.scope,\n      invocationId: input.invocationId,\n      signal: input.signal,\n    });\n    input.signal?.throwIfAborted();\n\n    yield* this.#executionHost.streamConversationTurn({\n      invocationId: input.invocationId,\n      runtimeSessionId: input.runtimeSessionId,\n      prompt: input.prompt,\n      ...(input.deadlineAt ? { deadlineAt: input.deadlineAt } : {}),\n      ...(input.signal ? { signal: input.signal } : {}),\n      executionAssertion: issued.executionAssertion(),\n      ...(mcpCapability ? { mcpCapability } : {}),\n      modelApiKey,\n    });\n  }\n}\n"]}

package/dist/conversation/index.d.ts

@@ -0,0 +1,7 @@
+export { DurableHostedConversationTurnService, interruptExpiredHostedConversationTurns, projectHostedConversationTerminalEvent, } from './durable-hosted-conversation-turn-service.js';
+export { HOSTED_CONVERSATION_CANCELLED_CODES, HOSTED_CONVERSATION_FAILURE_CODES, HOSTED_CONVERSATION_FAILED_CODES, HOSTED_CONVERSATION_INTERRUPTED_CODES, HOSTED_CONVERSATION_TURN_STATUSES, HostedConversationAcceptedTurnSchema, HostedConversationExpiredTurnReconciliationSchema, HostedConversationFailureCodeSchema, HostedConversationPersistenceScopeSchema, HostedConversationRequestedTurnSchema, HostedConversationTurnIdentitySchema, HostedConversationTurnSettlementSchema, HostedConversationTurnStatusSchema, } from './lifecycle-types.js';
+export { HostedConversationConfigurationError, HostedConversationTurnService, } from './hosted-conversation-turn-service.js';
+export type { DurableHostedConversationTurnServiceConfig, DurableHostedConversationTurnServiceOptions, HostedConversationAcceptedTurn, HostedConversationExpiredTurnReconciliation, HostedConversationFailureCode, HostedConversationPersistenceScope, HostedConversationRequestedTurn, HostedConversationTerminalProjection, HostedConversationTerminalStatus, HostedConversationTurnIdentity, HostedConversationTurnLifecycleRecord, HostedConversationTurnLifecycleStore, HostedConversationTurnReconciliationOptions, HostedConversationTurnSettlement, HostedConversationTurnStatus, } from './lifecycle-types.js';
+export { HostedConversationTurnInputSchema } from './types.js';
+export type { HostedConversationCredentialContext, HostedConversationModelCredentialProvider, HostedConversationTurnInput, HostedConversationTurnRunner, HostedConversationTurnServiceConfig, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conversation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oCAAoC,EACpC,uCAAuC,EACvC,sCAAsC,GACvC,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,mCAAmC,EACnC,iCAAiC,EACjC,gCAAgC,EAChC,qCAAqC,EACrC,iCAAiC,EACjC,oCAAoC,EACpC,iDAAiD,EACjD,mCAAmC,EACnC,wCAAwC,EACxC,qCAAqC,EACrC,oCAAoC,EACpC,sCAAsC,EACtC,kCAAkC,GACnC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oCAAoC,EACpC,6BAA6B,GAC9B,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,0CAA0C,EAC1C,2CAA2C,EAC3C,8BAA8B,EAC9B,2CAA2C,EAC3C,6BAA6B,EAC7B,kCAAkC,EAClC,+BAA+B,EAC/B,oCAAoC,EACpC,gCAAgC,EAChC,8BAA8B,EAC9B,qCAAqC,EACrC,oCAAoC,EACpC,2CAA2C,EAC3C,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EACV,mCAAmC,EACnC,yCAAyC,EACzC,2BAA2B,EAC3B,4BAA4B,EAC5B,mCAAmC,GACpC,MAAM,YAAY,CAAC"}

package/dist/conversation/index.js

@@ -0,0 +1,5 @@
+export { DurableHostedConversationTurnService, interruptExpiredHostedConversationTurns, projectHostedConversationTerminalEvent, } from './durable-hosted-conversation-turn-service.js';
+export { HOSTED_CONVERSATION_CANCELLED_CODES, HOSTED_CONVERSATION_FAILURE_CODES, HOSTED_CONVERSATION_FAILED_CODES, HOSTED_CONVERSATION_INTERRUPTED_CODES, HOSTED_CONVERSATION_TURN_STATUSES, HostedConversationAcceptedTurnSchema, HostedConversationExpiredTurnReconciliationSchema, HostedConversationFailureCodeSchema, HostedConversationPersistenceScopeSchema, HostedConversationRequestedTurnSchema, HostedConversationTurnIdentitySchema, HostedConversationTurnSettlementSchema, HostedConversationTurnStatusSchema, } from './lifecycle-types.js';
+export { HostedConversationConfigurationError, HostedConversationTurnService, } from './hosted-conversation-turn-service.js';
+export { HostedConversationTurnInputSchema } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/conversation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conversation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oCAAoC,EACpC,uCAAuC,EACvC,sCAAsC,GACvC,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,mCAAmC,EACnC,iCAAiC,EACjC,gCAAgC,EAChC,qCAAqC,EACrC,iCAAiC,EACjC,oCAAoC,EACpC,iDAAiD,EACjD,mCAAmC,EACnC,wCAAwC,EACxC,qCAAqC,EACrC,oCAAoC,EACpC,sCAAsC,EACtC,kCAAkC,GACnC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oCAAoC,EACpC,6BAA6B,GAC9B,MAAM,uCAAuC,CAAC;AAkB/C,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC","sourcesContent":["export {\n  DurableHostedConversationTurnService,\n  interruptExpiredHostedConversationTurns,\n  projectHostedConversationTerminalEvent,\n} from './durable-hosted-conversation-turn-service.js';\nexport {\n  HOSTED_CONVERSATION_CANCELLED_CODES,\n  HOSTED_CONVERSATION_FAILURE_CODES,\n  HOSTED_CONVERSATION_FAILED_CODES,\n  HOSTED_CONVERSATION_INTERRUPTED_CODES,\n  HOSTED_CONVERSATION_TURN_STATUSES,\n  HostedConversationAcceptedTurnSchema,\n  HostedConversationExpiredTurnReconciliationSchema,\n  HostedConversationFailureCodeSchema,\n  HostedConversationPersistenceScopeSchema,\n  HostedConversationRequestedTurnSchema,\n  HostedConversationTurnIdentitySchema,\n  HostedConversationTurnSettlementSchema,\n  HostedConversationTurnStatusSchema,\n} from './lifecycle-types.js';\nexport {\n  HostedConversationConfigurationError,\n  HostedConversationTurnService,\n} from './hosted-conversation-turn-service.js';\nexport type {\n  DurableHostedConversationTurnServiceConfig,\n  DurableHostedConversationTurnServiceOptions,\n  HostedConversationAcceptedTurn,\n  HostedConversationExpiredTurnReconciliation,\n  HostedConversationFailureCode,\n  HostedConversationPersistenceScope,\n  HostedConversationRequestedTurn,\n  HostedConversationTerminalProjection,\n  HostedConversationTerminalStatus,\n  HostedConversationTurnIdentity,\n  HostedConversationTurnLifecycleRecord,\n  HostedConversationTurnLifecycleStore,\n  HostedConversationTurnReconciliationOptions,\n  HostedConversationTurnSettlement,\n  HostedConversationTurnStatus,\n} from './lifecycle-types.js';\nexport { HostedConversationTurnInputSchema } from './types.js';\nexport type {\n  HostedConversationCredentialContext,\n  HostedConversationModelCredentialProvider,\n  HostedConversationTurnInput,\n  HostedConversationTurnRunner,\n  HostedConversationTurnServiceConfig,\n} from './types.js';\n"]}

package/dist/conversation/lifecycle-types.d.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod';
+import { type ExecutionHostTerminalEvent } from '../contracts/index.js';
+import type { HostedConversationTurnRunner } from './types.js';
+export declare const HOSTED_CONVERSATION_TURN_STATUSES: readonly ["requested", "running", "completed", "max_steps", "failed", "cancelled", "interrupted"];
+export declare const HOSTED_CONVERSATION_FAILED_CODES: readonly ["execution_error", "execution_failed", "execution_result_error", "host_protocol_error", "host_rejected", "model_authentication", "model_context_window", "model_empty_response", "model_permission", "model_quota", "model_rate_limit", "model_request", "model_transport", "model_unknown"];
+export declare const HOSTED_CONVERSATION_INTERRUPTED_CODES: readonly ["deadline_elapsed", "execution_interrupted", "invocation_aborted", "stream_ended_without_terminal", "stream_interrupted"];
+export declare const HOSTED_CONVERSATION_CANCELLED_CODES: readonly ["invocation_cancelled"];
+export declare const HOSTED_CONVERSATION_FAILURE_CODES: readonly ["execution_error", "execution_failed", "execution_result_error", "host_protocol_error", "host_rejected", "model_authentication", "model_context_window", "model_empty_response", "model_permission", "model_quota", "model_rate_limit", "model_request", "model_transport", "model_unknown", "deadline_elapsed", "execution_interrupted", "invocation_aborted", "stream_ended_without_terminal", "stream_interrupted", "invocation_cancelled"];
+export declare const HostedConversationTurnStatusSchema: z.ZodEnum<{
+    max_steps: "max_steps";
+    interrupted: "interrupted";
+    cancelled: "cancelled";
+    requested: "requested";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+}>;
+export declare const HostedConversationFailureCodeSchema: z.ZodEnum<{
+    execution_error: "execution_error";
+    execution_failed: "execution_failed";
+    execution_result_error: "execution_result_error";
+    host_protocol_error: "host_protocol_error";
+    host_rejected: "host_rejected";
+    model_authentication: "model_authentication";
+    model_context_window: "model_context_window";
+    model_empty_response: "model_empty_response";
+    model_permission: "model_permission";
+    model_quota: "model_quota";
+    model_rate_limit: "model_rate_limit";
+    model_request: "model_request";
+    model_transport: "model_transport";
+    model_unknown: "model_unknown";
+    deadline_elapsed: "deadline_elapsed";
+    execution_interrupted: "execution_interrupted";
+    invocation_aborted: "invocation_aborted";
+    stream_ended_without_terminal: "stream_ended_without_terminal";
+    stream_interrupted: "stream_interrupted";
+    invocation_cancelled: "invocation_cancelled";
+}>;
+export declare const HostedConversationPersistenceScopeSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    subjectId: z.ZodString;
+    productSessionId: z.ZodString;
+}, z.core.$strict>;
+export declare const HostedConversationTurnIdentitySchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const HostedConversationRequestedTurnSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    prompt: z.ZodString;
+    deadlineAt: z.ZodOptional<z.ZodISODateTime>;
+    requestedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const HostedConversationAcceptedTurnSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    runId: z.ZodString;
+    acceptedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const HostedConversationTurnSettlementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    settledAt: z.ZodISODateTime;
+    status: z.ZodLiteral<"completed">;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    settledAt: z.ZodISODateTime;
+    status: z.ZodLiteral<"max_steps">;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    settledAt: z.ZodISODateTime;
+    status: z.ZodLiteral<"failed">;
+    summary: z.ZodOptional<z.ZodString>;
+    failureCode: z.ZodEnum<{
+        execution_error: "execution_error";
+        execution_failed: "execution_failed";
+        execution_result_error: "execution_result_error";
+        host_protocol_error: "host_protocol_error";
+        host_rejected: "host_rejected";
+        model_authentication: "model_authentication";
+        model_context_window: "model_context_window";
+        model_empty_response: "model_empty_response";
+        model_permission: "model_permission";
+        model_quota: "model_quota";
+        model_rate_limit: "model_rate_limit";
+        model_request: "model_request";
+        model_transport: "model_transport";
+        model_unknown: "model_unknown";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    settledAt: z.ZodISODateTime;
+    status: z.ZodLiteral<"cancelled">;
+    failureCode: z.ZodLiteral<"invocation_cancelled">;
+}, z.core.$strict>, z.ZodObject<{
+    invocationId: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    settledAt: z.ZodISODateTime;
+    status: z.ZodLiteral<"interrupted">;
+    summary: z.ZodOptional<z.ZodString>;
+    failureCode: z.ZodEnum<{
+        deadline_elapsed: "deadline_elapsed";
+        execution_interrupted: "execution_interrupted";
+        invocation_aborted: "invocation_aborted";
+        stream_ended_without_terminal: "stream_ended_without_terminal";
+        stream_interrupted: "stream_interrupted";
+    }>;
+}, z.core.$strict>], "status">;
+export declare const HostedConversationExpiredTurnReconciliationSchema: z.ZodObject<{
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        subjectId: z.ZodString;
+        productSessionId: z.ZodString;
+    }, z.core.$strict>;
+    expiredBefore: z.ZodISODateTime;
+    settledAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type HostedConversationTurnStatus = z.infer<typeof HostedConversationTurnStatusSchema>;
+export type HostedConversationTerminalStatus = Exclude<HostedConversationTurnStatus, 'requested' | 'running'>;
+export type HostedConversationFailureCode = z.infer<typeof HostedConversationFailureCodeSchema>;
+export type HostedConversationPersistenceScope = z.infer<typeof HostedConversationPersistenceScopeSchema>;
+export type HostedConversationTurnIdentity = z.infer<typeof HostedConversationTurnIdentitySchema>;
+export type HostedConversationRequestedTurn = z.infer<typeof HostedConversationRequestedTurnSchema>;
+export type HostedConversationAcceptedTurn = z.infer<typeof HostedConversationAcceptedTurnSchema>;
+export type HostedConversationTurnSettlement = z.infer<typeof HostedConversationTurnSettlementSchema>;
+export type HostedConversationTurnLifecycleRecord = HostedConversationRequestedTurn & {
+    status: HostedConversationTurnStatus;
+    runId?: string;
+    summary?: string;
+    failureCode?: HostedConversationFailureCode;
+    acceptedAt?: string;
+    settledAt?: string;
+};
+export type HostedConversationExpiredTurnReconciliation = z.infer<typeof HostedConversationExpiredTurnReconciliationSchema>;
+/**
+ * Durable write port for the generic hosted-turn lifecycle.
+ *
+ * Implementations must fence every mutation by invocation and full scope.
+ * Creation rejects every duplicate invocation so a repeated request cannot
+ * start execution twice. Accepted and terminal writes allow only an exact
+ * repeat; conflicting or late transitions must fail atomically. The port
+ * deliberately cannot carry activity, raw errors, credentials, or tool data.
+ */
+export interface HostedConversationTurnLifecycleStore {
+    createTurn(input: HostedConversationRequestedTurn): Promise<void>;
+    recordAccepted(input: HostedConversationAcceptedTurn): Promise<void>;
+    settleTurn(input: HostedConversationTurnSettlement): Promise<void>;
+    interruptExpiredTurns(input: HostedConversationExpiredTurnReconciliation): Promise<void>;
+}
+export type DurableHostedConversationTurnServiceConfig = {
+    turns: HostedConversationTurnRunner;
+    store: HostedConversationTurnLifecycleStore;
+    maxSummaryCharacters?: number;
+    expiredTurnGraceMs?: number;
+};
+export type DurableHostedConversationTurnServiceOptions = {
+    now?: () => Date;
+};
+export type HostedConversationTurnReconciliationOptions = {
+    expiredTurnGraceMs?: number;
+    now?: () => Date;
+};
+type ProjectedSettlement<T> = T extends HostedConversationTurnSettlement ? Omit<T, keyof HostedConversationTurnIdentity | 'settledAt'> : never;
+export type HostedConversationTerminalProjection = {
+    event: ExecutionHostTerminalEvent;
+    settlement: ProjectedSettlement<HostedConversationTurnSettlement>;
+};
+export {};
+//# sourceMappingURL=lifecycle-types.d.ts.map