@hyperdrive.bot/paseo-protocol 0.2.5

package/dist/paseo-config-schema.d.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+export declare function normalizeLifecycleCommands(commands: unknown): string[];
+export declare const PaseoLifecycleCommandRawSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+export declare const PaseoScriptEntryRawSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodUnknown>;
+    command: z.ZodOptional<z.ZodUnknown>;
+    port: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export declare const PaseoWorktreeConfigRawSchema: z.ZodObject<{
+    setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    teardown: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    terminals: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export declare const PaseoMetadataGenerationEntrySchema: z.ZodCatch<z.ZodObject<{
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>;
+export declare const PaseoMetadataGenerationSchema: z.ZodCatch<z.ZodObject<{
+    title: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    branchName: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    commitMessage: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    pullRequest: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>>;
+export declare const PaseoConfigRawSchema: z.ZodObject<{
+    worktree: z.ZodOptional<z.ZodObject<{
+        setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        teardown: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        terminals: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodOptional<z.ZodUnknown>;
+        command: z.ZodOptional<z.ZodUnknown>;
+        port: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    metadataGeneration: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        title: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        branchName: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        commitMessage: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        pullRequest: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export declare const WorktreeConfigSchema: z.ZodCatch<z.ZodObject<{
+    terminals: z.ZodOptional<z.ZodUnknown>;
+    setup: z.ZodPipe<z.ZodOptional<z.ZodUnknown>, z.ZodTransform<string[], unknown>>;
+    teardown: z.ZodPipe<z.ZodOptional<z.ZodUnknown>, z.ZodTransform<string[], unknown>>;
+}, z.core.$loose>>;
+export declare const ScriptEntrySchema: z.ZodCatch<z.ZodObject<{
+    type: z.ZodOptional<z.ZodUnknown>;
+    command: z.ZodOptional<z.ZodUnknown>;
+    port: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>>;
+export declare const PaseoConfigSchema: z.ZodCatch<z.ZodObject<{
+    worktree: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        terminals: z.ZodOptional<z.ZodUnknown>;
+        setup: z.ZodPipe<z.ZodOptional<z.ZodUnknown>, z.ZodTransform<string[], unknown>>;
+        teardown: z.ZodPipe<z.ZodOptional<z.ZodUnknown>, z.ZodTransform<string[], unknown>>;
+    }, z.core.$loose>>>;
+    scripts: z.ZodCatch<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodObject<{
+        type: z.ZodOptional<z.ZodUnknown>;
+        command: z.ZodOptional<z.ZodUnknown>;
+        port: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>>>;
+    metadataGeneration: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+        title: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        branchName: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        commitMessage: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        pullRequest: z.ZodOptional<z.ZodCatch<z.ZodObject<{
+            instructions: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>>;
+export declare const PaseoConfigRevisionSchema: z.ZodObject<{
+    mtimeMs: z.ZodNumber;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ProjectConfigRpcErrorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    code: z.ZodLiteral<"project_not_found">;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodLiteral<"invalid_project_config">;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodLiteral<"stale_project_config">;
+    currentRevision: z.ZodNullable<z.ZodObject<{
+        mtimeMs: z.ZodNumber;
+        size: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodLiteral<"write_failed">;
+}, z.core.$strip>], "code">;
+export type PaseoScriptEntryRaw = z.infer<typeof PaseoScriptEntryRawSchema>;
+export type PaseoMetadataGenerationEntry = z.infer<typeof PaseoMetadataGenerationEntrySchema>;
+export type PaseoMetadataGeneration = z.infer<typeof PaseoMetadataGenerationSchema>;
+export type PaseoConfigRaw = z.infer<typeof PaseoConfigRawSchema>;
+export type PaseoConfig = z.infer<typeof PaseoConfigSchema>;
+export type PaseoConfigRevision = z.infer<typeof PaseoConfigRevisionSchema>;
+export type ProjectConfigRpcError = z.infer<typeof ProjectConfigRpcErrorSchema>;
+//# sourceMappingURL=paseo-config-schema.d.ts.map

package/dist/paseo-config-schema.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+export function normalizeLifecycleCommands(commands) {
+    if (typeof commands === "string") {
+        return commands.trim().length > 0 ? [commands] : [];
+    }
+    if (!Array.isArray(commands)) {
+        return [];
+    }
+    return commands.filter((command) => {
+        return typeof command === "string" && command.trim().length > 0;
+    });
+}
+export const PaseoLifecycleCommandRawSchema = z.union([z.string(), z.array(z.string())]);
+export const PaseoScriptEntryRawSchema = z
+    .object({
+    type: z.unknown().optional(),
+    command: z.unknown().optional(),
+    port: z.unknown().optional(),
+})
+    .passthrough();
+export const PaseoWorktreeConfigRawSchema = z
+    .object({
+    setup: PaseoLifecycleCommandRawSchema.optional(),
+    teardown: PaseoLifecycleCommandRawSchema.optional(),
+    terminals: z.unknown().optional(),
+})
+    .passthrough();
+export const PaseoMetadataGenerationEntrySchema = z
+    .object({
+    instructions: z.string().optional(),
+})
+    .passthrough()
+    .catch({});
+export const PaseoMetadataGenerationSchema = z
+    .object({
+    title: PaseoMetadataGenerationEntrySchema.optional(),
+    branchName: PaseoMetadataGenerationEntrySchema.optional(),
+    commitMessage: PaseoMetadataGenerationEntrySchema.optional(),
+    pullRequest: PaseoMetadataGenerationEntrySchema.optional(),
+})
+    // COMPAT(projectMetadataAgentTitle): `agentTitle` project metadata prompts were removed
+    // in v0.1.96; keep legacy paseo.json parseable until 2026-12-16.
+    .passthrough()
+    .catch({});
+export const PaseoConfigRawSchema = z
+    .object({
+    worktree: PaseoWorktreeConfigRawSchema.optional(),
+    scripts: z.record(z.string(), PaseoScriptEntryRawSchema).optional(),
+    metadataGeneration: PaseoMetadataGenerationSchema.optional(),
+})
+    .passthrough();
+export const WorktreeConfigSchema = PaseoWorktreeConfigRawSchema.extend({
+    setup: z.unknown().optional().transform(normalizeLifecycleCommands),
+    teardown: z.unknown().optional().transform(normalizeLifecycleCommands),
+})
+    .passthrough()
+    .catch({ setup: [], teardown: [] });
+export const ScriptEntrySchema = PaseoScriptEntryRawSchema.catch({});
+export const PaseoConfigSchema = PaseoConfigRawSchema.extend({
+    worktree: WorktreeConfigSchema.optional(),
+    scripts: z.record(z.string(), ScriptEntrySchema).optional().catch({}),
+    metadataGeneration: PaseoMetadataGenerationSchema.optional(),
+})
+    .passthrough()
+    .catch({});
+export const PaseoConfigRevisionSchema = z.object({
+    mtimeMs: z.number(),
+    size: z.number(),
+});
+export const ProjectConfigRpcErrorSchema = z.discriminatedUnion("code", [
+    z.object({ code: z.literal("project_not_found") }),
+    z.object({ code: z.literal("invalid_project_config") }),
+    z.object({
+        code: z.literal("stale_project_config"),
+        currentRevision: PaseoConfigRevisionSchema.nullable(),
+    }),
+    z.object({ code: z.literal("write_failed") }),
+]);
+//# sourceMappingURL=paseo-config-schema.js.map

package/dist/path-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function stripCwdPrefix(filePath: string, cwd?: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/path-utils.js

@@ -0,0 +1,16 @@
+export function stripCwdPrefix(filePath, cwd) {
+    if (!cwd || !filePath) {
+        return filePath;
+    }
+    const normalizedCwd = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const prefix = `${normalizedCwd}/`;
+    if (normalizedPath.startsWith(prefix)) {
+        return normalizedPath.slice(prefix.length);
+    }
+    if (normalizedPath === normalizedCwd) {
+        return ".";
+    }
+    return filePath;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/provider-config.d.ts

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import type { AgentProvider } from "./agent-types.js";
+export declare const ProviderCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"default">;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"append">;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"replace">;
+    argv: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "mode">;
+export declare const ProviderRuntimeSettingsSchema: z.ZodObject<{
+    command: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"default">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"append">;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"replace">;
+        argv: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "mode">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    transport: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        sdk: "sdk";
+        pty: "pty";
+    }>>;
+}, z.core.$strict>;
+export declare const ProviderProfileModelSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    thinkingOptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const ProviderOverrideSchema: z.ZodObject<{
+    extends: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    models: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
+        thinkingOptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            isDefault: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    additionalModels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
+        thinkingOptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            isDefault: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    order: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ProviderOverridesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    extends: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    models: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
+        thinkingOptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            isDefault: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    additionalModels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        isDefault: z.ZodOptional<z.ZodBoolean>;
+        thinkingOptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            isDefault: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    order: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const AgentProviderRuntimeSettingsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    command: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"default">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"append">;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"replace">;
+        argv: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "mode">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    transport: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        sdk: "sdk";
+        pty: "pty";
+    }>>;
+}, z.core.$strict>>;
+export type ProviderCommand = z.infer<typeof ProviderCommandSchema>;
+export type ProviderRuntimeSettings = z.infer<typeof ProviderRuntimeSettingsSchema>;
+export type ProviderProfileModel = z.infer<typeof ProviderProfileModelSchema>;
+export type ProviderOverride = z.infer<typeof ProviderOverrideSchema>;
+export type ProviderOverrides = z.infer<typeof ProviderOverridesSchema>;
+export type AgentProviderRuntimeSettingsMap = Partial<Record<AgentProvider, ProviderRuntimeSettings>>;
+//# sourceMappingURL=provider-config.d.ts.map

package/dist/provider-config.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { AgentProviderSchema } from "./provider-manifest.js";
+const ProviderCommandDefaultSchema = z.object({
+    mode: z.literal("default"),
+});
+const ProviderCommandAppendSchema = z.object({
+    mode: z.literal("append"),
+    args: z.array(z.string()).optional(),
+});
+const ProviderCommandReplaceSchema = z.object({
+    mode: z.literal("replace"),
+    argv: z.array(z.string().min(1)).min(1),
+});
+export const ProviderCommandSchema = z.discriminatedUnion("mode", [
+    ProviderCommandDefaultSchema,
+    ProviderCommandAppendSchema,
+    ProviderCommandReplaceSchema,
+]);
+export const ProviderRuntimeSettingsSchema = z
+    .object({
+    command: ProviderCommandSchema.optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    disallowedTools: z.array(z.string()).optional(),
+    // Optional runtime transport hint (PR #1198 + PTY migration). Controls
+    // which AgentTransport implementation a provider's session uses. "auto"
+    // lets the provider pick (SDK preferred, PTY fallback when SDK absent).
+    // Left optional with no schema-level default so existing partial inputs
+    // (diagnostic-utils etc) keep type-checking; consumers default to "sdk"
+    // when they need a concrete value.
+    transport: z.enum(["sdk", "pty", "auto"]).optional(),
+})
+    .strict();
+const ProviderProfileThinkingOptionSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    description: z.string().optional(),
+    isDefault: z.boolean().optional(),
+});
+export const ProviderProfileModelSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    isDefault: z.boolean().optional(),
+    thinkingOptions: z.array(ProviderProfileThinkingOptionSchema).optional(),
+});
+export const ProviderOverrideSchema = z.object({
+    extends: z.string().optional(),
+    label: z.string().optional(),
+    description: z.string().optional(),
+    command: z.array(z.string().min(1)).min(1).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+    models: z.array(ProviderProfileModelSchema).optional(),
+    additionalModels: z.array(ProviderProfileModelSchema).optional(),
+    disallowedTools: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    order: z.number().optional(),
+});
+const BUILTIN_PROVIDER_IDS = ["claude", "codex", "copilot", "opencode", "pi", "omp"];
+const PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export const ProviderOverridesSchema = z
+    .record(z.string(), ProviderOverrideSchema)
+    .superRefine((providers, ctx) => {
+    const builtinProviderIdSet = new Set(BUILTIN_PROVIDER_IDS);
+    const validExtendsValues = new Set([...BUILTIN_PROVIDER_IDS, "acp"]);
+    for (const [providerId, provider] of Object.entries(providers)) {
+        if (!PROVIDER_ID_PATTERN.test(providerId)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [providerId],
+                message: `Provider ID "${providerId}" must match ${PROVIDER_ID_PATTERN}.`,
+            });
+        }
+        const isBuiltinProvider = builtinProviderIdSet.has(providerId);
+        if (!isBuiltinProvider && !provider.extends) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [providerId, "extends"],
+                message: `Custom provider "${providerId}" must declare extends.`,
+            });
+        }
+        if (!isBuiltinProvider && !provider.label) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [providerId, "label"],
+                message: `Custom provider "${providerId}" must declare label.`,
+            });
+        }
+        if (provider.extends && !validExtendsValues.has(provider.extends)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [providerId, "extends"],
+                message: `Provider "${providerId}" extends unknown provider "${provider.extends}".`,
+            });
+        }
+        if (provider.extends === "acp" && !provider.command) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [providerId, "command"],
+                message: `Provider "${providerId}" extending "acp" must declare command.`,
+            });
+        }
+    }
+});
+export const AgentProviderRuntimeSettingsMapSchema = z
+    .record(z.string(), ProviderRuntimeSettingsSchema)
+    .superRefine((providers, ctx) => {
+    for (const providerId of Object.keys(providers)) {
+        const parsedProviderId = AgentProviderSchema.safeParse(providerId);
+        if (!parsedProviderId.success) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [providerId],
+                message: `Invalid agent provider "${providerId}".`,
+            });
+        }
+    }
+});
+//# sourceMappingURL=provider-config.js.map

package/dist/provider-icon-names.d.ts

@@ -0,0 +1,5 @@
+export declare const BUILTIN_PROVIDER_ICON_NAMES: string[];
+export declare const ACP_PROVIDER_ICON_NAMES: string[];
+export declare const TERMINAL_PROFILE_ICON_NAMES: string[];
+export declare const KNOWN_PROVIDER_ICON_NAMES: string[];
+//# sourceMappingURL=provider-icon-names.d.ts.map

package/dist/provider-icon-names.js

@@ -0,0 +1,52 @@
+export const BUILTIN_PROVIDER_ICON_NAMES = [
+    "claude",
+    "codex",
+    "copilot",
+    "kiro",
+    "minimax",
+    "omp",
+    "opencode",
+    "pi",
+];
+export const ACP_PROVIDER_ICON_NAMES = [
+    "agoragentic-acp",
+    "amp-acp",
+    "auggie",
+    "autohand",
+    "cline",
+    "codebuddy-code",
+    "codewhale",
+    "cortex-code",
+    "corust-agent",
+    "crow-cli",
+    "cursor",
+    "deepagents",
+    "dimcode",
+    "dirac",
+    "factory-droid",
+    "fast-agent",
+    "gemini",
+    "glm-acp-agent",
+    "goose",
+    "grok",
+    "junie",
+    "kilo",
+    "kimi",
+    "minion-code",
+    "mistral-vibe",
+    "nova",
+    "poolside",
+    "qoder",
+    "qwen-code",
+    "sigit",
+    "stakpak",
+    "traecli",
+    "vtcode",
+];
+export const TERMINAL_PROFILE_ICON_NAMES = ["agy"];
+export const KNOWN_PROVIDER_ICON_NAMES = [
+    ...BUILTIN_PROVIDER_ICON_NAMES,
+    ...ACP_PROVIDER_ICON_NAMES,
+    ...TERMINAL_PROFILE_ICON_NAMES,
+];
+//# sourceMappingURL=provider-icon-names.js.map

package/dist/provider-manifest.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import type { AgentMode } from "./agent-types.js";
+export type AgentModeColorTier = "safe" | "moderate" | "dangerous" | "planning" | `#${string}`;
+export type AgentModeIcon = string;
+export interface AgentModeVisuals {
+    icon: AgentModeIcon;
+    colorTier: AgentModeColorTier;
+}
+export type AgentProviderModeDefinition = Omit<AgentMode, "icon" | "colorTier"> & AgentModeVisuals & {
+    isUnattended?: boolean;
+};
+/**
+ * Wire-format family for an agent provider.
+ *
+ * Providers in the same family share message envelopes, model IDs, and
+ * persistence/resume token formats. Hot-swapping the provider on a running
+ * agent (via {@link AgentManager.swapAgentProvider}) is only allowed
+ * between providers in the same family, AND only between providers that
+ * declare each other in {@link AgentProviderDefinition.compatibleProviders}.
+ *
+ * - `anthropic-messages` — Claude family (`claude` builtin + any custom
+ *   provider that extends `claude`, e.g. "Claude (Pool)" / Z.AI Anthropic
+ *   gateway). Same wire format, same model IDs, identical resume tokens.
+ * - `openai-compatible` — OpenAI Codex family. Different wire format than
+ *   anthropic-messages — incompatible.
+ * - `generic-acp` — Agent Client Protocol (OpenCode, Copilot, custom ACP).
+ *   Different again.
+ */
+export type AgentProviderWireFamily = "anthropic-messages" | "openai-compatible" | "generic-acp";
+export interface AgentProviderDefinition {
+    id: string;
+    label: string;
+    description: string;
+    enabledByDefault?: boolean;
+    defaultModeId: string | null;
+    modes: AgentProviderModeDefinition[];
+    voice?: {
+        enabled: boolean;
+        defaultModeId: string;
+        defaultModel?: string;
+    };
+    /**
+     * Wire-format family for hot-swap compatibility. Providers can only swap
+     * mid-session to another provider in the SAME family. Models, message
+     * envelopes, and resume token formats are guaranteed identical within a
+     * family. Required for builtin providers; custom providers (declared via
+     * config `extends: <base>`) inherit the family from the base definition.
+     */
+    wireFamily: AgentProviderWireFamily;
+    /**
+     * Provider IDs that this provider can hot-swap TO mid-session. The swap
+     * preserves session history + persistence handle. Self is NOT included.
+     * Symmetry is validated at boot — see
+     * {@link validateCompatibleProvidersSymmetry}.
+     *
+     * For config-based custom providers extending a builtin: by default we
+     * treat them as bidirectionally compatible with their `extends` base AND
+     * with sibling providers extending the same base — see
+     * {@link computeEffectiveCompatibleProviders}. Explicit per-provider
+     * overrides (set by future config surface) take precedence.
+     */
+    compatibleProviders?: string[];
+}
+export declare const AGENT_PROVIDER_DEFINITIONS: AgentProviderDefinition[];
+export declare const DEV_AGENT_PROVIDER_DEFINITIONS: AgentProviderDefinition[];
+export declare function getAgentProviderDefinition(provider: string, definitions?: AgentProviderDefinition[]): AgentProviderDefinition;
+export declare const BUILTIN_PROVIDER_IDS: string[];
+export declare const AGENT_PROVIDER_IDS: string[];
+export declare const AgentProviderSchema: z.ZodString;
+export declare function isValidAgentProvider(value: string, validIds?: Iterable<string>): boolean;
+export declare function getUnattendedModeId(provider: string, definitions?: AgentProviderDefinition[]): string | undefined;
+export declare function getModeVisuals(provider: string, modeId: string, definitions: AgentProviderDefinition[]): AgentModeVisuals | undefined;
+export interface CompatibilityValidationResult {
+    /**
+     * Per-provider effective compatible providers, after dropping any one-sided
+     * (asymmetric) entries. Use this for hot-swap eligibility checks.
+     */
+    effective: Map<string, ReadonlySet<string>>;
+    /**
+     * Human-readable warnings for one-sided declarations. Callers should log
+     * these at boot — they indicate a definition or config bug.
+     */
+    warnings: string[];
+}
+/**
+ * Validates that `compatibleProviders` declarations are symmetric across all
+ * provided definitions: if A declares B compatible, B MUST declare A as well.
+ * One-sided declarations are dropped from the effective set and emitted as
+ * warnings so they fail loudly at boot rather than producing a half-broken
+ * swap experience at runtime.
+ *
+ * Wire-family mismatches are ALSO dropped + warned: even if both sides
+ * declare each other, a swap between two providers in different families
+ * cannot work (different wire formats / resume tokens).
+ */
+export declare function validateCompatibleProvidersSymmetry(definitions: readonly AgentProviderDefinition[]): CompatibilityValidationResult;
+/**
+ * Compute the effective set of compatibleProviders for a runtime registry
+ * that may include custom providers extending builtins (e.g. "Claude (Pool)"
+ * with `extends: "claude"`). Strategy:
+ *
+ * 1. Start from each provider's explicit `compatibleProviders` list.
+ * 2. Auto-link providers that share the same `extends` base (siblings) AND
+ *    auto-link each derived provider with its base — but ONLY when both have
+ *    the same wireFamily AND the base did not explicitly opt out.
+ * 3. Run symmetry validation on the resulting graph; drop asymmetric edges.
+ *
+ * The result is a Map keyed by provider id, listing the providers each one
+ * may swap TO.
+ */
+export declare function computeEffectiveCompatibleProviders(definitions: readonly AgentProviderDefinition[], 
+/** Optional: providerId -> base provider id (the `extends` target). */
+extensionMap?: ReadonlyMap<string, string>): CompatibilityValidationResult;
+//# sourceMappingURL=provider-manifest.d.ts.map