@xemahq/agent-session-runtime 0.5.0 → 0.6.1

package/src/lib/{composition-workspace-manifest.ts → agent-workspace-manifest.ts}

@@ -62,22 +62,22 @@ export type { CompiledWorkspaceManifest };
  * composition ref, or a `compileManifest` failure. Fail-fast: a session /
  * run cannot bootstrap a `/workspace/` tree without a valid mount layout.
  */
-export class CompositionMountLayoutError extends Error {
+export class AgentMountLayoutError extends Error {
   constructor(agentRef: string, detail: string) {
     super(
       `Cannot derive a workspace mount layout from Agent ` +
         `"${agentRef}": ${detail}`,
     );
-    this.name = 'CompositionMountLayoutError';
+    this.name = 'AgentMountLayoutError';
   }
 }
 
 /**
  * The agent run-config the seeder projects from the source manifest's
- * `spec.agent` block. Mirrors `CompositionAgentRunConfigDto` without
+ * `spec.agent` block. Mirrors `AgentRunConfigDto` without
  * importing the generated client.
  */
-export interface CompositionAgentRunConfigInput {
+export interface AgentRunConfigInput {
   /** Stage key. */
   readonly stage: string;
   /** Canonical `AgentRunRole` — drives renderer + system-overlay framing. */
@@ -96,11 +96,11 @@ export interface CompositionAgentRunConfigInput {
  * / `inputs` against the manifest DSL's authoritative schema, so the loose
  * typing here is checked downstream, not silently trusted.
  */
-export interface CompositionMountLayoutInput {
+export interface AgentMountLayoutInput {
   /** Raw `spec.mounts` block — manifest DSL mount-declaration map. */
   readonly mounts: Readonly<Record<string, unknown>>;
   /** Projected `spec.agent` run-config. */
-  readonly agentRunConfig: CompositionAgentRunConfigInput;
+  readonly agentRunConfig: AgentRunConfigInput;
   /** Raw `spec.seedFiles` array — manifest DSL seed-file entries. */
   readonly seedFiles: readonly unknown[];
   /** Raw `spec.inputs` block — manifest DSL input-declaration map. */
@@ -118,7 +118,7 @@ export interface CompositionMountLayoutInput {
  * worker drift). All optional ⇒ backward-compatible with callers that only
  * supply `slug` / `alias`.
  */
-export interface CompositionSubAgentBindingInput {
+export interface AgentSubAgentBindingInput {
   readonly slug: string;
   readonly alias?: string;
   /** Per-delegate model override — OVERRIDE on the referenced agent's model. */
@@ -141,7 +141,7 @@ export interface CompositionSubAgentBindingInput {
  * same kind/root/port the bundle-apply path reads from
  * `composition.workspace.outputSurface`.
  */
-export interface CompositionOutputSurfaceInput {
+export interface AgentOutputSurfaceInput {
   readonly kind: 'none' | 'web' | 'static' | 'app' | 'tunnel';
   readonly port?: number;
   readonly healthPath?: string;
@@ -156,19 +156,19 @@ export interface CompositionOutputSurfaceInput {
  * `WorkspaceManifest` from. The caller maps its richer resolved-composition
  * shape onto this — keeping the runtime package free of any API client.
  */
-export interface CompositionManifestSource {
+export interface AgentManifestSource {
   /** Version-pinned `slug@version` of the resolved composition. */
   readonly agentRef: string;
   /** Root node's agent slug — the manifest's primary agent. */
   readonly primaryAgentSlug: string;
   /** Manifest-declared sub-agent bindings (descendant nodes). */
-  readonly subAgentBindings: readonly CompositionSubAgentBindingInput[];
+  readonly subAgentBindings: readonly AgentSubAgentBindingInput[];
   /**
    * The composition's `workspace.mountLayout` block. `undefined` when the
    * composition declared no `workspace` block or the seeder did not project
    * a layout — a fail-fast condition.
    */
-  readonly mountLayout: CompositionMountLayoutInput | undefined;
+  readonly mountLayout: AgentMountLayoutInput | undefined;
   /**
    * The composition's `workspace.outputSurface` block. Threaded into the
    * reconstructed manifest's `spec.outputSurface` so the compiled
@@ -178,7 +178,7 @@ export interface CompositionManifestSource {
    * composition declared no surface — the DSL compile then yields the
    * `{ kind: 'none' }` default.
    */
-  readonly outputSurface?: CompositionOutputSurfaceInput;
+  readonly outputSurface?: AgentOutputSurfaceInput;
   /**
    * The composition's `workspace.credentials` block. Threaded into the
    * reconstructed manifest's `spec.credentials` so the compiled manifest's
@@ -218,7 +218,7 @@ export interface CompositionManifestSource {
  * it, and no first-party manifest does today. Optional so a caller with
  * no run-scoped id at all can omit it.
  */
-export interface CompositionManifestImplicitInputs {
+export interface AgentManifestImplicitInputs {
   readonly orgId: string;
   readonly projectId: string;
   readonly sessionId?: string;
@@ -242,17 +242,17 @@ type ManifestInputValue =
  * shape.
  *
  * `bindInputs` is the resolved manifest input bag (explicit inputs ∪
- * implicit inputs), built by {@link buildCompositionManifestBindInputs}.
+ * implicit inputs), built by {@link buildAgentManifestBindInputs}.
  * The compile fails fast on an unresolved required input or an enum
  * violation — exactly the legacy behaviour.
  */
-export function compileCompositionWorkspaceManifest(
-  source: CompositionManifestSource,
+export function compileAgentWorkspaceManifest(
+  source: AgentManifestSource,
   bindInputs: Readonly<Record<string, unknown>>,
 ): CompiledWorkspaceManifest {
   const mountLayout = source.mountLayout;
   if (!mountLayout) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       source.agentRef,
       'the composition declares no `workspace.mountLayout` block — its ' +
         'source workspace manifest was not projected by the llm-registry-api ' +
@@ -333,7 +333,7 @@ export function compileCompositionWorkspaceManifest(
     metadata: {
       slug,
       version,
-      // Compositions resolved for a session bootstrap are, by definition,
+      // 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],
@@ -343,7 +343,7 @@ export function compileCompositionWorkspaceManifest(
 
   const result = compileManifest(envelope, bindInputs);
   if (!result.ok) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       source.agentRef,
       `reconstructed manifest failed to compile: ${result.errors
         .map((e) => `${e.path}: ${e.message}`)
@@ -355,7 +355,7 @@ export function compileCompositionWorkspaceManifest(
 
 /**
  * Project the composition's `workspace.outputSurface` block (carried on
- * the runtime-agnostic `CompositionManifestSource`) into the manifest DSL's
+ * the runtime-agnostic `AgentManifestSource`) into the manifest DSL's
  * `ManifestOutputSurface` shape so the reconstructed envelope's
  * `spec.outputSurface` carries the same kind/root/port as the source. The
  * `kind` value strings match the DSL enum 1:1 (`none` / `web` / `static` /
@@ -366,7 +366,7 @@ export function compileCompositionWorkspaceManifest(
  * `{ kind: 'none', autoOpen: false, mode: 'single' }`.
  */
 function projectOutputSurface(
-  surface: CompositionOutputSurfaceInput | undefined,
+  surface: AgentOutputSurfaceInput | undefined,
 ): ManifestOutputSurface | undefined {
   if (!surface) return undefined;
   return {
@@ -386,7 +386,7 @@ function projectOutputSurface(
 
 /**
  * Project the composition's `workspace.credentials` block (carried on the
- * runtime-agnostic `CompositionManifestSource` as the kernel
+ * runtime-agnostic `AgentManifestSource` as the kernel
  * `CompiledManifestCredential[]`) into the manifest DSL's authored
  * `ManifestCredential[]` shape so the reconstructed envelope's
  * `spec.credentials` carries the same entries as the source.
@@ -415,7 +415,7 @@ function projectCredentials(
 
 /**
  * Project the composition's `workspace.permissions` block (carried on the
- * runtime-agnostic `CompositionManifestSource` as the kernel
+ * runtime-agnostic `AgentManifestSource` as the kernel
  * `CompiledManifestPermissions`) into the manifest DSL's authored
  * `ManifestPermissions` shape so the reconstructed envelope's
  * `spec.permissions` carries the same tool allow/deny lists as the source.
@@ -457,10 +457,10 @@ function projectPermissions(
  *
  * Returns `{}` when the composition declared no inputs.
  */
-export function buildCompositionManifestBindInputs(
-  source: CompositionManifestSource,
+export function buildAgentManifestBindInputs(
+  source: AgentManifestSource,
   explicitInputs: Record<string, unknown> | null,
-  implicitInputs: CompositionManifestImplicitInputs,
+  implicitInputs: AgentManifestImplicitInputs,
 ): Readonly<Record<string, unknown>> {
   const declared = new Set(Object.keys(source.mountLayout?.inputs ?? {}));
   if (declared.size === 0) {
@@ -471,7 +471,7 @@ export function buildCompositionManifestBindInputs(
     explicitInputs !== null &&
     (typeof explicitInputs !== 'object' || Array.isArray(explicitInputs))
   ) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       source.agentRef,
       'explicit manifest inputs must be an object when provided',
     );
@@ -479,7 +479,7 @@ export function buildCompositionManifestBindInputs(
   const explicit = explicitInputs ?? {};
   for (const [key, value] of Object.entries(explicit)) {
     if (!declared.has(key)) {
-      throw new CompositionMountLayoutError(
+      throw new AgentMountLayoutError(
         source.agentRef,
         `manifest inputs contain undeclared key "${key}"`,
       );
@@ -512,7 +512,7 @@ export function buildCompositionManifestBindInputs(
 function splitAgentRef(ref: string): [slug: string, version: string] {
   const at = ref.lastIndexOf('@');
   if (at <= 0 || at === ref.length - 1) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       ref,
       'expected a version-pinned `slug@version` composition ref — the ' +
         'session resolver always pins the resolved version',
@@ -539,7 +539,7 @@ function assertManifestInputValue(
     typeof value !== 'boolean' &&
     !Array.isArray(value)
   ) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       agentRef,
       `manifest input "${key}" must be a primitive ` +
         `(string, number, boolean, string[]) — got ${typeof value}`,
@@ -549,7 +549,7 @@ function assertManifestInputValue(
     Array.isArray(value) &&
     !value.every((entry) => typeof entry === 'string')
   ) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       agentRef,
       `manifest input "${key}" is an array — every element must be a string`,
     );