@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.0

package/dist/runtime.d.ts

@@ -0,0 +1,496 @@
+import * as z from 'zod/v4';
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+import type { RuntimeExecution } from '@vibesdotdev/kernel/execution';
+import type { RuntimeEnvironmentImplementation } from '@vibesdotdev/kernel/schemas/registry';
+import type { CLICommandArgument, CLICommandOption, CLICommandEffects } from '@vibesdotdev/cli/schemas/types';
+import { type Preset, type ExecutionContext } from './schemas/presets.ts';
+import type { LiveJson } from './harness/live-tools.ts';
+export declare const EXTERNAL_PRESET_KIND: "external/preset";
+export declare const EXTERNAL_PROFILE_KIND: "external/profile";
+export declare const EXTERNAL_OPERATION_KIND: "external/operation";
+export declare const ExternalPresetDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    target: z.ZodString;
+    category: z.ZodEnum<{
+        workflow: "workflow";
+        model: "model";
+        integration: "integration";
+        alias: "alias";
+    }>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    features: z.ZodObject<{
+        mcpServer: z.ZodDefault<z.ZodBoolean>;
+        hooks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        modelConfig: z.ZodDefault<z.ZodBoolean>;
+        workflowConfig: z.ZodDefault<z.ZodBoolean>;
+        disableInternalTools: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    recipe: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"file-write">;
+            path: z.ZodString;
+            content: z.ZodString;
+            mode: z.ZodOptional<z.ZodNumber>;
+            overwrite: z.ZodOptional<z.ZodBoolean>;
+            createDirs: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-edit">;
+            path: z.ZodString;
+            format: z.ZodEnum<{
+                json: "json";
+                yaml: "yaml";
+                toml: "toml";
+            }>;
+            merge: z.ZodRecord<z.ZodString, z.ZodType<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue, z.core.$ZodTypeInternals<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue>>>;
+            arrayStrategy: z.ZodOptional<z.ZodEnum<{
+                replace: "replace";
+                merge: "merge";
+                append: "append";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-copy">;
+            source: z.ZodString;
+            destination: z.ZodString;
+            mode: z.ZodOptional<z.ZodNumber>;
+            overwrite: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-backup">;
+            baseDir: z.ZodString;
+            files: z.ZodArray<z.ZodString>;
+            backupDirName: z.ZodDefault<z.ZodString>;
+            variable: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-restore">;
+            baseDir: z.ZodString;
+            backupDir: z.ZodOptional<z.ZodString>;
+            backupTimestamp: z.ZodOptional<z.ZodString>;
+            backupDirName: z.ZodDefault<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"command">;
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            silent: z.ZodDefault<z.ZodBoolean>;
+            allowFailure: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"hook-install">;
+            target: z.ZodString;
+            hooks: z.ZodArray<z.ZodEnum<{
+                "session.start": "session.start";
+                "session.end": "session.end";
+                "prompt.submit": "prompt.submit";
+                "tool.before": "tool.before";
+                "tool.after": "tool.after";
+                "context.beforeCompact": "context.beforeCompact";
+                "context.afterCompact": "context.afterCompact";
+                "permission.request": "permission.request";
+                "agent.stop": "agent.stop";
+                "subagent.stop": "subagent.stop";
+                notification: "notification";
+            }>>;
+            vibesPath: z.ZodDefault<z.ZodString>;
+            global: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"mcp-configure">;
+            target: z.ZodString;
+            serverName: z.ZodDefault<z.ZodString>;
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            toolTimeout: z.ZodOptional<z.ZodNumber>;
+            enabledTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            disabledTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            global: z.ZodOptional<z.ZodBoolean>;
+            tier: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                full: "full";
+                minimal: "minimal";
+                recommended: "recommended";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"adapter-codegen">;
+            adapterId: z.ZodString;
+            outputDir: z.ZodOptional<z.ZodString>;
+            tier: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                full: "full";
+                minimal: "minimal";
+                recommended: "recommended";
+            }>>;
+            global: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"operation">;
+            operationId: z.ZodString;
+            options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"prompt">;
+            message: z.ZodString;
+            promptType: z.ZodDefault<z.ZodEnum<{
+                input: "input";
+                select: "select";
+                confirm: "confirm";
+            }>>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            default: z.ZodOptional<z.ZodString>;
+            variable: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"validate">;
+            check: z.ZodEnum<{
+                "tool-installed": "tool-installed";
+                "vibes-authenticated": "vibes-authenticated";
+                "session-active": "session-active";
+                "file-exists": "file-exists";
+                "command-available": "command-available";
+            }>;
+            target: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            fatal: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>], "type">>;
+        rollback: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"file-write">;
+            path: z.ZodString;
+            content: z.ZodString;
+            mode: z.ZodOptional<z.ZodNumber>;
+            overwrite: z.ZodOptional<z.ZodBoolean>;
+            createDirs: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-edit">;
+            path: z.ZodString;
+            format: z.ZodEnum<{
+                json: "json";
+                yaml: "yaml";
+                toml: "toml";
+            }>;
+            merge: z.ZodRecord<z.ZodString, z.ZodType<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue, z.core.$ZodTypeInternals<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue>>>;
+            arrayStrategy: z.ZodOptional<z.ZodEnum<{
+                replace: "replace";
+                merge: "merge";
+                append: "append";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-copy">;
+            source: z.ZodString;
+            destination: z.ZodString;
+            mode: z.ZodOptional<z.ZodNumber>;
+            overwrite: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-backup">;
+            baseDir: z.ZodString;
+            files: z.ZodArray<z.ZodString>;
+            backupDirName: z.ZodDefault<z.ZodString>;
+            variable: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file-restore">;
+            baseDir: z.ZodString;
+            backupDir: z.ZodOptional<z.ZodString>;
+            backupTimestamp: z.ZodOptional<z.ZodString>;
+            backupDirName: z.ZodDefault<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"command">;
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            silent: z.ZodDefault<z.ZodBoolean>;
+            allowFailure: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"hook-install">;
+            target: z.ZodString;
+            hooks: z.ZodArray<z.ZodEnum<{
+                "session.start": "session.start";
+                "session.end": "session.end";
+                "prompt.submit": "prompt.submit";
+                "tool.before": "tool.before";
+                "tool.after": "tool.after";
+                "context.beforeCompact": "context.beforeCompact";
+                "context.afterCompact": "context.afterCompact";
+                "permission.request": "permission.request";
+                "agent.stop": "agent.stop";
+                "subagent.stop": "subagent.stop";
+                notification: "notification";
+            }>>;
+            vibesPath: z.ZodDefault<z.ZodString>;
+            global: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"mcp-configure">;
+            target: z.ZodString;
+            serverName: z.ZodDefault<z.ZodString>;
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            toolTimeout: z.ZodOptional<z.ZodNumber>;
+            enabledTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            disabledTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            global: z.ZodOptional<z.ZodBoolean>;
+            tier: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                full: "full";
+                minimal: "minimal";
+                recommended: "recommended";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"adapter-codegen">;
+            adapterId: z.ZodString;
+            outputDir: z.ZodOptional<z.ZodString>;
+            tier: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                full: "full";
+                minimal: "minimal";
+                recommended: "recommended";
+            }>>;
+            global: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"operation">;
+            operationId: z.ZodString;
+            options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"prompt">;
+            message: z.ZodString;
+            promptType: z.ZodDefault<z.ZodEnum<{
+                input: "input";
+                select: "select";
+                confirm: "confirm";
+            }>>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            default: z.ZodOptional<z.ZodString>;
+            variable: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"validate">;
+            check: z.ZodEnum<{
+                "tool-installed": "tool-installed";
+                "vibes-authenticated": "vibes-authenticated";
+                "session-active": "session-active";
+                "file-exists": "file-exists";
+                "command-available": "command-available";
+            }>;
+            target: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            fatal: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>], "type">>>;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>;
+    requires: z.ZodOptional<z.ZodObject<{
+        vibesVersion: z.ZodOptional<z.ZodString>;
+        toolVersion: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            win32: "win32";
+            darwin: "darwin";
+            linux: "linux";
+        }>>>;
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    author: z.ZodOptional<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    homepage: z.ZodOptional<z.ZodURL>;
+    kind: z.ZodLiteral<"external/preset">;
+    profiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        presetId: z.ZodString;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ExternalPresetDescriptor = z.infer<typeof ExternalPresetDescriptorSchema>;
+export interface ExternalPresetProfile {
+    id: string;
+    presetId: string;
+    aliases?: readonly string[];
+}
+export interface CreateExternalPresetDescriptorOptions {
+    preset: Preset;
+    profiles?: readonly ExternalPresetProfile[];
+}
+export declare const ExternalProfileDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    capabilityId: z.ZodOptional<z.ZodString>;
+    requiredContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    optionalContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodUnknown>;
+    retention: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+        maxEntries: z.ZodOptional<z.ZodNumber>;
+        maxBytes: z.ZodOptional<z.ZodNumber>;
+        cascadeFrom: z.ZodOptional<z.ZodString>;
+        ageField: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        enforcedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    kind: z.ZodLiteral<"external/profile">;
+    hostId: z.ZodString;
+    profile: z.ZodString;
+    presetId: z.ZodString;
+    aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ExternalProfileDescriptor = z.infer<typeof ExternalProfileDescriptorSchema>;
+/**
+ * One provider-owned operation is one runtime asset. Operation names are open
+ * strings: adding `repair`, `upgrade`, or a future provider verb never changes
+ * Framework schemas or a central dispatcher.
+ */
+export declare const ExternalOperationDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    capabilityId: z.ZodOptional<z.ZodString>;
+    requiredContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    optionalContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodUnknown>;
+    retention: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+        maxEntries: z.ZodOptional<z.ZodNumber>;
+        maxBytes: z.ZodOptional<z.ZodNumber>;
+        cascadeFrom: z.ZodOptional<z.ZodString>;
+        ageField: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        enforcedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    kind: z.ZodLiteral<"external/operation">;
+    hostId: z.ZodString;
+    operation: z.ZodString;
+    effect: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        write: "write";
+        process: "process";
+    }>>;
+    cli: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodLiteral<false>]>>;
+}, z.core.$strip>;
+export type ExternalOperationDescriptor = z.infer<typeof ExternalOperationDescriptorSchema>;
+export interface ExternalOperationInput {
+    arguments: Record<string, LiveJson | undefined>;
+    options: Record<string, LiveJson | undefined>;
+}
+export interface ExternalOperationChange {
+    action: string;
+    kind?: string;
+    path?: string;
+    detail?: string;
+}
+export interface ExternalOperationCheck {
+    id?: string;
+    status: string;
+    message: string;
+    remedy?: string;
+}
+export interface ExternalOperationResult {
+    status: string;
+    message?: string;
+    changed?: boolean;
+    changes?: readonly ExternalOperationChange[];
+    checks?: readonly ExternalOperationCheck[];
+    details?: readonly string[];
+    nextActions?: readonly string[];
+    data?: unknown;
+}
+/**
+ * What a provider operation actually answers: implementations are provider-owned
+ * (`impl: unknown`), so every field is optional and malformed fields fall back
+ * to absent. Both consumers (the CLI text projection and the preset executor)
+ * read through this schema; an answer that is not an object at all refuses
+ * `INVALID_INPUT external-operation-answer-invalid` at the call site.
+ */
+export declare const ExternalOperationAnswerSchema: z.ZodObject<{
+    status: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    ok: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    message: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    changes: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        action: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        kind: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        path: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        detail: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>>;
+    checks: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        status: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        message: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        remedy: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>>;
+    details: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    nextActions: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type ExternalOperationAnswer = z.infer<typeof ExternalOperationAnswerSchema>;
+export interface ExternalFilesystemCapability {
+    exists(path: string): Promise<boolean>;
+    readFile(path: string, encoding?: 'utf8' | 'utf-8'): Promise<string | Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array, options?: 'utf8' | 'utf-8' | {
+        encoding?: 'utf8' | 'utf-8';
+    }): Promise<void>;
+    list(path: string): Promise<Array<{
+        name: string;
+    }>>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    copy(source: string, destination: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    resolve(...pathSegments: string[]): string;
+    join(...pathSegments: string[]): string;
+    isAbsolute(path: string): boolean;
+}
+export interface ExternalRuntimeServices {
+    runtime: RuntimeRef;
+    filesystem?: ExternalFilesystemCapability;
+    execution?: RuntimeExecution;
+    environment?: RuntimeEnvironmentImplementation;
+    workspacePath?: string;
+}
+export interface ExternalOperation {
+    execute(input: ExternalOperationInput, context: ExecutionContext, services: ExternalRuntimeServices): Promise<ExternalOperationResult | ExternalOperationAnswer>;
+}
+export type ExternalOperationLoader = () => Promise<{
+    impl: unknown;
+    meta?: {
+        id: string;
+        kind: string;
+        priority: number;
+    };
+}>;
+export declare const externalPresetKind: import("@vibesdotdev/kernel").RuntimeKindDescriptorRecord<unknown>;
+export declare const externalProfileKind: import("@vibesdotdev/kernel").RuntimeKindDescriptorRecord<unknown>;
+export declare const externalOperationKind: import("@vibesdotdev/kernel").RuntimeKindDescriptorRecord<unknown>;
+/** Register one provider-owned operation and its lazy implementation. */
+export declare function registerExternalOperation(runtime: RuntimeRef, descriptor: ExternalOperationDescriptor, load: ExternalOperationLoader): Promise<void>;
+export declare function externalPresetDescriptor(options: CreateExternalPresetDescriptorOptions): ExternalPresetDescriptor;
+export declare function externalProfileDescriptors(preset: ExternalPresetDescriptor): ExternalProfileDescriptor[];
+/** Register a preset and its independently queryable profile descriptors. */
+export declare function registerExternalPreset(runtime: RuntimeRef, preset: ExternalPresetDescriptor): void;
+export declare function resolveExternalRuntimeServices(runtime: RuntimeRef): Promise<ExternalRuntimeServices>;
+export declare function createExternalOperationDescriptor(input: {
+    id: string;
+    hostId: string;
+    operation: string;
+    name: string;
+    description: string;
+    effect?: 'read' | 'write' | 'process';
+    cli?: false | {
+        name?: string;
+        aliases?: readonly string[];
+        arguments?: readonly CLICommandArgument[];
+        options?: readonly CLICommandOption[];
+        effects?: CLICommandEffects;
+        nonTtyBehavior?: 'service' | 'interactive';
+    };
+}): ExternalOperationDescriptor;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/runtime.js

@@ -0,0 +1,168 @@
+import * as z from 'zod/v4';
+import { createRuntimeKind } from '@vibesdotdev/kernel';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/kernel/schemas/descriptor';
+import { PresetSchema } from "./schemas/presets.js";
+import { resolveExternalCLIProjector } from "./runtime/external-surface-projector.js";
+export const EXTERNAL_PRESET_KIND = 'external/preset';
+export const EXTERNAL_PROFILE_KIND = 'external/profile';
+export const EXTERNAL_OPERATION_KIND = 'external/operation';
+const ExternalPresetProfileSchema = z.object({
+    id: z.string().trim().min(1),
+    presetId: z.string().trim().min(1),
+    aliases: z.array(z.string().trim().min(1)).optional()
+});
+export const ExternalPresetDescriptorSchema = PresetSchema.extend({
+    kind: z.literal(EXTERNAL_PRESET_KIND),
+    profiles: z.array(ExternalPresetProfileSchema).optional()
+});
+export const ExternalProfileDescriptorSchema = RuntimeDescriptorSchema.extend({
+    kind: z.literal(EXTERNAL_PROFILE_KIND),
+    hostId: z.string().trim().min(1),
+    profile: z.string().trim().min(1),
+    presetId: z.string().trim().min(1),
+    aliases: z.array(z.string().trim().min(1)).default([])
+});
+// Projector configuration is opaque to the universal External package. Each
+// selected surface validates its payload with the schema it owns.
+const ExternalOperationProjectionConfigSchema = z.record(z.string(), z.unknown());
+/**
+ * One provider-owned operation is one runtime asset. Operation names are open
+ * strings: adding `repair`, `upgrade`, or a future provider verb never changes
+ * Framework schemas or a central dispatcher.
+ */
+export const ExternalOperationDescriptorSchema = RuntimeDescriptorSchema.extend({
+    kind: z.literal(EXTERNAL_OPERATION_KIND),
+    hostId: z.string().trim().min(1),
+    operation: z
+        .string()
+        .trim()
+        .regex(/^[a-z][a-z0-9-]*$/),
+    effect: z.enum(['read', 'write', 'process']).default('write'),
+    cli: z.union([ExternalOperationProjectionConfigSchema, z.literal(false)]).optional()
+});
+/**
+ * What a provider operation actually answers: implementations are provider-owned
+ * (`impl: unknown`), so every field is optional and malformed fields fall back
+ * to absent. Both consumers (the CLI text projection and the preset executor)
+ * read through this schema; an answer that is not an object at all refuses
+ * `INVALID_INPUT external-operation-answer-invalid` at the call site.
+ */
+export const ExternalOperationAnswerSchema = z.object({
+    status: z.string().optional().catch(undefined),
+    ok: z.boolean().optional().catch(undefined),
+    message: z.string().optional().catch(undefined),
+    changes: z
+        .array(z.object({
+        action: z.string().optional().catch(undefined),
+        kind: z.string().optional().catch(undefined),
+        path: z.string().optional().catch(undefined),
+        detail: z.string().optional().catch(undefined)
+    }))
+        .optional()
+        .catch(undefined),
+    checks: z
+        .array(z.object({
+        status: z.string().optional().catch(undefined),
+        message: z.string().optional().catch(undefined),
+        remedy: z.string().optional().catch(undefined)
+    }))
+        .optional()
+        .catch(undefined),
+    details: z.array(z.string()).optional().catch(undefined),
+    nextActions: z.array(z.string()).optional().catch(undefined)
+});
+export const externalPresetKind = createRuntimeKind({
+    id: EXTERNAL_PRESET_KIND,
+    descriptorSchema: ExternalPresetDescriptorSchema
+});
+export const externalProfileKind = createRuntimeKind({
+    id: EXTERNAL_PROFILE_KIND,
+    descriptorSchema: ExternalProfileDescriptorSchema
+});
+export const externalOperationKind = createRuntimeKind({
+    id: EXTERNAL_OPERATION_KIND,
+    descriptorSchema: ExternalOperationDescriptorSchema
+});
+/** Register one provider-owned operation and its lazy implementation. */
+export async function registerExternalOperation(runtime, descriptor, load) {
+    if (runtime.query('external/host').withId(descriptor.hostId).descriptors().length === 0) {
+        throw new Error(`External operation '${descriptor.id}' references missing host '${descriptor.hostId}'`);
+    }
+    const collision = runtime
+        .query(EXTERNAL_OPERATION_KIND)
+        .descriptors()
+        .map((candidate) => ExternalOperationDescriptorSchema.parse(candidate))
+        .find((candidate) => candidate.hostId === descriptor.hostId && candidate.operation === descriptor.operation);
+    if (collision) {
+        throw new Error(`External operations '${collision.id}' and '${descriptor.id}' share runtime coordinate '${descriptor.hostId}/${descriptor.operation}'`);
+    }
+    runtime.registerDescriptor(EXTERNAL_OPERATION_KIND, descriptor);
+    runtime.registerLoader(EXTERNAL_OPERATION_KIND, descriptor.id, load, {
+        constraint: { hardware: ['consumer'] }
+    });
+    const projector = await resolveExternalCLIProjector(runtime);
+    projector?.projectOperation(descriptor);
+}
+export function externalPresetDescriptor(options) {
+    for (const profile of options.profiles ?? []) {
+        if (profile.presetId !== options.preset.id) {
+            throw new Error(`External preset profile '${profile.id}' references '${profile.presetId}', expected '${options.preset.id}'`);
+        }
+    }
+    return ExternalPresetDescriptorSchema.parse({
+        ...options.preset,
+        kind: EXTERNAL_PRESET_KIND,
+        profiles: options.profiles
+    });
+}
+export function externalProfileDescriptors(preset) {
+    const profiles = preset.profiles?.length
+        ? preset.profiles
+        : [{ id: preset.id, presetId: preset.id, aliases: [] }];
+    return profiles.map((profile) => ExternalProfileDescriptorSchema.parse({
+        kind: EXTERNAL_PROFILE_KIND,
+        id: `${preset.target}/${profile.id}`,
+        name: profile.id,
+        description: preset.description,
+        hostId: preset.target,
+        profile: profile.id,
+        presetId: preset.id,
+        aliases: profile.aliases ?? [],
+        tags: ['external', 'profile', preset.target],
+        hardware: ['consumer'],
+        enabled: true
+    }));
+}
+/** Register a preset and its independently queryable profile descriptors. */
+export function registerExternalPreset(runtime, preset) {
+    runtime.registerDescriptor(EXTERNAL_PRESET_KIND, preset);
+    for (const profile of externalProfileDescriptors(preset)) {
+        runtime.registerDescriptor(EXTERNAL_PROFILE_KIND, profile);
+    }
+}
+export async function resolveExternalRuntimeServices(runtime) {
+    const filesystem = runtime.hasKind('filesystem/adapter')
+        ? await runtime.query('filesystem/adapter').resolve()
+        : undefined;
+    const execution = runtime.hasKind('runtime/execution')
+        ? await runtime.query('runtime/execution').resolve()
+        : undefined;
+    const environment = runtime.hasKind('runtime/environment')
+        ? await runtime.query('runtime/environment').resolve()
+        : undefined;
+    let workspacePath;
+    if (runtime.hasContext('runtime/workspace-path')) {
+        workspacePath = await runtime.context('runtime/workspace-path');
+    }
+    return { runtime, filesystem, execution, environment, workspacePath };
+}
+export function createExternalOperationDescriptor(input) {
+    return ExternalOperationDescriptorSchema.parse({
+        kind: EXTERNAL_OPERATION_KIND,
+        tags: ['external', 'operation', input.hostId],
+        hardware: ['consumer'],
+        enabled: true,
+        ...input
+    });
+}
+//# sourceMappingURL=runtime.js.map