sparkecoder 0.1.98 → 0.1.100

package/dist/skills/default/manage-mcp.md

@@ -0,0 +1,94 @@
+---
+name: Manage MCP servers
+description: Add, remove, enable, or test Model Context Protocol (MCP) servers by editing sparkecoder.config.json directly. Load this when the user asks to wire up a new MCP, switch tokens, disable an integration, or troubleshoot one.
+---
+
+# Manage MCP servers
+
+MCP (Model Context Protocol) servers extend your toolset. Each registered server's tools get loaded into your toolset on the NEXT agent turn under the key pattern `mcp_<server-name>_<tool-name>`. There is intentionally NO dedicated MCP tool — you manage MCP by editing the config file directly with your normal `bash`, `read_file`, `write_file` toolset.
+
+## Where the config lives
+
+Run this to find it (in order of precedence):
+
+```bash
+# Local config (preferred if present — current working directory)
+ls -la "$(pwd)/sparkecoder.config.json" 2>/dev/null
+
+# Global config (fallback — OS app-data dir)
+ls -la "$HOME/Library/Application Support/sparkecoder/sparkecoder.config.json" 2>/dev/null   # macOS
+ls -la "$HOME/.config/sparkecoder/sparkecoder.config.json" 2>/dev/null                       # Linux
+```
+
+The local one (cwd) wins if it exists. If neither exists, you can create the local one with `sparkecoder init` from the CLI, or just write a fresh `sparkecoder.config.json` in the cwd.
+
+## Schema
+
+```json
+{
+  "mcp": {
+    "servers": [
+      {
+        "id": "mcp_abc123",                                           // unique; you can use a short random string or `mcp_` + nanoid
+        "name": "github",                                             // human-friendly; becomes the tool prefix (mcp_github_*)
+        "transport": "http" | "sse" | "stdio",
+        "url": "https://your-server.com/mcp",                         // required for http/sse
+        "headers": { "Authorization": "Bearer ghp_xxx..." },          // optional, http/sse
+        "command": "node",                                            // required for stdio
+        "args": ["src/stdio/dist/server.js"],                         // optional, stdio
+        "enabled": true,                                              // toggle without deleting
+        "createdAt": "2026-05-18T00:00:00.000Z"
+      }
+    ]
+  }
+}
+```
+
+## Recipes
+
+### Add an HTTP MCP server with a bearer token
+
+```bash
+# Read current config
+read_file({ path: "sparkecoder.config.json" })
+
+# Merge in a new server. Use jq if you trust the env to have it; otherwise
+# read it with read_file, mutate, write_file the whole thing.
+NEW_ID="mcp_$(node -e "console.log(Math.random().toString(36).slice(2,12))")"
+# Edit the file to add an entry to mcp.servers with the values above.
+```
+
+After saving the file, the new server's tools appear in your toolset on your **next** turn under `mcp_<name>_*`. No restart needed — the MCP pool re-reads disk every turn and refreshes its clients automatically.
+
+### Test connectivity
+
+You can either:
+
+1. **Just try it next turn** — if you call one of the new `mcp_<name>_*` tools and it fails, you'll see the error in the tool result.
+2. **Probe via the local REST API** without waiting:
+
+```bash
+# After saving the new server, the id is in the config; ask the API to test it
+SERVER_ID="<the id you wrote>"
+curl -s -X POST "http://127.0.0.1:3141/api/mcp/$SERVER_ID/test" | jq
+# Returns: { "ok": true, "toolCount": N, "toolNames": [...] }  or  { "ok": false, "error": "..." }
+```
+
+### Disable a server temporarily
+
+Flip `enabled` to `false` in the config. Tools stop appearing on the next turn. Flip back to `true` to re-enable.
+
+### Remove a server
+
+Delete the entry from the `servers` array.
+
+### OAuth-protected MCP servers
+
+For now, the simplest path is to obtain the OAuth access token out-of-band (the Settings UI or the MCP server's docs will tell you how) and paste it into `headers.Authorization` as `"Bearer <token>"`. Token refresh isn't yet automatic; ask the user to re-paste when it expires.
+
+## Notes
+
+- **Tool prefix:** the `name` becomes a sanitized prefix. `My GitHub` becomes `my_github` and its tools become `mcp_my_github_*`. Use short, snake_case names.
+- **No collisions:** two servers can expose tools with the same internal name; the prefix ensures they don't collide.
+- **Failure isolation:** if one MCP server is broken, the others still load. You'll see a warning in the server logs.
+- **Settings UI exists:** humans can manage MCP from the dashboard's Settings → MCP tab. You're editing the same underlying file.

package/dist/skills/default/search-conversations.md

@@ -0,0 +1,100 @@
+---
+name: Search conversations
+description: Long-term memory across sessions. Grep through every past conversation on this machine — every web/Slack/system/webhook turn is mirrored to local JSONL files. Load when the user asks "what did we talk about", "remind me what I said", "find that thing from last week", or any cross-session recall query.
+---
+
+# Search conversations (long-term memory)
+
+Every user-message and assistant-reply in every session is mirrored to a local JSONL archive on this device. This is your filesystem-backed long-term memory — grep through it like any text corpus.
+
+## Where the archive lives
+
+```bash
+# macOS / Linux
+HISTORY_DIR="$HOME/Library/Application Support/sparkecoder/history"     # macOS
+# or
+HISTORY_DIR="$HOME/.config/sparkecoder/history"                         # Linux
+
+ls "$HISTORY_DIR"
+# -> <session-id>.jsonl    one file per session
+```
+
+Each line is one turn:
+
+```json
+{
+  "ts": "2026-05-18T01:23:45.678Z",
+  "sessionId": "abc123",
+  "sessionName": "Orchestrator",
+  "role": "user",            // or "assistant"
+  "content": "...plain text...",
+  "channel": "slack"         // optional: web | slack | system | schedule | webhook
+}
+```
+
+The orchestrator's own history is in the JSONL named after its session id. Worker agents have their own files.
+
+## Common queries
+
+### "What did we talk about regarding deployments?"
+
+```bash
+HISTORY_DIR="${HOME}/Library/Application Support/sparkecoder/history"
+grep -l -i "deploy" "$HISTORY_DIR"/*.jsonl
+# Then for each match:
+grep -i "deploy" "$HISTORY_DIR/<session-id>.jsonl" | python3 -c '
+import json, sys
+for line in sys.stdin:
+    j = json.loads(line)
+    print(j["ts"], j["role"], j["content"][:200])
+'
+```
+
+### "Find that thing the user said about Python"
+
+```bash
+grep -h '"role":"user"' "$HISTORY_DIR"/*.jsonl | grep -i 'python' | head -20
+```
+
+### "Show the last 5 things I said"
+
+```bash
+grep -h '"role":"user"' "$HISTORY_DIR"/*.jsonl | tail -5 | python3 -c '
+import json, sys
+for line in sys.stdin:
+    j = json.loads(line)
+    print(j["ts"], "—", j["content"][:200])
+'
+```
+
+### "What happened in Slack yesterday"
+
+```bash
+grep -h '"channel":"slack"' "$HISTORY_DIR"/*.jsonl | python3 -c '
+import json, sys
+from datetime import datetime, timedelta
+cutoff = (datetime.utcnow() - timedelta(days=1)).isoformat()
+for line in sys.stdin:
+    j = json.loads(line)
+    if j["ts"] > cutoff: print(j["ts"], j["role"], j["content"][:200])
+'
+```
+
+### "Pull every webhook event since Friday"
+
+```bash
+grep -h '"channel":"webhook"' "$HISTORY_DIR"/*.jsonl | python3 -c '...'
+```
+
+## Tips
+
+- **Channel-aware:** filter by `"channel":"slack"`, `"webhook"`, `"system"`, `"schedule"`, or `"web"` (no channel field = legacy/plain web).
+- **Session-aware:** if the user references "the convo we had in <X>", look up `sessionName` first.
+- **Plain text:** images / files are flattened to `[image filename]` placeholders. The text content is what's searchable.
+- **Append-only:** never edit or delete these files — the orchestrator might lie to itself if it does. If you need to redact, do it at the DB level (out of scope here).
+- **Workers too:** worker agents' chats are also archived. Useful for "what did agent X actually do?" queries that go beyond the agent's persisted task summary.
+
+## When NOT to use
+
+- For the LIVE current session, use `agent({action:'get', id, recentMessages:20})` — that's faster and structured.
+- For very recent stuff in the orchestrator's own thread, just look at your own message history (you already have it in context).

package/dist/tools/index.d.ts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ToolSet } from 'ai';
-import { B as BashToolProgress, W as WriteFileProgress, S as SearchToolProgress } from '../search-CCffrVJE.js';
-export { b as BashToolOptions, d as SearchToolOptions, e as WriteFileToolOptions, c as createBashTool, f as createSearchTool, a as createWriteFileTool } from '../search-CCffrVJE.js';
+import { B as BashToolProgress, W as WriteFileProgress, S as SearchToolProgress } from '../search-DOzC4ojH.js';
+export { b as BashToolOptions, d as SearchToolOptions, e as WriteFileToolOptions, c as createBashTool, f as createSearchTool, a as createWriteFileTool } from '../search-DOzC4ojH.js';
 
 interface TaskCompletionSignal {
     status: 'completed' | 'failed';

package/dist/tools/index.js

@@ -56,7 +56,49 @@ var init_types = __esm({
       computerUseEnabled: z.boolean().optional(),
       // Display dimensions for the computer use tool (defaults: 1280x800).
       computerUseDisplayWidth: z.number().int().positive().optional(),
-      computerUseDisplayHeight: z.number().int().positive().optional()
+      computerUseDisplayHeight: z.number().int().positive().optional(),
+      // 'orchestrator' = supervisor session; 'worker' = task spawned by an orchestrator.
+      role: z.enum(["orchestrator", "worker", "chat"]).optional(),
+      // Optional persona / extra system-prompt text appended to the orchestrator's
+      // system prompt (e.g. "speak in haiku", "answer in Korean", "be terse").
+      personality: z.string().optional(),
+      // For workers: the orchestrator session that spawned them. Used so
+      // terminal events (complete_task / task_failed / ask_question_to_user)
+      // can push system events back to the orchestrator's inbox.
+      orchestratorSessionId: z.string().optional(),
+      // Persisted Slack thread context the orchestrator can reply to.
+      slack: z.object({
+        channel: z.string().optional(),
+        threadTs: z.string().optional(),
+        teamId: z.string().optional()
+      }).optional(),
+      // Recurring prompts owned by this orchestrator. Stored inline on the
+      // session row so we don't need a separate DB collection.
+      schedules: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        cron: z.string(),
+        prompt: z.string(),
+        replyChannel: z.string().optional(),
+        enabled: z.boolean().default(true),
+        lastFiredAt: z.string().optional(),
+        // ISO date
+        createdAt: z.string()
+        // ISO date
+      })).optional(),
+      // Custom token-protected inbound webhook URLs.
+      webhooks: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        token: z.string(),
+        wake: z.enum(["now", "next"]).default("now"),
+        template: z.string().optional(),
+        hitCount: z.number().int().default(0),
+        lastHitAt: z.string().optional(),
+        // ISO date
+        createdAt: z.string()
+        // ISO date
+      })).optional()
     });
     VectorGatewayConfigSchema = z.object({
       // Redis cluster nodes URL for Vector Gateway (or use REDIS_CLUSTER_NODES env var)
@@ -144,7 +186,74 @@ var init_types = __esm({
       // If configured, uses remote MongoDB instead of local SQLite
       remoteServer: RemoteServerConfigSchema,
       // Vector Gateway configuration for semantic search
-      vectorGateway: VectorGatewayConfigSchema
+      vectorGateway: VectorGatewayConfigSchema,
+      // Slack integration. When configured, the orchestrator can post to Slack
+      // and Slack `app_mention` events are routed into the orchestrator session.
+      slack: z.object({
+        botToken: z.string().optional(),
+        signingSecret: z.string().optional(),
+        defaultOrchestratorName: z.string().optional().default("orchestrator"),
+        // Allowlist controls — when set, only matching events reach the orchestrator.
+        // Empty arrays = "no allowlist" => allow all (subject to allowDmsFromAnyone below).
+        allowedUsers: z.array(z.string()).optional().default([]),
+        // Slack user IDs (U0123...)
+        allowedChannels: z.array(z.string()).optional().default([]),
+        // Slack channel IDs (C0123...)
+        // If true (default), the bot replies to DMs from anyone. If false, the user
+        // must also appear in `allowedUsers`.
+        allowDmsFromAnyone: z.boolean().optional().default(true),
+        // When true, denied @mentions / DMs get a friendly canned reply
+        // (no AI / no orchestrator). Use {user} and {channel} placeholders.
+        deniedReplyEnabled: z.boolean().optional().default(true),
+        deniedReplyTemplate: z.string().optional().default(
+          "Sorry, you don't have permission to use this bot. (Contact the bot owner if you think this is a mistake.)"
+        )
+      }).partial().optional(),
+      // MCP integrations. Each server is connected on demand and its tools are
+      // merged into the agent's toolset under `mcp_<server-name>_<tool>` keys.
+      mcp: z.object({
+        servers: z.array(z.object({
+          id: z.string(),
+          name: z.string(),
+          // human-friendly; also used as tool prefix
+          transport: z.enum(["http", "sse", "stdio"]),
+          url: z.string().optional(),
+          // http/sse
+          headers: z.record(z.string(), z.string()).optional(),
+          // http/sse (e.g. Authorization: Bearer ...)
+          command: z.string().optional(),
+          // stdio
+          args: z.array(z.string()).optional(),
+          // stdio
+          enabled: z.boolean().default(true),
+          createdAt: z.string(),
+          // ISO date
+          // OAuth scaffolding — present so tokens can be persisted by the
+          // settings UI once the auth flow completes. Bearer tokens can also
+          // be stored directly via `headers.Authorization` for now.
+          oauth: z.object({
+            authorizationUrl: z.string().optional(),
+            tokenUrl: z.string().optional(),
+            clientId: z.string().optional(),
+            clientSecret: z.string().optional(),
+            accessToken: z.string().optional(),
+            refreshToken: z.string().optional(),
+            expiresAt: z.string().optional()
+          }).partial().optional()
+        })).optional().default([])
+      }).partial().optional(),
+      // Authentication for the public (cloudflared) surface. When
+      // auth.cfAccess.enabled is true, every non-loopback request must carry a
+      // valid Cf-Access-Jwt-Assertion header whose `email` claim is in
+      // `auth.allowedEmails`. Slack events and /health bypass the check.
+      auth: z.object({
+        cfAccess: z.object({
+          enabled: z.boolean().optional().default(false),
+          teamDomain: z.string().optional(),
+          audTag: z.string().optional()
+        }).partial().optional(),
+        allowedEmails: z.array(z.string()).optional().default([])
+      }).partial().optional()
     });
   }
 });