@harbinger-ai/harbinger 0.1.0

package/setup/lib/prompts.mjs

@@ -0,0 +1,267 @@
+import * as clack from '@clack/prompts';
+import open from 'open';
+import { PROVIDERS } from './providers.mjs';
+
+/**
+ * Mask a secret, showing only last 4 characters
+ */
+export function maskSecret(secret) {
+  if (!secret || secret.length < 8) return '****';
+  return '****' + secret.slice(-4);
+}
+
+/**
+ * Handle cancel — exits cleanly if user pressed Ctrl+C
+ */
+function handleCancel(value) {
+  if (clack.isCancel(value)) {
+    clack.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
+/**
+ * Boolean gate — returns true (keep existing) or false (must configure).
+ * If no displayValue, returns false (must configure).
+ */
+export async function keepOrReconfigure(label, displayValue) {
+  if (!displayValue) return false;
+  clack.log.success(`${label}: ${displayValue}`);
+  const reconfig = handleCancel(await clack.confirm({
+    message: 'Reconfigure?',
+    initialValue: false,
+  }));
+  return !reconfig;
+}
+
+/**
+ * Prompt for GitHub PAT
+ */
+export async function promptForPAT() {
+  const pat = handleCancel(await clack.password({
+    message: 'Paste your GitHub Personal Access Token:',
+    validate: (input) => {
+      if (!input) return 'PAT is required';
+      if (!input.startsWith('ghp_') && !input.startsWith('github_pat_')) {
+        return 'Invalid PAT format. Should start with ghp_ or github_pat_';
+      }
+    },
+  }));
+  return pat;
+}
+
+/**
+ * Prompt for LLM provider selection
+ */
+export async function promptForProvider() {
+  const options = Object.entries(PROVIDERS).map(([key, p]) => ({
+    label: p.label,
+    value: key,
+  }));
+  options.push({ label: 'Local (OpenAI Compatible API)', value: 'custom' });
+
+  const provider = handleCancel(await clack.select({
+    message: 'Which LLM for your agent?',
+    options,
+  }));
+  return provider;
+}
+
+/**
+ * Prompt for model selection from a provider's model list
+ * @param {string} providerKey - Provider key from PROVIDERS registry
+ * @param {object} [options] - Options
+ * @param {string} [options.defaultModelId] - Override which model gets "(recommended)" instead of the registry default
+ */
+export async function promptForModel(providerKey, { defaultModelId } = {}) {
+  const provider = PROVIDERS[providerKey];
+  const isRecommended = (m) => defaultModelId ? m.id === defaultModelId : m.default;
+  const sorted = [...provider.models].sort((a, b) => isRecommended(b) - isRecommended(a));
+  const options = sorted.map((m) => ({
+    label: isRecommended(m) ? `${m.name} (recommended)` : m.name,
+    value: m.id,
+  }));
+  options.push({ label: 'Custom (enter model ID)', value: '__custom__' });
+
+  const model = handleCancel(await clack.select({
+    message: 'Which model?',
+    options,
+  }));
+
+  if (model === '__custom__') {
+    const customModel = handleCancel(await clack.text({
+      message: `Enter ${provider.name} model ID:`,
+      validate: (input) => {
+        if (!input) return 'Model ID is required';
+      },
+    }));
+    return customModel;
+  }
+
+  return model;
+}
+
+/**
+ * Prompt for an API key for a known provider
+ */
+export async function promptForApiKey(providerKey) {
+  const provider = PROVIDERS[providerKey];
+
+  const openPage = handleCancel(await clack.confirm({
+    message: `Open ${provider.name} API key page in browser?`,
+    initialValue: true,
+  }));
+  if (openPage) {
+    await open(provider.keyPage);
+  }
+
+  const key = handleCancel(await clack.password({
+    message: `Enter your ${provider.name} API key:`,
+    validate: (input) => {
+      if (!input) return `${provider.name} API key is required`;
+      if (provider.keyPrefix && !input.startsWith(provider.keyPrefix)) {
+        return `Invalid format. Should start with ${provider.keyPrefix}`;
+      }
+    },
+  }));
+  return key;
+}
+
+/**
+ * Prompt for an optional API key with a purpose description
+ */
+export async function promptForOptionalKey(providerKey, purpose) {
+  const provider = PROVIDERS[providerKey];
+
+  const addKey = handleCancel(await clack.confirm({
+    message: `Add ${provider.name} API key for ${purpose}? (optional)`,
+    initialValue: false,
+  }));
+
+  if (!addKey) return null;
+
+  const openPage = handleCancel(await clack.confirm({
+    message: `Open ${provider.name} API key page in browser?`,
+    initialValue: true,
+  }));
+  if (openPage) {
+    await open(provider.keyPage);
+  }
+
+  const key = handleCancel(await clack.password({
+    message: `Enter your ${provider.name} API key:`,
+    validate: (input) => {
+      if (!input) return 'Key is required if adding';
+      if (provider.keyPrefix && !input.startsWith(provider.keyPrefix)) {
+        return `Invalid format. Should start with ${provider.keyPrefix}`;
+      }
+    },
+  }));
+  return key;
+}
+
+/**
+ * Prompt for custom/local LLM provider details
+ */
+export async function promptForCustomProvider() {
+  const baseUrl = handleCancel(await clack.text({
+    message: 'API base URL (e.g., http://host.docker.internal:11434/v1):',
+    validate: (input) => {
+      if (!input) return 'Base URL is required';
+      if (!input.startsWith('http://') && !input.startsWith('https://')) {
+        return 'URL must start with http:// or https://';
+      }
+    },
+  }));
+
+  const model = handleCancel(await clack.text({
+    message: 'Model ID (e.g., qwen3:8b):',
+    validate: (input) => {
+      if (!input) return 'Model ID is required';
+    },
+  }));
+
+  const apiKey = handleCancel(await clack.password({
+    message: 'API key (leave blank if not needed):',
+  }));
+
+  return { baseUrl, model, apiKey: apiKey || '' };
+}
+
+/**
+ * Prompt for optional Brave Search API key
+ */
+export async function promptForBraveKey() {
+  const addKey = handleCancel(await clack.confirm({
+    message: 'Add Brave Search API key? (optional, lets your agent search the web)',
+    initialValue: false,
+  }));
+
+  if (!addKey) return null;
+
+  clack.log.info(
+    'To get a Brave Search API key:\n' +
+    '  1. Go to https://api-dashboard.search.brave.com/app/keys\n' +
+    '  2. Click "Get Started"\n' +
+    '  3. Create an account (or sign in)\n' +
+    '  4. Subscribe to a plan (free credits may be available)\n' +
+    '  5. Copy your API key'
+  );
+
+  const openPage = handleCancel(await clack.confirm({
+    message: 'Open Brave Search API page in browser?',
+    initialValue: true,
+  }));
+  if (openPage) {
+    await open('https://api-dashboard.search.brave.com/app/keys');
+  }
+
+  const key = handleCancel(await clack.password({
+    message: 'Enter your Brave Search API key:',
+    validate: (input) => {
+      if (!input) return 'Key is required if adding';
+    },
+  }));
+  return key;
+}
+
+/**
+ * Generate a Telegram webhook secret
+ */
+export async function generateTelegramWebhookSecret() {
+  const { randomBytes } = await import('crypto');
+  return randomBytes(32).toString('hex');
+}
+
+/**
+ * Prompt for confirmation (wraps clack.confirm with cancel handling)
+ */
+export async function confirm(message, initialValue = true) {
+  const result = handleCancel(await clack.confirm({
+    message,
+    initialValue,
+  }));
+  return result;
+}
+
+/**
+ * Press enter to continue
+ */
+export async function pressEnter(message = 'Press enter to continue') {
+  handleCancel(await clack.text({
+    message,
+    defaultValue: '',
+  }));
+}
+
+/**
+ * Prompt for text input
+ */
+export async function promptText(message, defaultValue = '') {
+  const value = handleCancel(await clack.text({
+    message,
+    defaultValue,
+  }));
+  return value;
+}

package/setup/lib/providers.mjs

@@ -0,0 +1,48 @@
+/**
+ * Provider registry — single source of truth for PI agent LLM providers.
+ *
+ * "builtin" means PI has a built-in provider (no models.json needed).
+ * Non-builtin providers (openai, custom) require a .pi/agent/models.json entry.
+ */
+export const PROVIDERS = {
+  anthropic: {
+    label: 'Claude (Anthropic)',
+    name: 'Anthropic',
+    envKey: 'ANTHROPIC_API_KEY',
+    keyPrefix: 'sk-ant-',
+    keyPage: 'https://platform.claude.com/settings/keys',
+    builtin: true,
+    oauthSupported: true,
+    models: [
+      { id: 'claude-opus-4-6', name: 'Claude Opus 4.6', default: true },
+      { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6' },
+      { id: 'claude-haiku-4-5-20251001', name: 'Claude Haiku 4.5' },
+    ],
+  },
+  openai: {
+    label: 'GPT (OpenAI)',
+    name: 'OpenAI',
+    envKey: 'OPENAI_API_KEY',
+    keyPrefix: 'sk-',
+    keyPage: 'https://platform.openai.com/settings/organization/api-keys',
+    builtin: false,
+    baseUrl: 'https://api.openai.com/v1',
+    api: 'openai-completions',
+    models: [
+      { id: 'gpt-5.2', name: 'GPT-5.2', default: true },
+      { id: 'gpt-4o', name: 'GPT-4o' },
+      { id: 'o4-mini', name: 'o4-mini' },
+    ],
+  },
+  google: {
+    label: 'Gemini (Google)',
+    name: 'Google',
+    envKey: 'GOOGLE_API_KEY',
+    keyPage: 'https://aistudio.google.com/apikey',
+    builtin: true,
+    models: [
+      { id: 'gemini-3.1-pro', name: 'Gemini 3.1 Pro', default: true },
+      { id: 'gemini-2.5-flash', name: 'Gemini 2.5 Flash' },
+    ],
+  },
+};

package/setup/lib/sync.mjs

@@ -0,0 +1,125 @@
+import * as clack from '@clack/prompts';
+import { updateEnvVariable } from './auth.mjs';
+import { setSecret, setVariable } from './github.mjs';
+import { CONFIG_TARGETS } from './targets.mjs';
+
+/**
+ * Sync collected config values to .env and GitHub.
+ *
+ * Only keys present in `collected` are considered.
+ * Only values that actually changed (vs `env`) are written.
+ *
+ * @param {object|null} env - Current .env values (null if no .env)
+ * @param {object} collected - All collected config values
+ * @param {object} options
+ * @param {string} options.owner - GitHub owner
+ * @param {string} options.repo - GitHub repo
+ * @returns {Promise<object>} Sync report
+ */
+export async function syncConfig(env, collected, { owner, repo }) {
+  const envUpdates = [];
+  const secretUpdates = [];
+  const variableUpdates = [];
+  const isFirstRun = !env?.GH_TOKEN;
+
+  for (const [key, value] of Object.entries(collected)) {
+    const target = CONFIG_TARGETS[key];
+    if (!target) continue;
+
+    const oldValue = env?.[key] ?? '';
+    const changed = value !== oldValue;
+
+    // .env — write if changed and target has env: true
+    if (target.env && changed) {
+      envUpdates.push({ key, value });
+    }
+
+    // GitHub secret — only if changed AND value is non-empty
+    if (target.secret && changed && value) {
+      const secretName = target.secret === true ? key : target.secret;
+      secretUpdates.push({ key, secretName, value });
+    }
+
+    // GitHub variable — only if changed
+    if (target.variable && changed) {
+      // Skip firstRunOnly variables unless this is the first setup
+      if (target.firstRunOnly && !isFirstRun) continue;
+      variableUpdates.push({ key, value });
+    }
+  }
+
+  // Also handle firstRunOnly defaults that aren't in collected
+  if (isFirstRun) {
+    for (const [key, target] of Object.entries(CONFIG_TARGETS)) {
+      if (target.firstRunOnly && target.default && !(key in collected)) {
+        variableUpdates.push({ key, value: target.default });
+      }
+    }
+  }
+
+  const report = { env: [], secrets: [], variables: [], errors: [] };
+
+  if (envUpdates.length === 0 && secretUpdates.length === 0 && variableUpdates.length === 0) {
+    clack.log.info('Config unchanged');
+    return report;
+  }
+
+  const s = clack.spinner();
+
+  // Write .env updates
+  if (envUpdates.length > 0) {
+    for (const { key, value } of envUpdates) {
+      updateEnvVariable(key, value);
+      report.env.push(key);
+    }
+    clack.log.success(`Updated .env (${report.env.join(', ')})`);
+  }
+
+  // Set GitHub secrets
+  if (secretUpdates.length > 0) {
+    s.start('Setting GitHub secrets...');
+    let allOk = true;
+    for (const { key, secretName, value } of secretUpdates) {
+      const result = await setSecret(owner, repo, secretName, value);
+      if (result.success) {
+        report.secrets.push(secretName);
+      } else {
+        report.errors.push(`Failed to set secret ${secretName}: ${result.error}`);
+        allOk = false;
+      }
+    }
+    if (allOk) {
+      s.stop('GitHub secrets set');
+    } else {
+      s.stop('Some secrets failed');
+      for (const err of report.errors) {
+        clack.log.error(err);
+      }
+    }
+  }
+
+  // Set GitHub variables
+  if (variableUpdates.length > 0) {
+    s.start('Setting GitHub variables...');
+    let allOk = true;
+    for (const { key, value } of variableUpdates) {
+      const result = await setVariable(owner, repo, key, value);
+      if (result.success) {
+        report.variables.push(key);
+      } else {
+        report.errors.push(`Failed to set variable ${key}: ${result.error}`);
+        allOk = false;
+      }
+    }
+    if (allOk) {
+      s.stop('GitHub variables set');
+    } else {
+      s.stop('Some variables failed');
+      for (const err of report.errors) {
+        clack.log.error(err);
+      }
+    }
+  }
+
+  return report;
+}

package/setup/lib/targets.mjs

@@ -0,0 +1,45 @@
+/**
+ * Config target mapping — single source of truth for where each config key goes.
+ *
+ * `env: true` — written to .env
+ * `secret: true` — GitHub secret name === env key name
+ * `secret: 'NAME'` — GitHub secret uses a different name
+ * `variable: true` — GitHub repository variable
+ * `default` — default value for firstRunOnly variables
+ * `firstRunOnly: true` — only set on GitHub during first-time setup
+ *
+ * Only keys present in `collected` are synced — absent keys are untouched.
+ * Empty string values write to .env but do NOT set as GitHub secrets.
+ */
+export const CONFIG_TARGETS = {
+  GH_TOKEN:              { env: true, secret: 'AGENT_GH_TOKEN' },
+  GH_OWNER:              { env: true },
+  GH_REPO:               { env: true },
+
+  LLM_PROVIDER:          { env: true, variable: true },
+  LLM_MODEL:             { env: true, variable: true },
+  ANTHROPIC_API_KEY:     { env: true, secret: 'AGENT_ANTHROPIC_API_KEY' },
+  OPENAI_API_KEY:        { env: true, secret: 'AGENT_OPENAI_API_KEY' },
+  GOOGLE_API_KEY:        { env: true, secret: 'AGENT_GOOGLE_API_KEY' },
+  CUSTOM_API_KEY:        { env: true, secret: 'AGENT_CUSTOM_API_KEY' },
+  OPENAI_BASE_URL:       { env: true, variable: true },
+
+  CLAUDE_CODE_OAUTH_TOKEN: { env: true, secret: 'AGENT_CLAUDE_CODE_OAUTH_TOKEN' },
+  AGENT_BACKEND:           { env: true, variable: true },
+
+  BRAVE_API_KEY:         { secret: 'AGENT_LLM_BRAVE_API_KEY' },
+
+  GH_WEBHOOK_SECRET:     { env: true, secret: true },
+
+  APP_URL:               { env: true, variable: true },
+  APP_HOSTNAME:          { env: true },
+
+  AUTO_MERGE:            { variable: true, default: 'true', firstRunOnly: true },
+  ALLOWED_PATHS:         { variable: true, default: '/logs', firstRunOnly: true },
+  RUNS_ON:               { variable: true },
+
+  TELEGRAM_BOT_TOKEN:    { env: true },
+  TELEGRAM_WEBHOOK_SECRET: { env: true },
+  TELEGRAM_CHAT_ID:      { env: true },
+  TELEGRAM_VERIFICATION: { env: true },
+};

package/setup/lib/telegram-verify.mjs

@@ -0,0 +1,63 @@
+import * as clack from '@clack/prompts';
+
+/**
+ * Run the chat ID verification flow
+ * @param {string} verificationCode - The code user should send to bot
+ * @param {object} [options] - Options
+ * @param {boolean} [options.allowSkip=false] - Allow pressing Enter to skip
+ * @returns {Promise<string|null>} - The chat ID or null if skipped
+ */
+export async function runVerificationFlow(verificationCode, { allowSkip = false } = {}) {
+  clack.log.warn('Chat ID Verification');
+  clack.log.info(
+    'To lock the bot to your chat, send the verification code.\n' +
+    `  Send this message to your bot: ${verificationCode}\n` +
+    '  The bot will reply with your chat ID. Paste it below.'
+  );
+
+  const message = allowSkip
+    ? 'Paste your chat ID from the bot (or press Enter to skip):'
+    : 'Paste your chat ID from the bot:';
+
+  const chatId = await clack.text({
+    message,
+    defaultValue: allowSkip ? '' : undefined,
+    validate: (input) => {
+      if (!input) return allowSkip ? undefined : 'Chat ID is required';
+      if (!/^-?\d+$/.test(input.trim())) {
+        return 'Chat ID should be a number (can be negative for groups)';
+      }
+    },
+  });
+
+  if (clack.isCancel(chatId)) {
+    clack.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  return chatId.trim() || null;
+}
+
+/**
+ * Wait for server to pick up .env changes and verify it's running
+ * @param {string} ngrokUrl - The ngrok URL
+ * @returns {Promise<boolean>} - True if verified successfully
+ */
+export async function verifyRestart(ngrokUrl) {
+  const s = clack.spinner();
+  s.start('Waiting for server to pick up changes...');
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  try {
+    await fetch(`${ngrokUrl}/api/ping`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(10000)
+    });
+  } catch (err) {
+    s.stop(`Server not reachable: ${err.message}`);
+    return false;
+  }
+
+  s.stop('Server is running');
+  return true;
+}

package/setup/lib/telegram.mjs

@@ -0,0 +1,76 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * Generate a verification code for Telegram chat ID capture
+ */
+export function generateVerificationCode() {
+  return 'verify-' + randomBytes(4).toString('hex');
+}
+
+/**
+ * Register a Telegram webhook
+ */
+export async function setTelegramWebhook(botToken, webhookUrl, secretToken = null) {
+  // Delete first — Telegram ignores secret_token changes if the URL is unchanged
+  await deleteTelegramWebhook(botToken);
+
+  const body = { url: webhookUrl };
+  if (secretToken) {
+    body.secret_token = secretToken;
+  }
+
+  const response = await fetch(
+    `https://api.telegram.org/bot${botToken}/setWebhook`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }
+  );
+
+  const result = await response.json();
+  return result;
+}
+
+/**
+ * Get current webhook info
+ */
+export async function getTelegramWebhookInfo(botToken) {
+  const response = await fetch(`https://api.telegram.org/bot${botToken}/getWebhookInfo`);
+  const result = await response.json();
+  return result;
+}
+
+/**
+ * Delete existing webhook
+ */
+export async function deleteTelegramWebhook(botToken) {
+  const response = await fetch(`https://api.telegram.org/bot${botToken}/deleteWebhook`, {
+    method: 'POST',
+  });
+  const result = await response.json();
+  return result;
+}
+
+/**
+ * Validate bot token by calling getMe
+ */
+export async function validateBotToken(botToken) {
+  try {
+    const response = await fetch(`https://api.telegram.org/bot${botToken}/getMe`);
+    const result = await response.json();
+    if (result.ok) {
+      return { valid: true, botInfo: result.result };
+    }
+    return { valid: false, error: result.description };
+  } catch (error) {
+    return { valid: false, error: error.message };
+  }
+}
+
+/**
+ * Get BotFather URL for creating a new bot
+ */
+export function getBotFatherURL() {
+  return 'https://t.me/BotFather';
+}