stagent 0.9.5 → 0.10.0

package/src/lib/tables/enrichment.ts

@@ -0,0 +1,328 @@
+/**
+ * Table enrichment orchestration.
+ *
+ * V1 shipped a single-step loop primitive. V2 keeps the row fan-out model but
+ * promotes planning, typed contracts, and richer metadata so the same plan can
+ * drive preview, launch, runtime validation, and recent-run UX.
+ */
+
+import { db } from "@/lib/db";
+import { workflows } from "@/lib/db/schema";
+import { desc, eq } from "drizzle-orm";
+import { listRows, getTable } from "@/lib/data/tables";
+import { executeWorkflow } from "@/lib/workflows/engine";
+import type { WorkflowDefinition } from "@/lib/workflows/types";
+import type { ColumnDef, FilterSpec } from "@/lib/tables/types";
+import {
+  assertEnrichmentCompatibleColumn,
+  buildEnrichmentPlan,
+  type EnrichmentPlan,
+  type EnrichmentPromptMode,
+  type EnrichmentRow,
+  validateEnrichmentPlan,
+  wrapPromptWithOutputContract,
+} from "@/lib/tables/enrichment-planner";
+
+export type { EnrichmentPlan, EnrichmentPromptMode, EnrichmentRow };
+export { wrapPromptWithOutputContract };
+
+export interface GenerateEnrichmentInput {
+  rows: EnrichmentRow[];
+  tableId: string;
+  tableName?: string;
+  targetColumn: ColumnDef | string;
+  plan?: EnrichmentPlan;
+  prompt?: string;
+  agentProfile?: string;
+  itemVariable?: string;
+}
+
+/**
+ * Build a row-driven loop workflow definition. Each plan step becomes one
+ * inner step inside the row iteration. Only the final step carries the
+ * writeback postAction.
+ */
+export function generateEnrichmentDefinition(
+  input: GenerateEnrichmentInput
+): WorkflowDefinition {
+  const targetColumn =
+    typeof input.targetColumn === "string"
+      ? {
+          name: input.targetColumn,
+          displayName: input.targetColumn,
+          dataType: "text" as const,
+          position: 0,
+        }
+      : input.targetColumn;
+  const plan =
+    input.plan ??
+    buildEnrichmentPlan({
+      targetColumn,
+      sampleRows: input.rows,
+      eligibleRowCount: input.rows.length,
+      promptMode: "custom",
+      prompt: input.prompt ?? "",
+      agentProfileOverride: input.agentProfile,
+    });
+  const itemVariable =
+    input.itemVariable && input.itemVariable.length > 0
+      ? input.itemVariable
+      : "row";
+
+  const items = input.rows.map((row) => ({
+    id: row.id,
+    ...row.data,
+  }));
+
+  return {
+    pattern: "loop",
+    steps: plan.steps.map((step, index) => ({
+      id: step.id,
+      name: step.name,
+      prompt: step.prompt,
+      agentProfile: step.agentProfile ?? plan.agentProfile,
+      postAction:
+        index === plan.steps.length - 1
+          ? {
+              type: "update_row" as const,
+              tableId: input.tableId,
+              rowId: `{{${itemVariable}.id}}`,
+              column: targetColumn.name,
+            }
+          : undefined,
+    })),
+    loopConfig: {
+      maxIterations: items.length,
+      items,
+      itemVariable,
+    },
+    metadata: {
+      enrichment: {
+        tableId: input.tableId,
+        tableName: input.tableName ?? input.tableId,
+        targetColumn: targetColumn.name,
+        targetColumnLabel: targetColumn.displayName,
+        promptMode: plan.promptMode,
+        strategy: plan.strategy,
+        agentProfile: plan.agentProfile,
+        eligibleRowCount: items.length,
+        targetContract: plan.targetContract,
+      },
+    },
+  };
+}
+
+/**
+ * Idempotent skip: drop rows whose target column already has a non-empty,
+ * non-whitespace value. Missing keys, null, "", and whitespace-only all
+ * count as "not yet populated".
+ */
+export function filterUnpopulatedRows(
+  rows: EnrichmentRow[],
+  targetColumn: string
+): EnrichmentRow[] {
+  return rows.filter((row) => {
+    const value = row.data[targetColumn];
+    if (value === undefined || value === null) return true;
+    if (typeof value !== "string") return false;
+    return value.trim() === "";
+  });
+}
+
+const DEFAULT_BATCH_SIZE = 50;
+const MAX_BATCH_SIZE = 200;
+
+interface EnrichmentPlanningParams {
+  targetColumn: string;
+  filter?: FilterSpec;
+  promptMode?: EnrichmentPromptMode;
+  prompt?: string;
+  agentProfile?: string;
+  agentProfileOverride?: string;
+  batchSize?: number;
+}
+
+export interface PreviewEnrichmentPlanParams extends EnrichmentPlanningParams {}
+
+export interface CreateEnrichmentWorkflowParams extends EnrichmentPlanningParams {
+  projectId?: string | null;
+  itemVariable?: string;
+  workflowName?: string;
+  plan?: EnrichmentPlan;
+}
+
+export interface CreateEnrichmentWorkflowResult {
+  workflowId: string;
+  rowCount: number;
+}
+
+export interface EnrichmentRunSummary {
+  workflowId: string;
+  name: string;
+  status: string;
+  updatedAt: string;
+  targetColumn: string;
+  targetColumnLabel: string;
+  rowCount: number;
+  strategy: EnrichmentPlan["strategy"];
+  promptMode: EnrichmentPromptMode;
+}
+
+export async function previewEnrichmentPlan(
+  tableId: string,
+  params: PreviewEnrichmentPlanParams
+): Promise<EnrichmentPlan> {
+  const prepared = await prepareEnrichment(tableId, params);
+  return buildEnrichmentPlan({
+    targetColumn: prepared.targetColumn,
+    sampleRows: prepared.eligibleRows,
+    eligibleRowCount: prepared.eligibleRows.length,
+    promptMode: resolvePromptMode(params.promptMode, params.prompt),
+    prompt: params.prompt,
+    agentProfileOverride: params.agentProfileOverride ?? params.agentProfile,
+    filter: params.filter,
+  });
+}
+
+export async function createEnrichmentWorkflow(
+  tableId: string,
+  params: CreateEnrichmentWorkflowParams
+): Promise<CreateEnrichmentWorkflowResult> {
+  const prepared = await prepareEnrichment(tableId, params);
+
+  const plan =
+    params.plan ??
+    buildEnrichmentPlan({
+      targetColumn: prepared.targetColumn,
+      sampleRows: prepared.eligibleRows,
+      eligibleRowCount: prepared.eligibleRows.length,
+      promptMode: resolvePromptMode(params.promptMode, params.prompt),
+      prompt: params.prompt,
+      agentProfileOverride: params.agentProfileOverride ?? params.agentProfile,
+      filter: params.filter,
+    });
+
+  validateEnrichmentPlan(plan, prepared.targetColumn);
+
+  const definition = generateEnrichmentDefinition({
+    rows: prepared.eligibleRows,
+    tableId,
+    tableName: prepared.table.name,
+    targetColumn: prepared.targetColumn,
+    plan,
+    itemVariable: params.itemVariable,
+  });
+
+  const workflowId = crypto.randomUUID();
+  const now = new Date();
+  const name =
+    params.workflowName?.trim() ||
+    `Enrich ${prepared.table.name} · ${prepared.targetColumn.displayName}`;
+
+  await db.insert(workflows).values({
+    id: workflowId,
+    name,
+    projectId: params.projectId ?? prepared.table.projectId ?? null,
+    definition: JSON.stringify(definition),
+    status: "draft",
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  executeWorkflow(workflowId).catch((err) => {
+    console.error(`[enrichment] executeWorkflow failed for ${workflowId}:`, err);
+  });
+
+  await db.select().from(workflows).where(eq(workflows.id, workflowId));
+
+  return {
+    workflowId,
+    rowCount: prepared.eligibleRows.length,
+  };
+}
+
+export async function listRecentEnrichmentRuns(
+  tableId: string,
+  limit: number = 5
+): Promise<EnrichmentRunSummary[]> {
+  const rows = await db
+    .select()
+    .from(workflows)
+    .orderBy(desc(workflows.updatedAt));
+
+  const runs = rows
+    .map((workflow): EnrichmentRunSummary | null => {
+      try {
+        const definition = JSON.parse(workflow.definition) as WorkflowDefinition;
+        const meta = definition.metadata?.enrichment;
+        if (!meta || meta.tableId !== tableId) return null;
+        return {
+          workflowId: workflow.id,
+          name: workflow.name,
+          status: workflow.status,
+          updatedAt: workflow.updatedAt.toISOString(),
+          targetColumn: meta.targetColumn,
+          targetColumnLabel: meta.targetColumnLabel,
+          rowCount: meta.eligibleRowCount,
+          strategy: meta.strategy,
+          promptMode: meta.promptMode,
+        } satisfies EnrichmentRunSummary;
+      } catch {
+        return null;
+      }
+    });
+
+  return runs
+    .filter((run): run is EnrichmentRunSummary => run !== null)
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+    .slice(0, limit);
+}
+
+async function prepareEnrichment(
+  tableId: string,
+  params: EnrichmentPlanningParams
+): Promise<{
+  table: NonNullable<Awaited<ReturnType<typeof getTable>>>;
+  targetColumn: ColumnDef;
+  eligibleRows: EnrichmentRow[];
+}> {
+  const table = await getTable(tableId);
+  if (!table) {
+    throw new Error(`Table ${tableId} not found`);
+  }
+
+  const columnSchema = JSON.parse(table.columnSchema) as ColumnDef[];
+  const targetColumn = columnSchema.find((column) => column.name === params.targetColumn);
+  if (!targetColumn) {
+    throw new Error(
+      `Column "${params.targetColumn}" does not exist on table ${tableId}`
+    );
+  }
+  assertEnrichmentCompatibleColumn(targetColumn);
+
+  const batchSize = Math.min(params.batchSize ?? DEFAULT_BATCH_SIZE, MAX_BATCH_SIZE);
+  const rawRows = await listRows(tableId, {
+    filters: params.filter ? [params.filter] : undefined,
+    limit: batchSize,
+  });
+
+  const rows: EnrichmentRow[] = rawRows.map((row) => ({
+    id: row.id,
+    data: JSON.parse(row.data) as Record<string, unknown>,
+  }));
+
+  const eligibleRows = filterUnpopulatedRows(rows, targetColumn.name);
+  return {
+    table,
+    targetColumn,
+    eligibleRows,
+  };
+}
+
+function resolvePromptMode(
+  promptMode: EnrichmentPromptMode | undefined,
+  prompt: string | undefined
+): EnrichmentPromptMode {
+  if (promptMode) return promptMode;
+  return prompt?.trim() ? "custom" : "auto";
+}

package/src/lib/tables/query-builder.ts

@@ -77,9 +77,12 @@ function buildFilterClause(
       return sql`${col} IN (${sql.join(placeholders, sql`, `)})`;
     }
     case "is_empty":
-      return sql`(${col} IS NULL OR ${col} = '')`;
+      // Treat whitespace-only as empty so the filter agrees with the
+      // server-side `filterUnpopulatedRows` / `shouldSkipPostActionValue`
+      // semantics used by bulk row enrichment.
+      return sql`(${col} IS NULL OR TRIM(${col}) = '')`;
     case "is_not_empty":
-      return sql`(${col} IS NOT NULL AND ${col} != '')`;
+      return sql`(${col} IS NOT NULL AND TRIM(${col}) != '')`;
     default:
       throw new Error(`Unknown filter operator: ${filter.operator}`);
   }

package/src/lib/tables/trigger-evaluator.ts

@@ -99,9 +99,10 @@ function matchesCondition(
     case "in":
       return Array.isArray(condition.value) && condition.value.includes(strValue);
     case "is_empty":
-      return value == null || strValue === "";
+      // Whitespace-only counts as empty (matches SQL `is_empty` operator).
+      return value == null || strValue.trim() === "";
     case "is_not_empty":
-      return value != null && strValue !== "";
+      return value != null && strValue.trim() !== "";
     default:
       return true;
   }

package/src/lib/theme.ts

@@ -0,0 +1,71 @@
+// Shared theme utilities. Server reads the `stagent-theme` cookie and renders
+// <html className="dark"> directly, so we no longer need a pre-hydration <script>
+// bootstrap to prevent FOUC. Every client-side toggle must keep the cookie in
+// sync so the next SSR matches.
+//
+// Previously a next/script <Script strategy="beforeInteractive"> injected the
+// theme, but in Next.js 16 + React 19 any <script> element in the component
+// tree fires a "script tag inside React component" dev warning.
+
+export type ResolvedTheme = "light" | "dark";
+
+export const THEME_COOKIE = "stagent-theme";
+export const DEFAULT_THEME: ResolvedTheme = "light";
+
+export function isResolvedTheme(value: unknown): value is ResolvedTheme {
+  return value === "light" || value === "dark";
+}
+
+/**
+ * Client-only: apply a theme everywhere it needs to land — DOM, localStorage,
+ * and cookie. Always use this instead of setting them individually so we can't
+ * drift between storage locations.
+ */
+export function applyTheme(theme: ResolvedTheme): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  root.classList.toggle("dark", theme === "dark");
+  root.dataset.theme = theme;
+  root.style.colorScheme = theme;
+  root.style.backgroundColor =
+    theme === "dark" ? "oklch(0.14 0.02 250)" : "oklch(0.985 0.004 250)";
+  try {
+    localStorage.setItem(THEME_COOKIE, theme);
+  } catch {
+    /* storage may be unavailable (private mode, quota) */
+  }
+  document.cookie = `${THEME_COOKIE}=${theme};path=/;max-age=31536000;SameSite=Lax`;
+}
+
+/**
+ * Client-only: flip the current theme and apply. Returns the new theme.
+ */
+export function toggleTheme(): ResolvedTheme {
+  const current: ResolvedTheme = document.documentElement.classList.contains(
+    "dark"
+  )
+    ? "dark"
+    : "light";
+  const next: ResolvedTheme = current === "dark" ? "light" : "dark";
+  applyTheme(next);
+  return next;
+}
+
+/**
+ * Client-only: resolve the user's preferred theme from localStorage, falling
+ * back to the cookie, then the default. Used by the toggle button to seed its
+ * `dark` state on mount.
+ */
+export function readClientTheme(): ResolvedTheme {
+  if (typeof document === "undefined") return DEFAULT_THEME;
+  try {
+    const stored = localStorage.getItem(THEME_COOKIE);
+    if (isResolvedTheme(stored)) return stored;
+  } catch {
+    /* ignore */
+  }
+  const cookieMatch = document.cookie.match(/(?:^|;\s*)stagent-theme=([^;]+)/);
+  const cookieValue = cookieMatch?.[1];
+  if (isResolvedTheme(cookieValue)) return cookieValue;
+  return DEFAULT_THEME;
+}

package/src/lib/usage/ledger.ts

@@ -19,7 +19,8 @@ export type UsageActivityType =
   | "pattern_extraction"
   | "context_summarization"
   | "chat_turn"
-  | "profile_assist";
+  | "profile_assist"
+  | "manual_force_bypass";
 
 export type UsageLedgerStatus =
   | "completed"
@@ -249,23 +250,6 @@ export async function recordUsageLedgerEntry(input: UsageLedgerWriteInput) {
 
   await db.insert(usageLedger).values(row);
 
-  // Queue telemetry event (opt-in, fire-and-forget)
-  try {
-    const { queueTelemetryEvent } = await import("@/lib/telemetry/queue");
-    queueTelemetryEvent({
-      runtimeId: input.runtimeId,
-      providerId: input.providerId,
-      modelId: input.modelId ?? "unknown",
-      activityType: input.activityType,
-      outcomeStatus: status,
-      tokenCount: normalizedTotalTokens ?? undefined,
-      costMicros: resolvedCostMicros ?? undefined,
-      durationMs: input.finishedAt.getTime() - input.startedAt.getTime(),
-    });
-  } catch {
-    // Telemetry is non-critical
-  }
-
   return row;
 }
 

package/src/lib/util/__tests__/similarity.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "vitest";
+import { extractKeywords, jaccard, tagOverlap, STOP_WORDS } from "../similarity";
+
+describe("similarity.extractKeywords", () => {
+  it("returns an empty set for empty input", () => {
+    expect(extractKeywords("")).toEqual(new Set());
+  });
+
+  it("lowercases and strips punctuation", () => {
+    const result = extractKeywords("Research Customer Feedback!");
+    expect(result.has("research")).toBe(true);
+    expect(result.has("customer")).toBe(true);
+    expect(result.has("feedback")).toBe(true);
+  });
+
+  it("excludes stop words", () => {
+    const result = extractKeywords("the research about customer and the feedback");
+    expect(result.has("the")).toBe(false);
+    expect(result.has("about")).toBe(false);
+    expect(result.has("research")).toBe(true);
+  });
+
+  it("filters tokens shorter than 4 chars", () => {
+    const result = extractKeywords("go do it now with research");
+    expect(result.has("go")).toBe(false);
+    expect(result.has("do")).toBe(false);
+    expect(result.has("it")).toBe(false);
+    expect(result.has("now")).toBe(false);
+    expect(result.has("research")).toBe(true);
+  });
+
+  it("filters tokens longer than 29 chars", () => {
+    const longWord = "a".repeat(30);
+    const result = extractKeywords(`research ${longWord} customer`);
+    expect(result.has(longWord)).toBe(false);
+    expect(result.has("research")).toBe(true);
+  });
+
+  it("respects the limit parameter", () => {
+    const text = "alpha bravo charlie delta echo foxtrot golf hotel india juliet";
+    const result = extractKeywords(text, 3);
+    expect(result.size).toBe(3);
+  });
+
+  it("orders by frequency before applying the limit", () => {
+    // 'research' appears 3 times, 'customer' 2 times, 'feedback' 1 time.
+    const text = "research customer feedback research customer research";
+    const result = extractKeywords(text, 2);
+    expect(result.has("research")).toBe(true);
+    expect(result.has("customer")).toBe(true);
+    expect(result.has("feedback")).toBe(false);
+  });
+
+  it("preserves hyphenated tokens", () => {
+    const result = extractKeywords("multi-agent workflow");
+    expect(result.has("multi-agent")).toBe(true);
+  });
+});
+
+describe("similarity.jaccard", () => {
+  it("returns 0 for two empty sets", () => {
+    expect(jaccard(new Set(), new Set())).toBe(0);
+  });
+
+  it("returns 0 for disjoint sets", () => {
+    expect(jaccard(new Set(["a", "b"]), new Set(["c", "d"]))).toBe(0);
+  });
+
+  it("returns 1 for identical sets", () => {
+    expect(jaccard(new Set(["a", "b"]), new Set(["a", "b"]))).toBe(1);
+  });
+
+  it("computes intersection / union correctly", () => {
+    // {a,b,c} vs {b,c,d} → intersection=2, union=4 → 0.5
+    expect(jaccard(new Set(["a", "b", "c"]), new Set(["b", "c", "d"]))).toBe(0.5);
+  });
+
+  it("returns 0 when one set is empty and other is not", () => {
+    expect(jaccard(new Set(), new Set(["a"]))).toBe(0);
+  });
+});
+
+describe("similarity.tagOverlap", () => {
+  it("returns 0 when candidate has no tags", () => {
+    expect(tagOverlap([], ["a", "b"])).toBe(0);
+  });
+
+  it("is case-insensitive", () => {
+    expect(tagOverlap(["Research"], ["research"])).toBe(1);
+  });
+
+  it("returns fraction of candidate tags present in existing", () => {
+    expect(tagOverlap(["a", "b", "c"], ["a", "b", "z"])).toBeCloseTo(2 / 3);
+  });
+
+  it("returns 1 when all candidate tags match", () => {
+    expect(tagOverlap(["a", "b"], ["a", "b", "c"])).toBe(1);
+  });
+});
+
+describe("similarity.STOP_WORDS", () => {
+  it("exposes a non-empty stop word set", () => {
+    expect(STOP_WORDS.size).toBeGreaterThan(0);
+    expect(STOP_WORDS.has("the")).toBe(true);
+  });
+});

package/src/lib/util/similarity.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared similarity utilities.
+ *
+ * Small, dependency-free helpers for fuzzy matching: keyword extraction,
+ * Jaccard similarity, and tag overlap. Used by the profile import dedup
+ * engine (`src/lib/import/dedup.ts`) and the chat workflow tool dedup
+ * check (`src/lib/chat/tools/workflow-tools.ts`).
+ *
+ * Extracted into a shared module so both callers use the same keyword
+ * normalization and comparison math — if one grows, the other benefits.
+ */
+
+/** Common stop words to exclude from keyword extraction. */
+export const STOP_WORDS = new Set([
+  "the", "and", "for", "are", "but", "not", "you", "all", "can", "had",
+  "her", "was", "one", "our", "out", "has", "have", "that", "this", "with",
+  "from", "they", "been", "will", "each", "make", "like", "into", "them",
+  "some", "when", "what", "your", "should", "would", "could", "about",
+  "which", "their", "other", "than", "then", "more", "also",
+  "only", "must", "does", "here", "just", "over", "such", "after",
+  "before", "between", "through", "where", "these", "those", "being",
+  "using", "ensure", "every", "following", "include",
+]);
+
+/**
+ * Extract meaningful keywords from text.
+ *
+ * Lowercases, strips non-alphanumeric, filters out stop words and tokens
+ * outside a reasonable length window, then returns the top-N most frequent
+ * terms as a Set.
+ */
+export function extractKeywords(text: string, limit = 20): Set<string> {
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 3 && w.length < 30 && !STOP_WORDS.has(w));
+
+  const freq = new Map<string, number>();
+  for (const word of words) {
+    freq.set(word, (freq.get(word) ?? 0) + 1);
+  }
+
+  const sorted = Array.from(freq.entries())
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([word]) => word);
+
+  return new Set(sorted);
+}
+
+/**
+ * Jaccard similarity between two sets — |A ∩ B| / |A ∪ B|.
+ *
+ * Returns 0 when both sets are empty (a reasonable default for "nothing to
+ * compare" rather than the mathematical indeterminate form).
+ */
+export function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const item of a) {
+    if (b.has(item)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Tag overlap ratio — how many of the candidate's tags match the existing
+ * set, normalized by candidate size. Case-insensitive.
+ */
+export function tagOverlap(candidateTags: string[], existingTags: string[]): number {
+  if (candidateTags.length === 0) return 0;
+  const existingSet = new Set(existingTags.map((t) => t.toLowerCase()));
+  const matches = candidateTags.filter((t) => existingSet.has(t.toLowerCase()));
+  return matches.length / candidateTags.length;
+}

package/src/lib/utils/format-timestamp.ts

@@ -44,3 +44,27 @@ export function formatTime(date: string | Date): string {
     second: "2-digit",
   });
 }
+
+/**
+ * Compact date-time for space-constrained surfaces (kanban cards, bento cells).
+ * Today: "14:23" | This week: "Mon 14:23" | This year: "Apr 12, 14:23" | Older: "Apr 12, 2025"
+ */
+export function formatCompactDateTime(date: string | Date): string {
+  const d = typeof date === "string" ? new Date(date) : date;
+  const now = new Date();
+  const diff = now.getTime() - d.getTime();
+  const time = d.toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit" });
+
+  if (d.toDateString() === now.toDateString()) return time;
+
+  if (diff > 0 && diff < 7 * DAY) {
+    const weekday = d.toLocaleDateString("en-US", { weekday: "short" });
+    return `${weekday} ${time}`;
+  }
+
+  const monthDay = d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+
+  if (d.getFullYear() === now.getFullYear()) return `${monthDay}, ${time}`;
+
+  return `${monthDay}, ${d.getFullYear()}`;
+}

package/src/lib/utils/stagent-paths.ts

@@ -40,3 +40,15 @@ export function getStagentLogsDir(): string {
 export function getStagentDocumentsDir(): string {
   return join(getStagentDataDir(), "documents");
 }
+
+export function getStagentCodexDir(): string {
+  return join(getStagentDataDir(), "codex");
+}
+
+export function getStagentCodexConfigPath(): string {
+  return join(getStagentCodexDir(), "config.toml");
+}
+
+export function getStagentCodexAuthPath(): string {
+  return join(getStagentCodexDir(), "auth.json");
+}