goatcode-sh 0.0.1 → 0.1.2

package/src/features/loops/plugin.ts

@@ -0,0 +1,107 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { FileLoopStore } from "./file-store";
+import { createLoopHandler, type LoopHandlerOptions } from "./handler";
+import { MemoryLoopStore } from "./memory-store";
+import { type LoopOptions, type LoopState, type LoopStore } from "./state";
+
+class RoutedLoopStore implements LoopStore {
+  constructor(
+    private readonly memoryStore: MemoryLoopStore,
+    private readonly fileStore: FileLoopStore,
+  ) {}
+
+  startLoop(sessionId: string, options?: LoopOptions): void {
+    if (options?.persist) {
+      this.memoryStore.stopLoop(sessionId);
+      this.fileStore.startLoop(sessionId, options);
+      return;
+    }
+
+    this.fileStore.stopLoop(sessionId);
+    this.memoryStore.startLoop(sessionId, options);
+  }
+
+  stopLoop(sessionId: string): void {
+    this.fileStore.stopLoop(sessionId);
+    this.memoryStore.stopLoop(sessionId);
+  }
+
+  isActive(sessionId: string): boolean {
+    return this.fileStore.isActive(sessionId) || this.memoryStore.isActive(sessionId);
+  }
+
+  getLoopState(sessionId: string): LoopState | undefined {
+    return this.fileStore.getLoopState(sessionId) ?? this.memoryStore.getLoopState(sessionId);
+  }
+
+  incrementIteration(sessionId: string): void {
+    this.fileStore.incrementIteration(sessionId);
+    this.memoryStore.incrementIteration(sessionId);
+  }
+
+  markCompletionDetected(sessionId: string): void {
+    this.fileStore.markCompletionDetected(sessionId);
+    this.memoryStore.markCompletionDetected(sessionId);
+  }
+
+  clearForTests(clearPersistedFile = false): void {
+    this.memoryStore.clearAllForTests();
+    this.fileStore.clearAllForTests(clearPersistedFile);
+  }
+
+  configureFilePathForTests(filePath: string): void {
+    this.fileStore.setStateFilePathForTests(filePath);
+  }
+
+  loadPersistedForTests(): void {
+    this.fileStore.loadPersistedStateForTests();
+  }
+}
+
+export const memoryLoopStore = new MemoryLoopStore();
+export const fileLoopStore = new FileLoopStore();
+export const defaultLoopStore = new RoutedLoopStore(memoryLoopStore, fileLoopStore);
+
+export function startLoop(sessionId: string, options?: LoopOptions): void {
+  defaultLoopStore.startLoop(sessionId, options);
+}
+
+export function stopLoop(sessionId: string): void {
+  defaultLoopStore.stopLoop(sessionId);
+}
+
+export function isLoopActive(sessionId: string): boolean {
+  return defaultLoopStore.isActive(sessionId);
+}
+
+export function getLoopState(sessionId: string): LoopState | undefined {
+  return defaultLoopStore.getLoopState(sessionId);
+}
+
+export function clearLoopStateForTests(clearPersistedFile = false): void {
+  defaultLoopStore.clearForTests(clearPersistedFile);
+}
+
+export function configureLoopStateFilePathForTests(filePath: string): void {
+  defaultLoopStore.configureFilePathForTests(filePath);
+}
+
+export function loadPersistedLoopStateForTests(): void {
+  defaultLoopStore.loadPersistedForTests();
+}
+
+export function createLoopPlugin(options?: LoopHandlerOptions) {
+  const eventHook = safeCreateHook("loop", () => createLoopHandler(defaultLoopStore, options));
+
+  return definePlugin({
+    name: "loop",
+    version: "0.1.0",
+    hooks: eventHook ? { event: eventHook } : {},
+  });
+}
+
+/**
+ * Default plugin registration. The host injects sendContinuationMessage at runtime via createLoopPlugin().
+ */
+export const loopPlugin = createLoopPlugin();

package/src/features/loops/shared/event-utils.ts

@@ -0,0 +1,50 @@
+export interface HookEvent {
+  type?: unknown;
+  properties?: unknown;
+}
+
+type HookInput = { event?: HookEvent };
+
+export function asEvent(input: unknown): HookEvent | null {
+  if (typeof input !== "object" || input === null) {
+    return null;
+  }
+
+  const value = (input as HookInput).event;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+export function getSessionId(properties: unknown): string | null {
+  if (!properties || typeof properties !== "object") {
+    return null;
+  }
+
+  const value = properties as Record<string, unknown>;
+  const sessionID = value.sessionID;
+  const sessionId = value.sessionId;
+  if (typeof sessionID === "string") return sessionID;
+  if (typeof sessionId === "string") return sessionId;
+  return null;
+}
+
+export function defaultCompletionDetector(event: HookEvent, completionPromise: string): boolean {
+  if (!event.properties || typeof event.properties !== "object") {
+    return false;
+  }
+
+  const props = event.properties as Record<string, unknown>;
+  if (props.completionDetected === true) {
+    return true;
+  }
+
+  const lastAssistantMessage = props.lastAssistantMessage;
+  if (typeof lastAssistantMessage !== "string") {
+    return false;
+  }
+
+  return lastAssistantMessage.includes(`<promise>${completionPromise}</promise>`);
+}

package/src/features/loops/state.ts

@@ -0,0 +1,44 @@
+export interface LoopOptions {
+  persist?: boolean;
+  maxIterations?: number;
+}
+
+export interface LoopState {
+  active: boolean;
+  iteration: number;
+  maxIterations: number;
+  completionDetected: boolean;
+  persist: boolean;
+}
+
+export interface LoopStore {
+  startLoop(sessionId: string, options?: LoopOptions): void;
+  stopLoop(sessionId: string): void;
+  isActive(sessionId: string): boolean;
+  getLoopState(sessionId: string): LoopState | undefined;
+  incrementIteration(sessionId: string): void;
+  markCompletionDetected(sessionId: string): void;
+}
+
+export const DEFAULT_MAX_ITERATIONS = 100;
+export const UNBOUNDED_MAX_ITERATIONS = 1000;
+
+export function createInitialLoopState(options?: LoopOptions): LoopState {
+  const persist = options?.persist ?? false;
+  const configuredMaxIterations = options?.maxIterations;
+  if (
+    configuredMaxIterations !== undefined &&
+    (!Number.isSafeInteger(configuredMaxIterations) || configuredMaxIterations <= 0)
+  ) {
+    throw new RangeError("maxIterations must be a positive safe integer");
+  }
+
+  return {
+    active: true,
+    iteration: 0,
+    maxIterations:
+      configuredMaxIterations ?? (persist ? UNBOUNDED_MAX_ITERATIONS : DEFAULT_MAX_ITERATIONS),
+    completionDetected: false,
+    persist,
+  };
+}

package/src/features/prompt-builder/agent-table-builder.ts

@@ -0,0 +1,23 @@
+export interface AgentTableEntry {
+  name: string;
+  description: string;
+  whenToUse: string;
+}
+
+const TABLE_HEADER = "| Agent | Description | When to Use |";
+const TABLE_SEPARATOR = "|-------|-------------|-------------|";
+
+function escapeTableCell(value: string): string {
+  return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+}
+
+export function buildAgentTable(agents: AgentTableEntry[]): string {
+  if (agents.length === 0) return "";
+
+  const rows = agents.map((agent) => {
+    const desc = agent.description.split(".")[0] || agent.description;
+    return `| \`${escapeTableCell(agent.name)}\` | ${escapeTableCell(desc)} | ${escapeTableCell(agent.whenToUse)} |`;
+  });
+
+  return ["### Available Agents", "", TABLE_HEADER, TABLE_SEPARATOR, ...rows].join("\n");
+}

package/src/features/prompt-builder/category-section-builder.ts

@@ -0,0 +1,21 @@
+import type { AvailableCategory } from "../../types/category";
+
+export function buildCategoriesSection(categories: AvailableCategory[]): string {
+  if (categories.length === 0) return "";
+
+  const rows = categories.map((cat) => {
+    const model = cat.model ?? "default";
+    const safeDescription = cat.description.replace(/\|/g, "\\|");
+    return `| \`${cat.name}\` | ${safeDescription} | ${model} |`;
+  });
+
+  return [
+    "### Category Mapping",
+    "",
+    "Each category routes to a model optimized for that domain.",
+    "",
+    "| Category | Description | Model |",
+    "|----------|-------------|-------|",
+    ...rows,
+  ].join("\n");
+}

package/src/features/prompt-builder/dynamic-prompt-builder.ts

@@ -0,0 +1,42 @@
+import type { AvailableCategory } from "../../types/category";
+import { ORCHESTRATOR_PROMPT } from "../../agents/orchestrator/prompt";
+import { log } from "../../shared/logger";
+import { buildAgentTable } from "./agent-table-builder";
+import type { AgentTableEntry } from "./agent-table-builder";
+import { buildSkillsSection } from "./skill-section-builder";
+import type { SkillEntry } from "./skill-section-builder";
+import { buildCategoriesSection } from "./category-section-builder";
+
+export interface DynamicPromptInput {
+  agents: AgentTableEntry[];
+  skills: SkillEntry[];
+  categories: AvailableCategory[];
+}
+
+export function buildDynamicPrompt(input: DynamicPromptInput): string {
+  const sections: string[] = [ORCHESTRATOR_PROMPT];
+
+  const agentSection = buildAgentTable(input.agents);
+  if (agentSection) {
+    sections.push(agentSection);
+  }
+
+  const skillsSection = buildSkillsSection(input.skills);
+  if (skillsSection) {
+    sections.push(skillsSection);
+  }
+
+  const categoriesSection = buildCategoriesSection(input.categories);
+  if (categoriesSection) {
+    sections.push(categoriesSection);
+  }
+
+  const agentCount = input.agents.length;
+  const skillCount = input.skills.length;
+  const categoryCount = input.categories.length;
+  log(
+    `[PromptBuilder] Built dynamic prompt: ${agentCount} agents, ${skillCount} skills, ${categoryCount} categories`,
+  );
+
+  return sections.join("\n\n");
+}

package/src/features/prompt-builder/index.ts

@@ -0,0 +1,7 @@
+export type { AgentTableEntry } from "./agent-table-builder";
+export { buildAgentTable } from "./agent-table-builder";
+export type { SkillEntry } from "./skill-section-builder";
+export { buildSkillsSection } from "./skill-section-builder";
+export { buildCategoriesSection } from "./category-section-builder";
+export type { DynamicPromptInput } from "./dynamic-prompt-builder";
+export { buildDynamicPrompt } from "./dynamic-prompt-builder";

package/src/features/prompt-builder/prompt-builder.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "bun:test";
+
+import type { AgentTableEntry } from "./agent-table-builder";
+import { buildAgentTable } from "./agent-table-builder";
+import type { SkillEntry } from "./skill-section-builder";
+import { buildSkillsSection } from "./skill-section-builder";
+import { buildCategoriesSection } from "./category-section-builder";
+import { buildDynamicPrompt } from "./dynamic-prompt-builder";
+import { ORCHESTRATOR_PROMPT } from "../../agents/orchestrator/prompt";
+import type { AvailableCategory } from "../../types/category";
+
+const SAMPLE_AGENTS: AgentTableEntry[] = [
+  {
+    name: "explorer",
+    description: "Searches the codebase for patterns.",
+    whenToUse: "Need to find code references",
+  },
+  {
+    name: "deep-worker",
+    description: "Autonomous implementation agent.",
+    whenToUse: "Complex multi-file changes",
+  },
+  {
+    name: "advisor",
+    description: "Read-only architecture consultant.",
+    whenToUse: "Design decisions and debugging",
+  },
+];
+
+const SAMPLE_SKILLS: SkillEntry[] = [
+  { name: "playwright", description: "Browser automation and testing." },
+  { name: "git-master", description: "Atomic commits and rebase surgery." },
+];
+
+const SAMPLE_CATEGORIES: AvailableCategory[] = [
+  { name: "visual-engineering", description: "Frontend and UI/UX work", model: "gpt-5.3-codex" },
+  { name: "ultrabrain", description: "Hard logic and architecture", model: "gpt-5.4" },
+  { name: "quick", description: "Trivial single-file fixes", model: "gpt-5-nano" },
+];
+
+describe("prompt-builder", () => {
+  describe("#given buildAgentTable", () => {
+    describe("#when called with agents", () => {
+      it("#then returns markdown table containing all agent names", () => {
+        //#given
+        const agents = SAMPLE_AGENTS;
+
+        //#when
+        const result = buildAgentTable(agents);
+
+        //#then
+        expect(result).toContain("explorer");
+        expect(result).toContain("deep-worker");
+        expect(result).toContain("advisor");
+        expect(result).toContain("| Agent | Description | When to Use |");
+      });
+
+      it("#then truncates descriptions at the first period", () => {
+        //#given
+        const agents: AgentTableEntry[] = [
+          {
+            name: "test-agent",
+            description: "First sentence. Second sentence.",
+            whenToUse: "Always",
+          },
+        ];
+
+        //#when
+        const result = buildAgentTable(agents);
+
+        //#then
+        expect(result).toContain("First sentence");
+        expect(result).not.toContain("Second sentence");
+      });
+
+      it("#then returns full description when no period present", () => {
+        //#given
+        const agents: AgentTableEntry[] = [
+          { name: "test-agent", description: "No period here", whenToUse: "Always" },
+        ];
+
+        //#when
+        const result = buildAgentTable(agents);
+
+        //#then
+        expect(result).toContain("No period here");
+      });
+    });
+
+    describe("#when called with empty array", () => {
+      it("#then returns empty string", () => {
+        //#given #when
+        const result = buildAgentTable([]);
+
+        //#then
+        expect(result).toBe("");
+      });
+    });
+  });
+
+  describe("#given buildSkillsSection", () => {
+    describe("#when called with skills", () => {
+      it("#then returns section containing all skill names", () => {
+        //#given
+        const skills = SAMPLE_SKILLS;
+
+        //#when
+        const result = buildSkillsSection(skills);
+
+        //#then
+        expect(result).toContain("playwright");
+        expect(result).toContain("git-master");
+        expect(result).toContain("### Available Skills");
+      });
+    });
+
+    describe("#when called with empty array", () => {
+      it("#then returns empty string", () => {
+        //#given #when
+        const result = buildSkillsSection([]);
+
+        //#then
+        expect(result).toBe("");
+      });
+    });
+  });
+
+  describe("#given buildCategoriesSection", () => {
+    describe("#when called with categories", () => {
+      it("#then returns table with category names and models", () => {
+        //#given
+        const categories = SAMPLE_CATEGORIES;
+
+        //#when
+        const result = buildCategoriesSection(categories);
+
+        //#then
+        expect(result).toContain("visual-engineering");
+        expect(result).toContain("gpt-5.3-codex");
+        expect(result).toContain("ultrabrain");
+        expect(result).toContain("gpt-5.4");
+        expect(result).toContain("quick");
+        expect(result).toContain("gpt-5-nano");
+      });
+
+      it("#then shows 'default' when model is undefined", () => {
+        //#given
+        const categories: AvailableCategory[] = [
+          { name: "unspecified-low", description: "General purpose" },
+        ];
+
+        //#when
+        const result = buildCategoriesSection(categories);
+
+        //#then
+        expect(result).toContain("default");
+      });
+
+      it("#then escapes pipe characters in descriptions", () => {
+        //#given
+        const categories: AvailableCategory[] = [
+          { name: "test-cat", description: "Contains | pipe character", model: "gpt-5" },
+        ];
+
+        //#when
+        const result = buildCategoriesSection(categories);
+
+        //#then
+        expect(result).toContain("Contains \\| pipe character");
+        expect(result).not.toContain("Contains | pipe character");
+      });
+    });
+
+    describe("#when called with empty array", () => {
+      it("#then returns empty string", () => {
+        //#given #when
+        const result = buildCategoriesSection([]);
+
+        //#then
+        expect(result).toBe("");
+      });
+    });
+  });
+
+  describe("#given buildDynamicPrompt", () => {
+    describe("#when called with agents, skills, and categories", () => {
+      it("#then composes prompt containing base orchestrator prompt and all sections", () => {
+        //#given
+        const input = {
+          agents: SAMPLE_AGENTS,
+          skills: SAMPLE_SKILLS,
+          categories: SAMPLE_CATEGORIES,
+        };
+
+        //#when
+        const result = buildDynamicPrompt(input);
+
+        //#then
+        expect(result).toContain(ORCHESTRATOR_PROMPT);
+        expect(result).toContain("explorer");
+        expect(result).toContain("deep-worker");
+        expect(result).toContain("playwright");
+        expect(result).toContain("git-master");
+        expect(result).toContain("visual-engineering");
+        expect(result).toContain("gpt-5.3-codex");
+      });
+    });
+
+    describe("#when called with empty inputs", () => {
+      it("#then returns only the base orchestrator prompt", () => {
+        //#given
+        const input = { agents: [], skills: [], categories: [] };
+
+        //#when
+        const result = buildDynamicPrompt(input);
+
+        //#then
+        expect(result).toBe(ORCHESTRATOR_PROMPT);
+        expect(result).not.toContain("### Available Agents");
+        expect(result).not.toContain("### Available Skills");
+        expect(result).not.toContain("### Category Mapping");
+      });
+    });
+
+    describe("#when called with partial inputs", () => {
+      it("#then includes only populated sections", () => {
+        //#given
+        const input = {
+          agents: SAMPLE_AGENTS,
+          skills: [],
+          categories: [],
+        };
+
+        //#when
+        const result = buildDynamicPrompt(input);
+
+        //#then
+        expect(result).toContain("### Available Agents");
+        expect(result).not.toContain("### Available Skills");
+        expect(result).not.toContain("### Category Mapping");
+      });
+    });
+  });
+});

package/src/features/prompt-builder/skill-section-builder.ts

@@ -0,0 +1,25 @@
+export interface SkillEntry {
+  name: string;
+  description: string;
+}
+
+function normaliseInline(value: string): string {
+  return value.replace(/\r?\n/g, " ").trim();
+}
+
+export function buildSkillsSection(skills: SkillEntry[]): string {
+  if (skills.length === 0) return "";
+
+  const items = skills.map((skill) => {
+    const shortDesc = skill.description.split(".")[0] || skill.description;
+    return `- \`${normaliseInline(skill.name)}\`: ${normaliseInline(shortDesc)}`;
+  });
+
+  return [
+    "### Available Skills",
+    "",
+    "Use the `skill` tool to load a skill before delegating work.",
+    "",
+    ...items,
+  ].join("\n");
+}

package/src/features/session-state/index.ts

@@ -0,0 +1,17 @@
+export {
+  setSessionState,
+  getSessionState,
+  deleteSessionState,
+  clearSessionStore,
+} from "./session-store";
+export type { SessionState } from "./session-store";
+
+export { consumeNewMessages, resetMessageCursor } from "./session-cursor";
+export type { CursorMessage } from "./session-cursor";
+
+export {
+  setSessionTools,
+  getSessionTools,
+  deleteSessionTools,
+  clearSessionTools,
+} from "./session-tools-store";