stagent 0.9.6 → 0.11.0

package/src/lib/chat/__tests__/stream-telemetry.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  recordTermination,
+  readTerminations,
+  countTerminations,
+  __resetForTesting,
+} from "../stream-telemetry";
+
+describe("stream-telemetry ring buffer", () => {
+  beforeEach(() => {
+    __resetForTesting();
+  });
+
+  it("returns [] before any events are recorded", () => {
+    expect(readTerminations()).toEqual([]);
+  });
+
+  it("records events in chronological order", () => {
+    recordTermination({
+      reason: "stream.completed",
+      conversationId: "c1",
+      messageId: "m1",
+      durationMs: 100,
+    });
+    recordTermination({
+      reason: "stream.aborted.client",
+      conversationId: "c2",
+      messageId: "m2",
+      durationMs: 50,
+    });
+
+    const events = readTerminations();
+    expect(events).toHaveLength(2);
+    expect(events[0].reason).toBe("stream.completed");
+    expect(events[1].reason).toBe("stream.aborted.client");
+    expect(events[0].timestamp).toBeLessThanOrEqual(events[1].timestamp);
+  });
+
+  it("stamps each event with a timestamp", () => {
+    const before = Date.now();
+    recordTermination({
+      reason: "stream.completed",
+      conversationId: "c1",
+      messageId: "m1",
+      durationMs: 0,
+    });
+    const after = Date.now();
+    const events = readTerminations();
+    expect(events[0].timestamp).toBeGreaterThanOrEqual(before);
+    expect(events[0].timestamp).toBeLessThanOrEqual(after);
+  });
+
+  it("wraps around after 500 events, preserving newest-500 in order", () => {
+    // Write 520 events — first 20 should be evicted.
+    for (let i = 0; i < 520; i++) {
+      recordTermination({
+        reason: "stream.completed",
+        conversationId: `c${i}`,
+        messageId: `m${i}`,
+        durationMs: i,
+      });
+    }
+
+    const events = readTerminations();
+    expect(events).toHaveLength(500);
+    // Oldest surviving event should be #20; newest should be #519.
+    expect(events[0].conversationId).toBe("c20");
+    expect(events[0].durationMs).toBe(20);
+    expect(events[499].conversationId).toBe("c519");
+    expect(events[499].durationMs).toBe(519);
+  });
+
+  it("countTerminations groups by reason code across the full buffer", () => {
+    recordTermination({ reason: "stream.completed", conversationId: "c", messageId: "m", durationMs: 1 });
+    recordTermination({ reason: "stream.completed", conversationId: "c", messageId: "m", durationMs: 1 });
+    recordTermination({ reason: "stream.aborted.client", conversationId: "c", messageId: "m", durationMs: 1 });
+    recordTermination({ reason: "stream.finalized.error", conversationId: "c", messageId: "m", durationMs: 1, error: "boom" });
+    recordTermination({ reason: "stream.abandoned", conversationId: "c", messageId: "m", durationMs: 42 });
+
+    const counts = countTerminations();
+    expect(counts["stream.completed"]).toBe(2);
+    expect(counts["stream.aborted.client"]).toBe(1);
+    expect(counts["stream.finalized.error"]).toBe(1);
+    expect(counts["stream.abandoned"]).toBe(1);
+    expect(counts["stream.aborted.signal"]).toBe(0);
+    expect(counts["stream.reconciled.stale"]).toBe(0);
+  });
+
+  it("stream.abandoned is a valid reason code for iterator abandonment", () => {
+    // finalizeStreamingMessage records this when the engine's happy and
+    // catch paths both missed the termination — the canonical "gap"
+    // indicator. Make sure it round-trips through the buffer.
+    recordTermination({
+      reason: "stream.abandoned",
+      conversationId: "c1",
+      messageId: "m1",
+      durationMs: 100,
+      error: "no content streamed before abandonment",
+    });
+    const events = readTerminations();
+    expect(events[0].reason).toBe("stream.abandoned");
+    expect(events[0].error).toBe("no content streamed before abandonment");
+  });
+
+  it("countTerminations honors the windowMs filter", async () => {
+    recordTermination({ reason: "stream.completed", conversationId: "c", messageId: "m", durationMs: 1 });
+    // Wait a few ms so the second event has a strictly later timestamp.
+    await new Promise((r) => setTimeout(r, 10));
+    const midpoint = Date.now();
+    await new Promise((r) => setTimeout(r, 10));
+    recordTermination({ reason: "stream.completed", conversationId: "c", messageId: "m", durationMs: 1 });
+
+    // Use a window that only includes the second event.
+    const windowMs = Date.now() - midpoint + 5;
+    const counts = countTerminations(windowMs);
+    expect(counts["stream.completed"]).toBe(1);
+  });
+
+  it("readTerminations returns a copy, not a live reference", () => {
+    recordTermination({ reason: "stream.completed", conversationId: "c", messageId: "m", durationMs: 1 });
+    const first = readTerminations();
+    recordTermination({ reason: "stream.completed", conversationId: "c2", messageId: "m2", durationMs: 1 });
+    // first snapshot should still have only the initial event.
+    expect(first).toHaveLength(1);
+    expect(readTerminations()).toHaveLength(2);
+  });
+
+  it("records optional error strings on error events", () => {
+    recordTermination({
+      reason: "stream.finalized.error",
+      conversationId: "c",
+      messageId: "m",
+      durationMs: 42,
+      error: "boom",
+    });
+    expect(readTerminations()[0].error).toBe("boom");
+  });
+
+  it("allows null conversationId / messageId / durationMs for edge cases", () => {
+    recordTermination({
+      reason: "stream.reconciled.stale",
+      conversationId: null,
+      messageId: null,
+      durationMs: null,
+    });
+    const events = readTerminations();
+    expect(events[0].conversationId).toBeNull();
+    expect(events[0].messageId).toBeNull();
+    expect(events[0].durationMs).toBeNull();
+  });
+});

package/src/lib/chat/__tests__/types.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { getFeaturesForModel, getRuntimeForModel } from "@/lib/chat/types";
+
+describe("getFeaturesForModel", () => {
+  it("returns Claude features for a Claude model id", () => {
+    const features = getFeaturesForModel("sonnet");
+    expect(features.hasNativeSkills).toBe(true);
+    expect(features.autoLoadsInstructions).toBe("CLAUDE.md");
+  });
+
+  it("returns Ollama features for an ollama-prefixed model id", () => {
+    const features = getFeaturesForModel("ollama:llama3");
+    expect(features.stagentInjectsSkills).toBe(true);
+    expect(features.hasNativeSkills).toBe(false);
+  });
+
+  it("returns Codex features for a GPT model id", () => {
+    const features = getFeaturesForModel("gpt-5.4");
+    expect(features.autoLoadsInstructions).toBe("AGENTS.md");
+  });
+
+  it("falls back to claude-code features for an unknown model id", () => {
+    // getRuntimeForModel's fallback chain lands on claude-code for unknown ids.
+    const features = getFeaturesForModel("totally-made-up-model");
+    expect(features.hasNativeSkills).toBe(true);
+    expect(getRuntimeForModel("totally-made-up-model")).toBe("claude-code");
+  });
+});

package/src/lib/chat/active-skills.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure helper for combining the legacy `conversations.active_skill_id`
+ * column with the new `conversations.active_skill_ids` JSON array
+ * (`features/chat-skill-composition.md`).
+ *
+ * Lives in its own module (no DB imports) so client components can use
+ * it without pulling server-only code into the bundle. The original
+ * lived alongside the chat-tool definition in `tools/skill-tools.ts`,
+ * which can only run server-side.
+ */
+
+export function mergeActiveSkillIds(
+  legacyId: string | null | undefined,
+  composed: string[] | null | undefined
+): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  if (legacyId) {
+    out.push(legacyId);
+    seen.add(legacyId);
+  }
+  if (composed) {
+    for (const id of composed) {
+      if (id && !seen.has(id)) {
+        out.push(id);
+        seen.add(id);
+      }
+    }
+  }
+  return out;
+}

package/src/lib/chat/active-streams.ts

@@ -0,0 +1,27 @@
+/**
+ * In-memory tracker for chat conversations that currently have an SSE stream
+ * in flight. Used by the scheduler tick loop to apply a soft pressure signal
+ * — when chat is active, new schedule firings are deferred by N seconds to
+ * keep the Node event loop responsive for the user's conversation.
+ *
+ * Module-level state; single-process (same Node instance as the scheduler).
+ * Must NOT be persisted — crash recovery relies on the set starting empty.
+ */
+
+const activeStreams = new Set<string>();
+
+export function registerChatStream(conversationId: string): void {
+  activeStreams.add(conversationId);
+}
+
+export function unregisterChatStream(conversationId: string): void {
+  activeStreams.delete(conversationId);
+}
+
+export function getActiveChatStreamCount(): number {
+  return activeStreams.size;
+}
+
+export function isAnyChatStreaming(): boolean {
+  return activeStreams.size > 0;
+}

package/src/lib/chat/clean-filter-input.ts

@@ -0,0 +1,30 @@
+/**
+ * Sanitize the filterInput we persist for a saved search.
+ *
+ * The chat popover input may include the mention trigger prefix
+ * (e.g. `@task: ` or `task: ` depending on what the trigger regex
+ * stripped). When the user "Saves this view", we want the persisted
+ * filterInput to contain ONLY the meaningful filter expression —
+ * `#key:value` clauses plus any free-text search the user typed —
+ * not the trigger residue.
+ *
+ * Pure function. Tested in isolation; called from
+ * `chat-command-popover.tsx` at the SaveViewFooter call site.
+ *
+ * See `features/saved-search-polish-v1.md` for the bug history.
+ */
+
+import type { FilterClause } from "@/lib/filters/parse";
+
+const TRIGGER_RESIDUE = /^@?[a-z]+:\s*/i;
+
+export function cleanFilterInput(
+  clauses: FilterClause[],
+  rawQuery: string
+): string {
+  const cleanRawQuery = rawQuery.replace(TRIGGER_RESIDUE, "").trim();
+  return [
+    ...clauses.map((c) => `#${c.key}:${c.value}`),
+    ...(cleanRawQuery ? [cleanRawQuery] : []),
+  ].join(" ");
+}

package/src/lib/chat/codex-engine.ts

@@ -2,7 +2,10 @@ import { db } from "@/lib/db";
 import { projects } from "@/lib/db/schema";
 import { eq } from "drizzle-orm";
 import { CodexAppServerClient } from "@/lib/agents/runtime/codex-app-server-client";
-import { getOpenAIApiKey } from "@/lib/settings/openai-auth";
+import {
+  ensureOpenAICodexClientAuthenticated,
+  resolveOpenAICodexAuthContext,
+} from "@/lib/agents/runtime/openai-codex-auth";
 import {
   extractUsageSnapshot,
   mergeUsageSnapshot,
@@ -31,6 +34,7 @@ import {
   cleanupConversation,
 } from "./permission-bridge";
 import { getWorkspaceContext } from "@/lib/environment/workspace-context";
+import type { ResolvedExecutionTarget } from "@/lib/agents/runtime/execution-target";
 
 // ── Helpers ──────────────────────────────────────────────────────────────
 
@@ -54,7 +58,8 @@ function asString(v: unknown): string | null {
 export async function* sendCodexMessage(
   conversationId: string,
   userContent: string,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  targetOverride?: ResolvedExecutionTarget
 ): AsyncGenerator<ChatStreamEvent> {
   const conversation = await getConversation(conversationId);
   if (!conversation) {
@@ -62,7 +67,7 @@ export async function* sendCodexMessage(
     return;
   }
 
-  const runtimeId = conversation.runtimeId;
+  const runtimeId = targetOverride?.effectiveRuntimeId ?? conversation.runtimeId;
   const providerId = getProviderForRuntime(runtimeId);
 
   // Enforce budget
@@ -128,11 +133,17 @@ export async function* sendCodexMessage(
   });
 
   // Get OpenAI API key
-  const { apiKey } = await getOpenAIApiKey();
-  if (!apiKey) {
-    await updateMessageContent(assistantMsg.id, "OpenAI API key is not configured. Add it in Settings → Auth.");
+  let auth;
+  try {
+    auth = await resolveOpenAICodexAuthContext();
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? error.message
+        : "OpenAI Codex authentication is not configured.";
+    await updateMessageContent(assistantMsg.id, message);
     await updateMessageStatus(assistantMsg.id, "error");
-    yield { type: "error", message: "OpenAI API key is not configured. Add it in Settings → Auth." };
+    yield { type: "error", message };
     return;
   }
 
@@ -164,20 +175,10 @@ export async function* sendCodexMessage(
   }
 
   try {
-    client = await CodexAppServerClient.connect({
-      cwd: workspace.cwd,
-      env: { OPENAI_API_KEY: apiKey },
-    });
+    client = await auth.connect(workspace.cwd);
 
     // Initialize and authenticate
-    await client.request("initialize", {
-      clientInfo: { name: "Stagent", version: "0.1.1" },
-      capabilities: null,
-    });
-    await client.request("account/login/start", {
-      type: "apiKey",
-      apiKey,
-    });
+    await ensureOpenAICodexClientAuthenticated(client, auth);
 
     // Validate model availability against what the user's account supports
     let validatedModel: string | undefined;
@@ -188,8 +189,10 @@ export async function* sendCodexMessage(
       const availableIds = new Set(
         (modelResponse.models ?? []).map((m: { id: string }) => m.id)
       );
-      if (conversation.modelId && availableIds.has(conversation.modelId)) {
-        validatedModel = conversation.modelId;
+      const requestedModelId =
+        targetOverride?.effectiveModelId ?? conversation.modelId;
+      if (requestedModelId && availableIds.has(requestedModelId)) {
+        validatedModel = requestedModelId;
       }
       // If not available, validatedModel stays undefined → Codex uses its default
     } catch {
@@ -377,7 +380,18 @@ export async function* sendCodexMessage(
 
     // Save usage metadata
     const metadata = JSON.stringify({
-      modelId: usage.modelId ?? conversation.modelId,
+      modelId:
+        usage.modelId ??
+        targetOverride?.effectiveModelId ??
+        conversation.modelId,
+      runtimeId,
+      requestedRuntimeId:
+        targetOverride?.requestedRuntimeId ?? conversation.runtimeId,
+      requestedModelId:
+        targetOverride?.requestedModelId ?? conversation.modelId,
+      ...(targetOverride?.fallbackReason
+        ? { fallbackReason: targetOverride.fallbackReason }
+        : {}),
       inputTokens: usage.inputTokens,
       outputTokens: usage.outputTokens,
       ...(quickAccess.length > 0 ? { quickAccess } : {}),
@@ -394,7 +408,11 @@ export async function* sendCodexMessage(
       activityType: "chat_turn",
       runtimeId,
       providerId,
-      modelId: usage.modelId ?? conversation.modelId ?? null,
+      modelId:
+        usage.modelId ??
+        targetOverride?.effectiveModelId ??
+        conversation.modelId ??
+        null,
       inputTokens: usage.inputTokens ?? null,
       outputTokens: usage.outputTokens ?? null,
       totalTokens: usage.totalTokens ?? null,
@@ -414,7 +432,11 @@ export async function* sendCodexMessage(
       activityType: "chat_turn",
       runtimeId,
       providerId,
-      modelId: usage.modelId ?? conversation.modelId ?? null,
+      modelId:
+        usage.modelId ??
+        targetOverride?.effectiveModelId ??
+        conversation.modelId ??
+        null,
       inputTokens: usage.inputTokens ?? null,
       outputTokens: usage.outputTokens ?? null,
       totalTokens: usage.totalTokens ?? null,

package/src/lib/chat/command-tabs.ts

@@ -0,0 +1,61 @@
+import type { ToolCatalogEntry, ToolGroup } from "./tool-catalog";
+
+export const COMMAND_TAB_IDS = ["actions", "skills", "tools", "entities"] as const;
+export type CommandTabId = (typeof COMMAND_TAB_IDS)[number];
+
+export interface CommandTab {
+  id: CommandTabId;
+  label: string;
+  shortcut: string; // ⌘1..⌘4
+}
+
+export const COMMAND_TABS: CommandTab[] = [
+  { id: "actions", label: "Actions", shortcut: "⌘1" },
+  { id: "skills", label: "Skills", shortcut: "⌘2" },
+  { id: "tools", label: "Tools", shortcut: "⌘3" },
+  { id: "entities", label: "Entities", shortcut: "⌘4" },
+];
+
+export const DEFAULT_COMMAND_TAB: CommandTabId = "actions";
+
+export const GROUP_TO_TAB = {
+  // Stagent actions / session primitives
+  Session: "actions",
+  Tasks: "actions",
+  Projects: "actions",
+  Workflows: "actions",
+  Schedules: "actions",
+  Documents: "actions",
+  Tables: "actions",
+  Notifications: "actions",
+  Profiles: "actions",
+  Usage: "actions",
+  Settings: "actions",
+  Chat: "actions",
+  // Skills
+  Skills: "skills",
+  // Tools (filesystem / system / utility)
+  Browser: "tools",
+  Utility: "tools",
+} satisfies Record<ToolGroup, CommandTabId>;
+
+export function isCommandTabId(value: string): value is CommandTabId {
+  return (COMMAND_TAB_IDS as readonly string[]).includes(value);
+}
+
+export interface PartitionedCatalog {
+  actions: ToolCatalogEntry[];
+  skills: ToolCatalogEntry[];
+  tools: ToolCatalogEntry[];
+  entities: ToolCatalogEntry[];
+}
+
+export function partitionCatalogByTab(
+  catalog: ToolCatalogEntry[]
+): PartitionedCatalog {
+  const out: PartitionedCatalog = { actions: [], skills: [], tools: [], entities: [] };
+  for (const entry of catalog) {
+    out[GROUP_TO_TAB[entry.group]].push(entry);
+  }
+  return out;
+}

package/src/lib/chat/context-builder.ts

@@ -5,6 +5,8 @@ import { getMessages } from "@/lib/data/chat";
 import { getProfile } from "@/lib/agents/profiles/registry";
 import { STAGENT_SYSTEM_PROMPT } from "./system-prompt";
 import type { WorkspaceContext } from "@/lib/environment/workspace-context";
+import { expandFileMention } from "./files/expand-mention";
+import { conversations } from "@/lib/db/schema";
 
 // ── Token budget constants ─────────────────────────────────────────────
 
@@ -50,6 +52,121 @@ function buildTier0(
   return parts.join("\n");
 }
 
+// ── Active skill injection (Ollama-first, runtime-agnostic) ────────────
+
+/**
+ * Token budget for a conversation-bound skill's SKILL.md content.
+ *
+ * Per spec §7.1: 1000-4000 tokens typical, with 300 tokens of index/
+ * metadata on top. We cap at ~4000 tokens (≈16K chars) so a large skill
+ * can't blow out a small-context local model. Single-active-skill is
+ * enforced at the MCP-tool layer.
+ */
+const ACTIVE_SKILL_BUDGET = 4_000;
+
+interface ActiveSkillSection {
+  name: string;
+  text: string;
+}
+
+function renderActiveSkillSections(
+  kept: ActiveSkillSection[],
+  omitted: ActiveSkillSection[]
+): string {
+  if (kept.length === 0) return "";
+
+  const parts: string[] = [];
+  if (omitted.length > 0) {
+    const label = omitted.length === 1 ? "skill" : "skills";
+    parts.push(
+      `## Active Skill Note\nOmitted ${omitted.length} older active ${label} to fit the prompt budget: ${omitted
+        .map((section) => section.name)
+        .join(", ")}.`
+    );
+  }
+  parts.push(...kept.map((section) => section.text));
+  return parts.join("\n\n---\n\n");
+}
+
+/**
+ * Build the "Active Skill" section of the system prompt, if one is bound
+ * to the conversation via `conversations.active_skill_id`. Returns "" for
+ * conversations without an active skill.
+ *
+ * Primary use case: Ollama has no SDK-native skill support, so this is
+ * how SKILL.md reaches a local model. Claude and Codex runtimes can
+ * also bind a skill via this path alongside their native Skill tools.
+ *
+ * See `features/chat-ollama-native-skills.md`.
+ */
+async function buildActiveSkill(conversationId: string): Promise<string> {
+  const row = await db
+    .select({
+      activeSkillId: conversations.activeSkillId,
+      activeSkillIds: conversations.activeSkillIds,
+      runtimeId: conversations.runtimeId,
+    })
+    .from(conversations)
+    .where(eq(conversations.id, conversationId))
+    .get();
+
+  // Merge legacy single-active + new composed array. Dynamic import to
+  // avoid loading the chat tools module on the hot path / risk import
+  // cycles per the runtime-catalog smoke-test budget rule in MEMORY.md.
+  const { mergeActiveSkillIds } = await import("@/lib/chat/active-skills");
+  const merged = mergeActiveSkillIds(row?.activeSkillId, row?.activeSkillIds);
+  if (merged.length === 0) return "";
+
+  // Composition (any entry in the new activeSkillIds column) is an
+  // explicit user opt-in to override the SDK-native default. Without
+  // this carve-out, composed skills would silently no-op on Claude/
+  // Codex where stagentInjectsSkills=false. When only the legacy
+  // activeSkillId is set, fall back to the original capability gate
+  // (Ollama-only injection).
+  const isComposed = (row?.activeSkillIds?.length ?? 0) > 0;
+
+  if (!isComposed && row?.runtimeId) {
+    try {
+      const { getRuntimeFeatures } = await import("@/lib/agents/runtime/catalog");
+      const features = getRuntimeFeatures(
+        row.runtimeId as Parameters<typeof getRuntimeFeatures>[0]
+      );
+      if (!features.stagentInjectsSkills) return "";
+    } catch {
+      // Unknown runtime — fall through and inject (safer default than
+      // silently dropping the skill on an unrecognized runtime id).
+    }
+  }
+
+  // Dynamic import keeps the scanner + fs dependency off the hot path for
+  // conversations that don't have an active skill (the common case).
+  const { getSkill } = await import("@/lib/environment/list-skills");
+  const sections: ActiveSkillSection[] = [];
+  for (const id of merged) {
+    const skill = getSkill(id);
+    if (!skill) continue;
+    sections.push({
+      name: skill.name,
+      text: `## Active Skill: ${skill.name}\n\n${skill.content}`,
+    });
+  }
+  if (sections.length === 0) return "";
+
+  const kept = [...sections];
+  const omitted: ActiveSkillSection[] = [];
+  while (
+    kept.length > 1 &&
+    estimateTokens(renderActiveSkillSections(kept, omitted)) > ACTIVE_SKILL_BUDGET
+  ) {
+    const oldest = kept.shift();
+    if (oldest) omitted.push(oldest);
+  }
+
+  const combined = renderActiveSkillSections(kept, omitted);
+  if (estimateTokens(combined) <= ACTIVE_SKILL_BUDGET) return combined;
+  return truncateToTokenBudget(combined, ACTIVE_SKILL_BUDGET);
+}
+
 // ── Tier 1: Conversation history ───────────────────────────────────────
 
 interface HistoryMessage {
@@ -108,7 +225,7 @@ async function buildTier2(projectId?: string | null): Promise<string> {
   if (recentTasks.length > 0) {
     parts.push("\n### Recent Tasks");
     for (const t of recentTasks) {
-      parts.push(`- [${t.status}] ${t.title} (id: ${t.id.slice(0, 8)})`);
+      parts.push(`- [${t.status}] ${t.title} (id: ${t.id})`);
     }
   }
 
@@ -123,7 +240,7 @@ async function buildTier2(projectId?: string | null): Promise<string> {
   if (activeWorkflows.length > 0) {
     parts.push("\n### Workflows");
     for (const w of activeWorkflows) {
-      parts.push(`- [${w.status}] ${w.name} (id: ${w.id.slice(0, 8)})`);
+      parts.push(`- [${w.status}] ${w.name} (id: ${w.id})`);
     }
   }
 
@@ -137,7 +254,7 @@ async function buildTier2(projectId?: string | null): Promise<string> {
   if (docs.length > 0) {
     parts.push(`\n### Documents (${docs.length})`);
     for (const d of docs) {
-      parts.push(`- ${d.filename} (id: ${d.id.slice(0, 8)})`);
+      parts.push(`- ${d.filename} (id: ${d.id})`);
     }
   }
 
@@ -278,6 +395,23 @@ async function buildTier3(mentions: MentionReference[]): Promise<string> {
         }
         break;
       }
+      case "file": {
+        // `entityId` is a relative path scoped to the active project's
+        // workingDirectory (preferred) or the stagent launch cwd (fallback).
+        // Security is enforced inside expandFileMention — the caller cannot
+        // influence cwd.
+        const { getLaunchCwd } = await import("@/lib/environment/workspace-context");
+        let cwd = getLaunchCwd();
+        // If the mention has a known project context in scope, prefer the
+        // project's workingDirectory. We don't have it at this scope today,
+        // so launch cwd is the safe default — matches the API route.
+        // (Future: plumb projectId into buildTier3 so file expansion honors
+        // per-project cwds exactly the same way as the search API.)
+        void cwd;
+        cwd = getLaunchCwd();
+        parts.push(...expandFileMention(mention.entityId, cwd));
+        break;
+      }
     }
   }
 
@@ -285,6 +419,7 @@ async function buildTier3(mentions: MentionReference[]): Promise<string> {
   return truncateToTokenBudget(text, TIER_3_BUDGET);
 }
 
+
 // ── Public API ─────────────────────────────────────────────────────────
 
 export interface ChatContext {
@@ -303,15 +438,22 @@ export async function buildChatContext(opts: {
   workspace?: WorkspaceContext | null;
   mentions?: MentionReference[];
 }): Promise<ChatContext> {
-  const [history, tier2, tier3] = await Promise.all([
+  const [history, tier2, tier3, activeSkill] = await Promise.all([
     buildTier1(opts.conversationId),
     buildTier2(opts.projectId),
     buildTier3(opts.mentions ?? []),
+    buildActiveSkill(opts.conversationId),
   ]);
 
   const tier0 = buildTier0(opts.projectName, opts.workspace);
 
   const systemParts = [tier0];
+
+  // Active skill (from conversations.active_skill_id) sits right below
+  // Tier 0 so its instructions carry the most weight. Empty string when
+  // no skill is bound — common case.
+  if (activeSkill) systemParts.push(activeSkill);
+
   if (tier3) systemParts.push(tier3);
   if (tier2) systemParts.push(tier2);