freddie 0.0.41

package/src/agent/pi-bridge.js

@@ -0,0 +1,37 @@
+import { logger } from '../observability/log.js'
+
+const log = logger('pi-bridge')
+
+let _piAi = null
+async function pi() {
+    if (_piAi) return _piAi
+    _piAi = await import('@mariozechner/pi-ai')
+    return _piAi
+}
+
+export async function callLLM({ messages, tools = [], model, provider = 'anthropic' } = {}) {
+    const m = await pi()
+    const modelObj = m.getModel ? m.getModel(provider, model) : { provider, id: model }
+    const apiKey = m.getEnvApiKey ? m.getEnvApiKey(provider) : process.env[providerEnv(provider)]
+    if (!apiKey) throw new Error(`pi-bridge: no API key for ${provider} (set ${providerEnv(provider)})`)
+    const result = await m.complete({ model: modelObj, apiKey, messages: messages.map(adaptMessage), tools: tools.map(adaptTool) })
+    log.info('completed', { model: model || 'default', usage: result.usage })
+    return adaptResponse(result)
+}
+
+function providerEnv(p) { return ({ anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', groq: 'GROQ_API_KEY' })[p] || `${String(p).toUpperCase()}_API_KEY` }
+
+function adaptMessage(m) {
+    if (m.role === 'tool') return { role: 'tool', tool_call_id: m.tool_call_id, content: m.content }
+    return { role: m.role, content: m.content || '', tool_calls: m.tool_calls }
+}
+
+function adaptTool(t) {
+    return { name: t.name, description: t.description, input_schema: t.parameters || t.input_schema || { type: 'object', properties: {} } }
+}
+
+function adaptResponse(r) {
+    const content = typeof r.content === 'string' ? r.content : (Array.isArray(r.content) ? r.content.filter(c => c.type === 'text').map(c => c.text).join('') : '')
+    const tool_calls = (Array.isArray(r.content) ? r.content.filter(c => c.type === 'tool_use').map(c => ({ id: c.id, name: c.name, arguments: c.input })) : (r.tool_calls || []))
+    return { content, tool_calls, raw: r }
+}

package/src/agent/prompt_builder.js

@@ -0,0 +1,12 @@
+import { SUMMARY_PREFIX } from './compress/index.js'
+export function buildSystemPrompt({ persona = '', skills = [], context = [], cacheBreakpoint = true } = {}) {
+    const parts = []
+    if (persona) parts.push(persona)
+    if (skills.length) parts.push('## Available skills\n' + skills.map(s => '- ' + s.name + ': ' + (s.description || '')).join('\n'))
+    if (context.length) parts.push('## Context\n' + context.map(c => '[' + c.name + ']\n' + c.body).join('\n\n'))
+    return { content: parts.join('\n\n'), cacheBreakpoint }
+}
+export function injectSummaryHandoff(messages, summary) {
+    if (!summary) return messages
+    return [...messages, { role: 'user', content: SUMMARY_PREFIX + '\n\n' + summary }]
+}

package/src/agent/prompt_caching.js

@@ -0,0 +1,24 @@
+export const CACHE_BREAKPOINT_MAX = 4
+export function annotateBreakpoints(messages, { provider = 'anthropic' } = {}) {
+    if (provider !== 'anthropic') return messages
+    const out = messages.map(m => ({ ...m }))
+    const candidates = []
+    for (let i = out.length - 1; i >= 0; i--) {
+        const r = out[i].role
+        if (r === 'system' || r === 'user') candidates.push(i)
+        if (candidates.length >= CACHE_BREAKPOINT_MAX) break
+    }
+    for (const i of candidates.slice(0, CACHE_BREAKPOINT_MAX)) {
+        const m = out[i]
+        if (typeof m.content === 'string') m.content = [{ type: 'text', text: m.content, cache_control: { type: 'ephemeral' } }]
+        else if (Array.isArray(m.content) && m.content.length) m.content[m.content.length - 1] = { ...m.content[m.content.length - 1], cache_control: { type: 'ephemeral' } }
+    }
+    return out
+}
+export function countBreakpoints(messages) {
+    let n = 0
+    for (const m of messages) {
+        if (Array.isArray(m.content)) for (const p of m.content) if (p?.cache_control) n++
+    }
+    return n
+}

package/src/agent/rate_limit_tracker.js

@@ -0,0 +1,12 @@
+const _windows = new Map()
+export function record(provider, e) {
+    const w = _windows.get(provider) || { count: 0, until: 0 }
+    w.count++
+    const m = String(e?.message || e || '').match(/retry.?after[:\s]+(\d+)/i) || String(e?.headers?.get?.('retry-after') || '').match(/(\d+)/)
+    if (m) w.until = Date.now() + Number(m[1]) * 1000
+    _windows.set(provider, w)
+    return w
+}
+export function shouldThrottle(provider) { const w = _windows.get(provider); return w ? Date.now() < w.until : false }
+export function clear(provider) { _windows.delete(provider) }
+export function snapshot() { return Object.fromEntries(_windows) }

package/src/agent/redact.js

@@ -0,0 +1,25 @@
+export const SECRET_PATTERNS = [
+    [/sk-[A-Za-z0-9-_]{20,}/g, 'openai-key'],
+    [/sk-ant-[A-Za-z0-9-_]{20,}/g, 'anthropic-key'],
+    [/ghp_[A-Za-z0-9]{36}/g, 'github-pat'],
+    [/gho_[A-Za-z0-9]{36}/g, 'github-oauth'],
+    [/xox[baprs]-[A-Za-z0-9-]{10,}/g, 'slack-token'],
+    [/AKIA[0-9A-Z]{16}/g, 'aws-key-id'],
+    [/[a-zA-Z0-9._%+-]+:[^@\s]{4,}@[a-zA-Z0-9.-]+/g, 'url-credentials'],
+    [/Bearer\s+[A-Za-z0-9._-]{20,}/gi, 'bearer-token'],
+    [/[\w-]{20,}\.[\w-]{6,}\.[\w-]{20,}/g, 'jwt'],
+    [/-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]+?-----END [A-Z ]+PRIVATE KEY-----/g, 'private-key'],
+]
+export function redactSensitive(text) {
+    let out = String(text)
+    for (const [re] of SECRET_PATTERNS) out = out.replace(re, '[REDACTED]')
+    return out
+}
+export function detectSecrets(text) {
+    const found = []
+    for (const [re, kind] of SECRET_PATTERNS) {
+        const m = String(text).match(re)
+        if (m) for (const s of m) found.push({ kind, value: s.slice(0, 20) + '…' })
+    }
+    return found
+}

package/src/agent/retry_utils.js

@@ -0,0 +1,17 @@
+import { isRetryable } from './error_classifier.js'
+export async function retryAsync(fn, { attempts = 3, backoff = 200, factor = 2, max = 10_000, jitter = 0.2 } = {}) {
+    let last
+    for (let i = 0; i < attempts; i++) {
+        try { return await fn(i) } catch (e) {
+            last = e
+            if (i === attempts - 1) break
+            if (!isRetryable(e)) break
+            const wait = Math.min(max, backoff * Math.pow(factor, i)) * (1 + (Math.random() * 2 - 1) * jitter)
+            await new Promise(r => setTimeout(r, wait))
+        }
+    }
+    throw last
+}
+export async function withTimeout(fn, ms) {
+    return await Promise.race([fn(), new Promise((_, rej) => setTimeout(() => rej(new Error('timeout after ' + ms + 'ms')), ms))])
+}

package/src/agent/shell_hooks.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { getFophHome } from '../home.js'
+function hookFile() { return path.join(getFophHome(), 'shell-hooks.json') }
+export function loadHooks() { try { return JSON.parse(fs.readFileSync(hookFile(), 'utf8')) } catch { return { pre_run: [], post_run: [] } } }
+export function saveHooks(h) { fs.writeFileSync(hookFile(), JSON.stringify(h, null, 2), 'utf8') }
+export function addHook(stage, command) { const h = loadHooks(); (h[stage] = h[stage] || []).push(command); saveHooks(h); return h }
+export async function runHooks(stage, ctx = {}) {
+    const { spawnSync } = await import('node:child_process')
+    const out = []
+    for (const cmd of (loadHooks()[stage] || [])) {
+        const r = spawnSync(process.platform === 'win32' ? 'cmd' : 'sh', [process.platform === 'win32' ? '/c' : '-c', cmd], { encoding: 'utf8', env: { ...process.env, ...ctx.env } })
+        out.push({ cmd, exitCode: r.status, stdout: r.stdout, stderr: r.stderr })
+    }
+    return out
+}

package/src/agent/skill_commands.js

@@ -0,0 +1,16 @@
+import { findSkill } from '../skills/index.js'
+
+export function buildSkillUserMessage(name, args = '') {
+    const s = findSkill(name)
+    if (!s) return null
+    const argLine = args ? `\nArguments: ${args}\n` : '\n'
+    return { role: 'user', content: `[skill:${name}]${argLine}\n${s.body}` }
+}
+export function isSkillCommand(input) {
+    return typeof input === 'string' && /^\/skill\s+\S+/.test(input.trim())
+}
+export function parseSkillCommand(input) {
+    const m = String(input).trim().match(/^\/skill\s+(\S+)\s*(.*)$/)
+    if (!m) return null
+    return { name: m[1], args: m[2] }
+}

package/src/agent/skill_preprocessing.js

@@ -0,0 +1,12 @@
+import { findSkill } from '../skills/index.js'
+const REF_RE = /@skill\/([\w-]+)(?:\s+([^\n@]*))?/g
+export function preprocessSkillRefs(text) {
+    if (!text || typeof text !== 'string') return text
+    return text.replace(REF_RE, (m, name, args) => {
+        const s = findSkill(name)
+        return s ? '\n[skill:' + name + ']\n' + s.body + '\n' : m
+    })
+}
+export function listSkillRefs(text) {
+    return [...String(text || '').matchAll(REF_RE)].map(m => ({ name: m[1], args: m[2]?.trim() || '' }))
+}

package/src/agent/skill_utils.js

@@ -0,0 +1,14 @@
+import { listSkills, findSkill } from '../skills/index.js'
+export function fuzzyFindSkill(needle) {
+    const all = listSkills()
+    const lower = String(needle).toLowerCase()
+    const exact = all.find(s => s.name.toLowerCase() === lower)
+    if (exact) return exact
+    const starts = all.find(s => s.name.toLowerCase().startsWith(lower))
+    if (starts) return starts
+    return all.find(s => s.name.toLowerCase().includes(lower)) || null
+}
+export function skillByCategory(category) {
+    return listSkills().filter(s => s.frontmatter?.category === category)
+}
+export function skillExists(name) { return Boolean(findSkill(name)) }

package/src/agent/subdirectory_hints.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs'
+import path from 'node:path'
+const HINT_FILES = ['CLAUDE.md', 'AGENTS.md', '.freddie-context', 'README.md']
+export function collectHints({ cwd = process.cwd(), maxDepth = 3 } = {}) {
+    const hints = []
+    let dir = cwd
+    for (let d = 0; d < maxDepth; d++) {
+        for (const f of HINT_FILES) {
+            const p = path.join(dir, f)
+            if (fs.existsSync(p)) { try { hints.push({ path: p, body: fs.readFileSync(p, 'utf8').slice(0, 4000) }) } catch {} }
+        }
+        const parent = path.dirname(dir)
+        if (parent === dir) break
+        dir = parent
+    }
+    return hints
+}

package/src/agent/title_generator.js

@@ -0,0 +1,13 @@
+export function generateTitle(prompt, { maxWords = 8 } = {}) {
+    const text = String(prompt || '').replace(/[\n\r]+/g, ' ').trim()
+    if (!text) return 'untitled'
+    const words = text.split(/\s+/).slice(0, maxWords)
+    let title = words.join(' ')
+    if (title.length > 60) title = title.slice(0, 57) + '…'
+    return title.charAt(0).toUpperCase() + title.slice(1)
+}
+export async function llmTitle(messages, { callLLM, model = null } = {}) {
+    if (!callLLM) return generateTitle(messages?.[0]?.content || '')
+    const out = await callLLM({ model, messages: [{ role: 'user', content: 'Title this conversation in <=8 words. Reply only with the title.\n\n' + JSON.stringify(messages.slice(0, 4)) }] })
+    return (out?.content || '').trim().replace(/^["']|["']$/g, '') || generateTitle(messages?.[0]?.content || '')
+}

package/src/agent/trajectory.js

@@ -0,0 +1,9 @@
+export function compressTrajectory({ messages = [], maxKeep = 20 } = {}) {
+    if (messages.length <= maxKeep * 2) return { compressed: messages, removed: 0 }
+    const head = messages.slice(0, maxKeep)
+    const tail = messages.slice(-maxKeep)
+    const middleCount = messages.length - head.length - tail.length
+    const summary = { role: 'system', content: `[trajectory.compressed] ${middleCount} middle messages elided` }
+    return { compressed: [...head, summary, ...tail], removed: middleCount }
+}
+export function expandTrajectory(trajectory) { return trajectory.compressed }

package/src/agent/usage_pricing.js

@@ -0,0 +1,16 @@
+const PRICING = {
+    'claude-opus-4-7': [15, 75], 'claude-sonnet-4-6': [3, 15], 'claude-haiku-4-5': [0.8, 4],
+    'gpt-5': [10, 30], 'gpt-5-mini': [0.25, 2], 'gpt-4o': [2.5, 10], 'gpt-4o-mini': [0.15, 0.6],
+    'o3': [15, 60], 'o3-mini': [1.1, 4.4], 'o1': [15, 60],
+    'gemini-2.5-pro': [1.25, 10], 'gemini-2.5-flash': [0.075, 0.3],
+    'grok-3': [3, 15], 'grok-4': [5, 25], 'deepseek-v3': [0.27, 1.1],
+}
+export function priceFor(model) {
+    if (PRICING[model]) return PRICING[model]
+    for (const [k, v] of Object.entries(PRICING)) if (model.startsWith(k)) return v
+    return [0, 0]
+}
+export function calculateCost({ model, prompt_tokens = 0, completion_tokens = 0 }) {
+    const [pIn, pOut] = priceFor(model)
+    return (prompt_tokens / 1_000_000) * pIn + (completion_tokens / 1_000_000) * pOut
+}

package/src/auth.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { getFophHome } from './home.js'
+
+class FileAuthStore {
+    constructor() { this.dir = path.join(getFophHome(), 'auth'); fs.mkdirSync(this.dir, { recursive: true }) }
+    _path(name) { return path.join(this.dir, name + '.json') }
+    async setCredential(name, value) {
+        fs.writeFileSync(this._path(name), JSON.stringify({ name, value, updated: Date.now() }), { encoding: 'utf8', mode: 0o600 })
+        return { name, stored: true }
+    }
+    async getCredential(name) {
+        const p = this._path(name)
+        if (!fs.existsSync(p)) return null
+        return JSON.parse(fs.readFileSync(p, 'utf8'))
+    }
+    async listCredentials() {
+        return fs.readdirSync(this.dir).filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''))
+    }
+    async deleteCredential(name) {
+        const p = this._path(name)
+        if (fs.existsSync(p)) fs.unlinkSync(p)
+        return { name, deleted: true }
+    }
+}
+
+let _store = null
+export function getAuthStore() {
+    if (!_store) _store = new FileAuthStore()
+    return _store
+}
+export function resetAuthStoreForTests() { _store = null }
+
+const PROVIDERS = ['anthropic', 'openai', 'groq', 'openrouter', 'xai', 'gemini', 'bedrock', 'codex', 'kimi', 'zai', 'deepseek', 'mistral', 'perplexity']
+const ENV_OF = { anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', groq: 'GROQ_API_KEY', openrouter: 'OPENROUTER_API_KEY', xai: 'XAI_API_KEY', gemini: 'GEMINI_API_KEY', bedrock: 'AWS_ACCESS_KEY_ID', codex: 'OPENAI_API_KEY', kimi: 'KIMI_API_KEY', zai: 'ZAI_API_KEY', deepseek: 'DEEPSEEK_API_KEY', mistral: 'MISTRAL_API_KEY', perplexity: 'PERPLEXITY_API_KEY' }
+
+export function isKnownAuthProvider(name) { return PROVIDERS.includes(name) }
+export function listAuthProviders() { return [...PROVIDERS] }
+export function envForProvider(name) { return ENV_OF[name] || null }
+
+export async function hasUsableSecret(provider) {
+    const env = envForProvider(provider)
+    if (!env) return false
+    if (process.env[env]) return true
+    const cred = await getAuthStore().getCredential(env)
+    return Boolean(cred?.value)
+}
+
+export async function clearProviderAuth(provider) {
+    const env = envForProvider(provider)
+    if (!env) return false
+    await getAuthStore().deleteCredential(env)
+    return true
+}
+
+export function isExpiring(token, { skewSeconds = 60 } = {}) {
+    if (!token || typeof token !== 'object') return true
+    const exp = token.expires_at || token.exp
+    if (!exp) return false
+    const now = Math.floor(Date.now() / 1000)
+    const expSec = typeof exp === 'string' ? Math.floor(new Date(exp).getTime() / 1000) : exp
+    return expSec - now < skewSeconds
+}
+
+export function decodeJwtClaims(jwt) {
+    if (typeof jwt !== 'string') return null
+    const parts = jwt.split('.')
+    if (parts.length < 2) return null
+    try { return JSON.parse(Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8')) } catch { return null }
+}
+
+export function tokenFingerprint(token) {
+    const s = typeof token === 'string' ? token : (token?.access_token || token?.value || '')
+    if (!s) return ''
+    return s.slice(0, 4) + '…' + s.slice(-4)
+}
+
+export async function getProviderAuthState(provider) {
+    return {
+        provider,
+        env: envForProvider(provider),
+        hasSecret: await hasUsableSecret(provider),
+    }
+}

package/src/batch.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { runTurn } from './agent/machine.js'
+import { getFophHome } from './home.js'
+import { randomUUID } from 'node:crypto'
+
+export async function runBatch({ prompts = [], concurrency = 4, model, callLLM } = {}) {
+    if (!Array.isArray(prompts) || prompts.length === 0) throw new Error('prompts required')
+    const id = randomUUID()
+    const dir = path.join(getFophHome(), 'batches')
+    fs.mkdirSync(dir, { recursive: true })
+    const file = path.join(dir, id + '.jsonl')
+    const stream = fs.createWriteStream(file, { flags: 'a' })
+    const queue = prompts.map((p, i) => ({ i, p }))
+    const results = new Array(prompts.length)
+    const workers = Array.from({ length: Math.min(concurrency, prompts.length) }, async () => {
+        while (queue.length) {
+            const job = queue.shift()
+            if (!job) break
+            try {
+                const out = await runTurn({ prompt: job.p, model, callLLM, timeoutMs: 60000 })
+                results[job.i] = { i: job.i, prompt: job.p, result: out.result, error: out.error }
+            } catch (e) {
+                results[job.i] = { i: job.i, prompt: job.p, error: String(e?.message || e) }
+            }
+            stream.write(JSON.stringify(results[job.i]) + '\n')
+        }
+    })
+    await Promise.all(workers)
+    await new Promise(r => stream.end(r))
+    return { id, file, results }
+}

package/src/cli/auth_commands.js

@@ -0,0 +1,17 @@
+import { getAuthStore } from '../auth.js'
+import { listProviders, resolveKey } from '../agent/credential_sources.js'
+export async function login(provider, key) {
+    const env = (provider.toUpperCase() + '_API_KEY')
+    await getAuthStore().setCredential(env, key)
+    return { provider, stored: env }
+}
+export async function logout(provider) {
+    const env = (provider.toUpperCase() + '_API_KEY')
+    await getAuthStore().deleteCredential(env)
+    return { provider, removed: env }
+}
+export async function status() {
+    const out = []
+    for (const p of listProviders()) { const k = await resolveKey(p); out.push({ provider: p, source: k.source, hasKey: k.value != null }) }
+    return out
+}

package/src/cli/azure_detect.js

@@ -0,0 +1,9 @@
+export function isAzureBaseUrl(url) {
+    if (!url) return false
+    return /\.openai\.azure\.com\b/i.test(String(url)) || /azure-api\.net\b/i.test(String(url))
+}
+export function detectFromEnv() {
+    const url = process.env.AZURE_OPENAI_ENDPOINT || process.env.OPENAI_BASE_URL
+    if (!url) return { azure: false }
+    return { azure: isAzureBaseUrl(url), endpoint: url, deployment: process.env.AZURE_OPENAI_DEPLOYMENT, apiVersion: process.env.AZURE_OPENAI_API_VERSION || '2024-08-01-preview' }
+}

package/src/cli/backup.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { getFophHome } from '../home.js'
+export async function createBackup({ outFile } = {}) {
+    const home = getFophHome()
+    const out = outFile || path.join(home, 'backups', 'freddie-' + new Date().toISOString().replace(/[:.]/g, '-') + '.tar.gz')
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    const { spawnSync } = await import('node:child_process')
+    const r = spawnSync('tar', ['-czf', out, '-C', path.dirname(home), path.basename(home)], { encoding: 'utf8' })
+    if (r.status === 0) return { ok: true, file: out, size: fs.statSync(out).size }
+    return { ok: false, stderr: r.stderr, hint: 'tar may be missing on Windows; install GNU tar or use a different archiver.' }
+}
+export function listBackups() {
+    const dir = path.join(getFophHome(), 'backups')
+    if (!fs.existsSync(dir)) return []
+    return fs.readdirSync(dir).filter(f => f.endsWith('.tar.gz')).map(f => ({ name: f, file: path.join(dir, f), mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+}

package/src/cli/banner.js

@@ -0,0 +1,13 @@
+import { getActiveSkin } from '../skin/engine.js'
+const ART = [
+    '  _____ _           _   _     ',
+    ' |_   _| |__   ___ | |_| |__  ',
+    '   | | | _ \\ / _ \\| __| _ \\ ',
+    '   | | | | | | (_)| |_| | | |',
+    '   |_| |_| |_|\\___/ \\__|_| |_|',
+]
+export function renderBanner() {
+    const skin = getActiveSkin()
+    return ART.join('\n') + '\n' + skin.branding.welcome
+}
+export function printBanner(out = process.stdout) { out.write(renderBanner() + '\n') }

package/src/cli/browser_connect.js

@@ -0,0 +1,11 @@
+let _puppeteer = null
+async function probe() { if (_puppeteer !== null) return _puppeteer; try { _puppeteer = (await import('puppeteer-core')).default } catch { _puppeteer = false } return _puppeteer }
+export async function connectToBrowser({ wsEndpoint, browserURL } = {}) {
+    const p = await probe()
+    if (!p) return { error: 'puppeteer-core not installed' }
+    const browser = wsEndpoint ? await p.connect({ browserWSEndpoint: wsEndpoint }) : await p.connect({ browserURL })
+    return { browser, pages: await browser.pages() }
+}
+export async function attachExisting(port = 9222) {
+    return await connectToBrowser({ browserURL: 'http://127.0.0.1:' + port })
+}

package/src/cli/callbacks.js

@@ -0,0 +1,5 @@
+const _callbacks = new Map()
+export function on(event, fn) { if (!_callbacks.has(event)) _callbacks.set(event, new Set()); _callbacks.get(event).add(fn); return () => _callbacks.get(event)?.delete(fn) }
+export async function emit(event, payload) { const out = []; for (const fn of (_callbacks.get(event) || [])) try { out.push(await fn(payload)) } catch (e) { out.push({ error: String(e?.message || e) }) } return out }
+export function listEvents() { return [..._callbacks.keys()] }
+export function clearAll() { _callbacks.clear() }

package/src/cli/claw.js

@@ -0,0 +1,8 @@
+import { paste } from './clipboard.js'
+const HEAVY_THRESHOLD = 4000
+export async function clawIntoMessage({ minLength = 50 } = {}) {
+    const text = (await paste()) || ''
+    if (text.length < minLength) return null
+    const trimmed = text.length > HEAVY_THRESHOLD ? text.slice(0, HEAVY_THRESHOLD) + '\n…[' + (text.length - HEAVY_THRESHOLD) + ' chars truncated]' : text
+    return { content: '[pasted]\n\n' + trimmed, originalLength: text.length, truncated: text.length > HEAVY_THRESHOLD }
+}

package/src/cli/cli_output.js

@@ -0,0 +1,19 @@
+import { getActiveSkin } from '../skin/engine.js'
+import { hex } from './colors.js'
+export function info(msg) { return hex(getActiveSkin().colors.banner_text, msg) }
+export function success(msg) { return hex('#22c55e', '✓ ' + msg) }
+export function warning(msg) { return hex('#fbbf24', '! ' + msg) }
+export function error(msg) { return hex('#ef4444', '✗ ' + msg) }
+export function box(title, body) {
+    const line = '─'.repeat(Math.max(20, title.length + 4))
+    return '┌' + line + '┐\n│ ' + title + ' '.repeat(line.length - title.length - 1) + '│\n├' + line + '┤\n' + body.split('\n').map(l => '│ ' + l + ' '.repeat(Math.max(0, line.length - l.length - 1)) + '│').join('\n') + '\n└' + line + '┘'
+}
+export function table(rows) {
+    if (!rows.length) return ''
+    const keys = Object.keys(rows[0])
+    const widths = keys.map(k => Math.max(k.length, ...rows.map(r => String(r[k] ?? '').length)))
+    const sep = '+-' + widths.map(w => '-'.repeat(w)).join('-+-') + '-+'
+    const head = '| ' + keys.map((k, i) => k.padEnd(widths[i])).join(' | ') + ' |'
+    const body = rows.map(r => '| ' + keys.map((k, i) => String(r[k] ?? '').padEnd(widths[i])).join(' | ') + ' |').join('\n')
+    return [sep, head, sep, body, sep].join('\n')
+}

package/src/cli/clipboard.js

@@ -0,0 +1,24 @@
+import { spawn } from 'node:child_process'
+function run(cmd, input = null) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd[0], cmd.slice(1))
+        let stdout = ''
+        child.stdout?.on('data', d => stdout += d.toString())
+        child.on('close', code => resolve({ code, stdout }))
+        child.on('error', () => resolve({ code: -1, stdout: '' }))
+        if (input != null) { child.stdin?.write(input); child.stdin?.end() }
+    })
+}
+export async function copy(text) {
+    if (process.platform === 'win32') return run(['clip'], text)
+    if (process.platform === 'darwin') return run(['pbcopy'], text)
+    const xclip = await run(['xclip', '-selection', 'clipboard'], text)
+    if (xclip.code === 0) return xclip
+    return run(['xsel', '--clipboard', '--input'], text)
+}
+export async function paste() {
+    if (process.platform === 'win32') return (await run(['powershell', '-NoProfile', '-Command', 'Get-Clipboard'])).stdout
+    if (process.platform === 'darwin') return (await run(['pbpaste'])).stdout
+    const x = await run(['xclip', '-selection', 'clipboard', '-o'])
+    return x.code === 0 ? x.stdout : (await run(['xsel', '--clipboard', '--output'])).stdout
+}

package/src/cli/codex_models.js

@@ -0,0 +1,8 @@
+export const CODEX_MODELS = ['o3', 'o3-mini', 'o1', 'o1-mini', 'gpt-5', 'gpt-5-mini']
+export function isCodexModel(id) {
+    if (!id) return false
+    return CODEX_MODELS.some(m => id === m || id.startsWith(m))
+}
+export function recommendCodexModel(scenario) {
+    return ({ reasoning: 'o3', fast: 'o3-mini', flagship: 'gpt-5', cheap: 'gpt-5-mini' })[scenario] || 'o3-mini'
+}

package/src/cli/colors.js

@@ -0,0 +1,13 @@
+const RESET = '\x1b[0m'
+const FG = { red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, white: 37, gray: 90 }
+const BG = { red: 41, green: 42, yellow: 43, blue: 44, magenta: 45, cyan: 46, white: 47 }
+const ATTR = { bold: 1, dim: 2, italic: 3, underline: 4 }
+function wrap(code, s) { return '\x1b[' + code + 'm' + s + RESET }
+export const fg = Object.fromEntries(Object.entries(FG).map(([k, c]) => [k, (s) => wrap(c, s)]))
+export const bg = Object.fromEntries(Object.entries(BG).map(([k, c]) => [k, (s) => wrap(c, s)]))
+export const attr = Object.fromEntries(Object.entries(ATTR).map(([k, c]) => [k, (s) => wrap(c, s)]))
+export function hex(h, s) {
+    const r = parseInt(h.slice(1, 3), 16), g = parseInt(h.slice(3, 5), 16), b = parseInt(h.slice(5, 7), 16)
+    return '\x1b[38;2;' + r + ';' + g + ';' + b + 'm' + s + RESET
+}
+export function strip(s) { return String(s).replace(/\x1b\[[0-9;]*m/g, '') }

package/src/cli/completer.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { COMMAND_REGISTRY } from '../commands/registry.js'
+
+export class SlashCommandCompleter {
+    constructor({ commands = COMMAND_REGISTRY } = {}) {
+        this.commands = commands
+        this.names = []
+        for (const c of commands) { this.names.push(c.name); for (const a of c.aliases || []) this.names.push(a) }
+    }
+    suggest(line) {
+        if (!line.startsWith('/')) return []
+        const stripped = line.slice(1)
+        const space = stripped.indexOf(' ')
+        if (space === -1) {
+            return this.names.filter(n => n.startsWith(stripped)).map(n => ({ value: '/' + n, kind: 'command', display: '/' + n + this._argHint(n) }))
+        }
+        const cmd = stripped.slice(0, space)
+        const def = this.commands.find(c => c.name === cmd || (c.aliases || []).includes(cmd))
+        if (!def) return []
+        return [{ value: line, kind: 'args', display: '/' + def.name + ' ' + (def.args_hint || ''), description: def.description }]
+    }
+    _argHint(name) {
+        const def = this.commands.find(c => c.name === name || (c.aliases || []).includes(name))
+        return def?.args_hint ? ' ' + def.args_hint : ''
+    }
+}
+
+export class PathCompleter {
+    constructor({ cwd = process.cwd(), maxResults = 20, includeHidden = false } = {}) {
+        this.cwd = cwd
+        this.maxResults = maxResults
+        this.includeHidden = includeHidden
+    }
+    suggest(input) {
+        try {
+            const abs = path.isAbsolute(input) ? input : path.resolve(this.cwd, input)
+            const dir = input.endsWith('/') || input.endsWith(path.sep) ? abs : path.dirname(abs)
+            const stem = input.endsWith('/') || input.endsWith(path.sep) ? '' : path.basename(abs)
+            if (!fs.existsSync(dir)) return []
+            const ents = fs.readdirSync(dir, { withFileTypes: true })
+            const out = []
+            for (const e of ents) {
+                if (!this.includeHidden && e.name.startsWith('.')) continue
+                if (!e.name.toLowerCase().startsWith(stem.toLowerCase())) continue
+                const isDir = e.isDirectory()
+                const value = path.join(dir, e.name) + (isDir ? path.sep : '')
+                out.push({ value, kind: isDir ? 'dir' : 'file', display: e.name + (isDir ? '/' : '') })
+                if (out.length >= this.maxResults) break
+            }
+            return out
+        } catch { return [] }
+    }
+}
+
+export class FuzzyMatcher {
+    constructor(items, { keyFn = (x) => String(x) } = {}) {
+        this.items = items
+        this.keyFn = keyFn
+    }
+    score(query, target) {
+        const q = query.toLowerCase()
+        const t = target.toLowerCase()
+        if (!q) return 1
+        if (t === q) return 1000
+        if (t.startsWith(q)) return 500 - (t.length - q.length)
+        if (t.includes(q)) return 250 - (t.length - q.length)
+        let qi = 0, score = 0, prev = -1
+        for (let i = 0; i < t.length && qi < q.length; i++) {
+            if (t[i] === q[qi]) { score += (i - prev === 1 ? 5 : 1); prev = i; qi++ }
+        }
+        return qi === q.length ? score : 0
+    }
+    match(query, { limit = 10 } = {}) {
+        const scored = []
+        for (const it of this.items) {
+            const s = this.score(query, this.keyFn(it))
+            if (s > 0) scored.push({ item: it, score: s })
+        }
+        scored.sort((a, b) => b.score - a.score)
+        return scored.slice(0, limit).map(s => s.item)
+    }
+}
+
+export function createCompleter({ cwd } = {}) {
+    const slash = new SlashCommandCompleter()
+    const file = new PathCompleter({ cwd })
+    return {
+        suggest(line, cursor = line.length) {
+            const before = line.slice(0, cursor)
+            if (before.startsWith('/')) return slash.suggest(before)
+            const lastSpace = before.lastIndexOf(' ')
+            const tok = before.slice(lastSpace + 1)
+            if (tok.startsWith('./') || tok.startsWith('/') || tok.startsWith('~') || tok.includes('/')) return file.suggest(tok)
+            return []
+        },
+    }
+}