@hellcoder/companion 0.96.0

package/server/agent-store.ts

@@ -0,0 +1,185 @@
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  existsSync,
+} from "node:fs";
+import { join } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+import { randomBytes } from "node:crypto";
+import type { AgentConfig, AgentConfigCreateInput } from "./agent-types.js";
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const AGENTS_DIR = join(COMPANION_HOME, "agents");
+
+function ensureDir(): void {
+  mkdirSync(AGENTS_DIR, { recursive: true });
+}
+
+function filePath(id: string): string {
+  return join(AGENTS_DIR, `${id}.json`);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function generateWebhookSecret(): string {
+  return randomBytes(24).toString("hex");
+}
+
+/**
+ * Strip the legacy `triggers.chat` block from agents loaded from disk.
+ * The Chat SDK was removed but agents saved with the old schema may still
+ * have chat platform credentials on disk. Stripping on load prevents
+ * leaking those secrets via the API.
+ */
+function stripLegacyChatTrigger(agent: AgentConfig): AgentConfig {
+  if (!agent.triggers || !("chat" in agent.triggers)) return agent;
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { chat: _chat, ...rest } = agent.triggers as Record<string, unknown>;
+  return { ...agent, triggers: rest as AgentConfig["triggers"] };
+}
+
+// ─── CRUD ───────────────────────────────────────────────────────────────────
+
+export function listAgents(): AgentConfig[] {
+  ensureDir();
+  try {
+    const files = readdirSync(AGENTS_DIR).filter((f) => f.endsWith(".json"));
+    const agents: AgentConfig[] = [];
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(AGENTS_DIR, file), "utf-8");
+        agents.push(stripLegacyChatTrigger(JSON.parse(raw)));
+      } catch {
+        // Skip corrupt files
+      }
+    }
+    agents.sort((a, b) => a.name.localeCompare(b.name));
+    return agents;
+  } catch {
+    return [];
+  }
+}
+
+export function getAgent(id: string): AgentConfig | null {
+  ensureDir();
+  try {
+    const raw = readFileSync(filePath(id), "utf-8");
+    return stripLegacyChatTrigger(JSON.parse(raw) as AgentConfig);
+  } catch {
+    return null;
+  }
+}
+
+export function createAgent(data: AgentConfigCreateInput): AgentConfig {
+  if (!data.name || !data.name.trim()) throw new Error("Agent name is required");
+  if (!data.prompt || !data.prompt.trim()) throw new Error("Agent prompt is required");
+
+  const id = slugify(data.name.trim());
+  if (!id) throw new Error("Agent name must contain alphanumeric characters");
+
+  ensureDir();
+  if (existsSync(filePath(id))) {
+    throw new Error(`An agent with a similar name already exists ("${id}")`);
+  }
+
+  // Auto-generate webhook secret if webhook trigger is enabled but has no secret
+  const triggers = data.triggers ? { ...data.triggers } : undefined;
+  if (triggers?.webhook && !triggers.webhook.secret) {
+    triggers.webhook = { ...triggers.webhook, secret: generateWebhookSecret() };
+  }
+
+  const now = Date.now();
+  const agent: AgentConfig = {
+    ...data,
+    triggers,
+    id,
+    name: data.name.trim(),
+    prompt: data.prompt.trim(),
+    description: data.description?.trim() || "",
+    cwd: data.cwd?.trim() || "",
+    createdAt: now,
+    updatedAt: now,
+    totalRuns: 0,
+    consecutiveFailures: 0,
+  };
+  writeFileSync(filePath(id), JSON.stringify(agent, null, 2), "utf-8");
+  return agent;
+}
+
+export function updateAgent(
+  id: string,
+  updates: Partial<AgentConfig>,
+): AgentConfig | null {
+  ensureDir();
+  const existing = getAgent(id);
+  if (!existing) return null;
+
+  const newName = updates.name?.trim() || existing.name;
+  const newId = slugify(newName);
+  if (!newId) throw new Error("Agent name must contain alphanumeric characters");
+
+  // If name changed, check for slug collision with a different agent
+  if (newId !== id && existsSync(filePath(newId))) {
+    throw new Error(`An agent with a similar name already exists ("${newId}")`);
+  }
+
+  const agent: AgentConfig = {
+    ...existing,
+    ...updates,
+    id: newId,
+    name: newName,
+    updatedAt: Date.now(),
+    // Preserve immutable fields
+    createdAt: existing.createdAt,
+  };
+
+  // If id changed, delete old file
+  if (newId !== id) {
+    try {
+      unlinkSync(filePath(id));
+    } catch {
+      /* ok */
+    }
+  }
+
+  writeFileSync(filePath(newId), JSON.stringify(agent, null, 2), "utf-8");
+  return agent;
+}
+
+export function deleteAgent(id: string): boolean {
+  ensureDir();
+  if (!existsSync(filePath(id))) return false;
+  try {
+    unlinkSync(filePath(id));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Generate a new webhook secret for an agent */
+export function regenerateWebhookSecret(id: string): AgentConfig | null {
+  const agent = getAgent(id);
+  if (!agent) return null;
+
+  const triggers = agent.triggers || {};
+  triggers.webhook = {
+    enabled: triggers.webhook?.enabled ?? false,
+    secret: generateWebhookSecret(),
+  };
+
+  return updateAgent(id, { triggers });
+}

package/server/agent-types.ts

@@ -0,0 +1,138 @@
+// ─── Agent Types ─────────────────────────────────────────────────────────────
+
+export interface McpServerConfigAgent {
+  type: "stdio" | "sse" | "http";
+  command?: string;
+  args?: string[];
+  url?: string;
+  env?: Record<string, string>;
+}
+
+export interface AgentConfig {
+  /** Unique slug-based ID (derived from name) */
+  id: string;
+  /** Schema version for forward compat */
+  version: 1;
+  /** Human-readable name */
+  name: string;
+  /** Short description of what this agent does */
+  description: string;
+  /** Emoji or icon identifier */
+  icon?: string;
+
+  // ── Session Config ──
+  /** "claude" or "codex" */
+  backendType: "claude" | "codex";
+  /** Model to use (e.g. "claude-sonnet-4-6") */
+  model: string;
+  /** Permission mode — "bypassPermissions" for Claude auto mode */
+  permissionMode: string;
+  /** Working directory path, or "temp" for an auto-created temp dir */
+  cwd: string;
+  /** Optional environment slug (references ~/.companion/envs/) */
+  envSlug?: string;
+  /** Extra environment variables */
+  env?: Record<string, string>;
+  /** Tool allowlist (empty = all tools) */
+  allowedTools?: string[];
+  /** Codex-specific: internet access */
+  codexInternetAccess?: boolean;
+
+  // ── Prompt ──
+  /** Prompt template. Use {{input}} as placeholder for trigger-provided input */
+  prompt: string;
+
+  // ── MCP Servers ──
+  /** MCP server configs to set on the session after CLI connects */
+  mcpServers?: Record<string, McpServerConfigAgent>;
+
+  // ── Skills ──
+  /** Skill slugs to attach (from ~/.claude/skills/) */
+  skills?: string[];
+
+  // ── Docker ──
+  /** Optional Docker container configuration */
+  container?: {
+    image?: string;
+    ports?: number[];
+    volumes?: string[];
+    initScript?: string;
+  };
+
+  // ── Git ──
+  branch?: string;
+  createBranch?: boolean;
+  useWorktree?: boolean;
+
+  // ── Triggers ──
+  triggers?: {
+    /** Webhook trigger config */
+    webhook?: {
+      enabled: boolean;
+      /** Auto-generated secret token for URL auth */
+      secret: string;
+    };
+    /** Cron/schedule trigger config */
+    schedule?: {
+      enabled: boolean;
+      /** Cron expression or ISO datetime */
+      expression: string;
+      /** true = recurring cron, false = one-shot */
+      recurring: boolean;
+    };
+    /** Linear Agent Interaction SDK trigger (per-agent OAuth app) */
+    linear?: {
+      enabled: boolean;
+      /** Reference to a LinearOAuthConnection by ID (new model) */
+      oauthConnectionId?: string;
+      /** @deprecated OAuth app client ID from Linear — use oauthConnectionId instead */
+      oauthClientId?: string;
+      /** @deprecated OAuth app client secret — use oauthConnectionId instead */
+      oauthClientSecret?: string;
+      /** @deprecated Webhook signing secret — use oauthConnectionId instead */
+      webhookSecret?: string;
+      /** @deprecated OAuth access token — use oauthConnectionId instead */
+      accessToken?: string;
+      /** @deprecated OAuth refresh token — use oauthConnectionId instead */
+      refreshToken?: string;
+    };
+  };
+
+  // ── Tracking ──
+  enabled: boolean;
+  createdAt: number;
+  updatedAt: number;
+  lastRunAt?: number;
+  lastSessionId?: string;
+  totalRuns: number;
+  consecutiveFailures: number;
+}
+
+/** Input for creating an agent (without auto-generated fields) */
+export type AgentConfigCreateInput = Omit<
+  AgentConfig,
+  "id" | "createdAt" | "updatedAt" | "totalRuns" | "consecutiveFailures" | "lastRunAt" | "lastSessionId"
+>;
+
+/** The portable/shareable JSON format (no internal tracking fields) */
+export type AgentConfigExport = Omit<
+  AgentConfig,
+  "id" | "createdAt" | "updatedAt" | "totalRuns" | "consecutiveFailures" | "lastRunAt" | "lastSessionId" | "enabled"
+>;
+
+export interface AgentExecution {
+  /** The session ID created for this execution */
+  sessionId: string;
+  /** The agent ID that triggered this */
+  agentId: string;
+  /** Trigger type that initiated this execution */
+  triggerType: "manual" | "webhook" | "schedule" | "linear";
+  /** When the execution started */
+  startedAt: number;
+  /** When the execution completed */
+  completedAt?: number;
+  /** Whether the execution succeeded */
+  success?: boolean;
+  /** Error message if it failed */
+  error?: string;
+}

package/server/ai-validation-settings.test.ts

@@ -0,0 +1,128 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  _resetForTest,
+  updateSettings,
+} from "./settings-manager.js";
+import { getEffectiveAiValidation } from "./ai-validation-settings.js";
+import type { SessionState } from "./session-types.js";
+
+let tempDir: string;
+let settingsPath: string;
+
+/** Minimal SessionState with only the fields needed for testing */
+function makeSessionState(overrides: Partial<SessionState> = {}): SessionState {
+  return {
+    session_id: "test-session",
+    model: "",
+    cwd: "",
+    tools: [],
+    permissionMode: "default",
+    claude_code_version: "",
+    mcp_servers: [],
+    agents: [],
+    slash_commands: [],
+    skills: [],
+    total_cost_usd: 0,
+    num_turns: 0,
+    context_used_percent: 0,
+    is_compacting: false,
+    git_branch: "",
+    is_worktree: false,
+    is_containerized: false,
+    repo_root: "",
+    git_ahead: 0,
+    git_behind: 0,
+    total_lines_added: 0,
+    total_lines_removed: 0,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "ai-validation-settings-test-"));
+  settingsPath = join(tempDir, "settings.json");
+  _resetForTest(settingsPath);
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+  _resetForTest();
+});
+
+describe("getEffectiveAiValidation", () => {
+  it("returns global defaults when session fields are undefined", () => {
+    // Global defaults: enabled=false, autoApprove=true, autoDeny=false
+    const session = makeSessionState();
+    const result = getEffectiveAiValidation(session);
+    expect(result.enabled).toBe(false);
+    expect(result.autoApprove).toBe(true);
+    expect(result.autoDeny).toBe(false);
+    expect(result.anthropicApiKey).toBe("");
+  });
+
+  it("returns global defaults when session fields are null (explicit inherit)", () => {
+    const session = makeSessionState({
+      aiValidationEnabled: null,
+      aiValidationAutoApprove: null,
+      aiValidationAutoDeny: null,
+    });
+    const result = getEffectiveAiValidation(session);
+    expect(result.enabled).toBe(false);
+    expect(result.autoApprove).toBe(true);
+    expect(result.autoDeny).toBe(false);
+  });
+
+  it("session override wins over global when session fields are set", () => {
+    // Set global to enabled
+    updateSettings({ aiValidationEnabled: true, aiValidationAutoApprove: true, aiValidationAutoDeny: true });
+
+    // Session overrides all three to different values
+    const session = makeSessionState({
+      aiValidationEnabled: false,
+      aiValidationAutoApprove: false,
+      aiValidationAutoDeny: false,
+    });
+    const result = getEffectiveAiValidation(session);
+    expect(result.enabled).toBe(false);
+    expect(result.autoApprove).toBe(false);
+    expect(result.autoDeny).toBe(false);
+  });
+
+  it("session enabled=true overrides global enabled=false", () => {
+    // Global: disabled
+    const session = makeSessionState({ aiValidationEnabled: true });
+    const result = getEffectiveAiValidation(session);
+    expect(result.enabled).toBe(true);
+  });
+
+  it("mixed: session sets enabled, inherits autoApprove/autoDeny from global", () => {
+    updateSettings({ aiValidationAutoApprove: false, aiValidationAutoDeny: false });
+
+    const session = makeSessionState({
+      aiValidationEnabled: true,
+      aiValidationAutoApprove: null, // inherit global (false)
+      aiValidationAutoDeny: undefined, // inherit global (false)
+    });
+    const result = getEffectiveAiValidation(session);
+    expect(result.enabled).toBe(true);
+    expect(result.autoApprove).toBe(false);
+    expect(result.autoDeny).toBe(false);
+  });
+
+  it("anthropicApiKey always comes from global settings", () => {
+    updateSettings({ anthropicApiKey: "sk-test-key-123" });
+
+    const session = makeSessionState({ aiValidationEnabled: true });
+    const result = getEffectiveAiValidation(session);
+    expect(result.anthropicApiKey).toBe("sk-test-key-123");
+  });
+
+  it("returns empty API key when global has none, regardless of session settings", () => {
+    const session = makeSessionState({ aiValidationEnabled: true });
+    const result = getEffectiveAiValidation(session);
+    expect(result.anthropicApiKey).toBe("");
+  });
+});

package/server/ai-validation-settings.ts

@@ -0,0 +1,35 @@
+import { getSettings } from "./settings-manager.js";
+import type { SessionState } from "./session-types.js";
+
+export interface EffectiveAiValidationSettings {
+  enabled: boolean;
+  autoApprove: boolean;
+  autoDeny: boolean;
+  anthropicApiKey: string;
+}
+
+/**
+ * Resolve effective AI validation settings for a session.
+ * Session-level overrides take priority; falls back to global settings.
+ * The anthropicApiKey is always from global settings.
+ */
+export function getEffectiveAiValidation(
+  sessionState: SessionState,
+): EffectiveAiValidationSettings {
+  const global = getSettings();
+  return {
+    enabled:
+      sessionState.aiValidationEnabled != null
+        ? sessionState.aiValidationEnabled
+        : global.aiValidationEnabled,
+    autoApprove:
+      sessionState.aiValidationAutoApprove != null
+        ? sessionState.aiValidationAutoApprove
+        : global.aiValidationAutoApprove,
+    autoDeny:
+      sessionState.aiValidationAutoDeny != null
+        ? sessionState.aiValidationAutoDeny
+        : global.aiValidationAutoDeny,
+    anthropicApiKey: global.anthropicApiKey,
+  };
+}