@agentplate/cli 1.0.0

package/src/paths.ts

@@ -0,0 +1,36 @@
+/**
+ * Canonical filesystem paths for Agentplate state, derived from a project root.
+ * Centralized so every command/store agrees on where things live.
+ */
+
+import { join } from "node:path";
+import { AGENTPLATE_DIR } from "./config.ts";
+
+export const sessionsDbPath = (root: string): string => join(root, AGENTPLATE_DIR, "sessions.db");
+export const eventsDbPath = (root: string): string => join(root, AGENTPLATE_DIR, "events.db");
+export const mailDbPath = (root: string): string => join(root, AGENTPLATE_DIR, "mail.db");
+export const mergeDbPath = (root: string): string => join(root, AGENTPLATE_DIR, "merge-queue.db");
+export const deploysDbPath = (root: string): string => join(root, AGENTPLATE_DIR, "deploys.db");
+export const manifestFilePath = (root: string): string =>
+	join(root, AGENTPLATE_DIR, "agent-manifest.json");
+export const currentRunPath = (root: string): string =>
+	join(root, AGENTPLATE_DIR, "current-run.txt");
+export const worktreesDir = (root: string): string => join(root, AGENTPLATE_DIR, "worktrees");
+export const agentDefsDir = (root: string): string => join(root, AGENTPLATE_DIR, "agent-defs");
+export const skillsDir = (root: string): string => join(root, AGENTPLATE_DIR, "skills");
+export const agentStateDir = (root: string, agentName: string): string =>
+	join(root, AGENTPLATE_DIR, "agents", agentName);
+export const appliedSkillsPath = (root: string, agentName: string): string =>
+	join(agentStateDir(root, agentName), "applied-skills.json");
+export const specPath = (root: string, taskId: string): string =>
+	join(root, AGENTPLATE_DIR, "specs", `${taskId}.md`);
+
+/**
+ * Path to a bundled base agent definition shipped with the package
+ * (`<package>/agents/<file>`). Resolved relative to this module (src/paths.ts).
+ */
+export const packageAgentDefPath = (file: string): string =>
+	join(import.meta.dir, "..", "agents", file);
+
+/** The package root (one level above src/). Used to locate bundled ui/dist. */
+export const packageRootDir = (): string => join(import.meta.dir, "..");

package/src/providers/apply.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_CONFIG } from "../config.ts";
+import { applyProviderSelection, buildProviderConfig } from "./apply.ts";
+import { getProviderSpec } from "./registry.ts";
+
+const anthropic = getProviderSpec("anthropic");
+const openrouter = getProviderSpec("openrouter");
+const custom = getProviderSpec("custom");
+
+describe("buildProviderConfig", () => {
+	test("api-key auth stores the token env var", () => {
+		if (!anthropic) throw new Error("anthropic spec missing");
+		const cfg = buildProviderConfig(anthropic, "claude-sonnet-4-6", "api-key");
+		expect(cfg.type).toBe("native");
+		expect(cfg.authMode).toBe("api-key");
+		expect(cfg.authTokenEnv).toBe("ANTHROPIC_API_KEY");
+		expect(cfg.model).toBe("claude-sonnet-4-6");
+		expect(cfg.baseUrl).toBeUndefined();
+	});
+
+	test("subscription auth stores NO token env var (delegated to CLI login)", () => {
+		if (!anthropic) throw new Error("anthropic spec missing");
+		const cfg = buildProviderConfig(anthropic, "claude-opus-4-8", "subscription");
+		expect(cfg.authMode).toBe("subscription");
+		expect(cfg.authTokenEnv).toBeUndefined();
+	});
+
+	test("env auth keeps the token env var (read from environment at run time)", () => {
+		if (!anthropic) throw new Error("anthropic spec missing");
+		const cfg = buildProviderConfig(anthropic, "claude-opus-4-8", "env");
+		expect(cfg.authMode).toBe("env");
+		expect(cfg.authTokenEnv).toBe("ANTHROPIC_API_KEY");
+	});
+
+	test("gateway provider gets its default baseUrl", () => {
+		if (!openrouter) throw new Error("openrouter spec missing");
+		const cfg = buildProviderConfig(openrouter, "openai/gpt-4o", "api-key");
+		expect(cfg.type).toBe("gateway");
+		expect(cfg.baseUrl).toBe("https://openrouter.ai/api/v1");
+	});
+
+	test("custom baseUrl overrides the default", () => {
+		if (!custom) throw new Error("custom spec missing");
+		const cfg = buildProviderConfig(custom, "my-model", "api-key", "https://my.endpoint/v1");
+		expect(cfg.baseUrl).toBe("https://my.endpoint/v1");
+	});
+});
+
+describe("applyProviderSelection", () => {
+	test("registers the provider, marks it active, sets the runtime", () => {
+		if (!openrouter) throw new Error("openrouter spec missing");
+		const next = applyProviderSelection(DEFAULT_CONFIG, {
+			providerId: "openrouter",
+			spec: openrouter,
+			model: "anthropic/claude-sonnet-4-6",
+			authMode: "api-key",
+			runtime: "codex",
+		});
+		expect(next.activeProvider).toBe("openrouter");
+		expect(next.providers.openrouter?.model).toBe("anthropic/claude-sonnet-4-6");
+		expect(next.providers.openrouter?.authMode).toBe("api-key");
+		expect(next.runtime.default).toBe("codex");
+	});
+
+	test("subscription selection records authMode without a token env var", () => {
+		if (!anthropic) throw new Error("anthropic spec missing");
+		const next = applyProviderSelection(DEFAULT_CONFIG, {
+			providerId: "anthropic",
+			spec: anthropic,
+			model: "claude-opus-4-8",
+			authMode: "subscription",
+			runtime: "claude",
+		});
+		expect(next.providers.anthropic?.authMode).toBe("subscription");
+		expect(next.providers.anthropic?.authTokenEnv).toBeUndefined();
+	});
+
+	test("does not mutate the input config", () => {
+		if (!anthropic) throw new Error("anthropic spec missing");
+		const before = structuredClone(DEFAULT_CONFIG);
+		applyProviderSelection(DEFAULT_CONFIG, {
+			providerId: "anthropic",
+			spec: anthropic,
+			model: "claude-opus-4-8",
+			authMode: "api-key",
+			runtime: "claude",
+		});
+		expect(DEFAULT_CONFIG).toEqual(before);
+	});
+});

package/src/providers/apply.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure helpers that turn a wizard selection into config — separated from the
+ * interactive I/O so they can be unit-tested without a TTY.
+ */
+
+import type { AgentplateConfig, AuthMode, ProviderConfig } from "../types.ts";
+import type { ProviderSpec } from "./registry.ts";
+
+export interface ProviderSelection {
+	/** Provider id (catalog id, or a user-chosen id for custom endpoints). */
+	providerId: string;
+	/** The catalog spec the selection was based on. */
+	spec: ProviderSpec;
+	/** Chosen model id. */
+	model: string;
+	/** How credentials are obtained (subscription / api-key / env / none). */
+	authMode: AuthMode;
+	/** Base URL (gateway/custom providers). */
+	baseUrl?: string;
+	/** Coding-agent runtime to drive workers (e.g. "claude"). */
+	runtime: string;
+}
+
+/** Build a {@link ProviderConfig} from a catalog spec and the chosen values. */
+export function buildProviderConfig(
+	spec: ProviderSpec,
+	model: string,
+	authMode: AuthMode,
+	baseUrl?: string,
+): ProviderConfig {
+	const config: ProviderConfig = {
+		type: spec.kind,
+		authMode,
+		model,
+	};
+	// Subscription/none auth delegates to the runtime login — no env var binding.
+	if (authMode === "api-key" || authMode === "env") {
+		config.authTokenEnv = spec.authEnvVar;
+	}
+	const resolvedBaseUrl = baseUrl ?? spec.defaultBaseUrl;
+	if (spec.kind === "gateway" && resolvedBaseUrl) {
+		config.baseUrl = resolvedBaseUrl;
+	}
+	return config;
+}
+
+/**
+ * Apply a provider selection to a config, returning a new config with the
+ * provider registered, marked active, and the runtime set. Does not mutate the
+ * input.
+ */
+export function applyProviderSelection(
+	config: AgentplateConfig,
+	selection: ProviderSelection,
+): AgentplateConfig {
+	const next = structuredClone(config);
+	next.providers[selection.providerId] = buildProviderConfig(
+		selection.spec,
+		selection.model,
+		selection.authMode,
+		selection.baseUrl,
+	);
+	next.activeProvider = selection.providerId;
+	next.runtime.default = selection.runtime;
+	return next;
+}

package/src/providers/registry.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import {
+	getProviderSpec,
+	listProviders,
+	MIN_CONTEXT_TOKENS,
+	meetsContextFloor,
+	PROVIDERS,
+} from "./registry.ts";
+
+describe("provider registry", () => {
+	test("getProviderSpec finds known providers", () => {
+		expect(getProviderSpec("anthropic")?.label).toBe("Anthropic");
+		expect(getProviderSpec("openrouter")?.kind).toBe("gateway");
+	});
+
+	test("getProviderSpec returns undefined for unknown", () => {
+		expect(getProviderSpec("nope")).toBeUndefined();
+	});
+
+	test("catalog includes the expected providers", () => {
+		const ids = listProviders().map((p) => p.id);
+		expect(ids).toContain("anthropic");
+		expect(ids).toContain("openai");
+		expect(ids).toContain("ollama");
+		expect(ids).toContain("custom");
+		expect(ids).toContain("opencode-zen");
+	});
+
+	test("CLI-login providers offer subscription via their runtime", () => {
+		// Each maps to a coding-agent CLI whose own login (OAuth/keys) is reused.
+		const cases: Array<[string, string]> = [
+			["anthropic", "claude"],
+			["openai", "codex"],
+			["google", "gemini"],
+			["opencode-zen", "opencode"],
+		];
+		for (const [id, runtime] of cases) {
+			const spec = getProviderSpec(id);
+			expect(spec?.supportsSubscription).toBe(true);
+			expect(spec?.subscriptionRuntime).toBe(runtime);
+		}
+	});
+
+	test("every provider declares an auth env var", () => {
+		for (const spec of PROVIDERS) {
+			expect(spec.authEnvVar.length).toBeGreaterThan(0);
+		}
+	});
+
+	test("custom provider requires a base URL and has no preset models", () => {
+		const custom = getProviderSpec("custom");
+		expect(custom?.requiresBaseUrl).toBe(true);
+		expect(custom?.models.length).toBe(0);
+	});
+
+	test("ollama is keyless", () => {
+		expect(getProviderSpec("ollama")?.keyless).toBe(true);
+	});
+
+	test("meetsContextFloor enforces the minimum", () => {
+		expect(meetsContextFloor({ id: "a", label: "A", contextWindow: MIN_CONTEXT_TOKENS })).toBe(
+			true,
+		);
+		expect(meetsContextFloor({ id: "b", label: "B", contextWindow: 8000 })).toBe(false);
+	});
+
+	test("all preset models meet the context floor", () => {
+		for (const spec of PROVIDERS) {
+			for (const model of spec.models) {
+				expect(model.contextWindow).toBeGreaterThanOrEqual(MIN_CONTEXT_TOKENS);
+			}
+		}
+	});
+});

package/src/providers/registry.ts

@@ -0,0 +1,254 @@
+/**
+ * Provider catalog — the static knowledge Agentplate has about AI providers.
+ *
+ * This is the menu the setup wizard presents. It is intentionally code (not
+ * config): adding a provider here makes it instantly available in `agentplate
+ * setup`, mirroring how Hermes Agent's `select_provider_and_model()` works.
+ *
+ * A *provider* is an LLM backend with credentials. It is distinct from a
+ * *runtime* (the coding-agent CLI that drives workers — see src/runtimes/).
+ * `native` providers are reached through the runtime's own auth; `gateway`
+ * providers route through a base URL with a bearer token.
+ *
+ * Agentplate rejects models below `minContextTokens` of context, because
+ * multi-step tool-calling agents need room to work (the same 64k floor Hermes
+ * enforces).
+ */
+
+/** Minimum context window (tokens) Agentplate will accept for an agent model. */
+export const MIN_CONTEXT_TOKENS = 64_000;
+
+export interface ProviderModel {
+	/** Model id passed to the provider/runtime (e.g. "claude-sonnet-4-6"). */
+	id: string;
+	/** Human label for the wizard. */
+	label: string;
+	/** Context window in tokens. */
+	contextWindow: number;
+}
+
+export interface ProviderSpec {
+	/** Unique provider id (key into config.providers). */
+	id: string;
+	/** Human label for the wizard. */
+	label: string;
+	/** One-line description. */
+	description: string;
+	/** `native` = runtime-native auth; `gateway` = base URL + bearer token. */
+	kind: "native" | "gateway";
+	/** Conventional env var name holding the API key. */
+	authEnvVar: string;
+	/** Default base URL for gateway providers. */
+	defaultBaseUrl?: string;
+	/** True if the user must supply a base URL (custom/self-hosted endpoints). */
+	requiresBaseUrl?: boolean;
+	/** True if this provider does not need an API key (e.g. local Ollama). */
+	keyless?: boolean;
+	/**
+	 * True if this provider can be used via an existing CLI/subscription login
+	 * (no API key stored) — e.g. a Claude Pro/Max OAuth session in Claude Code.
+	 */
+	supportsSubscription?: boolean;
+	/** The runtime CLI that provides the subscription login (e.g. "claude"). */
+	subscriptionRuntime?: string;
+	/** Human label for the subscription option (e.g. "Claude Pro/Max subscription"). */
+	subscriptionLabel?: string;
+	/** Known models (the wizard offers these; custom ids are always allowed). */
+	models: ProviderModel[];
+	/** Where to get credentials / docs. */
+	docsUrl?: string;
+}
+
+/**
+ * The catalog. Model lists are a curated starting point, not exhaustive — the
+ * wizard always lets the user type a custom model id.
+ */
+export const PROVIDERS: readonly ProviderSpec[] = [
+	{
+		id: "anthropic",
+		label: "Anthropic",
+		description: "Claude models (native Claude Code support)",
+		kind: "native",
+		authEnvVar: "ANTHROPIC_API_KEY",
+		supportsSubscription: true,
+		subscriptionRuntime: "claude",
+		subscriptionLabel: "Claude Pro/Max subscription (Claude Code login)",
+		docsUrl: "https://console.anthropic.com/settings/keys",
+		models: [
+			{ id: "claude-opus-4-8", label: "Claude Opus 4.8", contextWindow: 200_000 },
+			{ id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6", contextWindow: 200_000 },
+			{ id: "claude-haiku-4-5-20251001", label: "Claude Haiku 4.5", contextWindow: 200_000 },
+		],
+	},
+	{
+		id: "openai",
+		label: "OpenAI",
+		description: "GPT-5 series — frontier and coding-optimized models (Codex)",
+		kind: "gateway",
+		authEnvVar: "OPENAI_API_KEY",
+		defaultBaseUrl: "https://api.openai.com/v1",
+		supportsSubscription: true,
+		subscriptionRuntime: "codex",
+		subscriptionLabel: "ChatGPT/Codex subscription (codex login)",
+		docsUrl: "https://platform.openai.com/api-keys",
+		// The development-focused slice of the Codex model catalog (codex-cli 0.128).
+		// gpt-5.5 leads (frontier coding); the codex/spark variants are the
+		// coding-optimized line. Spark is Codex-subscription only (not in the public
+		// API), so prefer it with the `codex` runtime. The wizard always allows a
+		// custom model id, so this is a curated starting point, not the full list.
+		models: [
+			{ id: "gpt-5.5", label: "GPT-5.5 (frontier coding)", contextWindow: 272_000 },
+			{ id: "gpt-5.4", label: "GPT-5.4 (everyday coding)", contextWindow: 272_000 },
+			{ id: "gpt-5.4-mini", label: "GPT-5.4 Mini (fast, low-cost)", contextWindow: 272_000 },
+			{ id: "gpt-5.3-codex", label: "GPT-5.3 Codex (coding-optimized)", contextWindow: 272_000 },
+			{
+				id: "gpt-5.3-codex-spark",
+				label: "GPT-5.3 Codex Spark (ultra-fast, Codex login only)",
+				contextWindow: 128_000,
+			},
+		],
+	},
+	{
+		id: "openrouter",
+		label: "OpenRouter",
+		description: "Free development models behind one OpenAI-compatible gateway",
+		kind: "gateway",
+		authEnvVar: "OPENROUTER_API_KEY",
+		defaultBaseUrl: "https://openrouter.ai/api/v1",
+		docsUrl: "https://openrouter.ai/models?max_price=0",
+		// Curated free (`:free`) coding models verified against the OpenRouter API.
+		// Free tiers are rate-limited and may change; any paid model id can still be
+		// typed at the prompt. qwen3-coder leads (coding-specialized, 1M context).
+		models: [
+			{ id: "qwen/qwen3-coder:free", label: "Qwen3 Coder (free)", contextWindow: 1_000_000 },
+			{ id: "moonshotai/kimi-k2.6:free", label: "Kimi K2.6 (free)", contextWindow: 262_144 },
+			{
+				id: "qwen/qwen3-next-80b-a3b-instruct:free",
+				label: "Qwen3 Next 80B (free)",
+				contextWindow: 262_144,
+			},
+			{ id: "z-ai/glm-4.5-air:free", label: "GLM 4.5 Air (free)", contextWindow: 131_072 },
+			{ id: "openai/gpt-oss-120b:free", label: "GPT-OSS 120B (free)", contextWindow: 131_072 },
+			{
+				id: "meta-llama/llama-3.3-70b-instruct:free",
+				label: "Llama 3.3 70B (free)",
+				contextWindow: 131_072,
+			},
+		],
+	},
+	{
+		id: "opencode-zen",
+		label: "OpenCode Zen",
+		description: "Free development models (MiniMax 2.5, GLM, Kimi, Qwen, DeepSeek…)",
+		kind: "gateway",
+		authEnvVar: "OPENCODE_API_KEY",
+		defaultBaseUrl: "https://opencode.ai/zen/v1",
+		// OpenCode manages its own login (`opencode auth login`), so prefer the
+		// subscription path — Agentplate stores no key and the `opencode` runtime
+		// uses its existing Zen login, mirroring Anthropic→claude.
+		supportsSubscription: true,
+		subscriptionRuntime: "opencode",
+		subscriptionLabel: "OpenCode Zen login (opencode auth)",
+		docsUrl: "https://opencode.ai/docs/zen",
+		// OpenCode Zen models, addressed in the `opencode` runtime's `provider/model`
+		// form (`opencode/<name>`); a bare id is "Invalid model format". The free
+		// (`*-free`) catalog ROTATES often, so this is a current snapshot, not a
+		// contract — the wizard always allows a custom id. Verified against
+		// `opencode models` (opencode 1.15.x).
+		models: [
+			{ id: "opencode/minimax-m3-free", label: "MiniMax M3 (free)", contextWindow: 200_000 },
+			{ id: "opencode/big-pickle", label: "Big Pickle", contextWindow: 200_000 },
+			{
+				id: "opencode/deepseek-v4-flash-free",
+				label: "DeepSeek V4 Flash (free)",
+				contextWindow: 200_000,
+			},
+			{ id: "opencode/mimo-v2.5-free", label: "MiMo V2.5 (free)", contextWindow: 200_000 },
+			{
+				id: "opencode/nemotron-3-super-free",
+				label: "Nemotron 3 Super (free)",
+				contextWindow: 204_800,
+			},
+		],
+	},
+	{
+		id: "deepseek",
+		label: "DeepSeek",
+		description: "DeepSeek chat and reasoner models",
+		kind: "gateway",
+		authEnvVar: "DEEPSEEK_API_KEY",
+		defaultBaseUrl: "https://api.deepseek.com/v1",
+		docsUrl: "https://platform.deepseek.com/api_keys",
+		models: [
+			{ id: "deepseek-chat", label: "DeepSeek Chat", contextWindow: 128_000 },
+			{ id: "deepseek-reasoner", label: "DeepSeek Reasoner", contextWindow: 128_000 },
+		],
+	},
+	{
+		id: "google",
+		label: "Google Gemini",
+		description: "Latest Gemini 3.x models (1M context)",
+		kind: "gateway",
+		authEnvVar: "GEMINI_API_KEY",
+		defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+		supportsSubscription: true,
+		subscriptionRuntime: "gemini",
+		subscriptionLabel: "Google account (Gemini CLI login)",
+		docsUrl: "https://aistudio.google.com/apikey",
+		// Latest Gemini lineup verified against models.dev (release dates). 3.1 Pro
+		// leads (frontier coding/reasoning); 3.5 Flash is the newest fast model;
+		// `gemini-flash-latest` is Google's always-newest Flash alias. 2.5 Pro is the
+		// current non-preview GA fallback. The wizard always allows a custom id.
+		models: [
+			{ id: "gemini-3.1-pro-preview", label: "Gemini 3.1 Pro (preview)", contextWindow: 1_048_576 },
+			{ id: "gemini-3.5-flash", label: "Gemini 3.5 Flash", contextWindow: 1_048_576 },
+			{ id: "gemini-3-pro-preview", label: "Gemini 3 Pro (preview)", contextWindow: 1_048_576 },
+			{
+				id: "gemini-3.1-flash-lite",
+				label: "Gemini 3.1 Flash Lite (low-cost)",
+				contextWindow: 1_048_576,
+			},
+			{ id: "gemini-flash-latest", label: "Gemini Flash (latest alias)", contextWindow: 1_048_576 },
+			{ id: "gemini-2.5-pro", label: "Gemini 2.5 Pro (GA)", contextWindow: 1_048_576 },
+		],
+	},
+	{
+		id: "ollama",
+		label: "Ollama (local)",
+		description: "Run open models locally — no API key required",
+		kind: "gateway",
+		authEnvVar: "OLLAMA_API_KEY",
+		defaultBaseUrl: "http://localhost:11434/v1",
+		keyless: true,
+		docsUrl: "https://ollama.com/library",
+		models: [
+			{ id: "qwen2.5-coder:32b", label: "Qwen2.5 Coder 32B", contextWindow: 128_000 },
+			{ id: "llama3.3:70b", label: "Llama 3.3 70B", contextWindow: 128_000 },
+		],
+	},
+	{
+		id: "custom",
+		label: "Custom endpoint",
+		description: "Any OpenAI-compatible endpoint (self-hosted, NIM, vLLM, …)",
+		kind: "gateway",
+		authEnvVar: "AGENTPLATE_CUSTOM_API_KEY",
+		requiresBaseUrl: true,
+		docsUrl: undefined,
+		models: [],
+	},
+];
+
+/** Look up a provider spec by id. */
+export function getProviderSpec(id: string): ProviderSpec | undefined {
+	return PROVIDERS.find((p) => p.id === id);
+}
+
+/** All provider specs, in catalog order. */
+export function listProviders(): readonly ProviderSpec[] {
+	return PROVIDERS;
+}
+
+/** Does this model satisfy the minimum context requirement? */
+export function meetsContextFloor(model: ProviderModel): boolean {
+	return model.contextWindow >= MIN_CONTEXT_TOKENS;
+}