@dexto/agent-config

@dexto/agent-config

Schema + resolver utilities for turning an agent YAML config into concrete DI surfaces using images.

This package is product-layer glue: core (@dexto/core) stays DI-friendly, and hosts (CLI/server/apps) use @dexto/agent-config to:

• validate agent config (AgentConfigSchema)
• load an image module (loadImage())
• merge image defaults into raw config (applyImageDefaults())
• resolve image factories into concrete stores, workspace handles, skills, tools, hooks, and logger instances (resolveServicesFromConfig())
• convert the result into DextoAgentOptions (toDextoAgentOptions())

Quick example (apps)

import { DextoAgent } from '@dexto/core';
import { loadAgentConfig } from '@dexto/agent-management';
import {
  AgentConfigSchema,
  applyImageDefaults,
  loadImage,
  resolveServicesFromConfig,
  setImageImporter,
  toDextoAgentOptions,
} from '@dexto/agent-config';

// Under pnpm (strict dependency boundaries), configure image importing at the host entrypoint.
setImageImporter((specifier) => import(specifier));

const raw = await loadAgentConfig('./agents/my-agent.yml');
const image = await loadImage(raw.image ?? '@dexto/image-local');
const merged = applyImageDefaults(raw, image.defaults);

const config = AgentConfigSchema.parse(merged);
const services = await resolveServicesFromConfig(config, image);

const agent = new DextoAgent(toDextoAgentOptions({ config, services }));
await agent.start();

Typed host contexts

Hosted runtimes can thread a typed host context through image resolution without baking any platform-specific fields into upstream packages.

import type { DextoHostContext, DextoImage } from '@dexto/agent-config';

type CloudHostContext = DextoHostContext<
  {
    dextoCloudflare: {
      runtimeContext: {
        sessionId: string;
      };
    };
  },
  {
    workspace: boolean;
  }
>;

declare const image: DextoImage<CloudHostContext>;
declare const hostContext: CloudHostContext;

const services = await resolveServicesFromConfig(config, image, hostContext);
const options = toDextoAgentOptions({ config, services, image, hostContext });

Images (no registries)

Images are typed modules (DextoImage) that export plain factory surfaces. Tool/hook/compaction resolution still uses property access by config type (e.g., image.tools[entry.type]). Storage is resolved by the image as one createStores(config.storage, ...) call so images can compose or directly implement DextoStores without exposing lower-level backend construction details. There are no global registries or side effects.

Images may also provide:

• workspace.create(...): returns a WorkspaceHandleProvider. Local images usually return local filesystem handles; hosted images can return handles backed by their own workspace runtime.
• skills.create(...): returns SkillSource instances consumed by SkillManager. Skills stay out of prompt config; prompts remain prompt-only.