stagent 0.9.6 → 0.11.0

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/__tests__/openai-codex-auth.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  extractPlanTypeFromIdToken,
+  readCodexAuthStateFromClient,
+} from "@/lib/agents/runtime/openai-codex-auth";
+
+describe("openai codex auth", () => {
+  it("keeps a ChatGPT session connected when rate limit decoding fails", async () => {
+    const client = {
+      request: vi.fn(async (method: string) => {
+        if (method === "account/read") {
+          return {
+            account: {
+              type: "chatgpt",
+              email: "sehgal.manav@gmail.com",
+              planType: "prolite",
+            },
+            requiresOpenaiAuth: false,
+          };
+        }
+
+        if (method === "account/rateLimits/read") {
+          throw new Error("unknown variant `prolite`");
+        }
+
+        throw new Error(`Unexpected method: ${method}`);
+      }),
+    };
+
+    const state = await readCodexAuthStateFromClient(client as never, {
+      refreshToken: true,
+    });
+
+    expect(state.connected).toBe(true);
+    expect(state.account).toEqual({
+      type: "chatgpt",
+      email: "sehgal.manav@gmail.com",
+      planType: "prolite",
+    });
+    expect(state.rateLimits).toBeNull();
+    expect(state.authMode).toBe("chatgpt");
+  });
+
+  it("recovers the plan type from the rate limit error payload when account/read omits it", async () => {
+    const client = {
+      request: vi.fn(async (method: string) => {
+        if (method === "account/read") {
+          return {
+            account: {
+              type: "chatgpt",
+              email: "sehgal.manav@gmail.com",
+              planType: null,
+            },
+            requiresOpenaiAuth: false,
+          };
+        }
+
+        if (method === "account/rateLimits/read") {
+          throw new Error('Decode error: body={ "plan_type": "prolite" }');
+        }
+
+        throw new Error(`Unexpected method: ${method}`);
+      }),
+    };
+
+    const state = await readCodexAuthStateFromClient(client as never);
+
+    expect(state.connected).toBe(true);
+    expect(state.account?.planType).toBe("prolite");
+    expect(state.rateLimits).toBeNull();
+  });
+
+  it("treats account/read planType=unknown as missing and recovers the upstream plan", async () => {
+    const client = {
+      request: vi.fn(async (method: string) => {
+        if (method === "account/read") {
+          return {
+            account: {
+              type: "chatgpt",
+              email: "sehgal.manav@gmail.com",
+              planType: "unknown",
+            },
+            requiresOpenaiAuth: false,
+          };
+        }
+
+        if (method === "account/rateLimits/read") {
+          throw new Error('Decode error: body={ "plan_type": "prolite" }');
+        }
+
+        throw new Error(`Unexpected method: ${method}`);
+      }),
+    };
+
+    const state = await readCodexAuthStateFromClient(client as never);
+
+    expect(state.connected).toBe(true);
+    expect(state.account?.planType).toBe("prolite");
+    expect(state.rateLimits).toBeNull();
+  });
+
+  it("extracts the plan type from the stored id token payload", async () => {
+    const payload = Buffer.from(
+      JSON.stringify({
+        "https://api.openai.com/auth": {
+          chatgpt_plan_type: "prolite",
+        },
+      })
+    )
+      .toString("base64")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/g, "");
+
+    expect(extractPlanTypeFromIdToken(`header.${payload}.signature`)).toBe("prolite");
+  });
+});

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.
  *

package/src/lib/agents/runtime/codex-app-server-client.ts

@@ -24,7 +24,7 @@ interface JsonRpcNotification {
 type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
 
 export interface CodexAppServerClientOptions {
-  env?: Record<string, string>;
+  env?: Record<string, string | undefined>;
   cwd?: string;
 }
 
@@ -59,15 +59,21 @@ export class CodexAppServerClient {
   ): Promise<CodexAppServerClient> {
     const port = await reservePort();
     const listenUrl = `ws://127.0.0.1:${port}`;
+    const env: NodeJS.ProcessEnv = { ...process.env };
+    for (const [key, value] of Object.entries(options.env ?? {})) {
+      if (value === undefined) {
+        delete env[key];
+      } else {
+        env[key] = value;
+      }
+    }
+
     const child = spawn(
       "codex",
       ["app-server", "--listen", listenUrl],
       {
         cwd: options.cwd,
-        env: {
-          ...process.env,
-          ...(options.env ?? {}),
-        },
+        env,
         stdio: ["ignore", "pipe", "pipe"],
       }
     );