goatcode-sh 0.0.1 → 0.1.3

package/src/features/background-agent/poller.ts

@@ -0,0 +1,75 @@
+import { log } from "../../shared/logger";
+
+export const POLLING_INTERVAL_MS = 3_000;
+export const STABILITY_REQUIRED_POLLS = 2;
+
+export type PollState = {
+  lastMessageCount: number;
+  stablePolls: number;
+};
+
+export type PollSnapshot = {
+  messageCount: number;
+  isIdle: boolean;
+  result?: string;
+};
+
+export function createPollState(): PollState {
+  return { lastMessageCount: -1, stablePolls: 0 };
+}
+
+export function checkStability(
+  state: PollState,
+  currentMessageCount: number,
+  isIdle: boolean,
+): { stable: boolean; nextState: PollState } {
+  if (!isIdle) {
+    return {
+      stable: false,
+      nextState: { lastMessageCount: currentMessageCount, stablePolls: 0 },
+    };
+  }
+
+  if (currentMessageCount === state.lastMessageCount) {
+    const stablePolls = state.stablePolls + 1;
+    return {
+      stable: stablePolls >= STABILITY_REQUIRED_POLLS,
+      nextState: { lastMessageCount: currentMessageCount, stablePolls },
+    };
+  }
+
+  return {
+    stable: false,
+    nextState: { lastMessageCount: currentMessageCount, stablePolls: 0 },
+  };
+}
+
+export async function pollUntilStable(
+  fetchSnapshot: () => Promise<PollSnapshot>,
+  maxPolls = 120,
+  signal?: AbortSignal,
+): Promise<PollSnapshot> {
+  let state = createPollState();
+
+  for (let attempt = 0; attempt < maxPolls; attempt += 1) {
+    if (signal?.aborted) {
+      throw new Error("Polling cancelled");
+    }
+
+    const latest = await fetchSnapshot();
+    const { stable, nextState } = checkStability(state, latest.messageCount, latest.isIdle);
+    state = nextState;
+
+    if (stable) {
+      log("[poller] Session reached stable completion", {
+        messageCount: latest.messageCount,
+        stablePolls: state.stablePolls,
+      });
+      return latest;
+    }
+
+    await new Promise<void>((resolve) => setTimeout(resolve, POLLING_INTERVAL_MS));
+  }
+
+  throw new Error("Background polling timed out before reaching stable completion");
+}

package/src/features/background-agent/singleton.ts

@@ -0,0 +1,26 @@
+import { BackgroundAgentManager } from "./manager";
+
+export type BackgroundAgentContext = {
+  manager: BackgroundAgentManager;
+};
+
+let instance: BackgroundAgentContext | undefined;
+
+export function initBackgroundAgent(): BackgroundAgentContext {
+  instance = {
+    manager: new BackgroundAgentManager(),
+  };
+  return instance;
+}
+
+export function getBackgroundAgent(): BackgroundAgentContext {
+  if (!instance) {
+    throw new Error("BackgroundAgent not initialized. Call initBackgroundAgent first.");
+  }
+  return instance;
+}
+
+export function resetBackgroundAgent(): void {
+  instance?.manager.dispose();
+  instance = undefined;
+}

package/src/features/background-agent/spawner.ts

@@ -0,0 +1,51 @@
+import type { OpenCodeContext } from "../../types/plugin";
+
+import { log } from "../../shared/logger";
+import { parseModelId } from "../../shared/model-normalization";
+import { qualifyModel } from "../../shared/provider-registry";
+
+import type { LaunchInput } from "./types";
+
+export type SpawnResult = {
+  sessionId: string;
+};
+
+export async function spawnBackgroundSession(
+  ctx: OpenCodeContext,
+  input: LaunchInput,
+): Promise<SpawnResult> {
+  log("[spawner] Spawning background session", {
+    id: input.id,
+    model: input.model,
+  });
+
+  const createResult = await ctx.client.session.create({
+    body: {
+      title: `bg:${input.id}`,
+    },
+    query: {
+      directory: ctx.directory,
+    },
+  });
+
+  if (createResult.error) {
+    throw new Error(`Failed to create background session: ${String(createResult.error)}`);
+  }
+
+  const sessionId = createResult.data.id;
+
+  const parsed = parseModelId(qualifyModel(input.model));
+  const promptResult = await ctx.client.session.promptAsync({
+    path: { id: sessionId },
+    body: {
+      parts: [{ type: "text", text: input.prompt }],
+      ...(parsed && { model: { providerID: parsed.provider, modelID: parsed.modelId } }),
+    },
+  });
+
+  if (promptResult.error) {
+    throw new Error(`Failed to send prompt to background session: ${String(promptResult.error)}`);
+  }
+
+  return { sessionId };
+}

package/src/features/background-agent/types.ts

@@ -0,0 +1,20 @@
+export type BackgroundTaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+
+export interface BackgroundTask {
+  id: string;
+  sessionId?: string;
+  status: BackgroundTaskStatus;
+  prompt: string;
+  model: string;
+  createdAt: number;
+  startedAt?: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+}
+
+export interface LaunchInput {
+  id: string;
+  prompt: string;
+  model: string;
+}

package/src/features/builtin-features.ts

@@ -0,0 +1,5 @@
+import { createAutoUpdatePlugin } from "./auto-update/plugin";
+import { loopPlugin } from "./loops/plugin";
+import type { PluginDefinition } from "../types/plugin";
+
+export const BUILTIN_FEATURE_PLUGINS: PluginDefinition[] = [createAutoUpdatePlugin(), loopPlugin];

package/src/features/categories/categories.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "bun:test";
+import { CategoryResolver, resolveCategory } from "./category-resolver";
+import { DEFAULT_CATEGORIES } from "./category-config";
+
+describe("category-resolver", () => {
+  describe("#given built-in category names", () => {
+    describe("#when resolve is called", () => {
+      it("#then resolves each category to its default model", () => {
+        const resolver = new CategoryResolver();
+
+        expect(resolver.resolve("visual-engineering")?.model).toBe(
+          DEFAULT_CATEGORIES["visual-engineering"].model,
+        );
+        expect(resolver.resolve("ultrabrain")?.model).toBe(DEFAULT_CATEGORIES.ultrabrain.model);
+        expect(resolver.resolve("deep")?.model).toBe(DEFAULT_CATEGORIES.deep.model);
+        expect(resolver.resolve("artistry")?.model).toBe(DEFAULT_CATEGORIES.artistry.model);
+        expect(resolver.resolve("quick")?.model).toBe(DEFAULT_CATEGORIES.quick.model);
+        expect(resolver.resolve("unspecified-low")?.model).toBe(
+          DEFAULT_CATEGORIES["unspecified-low"].model,
+        );
+        expect(resolver.resolve("unspecified-high")?.model).toBe(
+          DEFAULT_CATEGORIES["unspecified-high"].model,
+        );
+        expect(resolver.resolve("writing")?.model).toBe(DEFAULT_CATEGORIES.writing.model);
+      });
+    });
+  });
+
+  describe("#given category overrides", () => {
+    describe("#when model override is provided", () => {
+      it("#then override model takes precedence over defaults", () => {
+        const resolver = new CategoryResolver();
+
+        const resolved = resolver.resolve("visual-engineering", {
+          "visual-engineering": {
+            model: "custom/model",
+          },
+        });
+
+        expect(resolved?.model).toBe("custom/model");
+      });
+    });
+
+    describe("#when resolveCategory helper is called with overrides", () => {
+      it("#then returns merged category config", () => {
+        const resolved = resolveCategory("writing", {
+          writing: {
+            model: "custom/writer-model",
+            variant: "high",
+          },
+        });
+
+        expect(resolved?.model).toBe("custom/writer-model");
+        expect(resolved?.variant).toBe("high");
+        expect(typeof resolved?.prompt_append).toBe("string");
+      });
+    });
+  });
+
+  describe("#given an unknown category", () => {
+    describe("#when resolve is called", () => {
+      it("#then returns undefined", () => {
+        const resolver = new CategoryResolver();
+        expect(resolver.resolve("not-a-category")).toBeUndefined();
+      });
+    });
+  });
+});

package/src/features/categories/category-config.ts

@@ -0,0 +1,70 @@
+import type { BuiltinCategoryName, CategoryConfig } from "../../types/category";
+import { CATEGORY_PROMPT_APPENDS } from "./prompt-appends";
+
+export type CategoryName = BuiltinCategoryName;
+
+export interface CategoryDefinition extends Required<Pick<CategoryConfig, "description">> {
+  model: string;
+  variant?: string;
+  promptAppend?: string;
+}
+
+export const DEFAULT_CATEGORY_DEFINITIONS: Record<CategoryName, CategoryDefinition> = {
+  "visual-engineering": {
+    model: "gemini-3.1-pro",
+    variant: "high",
+    description: "Frontend, UI/UX, design, styling, animation",
+    promptAppend: CATEGORY_PROMPT_APPENDS["visual-engineering"],
+  },
+  ultrabrain: {
+    model: "gpt-5.4",
+    variant: "xhigh",
+    description: "Hard logic, architecture decisions, complex reasoning",
+    promptAppend: CATEGORY_PROMPT_APPENDS.ultrabrain,
+  },
+  deep: {
+    model: "gpt-5.3-codex",
+    variant: "medium",
+    description: "Goal-oriented autonomous problem solving",
+    promptAppend: CATEGORY_PROMPT_APPENDS.deep,
+  },
+  artistry: {
+    model: "gemini-3.1-pro",
+    variant: "high",
+    description: "Creative approaches and unconventional solutions",
+    promptAppend: CATEGORY_PROMPT_APPENDS.artistry,
+  },
+  quick: {
+    model: "gpt-5.4-mini",
+    description: "Trivial tasks and small single-file changes",
+    promptAppend: CATEGORY_PROMPT_APPENDS.quick,
+  },
+  "unspecified-low": {
+    model: "claude-sonnet-4-6",
+    description: "Moderate effort tasks outside specialized categories",
+    promptAppend: CATEGORY_PROMPT_APPENDS["unspecified-low"],
+  },
+  "unspecified-high": {
+    model: "claude-opus-4-6",
+    variant: "max",
+    description: "High effort tasks outside specialized categories",
+    promptAppend: CATEGORY_PROMPT_APPENDS["unspecified-high"],
+  },
+  writing: {
+    model: "gemini-3.1-flash-lite",
+    description: "Documentation, prose, technical writing",
+    promptAppend: CATEGORY_PROMPT_APPENDS.writing,
+  },
+};
+
+export const DEFAULT_CATEGORIES: Record<CategoryName, CategoryConfig> = Object.fromEntries(
+  Object.entries(DEFAULT_CATEGORY_DEFINITIONS).map(([name, definition]) => [
+    name,
+    {
+      model: definition.model,
+      variant: definition.variant,
+      description: definition.description,
+      prompt_append: definition.promptAppend,
+    },
+  ]),
+) as Record<CategoryName, CategoryConfig>;

package/src/features/categories/category-resolver.ts

@@ -0,0 +1,36 @@
+import type { BuiltinCategoryName, CategoryConfig } from "../../types/category";
+import { log } from "../../shared/logger";
+import { DEFAULT_CATEGORIES } from "./category-config";
+
+export type CategoryOverrides = Partial<Record<BuiltinCategoryName, CategoryConfig>>;
+
+export class CategoryResolver {
+  resolve(name: string, configOverrides?: CategoryOverrides): CategoryConfig | undefined {
+    const categoryName = name as BuiltinCategoryName;
+    const baseConfig = DEFAULT_CATEGORIES[categoryName];
+    if (!baseConfig) {
+      log(`[category-resolver] Unknown category: ${name}`);
+      return undefined;
+    }
+
+    const override = configOverrides?.[categoryName];
+    if (!override) {
+      return { ...baseConfig };
+    }
+
+    return {
+      model: override.model ?? baseConfig.model,
+      variant: override.variant ?? baseConfig.variant,
+      description: override.description ?? baseConfig.description,
+      prompt_append: override.prompt_append ?? baseConfig.prompt_append,
+    };
+  }
+}
+
+export function resolveCategory(
+  name: string,
+  configOverrides?: CategoryOverrides,
+): CategoryConfig | undefined {
+  const resolver = new CategoryResolver();
+  return resolver.resolve(name, configOverrides);
+}

package/src/features/categories/index.ts

@@ -0,0 +1,8 @@
+export { CATEGORY_PROMPT_APPENDS } from "./prompt-appends";
+export {
+  DEFAULT_CATEGORIES,
+  DEFAULT_CATEGORY_DEFINITIONS,
+  type CategoryDefinition,
+  type CategoryName,
+} from "./category-config";
+export { CategoryResolver, resolveCategory, type CategoryOverrides } from "./category-resolver";

package/src/features/categories/prompt-appends.ts

@@ -0,0 +1,38 @@
+export const CATEGORY_PROMPT_APPENDS = {
+  "visual-engineering": `<Category_Context>
+You are working on VISUAL/UI tasks.
+
+Follow the project's design system first. Prefer existing UI patterns, tokens, and reusable components.
+</Category_Context>`,
+  ultrabrain: `<Category_Context>
+You are working on DEEP LOGICAL REASONING / COMPLEX ARCHITECTURE tasks.
+
+Prioritize clear recommendations, tradeoffs, and maintainable implementation strategy.
+</Category_Context>`,
+  deep: `<Category_Context>
+You are working on GOAL-ORIENTED AUTONOMOUS tasks.
+
+Research thoroughly before making changes and execute with minimal supervision.
+</Category_Context>`,
+  artistry: `<Category_Context>
+You are working on HIGHLY CREATIVE / ARTISTIC tasks.
+
+Explore unconventional approaches while keeping outcomes coherent.
+</Category_Context>`,
+  quick: `<Category_Context>
+You are working on SMALL / QUICK tasks.
+
+Use minimal overhead and solve directly without over-engineering.
+</Category_Context>`,
+  "unspecified-low": `<Category_Context>
+You are working on moderate-effort tasks that do not fit specialized categories.
+</Category_Context>`,
+  "unspecified-high": `<Category_Context>
+You are working on substantial-effort tasks that do not fit specialized categories.
+</Category_Context>`,
+  writing: `<Category_Context>
+You are working on WRITING / PROSE tasks.
+
+Favor clear, natural language and avoid AI-slop phrasing.
+</Category_Context>`,
+} as const;

package/src/features/loops/file-store.ts

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { log } from "../../shared/logger";
+import { createInitialLoopState, type LoopOptions, type LoopState, type LoopStore } from "./state";
+
+interface FileLoopStoreOptions {
+  stateFilePath?: string;
+}
+
+function isValidLoopState(value: unknown): value is LoopState {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.active === "boolean" &&
+    typeof obj.iteration === "number" &&
+    typeof obj.maxIterations === "number" &&
+    typeof obj.completionDetected === "boolean" &&
+    typeof obj.persist === "boolean"
+  );
+}
+
+export class FileLoopStore implements LoopStore {
+  private stateFilePath: string;
+  private loadedFromDisk = false;
+  private readonly loopStates = new Map<string, LoopState>();
+
+  constructor(options?: FileLoopStoreOptions) {
+    this.stateFilePath =
+      options?.stateFilePath ?? resolve(process.cwd(), ".sisyphus", "loop-state.json");
+  }
+
+  startLoop(sessionId: string, options?: LoopOptions): void {
+    this.ensureLoadedFromDisk();
+    const state = createInitialLoopState({ ...options, persist: true });
+    this.loopStates.set(sessionId, state);
+    this.persist();
+    log("[loop] started (file)", { sessionId, maxIterations: state.maxIterations });
+  }
+
+  stopLoop(sessionId: string): void {
+    this.ensureLoadedFromDisk();
+    const existing = this.loopStates.get(sessionId);
+    if (!existing) {
+      return;
+    }
+
+    this.loopStates.delete(sessionId);
+    this.persist();
+    log("[loop] stopped (file)", { sessionId, iteration: existing.iteration });
+  }
+
+  isActive(sessionId: string): boolean {
+    this.ensureLoadedFromDisk();
+    return this.loopStates.get(sessionId)?.active === true;
+  }
+
+  getLoopState(sessionId: string): LoopState | undefined {
+    this.ensureLoadedFromDisk();
+    const state = this.loopStates.get(sessionId);
+    return state ? { ...state } : undefined;
+  }
+
+  incrementIteration(sessionId: string): void {
+    this.ensureLoadedFromDisk();
+    const state = this.loopStates.get(sessionId);
+    if (!state || !state.active || state.completionDetected) {
+      return;
+    }
+
+    this.loopStates.set(sessionId, { ...state, iteration: state.iteration + 1 });
+    this.persist();
+  }
+
+  markCompletionDetected(sessionId: string): void {
+    this.ensureLoadedFromDisk();
+    const state = this.loopStates.get(sessionId);
+    if (!state) {
+      return;
+    }
+
+    this.loopStates.set(sessionId, { ...state, active: false, completionDetected: true });
+    this.persist();
+  }
+
+  setStateFilePathForTests(filePath: string): void {
+    this.stateFilePath = filePath;
+    this.loadedFromDisk = false;
+    this.loopStates.clear();
+  }
+
+  loadPersistedStateForTests(): void {
+    this.loadedFromDisk = false;
+    this.ensureLoadedFromDisk();
+  }
+
+  clearAllForTests(clearPersistedFile = false): void {
+    this.loopStates.clear();
+    this.loadedFromDisk = false;
+    if (clearPersistedFile) {
+      rmSync(this.stateFilePath, { force: true });
+    }
+  }
+
+  private ensureLoadedFromDisk(): void {
+    if (this.loadedFromDisk) {
+      return;
+    }
+
+    this.loadedFromDisk = true;
+    if (!existsSync(this.stateFilePath)) {
+      return;
+    }
+
+    try {
+      const fileContent = readFileSync(this.stateFilePath, "utf-8");
+      const parsed: unknown = JSON.parse(fileContent);
+
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        log("[loop] persisted state is not a plain object, ignoring");
+        return;
+      }
+
+      for (const [sessionId, state] of Object.entries(parsed as Record<string, unknown>)) {
+        if (!isValidLoopState(state)) {
+          log("[loop] skipping invalid persisted state", { sessionId });
+          continue;
+        }
+
+        this.loopStates.set(sessionId, { ...state });
+      }
+    } catch (error) {
+      log("[loop] failed to load persisted state", { error: String(error) });
+    }
+  }
+
+  private persist(): void {
+    try {
+      mkdirSync(dirname(this.stateFilePath), { recursive: true });
+      const serializable = Object.fromEntries(this.loopStates.entries());
+      const tmpPath = `${this.stateFilePath}.tmp`;
+      writeFileSync(tmpPath, JSON.stringify(serializable, null, 2), "utf-8");
+      renameSync(tmpPath, this.stateFilePath);
+    } catch (error) {
+      log("[loop] failed to persist state", { error: String(error) });
+    }
+  }
+}

package/src/features/loops/handler.ts

@@ -0,0 +1,89 @@
+import { log } from "../../shared/logger";
+import {
+  type HookEvent,
+  asEvent,
+  defaultCompletionDetector,
+  getSessionId,
+} from "./shared/event-utils";
+import { type LoopState, type LoopStore } from "./state";
+
+export interface LoopHandlerOptions {
+  completionPromise?: string;
+  detectCompletion?: (event: HookEvent, state: LoopState) => boolean;
+  sendContinuationMessage?: (sessionId: string, message: string) => Promise<void> | void;
+}
+
+export function buildLoopContinuationMessage(state: LoopState, completionPromise: string): string {
+  const maxIterations =
+    state.maxIterations === Number.MAX_SAFE_INTEGER ? "unbounded" : String(state.maxIterations);
+
+  return [
+    "[SYSTEM DIRECTIVE: LOOP CONTINUE]",
+    `Iteration ${state.iteration}/${maxIterations}`,
+    "Continue the task from your previous work.",
+    `When fully complete, output <promise>${completionPromise}</promise>.`,
+  ].join("\n");
+}
+
+export function createLoopHandler(store: LoopStore, options?: LoopHandlerOptions) {
+  const completionPromise = options?.completionPromise ?? "DONE";
+
+  return async (input: unknown): Promise<void> => {
+    const event = asEvent(input);
+    if (!event || event.type !== "session.idle") {
+      return;
+    }
+
+    const sessionId = getSessionId(event.properties);
+    if (!sessionId) {
+      return;
+    }
+
+    const state = store.getLoopState(sessionId);
+    if (!state) {
+      return;
+    }
+
+    if (state.completionDetected) {
+      store.stopLoop(sessionId);
+      return;
+    }
+
+    if (!store.isActive(sessionId)) {
+      return;
+    }
+
+    const completionDetected = options?.detectCompletion
+      ? options.detectCompletion(event, state)
+      : defaultCompletionDetector(event, completionPromise);
+
+    if (completionDetected) {
+      store.markCompletionDetected(sessionId);
+      log("[loop] completion detected", { sessionId, iteration: state.iteration });
+      return;
+    }
+
+    if (state.iteration >= state.maxIterations) {
+      store.stopLoop(sessionId);
+      log("[loop] max iterations reached", {
+        sessionId,
+        iteration: state.iteration,
+        maxIterations: state.maxIterations,
+      });
+      return;
+    }
+
+    store.incrementIteration(sessionId);
+    const updatedState = store.getLoopState(sessionId);
+    if (!updatedState) {
+      return;
+    }
+
+    const continuationMessage = buildLoopContinuationMessage(updatedState, completionPromise);
+    try {
+      await options?.sendContinuationMessage?.(sessionId, continuationMessage);
+    } catch (error) {
+      log("[loop] continuation injection failed", { sessionId, error: String(error) });
+    }
+  };
+}

package/src/features/loops/index.ts

@@ -0,0 +1,28 @@
+export {
+  DEFAULT_MAX_ITERATIONS,
+  UNBOUNDED_MAX_ITERATIONS,
+  type LoopOptions,
+  type LoopState,
+  type LoopStore,
+} from "./state";
+export { MemoryLoopStore } from "./memory-store";
+export { FileLoopStore } from "./file-store";
+export {
+  buildLoopContinuationMessage,
+  createLoopHandler,
+  type LoopHandlerOptions,
+} from "./handler";
+export {
+  clearLoopStateForTests,
+  configureLoopStateFilePathForTests,
+  createLoopPlugin,
+  defaultLoopStore,
+  fileLoopStore,
+  getLoopState,
+  isLoopActive,
+  loadPersistedLoopStateForTests,
+  loopPlugin,
+  memoryLoopStore,
+  startLoop,
+  stopLoop,
+} from "./plugin";