@soleri/core 2.9.0 → 2.11.0

package/src/chat/self-update.ts

@@ -0,0 +1,117 @@
+/**
+ * Self-Update Manager — restart context persistence for chat-driven updates.
+ *
+ * Manages the restart lifecycle: save context before exit, load on startup,
+ * confirm success or trigger rollback. The actual process exit and rebuild
+ * are handled by the supervisor — this module only manages the context.
+ *
+ * Exit code 75 signals the supervisor to rebuild before restarting.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/** Exit code that tells the supervisor to rebuild before restart. */
+export const RESTART_EXIT_CODE = 75;
+
+export interface RestartContext {
+  /** Why the restart was requested. */
+  reason: 'self-update' | 'rebuild' | 'manual';
+  /** Chat ID to send confirmation to after restart. */
+  chatId: string;
+  /** Git commit SHA that triggered the update (if applicable). */
+  commitSha?: string;
+  /** Unix timestamp ms when restart was requested. */
+  requestedAt: number;
+}
+
+export interface RestartResult {
+  /** Whether the restart was initiated. */
+  initiated: boolean;
+  /** The saved context. */
+  context?: RestartContext;
+  /** Error message if failed. */
+  error?: string;
+}
+
+export class SelfUpdateManager {
+  constructor(private readonly contextPath: string) {}
+
+  /**
+   * Save restart context and exit with code 75.
+   * The supervisor handles rebuild + restart.
+   * Returns the context (useful for testing — in production, process.exit fires).
+   */
+  requestRestart(
+    chatId: string,
+    reason: RestartContext['reason'] = 'manual',
+    commitSha?: string,
+  ): RestartResult {
+    const context: RestartContext = {
+      reason,
+      chatId,
+      commitSha,
+      requestedAt: Date.now(),
+    };
+
+    try {
+      this.saveContext(context);
+      return { initiated: true, context };
+    } catch (e) {
+      return {
+        initiated: false,
+        error: e instanceof Error ? e.message : String(e),
+      };
+    }
+  }
+
+  /**
+   * Save restart context to disk.
+   */
+  saveContext(context: RestartContext): void {
+    mkdirSync(dirname(this.contextPath), { recursive: true });
+    writeFileSync(this.contextPath, JSON.stringify(context, null, 2), 'utf-8');
+  }
+
+  /**
+   * Load restart context from disk (if any).
+   * Returns null if no pending restart context exists.
+   */
+  loadContext(): RestartContext | null {
+    try {
+      const raw = readFileSync(this.contextPath, 'utf-8');
+      return JSON.parse(raw) as RestartContext;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Clear restart context (call after successful startup confirmation).
+   */
+  clearContext(): void {
+    try {
+      unlinkSync(this.contextPath);
+    } catch {
+      // File doesn't exist — that's fine
+    }
+  }
+
+  /**
+   * Check if there's a pending restart context.
+   */
+  hasPendingRestart(): boolean {
+    return this.loadContext() !== null;
+  }
+
+  /**
+   * Sanitize a commit message for safe shell usage.
+   * Allows alphanumeric, spaces, basic punctuation. Max 120 chars.
+   */
+  static sanitizeCommitMessage(msg: string): string {
+    return msg
+      .replace(/[^\w\s.,!?:;()\-/'"#@]/g, '')
+      .trim()
+      .slice(0, 120);
+  }
+}

package/src/chat/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Chat transport types — generic primitives for conversational agent transports.
+ *
+ * Works for Telegram, Discord, Slack, or any chat-based interface.
+ * Transport-specific wiring (Grammy, discord.js, etc.) belongs in forge templates.
+ */
+
+// ─── Messages ────────────────────────────────────────────────────────
+
+export type ChatRole = 'user' | 'assistant' | 'system' | 'tool';
+
+export interface ChatMessage {
+  role: ChatRole;
+  content: string;
+  /** Optional structured content blocks (e.g. tool_use, tool_result, image). */
+  blocks?: unknown[];
+  /** Unix timestamp ms. */
+  timestamp: number;
+  /** Transport-specific metadata (message ID, chat ID, etc.). */
+  meta?: Record<string, unknown>;
+}
+
+// ─── Sessions ────────────────────────────────────────────────────────
+
+export interface ChatSession {
+  /** Unique session ID (typically the chat/channel ID from the transport). */
+  id: string;
+  /** Conversation messages. */
+  messages: ChatMessage[];
+  /** Unix timestamp ms when the session was created. */
+  createdAt: number;
+  /** Unix timestamp ms of the last activity. */
+  lastActiveAt: number;
+  /** Custom metadata (personality state, counters, etc.). */
+  meta?: Record<string, unknown>;
+}
+
+export interface ChatSessionConfig {
+  /** Directory for session persistence. */
+  storageDir: string;
+  /** TTL in ms for inactivity expiry. Default: 7_200_000 (2 hours). */
+  ttlMs?: number;
+  /** Max messages before compaction triggers. Default: 100. */
+  compactionThreshold?: number;
+  /** Messages to keep after compaction. Default: 40. */
+  compactionKeep?: number;
+}
+
+// ─── Fragment Buffering ──────────────────────────────────────────────
+
+export interface Fragment {
+  /** The message text. */
+  text: string;
+  /** Transport message ID (for ordering). */
+  messageId: number | string;
+  /** Unix timestamp ms when received. */
+  receivedAt: number;
+}
+
+export interface FragmentBufferConfig {
+  /** Character threshold to start buffering. Default: 4000. */
+  startThreshold?: number;
+  /** Max gap in ms between fragments before auto-flush. Default: 1500. */
+  maxGapMs?: number;
+  /** Maximum number of fragments to merge. Default: 12. */
+  maxParts?: number;
+  /** Maximum total bytes before force-flush. Default: 50_000. */
+  maxTotalBytes?: number;
+}
+
+// ─── Response Chunking ──────────────────────────────────────────────
+
+export type MarkupFormat = 'html' | 'markdown' | 'plain';
+
+export interface ChunkConfig {
+  /** Max characters per chunk. Default: 4000. */
+  maxChunkSize?: number;
+  /** Output markup format. Default: 'html'. */
+  format?: MarkupFormat;
+}
+
+// ─── Authentication ──────────────────────────────────────────────────
+
+export interface ChatAuthConfig {
+  /** Path to auth persistence file. */
+  storagePath: string;
+  /** Passphrase required for authentication. If unset, auth is disabled. */
+  passphrase?: string;
+  /** Allowed user IDs. If empty or unset, any authenticated user is allowed. */
+  allowedUsers?: (string | number)[];
+  /** Rate limit: max failed attempts before temporary lockout. Default: 5. */
+  maxFailedAttempts?: number;
+  /** Lockout duration in ms. Default: 300_000 (5 minutes). */
+  lockoutMs?: number;
+}
+
+export interface AuthRecord {
+  userId: string | number;
+  authenticatedAt: number;
+}
+
+export interface AuthState {
+  authenticated: AuthRecord[];
+  failedAttempts: Map<string, { count: number; lastAttempt: number }>;
+}
+
+// ─── Chat Manager (combines everything) ─────────────────────────────
+
+export interface ChatManagerConfig {
+  session: ChatSessionConfig;
+  fragment?: FragmentBufferConfig;
+  chunk?: ChunkConfig;
+  auth?: ChatAuthConfig;
+}
+
+export interface ChatManagerStatus {
+  activeSessions: number;
+  authenticatedUsers: number;
+  pendingFragments: number;
+  config: {
+    ttlMs: number;
+    compactionThreshold: number;
+    maxChunkSize: number;
+    authEnabled: boolean;
+  };
+}

package/src/chat/voice.ts

@@ -0,0 +1,134 @@
+/**
+ * Voice — transcription and text-to-speech via pure HTTP (no SDK deps).
+ *
+ * Supports OpenAI Whisper for transcription and OpenAI TTS for speech synthesis.
+ * Graceful degradation when API keys are missing.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface VoiceConfig {
+  /** OpenAI API key for Whisper transcription and TTS. */
+  openaiApiKey?: string;
+  /** TTS voice ID. Default: 'onyx'. */
+  ttsVoice?: string;
+  /** TTS model. Default: 'tts-1'. */
+  ttsModel?: string;
+  /** Whisper model. Default: 'whisper-1'. */
+  whisperModel?: string;
+}
+
+export interface TranscriptionResult {
+  /** Transcribed text. */
+  text: string;
+  /** Whether transcription was successful. */
+  success: boolean;
+}
+
+export interface SpeechResult {
+  /** Audio data as Buffer (MP3). */
+  audio: Buffer;
+  /** Whether synthesis was successful. */
+  success: boolean;
+}
+
+// ─── Transcriber ──────────────────────────────────────────────────────
+
+/**
+ * Transcribe audio using OpenAI Whisper API.
+ * Returns a fallback message if no API key is configured.
+ */
+export async function transcribeAudio(
+  audioBuffer: Buffer,
+  config: VoiceConfig,
+  filename: string = 'audio.ogg',
+): Promise<TranscriptionResult> {
+  if (!config.openaiApiKey) {
+    return { text: '[Voice message — transcription unavailable]', success: false };
+  }
+
+  const model = config.whisperModel ?? 'whisper-1';
+
+  // Build multipart form data manually (no SDK)
+  const boundary = `----SoleriFormBoundary${Date.now()}`;
+  const parts: Buffer[] = [];
+
+  // File part
+  parts.push(
+    Buffer.from(
+      `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${filename}"\r\nContent-Type: audio/ogg\r\n\r\n`,
+    ),
+  );
+  parts.push(audioBuffer);
+  parts.push(Buffer.from('\r\n'));
+
+  // Model part
+  parts.push(
+    Buffer.from(
+      `--${boundary}\r\nContent-Disposition: form-data; name="model"\r\n\r\n${model}\r\n`,
+    ),
+  );
+
+  parts.push(Buffer.from(`--${boundary}--\r\n`));
+  const body = Buffer.concat(parts);
+
+  try {
+    const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${config.openaiApiKey}`,
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+      },
+      body,
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!response.ok) {
+      await response.text().catch(() => {});
+      return { text: `[Transcription failed: ${response.status}]`, success: false };
+    }
+
+    const data = (await response.json()) as { text?: string };
+    return { text: data.text ?? '', success: true };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { text: `[Transcription error: ${msg}]`, success: false };
+  }
+}
+
+// ─── TTS ──────────────────────────────────────────────────────────────
+
+/**
+ * Synthesize speech from text using OpenAI TTS API.
+ * Returns null if no API key is configured.
+ */
+export async function synthesizeSpeech(
+  text: string,
+  config: VoiceConfig,
+): Promise<SpeechResult | null> {
+  if (!config.openaiApiKey) return null;
+
+  const model = config.ttsModel ?? 'tts-1';
+  const voice = config.ttsVoice ?? 'onyx';
+
+  try {
+    const response = await fetch('https://api.openai.com/v1/audio/speech', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${config.openaiApiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ model, voice, input: text }),
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!response.ok) {
+      return { audio: Buffer.alloc(0), success: false };
+    }
+
+    const audio = Buffer.from(await response.arrayBuffer());
+    return { audio, success: true };
+  } catch {
+    return { audio: Buffer.alloc(0), success: false };
+  }
+}

package/src/claudemd/compose.ts

@@ -0,0 +1,142 @@
+/**
+ * CLAUDE.md composition — generates LLM instructions from agent config and facades.
+ *
+ * Produces markdown with:
+ * 1. Global instructions (priority-sorted)
+ * 2. Activation / deactivation
+ * 3. Session start protocol
+ * 4. Facade reference table (auto-generated from registered facades)
+ * 5. Facade behavioral rules (from FacadeInstructions)
+ *
+ * Wrapped in versioned markers: `<!-- agent:mode v1 -->` / `<!-- /agent:mode -->`
+ */
+
+import type { FacadeConfig } from '../facades/types.js';
+import type { AgentMeta, FacadeInstructions, GlobalInstruction } from './types.js';
+
+export const FORMAT_VERSION = 1;
+export const OPEN_MARKER = `<!-- agent:mode v${FORMAT_VERSION} -->`;
+export const CLOSE_MARKER = '<!-- /agent:mode -->';
+export const USER_ZONE_OPEN = '<!-- user:custom -->';
+export const USER_ZONE_CLOSE = '<!-- /user:custom -->';
+
+function sortByPriority<T extends { priority?: number }>(items: T[]): T[] {
+  return [...items].sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50));
+}
+
+function renderActivation(agent: AgentMeta): string {
+  return [
+    `## ${agent.name} Mode`,
+    '',
+    '### Activation',
+    '',
+    `- "${agent.activationPhrase}" → \`${agent.activateCommand}\``,
+    `- "${agent.deactivationPhrase}" → \`${agent.deactivateCommand}\``,
+    '',
+    '> Persona details are returned dynamically by the activate response.',
+  ].join('\n');
+}
+
+function renderSessionStart(agent: AgentMeta): string {
+  return [
+    '### Session Start Protocol',
+    '',
+    'On EVERY new session:',
+    `1. Register project: \`${agent.id}_core op:register params:{ projectPath: "." }\``,
+    '2. Check activation response for `persistence.status`, `vault.connected`',
+    `3. Check for plans in \`executing\` state — remind user to reconcile`,
+  ].join('\n');
+}
+
+function renderFacadeTable(
+  facades: FacadeConfig[],
+  instructions?: Map<string, FacadeInstructions>,
+): string {
+  const lines = ['### Essential Tools', '', '| Facade | Key Ops |', '|--------|---------|'];
+
+  for (const facade of facades) {
+    const instr = instructions?.get(facade.name);
+    const allOps = facade.ops.map((o) => o.name);
+    const keyOps = instr?.keyOps ?? allOps.slice(0, 5);
+    const display = keyOps.map((o) => `\`${o}\``).join(', ');
+    const suffix = allOps.length > keyOps.length ? ', ...' : '';
+    lines.push(`| \`${facade.name}\` | ${display}${suffix} |`);
+  }
+
+  return lines.join('\n');
+}
+
+function renderGlobalInstruction(gi: GlobalInstruction): string {
+  return `## ${gi.heading}\n\n${gi.content.trim()}`;
+}
+
+function renderFacadeRules(name: string, instr: FacadeInstructions): string {
+  const lines: string[] = [`## ${instr.heading}`, ''];
+
+  if (instr.rules?.length) {
+    for (const rule of instr.rules) {
+      lines.push(`- ${rule}`);
+    }
+    lines.push('');
+  }
+
+  if (instr.templates) {
+    for (const [label, template] of Object.entries(instr.templates)) {
+      lines.push(`### ${label}`, '', template.trim(), '');
+    }
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+export interface ComposeOptions {
+  /** Per-facade behavioral instructions */
+  facadeInstructions?: Map<string, FacadeInstructions>;
+  /** Include an empty user-safe zone */
+  includeUserZone?: boolean;
+}
+
+/**
+ * Compose the full CLAUDE.md agent block from metadata and facades.
+ * Returns the content wrapped in versioned markers.
+ */
+export function composeCLAUDEmd(
+  agent: AgentMeta,
+  facades: FacadeConfig[],
+  options?: ComposeOptions,
+): string {
+  const sections: string[] = [];
+
+  // 1. Global instructions (sorted by priority)
+  if (agent.globalInstructions?.length) {
+    const sorted = sortByPriority(agent.globalInstructions);
+    for (const gi of sorted) {
+      sections.push(renderGlobalInstruction(gi));
+    }
+  }
+
+  // 2. Activation + session start
+  sections.push(renderActivation(agent));
+  sections.push(renderSessionStart(agent));
+
+  // 3. Facade reference table
+  sections.push(renderFacadeTable(facades, options?.facadeInstructions));
+
+  // 4. Facade behavioral rules
+  if (options?.facadeInstructions) {
+    const entries = [...options.facadeInstructions.entries()].sort(
+      ([, a], [, b]) => (a.priority ?? 50) - (b.priority ?? 50),
+    );
+    for (const [name, instr] of entries) {
+      sections.push(renderFacadeRules(name, instr));
+    }
+  }
+
+  // 5. User-safe zone
+  if (options?.includeUserZone) {
+    sections.push(`${USER_ZONE_OPEN}\n\n${USER_ZONE_CLOSE}`);
+  }
+
+  const body = sections.join('\n\n');
+  return `${OPEN_MARKER}\n\n${body}\n\n${CLOSE_MARKER}`;
+}

package/src/claudemd/index.ts

@@ -0,0 +1,17 @@
+export {
+  composeCLAUDEmd,
+  FORMAT_VERSION,
+  OPEN_MARKER,
+  CLOSE_MARKER,
+  USER_ZONE_OPEN,
+  USER_ZONE_CLOSE,
+} from './compose.js';
+export type { ComposeOptions } from './compose.js';
+export { injectCLAUDEmd, removeCLAUDEmd, hasCLAUDEmdBlock, extractUserZone } from './inject.js';
+export type {
+  AgentMeta,
+  GlobalInstruction,
+  FacadeInstructions,
+  InjectionResult,
+  RemovalResult,
+} from './types.js';