stagent 0.10.0 → 0.11.1

package/src/lib/environment/list-skills.ts

@@ -0,0 +1,176 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { scanEnvironment } from "./scanner";
+import { getLaunchCwd } from "./workspace-context";
+import type { EnvironmentArtifact } from "./types";
+
+export interface SkillSummary {
+  /** Stable opaque ID used by activate_skill. Today: the relative path. */
+  id: string;
+  /** Short display name, e.g. "capture" or "code-review". */
+  name: string;
+  /** Which tool persona (claude-code | codex | shared). */
+  tool: string;
+  /** "user" or "project". */
+  scope: string;
+  /** Short description (first ~200 chars of SKILL.md body). */
+  preview: string;
+  sizeBytes: number;
+  /** Absolute path to the skill's SKILL.md — consumers can read it. */
+  absPath: string;
+}
+
+/**
+ * Discover skills from both `.claude/skills/` and `.agents/skills/` under
+ * the active project and user home. Reuses the existing environment
+ * scanner — we're just filtering to `category === "skill"`.
+ *
+ * Deliberately narrow surface: the scanner returns many artifact
+ * categories; the skill MCP tools only care about skills.
+ */
+export function listSkills(
+  options: { projectDir?: string } = {}
+): SkillSummary[] {
+  const projectDir = options.projectDir ?? getLaunchCwd();
+  const scan = scanEnvironment({ projectDir });
+  const skills: SkillSummary[] = [];
+  for (const a of scan.artifacts) {
+    if (a.category !== "skill") continue;
+    // Skip dot-prefixed system dirs (e.g. ~/.codex/skills/.system) —
+    // internal artifacts, not user-facing skills.
+    if (a.name.startsWith(".")) continue;
+    skills.push(artifactToSummary(a));
+  }
+  // Stable sort: tool, then scope, then name — deterministic listing is
+  // easier for the LLM to reason over.
+  skills.sort((a, b) => {
+    if (a.tool !== b.tool) return a.tool.localeCompare(b.tool);
+    if (a.scope !== b.scope) return a.scope.localeCompare(b.scope);
+    return a.name.localeCompare(b.name);
+  });
+  return skills;
+}
+
+/**
+ * Locate a single skill by its opaque ID (the relative path) and return
+ * its full SKILL.md content. Returns `null` if the skill is not found
+ * or its content can't be read.
+ *
+ * NB: the artifact's `absPath` is the skill **directory**, not the
+ * SKILL.md file. We probe the conventional names (SKILL.md / skill.md)
+ * and fall back to the first .md file in the directory.
+ */
+export function getSkill(
+  id: string,
+  options: { projectDir?: string } = {}
+): (SkillSummary & { content: string }) | null {
+  const all = listSkills(options);
+  const hit = all.find((s) => s.id === id);
+  if (!hit) return null;
+
+  const filePath = resolveSkillFile(hit.absPath);
+  if (!filePath) return null;
+
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return { ...hit, content };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the SKILL.md (or equivalent) inside a skill directory.
+ * Falls back to the first `*.md` if a canonical name is missing —
+ * matches the lenient discovery already used by `parsers/skill.ts`.
+ */
+function resolveSkillFile(dirPath: string): string | null {
+  try {
+    const stat = statSync(dirPath);
+    if (!stat.isDirectory()) {
+      // Already a file path — return as-is.
+      return dirPath;
+    }
+  } catch {
+    return null;
+  }
+
+  for (const name of ["SKILL.md", "skill.md"]) {
+    const candidate = join(dirPath, name);
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // missing — try next
+    }
+  }
+
+  try {
+    const fallback = readdirSync(dirPath).find((f) => f.toLowerCase().endsWith(".md"));
+    if (fallback) return join(dirPath, fallback);
+  } catch {
+    // unreadable
+  }
+
+  return null;
+}
+
+function artifactToSummary(a: EnvironmentArtifact): SkillSummary {
+  return {
+    id: a.relPath,
+    name: a.name,
+    tool: a.tool,
+    scope: a.scope,
+    preview: a.preview,
+    sizeBytes: a.sizeBytes,
+    absPath: a.absPath,
+  };
+}
+
+import { getLatestScan, getArtifacts } from "./data";
+import { enrichSkills, type EnrichedSkill } from "./skill-enrichment";
+
+export type { EnrichedSkill } from "./skill-enrichment";
+
+/**
+ * Like `listSkills` but reads the latest scan directly from the DB so the
+ * result carries `linkedProfileId` (which isn't on the in-memory
+ * EnvironmentArtifact type), and folds in health + sync status via
+ * `enrichSkills`.
+ *
+ * Cache-only path — no filesystem I/O. Returns empty array if no scan has
+ * been persisted yet.
+ */
+export function listSkillsEnriched(
+  options: { nowMs?: number } = {}
+): EnrichedSkill[] {
+  const latest = getLatestScan();
+  if (!latest) return [];
+
+  const rows = getArtifacts({ scanId: latest.id, category: "skill" });
+
+  const skills: SkillSummary[] = [];
+  const modifiedAtMsByPath: Record<string, number | null> = {};
+  const linkedProfilesByPath: Record<string, string | null> = {};
+
+  for (const row of rows) {
+    // Skip dot-prefixed system dirs (e.g. .system) — internal, not user-facing.
+    if (row.name.startsWith(".")) continue;
+    skills.push({
+      id: row.relPath,
+      name: row.name,
+      tool: row.tool,
+      scope: row.scope,
+      preview: row.preview ?? "",
+      sizeBytes: row.sizeBytes,
+      absPath: row.absPath,
+    });
+    modifiedAtMsByPath[row.absPath] = row.modifiedAt ?? null;
+    linkedProfilesByPath[row.absPath] = row.linkedProfileId ?? null;
+  }
+
+  return enrichSkills(skills, {
+    modifiedAtMsByPath,
+    linkedProfilesByPath,
+    nowMs: options.nowMs,
+  });
+}

package/src/lib/environment/parsers/__tests__/skill.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { parseSkillDir } from "../skill";
+
+describe("parseSkillDir", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "stagent-skill-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("parses a well-formed skill directory", () => {
+    const dir = join(root, "greeter");
+    mkdirSync(dir);
+    writeFileSync(
+      join(dir, "SKILL.md"),
+      "---\nname: Greeter\ndescription: Says hello\n---\nBody.\n"
+    );
+
+    const artifact = parseSkillDir(dir, "claude-code", "user", root);
+
+    expect(artifact).not.toBeNull();
+    expect(artifact!.name).toBe("greeter");
+    expect(artifact!.metadata.description).toBe("Says hello");
+  });
+
+  it("rejects a hidden dot-prefixed directory", () => {
+    const dir = join(root, ".system");
+    mkdirSync(dir);
+    writeFileSync(
+      join(dir, "SKILL.md"),
+      "---\nname: System\ndescription: Hidden\n---\n"
+    );
+
+    const artifact = parseSkillDir(dir, "claude-code", "user", root);
+
+    expect(artifact).toBeNull();
+  });
+
+  it("rejects .DS_Store and similar hidden filesystem noise", () => {
+    const dir = join(root, ".DS_Store");
+    mkdirSync(dir);
+
+    const artifact = parseSkillDir(dir, "claude-code", "user", root);
+
+    expect(artifact).toBeNull();
+  });
+});

package/src/lib/environment/parsers/skill.ts

@@ -3,7 +3,7 @@
  * Skills live in .claude/skills/<name>/ or ~/.codex/skills/<name>/.
  */
 
-import { readdirSync, readFileSync, statSync } from "fs";
+import { readdirSync, readFileSync } from "fs";
 import { join, basename } from "path";
 import type { EnvironmentArtifact, ToolPersona, ArtifactScope } from "../types";
 import { computeHash, safePreview, safeStat } from "./utils";
@@ -18,6 +18,10 @@ export function parseSkillDir(
   if (!stat?.isDirectory()) return null;
 
   const name = basename(dirPath);
+  // Skip hidden directories (e.g., .system, .DS_Store).
+  // These are never user-authored skills and would otherwise
+  // surface as spurious profiles under auto-promote.
+  if (name.startsWith(".")) return null;
   let mainFile = "";
   let content = "";
 
@@ -36,20 +40,37 @@ export function parseSkillDir(
     return null;
   }
 
-  // Extract description from YAML frontmatter if present
+  // Extract description from YAML frontmatter if present.
   const metadata: Record<string, unknown> = {};
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  let bodyAfterFrontmatter = content;
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n*/);
   if (fmMatch) {
     for (const line of fmMatch[1].split("\n")) {
       const colonIdx = line.indexOf(":");
       if (colonIdx > 0) {
         const key = line.slice(0, colonIdx).trim();
-        const value = line.slice(colonIdx + 1).trim();
+        let value = line.slice(colonIdx + 1).trim();
+        // Strip surrounding YAML quotes so the UI doesn't leak them.
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
+          value = value.slice(1, -1);
+        }
         metadata[key] = value;
       }
     }
+    bodyAfterFrontmatter = content.slice(fmMatch[0].length);
   }
 
+  // Prefer the frontmatter description as the human-facing preview so the
+  // UI does not leak raw YAML. Falls back to post-frontmatter body text.
+  const description =
+    typeof metadata.description === "string" && metadata.description.length > 0
+      ? metadata.description
+      : null;
+  const preview = description ?? safePreview(bodyAfterFrontmatter);
+
   return {
     tool,
     category: "skill",
@@ -58,7 +79,7 @@ export function parseSkillDir(
     relPath: dirPath.replace(baseDir, "").replace(/^\//, ""),
     absPath: dirPath,
     contentHash: computeHash(content),
-    preview: safePreview(content),
+    preview,
     metadata,
     sizeBytes: Buffer.byteLength(content, "utf-8"),
     modifiedAt: stat.mtimeMs,

package/src/lib/environment/profile-generator.ts

@@ -4,8 +4,11 @@
 
 import { getArtifacts } from "./data";
 import { evaluateRules, generateTier2Suggestions, type ProfileSuggestion } from "./profile-rules";
-import { listProfiles, createProfile } from "@/lib/agents/profiles/registry";
+import { listProfiles, createPromotedProfile } from "@/lib/agents/profiles/registry";
 import type { ProfileConfig } from "@/lib/validators/profile";
+import { getSettingSync } from "@/lib/settings/helpers";
+import { SETTINGS_KEYS } from "@/lib/constants/settings";
+import { linkArtifactsToProfiles } from "./profile-linker";
 
 const MIN_CURATED_CONFIDENCE = 0.6;
 
@@ -123,9 +126,60 @@ export function createProfileFromSuggestion(
     skillMd = skillMd.replace(suggestion.systemPrompt, overrides.systemPrompt);
   }
 
-  createProfile(config, skillMd);
+  createPromotedProfile(config, skillMd);
 
   // Note: the created profile will have author "stagent-env" which,
   // combined with the env- prefix on the ID, identifies it as environment-originated.
   // The profile registry can infer origin from the author field.
 }
+
+export interface AutoPromoteResult {
+  created: string[];
+  skipped: string[];
+  errors: Array<{ ruleId: string; message: string }>;
+}
+
+/**
+ * If the AUTO_PROMOTE_SKILLS setting is enabled, auto-create profiles for
+ * every unlinked Tier 2 suggestion discovered in the given scan, then re-link
+ * the scan's artifacts so the newly-created profiles show as linked.
+ *
+ * Returns a summary of what happened. No-ops (returns empty result) when the
+ * setting is disabled.
+ */
+export function autoPromoteUnlinkedSkills(scanId: string): AutoPromoteResult {
+  const result: AutoPromoteResult = { created: [], skipped: [], errors: [] };
+
+  const flag = getSettingSync(SETTINGS_KEYS.AUTO_PROMOTE_SKILLS);
+  if (flag !== "true") return result;
+
+  const { discovered } = suggestProfilesTiered(scanId);
+  if (discovered.length === 0) return result;
+
+  for (const suggestion of discovered) {
+    try {
+      createProfileFromSuggestion(suggestion);
+      result.created.push(suggestion.ruleId);
+    } catch (err) {
+      // Skip duplicates (registry throws when a profile with the same id
+      // already exists) — count them as skipped, not errors.
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.toLowerCase().includes("already exists")) {
+        result.skipped.push(suggestion.ruleId);
+      } else {
+        result.errors.push({ ruleId: suggestion.ruleId, message });
+      }
+    }
+  }
+
+  // Re-link so freshly-created profiles are marked on their artifacts.
+  if (result.created.length > 0) {
+    try {
+      linkArtifactsToProfiles(scanId);
+    } catch (err) {
+      console.warn("[auto-promote] Re-link after promotion failed:", err);
+    }
+  }
+
+  return result;
+}

package/src/lib/environment/skill-enrichment.ts

@@ -0,0 +1,106 @@
+export type HealthScore = "healthy" | "stale" | "aging" | "broken" | "unknown";
+
+export type SyncStatus =
+  | "synced"
+  | "claude-only"
+  | "codex-only"
+  | "shared";
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const SIX_MONTHS_DAYS = 180;
+const TWELVE_MONTHS_DAYS = 365;
+
+export function computeHealthScore(
+  modifiedAtMs: number | null,
+  nowMs: number = Date.now()
+): HealthScore {
+  if (modifiedAtMs == null) return "unknown";
+  const ageDays = (nowMs - modifiedAtMs) / MS_PER_DAY;
+  if (ageDays < SIX_MONTHS_DAYS) return "healthy";
+  if (ageDays < TWELVE_MONTHS_DAYS) return "stale";
+  return "aging";
+}
+
+/**
+ * Compute sync status from the set of tools that own the skill.
+ * - Both claude-code and codex present → "synced"
+ * - Only claude-code → "claude-only"
+ * - Only codex → "codex-only"
+ * - Only shared → "shared" (project-level file, no user peer expected)
+ * - claude-code + shared (or codex + shared) → treat as synced
+ */
+export function computeSyncStatus(tools: string[]): SyncStatus {
+  const set = new Set(tools);
+  const hasClaude = set.has("claude-code");
+  const hasCodex = set.has("codex");
+  const hasShared = set.has("shared");
+  if (hasClaude && hasCodex) return "synced";
+  if (hasClaude && hasShared) return "synced";
+  if (hasCodex && hasShared) return "synced";
+  if (hasClaude) return "claude-only";
+  if (hasCodex) return "codex-only";
+  return "shared";
+}
+
+import type { SkillSummary } from "./list-skills";
+
+export interface EnrichedSkill extends SkillSummary {
+  healthScore: HealthScore;
+  syncStatus: SyncStatus;
+  linkedProfileId: string | null;
+  /** All absPaths for the same skill name (for symlink/dup handling). */
+  absPaths: string[];
+}
+
+export interface EnrichmentContext {
+  modifiedAtMsByPath: Record<string, number | null>;
+  linkedProfilesByPath: Record<string, string | null>;
+  nowMs?: number;
+}
+
+export function enrichSkills(
+  skills: SkillSummary[],
+  ctx: EnrichmentContext
+): EnrichedSkill[] {
+  const nowMs = ctx.nowMs ?? Date.now();
+  // Dedupe by absPath first (symlink loops).
+  const seen = new Set<string>();
+  const deduped: SkillSummary[] = [];
+  for (const s of skills) {
+    if (seen.has(s.absPath)) continue;
+    seen.add(s.absPath);
+    deduped.push(s);
+  }
+  // Group by name.
+  const byName = new Map<string, SkillSummary[]>();
+  for (const s of deduped) {
+    const list = byName.get(s.name) ?? [];
+    list.push(s);
+    byName.set(s.name, list);
+  }
+  const out: EnrichedSkill[] = [];
+  for (const [, group] of byName) {
+    const tools = group.map((g) => g.tool);
+    const syncStatus = computeSyncStatus(tools);
+    // Use the highest health (most recent modification) across the group.
+    const ages = group.map((g) => ctx.modifiedAtMsByPath[g.absPath] ?? null);
+    const newest = ages.reduce<number | null>(
+      (acc, v) => (v != null && (acc == null || v > acc) ? v : acc),
+      null
+    );
+    const healthScore = computeHealthScore(newest, nowMs);
+    const linkedProfileId =
+      group
+        .map((g) => ctx.linkedProfilesByPath[g.absPath] ?? null)
+        .find((v) => v != null) ?? null;
+    const primary = group[0];
+    out.push({
+      ...primary,
+      healthScore,
+      syncStatus,
+      linkedProfileId,
+      absPaths: group.map((g) => g.absPath),
+    });
+  }
+  return out;
+}

package/src/lib/environment/skill-recommendations.ts

@@ -0,0 +1,66 @@
+import type { EnrichedSkill } from "./skill-enrichment";
+
+const STOPWORDS = new Set([
+  "the","and","for","with","that","this","from","have","your","will","not","but",
+  "you","are","was","can","any","all","has","his","her","how","who","why","what",
+  "when","where","use","using","used","its","into","new","one","two","get","got",
+  "please","help","like","need","want","make","made","just","also","some",
+  "more","most","very","than","then","them","they","their","out","off","put",
+  "let","say","said","see","saw","per","via","about","over","under","code",
+  "file","files",
+]);
+
+const MIN_KEYWORD_LEN = 4;
+const MIN_DISTINCT_HITS = 2;
+
+interface Options {
+  activeSkillId?: string | null;
+  dismissedIds?: Set<string>;
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= MIN_KEYWORD_LEN && !STOPWORDS.has(t));
+}
+
+export function computeRecommendation(
+  skills: EnrichedSkill[],
+  recentMessages: string[],
+  opts: Options = {}
+): EnrichedSkill | null {
+  if (recentMessages.length === 0) return null;
+  const messageTokens = new Set(tokenize(recentMessages.join(" ")));
+  if (messageTokens.size === 0) return null;
+
+  const candidates: Array<{ skill: EnrichedSkill; hits: number }> = [];
+
+  for (const skill of skills) {
+    if (opts.activeSkillId && skill.id === opts.activeSkillId) continue;
+    if (opts.dismissedIds?.has(skill.id)) continue;
+    if (skill.healthScore !== "healthy" && skill.healthScore !== "stale") continue;
+
+    const skillTokens = new Set(tokenize(`${skill.name} ${skill.preview}`));
+    let hits = 0;
+    for (const t of skillTokens) {
+      if (messageTokens.has(t)) hits++;
+    }
+    if (hits >= MIN_DISTINCT_HITS) {
+      candidates.push({ skill, hits });
+    }
+  }
+
+  if (candidates.length === 0) return null;
+
+  // Rank by hits DESC, then health (healthy > stale), then name for determinism.
+  candidates.sort((a, b) => {
+    if (a.hits !== b.hits) return b.hits - a.hits;
+    if (a.skill.healthScore !== b.skill.healthScore) {
+      return a.skill.healthScore === "healthy" ? -1 : 1;
+    }
+    return a.skill.name.localeCompare(b.skill.name);
+  });
+
+  return candidates[0].skill;
+}

package/src/lib/filters/__tests__/parse.quoted.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { parseFilterInput } from "../parse";
+
+describe("parseFilterInput — quoted values", () => {
+  it("parses a double-quoted value with spaces", () => {
+    expect(parseFilterInput('#tag:"needs review"')).toEqual({
+      clauses: [{ key: "tag", value: "needs review" }],
+      rawQuery: "",
+    });
+  });
+
+  it("preserves raw query surrounding a quoted clause", () => {
+    expect(parseFilterInput('auth #label:"in progress" redesign')).toEqual({
+      clauses: [{ key: "label", value: "in progress" }],
+      rawQuery: "auth redesign",
+    });
+  });
+
+  it("allows `#` inside quoted values (previously a terminator)", () => {
+    expect(parseFilterInput('#note:"see #123"')).toEqual({
+      clauses: [{ key: "note", value: "see #123" }],
+      rawQuery: "",
+    });
+  });
+
+  it("falls back to whitespace termination for unquoted values", () => {
+    expect(parseFilterInput("#status:blocked more text")).toEqual({
+      clauses: [{ key: "status", value: "blocked" }],
+      rawQuery: "more text",
+    });
+  });
+
+  it("treats a lone opening quote as an unquoted value (malformed input survives)", () => {
+    // Fallback behavior: the regex's unquoted alternative matches `"unterminated` as the bare value
+    // since there's no closing quote. Acceptable degradation — no crash.
+    const result = parseFilterInput('#tag:"unterminated');
+    expect(result.clauses).toEqual([{ key: "tag", value: '"unterminated' }]);
+    expect(result.rawQuery).toBe("");
+  });
+});