@xemahq/agent-session-runtime 0.11.1 → 0.12.0

package/src/lib/dispatch-contract.ts

@@ -1,151 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Agent-session dispatch wire contract ──
-//
-// Typed shapes the workflow-runtime-worker activity passes to (and
-// receives from) `agent-session-api`'s
-// `POST /internal/sessions/:id/dispatch` endpoint.
-//
-// These live in the Kernel package so the worker can depend on them
-// without pulling in the (large) Orval client at type-check time. The
-// generated Orval models in `@xemahq/agent-session-api-client` MUST be
-// structurally compatible — CI enforces it via a type-equality check
-// in `biomes/agent-runtime/api/agent-session-api/test/contract-compat.test.ts`.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import type { ArtifactRef } from '@xemahq/kernel-contracts/workflow';
-
-/**
- * Mode discriminator on the dispatch envelope. Drives whether the
- * service creates a fresh Session row or resumes an existing one.
- */
-export const AgentSessionDispatchMode = {
-  /** Iter 1: mint a new Session, provision a worker, run one turn, pause. */
-  create_and_run: 'create_and_run',
-  /** Iter N+1: resume an existing Session, mount revision inputs, run one turn, pause. */
-  resume_and_run: 'resume_and_run',
-} as const;
-
-export type AgentSessionDispatchModeValue =
-  (typeof AgentSessionDispatchMode)[keyof typeof AgentSessionDispatchMode];
-
-/**
- * A single revision input file to seed into `/workspace/inputs/...`
- * BEFORE the agent's turn starts. The dispatch service writes the file
- * via workspace-proxy's mount-apply call (one round-trip), so the
- * agent's first read of the workspace sees it.
- *
- * The path is RELATIVE to `/workspace/inputs/` and validated against
- * path-traversal (`..`, absolute paths, symlinks). Slot membership is
- * enforced — only paths inside the manifest's declared `inputs` slot
- * can be written.
- */
-export interface RevisionInput {
-  /**
-   * Path under `/workspace/inputs/`, e.g. `revisions/revision-2-<iso>.md`.
-   * Validated: no leading slash, no `..`, must match the declared
-   * inputs-slot subpath whitelist.
-   */
-  readonly path: string;
-  /** Base64-encoded file bytes. UTF-8 markdown is the common case. */
-  readonly contentBase64: string;
-}
-
-/**
- * Per-iteration prompt-side context the worker hands to the agent.
- * Kept small on purpose: the bulk of the iteration's reviewer-feedback
- * lives in the revision file, not here. The agent reads the file path
- * out of `revisionFilePath` and `read`s it from the workspace.
- */
-export interface DispatchPromptContext {
-  /** Free-form task statement (same shape as `agentContext.prompt` today). */
-  readonly prompt: string;
-  /**
-   * Path inside the workspace where the agent will find the actionable
-   * revision directive for this iteration. Omitted on iter 1.
-   * Example: `inputs/revisions/revision-2-2026-05-19T12-30-00Z.md`.
-   */
-  readonly revisionFilePath?: string;
-  /**
-   * Iteration number for telemetry / heartbeat. `1` for create-and-run,
-   * `>=2` for resume-and-run.
-   */
-  readonly iteration: number;
-}
-
-/**
- * `mode: create_and_run` payload. The service creates a Session, calls
- * pool acquire, then drives one turn.
- */
-export interface CreateAndRunDispatch {
-  readonly mode: typeof AgentSessionDispatchMode.create_and_run;
-  /** ownerKind is forced to `pipeline_run` on this code path. */
-  readonly pipelineRunId: string;
-  readonly jobRunId: string;
-  /** Stable spine identity within the workflow run. */
-  readonly jobKey: string;
-  /** Immutable AgentRevision selected by workflow resolution. */
-  readonly agentRevisionId: string;
-  /** SHA-256 of the selected AgentRevision content. */
-  readonly agentContentHash: string;
-  readonly agentSlug: string;
-  readonly promptContext: DispatchPromptContext;
-}
-
-/**
- * `mode: resume_and_run` payload. The service resumes the named
- * Session (must be `paused`), writes the revision inputs into the
- * workspace as part of mount-apply, then drives one turn.
- */
-export interface ResumeAndRunDispatch {
-  readonly mode: typeof AgentSessionDispatchMode.resume_and_run;
-  readonly sessionId: string;
-  readonly revisionInputs: readonly RevisionInput[];
-  readonly promptContext: DispatchPromptContext;
-}
-
-export type AgentSessionDispatchRequest =
-  | CreateAndRunDispatch
-  | ResumeAndRunDispatch;
-
-/**
- * Response from the dispatch endpoint. Carries the harvested outputs
- * from the turn AND the session's new (post-pause) snapshot generation
- * so the caller can correlate the iteration with its MinIO blob.
- *
- * The `sessionId` is echoed back so a `create_and_run` caller can
- * record it on Temporal state for the next iteration.
- */
-export interface AgentSessionDispatchResponse {
-  readonly sessionId: string;
-  readonly snapshotGeneration: number;
-  readonly pausedAt: string;
-  /** Harvested deliverables (artifact refs emitted by the agent's turn). */
-  readonly deliverables: readonly ArtifactRef[];
-  /**
-   * Free-form structured output (e.g. inquiry answers). Same shape as
-   * today's `RawAgentActivityOutput.structuredOutput`.
-   */
-  readonly structuredOutput: unknown;
-  /**
-   * Markdown response artifact ref (if the manifest declared one).
-   * Same shape as today's `RawAgentActivityOutput.response`.
-   */
-  readonly response: ArtifactRef | null;
-}
-
-/**
- * Body for `POST /internal/sessions/:id/inputs/append`. Used by
- * out-of-band callers (e.g. interactive-session UI file uploads) when
- * the fast path through mount-apply isn't applicable. Internal-only;
- * never exposed through the public Gateway.
- */
-export interface InputsAppendRequest {
-  readonly path: string;
-  readonly contentBase64: string;
-}
-
-export interface InputsAppendResponse {
-  readonly written: boolean;
-  /** SHA-256 of the bytes as written. Useful for idempotency checks. */
-  readonly sha256: string;
-}

package/src/lib/drift-detector.ts

@@ -1,497 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Environment drift detector ──
-//
-// Diffs two `ResolvedEnvironment` snapshots and emits a structured
-// drift report. Used by agent-session resume to compare the
-// snapshot from the previous run against a freshly-resolved snapshot
-// at resume time — re-resolve is the source of truth, drift is what
-// surfaces to the operator.
-//
-// Drift kinds are a closed enum (`DriftKind`). Severity is `info |
-// warning` — purely advisory: NO drift blocks a resume. Resume always
-// proceeds with the freshly-resolved environment; the drift list is
-// surfaced to the operator (timeline entry + the `SessionResumed`
-// degradation toast) so they see what changed. `warning` flags the
-// changes worth a second look (a removed sub-agent/skill/credential, a
-// changed agent, a tightened permission); `info` is benign drift
-// (version bumps, additions, value tweaks).
-// ═══════════════════════════════════════════════════════════════════════════
-
-import type { ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
-import type {
-  CompiledManifestCredential,
-  CompiledManifestSkillRef,
-  SubAgentBinding,
-} from '@xemahq/kernel-contracts/workflow';
-
-import type { ResolvedEnvironment } from './environment-resolver';
-
-export enum DriftKind {
-  AGENT_CHANGED = 'agent-changed',
-  ROLE_CHANGED = 'role-changed',
-  MANIFEST_VERSION_CHANGED = 'manifest-version-changed',
-  MODEL_CHANGED = 'model-changed',
-  SUBAGENT_ADDED = 'subagent-added',
-  SUBAGENT_REMOVED = 'subagent-removed',
-  SUBAGENT_MODEL_CHANGED = 'subagent-model-changed',
-  SKILL_ADDED = 'skill-added',
-  SKILL_REMOVED = 'skill-removed',
-  SKILL_VERSION_CHANGED = 'skill-version-changed',
-  TOOL_SELECTION_ADDED = 'tool-selection-added',
-  TOOL_SELECTION_REMOVED = 'tool-selection-removed',
-  CREDENTIAL_ADDED = 'credential-added',
-  CREDENTIAL_REMOVED = 'credential-removed',
-  CREDENTIAL_KIND_CHANGED = 'credential-kind-changed',
-  PERMISSION_TIGHTENED = 'permission-tightened',
-  PERMISSION_RELAXED = 'permission-relaxed',
-  PERSISTENCE_PATH_ADDED = 'persistence-path-added',
-  PERSISTENCE_PATH_REMOVED = 'persistence-path-removed',
-  OUTPUT_SURFACE_CHANGED = 'output-surface-changed',
-  ENV_VAR_ADDED = 'env-var-added',
-  ENV_VAR_REMOVED = 'env-var-removed',
-  ENV_VAR_VALUE_CHANGED = 'env-var-value-changed',
-  MOUNT_ADDED = 'mount-added',
-  MOUNT_REMOVED = 'mount-removed',
-  MOUNT_MODE_CHANGED = 'mount-mode-changed',
-}
-
-/**
- * Advisory drift severity — `info` (benign) or `warning` (worth a look).
- * There is deliberately no `critical`: resume is non-blocking by design,
- * so severity only drives how the operator's drift
- * toast renders, never whether the session resumes.
- */
-export type DriftSeverity = 'info' | 'warning';
-
-export interface EnvironmentDrift {
-  readonly kind: DriftKind;
-  readonly severity: DriftSeverity;
-  readonly path: string;
-  readonly before?: unknown;
-  readonly after?: unknown;
-  readonly message: string;
-}
-
-/**
- * Diff two `ResolvedEnvironment` snapshots. Returns a possibly-empty
- * array of structured drifts. Order is stable (insertion order across
- * the structured walk) so callers can render a deterministic timeline
- * entry.
- *
- * Equal hashes short-circuit to `[]` — the hash covers every
- * structured field, so two snapshots with the same hash are
- * guaranteed to produce no drift.
- */
-export function diffResolvedEnvironment(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-): readonly EnvironmentDrift[] {
-  if (prev.hash === next.hash) {return [];}
-
-  const drifts: EnvironmentDrift[] = [];
-
-  diffAgent(prev, next, drifts);
-  diffSubAgents(prev.subAgents, next.subAgents, drifts);
-  diffSkills(prev.skills, next.skills, drifts);
-  diffToolSelection(prev.toolSelection, next.toolSelection, drifts);
-  diffCredentials(prev.credentials, next.credentials, drifts);
-  diffPermissions(prev, next, drifts);
-  diffPersistence(prev, next, drifts);
-  diffOutputSurface(prev, next, drifts);
-  diffEnv(prev, next, drifts);
-  diffMounts(prev, next, drifts);
-
-  return drifts;
-}
-
-function diffAgent(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-  out: EnvironmentDrift[],
-): void {
-  if (prev.manifest.version !== next.manifest.version) {
-    out.push({
-      kind: DriftKind.MANIFEST_VERSION_CHANGED,
-      severity: 'info',
-      path: '$.manifest.version',
-      before: prev.manifest.version,
-      after: next.manifest.version,
-      message: `Manifest version moved ${prev.manifest.version} → ${next.manifest.version}.`,
-    });
-  }
-  if (prev.agent.slug !== next.agent.slug) {
-    out.push({
-      kind: DriftKind.AGENT_CHANGED,
-      severity: 'warning',
-      path: '$.agent.slug',
-      before: prev.agent.slug,
-      after: next.agent.slug,
-      message: `Primary agent slug changed ${prev.agent.slug} → ${next.agent.slug}; the session resumes with the new agent.`,
-    });
-  }
-  if (prev.agent.role !== next.agent.role) {
-    out.push({
-      kind: DriftKind.ROLE_CHANGED,
-      severity: 'info',
-      path: '$.agent.role',
-      before: prev.agent.role,
-      after: next.agent.role,
-      message: `Agent role changed ${prev.agent.role} → ${next.agent.role}; AGENTS.md will be re-rendered.`,
-    });
-  }
-  const prevModel = JSON.stringify(prev.agent.model ?? null);
-  const nextModel = JSON.stringify(next.agent.model ?? null);
-  if (prevModel !== nextModel) {
-    out.push({
-      kind: DriftKind.MODEL_CHANGED,
-      severity: 'info',
-      path: '$.agent.model',
-      before: prev.agent.model,
-      after: next.agent.model,
-      message: 'Primary agent default model changed.',
-    });
-  }
-}
-
-function diffSubAgents(
-  prev: readonly SubAgentBinding[],
-  next: readonly SubAgentBinding[],
-  out: EnvironmentDrift[],
-): void {
-  const prevBySlug = new Map(prev.map((s) => [s.slug, s]));
-  const nextBySlug = new Map(next.map((s) => [s.slug, s]));
-  for (const [slug, n] of nextBySlug) {
-    const p = prevBySlug.get(slug);
-    if (!p) {
-      out.push({
-        kind: DriftKind.SUBAGENT_ADDED,
-        severity: 'info',
-        path: `$.subAgents[${slug}]`,
-        after: n,
-        message: `Sub-agent '${slug}' added.`,
-      });
-      continue;
-    }
-    if (JSON.stringify(p.modelOverride ?? null) !== JSON.stringify(n.modelOverride ?? null)) {
-      out.push({
-        kind: DriftKind.SUBAGENT_MODEL_CHANGED,
-        severity: 'info',
-        path: `$.subAgents[${slug}].modelOverride`,
-        before: p.modelOverride,
-        after: n.modelOverride,
-        message: `Sub-agent '${slug}' model override changed.`,
-      });
-    }
-  }
-  for (const [slug, p] of prevBySlug) {
-    if (!nextBySlug.has(slug)) {
-      out.push({
-        kind: DriftKind.SUBAGENT_REMOVED,
-        severity: 'warning',
-        path: `$.subAgents[${slug}]`,
-        before: p,
-        message: `Sub-agent '${slug}' removed; existing delegations may fail until the session is restarted.`,
-      });
-    }
-  }
-}
-
-function diffSkills(
-  prev: readonly CompiledManifestSkillRef[],
-  next: readonly CompiledManifestSkillRef[],
-  out: EnvironmentDrift[],
-): void {
-  const prevBySlug = new Map(prev.map((s) => [s.slug, s]));
-  const nextBySlug = new Map(next.map((s) => [s.slug, s]));
-  for (const [slug, n] of nextBySlug) {
-    const p = prevBySlug.get(slug);
-    if (!p) {
-      out.push({
-        kind: DriftKind.SKILL_ADDED,
-        severity: 'info',
-        path: `$.skills[${slug}]`,
-        after: n,
-        message: `Skill '${slug}' added.`,
-      });
-      continue;
-    }
-    if (p.version !== n.version) {
-      out.push({
-        kind: DriftKind.SKILL_VERSION_CHANGED,
-        severity: 'info',
-        path: `$.skills[${slug}].version`,
-        before: p.version,
-        after: n.version,
-        message: `Skill '${slug}' version moved ${p.version ?? '*'} → ${n.version ?? '*'}.`,
-      });
-    }
-  }
-  for (const [slug, p] of prevBySlug) {
-    if (!nextBySlug.has(slug)) {
-      out.push({
-        kind: DriftKind.SKILL_REMOVED,
-        severity: 'warning',
-        path: `$.skills[${slug}]`,
-        before: p,
-        message: `Skill '${slug}' removed.`,
-      });
-    }
-  }
-}
-
-function toolSelectionKey(entry: ToolSelectionEntry): string {
-  return entry.kind === 'tool'
-    ? `tool:${entry.providerKind}:${entry.resourceId}:${entry.toolName}`
-    : `provider:${entry.providerKind}:${entry.resourceId}`;
-}
-
-function diffToolSelection(
-  prev: readonly ToolSelectionEntry[],
-  next: readonly ToolSelectionEntry[],
-  out: EnvironmentDrift[],
-): void {
-  const prevByKey = new Map(prev.map((e) => [toolSelectionKey(e), e]));
-  const nextByKey = new Map(next.map((e) => [toolSelectionKey(e), e]));
-  for (const [key, n] of nextByKey) {
-    if (!prevByKey.has(key)) {
-      out.push({
-        kind: DriftKind.TOOL_SELECTION_ADDED,
-        severity: 'info',
-        path: `$.toolSelection[${key}]`,
-        after: n,
-        message: `Tool selection entry '${key}' added.`,
-      });
-    }
-  }
-  for (const [key, p] of prevByKey) {
-    if (!nextByKey.has(key)) {
-      out.push({
-        kind: DriftKind.TOOL_SELECTION_REMOVED,
-        severity: 'warning',
-        path: `$.toolSelection[${key}]`,
-        before: p,
-        message: `Tool selection entry '${key}' removed.`,
-      });
-    }
-  }
-}
-
-function diffCredentials(
-  prev: readonly CompiledManifestCredential[],
-  next: readonly CompiledManifestCredential[],
-  out: EnvironmentDrift[],
-): void {
-  const prevByName = new Map(prev.map((c) => [c.name, c]));
-  const nextByName = new Map(next.map((c) => [c.name, c]));
-  for (const [name, n] of nextByName) {
-    const p = prevByName.get(name);
-    if (!p) {
-      out.push({
-        kind: DriftKind.CREDENTIAL_ADDED,
-        severity: 'info',
-        path: `$.credentials[${name}]`,
-        after: n,
-        message: `Credential '${name}' added.`,
-      });
-      continue;
-    }
-    if (p.kind !== n.kind) {
-      out.push({
-        kind: DriftKind.CREDENTIAL_KIND_CHANGED,
-        severity: 'warning',
-        path: `$.credentials[${name}].kind`,
-        before: p.kind,
-        after: n.kind,
-        message: `Credential '${name}' kind changed ${p.kind} → ${n.kind}; the resolver will re-route it on resume.`,
-      });
-    }
-  }
-  for (const [name, p] of prevByName) {
-    if (!nextByName.has(name)) {
-      out.push({
-        kind: DriftKind.CREDENTIAL_REMOVED,
-        // Resume is non-blocking even for a previously-required
-        // credential — the restore path degrades to a still-usable
-        // provider. `warning` simply flags it for the operator.
-        severity: 'warning',
-        path: `$.credentials[${name}]`,
-        before: p,
-        message: `Credential '${name}' removed${p.required ? ' (was required; the session resumes with the remaining credentials)' : ''}.`,
-      });
-    }
-  }
-}
-
-function diffPermissions(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-  out: EnvironmentDrift[],
-): void {
-  const prevAllow = new Set(prev.permissions.tools.allow);
-  const nextAllow = new Set(next.permissions.tools.allow);
-  const prevDeny = new Set(prev.permissions.tools.deny);
-  const nextDeny = new Set(next.permissions.tools.deny);
-  // A tool is "tightened" if it was previously allowed and is now
-  // explicitly denied OR removed from the allow-list.
-  for (const tool of prevAllow) {
-    if (!nextAllow.has(tool) || nextDeny.has(tool)) {
-      out.push({
-        kind: DriftKind.PERMISSION_TIGHTENED,
-        severity: 'warning',
-        path: `$.permissions.tools.${tool}`,
-        before: 'allow',
-        after: nextDeny.has(tool) ? 'deny' : 'unset',
-        message: `Tool '${tool}' is no longer allowed.`,
-      });
-    }
-  }
-  for (const tool of nextAllow) {
-    if (!prevAllow.has(tool) || prevDeny.has(tool)) {
-      out.push({
-        kind: DriftKind.PERMISSION_RELAXED,
-        severity: 'info',
-        path: `$.permissions.tools.${tool}`,
-        before: prevDeny.has(tool) ? 'deny' : 'unset',
-        after: 'allow',
-        message: `Tool '${tool}' is now allowed.`,
-      });
-    }
-  }
-}
-
-function diffPersistence(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-  out: EnvironmentDrift[],
-): void {
-  const prevPaths = new Set(prev.persistence.paths);
-  const nextPaths = new Set(next.persistence.paths);
-  for (const path of nextPaths) {
-    if (!prevPaths.has(path)) {
-      out.push({
-        kind: DriftKind.PERSISTENCE_PATH_ADDED,
-        severity: 'info',
-        path: `$.persistence.paths`,
-        after: path,
-        message: `Persistence path '${path}' added; future pauses will snapshot it.`,
-      });
-    }
-  }
-  for (const path of prevPaths) {
-    if (!nextPaths.has(path)) {
-      out.push({
-        kind: DriftKind.PERSISTENCE_PATH_REMOVED,
-        severity: 'info',
-        path: `$.persistence.paths`,
-        before: path,
-        message: `Persistence path '${path}' removed; future pauses will not snapshot it.`,
-      });
-    }
-  }
-}
-
-function diffOutputSurface(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-  out: EnvironmentDrift[],
-): void {
-  if (
-    prev.outputSurface.kind !== next.outputSurface.kind ||
-    prev.outputSurface.port !== next.outputSurface.port ||
-    prev.outputSurface.healthPath !== next.outputSurface.healthPath ||
-    prev.outputSurface.mode !== next.outputSurface.mode
-  ) {
-    out.push({
-      kind: DriftKind.OUTPUT_SURFACE_CHANGED,
-      severity: 'info',
-      path: '$.outputSurface',
-      before: prev.outputSurface,
-      after: next.outputSurface,
-      message: 'Output surface configuration changed.',
-    });
-  }
-}
-
-function diffEnv(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-  out: EnvironmentDrift[],
-): void {
-  const prevByName = new Map(prev.env.map((e) => [e.name, e.value]));
-  const nextByName = new Map(next.env.map((e) => [e.name, e.value]));
-  for (const [name, value] of nextByName) {
-    const prevValue = prevByName.get(name);
-    if (prevValue === undefined) {
-      out.push({
-        kind: DriftKind.ENV_VAR_ADDED,
-        severity: 'info',
-        path: `$.env[${name}]`,
-        after: value,
-        message: `Env var '${name}' added.`,
-      });
-    } else if (prevValue !== value) {
-      out.push({
-        kind: DriftKind.ENV_VAR_VALUE_CHANGED,
-        severity: 'info',
-        path: `$.env[${name}]`,
-        before: prevValue,
-        after: value,
-        message: `Env var '${name}' value changed.`,
-      });
-    }
-  }
-  for (const name of prevByName.keys()) {
-    if (!nextByName.has(name)) {
-      out.push({
-        kind: DriftKind.ENV_VAR_REMOVED,
-        severity: 'warning',
-        path: `$.env[${name}]`,
-        before: prevByName.get(name),
-        message: `Env var '${name}' removed.`,
-      });
-    }
-  }
-}
-
-function diffMounts(
-  prev: ResolvedEnvironment,
-  next: ResolvedEnvironment,
-  out: EnvironmentDrift[],
-): void {
-  const prevSlots = new Map(prev.mountPlan.entries.map((e) => [e.slot, e]));
-  const nextSlots = new Map(next.mountPlan.entries.map((e) => [e.slot, e]));
-  for (const [slot, entry] of nextSlots) {
-    const prevEntry = prevSlots.get(slot);
-    if (!prevEntry) {
-      out.push({
-        kind: DriftKind.MOUNT_ADDED,
-        severity: 'info',
-        path: `$.mounts[${slot}]`,
-        after: { mountKey: entry.mountKey },
-        message: `Mount slot '${slot}' added.`,
-      });
-      continue;
-    }
-    if (prevEntry.mode !== entry.mode) {
-      out.push({
-        kind: DriftKind.MOUNT_MODE_CHANGED,
-        severity: 'warning',
-        path: `$.mounts[${slot}].mode`,
-        before: prevEntry.mode,
-        after: entry.mode,
-        message: `Mount slot '${slot}' mode changed ${prevEntry.mode} → ${entry.mode}.`,
-      });
-    }
-  }
-  for (const slot of prevSlots.keys()) {
-    if (!nextSlots.has(slot)) {
-      out.push({
-        kind: DriftKind.MOUNT_REMOVED,
-        severity: 'warning',
-        path: `$.mounts[${slot}]`,
-        before: { slot },
-        message: `Mount slot '${slot}' removed.`,
-      });
-    }
-  }
-}