@hmawla/co-assistant 1.0.0

package/heartbeats/email-reply-check.heartbeat.md

@@ -0,0 +1,39 @@
+You are checking my recent emails for any that require a reply from me.
+
+## Instructions
+
+1. Use the `gmail_search_emails` tool to fetch my last 5 emails (query: `in:inbox`, maxResults: 5).
+2. For each email, use `gmail_read_email` to read its full content.
+3. Skip any email whose message ID appears in the deduplication list below.
+4. For each **new** email, determine whether it requires a reply from me. Consider:
+   - Direct questions asked to me
+   - Action items or requests directed at me
+   - Invitations or RSVPs awaiting my response
+   - Important threads where I'm expected to respond
+   - Do NOT flag: newsletters, automated notifications, marketing, no-reply senders, receipts
+5. For each email that needs a reply, suggest a concise, professional reply draft.
+
+## Output Format
+
+For each email that needs a reply, format your output like this:
+
+**📧 From:** [sender]
+**Subject:** [subject]
+**Why reply:** [brief reason]
+**Suggested reply:**
+> [your suggested reply text]
+
+---
+
+If no emails require a reply, do not say anything unless invoked with /heartbeat
+
+## Deduplication
+
+{{DEDUP_STATE}}
+
+## IMPORTANT — Deduplication Marker
+
+At the very end of your response, you MUST output exactly one line in this format with ALL email message IDs you checked (whether they needed a reply or not). This prevents re-checking the same emails next time:
+
+<!-- PROCESSED: msg_id_1, msg_id_2, msg_id_3, msg_id_4, msg_id_5 -->
+Also, make sure to not output the same message id multiple times, so if it exist don't push it.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@hmawla/co-assistant",
+  "version": "1.0.0",
+  "description": "AI-powered Telegram personal assistant using GitHub Copilot SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli/index.js"
+  },
+  "bin": {
+    "co-assistant": "dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "plugins/",
+    "heartbeats/*.heartbeat.md",
+    "personality.md",
+    "user.md.example",
+    "config.json.example",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli/index.ts",
+    "start": "node dist/index.js",
+    "cli": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "assistant",
+    "telegram",
+    "bot",
+    "copilot",
+    "github-copilot",
+    "copilot-sdk",
+    "chatbot",
+    "plugins",
+    "gmail",
+    "google-calendar",
+    "automation"
+  ],
+  "author": {
+    "name": "Hussein Al Mawla",
+    "email": "hussein@kockatoos.co"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hmawla/co-assistant.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hmawla/co-assistant/issues"
+  },
+  "homepage": "https://github.com/hmawla/co-assistant#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@github/copilot-sdk": "^0.2.1",
+    "better-sqlite3": "^12.8.0",
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.0",
+    "pino": "^10.3.1",
+    "telegraf": "^4.16.3",
+    "tsx": "^4.21.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.2",
+    "pino-pretty": "^13.1.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2"
+  }
+}

package/personality.md

@@ -0,0 +1,48 @@
+# Co-Assistant Personality
+
+> **Edit this file to change how the AI responds.**
+> The contents are prepended to every message as system-level instructions.
+> Changes take effect on the next message — no restart required.
+
+---
+
+## Identity
+
+You are **Co-Assistant**, a personal AI assistant that communicates through Telegram.
+You are powered by the GitHub Copilot SDK and have access to tools (email, calendar, etc.)
+provided by plugins. You act on behalf of the user — your job is to be genuinely useful.
+
+## Tone & Style
+
+- **Professional yet warm** — like a reliable colleague, not a corporate robot.
+- **Concise by default** — get to the point. No filler phrases like "Sure!", "Of course!",
+  "Absolutely!", or "Great question!". Just answer.
+- **Expand when it matters** — if the topic is complex or the user explicitly asks for detail,
+  give a thorough response. Use your judgment.
+- **Plain language** — avoid jargon unless the user uses it first. No buzzwords.
+- **Structured when helpful** — use bullet points, numbered lists, or short paragraphs for
+  clarity. Avoid walls of text.
+
+## Thinking & Decision-Making
+
+- **Be proactive** — if you notice something the user likely wants (e.g. a follow-up action,
+  a related piece of information), mention it briefly.
+- **Ask before acting** — for irreversible actions (sending emails, deleting events, etc.),
+  confirm with the user first. Read-only actions (searching, listing) are fine to do immediately.
+- **Admit uncertainty** — if you don't know something or a tool call fails, say so plainly.
+  Don't guess or fabricate information.
+- **Use tools efficiently** — when you have tools available, use them rather than speculating.
+  Check the calendar instead of saying "I think you might have…".
+
+## Formatting (Telegram)
+
+- Telegram supports basic Markdown: **bold**, _italic_, `code`, ```code blocks```.
+- Keep messages under ~2000 characters when possible. Split longer responses naturally.
+- Use emoji sparingly and purposefully (✅ for confirmations, ⚠️ for warnings, 📧 for email
+  actions, 📅 for calendar). Don't overdo it.
+
+## Boundaries
+
+- You are a helpful assistant, not a therapist, lawyer, or doctor. Redirect appropriately.
+- Never share the user's credentials, tokens, or personal data in responses.
+- If a request is unclear, ask one focused clarifying question rather than guessing.

package/plugins/gmail/README.md

@@ -0,0 +1,78 @@
+# Gmail Plugin
+
+Send, read, and search Gmail messages via the Gmail REST API. This plugin is a
+**reference implementation** showing how to build Co-Assistant plugins end-to-end.
+
+## Features
+
+| Tool             | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `search_emails`  | Search Gmail using the same query syntax as the Gmail UI |
+| `read_email`     | Read the full content of an email by message ID          |
+| `send_email`     | Compose and send a plain-text email                      |
+
+## Getting Google OAuth2 Credentials
+
+Follow these steps to obtain the credentials the plugin requires:
+
+1. **Create a Google Cloud project**
+   - Go to the [Google Cloud Console](https://console.cloud.google.com/).
+   - Create a new project (or select an existing one).
+
+2. **Configure the OAuth consent screen**
+   - Navigate to **APIs & Services → OAuth consent screen**.
+   - Set to "External" for personal use, add your email as a test user.
+
+3. **Enable the Gmail API**
+   - Navigate to **APIs & Services → Library**.
+   - Search for "Gmail API" and click **Enable**.
+
+4. **Create OAuth2 credentials**
+   - Go to **APIs & Services → Credentials**.
+   - Click **Create Credentials → OAuth client ID**.
+   - Choose **Desktop app** as the application type (recommended — allows automatic localhost redirect).
+   - Download the **client secret JSON file**.
+
+5. **Run the setup wizard**
+   ```bash
+   npx tsx src/cli/index.ts setup --plugin gmail
+   ```
+   The setup will:
+   - Ask for your downloaded JSON file path (extracts credentials, does not store the file)
+   - Open your browser to authorize Gmail access
+   - Capture the refresh token automatically via a local callback server
+
+## Required Credentials
+
+| Key                    | Description                    | Type    |
+| ---------------------- | ------------------------------ | ------- |
+| `GMAIL_CLIENT_ID`     | Google OAuth2 Client ID        | `oauth` |
+| `GMAIL_CLIENT_SECRET`  | Google OAuth2 Client Secret    | `oauth` |
+| `GMAIL_REFRESH_TOKEN`  | Google OAuth2 Refresh Token    | `oauth` |
+
+Configure them via the CLI:
+
+```bash
+co-assistant plugin configure gmail
+```
+
+Or set them in `config.json` under `plugins.gmail.credentials`.
+
+## Example Usage
+
+Once configured, the AI assistant can use the tools naturally:
+
+> **User:** Do I have any unread emails from Alice?
+>
+> The assistant calls `search_emails` with query `from:alice is:unread` and
+> returns a summary of matching messages.
+
+> **User:** Read message ID `18f1a2b3c4d5e6f7`
+>
+> The assistant calls `read_email` and returns the full subject, sender, date,
+> and body text.
+
+> **User:** Send an email to bob@example.com about tomorrow's meeting
+>
+> The assistant calls `send_email` with the recipient, a generated subject line,
+> and the composed body text.

package/plugins/gmail/auth.ts

@@ -0,0 +1,92 @@
+/**
+ * @module gmail/auth
+ * @description Google OAuth2 helper for the Gmail plugin.
+ *
+ * Manages access-token acquisition using an offline refresh token.
+ * Uses the built-in `fetch` API (Node 18+) — no external HTTP library required.
+ */
+
+/** Google's OAuth2 token endpoint used to exchange a refresh token for an access token. */
+const GOOGLE_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+
+/**
+ * Manages Google OAuth2 tokens for Gmail API access.
+ *
+ * Holds the long-lived refresh token and transparently obtains short-lived
+ * access tokens, caching them until they expire.
+ */
+export class GmailAuth {
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private readonly refreshToken: string;
+
+  /** Cached access token from the most recent refresh. */
+  private accessToken: string | null = null;
+
+  /** Epoch-millisecond timestamp at which {@link accessToken} expires. */
+  private tokenExpiresAt = 0;
+
+  /**
+   * @param clientId     - Google OAuth2 Client ID.
+   * @param clientSecret - Google OAuth2 Client Secret.
+   * @param refreshToken - Long-lived Google OAuth2 Refresh Token.
+   */
+  constructor(clientId: string, clientSecret: string, refreshToken: string) {
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.refreshToken = refreshToken;
+  }
+
+  /**
+   * Returns `true` when all three required credentials are non-empty strings.
+   */
+  isConfigured(): boolean {
+    return Boolean(this.clientId && this.clientSecret && this.refreshToken);
+  }
+
+  /**
+   * Obtain a valid access token, refreshing automatically when necessary.
+   *
+   * The token is cached in memory and reused until 60 seconds before its
+   * stated expiry to account for clock skew and network latency.
+   *
+   * @returns A valid Google OAuth2 access token.
+   * @throws {Error} If the token refresh request fails.
+   */
+  async getAccessToken(): Promise<string> {
+    // Return the cached token if it is still valid (with a 60-second buffer).
+    if (this.accessToken && Date.now() < this.tokenExpiresAt - 60_000) {
+      return this.accessToken;
+    }
+
+    const body = new URLSearchParams({
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      refresh_token: this.refreshToken,
+      grant_type: "refresh_token",
+    });
+
+    const response = await fetch(GOOGLE_TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Failed to refresh Google access token (${response.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await response.json()) as {
+      access_token: string;
+      expires_in: number;
+    };
+
+    this.accessToken = data.access_token;
+    this.tokenExpiresAt = Date.now() + data.expires_in * 1000;
+
+    return this.accessToken;
+  }
+}

package/plugins/gmail/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @module gmail
+ * @description Gmail plugin entry point.
+ *
+ * Provides email searching, reading, and sending capabilities via the
+ * Gmail REST API. This plugin serves as a reference implementation for
+ * building Co-Assistant plugins.
+ */
+
+import type {
+  CoAssistantPlugin,
+  PluginContext,
+  ToolDefinition,
+} from "../../src/plugins/types.js";
+import { GmailAuth } from "./auth.js";
+import { createGmailTools } from "./tools.js";
+
+/**
+ * Factory function that creates a new Gmail plugin instance.
+ *
+ * The plugin follows the standard Co-Assistant lifecycle:
+ * 1. `initialize()` — sets up the OAuth2 auth helper and creates tool defs.
+ * 2. `getTools()`   — returns the tool definitions for the AI session.
+ * 3. `destroy()`    — cleans up resources (no-op for this plugin).
+ *
+ * @returns A fully-formed {@link CoAssistantPlugin} for Gmail integration.
+ */
+export default function createPlugin(): CoAssistantPlugin {
+  let auth: GmailAuth;
+  let toolDefs: ToolDefinition[];
+
+  return {
+    id: "gmail",
+    name: "Gmail Plugin",
+    version: "1.0.0",
+    description: "Send, read, and search Gmail messages",
+    requiredCredentials: [
+      "GMAIL_CLIENT_ID",
+      "GMAIL_CLIENT_SECRET",
+      "GMAIL_REFRESH_TOKEN",
+    ],
+
+    async initialize(context: PluginContext) {
+      auth = new GmailAuth(
+        context.credentials.GMAIL_CLIENT_ID,
+        context.credentials.GMAIL_CLIENT_SECRET,
+        context.credentials.GMAIL_REFRESH_TOKEN,
+      );
+
+      toolDefs = createGmailTools(auth, context.logger);
+      context.logger.info("Gmail plugin initialized");
+    },
+
+    getTools(): ToolDefinition[] {
+      return toolDefs;
+    },
+
+    async destroy() {
+      // No persistent connections or resources to release.
+    },
+
+    async healthCheck(): Promise<boolean> {
+      return auth.isConfigured();
+    },
+  };
+}

package/plugins/gmail/plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "gmail",
+  "name": "Gmail Plugin",
+  "version": "1.0.0",
+  "description": "Send, read, and search Gmail messages via the Gmail API",
+  "author": "co-assistant",
+  "requiredCredentials": [
+    { "key": "GMAIL_CLIENT_ID", "description": "Google OAuth2 Client ID", "type": "oauth" },
+    { "key": "GMAIL_CLIENT_SECRET", "description": "Google OAuth2 Client Secret", "type": "oauth" },
+    { "key": "GMAIL_REFRESH_TOKEN", "description": "Google OAuth2 Refresh Token", "type": "oauth" }
+  ],
+  "dependencies": []
+}