shraga 0.1.1 → 0.1.3

package/README.md

@@ -2,21 +2,35 @@
 
 # 🧑‍💻 Shraga
 
-**The teammate you delegate coding to — just forward it to Shraga.**
+**The teammate you delegate coding to. Just forward it to Shraga.**
 
 [![npm](https://img.shields.io/npm/v/shraga.svg)](https://www.npmjs.com/package/shraga)
 [![CI](https://github.com/Livshitz/shraga/actions/workflows/ci.yml/badge.svg)](https://github.com/Livshitz/shraga/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 </div>
 
-Shraga is a self-hostable, multi-user web UI for running an AI coding agent — Claude Code out
-of the box, with a pluggable engine seam for other runtimes — that you can reach from anywhere:
-your laptop, a home server, or a VM.
+Shraga is a self-hostable, multi-user web UI for running an AI coding agent (Claude Code out of
+the box, with a pluggable engine seam for other runtimes) that you can reach from anywhere: your
+laptop, a home server, or a VM.
 
-Give it its own machine, its own keys, its own identity — onboard it once and delegate.
+Give it its own machine, its own keys, its own identity. Onboard it once, then delegate.
 
----
+## Why Shraga
+
+- ⭐ **Runs on your Claude subscription, not a metered API key.** Point it at Claude Code and it
+  drives the agent through your existing plan (`claude auth login`). No per-token bill to watch.
+- ⭐ **A real teammate, not a chat box.** It has its own machine, its own identity, and its own
+  logins, so you delegate a task the way you would to a person and come back to the result.
+- ⭐ **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.
+- **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/`).
+- **MCP servers**: connect tools (GitHub, Slack, databases) per-user or globally.
+- **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.
 
 ## Quickstart
 
@@ -25,85 +39,67 @@ Requires [Bun](https://bun.sh) ≥ 1.0.
 ```bash
 # 1. Install & configure
 bun install
-cp .env.example .env          # then set ANTHROPIC_API_KEY
+cp .env.example .env
 
 # 2. Run
 bun run build                 # build the web UI
 bun run start                 # serve on http://localhost:3032
 ```
 
-Open http://localhost:3032. On first run you'll create your account (local username/password —
-no external auth needed). Or seed one from the CLI:
+Open http://localhost:3032. On first run you create your account (local username and password, no
+external auth needed). Or seed one from the CLI:
 
 ```bash
 shraga user add you@example.com <password>
 ```
 
-That's it — sign in and start delegating.
+Sign in and start delegating.
 
-> Prefer subscription auth? Run `claude auth login` and leave `ANTHROPIC_API_KEY` unset.
+### Auth: subscription or API key
 
-## What you get
+Shraga runs the agent through **Claude Code**, so it uses whatever Claude Code is authenticated
+with:
 
-- **Chat with an agent** that has your workspace, shell, and tools.
-- **Sessions** — fork, resume, and revisit past conversations.
-- **Skills** — teach the agent reusable procedures (files in `data/skills/`).
-- **MCP servers** — connect tools (GitHub, Slack, databases, …) per-user or globally.
-- **Schedules** — run agent jobs on a cron or in response to events.
-- **Programmatic API + MCP endpoint** — drive the agent from scripts or `claude.ai`.
+- **Your Claude subscription (recommended).** Run `claude auth login` once and leave
+  `ANTHROPIC_API_KEY` unset. The agent runs on your plan, with no metered API charges.
+- **An API key.** Set `ANTHROPIC_API_KEY` in `.env` if you would rather pay per token.
 
 ## Configuration
 
-All config is flat files under `data/` (no database). See `.env.example` for options.
-Key ones:
+All config is flat files under `data/` (no database). See `.env.example` for the full list. The
+common ones:
 
 | Var | Default | Purpose |
 |-----|---------|---------|
-| `ANTHROPIC_API_KEY` | — | Claude API key (or `claude auth login`) |
+| `ANTHROPIC_API_KEY` | *(unset)* | Claude API key. Leave unset to use `claude auth login`. |
 | `PORT` | `3032` | Server port |
 | `DATA_DIR` | `./data` | Where state lives |
 | `AUTH_PROVIDER` | `local` | `local` (username/password) or `firebase` |
-| `OWNERS` | — | Comma-list of admin emails |
-
-### Optional features
-
-Shraga's core is a focused chat workspace. Heavier surfaces are opt-in via env flags:
-
-| Flag | Enables |
-|------|---------|
-| `SHRAGA_FEAT_WORKSPACE=1` | Multi-tab workspace |
-| `SHRAGA_FEAT_INSTANCES=1` | Multi-instance switcher |
-
-Some surfaces are supplied by add-ons rather than the core — e.g. embedded terminals and voice
-mode. Their capability flags appear once the corresponding add-on is installed; on a bare core
-build the flags are inert.
+| `OWNERS` | *(unset)* | Comma-separated list of admin emails |
 
 ## Expose it (optional)
 
-Running on a home machine? Set `CLOUDFLARE_TUNNEL_TOKEN` to get a public URL via
-Cloudflare Tunnel, or put it behind any reverse proxy.
+Running on a home machine? Set `CLOUDFLARE_TUNNEL_TOKEN` for a public URL via Cloudflare Tunnel, or
+put it behind any reverse proxy.
 
 ## Architecture
 
-- **Runtime:** Bun · **Server:** Express + WebSocket (`src/server/`)
+- **Runtime:** Bun. **Server:** Express + WebSocket (`src/server/`)
 - **Client:** React + Vite + Tailwind (`src/client/`)
 - **Agent:** `@anthropic-ai/claude-agent-sdk`
-- **Storage:** flat JSON/JSONL in `data/` — no database
+- **Storage:** flat JSON/JSONL in `data/` (no database)
 - **Auth:** pluggable provider (local by default; Firebase optional)
 
 ## Read the thinking
 
-Shraga is a set of ideas before it's a binary:
+Shraga is a set of ideas before it is a binary:
 
-- **[Concept](./docs/concept.md)** — the mental model: delegation, not another chat box.
-- **[The shared brain](./docs/shared-brain.md)** — a teammate that onboards, learns, and compounds org knowledge.
-- **[Primitives](./docs/architecture/primitives.md)** — the core nouns you build with.
+- **[Concept](./docs/concept.md)**: the mental model of delegation, not another chat box.
+- **[The shared brain](./docs/shared-brain.md)**: a teammate that onboards, learns, and compounds
+  org knowledge.
+- **[Primitives](./docs/architecture/primitives.md)**: the core nouns you build with.
 
 ## Feedback
 
-Concepts, gaps, "why not X", use cases → [Discussions](https://github.com/Livshitz/shraga/discussions).
-Bugs and concrete proposals → [Issues](https://github.com/Livshitz/shraga/issues).
-
-## License
-
-[MIT](./LICENSE) © Elya Livshitz
+Concepts, gaps, "why not X", use cases: [Discussions](https://github.com/Livshitz/shraga/discussions).
+Bugs and concrete proposals: [Issues](https://github.com/Livshitz/shraga/issues).

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/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/`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "express": "^4.21.1",
     "firebase": "^11.0.0",
     "lucide-react": "^0.468.0",
-    "mcp-slack": "github:Livshitz/mcp-slack#7680804b8dfdf85c50ca66ede8931c364e0516ee",
+    "mcp-slack-use": "github:Livshitz/mcp-slack-use#1dde291",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^9.0.0",

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

@@ -457,7 +457,7 @@ export class ClaudeCodeEngine implements AgentEngine {
               }
 
               const pending = pendingToolUses.get(String(block.tool_use_id));
-              if (pending?.tool === 'mcp__mcp-slack__post_slack_message') {
+              if (pending?.tool === 'mcp__mcp-slack-use__post_slack_message') {
                 try {
                   const parsed = typeof output === 'string' ? JSON.parse(output) : output;
                   const ts = parsed?.ts || parsed?.preview?.ts;
@@ -470,7 +470,7 @@ export class ClaudeCodeEngine implements AgentEngine {
                   }
                 } catch (err) { console.warn('[claude] Failed to track proactive message:', (err as Error).message); }
               }
-              if (pending?.tool === 'mcp__mcp-slack__post_slack_poll') {
+              if (pending?.tool === 'mcp__mcp-slack-use__post_slack_poll') {
                 try {
                   const parsed = typeof output === 'string' ? JSON.parse(output) : output;
                   const body = ((pending.input as any)?.body ?? {}) as Record<string, any>;

package/src/server/hooks.ts

@@ -62,7 +62,7 @@ const SLACK_MENTION_FIELDS: Record<string, string[]> = {
 const resolveSlackMentions: HookCallback = async (input) => {
   if (input.hook_event_name !== 'PreToolUse') return {};
   const { tool_name, tool_input } = input as PreToolUseHookInput;
-  const m = /^mcp__mcp-slack__(post_slack_\w+)$/.exec(tool_name);
+  const m = /^mcp__mcp-slack-use__(post_slack_\w+)$/.exec(tool_name);
   if (!m) return {};
   const fields = SLACK_MENTION_FIELDS[m[1]];
   if (!fields) return {};
@@ -135,7 +135,7 @@ export function buildHooks(): Partial<Record<HookEvent, HookCallbackMatcher[]>>
   return {
     PreToolUse: [
       { matcher: 'Bash', hooks: [forceBackgroundForScripts] },
-      { matcher: 'mcp__mcp-slack__post_slack_.*', hooks: [resolveSlackMentions] },
+      { matcher: 'mcp__mcp-slack-use__post_slack_.*', hooks: [resolveSlackMentions] },
       { matcher: 'mcp__mcp-firebase-(?:prod|lab)__get_db.*', hooks: [guardFirebaseReads] },
     ],
   };

package/src/server/polls.ts

@@ -1,4 +1,4 @@
-// Proactive Slack poll / directed-question state. The vendor mcp-slack `post_slack_poll`
+// Proactive Slack poll / directed-question state. The mcp-slack-use `post_slack_poll`
 // tool posts the interactive message; shraga owns everything after: vote state, live
 // tally updates (chat.update), closing on deadline/quorum/first-answer, and waking the
 // originating agent session once with the result ("close then report").

package/src/server/slack/api.ts

@@ -1,11 +1,11 @@
-// Slack client — the ONE agent-glue seam onto the mcp-slack package `client` (unified Slack
+// Slack client — the ONE agent-glue seam onto the mcp-slack-use package `client` (unified Slack
 // Web API, single bot-vs-user token-resolution path). The former duplicate `slackPost` is gone:
 // everything routes through the package. Only contact/mention resolution stays here — this app owns
 // the contacts store, so it can't live in the vendor package.
 import * as contacts from '../contacts.ts';
-import { getUserProfile } from 'mcp-slack/src/client.ts';
+import { getUserProfile } from 'mcp-slack-use/src/client.ts';
 
-export * from 'mcp-slack/src/client.ts';
+export * from 'mcp-slack-use/src/client.ts';
 
 /** Rewrite Slack `<@Uxxx>` (and bare user ids) to `@Name (operator)?`, learning contacts as it goes. */
 export async function resolveUserMentions(text: string): Promise<string> {

package/src/server/slack/bot.ts

@@ -1,6 +1,6 @@
 // Slack agent-glue — the app-side half of the Slack bot. The Slack transport/protocol (routes, HMAC
 // verify, dedupe, DM identity, file hydrate, streamer wiring, reaction lifecycle) lives in the
-// mcp-slack package `ingress`. This module owns only what this app owns: sessions, locks, contacts,
+// mcp-slack-use package `ingress`. This module owns only what this app owns: sessions, locks, contacts,
 // thread-context sync, artifacts, broadcast, and message persistence — surfaced to the ingress as
 // callbacks (shouldRespond / onMessage / onReplied) plus the crash-recovery resume path.
 import crypto from 'node:crypto';
@@ -17,7 +17,7 @@ import {
   getChannelName, getUserName, getUserProfile, resolveUserMentions, isSupportedFile, SUPPORTED_FILE_MIMES,
   downloadSlackFileBuffer,
 } from './api.ts';
-import { pipeAgentReply, type AgentEvent, type IngressMessage } from 'mcp-slack/src/ingress.ts';
+import { pipeAgentReply, type AgentEvent, type IngressMessage } from 'mcp-slack-use/src/ingress.ts';
 import { makeSlackQuestionHandler } from './questions.ts';
 import * as contacts from '../contacts.ts';
 import { getChannelContext, invalidateChannelContext } from './context-cache.ts';
@@ -189,7 +189,7 @@ export async function* runAgentTurn(msg: IngressMessage): AsyncGenerator<AgentEv
         : `#${channelName || 'channel'} context`;
       appendMessage(sessionId, {
         id: crypto.randomUUID(), role: 'user',
-        blocks: [{ type: 'context', label, text: `${channelCtx}\n\n[Use mcp-slack tools (get_slack_history_by_channel, post_slack_message) for further context or replies. Always read channel history before posting.]` }],
+        blocks: [{ type: 'context', label, text: `${channelCtx}\n\n[Use mcp-slack-use tools (get_slack_history_by_channel, post_slack_message) for further context or replies. Always read channel history before posting.]` }],
       });
     }
   }

package/src/server/slack/feature.ts

@@ -1,8 +1,8 @@
-// slackFeature — the ServerFeature that mounts Slack in this app. It wires the mcp-slack package
+// slackFeature — the ServerFeature that mounts Slack in this app. It wires the mcp-slack-use package
 // `ingress` (protocol) to the agent-glue (bot.ts) and subscribes the data-sync deploy notifier
 // (event bus → owner DMs). Slack ships in this app, so index.ts registers this directly.
 import type { ServerFeature, FeatureContext } from '../features.ts';
-import { registerSlackIngress } from 'mcp-slack/src/ingress.ts';
+import { registerSlackIngress } from 'mcp-slack-use/src/ingress.ts';
 import { subscribeEvents } from '../events/bus.ts';
 import { postMessage, resolveUserMentions } from './api.ts';
 import { runAgentTurn, shouldRespond, onReplied, retrySlackSession, setBroadcast } from './bot.ts';

package/src/server/turn-context.ts

@@ -27,6 +27,13 @@ export function registerTurnContext(name: string, contribute: TurnContextContrib
   contributors.set(name, contribute);
 }
 
+/** Clear all registered contributors. For tests: the registry is a process-global, so a test that
+ *  asserts the empty-registry (no-contributor) behavior must reset it first or it inherits whatever
+ *  another test file registered — bun's cross-file order is not stable across platforms. */
+export function clearTurnContext(): void {
+  contributors.clear();
+}
+
 /**
  * Collect every contributor's block for this turn, joined by a blank line. Empty when none is
  * registered — which is the core's own state, so the core's prompt is byte-identical to before.