@plosson/agentio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 agentio contributors
+
+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,112 @@
+# agentio
+
+CLI for LLM agents to interact with communication and tracking services.
+
+## Installation
+
+### Via npm/bun (recommended)
+
+```bash
+# Using bun
+bunx agentio --help
+
+# Using npm
+npx agentio --help
+
+# Global install
+bun add -g agentio
+# or
+npm install -g agentio
+```
+
+### Native binaries
+
+Download from [GitHub Releases](https://github.com/plosson/agentio/releases):
+
+| Platform | Binary |
+|----------|--------|
+| macOS Intel | `agentio-darwin-x64` |
+| macOS Apple Silicon | `agentio-darwin-arm64` |
+| Linux x64 | `agentio-linux-x64` |
+| Linux ARM64 | `agentio-linux-arm64` |
+| Windows x64 | `agentio-windows-x64.exe` |
+
+## Services
+
+| Service | Status | Commands |
+|---------|--------|----------|
+| Gmail | Available | `list`, `get`, `search`, `send`, `reply`, `archive`, `mark` |
+| Telegram | Available | `send` |
+| Slack | Planned | - |
+| JIRA | Planned | - |
+| Linear | Planned | - |
+
+## Usage
+
+### Gmail
+
+```bash
+# First, authenticate
+agentio gmail profile add
+
+# List recent emails
+agentio gmail list --limit 10
+
+# Search emails
+agentio gmail search --query "from:boss@company.com is:unread"
+
+# Get a specific email
+agentio gmail get <message-id>
+
+# Send an email
+agentio gmail send --to user@example.com --subject "Hello" --body "Message body"
+
+# Or pipe content
+echo "Message body" | agentio gmail send --to user@example.com --subject "Hello"
+```
+
+### Telegram
+
+```bash
+# Set up bot profile (interactive wizard)
+agentio telegram profile add
+
+# Send message to channel
+agentio telegram send "Hello from agentio!"
+
+# Send with formatting
+agentio telegram send --parse-mode markdown "**Bold** and _italic_"
+```
+
+## Multi-Profile Support
+
+Each service supports multiple named profiles:
+
+```bash
+# Add profiles for different accounts
+agentio gmail profile add --profile work
+agentio gmail profile add --profile personal
+
+# Use specific profile
+agentio gmail list --profile work
+```
+
+## Design
+
+agentio is designed for LLM consumption:
+
+- **Structured output**: Human-readable text output optimized for LLM parsing
+- **Clear errors**: Error messages written to stderr with suggestions
+- **Stdin support**: Pipe content to commands that accept body text
+- **Multi-profile**: Manage multiple accounts per service
+
+## Configuration
+
+Configuration is stored in `~/.config/agentio/`:
+
+- `config.json` - Profile names and defaults
+- `tokens.enc` - Encrypted credentials (AES-256-GCM)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@plosson/agentio",
+  "version": "0.1.0",
+  "description": "CLI for LLM agents to interact with communication and tracking services",
+  "type": "module",
+  "license": "MIT",
+  "author": "plosson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plosson/agentio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/plosson/agentio/issues"
+  },
+  "homepage": "https://github.com/plosson/agentio#readme",
+  "keywords": [
+    "cli",
+    "llm",
+    "agent",
+    "gmail",
+    "telegram",
+    "automation",
+    "ai",
+    "mcp"
+  ],
+  "bin": {
+    "agentio": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "build:native": "bun build src/index.ts --compile --outfile dist/agentio",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "googleapis": "^169.0.0"
+  }
+}

package/src/auth/oauth.ts

@@ -0,0 +1,132 @@
+import { createServer, type Server } from 'http';
+import { URL } from 'url';
+import { google } from 'googleapis';
+import { GOOGLE_OAUTH_CONFIG } from '../config/credentials';
+import type { OAuthTokens } from '../types/tokens';
+
+const GMAIL_SCOPES = [
+  'https://www.googleapis.com/auth/gmail.modify',
+  'https://www.googleapis.com/auth/gmail.send',
+];
+
+const PORT_RANGE_START = 3000;
+const PORT_RANGE_END = 3010;
+
+async function findAvailablePort(): Promise<number> {
+  for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const server = createServer();
+        server.listen(port, () => {
+          server.close(() => resolve());
+        });
+        server.on('error', reject);
+      });
+      return port;
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`No available port found in range ${PORT_RANGE_START}-${PORT_RANGE_END}`);
+}
+
+export async function performOAuthFlow(
+  service: 'gmail' | 'gchat'
+): Promise<OAuthTokens> {
+  const port = await findAvailablePort();
+  const redirectUri = `http://localhost:${port}/callback`;
+
+  const oauth2Client = new google.auth.OAuth2(
+    GOOGLE_OAUTH_CONFIG.clientId,
+    GOOGLE_OAUTH_CONFIG.clientSecret,
+    redirectUri
+  );
+
+  const scopes = service === 'gmail' ? GMAIL_SCOPES : [];
+
+  const authUrl = oauth2Client.generateAuthUrl({
+    access_type: 'offline',
+    scope: scopes,
+    prompt: 'consent',
+  });
+
+  return new Promise((resolve, reject) => {
+    let server: Server;
+
+    const timeout = setTimeout(() => {
+      server?.close();
+      reject(new Error('OAuth flow timed out after 5 minutes'));
+    }, 5 * 60 * 1000);
+
+    server = createServer(async (req, res) => {
+      const url = new URL(req.url || '', `http://localhost:${port}`);
+
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      const code = url.searchParams.get('code');
+      const error = url.searchParams.get('error');
+
+      if (error) {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>');
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error(`OAuth error: ${error}`));
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h1>Missing Authorization Code</h1><p>You can close this window.</p></body></html>');
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error('Missing authorization code in OAuth callback'));
+        return;
+      }
+
+      try {
+        const { tokens } = await oauth2Client.getToken(code);
+
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h1>Authorization Successful!</h1><p>You can close this window and return to the terminal.</p></body></html>');
+
+        clearTimeout(timeout);
+        server.close();
+
+        resolve({
+          access_token: tokens.access_token!,
+          refresh_token: tokens.refresh_token || undefined,
+          expiry_date: tokens.expiry_date || undefined,
+          token_type: tokens.token_type || 'Bearer',
+          scope: tokens.scope || undefined,
+        });
+      } catch (err) {
+        res.writeHead(500);
+        res.end('Failed to exchange authorization code');
+        clearTimeout(timeout);
+        server.close();
+        reject(err);
+      }
+    });
+
+    server.listen(port, () => {
+      console.error(`\nOpening browser for authorization...`);
+      console.error(`If browser doesn't open, visit:\n${authUrl}\n`);
+
+      // Open browser
+      const open = process.platform === 'darwin' ? 'open' :
+                   process.platform === 'win32' ? 'start' : 'xdg-open';
+      Bun.spawn([open, authUrl], { stdout: 'ignore', stderr: 'ignore' });
+    });
+
+    server.on('error', (err) => {
+      clearTimeout(timeout);
+      server?.close();
+      reject(err);
+    });
+  });
+}

package/src/auth/token-manager.ts

@@ -0,0 +1,104 @@
+import { google } from 'googleapis';
+import { getCredentials, setCredentials } from './token-store';
+import { getProfile } from '../config/config-manager';
+import { GOOGLE_OAUTH_CONFIG } from '../config/credentials';
+import { CliError } from '../utils/errors';
+import type { ServiceName } from '../types/config';
+import type { OAuthTokens } from '../types/tokens';
+
+const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
+
+export async function getValidTokens(
+  service: ServiceName,
+  profileName?: string
+): Promise<{ tokens: OAuthTokens; profile: string }> {
+  const profile = await getProfile(service, profileName);
+
+  if (!profile) {
+    throw new CliError(
+      'PROFILE_NOT_FOUND',
+      profileName
+        ? `Profile "${profileName}" not found for ${service}`
+        : `No default profile configured for ${service}`,
+      `Run: agentio ${service} profile add`
+    );
+  }
+
+  const tokens = await getCredentials<OAuthTokens>(service, profile);
+
+  if (!tokens) {
+    throw new CliError(
+      'AUTH_FAILED',
+      `No tokens found for ${service} profile "${profile}"`,
+      `Run: agentio ${service} profile add --profile ${profile}`
+    );
+  }
+
+  // Check if token needs refresh
+  if (tokens.expiry_date && Date.now() > tokens.expiry_date - TOKEN_EXPIRY_BUFFER_MS) {
+    if (!tokens.refresh_token) {
+      throw new CliError(
+        'TOKEN_EXPIRED',
+        'Access token expired and no refresh token available',
+        `Run: agentio ${service} profile add --profile ${profile}`
+      );
+    }
+
+    const refreshed = await refreshTokens(service, profile, tokens);
+    return { tokens: refreshed, profile };
+  }
+
+  return { tokens, profile };
+}
+
+async function refreshTokens(
+  service: ServiceName,
+  profileName: string,
+  tokens: OAuthTokens
+): Promise<OAuthTokens> {
+  const oauth2Client = new google.auth.OAuth2(
+    GOOGLE_OAUTH_CONFIG.clientId,
+    GOOGLE_OAUTH_CONFIG.clientSecret
+  );
+
+  oauth2Client.setCredentials({
+    refresh_token: tokens.refresh_token,
+  });
+
+  try {
+    const { credentials } = await oauth2Client.refreshAccessToken();
+
+    const newTokens: OAuthTokens = {
+      access_token: credentials.access_token!,
+      refresh_token: credentials.refresh_token || tokens.refresh_token,
+      expiry_date: credentials.expiry_date || undefined,
+      token_type: credentials.token_type || 'Bearer',
+      scope: credentials.scope || tokens.scope,
+    };
+
+    await setCredentials(service, profileName, newTokens);
+    return newTokens;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    throw new CliError(
+      'TOKEN_EXPIRED',
+      `Failed to refresh access token: ${message}`,
+      `Run: agentio ${service} profile add --profile ${profileName}`
+    );
+  }
+}
+
+export function createGoogleAuth(tokens: OAuthTokens) {
+  const oauth2Client = new google.auth.OAuth2(
+    GOOGLE_OAUTH_CONFIG.clientId,
+    GOOGLE_OAUTH_CONFIG.clientSecret
+  );
+
+  oauth2Client.setCredentials({
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token,
+    expiry_date: tokens.expiry_date,
+  });
+
+  return oauth2Client;
+}

package/src/auth/token-store.ts

@@ -0,0 +1,114 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { hostname, userInfo } from 'os';
+import { CONFIG_DIR, ensureConfigDir } from '../config/config-manager';
+import type { StoredCredentials } from '../types/tokens';
+import type { ServiceName } from '../types/config';
+
+const TOKENS_FILE = join(CONFIG_DIR, 'tokens.enc');
+const ALGORITHM = 'aes-256-gcm';
+
+// Derive a machine-specific key from hostname + username
+function deriveKey(): Buffer {
+  const machineId = `${hostname()}-${userInfo().username}-agentio-v1`;
+  return scryptSync(machineId, 'agentio-salt', 32);
+}
+
+async function loadCredentials(): Promise<StoredCredentials> {
+  await ensureConfigDir();
+
+  if (!existsSync(TOKENS_FILE)) {
+    return {};
+  }
+
+  try {
+    const encrypted = await readFile(TOKENS_FILE, 'utf-8');
+    const { iv, tag, data } = JSON.parse(encrypted);
+
+    const key = deriveKey();
+    const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(iv, 'hex'));
+    decipher.setAuthTag(Buffer.from(tag, 'hex'));
+
+    const decrypted = Buffer.concat([
+      decipher.update(Buffer.from(data, 'hex')),
+      decipher.final(),
+    ]);
+
+    return JSON.parse(decrypted.toString('utf-8'));
+  } catch {
+    // File corrupted, tampered, or key changed - return empty credentials
+    return {};
+  }
+}
+
+async function saveCredentials(credentials: StoredCredentials): Promise<void> {
+  await ensureConfigDir();
+
+  const key = deriveKey();
+  const iv = randomBytes(16);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  const data = JSON.stringify(credentials);
+  const encrypted = Buffer.concat([
+    cipher.update(data, 'utf-8'),
+    cipher.final(),
+  ]);
+
+  const tag = cipher.getAuthTag();
+
+  const stored = JSON.stringify({
+    iv: iv.toString('hex'),
+    tag: tag.toString('hex'),
+    data: encrypted.toString('hex'),
+  });
+
+  await writeFile(TOKENS_FILE, stored, { mode: 0o600 });
+}
+
+export async function getCredentials<T = Record<string, unknown>>(
+  service: ServiceName,
+  profile: string
+): Promise<T | null> {
+  const credentials = await loadCredentials();
+  return (credentials[service]?.[profile] as T) || null;
+}
+
+export async function setCredentials(
+  service: ServiceName,
+  profile: string,
+  data: object
+): Promise<void> {
+  const credentials = await loadCredentials();
+
+  if (!credentials[service]) {
+    credentials[service] = {};
+  }
+
+  credentials[service][profile] = data as Record<string, unknown>;
+  await saveCredentials(credentials);
+}
+
+export async function removeCredentials(
+  service: ServiceName,
+  profile: string
+): Promise<boolean> {
+  const credentials = await loadCredentials();
+
+  if (!credentials[service]?.[profile]) {
+    return false;
+  }
+
+  delete credentials[service][profile];
+  await saveCredentials(credentials);
+  return true;
+}
+
+export async function hasCredentials(
+  service: ServiceName,
+  profile: string
+): Promise<boolean> {
+  const credentials = await loadCredentials();
+  return !!credentials[service]?.[profile];
+}