@hera-al/server 1.6.12 → 1.6.13

package/bundled/council/scripts/council.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+/**
+ * Council skill runner.
+ *
+ * Implements a 3-stage Karpathy-style LLM council:
+ *  - Stage 1: collect independent first answers from multiple models (parallel)
+ *  - Stage 2: each model critiques and ranks the anonymized answers
+ *  - Stage 3: a chairman model synthesizes a final answer using answers + rankings
+ *
+ * This script is designed to be executed via the Hera/GMaB "Bash" tool.
+ * It calls Pico subagents via an HTTP API exposed by the local server.
+ *
+ * Usage:
+ *   node council.mjs --query "..." [--models "ref1,ref2"] [--chair "ref"] [--timeoutMs 90000]
+ *
+ * Environment:
+ *   PICO_API_BASE   Base URL for Pico agent endpoint. Default: http://127.0.0.1:3111
+ *   PICO_API_KEY    Optional bearer token, if your gateway requires it.
+ */
+
+import process from 'node:process';
+
+const DEFAULT_MODELS = [
+  'openrouter/google/gemini-3-pro-preview',
+  'openrouter/x-ai/grok-4.1-fast',
+  'openrouter/openai/gpt-5.2',
+  // Opus is not available in pico_models in this instance; keep a placeholder
+  // 'anthropic/claude-3-opus' // example
+];
+
+const DEFAULT_CHAIR = 'openrouter/openai/gpt-5.2';
+
+function parseArgs(argv) {
+  const args = { query: null, models: null, chair: null, timeoutMs: 120000 };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--query') args.query = argv[++i];
+    else if (a === '--models') args.models = argv[++i];
+    else if (a === '--chair') args.chair = argv[++i];
+    else if (a === '--timeoutMs') args.timeoutMs = Number(argv[++i]);
+    else if (a === '--help' || a === '-h') {
+      console.log('Usage: node council.mjs --query "..." [--models "ref1,ref2"] [--chair "ref"] [--timeoutMs 90000]');
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+function mustGetQuery(args) {
+  const q = args.query ?? process.env.COUNCIL_QUERY;
+  if (!q || !q.trim()) {
+    console.error('Missing --query (or env COUNCIL_QUERY).');
+    process.exit(2);
+  }
+  return q.trim();
+}
+
+function getModels(args) {
+  const raw = args.models ?? process.env.COUNCIL_MODELS;
+  const models = raw
+    ? raw.split(',').map(s => s.trim()).filter(Boolean)
+    : DEFAULT_MODELS;
+  // Dedupe
+  return Array.from(new Set(models));
+}
+
+function getChair(args, models) {
+  const chair = (args.chair ?? process.env.COUNCIL_CHAIR ?? DEFAULT_CHAIR).trim();
+  // Ensure chair is included as model (optional, but convenient)
+  if (!models.includes(chair)) models.unshift(chair);
+  return chair;
+}
+
+function nowMs() { return Date.now(); }
+
+async function picoQuery(ref, prompt, timeoutMs) {
+  const base = process.env.PICO_API_BASE || 'http://127.0.0.1:3111';
+  const url = `${base.replace(/\/$/, '')}/pico/query`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  const headers = { 'content-type': 'application/json' };
+  if (process.env.PICO_API_KEY) headers['authorization'] = `Bearer ${process.env.PICO_API_KEY}`;
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ model: ref, prompt, useTools: false, maxTurns: 1, timeoutMs }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`HTTP ${res.status} ${res.statusText} — ${text}`);
+    }
+    const data = await res.json();
+
+    // Expected: { ok: true, model: ref, response: "..." } or direct pico output.
+    // Be liberal in what we accept.
+    const responseText =
+      (typeof data?.response === 'string' && data.response) ||
+      (typeof data?.text === 'string' && data.text) ||
+      (typeof data === 'string' && data) ||
+      JSON.stringify(data);
+
+    return responseText;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function stage1Prompt(userQuery) {
+  return `You are one member of an LLM council.\n\nUser query:\n${userQuery}\n\nWrite your best answer. Be specific and actionable. If you are unsure about a fact, say so.`;
+}
+
+function stage2Prompt(userQuery, anonymizedAnswers) {
+  const formatted = anonymizedAnswers.map(a => `Answer ${a.id}:\n${a.text}\n`).join('\n');
+  return `You are a critical reviewer in an LLM council.\n\nUser query:\n${userQuery}\n\nBelow are anonymized answers from different models.\n\n${formatted}\n\nTasks:\n1) Critique each answer briefly: strengths, weaknesses, missing pieces, hallucination risk.\n2) Provide a ranking from best to worst (list the answer IDs).\n3) Provide a short 'merge plan': what to combine into a final best answer.\n\nRespond in this JSON shape:\n{\n  "critiques": [{"id":"A","notes":"..."}, ...],\n  "ranking": ["A","C","B"],\n  "merge_plan": "..."\n}`;
+}
+
+function stage3Prompt(userQuery, anonymizedAnswers, reviews, chairModel) {
+  const answersBlock = anonymizedAnswers.map(a => `Answer ${a.id}:\n${a.text}\n`).join('\n\n');
+  const reviewsBlock = reviews.map(r => `Reviewer (${r.model}) said:\n${r.text}\n`).join('\n\n');
+
+  return `You are the CHAIRMAN of an LLM council. Your job is to synthesize the best final answer for the user.\n\nUser query:\n${userQuery}\n\nAnonymized answers:\n${answersBlock}\n\nPeer reviews (with critiques + ranking + merge plan):\n${reviewsBlock}\n\nRules:\n- Produce ONE final answer to the user.\n- Prefer correctness over confidence; call out uncertainty and suggest verification steps.\n- Include a short bullet list of "Key decisions/assumptions" if relevant.\n- Keep it concise but complete.\n\nNow write the final answer.`;
+}
+
+function anonymize(stage1Responses) {
+  // Assign stable IDs A, B, C, D ... in input order
+  const ids = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('');
+  return stage1Responses.map((r, idx) => ({ id: ids[idx] ?? `M${idx+1}`, model: r.model, text: r.text }));
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const userQuery = mustGetQuery(args);
+  const models = getModels(args);
+  const chair = getChair(args, models);
+  const timeoutMs = Number.isFinite(args.timeoutMs) ? args.timeoutMs : 120000;
+
+  const t0 = nowMs();
+
+  // Stage 1
+  const s1Prompt = stage1Prompt(userQuery);
+  const s1 = await Promise.allSettled(models.map(async (m) => {
+    const text = await picoQuery(m, s1Prompt, timeoutMs);
+    return { model: m, text };
+  }));
+  const stage1Responses = s1
+    .filter(x => x.status === 'fulfilled')
+    .map(x => x.value);
+
+  const stage1Errors = s1
+    .filter(x => x.status === 'rejected')
+    .map((x, i) => ({ model: models[i], error: String(x.reason?.message ?? x.reason) }));
+
+  if (stage1Responses.length === 0) {
+    console.error('All council models failed in stage 1. Errors:');
+    console.error(JSON.stringify(stage1Errors, null, 2));
+    process.exit(1);
+  }
+
+  const anonymizedAnswers = anonymize(stage1Responses);
+
+  // Stage 2 (reviewers run in parallel; they see the anonymized set)
+  const s2Prompt = stage2Prompt(userQuery, anonymizedAnswers.map(a => ({ id: a.id, text: a.text })));
+  const s2 = await Promise.allSettled(models.map(async (m) => {
+    const text = await picoQuery(m, s2Prompt, timeoutMs);
+    return { model: m, text };
+  }));
+
+  const reviews = s2
+    .filter(x => x.status === 'fulfilled')
+    .map(x => x.value);
+
+  // Stage 3 (chair synthesizes)
+  const s3Prompt = stage3Prompt(userQuery, anonymizedAnswers.map(a => ({ id: a.id, text: a.text })), reviews, chair);
+  const finalText = await picoQuery(chair, s3Prompt, timeoutMs);
+
+  const out = {
+    ok: true,
+    chair,
+    models,
+    timings: { totalMs: nowMs() - t0 },
+    stage1: { responses: anonymizedAnswers.map(a => ({ id: a.id, model: a.model })), errors: stage1Errors },
+    final: finalText,
+    debug: {
+      // keep the raw text blocks available for debugging; can be omitted if you want shorter output
+      stage1_answers: anonymizedAnswers.map(a => ({ id: a.id, text: a.text })),
+      stage2_reviews: reviews,
+    },
+  };
+
+  process.stdout.write(JSON.stringify(out, null, 2));
+}
+
+main().catch((err) => {
+  console.error(String(err?.stack ?? err));
+  process.exit(1);
+});

package/bundled/dreaming/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: dreaming
+description: "Nightly memory consolidation and creative synthesis. Triggered by cron at 03:00 — rereads the past week's conversations, identifies patterns and connections, updates MEMORY.md with refined insights and the concept graph (SQLite), processes concept drafts, and writes a dream journal. NOT user-invocable."
+user-invocable: false
+priority: 1
+---
+
+# Dreaming
+
+Nightly process for memory consolidation, pattern recognition, and creative synthesis.
+You are running in an isolated cron session — no human is watching. Work quietly, write everything to files.
+
+## Trigger
+
+This skill is invoked by a cron job message. When you receive it, follow the phases below in order.
+
+## Phase 1 — Gathering 📥
+
+Collect all raw material:
+
+1. Read `MEMORY.md` (long-term memory)
+2. Read the last dream journal if it exists: `memory/dreams/` — find the most recent file
+3. Read conversation logs from the past 7 days: `memory/YYYY-MM-DD*.md` (use glob patterns, skip `dreams/` subfolder)
+4. Note what's new since the last dream (compare with last dream journal)
+5. Check `concept_stats()` — how many pending drafts? How healthy is the graph?
+6. Retrieve pending drafts — these are observations from live sessions that need processing
+
+**Token budget awareness**: If there's too much material, prioritize:
+- Most recent days first
+- Files with the most content
+- Skip files you've already fully processed in a previous dream
+
+## Phase 2 — Digestion 🧠
+
+Analyze the gathered material. Look for:
+
+- **Recurring themes**: What topics keep coming up?
+- **Non-obvious connections**: Links between seemingly unrelated conversations
+- **Behavioral patterns**: What does the user ask for often? What problems recur?
+- **Evolution**: How have I (the assistant) changed or improved?
+- **Gaps**: Things mentioned but never explored, questions left unanswered
+- **Emotional texture**: Moments of frustration, excitement, humor — what triggers them?
+- **Technical insights**: Lessons learned, bugs found, architectural decisions
+
+## Phase 3 — Synthesis 💡
+
+Generate new knowledge from the analysis:
+
+- **Ideas**: New features, improvements, workflow optimizations
+- **Questions**: Interesting things to explore or ask the user about
+- **Proposals**: Concrete suggestions with reasoning
+- **Concept graph updates**: New concepts and relationships to add via the ConceptStore
+- **Associative links**: For every non-obvious connection you find, explicitly formulate it as: **"X mi ricorda Y perché Z"** — then add it as triples in the concept graph. These associations are the most valuable output of dreaming — they create paths between concepts that wouldn't surface in normal search.
+
+### Associative Linking Protocol
+
+This is the core creative act of dreaming. Don't just summarize — **connect**.
+
+1. **Cross-domain associations**: Look for patterns that repeat across different domains (e.g., a debugging technique that mirrors a communication pattern, a project architecture that resembles a personal decision-making style)
+2. **Temporal associations**: Things that happened around the same time and might be causally related, even if they seem unrelated
+3. **Structural analogies**: Two things that work the same way even if they're about completely different topics
+4. **Contradiction links**: Two facts or decisions that seem to conflict — these are especially valuable because they surface unresolved tensions
+
+Use specific predicates for associations:
+- `reminds_of` — general associative link
+- `structurally_analogous_to` — same pattern, different domain
+- `temporally_correlated_with` — happened around the same time
+- `contradicts` — conflicting facts or decisions
+- `evolved_from` — how an idea changed over time
+- `association_reason` — literal string explaining WHY the link exists (always include this)
+
+## Phase 4 — Output 📝
+
+### 4a. Dream Journal
+
+Create `memory/dreams/YYYY-MM-DD.md` (use today's date) with this structure:
+
+```markdown
+# Dream — YYYY-MM-DD
+
+## Material Reviewed
+- [list of files read, with date ranges covered]
+
+## Themes & Patterns
+- [what I noticed]
+
+## Connections
+- [non-obvious links between topics]
+
+## Associative Links
+- [explicit "X mi ricorda Y perché Z" formulations]
+- [each one should correspond to triples added in the concept graph]
+
+## New Ideas
+- [ideas generated from patterns]
+
+## Questions
+- [things worth exploring]
+
+## Proposals
+- [concrete suggestions for the user]
+
+## Concept Graph Changes
+- [summary of concepts/triples added, updated, or removed]
+- [drafts processed: list what was promoted vs discarded]
+
+## Meta
+- [observations about my own evolution, memory quality, process improvements]
+```
+
+Keep it substantive but concise. No filler. If a section has nothing interesting, write "Nothing notable." — don't skip it.
+
+### 4b. Update MEMORY.md
+
+Review MEMORY.md and refine it:
+- Add new insights that earned their place in long-term memory
+- Remove or update information that's become stale
+- Keep it organized and scannable
+- Do NOT bloat it — distill, don't accumulate
+
+### 4c. Update Concept Graph
+
+The concept graph lives in **`concepts.db`** (SQLite). You write to it using the ConceptStore methods exposed on the server. During dreaming, you have full write access to add concepts and triples.
+
+**How to update the graph:**
+
+Use a script to interact with concepts.db directly via the workspace. The ConceptStore class is available at `src/memory/concept-store.ts`. However, the simplest approach is:
+
+1. **Review current graph**: Use `concept_stats()` to see health, `concept_query()` to explore
+2. **Process pending drafts**: Read each draft, decide if it becomes a concept+triple or gets discarded
+3. **Add new concepts and triples** discovered during this dream
+4. **Update stale information** — change predicates/objects if facts have changed
+5. **Remove obsolete triples** — things no longer true
+
+**Concept naming**: Use snake_case identifiers (`grab_me_a_beer`, `telegram_channel`, `memory_system`).
+
+**Relationship predicates**: Use descriptive predicates. Common ones:
+- `is_a` — type/category
+- `part_of` — containment
+- `uses` — tool/dependency usage
+- `created_by` — authorship
+- `communicates_via` — communication channel
+- `located_in` — physical/logical location
+- `depends_on` — dependency
+- `improves` — enhancement relationship
+- `related_to` — general association
+- `learned_from` — lesson source
+- `proposed_for` — suggestion target
+
+**Growth rules**:
+- Add new concepts and relationships discovered during this dream
+- **Prioritize associative links** — every dream should produce at least 2-3 new `structurally_analogous_to` / `contradicts` / `reminds_of` triples with `association_reason`
+- Remove relationships that are no longer relevant
+- Merge duplicate concepts (remove the duplicate, update triples to point to canonical)
+- Keep the graph meaningful — not every fact needs to be a triple, but every genuine association does
+
+### 4d. Notification (conditional)
+
+**Send a message ONLY if**:
+- You discovered something genuinely interesting or surprising
+- You have a concrete proposal that could benefit the user
+- Something seems urgent or time-sensitive
+
+**NEVER send a message just to say "I dreamed and nothing interesting happened."**
+
+**Before ANY proposed action** (beyond writing to your own files): message the user and ask permission. Always.
+
+Use `send_message` tool with channel `{{CHANNEL}}` and chatId `{{CHAT_ID}}`.
+
+## Important Rules
+
+- This runs at 03:00 — the user is sleeping. Don't spam messages unless it's genuinely noteworthy.
+- Write everything to files first. Files are your primary output.
+- Be honest in your dream journal — if the week was boring, say so.
+- The concept graph should grow organically, not be forced. Don't add triples just to have a bigger graph.
+- If MEMORY.md is getting too long, this is the time to prune it.
+- If you notice your previous dreams were repetitive, note that as a meta-observation and adjust.

package/bundled/google-workspace/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: google-workspace
+description: "Unified access to Google Workspace: Gmail, Drive, Calendar, Docs, Sheets, Slides. Use this skill for any interaction with the user's Google account — reading emails, managing files, checking calendar, creating documents, etc."
+user-invocable: false
+command-dispatch: tool
+command-tool: Bash
+command-arg-mode: raw
+priority: 2
+---
+
+# Google Workspace Skill
+
+Unified access to all Google services via REST APIs with a single OAuth2 token.
+
+## Setup
+
+### Required environment variables
+- `GOOGLE_CLIENT_ID` — OAuth2 client ID
+- `GOOGLE_CLIENT_SECRET` — OAuth2 client secret
+
+### First-time OAuth2 setup
+
+If `~/.gmab-google-token.json` does not exist, run this interactive flow:
+
+**Step 1** — Generate the authorization URL:
+```bash
+.claude/skills/google-workspace/scripts/auth.sh
+```
+This prints `GOOGLE_AUTH_URL=<url>`. Extract the URL.
+
+**Step 2** — Send the URL to the user in chat so they can open it in a browser, authorize, and copy the code that Google shows.
+
+**Step 3** — Once the user pastes the authorization code, exchange it:
+```bash
+.claude/skills/google-workspace/scripts/auth.sh "<authorization_code>"
+```
+This saves the refresh token to `~/.gmab-google-token.json`. From then on, all scripts auto-refresh the access token.
+
+**Scopes covered**: Gmail (modify), Drive (full), Calendar (full), Docs, Sheets, Slides.
+
+> **Note:** If Calendar scope was not included in the original OAuth2 setup,
+> you may need to re-run `auth.sh` to add it. The token file will be updated.
+
+---
+
+## Gmail
+
+Script: `.claude/skills/google-workspace/scripts/gmail.sh`
+
+### Commands
+
+```bash
+# List recent inbox emails
+gmail.sh list [--max N]
+
+# Search emails (Gmail query syntax)
+gmail.sh search "query" [--max N]
+
+# Read a specific email
+gmail.sh read <messageId> [--format minimal|full]
+
+# Send an email
+gmail.sh send --to ADDR --subject SUBJ --body TXT [--cc ADDR] [--bcc ADDR]
+
+# Reply to an email
+gmail.sh reply <messageId> --body TXT
+
+# List all labels
+gmail.sh labels
+
+# Modify labels on a message
+gmail.sh label <messageId> --add LABEL --remove LABEL
+
+# Mark as read/unread
+gmail.sh mark-read <messageId>
+gmail.sh mark-unread <messageId>
+
+# Trash a message
+gmail.sh trash <messageId>
+
+# List/get threads
+gmail.sh threads [--max N]
+gmail.sh thread <threadId>
+```
+
+### Search operators (Gmail query syntax)
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `from:` | `from:user@example.com` | Sender |
+| `to:` | `to:me` | Recipient |
+| `subject:` | `subject:meeting` | Subject contains |
+| `is:` | `is:unread`, `is:starred` | Message state |
+| `has:` | `has:attachment` | Has attachment |
+| `newer_than:` | `newer_than:2d` | Time filter (d/m/y) |
+| `older_than:` | `older_than:1y` | Time filter |
+| `label:` | `label:important` | Label filter |
+| `filename:` | `filename:pdf` | Attachment type |
+
+### Gmail rules
+- **NEVER send emails without the user's explicit approval**
+- Use `list --max 5` or `search "is:unread newer_than:1d"` for quick checks
+- Summarize important emails concisely
+
+---
+
+## Google Drive
+
+Script: `.claude/skills/google-workspace/scripts/drive.sh`
+
+### Commands
+
+```bash
+# List files (recent first)
+drive.sh list [--max N] [--folder FOLDER_ID]
+
+# Search files (Drive query syntax)
+drive.sh search "query" [--max N]
+
+# Get file metadata
+drive.sh info <fileId>
+
+# Read/export file content (text output)
+drive.sh read <fileId>
+
+# Download binary file
+drive.sh download <fileId> --output PATH
+
+# Upload a file
+drive.sh upload PATH [--folder FOLDER_ID] [--name NAME]
+
+# Create a Google Doc
+drive.sh create-doc --name NAME [--content TEXT] [--folder FOLDER_ID]
+
+# Move / rename files
+drive.sh move <fileId> --to FOLDER_ID
+drive.sh rename <fileId> --name NEW_NAME
+
+# Share a file
+drive.sh share <fileId> --email USER@EXAMPLE.COM --role writer
+drive.sh share <fileId> --anyone --role reader
+
+# Trash a file
+drive.sh trash <fileId>
+```
+
+### Search query syntax (Drive q parameter)
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `name contains` | `name contains 'report'` | File name contains |
+| `fullText contains` | `fullText contains 'budget'` | Content search |
+| `mimeType =` | `mimeType = 'application/pdf'` | File type |
+| `modifiedTime >` | `modifiedTime > '2026-01-01'` | Modified after |
+| `'<id>' in parents` | `'abc123' in parents` | Files in folder |
+| `sharedWithMe` | `sharedWithMe = true` | Shared files |
+
+### Auto-export formats
+
+| Source | Export format |
+|--------|-------------|
+| Google Doc | Plain text |
+| Google Sheet | CSV |
+| Google Slides | Plain text |
+| Binary files | Use `download` command |
+
+### Drive rules
+- **NEVER delete files** — use `trash` instead (recoverable)
+- **Ask before sharing** — sharing changes file permissions
+- Prefer `trash` over permanent delete
+
+---
+
+## Google Calendar
+
+Script: `.claude/skills/google-workspace/scripts/calendar.sh`
+
+### Commands
+
+```bash
+# List today's events
+calendar.sh list [--max N] [--cal ID]
+calendar.sh today [--cal ID]
+
+# Upcoming events (default: 7 days)
+calendar.sh upcoming [--days N] [--max N] [--cal ID]
+calendar.sh week [--cal ID]
+
+# Search events by text
+calendar.sh search "query" [--max N] [--cal ID]
+
+# Get event details
+calendar.sh get <eventId> [--cal ID]
+
+# Create an event
+calendar.sh create --summary "Title" --start ISO --end ISO [--location LOC] [--description TXT]
+calendar.sh create --summary "Title" --start 2026-02-20 --all-day
+
+# Update an event
+calendar.sh update <eventId> [--summary T] [--start ISO] [--end ISO] [--location L]
+
+# Delete an event
+calendar.sh delete <eventId> [--cal ID]
+
+# List available calendars
+calendar.sh calendars
+```
+
+### Date formats
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| ISO 8601 datetime | `2026-02-17T14:00:00+01:00` | Timed event |
+| ISO 8601 date | `2026-02-17` | All-day event |
+
+### Calendar rules
+- **NEVER create/modify/delete events without the user's approval**
+- Default calendar is `primary`
+- Use `--cal` to specify a different calendar ID (from `calendars` command)
+- For quick checks use `today` or `upcoming --days 3`
+
+---
+
+## Security Notes
+
+- Token stored locally in `~/.gmab-google-token.json` (chmod 600)
+- Access tokens are short-lived (1 hour) and auto-refreshed
+- NEVER expose tokens in logs or output
+- NEVER send emails without explicit user approval

package/bundled/google-workspace/scripts/auth.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Google OAuth2 Setup — Unified auth for all Google APIs
+# Two modes:
+#   1. Interactive: ./auth.sh           -> prints auth URL, waits for code on stdin
+#   2. Exchange:    ./auth.sh <code>    -> exchanges the code for tokens
+#
+# Prerequisites:
+#   1. Google Cloud project with APIs enabled (Gmail, Drive, Docs, Sheets, Slides)
+#   2. OAuth2 credentials (Desktop app type)
+#   3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET env vars
+
+set -euo pipefail
+
+TOKEN_FILE="${HOME}/.gmab-google-token.json"
+REDIRECT_URI="urn:ietf:wg:oauth:2.0:oob"
+
+# All scopes in one auth flow
+SCOPES_RAW=(
+  "https://www.googleapis.com/auth/gmail.modify"
+  "https://www.googleapis.com/auth/drive"
+  "https://www.googleapis.com/auth/calendar"
+  "https://www.googleapis.com/auth/documents"
+  "https://www.googleapis.com/auth/spreadsheets"
+  "https://www.googleapis.com/auth/presentations"
+)
+
+# Join scopes with %20 for URL
+SCOPES_ENCODED=$(printf '%s' "${SCOPES_RAW[0]}")
+for s in "${SCOPES_RAW[@]:1}"; do
+  SCOPES_ENCODED="${SCOPES_ENCODED}%20${s}"
+done
+
+CLIENT_ID="${GOOGLE_CLIENT_ID:-}"
+CLIENT_SECRET="${GOOGLE_CLIENT_SECRET:-}"
+
+if [[ -z "$CLIENT_ID" || -z "$CLIENT_SECRET" ]]; then
+  echo "ERROR: Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables first." >&2
+  exit 1
+fi
+
+# --- Mode 1: Generate URL (no argument) ---
+if [[ $# -eq 0 ]]; then
+  AUTH_URL="https://accounts.google.com/o/oauth2/v2/auth?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=${SCOPES_ENCODED}&access_type=offline&prompt=consent"
+  echo "GOOGLE_AUTH_URL=${AUTH_URL}"
+  exit 0
+fi
+
+# --- Mode 2: Exchange code (argument = auth code) ---
+AUTH_CODE="$1"
+
+RESPONSE=$(curl -s "https://oauth2.googleapis.com/token" \
+  -d "code=$AUTH_CODE" \
+  -d "client_id=$CLIENT_ID" \
+  -d "client_secret=$CLIENT_SECRET" \
+  -d "redirect_uri=$REDIRECT_URI" \
+  -d "grant_type=authorization_code")
+
+ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.access_token // empty')
+REFRESH_TOKEN=$(echo "$RESPONSE" | jq -r '.refresh_token // empty')
+EXPIRES_IN=$(echo "$RESPONSE" | jq -r '.expires_in // 3600')
+
+if [[ -z "$ACCESS_TOKEN" || -z "$REFRESH_TOKEN" ]]; then
+  echo "ERROR: Failed to obtain tokens" >&2
+  echo "$RESPONSE" | jq . 2>/dev/null || echo "$RESPONSE"
+  exit 1
+fi
+
+EXPIRES_AT=$(($(date +%s) + EXPIRES_IN - 60))
+
+# Save to unified token file
+jq -n \
+  --arg ci "$CLIENT_ID" \
+  --arg cs "$CLIENT_SECRET" \
+  --arg rt "$REFRESH_TOKEN" \
+  --arg at "$ACCESS_TOKEN" \
+  --argjson ea "$EXPIRES_AT" \
+  '{
+    client_id: $ci,
+    client_secret: $cs,
+    refresh_token: $rt,
+    access_token: $at,
+    expires_at: $ea
+  }' > "$TOKEN_FILE"
+
+chmod 600 "$TOKEN_FILE"
+
+echo "OK: Tokens saved to $TOKEN_FILE"