feat(tess): persist durable session state (#729)

apps/gateway/src/agent/__tests__/runtime-provider-registry.service.test.ts

@@ -22,6 +22,8 @@ import {
   type RuntimeApprovalVerifier,
 } from '../runtime-provider-registry.service.js';
 
+process.env['MOSAIC_AGENT_NAME'] ??= 'test-runtime-agent';
+
 const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-1', tenantId: 'tenant-1' };
 const CONTEXT = {
   actorScope: OWNER_SCOPE,
@@ -243,6 +245,7 @@ describe('RuntimeProviderService security boundary', (): void => {
       tenantId: OWNER_SCOPE.tenantId,
       channelId: CONTEXT.channelId,
       correlationId: CONTEXT.correlationId,
+      agentName: process.env['MOSAIC_AGENT_NAME'],
     });
     expect(provider.terminateCalls).toBe(1);
   });

apps/gateway/src/agent/agent.module.ts

@@ -10,14 +10,17 @@ import { ProvidersController } from './providers.controller.js';
 import { SessionsController } from './sessions.controller.js';
 import { AgentConfigsController } from './agent-configs.controller.js';
 import { RoutingController } from './routing/routing.controller.js';
+import { TessDurableSessionRepository } from './tess-durable-session.repository.js';
+import { TessDurableSessionService } from './tess-durable-session.service.js';
 import { CoordModule } from '../coord/coord.module.js';
 import { McpClientModule } from '../mcp-client/mcp-client.module.js';
 import { SkillsModule } from '../skills/skills.module.js';
 import { GCModule } from '../gc/gc.module.js';
 import { LogModule } from '../log/log.module.js';
+import { CommandsModule } from '../commands/commands.module.js';
+import { CommandRuntimeApprovalVerifier } from '../commands/runtime-approval-verifier.js';
 import {
   AGENT_RUNTIME_PROVIDER_REGISTRY,
-  DenyRuntimeApprovalVerifier,
   RUNTIME_APPROVAL_VERIFIER,
   RUNTIME_PROVIDER_AUDIT_SINK,
   RuntimeProviderAuditService,
@@ -26,13 +29,15 @@ import {
 
 @Global()
 @Module({
-  imports: [CoordModule, McpClientModule, SkillsModule, GCModule, LogModule],
+  imports: [CoordModule, McpClientModule, SkillsModule, GCModule, LogModule, CommandsModule],
   providers: [
     ProviderService,
     ProviderCredentialsService,
     RoutingService,
     RoutingEngineService,
     SkillLoaderService,
+    TessDurableSessionRepository,
+    TessDurableSessionService,
     {
       provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
       useFactory: (): AgentRuntimeProviderRegistry => new AgentRuntimeProviderRegistry(),
@@ -42,10 +47,9 @@ import {
       provide: RUNTIME_PROVIDER_AUDIT_SINK,
       useExisting: RuntimeProviderAuditService,
     },
-    DenyRuntimeApprovalVerifier,
     {
       provide: RUNTIME_APPROVAL_VERIFIER,
-      useExisting: DenyRuntimeApprovalVerifier,
+      useExisting: CommandRuntimeApprovalVerifier,
     },
     RuntimeProviderService,
     AgentService,
@@ -58,6 +62,7 @@ import {
     RoutingService,
     RoutingEngineService,
     SkillLoaderService,
+    TessDurableSessionService,
     RuntimeProviderService,
     AGENT_RUNTIME_PROVIDER_REGISTRY,
   ],

apps/gateway/src/agent/runtime-provider-registry.service.ts

@@ -64,12 +64,19 @@ export interface RuntimeTerminationAction {
   tenantId: string;
   channelId: string;
   correlationId: string;
+  agentName: string;
 }
 
 export interface RuntimeApprovalVerifier {
   consume(approvalRef: string, action: RuntimeTerminationAction): Promise<boolean>;
 }
 
+function configuredAgentName(): string {
+  const agentName = process.env['MOSAIC_AGENT_NAME']?.trim();
+  if (!agentName) throw new RuntimeApprovalDeniedError();
+  return agentName;
+}
+
 class RuntimeApprovalDeniedError extends Error {
   constructor() {
     super('Runtime termination approval denied');
@@ -261,6 +268,7 @@ export class RuntimeProviderService {
           tenantId: scope.tenantId,
           channelId: scope.channelId,
           correlationId: scope.correlationId,
+          agentName: configuredAgentName(),
         });
         if (!approved) {
           throw new RuntimeApprovalDeniedError();

apps/gateway/src/agent/tess-durable-session.dto.ts

@@ -0,0 +1,10 @@
+import type { RuntimeProviderRequestContext } from './runtime-provider-registry.service.js';
+
+/** Server-side request for a replay-safe provider message. */
+export interface TessProviderOutboxDto {
+  sessionId: string;
+  idempotencyKey: string;
+  correlationId: string;
+  content: string;
+  context: RuntimeProviderRequestContext;
+}

apps/gateway/src/agent/tess-durable-session.repository.test.ts

@@ -0,0 +1,418 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { eq, sql, interactionCheckpoints, interactionInbox } from '@mosaicstack/db';
+import { DurableSessionCoordinator, type DurableSessionIdentity } from '@mosaicstack/agent';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPgliteDb, runPgliteMigrations, type DbHandle } from '@mosaicstack/db';
+import { TessDurableSessionRepository } from './tess-durable-session.repository.js';
+import { TessDurableSessionService } from './tess-durable-session.service.js';
+
+const IDENTITY: DurableSessionIdentity = {
+  agentName: 'Nova',
+  sessionId: 'tess-pglite-session',
+  tenantId: 'tenant-pglite',
+  ownerId: 'tess-owner',
+  providerId: 'fleet',
+  runtimeSessionId: 'nova',
+};
+
+describe('TessDurableSessionRepository', () => {
+  let dataDir: string | undefined;
+  let handle: DbHandle;
+  let previousAuthSecret: string | undefined;
+
+  beforeAll(async (): Promise<void> => {
+    previousAuthSecret = process.env['BETTER_AUTH_SECRET'];
+    process.env['BETTER_AUTH_SECRET'] = 'tess-durable-state-test-sealing-key';
+    dataDir = mkdtempSync(join(tmpdir(), 'tess-durable-state-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    await seedOwner(handle);
+  }, 30_000);
+
+  beforeEach(async (): Promise<void> => {
+    await handle.db.execute(sql`DELETE FROM interaction_handoffs`);
+    await handle.db.execute(sql`DELETE FROM interaction_checkpoints`);
+    await handle.db.execute(sql`DELETE FROM interaction_inbox`);
+    await handle.db.execute(sql`DELETE FROM interaction_outbox`);
+    await handle.db.execute(sql`DELETE FROM interaction_sessions`);
+  });
+
+  afterAll(async (): Promise<void> => {
+    await handle.close();
+    if (dataDir) rmSync(dataDir, { recursive: true, force: true });
+    if (previousAuthSecret === undefined) delete process.env['BETTER_AUTH_SECRET'];
+    else process.env['BETTER_AUTH_SECRET'] = previousAuthSecret;
+  });
+
+  it('survives a full PGlite close/reopen mid-session without duplicate inbox or outbox side effects', async () => {
+    const beforeRestart = new DurableSessionCoordinator(
+      new TessDurableSessionRepository(handle.db),
+    );
+    await beforeRestart.create(IDENTITY);
+    await beforeRestart.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'inbox-before-kill',
+      correlationId: 'correlation-before-kill',
+      content: 'resume after a kill',
+    });
+    await beforeRestart.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-before-kill',
+      correlationId: 'correlation-before-kill',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'one response only',
+    });
+    await beforeRestart.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-before-kill',
+      cursor: 'cursor-before-kill',
+      summary: 'restart-safe state',
+      compactionEpoch: 1,
+    });
+    await beforeRestart.handoff({
+      sessionId: IDENTITY.sessionId,
+      handoffId: 'handoff-before-kill',
+      destination: 'mos',
+      correlationId: 'correlation-before-kill',
+      checkpointId: 'checkpoint-before-kill',
+      status: 'pending',
+    });
+    await beforeRestart.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-after-handoff',
+      cursor: 'cursor-after-handoff',
+      summary: 'newer state cannot strand the portable handoff',
+      compactionEpoch: 2,
+    });
+
+    await handle.close();
+    handle = createPgliteDb(dataDir!);
+
+    const afterRestart = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    const recovered = await afterRestart.recover(IDENTITY.sessionId);
+    const resumedHandoff = await afterRestart.resumeHandoff('handoff-before-kill');
+    const handled: string[] = [];
+    const effects: string[] = [];
+
+    await afterRestart.drainInbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      handled.push(entry.idempotencyKey);
+    });
+    await afterRestart.dispatchOutbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      effects.push(entry.idempotencyKey);
+    });
+    await afterRestart.drainInbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      handled.push(entry.idempotencyKey);
+    });
+    await afterRestart.dispatchOutbox(IDENTITY.sessionId, async (entry): Promise<void> => {
+      effects.push(entry.idempotencyKey);
+    });
+
+    expect(recovered.identity).toEqual(IDENTITY);
+    expect(recovered.checkpoint).toMatchObject({ checkpointId: 'checkpoint-after-handoff' });
+    expect(recovered.handoffs).toMatchObject([{ handoffId: 'handoff-before-kill' }]);
+    expect(resumedHandoff.checkpoint).toMatchObject({ checkpointId: 'checkpoint-before-kill' });
+    expect(handled).toEqual(['inbox-before-kill']);
+    expect(effects).toEqual(['outbox-before-kill']);
+  }, 30_000);
+
+  it('redacts sensitive durable payloads before persistence', async () => {
+    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    await coordinator.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'redacted-inbox',
+      correlationId: 'correlation-redaction',
+      content: 'api_key=super-secret-canary',
+    });
+    await coordinator.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'redacted-outbox',
+      correlationId: 'correlation-redaction',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'email operator@example.test api_key=super-secret-canary',
+    });
+    await coordinator.checkpoint({
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'redacted-checkpoint',
+      cursor: 'bearer super-secret-canary',
+      summary: 'email operator@example.test',
+      compactionEpoch: 0,
+    });
+
+    const snapshot = await coordinator.snapshot(IDENTITY.sessionId);
+    const [persisted] = await handle.db
+      .select({ content: interactionInbox.content })
+      .from(interactionInbox)
+      .where(eq(interactionInbox.idempotencyKey, 'redacted-inbox'));
+
+    expect(JSON.stringify(snapshot)).not.toContain('super-secret-canary');
+    expect(JSON.stringify(snapshot)).not.toContain('operator@example.test');
+    expect(persisted?.content).not.toContain('super-secret-canary');
+    expect(persisted?.content).not.toContain('[REDACTED]');
+  }, 30_000);
+
+  it('fails closed when the configured idempotency secret is unavailable', async () => {
+    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    const secret = process.env['BETTER_AUTH_SECRET'];
+    delete process.env['BETTER_AUTH_SECRET'];
+    try {
+      await expect(
+        coordinator.receive({
+          sessionId: IDENTITY.sessionId,
+          idempotencyKey: 'requires-idempotency-secret',
+          correlationId: 'correlation-secret',
+          content: 'sensitive payload',
+        }),
+      ).rejects.toThrow(/required for durable idempotency digests/);
+    } finally {
+      if (secret === undefined) delete process.env['BETTER_AUTH_SECRET'];
+      else process.env['BETTER_AUTH_SECRET'] = secret;
+    }
+  }, 30_000);
+
+  it('uses keyed pre-redaction digests to reject distinct sensitive checkpoint payloads', async () => {
+    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    const input = {
+      sessionId: IDENTITY.sessionId,
+      checkpointId: 'checkpoint-secret-conflict',
+      cursor: 'api_key=secret-one',
+      summary: 'bearer secret-one',
+      compactionEpoch: 1,
+    };
+    await coordinator.checkpoint(input);
+
+    await expect(
+      coordinator.checkpoint({
+        ...input,
+        cursor: 'api_key=secret-two',
+        summary: 'bearer secret-two',
+      }),
+    ).rejects.toThrow(/checkpoint identity conflict/);
+
+    const [persisted] = await handle.db
+      .select({
+        digest: interactionCheckpoints.contentDigest,
+        cursor: interactionCheckpoints.cursor,
+      })
+      .from(interactionCheckpoints)
+      .where(eq(interactionCheckpoints.checkpointId, input.checkpointId));
+    expect(persisted?.cursor).not.toContain('secret-one');
+    expect(persisted?.digest).not.toBe(
+      createHash('sha256')
+        .update(JSON.stringify([input.cursor, input.summary]))
+        .digest('hex'),
+    );
+
+    await coordinator.checkpoint({
+      ...input,
+      checkpointId: 'checkpoint-delimiter-conflict',
+      cursor: 'a\u0000b',
+      summary: 'c',
+    });
+    await expect(
+      coordinator.checkpoint({
+        ...input,
+        checkpointId: 'checkpoint-delimiter-conflict',
+        cursor: 'a',
+        summary: 'b\u0000c',
+      }),
+    ).rejects.toThrow(/checkpoint identity conflict/);
+  }, 30_000);
+
+  it('rejects distinct sensitive inbox and outbox payloads under reused idempotency keys', async () => {
+    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    const inbox = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'inbox-secret-conflict',
+      correlationId: 'correlation-inbox-secret',
+      content: 'api_key=secret-one',
+    };
+    const outbox = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-secret-conflict',
+      correlationId: 'correlation-outbox-secret',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'api_key=secret-one',
+    };
+    await coordinator.receive(inbox);
+    await coordinator.enqueueOutbox(outbox);
+
+    await expect(coordinator.receive({ ...inbox, content: 'api_key=secret-two' })).rejects.toThrow(
+      /idempotency conflict/,
+    );
+    await expect(
+      coordinator.enqueueOutbox({ ...outbox, content: 'api_key=secret-two' }),
+    ).rejects.toThrow(/idempotency conflict/);
+  }, 30_000);
+
+  it('rejects database inbox and outbox idempotency-key conflicts', async () => {
+    const coordinator = new DurableSessionCoordinator(new TessDurableSessionRepository(handle.db));
+    await coordinator.create(IDENTITY);
+    await coordinator.receive({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'inbox-conflict',
+      correlationId: 'correlation-inbox',
+      content: 'original inbox',
+    });
+    await coordinator.enqueueOutbox({
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'outbox-conflict',
+      correlationId: 'correlation-outbox',
+      channelId: 'cli',
+      kind: 'provider.send',
+      content: 'original outbox',
+    });
+
+    await expect(
+      coordinator.receive({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'inbox-conflict',
+        correlationId: 'forged-correlation',
+        content: 'original inbox',
+      }),
+    ).rejects.toThrow(/idempotency conflict/);
+    await expect(
+      coordinator.enqueueOutbox({
+        sessionId: IDENTITY.sessionId,
+        idempotencyKey: 'outbox-conflict',
+        correlationId: 'correlation-outbox',
+        channelId: 'forged-channel',
+        kind: 'provider.send',
+        content: 'original outbox',
+      }),
+    ).rejects.toThrow(/idempotency conflict/);
+  }, 30_000);
+
+  it('does not requeue a live outbox claim during a normal scoped dispatch', async () => {
+    const repository = new TessDurableSessionRepository(handle.db);
+    const coordinator = new DurableSessionCoordinator(repository);
+    const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
+    const service = new TessDurableSessionService(repository, runtimeProviders as never);
+    const input = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'live-effect',
+      correlationId: 'correlation-live',
+      content: 'must not duplicate',
+      context: {
+        actorScope: { userId: IDENTITY.ownerId, tenantId: IDENTITY.tenantId },
+        channelId: 'cli',
+        correlationId: 'correlation-live',
+      },
+    };
+
+    await coordinator.create(IDENTITY);
+    await service.queueProviderSend(input);
+    expect(await repository.claimOutbox(IDENTITY.sessionId)).toMatchObject({
+      status: 'processing',
+    });
+
+    await service.dispatchProviderOutbox(IDENTITY.sessionId, input);
+    await expect(
+      service.recoverProviderSession(IDENTITY.sessionId, {
+        ...input,
+        context: {
+          ...input.context,
+          actorScope: { userId: 'intruder', tenantId: 'tenant-pglite' },
+        },
+      }),
+    ).rejects.toThrow(/scope or correlation mismatch/);
+
+    expect(runtimeProviders.sendMessage).not.toHaveBeenCalled();
+    expect(await coordinator.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [{ idempotencyKey: 'live-effect', status: 'processing' }],
+    });
+  }, 30_000);
+
+  it('rejects an outbox correlation mismatch before claiming the pending effect', async () => {
+    const repository = new TessDurableSessionRepository(handle.db);
+    const coordinator = new DurableSessionCoordinator(repository);
+    const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
+    const service = new TessDurableSessionService(repository, runtimeProviders as never);
+    const input = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'mismatch-effect',
+      correlationId: 'correlation-expected',
+      content: 'must remain pending',
+      context: {
+        actorScope: { userId: IDENTITY.ownerId, tenantId: IDENTITY.tenantId },
+        channelId: 'cli',
+        correlationId: 'correlation-expected',
+      },
+    };
+
+    await coordinator.create(IDENTITY);
+    await service.queueProviderSend(input);
+    await expect(
+      service.dispatchProviderOutbox(IDENTITY.sessionId, {
+        ...input,
+        correlationId: 'correlation-forged',
+        context: { ...input.context, correlationId: 'correlation-forged' },
+      }),
+    ).rejects.toThrow(/scope or correlation mismatch/);
+
+    expect(runtimeProviders.sendMessage).not.toHaveBeenCalled();
+    expect(await coordinator.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [{ idempotencyKey: 'mismatch-effect', status: 'pending' }],
+    });
+  }, 30_000);
+
+  it('dispatches only the outbox record bound to the supplied correlation and channel', async () => {
+    const repository = new TessDurableSessionRepository(handle.db);
+    const coordinator = new DurableSessionCoordinator(repository);
+    const runtimeProviders = { sendMessage: vi.fn().mockResolvedValue(undefined) };
+    const service = new TessDurableSessionService(repository, runtimeProviders as never);
+    const first = {
+      sessionId: IDENTITY.sessionId,
+      idempotencyKey: 'scoped-effect-one',
+      correlationId: 'correlation-one',
+      content: 'first result',
+      context: {
+        actorScope: { userId: IDENTITY.ownerId, tenantId: IDENTITY.tenantId },
+        channelId: 'cli',
+        correlationId: 'correlation-one',
+      },
+    };
+    const second = {
+      ...first,
+      idempotencyKey: 'scoped-effect-two',
+      correlationId: 'correlation-two',
+      content: 'second result',
+      context: { ...first.context, correlationId: 'correlation-two' },
+    };
+
+    await coordinator.create(IDENTITY);
+    await service.queueProviderSend(first);
+    await service.queueProviderSend(second);
+    await service.dispatchProviderOutbox(IDENTITY.sessionId, first);
+
+    expect(runtimeProviders.sendMessage).toHaveBeenCalledTimes(1);
+    expect(runtimeProviders.sendMessage).toHaveBeenCalledWith(
+      IDENTITY.providerId,
+      IDENTITY.runtimeSessionId,
+      { content: 'first result', idempotencyKey: 'scoped-effect-one' },
+      first.context,
+    );
+    expect(await coordinator.snapshot(IDENTITY.sessionId)).toMatchObject({
+      outbox: [
+        { idempotencyKey: 'scoped-effect-one', status: 'delivered' },
+        { idempotencyKey: 'scoped-effect-two', status: 'pending' },
+      ],
+    });
+  }, 30_000);
+});
+
+async function seedOwner(handle: DbHandle): Promise<void> {
+  await handle.db.execute(sql`
+    INSERT INTO users (id, name, email, email_verified, created_at, updated_at)
+    VALUES ('tess-owner', 'Tess Owner', 'tess-owner@example.test', false, now(), now())
+  `);
+}

apps/gateway/src/agent/tess-durable-session.repository.ts

@@ -0,0 +1,521 @@
+import { createHash, createHmac } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  interactionCheckpoints,
+  interactionHandoffs,
+  interactionInbox,
+  interactionOutbox,
+  interactionSessions,
+  type Db,
+} from '@mosaicstack/db';
+import { seal, unseal } from '@mosaicstack/auth';
+import { redactSensitiveContent } from '@mosaicstack/log';
+import type {
+  DurableCheckpoint,
+  DurableCheckpointInput,
+  DurableEnqueueResult,
+  DurableHandoff,
+  DurableHandoffInput,
+  DurableInboxEntry,
+  DurableInboxInput,
+  DurableInboxStatus,
+  DurableOutboxEntry,
+  DurableOutboxInput,
+  DurableOutboxStatus,
+  DurableSessionIdentity,
+  DurableSessionSnapshot,
+  DurableSessionStore,
+} from '@mosaicstack/agent';
+import { DB } from '../database/database.module.js';
+
+@Injectable()
+export class TessDurableSessionRepository implements DurableSessionStore {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async create(identity: DurableSessionIdentity): Promise<void> {
+    await this.db
+      .insert(interactionSessions)
+      .values({
+        id: identity.sessionId,
+        agentName: identity.agentName,
+        tenantId: identity.tenantId,
+        ownerId: identity.ownerId,
+        providerId: identity.providerId,
+        runtimeSessionId: identity.runtimeSessionId,
+      })
+      .onConflictDoNothing();
+
+    const existing = await this.session(identity.sessionId);
+    if (!existing || !sameIdentity(existing, identity)) {
+      throw new Error(`Durable Tess session identity conflict: ${identity.sessionId}`);
+    }
+  }
+
+  async snapshot(sessionId: string): Promise<DurableSessionSnapshot | null> {
+    const identity = await this.session(sessionId);
+    if (!identity) return null;
+
+    const [inbox, outbox, checkpoints, handoffs] = await Promise.all([
+      this.db
+        .select()
+        .from(interactionInbox)
+        .where(eq(interactionInbox.sessionId, sessionId))
+        .orderBy(asc(interactionInbox.createdAt)),
+      this.db
+        .select()
+        .from(interactionOutbox)
+        .where(eq(interactionOutbox.sessionId, sessionId))
+        .orderBy(asc(interactionOutbox.createdAt)),
+      this.db
+        .select()
+        .from(interactionCheckpoints)
+        .where(eq(interactionCheckpoints.sessionId, sessionId))
+        .orderBy(
+          desc(interactionCheckpoints.compactionEpoch),
+          desc(interactionCheckpoints.createdAt),
+        )
+        .limit(1),
+      this.db
+        .select()
+        .from(interactionHandoffs)
+        .where(eq(interactionHandoffs.sessionId, sessionId))
+        .orderBy(asc(interactionHandoffs.createdAt)),
+    ]);
+
+    const checkpoint = checkpoints[0];
+    return {
+      identity,
+      inbox: inbox.map(toInbox),
+      outbox: outbox.map(toOutbox),
+      ...(checkpoint ? { checkpoint: toCheckpoint(checkpoint) } : {}),
+      handoffs: handoffs.map(toHandoff),
+    };
+  }
+
+  async enqueueInbox(input: DurableInboxInput): Promise<DurableEnqueueResult<DurableInboxStatus>> {
+    const digest = contentDigest(input.content);
+    const record: DurableInboxInput = {
+      ...input,
+      content: redactSensitiveContent(input.content).content,
+    };
+    const inserted = await this.db
+      .insert(interactionInbox)
+      .values({
+        ...record,
+        content: seal(record.content),
+        contentDigest: digest,
+        status: 'pending',
+      })
+      .onConflictDoNothing()
+      .returning({ status: interactionInbox.status });
+    if (inserted[0]) return { accepted: true, status: inserted[0].status };
+
+    const existing = await this.db
+      .select()
+      .from(interactionInbox)
+      .where(
+        and(
+          eq(interactionInbox.sessionId, input.sessionId),
+          eq(interactionInbox.idempotencyKey, input.idempotencyKey),
+        ),
+      )
+      .limit(1);
+    if (!existing[0]) throw new Error(`Durable Tess inbox enqueue failed: ${input.idempotencyKey}`);
+    const entry = toInbox(existing[0]);
+    if (
+      !sameInbox(entry, record) ||
+      !matchesContentDigest(existing[0].contentDigest, input.content)
+    ) {
+      throw new Error(`Durable Tess inbox idempotency conflict: ${input.idempotencyKey}`);
+    }
+    return { accepted: false, status: entry.status };
+  }
+
+  async claimInbox(sessionId: string): Promise<DurableInboxEntry | null> {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const candidate = await this.db
+        .select()
+        .from(interactionInbox)
+        .where(
+          and(eq(interactionInbox.sessionId, sessionId), eq(interactionInbox.status, 'pending')),
+        )
+        .orderBy(asc(interactionInbox.createdAt))
+        .limit(1);
+      const entry = candidate[0];
+      if (!entry) return null;
+      const claimed = await this.db
+        .update(interactionInbox)
+        .set({ status: 'processing', updatedAt: new Date() })
+        .where(and(eq(interactionInbox.id, entry.id), eq(interactionInbox.status, 'pending')))
+        .returning();
+      if (claimed[0]) return toInbox(claimed[0]);
+    }
+    return null;
+  }
+
+  async completeInbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionInbox)
+      .set({ status: 'processed', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionInbox.sessionId, sessionId),
+          eq(interactionInbox.idempotencyKey, idempotencyKey),
+          eq(interactionInbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async releaseInbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionInbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionInbox.sessionId, sessionId),
+          eq(interactionInbox.idempotencyKey, idempotencyKey),
+          eq(interactionInbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async enqueueOutbox(
+    input: DurableOutboxInput,
+  ): Promise<DurableEnqueueResult<DurableOutboxStatus>> {
+    const digest = contentDigest(input.content);
+    const record: DurableOutboxInput = {
+      ...input,
+      content: redactSensitiveContent(input.content).content,
+    };
+    const inserted = await this.db
+      .insert(interactionOutbox)
+      .values({
+        ...record,
+        content: seal(record.content),
+        contentDigest: digest,
+        status: 'pending',
+      })
+      .onConflictDoNothing()
+      .returning({ status: interactionOutbox.status });
+    if (inserted[0]) return { accepted: true, status: inserted[0].status };
+
+    const existing = await this.db
+      .select()
+      .from(interactionOutbox)
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, input.sessionId),
+          eq(interactionOutbox.idempotencyKey, input.idempotencyKey),
+        ),
+      )
+      .limit(1);
+    if (!existing[0])
+      throw new Error(`Durable Tess outbox enqueue failed: ${input.idempotencyKey}`);
+    const entry = toOutbox(existing[0]);
+    if (
+      !sameOutbox(entry, record) ||
+      !matchesContentDigest(existing[0].contentDigest, input.content)
+    ) {
+      throw new Error(`Durable Tess outbox idempotency conflict: ${input.idempotencyKey}`);
+    }
+    return { accepted: false, status: entry.status };
+  }
+
+  async claimOutbox(sessionId: string): Promise<DurableOutboxEntry | null> {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const candidate = await this.db
+        .select()
+        .from(interactionOutbox)
+        .where(
+          and(eq(interactionOutbox.sessionId, sessionId), eq(interactionOutbox.status, 'pending')),
+        )
+        .orderBy(asc(interactionOutbox.createdAt))
+        .limit(1);
+      const entry = candidate[0];
+      if (!entry) return null;
+      const claimed = await this.db
+        .update(interactionOutbox)
+        .set({ status: 'processing', updatedAt: new Date() })
+        .where(and(eq(interactionOutbox.id, entry.id), eq(interactionOutbox.status, 'pending')))
+        .returning();
+      if (claimed[0]) return toOutbox(claimed[0]);
+    }
+    return null;
+  }
+
+  async claimOutboxByKey(
+    sessionId: string,
+    idempotencyKey: string,
+  ): Promise<DurableOutboxEntry | null> {
+    const claimed = await this.db
+      .update(interactionOutbox)
+      .set({ status: 'processing', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, sessionId),
+          eq(interactionOutbox.idempotencyKey, idempotencyKey),
+          eq(interactionOutbox.status, 'pending'),
+        ),
+      )
+      .returning();
+    return claimed[0] ? toOutbox(claimed[0]) : null;
+  }
+
+  async completeOutbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionOutbox)
+      .set({ status: 'delivered', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, sessionId),
+          eq(interactionOutbox.idempotencyKey, idempotencyKey),
+          eq(interactionOutbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async releaseOutbox(sessionId: string, idempotencyKey: string): Promise<void> {
+    await this.db
+      .update(interactionOutbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(
+        and(
+          eq(interactionOutbox.sessionId, sessionId),
+          eq(interactionOutbox.idempotencyKey, idempotencyKey),
+          eq(interactionOutbox.status, 'processing'),
+        ),
+      );
+  }
+
+  async checkpoint(input: DurableCheckpointInput): Promise<void> {
+    // Compute identity before redaction.  The persisted digest is keyed so a database
+    // reader cannot use it as an offline oracle for sensitive cursor/summary values.
+    const digest = contentDigest(JSON.stringify([input.cursor, input.summary]));
+    const checkpoint: DurableCheckpointInput = {
+      ...input,
+      cursor: redactSensitiveContent(input.cursor).content,
+      summary: redactSensitiveContent(input.summary).content,
+    };
+    const inserted = await this.db
+      .insert(interactionCheckpoints)
+      .values({
+        ...checkpoint,
+        contentDigest: digest,
+        cursor: seal(checkpoint.cursor),
+        summary: seal(checkpoint.summary),
+      })
+      .onConflictDoNothing()
+      .returning({ checkpointId: interactionCheckpoints.checkpointId });
+    if (inserted[0]) return;
+
+    const existing = await this.db
+      .select()
+      .from(interactionCheckpoints)
+      .where(
+        and(
+          eq(interactionCheckpoints.sessionId, input.sessionId),
+          eq(interactionCheckpoints.checkpointId, input.checkpointId),
+        ),
+      )
+      .limit(1);
+    if (
+      !existing[0] ||
+      !sameCheckpoint(toCheckpoint(existing[0]), checkpoint) ||
+      !matchesCheckpointDigest(existing[0].contentDigest, digest)
+    ) {
+      throw new Error(`Durable Tess checkpoint identity conflict: ${input.checkpointId}`);
+    }
+  }
+
+  async findCheckpoint(sessionId: string, checkpointId: string): Promise<DurableCheckpoint | null> {
+    const checkpoints = await this.db
+      .select()
+      .from(interactionCheckpoints)
+      .where(
+        and(
+          eq(interactionCheckpoints.sessionId, sessionId),
+          eq(interactionCheckpoints.checkpointId, checkpointId),
+        ),
+      )
+      .limit(1);
+    const checkpoint = checkpoints[0];
+    return checkpoint ? toCheckpoint(checkpoint) : null;
+  }
+
+  async handoff(input: DurableHandoffInput): Promise<void> {
+    const checkpoint = await this.findCheckpoint(input.sessionId, input.checkpointId);
+    if (!checkpoint) {
+      throw new Error(`Durable Tess handoff checkpoint is unavailable: ${input.checkpointId}`);
+    }
+    const inserted = await this.db
+      .insert(interactionHandoffs)
+      .values({ ...input })
+      .onConflictDoNothing()
+      .returning({ handoffId: interactionHandoffs.handoffId });
+    if (inserted[0]) return;
+
+    const existing = await this.findHandoff(input.handoffId);
+    if (!existing || !sameHandoff(existing, input)) {
+      throw new Error(`Durable Tess handoff identity conflict: ${input.handoffId}`);
+    }
+  }
+
+  async findHandoff(handoffId: string): Promise<DurableHandoff | null> {
+    const handoffs = await this.db
+      .select()
+      .from(interactionHandoffs)
+      .where(eq(interactionHandoffs.handoffId, handoffId))
+      .limit(1);
+    const handoff = handoffs[0];
+    return handoff ? toHandoff(handoff) : null;
+  }
+
+  async requeueInFlight(sessionId: string): Promise<void> {
+    // Inbox handlers are process-local work. A provider outbox claim may have
+    // reached an external target before a crash, so it is deliberately not
+    // replayed by generic recovery.
+    await this.db
+      .update(interactionInbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(
+        and(eq(interactionInbox.sessionId, sessionId), eq(interactionInbox.status, 'processing')),
+      );
+  }
+
+  private async session(sessionId: string): Promise<DurableSessionIdentity | null> {
+    const sessions = await this.db
+      .select()
+      .from(interactionSessions)
+      .where(eq(interactionSessions.id, sessionId))
+      .limit(1);
+    const session = sessions[0];
+    return session
+      ? {
+          agentName: session.agentName,
+          sessionId: session.id,
+          tenantId: session.tenantId,
+          ownerId: session.ownerId,
+          providerId: session.providerId,
+          runtimeSessionId: session.runtimeSessionId,
+        }
+      : null;
+  }
+}
+
+function contentDigest(content: string): string {
+  const secret = process.env['BETTER_AUTH_SECRET'];
+  if (!secret) {
+    throw new Error('BETTER_AUTH_SECRET is required for durable idempotency digests');
+  }
+  return `hmac:v1:${createHmac('sha256', secret).update(content).digest('hex')}`;
+}
+
+function matchesContentDigest(stored: string, content: string): boolean {
+  return (
+    stored === contentDigest(content) ||
+    stored === createHash('sha256').update(content).digest('hex')
+  );
+}
+
+function matchesCheckpointDigest(stored: string, digest: string): boolean {
+  // Legacy rows predate any pre-redaction identity and cannot safely prove equality.
+  // Reject rather than let redaction collapse distinct sensitive checkpoint payloads.
+  return stored === digest;
+}
+
+function sameIdentity(left: DurableSessionIdentity, right: DurableSessionIdentity): boolean {
+  return (
+    left.agentName === right.agentName &&
+    left.sessionId === right.sessionId &&
+    left.tenantId === right.tenantId &&
+    left.ownerId === right.ownerId &&
+    left.providerId === right.providerId &&
+    left.runtimeSessionId === right.runtimeSessionId
+  );
+}
+
+function sameInbox(left: DurableInboxEntry, right: DurableInboxInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.correlationId === right.correlationId &&
+    left.content === right.content
+  );
+}
+
+function sameOutbox(left: DurableOutboxEntry, right: DurableOutboxInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.idempotencyKey === right.idempotencyKey &&
+    left.correlationId === right.correlationId &&
+    left.channelId === right.channelId &&
+    left.kind === right.kind &&
+    left.content === right.content
+  );
+}
+
+function sameCheckpoint(left: DurableCheckpoint, right: DurableCheckpointInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.checkpointId === right.checkpointId &&
+    left.compactionEpoch === right.compactionEpoch
+  );
+}
+
+function sameHandoff(left: DurableHandoff, right: DurableHandoffInput): boolean {
+  return (
+    left.sessionId === right.sessionId &&
+    left.handoffId === right.handoffId &&
+    left.destination === right.destination &&
+    left.correlationId === right.correlationId &&
+    left.checkpointId === right.checkpointId &&
+    left.status === right.status
+  );
+}
+
+function toInbox(row: typeof interactionInbox.$inferSelect): DurableInboxEntry {
+  return {
+    sessionId: row.sessionId,
+    idempotencyKey: row.idempotencyKey,
+    correlationId: row.correlationId,
+    content: unseal(row.content),
+    status: row.status,
+  };
+}
+
+function toOutbox(row: typeof interactionOutbox.$inferSelect): DurableOutboxEntry {
+  return {
+    sessionId: row.sessionId,
+    idempotencyKey: row.idempotencyKey,
+    correlationId: row.correlationId,
+    channelId: row.channelId,
+    kind: row.kind,
+    content: unseal(row.content),
+    status: row.status,
+  };
+}
+
+function toCheckpoint(row: typeof interactionCheckpoints.$inferSelect): DurableCheckpoint {
+  return {
+    sessionId: row.sessionId,
+    checkpointId: row.checkpointId,
+    cursor: unseal(row.cursor),
+    summary: unseal(row.summary),
+    compactionEpoch: row.compactionEpoch,
+  };
+}
+
+function toHandoff(row: typeof interactionHandoffs.$inferSelect): DurableHandoff {
+  return {
+    sessionId: row.sessionId,
+    handoffId: row.handoffId,
+    destination: row.destination,
+    correlationId: row.correlationId,
+    checkpointId: row.checkpointId,
+    status: row.status,
+  };
+}

apps/gateway/src/agent/tess-durable-session.service.ts

@@ -0,0 +1,93 @@
+import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
+import { DurableSessionCoordinator } from '@mosaicstack/agent';
+import type { TessProviderOutboxDto } from './tess-durable-session.dto.js';
+import { TessDurableSessionRepository } from './tess-durable-session.repository.js';
+import { RuntimeProviderService } from './runtime-provider-registry.service.js';
+
+/**
+ * Scoped gateway boundary for the canonical Tess state machine. It deliberately
+ * uses composition: raw state methods cannot be injected into channel, CLI, or
+ * MCP adapters without a server-derived actor/tenant/correlation context.
+ */
+@Injectable()
+export class TessDurableSessionService {
+  private readonly coordinator: DurableSessionCoordinator;
+
+  constructor(
+    @Inject(TessDurableSessionRepository) repository: TessDurableSessionRepository,
+    @Inject(RuntimeProviderService) private readonly runtimeProviders: RuntimeProviderService,
+  ) {
+    this.coordinator = new DurableSessionCoordinator(repository);
+  }
+
+  async queueProviderSend(input: TessProviderOutboxDto): Promise<void> {
+    const snapshot = await this.coordinator.snapshot(input.sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    await this.coordinator.enqueueOutbox({
+      sessionId: input.sessionId,
+      idempotencyKey: input.idempotencyKey,
+      correlationId: input.correlationId,
+      channelId: input.context.channelId,
+      kind: 'provider.send',
+      content: input.content,
+    });
+  }
+
+  async dispatchProviderOutbox(sessionId: string, input: TessProviderOutboxDto): Promise<void> {
+    if (sessionId !== input.sessionId) {
+      throw new ForbiddenException('Durable Tess outbox session mismatch');
+    }
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    const pendingEntry = snapshot.outbox.find(
+      (entry): boolean => entry.idempotencyKey === input.idempotencyKey,
+    );
+    if (!pendingEntry) return;
+    // Validate immutable routing before claiming. A caller with a mismatched
+    // correlation/channel must not strand a pending external side effect.
+    this.assertOutboxScope(pendingEntry, input);
+    await this.coordinator.dispatchOutboxEntry(
+      sessionId,
+      input.idempotencyKey,
+      async (entry): Promise<void> => {
+        this.assertOutboxScope(entry, input);
+        await this.runtimeProviders.sendMessage(
+          snapshot.identity.providerId,
+          snapshot.identity.runtimeSessionId,
+          { content: entry.content, idempotencyKey: entry.idempotencyKey },
+          input.context,
+        );
+      },
+    );
+  }
+
+  /** Startup/recovery-only path; normal queue/dispatch methods never requeue live work. */
+  async recoverProviderSession(sessionId: string, input: TessProviderOutboxDto): Promise<void> {
+    const snapshot = await this.coordinator.snapshot(sessionId);
+    this.assertScope(snapshot.identity.ownerId, snapshot.identity.tenantId, input);
+    await this.coordinator.recover(sessionId);
+  }
+
+  private assertOutboxScope(
+    entry: { kind: string; correlationId: string; channelId: string },
+    input: TessProviderOutboxDto,
+  ): void {
+    if (
+      entry.kind !== 'provider.send' ||
+      entry.correlationId !== input.correlationId ||
+      entry.channelId !== input.context.channelId
+    ) {
+      throw new ForbiddenException('Durable Tess outbox scope or correlation mismatch');
+    }
+  }
+
+  private assertScope(ownerId: string, tenantId: string, input: TessProviderOutboxDto): void {
+    if (
+      input.context.actorScope.userId !== ownerId ||
+      input.context.actorScope.tenantId !== tenantId ||
+      input.context.correlationId !== input.correlationId
+    ) {
+      throw new ForbiddenException('Durable Tess session scope or correlation mismatch');
+    }
+  }
+}