flashlite 0.0.0-stage → 0.1.0

package/dist/config.js

@@ -0,0 +1,206 @@
+// Config loading. API credentials are read only from ~/.config/flashlite/config.json.
+// The real key is never logged or printed — not even in masked form (see CLAUDE.md).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseEffort } from "./effort.js";
+import { DEFAULT_TOOL_RESULT_BUDGET_BYTES } from "./contextbudget.js";
+const DEFAULTS = {
+    base_url: '',
+    api_key: null,
+    default_model: null,
+    reasoning_effort: 'auto',
+    max_output_tokens: 8192,
+    max_context_tokens: 32_000,
+    tool_result_budget_bytes: DEFAULT_TOOL_RESULT_BUDGET_BYTES,
+    auto_approve: false,
+    compact_context_remaining_percent: 60,
+    permission_mode: 'ask',
+    token_saver: 'off',
+    boost_mode: false,
+    // Schemas are resent every round; drop the two tools whose behaviour is
+    // already covered by write_file (parent creation) and run_command (stat).
+    disabled_tools: ['make_dir', 'file_info'],
+};
+/** The endpoint this build shipped before it became provider-agnostic (migration only). */
+const LEGACY_SUBROUTER_BASE_URL = 'https://router.eva.pink/v1';
+export const CONFIG_VERSION = 3;
+/** Values older versions wrote into config.json as their defaults; version 2 replaces them. */
+const LEGACY_DEFAULTS = { maxContext: null, compactPercent: 15, toolBudget: 65_536 };
+/**
+ * Validate and normalize an endpoint root: http(s) only, no credentials, query or fragment.
+ * Trailing slashes are stripped. Returns null when the value is unusable. The path is kept
+ * as given, so providers that need /v1 (or /api/v1) work and those that do not are untouched.
+ */
+export function normalizeBaseUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const text = value.trim();
+    if (!text || text.includes('?') || text.includes('#'))
+        return null;
+    try {
+        const url = new URL(text);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+            return null;
+        return text.replace(/\/+$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+export function configDir() {
+    return path.join(os.homedir(), '.config', 'flashlite');
+}
+export function configPath() {
+    return path.join(configDir(), 'config.json');
+}
+function loadConfigFile() {
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath(), 'utf8');
+    }
+    catch {
+        return null; // no file yet — normal on first run
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        return { ...DEFAULTS, ...parsed };
+    }
+    catch {
+        return null; // corrupt file — caller warns
+    }
+}
+/** Merge a patch into the config file, creating it (chmod 600) if needed. */
+export function saveConfigFile(patch) {
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = configPath();
+    const loaded = loadConfigFile();
+    if (loaded === null && fs.existsSync(file)) {
+        // Unreadable or corrupt config: keep a copy rather than silently discarding the saved key.
+        try {
+            fs.copyFileSync(file, file + '.bak');
+            fs.chmodSync(file + '.bak', 0o600);
+        }
+        catch { /* best effort */ }
+    }
+    const next = { ...(loaded ?? DEFAULTS), ...patch };
+    // Write privately from the first byte (no world-readable window) and replace atomically,
+    // so a crash mid-write can never leave a truncated config.
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+}
+/**
+ * One-time upgrade of an existing config.json. Older versions saved their defaults into the
+ * file, so changing a default in code never reached existing users. Only values still equal
+ * to the old defaults are replaced (a deliberate custom value is left alone), then the file
+ * is stamped with CONFIG_VERSION so later manual choices are never overridden again.
+ * Returns human-readable notes for what changed.
+ */
+export function migrateConfigFile() {
+    const file = loadConfigFile();
+    if (file === null || (typeof file.config_version === 'number' && file.config_version >= CONFIG_VERSION))
+        return [];
+    const patch = { config_version: CONFIG_VERSION };
+    const notes = [];
+    if (file.max_context_tokens === LEGACY_DEFAULTS.maxContext) {
+        patch.max_context_tokens = DEFAULTS.max_context_tokens;
+        notes.push(`max context ${DEFAULTS.max_context_tokens} tokens`);
+    }
+    if (file.compact_context_remaining_percent === LEGACY_DEFAULTS.compactPercent) {
+        patch.compact_context_remaining_percent = DEFAULTS.compact_context_remaining_percent;
+        notes.push(`auto-compaction at ${DEFAULTS.compact_context_remaining_percent}% remaining`);
+    }
+    if (file.tool_result_budget_bytes === LEGACY_DEFAULTS.toolBudget) {
+        patch.tool_result_budget_bytes = DEFAULTS.tool_result_budget_bytes;
+        notes.push(`tool-result replay ${DEFAULTS.tool_result_budget_bytes} bytes`);
+    }
+    // Drop the old built-in endpoint so the next launch asks which provider to use.
+    if (file.base_url === LEGACY_SUBROUTER_BASE_URL) {
+        patch.base_url = '';
+        notes.push('endpoint cleared (set it again on the next launch)');
+    }
+    try {
+        saveConfigFile(patch);
+    }
+    catch {
+        return [];
+    } // advisory: never block startup
+    return notes.length ? [`config updated to lower-token defaults (${notes.join(', ')}) · change any of them in /settings`] : [];
+}
+/** Endpoint precedence: overrideBaseUrl (--base-url) > FLASHLITE_BASE_URL > config file. Empty means unset. */
+export function resolveConfig(overrideBaseUrl) {
+    const warnings = [];
+    const file = loadConfigFile();
+    if (file === null && fs.existsSync(configPath())) {
+        warnings.push('config file is unreadable or invalid — using defaults');
+    }
+    if (file && 'max_tool_rounds' in file) {
+        warnings.push('max_tool_rounds is no longer supported — the tool-round limit was removed; the key is ignored');
+    }
+    const reasoningEffort = parseEffort(file?.reasoning_effort) ?? DEFAULTS.reasoning_effort;
+    if (file && parseEffort(file.reasoning_effort) === undefined)
+        warnings.push('invalid reasoning_effort in config — using auto');
+    const compactThreshold = file?.compact_context_remaining_percent;
+    const compactContextRemainingPercent = typeof compactThreshold === 'number' && Number.isInteger(compactThreshold) && compactThreshold >= 0 && compactThreshold <= 90
+        ? compactThreshold : DEFAULTS.compact_context_remaining_percent;
+    if (file && compactThreshold !== undefined && compactContextRemainingPercent !== compactThreshold)
+        warnings.push(`invalid compact_context_remaining_percent in config — using ${DEFAULTS.compact_context_remaining_percent}`);
+    const field = (name, valid, fallback) => {
+        const value = file?.[name];
+        if (value === undefined)
+            return fallback;
+        if (valid(value))
+            return value;
+        warnings.push(`invalid ${name} in config — using default`);
+        return fallback;
+    };
+    const optionalText = (value) => value === null || typeof value === 'string';
+    const httpUrl = (value) => normalizeBaseUrl(value) !== null;
+    const boundedInteger = (min, max) => (value) => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max;
+    const fileKey = field('api_key', optionalText, null)?.trim() || null;
+    const defaultModel = field('default_model', optionalText, null)?.trim() || null;
+    const fileBaseUrl = normalizeBaseUrl(field('base_url', (value) => value === '' || httpUrl(value), DEFAULTS.base_url)) ?? '';
+    const envRaw = process.env.FLASHLITE_BASE_URL?.trim();
+    const envBaseUrl = envRaw ? normalizeBaseUrl(envRaw) : null;
+    if (envRaw && !envBaseUrl)
+        warnings.push('invalid FLASHLITE_BASE_URL — ignoring it');
+    const flagBaseUrl = overrideBaseUrl ? normalizeBaseUrl(overrideBaseUrl) : null;
+    const baseUrl = flagBaseUrl ?? envBaseUrl ?? fileBaseUrl;
+    const baseUrlSource = flagBaseUrl ? 'flag' : envBaseUrl ? 'env' : fileBaseUrl ? 'config' : 'unset';
+    const maxOutputTokens = field('max_output_tokens', boundedInteger(256, 65536), DEFAULTS.max_output_tokens);
+    const maxContextTokens = field('max_context_tokens', (value) => value === null || (typeof value === 'number' && Number.isInteger(value) && value >= 1024 && value <= 1_000_000), DEFAULTS.max_context_tokens);
+    const toolResultBudgetBytes = field('tool_result_budget_bytes', boundedInteger(0, 4_000_000), DEFAULTS.tool_result_budget_bytes);
+    const autoApprove = field('auto_approve', (value) => typeof value === 'boolean', false);
+    // Fail closed: an unrecognized permission_mode falls back to ask; never widen.
+    const permissionMode = field('permission_mode', (value) => typeof value === 'string' && ['ask', 'files', 'auto', 'unguarded'].includes(value), DEFAULTS.permission_mode);
+    const tokenSaver = field('token_saver', (value) => value === 'off' || value === 'low' || value === 'high' || value === 'custom', 'off');
+    const boostMode = field('boost_mode', (value) => typeof value === 'boolean', false);
+    const promptCaching = field('prompt_caching', (value) => typeof value === 'boolean', true);
+    const disabledTools = field('disabled_tools', (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string'), DEFAULTS.disabled_tools ?? []);
+    return {
+        config: {
+            baseUrl,
+            apiKey: fileKey ?? '',
+            defaultModel,
+            reasoningEffort,
+            maxOutputTokens,
+            maxContextTokens,
+            toolResultBudgetBytes,
+            autoApprove,
+            compactContextRemainingPercent,
+            permissionMode,
+            tokenSaver,
+            boostMode,
+            configPath: file ? configPath() : null,
+            baseUrlSource,
+            promptCaching,
+            disabledTools,
+        },
+        warnings,
+    };
+}

package/dist/contextbudget.js

@@ -0,0 +1,201 @@
+// contextbudget.ts — bound how much earlier tool output is replayed to the model.
+//
+// The agent loop re-sends the whole conversation on every tool round, so without a
+// ceiling a turn that reads a few files re-uploads every earlier result again and
+// again (roughly rounds × results). This module builds the *replay view* of history
+// used for provider requests: the newest tool results are kept whole up to a per-result
+// cap (anything larger is replayed cropped head+tail), and older ones are replaced with a
+// short stub once their combined content exceeds a byte budget.
+//
+// It never mutates the canonical history, and only ever touches `tool` message
+// content: role, toolCallId, ordering and tool_call/tool_result pairing are preserved,
+// so the transcript and every downstream consumer still see the full results. The
+// model can re-run a tool if it still needs an elided result.
+/** Default ceiling for the sum of replayed tool-result bytes (~2K tokens at 4 chars/token). */
+export const DEFAULT_TOOL_RESULT_BUDGET_BYTES = 8_192;
+/**
+ * Hard ceiling for any single replayed tool result (~1K tokens at 4 chars/token). A command
+ * that prints tens of KB is cropped head+tail to this even when it is the newest result and
+ * therefore exempt from the sum budget: without it, one terminal command can spike the
+ * context by ~10k tokens and make the meter rise and fall as it is displaced and elided.
+ */
+export const DEFAULT_TOOL_RESULT_MAX_BYTES = 4_096;
+const ELISION_PREFIX = '[earlier tool result elided to save context:';
+// Marker inserted where a per-result crop dropped the middle of an oversized result. Kept
+// in the middle (not the prefix) so the retained head still lines up with any prior cache.
+const CROP_PREFIX = '[tool result cropped to save context:';
+/**
+ * Sticky, batched elision. The plain mode above moves its cut-off a little every round,
+ * which rewrites an early message each time and defeats provider prefix caching (the
+ * cached prefix must be byte-identical). Here a result, once elided, stays elided, and
+ * nothing is elided until the live results exceed the budget; then the oldest are dropped
+ * in one batch down to half the budget. The start of every request is therefore identical
+ * for many rounds in a row, and the cache is only invalidated once per batch.
+ */
+function boundSticky(history, budgetBytes, state) {
+    const limit = perResultLimit(budgetBytes);
+    const live = [];
+    let kept = 0;
+    for (const message of history) {
+        if (message.role !== 'tool' || state.has(message))
+            continue;
+        live.push(message);
+        // Count each result at most `limit` bytes: an oversized newest result is replayed
+        // cropped, so it cannot push the live total far past the budget on its own.
+        kept += Math.min(message.content.length, limit);
+    }
+    if (kept > budgetBytes) {
+        const target = Math.floor(budgetBytes / 2);
+        // The newest result is always kept (cropped to `limit` at most); older ones are elided.
+        for (let i = 0; i < live.length - 1 && kept > target; i++) {
+            state.add(live[i]);
+            kept -= Math.min(live[i].content.length, limit);
+        }
+    }
+    let view;
+    for (let i = 0; i < history.length; i++) {
+        const message = history[i];
+        if (message.role !== 'tool')
+            continue;
+        if (state.has(message)) {
+            view ??= history.slice();
+            view[i] = isElidedToolResult(message.content) ? message : { ...message, content: elisionStub(message.content.length) };
+        }
+        else if (message.content.length > limit) {
+            view ??= history.slice();
+            view[i] = { ...message, content: cropToolResult(message.content, limit) };
+        }
+    }
+    return view ?? history;
+}
+/** True for contents already replaced by a stub, so elision is idempotent. */
+export function isElidedToolResult(content) {
+    return content.startsWith(ELISION_PREFIX);
+}
+function elisionStub(bytes) {
+    return `${ELISION_PREFIX} ${bytes} bytes; re-run the tool if you need it again]`;
+}
+/** True for contents already cropped, so cropping is idempotent and prefix-cache stable. */
+export function isCroppedToolResult(content) {
+    return content.includes(CROP_PREFIX);
+}
+/** Byte ceiling for a single replayed result: the fixed ceiling, never more than the budget. */
+function perResultLimit(budgetBytes) {
+    return Math.max(1, Math.min(DEFAULT_TOOL_RESULT_MAX_BYTES, budgetBytes));
+}
+/**
+ * Cap one result by keeping its head and tail and marking the dropped middle. Pure and
+ * deterministic: the same content always crops to the same bytes, so provider prefix
+ * caching is not disturbed.
+ */
+function cropToolResult(content, limit) {
+    if (content.length <= limit || isCroppedToolResult(content))
+        return content;
+    const headBytes = Math.ceil(limit / 2);
+    const tailBytes = limit - headBytes;
+    const omitted = content.length - limit;
+    return `${content.slice(0, headBytes)}\n${CROP_PREFIX} ${omitted} bytes; narrow the tool call if you need the middle]\n${content.slice(content.length - tailBytes)}`;
+}
+const ASSISTANT_ELISION_PREFIX = '[earlier assistant message elided to save context:';
+/** True for assistant contents already replaced by a stub, so elision is idempotent. */
+export function isElidedAssistantMessage(content) {
+    return content.startsWith(ASSISTANT_ELISION_PREFIX);
+}
+function assistantStub(bytes) {
+    return `${ASSISTANT_ELISION_PREFIX} ${bytes} bytes]`;
+}
+/**
+ * Assistant text is safe to stub only when it carries nothing the wire requires: no
+ * tool_calls (tool_call/tool_result pairing), no signed thinking blocks, no replayed
+ * reasoning, no images, and no content already elided.
+ */
+function isElidableAssistant(message) {
+    return message.role === 'assistant'
+        && message.content.length > 0
+        && !isElidedAssistantMessage(message.content)
+        && !message.toolCalls?.length
+        && !message.thinkingBlocks?.length
+        && !message.reasoningContent
+        && !message.images?.length;
+}
+/**
+ * Sticky companion to boundToolResults: stubs older *assistant prose* once its combined
+ * size exceeds the budget, keeping the newest assistant text whole and marking elided
+ * messages in the shared state so the cached prefix stays byte-identical between rounds.
+ * Only plain-text assistant messages are eligible; tool-call/thinking/reasoning messages
+ * are left untouched so pairing and signed blocks survive.
+ */
+function boundAssistantProseSticky(history, budgetBytes, state) {
+    const live = [];
+    let kept = 0;
+    for (const message of history) {
+        if (!isElidableAssistant(message) || state.has(message))
+            continue;
+        live.push(message);
+        kept += message.content.length;
+    }
+    if (kept > budgetBytes) {
+        const target = Math.floor(budgetBytes / 2);
+        // The newest assistant prose is always kept whole.
+        for (let i = 0; i < live.length - 1 && kept > target; i++) {
+            state.add(live[i]);
+            kept -= live[i].content.length;
+        }
+    }
+    let view;
+    for (let i = 0; i < history.length; i++) {
+        const message = history[i];
+        if (message.role !== 'assistant' || !state.has(message))
+            continue;
+        view ??= history.slice();
+        view[i] = isElidedAssistantMessage(message.content) ? message : { ...message, content: assistantStub(message.content.length) };
+    }
+    return view ?? history;
+}
+/**
+ * Replay view for provider requests: recent tool results (and, when enabled, assistant
+ * prose) are kept whole and older ones elided. Falls back to the tool-only view when
+ * assistant-prose elision is off or no sticky state was supplied.
+ */
+export function boundReplay(history, budgetBytes = DEFAULT_TOOL_RESULT_BUDGET_BYTES, state, options) {
+    const toolView = boundToolResults(history, budgetBytes, state);
+    if (!options?.assistantProse || !state)
+        return toolView;
+    return boundAssistantProseSticky(toolView, budgetBytes, state);
+}
+/**
+ * Return a replay copy of `history` with old tool results elided to fit `budgetBytes`.
+ * The newest tool result is always kept whole up to a per-result cap (DEFAULT_TOOL_RESULT_MAX_BYTES);
+ * anything larger is replayed cropped head+tail so one big command cannot blow up a
+ * request. Older results are kept, newest-first, until the budget is reached, then
+ * replaced with a stub. budgetBytes <= 0 disables elision and returns the original array
+ * unchanged. Non-tool messages and message identity are never altered.
+ */
+export function boundToolResults(history, budgetBytes = DEFAULT_TOOL_RESULT_BUDGET_BYTES, state) {
+    if (!Number.isFinite(budgetBytes) || budgetBytes <= 0)
+        return history;
+    if (state)
+        return boundSticky(history, budgetBytes, state);
+    const limit = perResultLimit(budgetBytes);
+    let kept = 0;
+    let keptAny = false;
+    let view;
+    for (let index = history.length - 1; index >= 0; index--) {
+        const message = history[index];
+        if (message.role !== 'tool')
+            continue;
+        const size = Math.min(message.content.length, limit);
+        if (!keptAny || kept + size <= budgetBytes) {
+            kept += size;
+            keptAny = true;
+            if (message.content.length > limit) {
+                view ??= history.slice();
+                view[index] = { ...message, content: cropToolResult(message.content, limit) };
+            }
+            continue;
+        }
+        view ??= history.slice();
+        view[index] = { ...message, content: elisionStub(message.content.length) };
+    }
+    return view ?? history;
+}

package/dist/customcommands.js

@@ -0,0 +1,105 @@
+// Custom slash commands: markdown prompt templates discovered from the user's command
+// directory (~/.config/flashlite/commands) and the project's .flashlite/commands directory.
+// A file's body is a prompt template; `$1`..`$9` substitute positional arguments and
+// `$ARGS` substitutes all arguments joined by spaces. No shell interpolation is performed
+// (prompt text is data, not a script). Frontmatter is optional:
+//   ---
+//   description: Short one-liner for the palette
+//   argument-hint: "[query]"
+//   ---
+import fs from 'node:fs';
+import path from 'node:path';
+import { configDir } from "./config.js";
+const MAX_BODY_BYTES = 64 * 1024;
+const NAME = /^[a-z0-9][a-z0-9_-]*$/i;
+function splitFrontmatter(raw) {
+    const normalized = raw.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const match = /^---\n([\s\S]*?)\n---\n?/.exec(normalized);
+    if (!match)
+        return { meta: {}, body: normalized.trim() };
+    const meta = {};
+    for (const line of match[1].split('\n')) {
+        const sep = line.indexOf(':');
+        if (sep === -1)
+            continue;
+        const key = line.slice(0, sep).trim();
+        const value = line.slice(sep + 1).trim();
+        if (key === 'description')
+            meta.description = value;
+        else if (key === 'argument-hint' || key === 'argumentHint')
+            meta.argumentHint = value;
+    }
+    return { meta, body: normalized.slice(match[0].length).trim() };
+}
+/** Directory lists are read with a symlink guard; a malformed entry is skipped, not fatal. */
+function readCommandFiles(dir, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const name = entry.name.slice(0, -3);
+        if (!NAME.test(name))
+            continue;
+        const source = path.join(dir, entry.name);
+        let stat;
+        try {
+            stat = fs.lstatSync(source);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_BODY_BYTES)
+            continue;
+        let raw;
+        try {
+            raw = fs.readFileSync(source, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { meta, body } = splitFrontmatter(raw);
+        if (!body)
+            continue;
+        out.push({
+            name,
+            description: meta.description ?? '',
+            argumentHint: meta.argumentHint,
+            body,
+            source,
+        });
+    }
+}
+/** Discover global + project custom commands. Project commands shadow global ones by name. */
+export function discoverCustomCommands(cwd) {
+    const global = path.join(configDir(), 'commands');
+    const project = path.join(cwd, '.flashlite', 'commands');
+    const found = [];
+    readCommandFiles(global, found);
+    readCommandFiles(project, found);
+    const byName = new Map();
+    for (const command of found)
+        byName.set(command.name, command); // later (project) wins
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findCustomCommand(commands, name) {
+    return commands.find((command) => command.name === name);
+}
+/** Substitute `$1`..`$9` and `$ARGS` into a command body. Unknown positions become ''. */
+export function renderCustomCommand(body, args) {
+    return body
+        .replace(/\$ARGS\b/g, args.join(' '))
+        .replace(/\$([1-9])\b/g, (_, digit) => args[Number(digit) - 1] ?? '');
+}
+/** Palette entries for the `/` menu; ids carry a trailing space hint when args are expected. */
+export function customCommandPalette(commands) {
+    return commands.map((command) => ({
+        id: `/${command.name}${command.argumentHint ? ' ' : ''}`,
+        description: command.description || 'custom command',
+    }));
+}

package/dist/effort.js

@@ -0,0 +1,79 @@
+export const EFFORT_LEVELS = ['auto', 'low', 'medium', 'high', 'xhigh', 'max'];
+export const EFFORT_DESCRIPTIONS = {
+    auto: 'Use the provider default',
+    low: 'Fast, lightweight reasoning',
+    medium: 'Balance reasoning and latency',
+    high: 'More thorough reasoning',
+    xhigh: 'Extra-high reasoning · model support varies',
+    max: 'Maximum reasoning · model support varies',
+};
+const THINKING_BUDGETS = { low: 2048, medium: 4096, high: 8192, xhigh: 16384, max: 32000 };
+export function anthropicThinkingBudget(effort) {
+    return effort && effort !== 'auto' ? THINKING_BUDGETS[effort] : undefined;
+}
+/** Match the adapter's actual wire output ceiling when reserving context space. */
+export function effectiveOutputTokens(dialect, maxTokens, effort) {
+    const budget = dialect === 'anthropic' ? anthropicThinkingBudget(effort) : undefined;
+    return budget ? Math.max(maxTokens, budget + 4096) : maxTokens;
+}
+export function parseEffort(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const level = value.trim().toLowerCase();
+    return EFFORT_LEVELS.find((effort) => effort === level);
+}
+/** True when the model id is any DeepSeek model (base or pro). */
+export function isDeepSeek(model) {
+    return model.toLowerCase().includes('deepseek');
+}
+/** True when the DeepSeek model id is a `pro` variant (e.g. `deepseek-pro-…`). */
+function isDeepSeekPro(model) {
+    // Match a `pro` token in the same path segment as the deepseek id so an unrelated
+    // `proxy`/`prompt` path segment cannot misclassify a base model as pro.
+    return model.toLowerCase().split('/').some((segment) => segment.includes('deepseek') && /(^|[-_.])pro($|[-_.])/.test(segment));
+}
+/**
+ * The reasoning_effort value to put on the wire for a DeepSeek model, mapping CLI
+ * levels onto the provider's real thinking levels. Returns undefined (omit the field)
+ * for `auto`. Non-DeepSeek models should send `req.effort` verbatim via the adapter.
+ */
+export function deepSeekWireEffort(model, effort) {
+    if (!effort || effort === 'auto')
+        return undefined;
+    if (isDeepSeekPro(model)) {
+        // DeepSeek pro only accepts high/max.
+        switch (effort) {
+            case 'low':
+            case 'medium':
+            case 'high':
+                return 'high';
+            case 'xhigh':
+            case 'max':
+                return 'max';
+            default:
+                return undefined;
+        }
+    }
+    // Base DeepSeek accepts low/high/max only. Its documented effort mapping rounds
+    // `medium`/`xhigh` up to `high` (medium→high, xhigh→high); CLI `low`/`max` pass through.
+    switch (effort) {
+        case 'low':
+            return 'low';
+        case 'medium':
+        case 'high':
+        case 'xhigh':
+            return 'high';
+        case 'max':
+            return 'max';
+        default:
+            return undefined;
+    }
+}
+/** The effort levels the UI may offer for the current model. */
+export function effortLevelsFor(model) {
+    if (isDeepSeekPro(model))
+        return ['auto', 'high', 'max'];
+    if (isDeepSeek(model))
+        return ['auto', 'low', 'high', 'max'];
+    return EFFORT_LEVELS;
+}

package/dist/hooks.js

@@ -0,0 +1,86 @@
+// Lifecycle hooks (Claude Code style): executable scripts discovered in
+// ~/.config/flashlite/hooks and <project>/.flashlite/hooks. A hook reads one JSON object on
+// stdin and may write a JSON object on stdout. PreToolUse may veto a tool with
+// {"decision":"block","reason":"…"}; any other output is advisory. Hooks are untrusted and
+// time-boxed; a hung or failing hook never blocks the tool (fail open, with a notice).
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { configDir } from "./config.js";
+const HOOK_TIMEOUT_MS = 10_000;
+function readHooks(dir, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || entry.isSymbolicLink())
+            continue;
+        const event = entry.name;
+        if (!['PreToolUse', 'PostToolUse', 'Notification', 'Stop'].includes(event))
+            continue;
+        out.push({ event, path: path.join(dir, entry.name) });
+    }
+}
+/** Discover hooks; project hooks append to global hooks (both run, project last). */
+export function discoverHooks(cwd) {
+    const hooks = [];
+    readHooks(path.join(configDir(), 'hooks'), hooks);
+    readHooks(path.join(cwd, '.flashlite', 'hooks'), hooks);
+    return hooks;
+}
+/** Run a single hook script with `payload` (JSON) on stdin; resolves after it exits. */
+function runOne(scriptPath, payload) {
+    return new Promise((resolve) => {
+        const child = spawn('/bin/zsh', ['-f', '-c', `exec "${scriptPath}"`], {
+            stdio: ['pipe', 'pipe', 'ignore'],
+            env: { ...process.env },
+        });
+        const timer = setTimeout(() => { child.kill('SIGKILL'); }, HOOK_TIMEOUT_MS);
+        let stdout = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+        child.on('error', () => { clearTimeout(timer); resolve({ blocked: false }); });
+        child.on('close', () => {
+            clearTimeout(timer);
+            const trimmed = stdout.trim();
+            let parsed;
+            if (trimmed) {
+                try {
+                    parsed = JSON.parse(trimmed);
+                }
+                catch { /* non-JSON output is advisory */ }
+            }
+            if (parsed && typeof parsed === 'object' && parsed.decision === 'block') {
+                const reason = typeof parsed.reason === 'string' ? parsed.reason : 'blocked by hook';
+                resolve({ blocked: true, reason, output: trimmed });
+            }
+            else {
+                resolve({ blocked: false, output: trimmed || undefined });
+            }
+        });
+        child.stdin.on('error', () => { });
+        child.stdin.end(JSON.stringify(payload));
+    });
+}
+/** Run every hook for `event`; PreToolUse merges block decisions (first blocker wins). */
+export async function runHooks(hooks, event, payload) {
+    const matching = hooks.filter((hook) => hook.event === event);
+    const results = [];
+    for (const hook of matching)
+        results.push(await runOne(hook.path, payload));
+    return results;
+}
+/** macOS notification via osascript; best-effort and never throws. */
+export function notifyMac(title, body) {
+    if (process.platform !== 'darwin')
+        return;
+    const script = `display notification ${JSON.stringify(body.slice(0, 200))} with title ${JSON.stringify(title)}`;
+    try {
+        const child = spawn('/usr/bin/osascript', ['-e', script], { stdio: 'ignore' });
+        child.unref();
+    }
+    catch { /* notifications are advisory */ }
+}