shraga 0.1.13 → 0.1.15

package/src/client/hooks/useModules.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useState } from 'react';
+import { api } from '@/lib/api';
+
+export interface ModuleConfigField {
+  type: 'string' | 'number' | 'boolean';
+  default: unknown;
+  description?: string;
+}
+export type ModuleConfigSchema = Record<string, ModuleConfigField>;
+
+export interface InstalledModule {
+  name: string;
+  version: string;
+  description?: string;
+  enabled: boolean;
+  config: Record<string, unknown>;
+  installedAt: string;
+  source: string;
+  configSchema?: ModuleConfigSchema;
+  skillCount?: number;
+  scheduleCount?: number;
+  /** Server contract addition: GET /api/modules entries may include the module's README (markdown). */
+  readme?: string;
+}
+
+export interface AvailableModule {
+  name: string;
+  version: string;
+  description?: string;
+  installed: boolean;
+  configSchema?: ModuleConfigSchema;
+}
+
+export function useModules(getToken: () => Promise<string | null>, enabled: boolean, refreshKey = 0) {
+  const [installed, setInstalled] = useState<InstalledModule[]>([]);
+  const [available, setAvailable] = useState<AvailableModule[]>([]);
+  const [unsupported, setUnsupported] = useState(false); // server predates /api/modules (404)
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await api<{ installed: InstalledModule[]; available: AvailableModule[] }>('/api/modules', getToken);
+      setInstalled(data.installed ?? []);
+      setAvailable(data.available ?? []);
+      setUnsupported(false);
+    } catch (e: any) {
+      // Note: this detection assumes a pre-modules server 404 carries no JSON `error` field (message stays "404 Not Found").
+      if (/^404\b/.test(e.message)) setUnsupported(true);
+      else setError(e.message);
+    } finally {
+      setLoading(false);
+    }
+  }, [getToken]);
+
+  useEffect(() => { if (enabled) refresh(); }, [enabled, refresh, refreshKey]);
+
+  const install = useCallback(async (ref: { name?: string; path?: string }) => {
+    await api('/api/modules/install', getToken, { method: 'POST', body: JSON.stringify(ref) });
+    await refresh();
+  }, [getToken, refresh]);
+
+  const toggle = useCallback(async (name: string, en: boolean) => {
+    await api(`/api/modules/${name}/${en ? 'enable' : 'disable'}`, getToken, { method: 'POST' });
+    await refresh();
+  }, [getToken, refresh]);
+
+  const updateConfig = useCallback(async (name: string, config: Record<string, unknown>) => {
+    await api(`/api/modules/${name}/config`, getToken, { method: 'PUT', body: JSON.stringify({ config }) });
+    await refresh();
+  }, [getToken, refresh]);
+
+  const uninstall = useCallback(async (name: string) => {
+    await api(`/api/modules/${name}`, getToken, { method: 'DELETE' });
+    await refresh();
+  }, [getToken, refresh]);
+
+  return { installed, available, unsupported, loading, error, refresh, install, toggle, updateConfig, uninstall };
+}

package/src/client/lib/api.ts

@@ -0,0 +1,13 @@
+/** Minimal authenticated JSON fetch helper. Throws `Error("<status> <statusText>")` or the server's `error` field. */
+export async function api<T>(path: string, getToken: () => Promise<string | null>, init?: RequestInit): Promise<T> {
+  const token = await getToken();
+  const res = await fetch(path, {
+    ...init,
+    headers: { Authorization: `Bearer ${token ?? ''}`, 'Content-Type': 'application/json', ...init?.headers },
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || `${res.status} ${res.statusText}`);
+  }
+  return res.json();
+}

package/src/client/lib/sessionApi.ts

@@ -1,7 +1,21 @@
 import { randomUUID } from '@/lib/utils';
 import type { ChatMessage, MessageBlock } from '@/hooks/useConversation';
 
-/** Authenticated fetch with bearer token + timeout. Throws on !ok. */
+/** An !ok response from `apiFetch`, carrying the HTTP `status` so callers can branch on it.
+ *
+ *  WHY a class and not a bare Error: apiFetch THROWS on !ok — it never RETURNS a non-ok response — so
+ *  the natural-looking `const res = await apiFetch(…); if (res.status === 404) …` is DEAD CODE that
+ *  never runs. Callers must branch in the `catch`, and a stringified `Error('404 Not Found')` leaves
+ *  them parsing the message to do it. This shipped as a real bug: a dead-PTY cwd poller kept 404ing
+ *  every 3s forever because its "stop on 404" test sat on the return value. */
+export class ApiError extends Error {
+  constructor(public readonly status: number, statusText: string) {
+    super(`${status} ${statusText}`);
+    this.name = 'ApiError';
+  }
+}
+
+/** Authenticated fetch with bearer token + timeout. Throws `ApiError` (with `.status`) on !ok. */
 export async function apiFetch(
   path: string,
   getToken: () => Promise<string | null>,
@@ -19,7 +33,7 @@ export async function apiFetch(
       signal: controller.signal,
       headers: { Authorization: `Bearer ${token}`, ...init?.headers },
     });
-    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    if (!res.ok) throw new ApiError(res.status, res.statusText);
     return res;
   } finally {
     clearTimeout(timer);

package/src/client/lib/workspaceContext.tsx

@@ -11,6 +11,8 @@ export interface AgentConfig {
   systemPrompt?: string;
   thinking?: 'adaptive' | 'enabled' | 'disabled';
   effort?: 'low' | 'medium' | 'high' | 'max';
+  /** Derived server state (read-only, not persisted): claude-code credentials in use — see /api/config. */
+  claudeAuthSource?: 'subscription' | 'api-key';
 }
 
 /**

package/src/mcp-stdio-bridge.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 // stdio↔HTTP bridge for MCP (Streamable HTTP transport, maintains session ID)
-// Generic: MCP_URL + MCP_API_KEY, or legacy: UNCLAW_URL + UNCLAW_API_KEY
-const baseUrl = (process.env.MCP_URL || process.env.UNCLAW_URL || 'http://localhost:3033').replace(/\/$/, '');
-const mcpPath = process.env.MCP_PATH || '/mcp';
-const apiKey = process.env.MCP_API_KEY || process.env.UNCLAW_API_KEY;
-if (!apiKey) { console.error('[mcp-bridge] MCP_API_KEY (or UNCLAW_API_KEY) is required'); process.exit(1); }
+// Env: SHRAGA_URL + SHRAGA_API_KEY (preferred), or generic MCP_URL + MCP_API_KEY, or legacy UNCLAW_*
+const baseUrl = (process.env.SHRAGA_URL || process.env.MCP_URL || process.env.UNCLAW_URL || 'http://localhost:3033').replace(/\/$/, '');
+const mcpPath = process.env.SHRAGA_MCP_PATH || process.env.MCP_PATH || '/mcp';
+const apiKey = process.env.SHRAGA_API_KEY || process.env.MCP_API_KEY || process.env.UNCLAW_API_KEY;
+if (!apiKey) { console.error('[mcp-bridge] SHRAGA_API_KEY (or MCP_API_KEY/UNCLAW_API_KEY) is required'); process.exit(1); }
 
 let sessionId: string | null = null;
 

package/src/server/boot.ts

@@ -12,6 +12,7 @@ process.on('unhandledRejection', (reason) => {
   console.error('[server] Unhandled rejection (kept alive):', msg);
 });
 import { createServer } from 'node:http';
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import path from 'node:path';
@@ -20,7 +21,7 @@ import express from 'express';
 import { WebSocketServer, WebSocket } from 'ws';
 import { requireAuth, verifyBearer, AUTH_PROVIDER, localLogin, addLocalUser, localUserCount } from './auth.ts';
 import { getMcpConfig, getRawMcpConfig, getResolvedMcpConfig, getGlobalMcpConfig, saveMcpConfig, maskEnvValues, mergeWithOriginal, type McpConfig } from './mcp.ts';
-import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, type AgentConfig, type PermissionHandler, type QuestionHandler, type QuestionAnswers, type AttachmentMeta, type WsEvent } from './claude.ts';
+import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, getClaudeAuthSource, type AgentConfig, type PermissionHandler, type QuestionHandler, type QuestionAnswers, type AttachmentMeta, type WsEvent } from './claude.ts';
 import { mountFeatures, registerFeature, resumeFeatureSession, collectFeatureFlags, collectSidecarRoutes } from './features.ts';
 import { registerSpaCatchAll } from './spa-catchall.ts';
 import { slackFeature } from './slack/feature.ts';
@@ -36,9 +37,11 @@ import type { Schedule } from './scheduler/index.ts';
 import { listSkills, listMcpCommands, getSkill, saveSkill, deleteSkill, duplicateSkill, renameSkill, getDefaultSkills, setDefaultSkills, resolveDefaultSkillsContent, purgeExpiredSkills, lintSkills } from './skills.ts';
 import { listWorkspaceTree, listWorkspaceDir, readWorkspaceFile, safeResolve as resolveWorkspacePath, watchWorkspace, ensureDir as ensureWorkspaceDir } from './workspace.ts';
 import { seedDefaults, getBuiltinSkillNames } from './seed.ts';
+import { registerModuleRoutes, reconcileInstalledModules } from './modules/index.ts';
 import { hydrateSlackUserToken } from './slack/oauth.ts';
 import { registerMcpOAuthRoutes } from './mcp-oauth.ts';
 import { registerEventRoutes } from './events/routes.ts';
+import { registerWebhook } from './events/webhook.ts';
 import { startEventDispatcher } from './events/dispatcher.ts';
 import { seedOperators } from './contacts.ts';
 import { dataSync } from './data-sync.ts';
@@ -47,7 +50,7 @@ import { lookupIdempotent, rememberIdempotent } from './idempotency.ts';
 import { createApiKey, deleteApiKey, listApiKeys } from './api-keys.ts';
 import { addUnread, markRead as markUnread, getUnreads } from './unread.ts';
 
-import { loadShragaConfig } from './shraga-config.ts';
+import { loadShragaConfig, getPublicOrigin } from './shraga-config.ts';
 import { startSidecars, stopSidecars } from './mcp-sidecar.ts';
 import { syncVendorRepos } from './vendor-sync.ts';
 import { initEngines, getAvailableEngines, getEngine } from './engine/index.ts';
@@ -297,11 +300,14 @@ app.put('/api/mcps', requireAuth, (req, res) => {
 });
 
 app.get('/api/config', requireAuth, (_req, res) => {
-  res.json(getAgentConfig());
+  // `claudeAuthSource` is derived server state (not persisted config) — the spread always overrides
+  // any stale value, so it can never round-trip into agent-config.json even if a client echoes it back.
+  res.json({ ...getAgentConfig(), claudeAuthSource: getClaudeAuthSource() });
 });
 
 app.put('/api/config', requireAuth, (req, res) => {
-  saveAgentConfig(req.body as AgentConfig);
+  const { claudeAuthSource: _drop, ...config } = (req.body ?? {}) as AgentConfig & { claudeAuthSource?: string };
+  saveAgentConfig(config);
   res.json({ ok: true });
 });
 
@@ -365,6 +371,9 @@ app.put('/api/skills-defaults', requireAuth, (req, res) => {
   res.json({ ok: true });
 });
 
+// ── Data-plane modules ───────────────────────────────────────────────────────
+registerModuleRoutes(app, requireAuth);
+
 // ── Schedules ────────────────────────────────────────────────────────────────
 
 function scheduleIfVisible(id: string, uid: string, isOwner = false): Schedule | undefined {
@@ -932,7 +941,14 @@ function broadcast(data: object, exclude?: WebSocket) {
 setBroadcaster(broadcast); // let session-bus push async events (e.g. an add-on's background worker output) to clients
 ensureWorkspaceDir();
 watchWorkspace((event) => broadcast({ type: 'workspace_change', ...event }));
-if (!PASSIVE) { scheduler.start(broadcast); startEventDispatcher(); }
+if (!PASSIVE) {
+  scheduler.start(broadcast);
+  startEventDispatcher();
+  // Modules reconcile MUST follow scheduler.start(): upsertSchedule mutates the engine's
+  // in-memory list, which is empty (and would be saved over schedules.json) before start.
+  // Skipped when passive (single-active-writer: no data/ mutations from a standby twin).
+  try { reconcileInstalledModules(); } catch (err) { console.error('[modules] boot reconcile failed:', (err as Error).message); }
+}
 // Host telemetry is read-only (no persistence, unref'd timer) — not a writer or consumer, so it
 // runs in passive too. Otherwise a standby instance reports empty stats and /api/stats is a lie.
 statsSampler.start(broadcast);
@@ -945,7 +961,7 @@ initPolls({
 // Remote-push triggers: subscribe to schedule.finished and expose turn-done/question
 // hooks. isForeground reuses the existing presence tracking (see isUserViewingSession).
 initPushTriggers({
-  origin: process.env.PUBLIC_ORIGIN || '',
+  origin: getPublicOrigin(),
   isForeground: (uid, sessionId) => isUserViewingSession(uid, sessionId),
 });
 // Optional add-ons (voice, github, gmail, fleet, …) mount here through the feature seam.
@@ -1002,12 +1018,62 @@ app.post('/internal/activate', async (req, res) => {
   res.json({ ok: true });
 });
 
-app.post('/api/data-sync/webhook', async (req, res) => {
-  if (!activated || !dataSync.isEnabled()) return res.sendStatus(404);
-  const secret = process.env.DATA_SYNC_WEBHOOK_SECRET;
-  if (secret && req.headers['x-webhook-secret'] !== secret) return res.sendStatus(403);
-  await dataSync.pull();
-  res.sendStatus(200);
+// Constant-time equality for two strings (avoids leaking length/content via timing).
+function safeStrEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a), bb = Buffer.from(b);
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+
+// Verify GitHub's HMAC signature (x-hub-signature-256 = "sha256=" + HMAC-SHA256(secret, RAW BODY)).
+// Must run over the EXACT bytes GitHub sent, captured as req.rawBody by express.json's verify hook —
+// re-serializing req.body would change the bytes and never match.
+function validGithubSignature(req: express.Request, secret: string): boolean {
+  const header = req.headers['x-hub-signature-256'];
+  if (typeof header !== 'string') return false;
+  const raw = (req as any).rawBody as Buffer | undefined;
+  if (!raw) return false;
+  const expected = 'sha256=' + createHmac('sha256', secret).update(raw).digest('hex');
+  return safeStrEqual(header, expected);
+}
+
+// Data-sync webhook, ported to shraga's first-class registerWebhook convention: the framework mounts
+// the PUBLIC route, captures rawBody, runs `verify` (the ONLY per-vendor piece — the HMAC below),
+// rejects on a falsy result, and on a pass emits the 'data-sync.pull' event. The subscribeEvent below
+// (gated on active/non-passive) consumes it and calls dataSync.pull(). Mounted on `app` at the
+// SAME position the bespoke route occupied — before the SPA catch-all — via the `path` option, so the
+// GitHub webhook needs no reconfig.
+//
+// Semantic deltas vs the old inline route (documented, deliberate):
+//   • bad signature → 400 (was 403): registerWebhook's convention is 400 for any falsy verify. GitHub
+//     treats any non-2xx as a failed delivery, so redelivery/behavior is unchanged.
+//   • not-activated / data-sync disabled → 200 (was 404): the route now always accepts + emits; the
+//     PULL is what's gated. In passive/standby no pull handler is subscribed (single-active-writer),
+//     and pull() itself no-ops when disabled — so no data is mutated. The webhook only ever targets
+//     the active instance, so the visible-status change is inert in practice.
+//   • response no longer awaits the pull: 200 is returned on emit and pull() runs async. This is the
+//     convention (and safer — a git pull must not block GitHub's ~10s webhook timeout).
+registerWebhook(app, {
+  source: 'data-sync.pull',
+  path: '/api/data-sync/webhook',
+  // Reuse the verified-correct crypto below verbatim — signature-only; activation/enablement gating
+  // lives on the pull handler, not here.
+  verify: (req) => {
+    const secret = process.env.DATA_SYNC_WEBHOOK_SECRET;
+    if (!secret) return true; // secret unset → open (current live behavior)
+    // Accept EITHER a valid GitHub HMAC signature OR the legacy plain header (backward-compat).
+    const plain = req.headers['x-webhook-secret'];
+    return validGithubSignature(req, secret) || (typeof plain === 'string' && safeStrEqual(plain, secret));
+  },
+});
+
+// Consume the verified webhook's event → pull. The PULL is gated on active (non-passive) via the live
+// `activated`/`PASSIVE` closure: a passive/standby twin shares DATA_DIR and must NOT mutate data/
+// (single-active-writer), and before promotion there's nothing to pull into serving. `activated` flips
+// true in activateConsumers(), so a promoted instance starts pulling with no extra wiring. pull() also
+// self-no-ops when data-sync is disabled.
+subscribeEvent('data-sync.pull', () => {
+  if (PASSIVE || !activated) return;
+  dataSync.pull().catch((err) => console.error('[data-sync] webhook pull failed:', (err as Error).message));
 });
 
 async function runStream(ws: WebSocket, session: WsSession, sid: string, promptText: string, attachments: AttachmentMeta[] | undefined, mcpServers: McpConfig, isSteerRestart = false, conversationReset = false, turnHints?: Record<string, unknown>) {
@@ -1204,6 +1270,10 @@ async function runStream(ws: WebSocket, session: WsSession, sid: string, promptT
           console.log(`[ws] Suppressing error during steer for ${sid.slice(0, 8)}`);
         } else {
           console.error(`[ws] Error event for ${session.email}: ${event.message}`);
+          // Persist alongside whatever partial output the turn produced — flushAssistant() saves it.
+          if (thinkingText) { assistantBlocks.push({ type: 'thinking', text: thinkingText }); thinkingText = ''; }
+          if (assistantText) { assistantBlocks.push({ type: 'text', text: assistantText }); assistantText = ''; }
+          assistantBlocks.push({ type: 'error', text: event.message });
           send(ws, { type: 'error', message: event.message, sessionId: sid });
         }
         break;
@@ -1218,8 +1288,14 @@ async function runStream(ws: WebSocket, session: WsSession, sid: string, promptT
       console.log(`[ws] Stream aborted for steer in ${sid.slice(0, 8)}`);
     } else {
       stopReason = 'error';
-      console.error(`[ws] Stream error for ${session.email}:`, err.message || err);
-      send(ws, { type: 'error', message: err.message || String(err), sessionId: sid });
+      const msg = err.message || String(err);
+      console.error(`[ws] Stream error for ${session.email}:`, msg);
+      // Flush partial output first — flushAssistant() appends it in the finally, which would
+      // otherwise order the failure ahead of the text it followed.
+      if (thinkingText) { assistantBlocks.push({ type: 'thinking', text: thinkingText }); thinkingText = ''; }
+      if (assistantText) { assistantBlocks.push({ type: 'text', text: assistantText }); assistantText = ''; }
+      assistantBlocks.push({ type: 'error', text: msg });
+      send(ws, { type: 'error', message: msg, sessionId: sid });
     }
   } finally {
     clearInterval(partialInterval);
@@ -1561,7 +1637,8 @@ async function retryWebSession(session: SessionMeta, prompt: string) {
       } else if (ev.type === 'done') {
         break;
       } else if (ev.type === 'error') {
-        assistantText += `\n⚠️ ${ev.message}`;
+        if (assistantText) { assistantBlocks.push({ type: 'text', text: assistantText }); assistantText = ''; }
+        assistantBlocks.push({ type: 'error', text: ev.message });
         break;
       }
     }
@@ -1569,7 +1646,9 @@ async function retryWebSession(session: SessionMeta, prompt: string) {
     if (assistantBlocks.length) {
       appendMessage(sid, { id: crypto.randomUUID(), role: 'assistant', blocks: assistantBlocks });
       broadcast({ type: 'session_messages_changed', sessionId: sid });
-      const preview = assistantText.slice(0, 120) || '(completed)';
+      const errBlock = assistantBlocks.find((b) => b.type === 'error');
+      const preview = assistantText.slice(0, 120)
+        || (errBlock?.type === 'error' ? `⚠️ ${errBlock.text}`.slice(0, 120) : '(completed)');
       notifyUnread(session.uid, sid, preview, 'response', session.title);
     }
   } catch (err: any) {

package/src/server/claude.ts

@@ -52,6 +52,16 @@ export function getAgentConfig(): AgentConfig {
   return config;
 }
 
+/**
+ * Which credentials the claude-code SDK will resolve — process-global, derived from env at call time
+ * (an API-key env var wins over a stored claude.ai login, matching the SDK's own precedence). Surfaced
+ * to the UI so the header shows subscription-vs-API-key immediately, without waiting for a turn. The
+ * per-turn ground truth (SDK `apiKeySource`) is logged by the engine.
+ */
+export function getClaudeAuthSource(): 'subscription' | 'api-key' {
+  return process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN ? 'api-key' : 'subscription';
+}
+
 export function saveAgentConfig(config: AgentConfig): void {
   mkdirSync(DATA_DIR, { recursive: true });
   writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
@@ -382,7 +392,8 @@ export async function consumeStream(stream: AsyncGenerator<WsEvent>, onEvent?: (
     } else if (ev.type === 'done') {
       break;
     } else if (ev.type === 'error') {
-      text += `\n⚠️ ${ev.message}`;
+      if (text) { blocks.push({ type: 'text', text }); text = ''; }
+      blocks.push({ type: 'error', text: ev.message });
       break;
     }
   }

package/src/server/data-sync.ts

@@ -24,6 +24,8 @@ export class DataSync {
   private pending = new Set<string>();
   private timer: ReturnType<typeof setTimeout> | null = null;
   private pushing = false;
+  private pulling = false;
+  private pullPending = false;
   private ready = false;
   private warnedDisabled = false;
 
@@ -181,6 +183,32 @@ export class DataSync {
   }
 
   async pull(): Promise<void> {
+    // Coalesce overlapping triggers WITHOUT dropping any. Serializing pulls is required — concurrent
+    // stash/merge/pop on shared uncommitted state would corrupt the worktree. But a trigger that
+    // arrives mid-pull (webhook B fires while pull A is already past its `git fetch`) references a
+    // commit A will NOT see, so silently skipping B leaves a pure-consumer permanently stale (no
+    // periodic poller catches up). Instead, mark work pending and guarantee exactly one follow-up
+    // pass after the current one — mirrors the push-side pending/re-run pattern (flush()).
+    if (this.pulling) {
+      this.pullPending = true;
+      console.log(`${TAG} Pull in progress — queued a follow-up (coalesced)`);
+      return;
+    }
+    this.pulling = true;
+    try {
+      do {
+        // Clear BEFORE the pass: a trigger during this _pull() re-sets it → one more loop.
+        this.pullPending = false;
+        await this._pull();
+      } while (this.pullPending);
+    } finally {
+      // Reset both so a throw mid-pass can never wedge the lock or a stale pending flag.
+      this.pulling = false;
+      this.pullPending = false;
+    }
+  }
+
+  private async _pull(): Promise<void> {
     if (!this.isEnabled()) return;
     try {
       await this.git('fetch', 'origin', this.options.branch);

package/src/server/engine/claude-code.ts

@@ -13,8 +13,7 @@ import { resolveModelSwitch } from '../model-aliases.ts';
 import type { WsEvent, AskQuestion, QuestionAnswers, QuestionHandler } from '../claude.ts';
 import type { AgentEngine, EngineStreamOpts, EngineModel } from './types.ts';
 import { getPromptSuffix } from '../prompt-suffix.ts';
-
-const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..', '..');
+import { APP_ROOT } from '../paths.ts';
 const IMMUTABLE_SYSTEM_PROMPT = readFileSync(path.resolve(import.meta.dirname, '../../../defaults/system-prompt.md'), 'utf-8');
 const DEFAULT_USER_PROMPT = `You are a helpful assistant with access to MCP tools.`;
 const DEFAULT_ALLOWED_TOOLS = ['Read', 'Edit', 'Bash', 'WebSearch', 'Glob', 'LS', 'ToolSearch'];
@@ -175,7 +174,7 @@ export class ClaudeCodeEngine implements AgentEngine {
 
   async *stream(opts: EngineStreamOpts): AsyncGenerator<WsEvent> {
     const { config, directives } = opts;
-    const cwd = PROJECT_ROOT;
+    const cwd = APP_ROOT;
 
     const fullPrompt = buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt);
     const permMode = opts.onPermissionRequest ? 'default' : (config.permissionMode ?? 'acceptEdits');
@@ -334,6 +333,14 @@ export class ClaudeCodeEngine implements AgentEngine {
         }
 
         if (m.type === 'system' && m.subtype === 'init') {
+          // Which credentials the SDK actually resolved (env key vs claude.ai login) — a process-global
+          // fact surfaced per-run so logs (incl. headless/scheduler) answer "subscription or API key?".
+          // Runtime `apiKeySource` is the RESOLVED source string (verified against the SDK, not its .d.ts
+          // enum): a named env var ("ANTHROPIC_API_KEY") ⇒ API key; "none"/"oauth" ⇒ stored login ⇒ sub.
+          const src = m.apiKeySource as string | undefined;
+          const authSource: 'subscription' | 'api-key' | undefined =
+            src == null ? undefined : src === 'none' || src === 'oauth' ? 'subscription' : 'api-key';
+          if (authSource) console.log(`[claude] Auth: ${authSource} (apiKeySource=${src})`);
           if (m.model) {
             console.log(`[claude] Init model=${m.model}${m.model !== options['model'] ? ` (requested ${options['model']})` : ''}`);
             // If the user explicitly asked to switch models via a [directive], announce the change

package/src/server/events/types.ts

@@ -24,6 +24,9 @@ export interface ShragaEventMap {
     name?: string;
     status?: string;
     sessionId?: string;
+    /** Absolute link to the run's session. Present only when a public origin is configured
+     *  (see getSessionUrl) — a scheduled run has no request to derive one from. */
+    sessionUrl?: string;
     error?: string;
   };
 }

package/src/server/mcp-sidecar.ts

@@ -1,8 +1,8 @@
 import { spawn, type ChildProcess } from 'node:child_process';
 import path from 'node:path';
 import { getHttpSidecarSpecs, type HttpSidecarSpec } from './shraga-config.ts';
+import { APP_ROOT } from './paths.ts';
 
-const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..');
 const sidecars = new Map<string, { proc: ChildProcess; spec: HttpSidecarSpec }>();
 
 async function isPortAlive(url: string): Promise<boolean> {
@@ -17,7 +17,7 @@ async function isPortAlive(url: string): Promise<boolean> {
 let shuttingDown = false;
 
 function startOne(spec: HttpSidecarSpec, restarts = 0) {
-  const vendorDir = path.join(PROJECT_ROOT, 'vendor', spec.dir);
+  const vendorDir = path.join(APP_ROOT, 'vendor', spec.dir);
   const entrypoint = path.join(vendorDir, 'src/mcp/cli.ts');
   const args = ['run', entrypoint, '--port', String(spec.port)];
   const startedAt = Date.now();

package/src/server/mcp.ts

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { dataPath } from './paths.ts';
+import { dataPath, APP_ROOT } from './paths.ts';
 import { dataSync } from './data-sync.ts';
 import { getGlobalMcpsFromConfig } from './shraga-config.ts';
 
@@ -151,8 +151,6 @@ function withStdioType(config: McpConfig): McpConfig {
   return out;
 }
 
-const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..');
-
 /** Canonical path baked into MCP env when prod has the file deployed (cwd = app dir). */
 const GOOGLE_SA_DEPLOY_REL = './secrets/google-service-account.json';
 
@@ -163,7 +161,7 @@ const GOOGLE_SA_DEPLOY_REL = './secrets/google-service-account.json';
  */
 function finalizeGoogleServiceAccountCredentials(config: McpConfig): McpConfig {
   const jsonFromEnv = process.env.GOOGLE_SERVICE_ACCOUNT_JSON?.trim();
-  const defaultAbs = path.join(PROJECT_ROOT, 'secrets/google-service-account.json');
+  const defaultAbs = path.join(APP_ROOT, 'secrets/google-service-account.json');
   const defaultExists = existsSync(defaultAbs);
 
   let result = { ...config };
@@ -184,7 +182,7 @@ function finalizeGoogleServiceAccountCredentials(config: McpConfig): McpConfig {
     const pathOk =
       raw &&
       !raw.includes('${') &&
-      existsSync(path.isAbsolute(raw) ? raw : path.resolve(PROJECT_ROOT, raw.replace(/^\.\//, '')));
+      existsSync(path.isAbsolute(raw) ? raw : path.resolve(APP_ROOT, raw.replace(/^\.\//, '')));
 
     if (pathOk) continue;
     if (!defaultExists) continue;

package/src/server/modules/index.ts

@@ -0,0 +1,3 @@
+export * from './types.ts';
+export { loadState, getInstalled, readManifest, listAvailableModules, renderTemplate, renderDeep, effectiveConfig, reconcileInstalledModules, installModule, enableModule, disableModule, setModuleConfig, uninstallModule } from './service.ts';
+export { registerModuleRoutes } from './routes.ts';

package/src/server/modules/routes.ts

@@ -0,0 +1,78 @@
+/** REST surface for data-plane modules. Reads: any authed user. Mutations: owner-gated
+ *  (modules are system-scope, like schedule edits on records you don't own). */
+import type { Express, RequestHandler, Request, Response } from 'express';
+import { loadState, listAvailableModules, installModule, enableModule, disableModule, setModuleConfig, uninstallModule, readManifest, readModuleReadme } from './service.ts';
+import { dataPath } from '../paths.ts';
+
+function ownerOnly(req: Request, res: Response): boolean {
+  const user = (req as any).user;
+  if (user?.isOwner) return true;
+  res.status(403).json({ error: 'Only an owner can manage modules' });
+  return false;
+}
+
+export function registerModuleRoutes(app: Express, requireAuth: RequestHandler): void {
+  app.get('/api/modules', requireAuth, (_req, res) => {
+    const installed = loadState().installed.map((rec) => {
+      let manifest = null;
+      try { manifest = readManifest(dataPath('modules', rec.name)); } catch { /* folder missing */ }
+      return {
+        ...rec,
+        manifest,
+        description: manifest?.description,
+        configSchema: manifest?.configSchema,
+        readme: readModuleReadme(rec.name, 'installed'),
+        skillCount: manifest?.skills?.length ?? 0,
+        scheduleCount: manifest?.schedules?.length ?? 0,
+      };
+    });
+    const installedNames = new Set(installed.map((m) => m.name));
+    const available = listAvailableModules()
+      .filter((m) => !installedNames.has(m.name))
+      .map((m) => ({ ...m, readme: readModuleReadme(m.name, 'builtin') }));
+    res.json({ installed, available });
+  });
+
+  app.post('/api/modules/install', requireAuth, (req, res) => {
+    if (!ownerOnly(req, res)) return;
+    const { name, path: folder } = req.body ?? {};
+    try {
+      const rec = installModule({ name: typeof name === 'string' ? name : undefined, path: typeof folder === 'string' ? folder : undefined });
+      res.json(rec);
+    } catch (err) {
+      res.status(400).json({ error: (err as Error).message });
+    }
+  });
+
+  app.post('/api/modules/:name/enable', requireAuth, (req, res) => {
+    if (!ownerOnly(req, res)) return;
+    try { res.json(enableModule(String(req.params.name))); }
+    catch (err) { res.status(404).json({ error: (err as Error).message }); }
+  });
+
+  app.post('/api/modules/:name/disable', requireAuth, (req, res) => {
+    if (!ownerOnly(req, res)) return;
+    try { res.json(disableModule(String(req.params.name))); }
+    catch (err) { res.status(404).json({ error: (err as Error).message }); }
+  });
+
+  app.put('/api/modules/:name/config', requireAuth, (req, res) => {
+    if (!ownerOnly(req, res)) return;
+    const { config } = req.body ?? {};
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+      res.status(400).json({ error: 'Body must be {"config": {...}}' });
+      return;
+    }
+    try { res.json(setModuleConfig(String(req.params.name), config)); }
+    catch (err) {
+      const msg = (err as Error).message;
+      res.status(msg.includes('not installed') ? 404 : 400).json({ error: msg });
+    }
+  });
+
+  app.delete('/api/modules/:name', requireAuth, (req, res) => {
+    if (!ownerOnly(req, res)) return;
+    try { uninstallModule(String(req.params.name)); res.json({ ok: true }); }
+    catch (err) { res.status(404).json({ error: (err as Error).message }); }
+  });
+}