@xemahq/agent-session-runtime 0.6.6 → 0.7.0

package/src/lib/launch-identity/runtime-template-key.ts

@@ -0,0 +1,148 @@
+import {
+  assertNoTenantOrSecretTemplateFields,
+  canonicalContractJson,
+  hashCanonicalContract,
+  requireEnumValue,
+  requireExactObject,
+  requireNonEmptyString,
+  requireSha256,
+} from './canonical-contract';
+
+export enum RuntimeTemplateTenantDependency {
+  OrganizationNeutral = 'organization-neutral',
+  OrganizationBound = 'organization-bound',
+}
+
+export enum RuntimeTemplateTrustPolicy {
+  Shared = 'shared',
+  Dedicated = 'dedicated',
+  Confidential = 'confidential',
+}
+
+export interface RuntimeTemplateKey {
+  readonly schemaVersion: 1;
+  readonly tenantDependency: RuntimeTemplateTenantDependency;
+  readonly trustPolicy: RuntimeTemplateTrustPolicy;
+  readonly runtimeRef: string;
+  readonly runtimeRevision: string;
+  readonly imageDigest: string;
+  readonly agentRevision: string;
+  readonly primaryAgentHash: string;
+  readonly subagentsHash: string;
+  readonly skillsHash: string;
+  readonly toolsHash: string;
+  readonly capabilityDescriptorsHash: string;
+  readonly mcpDescriptorsHash: string;
+  readonly workspacePlanHash: string;
+  readonly layoutProfile: string;
+}
+
+const REQUIRED_KEYS = [
+  'schemaVersion',
+  'tenantDependency',
+  'trustPolicy',
+  'runtimeRef',
+  'runtimeRevision',
+  'imageDigest',
+  'agentRevision',
+  'primaryAgentHash',
+  'subagentsHash',
+  'skillsHash',
+  'toolsHash',
+  'capabilityDescriptorsHash',
+  'mcpDescriptorsHash',
+  'workspacePlanHash',
+  'layoutProfile',
+] as const;
+
+const TENANT_DEPENDENCIES = Object.values(RuntimeTemplateTenantDependency);
+const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
+const IMAGE_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+
+/**
+ * Validates and canonicalizes the immutable execution dimensions used to
+ * select warm compute. Tenant, invocation and credential data have no valid
+ * slot in this contract and are rejected even when supplied as extra fields.
+ */
+export function createRuntimeTemplateKey(input: unknown): RuntimeTemplateKey {
+  assertNoTenantOrSecretTemplateFields(input, 'RuntimeTemplateKey');
+  const object = requireExactObject(input, 'RuntimeTemplateKey', REQUIRED_KEYS);
+
+  if (object.schemaVersion !== 1) {
+    throw new TypeError('RuntimeTemplateKey.schemaVersion must be 1.');
+  }
+
+  const imageDigest = requireNonEmptyString(
+    object.imageDigest,
+    'RuntimeTemplateKey.imageDigest',
+  );
+  if (!IMAGE_DIGEST_PATTERN.test(imageDigest)) {
+    throw new TypeError(
+      'RuntimeTemplateKey.imageDigest must be an immutable sha256 image digest.',
+    );
+  }
+
+  return Object.freeze({
+    schemaVersion: 1,
+    tenantDependency: requireEnumValue(
+      object.tenantDependency,
+      'RuntimeTemplateKey.tenantDependency',
+      TENANT_DEPENDENCIES,
+    ),
+    trustPolicy: requireEnumValue(
+      object.trustPolicy,
+      'RuntimeTemplateKey.trustPolicy',
+      TRUST_POLICIES,
+    ),
+    runtimeRef: requireNonEmptyString(
+      object.runtimeRef,
+      'RuntimeTemplateKey.runtimeRef',
+    ),
+    runtimeRevision: requireNonEmptyString(
+      object.runtimeRevision,
+      'RuntimeTemplateKey.runtimeRevision',
+    ),
+    imageDigest,
+    agentRevision: requireNonEmptyString(
+      object.agentRevision,
+      'RuntimeTemplateKey.agentRevision',
+    ),
+    primaryAgentHash: requireSha256(
+      object.primaryAgentHash,
+      'RuntimeTemplateKey.primaryAgentHash',
+    ),
+    subagentsHash: requireSha256(
+      object.subagentsHash,
+      'RuntimeTemplateKey.subagentsHash',
+    ),
+    skillsHash: requireSha256(
+      object.skillsHash,
+      'RuntimeTemplateKey.skillsHash',
+    ),
+    toolsHash: requireSha256(object.toolsHash, 'RuntimeTemplateKey.toolsHash'),
+    capabilityDescriptorsHash: requireSha256(
+      object.capabilityDescriptorsHash,
+      'RuntimeTemplateKey.capabilityDescriptorsHash',
+    ),
+    mcpDescriptorsHash: requireSha256(
+      object.mcpDescriptorsHash,
+      'RuntimeTemplateKey.mcpDescriptorsHash',
+    ),
+    workspacePlanHash: requireSha256(
+      object.workspacePlanHash,
+      'RuntimeTemplateKey.workspacePlanHash',
+    ),
+    layoutProfile: requireNonEmptyString(
+      object.layoutProfile,
+      'RuntimeTemplateKey.layoutProfile',
+    ),
+  });
+}
+
+export function serializeRuntimeTemplateKey(input: RuntimeTemplateKey): string {
+  return canonicalContractJson(createRuntimeTemplateKey(input));
+}
+
+export function hashRuntimeTemplateKey(input: RuntimeTemplateKey): string {
+  return hashCanonicalContract(createRuntimeTemplateKey(input));
+}

package/src/lib/launch-identity/session-binding.ts

@@ -0,0 +1,152 @@
+import {
+  canonicalContractJson,
+  type CanonicalJsonValue,
+  hashCanonicalContract,
+  type ResourceBindingRef,
+  requireExactObject,
+  requireNonEmptyString,
+  requireNonNegativeSafeInteger,
+  requireResourceBindingRefs,
+  requireSecretFreeJsonObject,
+  requireStringRefs,
+} from './canonical-contract';
+
+export interface SessionBinding {
+  readonly schemaVersion: 1;
+  readonly sessionId: string;
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly userId: string;
+  readonly domainRefs: readonly ResourceBindingRef[];
+  readonly storageAllocationRef: string;
+  readonly workingFileSourceRefs: readonly string[];
+  readonly outputRouteRef: string;
+  readonly actorTokenRef?: string;
+  readonly serviceTokenRef?: string;
+  readonly providerTokenRefs: readonly string[];
+  readonly credentialGrantRefs: readonly string[];
+  readonly databaseGrantRefs: readonly string[];
+  readonly dynamicContext: Readonly<Record<string, CanonicalJsonValue>>;
+  readonly bindingRevision: string;
+  readonly bindingEpoch: number;
+}
+
+const REQUIRED_KEYS = [
+  'schemaVersion',
+  'sessionId',
+  'organizationId',
+  'projectId',
+  'userId',
+  'domainRefs',
+  'storageAllocationRef',
+  'workingFileSourceRefs',
+  'outputRouteRef',
+  'providerTokenRefs',
+  'credentialGrantRefs',
+  'databaseGrantRefs',
+  'dynamicContext',
+  'bindingRevision',
+  'bindingEpoch',
+] as const;
+
+const OPTIONAL_KEYS = ['actorTokenRef', 'serviceTokenRef'] as const;
+
+/**
+ * Canonical tenant/session state applied atomically after a runtime claim.
+ * Credentials are represented only by opaque refs; raw secrets are rejected
+ * from dynamicContext.
+ */
+export function createSessionBinding(input: unknown): SessionBinding {
+  const object = requireExactObject(
+    input,
+    'SessionBinding',
+    REQUIRED_KEYS,
+    OPTIONAL_KEYS,
+  );
+
+  if (object.schemaVersion !== 1) {
+    throw new TypeError('SessionBinding.schemaVersion must be 1.');
+  }
+
+  const actorTokenRef =
+    object.actorTokenRef === undefined
+      ? undefined
+      : requireNonEmptyString(
+          object.actorTokenRef,
+          'SessionBinding.actorTokenRef',
+        );
+  const serviceTokenRef =
+    object.serviceTokenRef === undefined
+      ? undefined
+      : requireNonEmptyString(
+          object.serviceTokenRef,
+          'SessionBinding.serviceTokenRef',
+        );
+
+  return Object.freeze({
+    schemaVersion: 1,
+    sessionId: requireNonEmptyString(
+      object.sessionId,
+      'SessionBinding.sessionId',
+    ),
+    organizationId: requireNonEmptyString(
+      object.organizationId,
+      'SessionBinding.organizationId',
+    ),
+    projectId: requireNonEmptyString(
+      object.projectId,
+      'SessionBinding.projectId',
+    ),
+    userId: requireNonEmptyString(object.userId, 'SessionBinding.userId'),
+    domainRefs: requireResourceBindingRefs(
+      object.domainRefs,
+      'SessionBinding.domainRefs',
+    ),
+    storageAllocationRef: requireNonEmptyString(
+      object.storageAllocationRef,
+      'SessionBinding.storageAllocationRef',
+    ),
+    workingFileSourceRefs: requireStringRefs(
+      object.workingFileSourceRefs,
+      'SessionBinding.workingFileSourceRefs',
+    ),
+    outputRouteRef: requireNonEmptyString(
+      object.outputRouteRef,
+      'SessionBinding.outputRouteRef',
+    ),
+    ...(actorTokenRef === undefined ? {} : { actorTokenRef }),
+    ...(serviceTokenRef === undefined ? {} : { serviceTokenRef }),
+    providerTokenRefs: requireStringRefs(
+      object.providerTokenRefs,
+      'SessionBinding.providerTokenRefs',
+    ),
+    credentialGrantRefs: requireStringRefs(
+      object.credentialGrantRefs,
+      'SessionBinding.credentialGrantRefs',
+    ),
+    databaseGrantRefs: requireStringRefs(
+      object.databaseGrantRefs,
+      'SessionBinding.databaseGrantRefs',
+    ),
+    dynamicContext: requireSecretFreeJsonObject(
+      object.dynamicContext,
+      'SessionBinding.dynamicContext',
+    ),
+    bindingRevision: requireNonEmptyString(
+      object.bindingRevision,
+      'SessionBinding.bindingRevision',
+    ),
+    bindingEpoch: requireNonNegativeSafeInteger(
+      object.bindingEpoch,
+      'SessionBinding.bindingEpoch',
+    ),
+  });
+}
+
+export function serializeSessionBinding(input: SessionBinding): string {
+  return canonicalContractJson(createSessionBinding(input));
+}
+
+export function hashSessionBinding(input: SessionBinding): string {
+  return hashCanonicalContract(createSessionBinding(input));
+}

package/src/lib/launch-identity/thread-reuse-key.ts

@@ -0,0 +1,93 @@
+import {
+  canonicalContractJson,
+  hashCanonicalContract,
+  type ResourceBindingRef,
+  requireEnumValue,
+  requireExactObject,
+  requireNonEmptyString,
+  requireResourceBindingRefs,
+  requireSha256,
+} from './canonical-contract';
+
+export enum ThreadReusePolicy {
+  ExplicitlyShareable = 'explicitly-shareable',
+}
+
+export interface ThreadReuseKey {
+  readonly schemaVersion: 1;
+  readonly reusePolicy: ThreadReusePolicy.ExplicitlyShareable;
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly userId: string;
+  readonly runtimeTemplateHash: string;
+  readonly conversationRef: string;
+  readonly workspaceRef: string;
+  readonly domainRefs: readonly ResourceBindingRef[];
+}
+
+const REQUIRED_KEYS = [
+  'schemaVersion',
+  'reusePolicy',
+  'organizationId',
+  'projectId',
+  'userId',
+  'runtimeTemplateHash',
+  'conversationRef',
+  'workspaceRef',
+  'domainRefs',
+] as const;
+
+/**
+ * Canonical identity for the deliberately narrower same-user conversation and
+ * filesystem reuse decision. A RuntimeTemplateKey match alone never permits
+ * Thread reuse.
+ */
+export function createThreadReuseKey(input: unknown): ThreadReuseKey {
+  const object = requireExactObject(input, 'ThreadReuseKey', REQUIRED_KEYS);
+
+  if (object.schemaVersion !== 1) {
+    throw new TypeError('ThreadReuseKey.schemaVersion must be 1.');
+  }
+
+  return Object.freeze({
+    schemaVersion: 1,
+    reusePolicy: requireEnumValue(
+      object.reusePolicy,
+      'ThreadReuseKey.reusePolicy',
+      [ThreadReusePolicy.ExplicitlyShareable],
+    ),
+    organizationId: requireNonEmptyString(
+      object.organizationId,
+      'ThreadReuseKey.organizationId',
+    ),
+    projectId: requireNonEmptyString(
+      object.projectId,
+      'ThreadReuseKey.projectId',
+    ),
+    userId: requireNonEmptyString(object.userId, 'ThreadReuseKey.userId'),
+    runtimeTemplateHash: requireSha256(
+      object.runtimeTemplateHash,
+      'ThreadReuseKey.runtimeTemplateHash',
+    ),
+    conversationRef: requireNonEmptyString(
+      object.conversationRef,
+      'ThreadReuseKey.conversationRef',
+    ),
+    workspaceRef: requireNonEmptyString(
+      object.workspaceRef,
+      'ThreadReuseKey.workspaceRef',
+    ),
+    domainRefs: requireResourceBindingRefs(
+      object.domainRefs,
+      'ThreadReuseKey.domainRefs',
+    ),
+  });
+}
+
+export function serializeThreadReuseKey(input: ThreadReuseKey): string {
+  return canonicalContractJson(createThreadReuseKey(input));
+}
+
+export function hashThreadReuseKey(input: ThreadReuseKey): string {
+  return hashCanonicalContract(createThreadReuseKey(input));
+}

package/src/lib/skill-bundle-template-resolver.ts

@@ -1,7 +1,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── Skill-bundle-backed TemplateResolver ──
 //
-// Phase 10 (workspace-manifests-api retirement). Seed-file templates used to
+// Seed-file templates used to
 // live in `workspace-manifests-api` (the `workspace_manifest_templates` table)
 // and were fetched by name. They are now SKILL-BUNDLE RESOURCES served by
 // `skill-registry-api` (`GET /skills/bundle`): a biome that ships templates

package/src/lib/types.ts

@@ -69,7 +69,7 @@ export interface ComposeWorkspaceImageRequest {
   readonly templateResolver?: TemplateResolver;
   /**
    * Kernel-shipped System-scope skill slugs to PREPEND to the composer's
-   * mounted skill set. Per `.claude/rules/skills-and-composition.md`,
+   * mounted skill set. Per the skill composition rules,
    * skills owned by `SkillSpace.System` are auto-injected into every
    * agent's mounted bundle — they ship from `@xemahq/system-skills`
    * via the System-tier seeder in `skill-registry-api`. The caller