stagent 0.10.0 → 0.11.1

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

@@ -11,6 +11,7 @@ import { invalidateLatestScan, getLatestScan } from "@/lib/environment/data";
 import { db } from "@/lib/db";
 import { environmentArtifacts } from "@/lib/db/schema";
 import { eq, and } from "drizzle-orm";
+import { getStagentProfilesDir } from "@/lib/utils/stagent-paths";
 
 /**
  * Builtins ship inside the repo at src/lib/agents/profiles/builtins/.
@@ -36,6 +37,12 @@ const SKILLS_DIR = path.join(
   "skills"
 );
 
+/**
+ * Auto-promoted profiles (from environment discovery) are written here
+ * instead of SKILLS_DIR to avoid colliding with Claude Code's skill namespace.
+ */
+const PROMOTED_PROFILES_DIR = getStagentProfilesDir();
+
 // ---------------------------------------------------------------------------
 // Cache
 // ---------------------------------------------------------------------------
@@ -43,37 +50,44 @@ const SKILLS_DIR = path.join(
 let profileCache: Map<string, AgentProfile> | null = null;
 let profileCacheSignature: string | null = null;
 
-function getSkillsDirectorySignature(): string {
-  if (!fs.existsSync(SKILLS_DIR)) {
-    return "missing";
-  }
+function getDirectorySignatureParts(baseDir: string): string[] {
+  if (!fs.existsSync(baseDir)) return [];
 
   const entries = fs
-    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .readdirSync(baseDir, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
     .sort((a, b) => a.name.localeCompare(b.name));
 
-  const signatureParts: string[] = [];
+  const parts: string[] = [];
 
   for (const entry of entries) {
-    const dir = path.join(SKILLS_DIR, entry.name);
+    const dir = path.join(baseDir, entry.name);
     const yamlPath = path.join(dir, "profile.yaml");
     const skillPath = path.join(dir, "SKILL.md");
 
-    signatureParts.push(entry.name);
+    parts.push(entry.name);
 
     if (fs.existsSync(yamlPath)) {
       const stats = fs.statSync(yamlPath);
-      signatureParts.push(`yaml:${stats.mtimeMs}:${stats.size}`);
+      parts.push(`yaml:${stats.mtimeMs}:${stats.size}`);
     }
 
     if (fs.existsSync(skillPath)) {
       const stats = fs.statSync(skillPath);
-      signatureParts.push(`skill:${stats.mtimeMs}:${stats.size}`);
+      parts.push(`skill:${stats.mtimeMs}:${stats.size}`);
     }
   }
 
-  return signatureParts.join("|");
+  return parts;
+}
+
+function getSkillsDirectorySignature(): string {
+  const skillsParts = getDirectorySignatureParts(SKILLS_DIR);
+  const promotedParts = getDirectorySignatureParts(PROMOTED_PROFILES_DIR);
+
+  if (skillsParts.length === 0 && promotedParts.length === 0) return "missing";
+
+  return [...skillsParts, "||promoted||", ...promotedParts].join("|");
 }
 
 // ---------------------------------------------------------------------------
@@ -118,6 +132,22 @@ function ensureBuiltins(): void {
           changed = true;
         }
 
+        if (
+          source.preferredRuntime !== undefined &&
+          target.preferredRuntime !== source.preferredRuntime
+        ) {
+          target.preferredRuntime = source.preferredRuntime;
+          changed = true;
+        }
+
+        if (
+          source.capabilityOverrides !== undefined &&
+          target.capabilityOverrides === undefined
+        ) {
+          target.capabilityOverrides = source.capabilityOverrides;
+          changed = true;
+        }
+
         if (changed) {
           fs.writeFileSync(targetYaml, yaml.dump(target));
         }
@@ -140,15 +170,16 @@ function ensureBuiltins(): void {
 // 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;
+function scanProfilesFromDir(
+  baseDir: string,
+  profiles: Map<string, AgentProfile>
+): void {
+  if (!fs.existsSync(baseDir)) return;
 
-  for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+  for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
 
-    const dir = path.join(SKILLS_DIR, entry.name);
+    const dir = path.join(baseDir, entry.name);
     const yamlPath = path.join(dir, "profile.yaml");
     const skillPath = path.join(dir, "SKILL.md");
 
@@ -206,7 +237,9 @@ function scanProfiles(): Map<string, AgentProfile> {
         tests: config.tests,
         importMeta: config.importMeta,
         supportedRuntimes: getSupportedRuntimes(config),
+        preferredRuntime: config.preferredRuntime,
         runtimeOverrides: config.runtimeOverrides,
+        capabilityOverrides: config.capabilityOverrides,
         origin,
       });
     } catch (err) {
@@ -214,6 +247,12 @@ function scanProfiles(): Map<string, AgentProfile> {
     }
   }
 
+}
+
+function scanProfiles(): Map<string, AgentProfile> {
+  const profiles = new Map<string, AgentProfile>();
+  scanProfilesFromDir(SKILLS_DIR, profiles);
+  scanProfilesFromDir(PROMOTED_PROFILES_DIR, profiles);
   return profiles;
 }
 
@@ -299,6 +338,28 @@ export function createProfile(config: ProfileConfig, skillMd: string): void {
   invalidateLatestScan();
 }
 
+/**
+ * Create an auto-promoted profile in ~/.stagent/profiles/ (not ~/.claude/skills/).
+ * This avoids colliding with Claude Code's skill discovery namespace.
+ */
+export function createPromotedProfile(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(PROMOTED_PROFILES_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();
+  invalidateLatestScan();
+}
+
 /** Update an existing custom profile (rejects builtins) */
 export function updateProfile(id: string, config: ProfileConfig, skillMd: string): void {
   if (isBuiltin(id)) {
@@ -310,8 +371,15 @@ export function updateProfile(id: string, config: ProfileConfig, skillMd: string
     throw new Error(`Invalid profile: ${result.error.issues.map(i => i.message).join(", ")}`);
   }
 
-  const dir = path.join(SKILLS_DIR, id);
-  if (!fs.existsSync(dir)) {
+  const skillsDir = path.join(SKILLS_DIR, id);
+  const promotedDir = path.join(PROMOTED_PROFILES_DIR, id);
+  const dir = fs.existsSync(skillsDir)
+    ? skillsDir
+    : fs.existsSync(promotedDir)
+      ? promotedDir
+      : null;
+
+  if (!dir) {
     throw new Error(`Profile "${id}" not found`);
   }
 
@@ -321,14 +389,21 @@ export function updateProfile(id: string, config: ProfileConfig, skillMd: string
   invalidateLatestScan();
 }
 
-/** Delete a custom profile (rejects builtins) */
+/** Delete a custom profile (rejects builtins). Checks both user and promoted dirs. */
 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)) {
+  const skillsDir = path.join(SKILLS_DIR, id);
+  const promotedDir = path.join(PROMOTED_PROFILES_DIR, id);
+  const dir = fs.existsSync(skillsDir)
+    ? skillsDir
+    : fs.existsSync(promotedDir)
+      ? promotedDir
+      : null;
+
+  if (!dir) {
     throw new Error(`Profile "${id}" not found`);
   }
 

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

@@ -31,7 +31,13 @@ export interface ProfileRuntimeCapabilityOverride {
 export type ProfileScope = "builtin" | "user" | "project";
 
 /** How a profile entered the system — distinct from scope (where it lives). */
-export type ProfileOrigin = "manual" | "environment" | "import" | "ai-assist";
+export type ProfileOrigin =
+  | "manual"
+  | "environment"
+  | "import"
+  | "ai-assist"
+  | "filesystem-project"
+  | "filesystem-user";
 
 export interface AgentProfile {
   id: string;

package/src/lib/agents/router.ts

@@ -1,15 +1,12 @@
 import { listProfiles, getProfile } from "./profiles/registry";
 import { profileSupportsRuntime } from "./profiles/compatibility";
-import {
-  executeTaskWithRuntime,
-  resumeTaskWithRuntime,
-} from "./runtime";
 import {
   DEFAULT_AGENT_RUNTIME,
   SUPPORTED_AGENT_RUNTIMES,
   type AgentRuntimeId,
 } from "./runtime/catalog";
 import type { RoutingPreference } from "@/lib/constants/settings";
+import { resumeTaskExecution, startTaskExecution } from "./task-dispatch";
 
 // ── Keyword signal maps for runtime scoring ──────────────────────────
 
@@ -217,12 +214,12 @@ export async function executeTaskWithAgent(
   taskId: string,
   agentType: string | null | undefined = DEFAULT_AGENT_RUNTIME
 ): Promise<void> {
-  return executeTaskWithRuntime(taskId, agentType);
+  return startTaskExecution(taskId, { requestedRuntimeId: agentType });
 }
 
 export async function resumeTaskWithAgent(
   taskId: string,
   agentType: string | null | undefined = DEFAULT_AGENT_RUNTIME
 ): Promise<void> {
-  return resumeTaskWithRuntime(taskId, agentType);
+  return resumeTaskExecution(taskId, { requestedRuntimeId: agentType });
 }

package/src/lib/agents/runtime/__tests__/catalog.test.ts

@@ -3,6 +3,7 @@ import {
   DEFAULT_AGENT_RUNTIME,
   getRuntimeCapabilities,
   getRuntimeCatalogEntry,
+  getRuntimeFeatures,
   listRuntimeCatalog,
   resolveAgentRuntime,
 } from "@/lib/agents/runtime/catalog";
@@ -46,4 +47,133 @@ describe("runtime catalog", () => {
     expect(result).toBe("claude-code");
     warnSpy.mockRestore();
   });
+
+  it("exposes LLM-surface features via getRuntimeFeatures", () => {
+    const features = getRuntimeFeatures("claude-code");
+    expect(features.hasNativeSkills).toBe(true);
+    expect(features.hasProgressiveDisclosure).toBe(true);
+    expect(features.autoLoadsInstructions).toBe("CLAUDE.md");
+    expect(features.stagentInjectsSkills).toBe(false);
+  });
+
+  it("marks Ollama as requiring Stagent-injected skills", () => {
+    const features = getRuntimeFeatures("ollama");
+    expect(features.hasNativeSkills).toBe(false);
+    expect(features.stagentInjectsSkills).toBe(true);
+    expect(features.autoLoadsInstructions).toBeNull();
+  });
+
+  it("declares Codex auto-loads AGENTS.md", () => {
+    expect(getRuntimeFeatures("openai-codex-app-server").autoLoadsInstructions).toBe("AGENTS.md");
+  });
+
+  it("every runtime declares every feature key (exhaustiveness guard)", () => {
+    const runtimes = listRuntimeCatalog();
+    const expectedKeys: Array<keyof ReturnType<typeof getRuntimeFeatures>> = [
+      "hasNativeSkills",
+      "hasProgressiveDisclosure",
+      "hasFilesystemTools",
+      "hasBash",
+      "hasTodoWrite",
+      "hasSubagentDelegation",
+      "hasHooks",
+      "autoLoadsInstructions",
+      "stagentInjectsSkills",
+      "supportsSkillComposition",
+      "maxActiveSkills",
+    ];
+
+    // Guard against the "list grows stale" failure mode: if a new key is added
+    // to RuntimeFeatures but not to expectedKeys above, this catches it.
+    expect(expectedKeys.length).toBe(Object.keys(getRuntimeFeatures()).length);
+
+    for (const runtime of runtimes) {
+      for (const key of expectedKeys) {
+        expect(
+          runtime.features,
+          `${runtime.id} missing feature "${key}"`
+        ).toHaveProperty(key);
+      }
+    }
+  });
+
+  it("feature matrix snapshot matches declared values", () => {
+    // Guard against silent regressions: the declared feature matrix must match
+    // this snapshot exactly. Update intentionally when flipping a capability flag
+    // (and reference the spec change in the commit message).
+    const snapshot = listRuntimeCatalog().reduce<Record<string, unknown>>((acc, r) => {
+      acc[r.id] = r.features;
+      return acc;
+    }, {});
+
+    expect(snapshot).toMatchInlineSnapshot(`
+      {
+        "anthropic-direct": {
+          "autoLoadsInstructions": null,
+          "hasBash": false,
+          "hasFilesystemTools": false,
+          "hasHooks": false,
+          "hasNativeSkills": false,
+          "hasProgressiveDisclosure": false,
+          "hasSubagentDelegation": false,
+          "hasTodoWrite": false,
+          "maxActiveSkills": 3,
+          "stagentInjectsSkills": false,
+          "supportsSkillComposition": true,
+        },
+        "claude-code": {
+          "autoLoadsInstructions": "CLAUDE.md",
+          "hasBash": true,
+          "hasFilesystemTools": true,
+          "hasHooks": false,
+          "hasNativeSkills": true,
+          "hasProgressiveDisclosure": true,
+          "hasSubagentDelegation": false,
+          "hasTodoWrite": true,
+          "maxActiveSkills": 3,
+          "stagentInjectsSkills": false,
+          "supportsSkillComposition": true,
+        },
+        "ollama": {
+          "autoLoadsInstructions": null,
+          "hasBash": false,
+          "hasFilesystemTools": false,
+          "hasHooks": false,
+          "hasNativeSkills": false,
+          "hasProgressiveDisclosure": false,
+          "hasSubagentDelegation": false,
+          "hasTodoWrite": false,
+          "maxActiveSkills": 1,
+          "stagentInjectsSkills": true,
+          "supportsSkillComposition": false,
+        },
+        "openai-codex-app-server": {
+          "autoLoadsInstructions": "AGENTS.md",
+          "hasBash": true,
+          "hasFilesystemTools": true,
+          "hasHooks": false,
+          "hasNativeSkills": true,
+          "hasProgressiveDisclosure": true,
+          "hasSubagentDelegation": false,
+          "hasTodoWrite": true,
+          "maxActiveSkills": 3,
+          "stagentInjectsSkills": false,
+          "supportsSkillComposition": true,
+        },
+        "openai-direct": {
+          "autoLoadsInstructions": null,
+          "hasBash": false,
+          "hasFilesystemTools": false,
+          "hasHooks": false,
+          "hasNativeSkills": false,
+          "hasProgressiveDisclosure": false,
+          "hasSubagentDelegation": false,
+          "hasTodoWrite": false,
+          "maxActiveSkills": 3,
+          "stagentInjectsSkills": false,
+          "supportsSkillComposition": true,
+        },
+      }
+    `);
+  });
 });

package/src/lib/agents/runtime/__tests__/execution-target.test.ts

@@ -0,0 +1,183 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentRuntimeId } from "@/lib/agents/runtime/catalog";
+
+const {
+  mockGetRuntimeSetupStates,
+  mockListConfiguredRuntimeIds,
+  mockGetRoutingPreference,
+  mockTestRuntimeConnection,
+  mockGetProfile,
+  mockProfileSupportsRuntime,
+  mockSuggestRuntime,
+} = vi.hoisted(() => ({
+  mockGetRuntimeSetupStates: vi.fn(),
+  mockListConfiguredRuntimeIds: vi.fn(),
+  mockGetRoutingPreference: vi.fn(),
+  mockTestRuntimeConnection: vi.fn(),
+  mockGetProfile: vi.fn(),
+  mockProfileSupportsRuntime: vi.fn(),
+  mockSuggestRuntime: vi.fn(),
+}));
+
+vi.mock("@/lib/settings/runtime-setup", () => ({
+  getRuntimeSetupStates: mockGetRuntimeSetupStates,
+  listConfiguredRuntimeIds: mockListConfiguredRuntimeIds,
+}));
+
+vi.mock("@/lib/settings/routing", () => ({
+  getRoutingPreference: mockGetRoutingPreference,
+}));
+
+vi.mock("@/lib/agents/runtime/index", () => ({
+  testRuntimeConnection: mockTestRuntimeConnection,
+}));
+
+vi.mock("@/lib/agents/profiles/registry", () => ({
+  getProfile: mockGetProfile,
+}));
+
+vi.mock("@/lib/agents/profiles/compatibility", () => ({
+  profileSupportsRuntime: mockProfileSupportsRuntime,
+}));
+
+vi.mock("@/lib/agents/router", () => ({
+  suggestRuntime: mockSuggestRuntime,
+}));
+
+import {
+  RequestedModelUnavailableError,
+  resolveChatExecutionTarget,
+  resolveResumeExecutionTarget,
+  resolveTaskExecutionTarget,
+} from "../execution-target";
+
+function makeStates(configured: AgentRuntimeId[]) {
+  const all: AgentRuntimeId[] = [
+    "claude-code",
+    "openai-codex-app-server",
+    "anthropic-direct",
+    "openai-direct",
+    "ollama",
+  ];
+
+  return Object.fromEntries(
+    all.map((runtimeId) => [
+      runtimeId,
+      {
+        runtimeId,
+        configured: configured.includes(runtimeId),
+      },
+    ])
+  );
+}
+
+describe("execution target resolver", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetRuntimeSetupStates.mockResolvedValue(
+      makeStates(["claude-code", "openai-codex-app-server"])
+    );
+    mockListConfiguredRuntimeIds.mockReturnValue([
+      "claude-code",
+      "openai-codex-app-server",
+    ]);
+    mockGetRoutingPreference.mockResolvedValue("latency");
+    mockProfileSupportsRuntime.mockReturnValue(true);
+    mockSuggestRuntime.mockImplementation(
+      (
+        _title: string,
+        _description: string | undefined,
+        _profileId: string | undefined,
+        availableRuntimeIds: AgentRuntimeId[]
+      ) => ({
+        runtimeId: availableRuntimeIds[0],
+        reason: "test",
+      })
+    );
+    mockTestRuntimeConnection.mockImplementation((runtimeId: AgentRuntimeId) => {
+      if (runtimeId === "claude-code") {
+        return Promise.resolve({
+          connected: false,
+          error: "Claude Code process exited with code 1",
+        });
+      }
+      return Promise.resolve({ connected: true });
+    });
+  });
+
+  it("falls back from an unavailable requested task runtime to a compatible alternate", async () => {
+    mockGetProfile.mockReturnValue({
+      id: "upgrade-assistant",
+      allowedTools: ["Bash(git status)", "Read", "Write"],
+    });
+
+    const target = await resolveTaskExecutionTarget({
+      title: "Upgrade local branch",
+      description: "Merge upstream main safely",
+      requestedRuntimeId: "claude-code",
+      profileId: "upgrade-assistant",
+    });
+
+    expect(target.requestedRuntimeId).toBe("claude-code");
+    expect(target.effectiveRuntimeId).toBe("openai-codex-app-server");
+    expect(target.fallbackApplied).toBe(true);
+    expect(target.fallbackReason).toContain("Fell back to OpenAI Codex App Server");
+  });
+
+  it("auto-selects a healthy runtime when no task runtime was requested", async () => {
+    mockGetProfile.mockReturnValue({
+      id: "general",
+      allowedTools: [],
+      preferredRuntime: "anthropic-direct",
+    });
+    mockSuggestRuntime.mockReturnValue({
+      runtimeId: "openai-codex-app-server",
+      reason: "test",
+    });
+
+    const target = await resolveTaskExecutionTarget({
+      title: "Fix failing build",
+      description: "Debug and patch the repo",
+      profileId: "general",
+    });
+
+    expect(target.requestedRuntimeId).toBeNull();
+    expect(target.effectiveRuntimeId).toBe("openai-codex-app-server");
+    expect(target.fallbackApplied).toBe(false);
+  });
+
+  it("falls back chat turns to the mapped alternate model when the requested runtime is unavailable", async () => {
+    const target = await resolveChatExecutionTarget({
+      requestedRuntimeId: "claude-code",
+      requestedModelId: "sonnet",
+    });
+
+    expect(target.requestedRuntimeId).toBe("claude-code");
+    expect(target.effectiveRuntimeId).toBe("openai-codex-app-server");
+    expect(target.effectiveModelId).toBe("gpt-5.3-codex");
+    expect(target.fallbackApplied).toBe(true);
+  });
+
+  it("refuses resume when the last effective runtime is unavailable", async () => {
+    await expect(
+      resolveResumeExecutionTarget({
+        requestedRuntimeId: "claude-code",
+        effectiveRuntimeId: "claude-code",
+      })
+    ).rejects.toThrow("Claude Code process exited with code 1");
+  });
+
+  it("throws a named error when no chat runtime is healthy", async () => {
+    mockTestRuntimeConnection.mockResolvedValue({
+      connected: false,
+      error: "all down",
+    });
+
+    await expect(
+      resolveChatExecutionTarget({
+        requestedRuntimeId: "claude-code",
+        requestedModelId: "sonnet",
+      })
+    ).rejects.toBeInstanceOf(RequestedModelUnavailableError);
+  });
+});

package/src/lib/agents/runtime/anthropic-direct.ts

@@ -481,6 +481,14 @@ async function executeAnthropicDirectTask(taskId: string, isResume = false): Pro
       startedAt: usageState.startedAt,
       finishedAt: new Date(),
     });
+
+    await db
+      .update(tasks)
+      .set({
+        effectiveModelId: result.totalUsage.modelId ?? modelId,
+        updatedAt: new Date(),
+      })
+      .where(eq(tasks.id, taskId));
   } catch (err) {
     if (!abortController.signal.aborted) {
       const errorMsg = err instanceof Error ? err.message : String(err);