@skaile/workspaces 0.8.5

package/dist/core/src/workspace-config.d.ts

@@ -0,0 +1,744 @@
+/**
+ * Unified workspace configuration — `skaile.yaml` / `<name>.skaile.yaml`
+ *
+ * Single file combining AI resources, data connectors, agent behavior,
+ * runtime defaults, and workspace layout.
+ *
+ * ── File naming ──────────────────────────────────────────────────────────
+ *
+ *   skaile.yaml              → canonical default workspace config
+ *   staging.skaile.yaml      → alternative workspace config
+ *   *.skaile.yaml            → glob pattern for named configs
+ *
+ * ── Stacking ─────────────────────────────────────────────────────────────
+ *
+ * Files stack across scope levels (same name must match):
+ *   ~/.skaile/skaile.yaml            priority 10 (user)
+ *   /app/skaile.yaml                 priority 20 (app)
+ *   /project/skaile.yaml             priority 30 (project)
+ *
+ * ── Relationship to other files ──────────────────────────────────────────
+ *
+ * .skaile/settings.json   User-specific overrides (API keys, personal
+ *                          model preferences). Gitignored. Overrides
+ *                          workspace config defaults at runtime.
+ *
+ * workspace.yaml           Scaffold template. Generates skaile.yaml
+ *                          at `skaile init` time. Never read at runtime.
+ *
+ * agent.yaml               Agent definition (identity). Referenced from
+ *                          skaile.yaml via `agent.definition`.
+ */
+/**
+ * Named agent configuration profile. The "default" profile is the active one.
+ * Personal overrides (apiKeys, model preference) live in .skaile/settings.json.
+ * @docLink packages/core/workspace-config#agent-config-profile
+ */
+export interface AgentConfigProfile {
+    /** Bridge driver to use: "claude-sdk", "codex", or "omp". */
+    driver?: string;
+    /** Default LLM provider: "anthropic", "openai", "google", etc. */
+    provider?: string;
+    /** Default model identifier. */
+    model?: string;
+    /** Thinking mode for Claude models. */
+    thinking?: "adaptive" | "enabled" | "disabled";
+    /** Reasoning effort level. */
+    effort?: "low" | "medium" | "high" | string;
+    /** Override framework install paths (rarely needed). */
+    skills_dir?: string;
+    agents_dir?: string;
+    prompts_dir?: string;
+}
+/**
+ * A startup directive — run on workspace launch.
+ *
+ * String form:  "agent:research-assistant"  — start the named agent
+ * Object form:  { "system-prompt-override": "..." }  — replace system prompt
+ *               { "system-prompt-append": "..." }     — append to system prompt
+ * @docLink packages/core/workspace-config#startup-directive
+ */
+export type StartupDirective = string | Record<string, string>;
+/**
+ * An AI resource source with its own dependency list.
+ * All declared dependencies are installed from this source's catalog.
+ * @docLink packages/core/workspace-config#ai-resource-entry
+ */
+export interface AiResourceEntry {
+    /** Source name (used as cache key and in CLI output). */
+    name: string;
+    /** Path to local directory or GitHub repo URL. */
+    path: string;
+    /** Git branch (default: main). */
+    branch?: string;
+    /** Skill/agent/package/flow refs to install from this source. Syntax: "kind:name". */
+    dependencies?: string[];
+    /** Auto-deploy to framework dirs on install. */
+    auto_deploy?: boolean;
+}
+/**
+ * Internal-only data shape used by the legacy asset install pipeline
+ * (`repo-manager`, `lock`, `runtime-assets`). Carries the resolved URL or
+ * path for an `ai_resources[]` entry. Not surfaced via the workspace config
+ * schema — new sources are registered through `@skaile/library`.
+ *
+ * @docLink packages/core/workspace-config#repository-declaration
+ */
+export interface RepositoryDeclaration {
+    /** GitHub or git URL (for remote repos). */
+    url?: string;
+    /** Local filesystem path (for local repos). */
+    path?: string;
+    /** Git branch (default: main). */
+    branch?: string;
+    /** Upstream URL for fork workflows. */
+    upstream?: string;
+}
+/**
+ * A filesystem mount — projected storage backend.
+ * @docLink packages/core/workspace-config#mount-declaration
+ */
+export interface MountDeclaration {
+    /** Unique identifier. Used as mount dir name. */
+    id: string;
+    /** Mount driver: "local", "git", "s3", "webdav", "sharepoint". */
+    driver: string;
+    /** What to mount: URL, bucket path, host filesystem path. */
+    source: string;
+    /** Workspace-relative mount point (default: .mounts/<id>). */
+    target?: string;
+    /** Access level enforced by MountManager. */
+    access?: "read-only" | "read-write";
+    /** Credential reference: "env:VAR_NAME" or inline value. */
+    auth?: string;
+    /**
+     * Whether to watch this mount for filesystem changes.
+     * true = always watch, false = never watch, undefined = auto (watch if read-write).
+     */
+    watch?: boolean;
+    /**
+     * **Expert-only.** When `true`, the mount manager wires the resolved
+     * credential into the workspace so the agent's interactive `git`/`curl`
+     * tools can authenticate directly against the mount's host. Defaults to
+     * `false` — agents have no credential exposure and rely on driver-managed
+     * pulls/pushes. See `_devlog/specs/2026-05-05-git-credential-tiers.md`.
+     */
+    exposeAccessToken?: boolean;
+    /**
+     * Optional override for the access token TTL (seconds). When omitted, the
+     * provider's natural TTL is used. Values above the provider's documented
+     * maximum are silently capped.
+     */
+    accessTokenTTL?: number;
+    /** Driver-specific configuration (branch, region, etc.). */
+    options?: Record<string, unknown>;
+}
+/**
+ * A data connector — tool-accessed backend the agent interacts with.
+ * @docLink packages/core/workspace-config#connector-declaration
+ */
+export interface ConnectorDeclaration {
+    /** Unique identifier. Used as tool namespace. */
+    id: string;
+    /** Connector adapter: "postgres", "redis", "sqlite", "memory", "xstate", "xstate-store", "yjs". */
+    driver: string;
+    /**
+     * Access level enforced by ConnectorManager.
+     * Optional in config — ConnectorManager defaults to "read-only" when absent.
+     */
+    access?: "read-only" | "read-write";
+    /** Credential reference: "env:VAR_NAME" or inline value. */
+    auth?: string;
+    /** Adapter-specific configuration (dsn, host, etc.). */
+    options?: Record<string, unknown>;
+    /** Semver range for future catalog versioning, e.g. "^1.0.0". */
+    version?: string;
+    /**
+     * Run a health check (ping) when the connector is first connected.
+     * Default: false. Set to true to surface connection errors early.
+     */
+    health_check?: boolean;
+    /**
+     * Inject this connector's skill description into the agent's system prompt.
+     * Default: false.
+     */
+    expose_as_skill?: boolean;
+    /** Tags for catalog browsing and skill routing. */
+    tags?: string[];
+}
+/**
+ * Reference to a Nix-built asset recipe.
+ *
+ * The `attr` field selects an attribute path in the platform's flake
+ * (`/etc/skaile/flake/`), e.g. `mcps.excel`, `mcps.ppt`, `stacks.baseline`.
+ * Resolution happens at session start (cold) and on `reconfigure_mcps`
+ * (hot-add) via `nix path-info --offline`.
+ *
+ * @docLink packages/core/concepts#asset-recipe
+ */
+export interface AssetRecipe {
+    /** Flake attribute path, e.g. `mcps.excel`. */
+    attr: string;
+}
+/**
+ * Validates an `AssetRecipe.attr` value against nix attribute path syntax.
+ *
+ * Nix attribute paths are dot-separated segments. Each segment must start with
+ * a letter and contain only letters, digits, underscores, hyphens, and dots.
+ * Characters like `#`, spaces, and nix expression fragments are explicitly
+ * rejected — even though `spawnSync` array args prevent shell injection, nix
+ * parses the combined `flakeRef#attr` string and invalid chars trigger
+ * unintended evaluation paths.
+ *
+ * Deliberate restriction: leading digits per segment are not allowed even
+ * though some nix attrs permit them, because they are rare in practice and
+ * the restriction makes the validation straightforward to audit.
+ *
+ * @throws Error when `attr` is invalid
+ */
+export declare function validateAssetRecipeAttr(attr: string): void;
+/**
+ * A declarative external MCP server — spawned or connected at session startup
+ * and injected into the Claude SDK driver as a named `mcpServers` entry.
+ *
+ * Maps directly to the Claude Agent SDK's `McpServerConfig` union:
+ *   - `transport: "stdio"` (default) → `McpStdioServerConfig`  — subprocess spawn
+ *   - `transport: "sse"`             → `McpSSEServerConfig`     — HTTP Server-Sent Events
+ *   - `transport: "http"`            → `McpHttpServerConfig`    — HTTP streaming
+ *
+ * The `id` becomes the key in the SDK's `mcpServers` record and also the MCP
+ * tool prefix (e.g., `mcp__my-server__<tool-name>`).
+ * @docLink packages/core/workspace-config#mcp-server-declaration
+ */
+export interface McpServerDeclaration {
+    /** Unique identifier — used as the `mcpServers` record key and tool prefix. */
+    id: string;
+    /**
+     * Transport type.
+     * Default: `"stdio"` (subprocess).
+     */
+    transport?: "stdio" | "sse" | "http";
+    /** For `"stdio"`: the command to execute (e.g. `"npx"`, `"node"`, `"python"`). */
+    command?: string;
+    /** For `"stdio"`: arguments passed to the command. */
+    args?: string[];
+    /** For `"stdio"`: environment variables injected into the subprocess. */
+    env?: Record<string, string>;
+    /** For `"sse"` and `"http"`: the server URL. */
+    url?: string;
+    /** For `"sse"` and `"http"`: HTTP headers (e.g. `Authorization`). */
+    headers?: Record<string, string>;
+    /** Short description of what this server provides (used in catalog). */
+    description?: string;
+    /** Tags for catalog browsing and discovery. */
+    tags?: string[];
+    /**
+     * Optional Nix recipe binding. When present, the runner resolves the
+     * recipe's `/nix/store` out-path before subprocess spawn and substitutes
+     * `${recipe:<id>}` / `${recipe:<id>:<sub>}` / `${recipe:<id>:bin}` /
+     * `${recipe:<id>:lib}` markers in `command`, `args`, and `env` values.
+     * `<id>` matches this declaration's `id` field.
+     */
+    recipe?: AssetRecipe;
+}
+/**
+ * Platform-level context describing the environment the agent operates in.
+ * Rendered by the runner into a "## Platform" section of the system prompt.
+ */
+export interface AgentContextConfig {
+    /** Platform identifier (e.g. "skaile"). Controls the rendered header sentence. */
+    platform?: string;
+    /** Whether multiple users may interact in the same session. */
+    multi_user?: boolean;
+    /** Session persistence model. */
+    session_model?: "persistent" | "ephemeral";
+}
+export interface AgentConfig {
+    /**
+     * Agent definition reference. Resolved in order:
+     *   - Local path:        ".skaile/agent" or "./my-agent"
+     *   - Catalog reference: "agent:<name>" (resolved via asset manager catalog)
+     *   - Resource path:     "ai-assets://<domain>/agents/<name>"
+     */
+    definition?: string;
+    /**
+     * Platform-level context (platform identifier, multi-user flag, session model).
+     * Consumed by the runner to build the "## Platform" section of the system prompt.
+     */
+    context?: AgentContextConfig;
+    /** Agent runtime constraints. */
+    permissions?: AgentPermissions;
+    /** Lifecycle hooks — shell commands run at specific points. */
+    hooks?: AgentHooks;
+    /** Named subagent definitions available for delegation. */
+    subagents?: Record<string, SubagentConfig>;
+    /**
+     * Control which framework fragments are included in the rendered system prompt.
+     *   true  (default) — include built-in fragment
+     *   false           — omit this fragment
+     *   string          — path to a custom markdown file (relative to project root)
+     *
+     * Fragment IDs: "agent-mode" | "skill-discovery" | "connector-usage" | "handoff"
+     */
+    fragments?: Record<string, boolean | string>;
+    /**
+     * Additional markdown files appended at the end of every rendered agent system
+     * prompt in this workspace. Paths relative to the project root (skaile.yaml).
+     *
+     * YAML key: `prompt-extensions`
+     */
+    "prompt-extensions"?: string[];
+    /**
+     * Free-form user-authored agent prompt. Plain text or markdown — no length
+     * cap, no template substitution. Prepended immediately after the platform
+     * context section and before the environment section in the assembled
+     * system prompt (see runner's {@link assembleSystemPrompt}).
+     *
+     * Written by the platform's wake-time yaml serializer from the combined
+     * project-level + session-level prompts stored on `SkaileConfigData.agent.prompt`.
+     * Standalone CLI / forge sessions may set this directly in `skaile.yaml`.
+     *
+     * Spec: `docs/superpowers/specs/2026-05-13-platform-agent-prompt-design.md`
+     * @since 2026-05
+     */
+    prompt?: string;
+}
+export interface AgentPermissions {
+    /** Maximum agentic turns per query (default: 15). */
+    max_turns?: number;
+    /**
+     * Permission mode for Claude SDK driver.
+     * 'auto' = bypassPermissions (default for automated flows).
+     * 'interactive' = prompt for each tool use.
+     */
+    permission_mode?: "auto" | "interactive";
+    /** Glob patterns the agent may NOT write to. Stacking: union across scopes. */
+    deny_write?: string[];
+    /** Glob patterns the agent may NOT read. Stacking: union across scopes. */
+    deny_read?: string[];
+}
+export interface AgentHooks {
+    /** Run before a flow starts (after resources are connected). */
+    pre_flow?: HookEntry[];
+    /** Run after a flow completes (before resources disconnect). */
+    post_flow?: HookEntry[];
+    /** Run before each flow node executes. */
+    pre_node?: HookEntry[];
+    /** Run after each flow node completes successfully. */
+    post_node?: HookEntry[];
+}
+export interface HookEntry {
+    /** Human-readable hook name. */
+    name: string;
+    /** Shell command to execute. */
+    run: string;
+    /** Working directory relative to workspace root (default: workspace root). */
+    cwd?: string;
+    /** Timeout in seconds (default: 60). */
+    timeout?: number;
+    /** Continue flow if hook fails (default: false). */
+    continue_on_error?: boolean;
+}
+export interface SubagentConfig {
+    /** What this subagent does. */
+    description: string;
+    /** System prompt for the subagent. */
+    prompt: string;
+    /** Tools this subagent may use (default: all). */
+    tools?: string[];
+    /** Tools this subagent may NOT use. */
+    disallowed_tools?: string[];
+    /** Model override. */
+    model?: string;
+}
+export interface WorkspaceLayoutConfig {
+    /** Directories to ensure exist (created at scaffold time, verified at run time). */
+    directories?: string[];
+    /** Git configuration. */
+    git?: GitConfig;
+    /** Post-scaffold setup commands (run once after `skaile init`). */
+    setup?: SetupEntry[];
+    /** Container configuration (Docker). */
+    container?: ContainerConfig;
+}
+export interface GitConfig {
+    /** Initialize a git repo at scaffold time (default: true). */
+    init?: boolean;
+    /** .gitignore entries. Stacking: concatenate + deduplicate. */
+    ignore?: string[];
+}
+export interface SetupEntry {
+    /** Human-readable name. */
+    name: string;
+    /** Shell command to execute. */
+    run: string;
+    /** Working directory relative to workspace root. */
+    cwd?: string;
+    /** Continue if command fails (default: false). */
+    continue_on_error?: boolean;
+}
+export interface NixContainerConfig {
+    /**
+     * Nixpkgs package attribute names to include in the environment.
+     * Example: ["nodejs_22", "bun", "git", "python3"]
+     */
+    packages?: string[];
+    /**
+     * Nixpkgs registry name used as a package prefix for `nix shell`.
+     * MUST be a bare registry name like "nixpkgs" — not a channel path like
+     * "nixpkgs/nixos-24.11" (which is not valid as a flake ref prefix).
+     * Defaults to "nixpkgs".
+     */
+    channel?: string;
+    /**
+     * Path to a Nix file (shell.nix / flake.nix) relative to the project root.
+     * When set, `packages` and `channel` are ignored — the file is the source of truth.
+     */
+    flake?: string;
+    /**
+     * Predefined named stack to resolve from the system stack registry (SKAILE_NIX_STACK_REGISTRY).
+     * Overridden by `packages` if present.
+     * Takes precedence over the parent `ContainerConfig.stack` field when nix mode is active.
+     */
+    stack?: string;
+}
+export interface ContainerConfig {
+    /** Enable Docker container generation. */
+    enabled?: boolean;
+    /** Base Docker image. */
+    image?: string;
+    /** System packages to install. */
+    packages?: string[];
+    /** Agent CLIs to install globally in the container. */
+    agent_clis?: string[];
+    /** Ports to expose. */
+    ports?: string[];
+    /** Environment variables to pass through. */
+    env?: string[];
+    /** Docker volume/bind mounts. */
+    mounts?: Array<{
+        type: "bind" | "volume";
+        source: string;
+        target: string;
+    }>;
+    /** WebSocket port for IPC. */
+    ws_port?: number;
+    /**
+     * Named system stack.
+     * - Docker mode: resolved to an image tag via `dockerImageMap` (SKAILE_DOCKER_IMAGE_MAP).
+     * - Nix mode: resolved to a package list via `nixStackRegistry` (SKAILE_NIX_STACK_REGISTRY).
+     *   Overridden by `nix.stack` if both are present.
+     */
+    stack?: string;
+    /** Nix-specific environment configuration (nix session mode only). */
+    nix?: NixContainerConfig;
+}
+export interface SkWorkspaceConfig {
+    /** Project name (defaults to directory basename). */
+    name?: string;
+    /** Project description. */
+    description?: string;
+    /**
+     * Agent configuration profiles. The "default" profile provides runtime
+     * defaults (framework, model, provider). Personal overrides live in
+     * .skaile/settings.json and always take priority.
+     *
+     * YAML key: `agent-config` or `agent_config`
+     */
+    agent_config?: Record<string, AgentConfigProfile>;
+    /**
+     * Startup directives — executed when the workspace is launched.
+     * Each item is either a string ("agent:name") or a map
+     * ({ "system-prompt-override": "..." }).
+     */
+    startup?: StartupDirective[];
+    /**
+     * Internal-only — always `{}` on the merged config. Kept on the shape so
+     * `repo-manager`, `lock`, and `runtime-assets` keep type-checking; their
+     * `Record<string, RepositoryDeclaration>` arguments are built from
+     * `ai_resources[]` entries inside the install pipeline.
+     */
+    repositories?: Record<string, RepositoryDeclaration>;
+    /**
+     * Asset dependencies using kind:name[@repo][#pin] syntax (new format).
+     * Top-level flat list — repos and deps are separate concerns.
+     *
+     * YAML key: `dependencies`
+     */
+    dependencies?: string[];
+    /**
+     * Local patches applied during install (new format).
+     * Maps "kind:name" → patch file path relative to project root.
+     *
+     * YAML key: `patches`
+     */
+    patches?: Record<string, string>;
+    /**
+     * AI resource sources, each with its own dependency list.
+     * @deprecated Use `repositories` + `dependencies` instead.
+     */
+    ai_resources?: AiResourceEntry[];
+    /**
+     * Mount declarations — filesystem-projected storage backends.
+     *
+     * Each declaration's `driver` field is an *implicit* catalog ref
+     * (`mount:<driver>`). The runtime resolves it through `resolveRuntimeAssets()`,
+     * which scans every declared `repositories` entry plus the implicit
+     * `@skaile/base-assets` repo for matching `MOUNT.md` manifests. Drivers that
+     * do not match any catalog entry produce a `missing_driver` warning at
+     * session startup.
+     *
+     * YAML key: `mounts`
+     */
+    mounts?: MountDeclaration[];
+    /**
+     * Data connectors — tool-accessed backends.
+     *
+     * Each declaration's `driver` field is an *implicit* catalog ref
+     * (`connector:<driver>`). The runtime resolves it through
+     * `resolveRuntimeAssets()`, which scans every declared `repositories` entry
+     * plus the implicit `@skaile/base-assets` repo for matching `CONNECTOR.md`
+     * manifests. Drivers that do not match any catalog entry produce a
+     * `missing_driver` warning at session startup.
+     *
+     * YAML key: `connectors`
+     */
+    connectors?: ConnectorDeclaration[];
+    /**
+     * External MCP servers — injected into the Claude SDK driver at session startup.
+     * Supports stdio subprocess, SSE, and HTTP transports.
+     *
+     * YAML key: `mcp_servers`
+     */
+    mcp_servers?: McpServerDeclaration[];
+    /** Agent behavior — definition reference, permissions, hooks, subagents. */
+    agent?: AgentConfig;
+    /** Workspace layout — directories, git, setup scripts, container. */
+    workspace?: WorkspaceLayoutConfig;
+    /**
+     * Secret provisioning configuration.
+     * Controls how connector credentials are resolved at runtime.
+     *
+     * YAML key: `secrets`
+     */
+    secrets?: SecretsConfig;
+    /**
+     * Telemetry configuration — passed through raw to the telemetry package.
+     * Parsed by `resolveTelemetryConfig` in `@skaile/workspaces/telemetry`.
+     *
+     * YAML key: `telemetry`
+     */
+    telemetry?: Record<string, unknown>;
+    /**
+     * Session compaction settings -- controls when and how conversation
+     * snapshots are created.
+     *
+     * YAML key: `compaction`
+     */
+    compaction?: CompactionConfig;
+}
+export interface SecretsConfig {
+    /**
+     * How secrets are provided to the container.
+     *   "env"         — read from process.env (default, for CLI/standalone)
+     *   "provisioned" — wait for secrets over transport bridge (platform containers)
+     */
+    provider?: "env" | "provisioned";
+    /** Timeout in ms for waiting for provisioned secrets (default: 30000). */
+    timeoutMs?: number;
+}
+export interface CompactionConfig {
+    /** Enable managed compaction (default: true). */
+    enabled?: boolean;
+    /** Context fill percentage that triggers compaction (default: 80). */
+    thresholdPercent?: number;
+    /** Compact before hibernation for cheap restores (default: true). */
+    compactOnHibernate?: boolean;
+    /** Minimum ms between compactions to prevent thrashing (default: 120000). */
+    minCooldownMs?: number;
+    /** Enable manual compact command in expert mode (default: false). */
+    manualCompactEnabled?: boolean;
+}
+export declare const COMPACTION_DEFAULTS: Required<CompactionConfig>;
+/** @deprecated Use AgentConfigProfile */
+export interface RuntimeDefaults {
+    framework?: string;
+    driver?: string;
+    provider?: string;
+    model?: string;
+    skills_dir?: string;
+    agents_dir?: string;
+    prompts_dir?: string;
+}
+/** @deprecated Use AiResourceEntry[] */
+export interface AiResourcesConfig {
+    sources?: AiResourceSource[];
+    requires?: string[];
+    auto_deploy?: boolean;
+}
+/** @deprecated Use AiResourceEntry */
+export interface AiResourceSource {
+    name: string;
+    path: string;
+    branch?: string;
+}
+export interface SkWorkspaceConfigFile {
+    /** Absolute path to the config file. */
+    path: string;
+    /** Workspace name (extracted from filename). */
+    name: string;
+    /** Parsed config. */
+    config: SkWorkspaceConfig;
+}
+/** Suffix for named workspace configs: `<name>.skaile.yaml` */
+export declare const SKAILE_YAML_SUFFIX = ".skaile.yaml";
+/** Filename for the default workspace config when no name is given. */
+export declare const SKAILE_YAML_DEFAULT = "skaile.yaml";
+/** @deprecated Use SKAILE_YAML_SUFFIX */
+export declare const SK_WORKSPACE_SUFFIX = ".skaile.yaml";
+/** @deprecated Use SKAILE_YAML_DEFAULT */
+export declare const SK_WORKSPACE_DEFAULT_NAME = "default";
+/**
+ * Return the canonical filename for a workspace config.
+ * The default workspace resolves to `"skaile.yaml"`; named workspaces resolve to
+ * `"<name>.skaile.yaml"`.
+ *
+ * @param name - Optional workspace name (omit or pass `"default"` for the primary config)
+ * @returns Filename string (not a full path)
+ * @docLink packages/core/workspace-config#workspace-config-filename
+ */
+export declare function workspaceConfigFilename(name?: string): string;
+/**
+ * Return `true` if `filename` matches the workspace config naming convention
+ * (`"skaile.yaml"` or any `"*.skaile.yaml"`).
+ *
+ * @param filename - Bare filename (no directory component)
+ * @docLink packages/core/workspace-config#is-workspace-config-filename
+ */
+export declare function isWorkspaceConfigFilename(filename: string): boolean;
+/**
+ * Extract the workspace name from a config filename.
+ * `"skaile.yaml"` → `"default"`, `"staging.skaile.yaml"` → `"staging"`.
+ *
+ * @param filename - Bare filename produced by `workspaceConfigFilename`
+ * @returns Workspace name string
+ * @docLink packages/core/workspace-config#workspace-name-from-filename
+ */
+export declare function workspaceNameFromFilename(filename: string): string;
+/**
+ * Load a single workspace config file from `dir`.
+ * When `name` is omitted and no `skaile.yaml` exists, falls back to the sole
+ * `*.skaile.yaml` file in the directory if exactly one is present.
+ *
+ * @param dir - Directory to search for the config file
+ * @param name - Optional workspace name (omit for the default `skaile.yaml`)
+ * @returns Parsed config file info, or `null` if no matching file was found
+ * @docLink packages/core/workspace-config#load-sk-workspace-config
+ */
+export declare function loadSkWorkspaceConfig(dir: string, name?: string): SkWorkspaceConfigFile | null;
+/**
+ * Serialize and write a workspace config to `dir`, creating the directory if needed.
+ *
+ * @param dir - Target directory (created recursively if absent)
+ * @param config - Config object to serialize as YAML
+ * @param name - Optional workspace name (omit for the default `skaile.yaml`)
+ * @returns Absolute path of the written file
+ * @docLink packages/core/workspace-config#save-sk-workspace-config
+ */
+export declare function saveSkWorkspaceConfig(dir: string, config: SkWorkspaceConfig, name?: string): string;
+/**
+ * List all workspace config files present in `dir`, sorted alphabetically by name.
+ * Returns an empty array when `dir` does not exist or is unreadable.
+ *
+ * @param dir - Directory to scan for `skaile.yaml` and `*.skaile.yaml` files
+ * @returns Array of parsed config file descriptors
+ * @docLink packages/core/workspace-config#list-sk-workspace-configs
+ */
+export declare function listSkWorkspaceConfigs(dir: string): SkWorkspaceConfigFile[];
+/**
+ * Resolve the effective workspace config by stacking configs across three scope levels:
+ * user (`~/.skaile/`) < app (`opts.appDir`) < project (`projectDir`).
+ *
+ * Each level's config is merged with `mergeSkWorkspaceConfigs`, with higher-priority
+ * scopes winning for scalars and unions applied for arrays (deny lists, directories, etc.).
+ * Returns an empty object `{}` when no config files are found.
+ *
+ * @param projectDir - Root directory of the current project
+ * @param opts - Optional overrides: `name` selects a named workspace (default: `"default"`),
+ *               `appDir` inserts an app-level config between user and project scopes
+ * @returns Merged effective `SkWorkspaceConfig`
+ * @docLink packages/core/workspace-config#resolve-sk-workspace-config
+ */
+export declare function resolveSkWorkspaceConfig(projectDir: string, opts?: {
+    name?: string;
+    appDir?: string;
+}): SkWorkspaceConfig;
+/**
+ * Walk upward from `startDir` looking for a `skaile.yaml` (or `*.skaile.yaml`).
+ * Returns the directory containing the first match, or `undefined` if none found.
+ *
+ * Stops after 20 levels to avoid scanning all the way to `/`.
+ *
+ * @param startDir - Directory to start searching from (usually `process.cwd()`)
+ * @returns Absolute path to the workspace root, or `undefined`
+ * @docLink packages/core/workspace-config#find-workspace-root
+ */
+export declare function findWorkspaceRoot(startDir: string): string | undefined;
+/**
+ * Deep-merge two workspace configs according to stacking rules.
+ * `overlay` takes priority over `base` for scalar fields.
+ * Arrays use concatenation + deduplication; deny lists always union.
+ * Mounts and connectors are merged by `id` (overlay entry wins for same id).
+ * Hooks are concatenated in order (base first, overlay appended).
+ *
+ * @param base - Lower-priority config (e.g. user or app scope)
+ * @param overlay - Higher-priority config (e.g. project scope)
+ * @returns Merged `SkWorkspaceConfig`
+ * @docLink packages/core/workspace-config#merge-sk-workspace-configs
+ */
+export declare function mergeSkWorkspaceConfigs(base: SkWorkspaceConfig, overlay: SkWorkspaceConfig): SkWorkspaceConfig;
+/**
+ * Normalize a raw parsed YAML object into the canonical SkWorkspaceConfig shape.
+ * Handles backward-compatible fields:
+ *   - `agent-config` (hyphen) → `agent_config`
+ *   - `ai_resources` as object (old {sources, requires}) → AiResourceEntry[]
+ *   - `data_resources` → `connectors`
+ * @docLink packages/core/workspace-config#normalize-config
+ */
+export declare function normalizeConfig(raw: Record<string, unknown>): SkWorkspaceConfig;
+/**
+ * Load MCP server declarations by merging two sources:
+ *
+ * 1. **Catalog defaults** — `mcp-server:*` refs in the `dependencies` array
+ *    (or legacy `ai_resources[].dependencies`). Each ref is resolved from the
+ *    repository catalog; the `MCP.md` frontmatter provides default config
+ *    (transport, command, args, env, url, headers).
+ *
+ * 2. **Explicit declarations** — entries in the `mcp_servers` section of
+ *    `skaile.yaml`. These override catalog defaults field-by-field when the
+ *    `id` matches a catalog-resolved server name.
+ *
+ * This allows users to write `dependencies: [mcp:excel]` and get a working
+ * server from catalog defaults, or add an `mcp_servers:` override to customize
+ * specific fields (e.g. env vars, mount paths).
+ *
+ * @param projectDir - Workspace root where `skaile.yaml` lives
+ * @returns Unified array of `McpServerDeclaration` objects ready for the runner
+ * @docLink packages/core/workspace-config#load-mcp-server-declarations
+ */
+export declare function loadMcpServerDeclarations(projectDir: string): McpServerDeclaration[];
+/**
+ * Resolve the `agent.definition` field from `skaile.yaml` in `projectDir`
+ * to an absolute filesystem path.
+ *
+ * Resolution rules:
+ *   - Absent or empty → undefined
+ *   - Relative/absolute local path → resolve(projectDir, definition)
+ *   - `ai-assets://<rest>` → walk up for ai-assets/, join with <rest>
+ *   - `agent:<name>` catalog refs → resolved via repository scanning
+ *
+ * Used by the runner to determine agentDir without requiring --agent-dir.
+ * @docLink packages/core/workspace-config#resolve-agent-dir
+ */
+export declare function resolveAgentDir(projectDir: string): string | undefined;
+//# sourceMappingURL=workspace-config.d.ts.map