@onmars/lunar-core 0.1.0

package/src/__tests__/whoami-command.test.ts

@@ -0,0 +1,124 @@
+/**
+ * /whoami Command — Test Suite
+ *
+ * Spec: shows sender identity, platform, channel, and agent info.
+ *
+ * Key contracts:
+ * - Always shows sender name and ID
+ * - Shows username only when present
+ * - Platform comes from channelPersona, defaults to "unknown"
+ * - Channel comes from channelPersona.name, falls back to channelId
+ * - Shows current agent info
+ */
+import { describe, expect, test } from 'bun:test'
+import type { CommandContext } from '../lib/command-handler'
+import { whoamiCommand } from '../lib/commands/whoami'
+import { SessionTracker } from '../lib/session-tracker'
+
+function makeCtx(overrides?: Partial<CommandContext>): CommandContext {
+  return {
+    sessionKey: 'test:channel-1',
+    message: {
+      id: 'msg-1',
+      channelId: 'channel-1',
+      sender: { id: 'user-1', name: 'Test User', username: 'testuser' },
+      text: '/whoami',
+      timestamp: new Date(),
+    },
+    tracker: new SessionTracker(),
+    daemonStartedAt: Date.now(),
+    agent: { id: 'claude', name: 'Claude Code (CLI)' },
+    clearSession: async () => ({ sessionCleared: true, hooksRan: false }),
+    ...overrides,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════
+// Sender identity
+// ═══════════════════════════════════════════════════════════
+
+describe('/whoami sender', () => {
+  test('shows sender name', () => {
+    const result = whoamiCommand('', makeCtx())
+    expect(result).toContain('Test User')
+  })
+
+  test('shows username when present', () => {
+    const result = whoamiCommand('', makeCtx())
+    expect(result).toContain('testuser')
+    expect(result).toContain('**Username:**')
+  })
+
+  test('omits username line when not present', () => {
+    const ctx = makeCtx({
+      message: {
+        id: 'msg-1',
+        channelId: 'channel-1',
+        sender: { id: 'user-1', name: 'Test User' },
+        text: '/whoami',
+        timestamp: new Date(),
+      },
+    })
+    const result = whoamiCommand('', ctx)
+    expect(result).not.toContain('**Username:**')
+  })
+
+  test('shows sender ID', () => {
+    const result = whoamiCommand('', makeCtx())
+    expect(result).toContain('user-1')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Platform & channel
+// ═══════════════════════════════════════════════════════════
+
+describe('/whoami platform & channel', () => {
+  test('shows platform from channelPersona', () => {
+    const ctx = makeCtx({
+      channelPersona: {
+        id: 'channel-1',
+        name: 'orbit',
+        platform: 'discord',
+      },
+    })
+    const result = whoamiCommand('', ctx)
+    expect(result).toContain('discord')
+  })
+
+  test('defaults to "unknown" platform when no channelPersona', () => {
+    const ctx = makeCtx({ channelPersona: undefined })
+    const result = whoamiCommand('', ctx)
+    expect(result).toContain('unknown')
+  })
+
+  test('shows channel name from channelPersona', () => {
+    const ctx = makeCtx({
+      channelPersona: {
+        id: 'channel-1',
+        name: 'orbit',
+        platform: 'discord',
+      },
+    })
+    const result = whoamiCommand('', ctx)
+    expect(result).toContain('#orbit')
+  })
+
+  test('falls back to channelId when no channelPersona name', () => {
+    const ctx = makeCtx({ channelPersona: undefined })
+    const result = whoamiCommand('', ctx)
+    expect(result).toContain('#channel-1')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// Agent info
+// ═══════════════════════════════════════════════════════════
+
+describe('/whoami agent', () => {
+  test('shows agent name and id', () => {
+    const result = whoamiCommand('', makeCtx())
+    expect(result).toContain('Claude Code (CLI)')
+    expect(result).toContain('claude')
+  })
+})

package/src/index.ts

@@ -0,0 +1,122 @@
+// Types — the public interfaces that adapters implement
+
+export type { ClearResult, CommandContext, CommandFn } from './lib/command-handler'
+// Command handler
+export { CommandHandler } from './lib/command-handler'
+export type { LunarConfig } from './lib/config'
+export { loadConfig } from './lib/config'
+export type {
+  AgentBackendConfig,
+  AgentEntry,
+  DedupConfig,
+  HookCondition,
+  HookEntry,
+  HooksConfig,
+  InputSanitizationConfig,
+  LifecycleEvent,
+  MemoryConfig,
+  MoonEntry,
+  PlatformConfig,
+  ProviderConfig,
+  RecallConfig,
+  SchedulerConfigParsed,
+  SchedulerJobConfig,
+  SecurityConfig,
+  VoiceConfig,
+  VoiceSTTConfig,
+  VoiceTTSConfig,
+  WorkspaceConfig,
+} from './lib/config-loader'
+// Config loader (workspace config.yaml — v2)
+export { loadWorkspaceConfig, parseSchedulerConfig } from './lib/config-loader'
+export type { CronFields } from './lib/cron-parser'
+export { nextCron, nextOccurrence, parseCron, parseField } from './lib/cron-parser'
+export type { DaemonOptions } from './lib/daemon'
+// Lib — the runtime core
+export { Daemon } from './lib/daemon'
+export type { HookContext, LLMFunction } from './lib/hook-runner'
+// Hook runner
+export {
+  evaluateGuard,
+  getAction,
+  HookRunner,
+  listActions,
+  parseTimeWindow,
+  registerAction,
+} from './lib/hook-runner'
+export type { LoggerOptions } from './lib/logger'
+export { createLogger, log, reconfigureLogger } from './lib/logger'
+export type { OrchestratorConfig } from './lib/memory-orchestrator'
+
+// Memory orchestrator
+export { MemoryOrchestrator } from './lib/memory-orchestrator'
+export type { ModelInfo } from './lib/model-catalog'
+// Model catalog
+export {
+  calculateCost,
+  getContextWindowSize,
+  getModelDisplayName,
+  getModelInfo,
+  listModels,
+} from './lib/model-catalog'
+export { MoonLoader } from './lib/moon-loader'
+export { PluginRegistry } from './lib/plugin'
+export { Router } from './lib/router'
+export type {
+  DispatchFn,
+  Job,
+  JobConfig,
+  JobPayload,
+  Schedule,
+  SchedulerConfig,
+} from './lib/scheduler'
+// Scheduler (v0.3)
+export { JobStore, Scheduler } from './lib/scheduler'
+export type { SanitizationResult } from './lib/security'
+// Security
+export { buildSafeEnv, createRedactor, createSanitizer, sanitizeInput } from './lib/security'
+export { SessionStore } from './lib/session'
+export type { SessionStatus, SessionUsage } from './lib/session-tracker'
+// Session tracker
+export {
+  buildProgressBar,
+  formatDuration,
+  formatTokens,
+  SessionTracker,
+} from './lib/session-tracker'
+export type { SkillMeta } from './lib/skill-loader'
+export { SkillLoader } from './lib/skill-loader'
+export type { AccountUsage, UsageWindow } from './lib/usage-api'
+// Usage API
+export { fetchAccountUsage, hasOAuthCredentials } from './lib/usage-api'
+export type {
+  Agent,
+  AgentAttachment,
+  AgentConfig,
+  AgentEvent,
+  AgentInput,
+  AgentUsage,
+} from './types/agent'
+export type {
+  Attachment,
+  Channel,
+  ChannelConfig,
+  IncomingMessage,
+  OutgoingAttachment,
+  OutgoingMessage,
+} from './types/channel'
+export type {
+  Fact,
+  MemoryProvider,
+  MemoryResult,
+  SearchOptions,
+} from './types/memory'
+export type { ChannelPersona, Moon } from './types/moon'
+export type {
+  STTOptions,
+  STTProvider,
+  STTResult,
+  TTSOptions,
+  TTSProvider,
+  TTSResult,
+} from './types/voice'

package/src/lib/command-handler.ts

@@ -0,0 +1,135 @@
+/**
+ * Command Handler — Slash command interception and dispatch.
+ *
+ * Detects messages starting with "/" and routes them to registered
+ * command handlers. Commands are processed by the Router BEFORE
+ * being sent to the agent — zero token cost, instant response.
+ *
+ * Design:
+ * - Commands are simple functions: (args, context) → string | null
+ * - null return = command not handled, fall through to agent
+ * - string return = response sent directly to channel
+ * - Context provides access to session tracker, memory, daemon info
+ */
+
+import type { IncomingMessage } from '../types/channel'
+import type { MemoryProvider } from '../types/memory'
+import type { ChannelPersona, Moon } from '../types/moon'
+import type { LunarConfig } from './config'
+import type { Scheduler } from './scheduler'
+import type { SessionStatus, SessionTracker } from './session-tracker'
+
+/**
+ * Result of a session clear operation.
+ */
+export interface ClearResult {
+  /** Whether the session was successfully cleared */
+  sessionCleared: boolean
+  /** Whether memory lifecycle hooks ran before clearing */
+  hooksRan: boolean
+}
+
+export interface CommandContext {
+  /** Session key for the current channel */
+  sessionKey: string
+  /** The incoming message */
+  message: IncomingMessage
+  /** Session tracker with usage data */
+  tracker: SessionTracker
+  /** Active moon for this channel */
+  moon?: Moon
+  /** Channel persona */
+  channelPersona?: ChannelPersona
+  /** Memory provider (for health checks) */
+  memory?: MemoryProvider
+  /** Scheduler instance (if enabled) */
+  scheduler?: Scheduler
+  /** Daemon start time (ms since epoch) */
+  daemonStartedAt: number
+  /** Agent ID and name */
+  agent: { id: string; name: string }
+  /** Active workspace configuration */
+  config?: LunarConfig
+  /** Update session metadata (for /model, /think overrides) */
+  updateSessionMeta?: (updates: Record<string, unknown>) => void
+  /** Get current session metadata */
+  getSessionMeta?: () => Record<string, unknown> | null
+  /** Abort the currently running agent query (for /stop) */
+  abortAgent?: () => void
+  /**
+   * Clear the current session: Claude context, token counters, message history.
+   * By default runs memory hooks (summarize, promote) before clearing.
+   * Pass { skipHooks: true } to clear immediately without hooks.
+   */
+  clearSession: (options?: { skipHooks?: boolean }) => Promise<ClearResult>
+}
+
+/**
+ * A command handler function.
+ * @param args - The text after the command name (e.g., "/status foo" → args = "foo")
+ * @param ctx - Command context with access to framework state
+ * @returns Response text to send, or null to pass through to agent
+ */
+export type CommandFn = (
+  args: string,
+  ctx: CommandContext,
+) => Promise<string | null> | string | null
+
+interface RegisteredCommand {
+  name: string
+  description: string
+  handler: CommandFn
+}
+
+/**
+ * Command registry and dispatcher.
+ */
+export class CommandHandler {
+  private commands = new Map<string, RegisteredCommand>()
+
+  /**
+   * Register a slash command.
+   */
+  register(name: string, description: string, handler: CommandFn): void {
+    // Normalize: store without leading /
+    const normalized = name.startsWith('/') ? name.slice(1) : name
+    this.commands.set(normalized, { name: normalized, description, handler })
+  }
+
+  /**
+   * Check if a message is a slash command.
+   */
+  isCommand(text: string): boolean {
+    const trimmed = text.trim()
+    if (!trimmed.startsWith('/')) return false
+
+    const commandName = trimmed.slice(1).split(/\s+/)[0]?.toLowerCase()
+    return commandName ? this.commands.has(commandName) : false
+  }
+
+  /**
+   * Try to handle a message as a command.
+   * Returns the response string if handled, null otherwise.
+   */
+  async handle(text: string, ctx: CommandContext): Promise<string | null> {
+    const trimmed = text.trim()
+    if (!trimmed.startsWith('/')) return null
+
+    const parts = trimmed.slice(1).split(/\s+/)
+    const commandName = parts[0]?.toLowerCase()
+    if (!commandName) return null
+
+    const command = this.commands.get(commandName)
+    if (!command) return null
+
+    const args = parts.slice(1).join(' ')
+    return command.handler(args, ctx)
+  }
+
+  /**
+   * List all registered commands (for /help).
+   */
+  list(): Array<{ name: string; description: string }> {
+    return [...this.commands.values()].map(({ name, description }) => ({ name, description }))
+  }
+}

package/src/lib/commands/clear.ts

@@ -0,0 +1,69 @@
+/**
+ * /clear — Clear session command.
+ *
+ * Resets the current session: clears Claude Code's accumulated context,
+ * token counters, and message history. The next query starts a fresh
+ * conversation (no --resume flag).
+ *
+ * By default, runs memory lifecycle hooks before clearing (summarize,
+ * promote, etc.) so session knowledge is preserved. Use `--hard` to
+ * skip hooks and clear immediately.
+ *
+ * Usage:
+ *   /clear         — Graceful: run hooks, then clear
+ *   /clear --hard  — Hard: skip hooks, clear immediately
+ */
+
+import type { CommandContext } from '../command-handler'
+import { formatTokens } from '../session-tracker'
+
+export async function clearCommand(args: string, ctx: CommandContext): Promise<string> {
+  const skipHooks = args.includes('--hard') || args.trim().toLowerCase() === 'hard'
+
+  // Capture previous status before clearing
+  const previousStatus = ctx.tracker.getStatus(ctx.sessionKey)
+
+  // Execute the clear
+  const result = await ctx.clearSession({ skipHooks })
+
+  const moonName = ctx.moon?.name ?? 'Lunar'
+  const lines: string[] = []
+
+  lines.push(`🌑 **${moonName}** — Session Cleared`)
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+
+  // Show what was cleared (previous stats)
+  if (previousStatus) {
+    const { usage } = previousStatus
+
+    const totalTokens =
+      usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+    lines.push(
+      `🗑️ **Cleared:** ${formatTokens(totalTokens)} tokens · ${usage.messageCount} messages · ${usage.queryCount} turns`,
+    )
+
+    if (previousStatus.estimatedCostUsd > 0) {
+      const costStr =
+        previousStatus.estimatedCostUsd < 0.01
+          ? '<$0.01'
+          : `~$${previousStatus.estimatedCostUsd.toFixed(2)}`
+      lines.push(`💰 **Session cost:** ${costStr} · ${previousStatus.sessionAge}`)
+    }
+  } else {
+    lines.push('🗑️ **Cleared:** no active session data')
+  }
+
+  // Hooks status
+  if (result.hooksRan) {
+    lines.push('🧠 **Memory:** hooks ran (summary saved)')
+  } else if (skipHooks) {
+    lines.push('⚡ **Memory:** hooks skipped (--hard)')
+  } else {
+    lines.push('🧠 **Memory:** no hooks to run')
+  }
+
+  lines.push('')
+  lines.push('_Next message starts a fresh session._')
+
+  return lines.join('\n')
+}

package/src/lib/commands/compact.ts

@@ -0,0 +1,14 @@
+/**
+ * /compact — Force context compaction (clears session, starts fresh).
+ *
+ * v1: thin wrapper around /clear with different wording.
+ * Future: could summarize context before clearing.
+ */
+
+import type { CommandContext } from '../command-handler'
+import { clearCommand } from './clear'
+
+export async function compactCommand(args: string, ctx: CommandContext): Promise<string> {
+  const result = await clearCommand(args, ctx)
+  return result ? result.replace('Session Cleared', 'Session Compacted') : result
+}

package/src/lib/commands/config-show.ts

@@ -0,0 +1,49 @@
+/**
+ * /config — Show active runtime configuration.
+ *
+ * Usage:
+ *   /config        — Show all config
+ *   /config show   — Same as above
+ */
+
+import type { CommandContext } from '../command-handler'
+
+export function configCommand(args: string, ctx: CommandContext): string {
+  const sub = args.trim().toLowerCase().split(/\s+/)[0] || 'show'
+
+  if (sub !== 'show' && sub !== '') {
+    return `Unknown subcommand: \`${sub}\`. Available: \`show\``
+  }
+
+  const lines: string[] = []
+  const moonName = ctx.moon?.name ?? 'none'
+
+  lines.push('**Configuration**')
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+
+  lines.push(`**Moon:** ${moonName}`)
+
+  const model = ctx.channelPersona?.model ?? ctx.moon?.model ?? 'default'
+  lines.push(`**Model:** ${model}`)
+
+  if (ctx.moon?.context1m) {
+    lines.push('**Context:** 1M extended')
+  }
+
+  if (ctx.channelPersona) {
+    lines.push(`**Channel:** #${ctx.channelPersona.name} (${ctx.channelPersona.platform})`)
+    if (ctx.channelPersona.tone) lines.push(`**Tone:** ${ctx.channelPersona.tone}`)
+    if (ctx.channelPersona.focus) lines.push(`**Focus:** ${ctx.channelPersona.focus}`)
+    if (ctx.channelPersona.skills?.length) {
+      lines.push(`**Skills:** ${ctx.channelPersona.skills.join(', ')}`)
+    }
+    if (ctx.channelPersona.agentId) {
+      lines.push(`**Agent routing:** ${ctx.channelPersona.agentId}`)
+    }
+  }
+
+  lines.push(`**Memory:** ${ctx.memory ? `${ctx.memory.id} (active)` : 'disabled'}`)
+  lines.push(`**Agent:** ${ctx.agent.name} (\`${ctx.agent.id}\`)`)
+
+  return lines.join('\n')
+}

package/src/lib/commands/cron.ts

@@ -0,0 +1,118 @@
+import type { CommandContext, CommandFn } from '../command-handler'
+import { parseCron } from '../cron-parser'
+import type { Job } from '../scheduler'
+
+export const cronCommand: CommandFn = async (args: string, ctx: CommandContext) => {
+  if (!ctx.scheduler) {
+    return '❌ Scheduler is not enabled in config.yaml'
+  }
+
+  const parts = args.trim().split(/\s+/)
+  const subcommand = parts[0]?.toLowerCase()
+
+  if (!subcommand || subcommand === 'help') {
+    return `**Cron Commands:**
+\`/cron list\` - List all jobs
+\`/cron add <expr> <channel> <prompt>\` - Add recurring query job
+\`/cron remove <id|name>\` - Remove a job
+\`/cron enable <id|name>\` - Enable a job
+\`/cron disable <id|name>\` - Disable a job`
+  }
+
+  const store = ctx.scheduler.getStore()
+
+  if (subcommand === 'list') {
+    const jobs = store.list()
+    if (jobs.length === 0) return 'No jobs scheduled.'
+
+    const lines = jobs.map((j) => {
+      const state = j.enabled ? '🟢' : '🔴'
+      const sched = j.schedule.kind === 'cron' ? j.schedule.expr : j.schedule.kind
+      const next = j.nextRun ? new Date(j.nextRun * 1000).toLocaleString() : 'None'
+      const name = j.name ? `**${j.name}**` : `\`${j.id.slice(0, 8)}\``
+      return `${state} ${name} | \`${sched}\` | Next: ${next} | Ch: #${j.channel}`
+    })
+    return `**Scheduled Jobs (${jobs.length}):**\n${lines.join('\n')}`
+  }
+
+  if (subcommand === 'remove') {
+    const target = parts[1]
+    if (!target) return 'Usage: `/cron remove <id|name>`'
+    const success = store.remove(target)
+    return success ? `✅ Removed job \`${target}\`` : `❌ Job \`${target}\` not found.`
+  }
+
+  if (subcommand === 'enable') {
+    const target = parts[1]
+    if (!target) return 'Usage: `/cron enable <id|name>`'
+    const job = store.get(target)
+    if (!job) return `❌ Job \`${target}\` not found.`
+    store.enable(job.id)
+    return `✅ Enabled job \`${target}\``
+  }
+
+  if (subcommand === 'disable') {
+    const target = parts[1]
+    if (!target) return 'Usage: `/cron disable <id|name>`'
+    const job = store.get(target)
+    if (!job) return `❌ Job \`${target}\` not found.`
+    store.disable(job.id)
+    return `✅ Disabled job \`${target}\``
+  }
+
+  if (subcommand === 'add') {
+    // /cron add "45 6 * * 1-5" orbit "Good morning!"
+    // /cron add 0 * * * * orbit "Hourly check"
+
+    // Extract expression
+    let expr = ''
+    let remaining = args.substring(3).trim()
+
+    if (remaining.startsWith('"') || remaining.startsWith("'")) {
+      const quote = remaining[0]
+      const endQuote = remaining.indexOf(quote, 1)
+      if (endQuote === -1) return '❌ Missing closing quote for cron expression.'
+      expr = remaining.substring(1, endQuote)
+      remaining = remaining.substring(endQuote + 1).trim()
+    } else {
+      // 5 parts for cron
+      const ep = remaining.split(/\s+/)
+      if (ep.length < 5) return '❌ Invalid cron expression. Need 5 fields.'
+      expr = ep.slice(0, 5).join(' ')
+      remaining = ep.slice(5).join(' ')
+    }
+
+    try {
+      parseCron(expr) // validate
+    } catch (e) {
+      return `❌ Invalid cron expression: ${e instanceof Error ? e.message : String(e)}`
+    }
+
+    const remainingParts = remaining.split(/\s+/)
+    const channel = remainingParts[0]
+    let prompt = remainingParts.slice(1).join(' ')
+
+    if (prompt.startsWith('"') || prompt.startsWith("'")) {
+      prompt = prompt.slice(1, prompt.length - 1)
+    }
+
+    if (!channel || !prompt) {
+      return 'Usage: `/cron add "<expr>" <channel> <prompt>`'
+    }
+
+    const job: Job = {
+      id: crypto.randomUUID(),
+      schedule: { kind: 'cron', expr },
+      payload: { kind: 'query', prompt },
+      channel,
+      enabled: true,
+      oneShot: false,
+      createdAt: Math.floor(Date.now() / 1000),
+    }
+
+    store.add(job)
+    return `✅ Added cron job: \`${expr}\` -> #${channel}`
+  }
+
+  return `❌ Unknown subcommand \`${subcommand}\``
+}

package/src/lib/commands/help.ts

@@ -0,0 +1,26 @@
+/**
+ * /help — List available commands.
+ */
+
+import type { CommandContext, CommandHandler } from '../command-handler'
+
+/**
+ * Creates a /help command that lists all registered commands.
+ * Needs the handler reference to enumerate commands.
+ */
+export function createHelpCommand(handler: CommandHandler) {
+  return function helpCommand(_args: string, ctx: CommandContext): string {
+    const commands = handler.list()
+    const moonName = ctx.moon?.name ?? 'Lunar'
+
+    const lines: string[] = []
+    lines.push(`🌑 **${moonName}** — Commands`)
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+
+    for (const cmd of commands) {
+      lines.push(`**/${cmd.name}** — ${cmd.description}`)
+    }
+
+    return lines.join('\n')
+  }
+}