@xemahq/agent-session-runtime 0.8.0 → 0.9.1

package/src/lib/launch-identity/index.ts

@@ -1,6 +1,8 @@
 export * from './canonical-contract';
 export * from './compiled-session-launch-plan';
 export * from './compiled-session-launch-plan-store';
+export * from './preparation-generation';
+export * from './prepared-launch-variant';
 export * from './runtime-template-key';
 export * from './session-binding';
 export * from './thread-reuse-key';

package/src/lib/launch-identity/preparation-generation.ts

@@ -0,0 +1,171 @@
+import {
+  canonicalContractJson,
+  hashCanonicalContract,
+  requireEnumValue,
+  requireExactObject,
+  requireNonEmptyString,
+  requireNonNegativeSafeInteger,
+  requireSha256,
+} from './canonical-contract';
+
+export enum PreparationGenerationStatus {
+  Validating = 'validating',
+  Materializing = 'materializing',
+  Ready = 'ready',
+  Failed = 'failed',
+  Superseded = 'superseded',
+}
+
+export interface PreparationFailure {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface PreparationGeneration {
+  readonly id: string;
+  readonly agentRevisionId: string;
+  readonly sourceGenerationHash: string;
+  readonly requiredVariantKeyHashes: readonly string[];
+  readonly status: PreparationGenerationStatus;
+  readonly failure?: PreparationFailure;
+  readonly rowVersion: number;
+}
+
+const GENERATION_KEYS = [
+  'id',
+  'agentRevisionId',
+  'sourceGenerationHash',
+  'requiredVariantKeyHashes',
+  'status',
+  'rowVersion',
+] as const;
+const GENERATION_OPTIONAL_KEYS = ['failure'] as const;
+const FAILURE_KEYS = ['code', 'message'] as const;
+const GENERATION_STATUSES = Object.values(PreparationGenerationStatus);
+
+export function createPreparationFailure(input: unknown): PreparationFailure {
+  const object = requireExactObject(input, 'PreparationFailure', FAILURE_KEYS);
+  return Object.freeze({
+    code: requireNonEmptyString(object.code, 'PreparationFailure.code'),
+    message: requireNonEmptyString(
+      object.message,
+      'PreparationFailure.message',
+    ),
+  });
+}
+
+export function createPreparationGeneration(
+  input: unknown,
+): PreparationGeneration {
+  const object = requireExactObject(
+    input,
+    'PreparationGeneration',
+    GENERATION_KEYS,
+    GENERATION_OPTIONAL_KEYS,
+  );
+  const status = requireEnumValue(
+    object.status,
+    'PreparationGeneration.status',
+    GENERATION_STATUSES,
+  );
+  const failure = requireFailureForStatus(
+    object.failure,
+    Object.hasOwn(object, 'failure'),
+    status,
+    'PreparationGeneration',
+  );
+
+  return Object.freeze({
+    id: requireNonEmptyString(object.id, 'PreparationGeneration.id'),
+    agentRevisionId: requireNonEmptyString(
+      object.agentRevisionId,
+      'PreparationGeneration.agentRevisionId',
+    ),
+    sourceGenerationHash: requireSha256(
+      object.sourceGenerationHash,
+      'PreparationGeneration.sourceGenerationHash',
+    ),
+    requiredVariantKeyHashes: requireSortedUniqueHashes(
+      object.requiredVariantKeyHashes,
+      'PreparationGeneration.requiredVariantKeyHashes',
+    ),
+    status,
+    ...(failure === undefined ? {} : { failure }),
+    rowVersion: requireNonNegativeSafeInteger(
+      object.rowVersion,
+      'PreparationGeneration.rowVersion',
+    ),
+  });
+}
+
+export function serializePreparationGeneration(
+  input: PreparationGeneration,
+): string {
+  return canonicalContractJson(createPreparationGeneration(input));
+}
+
+export function hashPreparationGeneration(
+  input: PreparationGeneration,
+): string {
+  return hashCanonicalContract(createPreparationGeneration(input));
+}
+
+export function requirePreparationFailureForStatus(
+  value: unknown,
+  hasFailure: boolean,
+  failed: boolean,
+  path: string,
+): PreparationFailure | undefined {
+  if (failed) {
+    if (!hasFailure) {
+      throw new TypeError(`${path}.failure is required when status is failed.`);
+    }
+    return createPreparationFailure(value);
+  }
+  if (hasFailure) {
+    throw new TypeError(
+      `${path}.failure is only supported when status is failed.`,
+    );
+  }
+  return undefined;
+}
+
+function requireFailureForStatus(
+  value: unknown,
+  hasFailure: boolean,
+  status: PreparationGenerationStatus,
+  path: string,
+): PreparationFailure | undefined {
+  return requirePreparationFailureForStatus(
+    value,
+    hasFailure,
+    status === PreparationGenerationStatus.Failed,
+    path,
+  );
+}
+
+function requireSortedUniqueHashes(
+  value: unknown,
+  path: string,
+): readonly string[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${path} must be an array.`);
+  }
+
+  const hashes = value.map((entry, index) =>
+    requireSha256(entry, `${path}[${index}]`),
+  );
+  for (let index = 1; index < hashes.length; index += 1) {
+    const previous = hashes[index - 1];
+    const current = hashes[index];
+    if (previous === undefined || current === undefined) {
+      throw new TypeError(`${path} contains an invalid sparse entry.`);
+    }
+    if (previous >= current) {
+      throw new TypeError(
+        `${path} must contain unique hashes in ascending lexical order.`,
+      );
+    }
+  }
+  return Object.freeze(hashes);
+}

package/src/lib/launch-identity/prepared-launch-variant.ts

@@ -0,0 +1,263 @@
+import { WorkerRuntimeKind } from '@xemahq/kernel-contracts/worker-runtime';
+
+import {
+  canonicalContractJson,
+  hashCanonicalContract,
+  requireEnumValue,
+  requireExactObject,
+  requireImageDigest,
+  requireNonEmptyString,
+  requireNonNegativeSafeInteger,
+  requireSha256,
+} from './canonical-contract';
+import {
+  requirePreparationFailureForStatus,
+  type PreparationFailure,
+} from './preparation-generation';
+import {
+  RuntimeTemplateTenantDependency,
+  RuntimeTemplateTrustPolicy,
+} from './runtime-template-key';
+
+export enum PreparedLaunchVariantStatus {
+  Materializing = 'materializing',
+  Ready = 'ready',
+  Failed = 'failed',
+  Retired = 'retired',
+}
+
+export type PreparedLaunchTenantDependency =
+  | {
+      readonly kind: RuntimeTemplateTenantDependency.OrganizationNeutral;
+    }
+  | {
+      readonly kind: RuntimeTemplateTenantDependency.OrganizationBound;
+      readonly organizationScopeHash: string;
+    };
+
+export interface PreparedLaunchVariantKey {
+  readonly schemaVersion: 1;
+  readonly runtimeKind: WorkerRuntimeKind;
+  readonly runtimeRevision: string;
+  readonly imageDigest: `sha256:${string}`;
+  readonly layoutProfileRef: string;
+  readonly staticDependencyClosureHash: string;
+  readonly tenantDependency: PreparedLaunchTenantDependency;
+  readonly trustPolicy: RuntimeTemplateTrustPolicy;
+  readonly policyGenerationHash: string;
+  readonly region: string;
+}
+
+export interface PreparedLaunchVariant {
+  readonly id: string;
+  readonly preparationGenerationId: string;
+  readonly key: PreparedLaunchVariantKey;
+  readonly keyHash: string;
+  readonly compiledLaunchPlanHash: string;
+  readonly preparedRuntimeTemplateHash: string;
+  readonly preparedRuntimeTemplateRef: string;
+  readonly status: PreparedLaunchVariantStatus;
+  readonly failure?: PreparationFailure;
+  readonly rowVersion: number;
+}
+
+const KEY_KEYS = [
+  'schemaVersion',
+  'runtimeKind',
+  'runtimeRevision',
+  'imageDigest',
+  'layoutProfileRef',
+  'staticDependencyClosureHash',
+  'tenantDependency',
+  'trustPolicy',
+  'policyGenerationHash',
+  'region',
+] as const;
+const VARIANT_KEYS = [
+  'id',
+  'preparationGenerationId',
+  'key',
+  'keyHash',
+  'compiledLaunchPlanHash',
+  'preparedRuntimeTemplateHash',
+  'preparedRuntimeTemplateRef',
+  'status',
+  'rowVersion',
+] as const;
+const VARIANT_OPTIONAL_KEYS = ['failure'] as const;
+const RUNTIME_KINDS = Object.values(WorkerRuntimeKind);
+const TENANT_DEPENDENCY_KINDS = Object.values(RuntimeTemplateTenantDependency);
+const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
+const VARIANT_STATUSES = Object.values(PreparedLaunchVariantStatus);
+
+export function createPreparedLaunchVariantKey(
+  input: unknown,
+): PreparedLaunchVariantKey {
+  const object = requireExactObject(
+    input,
+    'PreparedLaunchVariantKey',
+    KEY_KEYS,
+  );
+  if (object.schemaVersion !== 1) {
+    throw new TypeError('PreparedLaunchVariantKey.schemaVersion must be 1.');
+  }
+
+  return Object.freeze({
+    schemaVersion: 1,
+    runtimeKind: requireEnumValue(
+      object.runtimeKind,
+      'PreparedLaunchVariantKey.runtimeKind',
+      RUNTIME_KINDS,
+    ),
+    runtimeRevision: requireNonEmptyString(
+      object.runtimeRevision,
+      'PreparedLaunchVariantKey.runtimeRevision',
+    ),
+    imageDigest: requireImageDigest(
+      object.imageDigest,
+      'PreparedLaunchVariantKey.imageDigest',
+    ) as `sha256:${string}`,
+    layoutProfileRef: requireNonEmptyString(
+      object.layoutProfileRef,
+      'PreparedLaunchVariantKey.layoutProfileRef',
+    ),
+    staticDependencyClosureHash: requireSha256(
+      object.staticDependencyClosureHash,
+      'PreparedLaunchVariantKey.staticDependencyClosureHash',
+    ),
+    tenantDependency: requireTenantDependency(object.tenantDependency),
+    trustPolicy: requireEnumValue(
+      object.trustPolicy,
+      'PreparedLaunchVariantKey.trustPolicy',
+      TRUST_POLICIES,
+    ),
+    policyGenerationHash: requireSha256(
+      object.policyGenerationHash,
+      'PreparedLaunchVariantKey.policyGenerationHash',
+    ),
+    region: requireNonEmptyString(
+      object.region,
+      'PreparedLaunchVariantKey.region',
+    ),
+  });
+}
+
+export function serializePreparedLaunchVariantKey(
+  input: PreparedLaunchVariantKey,
+): string {
+  return canonicalContractJson(createPreparedLaunchVariantKey(input));
+}
+
+export function hashPreparedLaunchVariantKey(
+  input: PreparedLaunchVariantKey,
+): string {
+  return hashCanonicalContract(createPreparedLaunchVariantKey(input));
+}
+
+export function createPreparedLaunchVariant(
+  input: unknown,
+): PreparedLaunchVariant {
+  const object = requireExactObject(
+    input,
+    'PreparedLaunchVariant',
+    VARIANT_KEYS,
+    VARIANT_OPTIONAL_KEYS,
+  );
+  const key = createPreparedLaunchVariantKey(object.key);
+  const keyHash = requireSha256(
+    object.keyHash,
+    'PreparedLaunchVariant.keyHash',
+  );
+  if (keyHash !== hashPreparedLaunchVariantKey(key)) {
+    throw new TypeError(
+      'PreparedLaunchVariant.keyHash must equal the canonical key hash.',
+    );
+  }
+  const status = requireEnumValue(
+    object.status,
+    'PreparedLaunchVariant.status',
+    VARIANT_STATUSES,
+  );
+  const failure = requirePreparationFailureForStatus(
+    object.failure,
+    Object.hasOwn(object, 'failure'),
+    status === PreparedLaunchVariantStatus.Failed,
+    'PreparedLaunchVariant',
+  );
+
+  return Object.freeze({
+    id: requireNonEmptyString(object.id, 'PreparedLaunchVariant.id'),
+    preparationGenerationId: requireNonEmptyString(
+      object.preparationGenerationId,
+      'PreparedLaunchVariant.preparationGenerationId',
+    ),
+    key,
+    keyHash,
+    compiledLaunchPlanHash: requireSha256(
+      object.compiledLaunchPlanHash,
+      'PreparedLaunchVariant.compiledLaunchPlanHash',
+    ),
+    preparedRuntimeTemplateHash: requireSha256(
+      object.preparedRuntimeTemplateHash,
+      'PreparedLaunchVariant.preparedRuntimeTemplateHash',
+    ),
+    preparedRuntimeTemplateRef: requireNonEmptyString(
+      object.preparedRuntimeTemplateRef,
+      'PreparedLaunchVariant.preparedRuntimeTemplateRef',
+    ),
+    status,
+    ...(failure === undefined ? {} : { failure }),
+    rowVersion: requireNonNegativeSafeInteger(
+      object.rowVersion,
+      'PreparedLaunchVariant.rowVersion',
+    ),
+  });
+}
+
+export function serializePreparedLaunchVariant(
+  input: PreparedLaunchVariant,
+): string {
+  return canonicalContractJson(createPreparedLaunchVariant(input));
+}
+
+export function hashPreparedLaunchVariant(
+  input: PreparedLaunchVariant,
+): string {
+  return hashCanonicalContract(createPreparedLaunchVariant(input));
+}
+
+function requireTenantDependency(
+  input: unknown,
+): PreparedLaunchTenantDependency {
+  const base = requireExactObject(
+    input,
+    'PreparedLaunchVariantKey.tenantDependency',
+    ['kind'],
+    ['organizationScopeHash'],
+  );
+  const kind = requireEnumValue(
+    base.kind,
+    'PreparedLaunchVariantKey.tenantDependency.kind',
+    TENANT_DEPENDENCY_KINDS,
+  );
+  if (kind === RuntimeTemplateTenantDependency.OrganizationNeutral) {
+    if (Object.hasOwn(base, 'organizationScopeHash')) {
+      throw new TypeError(
+        'PreparedLaunchVariantKey.tenantDependency.organizationScopeHash is forbidden for organization-neutral variants.',
+      );
+    }
+    return Object.freeze({ kind });
+  }
+  if (!Object.hasOwn(base, 'organizationScopeHash')) {
+    throw new TypeError(
+      'PreparedLaunchVariantKey.tenantDependency.organizationScopeHash is required for organization-bound variants.',
+    );
+  }
+  return Object.freeze({
+    kind,
+    organizationScopeHash: requireSha256(
+      base.organizationScopeHash,
+      'PreparedLaunchVariantKey.tenantDependency.organizationScopeHash',
+    ),
+  });
+}

package/dist/lib/composition-resolution.d.ts

@@ -1,43 +0,0 @@
-import { type ModelRef, type NodeOverlayFragment, type SubAgentBinding } from '@xemahq/kernel-contracts/workflow';
-import type { ResolvedAgent, ResolvedAgentNode } from '@xemahq/kernel-contracts/agent-composition';
-import type { PermissionMap } from '@xemahq/kernel-contracts/agent-permission';
-import { type ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
-export declare class AgentResolutionError extends Error {
-    constructor(context: string, detail: string);
-}
-export interface FlattenedAgentNode {
-    readonly slug: string;
-    readonly alias?: string;
-    readonly modelOverride?: ModelRef;
-    readonly instructions?: string;
-    readonly permission?: PermissionMap;
-}
-export interface CollectScopeOptions {
-    readonly scope?: 'tree' | 'root';
-}
-export interface RuntimeAgentConfig {
-    readonly agentRef: string;
-    readonly primaryAgentSlug: string;
-    readonly primaryInstructions: string | null;
-    readonly primaryPermission: PermissionMap | null;
-    readonly primaryModelOverride: ModelRef | null;
-    readonly subAgentBindings: readonly SubAgentBinding[];
-    readonly subAgentInstructionsBySlug: Readonly<Record<string, string>>;
-    readonly subAgentPermissionBySlug: Readonly<Record<string, PermissionMap>>;
-    readonly subAgentModelOverridesBySlug: Readonly<Record<string, ModelRef>>;
-    readonly defaultSkillSlugs: readonly string[];
-    readonly allSkillSlugs: readonly string[];
-    readonly defaultToolSelection: readonly ToolSelectionEntry[];
-}
-export declare function flattenAgentTree(root: ResolvedAgentNode): readonly FlattenedAgentNode[];
-export declare function collectSkills(root: ResolvedAgentNode, opts?: CollectScopeOptions): readonly string[];
-export declare function collectTools(root: ResolvedAgentNode, opts?: CollectScopeOptions): readonly ToolSelectionEntry[];
-export declare function collectInstructionsBySlug(root: ResolvedAgentNode): Readonly<Record<string, string>>;
-export declare function collectPermissionsBySlug(root: ResolvedAgentNode): Readonly<Record<string, PermissionMap>>;
-export declare function collectModelOverridesBySlug(root: ResolvedAgentNode): Readonly<Record<string, ModelRef>>;
-export declare function appendInstructions(baseSystemPrompt: string, nodeInstructions: string | null): string;
-export declare function normalizeInstructions(raw: string | undefined): string | null;
-export declare function normalizePermission(raw: PermissionMap | undefined): PermissionMap | null;
-export declare function projectModelOverride(raw: ModelRef | undefined, context: string): ModelRef | null;
-export declare function projectAgentToRuntimeConfig(resolved: ResolvedAgent, overlay?: NodeOverlayFragment): RuntimeAgentConfig;
-//# sourceMappingURL=composition-resolution.d.ts.map

package/dist/lib/composition-resolution.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"composition-resolution.d.ts","sourceRoot":"","sources":["../../src/lib/composition-resolution.ts"],"names":[],"mappings":"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"}