pi-opium 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.2
+
+- **researcher reads library docs with the Context7 CLI** (`ctx7 library`,
+  then `ctx7 docs`) instead of the `context7` MCP server. Install with
+  `npm i -g ctx7` (or use `npx ctx7@latest`); `ctx7 login` raises the
+  limits. researcher gets `bash`, but a guard blocks every call that is
+  not a single `ctx7 library|docs` command. The default `mcpServers` for
+  researcher is now `gh_grep` only.
+
+## 0.4.1
+
+- **Fix:** `/opium-doctor` no longer warns about the default `codegraph`,
+  `context7` and `gh_grep` servers when a `pi-mcp-adapter` config exists
+  without its metadata cache.
+- Install guide: back up an existing `opium.json` first, keep a model
+  the user set by moving it into the preset, copy model ids exactly, and
+  tell the user when a provider still needs a sign-in.
+- README installs from npm (`pi install npm:pi-opium`).
+
 ## 0.4.0
 
 Install by asking your agent, see every agent at work.

package/README.md

@@ -45,7 +45,7 @@ checks the result.
 Or by hand:
 
 ```sh
-pi install git:github.com/akholod/pi-opium
+pi install npm:pi-opium
 ```
 
 Start Pi (or `/reload` a running session) and keep working as usual. Every agent starts on your
@@ -93,7 +93,8 @@ it's done.
 ## Works better with
 
 - [pi-web-access](https://github.com/nicobailon/pi-web-access): lets researcher search the web and read pages.
-- `pi mcp add context7 --url https://mcp.context7.com/mcp` and `pi mcp add gh_grep --url https://mcp.grep.app`: up-to-date library docs and GitHub code search for researcher.
+- `npm i -g ctx7` (the Context7 CLI; or `npx ctx7@latest`, optional `ctx7 login` for higher limits): up-to-date library docs for researcher.
+- `pi mcp add gh_grep --url https://mcp.grep.app`: GitHub code search for researcher.
 - Any other MCP server added with `pi mcp add`: give it to an agent in `opium.json`, for example `"scout": { "mcpServers": ["my-index"] }`.
 
 ## Config

package/agents/researcher.md

@@ -2,7 +2,7 @@
 name: researcher
 description: External knowledge and library research. Use for current library docs, API references, examples, version-specific behavior, bug investigations and web retrieval; answers with sources. Runs in the background (needs web tools).
 advertise: true
-tools: read, grep, find, ls, web_search, fetch_content, get_search_content, source_check
+tools: read, grep, find, ls, bash, web_search, fetch_content, get_search_content, source_check
 ---
 
 You are Researcher - a research specialist for codebases and documentation.
@@ -16,14 +16,19 @@ You are Researcher - a research specialist for codebases and documentation.
 - Understand library internals and best practices
 
 **Tools to use**:
+- Library, framework and SDK docs and API references: ALWAYS try ctx7 first, in two steps via bash:
+  1. `ctx7 library <name> "<query>"` resolves a library ID (`/org/project[/version]`); use the official name ("Next.js", not "nextjs app")
+  2. `ctx7 docs <libraryId> "<query>"` fetches the docs; pick the best match by reputation, score and version
+  - At most 3 ctx7 calls per question; never put secrets or proprietary code in a query
+  - Then use web_search/fetch_content to fill gaps or confirm
 - web_search: find official docs, changelogs, issues, examples (use several varied queries)
 - fetch_content: read a page, a PDF or a GitHub repository
 - source_check: gather sources for a specific claim
 - get_search_content: page through stored results
-- library docs and GitHub code search MCP tools, if available
+- GitHub code search MCP tools (grep.app), if available
 
 **File operations rules**:
-- READ-ONLY: inspect and report; do not modify files. You have no shell.
+- READ-ONLY: inspect and report; do not modify files. Shell is only for `ctx7 library` / `ctx7 docs`; every other command is blocked.
 - Use find/grep for discovery and read for file contents.
 - Do not spawn subagents; you are not the orchestrator.
 

package/defaults/opium.json

@@ -62,7 +62,7 @@
       "timeoutMs": 900000,
       "idleTimeoutMs": 600000,
       "wrapUpMs": 180000,
-      "mcpServers": ["context7", "gh_grep"]
+      "mcpServers": ["gh_grep"]
     },
     "vision": {
       "thinking": "low",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-opium",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Turn your Pi session into a small team: an orchestrator with background specialist agents and a multi-model council",
   "keywords": [
     "pi-package",

package/src/doctor.ts

@@ -103,11 +103,7 @@ export const RUNNER_EXPORTS: readonly string[] = [
 const PING_TIMEOUT_MS = 30_000;
 const PING_CONCURRENCY = 4;
 // shipped defaults of scout, fixer, senior and researcher; absent is fine
-const OPTIONAL_MCP: ReadonlySet<string> = new Set([
-  'codegraph',
-  'context7',
-  'gh_grep',
-]);
+const OPTIONAL_MCP: ReadonlySet<string> = new Set(['codegraph', 'gh_grep']);
 
 const ok = (title: string, detail?: string): Check => ({
   status: 'ok',

package/src/launch.ts

@@ -170,6 +170,39 @@ export const readOnlyLsp: ExtensionFactory = (pi) => {
   });
 };
 
+// A single `ctx7 library|docs ...` (or via npx) with no shell syntax: no
+// separators, pipes, redirects, substitution, variables or newlines.
+export const CTX7_COMMAND = new RegExp(
+  '^\\s*(?:ctx7|npx(?:\\s+(?:-y|--yes))?\\s+ctx7(?:@[\\w.-]+)?)' +
+    '\\s+(?:library|docs)(?:\\s[^;&|`$<>\\r\\n]*)?\\s*$',
+);
+
+// researcher gets a shell only to read library docs through the Context7
+// CLI; everything else is refused.
+export const ctx7OnlyBash: ExtensionFactory = (pi) => {
+  pi.on('tool_call', (event) => {
+    const { command } = event.input as { command?: unknown };
+    const allowed =
+      event.toolName !== 'bash' ||
+      (typeof command === 'string' && CTX7_COMMAND.test(command));
+    return allowed
+      ? undefined
+      : {
+          block: true,
+          reason:
+            'bash is limited to a single `ctx7 library <name> "<query>"` ' +
+            'or `ctx7 docs <libraryId> "<query>"` call (optionally via ' +
+            '`npx -y ctx7@latest`), with no pipes, redirects, `;`, `&`, ' +
+            'substitution or variables',
+        };
+  });
+};
+
+// Agents whose bash tool is restricted, and how.
+const BASH_GUARDS: Readonly<Record<string, ExtensionFactory>> = {
+  researcher: ctx7OnlyBash,
+};
+
 export const buildLaunch = (
   def: AgentDefinition,
   ctx: LaunchContext,
@@ -270,11 +303,13 @@ export const buildLaunch = (
     !tools.includes('write');
   const lazy =
     tools !== undefined && packages.some((name) => LAZY_PACKAGES.has(name));
-  if (vision || readOnly || lazy) {
+  const bashGuard = tools?.includes('bash') ? BASH_GUARDS[def.name] : undefined;
+  if (vision || readOnly || lazy || bashGuard) {
     start.extensionFactories = [
       ...sessionGuards,
       ...(vision ? [vision.tool(def.name)] : []),
       ...(readOnly ? [readOnlyLsp] : []),
+      ...(bashGuard ? [bashGuard] : []),
       ...(lazy && tools ? [activateAllowed(tools)] : []),
     ];
   }

package/src/mcp.ts

@@ -95,11 +95,14 @@ export const resolveMcpTools = (
   if (!existsSync(configPath)) return { tools, errors };
   const config = read(configPath, 'MCP config');
   if (typeof config === 'string') return { tools, errors: [config] };
-  const cache = read(cachePath, 'MCP metadata cache');
-  if (typeof cache === 'string') return { tools, errors: [cache] };
-
   const settings = isRecord(config.settings) ? config.settings : {};
   const defs = isRecord(config.mcpServers) ? config.mcpServers : {};
+  // the cache only matters for servers the config defines
+  if (!servers.some((server) => isRecord(defs[server]))) {
+    return { tools, errors };
+  }
+  const cache = read(cachePath, 'MCP metadata cache');
+  if (typeof cache === 'string') return { tools, errors: [cache] };
   const cached = isRecord(cache.servers) ? cache.servers : {};
   for (const server of servers) {
     const def = defs[server];