goatcode-sh 0.0.1 → 0.1.3

package/src/agents/researcher/prompt.ts

@@ -0,0 +1,116 @@
+export const RESEARCHER_PROMPT = `# Role
+You are GoatCode's external research specialist.
+You gather high-quality, current, and citable evidence from documentation, code search, and authoritative sources.
+
+Your output must help implementation decisions, not just list links.
+
+# Primary Responsibilities
+- Classify research intent.
+- Discover authoritative sources first.
+- Run parallel searches across varied query angles.
+- Synthesize findings with explicit citations.
+- Distinguish confirmed facts from open questions.
+
+# Request Classification (Mandatory)
+Classify each request before searching:
+
+## TYPE A - Conceptual
+- User needs explanation, terminology, or best-practice overview.
+
+## TYPE B - Implementation
+- User needs concrete API usage, examples, signatures, or config.
+
+## TYPE C - Context / Change History
+- User needs "why" behind behavior, version changes, migration notes.
+
+## TYPE D - Comprehensive
+- User needs broad comparison, decision support, or deep investigation.
+
+Classification determines search breadth and synthesis depth.
+
+# Documentation Discovery Protocol
+Always attempt official docs first.
+
+## Ordered Source Priority
+1) Official project documentation / specs.
+2) Official repo docs (README, release notes, migration docs).
+3) Maintainer-authored guides/issues/PRs.
+4) High-quality community sources.
+
+If official docs conflict with community content, prefer official sources and call out discrepancy.
+
+# Search Strategy
+
+## Parallelization Requirement
+- Launch multiple independent searches in parallel.
+- Vary query phrasing and focus per call.
+- Do not run near-duplicate searches with identical terms.
+
+## Query Variation Axes
+- API name and signature variants.
+- Version-specific phrasing.
+- Error-message-based query.
+- "official docs" discovery query.
+- "migration" / "breaking changes" query.
+
+# Date and Version Awareness
+- Treat current year as authoritative temporal anchor.
+- For "latest" requests, verify recency and version explicitly.
+- If user specifies a version, prioritize matching docs/examples for that version.
+- Flag when evidence is stale or version-ambiguous.
+
+# Citation Policy (Mandatory)
+Every material claim must include a source URL.
+
+## Citation Format
+- Claim
+- Source URL
+- Why source is relevant/trustworthy
+
+Avoid uncited claims for behavior, compatibility, defaults, or security guidance.
+
+# Synthesis Standard
+Do not dump search results.
+
+For each answer, provide:
+- Direct recommendation for user's question.
+- Key evidence points grouped by agreement/conflict.
+- Decision implications (what to do next).
+- Open uncertainties and how to resolve them.
+
+# Anti-Patterns to Avoid
+- Presenting outdated snippets as current best practice.
+- Using only one source when conflict risk is high.
+- Treating forum comments as canonical.
+- Hiding uncertainty.
+- Overly long narrative without actionable conclusion.
+
+# Tool Guidance
+- Use web/doc/code-search tools appropriate to request type.
+- Prefer structured doc-query tools for official API details.
+- Use web crawl/fetch for exact wording when precision matters.
+- Use repository search for real-world implementation patterns.
+
+# Output Format
+
+## 1. Classification
+Request type and rationale.
+
+## 2. Findings
+Bullet points with citations.
+
+## 3. Recommendation
+Concrete answer for immediate next action.
+
+## 4. Caveats
+Version assumptions, conflicts, and unknowns.
+
+## 5. Optional Next Queries
+Only if additional research would materially change implementation.
+
+# Hard Constraints
+- Never modify local files.
+- Never claim certainty without supporting evidence.
+- Never omit citations for technical claims.
+- Never prioritize popularity over source authority.
+`;

package/src/agents/tool-restrictions.ts

@@ -0,0 +1,87 @@
+export type ToolRestriction = {
+  denied?: string[];
+  allowed?: string[];
+};
+
+const ALL_KNOWN_TOOLS = [
+  // Core file operations (OpenCode built-ins)
+  "read",
+  "write",
+  "edit",
+  "bash",
+  "glob",
+  "grep",
+  "task",
+  "todowrite",
+  // LSP tools
+  "lsp_goto_definition",
+  "lsp_find_references",
+  "lsp_symbols",
+  "lsp_diagnostics",
+  "lsp_prepare_rename",
+  "lsp_rename",
+  // AST tools
+  "ast_grep_search",
+  "ast_grep_replace",
+  // Web tools
+  "webfetch",
+  "websearch",
+  "codesearch",
+  // GoatCode custom tools
+  "hashline_edit",
+  "interactive_bash",
+  "look_at",
+  "delegate_task",
+  "background_output",
+  "background_cancel",
+  "session_list",
+  "session_read",
+  "session_search",
+  "session_info",
+  "skill",
+  "skill_mcp",
+  "task_create",
+  "task_list",
+  "task_get",
+  "task_update",
+];
+
+export const AGENT_TOOL_RESTRICTIONS: Record<string, ToolRestriction> = {
+  advisor: {
+    denied: [
+      "write",
+      "edit",
+      "bash",
+      "interactive_bash",
+      "delegate_task",
+      "task_create",
+      "task_update",
+    ],
+  },
+};
+
+export function getToolRestrictions(agentName: string): ToolRestriction {
+  return AGENT_TOOL_RESTRICTIONS[agentName] ?? { denied: [] };
+}
+
+export function buildToolsMap(agentName: string): Record<string, boolean> | undefined {
+  const restriction = AGENT_TOOL_RESTRICTIONS[agentName];
+  if (!restriction) return undefined;
+
+  const tools: Record<string, boolean> = {};
+
+  if (restriction.allowed) {
+    for (const tool of ALL_KNOWN_TOOLS) {
+      tools[tool] = false;
+    }
+    for (const tool of restriction.allowed) {
+      tools[tool] = true;
+    }
+  } else if (restriction.denied) {
+    for (const tool of restriction.denied) {
+      tools[tool] = false;
+    }
+  }
+
+  return Object.keys(tools).length > 0 ? tools : undefined;
+}

package/src/agents/worker/config.ts

@@ -0,0 +1,6 @@
+import type { AgentMode } from "../../types/agent";
+import { DEFAULT_TEMPERATURE } from "../../config/defaults";
+
+export const WORKER_TEMPERATURE = DEFAULT_TEMPERATURE;
+export const WORKER_MODE: AgentMode = "subagent";
+export const WORKER_FALLBACK_MODELS = ["gpt-5.3-codex"];

package/src/agents/worker/index.ts

@@ -0,0 +1,2 @@
+export { workerPlugin } from "./plugin";
+export * from "./config";

package/src/agents/worker/plugin.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "bun:test";
+import { workerPlugin } from "./plugin";
+
+describe("workerPlugin", () => {
+  describe("#given the worker plugin", () => {
+    describe("#when inspecting plugin metadata", () => {
+      it("#then has the correct plugin name", () => {
+        expect(workerPlugin.name).toBe("worker");
+      });
+    });
+
+    describe("#when inspecting the agent config", () => {
+      it("#then mode is 'subagent'", () => {
+        const agent = workerPlugin.agents!.worker;
+        expect(agent.mode).toBe("subagent");
+      });
+
+      it("#then has a temperature and non-empty prompt", () => {
+        const agent = workerPlugin.agents!.worker;
+        expect(typeof agent.temperature).toBe("number");
+        expect(typeof agent.prompt).toBe("string");
+        expect(agent.prompt!.length).toBeGreaterThan(0);
+      });
+
+      it("#then does not define tool restrictions", () => {
+        const agent = workerPlugin.agents!.worker;
+        expect(agent.tools).toBeUndefined();
+      });
+    });
+  });
+});

package/src/agents/worker/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin } from "../../plugin-api";
+import { WORKER_TEMPERATURE, WORKER_MODE } from "./config";
+import { WORKER_PROMPT } from "./prompt";
+
+export const workerPlugin = definePlugin({
+  name: "worker",
+  version: "0.1.0",
+  agents: {
+    worker: {
+      temperature: WORKER_TEMPERATURE,
+      mode: WORKER_MODE,
+      prompt: WORKER_PROMPT,
+    },
+  },
+});

package/src/agents/worker/prompt-meta.ts

@@ -0,0 +1,14 @@
+import type { PromptMeta } from "../prompt-meta";
+
+export const WORKER_PROMPT_META: PromptMeta = {
+  version: "1.0.0",
+  date: "2025-03-28",
+  summary: "Executes assigned atomic tasks with concrete completion evidence.",
+  changelog: [
+    {
+      version: "1.0.0",
+      date: "2025-03-28",
+      description: "Production-grade prompt with structured sections and quality gates",
+    },
+  ],
+};

package/src/agents/worker/prompt.ts

@@ -0,0 +1,83 @@
+export const WORKER_PROMPT = `# Role
+You are GoatCode's focused execution worker.
+You are assigned one bounded task. Complete it fully, verify it, and report evidence.
+
+You do not broaden scope.
+
+# Execution Contract
+- Deliver exactly the assigned outcome.
+- Follow the assigned category/domain conventions.
+- Keep changes minimal and targeted.
+- Verify before claiming completion.
+
+# Working Method
+
+## 1) Parse Assignment
+- Extract explicit requirements.
+- Extract implicit constraints from context.
+- Identify acceptance checks before editing.
+
+## 2) Execute Precisely
+- Edit only relevant files.
+- Match existing style and architecture.
+- Avoid incidental refactors.
+
+## 3) Verify Rigorously
+- Run diagnostics for changed files.
+- Run build/test commands required by task.
+- Confirm outputs, not assumptions.
+
+## 4) Report
+- What was changed.
+- Why it satisfies requirements.
+- Verification evidence.
+- Any unresolved blockers.
+
+# Category Alignment
+Respect category intent (e.g., quick fix, deep logic, visual work).
+If category guidance and assignment conflict, prioritize explicit assignment and note the conflict.
+
+# Scope Discipline
+- Do not pick up adjacent tasks.
+- Do not add "nice to have" enhancements.
+- Do not redesign architecture unless explicitly required.
+
+# Evidence Standard
+No completion claim without command evidence.
+
+Evidence examples:
+- LSP diagnostics output (clean).
+- Build command exit code 0.
+- Test command pass output.
+
+If verification fails:
+- Report failure honestly.
+- Include failure details.
+- Provide next corrective action.
+
+# Anti-Patterns to Avoid
+- Assuming correctness without running checks.
+- Touching unrelated files "while here".
+- Hiding uncertainty.
+- Excessive rewrites for small tasks.
+- Type safety bypasses as shortcut fixes.
+
+# Tool Usage Guidance
+- Use search/read tools to localize changes fast.
+- Use edit tools surgically.
+- Use bash for reproducible verification commands.
+- Use diagnostics before final response.
+
+# Hard Constraints
+- No delegation: execute task yourself.
+- No as any, @ts-ignore, @ts-expect-error.
+- No commits/pushes unless user explicitly requests.
+- No task expansion beyond assigned objective.
+
+# Completion Checklist
+- Assigned objective fully met.
+- Only relevant files changed.
+- Diagnostics clean on changed files.
+- Build/test checks passed as required.
+- Final response includes concrete evidence.
+`;

package/src/bootstrap.integration.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, it, mock } from "bun:test";
+
+const BOOTSTRAP_TEST_DIRECTORY = "/tmp/bootstrap-integration-test-project";
+
+let loadConfigImpl: (projectDir: string) => Promise<unknown> = async () => undefined;
+let realLoadConfig: ((projectDir: string) => Promise<unknown>) | null = null;
+const originalStructuredClone = globalThis.structuredClone;
+
+const passthroughStructuredClone = ((value: unknown) => value) as typeof structuredClone;
+
+mock.module("./config/loader", () => ({
+  loadConfig: (projectDir: string) => {
+    if (projectDir === BOOTSTRAP_TEST_DIRECTORY) {
+      return loadConfigImpl(projectDir);
+    }
+    if (!realLoadConfig) {
+      throw new Error("real loadConfig is not initialized");
+    }
+    return realLoadConfig(projectDir);
+  },
+}));
+
+import { bootstrap } from "./bootstrap";
+import { createMockPluginContext } from "./test-utils/mock-plugin-context";
+
+const unmockedLoaderModule = (await import(`./config/loader.ts?unmocked=${Date.now()}`)) as {
+  loadConfig: (projectDir: string) => Promise<unknown>;
+};
+realLoadConfig = unmockedLoaderModule.loadConfig;
+
+function createBootstrapContext() {
+  return createMockPluginContext({ directory: BOOTSTRAP_TEST_DIRECTORY });
+}
+
+const EXPECTED_TOOL_NAMES = [
+  "grep",
+  "glob",
+  "hashline_edit",
+  "look_at",
+  "skill",
+  "task",
+  "lsp_goto_definition",
+  "lsp_find_references",
+  "lsp_symbols",
+  "lsp_diagnostics",
+  "lsp_prepare_rename",
+  "lsp_rename",
+  "ast_grep_search",
+  "ast_grep_replace",
+  "background_output",
+  "background_cancel",
+  "session_list",
+  "session_read",
+  "session_search",
+  "session_info",
+  "task_create",
+  "task_list",
+  "task_get",
+  "task_update",
+] as const;
+
+const EXPECTED_AGENT_NAMES = [
+  "orchestrator",
+  "deep-worker",
+  "planner",
+  "advisor",
+  "researcher",
+  "explorer",
+  "worker",
+] as const;
+
+describe("bootstrap", () => {
+  afterEach(() => {
+    loadConfigImpl = async () => undefined;
+    globalThis.structuredClone = originalStructuredClone;
+  });
+
+  describe("#given default config", () => {
+    describe("#when bootstrap is executed", () => {
+      it("#then registers all built-in GoatCode tools in hooks.tool", async () => {
+        globalThis.structuredClone = passthroughStructuredClone;
+        const hooks = await bootstrap(createBootstrapContext());
+
+        expect(hooks.tool).toBeDefined();
+        for (const name of EXPECTED_TOOL_NAMES) {
+          expect(hooks.tool?.[name]).toBeDefined();
+        }
+      });
+
+      it("#then registers all built-in GoatCode agents through the config hook", async () => {
+        globalThis.structuredClone = passthroughStructuredClone;
+        const hooks = await bootstrap(createBootstrapContext());
+        expect(hooks.config).toBeDefined();
+
+        if (!hooks.config) {
+          throw new Error("Expected hooks.config to be defined");
+        }
+
+        type ConfigInput = Parameters<NonNullable<typeof hooks.config>>[0];
+        const input = { agent: {} } as ConfigInput;
+
+        await hooks.config(input);
+
+        const configuredAgents = input.agent ?? {};
+        for (const name of EXPECTED_AGENT_NAMES) {
+          expect(configuredAgents[name]).toBeDefined();
+        }
+        const configuredAgentNames = Object.keys(configuredAgents);
+        const allowedExtraAgents = new Set(["build", "plan"]);
+        const unexpectedAgents = configuredAgentNames.filter(
+          (name) =>
+            !EXPECTED_AGENT_NAMES.includes(name as (typeof EXPECTED_AGENT_NAMES)[number]) &&
+            !allowedExtraAgents.has(name),
+        );
+        expect(unexpectedAgents).toEqual([]);
+        expect(configuredAgentNames.length).toBeGreaterThanOrEqual(EXPECTED_AGENT_NAMES.length);
+      });
+
+      it("#then exposes key hook event slots as callable functions", async () => {
+        globalThis.structuredClone = passthroughStructuredClone;
+        const hooks = await bootstrap(createBootstrapContext());
+
+        expect(typeof hooks["tool.execute.before"]).toBe("function");
+        expect(typeof hooks["tool.execute.after"]).toBe("function");
+        expect(typeof hooks["chat.params"]).toBe("function");
+        expect(typeof hooks["tool.definition"]).toBe("function");
+      });
+    });
+  });
+
+  describe("#given invalid raw config from loader", () => {
+    describe("#when bootstrap is executed", () => {
+      it("#then falls back to defaults, returns hooks, and warns to stderr", async () => {
+        loadConfigImpl = async () => ({ agents: "invalid" });
+        globalThis.structuredClone = passthroughStructuredClone;
+
+        const originalStderrWrite = process.stderr.write;
+        const stderrWriteSpy = mock((..._args: unknown[]) => true);
+        process.stderr.write = stderrWriteSpy as typeof process.stderr.write;
+
+        try {
+          const hooks = await bootstrap(createBootstrapContext());
+
+          expect(hooks.tool).toBeDefined();
+          expect(hooks.tool?.grep).toBeDefined();
+          expect(stderrWriteSpy).toHaveBeenCalled();
+          expect(stderrWriteSpy.mock.calls[0]?.[0]).toContain("validation errors");
+        } finally {
+          process.stderr.write = originalStderrWrite;
+        }
+      });
+    });
+  });
+
+  describe("#given disabled_tools config", () => {
+    describe("#when bootstrap is executed", () => {
+      it("#then excludes disabled tools from hooks.tool", async () => {
+        loadConfigImpl = async () => ({ disabled_tools: ["grep"] });
+        globalThis.structuredClone = passthroughStructuredClone;
+
+        const hooks = await bootstrap(createBootstrapContext());
+
+        expect(hooks.tool?.grep).toBeUndefined();
+        expect(hooks.tool?.glob).toBeDefined();
+      });
+    });
+  });
+});