fabiana 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arifcamp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="fabiana.png" alt="Fabiana" width="180" />
+</p>
+
+<h1 align="center">Fabiana</h1>
+<p align="center"><em>Your personal AI companion that actually feels personal</em></p>
+
+---
+
+## The pitch
+
+Every other AI assistant sits there, waiting for your command, answering like an overly polite receptionist with a forced smile. Fabiana doesn’t wait. She texts you first, asks about your day, and remembers your habits. She has things on her mind, patterns she noticed, stories she thinks you’d enjoy. 
+
+Fabiana is not your typical obedient worker. She's independent, proactive, and has her own agenda. She's not an assistant who you tried to befriends with. She's a friend who slowly learn to help you with your tasks. The kind who remembers your sister’s name, knows you refuse to schedule meetings before 10am, and will roast you—gently—when you promised to sleep early but it’s 1am and you’re asking her about world news again.
+
+No dashboards. No commands to memorize. She just slides into your DM.
+
+---
+
+## What she does
+
+**She messages you first.** She has a schedule and a TODO list she manages herself. She'll reach out when there's something worth saying — not when you remember to ask.
+
+**She remembers everything.** Every conversation gets distilled into plain-text memory. Next week she still knows what you're working on, who you mentioned, and what's stressing you out. Next month too.
+
+**Her memory is yours.** All data lives in `.fabiana/data/` as plain text files. Read it, edit it, back it up, delete it. No black boxes. No vector embeddings. No vendor lock-in.
+
+**She learns new tricks.** Drop a plugin into `plugins/` and she wakes up with a new capability. Web search, calendar, Hacker News — or whatever you build.
+
+**She's small enough to trust.** The codebase is intentionally tiny. TypeScript, a handful of dependencies, plain text files. You can read the whole thing in an afternoon.
+
+---
+
+## How it works
+
+Fabiana runs as a background daemon doing three things on a loop:
+
+| Mode | What it does |
+|------|-------------|
+| **Chat** | Listens for your Telegram messages and responds |
+| **Initiative** | Checks her TODO list and calendar, decides if there's something worth telling you |
+| **Consolidation** | Every night at midnight, distills the day's conversations into structured memory |
+
+She's built on [Pi SDK](https://github.com/mariozechner/pi) — which means she runs on Anthropic, OpenAI, Google Gemini, Groq, Mistral, Amazon Bedrock, and more. [OpenRouter](https://openrouter.ai) is the default because one key gets you 240+ models.
+
+### Memory — plain text, always
+
+```
+.fabiana/data/memory/
+├── identity.md          ← who you are
+├── core.md              ← what's happening in your life right now
+├── people/              ← one file per person you mention
+├── interests/topics.md  ← what you care about
+├── recent/this-week.md  ← short-term context
+└── diary/               ← daily entries (auto-written)
+```
+
+Memory is tiered — hot files load every session, warm files load when relevant, cold files sit in the archive, searchable when needed. She writes and organizes it herself. You can read any of it any time.
+
+---
+
+## Installation
+
+### What you need
+
+- **Node.js ≥ 22**
+- A **Telegram bot** — takes 2 minutes via [@BotFather](https://t.me/BotFather)
+- An LLM API key — [OpenRouter](https://openrouter.ai/keys) is the easiest starting point (one key, 240+ models)
+
+### Setup
+
+```bash
+git clone https://github.com/your-username/fabiana
+cd fabiana
+npm install
+fabiana init
+```
+
+`fabiana init` walks you through the whole setup. Or do it manually:
+
+Create a `.env` file:
+
+```env
+TELEGRAM_BOT_TOKEN=your_token_from_botfather
+TELEGRAM_CHAT_ID=your_chat_id
+
+# Pick one (or more)
+OPENROUTER_API_KEY=sk-or-v1-...   # OpenRouter (recommended — covers everything)
+ANTHROPIC_API_KEY=...             # Direct Anthropic
+OPENAI_API_KEY=...                # Direct OpenAI
+GEMINI_API_KEY=...                # Direct Google
+
+# Optional extras
+BRAVE_API_KEY=...                 # Web search
+GOOGLE_CALENDAR_EMAIL=your@gmail.com  # Calendar awareness
+```
+
+**Getting your Telegram credentials:**
+1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token
+2. Message [@userinfobot](https://t.me/userinfobot) → copy your numeric ID
+
+### Check everything's wired up
+
+```bash
+fabiana doctor
+```
+
+Verifies your environment, credentials, plugins, and data directories. Fix anything it flags, then:
+
+```bash
+fabiana start
+```
+
+She'll start listening on Telegram and schedule herself from there.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `fabiana init` | First time? Let's get acquainted |
+| `fabiana start` | Wake her up — she'll take it from there |
+| `fabiana initiative` | Make her think. Just once. (good for testing) |
+| `fabiana consolidate` | Tidy up the mind palace |
+| `fabiana doctor` | Is everything okay in there? Let's check |
+| `fabiana backup` | Save her brain to a zip file |
+| `fabiana restore <file>` | Bring her back from the archive |
+| `fabiana plugins add <user/repo>` | Teach her a new trick from GitHub |
+| `fabiana plugins list` | What can she do? |
+
+---
+
+## Choosing a model
+
+Edit `config.json`:
+
+```json
+{
+  "model": {
+    "provider": "openrouter",
+    "modelId": "anthropic/claude-sonnet-4-5",
+    "thinkingLevel": "low"
+  }
+}
+```
+
+**Popular choices:**
+
+| Provider | Model | Notes |
+|---|---|---|
+| `openrouter` | `anthropic/claude-sonnet-4-5` | Best quality via OpenRouter |
+| `openrouter` | `google/gemini-2.5-flash` | Fast and cheap |
+| `anthropic` | `claude-sonnet-4-6` | Direct Anthropic |
+| `google` | `gemini-2.5-flash` | Direct Google |
+| `groq` | `llama-3.3-70b-versatile` | Very fast, generous free tier |
+
+See [docs/providers.md](docs/providers.md) for the full list.
+
+---
+
+## Optional: Google Calendar
+
+```bash
+npm install -g @mariozechner/gccli
+gccli accounts credentials ~/path/to/oauth-credentials.json
+gccli accounts add your@gmail.com
+```
+
+Then add `GOOGLE_CALENDAR_EMAIL=your@gmail.com` to `.env`. Now she'll actually know when you have that meeting you keep forgetting.
+
+---
+
+## Optional: Brave Search
+
+1. Create a free account at [api-dashboard.search.brave.com](https://api-dashboard.search.brave.com/register)
+2. Grab an API key and add `BRAVE_API_KEY=your_key` to `.env`
+
+---
+
+## Backup & restore
+
+```bash
+# Save everything
+fabiana backup
+# → fabiana-2026-03-14T09-51-08.tar.gz
+
+# Bring it back
+fabiana restore fabiana-2026-03-14T09-51-08.tar.gz
+```
+
+Memory, diary, conversations — all of it, safely portable.
+
+---
+
+## Plugin development
+
+Plugins live in `plugins/` and are auto-discovered at startup. A plugin is just a TypeScript file that exports a tool definition. See [docs/plugins.md](docs/plugins.md) for the full guide.
+
+---
+
+## License
+
+MIT
+
+---
+
+*Built with the Pi SDK · For Arif — who wanted a companion, not a chatbot*

package/bin/fabiana.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+await import(path.join(__dirname, '..', 'dist', 'cli.js'));

package/dist/backup.js

@@ -0,0 +1,89 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import chalk from 'chalk';
+import readline from 'readline';
+import { DATA_DIR, FABIANA_HOME } from './paths.js';
+const execFileAsync = promisify(execFile);
+function makeFilename() {
+    const now = new Date();
+    const iso = now.toISOString().replace(/:/g, '-').replace(/\..+/, '');
+    return `fabiana-${iso}.tar.gz`;
+}
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(question, answer => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+export async function runBackup(options) {
+    // Verify data directory exists
+    try {
+        await fs.access(DATA_DIR);
+    }
+    catch {
+        console.error(chalk.red(`✗ ${DATA_DIR} not found — nothing to back up`));
+        process.exit(1);
+    }
+    const filename = options.output ?? makeFilename();
+    const outPath = path.resolve(filename);
+    console.log(chalk.bold('\nBacking up Fabiana data...'));
+    console.log(chalk.dim(`  Source: ${DATA_DIR}`));
+    console.log(chalk.dim(`  Output: ${outPath}`));
+    try {
+        await execFileAsync('tar', ['-czf', outPath, '-C', FABIANA_HOME, 'data']);
+        const stat = await fs.stat(outPath);
+        const kb = (stat.size / 1024).toFixed(1);
+        console.log(`\n${chalk.green('✓')} Backup saved: ${chalk.cyan(path.basename(outPath))} ${chalk.dim(`(${kb} KB)`)}\n`);
+    }
+    catch (e) {
+        console.error(chalk.red(`✗ Backup failed: ${e.message}`));
+        process.exit(1);
+    }
+}
+export async function runRestore(filepath, options) {
+    const absPath = path.resolve(filepath);
+    // Verify archive exists
+    try {
+        await fs.access(absPath);
+    }
+    catch {
+        console.error(chalk.red(`✗ File not found: ${absPath}`));
+        process.exit(1);
+    }
+    console.log(chalk.bold('\nRestoring Fabiana data...'));
+    console.log(chalk.dim(`  Archive: ${absPath}`));
+    // Warn if data directory already exists
+    let dataExists = false;
+    try {
+        await fs.access(DATA_DIR);
+        dataExists = true;
+    }
+    catch {
+        // doesn't exist — no conflict
+    }
+    if (dataExists) {
+        console.log(`\n${chalk.yellow('⚠')} ${chalk.yellow(`${DATA_DIR} already exists and will be overwritten.`)}`);
+        if (!options.force) {
+            const ok = await confirm('  Continue? (y/N) ');
+            if (!ok) {
+                console.log(chalk.dim('  Restore cancelled.\n'));
+                return;
+            }
+        }
+        await fs.rm(DATA_DIR, { recursive: true, force: true });
+    }
+    try {
+        await fs.mkdir(FABIANA_HOME, { recursive: true });
+        await execFileAsync('tar', ['-xzf', absPath, '-C', FABIANA_HOME]);
+        console.log(`\n${chalk.green('✓')} Data restored to ${chalk.cyan(DATA_DIR)}\n`);
+    }
+    catch (e) {
+        console.error(chalk.red(`✗ Restore failed: ${e.message}`));
+        process.exit(1);
+    }
+}

package/dist/channels/index.js

@@ -0,0 +1,37 @@
+import { TelegramAdapter } from './telegram.js';
+import { SlackAdapter } from './slack.js';
+export async function loadChannels(channels) {
+    // Fallback for installs that don't have a channels block yet
+    if (!channels) {
+        channels = { primary: 'telegram', telegram: { enabled: true } };
+    }
+    const adapters = [];
+    // Telegram — enabled by default if the block exists or there is no channels config
+    if (channels.telegram?.enabled !== false) {
+        const token = process.env.TELEGRAM_BOT_TOKEN;
+        const chatId = process.env.TELEGRAM_CHAT_ID
+            ? parseInt(process.env.TELEGRAM_CHAT_ID)
+            : undefined;
+        if (!token || !chatId) {
+            throw new Error('TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID required for the Telegram channel');
+        }
+        adapters.push(new TelegramAdapter(token, chatId));
+    }
+    // Slack — opt-in only
+    if (channels.slack?.enabled) {
+        const ownerUserId = channels.slack.ownerUserId;
+        if (!ownerUserId) {
+            throw new Error('channels.slack.ownerUserId is required in config.json when Slack is enabled');
+        }
+        adapters.push(new SlackAdapter(ownerUserId));
+    }
+    if (adapters.length === 0) {
+        throw new Error('No channels enabled — enable at least one channel in config.json');
+    }
+    const primaryName = channels.primary ?? adapters[0].name;
+    const primary = adapters.find((a) => a.name === primaryName);
+    if (!primary) {
+        throw new Error(`Primary channel "${primaryName}" is not among enabled channels: ${adapters.map((a) => a.name).join(', ')}`);
+    }
+    return { all: adapters, primary };
+}

package/dist/channels/slack.js

@@ -0,0 +1,96 @@
+import fs from 'fs/promises';
+import { paths } from '../paths.js';
+export class SlackAdapter {
+    name = 'slack';
+    app = null;
+    ownerUserId;
+    ownerDmChannelId = null;
+    queue = [];
+    constructor(ownerUserId) {
+        this.ownerUserId = ownerUserId;
+    }
+    async start() {
+        const botToken = process.env.SLACK_BOT_TOKEN;
+        const appToken = process.env.SLACK_APP_TOKEN;
+        if (!botToken || !appToken) {
+            throw new Error('SLACK_BOT_TOKEN and SLACK_APP_TOKEN are required for the Slack channel');
+        }
+        let App;
+        try {
+            ({ App } = await import('@slack/bolt'));
+        }
+        catch {
+            throw new Error('@slack/bolt is not installed — run: npm install @slack/bolt');
+        }
+        this.app = new App({
+            token: botToken,
+            appToken,
+            socketMode: true,
+        });
+        this.app.message(async ({ message }) => {
+            // Skip bot messages, edits, and other subtypes
+            if (message.subtype)
+                return;
+            const text = (message.text || '').trim();
+            if (!text)
+                return;
+            this.queue.push({
+                text,
+                senderId: message.user,
+                channelId: message.channel,
+                threadId: message.thread_ts || message.ts,
+                timestamp: new Date(parseFloat(message.ts) * 1000),
+                source: 'slack',
+            });
+            console.log(`📨 [slack] Message queued: "${text.slice(0, 50)}"`);
+        });
+        await this.app.start();
+        console.log('✓ Slack Socket Mode started');
+    }
+    async stop() {
+        if (this.app)
+            await this.app.stop();
+    }
+    /**
+     * Send a message. If channelId is provided, sends there (with optional thread_ts).
+     * If omitted, opens/reuses a DM with the owner.
+     */
+    async send(text, channelId, threadId) {
+        if (!this.app)
+            throw new Error('Slack adapter not started');
+        const target = channelId ?? (await this.getOwnerDmChannelId());
+        await this.app.client.chat.postMessage({
+            channel: target,
+            text,
+            ...(threadId ? { thread_ts: threadId } : {}),
+        });
+    }
+    async getOwnerDmChannelId() {
+        if (this.ownerDmChannelId)
+            return this.ownerDmChannelId;
+        const result = await this.app.client.conversations.open({ users: this.ownerUserId });
+        this.ownerDmChannelId = result.channel.id;
+        return this.ownerDmChannelId;
+    }
+    drainQueue() {
+        const messages = [...this.queue];
+        this.queue = [];
+        return messages;
+    }
+    hasMessages() {
+        return this.queue.length > 0;
+    }
+    isOwner(senderId) {
+        return senderId === this.ownerUserId;
+    }
+    async logConversation(role, text, source = 'slack') {
+        const today = new Date().toISOString().slice(0, 10);
+        const timestamp = new Date().toISOString();
+        const entry = `[${timestamp}] [${source}] ${role === 'user' ? '👤 You' : '🌸 Fabiana'}: ${text}\n`;
+        await fs.appendFile(paths.logs(`conversation-${today}.log`), entry, 'utf-8').catch(() => { });
+    }
+    /** Expose the Bolt app for use by the start_external_conversation tool */
+    getBoltApp() {
+        return this.app;
+    }
+}

package/dist/channels/telegram.js

@@ -0,0 +1,70 @@
+import { Telegraf } from 'telegraf';
+import fs from 'fs/promises';
+import { paths } from '../paths.js';
+export class TelegramAdapter {
+    name = 'telegram';
+    bot;
+    chatId;
+    queue = [];
+    constructor(token, chatId) {
+        this.bot = new Telegraf(token);
+        this.chatId = chatId;
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.bot.on('text', (ctx) => {
+            // Only accept messages from the configured chat
+            if (ctx.chat.id !== this.chatId)
+                return;
+            // Normalize Telegram system commands (e.g. /start from clearing chat history)
+            const rawText = ctx.message.text;
+            const text = rawText === '/start' ? "hey, what's up?" : rawText;
+            this.queue.push({
+                text,
+                senderId: String(ctx.from.id),
+                channelId: String(ctx.chat.id),
+                threadId: String(ctx.message.message_id),
+                timestamp: new Date(ctx.message.date * 1000),
+                source: 'telegram',
+            });
+            console.log(`📨 [telegram] Message queued: "${text.slice(0, 50)}"`);
+        });
+        this.bot.catch((err) => {
+            console.error('Telegram error:', err);
+        });
+    }
+    async start() {
+        this.bot.launch({ dropPendingUpdates: false }).catch((err) => {
+            console.error('Telegram launch error:', err);
+        });
+        await new Promise((r) => setTimeout(r, 1000));
+        console.log('✓ Telegram polling started');
+    }
+    async stop() {
+        this.bot.stop();
+    }
+    // channelId and threadId are ignored — Telegram always replies to the configured chatId
+    async send(text, _channelId, _threadId) {
+        await this.bot.telegram.sendMessage(this.chatId, text, {
+            parse_mode: 'Markdown',
+        });
+    }
+    drainQueue() {
+        const messages = [...this.queue];
+        this.queue = [];
+        return messages;
+    }
+    hasMessages() {
+        return this.queue.length > 0;
+    }
+    // All Telegram messages are from the owner — chatId filter already applied
+    isOwner(_senderId) {
+        return true;
+    }
+    async logConversation(role, text, source = 'telegram') {
+        const today = new Date().toISOString().slice(0, 10);
+        const timestamp = new Date().toISOString();
+        const entry = `[${timestamp}] [${source}] ${role === 'user' ? '👤 You' : '🌸 Fabiana'}: ${text}\n`;
+        await fs.appendFile(paths.logs(`conversation-${today}.log`), entry, 'utf-8').catch(() => { });
+    }
+}

package/dist/channels/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,84 @@
+import { config as dotenvConfig } from 'dotenv';
+import { paths } from './paths.js';
+dotenvConfig({ path: paths.envFile }); // ~/.fabiana/.env (production)
+dotenvConfig(); // .env in cwd (dev fallback)
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { join, dirname } from 'path';
+import { startDaemon, runInitiativeOnce, runConsolidateOnce } from './daemon/index.js';
+import { runDoctor } from './doctor.js';
+import { runBackup, runRestore } from './backup.js';
+import { pluginsAdd, pluginsList } from './plugins-cmd.js';
+import { runSetup } from './setup/index.js';
+const C = '\x1b[96m'; // cyan — name
+const D = '\x1b[2m'; // dim  — subtitle
+const R = '\x1b[0m'; // reset
+function printBanner() {
+    let asciiLines = [];
+    try {
+        const asciiPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'ascii.txt');
+        asciiLines = readFileSync(asciiPath, 'utf8').trimEnd().split('\n');
+    }
+    catch {
+        // ascii.txt not found — skip the big title
+    }
+    console.log();
+    if (asciiLines.length) {
+        asciiLines.forEach(line => console.log(`${C}${line}${R}`));
+    }
+    console.log(`\n${D} AI companion who texts you first.${R}\n`);
+}
+printBanner();
+const program = new Command();
+program
+    .name('fabiana')
+    .description('She remembers. She reaches out. She cares.')
+    .version('0.1.0')
+    .addHelpText('after', `
+  She's not waiting to be asked. She'll message you first.
+  Run \`fabiana start\` and get out of her way.`);
+program
+    .command('init')
+    .description('First time? Let\'s get acquainted')
+    .action(runSetup);
+program
+    .command('start', { isDefault: true })
+    .description('Wake her up — she\'ll take it from there')
+    .action(startDaemon);
+program
+    .command('initiative')
+    .description('Make her think. Just once. (good for testing)')
+    .action(runInitiativeOnce);
+program
+    .command('consolidate')
+    .description('Tidy up the mind palace')
+    .action(runConsolidateOnce);
+program
+    .command('doctor')
+    .description('Is everything okay in there? Let\'s check')
+    .action(runDoctor);
+program
+    .command('backup')
+    .description('Save her brain to a zip file')
+    .option('-o, --output <filename>', 'override output filename')
+    .action((opts) => runBackup(opts));
+program
+    .command('restore <filepath>')
+    .description('Bring her back from the archive')
+    .option('-f, --force', 'skip confirmation prompt if data directory exists')
+    .action((filepath, opts) => runRestore(filepath, opts));
+const plugins = new Command('plugins').description('Teach her new tricks');
+plugins
+    .command('add <repo>')
+    .description('Install a plugin from GitHub (format: username/reponame)')
+    .action((repo) => pluginsAdd(repo));
+plugins
+    .command('list')
+    .description('What can she do?')
+    .action(pluginsList);
+program.addCommand(plugins);
+program.addHelpCommand(new Command('help')
+    .argument('[command]', 'command to show help for')
+    .description('Show help for fabiana or a specific command'));
+program.parse();