shraga 0.1.2 → 0.1.4

package/README.md

@@ -24,7 +24,8 @@ Give it its own machine, its own keys, its own identity. Onboard it once, then d
 - ⭐ **Multi-user by design.** One Shraga serves a whole team, each with their own sessions,
   tools, and permissions.
 - ⭐ **A shared brain that compounds.** It onboards, learns your codebase and conventions, and
-  carries that knowledge forward across sessions and teammates.
+  carries that knowledge forward via skills and sessions. The full org-wide capture is the
+  north star ([the shared brain](./docs/shared-brain.md)) — it opens in stages.
 - **Chat with an agent** that has your workspace, shell, and tools.
 - **Sessions** you can fork, resume, and revisit.
 - **Skills**: reusable procedures you teach it once (files in `data/skills/`).
@@ -32,10 +33,71 @@ Give it its own machine, its own keys, its own identity. Onboard it once, then d
 - **Schedules**: run agent jobs on a cron or in response to events.
 - **Programmatic API + MCP endpoint**: drive the agent from scripts or from claude.ai.
 
+## What's in the box
+
+Shraga ships as a small core (this repo, the `shraga` npm package — "CE") plus two ways to grow it.
+Capabilities fall into three tiers:
+
+- **Built-in** — ships and runs in CE. Nothing to install; some need credentials configured.
+- **Optional overlay** — an external add-on module loaded at startup via `SHRAGA_OVERLAY`. Not in
+  this repo; you bring or build it.
+- **Bring-your-own** — you extend the core yourself through its seams (MCP, engine, skills, features).
+
+### Built-in (ships in CE)
+
+| Capability | What you get | Setup |
+|-----------|--------------|-------|
+| **Agent chat & sessions** | Chat with an agent that has your workspace, shell, and tools; fork, resume, and revisit sessions. | none |
+| **Slack** | The agent is **active on Slack** — it replies in threads, manages reactions, handles uploaded files, resolves `@mentions`, and runs polls. Via the public [`mcp-slack-use`](https://github.com/Livshitz/mcp-slack-use) package. | Slack app + tokens |
+| **Scheduler** | Cron schedules and event-triggered tasks that run agent jobs unattended. | none |
+| **Events** | Generic event-bus ingress (`POST /api/events/:source`) that fires matching schedules. | none |
+| **Push notifications** | Web and native push. | none |
+| **Artifacts** | Render HTML artifacts from a session. (PNG export is overlay-only — see below.) | none |
+| **MCP — both directions** | *Consume* external MCP servers to give the agent tools, **and** *expose* Shraga itself as an MCP endpoint (`POST /mcp`) so claude.ai and other clients can drive it. | per-server config |
+| **Engine seam** | Pluggable agent runtime. Claude Code is the built-in engine. | none |
+| **Auth** | Local username/password by default; Firebase optional (`AUTH_PROVIDER=firebase`). | none / Firebase config |
+| **CLI** | `shraga` server bin plus `shraga user add <email> <password>` to seed a local user. | none |
+
+### Optional overlay (add-on module, not in CE)
+
+Loaded only when you point `SHRAGA_OVERLAY` at an external module. **None of these ship in this
+repo** — a bare self-host does not get them out of the box:
+
+| Capability | Notes |
+|-----------|-------|
+| **Email / Gmail** | Inbound email → agent sessions. **Not built-in** — overlay only. |
+| **GitHub bot** | Issues/PRs → agent sessions with GH-native trust tiers. |
+| **Voice** | Voice input/output. |
+| **Fleet / multi-instance** | Blue-green and multi-instance orchestration. |
+| **PNG artifact export** | Puppeteer-rendered PNGs of artifacts. |
+
+### Bring-your-own (extend it yourself)
+
+The core is deliberately small and grows through documented seams (see
+[`AGENTS.md`](./AGENTS.md#the-extension-seams)):
+
+| Seam | Use it for |
+|------|-----------|
+| **MCP servers** | Give the agent new tools, per-user or globally. |
+| **Skills** (`data/skills/`) | Reusable procedures you teach the agent once. |
+| **Engines** (`src/server/engine/`) | Swap or add agent runtimes behind the engine seam. |
+| **Server features** (`src/server/features.ts`) | Mount new server-side surfaces via `registerFeature`. |
+| **Client slots** (`src/client/lib/slots.tsx`) | Inject UI into typed render slots without touching core. |
+| **Route extensions** (`data/extensions/*.ext.ts`) | Drop-in public routes (webhooks, OAuth callbacks) per deployment. |
+| **`SHRAGA_OVERLAY`** | Load a whole external add-on module at startup (the overlay tier above). |
+
 ## Quickstart
 
 Requires [Bun](https://bun.sh) ≥ 1.0.
 
+**Fastest — run from npm:**
+
+```bash
+bunx shraga                   # serve on http://localhost:3032, state in ./data/
+```
+
+**From source (to develop or customize):**
+
 ```bash
 # 1. Install & configure
 bun install

package/defaults/agents/trace-extractor.md

@@ -67,7 +67,7 @@ summary: |
 tools_used:
   - stripe.get_disputes
   - stripe.get_charges_by_id
-  - mcp-slack.post_slack_message
+  - mcp-slack-use.post_slack_message
 tool_call_count: 15
 tool_failures:
   - tool: stripe.get_disputes

package/defaults/extensions/stripe-webhook.ext.ts

@@ -1,9 +1,13 @@
-// Example: a vendor webhook → event-trigger bridge.
+// Example: a vendor webhook → event-trigger bridge, via the generic helper.
 //
 // A vendor (Stripe here) can't send shraga auth, so its webhook can't hit the
-// generic POST /api/events/:source endpoint. Instead this extension exposes a
-// PUBLIC route, verifies the vendor's OWN signature, then calls ctx.emitEvent() —
-// which fires any enabled schedule with trigger { kind:'event', source:'stripe' }.
+// generic POST /api/events/:source endpoint. Instead this extension declares a
+// webhook as DATA: ctx.registerWebhook({ source, verify }) mounts a PUBLIC route
+// that verifies the vendor's OWN signature and, on success, emits the event —
+// firing any enabled schedule with trigger { kind:'event', source:'stripe' }.
+//
+// The ONLY per-vendor code is `verify`. Dispatch, dedup (by event id), the route,
+// and typing are all generic (src/server/events/webhook.ts).
 //
 // Pair it with a schedule (see the scheduler skill):
 //   { "trigger": { "kind":"event", "source":"stripe", "match":{ "type":"invoice.paid" } },
@@ -11,15 +15,24 @@
 //
 // DORMANT until STRIPE_WEBHOOK_SECRET is set — no route is registered without it,
 // so this ships harmlessly enabled. Swap the verifier for any vendor's scheme.
-import type { Express, Request, Response } from 'express';
+import type { Express, Request } from 'express';
 import { createHmac, timingSafeEqual } from 'node:crypto';
 
+// Minimal local shape of the loader's ctx (see src/server/extensions.ts).
+interface WebhookOptions {
+  source: string;
+  verify: (req: Request, raw: string) => boolean | unknown;
+  normalize?: (req: Request) => unknown;
+  eventId?: (payload: unknown, req: Request) => string | undefined;
+  path?: string;
+}
 interface ExtensionContext {
   dataPath: (p: string) => string;
   requireAuth: any;
   log: (...a: unknown[]) => void;
   app: Express;
   emitEvent: (source: string, payload: unknown, opts?: { id?: string }) => void;
+  registerWebhook: (opts: WebhookOptions) => string;
 }
 
 /** Minimal Stripe `Stripe-Signature` verification (t=…,v1=…) over the raw body. */
@@ -31,28 +44,23 @@ function verifyStripeSig(raw: string, header: string, secret: string): boolean {
   try { return timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); } catch { return false; }
 }
 
-export default function register(app: Express, ctx: ExtensionContext) {
+export default function register(_app: Express, ctx: ExtensionContext) {
   const secret = process.env.STRIPE_WEBHOOK_SECRET;
   if (!secret) {
     ctx.log('stripe-webhook extension dormant (set STRIPE_WEBHOOK_SECRET to enable)');
     return;
   }
 
-  // PUBLIC route — Stripe authenticates via its own signature, not shraga auth.
-  // The server's global express.json() already parsed the body AND stashed the exact
-  // bytes on req.rawBody (see index.ts) — verify the signature against those. Adding
-  // our own express.raw here would be too late: the stream is already consumed.
-  app.post('/webhooks/stripe', (req: Request, res: Response) => {
-    const rawBuf = (req as any).rawBody;
-    const raw = rawBuf instanceof Buffer ? rawBuf.toString('utf8') : '';
-    const sig = String(req.headers['stripe-signature'] ?? '');
-    if (!verifyStripeSig(raw, sig, secret)) return res.status(400).json({ error: 'bad signature' });
-
-    // evt.id dedupes Stripe's retries; evt.type is what schedules `match` on.
-    const evt = req.body; // already parsed by the global JSON body parser
-    ctx.emitEvent('stripe', evt, { id: evt?.id });
-    res.json({ received: true });
+  // Stripe authenticates via its own signature, not shraga auth. The raw request
+  // bytes are read from req.rawBody (stashed by the global express.json in index.ts);
+  // `verify` returns true iff the signature matches. Payload = the parsed body, and
+  // its `id` dedupes Stripe's retries — both handled generically by registerWebhook.
+  const path = ctx.registerWebhook({
+    source: 'stripe',
+    // Keep the original public path (Stripe's dashboard points at /webhooks/stripe).
+    path: '/webhooks/stripe',
+    verify: (req, raw) => verifyStripeSig(raw, String(req.headers['stripe-signature'] ?? ''), secret),
   });
 
-  ctx.log('stripe-webhook extension ready — POST /webhooks/stripe → emitEvent("stripe")');
+  ctx.log(`stripe-webhook extension ready — POST ${path} → emitEvent("stripe")`);
 }

package/defaults/scripts/agent-once.ts

@@ -19,7 +19,7 @@ if (argv[0] === '--uid') {
 }
 const prompt =
   argv.join(' ').trim() ||
-  'Call mcp-slack tool get_slack_channels with limit=2 only. Output the JSON ok field and first channel name, nothing else.';
+  'Call mcp-slack-use tool get_slack_channels with limit=2 only. Output the JSON ok field and first channel name, nothing else.';
 
 if (!process.env.ANTHROPIC_API_KEY?.trim()) {
   console.error('Missing ANTHROPIC_API_KEY — cannot run Claude Agent SDK.');

package/defaults/skills/communications.md

@@ -12,7 +12,7 @@ Dedup applies only when **you** decide to reach out (not when fulfilling a user
 
 1. **Read the comms log** — `Read data/comms-log.jsonl` (tail last 50-100 lines if large). If the file exceeds 500 lines, only read the last 100.
 2. **Check for recent similar outreach** — same recipient + similar topic within the last 24h = skip or significantly alter the message
-3. **For Slack** — the mcp-slack skill already requires reading channel history before posting (rule #6). That check + this log together cover both same-session and cross-session duplicates.
+3. **For Slack** — the mcp-slack-use skill already requires reading channel history before posting (rule #6). That check + this log together cover both same-session and cross-session duplicates.
 
 ### What counts as a duplicate (proactive only)
 

package/defaults/skills/mcps-sync.md

@@ -83,7 +83,7 @@ Print a summary table:
 
 ```
 MCP Sync Results:
-  mcp-slack      up to date
+  mcp-slack-use      up to date
   mcp-firebase   pulled 3 commits
   mcp-pdf        cloned (NEW)
   mcp-cursor     pushed 1, pulled 2
@@ -92,7 +92,7 @@ Missing env vars (add to .env):
   mcp-stripe     STRIPE_SECRET_KEY
   mcp-gmail      GOOGLE_SERVICE_ACCOUNT, GMAIL_USER_EMAIL
 
-All configured: mcp-slack, mcp-firebase, mcp-google-drive
+All configured: mcp-slack-use, mcp-firebase, mcp-google-drive
 ```
 
 ## Rules

package/defaults/skills/self-aware.md

@@ -85,7 +85,7 @@ List checkpoints with `git -C "$APP_DIR" log --oneline`; reset to any of them.
 - `src/server/mcp.ts` — MCP server injection and config
 - `src/server/skills.ts` — skill loading and injection
 - `defaults/` — canonical source for runtime-seeded dirs (see Architecture skill § "Defaults → Runtime Seeding Pattern")
-- `vendor/` — vendored MCP servers (mcp-firebase, mcp-github, mcp-slack, etc.)
+- `vendor/` — vendored MCP servers (mcp-firebase, mcp-github, mcp-slack-use, etc.)
 - `data/` — runtime data, git-tracked behavioral config via data-sync (skills, mcps, workspace, schedules, contacts, agent-config, whitelist)
 
 ## Where one-off / custom code goes (NOT main `src/`)