@tinyclaw/plugin-channel-friends 1.0.1-dev.3004a38

package/README.md

@@ -0,0 +1,29 @@
+# @tinyclaw/plugin-channel-friends
+
+Invite-based web chat channel plugin for Tiny Claw. Lets the owner invite friends to chat with the agent through a lightweight web interface.
+
+## Setup
+
+1. Enable the plugin via config or ask the agent
+2. Ask the agent to invite a friend (e.g. "invite my friend John to friends chat")
+3. Share the invite URL or code with your friend
+4. Friend opens the link and starts chatting
+
+## How It Works
+
+- Runs an HTTP server on a configurable port (default 3001)
+- Invite codes are single-use — redeemed into a session cookie
+- Messages route through the agent loop as `friend:<username>`
+
+## Management Tools
+
+| Tool | Description |
+|------|-------------|
+| `friends_chat_invite` | Create a friend and generate an invite code |
+| `friends_chat_reinvite` | Regenerate an invite for an existing friend |
+| `friends_chat_revoke` | Revoke a friend's session and invite |
+| `friends_chat_list` | List all friends |
+
+## License
+
+GPLv3

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Friends Chat Channel Plugin
+ *
+ * A channel plugin that provides a web-based chat interface for friends.
+ * Friends are invited by the owner via the AI agent, and each friend gets
+ * a unique invite code to authenticate.
+ *
+ * Setup:
+ *   1. Enable the plugin (add to plugins.enabled or ask the agent)
+ *   2. Ask the AI agent to invite a friend: "invite my friend John to friends chat"
+ *   3. Share the invite URL or code with your friend
+ *   4. Friend opens the link → starts chatting via FRIENDS.md
+ *
+ * Architecture:
+ *   - Runs its own HTTP server on a configurable port (default 3001)
+ *   - Invite codes are single-use → consumed → session cookie
+ *   - All friend messages route through `context.enqueue()` as `friend:<username>`
+ *   - The plugin provides tools for invite management (owner-only)
+ *
+ * userId format: "friend:<username>"
+ */
+import type { ChannelPlugin } from '@tinyclaw/types';
+declare const friendsPlugin: ChannelPlugin;
+export default friendsPlugin;

package/dist/index.js

@@ -0,0 +1,102 @@
+/**
+ * Friends Chat Channel Plugin
+ *
+ * A channel plugin that provides a web-based chat interface for friends.
+ * Friends are invited by the owner via the AI agent, and each friend gets
+ * a unique invite code to authenticate.
+ *
+ * Setup:
+ *   1. Enable the plugin (add to plugins.enabled or ask the agent)
+ *   2. Ask the AI agent to invite a friend: "invite my friend John to friends chat"
+ *   3. Share the invite URL or code with your friend
+ *   4. Friend opens the link → starts chatting via FRIENDS.md
+ *
+ * Architecture:
+ *   - Runs its own HTTP server on a configurable port (default 3001)
+ *   - Invite codes are single-use → consumed → session cookie
+ *   - All friend messages route through `context.enqueue()` as `friend:<username>`
+ *   - The plugin provides tools for invite management (owner-only)
+ *
+ * userId format: "friend:<username>"
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from '@tinyclaw/logger';
+import { InviteStore } from './store.js';
+import { createFriendsTools, FRIENDS_ENABLED_CONFIG_KEY, FRIENDS_PORT_CONFIG_KEY, FRIENDS_PLUGIN_ID, } from './tools.js';
+import { createFriendsServer } from './server.js';
+// Resolve the directory of this source file for static asset paths
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** Load the embedded chat HTML at boot time. */
+function loadChatHtml() {
+    const htmlPath = join(__dirname, 'chat.html');
+    return readFileSync(htmlPath, 'utf-8');
+}
+let store = null;
+let friendsServer = null;
+const friendsPlugin = {
+    id: FRIENDS_PLUGIN_ID,
+    name: 'Friends Chat',
+    description: 'Invite-based web chat for friends — powered by FRIENDS.md',
+    type: 'channel',
+    version: '0.1.0',
+    getPairingTools(_secrets, configManager) {
+        // Initialize the store early so pairing tools work before start()
+        if (!store) {
+            const dataDir = configManager.get('dataDir') || '.';
+            const dbPath = join(dataDir, 'data', 'friends.db');
+            store = new InviteStore(dbPath);
+        }
+        return createFriendsTools(store, configManager);
+    },
+    async start(context) {
+        const isEnabled = context.configManager.get(FRIENDS_ENABLED_CONFIG_KEY);
+        if (!isEnabled) {
+            logger.info('Friends chat plugin: not enabled — enable via config or ask the agent');
+            return;
+        }
+        // Initialize store if not already done by getPairingTools
+        if (!store) {
+            const dataDir = context.configManager.get('dataDir') || '.';
+            const dbPath = join(dataDir, 'data', 'friends.db');
+            store = new InviteStore(dbPath);
+        }
+        const port = context.configManager.get(FRIENDS_PORT_CONFIG_KEY) || 3001;
+        const host = process.env.HOST || context.configManager.get('friends.host') || '127.0.0.1';
+        const chatHtml = loadChatHtml();
+        friendsServer = createFriendsServer({
+            port,
+            host,
+            store,
+            chatHtml,
+            async onMessage(message, userId) {
+                return context.enqueue(userId, message);
+            },
+            async onMessageStream(message, userId, send) {
+                // Use the streaming enqueue if available, otherwise fallback
+                const response = await context.enqueue(userId, message);
+                // If enqueue returned a string directly (non-streaming), send it as done
+                if (response !== undefined && response !== null) {
+                    send({ type: 'text', content: response });
+                    send({ type: 'done' });
+                }
+            },
+        });
+        await friendsServer.start();
+        logger.info(`Friends chat available at http://${host}:${port}/chat`);
+    },
+    async stop() {
+        if (friendsServer) {
+            friendsServer.stop();
+            friendsServer = null;
+        }
+        if (store) {
+            store.close();
+            store = null;
+        }
+        logger.info('Friends chat plugin stopped');
+    },
+};
+export default friendsPlugin;

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Friends Chat HTTP Server
+ *
+ * Lightweight Bun HTTP server that exposes:
+ *   - GET  /chat           → Friends chat UI (static HTML)
+ *   - GET  /chat?invite=X  → Auto-redeem invite, set cookie, show chat
+ *   - POST /api/chat       → Chat API (SSE stream or JSON)
+ *   - POST /api/nickname   → Update friend's nickname
+ *   - GET  /api/health     → Health check
+ *
+ * Authentication is cookie-based. The invite code is consumed on first use
+ * and replaced with a long-lived session cookie (`tc_friend_session`).
+ */
+import type { InviteStore } from './store.js';
+interface FriendsServerConfig {
+    port: number;
+    host: string;
+    store: InviteStore;
+    chatHtml: string;
+    secure?: boolean;
+    onMessage: (message: string, userId: string) => Promise<string>;
+    onMessageStream?: (message: string, userId: string, send: (payload: unknown) => void) => Promise<void>;
+}
+export declare function createFriendsServer(config: FriendsServerConfig): {
+    start(): Promise<void>;
+    stop(): void;
+    getPort(): number;
+};
+export {};

package/dist/server.js

@@ -0,0 +1,293 @@
+/**
+ * Friends Chat HTTP Server
+ *
+ * Lightweight Bun HTTP server that exposes:
+ *   - GET  /chat           → Friends chat UI (static HTML)
+ *   - GET  /chat?invite=X  → Auto-redeem invite, set cookie, show chat
+ *   - POST /api/chat       → Chat API (SSE stream or JSON)
+ *   - POST /api/nickname   → Update friend's nickname
+ *   - GET  /api/health     → Health check
+ *
+ * Authentication is cookie-based. The invite code is consumed on first use
+ * and replaced with a long-lived session cookie (`tc_friend_session`).
+ */
+import { logger } from '@tinyclaw/logger';
+const COOKIE_NAME = 'tc_friend_session';
+const COOKIE_MAX_AGE = 365 * 24 * 60 * 60; // 1 year in seconds
+/**
+ * Parse the session token from the cookie header.
+ */
+function getSessionToken(request) {
+    const cookieHeader = request.headers.get('cookie') || '';
+    const match = cookieHeader.match(new RegExp(`${COOKIE_NAME}=([^;]+)`));
+    return match ? match[1] : null;
+}
+/**
+ * Build a Set-Cookie header for the friend session.
+ */
+function buildSessionCookie(token, secure = false) {
+    let cookie = `${COOKIE_NAME}=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${COOKIE_MAX_AGE}`;
+    if (secure)
+        cookie += '; Secure';
+    return cookie;
+}
+/**
+ * JSON response helper.
+ */
+function jsonResponse(data, status = 200, headers) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: {
+            'Content-Type': 'application/json',
+            ...headers,
+        },
+    });
+}
+/**
+ * HTML response helper.
+ */
+function htmlResponse(html, status = 200, headers) {
+    return new Response(html, {
+        status,
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            ...headers,
+        },
+    });
+}
+/**
+ * Authenticate a request — returns the friend user or null.
+ */
+function authenticateFriend(request, store) {
+    const token = getSessionToken(request);
+    if (!token)
+        return null;
+    return store.getBySessionToken(token);
+}
+export function createFriendsServer(config) {
+    const { port, host, store, chatHtml, onMessage, onMessageStream } = config;
+    const secure = config.secure ?? (process.env.NODE_ENV === 'production');
+    const textEncoder = new TextEncoder();
+    let server = null;
+    return {
+        async start() {
+            server = Bun.serve({
+                port,
+                hostname: host,
+                async fetch(request) {
+                    const url = new URL(request.url);
+                    const pathname = url.pathname;
+                    // ─── Health check ───────────────────────────────────────
+                    if (pathname === '/api/health' && request.method === 'GET') {
+                        return jsonResponse({ ok: true, service: 'friends-chat' });
+                    }
+                    // ─── Chat page ──────────────────────────────────────────
+                    if ((pathname === '/chat' || pathname === '/') && request.method === 'GET') {
+                        const inviteCode = url.searchParams.get('invite');
+                        // If invite code provided, try to redeem
+                        if (inviteCode) {
+                            const result = store.redeemInvite(inviteCode);
+                            if (result) {
+                                logger.info(`Friend "${result.friend.username}" redeemed invite`);
+                                // Redirect to /chat (without invite param) with session cookie
+                                return new Response(null, {
+                                    status: 302,
+                                    headers: {
+                                        Location: '/chat',
+                                        'Set-Cookie': buildSessionCookie(result.sessionToken, secure),
+                                    },
+                                });
+                            }
+                            // Invalid code — show chat page (will show invite code input)
+                            return htmlResponse(chatHtml);
+                        }
+                        // No invite code — serve the chat page
+                        // Auth check happens client-side via /api/auth/status
+                        return htmlResponse(chatHtml);
+                    }
+                    // ─── Auth status ────────────────────────────────────────
+                    if (pathname === '/api/auth/status' && request.method === 'GET') {
+                        const friend = authenticateFriend(request, store);
+                        if (friend) {
+                            store.touchLastSeen(friend.username);
+                            return jsonResponse({
+                                authenticated: true,
+                                username: friend.username,
+                                nickname: friend.nickname,
+                            });
+                        }
+                        return jsonResponse({ authenticated: false });
+                    }
+                    // ─── Redeem invite via API (for manual code entry) ──────
+                    if (pathname === '/api/auth/redeem' && request.method === 'POST') {
+                        let body = null;
+                        try {
+                            body = await request.json();
+                        }
+                        catch {
+                            return jsonResponse({ error: 'Invalid JSON' }, 400);
+                        }
+                        if (typeof body?.code !== 'string') {
+                            return jsonResponse({ error: 'Invite code must be a string' }, 400);
+                        }
+                        const code = body.code.trim();
+                        if (!code) {
+                            return jsonResponse({ error: 'Invite code is required' }, 400);
+                        }
+                        const result = store.redeemInvite(code);
+                        if (!result) {
+                            return jsonResponse({ error: 'Invalid or expired invite code' }, 401);
+                        }
+                        logger.info(`Friend "${result.friend.username}" redeemed invite via code entry`);
+                        return jsonResponse({
+                            authenticated: true,
+                            username: result.friend.username,
+                            nickname: result.friend.nickname,
+                        }, 200, { 'Set-Cookie': buildSessionCookie(result.sessionToken, secure) });
+                    }
+                    // ─── Update nickname ────────────────────────────────────
+                    if (pathname === '/api/nickname' && request.method === 'POST') {
+                        const friend = authenticateFriend(request, store);
+                        if (!friend) {
+                            return jsonResponse({ error: 'Unauthorized' }, 401);
+                        }
+                        let body = null;
+                        try {
+                            body = await request.json();
+                        }
+                        catch {
+                            return jsonResponse({ error: 'Invalid JSON' }, 400);
+                        }
+                        if (typeof body?.nickname !== 'string') {
+                            return jsonResponse({ error: 'Nickname must be a string' }, 400);
+                        }
+                        const newNickname = body.nickname.trim();
+                        if (!newNickname || newNickname.length > 64) {
+                            return jsonResponse({ error: 'Nickname must be 1–64 characters' }, 400);
+                        }
+                        store.updateNickname(friend.username, newNickname);
+                        return jsonResponse({ ok: true, nickname: newNickname });
+                    }
+                    // ─── Chat API (message) ─────────────────────────────────
+                    if (pathname === '/api/chat' && request.method === 'POST') {
+                        const friend = authenticateFriend(request, store);
+                        if (!friend) {
+                            return jsonResponse({ error: 'Unauthorized' }, 401);
+                        }
+                        let body = null;
+                        try {
+                            body = await request.json();
+                        }
+                        catch {
+                            return jsonResponse({ error: 'Invalid JSON' }, 400);
+                        }
+                        if (typeof body?.message !== 'string') {
+                            return jsonResponse({ error: 'Message is required' }, 400);
+                        }
+                        const message = body.message.trim();
+                        if (!message) {
+                            return jsonResponse({ error: 'Message is required' }, 400);
+                        }
+                        store.touchLastSeen(friend.username);
+                        const userId = `friend:${friend.username}`;
+                        // SSE streaming response
+                        if (onMessageStream) {
+                            const stream = new ReadableStream({
+                                start(controller) {
+                                    let isClosed = false;
+                                    const heartbeat = setInterval(() => {
+                                        if (isClosed) {
+                                            clearInterval(heartbeat);
+                                            return;
+                                        }
+                                        try {
+                                            controller.enqueue(textEncoder.encode(': heartbeat\n\n'));
+                                        }
+                                        catch {
+                                            clearInterval(heartbeat);
+                                        }
+                                    }, 8_000);
+                                    const send = (payload) => {
+                                        if (isClosed)
+                                            return;
+                                        try {
+                                            const data = typeof payload === 'string'
+                                                ? payload
+                                                : JSON.stringify(payload);
+                                            controller.enqueue(textEncoder.encode(`data: ${data}\n\n`));
+                                            if (typeof payload === 'object' &&
+                                                payload &&
+                                                payload.type === 'done') {
+                                                isClosed = true;
+                                                clearInterval(heartbeat);
+                                                controller.close();
+                                            }
+                                        }
+                                        catch {
+                                            isClosed = true;
+                                            clearInterval(heartbeat);
+                                        }
+                                    };
+                                    onMessageStream(message, userId, send)
+                                        .then(() => {
+                                        if (!isClosed) {
+                                            isClosed = true;
+                                            clearInterval(heartbeat);
+                                            try {
+                                                controller.close();
+                                            }
+                                            catch { }
+                                        }
+                                    })
+                                        .catch((error) => {
+                                        if (!isClosed) {
+                                            send({
+                                                type: 'error',
+                                                error: error?.message || 'Streaming error.',
+                                            });
+                                            isClosed = true;
+                                            clearInterval(heartbeat);
+                                            try {
+                                                controller.close();
+                                            }
+                                            catch { }
+                                        }
+                                    });
+                                },
+                            });
+                            return new Response(stream, {
+                                headers: {
+                                    'Content-Type': 'text/event-stream',
+                                    'Cache-Control': 'no-cache',
+                                    Connection: 'keep-alive',
+                                },
+                            });
+                        }
+                        // Fallback: non-streaming
+                        try {
+                            const responseText = await onMessage(message, userId);
+                            return jsonResponse({ content: responseText });
+                        }
+                        catch (error) {
+                            logger.error(`Friends chat onMessage error for userId=${userId}: ${error?.message}`);
+                            return jsonResponse({ error: 'Internal server error' }, 500);
+                        }
+                    }
+                    // ─── 404 fallback ───────────────────────────────────────
+                    return jsonResponse({ error: 'Not found' }, 404);
+                },
+            });
+            logger.info(`Friends chat server listening on ${host}:${port}`);
+        },
+        stop() {
+            if (server) {
+                server.stop();
+                server = null;
+                logger.info('Friends chat server stopped');
+            }
+        },
+        getPort() {
+            return server?.port || port;
+        },
+    };
+}

package/dist/store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Friends Invite Store
+ *
+ * Manages invite codes, friend sessions, and friend user records.
+ * Uses a SQLite database (via Bun's built-in `bun:sqlite`) stored
+ * in the Tiny Claw data directory.
+ *
+ * Each friend has:
+ *   - username: permanent identifier, set by owner
+ *   - nickname: display name, changeable by the friend
+ *   - inviteCode: single-use, consumed on first use → sets session cookie
+ *   - sessionToken: long-lived browser auth after invite is redeemed
+ */
+export interface FriendUser {
+    username: string;
+    nickname: string;
+    inviteCode: string | null;
+    sessionToken: string | null;
+    createdAt: number;
+    lastSeen: number;
+}
+/**
+ * Generate a short, URL-safe invite code.
+ * 8 chars from a base-62 alphabet — ~47 bits of entropy.
+ */
+export declare function generateInviteCode(): string;
+/**
+ * Generate a cryptographic session token.
+ * 32 hex chars — 128 bits of entropy.
+ */
+export declare function generateSessionToken(): string;
+export declare class InviteStore {
+    private db;
+    constructor(dbPath: string);
+    private migrate;
+    /** Create a new friend with a fresh invite code. */
+    createFriend(username: string, nickname?: string): FriendUser;
+    /** Look up a friend by username. */
+    getFriend(username: string): FriendUser | null;
+    /** Look up a friend by their invite code. */
+    getByInviteCode(code: string): FriendUser | null;
+    /** Look up a friend by their session token. */
+    getBySessionToken(token: string): FriendUser | null;
+    /**
+     * Redeem an invite code — consumes the code and sets a session token.
+     * Returns the session token on success, null if code is invalid.
+     */
+    redeemInvite(code: string): {
+        sessionToken: string;
+        friend: FriendUser;
+    } | null;
+    /** Regenerate an invite code for an existing friend (invalidates old session). */
+    regenerateInvite(username: string): string | null;
+    /** Update a friend's nickname. */
+    updateNickname(username: string, newNickname: string): boolean;
+    /** Touch last_seen timestamp. */
+    touchLastSeen(username: string): void;
+    /** Revoke a friend's access — clears session and invite code. */
+    revokeFriend(username: string): boolean;
+    /** List all friends. */
+    listFriends(): FriendUser[];
+    /** Check if a username already exists. */
+    exists(username: string): boolean;
+    private rowToFriend;
+    close(): void;
+}

package/dist/store.js

@@ -0,0 +1,183 @@
+/**
+ * Friends Invite Store
+ *
+ * Manages invite codes, friend sessions, and friend user records.
+ * Uses a SQLite database (via Bun's built-in `bun:sqlite`) stored
+ * in the Tiny Claw data directory.
+ *
+ * Each friend has:
+ *   - username: permanent identifier, set by owner
+ *   - nickname: display name, changeable by the friend
+ *   - inviteCode: single-use, consumed on first use → sets session cookie
+ *   - sessionToken: long-lived browser auth after invite is redeemed
+ */
+import { Database } from 'bun:sqlite';
+import { logger } from '@tinyclaw/logger';
+/**
+ * Generate a short, URL-safe invite code.
+ * 8 chars from a base-62 alphabet — ~47 bits of entropy.
+ */
+export function generateInviteCode() {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    const bytes = crypto.getRandomValues(new Uint8Array(8));
+    return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join('');
+}
+/**
+ * Generate a cryptographic session token.
+ * 32 hex chars — 128 bits of entropy.
+ */
+export function generateSessionToken() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export class InviteStore {
+    db;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.exec('PRAGMA journal_mode = WAL;');
+        this.db.exec('PRAGMA foreign_keys = ON;');
+        this.migrate();
+    }
+    migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS friends (
+        username      TEXT PRIMARY KEY,
+        nickname      TEXT NOT NULL,
+        invite_code   TEXT UNIQUE,
+        session_token TEXT UNIQUE,
+        created_at    INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+        last_seen     INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+      );
+    `);
+        logger.info('Friends invite store ready');
+    }
+    /** Create a new friend with a fresh invite code. */
+    createFriend(username, nickname) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        if (this.exists(sanitized)) {
+            throw new Error(`A friend with username "${sanitized}" already exists`);
+        }
+        const displayName = nickname || username;
+        const inviteCode = generateInviteCode();
+        const now = Date.now();
+        this.db.run(`INSERT INTO friends (username, nickname, invite_code, created_at, last_seen)
+       VALUES (?, ?, ?, ?, ?)`, [sanitized, displayName, inviteCode, now, now]);
+        return {
+            username: sanitized,
+            nickname: displayName,
+            inviteCode,
+            sessionToken: null,
+            createdAt: now,
+            lastSeen: now,
+        };
+    }
+    /** Look up a friend by username. */
+    getFriend(username) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const row = this.db
+            .query(`SELECT username, nickname, invite_code, session_token, created_at, last_seen
+         FROM friends WHERE username = ?`)
+            .get(sanitized);
+        if (!row)
+            return null;
+        return this.rowToFriend(row);
+    }
+    /** Look up a friend by their invite code. */
+    getByInviteCode(code) {
+        const row = this.db
+            .query(`SELECT username, nickname, invite_code, session_token, created_at, last_seen
+         FROM friends WHERE invite_code = ?`)
+            .get(code);
+        if (!row)
+            return null;
+        return this.rowToFriend(row);
+    }
+    /** Look up a friend by their session token. */
+    getBySessionToken(token) {
+        if (!token)
+            return null;
+        const row = this.db
+            .query(`SELECT username, nickname, invite_code, session_token, created_at, last_seen
+         FROM friends WHERE session_token = ?`)
+            .get(token);
+        if (!row)
+            return null;
+        return this.rowToFriend(row);
+    }
+    /**
+     * Redeem an invite code — consumes the code and sets a session token.
+     * Returns the session token on success, null if code is invalid.
+     */
+    redeemInvite(code) {
+        const sessionToken = generateSessionToken();
+        const now = Date.now();
+        // Atomic: consume the invite code and set the session token in one statement
+        const row = this.db
+            .query(`UPDATE friends SET invite_code = NULL, session_token = ?, last_seen = ?
+         WHERE invite_code = ? RETURNING username, nickname, invite_code, session_token, created_at, last_seen`)
+            .get(sessionToken, now, code);
+        if (!row)
+            return null;
+        return {
+            sessionToken,
+            friend: this.rowToFriend(row),
+        };
+    }
+    /** Regenerate an invite code for an existing friend (invalidates old session). */
+    regenerateInvite(username) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const friend = this.getFriend(sanitized);
+        if (!friend)
+            return null;
+        const newCode = generateInviteCode();
+        // New code, clear session so they must re-authenticate
+        this.db.run(`UPDATE friends SET invite_code = ?, session_token = NULL WHERE username = ?`, [newCode, sanitized]);
+        return newCode;
+    }
+    /** Update a friend's nickname. */
+    updateNickname(username, newNickname) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const result = this.db.run(`UPDATE friends SET nickname = ? WHERE username = ?`, [newNickname, sanitized]);
+        return result.changes > 0;
+    }
+    /** Touch last_seen timestamp. */
+    touchLastSeen(username) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        this.db.run(`UPDATE friends SET last_seen = ? WHERE username = ?`, [Date.now(), sanitized]);
+    }
+    /** Revoke a friend's access — clears session and invite code. */
+    revokeFriend(username) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const result = this.db.run(`UPDATE friends SET invite_code = NULL, session_token = NULL WHERE username = ?`, [sanitized]);
+        return result.changes > 0;
+    }
+    /** List all friends. */
+    listFriends() {
+        const rows = this.db
+            .query(`SELECT username, nickname, invite_code, session_token, created_at, last_seen
+         FROM friends ORDER BY created_at ASC`)
+            .all();
+        return rows.map((row) => this.rowToFriend(row));
+    }
+    /** Check if a username already exists. */
+    exists(username) {
+        const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const row = this.db
+            .query(`SELECT 1 FROM friends WHERE username = ?`)
+            .get(sanitized);
+        return row !== null;
+    }
+    rowToFriend(row) {
+        return {
+            username: row.username,
+            nickname: row.nickname,
+            inviteCode: row.invite_code || null,
+            sessionToken: row.session_token || null,
+            createdAt: row.created_at,
+            lastSeen: row.last_seen,
+        };
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Friends Chat Tools
+ *
+ * Agent tools for managing friend invites. These are registered as pairing
+ * tools so the AI agent can create invite links, regenerate codes, revoke
+ * access, and list friends conversationally.
+ *
+ * All tools are owner-only (checked by the agent loop's authority system).
+ */
+import type { Tool, ConfigManagerInterface } from '@tinyclaw/types';
+import { InviteStore } from './store.js';
+/** Config key for the enabled flag. */
+export declare const FRIENDS_ENABLED_CONFIG_KEY = "channels.friends.enabled";
+/** Config key for the plugin server port. */
+export declare const FRIENDS_PORT_CONFIG_KEY = "channels.friends.port";
+/** Config key for the base URL (for generating invite links). */
+export declare const FRIENDS_BASE_URL_CONFIG_KEY = "channels.friends.baseUrl";
+/** The plugin's package ID. */
+export declare const FRIENDS_PLUGIN_ID = "@tinyclaw/plugin-channel-friends";
+export declare function createFriendsTools(store: InviteStore, configManager: ConfigManagerInterface): Tool[];

package/dist/tools.js

@@ -0,0 +1,164 @@
+/**
+ * Friends Chat Tools
+ *
+ * Agent tools for managing friend invites. These are registered as pairing
+ * tools so the AI agent can create invite links, regenerate codes, revoke
+ * access, and list friends conversationally.
+ *
+ * All tools are owner-only (checked by the agent loop's authority system).
+ */
+/** Config key for the enabled flag. */
+export const FRIENDS_ENABLED_CONFIG_KEY = 'channels.friends.enabled';
+/** Config key for the plugin server port. */
+export const FRIENDS_PORT_CONFIG_KEY = 'channels.friends.port';
+/** Config key for the base URL (for generating invite links). */
+export const FRIENDS_BASE_URL_CONFIG_KEY = 'channels.friends.baseUrl';
+/** The plugin's package ID. */
+export const FRIENDS_PLUGIN_ID = '@tinyclaw/plugin-channel-friends';
+export function createFriendsTools(store, configManager) {
+    return [
+        {
+            name: 'friends_chat_invite',
+            description: 'Create a new friend and generate an invite link for the Friends Web Chat. ' +
+                'The owner must provide a unique username. An invite code and URL will be generated. ' +
+                'The friend uses the link or code to start chatting. ' +
+                'The invite code is single-use — once redeemed, the friend gets a session cookie.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    username: {
+                        type: 'string',
+                        description: 'Unique username for the friend (lowercase alphanumeric + underscores). ' +
+                            'This is permanent and identifies the friend in FRIENDS.md.',
+                    },
+                    nickname: {
+                        type: 'string',
+                        description: 'Optional display name for the friend. Defaults to the username. ' +
+                            'The friend can change this later.',
+                    },
+                },
+                required: ['username'],
+            },
+            async execute(args) {
+                const username = (args.username || '').trim();
+                if (!username) {
+                    return 'Error: username is required.';
+                }
+                const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+                if (sanitized.length < 2 || sanitized.length > 32) {
+                    return 'Error: username must be 2–32 characters (letters, numbers, underscores).';
+                }
+                if (store.exists(sanitized)) {
+                    return `Error: a friend with username "${sanitized}" already exists. Use friends_chat_reinvite to generate a new invite code for them.`;
+                }
+                const nickname = (args.nickname || '').trim() || undefined;
+                const friend = store.createFriend(sanitized, nickname);
+                const baseUrl = configManager.get(FRIENDS_BASE_URL_CONFIG_KEY) || '';
+                const port = configManager.get(FRIENDS_PORT_CONFIG_KEY) || 3001;
+                const base = baseUrl || `http://localhost:${port}`;
+                const inviteUrl = `${base}/chat?invite=${friend.inviteCode}`;
+                return (`Friend "${friend.nickname}" (username: ${friend.username}) created!\n\n` +
+                    `Invite URL: ${inviteUrl}\n` +
+                    `Invite code: ${friend.inviteCode}\n\n` +
+                    `Share the URL or code with your friend. ` +
+                    `The code is single-use — once they open the link and start chatting, ` +
+                    `their browser is authenticated. If they switch browsers or clear cookies, ` +
+                    `use friends_chat_reinvite to generate a new code for them.`);
+            },
+        },
+        {
+            name: 'friends_chat_reinvite',
+            description: 'Generate a new invite code for an existing friend. ' +
+                'Use this when a friend switches browsers, clears cookies, or loses access. ' +
+                'The old session is invalidated — the friend must use the new code to re-authenticate.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    username: {
+                        type: 'string',
+                        description: 'The username of the existing friend to re-invite.',
+                    },
+                },
+                required: ['username'],
+            },
+            async execute(args) {
+                const username = (args.username || '').trim();
+                if (!username) {
+                    return 'Error: username is required.';
+                }
+                const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+                const newCode = store.regenerateInvite(sanitized);
+                if (!newCode) {
+                    return `Error: no friend found with username "${sanitized}". Use friends_chat_invite to create a new friend.`;
+                }
+                const baseUrl = configManager.get(FRIENDS_BASE_URL_CONFIG_KEY) || '';
+                const port = configManager.get(FRIENDS_PORT_CONFIG_KEY) || 3001;
+                const base = baseUrl || `http://localhost:${port}`;
+                const inviteUrl = `${base}/chat?invite=${newCode}`;
+                return (`New invite generated for "${sanitized}"!\n\n` +
+                    `Invite URL: ${inviteUrl}\n` +
+                    `Invite code: ${newCode}\n\n` +
+                    `Their previous session has been invalidated. ` +
+                    `Share the new link or code with them.`);
+            },
+        },
+        {
+            name: 'friends_chat_revoke',
+            description: 'Revoke a friend\'s access to the Friends Web Chat. ' +
+                'Their session and any pending invite code are invalidated immediately. ' +
+                'To restore access later, use friends_chat_reinvite.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    username: {
+                        type: 'string',
+                        description: 'The username of the friend to revoke.',
+                    },
+                },
+                required: ['username'],
+            },
+            async execute(args) {
+                const username = (args.username || '').trim();
+                if (!username) {
+                    return 'Error: username is required.';
+                }
+                const sanitized = username.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+                const revoked = store.revokeFriend(sanitized);
+                if (!revoked) {
+                    return `Error: no friend found with username "${sanitized}".`;
+                }
+                return (`Access revoked for "${sanitized}". ` +
+                    `Their session cookie and invite code have been invalidated. ` +
+                    `Use friends_chat_reinvite to restore access.`);
+            },
+        },
+        {
+            name: 'friends_chat_list',
+            description: 'List all registered friends and their status. ' +
+                'Shows username, nickname, whether they have an active session or pending invite, ' +
+                'and when they were last seen.',
+            parameters: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+            async execute() {
+                const friends = store.listFriends();
+                if (friends.length === 0) {
+                    return 'No friends registered yet. Use friends_chat_invite to invite someone.';
+                }
+                const lines = friends.map((f) => {
+                    const status = f.sessionToken
+                        ? 'active'
+                        : f.inviteCode
+                            ? 'invite pending'
+                            : 'revoked';
+                    const lastSeenDate = new Date(f.lastSeen);
+                    const lastSeen = f.lastSeen && !isNaN(lastSeenDate.getTime()) ? lastSeenDate.toLocaleString() : 'Unknown';
+                    return `- **${f.nickname}** (@${f.username}) — ${status}, last seen: ${lastSeen}`;
+                });
+                return `**Registered Friends (${friends.length})**\n\n${lines.join('\n')}`;
+            },
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@tinyclaw/plugin-channel-friends",
+  "version": "1.0.1-dev.3004a38",
+  "description": "Friends web chat channel plugin for Tiny Claw",
+  "license": "GPL-3.0",
+  "author": "Waren Gonzaga",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warengonzaga/tinyclaw.git",
+    "directory": "plugins/channel/plugin-channel-friends"
+  },
+  "homepage": "https://github.com/warengonzaga/tinyclaw/tree/main/plugins/channel/plugin-channel-friends#readme",
+  "bugs": {
+    "url": "https://github.com/warengonzaga/tinyclaw/issues"
+  },
+  "keywords": [
+    "tinyclaw",
+    "plugin",
+    "channel",
+    "friends",
+    "chat"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tinyclaw/logger": "workspace:*",
+    "@tinyclaw/types": "workspace:*"
+  }
+}