@xemahq/agent-session-runtime 0.6.7 → 0.8.0

package/src/lib/launch-identity/compiled-session-launch-plan.ts

@@ -0,0 +1,681 @@
+import {
+  canonicalContractJson,
+  type CanonicalJsonValue,
+  hashCanonicalContract,
+  requireBoolean,
+  requireCanonicalJsonObject,
+  requireEnumValue,
+  requireExactObject,
+  requireImageDigest,
+  requireNonEmptyString,
+  requireSha256,
+  requireStringRefs,
+} from './canonical-contract';
+import {
+  createRuntimeTemplateKey,
+  type RuntimeTemplateKey,
+  RuntimeTemplateTenantDependency,
+  RuntimeTemplateTrustPolicy,
+} from './runtime-template-key';
+
+export enum LaunchPlanBindingSlotKind {
+  OrganizationId = 'organization-id',
+  ProjectId = 'project-id',
+  UserId = 'user-id',
+  SessionId = 'session-id',
+  ThreadId = 'thread-id',
+  InvocationId = 'invocation-id',
+  DomainRef = 'domain-ref',
+  Input = 'input',
+  DynamicContext = 'dynamic-context',
+  StorageAllocationRef = 'storage-allocation-ref',
+  WorkingFileSourceRef = 'working-file-source-ref',
+  OutputRouteRef = 'output-route-ref',
+  ActorTokenRef = 'actor-token-ref',
+  ServiceTokenRef = 'service-token-ref',
+  ProviderTokenRef = 'provider-token-ref',
+  CredentialGrantRef = 'credential-grant-ref',
+  DatabaseGrantRef = 'database-grant-ref',
+  SecretRef = 'secret-ref',
+}
+
+export enum LaunchPlanBindingSlotCardinality {
+  One = 'one',
+  Many = 'many',
+}
+
+export interface LaunchPlanBindingSlot {
+  readonly name: string;
+  readonly kind: LaunchPlanBindingSlotKind;
+  readonly cardinality: LaunchPlanBindingSlotCardinality;
+  readonly required: boolean;
+}
+
+export interface PinnedLaunchResource {
+  readonly kind: string;
+  readonly ref: string;
+  readonly revisionRef: string;
+  readonly contentHash: string;
+}
+
+export interface CompiledWorkspaceLaunchPlan {
+  readonly manifestRef: string;
+  readonly manifestHash: string;
+  readonly structure: Readonly<Record<string, CanonicalJsonValue>>;
+  readonly layout: Readonly<Record<string, CanonicalJsonValue>>;
+}
+
+export interface CompiledRuntimeRequirements {
+  readonly runtimeRef: string;
+  readonly runtimeRevision: string;
+  readonly imageDigest: string;
+  readonly requirementsHash: string;
+  readonly requirements: Readonly<Record<string, CanonicalJsonValue>>;
+}
+
+export interface LaunchPolicyCompatibility {
+  readonly tenantDependency: RuntimeTemplateTenantDependency;
+  readonly trustPolicy: RuntimeTemplateTrustPolicy;
+  readonly compatibleSurfaces: readonly string[];
+  readonly policies: readonly PinnedLaunchResource[];
+}
+
+export interface CompiledOutputSurfaceSchema {
+  readonly kind: string;
+  readonly schemaRef: string;
+  readonly schemaHash: string;
+  readonly schema: Readonly<Record<string, CanonicalJsonValue>>;
+}
+
+/**
+ * Immutable, publish-time session launch input. This protocol deliberately
+ * excludes invocation identity, tenant data, credentials and raw inputs.
+ * Runtime values are supplied only through the declared `bindingSlots`.
+ */
+export interface CompiledSessionLaunchPlan {
+  readonly schemaVersion: 1;
+  readonly runtimeTemplateKey: RuntimeTemplateKey;
+  readonly agent: PinnedLaunchResource;
+  readonly subagents: readonly PinnedLaunchResource[];
+  readonly skills: readonly PinnedLaunchResource[];
+  readonly tools: readonly PinnedLaunchResource[];
+  readonly mcpDescriptors: readonly PinnedLaunchResource[];
+  readonly capabilityDescriptors: readonly PinnedLaunchResource[];
+  readonly workspace: CompiledWorkspaceLaunchPlan;
+  readonly runtimeRequirements: CompiledRuntimeRequirements;
+  readonly policyCompatibility: LaunchPolicyCompatibility;
+  readonly outputSurface: CompiledOutputSurfaceSchema;
+  readonly bindingSlots: readonly LaunchPlanBindingSlot[];
+}
+
+const PLAN_KEYS = [
+  'schemaVersion',
+  'runtimeTemplateKey',
+  'agent',
+  'subagents',
+  'skills',
+  'tools',
+  'mcpDescriptors',
+  'capabilityDescriptors',
+  'workspace',
+  'runtimeRequirements',
+  'policyCompatibility',
+  'outputSurface',
+  'bindingSlots',
+] as const;
+const RESOURCE_KEYS = ['kind', 'ref', 'revisionRef', 'contentHash'] as const;
+const WORKSPACE_KEYS = [
+  'manifestRef',
+  'manifestHash',
+  'structure',
+  'layout',
+] as const;
+const RUNTIME_REQUIREMENT_KEYS = [
+  'runtimeRef',
+  'runtimeRevision',
+  'imageDigest',
+  'requirementsHash',
+  'requirements',
+] as const;
+const POLICY_KEYS = [
+  'tenantDependency',
+  'trustPolicy',
+  'compatibleSurfaces',
+  'policies',
+] as const;
+const OUTPUT_SURFACE_KEYS = [
+  'kind',
+  'schemaRef',
+  'schemaHash',
+  'schema',
+] as const;
+const BINDING_SLOT_KEYS = ['name', 'kind', 'cardinality', 'required'] as const;
+const BINDING_SLOT_KINDS = Object.values(LaunchPlanBindingSlotKind);
+const BINDING_SLOT_CARDINALITIES = Object.values(
+  LaunchPlanBindingSlotCardinality,
+);
+const TENANT_DEPENDENCIES = Object.values(RuntimeTemplateTenantDependency);
+const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
+const BINDING_SLOT_NAME_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z][a-z0-9]*)*$/u;
+const DYNAMIC_LITERAL_PATTERN =
+  /\$\{\s*(?:input|tenant|org|organization|project|user|session|thread|domain|token|secret|credential)(?:[.:[\]}]|$)/iu;
+const SECRET_REFERENCE_PATTERN =
+  /^(?:secret|vault|credential|token)(?:-ref)?:\/\//iu;
+const DYNAMIC_FIELD_NAMES = new Set([
+  'apikey',
+  'authorization',
+  'cookie',
+  'credential',
+  'credentialgrantref',
+  'credentialref',
+  'databasegrantref',
+  'domain',
+  'domainid',
+  'domainref',
+  'input',
+  'invocationid',
+  'organization',
+  'organizationid',
+  'org',
+  'orgid',
+  'password',
+  'privatekey',
+  'project',
+  'projectid',
+  'secret',
+  'secretref',
+  'session',
+  'sessionid',
+  'storageref',
+  'tenant',
+  'tenantid',
+  'thread',
+  'threadid',
+  'token',
+  'tokenref',
+  'user',
+  'userid',
+  'value',
+]);
+const SECRET_OR_CREDENTIAL_FIELD_PATTERN =
+  /(?:apikey|authorization|cookie|credential|password|privatekey|secret|token)(?:ref)?$/u;
+
+export function createCompiledSessionLaunchPlan(
+  input: unknown,
+): CompiledSessionLaunchPlan {
+  const object = requireExactObject(
+    input,
+    'CompiledSessionLaunchPlan',
+    PLAN_KEYS,
+  );
+  if (object.schemaVersion !== 1) {
+    throw new TypeError('CompiledSessionLaunchPlan.schemaVersion must be 1.');
+  }
+
+  const runtimeTemplateKey = createRuntimeTemplateKey(
+    object.runtimeTemplateKey,
+  );
+  const agent = requirePinnedResource(
+    object.agent,
+    'CompiledSessionLaunchPlan.agent',
+  );
+  const subagents = requirePinnedResources(
+    object.subagents,
+    'CompiledSessionLaunchPlan.subagents',
+  );
+  const skills = requirePinnedResources(
+    object.skills,
+    'CompiledSessionLaunchPlan.skills',
+  );
+  const tools = requirePinnedResources(
+    object.tools,
+    'CompiledSessionLaunchPlan.tools',
+  );
+  const mcpDescriptors = requirePinnedResources(
+    object.mcpDescriptors,
+    'CompiledSessionLaunchPlan.mcpDescriptors',
+  );
+  const capabilityDescriptors = requirePinnedResources(
+    object.capabilityDescriptors,
+    'CompiledSessionLaunchPlan.capabilityDescriptors',
+  );
+  const workspace = requireWorkspace(object.workspace);
+  const runtimeRequirements = requireRuntimeRequirements(
+    object.runtimeRequirements,
+  );
+  const policyCompatibility = requirePolicyCompatibility(
+    object.policyCompatibility,
+  );
+  const outputSurface = requireOutputSurface(object.outputSurface);
+  const bindingSlots = requireBindingSlots(object.bindingSlots);
+
+  assertTemplateConsistency({
+    runtimeTemplateKey,
+    agent,
+    subagents,
+    skills,
+    tools,
+    mcpDescriptors,
+    capabilityDescriptors,
+    workspace,
+    runtimeRequirements,
+    policyCompatibility,
+  });
+  assertDeclaredBindingSlotReferences(
+    [workspace.structure, workspace.layout, runtimeRequirements.requirements],
+    bindingSlots,
+  );
+
+  return Object.freeze({
+    schemaVersion: 1,
+    runtimeTemplateKey,
+    agent,
+    subagents,
+    skills,
+    tools,
+    mcpDescriptors,
+    capabilityDescriptors,
+    workspace,
+    runtimeRequirements,
+    policyCompatibility,
+    outputSurface,
+    bindingSlots,
+  });
+}
+
+export function encodeCompiledSessionLaunchPlan(
+  input: CompiledSessionLaunchPlan,
+): string {
+  return canonicalContractJson(createCompiledSessionLaunchPlan(input));
+}
+
+export function decodeCompiledSessionLaunchPlan(
+  encoded: string,
+): CompiledSessionLaunchPlan {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(encoded);
+  } catch (error) {
+    throw new TypeError(
+      `CompiledSessionLaunchPlan is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return createCompiledSessionLaunchPlan(parsed);
+}
+
+export function hashCompiledSessionLaunchPlan(
+  input: CompiledSessionLaunchPlan,
+): string {
+  return hashCanonicalContract(createCompiledSessionLaunchPlan(input));
+}
+
+export function hashCompiledWorkspaceLaunchPlan(
+  input: CompiledWorkspaceLaunchPlan,
+): string {
+  return hashCanonicalContract(input);
+}
+
+function requirePinnedResource(
+  value: unknown,
+  path: string,
+): PinnedLaunchResource {
+  const object = requireExactObject(value, path, RESOURCE_KEYS);
+  return Object.freeze({
+    kind: requireNonEmptyString(object.kind, `${path}.kind`),
+    ref: requireNonEmptyString(object.ref, `${path}.ref`),
+    revisionRef: requireNonEmptyString(
+      object.revisionRef,
+      `${path}.revisionRef`,
+    ),
+    contentHash: requireSha256(object.contentHash, `${path}.contentHash`),
+  });
+}
+
+function requirePinnedResources(
+  value: unknown,
+  path: string,
+): readonly PinnedLaunchResource[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${path} must be an array.`);
+  }
+  const resources = value.map((entry, index) =>
+    requirePinnedResource(entry, `${path}[${index}]`),
+  );
+  const identities = new Set<string>();
+  for (const resource of resources) {
+    const identity = `${resource.kind}\u0000${resource.ref}`;
+    if (identities.has(identity)) {
+      throw new TypeError(
+        `${path} contains duplicate resource '${resource.kind}:${resource.ref}'.`,
+      );
+    }
+    identities.add(identity);
+  }
+  return Object.freeze(
+    resources.toSorted((left, right) =>
+      canonicalContractJson(left).localeCompare(canonicalContractJson(right)),
+    ),
+  );
+}
+
+function requireWorkspace(value: unknown): CompiledWorkspaceLaunchPlan {
+  const path = 'CompiledSessionLaunchPlan.workspace';
+  const object = requireExactObject(value, path, WORKSPACE_KEYS);
+  return Object.freeze({
+    manifestRef: requireNonEmptyString(
+      object.manifestRef,
+      `${path}.manifestRef`,
+    ),
+    manifestHash: requireSha256(object.manifestHash, `${path}.manifestHash`),
+    structure: requireStaticPayload(object.structure, `${path}.structure`),
+    layout: requireStaticPayload(object.layout, `${path}.layout`),
+  });
+}
+
+function requireRuntimeRequirements(
+  value: unknown,
+): CompiledRuntimeRequirements {
+  const path = 'CompiledSessionLaunchPlan.runtimeRequirements';
+  const object = requireExactObject(value, path, RUNTIME_REQUIREMENT_KEYS);
+  const imageDigest = requireImageDigest(object.imageDigest, `${path}.imageDigest`);
+  const requirements = requireStaticPayload(
+    object.requirements,
+    `${path}.requirements`,
+  );
+  const requirementsHash = requireSha256(
+    object.requirementsHash,
+    `${path}.requirementsHash`,
+  );
+  assertContentHash(requirementsHash, requirements, `${path}.requirementsHash`);
+  return Object.freeze({
+    runtimeRef: requireNonEmptyString(object.runtimeRef, `${path}.runtimeRef`),
+    runtimeRevision: requireNonEmptyString(
+      object.runtimeRevision,
+      `${path}.runtimeRevision`,
+    ),
+    imageDigest,
+    requirementsHash,
+    requirements,
+  });
+}
+
+function requirePolicyCompatibility(value: unknown): LaunchPolicyCompatibility {
+  const path = 'CompiledSessionLaunchPlan.policyCompatibility';
+  const object = requireExactObject(value, path, POLICY_KEYS);
+  return Object.freeze({
+    tenantDependency: requireEnumValue(
+      object.tenantDependency,
+      `${path}.tenantDependency`,
+      TENANT_DEPENDENCIES,
+    ),
+    trustPolicy: requireEnumValue(
+      object.trustPolicy,
+      `${path}.trustPolicy`,
+      TRUST_POLICIES,
+    ),
+    compatibleSurfaces: requireStringRefs(
+      object.compatibleSurfaces,
+      `${path}.compatibleSurfaces`,
+    ),
+    policies: requirePinnedResources(object.policies, `${path}.policies`),
+  });
+}
+
+function requireOutputSurface(value: unknown): CompiledOutputSurfaceSchema {
+  const path = 'CompiledSessionLaunchPlan.outputSurface';
+  const object = requireExactObject(value, path, OUTPUT_SURFACE_KEYS);
+  const schema = requireCanonicalJsonObject(object.schema, `${path}.schema`);
+  const schemaHash = requireSha256(object.schemaHash, `${path}.schemaHash`);
+  assertContentHash(schemaHash, schema, `${path}.schemaHash`);
+  return Object.freeze({
+    kind: requireNonEmptyString(object.kind, `${path}.kind`),
+    schemaRef: requireNonEmptyString(object.schemaRef, `${path}.schemaRef`),
+    schemaHash,
+    schema,
+  });
+}
+
+function requireBindingSlots(value: unknown): readonly LaunchPlanBindingSlot[] {
+  const path = 'CompiledSessionLaunchPlan.bindingSlots';
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${path} must be an array.`);
+  }
+  const slots = value.map((entry, index) => {
+    const slotPath = `${path}[${index}]`;
+    const object = requireExactObject(entry, slotPath, BINDING_SLOT_KEYS);
+    const name = requireNonEmptyString(object.name, `${slotPath}.name`);
+    if (!BINDING_SLOT_NAME_PATTERN.test(name)) {
+      throw new TypeError(
+        `${slotPath}.name must be a lowercase dotted or hyphenated identifier.`,
+      );
+    }
+    return Object.freeze({
+      name,
+      kind: requireEnumValue(
+        object.kind,
+        `${slotPath}.kind`,
+        BINDING_SLOT_KINDS,
+      ),
+      cardinality: requireEnumValue(
+        object.cardinality,
+        `${slotPath}.cardinality`,
+        BINDING_SLOT_CARDINALITIES,
+      ),
+      required: requireBoolean(object.required, `${slotPath}.required`),
+    });
+  });
+  const names = new Set<string>();
+  for (const slot of slots) {
+    if (names.has(slot.name)) {
+      throw new TypeError(`${path} contains duplicate slot '${slot.name}'.`);
+    }
+    names.add(slot.name);
+  }
+  return Object.freeze(
+    slots.toSorted((left, right) => left.name.localeCompare(right.name)),
+  );
+}
+
+function requireStaticPayload(
+  value: unknown,
+  path: string,
+): Readonly<Record<string, CanonicalJsonValue>> {
+  const normalized = requireCanonicalJsonObject(value, path);
+  assertStaticPayloadNode(normalized, path);
+  return normalized;
+}
+
+function assertStaticPayloadNode(
+  value: CanonicalJsonValue,
+  path: string,
+): void {
+  if (typeof value === 'string') {
+    if (
+      DYNAMIC_LITERAL_PATTERN.test(value) ||
+      SECRET_REFERENCE_PATTERN.test(value)
+    ) {
+      throw new TypeError(
+        `${path} embeds dynamic or secret data; use a typed $bindingSlot reference.`,
+      );
+    }
+    return;
+  }
+  if (value === null || typeof value !== 'object') {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) =>
+      assertStaticPayloadNode(entry, `${path}[${index}]`),
+    );
+    return;
+  }
+  if (Object.hasOwn(value, '$bindingSlot')) {
+    const marker = requireExactObject(value, path, ['$bindingSlot']);
+    requireNonEmptyString(marker.$bindingSlot, `${path}.$bindingSlot`);
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const normalizedKey = key.replaceAll(/[^a-z0-9]/giu, '').toLowerCase();
+    if (
+      DYNAMIC_FIELD_NAMES.has(normalizedKey) ||
+      SECRET_OR_CREDENTIAL_FIELD_PATTERN.test(normalizedKey)
+    ) {
+      if (!isBindingSlotMarker(entry)) {
+        throw new TypeError(
+          `${path}.${key} is dynamic data; its value must be a typed $bindingSlot reference.`,
+        );
+      }
+    }
+    assertStaticPayloadNode(entry, `${path}.${key}`);
+  }
+}
+
+function isBindingSlotMarker(
+  value: CanonicalJsonValue,
+): value is Readonly<{ readonly $bindingSlot: CanonicalJsonValue }> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.hasOwn(value, '$bindingSlot')
+  );
+}
+
+function assertDeclaredBindingSlotReferences(
+  values: readonly Readonly<Record<string, CanonicalJsonValue>>[],
+  slots: readonly LaunchPlanBindingSlot[],
+): void {
+  const declared = new Set(slots.map((slot) => slot.name));
+  for (const [index, value] of values.entries()) {
+    inspectBindingSlotReferences(value, `staticPayloads[${index}]`, declared);
+  }
+}
+
+function inspectBindingSlotReferences(
+  value: CanonicalJsonValue,
+  path: string,
+  declared: ReadonlySet<string>,
+): void {
+  if (value === null || typeof value !== 'object') {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) =>
+      inspectBindingSlotReferences(entry, `${path}[${index}]`, declared),
+    );
+    return;
+  }
+  if (isBindingSlotMarker(value)) {
+    const name = value.$bindingSlot;
+    if (typeof name !== 'string' || !declared.has(name)) {
+      throw new TypeError(
+        `${path} references undeclared binding slot '${String(name)}'.`,
+      );
+    }
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    inspectBindingSlotReferences(entry, `${path}.${key}`, declared);
+  }
+}
+
+function assertTemplateConsistency(input: {
+  readonly runtimeTemplateKey: RuntimeTemplateKey;
+  readonly agent: PinnedLaunchResource;
+  readonly subagents: readonly PinnedLaunchResource[];
+  readonly skills: readonly PinnedLaunchResource[];
+  readonly tools: readonly PinnedLaunchResource[];
+  readonly mcpDescriptors: readonly PinnedLaunchResource[];
+  readonly capabilityDescriptors: readonly PinnedLaunchResource[];
+  readonly workspace: CompiledWorkspaceLaunchPlan;
+  readonly runtimeRequirements: CompiledRuntimeRequirements;
+  readonly policyCompatibility: LaunchPolicyCompatibility;
+}): void {
+  const key = input.runtimeTemplateKey;
+  assertEqual(
+    input.agent.revisionRef,
+    key.agentRevision,
+    'agent.revisionRef',
+    'runtimeTemplateKey.agentRevision',
+  );
+  assertEqual(
+    input.agent.contentHash,
+    key.primaryAgentHash,
+    'agent.contentHash',
+    'runtimeTemplateKey.primaryAgentHash',
+  );
+  assertContentHash(key.subagentsHash, input.subagents, 'subagents');
+  assertContentHash(key.skillsHash, input.skills, 'skills');
+  assertContentHash(key.toolsHash, input.tools, 'tools');
+  assertContentHash(
+    key.mcpDescriptorsHash,
+    input.mcpDescriptors,
+    'mcpDescriptors',
+  );
+  assertContentHash(
+    key.capabilityDescriptorsHash,
+    input.capabilityDescriptors,
+    'capabilityDescriptors',
+  );
+  assertContentHash(
+    key.workspacePlanHash,
+    input.workspace,
+    'runtimeTemplateKey.workspacePlanHash',
+  );
+  assertEqual(
+    input.runtimeRequirements.runtimeRef,
+    key.runtimeRef,
+    'runtimeRequirements.runtimeRef',
+    'runtimeTemplateKey.runtimeRef',
+  );
+  assertEqual(
+    input.runtimeRequirements.runtimeRevision,
+    key.runtimeRevision,
+    'runtimeRequirements.runtimeRevision',
+    'runtimeTemplateKey.runtimeRevision',
+  );
+  assertEqual(
+    input.runtimeRequirements.imageDigest,
+    key.imageDigest,
+    'runtimeRequirements.imageDigest',
+    'runtimeTemplateKey.imageDigest',
+  );
+  assertEqual(
+    input.policyCompatibility.tenantDependency,
+    key.tenantDependency,
+    'policyCompatibility.tenantDependency',
+    'runtimeTemplateKey.tenantDependency',
+  );
+  assertEqual(
+    input.policyCompatibility.trustPolicy,
+    key.trustPolicy,
+    'policyCompatibility.trustPolicy',
+    'runtimeTemplateKey.trustPolicy',
+  );
+}
+
+function assertContentHash(
+  expectedHash: string,
+  content: unknown,
+  path: string,
+): void {
+  const actualHash = hashCanonicalContract(content);
+  if (actualHash !== expectedHash) {
+    throw new TypeError(
+      `${path} content hash mismatch: expected '${expectedHash}', computed '${actualHash}'.`,
+    );
+  }
+}
+
+function assertEqual(
+  actual: string,
+  expected: string,
+  actualPath: string,
+  expectedPath: string,
+): void {
+  if (actual !== expected) {
+    throw new TypeError(
+      `${actualPath} must equal ${expectedPath}; received '${actual}' and '${expected}'.`,
+    );
+  }
+}

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

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