@shadowob/cloud 1.1.6-dev.311

package/dist/index.d.ts

@@ -0,0 +1,3013 @@
+import { spawn, ChildProcess } from 'node:child_process';
+import { z } from 'zod';
+import { Command } from 'commander';
+import { tags } from 'typia';
+import * as _pulumi_pulumi_automation_stack_js from '@pulumi/pulumi/automation/stack.js';
+import * as automation from '@pulumi/pulumi/automation/index.js';
+import * as pulumi from '@pulumi/pulumi';
+
+interface DeploymentRuntimeContext {
+    locale?: string;
+    timezone?: string;
+}
+
+/**
+ * Provision state — persists provisioned resource IDs to disk.
+ *
+ * State is saved to `.shadowob/provision-state.json` relative to the config file.
+ * This allows follow-up commands (status, logs, scale, down) to reference
+ * real IDs without re-provisioning.
+ *
+ * State file is gitignored (.shadowob/).
+ */
+interface ProvisionState {
+    /** ISO timestamp of when provisioning last ran */
+    provisionedAt: string;
+    /** Stack name used during deployment (if any) */
+    stackName?: string;
+    /** K8s namespace deployed to (if any) */
+    namespace?: string;
+    /**
+     * Plugin-keyed state blobs. Each plugin owns its own schema under its plugin ID.
+     * e.g. plugins.shadowob = { servers: {...}, channels: {...}, buddies: {...} }
+     */
+    plugins: Record<string, Record<string, unknown>>;
+}
+
+declare const CLOUD_SAAS_RUNTIME_KEY = "__shadowobRuntime";
+declare function validateCloudSaasConfigSnapshot(configSnapshot: unknown): Record<string, unknown>;
+declare function prepareCloudSaasConfigSnapshot(configSnapshot: unknown, envVars?: Record<string, string>, context?: DeploymentRuntimeContext): Record<string, unknown>;
+declare function attachCloudSaasProvisionState(configSnapshot: unknown, provisionState: ProvisionState): Record<string, unknown>;
+declare function extractCloudSaasRuntime(configSnapshot: unknown): {
+    configSnapshot: Record<string, unknown> | null;
+    envVars: Record<string, string>;
+    context: DeploymentRuntimeContext;
+    provisionState: ProvisionState | null;
+};
+declare function resolveCloudSaasShadowRuntime(envVars?: Record<string, string>, processEnv?: Record<string, string | undefined>): {
+    shadowUrl?: string;
+    podShadowUrl?: string;
+    shadowToken?: string;
+};
+declare function redactCloudSaasConfigSnapshot(configSnapshot: unknown): unknown;
+declare function sanitizeCloudSaasDeployment<T extends {
+    configSnapshot?: unknown;
+}>(deployment: T): T;
+
+declare function loadCloudConfigSchema(): Record<string, unknown>;
+
+interface CloudConfigValidationSummary {
+    valid: boolean;
+    agents: number;
+    configurations: number;
+    violations: Array<{
+        path: string;
+        prefix: string;
+    }>;
+    extendsErrors: string[];
+    templateRefs: {
+        env: number;
+        secret: number;
+        file: number;
+    };
+}
+declare function summarizeCloudConfigValidation(configData: unknown): CloudConfigValidationSummary;
+
+/**
+ * OpenClaw official config types.
+ * Based on https://docs.openclaw.ai/gateway/configuration-reference
+ */
+
+/**
+ * OpenClaw model configuration.
+ * Accepts "provider/model" string form or object with primary + fallbacks.
+ */
+interface OpenClawModelConfig {
+    /** Primary model in "provider/model" format */
+    primary: string;
+    /** Ordered fallback models */
+    fallbacks?: string[];
+}
+/**
+ * OpenClaw model catalog entry with alias and params.
+ */
+interface OpenClawModelEntry {
+    /** Shortcut alias for /model command */
+    alias?: string;
+    /** Provider-specific params (temperature, maxTokens, etc.) */
+    params?: Record<string, unknown>;
+}
+/**
+ * OpenClaw agent defaults configuration.
+ */
+interface OpenClawAgentDefaults {
+    /** Default workspace path */
+    workspace?: string;
+    /** Repository root for system prompt */
+    repoRoot?: string;
+    /** Skip bootstrap file creation */
+    skipBootstrap?: boolean;
+    /** Max chars per bootstrap file */
+    bootstrapMaxChars?: number & tags.Type<'uint32'>;
+    /** Max total bootstrap chars */
+    bootstrapTotalMaxChars?: number & tags.Type<'uint32'>;
+    /** Model config — string or { primary, fallbacks } */
+    model?: string | OpenClawModelConfig;
+    /** Image model config */
+    imageModel?: string | OpenClawModelConfig;
+    /** PDF model config */
+    pdfModel?: string | OpenClawModelConfig;
+    /** Image generation model config */
+    imageGenerationModel?: string | OpenClawModelConfig;
+    /** Model catalog keyed by "provider/model" */
+    models?: Record<string, OpenClawModelEntry>;
+    /** Default thinking level */
+    thinkingDefault?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'adaptive';
+    /** Default verbose level */
+    verboseDefault?: 'off' | 'on' | 'full';
+    /** Default elevated-output level */
+    elevatedDefault?: 'off' | 'on' | 'ask' | 'full';
+    /** Timeout in seconds */
+    timeoutSeconds?: number & tags.Type<'uint32'>;
+    /** Media max size in MB */
+    mediaMaxMb?: number & tags.Type<'uint32'>;
+    /** Context token limit */
+    contextTokens?: number & tags.Type<'uint32'>;
+    /** Max concurrent agent runs */
+    maxConcurrent?: number & tags.Type<'uint32'>;
+    /** User timezone */
+    userTimezone?: string;
+    /** Timezone for inbound message envelope timestamps */
+    envelopeTimezone?: string;
+    /** Whether to include absolute timestamps in inbound message envelopes */
+    envelopeTimestamp?: 'on' | 'off';
+    /** Whether to include elapsed time suffixes in inbound message envelopes */
+    envelopeElapsed?: 'on' | 'off';
+    /** Time format */
+    timeFormat?: 'auto' | '12' | '24';
+    /** Heartbeat config */
+    heartbeat?: OpenClawHeartbeatConfig;
+    /** Compaction config */
+    compaction?: OpenClawCompactionConfig;
+    /** Sandbox config */
+    sandbox?: Record<string, unknown>;
+    /** Subagent defaults */
+    subagents?: OpenClawSubagentDefaults;
+}
+interface OpenClawHeartbeatConfig {
+    /** Interval duration string (e.g. "30m") */
+    every?: string;
+    /** Model for heartbeat runs */
+    model?: string;
+    /** Heartbeat prompt */
+    prompt?: string;
+    /** Session key */
+    session?: string;
+    /** Delivery target */
+    to?: string;
+    /** Target channel */
+    target?: string;
+}
+interface OpenClawCompactionConfig {
+    /** Compaction mode */
+    mode?: 'default' | 'safeguard';
+    /** Timeout in seconds */
+    timeoutSeconds?: number & tags.Type<'uint32'>;
+    /** Identifier policy */
+    identifierPolicy?: 'strict' | 'off' | 'custom';
+    /** Custom instructions for identifier preservation */
+    identifierInstructions?: string;
+    /** Model for compaction summarization */
+    model?: string;
+}
+interface OpenClawSubagentDefaults {
+    /** Default model for sub-agents */
+    model?: string;
+    /** Max concurrent sub-agents */
+    maxConcurrent?: number & tags.Type<'uint32'>;
+    /** Run timeout in seconds */
+    runTimeoutSeconds?: number & tags.Type<'uint32'>;
+}
+/**
+ * OpenClaw ACP runtime config for an agent.
+ */
+interface OpenClawAcpRuntime {
+    /** ACP harness agent id (e.g. "claude", "codex") */
+    agent: string;
+    /** ACP backend id */
+    backend?: string;
+    /** Session mode */
+    mode?: 'persistent' | 'ephemeral';
+    /** Working directory inside the harness */
+    cwd?: string;
+}
+/**
+ * OpenClaw agent identity config.
+ */
+interface OpenClawAgentIdentity {
+    /** Agent display name */
+    name?: string;
+    /** Theme description */
+    theme?: string;
+    /** Emoji identifier */
+    emoji?: string;
+    /** Avatar path or URL */
+    avatar?: string;
+}
+/**
+ * OpenClaw per-agent configuration (agents.list[] entry).
+ */
+interface OpenClawAgentConfig {
+    /** Stable agent id (required) */
+    id: string;
+    /** Whether this is the default agent */
+    default?: boolean;
+    /** Agent display name */
+    name?: string;
+    /** Workspace path */
+    workspace?: string;
+    /** Agent dir override */
+    agentDir?: string;
+    /** Model override */
+    model?: string | OpenClawModelConfig;
+    /** Per-agent thinking level */
+    thinkingDefault?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'adaptive';
+    /** Per-agent params merged over model catalog */
+    params?: Record<string, unknown>;
+    /** Agent identity */
+    identity?: OpenClawAgentIdentity;
+    /** Group chat mention patterns */
+    groupChat?: {
+        mentionPatterns?: string[];
+    };
+    /** Runtime descriptor */
+    runtime?: {
+        type: 'acp' | 'subagent';
+        acp?: OpenClawAcpRuntime;
+    };
+    /** Subagent allow rules */
+    subagents?: {
+        allowAgents?: string[];
+    };
+    /** Tool restrictions */
+    tools?: {
+        profile?: 'minimal' | 'coding' | 'messaging' | 'full' | 'dangerously-skip-permissions' | 'approve-reads' | 'approve-all' | 'deny-all';
+        allow?: string[];
+        deny?: string[];
+        elevated?: {
+            enabled?: boolean;
+        };
+    };
+    /** Sandbox config override */
+    sandbox?: Record<string, unknown>;
+    /** System prompt (convenience, non-standard) */
+    systemPrompt?: string;
+    /** Final instructions text (mapped from personality + systemPrompt) */
+    instructions?: string;
+}
+/**
+ * OpenClaw agents section.
+ */
+interface OpenClawAgentsConfig {
+    /** Agent defaults */
+    defaults?: OpenClawAgentDefaults;
+    /** Per-agent list */
+    list?: OpenClawAgentConfig[];
+}
+/**
+ * OpenClaw ACP global config.
+ */
+interface OpenClawAcpConfig {
+    /** Enable ACP feature */
+    enabled?: boolean;
+    /** Dispatch toggle */
+    dispatch?: {
+        enabled?: boolean;
+    };
+    /** Default ACP runtime backend id */
+    backend?: string;
+    /** Default ACP target agent id */
+    defaultAgent?: string;
+    /** Allowed agent ids for ACP sessions */
+    allowedAgents?: string[];
+    /** Max concurrent ACP sessions */
+    maxConcurrentSessions?: number & tags.Type<'uint32'>;
+    /** Stream config */
+    stream?: {
+        coalesceIdleMs?: number;
+        maxChunkChars?: number;
+        repeatSuppression?: boolean;
+        deliveryMode?: 'live' | 'final_only';
+        maxOutputChars?: number;
+        maxSessionUpdateChars?: number;
+    };
+    /** Runtime TTL */
+    runtime?: {
+        ttlMinutes?: number;
+    };
+}
+/**
+ * OpenClaw binding entry for multi-agent routing.
+ */
+interface OpenClawBinding {
+    /** Agent to route to */
+    agentId: string;
+    /** Binding type */
+    type?: 'route' | 'acp';
+    /** Match criteria */
+    match: {
+        /** Channel name (e.g. "telegram", "discord", "shadowob") */
+        channel: string;
+        /** Account id or "*" for any */
+        accountId?: string;
+        /** Peer matching */
+        peer?: {
+            kind?: 'direct' | 'group' | 'channel';
+            id?: string;
+        };
+        /** Guild ID (Discord) */
+        guildId?: string;
+        /** Team ID (Teams) */
+        teamId?: string;
+    };
+    /** ACP binding config (only for type: "acp") */
+    acp?: {
+        mode?: string;
+        label?: string;
+        cwd?: string;
+        backend?: string;
+    };
+}
+/**
+ * OpenClaw channel-level DM/group policies.
+ */
+interface OpenClawChannelBase {
+    /** Whether channel is enabled */
+    enabled?: boolean;
+    /** Channel-specific feature gates such as inline buttons or file uploads */
+    capabilities?: OpenClawChannelCapabilities;
+    /** DM policy */
+    dmPolicy?: 'pairing' | 'allowlist' | 'open' | 'disabled';
+    /** Allowed senders */
+    allowFrom?: string[];
+    /** Group policy */
+    groupPolicy?: 'allowlist' | 'open' | 'disabled';
+    /** History limit */
+    historyLimit?: number & tags.Type<'uint32'>;
+    /** Media max size in MB */
+    mediaMaxMb?: number & tags.Type<'uint32'>;
+    /** Streaming mode */
+    streaming?: 'off' | 'partial' | 'block' | 'progress';
+    /** Config writes toggle */
+    configWrites?: boolean;
+}
+interface OpenClawChannelCapabilities {
+    /** Inline button scope: off, DM-only, group-only, all, or allowlist */
+    inlineButtons?: 'off' | 'dm' | 'group' | 'all' | 'allowlist' | boolean;
+    /** Native interactive message support */
+    interactive?: boolean;
+    /** Native form message support */
+    forms?: boolean;
+    /** Plugin-specific feature gates */
+    [key: string]: unknown;
+}
+/**
+ * OpenClaw channels section — each channel key matches official docs.
+ */
+interface OpenClawChannelsConfig {
+    /** Channel defaults */
+    defaults?: {
+        groupPolicy?: 'allowlist' | 'open' | 'disabled';
+        heartbeat?: {
+            showOk?: boolean;
+            showAlerts?: boolean;
+            useIndicator?: boolean;
+        };
+    };
+    /** Model overrides by channel ID */
+    modelByChannel?: Record<string, Record<string, string>>;
+    /** Telegram config */
+    telegram?: OpenClawChannelBase & {
+        botToken?: string;
+        groups?: Record<string, unknown>;
+        customCommands?: Array<{
+            command: string;
+            description: string;
+        }>;
+        replyToMode?: 'off' | 'first' | 'all';
+        linkPreview?: boolean;
+    };
+    /** Discord config */
+    discord?: OpenClawChannelBase & {
+        token?: string;
+        allowBots?: boolean | 'mentions';
+        guilds?: Record<string, unknown>;
+        replyToMode?: 'off' | 'first' | 'all';
+        textChunkLimit?: number;
+        chunkMode?: 'length' | 'newline';
+    };
+    /** Slack config */
+    slack?: OpenClawChannelBase & {
+        botToken?: string;
+        appToken?: string;
+        channels?: Record<string, unknown>;
+        allowBots?: boolean;
+    };
+    /** WhatsApp config */
+    whatsapp?: OpenClawChannelBase & {
+        textChunkLimit?: number;
+        chunkMode?: 'length' | 'newline';
+        sendReadReceipts?: boolean;
+        groups?: Record<string, unknown>;
+    };
+    /** Shadow/ShadowOB channel config */
+    shadowob?: OpenClawChannelBase & {
+        enabled?: boolean;
+        capabilities?: OpenClawChannelCapabilities;
+        accounts?: Record<string, {
+            token?: string;
+            serverUrl?: string;
+            enabled?: boolean;
+            capabilities?: OpenClawChannelCapabilities;
+        }>;
+    };
+    /** Additional channels (Google Chat, Signal, iMessage, etc.) */
+    [key: string]: unknown;
+}
+/**
+ * OpenClaw tools section.
+ */
+interface OpenClawToolsConfig {
+    /** Tool profile */
+    profile?: 'minimal' | 'coding' | 'messaging' | 'full' | 'dangerously-skip-permissions' | 'approve-reads' | 'approve-all' | 'deny-all';
+    /** Allow specific tools */
+    allow?: string[];
+    /** Deny specific tools */
+    deny?: string[];
+    /** Read-only tools (approve-reads level) */
+    readOnly?: string[];
+    /** Behavior when approval is needed but no human is present */
+    nonInteractive?: 'deny' | 'fail';
+    /** Elevated exec config */
+    elevated?: {
+        enabled?: boolean;
+        allowFrom?: Record<string, string[]>;
+    };
+    /** Exec config */
+    exec?: {
+        backgroundMs?: number;
+        timeoutSec?: number;
+    };
+    /** Web tools config */
+    web?: {
+        search?: {
+            enabled?: boolean;
+            apiKey?: string;
+            maxResults?: number;
+        };
+        fetch?: {
+            enabled?: boolean;
+            maxChars?: number;
+        };
+    };
+    /** Sandbox tools */
+    sandbox?: Record<string, unknown>;
+}
+/**
+ * OpenClaw custom provider config.
+ */
+interface OpenClawProviderConfig {
+    /** Provider ID */
+    id?: string;
+    /** API adapter type */
+    api?: string;
+    /** API key or SecretRef */
+    apiKey?: string;
+    /** Auth strategy */
+    auth?: string;
+    /** Upstream base URL */
+    baseUrl?: string;
+    /** Extra static headers */
+    headers?: Record<string, string>;
+    /** Transport overrides (e.g. allowPrivateNetwork for proxy environments) */
+    request?: {
+        allowPrivateNetwork?: boolean;
+    };
+    /** Provider model catalog */
+    models?: Array<{
+        id: string;
+        name?: string;
+        reasoning?: boolean;
+        input?: string[];
+        contextWindow?: number;
+        maxTokens?: number;
+        cost?: {
+            input?: number;
+            output?: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+        };
+    }>;
+}
+/**
+ * OpenClaw models section.
+ */
+interface OpenClawModelsConfig {
+    /** Merge mode */
+    mode?: 'merge' | 'replace';
+    /** Custom providers */
+    providers?: Record<string, OpenClawProviderConfig>;
+}
+/**
+ * OpenClaw plugins section.
+ */
+interface OpenClawPluginsConfig {
+    /** Global enable/disable */
+    enabled?: boolean;
+    /** Plugin allowlist */
+    allow?: string[];
+    /** Plugin denylist */
+    deny?: string[];
+    /** Plugin load paths */
+    load?: {
+        paths?: string[];
+    };
+    /** Per-plugin config */
+    entries?: Record<string, {
+        enabled?: boolean;
+        config?: Record<string, unknown>;
+        hooks?: {
+            allowPromptInjection?: boolean;
+        };
+    }>;
+}
+/**
+ * OpenClaw skills section.
+ * Matches https://docs.openclaw.ai/gateway/configuration-reference#skills
+ */
+interface OpenClawSkillsConfig {
+    /** Allowed bundled skills */
+    allowBundled?: string[];
+    /** Extra skill directories */
+    load?: {
+        extraDirs?: string[];
+    };
+    /** Installation preferences */
+    install?: {
+        preferBrew?: boolean;
+        nodeManager?: 'npm' | 'pnpm' | 'yarn';
+    };
+    /** Per-skill config */
+    entries?: Record<string, {
+        enabled?: boolean;
+        apiKey?: string;
+        env?: Record<string, string>;
+        config?: Record<string, unknown>;
+    }>;
+}
+/**
+ * OpenClaw gateway section.
+ */
+interface OpenClawGatewayConfig {
+    /** Gateway mode */
+    mode?: 'local' | 'remote';
+    /** Gateway port */
+    port?: number & tags.Type<'uint32'>;
+    /** Bind address */
+    bind?: string;
+    /** Auth config */
+    auth?: {
+        mode?: 'none' | 'token' | 'password' | 'trusted-proxy';
+        token?: string;
+        password?: string;
+        allowTailscale?: boolean;
+    };
+    /** TLS config */
+    tls?: {
+        enabled?: boolean;
+        certPath?: string;
+        keyPath?: string;
+    };
+    /** Reload behavior */
+    reload?: {
+        mode?: 'off' | 'restart' | 'hot' | 'hybrid';
+        debounceMs?: number;
+    };
+}
+/**
+ * OpenClaw session section.
+ */
+interface OpenClawSessionConfig {
+    /** Session scope */
+    scope?: string;
+    /** DM session scope */
+    dmScope?: 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
+    /** Session reset config */
+    reset?: {
+        mode?: 'daily' | 'idle';
+        atHour?: number;
+        idleMinutes?: number;
+    };
+    /** Reset by chat type */
+    resetByType?: Record<string, {
+        mode?: 'daily' | 'idle';
+        atHour?: number;
+        idleMinutes?: number;
+    }>;
+    /** Reset triggers */
+    resetTriggers?: string[];
+    /** Session store path */
+    store?: string;
+    /** Thread bindings */
+    threadBindings?: {
+        enabled?: boolean;
+        idleHours?: number;
+        maxAgeHours?: number;
+    };
+}
+/**
+ * OpenClaw logging section.
+ * Matches https://docs.openclaw.ai/gateway/configuration-reference#logging
+ */
+interface OpenClawLoggingConfig {
+    /** Log level */
+    level?: string;
+    /** Log file path */
+    file?: string;
+    /** Console log level */
+    consoleLevel?: string;
+    /** Console output style */
+    consoleStyle?: 'pretty' | 'compact' | 'json';
+    /** Redact sensitive data from tool output */
+    redactSensitive?: 'off' | 'tools';
+}
+/**
+ * OpenClaw messages section.
+ * Matches https://docs.openclaw.ai/gateway/configuration-reference#messages
+ */
+interface OpenClawMessagesConfig {
+    /** Response prefix */
+    responsePrefix?: string;
+    /** Ack reaction emoji */
+    ackReaction?: string;
+    /** Ack reaction scope */
+    ackReactionScope?: 'group-mentions' | 'group-all' | 'direct' | 'all';
+    /** Remove ack after reply */
+    removeAckAfterReply?: boolean;
+    /** Message queue config */
+    queue?: {
+        mode?: 'collect' | 'steer' | 'followup' | 'queue' | 'interrupt';
+        debounceMs?: number;
+        cap?: number;
+    };
+    /** Group chat config */
+    groupChat?: {
+        historyLimit?: number;
+    };
+}
+/**
+ * Full OpenClaw config (openclaw.json format).
+ * Matches https://docs.openclaw.ai/gateway/configuration-reference
+ */
+interface OpenClawConfig {
+    /** Agents section */
+    agents?: OpenClawAgentsConfig;
+    /** Multi-agent routing bindings */
+    bindings?: OpenClawBinding[];
+    /** Channel configs */
+    channels?: OpenClawChannelsConfig;
+    /** ACP config */
+    acp?: OpenClawAcpConfig;
+    /** Session config */
+    session?: OpenClawSessionConfig;
+    /** Messages config */
+    messages?: OpenClawMessagesConfig;
+    /** Tools config */
+    tools?: OpenClawToolsConfig;
+    /** Custom model providers */
+    models?: OpenClawModelsConfig;
+    /** Plugin config */
+    plugins?: OpenClawPluginsConfig;
+    /** Skill config */
+    skills?: OpenClawSkillsConfig;
+    /** Gateway config */
+    gateway?: OpenClawGatewayConfig;
+    /** Logging config */
+    logging?: OpenClawLoggingConfig;
+    /** Environment variables */
+    env?: Record<string, unknown>;
+    /** Additional top-level fields */
+    [key: string]: unknown;
+}
+
+/**
+ * GitAgent source and manifest types.
+ * Based on the gitagent standard (MIT): https://github.com/open-gitagent/gitagent
+ */
+
+/**
+ * Git repository reference for an agent source.
+ */
+interface GitSource {
+    /** Repository URL (https or ssh) */
+    url: string;
+    /** Branch, tag, or full SHA. Defaults to "main" */
+    ref?: string;
+    /**
+     * Subdirectory inside the repository that contains the agent definition
+     * (e.g. "agents/my-agent" in a monorepo). Defaults to repo root.
+     */
+    dir?: string;
+    /** Shallow clone depth. Defaults to 1 */
+    depth?: number & tags.Type<'uint32'>;
+    /**
+     * Name of a K8s Secret that contains an SSH private key for private repos.
+     * The secret must have a key named `ssh-privatekey`.
+     */
+    sshKeySecret?: string;
+    /**
+     * Name of a K8s Secret (or literal token via ${env:VAR}) for HTTPS auth.
+     * Used as: git clone https://<token>@host/repo
+     */
+    tokenSecret?: string;
+}
+/**
+ * How the agent source overlay is handled.
+ * - "init-container": At pod startup, an init container clones the repo and
+ *   copies files to a shared EmptyDir volume. No build step required.
+ * - "build-image": Files are baked into the container image at `shadowob-cloud build` time
+ *   using a multi-stage Dockerfile (no runtime git access in K8s).
+ */
+type AgentSourceStrategy = 'init-container' | 'build-image';
+/**
+ * Agent file source specification.
+ * Points the agent at a git repository (or local path) that follows the
+ * gitagent directory layout: SOUL.md, RULES.md, agent.yaml, skills/, tools/,
+ * hooks/, skillflows/, memory/, compliance/, etc.
+ */
+interface AgentSource {
+    /** Git repository source */
+    git?: GitSource;
+    /**
+     * Local filesystem path (dev/CI mode).
+     * Resolved at `shadowob-cloud up` time and baked into a ConfigMap or
+     * used for local adapter pre-population.
+     */
+    path?: string;
+    /**
+     * Strategy for delivering source files into the container.
+     * Default: "init-container"
+     */
+    strategy?: AgentSourceStrategy;
+    /**
+     * Path inside the container where the agent source is mounted.
+     * OpenClaw reads SOUL.md, RULES.md, skills/, etc. from this directory.
+     * Default: "/agent"
+     */
+    mountPath?: string;
+    /**
+     * Specific file/directory patterns to copy from the source.
+     * Default: all standard gitagent files (SOUL.md, RULES.md, skills/, etc.)
+     * Use this to limit what gets overlaid.
+     */
+    include?: string[];
+    /**
+     * When true, the mounted directory is treated as a gitagent standard layout.
+     * The adapter will:
+     *   - set OpenClaw's agentDir to mountPath (reads SOUL.md, RULES.md automatically)
+     *   - parse agent.yaml model config and merge into agent.model
+     *   - parse hooks/hooks.yaml and map to OpenClaw hooks
+     *   - enumerate skillflows/*.yaml and map to agent.workflows
+     *   - configure compliance from compliance/regulatory-map.yaml
+     * Default: true
+     */
+    gitagent?: boolean;
+    /**
+     * When strategy is "build-image": Docker registry to push the built image to.
+     * e.g. "ghcr.io/my-org/my-agent:latest"
+     * If omitted, uses a local image name based on agentId.
+     */
+    imageTag?: string;
+}
+
+/**
+ * Managed agents types — vault, permissions, networking.
+ */
+/** Permission level for agent tools — maps to ACPX permission modes. */
+type PermissionLevel = 'always-allow' | 'approve-reads' | 'always-ask' | 'deny-all';
+/**
+ * Per-tool permission policy for an agent.
+ * Inspired by Claude Managed Agents' toolset-level permission control.
+ */
+interface AgentPermissions {
+    /** Default permission level for all tools */
+    default: PermissionLevel;
+    /** Per-tool overrides — key is tool name, supports glob patterns (e.g. "mcp-*") */
+    tools?: Record<string, PermissionLevel>;
+    /** Behaviour when the agent runs non-interactively (no human in the loop) */
+    nonInteractive?: 'deny' | 'fail';
+}
+/**
+ * Per-agent networking policy configuration.
+ * Generates K8s NetworkPolicy resources to control egress.
+ */
+interface AgentNetworking {
+    /** Network policy type */
+    type: 'unrestricted' | 'limited' | 'deny-all';
+    /** Allowed egress domains (requires Cilium for FQDN-level enforcement) */
+    allowedHosts?: string[];
+    /** Allow egress to MCP server endpoints (auto-extracted from agent config) */
+    allowMcpServers?: boolean;
+    /** Allow egress to package manager registries (npm, pypi, etc.) */
+    allowPackageManagers?: boolean;
+}
+/**
+ * Vault provider secret source — where to read a secret value from.
+ */
+interface VaultSecretSource {
+    /** API key or token value (template ref: ${env:...}, ${file:...}, ${k8s:ns/secret/key}) */
+    apiKey?: string;
+}
+/**
+ * Vault configuration — per-agent secret isolation.
+ * Each vault generates an isolated K8s Secret containing only the keys an agent needs.
+ */
+interface VaultConfig {
+    /** Provider API keys for this vault */
+    providers?: Record<string, VaultSecretSource>;
+    /** Additional named secrets */
+    secrets?: Record<string, string>;
+}
+
+/**
+ * Shadow plugin config types — servers, channels, buddies, bindings.
+ * Also defines the universal UseEntry type for the "use" pattern.
+ */
+
+/**
+ * A single plugin declaration in the `use` array.
+ *
+ * @example
+ * { "plugin": "shadowob", "options": { "baseURL": "${env:SHADOWOB_BASE_URL}" } }
+ * { "plugin": "gitagent", "options": { "repo": "github.com/user/repo" } }
+ */
+interface UseEntry {
+    /** Plugin identifier (e.g. "shadowob", "gitagent", "slack") */
+    plugin: string;
+    /** Plugin-specific options */
+    options?: Record<string, unknown>;
+}
+
+/**
+ * Agent runtime types.
+ */
+type AgentRuntime = 'openclaw' | 'claude-code' | 'codex' | 'gemini' | 'opencode' | 'hermes';
+/**
+ * Agent model configuration — mirrors gitagent's model section.
+ * Specifies primary model with ordered fallbacks and inference constraints.
+ */
+interface AgentModel {
+    /** Primary model in "provider/model" format (e.g. "anthropic/claude-sonnet-4-5") */
+    preferred: string;
+    /** Ordered fallback models tried if primary is unavailable */
+    fallbacks?: string[];
+    /** Inference constraints */
+    constraints?: {
+        /** Sampling temperature 0.0–2.0 */
+        temperature?: number & tags.Minimum<0> & tags.Maximum<2>;
+        /** Max output tokens */
+        maxTokens?: number & tags.Type<'uint32'>;
+        /** Top-p sampling parameter */
+        topP?: number & tags.Minimum<0> & tags.Maximum<1>;
+        /** Thinking depth level */
+        thinkingLevel?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'adaptive';
+    };
+}
+/**
+ * Agent identity / soul — who the agent is.
+ * Mirrors gitagent's SOUL.md concept, expressed inline in the config.
+ */
+interface AgentIdentity {
+    /** Display name for the agent */
+    name?: string;
+    /** One-line description of what this agent does */
+    description?: string;
+    /**
+     * Personality, communication style, values, domain expertise.
+     * Free-form text injected before the main system prompt.
+     * Equivalent to SOUL.md content.
+     */
+    personality?: string;
+    /**
+     * Full system prompt override. When set, replaces any inherited prompt.
+     * If `personality` is also set, it is prepended to this value.
+     *
+     * **Priority** (highest to lowest):
+     * 1. `identity.systemPrompt` — overrides everything
+     * 2. `configuration.openclaw.agents[].systemPrompt` — OpenClaw agent level
+     * 3. `OpenClawAgentConfig.systemPrompt` — convenience field in config preset
+     *
+     * When `identity.personality` is also set, final prompt is:
+     * `${personality}\n\n${systemPrompt}`
+     */
+    systemPrompt?: string;
+}
+/**
+ * A single step in an agent workflow (SkillsFlow-style).
+ */
+interface AgentWorkflowStep {
+    /** Skill name to invoke */
+    skill?: string;
+    /** Sub-agent ID to delegate to */
+    agent?: string;
+    /** Tool name to call */
+    tool?: string;
+    /** Step IDs that must complete before this step runs */
+    dependsOn?: string[];
+    /** Input mappings — supports ${{ steps.X.outputs.Y }} template syntax */
+    inputs?: Record<string, string>;
+    /** Per-step prompt injection — extra guidance appended to the step context */
+    prompt?: string;
+    /** Conditions that must be true for this step to run */
+    conditions?: string[];
+}
+/**
+ * Deterministic multi-step workflow — mirrors gitagent's SkillsFlow / workflows/*.yaml.
+ * Chains skills, agents, and tools with explicit dependencies and data flow.
+ */
+interface AgentWorkflowDef {
+    /** Workflow identifier */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Events or cron expressions that trigger this workflow */
+    triggers?: string[];
+    /** Cron schedule (e.g. "0 9 * * *" for 9am daily) */
+    schedule?: string;
+    /** Ordered/parallel steps keyed by step ID */
+    steps: Record<string, AgentWorkflowStep>;
+    /** Error handling config */
+    errorHandling?: {
+        onFailure?: 'retry' | 'notify' | 'abort';
+        notifyChannel?: string;
+        maxRetries?: number & tags.Type<'uint32'>;
+    };
+}
+/**
+ * Agent compliance/risk policy.
+ * Mirrors gitagent compliance fields in camelCase for internal usage.
+ */
+interface AgentCompliance {
+    /** Risk tier for this agent's tasks */
+    riskTier?: 'low' | 'standard' | 'high' | 'critical';
+    /** Regulatory / governance frameworks to align with */
+    frameworks?: string[];
+    /** Human supervision level */
+    humanInTheLoop?: 'always' | 'conditional' | 'advisory' | 'none';
+    /** Enable audit logging */
+    auditLogging?: boolean;
+    /** Retention period for audit records (e.g. 90d) */
+    retentionPeriod?: string;
+}
+/**
+ * Team / agent pack metadata — groups agents into a cohesive named team.
+ * Inspired by CrewClaw's "Agent Packs" concept.
+ *
+ * @deprecated Template metadata should use top-level `title` and `description`.
+ */
+interface TeamConfig {
+    /** Team display name */
+    name: string;
+    /** What this team does — appears in console and CLI output */
+    description?: string;
+    /** Default model applied to agents that don't set `agent.model` */
+    defaultModel?: AgentModel;
+    /** Default compliance policy applied to agents that don't set `agent.compliance` */
+    defaultCompliance?: AgentCompliance;
+}
+/**
+ * K8s resource requests/limits.
+ */
+interface K8sResources {
+    cpu?: string;
+    memory?: string;
+}
+/**
+ * Shared workspace configuration — creates a PersistentVolumeClaim
+ * that is mounted into every agent container, so agents share a
+ * distributed filesystem that OpenClaw can discover.
+ */
+interface SharedWorkspaceConfig {
+    /** Enable shared workspace across agents */
+    enabled: boolean;
+    /** Storage size (e.g. "5Gi") */
+    storageSize?: string;
+    /** Storage class name (empty for cluster default) */
+    storageClassName?: string;
+    /** Mount path inside containers */
+    mountPath?: string;
+    /** Access mode */
+    accessMode?: 'ReadWriteOnce' | 'ReadWriteMany' | 'ReadOnlyMany';
+}
+type CloudWorkloadBackend = 'agent-sandbox' | 'deployment';
+type SandboxBackupDriver = 'volumeSnapshot' | 'restic';
+type SandboxWarmPoolUpdateStrategy = 'OnReplenish' | 'Recreate';
+interface AgentSandboxStateConfig {
+    /** Enable the per-agent OpenClaw state PVC. Defaults to true for agent-sandbox. */
+    enabled?: boolean;
+    /** PVC size for /home/shadow/.openclaw. */
+    size?: string;
+    /** Storage class name (empty for cluster default). */
+    storageClassName?: string;
+    /** Access mode for the state PVC. */
+    accessMode?: 'ReadWriteOnce' | 'ReadWriteMany' | 'ReadOnlyMany';
+}
+interface AgentSandboxLifecycleConfig {
+    /** Enable Cloud-side automatic pause after idleSeconds. */
+    autoPause?: boolean;
+    /** Idle duration before automatic pause. */
+    idleSeconds?: number & tags.Type<'uint32'>;
+    /** Create a backup before pause. */
+    backupBeforePause?: boolean;
+    /** agent-sandbox shutdown policy. */
+    shutdownPolicy?: 'Delete' | 'Retain';
+}
+interface AgentSandboxBackupConfig {
+    /** Enable state backup. */
+    enabled?: boolean;
+    /** Preferred backup driver. */
+    driver?: SandboxBackupDriver;
+    /** Optional schedule expression interpreted by the Cloud control plane. */
+    schedule?: string;
+    /** Number of backups to retain. */
+    retention?: number & tags.Type<'uint32'>;
+}
+interface AgentSandboxWarmPoolConfig {
+    /**
+     * Enable SandboxWarmPool. Disabled by default because current per-agent
+     * Secret/env injection is not compatible with warm-pool adoption.
+     */
+    enabled?: boolean;
+    /** Number of prewarmed sandboxes. */
+    replicas?: number & tags.Type<'uint32'>;
+    /** Warm-pool update strategy. */
+    updateStrategy?: SandboxWarmPoolUpdateStrategy;
+}
+interface AgentSandboxConfig {
+    /** RuntimeClass used by sandbox pods. Defaults to gvisor. */
+    runtimeClassName?: string;
+    /** Per-agent OpenClaw state volume config. */
+    state?: AgentSandboxStateConfig;
+    /** Pause/resume lifecycle config. */
+    lifecycle?: AgentSandboxLifecycleConfig;
+    /** Backup/restore config. */
+    backup?: AgentSandboxBackupConfig;
+    /** Warm pool config. */
+    warmPool?: AgentSandboxWarmPoolConfig;
+}
+/**
+ * Agent-level configuration that can extend a base config.
+ */
+interface AgentConfiguration {
+    /** Base configuration ID to extend from registry.configurations */
+    extends?: string;
+    /**
+     * Model preferences resolved from registry.configurations preset.
+     * Populated after extends resolution; lower priority than agent.model.
+     */
+    model?: AgentModel;
+    /** OpenClaw config overrides (official format) */
+    openclaw?: Partial<OpenClawConfig>;
+    /** Additional pass-through fields */
+    [key: string]: unknown;
+}
+/**
+ * Agent deployment definition.
+ */
+interface AgentDeployment {
+    /** Unique agent ID */
+    id: string;
+    /** Runtime type */
+    runtime: AgentRuntime;
+    /** Custom container image */
+    image?: string;
+    /** Number of replicas */
+    replicas?: number & tags.Minimum<0> & tags.Type<'uint32'>;
+    /** Agent configuration (can extend a base config) */
+    configuration: AgentConfiguration;
+    /** K8s resource constraints */
+    resources?: {
+        requests?: K8sResources;
+        limits?: K8sResources;
+    };
+    /** Extra environment variables */
+    env?: Record<string, string>;
+    /**
+     * Agent identity / soul — who this agent is.
+     * systemPrompt and personality are merged into the OpenClaw system prompt.
+     * Equivalent to SOUL.md in the gitagent standard.
+     */
+    identity?: AgentIdentity;
+    /**
+     * Model preferences — overrides registry and team defaults.
+     * Mirrors gitagent's `model` section: preferred primary + ordered fallbacks.
+     */
+    model?: AgentModel;
+    /**
+     * Compliance/risk policy for this agent.
+     * Falls back to team.defaultCompliance when omitted.
+     */
+    compliance?: AgentCompliance;
+    /**
+     * Deterministic multi-step workflows this agent can run.
+     * Mirrors gitagent's SkillsFlow workflows/*.yaml.
+     */
+    workflows?: AgentWorkflowDef[];
+    /**
+     * Per-agent plugin declarations (webpack-style "use" pattern).
+     * Each entry specifies a plugin and its options.
+     *
+     * @example
+     * [
+     *   { "plugin": "gitagent", "options": { "repo": "github.com/user/repo" } },
+     *   { "plugin": "stripe", "options": { "apiKey": "${vault:STRIPE_KEY}" } }
+     * ]
+     */
+    use?: UseEntry[];
+    /** Short description shown in console and CLI output */
+    description?: string;
+    /**
+     * Agent source overlay — pulls files from a git repository or local path
+     * into the container using the gitagent directory convention.
+     *
+     * When set, the agent container will have SOUL.md, RULES.md, skills/,
+     * tools/, hooks/, etc. available at `source.mountPath` (default: /agent).
+     * OpenClaw's agentDir is automatically configured to read from this path.
+     *
+     * Supports two strategies:
+     * - "init-container": Runtime git clone via K8s init container (default)
+     * - "build-image":    Bake files into Docker image layer at build time
+     */
+    source?: AgentSource;
+    /**
+     * Vault reference — which vault to use for this agent's secrets.
+     * Defaults to "default". Each vault generates an isolated K8s Secret.
+     */
+    vault?: string;
+    /**
+     * Per-tool permission policy.
+     * Controls which tools can auto-execute vs. require human approval.
+     * Maps to ACPX permission modes in the generated OpenClaw config.
+     */
+    permissions?: AgentPermissions;
+    /**
+     * Network egress policy for this agent's pods.
+     * Generates a K8s NetworkPolicy resource.
+     */
+    networking?: AgentNetworking;
+    /** agent-sandbox backend options. */
+    sandbox?: AgentSandboxConfig;
+    /**
+     * Agent configuration version (semver).
+     * Recorded in K8s Deployment annotations for rollback tracking.
+     */
+    version?: string;
+    /** Change description for this version (stored in K8s annotations) */
+    changelog?: string;
+}
+/**
+ * Deployments section.
+ */
+interface DeploymentsConfig {
+    /** K8s namespace */
+    namespace?: string;
+    /** Kubernetes workload backend. Defaults to agent-sandbox for new deployments. */
+    backend?: CloudWorkloadBackend;
+    /** Default agent-sandbox options inherited by agents. */
+    sandbox?: AgentSandboxConfig;
+    /** Agent deployments */
+    agents: AgentDeployment[];
+}
+/**
+ * Registry configuration preset.
+ */
+interface Configuration {
+    /** Unique configuration ID */
+    id: string;
+    /**
+     * Base configuration to inherit from.
+     * Resolved recursively — child fields override parent.
+     */
+    extends?: string;
+    /**
+     * Model preset for agents using this configuration.
+     * After extends resolution, merged into AgentConfiguration.model.
+     * Priority: agent.model > configuration.model > team.defaultModel.
+     */
+    model?: AgentModel;
+    /** OpenClaw config values */
+    openclaw?: Partial<OpenClawConfig>;
+    /** Additional pass-through fields */
+    [key: string]: unknown;
+}
+/**
+ * Registry section — reusable model provider, configuration presets, and vault definitions.
+ */
+interface RegistryConfig {
+    /** Custom LLM provider configurations */
+    providers?: OpenClawProviderConfig[];
+    /** Reusable configuration presets */
+    configurations?: Configuration[];
+    /**
+     * Vault definitions for secret isolation.
+     * Each agent references a vault by name (default: "default").
+     * Per-agent K8s Secrets are generated with only the relevant keys.
+     */
+    vaults?: Record<string, VaultConfig>;
+}
+/**
+ * Cloud-level skill entry — specifies a skill to load
+ * from a registry or directory into the agent containers.
+ */
+interface CloudSkillEntry {
+    /** Skill identifier (npm package name or local directory name) */
+    name: string;
+    /** Skill source: "bundled" (built-in), "npm" (install from registry), or "path" (local directory) */
+    source?: 'bundled' | 'npm' | 'path';
+    /** For npm: package version. For path: directory on the host. */
+    version?: string;
+    /** For path source: the local directory path */
+    path?: string;
+    /** Whether skill is enabled */
+    enabled?: boolean;
+    /** Environment variables for this skill */
+    env?: Record<string, string>;
+    /** API key for this skill */
+    apiKey?: string;
+}
+/**
+ * Cloud-level skills configuration — manages skill installation
+ * and distribution across agent containers.
+ */
+interface CloudSkillsConfig {
+    /** Directory inside the container where skills are installed */
+    installDir?: string;
+    /** Skills to distribute to agents */
+    entries?: CloudSkillEntry[];
+}
+
+/**
+ * Top-level CloudConfig — the root shadowob-cloud.json schema.
+ */
+
+/**
+ * Plugin instance config (legacy map form).
+ * Kept for backward compatibility with existing templates and builder logic.
+ */
+interface CloudPluginInstanceConfig {
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+    agents?: Record<string, {
+        enabled?: boolean;
+        config?: Record<string, unknown>;
+    }>;
+    secrets?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Top-level shadowob-cloud.json config.
+ *
+ * @title Shadow Cloud Configuration
+ * @description Configuration file for deploying OpenClaw AI agents to Kubernetes.
+ */
+interface CloudConfig {
+    /** Config version */
+    version: string;
+    /** Stable kebab-case config/template slug */
+    name?: string;
+    /** Human-readable title for this deployment config (shown in console) */
+    title?: string;
+    /** Description of the customer value this agent team provides */
+    description?: string;
+    /** Deployment environment */
+    environment?: 'development' | 'staging' | 'production';
+    /** Active locale for i18n resolution (e.g. "en", "zh-CN"). Defaults to "en". */
+    locale?: string;
+    /**
+     * Internationalization dictionary.
+     * Keyed by locale → key → translated string.
+     *
+     * Template strings can reference translations via `${i18n:key}`.
+     * The active locale is determined by `config.locale`.
+     *
+     * @example
+     * {
+     *   "en": { "title": "Research Team", "description": "AI research agents" },
+     *   "zh-CN": { "title": "研究团队", "description": "AI 研究 Agent 集群" }
+     * }
+     */
+    i18n?: Record<string, Record<string, string>>;
+    /**
+     * Team / agent pack definition.
+     * Groups agents with shared defaults.
+     *
+     * @deprecated Template metadata should use top-level `title` and `description`.
+     */
+    team?: TeamConfig;
+    /**
+     * Global plugin declarations — webpack-style "use" pattern.
+     * Each entry specifies a plugin id and optional configuration.
+     *
+     * @example
+     * [
+     *   { "plugin": "shadowob", "options": { "baseURL": "${env:SHADOWOB_BASE_URL}" } },
+     *   { "plugin": "slack", "options": { "token": "${vault:SLACK_TOKEN}" } }
+     * ]
+     */
+    use?: UseEntry[];
+    /**
+     * Legacy plugin declarations map.
+     * Prefer `use`, but keep this field for compatibility during migration.
+     */
+    plugins?: Record<string, CloudPluginInstanceConfig>;
+    /**
+     * Reusable provider/configuration registry.
+     * Also contains vault definitions (registry.vaults) for secret isolation.
+     */
+    registry?: RegistryConfig;
+    /** K8s deployment definitions */
+    deployments?: DeploymentsConfig;
+    /** Shared workspace (distributed filesystem across agents) */
+    workspace?: SharedWorkspaceConfig;
+    /** Cloud-level skills registry */
+    skills?: CloudSkillsConfig;
+}
+
+/**
+ * Core plugin system types — ModernJS-style setup(api) pattern.
+ *
+ * Every plugin calls definePlugin(manifest, setup) and exports the result.
+ *
+ * The setup function receives a PluginAPI object and registers hooks + capabilities
+ * imperatively. This keeps all plugin logic in a single closure, enables conditional
+ * hook registration, and makes plugin options natural via closure capture.
+ *
+ * @example
+ * // Skill plugin with custom health check
+ * export default definePlugin(manifest, (api) => {
+ *   api.addSkills({ bundled: ['github'] })
+ *   api.addCLI([{ name: 'gh', command: 'gh', description: 'GitHub CLI' }])
+ *   api.onBuildEnv((ctx) => ({ GITHUB_TOKEN: ctx.secrets.GITHUB_TOKEN }))
+ *   api.onHealthCheck(async (ctx) => ({ healthy: true, message: 'OK' }))
+ * })
+ *
+ * @example
+ * // Channel plugin with provision lifecycle
+ * export default definePlugin(manifest, (api) => {
+ *   api.onBuildConfig(buildSlackConfig)
+ *   api.onProvision(async (ctx) => { ... })
+ *   api.onHealthCheck(async (ctx) => { ... })
+ * })
+ *
+ * @example
+ * // Use factory shorthand for standard patterns
+ * export default defineSkillPlugin(manifest, {
+ *   skills: { bundled: ['github'], entries: [...] },
+ *   cli: [{ name: 'gh', command: 'gh', description: 'GitHub CLI' }],
+ * })
+ */
+
+type PluginCategory = 'communication' | 'project-management' | 'ai-provider' | 'devops' | 'database' | 'productivity' | 'automation' | 'crm' | 'finance' | 'analytics' | 'media' | 'email' | 'calendar' | 'search' | 'code' | 'other';
+type PluginCapability = 'channel' | 'tool' | 'notification' | 'webhook' | 'data-source' | 'action' | 'auth-provider' | 'skill' | 'cli' | 'mcp' | 'config-builder' | 'config-resolver';
+type PluginAuthType = 'oauth2' | 'api-key' | 'token' | 'basic' | 'none';
+interface PluginAuthField {
+    key: string;
+    label: string;
+    description?: string;
+    required: boolean;
+    sensitive: boolean;
+    placeholder?: string;
+    validation?: string;
+    helpUrl?: string;
+}
+interface PluginOAuthConfig {
+    authorizationUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    pkce?: boolean;
+}
+interface PluginAuth {
+    type: PluginAuthType;
+    fields: PluginAuthField[];
+    oauth?: PluginOAuthConfig;
+}
+interface PluginManifest {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    category: PluginCategory;
+    icon: string;
+    website?: string;
+    docs?: string;
+    auth: PluginAuth;
+    config?: Record<string, unknown>;
+    capabilities: PluginCapability[];
+    tags: string[];
+    popularity?: number;
+}
+type PluginMCPTransport = 'stdio' | 'sse' | 'http' | 'streamable-http';
+/** MCP server config (prefer skills+cli for most integrations). */
+interface PluginMCPServer {
+    id?: string;
+    transport: PluginMCPTransport;
+    /** Command used by stdio MCP servers. */
+    command?: string;
+    args?: string[];
+    /** URL used by remote HTTP, streamable HTTP, or SSE MCP servers. */
+    url?: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+    description?: string;
+    requiredEnv?: string[];
+    auth?: {
+        type: 'none' | 'bearer' | 'oauth2';
+        tokenEnvKey?: string;
+        scopes?: string[];
+    };
+}
+interface PluginRuntimeDependency {
+    id: string;
+    kind: 'npm-global' | 'system-package' | 'binary' | 'shell';
+    packages?: string[];
+    command?: string[];
+    targetPath?: string;
+    binPath?: string;
+    description?: string;
+}
+interface PluginRuntimeSource {
+    id: string;
+    kind: 'git' | 'local' | 'http-archive';
+    url?: string;
+    ref?: string;
+    from?: string;
+    targetPath: string;
+    include?: string[];
+    includePattern?: string;
+    description?: string;
+}
+type ModelTag = 'default' | 'fast' | 'flash' | 'reasoning' | 'vision' | 'tools';
+interface ProviderModelEntry {
+    /** Model ID within the provider. */
+    id: string;
+    /** Display name. Defaults to id. */
+    name?: string;
+    /** Capability tags used by selector plugins such as model-provider. */
+    tags?: ModelTag[];
+    contextWindow?: number;
+    maxTokens?: number;
+    cost?: {
+        inputPerMillion?: number;
+        outputPerMillion?: number;
+        currency?: string;
+    };
+    capabilities?: {
+        vision?: boolean;
+        tools?: boolean;
+        reasoning?: boolean;
+    };
+}
+interface ProviderCatalog {
+    /** Provider ID used in model refs, e.g. anthropic/claude-sonnet-4-5. */
+    id: string;
+    /** Provider API adapter identifier. */
+    api: string;
+    baseUrl?: string;
+    /** Primary env var used to authenticate this provider. */
+    envKey: string;
+    /** Compatible aliases to sniff before falling back to envKey. */
+    envKeyAliases?: string[];
+    /** Optional base URL override env var. */
+    baseUrlEnvKey?: string;
+    /** Optional default model override env var. */
+    modelEnvKey?: string;
+    /** Lower number means higher selector priority. */
+    priority?: number;
+    /** Enables local env sniffing when no community profile is connected. Defaults to true. */
+    allowEnvDetection?: boolean;
+    models: ProviderModelEntry[];
+}
+interface PluginSecretField {
+    key: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    sensitive?: boolean;
+    placeholder?: string;
+    helpUrl?: string;
+    /** Legacy or compatible env names that should resolve to this canonical field. */
+    aliases?: string[];
+    /** Whether this value must be present in the runtime container env. Defaults to true. */
+    runtime?: boolean;
+}
+interface PluginOpenClawManifestPatch {
+    /** Extension folder under /app/extensions, e.g. "shadowob". */
+    extensionId?: string;
+    /** Absolute manifest path, or path relative to /app. Prefer extensionId. */
+    manifestPath?: string;
+    /** Generic deep-merge patch for manifest fields. */
+    merge?: Record<string, unknown>;
+    channelEnvVars?: Record<string, string[]>;
+    channelConfigs?: Record<string, unknown>;
+}
+type PluginRuntimeArtifactKind = 'shadow.slashCommands' | (string & {});
+interface PluginRuntimeArtifact {
+    /** Stable consumer-facing artifact kind, e.g. "shadow.slashCommands". */
+    kind: PluginRuntimeArtifactKind;
+    /** Runtime-readable absolute path produced by the plugin. */
+    path: string;
+    /** Optional media type or format hint for future consumers. */
+    mediaType?: string;
+}
+interface PluginCredentialFile {
+    /** Env var containing file contents, e.g. GOOGLE_WORKSPACE_CLI_CREDENTIALS_JSON. */
+    envKey: string;
+    /** Absolute path to materialize inside the runtime container. */
+    path: string;
+    /** Octal file mode. Defaults to 0600. */
+    mode?: string;
+}
+interface PluginVerificationCheck {
+    id: string;
+    label: string;
+    kind: 'command' | 'http' | 'mcp-tool';
+    command?: string[];
+    http?: {
+        method?: 'GET' | 'POST';
+        url: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+        expectStatus?: number | number[];
+        expectJsonPath?: string;
+    };
+    mcp?: {
+        serverId: string;
+        toolName: string;
+        args?: unknown;
+    };
+    timeoutMs?: number;
+    risk?: 'safe' | 'read' | 'write';
+    /** All listed env vars must be present before running this check. */
+    requiredEnv?: string[];
+    /** At least one listed env var must be present before running this check. */
+    requiredEnvAny?: string[];
+    cleanup?: PluginVerificationCheck;
+}
+interface PluginShadowobRuntimeAccount {
+    buddyId: string;
+    buddyName?: string;
+    buddyDescription?: string;
+    tokenEnvKey: string;
+    replyPolicy?: {
+        mode: string;
+        custom?: Record<string, unknown>;
+    };
+}
+interface PluginShadowobRuntime {
+    enabled: boolean;
+    serverUrlEnvKey: string;
+    accounts: PluginShadowobRuntimeAccount[];
+    defaultAccountEnvKey?: string;
+    capabilities?: Record<string, unknown>;
+}
+interface PluginRuntimeExtension {
+    openclaw?: {
+        manifestPatches?: PluginOpenClawManifestPatch[];
+    };
+    shadowob?: PluginShadowobRuntime;
+    artifacts?: PluginRuntimeArtifact[];
+    runtimeDependencies?: PluginRuntimeDependency[];
+    skillSources?: PluginRuntimeSource[];
+    subagentSources?: PluginRuntimeSource[];
+    mcpServers?: PluginMCPServer[];
+    credentialFiles?: PluginCredentialFile[];
+    verificationChecks?: PluginVerificationCheck[];
+}
+
+interface PluginCatalogEntry {
+    id: string;
+    name: string;
+    description: string;
+    category: PluginCategory;
+    capabilities: PluginCapability[];
+    tags: string[];
+    authType: PluginManifest['auth']['type'];
+    requiredFields: Array<{
+        key: string;
+        label: string;
+        description?: string;
+        sensitive: boolean;
+    }>;
+}
+declare function listPluginCatalogs(): PluginCatalogEntry[];
+
+interface PluginLibraryEntry {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    category: PluginCategory;
+    capabilities: PluginCapability[];
+    tags: string[];
+    authType: PluginManifest['auth']['type'];
+    website?: string;
+    docs?: string;
+    popularity?: number;
+    manifest: PluginManifest;
+    requiredFields: Array<{
+        key: string;
+        label: string;
+        description?: string;
+        sensitive: boolean;
+    }>;
+    readme: {
+        title: string;
+        excerpt: string;
+        headings: string[];
+    };
+    searchText: string;
+}
+interface PluginLibrarySearchResult extends PluginLibraryEntry {
+    score: number;
+    matchedTerms: string[];
+}
+declare function listPluginLibrary(): PluginLibraryEntry[];
+declare function searchPluginLibrary(query: string, options?: {
+    limit?: number;
+    includeIds?: string[];
+}): PluginLibrarySearchResult[];
+declare function getPluginLibraryEntry(id: string): PluginLibraryEntry | undefined;
+
+interface ProviderCatalogEntry {
+    pluginId: string;
+    pluginName: string;
+    provider: ProviderCatalog;
+    secretFields: PluginSecretField[];
+}
+declare function listProviderCatalogs(): Promise<ProviderCatalogEntry[]>;
+
+interface RuntimeEnvField {
+    key: string;
+    label: string;
+    description?: string;
+    required: boolean;
+    sensitive: boolean;
+    placeholder?: string;
+    source: 'template' | 'plugin';
+    sourceId: string;
+    sourceLabel: string;
+    helpUrl?: string;
+}
+interface RuntimeEnvRefPolicy {
+    /** Env ref aliases that should be satisfied by a canonical field. */
+    aliases: Record<string, string>;
+    /** Env refs intentionally ignored by active plugins. */
+    ignoredKeys: string[];
+    /** Env refs that should not be exposed as standalone deploy fields. */
+    hiddenKeys: string[];
+}
+/**
+ * Collect runtime env keys a SaaS deployment may need from the plugin graph.
+ *
+ * This intentionally returns key names only. Values still come from the user's
+ * encrypted Cloud env store, explicit deploy input, or local process.env fallback.
+ */
+declare function collectRuntimeEnvRequirements(configSnapshot: unknown): Promise<string[]>;
+declare function collectRuntimeEnvRefPolicy(configSnapshot: unknown): Promise<RuntimeEnvRefPolicy>;
+declare function applyRuntimeEnvRefPolicy(envVars: Record<string, string>, policy: Pick<RuntimeEnvRefPolicy, 'aliases' | 'ignoredKeys'>): Record<string, string>;
+/**
+ * Collect user-fillable runtime env slots for the deploy UI.
+ *
+ * This includes direct `${env:VAR}` template references plus fields declared by
+ * plugins used by the template. The richer metadata lets Cloud render labels,
+ * descriptions, sensitivity, required state, and placeholders without
+ * hardcoding per-plugin forms.
+ */
+declare function collectRuntimeEnvFields(configSnapshot: unknown): Promise<RuntimeEnvField[]>;
+
+interface TemplateEnvRefPolicy {
+    aliases?: Record<string, string>;
+    ignoredKeys?: string[];
+}
+declare function extractRequiredEnvVars(config: unknown, policy?: TemplateEnvRefPolicy): string[];
+
+interface TemplateLibraryEntry {
+    slug: string;
+    title: string;
+    description: string;
+    category: string;
+    plugins: string[];
+    channels: string[];
+    buddyNames: string[];
+    agentCount: number;
+    systemPromptExcerpt: string;
+    valid: boolean;
+    validation: CloudConfigValidationSummary;
+    searchText: string;
+}
+interface TemplateLibrarySearchResult extends TemplateLibraryEntry {
+    score: number;
+    matchedTerms: string[];
+}
+declare function listTemplateLibrary(): TemplateLibraryEntry[];
+declare function searchTemplateLibrary(query: string, options?: {
+    limit?: number;
+}): TemplateLibrarySearchResult[];
+
+type BillingUnit = 'usd' | 'shrimp';
+interface ProviderUsageSummary {
+    provider: string;
+    amountUsd: number | null;
+    usageLabel: string | null;
+    raw: string | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+}
+interface AgentCostSummary {
+    agentName: string;
+    podName: string | null;
+    totalUsd: number | null;
+    billingAmount: number | null;
+    billingUnit: BillingUnit;
+    totalTokens: number | null;
+    providers: ProviderUsageSummary[];
+    source: 'json' | 'text' | 'telemetry' | 'unavailable';
+    message: string | null;
+}
+interface NamespaceCostSummary {
+    namespace: string;
+    totalUsd: number | null;
+    billingAmount: number | null;
+    billingUnit: BillingUnit;
+    totalTokens: number | null;
+    agents: AgentCostSummary[];
+    availableAgents: number;
+    unavailableAgents: number;
+    generatedAt: string;
+}
+interface CostOverviewSummary {
+    totalUsd: number | null;
+    billingAmount: number | null;
+    billingUnit: BillingUnit;
+    totalTokens: number | null;
+    namespaces: Array<{
+        namespace: string;
+        totalUsd: number | null;
+        billingAmount: number | null;
+        billingUnit: BillingUnit;
+        totalTokens: number | null;
+        agentCount: number;
+        availableAgents: number;
+        unavailableAgents: number;
+    }>;
+    generatedAt: string;
+}
+interface UsageCostPodSummary {
+    name: string;
+    status: string;
+    age: string;
+}
+interface UsageCostExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface UsageCostRuntime {
+    listPods(namespace: string, kubeconfig?: string): UsageCostPodSummary[];
+    execInPod(opts: {
+        namespace: string;
+        pod: string;
+        command: string[];
+        kubeconfig?: string;
+        timeout?: number;
+    }): UsageCostExecResult;
+}
+interface ParsedUsageSnapshot {
+    totalUsd: number | null;
+    totalTokens: number | null;
+    providers: ProviderUsageSummary[];
+    source: 'json' | 'text';
+}
+declare const OPENCLAW_USAGE_COMMANDS: string[][];
+declare function parseOpenClawUsageOutput(stdout: string, stderr?: string): ParsedUsageSnapshot | null;
+declare function collectAgentUsage(opts: {
+    namespace: string;
+    agentName: string;
+    runtime: UsageCostRuntime;
+    kubeconfig?: string;
+}): Omit<AgentCostSummary, 'billingAmount' | 'billingUnit'>;
+declare function collectNamespaceCost(opts: {
+    namespace: string;
+    agentNames: string[];
+    billingAmount: number | null;
+    billingUnit: BillingUnit;
+    runtime: UsageCostRuntime;
+    kubeconfig?: string;
+}): NamespaceCostSummary;
+declare function summarizeCostOverview(summaries: NamespaceCostSummary[], billingUnit: BillingUnit): CostOverviewSummary;
+
+/**
+ * Runtime kubectl helper set used by SaaS orchestration and APIs.
+ *
+ * This module supports both explicit kubeconfig content and ambient kubeconfig
+ * discovery from process env / local defaults. It also rewrites localhost
+ * kubeconfig endpoints for containerized runtime access where needed.
+ */
+
+interface K8sPodSummary {
+    name: string;
+    ready: string;
+    status: string;
+    restarts: number;
+    age: string;
+    containers: string[];
+}
+interface K8sExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+type AgentSandboxRuntimeState = 'running' | 'paused' | 'resuming' | 'failed' | 'unknown';
+interface AgentSandboxStatus {
+    name: string;
+    sandboxName: string;
+    replicas: number;
+    ready: boolean;
+    runtimeState: AgentSandboxRuntimeState;
+}
+interface VolumeSnapshotReadyStatus {
+    ready: boolean;
+    error?: string;
+}
+declare function resolveSandboxNameAsync(namespace: string, agentName: string, kubeconfig?: string): Promise<string>;
+declare function getAgentSandboxStatusAsync(namespace: string, agentName: string, kubeconfig?: string): Promise<AgentSandboxStatus>;
+declare function scaleAgentSandboxAsync(namespace: string, agentName: string, replicas: 0 | 1, kubeconfig?: string): Promise<void>;
+declare function waitForAgentSandboxReady(options: {
+    namespace: string;
+    agentName: string;
+    kubeconfig?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<AgentSandboxStatus>;
+declare function waitForAgentSandboxPaused(options: {
+    namespace: string;
+    agentName: string;
+    kubeconfig?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<AgentSandboxStatus>;
+declare function createVolumeSnapshotBackupAsync(options: {
+    namespace: string;
+    snapshotName: string;
+    pvcName: string;
+    volumeSnapshotClassName?: string;
+    kubeconfig?: string;
+}): Promise<void>;
+declare function isVolumeSnapshotApiAvailable(options?: {
+    kubeconfig?: string;
+}): Promise<boolean>;
+type PvcVolumeSnapshotCapability = {
+    storageClassName: string | null;
+    provisioner: string | null;
+    isCsi: boolean;
+    volumeSnapshotClassName: string | null;
+};
+declare function isPvcBackedByCsiProvisioner(options: {
+    namespace: string;
+    pvcName: string;
+    kubeconfig?: string;
+}): Promise<boolean>;
+declare function getPvcVolumeSnapshotCapability(options: {
+    namespace: string;
+    pvcName: string;
+    kubeconfig?: string;
+}): Promise<PvcVolumeSnapshotCapability>;
+declare function resolveVolumeSnapshotClassForPvc(options: {
+    namespace: string;
+    pvcName: string;
+    kubeconfig?: string;
+}): Promise<string | null>;
+declare function getVolumeSnapshotReadyStatus(options: {
+    namespace: string;
+    snapshotName: string;
+    kubeconfig?: string;
+}): Promise<VolumeSnapshotReadyStatus>;
+declare function waitForVolumeSnapshotReady(options: {
+    namespace: string;
+    snapshotName: string;
+    kubeconfig?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<VolumeSnapshotReadyStatus>;
+declare function restorePvcFromVolumeSnapshot(options: {
+    namespace: string;
+    pvcName: string;
+    snapshotName: string;
+    kubeconfig?: string;
+    accessModes?: string[];
+    storage?: string;
+    storageClassName?: string;
+    timeoutMs?: number;
+}): Promise<void>;
+declare function listPods(namespace: string, kubeconfig?: string): K8sPodSummary[];
+declare function listPodsAsync(namespace: string, kubeconfig?: string): Promise<K8sPodSummary[]>;
+declare function spawnPodLogStream(opts: {
+    namespace: string;
+    pod: string;
+    container?: string;
+    follow?: boolean;
+    tail?: number;
+    kubeconfig?: string;
+}): {
+    proc: ReturnType<typeof spawn>;
+    cleanup: () => void;
+};
+declare function readPodLogs(opts: {
+    namespace: string;
+    pod: string;
+    container?: string;
+    tail?: number;
+    timestamps?: boolean;
+    kubeconfig?: string;
+    timeout?: number;
+}): string;
+declare function readPodLogsAsync(opts: {
+    namespace: string;
+    pod: string;
+    container?: string;
+    tail?: number;
+    timestamps?: boolean;
+    kubeconfig?: string;
+    timeout?: number;
+}): Promise<string>;
+declare function execInPod(opts: {
+    namespace: string;
+    pod: string;
+    command: string[];
+    container?: string;
+    kubeconfig?: string;
+    timeout?: number;
+}): K8sExecResult;
+declare function execInPodAsync(opts: {
+    namespace: string;
+    pod: string;
+    command: string[];
+    container?: string;
+    kubeconfig?: string;
+    timeout?: number;
+}): Promise<K8sExecResult>;
+declare function execInPodWithInputAsync(opts: {
+    namespace: string;
+    pod: string;
+    command: string[];
+    input: Buffer | string;
+    container?: string;
+    kubeconfig?: string;
+    timeout?: number;
+}): Promise<K8sExecResult>;
+declare function applyKubernetesManifestAsync(manifest: Record<string, unknown>, kubeconfig?: string, timeout?: number): Promise<void>;
+declare function deleteKubernetesResourceAsync(options: {
+    namespace: string;
+    kind: string;
+    name: string;
+    kubeconfig?: string;
+    timeoutMs?: number;
+}): Promise<void>;
+declare function waitForPodReadyAsync(options: {
+    namespace: string;
+    pod: string;
+    kubeconfig?: string;
+    timeoutMs?: number;
+}): Promise<void>;
+declare function listManagedNamespaces(kubeconfig?: string): string[] | null;
+declare function namespaceExists(namespace: string, kubeconfig?: string): boolean | null;
+declare function deleteNamespace(namespace: string, kubeconfig?: string): void;
+
+/**
+ * Cluster config schema — defines the shape of cluster.json.
+ *
+ * cluster.json describes bare servers to bootstrap into a k3s cluster.
+ * Credentials use ${env:VAR} template syntax so secrets are never stored on disk.
+ */
+
+declare const NodeConfigSchema: z.ZodEffects<z.ZodObject<{
+    /** Node role in the cluster */
+    role: z.ZodEnum<["master", "worker"]>;
+    /** Public IP or hostname */
+    host: z.ZodString;
+    /** SSH port (default: 22) */
+    port: z.ZodDefault<z.ZodNumber>;
+    /** SSH username */
+    user: z.ZodString;
+    /** Path to SSH private key (supports ~) — mutually inclusive with or exclusive of password */
+    sshKeyPath: z.ZodOptional<z.ZodString>;
+    /** SSH password — use ${env:VAR} to avoid storing plaintext */
+    password: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    host: string;
+    port: number;
+    user: string;
+    role: "master" | "worker";
+    password?: string | undefined;
+    sshKeyPath?: string | undefined;
+}, {
+    host: string;
+    user: string;
+    role: "master" | "worker";
+    password?: string | undefined;
+    port?: number | undefined;
+    sshKeyPath?: string | undefined;
+}>, {
+    host: string;
+    port: number;
+    user: string;
+    role: "master" | "worker";
+    password?: string | undefined;
+    sshKeyPath?: string | undefined;
+}, {
+    host: string;
+    user: string;
+    role: "master" | "worker";
+    password?: string | undefined;
+    port?: number | undefined;
+    sshKeyPath?: string | undefined;
+}>;
+type NodeConfig = z.infer<typeof NodeConfigSchema>;
+declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    /** Cluster name — used as --cluster value */
+    name: z.ZodString;
+    /** Provider type (default: ssh) */
+    provider: z.ZodDefault<z.ZodEnum<["ssh"]>>;
+    /** List of nodes */
+    nodes: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        /** Node role in the cluster */
+        role: z.ZodEnum<["master", "worker"]>;
+        /** Public IP or hostname */
+        host: z.ZodString;
+        /** SSH port (default: 22) */
+        port: z.ZodDefault<z.ZodNumber>;
+        /** SSH username */
+        user: z.ZodString;
+        /** Path to SSH private key (supports ~) — mutually inclusive with or exclusive of password */
+        sshKeyPath: z.ZodOptional<z.ZodString>;
+        /** SSH password — use ${env:VAR} to avoid storing plaintext */
+        password: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        host: string;
+        port: number;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        sshKeyPath?: string | undefined;
+    }, {
+        host: string;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        port?: number | undefined;
+        sshKeyPath?: string | undefined;
+    }>, {
+        host: string;
+        port: number;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        sshKeyPath?: string | undefined;
+    }, {
+        host: string;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        port?: number | undefined;
+        sshKeyPath?: string | undefined;
+    }>, "many">;
+    /** Optional k3s installer settings for restricted networks or pinned versions. */
+    install: z.ZodOptional<z.ZodObject<{
+        /** k3s release version. Example: v1.35.4+k3s1 */
+        k3sVersion: z.ZodOptional<z.ZodString>;
+        /** k3s release channel used when k3sVersion is omitted. */
+        k3sChannel: z.ZodOptional<z.ZodString>;
+        /** k3s channel endpoint used by the official install script. */
+        k3sChannelUrl: z.ZodOptional<z.ZodString>;
+        /** k3s release artifact URL prefix. */
+        k3sArtifactUrl: z.ZodOptional<z.ZodString>;
+        /** Common mirror shortcut. "cn" maps to Rancher's China mirror. */
+        k3sMirror: z.ZodOptional<z.ZodString>;
+        /** Registry prefix used by k3s for bundled system images. */
+        systemDefaultRegistry: z.ZodOptional<z.ZodString>;
+        /** Sandbox pause image used by k3s/containerd. Useful when Docker Hub is unreachable. */
+        pauseImage: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+    }, {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    provider: "ssh";
+    nodes: {
+        host: string;
+        port: number;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        sshKeyPath?: string | undefined;
+    }[];
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+}, {
+    name: string;
+    nodes: {
+        host: string;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        port?: number | undefined;
+        sshKeyPath?: string | undefined;
+    }[];
+    provider?: "ssh" | undefined;
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+}>, {
+    name: string;
+    provider: "ssh";
+    nodes: {
+        host: string;
+        port: number;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        sshKeyPath?: string | undefined;
+    }[];
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+}, {
+    name: string;
+    nodes: {
+        host: string;
+        user: string;
+        role: "master" | "worker";
+        password?: string | undefined;
+        port?: number | undefined;
+        sshKeyPath?: string | undefined;
+    }[];
+    provider?: "ssh" | undefined;
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+}>;
+type ClusterConfig = z.infer<typeof ClusterConfigSchema>;
+/** Persisted to ~/.shadow-cloud/clusters/<name>.json after successful init */
+interface ClusterMeta {
+    name: string;
+    masterHost: string;
+    nodeCount: number;
+    createdAt: string;
+    kubeconfigPath: string;
+}
+
+/**
+ * Kubeconfig management — store and retrieve kubeconfigs for registered clusters.
+ *
+ * Kubeconfigs are stored at ~/.shadow-cloud/clusters/<name>.yaml
+ * Metadata is stored at ~/.shadow-cloud/clusters/<name>.json
+ */
+
+/**
+ * Load the kubeconfig path for a named cluster.
+ * Throws if the cluster is not registered.
+ */
+declare function loadKubeconfigPath(clusterName: string): string;
+
+/**
+ * Cluster config parser — read, validate, and resolve cluster.json.
+ *
+ * Supports ${env:VAR} template syntax in password fields.
+ */
+
+/**
+ * Read and validate cluster.json from the given path.
+ * Performs schema validation but does NOT resolve env vars yet
+ * (credentials are resolved lazily at connection time via resolveNodeCredentials).
+ */
+declare function readClusterConfig(filePath: string): ClusterConfig;
+
+type NamedEnvVar = {
+    name?: unknown;
+};
+declare const RESERVED_RUNTIME_ENV_KEYS: Set<string>;
+declare function isReservedRuntimeEnvKey(key: string): boolean;
+declare function assertNoReservedEnvOverrides<T extends NamedEnvVar>(baseEnvVars: T[], candidateEnvVars: T[], source: string): void;
+
+/**
+ * Logger interface — used by service layer for dependency injection.
+ * Services depend on this interface, not the concrete implementation.
+ */
+interface Logger {
+    info(msg: string): void;
+    success(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    step(msg: string): void;
+    dim(msg: string): void;
+    table(rows: Array<Record<string, string>>): void;
+}
+
+/**
+ * Cluster status — check SSH connectivity and k3s service state for each node.
+ */
+
+interface NodeStatus {
+    host: string;
+    role: NodeConfig['role'];
+    reachable: boolean;
+    k3sRunning?: boolean;
+    k3sVersion?: string;
+    error?: string;
+}
+interface ClusterStatus {
+    clusterName: string;
+    nodes: NodeStatus[];
+}
+
+/**
+ * ClusterService — orchestrates cluster lifecycle operations.
+ *
+ * Thin service layer that delegates to cluster/* modules.
+ * Registered in the ServiceContainer for CLI command use.
+ */
+
+declare class ClusterService {
+    /**
+     * Bootstrap a k3s cluster on bare servers.
+     */
+    init(config: ClusterConfig, onLog?: (msg: string) => void, force?: boolean): Promise<ClusterMeta>;
+    /**
+     * Check SSH connectivity and k3s status on all nodes.
+     */
+    status(config: ClusterConfig): Promise<ClusterStatus>;
+    /**
+     * Uninstall k3s from all nodes and clean up local files.
+     */
+    destroy(config: ClusterConfig, onLog?: (msg: string) => void): Promise<void>;
+    /**
+     * List all clusters with stored kubeconfigs.
+     */
+    listClusters(): ClusterMeta[];
+    /**
+     * Resolve the kubeconfig file path for a named cluster.
+     * Throws if the cluster is not registered.
+     */
+    resolveKubeconfig(clusterName: string): string;
+}
+
+type RuntimeKind = 'openclaw' | 'cc-connect' | 'hermes';
+type RuntimeEnv = Record<string, string | undefined>;
+interface RuntimePackageBuildContext {
+    agent: AgentDeployment;
+    config: CloudConfig;
+    cwd?: string;
+    runtimeEnv: RuntimeEnv;
+    runtimeExtensions: PluginRuntimeExtension;
+    runtimeContext?: DeploymentRuntimeContext;
+}
+interface RuntimePackageBuildResult {
+    openclawConfig?: OpenClawConfig;
+    configData: Record<string, string>;
+    pluginResources: Record<string, unknown>[];
+    provisionSecrets?: Record<string, string>;
+}
+interface RuntimeContainerSpec {
+    homeDir: string;
+    healthPort: number;
+    statePath: string;
+    logPath: string;
+    env: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Runtime adapter interface — one per supported runtime type. Package generation
+ * lives with the concrete runtime so the shared infra layer does not know native
+ * config details for Claude, Codex, OpenCode, Gemini, Hermes, or OpenClaw.
+ */
+interface RuntimeAdapter {
+    /** Runtime identifier (matches AgentRuntime type) */
+    readonly id: AgentRuntime;
+    /** Human-readable name */
+    readonly name: string;
+    /** Native runner package family. */
+    readonly runtimeKind: RuntimeKind;
+    /** Default container image when not overridden by user */
+    readonly defaultImage: string;
+    /** Kubernetes/container layout for this runtime. */
+    readonly container: RuntimeContainerSpec;
+    /** Build the runtime's ConfigMap payload and plugin resource artifacts. */
+    buildPackage(context: RuntimePackageBuildContext): RuntimePackageBuildResult;
+}
+
+/**
+ * Template engine — resolves ${env:VAR}, ${secret:NAME}, ${file:PATH},
+ * ${vault:KEY}, ${config:path.to.value}, and ${i18n:key} in config values.
+ */
+interface TemplateContext {
+    /** Environment variables (defaults to process.env) */
+    env?: Record<string, string | undefined>;
+    /** Pre-loaded secret values */
+    secrets?: Record<string, string>;
+    /** Vault secret values — resolved from registry.vaults */
+    vaultSecrets?: Record<string, string>;
+    /** The full config object (for ${config:path} resolution) */
+    configRoot?: Record<string, unknown>;
+    /** i18n dictionary for the active locale */
+    i18nDict?: Record<string, string>;
+}
+
+/**
+ * Config parser — reads shadowob-cloud.json, validates with typia,
+ * expands 'extends' references, resolves template variables,
+ * and builds official OpenClaw config format.
+ */
+
+/**
+ * Expand the 'extends' field in an agent configuration by merging
+ * with the referenced base configuration from registry.configurations.
+ * Supports chained Configuration extends (Configuration → Configuration).
+ */
+declare function expandExtends(agentConfig: AgentConfiguration, configurations: Configuration[]): AgentConfiguration;
+
+/**
+ * Config security — inline key detection and validation.
+ *
+ * Scans shadowob-cloud.json for hardcoded API keys that should use
+ * ${env:...} or ${secret:...} template references instead.
+ */
+interface SecurityViolation {
+    path: string;
+    value: string;
+    prefix: string;
+    message: string;
+}
+
+declare class ConfigService {
+    /** Parse and validate a cloud config file using typia. */
+    parseFile(filePath: string): Promise<CloudConfig>;
+    /** Expand 'extends' references and resolve template variables. */
+    resolve(config: CloudConfig, cwd?: string, templateCtx?: TemplateContext): Promise<CloudConfig>;
+    /** Build OpenClaw config for a specific agent. */
+    buildOpenClawConfig(agent: AgentDeployment, config: CloudConfig, cwd?: string, env?: Record<string, string | undefined>, runtimeContext?: DeploymentRuntimeContext): OpenClawConfig;
+    /**
+     * Full validation: parse + security check + collect template refs.
+     * Returns the parsed config and any security violations found.
+     */
+    validate(filePath: string): Promise<{
+        config: CloudConfig;
+        violations: SecurityViolation[];
+    }>;
+    /**
+     * Parse, validate, and resolve in one call.
+     * Convenience for callers that need the final resolved config.
+     */
+    resolveFromFile(filePath: string, templateCtx?: TemplateContext): Promise<CloudConfig>;
+    /** Detect inline API keys in config (SEC-01). */
+    validateSecurity(config: CloudConfig): SecurityViolation[];
+    /** Collect all ${env:...} and ${secret:...} references. */
+    collectTemplateRefs(config: CloudConfig): {
+        type: "env" | "secret" | "file" | "vault" | "config";
+        key: string;
+        raw: string;
+    }[];
+    /** Deep merge two objects (arrays replaced, not merged). */
+    deepMerge<T extends Record<string, unknown>>(base: T, override: Partial<T>): T;
+    /** Expand 'extends' in an agent configuration. */
+    expandExtends(agentConfig: Parameters<typeof expandExtends>[0], configs: Configuration[]): AgentConfiguration;
+}
+
+/**
+ * kubectl operational commands — deployments, pods, logs, scaling.
+ *
+ * All functions shell out to `kubectl` for runtime cluster operations
+ * (as opposed to Pulumi which handles declarative infrastructure).
+ */
+
+interface PodStatus {
+    name: string;
+    ready: string;
+    status: string;
+    restarts: string;
+    age: string;
+}
+interface DeploymentStatus {
+    name: string;
+    ready: string;
+    upToDate: string;
+    available: string;
+    age: string;
+    workloadKind?: 'deployment' | 'agent-sandbox';
+    runtimeState?: 'running' | 'paused' | 'resuming' | 'failed' | 'unknown';
+    sandboxName?: string;
+    serviceFQDN?: string;
+    statePvc?: string;
+    pausedAt?: string;
+    lastActiveAt?: string;
+}
+interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+
+/**
+ * Pulumi automation API client — stack lifecycle management.
+ *
+ * Uses Pulumi's programmatic automation API for creating, deploying,
+ * and destroying K8s stacks without requiring the Pulumi CLI.
+ */
+
+interface StackOptions {
+    projectName?: string;
+    stackName: string;
+    config: CloudConfig;
+    namespace: string;
+    shadowServerUrl?: string;
+    /** Per-deployment runtime env resolved from SaaS/user input. */
+    runtimeEnvVars?: Record<string, string>;
+    /** Browser/deployment locale and timezone context. */
+    runtimeContext?: DeploymentRuntimeContext;
+    /** Directory to store Pulumi local state — defaults to ~/.shadowob/pulumi */
+    stateDir?: string;
+    /** kubectl context for K8s provider */
+    kubeContext?: string;
+    /** Path to a kubeconfig YAML file — takes precedence over kubeContext when set */
+    kubeConfigPath?: string;
+    /** Image pull policy for containers */
+    imagePullPolicy?: 'Always' | 'IfNotPresent' | 'Never';
+}
+/**
+ * Create or select a Pulumi stack for shadowob-cloud deployments.
+ * Uses a local file backend by default for reproducible, offline operation.
+ */
+declare function getOrCreateStack(options: StackOptions): Promise<automation.Stack>;
+
+declare class K8sService {
+    /**
+     * Deploy config to K8s in one call: create stack + deploy.
+     * Returns stack outputs on success.
+     */
+    deploy(options: StackOptions & {
+        dryRun?: boolean;
+        onOutput?: (out: string) => void;
+    }): Promise<_pulumi_pulumi_automation_stack_js.OutputMap>;
+    /**
+     * Setup a local kind cluster, creating it if needed.
+     * Optionally loads an image into the cluster.
+     */
+    setupLocalCluster(imageName?: string): void;
+    getOrCreateStack(options: StackOptions): Promise<_pulumi_pulumi_automation_stack_js.Stack>;
+    deployStack(stack: Awaited<ReturnType<typeof getOrCreateStack>>, options?: {
+        dryRun?: boolean;
+        onOutput?: (out: string) => void;
+    }): Promise<_pulumi_pulumi_automation_stack_js.PreviewResult | _pulumi_pulumi_automation_stack_js.UpResult>;
+    destroyStack(stack: Awaited<ReturnType<typeof getOrCreateStack>>, options?: {
+        onOutput?: (out: string) => void;
+    }): Promise<_pulumi_pulumi_automation_stack_js.DestroyResult>;
+    getStackOutputs(stack: Awaited<ReturnType<typeof getOrCreateStack>>): Promise<_pulumi_pulumi_automation_stack_js.OutputMap>;
+    getDeployments(namespace: string): DeploymentStatus[];
+    getPods(namespace: string): PodStatus[];
+    streamLogs(namespace: string, podName: string, options?: {
+        follow?: boolean;
+        tail?: number;
+    }): ChildProcess;
+    readLogs(namespace: string, podName: string, options?: {
+        tail?: number;
+        timestamps?: boolean;
+    }): string;
+    execInPod(namespace: string, podName: string, command: string[], options?: {
+        timeout?: number;
+    }): CommandResult;
+    scaleDeployment(namespace: string, name: string, replicas: number): void;
+    scaleAgentSandbox(namespace: string, name: string, replicas: number): void;
+    pauseAgentSandbox(namespace: string, name: string): void;
+    resumeAgentSandbox(namespace: string, name: string): void;
+    createVolumeSnapshotBackup(options: {
+        namespace: string;
+        snapshotName: string;
+        pvcName: string;
+        volumeSnapshotClassName?: string;
+    }): void;
+    createVolumeSnapshotBackupAndWait(options: {
+        namespace: string;
+        snapshotName: string;
+        pvcName: string;
+        volumeSnapshotClassName?: string;
+        timeoutMs?: number;
+    }): Promise<void>;
+    waitForAgentSandboxReady(options: {
+        namespace: string;
+        agentName: string;
+        kubeconfig?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<AgentSandboxStatus>;
+    waitForAgentSandboxPaused(options: {
+        namespace: string;
+        agentName: string;
+        kubeconfig?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<AgentSandboxStatus>;
+    restorePvcFromVolumeSnapshot(options: {
+        namespace: string;
+        pvcName: string;
+        snapshotName: string;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * List namespaces labeled `managed-by=shadowob-cloud-cli` on the cluster.
+     */
+    getManagedNamespaces(): string[];
+    /**
+     * Delete a namespace and all its resources.
+     */
+    deleteNamespace(namespace: string): void;
+    /**
+     * Rollout restart all deployments in a namespace.
+     */
+    rolloutRestartAll(namespace: string): void;
+    /**
+     * Rollback all deployments in a namespace to the previous revision.
+     */
+    rolloutUndoAll(namespace: string): void;
+    isToolInstalled(cmd: string): boolean;
+    isKubeReachable(): boolean;
+    kindClusterExists(): boolean;
+    createKindCluster(): void;
+    deleteKindCluster(): void;
+    loadImageToKind(imageName: string): void;
+}
+
+/**
+ * Pulumi program — deploys K8s resources from resolved cloud config.
+ */
+
+interface InfraOptions {
+    config: CloudConfig;
+    namespace: string;
+    shadowServerUrl?: string;
+    /** Per-deployment runtime env resolved from SaaS/user input. */
+    runtimeEnvVars?: Record<string, string>;
+    /** Browser/deployment locale and timezone context. */
+    runtimeContext?: DeploymentRuntimeContext;
+    /** kubectl context for K8s provider — defaults to KUBECONFIG_CONTEXT or 'rancher-desktop' */
+    kubeContext?: string;
+    /** Path to a kubeconfig YAML file — takes precedence over kubeContext when set */
+    kubeConfigPath?: string;
+    /**
+     * Image pull policy for all agent containers.
+     * Default: 'IfNotPresent' for the official OpenClaw runner and immutable/local tags,
+     * and 'Always' for other mutable registry tags.
+     */
+    imagePullPolicy?: 'Always' | 'IfNotPresent' | 'Never';
+}
+
+declare class ManifestService {
+    /** Build K8s resource definitions as plain objects (serializable to YAML/JSON). */
+    build(options: InfraOptions): Array<Record<string, unknown>>;
+    /** Create a Pulumi program function for programmatic deployments. */
+    createProgram(options: InfraOptions): () => Promise<Record<string, pulumi.Output<string>>>;
+}
+
+/**
+ * DeployService — deployment orchestration.
+ *
+ * Contains the core deploy/destroy workflow extracted from CLI commands.
+ * This is the primary service for deploying agents to Kubernetes.
+ */
+
+interface DeployOptions {
+    filePath: string;
+    namespace?: string;
+    stack?: string;
+    shadowUrl?: string;
+    shadowToken?: string;
+    dryRun?: boolean;
+    skipProvision?: boolean;
+    outputDir?: string;
+    k8sContext?: string;
+    stateDir?: string;
+    imagePullPolicy?: 'Always' | 'IfNotPresent' | 'Never';
+    k8sShadowUrl?: string;
+    local?: boolean;
+    onOutput?: (out: string) => void;
+    /** Per-request env overrides used for template/plugin resolution. Never mutates process.env. */
+    runtimeEnvVars?: Record<string, string>;
+    /** Browser/deployment locale and timezone context. */
+    runtimeContext?: DeploymentRuntimeContext;
+    /** Named cluster — resolves to kubeconfig in ~/.shadow-cloud/clusters/<name>.yaml */
+    cluster?: string;
+    /** Explicit path to a kubeconfig file (overrides cluster and k8sContext) */
+    kubeConfigPath?: string;
+    /**
+     * Optional callback invoked once the Pulumi Stack object exists.
+     * Callers can store the reference and later invoke `stack.cancel()` to
+     * abort an in-progress `up` operation cooperatively.
+     */
+    onStackReady?: (stack: {
+        cancel: () => Promise<void>;
+    }) => void;
+    /**
+     * Optional cooperative-cancel checker. Polled at safe boundaries; if it
+     * returns `true`, the deploy aborts before performing further side-effects.
+     */
+    isCancelled?: () => boolean;
+    /**
+     * Initial provision state supplied by SaaS/database callers. CLI callers
+     * still use the on-disk state file next to the config.
+     */
+    initialProvisionState?: ProvisionState | null;
+    /**
+     * Called whenever plugin provisioning produces a new durable state snapshot.
+     * SaaS uses this to persist Shadow server/channel/buddy IDs before Pulumi
+     * starts mutating Kubernetes.
+     */
+    onProvisionState?: (state: ProvisionState) => void | Promise<void>;
+}
+interface DeployResult {
+    namespace: string;
+    agentCount: number;
+    config: CloudConfig;
+    manifests?: Array<Record<string, unknown>>;
+    outputs?: Record<string, unknown>;
+    provisionState?: ProvisionState;
+}
+interface DestroyOptions {
+    filePath?: string;
+    namespace?: string;
+    stack?: string;
+    k8sContext?: string;
+    kubeConfigPath?: string;
+    config?: CloudConfig;
+    onStackReady?: (stack: {
+        cancel: () => Promise<void>;
+    }) => void;
+    isCancelled?: () => boolean;
+}
+declare class DeployService {
+    private configService;
+    private manifestService;
+    private k8s;
+    private logger;
+    constructor(configService: ConfigService, manifestService: ManifestService, k8s: K8sService, logger: Logger);
+    /**
+     * Deploy or update agents to Kubernetes.
+     *
+     * Orchestrates: parse → provision → resolve → manifest/deploy.
+     * Throws on errors instead of calling process.exit().
+     */
+    up(options: DeployOptions): Promise<DeployResult>;
+    /**
+     * Destroy agent cluster from Kubernetes.
+     * Throws on errors instead of calling process.exit().
+     */
+    destroy(options: DestroyOptions): Promise<void>;
+}
+
+interface DeploymentRuntimeCluster {
+    id?: string | null;
+    name?: string | null;
+    kubeconfig?: string | null;
+}
+interface DeployFromSnapshotOptions extends Omit<DeployOptions, 'filePath' | 'k8sContext' | 'shadowUrl' | 'shadowToken' | 'cluster' | 'kubeConfigPath'> {
+    configSnapshot: unknown;
+    runtimeEnvVars?: Record<string, string>;
+    runtimeContext?: DeploymentRuntimeContext;
+    shadowUrl?: string;
+    shadowToken?: string;
+    cluster?: DeploymentRuntimeCluster | null;
+    provisionState?: ProvisionState | null;
+    onProvisionState?: (state: ProvisionState) => void | Promise<void>;
+}
+interface DestroyRuntimeOptions {
+    namespace: string;
+    stack?: string;
+    cluster?: DeploymentRuntimeCluster | null;
+    configSnapshot?: unknown;
+    onStackReady?: (stack: {
+        cancel: () => Promise<void>;
+    }) => void;
+    isCancelled?: () => boolean;
+}
+declare function rewriteLoopbackKubeconfig(kubeconfigYaml: string, loopbackHost?: string | undefined): string;
+declare class DeploymentRuntimeService {
+    private readonly deployService;
+    constructor(deployService: DeployService);
+    deployFromSnapshot(options: DeployFromSnapshotOptions): Promise<DeployResult>;
+    destroy(options: DestroyRuntimeOptions): Promise<void>;
+    private withResolvedContext;
+}
+
+/**
+ * ImageService — Docker image build and push operations.
+ *
+ * Manages building, tagging, and pushing container images
+ * for agent runtimes.
+ */
+
+declare const IMAGES: readonly ["openclaw-runner", "claude-runner", "codex-runner", "gemini-runner", "opencode-runner"];
+interface ImageBuildOptions {
+    name: string;
+    tag?: string;
+    noCache?: boolean;
+    intoK8s?: boolean;
+    push?: boolean;
+    platform?: string;
+}
+declare class ImageService {
+    private imagesDir;
+    private logger;
+    constructor(logger: Logger, imagesDir?: string);
+    /** Get the images directory path. */
+    getImagesDir(): string;
+    /** Get the container registry URL. */
+    getRegistry(): string;
+    /** Get all available image names. */
+    getAvailableImages(): readonly string[];
+    /** Get a local image tag. */
+    getLocalTag(name: string, tag: string): string;
+    /** Build a Docker image with streaming output. */
+    build(options: ImageBuildOptions): Promise<void>;
+    /** Push an image to the registry. */
+    push(name: string, tag?: string): Promise<void>;
+    /** List available image definitions with their status. */
+    list(): Array<{
+        name: string;
+        hasDockerfile: boolean;
+    }>;
+    private getBuildContext;
+    private dockerBuild;
+    private spawnProcess;
+}
+
+/**
+ * RuntimeService — runtime adapter registry access.
+ *
+ * Wraps runtimes/index.ts for querying registered runtime adapters.
+ */
+
+declare class RuntimeService {
+    /** Get a runtime adapter by ID. Throws if not found. */
+    get(id: string): RuntimeAdapter;
+    /** Get all registered runtime adapters. */
+    getAll(): RuntimeAdapter[];
+    /** Get all registered runtime IDs. */
+    getIds(): string[];
+}
+
+/**
+ * TemplateDao — file-based template data access.
+ *
+ * All I/O is async. Supports two on-disk layouts:
+ *   Folder: templates/<slug>/shadowob-cloud.json  (+ optional index.json)
+ *   Flat:   templates/<slug>.template.json
+ *
+ * Folder layout takes priority over flat when both exist for the same slug.
+ */
+interface TemplateRecord {
+    slug: string;
+    isFolder: boolean;
+    configPath: string;
+    indexPath: string | null;
+    dir: string;
+}
+declare class TemplateDao {
+    readonly templatesDir: string;
+    constructor(templatesDir: string);
+    /** Discover all available template slugs. Folder layout takes priority. */
+    findAll(): Promise<TemplateRecord[]>;
+    /** Find a single template by slug. Returns null if not found. */
+    findBySlug(slug: string): Promise<TemplateRecord | null>;
+    /** Read and parse a JSON/JSONC file. Returns null on error. */
+    readJson<T = Record<string, unknown>>(filePath: string): Promise<T | null>;
+    /** Get file mtime as ISO string. Returns null if file not found. */
+    mtime(filePath: string): Promise<string | null>;
+    /** Copy a template folder (or single file) to destDir. */
+    copyTo(slug: string, destDir: string): Promise<void>;
+    private exists;
+}
+
+/**
+ * TemplateService — template discovery and metadata.
+ *
+ * All I/O is delegated to TemplateDao. This service handles
+ * business logic: i18n resolution, sorting, metadata mapping.
+ */
+
+interface TemplateMeta {
+    /** Stable kebab-case template slug */
+    name: string;
+    /** Locale-aware display title */
+    title: string;
+    /** Relative path to the config file from templatesDir */
+    file: string;
+    /** Locale-aware customer value proposition */
+    description: string;
+    agentCount: number;
+    namespace: string;
+    /** Absolute path to the directory containing the config (for relative path resolution) */
+    dir: string;
+}
+declare class TemplateService {
+    private readonly dao;
+    constructor(dao: TemplateDao);
+    /** Get the templates directory path. */
+    getDir(): string;
+    /** Discover all available config templates. */
+    discover(locale?: string): Promise<TemplateMeta[]>;
+    /**
+     * Read a template config by name.
+     * Prefers folder layout over flat files.
+     */
+    getTemplate(name: string): Promise<unknown | null>;
+    /**
+     * Get the absolute path to a template's config file.
+     * Useful for resolving relative paths (e.g. gitagent source.path).
+     */
+    getTemplatePath(name: string): Promise<string | null>;
+    /** List templates metadata (alias for discover). */
+    list(locale?: string): Promise<TemplateMeta[]>;
+}
+
+/**
+ * TemplateI18nService — locale-aware presentation metadata for built-in templates.
+ *
+ * The raw TemplateService owns template discovery and config loading.
+ * This service owns all console-facing copy (overview, highlights, requirements,
+ * categories, deploy-time labels, etc.) so the dashboard can pass locale in
+ * requests and keep presentation logic on the backend.
+ */
+
+type TemplateCategoryId = 'devops' | 'security' | 'support' | 'research' | 'monitoring' | 'business' | 'demo';
+type TemplateDifficulty = 'beginner' | 'intermediate' | 'advanced';
+interface TemplateCategoryInfo {
+    id: TemplateCategoryId | 'all';
+    label: string;
+    emoji: string;
+    description: string;
+}
+interface TemplateCatalogSummary {
+    /** Stable kebab-case template slug */
+    name: string;
+    /** Locale-aware display title */
+    title: string;
+    description: string;
+    agentCount: number;
+    namespace: string;
+    category: TemplateCategoryId;
+    emoji: string;
+    featured: boolean;
+    popularity: number;
+    difficulty: TemplateDifficulty;
+    estimatedDeployTime: string;
+    overview: string[];
+    features: string[];
+    highlights: string[];
+}
+interface TemplateCatalogDetail extends TemplateCatalogSummary {
+    file: string;
+    lastUpdated: string | null;
+    useCases: string[];
+    requirements: string[];
+    requiredEnvVars: string[];
+}
+interface TemplateCatalogResponse {
+    templates: TemplateCatalogSummary[];
+    categories: TemplateCategoryInfo[];
+}
+declare class TemplateI18nService {
+    private templateService;
+    constructor(templateService: TemplateService);
+    getCategories(locale?: string): TemplateCategoryInfo[];
+    listCatalog(locale?: string): Promise<TemplateCatalogResponse>;
+    getTemplateDetail(name: string, locale?: string): Promise<TemplateCatalogDetail | null>;
+    private buildSummary;
+    private resolveCopy;
+    private safeStat;
+}
+
+declare class UsageCostService {
+    private k8s;
+    private readonly cacheTtlMs;
+    private readonly namespaceCache;
+    constructor(k8s: K8sService, cacheTtlMs?: number);
+    collectNamespace(namespace: string): NamespaceCostSummary;
+    collectOverview(namespaces: string[]): CostOverviewSummary;
+    private getRuntime;
+}
+
+/**
+ * IoC Container — service registry and dependency injection.
+ *
+ * All services are registered here and injected via constructor.
+ * Use createContainer() to get a fully-wired ServiceContainer.
+ *
+ * For SDK use: import { createContainer } from '@shadowob/cloud/services/container'
+ * For testing: pass overrides to createContainer({ logger: mockLogger })
+ */
+
+/**
+ * Service container interface — all services accessible via a single object.
+ */
+interface ServiceContainer {
+    logger: Logger;
+    config: ConfigService;
+    manifest: ManifestService;
+    deploy: DeployService;
+    deploymentRuntime: DeploymentRuntimeService;
+    template: TemplateService;
+    templateI18n: TemplateI18nService;
+    runtime: RuntimeService;
+    image: ImageService;
+    k8s: K8sService;
+    usageCost: UsageCostService;
+    cluster: ClusterService;
+}
+/**
+ * Create a fully-wired service container.
+ *
+ * @param overrides - Optional partial overrides for testing or custom configurations.
+ *                    Override individual services or the logger.
+ */
+declare function createContainer(overrides?: Partial<ServiceContainer>): ServiceContainer;
+
+/**
+ * CLI Interface — registers all commands on the Commander program.
+ *
+ * This is the thin interface layer. Each command only:
+ * 1. Defines options and arguments
+ * 2. Parses and validates input
+ * 3. Delegates to the service container
+ * 4. Handles output formatting and process.exit
+ */
+
+/**
+ * Create the CLI program with all commands registered.
+ */
+declare function createCLI(container: ServiceContainer): Command;
+
+export { type AgentCostSummary, type AgentSandboxRuntimeState, type AgentSandboxStatus, type BillingUnit, CLOUD_SAAS_RUNTIME_KEY, type ClusterConfig, type ClusterMeta, ClusterService, ConfigService, type CostOverviewSummary, type DeployFromSnapshotOptions, type DeployOptions, type DeployResult, DeployService, type DeploymentRuntimeCluster, type DeploymentRuntimeContext, DeploymentRuntimeService, type DestroyRuntimeOptions, IMAGES, type ImageBuildOptions, ImageService, type K8sExecResult, type K8sPodSummary, K8sService, ManifestService, type NamespaceCostSummary, OPENCLAW_USAGE_COMMANDS, type PluginCatalogEntry, type PluginLibraryEntry, type PluginLibrarySearchResult, type ProviderCatalogEntry, type ProviderUsageSummary, type PvcVolumeSnapshotCapability, RESERVED_RUNTIME_ENV_KEYS, type RuntimeEnvField, type RuntimeEnvRefPolicy, RuntimeService, type ServiceContainer, type TemplateCatalogDetail, type TemplateCatalogResponse, type TemplateCatalogSummary, type TemplateCategoryId, type TemplateCategoryInfo, type TemplateDifficulty, TemplateI18nService, type TemplateLibraryEntry, type TemplateLibrarySearchResult, type TemplateMeta, TemplateService, UsageCostService, type VolumeSnapshotReadyStatus, applyKubernetesManifestAsync, applyRuntimeEnvRefPolicy, assertNoReservedEnvOverrides, attachCloudSaasProvisionState, collectAgentUsage, collectNamespaceCost, collectRuntimeEnvFields, collectRuntimeEnvRefPolicy, collectRuntimeEnvRequirements, createCLI, createContainer, createVolumeSnapshotBackupAsync, deleteKubernetesResourceAsync, deleteNamespace, execInPod, execInPodAsync, execInPodWithInputAsync, extractCloudSaasRuntime, extractRequiredEnvVars, getAgentSandboxStatusAsync, getPluginLibraryEntry, getPvcVolumeSnapshotCapability, getVolumeSnapshotReadyStatus, isPvcBackedByCsiProvisioner, isReservedRuntimeEnvKey, isVolumeSnapshotApiAvailable, listManagedNamespaces, listPluginCatalogs, listPluginLibrary, listPods, listPodsAsync, listProviderCatalogs, listTemplateLibrary, loadCloudConfigSchema, loadKubeconfigPath, namespaceExists, parseOpenClawUsageOutput, prepareCloudSaasConfigSnapshot, readClusterConfig, readPodLogs, readPodLogsAsync, redactCloudSaasConfigSnapshot, resolveCloudSaasShadowRuntime, resolveSandboxNameAsync, resolveVolumeSnapshotClassForPvc, restorePvcFromVolumeSnapshot, rewriteLoopbackKubeconfig, sanitizeCloudSaasDeployment, scaleAgentSandboxAsync, searchPluginLibrary, searchTemplateLibrary, spawnPodLogStream, summarizeCloudConfigValidation, summarizeCostOverview, validateCloudSaasConfigSnapshot, waitForAgentSandboxPaused, waitForAgentSandboxReady, waitForPodReadyAsync, waitForVolumeSnapshotReady };