shraga 0.1.12 → 0.1.14

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

@@ -12,8 +12,8 @@ import { DEFAULT_MODEL } from '../directives.ts';
 import { resolveModelSwitch } from '../model-aliases.ts';
 import type { WsEvent, AskQuestion, QuestionAnswers, QuestionHandler } from '../claude.ts';
 import type { AgentEngine, EngineStreamOpts, EngineModel } from './types.ts';
-
-const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..', '..');
+import { getPromptSuffix } from '../prompt-suffix.ts';
+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'];
@@ -174,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');
@@ -265,8 +265,10 @@ export class ClaudeCodeEngine implements AgentEngine {
     if (effort) options['effort'] = effort;
 
     const userPrompt = config.systemPrompt || DEFAULT_USER_PROMPT;
-    const voiceSuffix = ""; // voice mode is an optional add-on; not present in this build
-    options['systemPrompt'] = `${IMMUTABLE_SYSTEM_PROMPT}\n\n${userPrompt}${voiceSuffix}`;
+    // Optional add-ons may append a system-prompt suffix decided off the opaque turn hints (add-on-owned
+    // text). With nothing registered (CE's own state) this is '' and the prompt is byte-identical to before.
+    const addonSuffix = getPromptSuffix(opts.turnHints);
+    options['systemPrompt'] = `${IMMUTABLE_SYSTEM_PROMPT}\n\n${userPrompt}${addonSuffix ? `\n\n${addonSuffix}` : ''}`;
     if (opts.abortController) options['abortController'] = opts.abortController;
     if (opts.mcpServers && Object.keys(opts.mcpServers).length > 0) options['mcpServers'] = opts.mcpServers;
 

package/src/server/engine/types.ts

@@ -23,7 +23,9 @@ export interface EngineStreamOpts {
   onPermissionRequest?: PermissionHandler;
   onDestructiveApproval?: PermissionHandler;
   onUserQuestion?: QuestionHandler;
-  voiceMode?: boolean;
+  /** Opaque per-send hints bag, forwarded verbatim from the client. The core interprets no key of it;
+   *  an add-on engine reads its own keys (e.g. a duplex engine's `voice` marker). */
+  turnHints?: Record<string, unknown>;
   /** True when the conversation was truncated (user replayed/edited a message) — engines with cached state should reset. */
   conversationReset?: boolean;
   context?: Record<string, string>;

package/src/server/ingress-router.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+// Ingress router: tiny host-header TCP router fronting shraga instances.
+// The deployment's ingress (CF Tunnel or Caddy) always points here; this process
+// routes by Host header to local ports. Previews and blue-green flips are just edits
+// to the routing file — this process never restarts during a flip (that's why it runs
+// as its own process, NOT inside the server: `flip-restart` restarts the server while
+// the router holds traffic).
+//
+//   bun run src/server/ingress-router.ts          # INGRESS_PORT (default 3100)
+//   shraga ingress                                # same, via the CLI
+//
+// Routing file (dataPath('ingress-router.json'), hot-reloaded on change):
+//   { "default": 3032, "routes": { "pr-13.preview.agent.example.com": 3850 } }
+//
+// Works at the TCP level: reads bytes until the first request's headers end, parses Host,
+// connects upstream, replays the buffered bytes, then splices both directions blindly.
+// WebSocket upgrades and keep-alive flow through untouched (same upstream per connection).
+
+import net from 'node:net';
+import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
+import { dataPath } from './paths.ts';
+
+const PORT = Number(process.env.INGRESS_PORT) || 3100;
+const CONFIG = dataPath('ingress-router.json');
+const HEADER_LIMIT = 16 * 1024;
+
+interface Routing { default: number; routes: Record<string, number>; }
+let routing: Routing = { default: 3032, routes: {} };
+
+function loadRouting() {
+  try {
+    routing = { routes: {}, ...JSON.parse(readFileSync(CONFIG, 'utf-8')) };
+    console.log(`[ingress] routing: default→:${routing.default}, ${Object.keys(routing.routes).length} route(s)`);
+  } catch (err) {
+    console.error(`[ingress] bad routing file, keeping previous:`, (err as Error).message);
+  }
+}
+if (!existsSync(CONFIG)) writeFileSync(CONFIG, JSON.stringify(routing, null, 2));
+loadRouting();
+let reloadTimer: ReturnType<typeof setTimeout> | null = null;
+watch(CONFIG, () => { // debounce — editors fire multiple events per save
+  if (reloadTimer) clearTimeout(reloadTimer);
+  reloadTimer = setTimeout(loadRouting, 100);
+});
+
+function upstreamFor(host: string): number {
+  const bare = host.toLowerCase().split(':')[0];
+  return routing.routes[bare] ?? routing.default;
+}
+
+const server = net.createServer((client) => {
+  let buf = Buffer.alloc(0);
+  client.once('error', () => client.destroy());
+
+  const onData = (chunk: Buffer) => {
+    buf = Buffer.concat([buf, chunk]);
+    const headerEnd = buf.indexOf('\r\n\r\n');
+    if (headerEnd === -1) {
+      if (buf.length > HEADER_LIMIT) client.destroy();
+      return;
+    }
+    client.off('data', onData);
+    client.pause();
+
+    const head = buf.subarray(0, headerEnd).toString('latin1');
+    const host = /\r\nhost:\s*([^\r\n]+)/i.exec('\r\n' + head)?.[1]?.trim() ?? '';
+    const port = upstreamFor(host);
+
+    const upstream = net.connect(port, '127.0.0.1', () => {
+      client.setTimeout(0); // routed — long-lived (WS) connections idle freely
+      upstream.write(buf);
+      client.pipe(upstream);
+      upstream.pipe(client);
+      client.resume();
+    });
+    const drop = () => { client.destroy(); upstream.destroy(); };
+    upstream.on('error', (err) => {
+      console.warn(`[ingress] upstream :${port} (${host}):`, err.message);
+      if (!client.writableEnded) client.end('HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\nconnection: close\r\n\r\n');
+      upstream.destroy();
+    });
+    client.on('error', drop);
+    client.on('close', () => upstream.destroy());
+    upstream.on('close', () => client.destroy());
+  };
+  client.on('data', onData);
+  client.setTimeout(15_000, () => { if (!client.bytesWritten) client.destroy(); });
+});
+
+server.listen(PORT, () => console.log(`[ingress] listening on :${PORT}, routing file: ${CONFIG}`));

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/paths.ts

@@ -2,7 +2,11 @@ import path from 'node:path';
 import { readdirSync } from 'node:fs';
 
 function resolveDataDir(): string {
-  if (process.env.DATA_DIR) return process.env.DATA_DIR;
+  // Absolutize against cwd: run.sh sets a RELATIVE `DATA_DIR=data-<env>`, and a relative path breaks
+  // any consumer that isn't cwd-relative — notably the dynamic `import(configPath)` in
+  // shraga-config.ts, which resolves a relative specifier against the IMPORTING MODULE
+  // (`node_modules/shraga/src/server/`), not the process cwd.
+  if (process.env.DATA_DIR) return path.resolve(process.env.DATA_DIR);
   const root = process.cwd();
   const hasNamed = readdirSync(root).some(f => f.startsWith('data-'));
   if (hasNamed) {
@@ -17,8 +21,55 @@ function resolveDataDir(): string {
 export const DATA_DIR = resolveDataDir();
 export const dataPath = (...segments: string[]) => path.join(DATA_DIR, ...segments);
 
-// The Shraga app root (where `defaults/` lives and the agent's project filesystem is rooted).
-// Derived from THIS module's stable location — `src/server/paths.ts` → repo root is two dirs up — so
-// it's correct even for code loaded from an overlay checkout in a different directory (where
-// `import.meta.dirname`-relative math would resolve to the overlay, not the app).
-export const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..');
+// ── Two distinct roots. Conflating them is what broke npm-consumer deployments. ──────────────────
+//
+// PACKAGE_ROOT — where the SHRAGA PACKAGE's own shipped assets live (`defaults/`, `dist/client/`,
+// `package.json` — everything in package.json `files`). Package-relative is CORRECT here: in an npm
+// consumer these really do live under `node_modules/shraga/`. Do not "fix" this to APP_ROOT.
+export const PACKAGE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+
+/**
+ * APP_ROOT — the DEPLOYMENT/consumer root: where `vendor/`, `secrets/` and `data/` live, and where
+ * the agent's project filesystem is rooted. NOT shipped in the package.
+ *
+ * In a source checkout this equals PACKAGE_ROOT. In an npm consumer (`shraga-circles`, `shraga-ee`)
+ * it is the CONSUMER root, while PACKAGE_ROOT is `<consumer>/node_modules/shraga` — resolving vendor
+ * from PACKAGE_ROOT is what silently killed ~21/25 MCPs in prod.
+ *
+ * Signal, in precedence order:
+ *  1. SHRAGA_APP_ROOT env — explicit escape hatch for any layout the heuristics get wrong.
+ *  2. node_modules ancestor — if this file sits under `.../node_modules/shraga/...`, the app root is
+ *     the directory CONTAINING that `node_modules`. Independent of cwd, so it survives a server
+ *     started from anywhere (systemd, a cron shell, `bun --cwd`).
+ *  3. process.cwd() — the source-checkout case, and already this module's established app-root signal
+ *     (see resolveDataDir above; run.sh `cd`s to the app root before launching).
+ *
+ * Failure modes, explicit:
+ *  - Hoisted/pnpm layouts where `shraga` resolves to a store dir outside the consumer's own
+ *    node_modules: rule 2 picks the hoisting root, which may not be the dir holding `vendor/`.
+ *  - A nested `node_modules/x/node_modules/shraga`: rule 2 stops at the INNERMOST node_modules.
+ *  Both are exactly why rule 1 exists — set SHRAGA_APP_ROOT and the heuristics are bypassed.
+ */
+function resolveAppRoot(): string {
+  const explicit = process.env.SHRAGA_APP_ROOT?.trim();
+  if (explicit) return path.resolve(explicit);
+
+  const marker = `${path.sep}node_modules${path.sep}`;
+  const idx = PACKAGE_ROOT.lastIndexOf(marker);
+  if (idx !== -1) return PACKAGE_ROOT.slice(0, idx);
+
+  return process.cwd();
+}
+
+export const APP_ROOT = resolveAppRoot();
+
+/**
+ * @deprecated Ambiguous name — use APP_ROOT (vendor/secrets/data, agent cwd) or PACKAGE_ROOT
+ * (shipped assets) explicitly.
+ *
+ * Aliased to APP_ROOT, not PACKAGE_ROOT, deliberately: every remaining external consumer of this
+ * export (shraga-ee `engine/cursor.ts`, `engine/agentx.ts`) uses it as the agent's project root —
+ * i.e. they meant APP_ROOT and were hitting the same npm-layout bug. Pointing the alias here fixes
+ * them without an EE change. Nothing in this package reads shipped assets through it.
+ */
+export const PROJECT_ROOT = APP_ROOT;

package/src/server/prompt-suffix.ts

@@ -0,0 +1,38 @@
+// System-prompt-suffix seam — a generic drop-in for optional add-ons to append text to the agent's
+// system prompt, decided per-turn off the opaque hints bag.
+//
+// Every turn, each engine appends whatever the registered contributors return. A contributor reads its
+// OWN keys off the opaque `turnHints` bag (the core interprets none) and returns a suffix — or '' to
+// contribute nothing. The core owns only this seam: it names no add-on concept (voice, etc.). With no
+// contributor registered (CE's own state) the suffix is '' and the assembled prompt is byte-identical
+// to before. An add-on (e.g. shraga-ee's voice feature) registers a contributor that returns its own
+// bundled suffix when its marker (e.g. `turnHints.voice`) is present.
+//
+// Sibling of `turn-context.ts` and shaped like it: typed, optional, registered before startup, a no-op
+// when nothing registers.
+
+/** Return a system-prompt suffix for this turn (trimmed by the seam), or '' to contribute nothing.
+ *  Reads its own keys off the opaque per-turn hints bag. */
+export type PromptSuffixContributor = (turnHints?: Record<string, unknown>) => string;
+
+const contributors: PromptSuffixContributor[] = [];
+
+/** Register a prompt-suffix contributor. Called by an optional add-on before startup. */
+export function registerPromptSuffix(fn: PromptSuffixContributor): void {
+  contributors.push(fn);
+}
+
+/** The combined suffix for this turn, or '' when nothing contributes. A throwing contributor is
+ *  contained (logged, skipped) so a broken add-on can't take down a turn. */
+export function getPromptSuffix(turnHints?: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const fn of contributors) {
+    try {
+      const s = fn(turnHints)?.trim();
+      if (s) parts.push(s);
+    } catch (err) {
+      console.error('[prompt-suffix] contributor failed:', (err as Error)?.message ?? err);
+    }
+  }
+  return parts.join('\n\n');
+}

package/src/server/sessions.ts

@@ -356,6 +356,8 @@ export type ConvBlock =
   | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown }
   | { type: 'tool_result'; toolUseId: string; output: string }
   | { type: 'thinking'; text: string }
+  // Persisted block written by an add-on engine's background worker (e.g. EE's duplex voice brain).
+  // The core stores/renders it but owns none of its semantics; name kept for stored-history back-compat.
   | { type: 'duplex_result'; label?: string; tier?: string; text?: string }
   | { type: 'summary'; text: string; compactedCount: number }
   | { type: 'compact_marker'; summary: string; compactedCount: number };

package/src/server/shraga-config.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { DATA_DIR } from './paths.ts';
+import { DATA_DIR, APP_ROOT } from './paths.ts';
 import type { McpServerConfig, McpConfig, McpHttpServerConfig } from './mcp.ts';
 
 /** Shorthand for vendor-dir MCPs (auto-resolves command/args from vendor/{name}) */
@@ -70,8 +70,6 @@ export function defineConfig(config: ShragaConfig): ShragaConfig {
   return config;
 }
 
-const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..');
-
 /**
  * Config filenames, in precedence order. `shraga.config.ts` is canonical; `unclaw.config.ts` is
  * the legacy name kept for back-compat — existing deployments have that file in their data dir,
@@ -131,7 +129,7 @@ export function getGlobalMcpsFromConfig(): McpConfig {
       result[name] = { type: 'stdio', ...full } satisfies McpServerConfig;
     } else {
       const shorthand = entry as McpShorthandEntry;
-      const vendorDir = path.join(PROJECT_ROOT, 'vendor', shorthand.dir ?? name);
+      const vendorDir = path.join(APP_ROOT, 'vendor', shorthand.dir ?? name);
       const command = shorthand.command ?? 'bun';
       const args = shorthand.args ?? ['run', path.join(vendorDir, 'src/mcp/cli.ts'), '--stdio'];
       const env: Record<string, string> = {};

package/src/server/skills.ts

@@ -1,13 +1,11 @@
 import { mkdirSync, readdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, renameSync } from 'node:fs';
 import path from 'node:path';
-import { DATA_DIR, dataPath } from './paths.ts';
+import { DATA_DIR, dataPath, APP_ROOT } from './paths.ts';
 import { getBuiltinSkillNames } from './seed.ts';
 import { dataSync } from './data-sync.ts';
 import { injectFile } from './file-inject.ts';
 import { getGlobalMcpConfig } from './mcp.ts';
 
-const PROJECT_ROOT = path.resolve(import.meta.dirname, '..', '..');
-
 const SKILLS_DIR = dataPath('skills');
 const DEFAULTS_PATH = dataPath('skills-defaults.json');
 
@@ -108,7 +106,7 @@ function formatMcpCommandBlock(mcpName: string, skillBody: string, args: string)
  * Markdown from `vendor/<serverName>/.claude/skills/<serverName>/SKILL.md` — same file the MCP exposes as skill://serverName/workflow.
  */
 export function resolveMcpBundledSkillContent(serverName: string): string | null {
-  const file = path.join(PROJECT_ROOT, 'vendor', serverName, '.claude/skills', serverName, 'SKILL.md');
+  const file = path.join(APP_ROOT, 'vendor', serverName, '.claude/skills', serverName, 'SKILL.md');
   if (!existsSync(file)) return null;
   return readFileSync(file, 'utf-8');
 }
@@ -128,7 +126,7 @@ export function resolvedSkillInjectionBlock(name: string): string | null {
 }
 
 function mcpSkillFilePath(serverName: string): string {
-  return path.join(PROJECT_ROOT, 'vendor', serverName, '.claude/skills', serverName, 'SKILL.md');
+  return path.join(APP_ROOT, 'vendor', serverName, '.claude/skills', serverName, 'SKILL.md');
 }
 
 /**