stagent 0.9.6 → 0.11.0

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

@@ -49,7 +49,7 @@ describe("profile registry", () => {
     expect(general!.domain).toBe("work");
   });
 
-  it("returns all 20 builtin profiles", () => {
+  it("returns all 21 builtin profiles", () => {
     const profiles = listProfiles().filter((p) => isBuiltin(p.id));
     const ids = profiles.map((p) => p.id);
 
@@ -68,14 +68,16 @@ describe("profile registry", () => {
     expect(ids).toContain("shopping-assistant");
     expect(ids).toContain("learning-coach");
     expect(ids).toContain("sweep");
-    // 6 new business function profiles
+    // 6 business function profiles
     expect(ids).toContain("marketing-strategist");
     expect(ids).toContain("sales-researcher");
     expect(ids).toContain("customer-support-agent");
     expect(ids).toContain("financial-analyst");
     expect(ids).toContain("content-creator");
     expect(ids).toContain("operations-coordinator");
-    expect(profiles.length).toBe(20);
+    // Clone lifecycle profile
+    expect(ids).toContain("upgrade-assistant");
+    expect(profiles.length).toBe(21);
   });
 
   it("getProfile returns undefined for unknown id", () => {
@@ -96,6 +98,53 @@ describe("profile registry", () => {
     expect(codeReviewer!.canUseToolPolicy!.autoApprove).toContain("Grep");
   });
 
+  it("preserves preferredRuntime from profile.yaml", async () => {
+    const originalHome = process.env.HOME;
+    const tempHome = fs.mkdtempSync(
+      path.join(os.tmpdir(), "registry-preferred-runtime-")
+    );
+
+    try {
+      process.env.HOME = tempHome;
+      vi.resetModules();
+
+      const profileId = `preferred-runtime-${Date.now()}`;
+      const profileDir = path.join(tempHome, ".claude", "skills", profileId);
+      fs.mkdirSync(profileDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(profileDir, "profile.yaml"),
+        yaml.dump({
+          id: profileId,
+          name: "Preferred Runtime Test",
+          version: "1.0.0",
+          domain: "work",
+          tags: ["runtime"],
+          preferredRuntime: "openai-direct",
+        })
+      );
+      fs.writeFileSync(
+        path.join(profileDir, "SKILL.md"),
+        `---
+name: ${profileId}
+description: Preferred runtime test profile.
+---
+
+Testing preferred runtime loading.
+`
+      );
+
+      const registry = await import("../registry");
+      const loaded = registry.getProfile(profileId);
+
+      expect(loaded).toBeDefined();
+      expect(loaded?.preferredRuntime).toBe("openai-direct");
+    } finally {
+      process.env.HOME = originalHome;
+      fs.rmSync(tempHome, { recursive: true, force: true });
+      vi.resetModules();
+    }
+  });
+
   it("getProfileTags returns tag map", () => {
     const tagMap = getProfileTags();
     expect(tagMap.get("researcher")).toContain("research");
@@ -129,7 +178,7 @@ describe("profile registry", () => {
       (p) => p.domain === "personal"
     );
 
-    expect(workProfiles.length).toBe(15); // general, code-reviewer, researcher, document-writer, project-manager, data-analyst, technical-writer, devops-engineer, sweep + 6 business profiles
+    expect(workProfiles.length).toBe(16); // general, code-reviewer, researcher, document-writer, project-manager, data-analyst, technical-writer, devops-engineer, sweep + 6 business profiles + upgrade-assistant
     expect(personalProfiles.length).toBe(5); // wealth-manager, travel-planner, health-fitness-coach, shopping-assistant, learning-coach
   });
 

package/src/lib/agents/profiles/builtins/upgrade-assistant/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: upgrade-assistant
+description: Guided interactive git merge of upstream stagent commits into the user's local instance branch
+---
+
+You are the Upgrade Assistant for a stagent clone. Your job is to pull upstream commits from `origin/main` into the user's instance branch safely and interactively, surfacing merge conflicts in plain language so the user can decide how to resolve them.
+
+## Context for this upgrade
+
+- **Instance branch:** `{{INSTANCE_BRANCH}}`
+- **Upstream commits behind:** `{{COMMITS_BEHIND}}`
+- **Data directory:** `{{DATA_DIR}}`
+- **Working directory:** the current repo root
+
+## How to ask the user a question
+
+**Never emit a question as plain text in the log.** The session UI cannot turn text into a reply input. Always invoke the `AskUserQuestion` tool — the user sees a structured prompt in the task view and the tool call returns with their answer so you can continue.
+
+Two canonical shapes:
+
+- **Free-form answer** (for "should I…" questions that don't have a fixed choice set):
+  ```
+  AskUserQuestion({ question: "Your main branch has 3 commits not in origin/main. Move them to `local` and reset main, or abort so you can review?" })
+  ```
+  The user types a reply and the tool returns `{ answer: "..."}`. Act on it.
+
+- **Choice-based answer** (for merge-conflict resolution — always three canonical choices):
+  ```
+  AskUserQuestion({
+    question: "Conflict in src/app/page.tsx — which version do you want?",
+    options: [
+      { label: "Keep my version",     description: "Use your changes; discard main's version" },
+      { label: "Take main's version", description: "Use main's changes; discard yours" },
+      { label: "Show me the diff",    description: "Output the full conflict diff for manual review" }
+    ]
+  })
+  ```
+  The tool returns `{ answer: "Keep my version" }` (or one of the other labels). Run the matching `git checkout --ours` / `--theirs` / `git diff` command and continue.
+
+If the answer is free-form prose, read it literally. Do not second-guess the user.
+
+## Crucial rules — read these before doing anything
+
+1. **Never modify `main` except by fast-forward.** After fetching, merge `origin/main` into local `main` with `--ff-only`. If that fast-forward fails, the user has local commits on `main` that aren't in `origin/main` — **invoke `AskUserQuestion`** asking whether to move them to `{{INSTANCE_BRANCH}}` or abort so they can review. Do not auto-resolve.
+
+2. **Never push any branch.** The pre-push hook blocks `{{INSTANCE_BRANCH}}` pushes, but you should not even attempt one. Your job ends at a local commit.
+
+3. **If any step fails, roll back.** On any error after the merge has begun, run `git merge --abort` and `git stash pop` (if you stashed earlier) before reporting the failure. Leave the working tree in the state the user started in.
+
+4. **Treat `local` identically to any named instance branch.** Users with a default single-clone setup have `{{INSTANCE_BRANCH}}=local`. Users running private domain clones have names like `wealth-mgr` or `investor-mgr`. The merge flow is identical in both cases.
+
+5. **Stop and ask on merge conflicts — always via `AskUserQuestion`.** Do not guess and do not emit the question as plain text. For each conflicted file, invoke `AskUserQuestion` with the three-choice payload shown above in "How to ask the user a question". Map the returned `answer` to the git command:
+   - **"Keep my version"** → `git checkout --ours <file>`
+   - **"Take main's version"** → `git checkout --theirs <file>`
+   - **"Show me the diff"** → `git diff <file>` and output the full conflict; then re-invoke `AskUserQuestion` so the user can pick one of the first two options after reviewing.
+   After all conflicts are resolved, `git add` the files and continue the merge.
+
+## Standard merge flow
+
+Execute these steps in order. Report progress as you go so the live log view shows the user what's happening.
+
+1. **Pre-flight check.** Run `git status` to confirm the working tree state. If there's uncommitted work, tell the user you'll stash it first.
+
+2. **Stash any work-in-progress.** If the working tree is dirty, run `git stash push -m "upgrade-session auto-stash"`. Record that you stashed — you need to pop it at the end.
+
+3. **Fetch origin.** Run `git fetch origin main`. This is the only network operation. If it fails, report the error and stop.
+
+4. **Fast-forward main.** Run `git checkout main` then `git merge --ff-only origin/main`. If `--ff-only` fails, stop and ask the user (see Rule 1).
+
+5. **Return to the instance branch.** Run `git checkout {{INSTANCE_BRANCH}}`.
+
+6. **Merge main into the instance branch.** Run `git merge main`. If there are conflicts, git will report them. For each conflicted file, use the three-choice flow (Rule 5).
+
+7. **Complete the merge commit.** After conflicts are resolved (or if there were none), run `git commit` to finalize the merge if git hasn't already done so automatically.
+
+8. **Reinstall dependencies if package-lock.json changed.** Check `git diff HEAD~1 HEAD -- package-lock.json`. If there are changes, run `npm install`.
+
+9. **Pop the stash.** If you stashed in step 2, run `git stash pop`. Then immediately run `git status` to check for conflicts. If any file shows "both modified" or "Unmerged", the stash pop conflicted — resolve each file using the same three-choice flow (Rule 5), then `git add` the resolved files. After all stash conflicts are resolved, run `git stash drop` to remove the stash entry (a conflicted pop does NOT auto-drop the stash). Finally, run `grep -rn "<<<<<<< \|>>>>>>>" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.json" .` to verify no conflict markers remain in the working tree.
+
+10. **Report completion.** Tell the user the merge is complete, how many new commits landed, whether dependencies were reinstalled, and that they should restart the dev server to apply changes.
+
+## Aborting
+
+If the user clicks "Abort" during the session, or if any step fails irrecoverably, run:
+- `git merge --abort` (safe to run even if no merge is in progress — it'll just exit 0)
+- `git checkout {{INSTANCE_BRANCH}}` (return the user to where they started)
+- If you stashed in step 2: run `git stash pop`. Then run `git status` — if there are conflicts from the pop, resolve them using the three-choice flow (Rule 5), `git add` the files, and `git stash drop`. Run `grep -rn "<<<<<<< \|>>>>>>>" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.json" .` to verify no markers remain
+
+Then report the abort and what state the repo is in.
+
+## Guidelines
+
+- Be concise but explanatory. The user is watching a live log — they need enough context to understand what's happening, not a novel.
+- Always name the file path when asking about a conflict.
+- If the user sends a natural-language question mid-merge ("what do these changes do?"), answer it based on the diff before proceeding.
+- Never use `git push`. Never use `git rebase`. Never use `git reset --hard`. Never delete branches. Never touch the remote.
+- If `git status` shows files you didn't touch and the user didn't mention, bring them up before assuming they're safe to stash.

package/src/lib/agents/profiles/builtins/upgrade-assistant/profile.yaml

@@ -0,0 +1,36 @@
+id: upgrade-assistant
+name: Upgrade Assistant
+version: "1.0.0"
+domain: work
+tags: [upgrade, git, merge, maintenance, instance]
+supportedRuntimes: [claude-code, openai-codex-app-server]
+preferredRuntime: claude-code
+
+maxTurns: 40
+
+author: stagent
+
+# Bash tool allowlist — tight scope.
+# The upgrade assistant should only ever run git and npm install, nothing else.
+# Cross-reference: TDR-028 "self-upgrade via task pipeline, not chat tools"
+# explains why this profile is the only safe surface for git shell access.
+allowedTools:
+  - Bash(git fetch *)
+  - Bash(git status)
+  - Bash(git status *)
+  - Bash(git stash *)
+  - Bash(git checkout *)
+  - Bash(git merge *)
+  - Bash(git merge --abort)
+  - Bash(git commit *)
+  - Bash(git diff *)
+  - Bash(git rev-parse *)
+  - Bash(git log *)
+  - Bash(git branch *)
+  - Bash(npm install)
+  - Read
+  - Write
+  # Used for every decision point (merge conflicts, drifted main, etc.) —
+  # the agent must NEVER emit a question as plain text; always invoke this
+  # tool so the user can answer through the session UI.
+  - AskUserQuestion

package/src/lib/agents/profiles/list-fused-profiles.ts

@@ -0,0 +1,104 @@
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { listProfiles } from "./registry";
+import type { AgentProfile } from "./types";
+
+/**
+ * Minimal YAML frontmatter parser — handles the `---\nkey: value\n---\n...`
+ * pattern used by SKILL.md files. Returns null if no frontmatter or no `name`.
+ */
+function parseFrontmatter(content: string): Record<string, string> | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const result: Record<string, string> = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function loadFilesystemSkills(
+  skillsDir: string,
+  origin: "filesystem-project" | "filesystem-user",
+  projectRootDir: string | undefined
+): AgentProfile[] {
+  if (!existsSync(skillsDir)) return [];
+  const profiles: AgentProfile[] = [];
+  for (const entry of readdirSync(skillsDir)) {
+    const skillPath = join(skillsDir, entry);
+    try {
+      if (!statSync(skillPath).isDirectory()) continue;
+      const skillMdPath = join(skillPath, "SKILL.md");
+      if (!existsSync(skillMdPath)) continue;
+      const content = readFileSync(skillMdPath, "utf8");
+      const fm = parseFrontmatter(content);
+      if (!fm || !fm.name) {
+        console.warn(
+          `[listFusedProfiles] skipping ${skillMdPath}: missing name in frontmatter`
+        );
+        continue;
+      }
+      profiles.push({
+        id: fm.name,
+        name: fm.name,
+        description: fm.description ?? "",
+        domain: "skill",
+        tags: [],
+        systemPrompt: content,
+        skillMd: content,
+        allowedTools: [],
+        mcpServers: {},
+        supportedRuntimes: ["claude-code"],
+        origin,
+        scope: origin === "filesystem-project" ? "project" : "user",
+        readOnly: true,
+        projectDir: origin === "filesystem-project" ? projectRootDir : undefined,
+      } as AgentProfile);
+    } catch (err) {
+      console.warn(
+        `[listFusedProfiles] failed to load skill at ${skillPath}:`,
+        (err as Error).message
+      );
+    }
+  }
+  return profiles;
+}
+
+/**
+ * Lists every agent profile reachable from this Stagent instance, merging
+ * registry profiles with filesystem skills ("fused" view):
+ *   1. Registry profiles (builtins + user registry)
+ *   2. User filesystem skills at `~/.claude/skills/*\/SKILL.md` (or `userSkillsDir` override)
+ *   3. Project filesystem skills at `<projectDir>/.claude/skills/*\/SKILL.md`
+ * Dedupes by id — registry profiles win on collision (they're curated), then
+ * user skills win over project skills.
+ *
+ * @param projectDir Absolute path to the active project's working directory (project root)
+ * @param userSkillsDir Override for user skills dir (tests); defaults to `~/.claude/skills`
+ */
+export async function listFusedProfiles(
+  projectDir: string | null | undefined,
+  userSkillsDir: string = join(homedir(), ".claude", "skills")
+): Promise<AgentProfile[]> {
+  const registry = listProfiles();
+  const registryIds = new Set(registry.map((p) => p.id));
+
+  const userSkills = loadFilesystemSkills(userSkillsDir, "filesystem-user", undefined).filter(
+    (p) => !registryIds.has(p.id)
+  );
+
+  const projectSkills = projectDir
+    ? loadFilesystemSkills(
+        join(projectDir, ".claude", "skills"),
+        "filesystem-project",
+        projectDir
+      ).filter((p) => !registryIds.has(p.id) && !userSkills.some((u) => u.id === p.id))
+    : [];
+
+  return [...registry, ...userSkills, ...projectSkills];
+}

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

@@ -118,6 +118,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));
         }
@@ -206,7 +222,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) {

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,
+        },
+      }
+    `);
+  });
 });