@xemahq/agent-session-runtime 0.6.5 → 0.6.7

package/src/lib/agent-workspace-manifest.ts

@@ -1,7 +1,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── Agent → CompiledWorkspaceManifest reconstruction ──
 //
-// Phase 10 (`workspace-manifests-api` retirement). The composer turns a
+// The composer turns a
 // `CompiledWorkspaceManifest` into a `WorkspaceMountPlan`; before this
 // module the only way to obtain that compiled manifest was to fetch the
 // `WorkspaceManifest` row from `workspace-manifests-api` and run
@@ -47,7 +47,7 @@ import {
   type ManifestSeedFile,
   type ManifestSubAgent,
   type ManifestWorkingFile,
-  type WorkspaceManifest as DslWorkspaceManifest,
+  type AgentWorkspaceSpec as DslWorkspaceManifest,
   type WorkspaceManifestSpec,
 } from '@xemahq/dsl/workspace-manifest';
 
@@ -359,10 +359,19 @@ export function compileAgentWorkspaceManifest(
     metadata: {
       slug,
       version,
-      // Agents resolved for a session bootstrap are, by definition,
-      // agent-session compatible — the runtime EnvironmentResolver still
-      // re-asserts `surfaceCompat` against the AGENT_SESSION surface.
-      surfaceCompat: [ManifestSurface.AGENT_SESSION],
+      // A manifest RECONSTRUCTED from a bare `agentRef` carries no inherent
+      // surface restriction — the SAME agent (e.g. `demo-runner`,
+      // `requirements-coordinator`) is legitimately driven on BOTH the
+      // agent-session surface (interactive bootstrap) AND the workflow surface
+      // (pipeline `xema/agent@v1` jobs). Defaulting to AGENT_SESSION only made
+      // every workflow agent run fail `assertSurfaceCompat` with
+      // "surfaceCompat=[agent-session] but was resolved on 'workflow'". Mirror
+      // the DSL compiler's permissive `DEFAULT_SURFACE_COMPAT` ([workflow,
+      // agent-session]); the runtime EnvironmentResolver still re-asserts the
+      // ACTUAL surface, so widening the reconstructed set cannot let an agent
+      // run somewhere its real manifest forbids — an authored manifest that
+      // explicitly narrows `surfaceCompat` is parsed via the DSL path, not here.
+      surfaceCompat: [ManifestSurface.WORKFLOW, ManifestSurface.AGENT_SESSION],
     },
     spec,
   };

package/src/lib/composer.ts

@@ -328,8 +328,8 @@ export class DefaultWorkspaceImageComposer implements WorkspaceImageComposer {
     // `/<skillKey>` in a session loads and applies that skill natively.
     //
     // Kernel-shipped System skills are PREPENDED to whatever skills the
-    // caller already named in `agentContext.skills` (see
-    // `.claude/rules/skills-and-composition.md` — `SkillSpace.System`
+    // caller already named in `agentContext.skills` (per the skill
+    // composition rules — `SkillSpace.System`
     // skills are auto-injected into every agent's mounted bundle).
     // `dedupe` collapses any overlap so a caller that re-mentions a
     // System skill in `agentContext.skills` does not double-mount it.

package/src/lib/drift-detector.ts

@@ -57,8 +57,8 @@ export enum DriftKind {
 
 /**
  * Advisory drift severity — `info` (benign) or `warning` (worth a look).
- * There is deliberately no `critical`: resume is non-blocking by design
- * (plan Epic D §D4), so severity only drives how the operator's drift
+ * 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';

package/src/lib/environment-resolver.ts

@@ -124,7 +124,7 @@ export interface EnvironmentResolverRequest {
    */
   readonly systemSkillSlugs?: readonly string[];
   /**
-   * Optional MCP stanza resolver (Phase D1). Translates the manifest's
+   * Optional MCP stanza resolver. Translates the manifest's
    * `toolSelection` into a `mcpServers` map suitable for direct write
    * into `opencode.jsonc:mcp`. When absent, the resolved environment
    * carries no MCP stanzas — appropriate for workflow surfaces today
@@ -205,7 +205,7 @@ export interface ResolvedEnvironment {
   readonly mountPlan: WorkspaceMountPlan;
   readonly env: readonly { readonly name: string; readonly value: string }[];
   /**
-   * Phase D1: resolved `mcpServers` map ready to drop into
+   * Resolved `mcpServers` map ready to drop into
    * `opencode.jsonc:mcp`. Empty `{}` when the manifest declares no
    * toolSelection or when the request omits an `mcpResolver`. Keeps
    * the snapshot self-contained so downstream callers (workflow
@@ -279,7 +279,7 @@ export class DefaultEnvironmentResolver implements EnvironmentResolver {
       req.briefcase?.mcpTools,
     );
 
-    // Phase H.2: capability federation. When an `mcpResolver` is wired
+    // Capability federation. When an `mcpResolver` is wired
     // (session-boot, workflow-runtime-worker) the resolver ALWAYS runs —
     // the returned stanza is the fixed three meta-tool surface
     // (`xema-capabilities-{list,describe,invoke}`), regardless of

package/src/lib/lifecycle-state.ts

@@ -1,139 +1,30 @@
 // ═══════════════════════════════════════════════════════════════════════════
-// ── Agent-session lifecycle state machine ──
+// ── Agent-session lifecycle state machine — re-export of the kernel SSOT ──
 //
-// Pure enums + transitions. Mirrors the `SessionStatus` enum persisted by
-// the agent-session-api service; the worker imports from here (the
-// service's persistence-layer enums are not importable across the apps
-// boundary).
+// This file is a thin re-export surface. The closed `SessionLifecycleState` /
+// `SessionOwnerKind` value sets, the transition FSM (`canTransition`), and the
+// `isTerminal` / `isPausable` / `isResumable` predicates are the canonical
+// Layer-0 contract owned by `@xemahq/kernel-contracts/agent-session`. The former
+// hand-maintained copy that lived here was collapsed into that single source of
+// truth; this module is retained ONLY so the package's public surface
+// (re-exported from `src/index.ts`) is unchanged.
 //
-// Single source of truth for "can this session be paused right now?".
-// Both interactive-session callers AND the workflow-runtime-worker
-// dispatch activity consult `canTransition()` before issuing the HTTP
-// call so misuse fails fast at compile time rather than as a 409 from
-// the service.
+// Prisma cannot import a TS value, so the agent-session-api schema re-declares
+// the same members and CI guards parity
+// (`tooling/boundaries/check-session-enum-parity.mjs`).
 // ═══════════════════════════════════════════════════════════════════════════
 
-/**
- * Lifecycle state of an agent-session row. Mirrors the persisted enum on
- * the agent-session-api service. Closed set.
- */
-export const SessionLifecycleState = {
-  creating: 'creating',
-  provisioning: 'provisioning',
-  active: 'active',
-  paused: 'paused',
-  recovering: 'recovering',
-  completing: 'completing',
-  completed: 'completed',
-  failed: 'failed',
-  archived: 'archived',
-} as const;
-
-export type SessionLifecycleStateValue =
-  (typeof SessionLifecycleState)[keyof typeof SessionLifecycleState];
-
-/**
- * Who created the session row. Mirrors the persisted `SessionOwnerKind`.
- *
- *   - `interactive_session`  — user-facing chat sessions
- *   - `pipeline_run`         — workflow-runtime-worker redraft loop spines
- *   - `chat_thread`          — reserved (no dispatcher today)
- *
- * The CI enum-parity check verifies this stays in lockstep with the
- * persisted enum.
- */
-export const SessionOwnerKind = {
-  interactive_session: 'interactive_session',
-  pipeline_run: 'pipeline_run',
-  chat_thread: 'chat_thread',
-} as const;
-
-export type SessionOwnerKindValue =
-  (typeof SessionOwnerKind)[keyof typeof SessionOwnerKind];
-
-/**
- * Per-state transition matrix. `canTransition(from, to)` returns true
- * iff the transition is valid.
- *
- * Notable transitions:
- *   - `paused → recovering` (resume claim)
- *   - `recovering → active` (resume success)
- *   - `recovering → paused` (resume rollback)
- *   - `active → completing → completed` (terminal success)
- *   - any-non-terminal → `failed` (terminal failure)
- *   - `paused | completed | failed → archived` (cleanup sweep)
- */
-const TRANSITIONS: Readonly<
-  Record<SessionLifecycleStateValue, ReadonlySet<SessionLifecycleStateValue>>
-> = {
-  creating: new Set([
-    SessionLifecycleState.provisioning,
-    SessionLifecycleState.failed,
-  ]),
-  provisioning: new Set([
-    SessionLifecycleState.active,
-    SessionLifecycleState.failed,
-  ]),
-  active: new Set([
-    SessionLifecycleState.paused,
-    SessionLifecycleState.completing,
-    SessionLifecycleState.failed,
-  ]),
-  paused: new Set([
-    SessionLifecycleState.recovering,
-    SessionLifecycleState.archived,
-    SessionLifecycleState.failed,
-  ]),
-  recovering: new Set([
-    SessionLifecycleState.active,
-    SessionLifecycleState.paused,
-    SessionLifecycleState.failed,
-  ]),
-  completing: new Set([
-    SessionLifecycleState.completed,
-    SessionLifecycleState.failed,
-  ]),
-  completed: new Set([SessionLifecycleState.archived]),
-  failed: new Set([SessionLifecycleState.archived]),
-  archived: new Set(),
-};
-
-export function canTransition(
-  from: SessionLifecycleStateValue,
-  to: SessionLifecycleStateValue,
-): boolean {
-  return TRANSITIONS[from].has(to);
-}
-
-/**
- * Terminal states — no further transitions possible (except the
- * `completed | failed → archived` cleanup sweep). Callers use this to
- * short-circuit "is this session done?" checks.
- */
-export function isTerminal(state: SessionLifecycleStateValue): boolean {
-  return (
-    state === SessionLifecycleState.completed ||
-    state === SessionLifecycleState.failed ||
-    state === SessionLifecycleState.archived
-  );
-}
-
-/**
- * Pausable states — the session has a live worker that can be told to
- * snapshot. `provisioning` is intentionally excluded: the worker isn't
- * ready yet, so a pause request would 409. Callers receiving such a
- * 409 should retry with backoff once `active` is reached.
- */
-export function isPausable(state: SessionLifecycleStateValue): boolean {
-  return state === SessionLifecycleState.active;
-}
-
-/**
- * Resumable states. `paused` is the canonical case. `failed` rows are
- * NOT resumable from here — they require explicit operator action
- * (the resume API would 409). `recovering` is a transient state owned
- * by an in-flight resume; another caller observing it should back off.
- */
-export function isResumable(state: SessionLifecycleStateValue): boolean {
-  return state === SessionLifecycleState.paused;
-}
+export {
+  SessionLifecycleState,
+  SessionOwnerKind,
+  canTransition,
+  isTerminal,
+  isPausable,
+  isResumable,
+  SessionLifecycleStateSchema,
+  SessionOwnerKindSchema,
+} from '@xemahq/kernel-contracts/agent-session';
+export type {
+  SessionLifecycleStateValue,
+  SessionOwnerKindValue,
+} from '@xemahq/kernel-contracts/agent-session';

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