stagent 0.10.0 → 0.11.0

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);

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

@@ -21,6 +21,51 @@ export interface RuntimeCapabilities {
   authHealthCheck: boolean;
 }
 
+/**
+ * LLM-surface features that affect what the model sees and which tools/skills
+ * Stagent exposes to it. Distinct from RuntimeCapabilities above, which is
+ * adapter-plumbing concerns (can the adapter resume/cancel/etc.).
+ *
+ * Values reflect post-Phase-1 capability (what the runtime SDK *can* do),
+ * not current engagement (what `engine.ts` currently activates). Downstream
+ * features read this bag to decide rendering, filtering, and dispatch.
+ */
+export interface RuntimeFeatures {
+  /** SDK provides a native skill-invocation tool (e.g. Claude SDK `Skill` tool). */
+  hasNativeSkills: boolean;
+  /** SDK loads skill metadata first, full SKILL.md on demand. */
+  hasProgressiveDisclosure: boolean;
+  /** Read/Grep/Glob/Edit/Write available as LLM tools. */
+  hasFilesystemTools: boolean;
+  /** Bash tool available (Stagent gates via permission bridge). */
+  hasBash: boolean;
+  /** TodoWrite tool available. */
+  hasTodoWrite: boolean;
+  /** Runtime supports delegating to sub-agents (e.g. Task tool). */
+  hasSubagentDelegation: boolean;
+  /** Runtime loads filesystem hooks (pre/post tool-use shell scripts). */
+  hasHooks: boolean;
+  /** Which project-level instructions file the runtime auto-loads, if any. */
+  autoLoadsInstructions: "CLAUDE.md" | "AGENTS.md" | null;
+  /**
+   * Runtime has no native skill support — Stagent must inject SKILL.md content
+   * into the system prompt to expose skills to the LLM.
+   */
+  stagentInjectsSkills: boolean;
+  /**
+   * Runtime supports composing multiple active skills in one conversation.
+   * When false, only one skill may be active at a time (Ollama: context
+   * budget too tight). When true, `activate_skill mode:"add"` is allowed
+   * up to `maxActiveSkills`.
+   */
+  supportsSkillComposition: boolean;
+  /**
+   * Maximum number of skills that may be simultaneously active. Enforced
+   * by the activate_skill tool. Ignored when supportsSkillComposition=false.
+   */
+  maxActiveSkills: number;
+}
+
 export interface RuntimeModelConfig {
   /** Default model ID for this runtime */
   default: string;
@@ -34,6 +79,7 @@ export interface RuntimeCatalogEntry {
   description: string;
   providerId: "anthropic" | "openai" | "ollama";
   capabilities: RuntimeCapabilities;
+  features: RuntimeFeatures;
   /** Model catalog — default and supported model IDs for this runtime */
   models: RuntimeModelConfig;
 }
@@ -54,6 +100,19 @@ const RUNTIME_CATALOG: Record<AgentRuntimeId, RuntimeCatalogEntry> = {
       profileAssist: true,
       authHealthCheck: true,
     },
+    features: {
+      hasNativeSkills: true,
+      hasProgressiveDisclosure: true,
+      hasFilesystemTools: true,
+      hasBash: true,
+      hasTodoWrite: true,
+      hasSubagentDelegation: false, // Stagent task primitives replace SDK Task tool
+      hasHooks: false, // excluded per Q2
+      autoLoadsInstructions: "CLAUDE.md",
+      stagentInjectsSkills: false,
+      supportsSkillComposition: true,
+      maxActiveSkills: 3,
+    },
     models: {
       default: "sonnet",
       supported: ["haiku", "sonnet", "opus"],
@@ -74,6 +133,19 @@ const RUNTIME_CATALOG: Record<AgentRuntimeId, RuntimeCatalogEntry> = {
       profileAssist: false,
       authHealthCheck: true,
     },
+    features: {
+      hasNativeSkills: true,
+      hasProgressiveDisclosure: true,
+      hasFilesystemTools: true,
+      hasBash: true,
+      hasTodoWrite: true,
+      hasSubagentDelegation: false,
+      hasHooks: false,
+      autoLoadsInstructions: "AGENTS.md",
+      stagentInjectsSkills: false,
+      supportsSkillComposition: true,
+      maxActiveSkills: 3,
+    },
     models: {
       default: "gpt-5.4",
       supported: ["gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex"],
@@ -94,6 +166,21 @@ const RUNTIME_CATALOG: Record<AgentRuntimeId, RuntimeCatalogEntry> = {
       profileAssist: true,
       authHealthCheck: true,
     },
+    features: {
+      // Direct Messages API — no SDK-native skill machinery.
+      // Revisit when chat-claude-sdk-skills designs direct-API skill injection.
+      hasNativeSkills: false,
+      hasProgressiveDisclosure: false,
+      hasFilesystemTools: false,
+      hasBash: false,
+      hasTodoWrite: false,
+      hasSubagentDelegation: false,
+      hasHooks: false,
+      autoLoadsInstructions: null,
+      stagentInjectsSkills: false,
+      supportsSkillComposition: true,
+      maxActiveSkills: 3,
+    },
     models: {
       default: "claude-sonnet-4-20250514",
       supported: ["claude-haiku-4-5-20251001", "claude-sonnet-4-20250514", "claude-opus-4-20250514"],
@@ -114,6 +201,21 @@ const RUNTIME_CATALOG: Record<AgentRuntimeId, RuntimeCatalogEntry> = {
       profileAssist: false,
       authHealthCheck: true,
     },
+    features: {
+      // Direct Responses API — no SDK-native skill machinery.
+      // Revisit when chat-claude-sdk-skills designs direct-API skill injection.
+      hasNativeSkills: false,
+      hasProgressiveDisclosure: false,
+      hasFilesystemTools: false,
+      hasBash: false,
+      hasTodoWrite: false,
+      hasSubagentDelegation: false,
+      hasHooks: false,
+      autoLoadsInstructions: null,
+      stagentInjectsSkills: false,
+      supportsSkillComposition: true,
+      maxActiveSkills: 3,
+    },
     models: {
       default: "gpt-4.1",
       supported: ["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano"],
@@ -134,6 +236,19 @@ const RUNTIME_CATALOG: Record<AgentRuntimeId, RuntimeCatalogEntry> = {
       profileAssist: false,
       authHealthCheck: true,
     },
+    features: {
+      hasNativeSkills: false,
+      hasProgressiveDisclosure: false,
+      hasFilesystemTools: false,
+      hasBash: false,
+      hasTodoWrite: false, // Stagent MCP exposes todo tools separately
+      hasSubagentDelegation: false,
+      hasHooks: false,
+      autoLoadsInstructions: null,
+      stagentInjectsSkills: true,
+      supportsSkillComposition: false,
+      maxActiveSkills: 1,
+    },
     models: {
       default: "llama3",
       supported: [],  // Dynamic — populated from Ollama API at runtime
@@ -157,6 +272,12 @@ export function getRuntimeCapabilities(
   return getRuntimeCatalogEntry(runtimeId).capabilities;
 }
 
+export function getRuntimeFeatures(
+  runtimeId: AgentRuntimeId = DEFAULT_AGENT_RUNTIME
+): RuntimeFeatures {
+  return getRuntimeCatalogEntry(runtimeId).features;
+}
+
 export function resolveAgentRuntime(runtimeId?: string | null): AgentRuntimeId {
   if (!runtimeId) return DEFAULT_AGENT_RUNTIME;
   if (isAgentRuntimeId(runtimeId)) return runtimeId;

package/src/lib/agents/runtime/claude-sdk.ts

@@ -1,3 +1,35 @@
+// ─── Claude Agent SDK options shared by chat and task runtimes ──────
+//
+// Chat (src/lib/chat/engine.ts) and task (src/lib/agents/claude-agent.ts)
+// both construct query() options for the `claude-code` runtime. These
+// constants are the single source of truth so the two code paths cannot
+// drift — a drift that would manifest as "skills work in chat but vanish
+// in tasks on the same project." See features/task-runtime-skill-parity.md
+// and features/chat-claude-sdk-skills.md.
+
+export const CLAUDE_SDK_SETTING_SOURCES = ["user", "project"] as const;
+
+export const CLAUDE_SDK_ALLOWED_TOOLS = [
+  "Skill",
+  "Read",
+  "Grep",
+  "Glob",
+  "Edit",
+  "Write",
+  "Bash",
+  "TodoWrite",
+] as const;
+
+/**
+ * Filesystem tools safe to auto-allow without a permission prompt.
+ * Mirrors the existing browser/exa read-only auto-allow pattern.
+ */
+export const CLAUDE_SDK_READ_ONLY_FS_TOOLS = new Set<string>([
+  "Read",
+  "Grep",
+  "Glob",
+]);
+
 /**
  * Build the environment for the Claude Agent SDK subprocess.
  *