pikiloop 0.4.0

package/dist/model/injector.js

@@ -0,0 +1,272 @@
+/**
+ * Credential injector — turn an active Profile into the env vars and
+ * additional argv that should be applied when spawning a specific agent.
+ *
+ * This is the single point where pikiloop's Profile abstraction is
+ * translated into per-agent quirks. Adding a new agent (e.g. OpenCode)
+ * = adding one entry to AGENT_INJECT_TABLE.
+ */
+import { resolveCredential } from '../core/secrets/index.js';
+import { getActiveProfile, getProvider } from './store.js';
+import { peekProviderModelInfo, prefetchProviderModels } from './provider-models.js';
+const EMPTY = { env: {}, argvAppend: [], detail: '' };
+// ---------------------------------------------------------------------------
+// Shared host-based provider identification
+// ---------------------------------------------------------------------------
+function providerHost(provider) {
+    try {
+        return new URL(provider.baseURL).host.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Stable slug used to identify the provider in TOML-style configs (Codex
+ * `model_providers.<slug>`, Hermes ACP `<slug>:<model>`). Host-aware so a
+ * "DeepSeek personal" provider always resolves to `deepseek`, regardless of
+ * its display name.
+ */
+function providerSlug(provider) {
+    if (provider.kind === 'anthropic')
+        return 'anthropic';
+    if (provider.kind === 'openai')
+        return 'openai';
+    if (provider.kind === 'google')
+        return 'google';
+    const host = providerHost(provider);
+    if (host.includes('deepseek'))
+        return 'deepseek';
+    if (host.includes('moonshot') || host.includes('kimi'))
+        return 'kimi';
+    if (host.includes('minimax'))
+        return 'minimax';
+    if (host.includes('zhipuai') || host.includes('z.ai') || host.includes('bigmodel'))
+        return 'zai';
+    if (host.includes('x.ai'))
+        return 'xai';
+    if (host.includes('stepfun'))
+        return 'stepfun';
+    if (host.includes('dashscope') || host.includes('qwen'))
+        return 'qwen';
+    if (host.includes('volces') || host.includes('volcengine') || host.includes('doubao'))
+        return 'doubao';
+    if (host.includes('openrouter'))
+        return 'openrouter';
+    return 'openrouter';
+}
+/**
+ * Canonical env-var name(s) carrying the credential for a provider. Returned
+ * as a map so e.g. Google fans out to both `GOOGLE_API_KEY` and
+ * `GEMINI_API_KEY` for SDKs that expect either.
+ */
+function providerCredentialEnv(provider, apiKey) {
+    if (provider.kind === 'anthropic')
+        return { ANTHROPIC_API_KEY: apiKey };
+    if (provider.kind === 'openai')
+        return { OPENAI_API_KEY: apiKey };
+    if (provider.kind === 'google')
+        return { GOOGLE_API_KEY: apiKey, GEMINI_API_KEY: apiKey };
+    const host = providerHost(provider);
+    if (host.includes('openrouter'))
+        return { OPENROUTER_API_KEY: apiKey };
+    if (host.includes('deepseek'))
+        return { DEEPSEEK_API_KEY: apiKey };
+    if (host.includes('moonshot') || host.includes('kimi'))
+        return { KIMI_API_KEY: apiKey, MOONSHOT_API_KEY: apiKey };
+    if (host.includes('minimax'))
+        return { MINIMAX_API_KEY: apiKey };
+    if (host.includes('zhipuai') || host.includes('z.ai') || host.includes('bigmodel'))
+        return { ZAI_API_KEY: apiKey, ZHIPU_API_KEY: apiKey };
+    if (host.includes('x.ai'))
+        return { XAI_API_KEY: apiKey };
+    if (host.includes('stepfun'))
+        return { STEPFUN_API_KEY: apiKey };
+    if (host.includes('dashscope') || host.includes('qwen'))
+        return { DASHSCOPE_API_KEY: apiKey, QWEN_API_KEY: apiKey };
+    if (host.includes('volces') || host.includes('volcengine') || host.includes('doubao'))
+        return { ARK_API_KEY: apiKey, DOUBAO_API_KEY: apiKey };
+    return { OPENROUTER_API_KEY: apiKey };
+}
+/** Pick the single env var Codex's `model_providers.<slug>.env_key` should reference. */
+function codexEnvKey(provider) {
+    const keys = Object.keys(providerCredentialEnv(provider, ''));
+    return keys[0] || 'OPENROUTER_API_KEY';
+}
+/** Escape a string for embedding inside a TOML double-quoted string literal. */
+function tomlEscape(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Anthropic-protocol baseURL: the SDK appends `/v1/messages` itself, so
+ * `ANTHROPIC_BASE_URL` must NOT carry a trailing `/v1` (otherwise requests
+ * land on `/v1/v1/messages` and 404). Providers (OpenRouter, DeepSeek, …)
+ * publish their endpoints with `/v1` for OpenAI-protocol callers, so we
+ * keep that as the canonical stored form and strip it here for Claude.
+ */
+function anthropicBaseURL(rawBaseURL) {
+    return rawBaseURL.replace(/\/+$/, '').replace(/\/v1$/, '');
+}
+/**
+ * Claude Code respects `ANTHROPIC_BASE_URL` + `ANTHROPIC_API_KEY` (or
+ * `ANTHROPIC_AUTH_TOKEN`) as a BYOK route. The CLI itself is unchanged.
+ * The model is overridden via opts.claudeModel (handled in stream.ts).
+ *
+ * For OpenAI-compatible providers (OpenRouter, DeepSeek native, …), the
+ * baseURL must point to an Anthropic-protocol-compatible endpoint
+ * (`/v1/messages`-shaped). OpenRouter's `/api/v1` and DeepSeek's
+ * `/anthropic/v1` both qualify.
+ */
+const claudeInjector = (provider, profile, apiKey) => {
+    if (provider.kind !== 'anthropic' && provider.kind !== 'openai-compatible') {
+        return {
+            ...EMPTY,
+            detail: `Claude BYOK requires Anthropic or OpenAI-compatible (Anthropic-API-shaped) provider; got ${provider.kind}.`,
+        };
+    }
+    return {
+        env: {
+            ANTHROPIC_BASE_URL: anthropicBaseURL(provider.baseURL),
+            ANTHROPIC_API_KEY: apiKey,
+            ANTHROPIC_AUTH_TOKEN: apiKey,
+        },
+        argvAppend: [],
+        modelOverride: profile.modelId,
+        detail: `Claude BYOK → ${provider.name} / ${profile.modelId}`,
+    };
+};
+/**
+ * Codex CLI honours `model_providers.<slug>` definitions in `config.toml`.
+ * Setting `OPENAI_BASE_URL` alone is not enough — Codex still routes through
+ * the default `openai` provider's auth flow. The robust path is to declare a
+ * one-shot `model_providers.<slug>` via `-c` overrides and bind it via
+ * `model_provider="<slug>"`. The credential lives in the env var named by
+ * `env_key`, picked host-aware (e.g. `OPENROUTER_API_KEY` for openrouter.ai).
+ *
+ * Note on `wire_api`: codex 0.130 dropped `"chat"` ("no longer supported"); we
+ * omit the field entirely so codex picks its current default (`responses`),
+ * which OpenRouter and other major OpenAI-compatible providers accept.
+ */
+const codexInjector = (provider, profile, apiKey) => {
+    if (provider.kind !== 'openai' && provider.kind !== 'openai-compatible') {
+        return {
+            ...EMPTY,
+            detail: `Codex BYOK requires OpenAI-compatible provider; got ${provider.kind}.`,
+        };
+    }
+    const slug = providerSlug(provider);
+    const envKey = codexEnvKey(provider);
+    const overrides = [
+        `model_providers.${slug}.name="${tomlEscape(provider.name)}"`,
+        `model_providers.${slug}.base_url="${tomlEscape(provider.baseURL)}"`,
+        `model_providers.${slug}.env_key="${envKey}"`,
+        `model_provider="${slug}"`,
+    ];
+    return {
+        env: { [envKey]: apiKey },
+        argvAppend: [],
+        codexConfigOverrides: overrides,
+        modelOverride: profile.modelId,
+        detail: `Codex BYOK → ${provider.name} / ${profile.modelId} (provider=${slug})`,
+    };
+};
+/** Gemini CLI accepts `GEMINI_API_KEY` but does not allow custom baseURL. */
+const geminiInjector = (provider, profile, apiKey) => {
+    if (provider.kind !== 'google') {
+        return {
+            ...EMPTY,
+            detail: `Gemini BYOK only supports Google AI Studio keys; got ${provider.kind}.`,
+        };
+    }
+    return {
+        env: { GEMINI_API_KEY: apiKey },
+        argvAppend: [],
+        modelOverride: profile.modelId,
+        detail: `Gemini BYOK → ${provider.name} / ${profile.modelId}`,
+    };
+};
+/**
+ * Hermes injector. Two channels:
+ *   1. Env vars carry the credential — `hermes acp` honours `OPENROUTER_API_KEY`,
+ *      `ANTHROPIC_API_KEY`, etc. just like the top-level `hermes` CLI.
+ *   2. The model is bound *per-session* by the driver via the ACP
+ *      `session/set_model` request — `hermes acp` does NOT accept `-m` /
+ *      `--provider` (only `--accept-hooks`); appending `-m` here used to make
+ *      every BYOK-bound spawn die with `unrecognized arguments`.
+ *
+ * The model is handed to the driver via `modelOverride` (an ACP-style
+ * `<provider>:<model>` string). The driver passes it to `session/set_model`
+ * after `session/new` returns; if the user has no Profile bound, no
+ * `set_model` call is made and Hermes uses its `~/.hermes/config.yaml`
+ * default.
+ */
+const hermesInjector = (provider, profile, apiKey) => {
+    const env = providerCredentialEnv(provider, apiKey);
+    const slug = providerSlug(provider);
+    // Only strip a leading `<slug>/` or `<slug>:` if the user accidentally
+    // stored a redundant provider prefix. Do NOT strip the *first segment* of
+    // a slash-separated model id wholesale — for OpenRouter the canonical
+    // model id is `vendor/model` (e.g. `deepseek/deepseek-v4-flash`), and
+    // dropping the `vendor/` part yields a non-existent model.
+    let bareModel = profile.modelId;
+    if (bareModel.startsWith(`${slug}/`) || bareModel.startsWith(`${slug}:`)) {
+        bareModel = bareModel.slice(slug.length + 1);
+    }
+    return {
+        env,
+        argvAppend: [],
+        modelOverride: `${slug}:${bareModel}`,
+        detail: `Hermes → ${provider.name} / ${profile.modelId}`,
+    };
+};
+const AGENT_INJECT_TABLE = {
+    claude: claudeInjector,
+    codex: codexInjector,
+    gemini: geminiInjector,
+    hermes: hermesInjector,
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the active Profile for an agent and return the spawn config to
+ * inject. Returns `null` when no Profile is bound (caller should fall back
+ * to the agent's native auth / default model).
+ */
+export async function resolveAgentInjection(agentId) {
+    const profile = getActiveProfile(agentId);
+    if (!profile)
+        return null;
+    const provider = getProvider(profile.providerId);
+    if (!provider)
+        return null;
+    const injector = AGENT_INJECT_TABLE[agentId];
+    if (!injector)
+        return null;
+    let apiKey;
+    try {
+        apiKey = await resolveCredential(provider.credential);
+    }
+    catch (e) {
+        throw new Error(`Failed to resolve credential for ${provider.name}: ${e?.message || e}`);
+    }
+    const result = await injector(provider, profile, apiKey);
+    // Attach the provider display name so renders can surface "via <provider>"
+    // — this is what tells the user the turn is going through a BYOK route.
+    result.providerName = provider.name;
+    // Attach the real context window from the provider's cached /models listing.
+    // Sync peek — no network blocking; on miss we kick off a fetch so the *next*
+    // session has it, and this turn falls back to the CLI's advertised value.
+    const cached = peekProviderModelInfo(provider.id, profile.modelId);
+    if (cached?.contextLength && cached.contextLength > 0) {
+        result.contextWindow = cached.contextLength;
+    }
+    else {
+        prefetchProviderModels(provider.id);
+    }
+    return result;
+}
+/** Returns `true` if the given agent is bound to a Profile. */
+export function isAgentBoundToProfile(agentId) {
+    return getActiveProfile(agentId) !== null;
+}

package/dist/model/provider-models.js

@@ -0,0 +1,112 @@
+/**
+ * Provider model-list cache.
+ *
+ * Backs the GET /api/models/providers/:id/models endpoint and the agent-status
+ * + IM /models surfaces. Each entry is a list of model ids the provider's
+ * /models endpoint reported, plus a fetch timestamp for TTL invalidation.
+ *
+ * Cache is in-memory only — providers' validation state already persists in
+ * setting.json; the model list itself can be re-fetched cheaply on demand.
+ */
+import { getProvider } from './store.js';
+import { validateProvider } from './validation.js';
+const TTL_MS = 30 * 60 * 1000; // 30 minutes
+// Cache is pinned to globalThis so module re-instantiation under tsx ESM
+// (e.g. when the same file is imported via different specifier strings) can't
+// fragment it into multiple disjoint maps. Without this, `getProviderModelList`
+// from `dashboard/routes/models.ts` (barrel) and `peekProviderModelList` from
+// `dashboard/routes/agents.ts` (also barrel) were writing/reading two
+// different Map instances, making the peek perpetually miss.
+// Cache pinned to globalThis so module re-instantiation under tsx ESM
+// (where the same file imported via different specifier strings ends up as
+// separate ESM module instances) can't fragment it into multiple disjoint
+// maps. Without this, `getProviderModelList` from `dashboard/routes/models.ts`
+// and `peekProviderModelList` from `dashboard/routes/agents.ts` would be
+// writing/reading two different Map instances and the peek would
+// perpetually miss.
+const GLOBAL_KEY = Symbol.for('pikiloop.providerModelsCache');
+const _existing = globalThis[GLOBAL_KEY];
+const cache = _existing || new Map();
+if (!_existing)
+    globalThis[GLOBAL_KEY] = cache;
+function isFresh(entry, provider) {
+    if (entry.providerUpdatedAt !== provider.updatedAt)
+        return false;
+    return (Date.now() - entry.fetchedAt) < TTL_MS;
+}
+/**
+ * Get the model list for a provider, fetching from /models on cache miss or
+ * when the provider config has been updated since the last fetch.
+ */
+export async function getProviderModelList(providerId, opts = {}) {
+    const provider = getProvider(providerId);
+    if (!provider)
+        return null;
+    const cached = cache.get(providerId);
+    if (!opts.forceRefresh && cached && isFresh(cached, provider)) {
+        return {
+            models: cached.models,
+            modelInfos: cached.modelInfos,
+            fetchedAt: cached.fetchedAt,
+            fromCache: true,
+        };
+    }
+    const result = await validateProvider(provider);
+    const entry = {
+        models: result.models,
+        modelInfos: result.modelInfos,
+        fetchedAt: Date.now(),
+        providerUpdatedAt: provider.updatedAt,
+    };
+    cache.set(providerId, entry);
+    return {
+        models: entry.models,
+        modelInfos: entry.modelInfos,
+        fetchedAt: entry.fetchedAt,
+        fromCache: false,
+    };
+}
+/**
+ * Invalidate cached model list (e.g. after a provider edit/delete).
+ */
+export function invalidateProviderModels(providerId) {
+    cache.delete(providerId);
+}
+/**
+ * Synchronous peek for a single model's cached metadata (context length,
+ * pricing). Returns `null` on cache miss or when the entry is stale relative
+ * to the provider's `updatedAt` — callers should treat that as "unknown" and
+ * fall back to whatever the agent CLI reports. Pair with
+ * `prefetchProviderModels` to populate the cache lazily for the next call.
+ */
+export function peekProviderModelInfo(providerId, modelId) {
+    const provider = getProvider(providerId);
+    if (!provider)
+        return null;
+    const entry = cache.get(providerId);
+    if (!entry || !isFresh(entry, provider))
+        return null;
+    return entry.modelInfos.find(info => info.id === modelId) ?? null;
+}
+/**
+ * Synchronous peek for the full cached model list of a provider. Returns
+ * `null` on cache miss / stale entry — callers should fall back and let a
+ * background refresh populate it (`prefetchProviderModels`).
+ */
+export function peekProviderModelList(providerId) {
+    const provider = getProvider(providerId);
+    if (!provider)
+        return null;
+    const entry = cache.get(providerId);
+    if (!entry || !isFresh(entry, provider))
+        return null;
+    return entry.modelInfos;
+}
+/**
+ * Fire-and-forget cache fill. Safe to call repeatedly: no-ops when the cache
+ * is already fresh, otherwise triggers a single in-flight fetch and discards
+ * the result (the next sync peek will see the populated cache).
+ */
+export function prefetchProviderModels(providerId) {
+    void getProviderModelList(providerId).catch(() => { });
+}

package/dist/model/store.js

@@ -0,0 +1,212 @@
+/**
+ * Persistence for Provider / Profile / activeProfileByAgent.
+ * Reads and writes the `models` section of ~/.pikiloop/setting.json.
+ */
+import { randomUUID } from 'node:crypto';
+import { loadUserConfig, saveUserConfig } from '../core/config/user-config.js';
+import { persistSecret, forgetSecret } from '../core/secrets/index.js';
+// ---------------------------------------------------------------------------
+// Read helpers
+// ---------------------------------------------------------------------------
+function getModelLayer() {
+    const config = loadUserConfig();
+    return config.models || {};
+}
+function writeModelLayer(layer) {
+    const config = loadUserConfig();
+    saveUserConfig({ ...config, models: layer });
+}
+export function listProviders() {
+    const layer = getModelLayer();
+    const map = layer.providers || {};
+    return Object.values(map).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export function getProvider(id) {
+    const layer = getModelLayer();
+    return layer.providers?.[id] || null;
+}
+export async function addProvider(input) {
+    if (!input.apiKey && !input.credentialRef) {
+        throw new Error('addProvider requires either apiKey or credentialRef');
+    }
+    const id = randomUUID();
+    const credential = input.credentialRef
+        ? input.credentialRef
+        : await persistSecret(`provider/${id}`, input.apiKey);
+    const now = new Date().toISOString();
+    const provider = {
+        id,
+        kind: input.kind,
+        name: input.name.trim(),
+        baseURL: input.baseURL.trim().replace(/\/+$/, ''),
+        credential,
+        extraHeaders: input.extraHeaders && Object.keys(input.extraHeaders).length ? input.extraHeaders : undefined,
+        validation: null,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const layer = getModelLayer();
+    const providers = { ...(layer.providers || {}) };
+    providers[id] = provider;
+    writeModelLayer({ ...layer, providers });
+    return provider;
+}
+export async function updateProvider(id, patch) {
+    const layer = getModelLayer();
+    const providers = { ...(layer.providers || {}) };
+    const existing = providers[id];
+    if (!existing)
+        throw new Error(`Provider not found: ${id}`);
+    let credential = existing.credential;
+    if (patch.credentialRef)
+        credential = patch.credentialRef;
+    else if (patch.apiKey !== undefined) {
+        if (existing.credential.source === 'keychain') {
+            // overwrite same keychain slot
+            credential = await persistSecret(existing.credential.account, patch.apiKey);
+        }
+        else {
+            // upgrade from inline/env/command to keychain
+            credential = await persistSecret(`provider/${id}`, patch.apiKey);
+        }
+    }
+    const next = {
+        ...existing,
+        name: patch.name?.trim() ?? existing.name,
+        baseURL: patch.baseURL?.trim().replace(/\/+$/, '') ?? existing.baseURL,
+        credential,
+        extraHeaders: patch.extraHeaders === null
+            ? undefined
+            : patch.extraHeaders ?? existing.extraHeaders,
+        validation: patch.apiKey !== undefined || patch.credentialRef ? null : existing.validation,
+        updatedAt: new Date().toISOString(),
+    };
+    providers[id] = next;
+    writeModelLayer({ ...layer, providers });
+    return next;
+}
+export async function removeProvider(id) {
+    const layer = getModelLayer();
+    const providers = { ...(layer.providers || {}) };
+    const existing = providers[id];
+    if (!existing)
+        return false;
+    delete providers[id];
+    // also drop any profiles bound to this provider
+    const profiles = { ...(layer.profiles || {}) };
+    for (const [pid, prof] of Object.entries(profiles)) {
+        if (prof.providerId === id)
+            delete profiles[pid];
+    }
+    // and any active bindings
+    const bindings = { ...(layer.activeProfileByAgent || {}) };
+    for (const agentId of Object.keys(bindings)) {
+        const profileId = bindings[agentId];
+        if (profileId && !profiles[profileId])
+            bindings[agentId] = null;
+    }
+    writeModelLayer({ ...layer, providers, profiles, activeProfileByAgent: bindings });
+    await forgetSecret(existing.credential).catch(() => { });
+    return true;
+}
+export function setProviderValidation(id, status) {
+    const layer = getModelLayer();
+    const providers = { ...(layer.providers || {}) };
+    const existing = providers[id];
+    if (!existing)
+        return;
+    providers[id] = { ...existing, validation: status, updatedAt: new Date().toISOString() };
+    writeModelLayer({ ...layer, providers });
+}
+export function listProfiles() {
+    const layer = getModelLayer();
+    return Object.values(layer.profiles || {}).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export function getProfile(id) {
+    const layer = getModelLayer();
+    return layer.profiles?.[id] || null;
+}
+function defaultProfileName(_providerName, modelId, _effort) {
+    // Keep the auto-generated label short: the brand icon already carries the
+    // provider, and effort lives in its own pill on the card. Just the model id
+    // gives the cleanest tile + IM list, with the user free to override.
+    return modelId;
+}
+export function addProfile(input) {
+    const layer = getModelLayer();
+    const provider = layer.providers?.[input.providerId];
+    if (!provider)
+        throw new Error(`Provider not found: ${input.providerId}`);
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    const profile = {
+        id,
+        name: input.name?.trim() || defaultProfileName(provider.name, input.modelId, input.effort),
+        providerId: input.providerId,
+        modelId: input.modelId.trim(),
+        effort: input.effort ?? null,
+        maxOutputTokens: input.maxOutputTokens ?? null,
+        extras: input.extras,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const profiles = { ...(layer.profiles || {}) };
+    profiles[id] = profile;
+    writeModelLayer({ ...layer, profiles });
+    return profile;
+}
+export function updateProfile(id, patch) {
+    const layer = getModelLayer();
+    const profiles = { ...(layer.profiles || {}) };
+    const existing = profiles[id];
+    if (!existing)
+        throw new Error(`Profile not found: ${id}`);
+    const next = {
+        ...existing,
+        ...('name' in patch && patch.name !== undefined ? { name: patch.name.trim() || existing.name } : {}),
+        ...('modelId' in patch && patch.modelId !== undefined ? { modelId: patch.modelId.trim() } : {}),
+        ...('effort' in patch ? { effort: patch.effort ?? null } : {}),
+        ...('maxOutputTokens' in patch ? { maxOutputTokens: patch.maxOutputTokens ?? null } : {}),
+        ...('extras' in patch ? { extras: patch.extras } : {}),
+        updatedAt: new Date().toISOString(),
+    };
+    profiles[id] = next;
+    writeModelLayer({ ...layer, profiles });
+    return next;
+}
+export function removeProfile(id) {
+    const layer = getModelLayer();
+    const profiles = { ...(layer.profiles || {}) };
+    if (!profiles[id])
+        return false;
+    delete profiles[id];
+    const bindings = { ...(layer.activeProfileByAgent || {}) };
+    for (const agentId of Object.keys(bindings)) {
+        if (bindings[agentId] === id)
+            bindings[agentId] = null;
+    }
+    writeModelLayer({ ...layer, profiles, activeProfileByAgent: bindings });
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Active binding
+// ---------------------------------------------------------------------------
+export function getActiveProfileId(agentId) {
+    const layer = getModelLayer();
+    return layer.activeProfileByAgent?.[agentId] || null;
+}
+export function getActiveProfile(agentId) {
+    const id = getActiveProfileId(agentId);
+    if (!id)
+        return null;
+    return getProfile(id);
+}
+export function setActiveProfile(agentId, profileId) {
+    const layer = getModelLayer();
+    if (profileId && !layer.profiles?.[profileId]) {
+        throw new Error(`Profile not found: ${profileId}`);
+    }
+    const bindings = { ...(layer.activeProfileByAgent || {}) };
+    bindings[agentId] = profileId;
+    writeModelLayer({ ...layer, activeProfileByAgent: bindings });
+}

package/dist/model/types.js

@@ -0,0 +1,13 @@
+/**
+ * Pikiloop "Model" layer — Provider/Profile data model.
+ *
+ *   Provider  = a configured endpoint + credential reference (e.g. "OpenRouter
+ *               personal", "Anthropic direct"). Holds baseURL + extra headers.
+ *   Profile   = a Provider + modelId + tuning params (effort, max output).
+ *               This is the unit a user binds to an agent.
+ *
+ * Profiles are the smallest selectable unit because Hermes (and most coding
+ * agents) only support one model per session. Binding `activeProfileByAgent`
+ * tells the driver which Profile to use when spawning that agent.
+ */
+export {};