shraga 0.0.2 → 0.1.1

package/src/server/engine/shared.ts

@@ -0,0 +1,47 @@
+/**
+ * Helpers shared across add-on engine adapters (multi-provider loop, native cursor).
+ * Kept here so those engines don't duplicate event/transcript plumbing.
+ */
+import type { WsEvent } from '../claude.ts';
+import type { ConvMessage } from '../sessions.ts';
+
+/** Surface inline preview images embedded in a tool result as a separate image event. */
+export function* extractPreviewImages(output: string, toolUseId: string): Generator<WsEvent> {
+  if (!output.includes('preview') || !output.includes('data:image/')) return;
+  try {
+    const outer = JSON.parse(output);
+    // Cursor MCP wraps: {status, value: {content: [{text: {text: "<inner-json>"}}]}}
+    const innerRaw = outer?.value?.content?.[0]?.text?.text ?? outer?.value?.content?.[0]?.text;
+    const parsed = typeof innerRaw === 'string' ? JSON.parse(innerRaw) : outer;
+    const dataUrl = parsed?.preview;
+    if (typeof dataUrl === 'string' && dataUrl.startsWith('data:image/')) {
+      yield { type: 'tool_result_image', toolUseId, dataUrl } as any;
+    }
+  } catch {}
+}
+
+/** Flatten prior conversation turns into a compact <conversation-history> block for engines that lack native multi-turn state. */
+export function buildConversationSummary(conversation: ConvMessage[]): string {
+  if (conversation.length <= 1) return '';
+  // Skip the last message (it's the current user prompt, already in the prompt)
+  const prior = conversation.slice(0, -1);
+  const lines: string[] = ['<conversation-history>'];
+  for (const msg of prior) {
+    const texts = msg.blocks
+      .filter((b: any) => b.type === 'text' && b.text)
+      .map((b: any) => b.text.trim())
+      .filter(Boolean);
+    const tools = msg.blocks
+      .filter((b: any) => b.type === 'tool_use')
+      .map((b: any) => b.tool);
+    const images = msg.blocks.filter((b: any) => b.type === 'image').length;
+    if (texts.length || tools.length) {
+      lines.push(`[${msg.role}]`);
+      for (const t of texts) lines.push(t.length > 500 ? t.slice(0, 500) + '…' : t);
+      if (tools.length) lines.push(`(tools used: ${tools.join(', ')})`);
+      if (images) lines.push(`(${images} image(s) shown)`);
+    }
+  }
+  lines.push('</conversation-history>');
+  return lines.length > 2 ? lines.join('\n') : '';
+}

package/src/server/engine/types.ts

@@ -0,0 +1,48 @@
+import type { McpConfig } from '../mcp.ts';
+import type { WsEvent, AttachmentMeta, PermissionHandler, QuestionHandler } from '../claude.ts';
+import type { ConvMessage } from '../sessions.ts';
+import type { Directives } from '../directives.ts';
+import type { AgentSettings } from '../shraga-config.ts';
+
+export interface EngineStreamOpts {
+  /** The user's effective prompt (after directive stripping, slash command expansion, skill/workspace mentions) */
+  prompt: string;
+  /** Raw conversation history from JSONL (engine formats as needed) */
+  conversation: ConvMessage[];
+  /** Contextual blocks to prepend (user block, skills, workspace tree, etc.) */
+  contextBlock: string;
+
+  attachments?: AttachmentMeta[];
+  images?: string[];
+  sessionId: string;
+  uid: string;
+  userEmail?: string;
+  userName?: string;
+  mcpServers?: McpConfig;
+  abortController?: AbortController;
+  onPermissionRequest?: PermissionHandler;
+  onDestructiveApproval?: PermissionHandler;
+  onUserQuestion?: QuestionHandler;
+  voiceMode?: boolean;
+  /** True when the conversation was truncated (user replayed/edited a message) — engines with cached state should reset. */
+  conversationReset?: boolean;
+  context?: Record<string, string>;
+
+  directives: Directives;
+  config: AgentSettings;
+}
+
+export interface AgentEngine {
+  readonly name: string;
+  stream(opts: EngineStreamOpts): AsyncGenerator<WsEvent>;
+  /** Return model options for the UI picker (only called when engine is available) */
+  getModels(): EngineModel[];
+  init?(): Promise<void>;
+  shutdown?(): Promise<void>;
+}
+
+export interface EngineModel {
+  value: string;
+  label: string;
+  provider?: string;
+}

package/src/server/env-resolve.ts

@@ -0,0 +1,71 @@
+// Resolve and load the correct .env file at startup.
+// Must be imported FIRST — before env-sanitize or any config reader.
+//
+// Resolution order:
+// 1. ENV_NAME env var → .env.{name}
+// 2. --env-file already loaded (has ANTHROPIC_API_KEY) → no-op
+// 3. Scan for .env.* files:
+//    - exactly one non-example → auto-select
+//    - multiple → error with list
+//    - none → fall back to bare .env (prod)
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dir, '../..');
+const TAG = '[env]';
+const SKIP = /\.(example|bak|copy|deploy-restore)/;
+
+function alreadyLoaded(): boolean {
+  return !!(process.env.ANTHROPIC_API_KEY || process.env.DATA_SYNC_REPO);
+}
+
+function findNamedEnvs(): string[] {
+  return readdirSync(ROOT)
+    .filter(f => f.startsWith('.env.') && !SKIP.test(f))
+    .map(f => f.slice(5));
+}
+
+function loadFile(filePath: string): void {
+  const content = readFileSync(filePath, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 1) continue;
+    const key = trimmed.slice(0, eq);
+    const val = trimmed.slice(eq + 1).replace(/^["']|["']$/g, '').replace(/\s+#.*$/, '');
+    if (!(key in process.env)) process.env[key] = val;
+  }
+}
+
+if (!alreadyLoaded()) {
+  const envName = process.env.ENV_NAME;
+
+  if (envName) {
+    const p = path.join(ROOT, `.env.${envName}`);
+    if (!existsSync(p)) {
+      console.error(`${TAG} ❌ .env.${envName} not found`);
+      process.exit(1);
+    }
+    loadFile(p);
+    console.log(`${TAG} Loaded .env.${envName}`);
+  } else {
+    const named = findNamedEnvs();
+    const bare = path.join(ROOT, '.env');
+
+    if (named.length === 1) {
+      const p = path.join(ROOT, `.env.${named[0]}`);
+      loadFile(p);
+      process.env.ENV_NAME = named[0];
+      console.log(`${TAG} Auto-selected .env.${named[0]} (only named env)`);
+    } else if (named.length > 1 && !existsSync(bare)) {
+      console.error(`${TAG} ❌ Multiple named envs found, set ENV_NAME to pick one:`);
+      for (const n of named) console.error(`${TAG}   .env.${n}`);
+      process.exit(1);
+    } else if (existsSync(bare)) {
+      loadFile(bare);
+    } else {
+      console.warn(`${TAG} No .env file found — relying on system environment`);
+    }
+  }
+}

package/src/server/env-sanitize.ts

@@ -0,0 +1,9 @@
+// Drop env vars whose value is an unresolved `${VAR}` placeholder left by deploy tooling
+// (deploy tools may write `KEY=${VAR}` when the source var is unset). Such a value is never
+// legitimate — it defeats `process.env.A ?? process.env.B` fallbacks and breaks JSON.parse.
+// Imported first in index.ts so it runs before any config is read.
+const PLACEHOLDER = /^['"]?\$\{[A-Za-z0-9_]+\}['"]?$/;
+
+for (const [key, value] of Object.entries(process.env)) {
+  if (typeof value === 'string' && PLACEHOLDER.test(value.trim())) delete process.env[key];
+}

package/src/server/events/bus.ts

@@ -0,0 +1,29 @@
+// Tiny in-process event bus — the driving port for event-based triggers.
+//
+// Sources (the generic /api/events route, data-side extensions, internal watchers)
+// call emitEvent(); the dispatcher subscribes and routes matching events to the
+// scheduler's execution path. Deliberately minimal: no plugin registry, no
+// lifecycle — just emit + subscribe. Adding a source = one emitEvent() call.
+import type { ShragaEvent } from './types.ts';
+
+type Listener = (evt: ShragaEvent) => void;
+
+const listeners = new Set<Listener>();
+
+/** Subscribe to all events. Returns an unsubscribe fn. */
+export function subscribeEvents(fn: Listener): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/** Publish an event. Listeners are invoked synchronously; a throwing listener is
+ *  logged and skipped so one bad subscriber can't sink the emit. */
+export function emitEvent(source: string, payload: unknown, opts?: { id?: string }): ShragaEvent {
+  const evt: ShragaEvent = { source, payload, id: opts?.id, at: Date.now() };
+  for (const fn of listeners) {
+    try { fn(evt); } catch (err) {
+      console.error(`[events] listener threw for source "${source}":`, err);
+    }
+  }
+  return evt;
+}

package/src/server/events/dispatcher.ts

@@ -0,0 +1,48 @@
+// Routes bus events to the scheduler. Subscribes once; for each event, dedupes by
+// id (retried webhooks) then asks the scheduler to fire matching `event`-trigger
+// schedules. Actual execution + active-instance gating lives in scheduler.fireEvent.
+import { subscribeEvents } from './bus.ts';
+import * as scheduler from '../scheduler/index.ts';
+
+const DEDUPE_TTL_MS = 5 * 60_000;
+const DEDUPE_MAX = 1000;
+/** id → first-seen timestamp. Bounded; old entries pruned on insert. */
+const seen = new Map<string, number>();
+
+function isDuplicate(id: string): boolean {
+  const now = Date.now();
+  // Prune expired (and cap size) before checking.
+  if (seen.size >= DEDUPE_MAX) {
+    for (const [k, ts] of seen) {
+      if (now - ts > DEDUPE_TTL_MS) seen.delete(k);
+    }
+    // Still over cap → drop oldest insertion (Map preserves insertion order).
+    while (seen.size >= DEDUPE_MAX) {
+      const oldest = seen.keys().next().value;
+      if (oldest === undefined) break;
+      seen.delete(oldest);
+    }
+  }
+  const prev = seen.get(id);
+  if (prev !== undefined && now - prev <= DEDUPE_TTL_MS) return true;
+  seen.set(id, now);
+  return false;
+}
+
+let started = false;
+
+export function startEventDispatcher(): void {
+  if (started) return; // idempotent — a double subscribe would double-fire every event
+  started = true;
+  subscribeEvents((evt) => {
+    if (evt.id && isDuplicate(evt.id)) {
+      console.log(`[events] duplicate ${evt.source}#${evt.id} — ignored`);
+      return;
+    }
+    const fired = scheduler.fireEvent(evt.source, evt.payload);
+    if (fired.length) {
+      console.log(`[events] "${evt.source}" → fired ${fired.length} trigger(s): ${fired.join(', ')}`);
+    }
+  });
+  console.log('[events] dispatcher started');
+}

package/src/server/events/routes.ts

@@ -0,0 +1,19 @@
+// Generic inbound event endpoint: POST /api/events/:source
+//
+// For trusted callers that can present shraga auth (API key `uck_…`, bearer, or the
+// internal token). The body becomes the event payload; an optional `X-Event-Id`
+// header dedupes retries. Vendor webhooks that can't send shraga auth (Stripe,
+// GitHub, …) should instead live in a data-side extension that verifies the
+// vendor's own signature and calls ctx.emitEvent() server-side.
+import type { Express, RequestHandler } from 'express';
+import { emitEvent } from './bus.ts';
+
+export function registerEventRoutes(app: Express, requireAuth: RequestHandler): void {
+  app.post('/api/events/:source', requireAuth, (req, res) => {
+    const source = String(req.params.source || '').trim();
+    if (!source) return res.status(400).json({ error: 'Missing source' });
+    const id = typeof req.headers['x-event-id'] === 'string' ? req.headers['x-event-id'] : undefined;
+    const evt = emitEvent(source, req.body ?? {}, { id });
+    res.json({ ok: true, source, at: evt.at });
+  });
+}

package/src/server/events/types.ts

@@ -0,0 +1,9 @@
+/** A single event flowing through the bus. `source` routes it to matching
+ *  `event`-trigger schedules; `payload` is matched against their `match` filter and
+ *  injected into the run. `id` (optional) dedupes retried webhook deliveries. */
+export interface ShragaEvent {
+  source: string;
+  payload: unknown;
+  id?: string;
+  at: number;
+}

package/src/server/extensions.ts

@@ -0,0 +1,101 @@
+// Generic loader for deployment-specific HTTP routes ("extensions").
+//
+// Drop a `*.ext.ts` file into the data dir's `extensions/` folder that exports a
+// default `register(router, ctx)` function and it's mounted — into a persistent
+// Router that is itself mounted BEFORE the SPA catch-all (`app.get('*')`). That
+// ordering is the whole trick: a route registered after the catch-all is silently
+// swallowed → returns SPA HTML.
+//
+// HOT-RELOAD: NEW `*.ext.ts` files are picked up at runtime (a dir watch re-scans)
+// — no server restart needed. Because routes are added to the already-mounted
+// Router, they're reachable immediately and still sit before the catch-all.
+// CAVEAT: EDITING an already-loaded file does NOT hot-reload (ESM module cache;
+// re-importing would stack duplicate handlers) — that still needs a restart.
+//
+// Keeps one-off / per-deployment flows that must live on this instance's own
+// public URL (OAuth/manifest callbacks, webhooks) OUT of shared `src/`.
+// See the self-aware skill, "Where one-off / custom code goes".
+import express, { type Express, type Router as ExpressRouter, type RequestHandler } from 'express';
+import { existsSync, readdirSync, watch } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { dataPath } from './paths.ts';
+import { requireAuth } from './auth.ts';
+import { emitEvent } from './events/bus.ts';
+
+export interface ExtensionContext {
+  /** Resolve a path inside the active data dir (e.g. ctx.dataPath('github-app.json')). */
+  dataPath: (p: string) => string;
+  /** Express middleware enforcing auth (bearer / api-key / internal token / ?token=). */
+  requireAuth: RequestHandler;
+  /** Prefixed logger. */
+  log: (...a: unknown[]) => void;
+  /** The root Express app, for the rare extension needing app-level middleware. */
+  app: Express;
+  /** Publish an event onto the bus → fires matching `event`-trigger schedules.
+   *  Use after verifying a vendor webhook's own signature. */
+  emitEvent: (source: string, payload: unknown, opts?: { id?: string }) => void;
+}
+
+const loaded = new Set<string>();
+let extRouter: ExpressRouter | null = null;
+let ctx: ExtensionContext | null = null;
+
+async function mountFile(dir: string, f: string): Promise<void> {
+  if (loaded.has(f) || !extRouter || !ctx) return;
+  loaded.add(f); // claim before the await, so overlapping scans can't double-mount the same file
+  try {
+    const mod = await import(pathToFileURL(path.join(dir, f)).href);
+    const register = mod.default ?? mod.register;
+    if (typeof register !== 'function') {
+      loaded.delete(f); // release so a fixed file is retried on its next change event
+      console.warn(`[extensions] ${f}: no default export (register fn) — skipped`);
+      return;
+    }
+    // Routes register onto the persistent Router (mounted before the catch-all).
+    await register(extRouter, ctx);
+    console.log(`[extensions] mounted ${f}`);
+  } catch (err) {
+    loaded.delete(f); // import/register threw — allow a retry on the next change
+    console.error(`[extensions] failed to mount ${f}:`, (err as Error)?.stack || err);
+  }
+}
+
+async function scan(dir: string): Promise<void> {
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir).filter((f) => f.endsWith('.ext.ts')).sort()) {
+    await mountFile(dir, f);
+  }
+}
+
+export async function loadExtensions(app: Express): Promise<void> {
+  extRouter = express.Router();
+  app.use(extRouter); // BEFORE the SPA catch-all (loadExtensions is called before it in index.ts)
+  ctx = {
+    dataPath,
+    requireAuth: requireAuth as unknown as RequestHandler,
+    log: (...a) => console.log('[extensions]', ...a),
+    app,
+    emitEvent,
+  };
+
+  const dir = path.resolve(dataPath('extensions'));
+  await scan(dir);
+
+  // Hot-reload: re-scan when a *.ext.ts file appears at runtime (debounced).
+  if (existsSync(dir)) {
+    try {
+      let t: ReturnType<typeof setTimeout> | null = null;
+      watch(dir, (_evt, filename) => {
+        if (!filename || !String(filename).endsWith('.ext.ts')) return;
+        if (t) clearTimeout(t);
+        t = setTimeout(() => {
+          scan(dir).catch((err) => console.error('[extensions] rescan failed:', (err as Error).message));
+        }, 300);
+      });
+      console.log('[extensions] watching for new *.ext.ts (hot-reload of new files, no restart)');
+    } catch (err) {
+      console.warn('[extensions] dir watch unavailable (new files need a restart):', (err as Error).message);
+    }
+  }
+}

package/src/server/features.ts

@@ -0,0 +1,109 @@
+// Server feature seam — the drop-in point for optional add-ons.
+//
+// The core mounts only the seam; it registers NOTHING here. An optional add-on (a downstream
+// distribution or a private module) imports this and calls registerFeature({...}) for each
+// add-on surface BEFORE the server starts, then those get
+// mounted at the one `mountFeatures()` call in index.ts. This keeps add-on code entirely out of
+// the core tree while giving it a clean, typed way in.
+//
+// Deeper than the data-side `*.ext.ts` extensions (which are just routes): a feature gets the
+// live app + broadcast + auth so it can wire websockets, background workers, recovery, etc.
+
+import type { Express, RequestHandler } from 'express';
+
+export interface FeatureContext {
+  app: Express;
+  requireAuth: RequestHandler;
+  /** Push a server event to all connected clients (same fn the core uses). */
+  broadcast: (event: object) => void;
+  /** True in passive/standby mode — features should skip background writers/consumers. */
+  passive: boolean;
+}
+
+export interface ServerFeature {
+  readonly name: string;
+  /** Mount routes/handlers/consumers. Throwing is contained (logged, other features still load). */
+  register(ctx: FeatureContext): void;
+  /** Optional: resume an interrupted session for this feature's channel (called by recovery). */
+  resumeSession?(session: unknown, prompt: string): Promise<void> | void;
+  /**
+   * Optional: client-facing capability flags this feature contributes to `/api/features`.
+   * A static map or a getter (evaluated per request, so it can honor env). Merged OVER the core
+   * flags. This is how an add-on surface turns itself on WITHOUT the core naming it — the core
+   * declares none; an add-on's feature declares its own flag (e.g. `{ someSurface: true }`).
+   */
+  readonly flags?: Record<string, boolean> | (() => Record<string, boolean>);
+  /**
+   * Optional: sidecar WebSocket proxy routes this feature contributes (url-prefix → localhost port).
+   * Merged into the core WS proxy table so a feature's daemon socket is reachable WITHOUT the core
+   * naming the prefix. Same generic bridge as `flags`.
+   */
+  readonly sidecarRoutes?: Record<string, number>;
+  /**
+   * Optional: MCP server names that must ALWAYS be handed to an engine which narrows its MCP set for
+   * speed (rather than only when the prompt happens to mention them). A feature that depends on one
+   * of its own MCP servers declares it here, so the core never has to name it. Static or a getter
+   * (evaluated per call, so it can honor env) — same shape as `flags`.
+   */
+  readonly alwaysMcp?: string[] | (() => string[]);
+}
+
+const registry: ServerFeature[] = [];
+
+/** Register an add-on feature. Called by an optional add-on before startup. Idempotent by name. */
+export function registerFeature(feature: ServerFeature): void {
+  if (registry.some((f) => f.name === feature.name)) return;
+  registry.push(feature);
+}
+
+/** Mount all registered features. The single seam call in index.ts. */
+export function mountFeatures(ctx: FeatureContext): void {
+  for (const f of registry) {
+    try {
+      f.register(ctx);
+      console.log(`[features] mounted ${f.name}`);
+    } catch (err) {
+      console.error(`[features] failed to mount ${f.name}:`, (err as Error)?.stack || err);
+    }
+  }
+}
+
+/** Merge every registered feature's contributed capability flags. Merged OVER core flags in
+ *  `/api/features` so an add-on feature's declaration wins. The core contributes nothing here. */
+export function collectFeatureFlags(): Record<string, boolean> {
+  const out: Record<string, boolean> = {};
+  for (const f of registry) {
+    if (!f.flags) continue;
+    Object.assign(out, typeof f.flags === 'function' ? f.flags() : f.flags);
+  }
+  return out;
+}
+
+/** Merge every registered feature's sidecar WS proxy routes (prefix → port). Folded into the
+ *  core WS proxy table after startup so feature daemons are reachable. */
+export function collectSidecarRoutes(): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const f of registry) if (f.sidecarRoutes) Object.assign(out, f.sidecarRoutes);
+  return out;
+}
+
+/** Every MCP server name registered features insist on always having. The core contributes NONE, so
+ *  an engine that narrows its MCP set starts from empty and names no add-on server itself. */
+export function collectAlwaysMcp(): Set<string> {
+  const out = new Set<string>();
+  for (const f of registry) {
+    if (!f.alwaysMcp) continue;
+    for (const n of typeof f.alwaysMcp === 'function' ? f.alwaysMcp() : f.alwaysMcp) out.add(n);
+  }
+  return out;
+}
+
+/** Let a registered feature resume its own interrupted sessions (used by crash recovery). */
+export function resumeFeatureSession(channel: string, session: unknown, prompt: string): boolean {
+  const f = registry.find((x) => x.name === channel && x.resumeSession);
+  if (!f) return false;
+  Promise.resolve(f.resumeSession!(session, prompt)).catch((err) =>
+    console.error(`[features] ${channel} resume failed:`, (err as Error).message),
+  );
+  return true;
+}

package/src/server/file-inject.ts

@@ -0,0 +1,45 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+export interface InjectFileOptions {
+  maxChars?: number;
+  label?: string;
+  /** Transform raw content before truncation. 'conversation' extracts text-only blocks from JSONL. */
+  transform?: 'conversation' | ((content: string) => string);
+}
+
+function transformConversation(raw: string): string {
+  return raw.split('\n').filter(Boolean).flatMap(line => {
+    try {
+      const msg = JSON.parse(line);
+      if (!msg.blocks || !msg.role) return [];
+      return msg.blocks
+        .filter((b: any) => b.type === 'text')
+        .map((b: any) => `[${msg.role}]: ${b.text}`);
+    } catch { return []; }
+  }).join('\n');
+}
+
+export function injectFile(filePath: string, opts?: InjectFileOptions): string {
+  if (!existsSync(filePath)) return '';
+  const label = opts?.label ?? 'file';
+  const maxChars = opts?.maxChars ?? 2000;
+  const unlimited = maxChars <= 0;
+  const name = path.basename(filePath);
+  let content: string;
+  try {
+    content = readFileSync(filePath, 'utf-8').trim();
+  } catch (e) {
+    console.warn(`[file-inject] Failed to read ${filePath}:`, e);
+    return '';
+  }
+  if (!content) return '';
+  if (opts?.transform === 'conversation') content = transformConversation(content);
+  else if (typeof opts?.transform === 'function') content = opts.transform(content);
+  if (!content) return '';
+  const truncated = !unlimited && content.length > maxChars;
+  const body = truncated
+    ? `${content.slice(0, maxChars)}\n… (truncated at ${maxChars} chars — full file: ${filePath})`
+    : content;
+  return `<${label} path="${filePath}">\n# ${name}\n${body}\n</${label}>`;
+}