@a4hgehad/weave-mcp 0.8.5 → 0.8.7

package/README.md

@@ -301,14 +301,25 @@ All hooks are enabled by default and can be disabled via the `disabled_hooks` co
 
 Weave supports MCP servers for extended capabilities. Built-in MCPs are:
 
-| MCP Server | Purpose | Default Agents |
-|------------|---------|----------------|
-| `websearch` | Web search via Exa AI | loom, tapestry, weft, warp |
-| `context7` | Library documentation lookup | loom, tapestry, spindle |
-| `grep_app` | Enhanced code search | loom, tapestry, thread, spindle, warp, shuttle |
+| MCP Server | Purpose | Type | Default Agents |
+|------------|---------|------|----------------|
+| `websearch` | Web search via Exa AI | Remote | loom, tapestry, weft, warp |
+| `context7` | Library documentation lookup | Remote | loom, tapestry, spindle |
+| `grep_app` | Enhanced code search | Remote | loom, tapestry, thread, spindle, warp, shuttle |
 
 > **Note**: Orchestrator agents (loom, tapestry) get all MCPs by default for maximum capability.
 
+#### Websearch Configuration
+
+The `websearch` MCP uses **EXA's remote MCP server** for web search capabilities. It works out-of-the-box with rate-limited access, but for production use we recommend setting up your EXA API key:
+
+```bash
+# Set EXA API key environment variable
+export EXA_API_KEY="your-exa-api-key"
+```
+
+The plugin automatically detects the `EXA_API_KEY` environment variable and includes it in requests for authenticated access with higher rate limits.
+
 #### Configuration
 
 ```jsonc
@@ -326,9 +337,9 @@ Weave supports MCP servers for extended capabilities. Built-in MCPs are:
   "mcp": {
     "servers": {
       "my-server": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "my-mcp-server"]
+        "type": "local",
+        "command": ["npx", "-y", "my-mcp-server"],
+        "timeout": 60000
       }
     }
   },
@@ -345,6 +356,10 @@ Weave supports MCP servers for extended capabilities. Built-in MCPs are:
 }
 ```
 
+> **MCP Server Types**:
+> - `local` — Runs a local MCP server via command (stdio)
+> - `remote` — Connects to a remote MCP server via HTTP
+
 See [Provider Configurations](./docs/provider-configurations.md) for model recommendations per agent.
 
 ### Skills

package/dist/agents/agent-builder.d.ts

@@ -0,0 +1,49 @@
+import type { AgentConfig } from '@opencode-ai/sdk';
+import type { CategoriesConfig } from '../config/schema';
+import type { AgentSource } from './types';
+export type ResolveSkillsFn = (skillNames: string[], disabledSkills?: Set<string>) => string;
+export type BuildAgentOptions = {
+    categories?: CategoriesConfig;
+    disabledSkills?: Set<string>;
+    resolveSkills?: ResolveSkillsFn;
+    disabledAgents?: Set<string>;
+    agentName?: string;
+    mcpConfig?: string[];
+    enabledMcps?: Set<string>;
+};
+/**
+ * Map from agent config key (lowercase) to display name variants that
+ * might appear in prompt text. Used by stripDisabledAgentReferences to
+ * remove lines that mention disabled agents.
+ *
+ * Exported for test cleanup — tests that call addBuiltinNameVariant
+ * must restore original arrays in afterEach to avoid state pollution.
+ */
+export declare const AGENT_NAME_VARIANTS: Record<string, string[]>;
+/**
+ * Reset the mutable name variants map to its initial state.
+ * Used by tests to prevent cross-test state pollution.
+ */
+export declare function resetNameVariants(): void;
+/**
+ * Register name variants for a custom agent so that
+ * `stripDisabledAgentReferences` can strip its references from prompts.
+ * Does not override existing (builtin) entries.
+ */
+export declare function registerAgentNameVariants(name: string, variants?: string[]): void;
+/**
+ * Add additional name variants for a builtin agent.
+ * Used when a user sets a custom display_name — the custom name
+ * must be included in variants so stripDisabledAgentReferences
+ * can match it when the agent is disabled.
+ * No-op if the config key has no existing variant entry or the variant is already present.
+ */
+export declare function addBuiltinNameVariant(configKey: string, variant: string): void;
+/**
+ * Remove lines from a prompt that reference disabled agents.
+ * Only strips lines where an agent name appears as a standalone concept
+ * (e.g. "Use thread (codebase explorer)"), not incidental word matches.
+ * Uses word-boundary matching to avoid false positives.
+ */
+export declare function stripDisabledAgentReferences(prompt: string, disabled: Set<string>): string;
+export declare function buildAgent(source: AgentSource, model: string, options?: BuildAgentOptions): AgentConfig;

package/dist/agents/builtin-agents.d.ts

@@ -0,0 +1,34 @@
+import type { AgentConfig } from '@opencode-ai/sdk';
+import type { AgentOverrideConfig, CategoriesConfig } from '../config/schema';
+import type { ProjectFingerprint } from '../features/analytics/types';
+import type { ResolveSkillsFn } from './agent-builder';
+import type { AvailableAgent } from './dynamic-prompt-builder';
+import type { AgentPromptMetadata, WeaveAgentName } from './types';
+export interface CreateBuiltinAgentsOptions {
+    disabledAgents?: string[];
+    agentOverrides?: Record<string, AgentOverrideConfig>;
+    categories?: CategoriesConfig;
+    uiSelectedModel?: string;
+    systemDefaultModel?: string;
+    availableModels?: Set<string>;
+    disabledSkills?: Set<string>;
+    resolveSkills?: ResolveSkillsFn;
+    /** Project fingerprint for injecting project context into agent prompts */
+    fingerprint?: ProjectFingerprint | null;
+    /** Custom agent metadata for Loom's dynamic delegation prompt */
+    customAgentMetadata?: AvailableAgent[];
+    /** Set of enabled MCP servers */
+    enabledMcps?: Set<string>;
+}
+export declare const AGENT_METADATA: Record<WeaveAgentName, AgentPromptMetadata>;
+/**
+ * Register metadata for a custom agent. Used by create-managers.ts
+ * to integrate custom agents into Loom's dynamic prompt builder.
+ */
+export declare function registerCustomAgentMetadata(name: string, metadata: AgentPromptMetadata): void;
+/**
+ * Get all agent metadata — builtins + registered custom agents.
+ * Returns a new merged record on each call.
+ */
+export declare function getAllAgentMetadata(): Record<string, AgentPromptMetadata>;
+export declare function createBuiltinAgents(options?: CreateBuiltinAgentsOptions): Record<string, AgentConfig>;

package/dist/agents/custom-agent-factory.d.ts

@@ -0,0 +1,24 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { CustomAgentConfig } from "../config/schema";
+import type { AgentPromptMetadata } from "./types";
+import type { ResolveSkillsFn } from "./agent-builder";
+export interface BuildCustomAgentOptions {
+    resolveSkills?: ResolveSkillsFn;
+    disabledSkills?: Set<string>;
+    availableModels?: Set<string>;
+    systemDefaultModel?: string;
+    uiSelectedModel?: string;
+    /** Base directory for resolving relative prompt_file paths */
+    configDir?: string;
+}
+/**
+ * Build an AgentConfig from a custom agent definition.
+ * Handles prompt resolution (inline, file, or skills), model resolution,
+ * and display name registration.
+ */
+export declare function buildCustomAgent(name: string, config: CustomAgentConfig, options?: BuildCustomAgentOptions): AgentConfig;
+/**
+ * Build AgentPromptMetadata for a custom agent from its config.
+ * Used to integrate custom agents into Loom's delegation table.
+ */
+export declare function buildCustomAgentMetadata(name: string, config: CustomAgentConfig): AgentPromptMetadata;

package/dist/agents/dynamic-prompt-builder.d.ts

@@ -0,0 +1,35 @@
+import type { AgentPromptMetadata } from "./types";
+import type { ProjectFingerprint } from "../features/analytics/types";
+export interface AvailableAgent {
+    name: string;
+    description: string;
+    metadata: AgentPromptMetadata;
+}
+export interface AvailableTool {
+    name: string;
+    category: "lsp" | "ast" | "search" | "session" | "command" | "other";
+}
+export interface AvailableSkill {
+    name: string;
+    description: string;
+    location: "user" | "project" | "builtin";
+}
+export interface AvailableCategory {
+    name: string;
+    description: string;
+    model?: string;
+}
+export declare function categorizeTools(toolNames: string[]): AvailableTool[];
+export declare function buildKeyTriggersSection(agents: AvailableAgent[], _skills?: AvailableSkill[]): string;
+export declare function buildToolSelectionTable(agents: AvailableAgent[], tools?: AvailableTool[], _skills?: AvailableSkill[]): string;
+export declare function buildThreadSection(agents: AvailableAgent[]): string;
+export declare function buildSpindleSection(agents: AvailableAgent[]): string;
+export declare function buildWeftSection(agents: AvailableAgent[]): string;
+export declare function buildWarpSection(agents: AvailableAgent[]): string;
+export declare function buildDelegationTable(agents: AvailableAgent[]): string;
+export declare function buildCategorySkillsDelegationGuide(categories: AvailableCategory[], skills: AvailableSkill[]): string;
+/**
+ * Build a project context section from a codebase fingerprint.
+ * Returns an empty string if no fingerprint is available.
+ */
+export declare function buildProjectContextSection(fingerprint: ProjectFingerprint | null | undefined): string;

package/dist/agents/index.d.ts

@@ -0,0 +1,12 @@
+export { createBuiltinAgents, AGENT_METADATA, registerCustomAgentMetadata, getAllAgentMetadata } from "./builtin-agents";
+export type { CreateBuiltinAgentsOptions } from "./builtin-agents";
+export { buildAgent, stripDisabledAgentReferences } from "./agent-builder";
+export type { BuildAgentOptions, ResolveSkillsFn } from "./agent-builder";
+export { resolveAgentModel, AGENT_MODEL_REQUIREMENTS } from "./model-resolution";
+export type { FallbackEntry, AgentModelRequirement, ResolveAgentModelOptions } from "./model-resolution";
+export { buildCustomAgent, buildCustomAgentMetadata } from "./custom-agent-factory";
+export type { BuildCustomAgentOptions } from "./custom-agent-factory";
+export { loadPromptFile } from "./prompt-loader";
+export * from "./dynamic-prompt-builder";
+export type { AgentMode, AgentFactory, AgentSource, AgentCategory, AgentCost, DelegationTrigger, AgentPromptMetadata, WeaveAgentName, } from "./types";
+export { isFactory, isGptModel } from "./types";

package/dist/agents/loom/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const LOOM_DEFAULTS: AgentConfig;

package/dist/agents/loom/index.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentFactory } from "../types";
+import type { AvailableAgent } from "../dynamic-prompt-builder";
+import type { ProjectFingerprint } from "../../features/analytics/types";
+export { composeLoomPrompt } from "./prompt-composer";
+export type { LoomPromptOptions } from "./prompt-composer";
+/**
+ * Create a Loom agent config with optional disabled agents, fingerprint, and custom agents for prompt composition.
+ */
+export declare function createLoomAgentWithOptions(model: string, disabledAgents?: Set<string>, fingerprint?: ProjectFingerprint | null, customAgents?: AvailableAgent[]): AgentConfig;
+export declare const createLoomAgent: AgentFactory;

package/dist/agents/loom/prompt-composer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Loom prompt composer — assembles the Loom system prompt from sections,
+ * conditionally including/excluding content based on enabled agents.
+ *
+ * Default behavior (no disabled agents) produces identical output to the
+ * hardcoded LOOM_DEFAULTS.prompt string.
+ */
+import type { ProjectFingerprint } from "../../features/analytics/types";
+import type { AvailableAgent } from "../dynamic-prompt-builder";
+export interface LoomPromptOptions {
+    /** Set of disabled agent names (lowercase config keys) */
+    disabledAgents?: Set<string>;
+    /** Project fingerprint for injecting project context into the prompt */
+    fingerprint?: ProjectFingerprint | null;
+    /** Custom agent metadata for dynamic delegation sections */
+    customAgents?: AvailableAgent[];
+}
+export declare function buildRoleSection(): string;
+export declare function buildDisciplineSection(): string;
+export declare function buildSidebarTodosSection(): string;
+export declare function buildDelegationSection(disabled: Set<string>): string;
+export declare function buildDelegationNarrationSection(disabled?: Set<string>): string;
+export declare function buildPlanWorkflowSection(disabled: Set<string>): string;
+export declare function buildReviewWorkflowSection(disabled: Set<string>): string;
+export declare function buildStyleSection(): string;
+/**
+ * Build a delegation section for custom agents.
+ * Returns empty string if no enabled custom agents exist.
+ */
+export declare function buildCustomAgentDelegationSection(customAgents: AvailableAgent[], disabled: Set<string>): string;
+/**
+ * Compose the full Loom system prompt from sections.
+ * When no agents are disabled, produces identical output to LOOM_DEFAULTS.prompt.
+ */
+export declare function composeLoomPrompt(options?: LoomPromptOptions): string;

package/dist/agents/model-resolution.d.ts

@@ -0,0 +1,27 @@
+import type { AgentMode, WeaveAgentName } from "./types";
+export type FallbackEntry = {
+    providers: string[];
+    model: string;
+    variant?: string;
+};
+export type AgentModelRequirement = {
+    fallbackChain: FallbackEntry[];
+};
+export declare const AGENT_MODEL_REQUIREMENTS: Record<WeaveAgentName, AgentModelRequirement>;
+export type ResolveAgentModelOptions = {
+    availableModels: Set<string>;
+    agentMode: AgentMode;
+    uiSelectedModel?: string;
+    categoryModel?: string;
+    overrideModel?: string;
+    systemDefaultModel?: string;
+    /** Custom fallback chain for agents not in AGENT_MODEL_REQUIREMENTS */
+    customFallbackChain?: FallbackEntry[];
+};
+/**
+ * Resolve the model for an agent. Accepts any string agent name.
+ * Built-in agents use AGENT_MODEL_REQUIREMENTS for fallback chains.
+ * Custom agents use the customFallbackChain option, or fall through
+ * to system default / hardcoded fallback.
+ */
+export declare function resolveAgentModel(agentName: string, options: ResolveAgentModelOptions): string;

package/dist/agents/pattern/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const PATTERN_DEFAULTS: AgentConfig;

package/dist/agents/pattern/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createPatternAgent: AgentFactory;

package/dist/agents/prompt-loader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Load a prompt from a file path. Supports .md and .txt files.
+ * Paths are sandboxed to basePath (or cwd) — traversal outside is rejected.
+ *
+ * @param promptFilePath - Path to the prompt file (relative to basePath; absolute paths are rejected)
+ * @param basePath - Base directory for resolving relative paths (defaults to cwd)
+ * @returns The file contents as a string, or null if the file doesn't exist or path escapes the sandbox
+ */
+export declare function loadPromptFile(promptFilePath: string, basePath?: string): string | null;

package/dist/agents/prompt-utils.d.ts

@@ -0,0 +1,2 @@
+/** Check whether an agent is enabled (not in the disabled set). */
+export declare function isAgentEnabled(name: string, disabled: Set<string>): boolean;

package/dist/agents/shuttle/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const SHUTTLE_DEFAULTS: AgentConfig;

package/dist/agents/shuttle/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createShuttleAgent: AgentFactory;

package/dist/agents/spindle/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const SPINDLE_DEFAULTS: AgentConfig;

package/dist/agents/spindle/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createSpindleAgent: AgentFactory;

package/dist/agents/tapestry/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const TAPESTRY_DEFAULTS: AgentConfig;

package/dist/agents/tapestry/index.d.ts

@@ -0,0 +1,9 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentFactory } from "../types";
+export { composeTapestryPrompt } from "./prompt-composer";
+export type { TapestryPromptOptions } from "./prompt-composer";
+/**
+ * Create a Tapestry agent config with optional disabled agents for prompt composition.
+ */
+export declare function createTapestryAgentWithOptions(model: string, disabledAgents?: Set<string>): AgentConfig;
+export declare const createTapestryAgent: AgentFactory;

package/dist/agents/tapestry/prompt-composer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tapestry prompt composer — assembles the Tapestry system prompt from sections,
+ * conditionally including/excluding content based on enabled agents.
+ *
+ * Default behavior (no disabled agents) produces identical output to the
+ * hardcoded TAPESTRY_DEFAULTS.prompt string.
+ */
+export interface TapestryPromptOptions {
+    /** Set of disabled agent names (lowercase config keys) */
+    disabledAgents?: Set<string>;
+}
+export declare function buildTapestryRoleSection(): string;
+export declare function buildTapestryDisciplineSection(): string;
+export declare function buildTapestrySidebarTodosSection(): string;
+export declare function buildTapestryPlanExecutionSection(disabled?: Set<string>): string;
+export declare function buildTapestryVerificationSection(): string;
+export declare function buildTapestryPostExecutionReviewSection(disabled: Set<string>): string;
+export declare function buildTapestryExecutionSection(): string;
+export declare function buildTapestryStyleSection(): string;
+/**
+ * Compose the full Tapestry system prompt from sections.
+ * When no agents are disabled, produces identical output to TAPESTRY_DEFAULTS.prompt.
+ */
+export declare function composeTapestryPrompt(options?: TapestryPromptOptions): string;

package/dist/agents/thread/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const THREAD_DEFAULTS: AgentConfig;

package/dist/agents/thread/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createThreadAgent: AgentFactory;

package/dist/agents/types.d.ts

@@ -0,0 +1,82 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+/**
+ * Agent mode determines UI model selection behavior:
+ * - "primary": Respects user's UI-selected model (loom, tapestry)
+ * - "subagent": Uses own fallback chain, ignores UI selection (pattern, thread, spindle)
+ * - "all": Available in both contexts (shuttle)
+ */
+export type AgentMode = "primary" | "subagent" | "all";
+/**
+ * Agent factory function with static mode property.
+ * Mode is exposed as static property for pre-instantiation access.
+ */
+export type AgentFactory = ((model: string) => AgentConfig) & {
+    mode: AgentMode;
+};
+/**
+ * Agent source is either a factory (called with model) or a static config (cloned)
+ */
+export type AgentSource = AgentFactory | AgentConfig;
+/**
+ * Agent category for grouping in Loom prompt sections
+ */
+export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility";
+/**
+ * Cost classification for Tool Selection table
+ */
+export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE";
+/**
+ * Delegation trigger for Loom prompt's Delegation Table
+ */
+export interface DelegationTrigger {
+    /** Domain of work (e.g., "Frontend UI/UX") */
+    domain: string;
+    /** When to delegate (e.g., "Visual changes only...") */
+    trigger: string;
+}
+/**
+ * Metadata for generating Loom prompt sections dynamically.
+ * Allows adding/removing agents without manually updating the Loom prompt.
+ */
+export interface AgentPromptMetadata {
+    /** Category for grouping in prompt sections */
+    category: AgentCategory;
+    /** Cost classification for Tool Selection table */
+    cost: AgentCost;
+    /** Domain triggers for Delegation Table */
+    triggers: DelegationTrigger[];
+    /** When to use this agent (for detailed sections) */
+    useWhen?: string[];
+    /** When NOT to use this agent */
+    avoidWhen?: string[];
+    /** Optional dedicated prompt section (markdown) */
+    dedicatedSection?: string;
+    /** Nickname/alias used in prompt (e.g., "Pattern" instead of "pattern") */
+    promptAlias?: string;
+    /** Key trigger that should appear in Phase 0 quick checks */
+    keyTrigger?: string;
+}
+/**
+ * The 8 built-in Weave agent names
+ */
+export type WeaveAgentName = "loom" | "tapestry" | "shuttle" | "pattern" | "thread" | "spindle" | "weft" | "warp";
+/**
+ * Override config for a single agent — all fields optional
+ */
+export type AgentOverrideConfig = Partial<AgentConfig> & {
+    prompt_append?: string;
+    variant?: string;
+    fallback_models?: string | string[];
+};
+/**
+ * Map of agent name to override config
+ */
+export type AgentOverrides = Partial<Record<WeaveAgentName, AgentOverrideConfig>>;
+/**
+ * Returns true if the model string identifies a GPT/OpenAI model.
+ */
+export declare function isGptModel(model: string): boolean;
+/**
+ * Type guard: returns true if source is an AgentFactory (callable with .mode).
+ */
+export declare function isFactory(source: AgentSource): source is AgentFactory;

package/dist/agents/warp/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const WARP_DEFAULTS: AgentConfig;

package/dist/agents/warp/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createWarpAgent: AgentFactory;

package/dist/agents/weft/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const WEFT_DEFAULTS: AgentConfig;

package/dist/agents/weft/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createWeftAgent: AgentFactory;

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./schema";
+export { loadWeaveConfig } from "./loader";
+export { mergeConfigs } from "./merge";

package/dist/config/loader.d.ts

@@ -0,0 +1,2 @@
+import { type WeaveConfig } from "./schema";
+export declare function loadWeaveConfig(directory: string, _ctx?: unknown, _homeDir?: string): WeaveConfig;

package/dist/config/merge.d.ts

@@ -0,0 +1,3 @@
+import type { WeaveConfig } from "./schema";
+import type { DeepPartial } from "../shared/types";
+export declare function mergeConfigs(user: DeepPartial<WeaveConfig>, project: DeepPartial<WeaveConfig>): DeepPartial<WeaveConfig>;