stagent 0.1.0

package/src/lib/agents/profiles/builtins/technical-writer/profile.yaml

@@ -0,0 +1,29 @@
+id: technical-writer
+name: Technical Writer
+version: "1.0.0"
+domain: work
+tags: [documentation, api-docs, adr, readme, changelog, technical-writing]
+supportedRuntimes: [claude-code, openai-codex-app-server]
+
+allowedTools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - Edit
+
+canUseToolPolicy:
+  autoApprove: [Read, Grep, Glob]
+  autoDeny: []
+
+temperature: 0.4
+maxTurns: 20
+outputFormat: markdown
+
+author: stagent
+
+tests:
+  - task: "Write API documentation for the /api/tasks endpoint"
+    expectedKeywords: [endpoint, request, response, parameters, status]
+  - task: "Create an ADR for switching from REST to GraphQL"
+    expectedKeywords: [context, decision, consequences, alternatives, status]

package/src/lib/agents/profiles/builtins/travel-planner/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: travel-planner
+description: Itinerary building, budget optimization, and booking research
+---
+
+You are an experienced travel planner who creates detailed, practical itineraries.
+
+## Core Capabilities
+
+1. **Itinerary Building** — Day-by-day plans with timing, logistics, and alternatives
+2. **Budget Optimization** — Cost breakdowns, money-saving tips, price comparisons
+3. **Destination Research** — Local tips, seasonal considerations, safety information
+4. **Logistics Planning** — Transportation routing, accommodation recommendations, booking timing
+5. **Personalization** — Adapt plans to traveler preferences, pace, and interests
+
+## Output Format
+
+Structure itineraries as:
+- **Overview**: Destination, dates, budget range, travel style
+- **Day-by-Day Plan**: Morning/afternoon/evening activities with addresses and costs
+- **Budget Breakdown**: Accommodation, transport, food, activities, contingency
+- **Booking Checklist**: What to book when, with priority order
+- **Tips**: Local customs, packing suggestions, money-saving hacks

package/src/lib/agents/profiles/builtins/travel-planner/profile.yaml

@@ -0,0 +1,26 @@
+id: travel-planner
+name: Travel Planner
+version: "1.0.0"
+domain: personal
+tags: [travel, itinerary, budget, booking, vacation, trip]
+supportedRuntimes: [claude-code]
+
+allowedTools:
+  - WebSearch
+  - WebFetch
+  - Read
+
+canUseToolPolicy:
+  autoApprove: [WebSearch, WebFetch, Read]
+  autoDeny: [Bash, Write, Edit]
+
+temperature: 0.6
+maxTurns: 25
+
+author: stagent
+
+tests:
+  - task: "Plan a 5-day trip to Tokyo on a moderate budget"
+    expectedKeywords: [itinerary, budget, accommodation, transport]
+  - task: "Compare flight options from New York to London in March"
+    expectedKeywords: [flight, price, comparison, booking]

package/src/lib/agents/profiles/builtins/wealth-manager/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: wealth-manager
+description: Portfolio analysis, tax optimization, and risk assessment with appropriate disclaimers
+---
+
+You are a knowledgeable financial analyst who helps users understand their financial situation. You provide educational analysis, NOT financial advice.
+
+**IMPORTANT DISCLAIMER**: You are an AI assistant providing general financial education and analysis. This is NOT personalized financial advice. Always recommend consulting a licensed financial advisor for investment decisions.
+
+## Core Capabilities
+
+1. **Portfolio Analysis** — Asset allocation review, diversification assessment, sector exposure
+2. **Tax Optimization** — Tax-loss harvesting opportunities, account type optimization (401k/IRA/taxable)
+3. **Risk Assessment** — Risk tolerance alignment, drawdown analysis, concentration risk
+4. **Goal Planning** — Retirement projections, savings rate analysis, milestone tracking
+5. **Market Context** — Relate portfolio positioning to current market conditions
+
+## Output Format
+
+- **Portfolio Summary**: Current allocation with percentages
+- **Analysis**: Key observations about diversification, risk, and performance
+- **Opportunities**: Potential optimizations with pros/cons
+- **Risks**: Concentration or strategy risks identified
+- **Disclaimer**: Always end with the standard financial disclaimer

package/src/lib/agents/profiles/builtins/wealth-manager/profile.yaml

@@ -0,0 +1,26 @@
+id: wealth-manager
+name: Wealth Manager
+version: "1.0.0"
+domain: personal
+tags: [finance, investing, tax, portfolio, retirement, savings]
+supportedRuntimes: [claude-code]
+
+allowedTools:
+  - WebSearch
+  - WebFetch
+  - Read
+
+canUseToolPolicy:
+  autoApprove: [Read]
+  autoDeny: [Bash, Write, Edit]
+
+temperature: 0.3
+maxTurns: 20
+
+author: stagent
+
+tests:
+  - task: "Review my portfolio allocation and suggest improvements"
+    expectedKeywords: [allocation, diversification, risk, disclaimer]
+  - task: "What tax optimization strategies should I consider this year?"
+    expectedKeywords: [tax, optimization, strategy, disclaimer]

package/src/lib/agents/profiles/compatibility.ts

@@ -0,0 +1,109 @@
+import {
+  DEFAULT_AGENT_RUNTIME,
+  SUPPORTED_AGENT_RUNTIMES,
+  resolveAgentRuntime,
+  type AgentRuntimeId,
+} from "@/lib/agents/runtime/catalog";
+import type {
+  CanUseToolPolicy,
+  ProfileRuntimeOverride,
+  ProfileSmokeTest,
+} from "./types";
+
+type CompatibilityProfile = {
+  id: string;
+  name: string;
+  skillMd?: string;
+  systemPrompt?: string;
+  allowedTools?: string[];
+  mcpServers?: Record<string, unknown>;
+  canUseToolPolicy?: CanUseToolPolicy;
+  tests?: ProfileSmokeTest[];
+  supportedRuntimes?: AgentRuntimeId[];
+  runtimeOverrides?: Partial<Record<AgentRuntimeId, ProfileRuntimeOverride>>;
+};
+
+export interface ProfileRuntimeCompatibility {
+  runtimeId: AgentRuntimeId;
+  supported: boolean;
+  reason?: string;
+  instructionsSource: "shared" | "runtime-override";
+}
+
+export interface ResolvedProfileRuntimePayload
+  extends ProfileRuntimeCompatibility {
+  profileId: string;
+  profileName: string;
+  instructions: string;
+  allowedTools?: string[];
+  mcpServers?: Record<string, unknown>;
+  canUseToolPolicy?: CanUseToolPolicy;
+  tests?: ProfileSmokeTest[];
+}
+
+export function getSupportedRuntimes(
+  profile: Pick<CompatibilityProfile, "supportedRuntimes">
+): AgentRuntimeId[] {
+  const supported =
+    profile.supportedRuntimes && profile.supportedRuntimes.length > 0
+      ? profile.supportedRuntimes
+      : ["claude-code"];
+
+  return SUPPORTED_AGENT_RUNTIMES.filter((runtimeId) =>
+    supported.includes(runtimeId)
+  );
+}
+
+export function getProfileRuntimeCompatibility(
+  profile: CompatibilityProfile,
+  runtimeId?: string | null
+): ProfileRuntimeCompatibility {
+  const resolvedRuntime = resolveAgentRuntime(runtimeId ?? DEFAULT_AGENT_RUNTIME);
+  const supportedRuntimes = getSupportedRuntimes(profile);
+  const supported = supportedRuntimes.includes(resolvedRuntime);
+  const runtimeOverride = profile.runtimeOverrides?.[resolvedRuntime];
+
+  return {
+    runtimeId: resolvedRuntime,
+    supported,
+    reason: supported
+      ? undefined
+      : `${profile.name} does not support ${resolvedRuntime}`,
+    instructionsSource: runtimeOverride?.instructions ? "runtime-override" : "shared",
+  };
+}
+
+export function profileSupportsRuntime(
+  profile: CompatibilityProfile,
+  runtimeId?: string | null
+): boolean {
+  return getProfileRuntimeCompatibility(profile, runtimeId).supported;
+}
+
+export function resolveProfileRuntimePayload(
+  profile: CompatibilityProfile,
+  runtimeId?: string | null
+): ResolvedProfileRuntimePayload {
+  const compatibility = getProfileRuntimeCompatibility(profile, runtimeId);
+  const runtimeOverride = profile.runtimeOverrides?.[compatibility.runtimeId];
+  const instructions =
+    runtimeOverride?.instructions ??
+    profile.skillMd ??
+    profile.systemPrompt ??
+    "";
+
+  return {
+    profileId: profile.id,
+    profileName: profile.name,
+    runtimeId: compatibility.runtimeId,
+    supported: compatibility.supported,
+    reason: compatibility.reason,
+    instructionsSource: compatibility.instructionsSource,
+    instructions,
+    allowedTools: runtimeOverride?.allowedTools ?? profile.allowedTools,
+    mcpServers: runtimeOverride?.mcpServers ?? profile.mcpServers,
+    canUseToolPolicy:
+      runtimeOverride?.canUseToolPolicy ?? profile.canUseToolPolicy,
+    tests: runtimeOverride?.tests ?? profile.tests,
+  };
+}

package/src/lib/agents/profiles/registry.ts

@@ -0,0 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { ProfileConfigSchema } from "@/lib/validators/profile";
+import type { ProfileConfig } from "@/lib/validators/profile";
+import { getSupportedRuntimes } from "./compatibility";
+import type { AgentProfile } from "./types";
+
+/**
+ * Builtins ship inside the repo at src/lib/agents/profiles/builtins/.
+ * At runtime they are copied (if missing) to ~/.claude/skills/ so users
+ * can customize them without touching source.
+ */
+const BUILTINS_DIR = path.resolve(
+  import.meta.dirname ?? __dirname,
+  "builtins"
+);
+
+const SKILLS_DIR = path.join(
+  process.env.HOME ?? process.env.USERPROFILE ?? ".",
+  ".claude",
+  "skills"
+);
+
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+
+let profileCache: Map<string, AgentProfile> | null = null;
+let profileCacheSignature: string | null = null;
+
+function getSkillsDirectorySignature(): string {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    return "missing";
+  }
+
+  const entries = fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const signatureParts: string[] = [];
+
+  for (const entry of entries) {
+    const dir = path.join(SKILLS_DIR, entry.name);
+    const yamlPath = path.join(dir, "profile.yaml");
+    const skillPath = path.join(dir, "SKILL.md");
+
+    signatureParts.push(entry.name);
+
+    if (fs.existsSync(yamlPath)) {
+      const stats = fs.statSync(yamlPath);
+      signatureParts.push(`yaml:${stats.mtimeMs}:${stats.size}`);
+    }
+
+    if (fs.existsSync(skillPath)) {
+      const stats = fs.statSync(skillPath);
+      signatureParts.push(`skill:${stats.mtimeMs}:${stats.size}`);
+    }
+  }
+
+  return signatureParts.join("|");
+}
+
+// ---------------------------------------------------------------------------
+// ensureBuiltins — copy missing builtins to .claude/skills/ (idempotent)
+// ---------------------------------------------------------------------------
+
+function ensureBuiltins(): void {
+  if (!fs.existsSync(BUILTINS_DIR)) return;
+
+  fs.mkdirSync(SKILLS_DIR, { recursive: true });
+
+  for (const entry of fs.readdirSync(BUILTINS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const targetDir = path.join(SKILLS_DIR, entry.name);
+    const targetYaml = path.join(targetDir, "profile.yaml");
+    const srcYaml = path.join(BUILTINS_DIR, entry.name, "profile.yaml");
+
+    // Never overwrite user edits — only copy if profile.yaml is missing
+    if (fs.existsSync(targetYaml)) {
+      try {
+        const source = (yaml.load(fs.readFileSync(srcYaml, "utf-8")) ??
+          {}) as Record<string, unknown>;
+        const target = (yaml.load(fs.readFileSync(targetYaml, "utf-8")) ??
+          {}) as Record<string, unknown>;
+        let changed = false;
+
+        if (
+          source.supportedRuntimes !== undefined &&
+          target.supportedRuntimes === undefined
+        ) {
+          target.supportedRuntimes = source.supportedRuntimes;
+          changed = true;
+        }
+
+        if (
+          source.runtimeOverrides !== undefined &&
+          target.runtimeOverrides === undefined
+        ) {
+          target.runtimeOverrides = source.runtimeOverrides;
+          changed = true;
+        }
+
+        if (changed) {
+          fs.writeFileSync(targetYaml, yaml.dump(target));
+        }
+      } catch {
+        // If a user has customized or broken the YAML, leave it untouched.
+      }
+      continue;
+    }
+
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    const srcDir = path.join(BUILTINS_DIR, entry.name);
+    for (const file of fs.readdirSync(srcDir)) {
+      fs.copyFileSync(path.join(srcDir, file), path.join(targetDir, file));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// scanProfiles — read .claude/skills/*/profile.yaml, validate, pair w/ SKILL.md
+// ---------------------------------------------------------------------------
+
+function scanProfiles(): Map<string, AgentProfile> {
+  const profiles = new Map<string, AgentProfile>();
+
+  if (!fs.existsSync(SKILLS_DIR)) return profiles;
+
+  for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const dir = path.join(SKILLS_DIR, entry.name);
+    const yamlPath = path.join(dir, "profile.yaml");
+    const skillPath = path.join(dir, "SKILL.md");
+
+    if (!fs.existsSync(yamlPath)) continue;
+
+    try {
+      const rawYaml = fs.readFileSync(yamlPath, "utf-8");
+      const parsed = yaml.load(rawYaml);
+      const result = ProfileConfigSchema.safeParse(parsed);
+
+      if (!result.success) {
+        console.warn(
+          `[profiles] Invalid profile.yaml in ${entry.name}:`,
+          result.error.issues.map((i) => i.message).join(", ")
+        );
+        continue;
+      }
+
+      const config = result.data;
+      const skillMd = fs.existsSync(skillPath)
+        ? fs.readFileSync(skillPath, "utf-8")
+        : "";
+
+      // Extract description from SKILL.md frontmatter or fall back to name
+      const descMatch = skillMd.match(
+        /^---\s*\n[\s\S]*?description:\s*(.+?)\s*\n[\s\S]*?---/
+      );
+      const description = descMatch?.[1] ?? config.name;
+
+      profiles.set(config.id, {
+        id: config.id,
+        name: config.name,
+        description,
+        domain: config.domain,
+        tags: config.tags,
+        systemPrompt: skillMd, // backward compat
+        skillMd,
+        allowedTools: config.allowedTools,
+        mcpServers: config.mcpServers as Record<string, unknown>,
+        canUseToolPolicy: config.canUseToolPolicy,
+        temperature: config.temperature,
+        maxTurns: config.maxTurns,
+        outputFormat: config.outputFormat,
+        version: config.version,
+        author: config.author,
+        source: config.source,
+        tests: config.tests,
+        supportedRuntimes: getSupportedRuntimes(config),
+        runtimeOverrides: config.runtimeOverrides,
+      });
+    } catch (err) {
+      console.warn(`[profiles] Error loading profile ${entry.name}:`, err);
+    }
+  }
+
+  return profiles;
+}
+
+// ---------------------------------------------------------------------------
+// Initialization — lazy on first access
+// ---------------------------------------------------------------------------
+
+function ensureLoaded(): Map<string, AgentProfile> {
+  ensureBuiltins();
+  const signature = getSkillsDirectorySignature();
+
+  if (!profileCache || profileCacheSignature !== signature) {
+    profileCache = scanProfiles();
+    profileCacheSignature = signature;
+  }
+  return profileCache;
+}
+
+// ---------------------------------------------------------------------------
+// Public API — same synchronous signatures as before
+// ---------------------------------------------------------------------------
+
+export function getProfile(id: string): AgentProfile | undefined {
+  return ensureLoaded().get(id);
+}
+
+export function listProfiles(): AgentProfile[] {
+  return Array.from(ensureLoaded().values());
+}
+
+export function getProfileTags(): Map<string, string[]> {
+  const tagMap = new Map<string, string[]>();
+  for (const profile of ensureLoaded().values()) {
+    tagMap.set(profile.id, profile.tags);
+  }
+  return tagMap;
+}
+
+/** Force re-scan of .claude/skills/ — call after user adds/edits profiles */
+export function reloadProfiles(): void {
+  profileCache = null;
+  profileCacheSignature = null;
+}
+
+/** Check if a profile ID is a built-in (exists in builtins/ source directory) */
+export function isBuiltin(id: string): boolean {
+  return fs.existsSync(path.join(BUILTINS_DIR, id, "profile.yaml"));
+}
+
+/** Create a new custom profile in ~/.claude/skills/ */
+export function createProfile(config: ProfileConfig, skillMd: string): void {
+  const result = ProfileConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error(`Invalid profile: ${result.error.issues.map(i => i.message).join(", ")}`);
+  }
+
+  const dir = path.join(SKILLS_DIR, config.id);
+  if (fs.existsSync(path.join(dir, "profile.yaml"))) {
+    throw new Error(`Profile "${config.id}" already exists`);
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "profile.yaml"), yaml.dump(config));
+  fs.writeFileSync(path.join(dir, "SKILL.md"), skillMd);
+  reloadProfiles();
+}
+
+/** Update an existing custom profile (rejects builtins) */
+export function updateProfile(id: string, config: ProfileConfig, skillMd: string): void {
+  if (isBuiltin(id)) {
+    throw new Error("Cannot modify built-in profiles");
+  }
+
+  const result = ProfileConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error(`Invalid profile: ${result.error.issues.map(i => i.message).join(", ")}`);
+  }
+
+  const dir = path.join(SKILLS_DIR, id);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Profile "${id}" not found`);
+  }
+
+  fs.writeFileSync(path.join(dir, "profile.yaml"), yaml.dump(config));
+  fs.writeFileSync(path.join(dir, "SKILL.md"), skillMd);
+  reloadProfiles();
+}
+
+/** Delete a custom profile (rejects builtins) */
+export function deleteProfile(id: string): void {
+  if (isBuiltin(id)) {
+    throw new Error("Cannot delete built-in profiles");
+  }
+
+  const dir = path.join(SKILLS_DIR, id);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Profile "${id}" not found`);
+  }
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  reloadProfiles();
+}

package/src/lib/agents/profiles/test-runner.ts

@@ -0,0 +1,18 @@
+import {
+  DEFAULT_AGENT_RUNTIME,
+  type AgentRuntimeId,
+} from "@/lib/agents/runtime/catalog";
+import { runProfileTestsWithRuntime } from "@/lib/agents/runtime";
+
+export type { ProfileTestResult, ProfileTestReport } from "./test-types";
+
+/**
+ * Run behavioral smoke tests for a profile through the active runtime layer.
+ * Default remains Claude until additional runtimes are wired into the UI.
+ */
+export async function runProfileTests(
+  profileId: string,
+  runtimeId: AgentRuntimeId = DEFAULT_AGENT_RUNTIME
+) {
+  return runProfileTestsWithRuntime(profileId, runtimeId);
+}

package/src/lib/agents/profiles/test-types.ts

@@ -0,0 +1,20 @@
+import type { AgentRuntimeId } from "@/lib/agents/runtime/catalog";
+
+export interface ProfileTestResult {
+  task: string;
+  expectedKeywords: string[];
+  foundKeywords: string[];
+  missingKeywords: string[];
+  passed: boolean;
+}
+
+export interface ProfileTestReport {
+  profileId: string;
+  profileName: string;
+  runtimeId: AgentRuntimeId;
+  results: ProfileTestResult[];
+  totalPassed: number;
+  totalFailed: number;
+  unsupported?: boolean;
+  unsupportedReason?: string;
+}

package/src/lib/agents/profiles/types.ts

@@ -0,0 +1,43 @@
+import type { AgentRuntimeId } from "@/lib/agents/runtime/catalog";
+
+export interface CanUseToolPolicy {
+  autoApprove?: string[];
+  autoDeny?: string[];
+}
+
+export interface ProfileSmokeTest {
+  task: string;
+  expectedKeywords: string[];
+}
+
+export interface ProfileRuntimeOverride {
+  instructions?: string;
+  allowedTools?: string[];
+  mcpServers?: Record<string, unknown>;
+  canUseToolPolicy?: CanUseToolPolicy;
+  tests?: ProfileSmokeTest[];
+}
+
+export interface AgentProfile {
+  id: string;
+  name: string;
+  description: string;
+  domain: string;
+  tags: string[];
+  /** @deprecated Use skillMd instead — kept for backward compat during migration */
+  systemPrompt: string;
+  /** Full content of the SKILL.md file (system prompt + behavioral instructions) */
+  skillMd: string;
+  allowedTools?: string[];
+  mcpServers?: Record<string, unknown>;
+  canUseToolPolicy?: CanUseToolPolicy;
+  temperature?: number;
+  maxTurns?: number;
+  outputFormat?: string;
+  version?: string;
+  author?: string;
+  source?: string;
+  tests?: ProfileSmokeTest[];
+  supportedRuntimes: AgentRuntimeId[];
+  runtimeOverrides?: Partial<Record<AgentRuntimeId, ProfileRuntimeOverride>>;
+}

package/src/lib/agents/router.ts

@@ -0,0 +1,56 @@
+import { listProfiles } from "./profiles/registry";
+import { profileSupportsRuntime } from "./profiles/compatibility";
+import {
+  executeTaskWithRuntime,
+  resumeTaskWithRuntime,
+} from "./runtime";
+import { DEFAULT_AGENT_RUNTIME } from "./runtime/catalog";
+
+/**
+ * Classify a task into an agent profile based on keyword matching.
+ * Scores each profile by keyword hits in title + description.
+ * Returns the highest-scoring profile ID, or "general" if no strong match.
+ */
+export function classifyTaskProfile(
+  title: string,
+  description?: string | null,
+  runtimeId: string | null | undefined = DEFAULT_AGENT_RUNTIME
+): string {
+  const text = `${title} ${description ?? ""}`.toLowerCase();
+  const profiles = listProfiles().filter((profile) =>
+    profileSupportsRuntime(profile, runtimeId)
+  );
+
+  let bestProfile = "general";
+  let bestScore = 0;
+
+  for (const profile of profiles) {
+    const profileId = profile.id;
+    if (profileId === "general") continue;
+    let score = 0;
+    for (const tag of profile.tags) {
+      if (text.includes(tag)) score++;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestProfile = profileId;
+    }
+  }
+
+  // Require at least 2 keyword hits to avoid false positives
+  return bestScore >= 2 ? bestProfile : "general";
+}
+
+export async function executeTaskWithAgent(
+  taskId: string,
+  agentType: string | null | undefined = DEFAULT_AGENT_RUNTIME
+): Promise<void> {
+  return executeTaskWithRuntime(taskId, agentType);
+}
+
+export async function resumeTaskWithAgent(
+  taskId: string,
+  agentType: string | null | undefined = DEFAULT_AGENT_RUNTIME
+): Promise<void> {
+  return resumeTaskWithRuntime(taskId, agentType);
+}