stagent 0.5.0 → 0.6.1

package/src/lib/agents/runtime/openai-direct.ts

@@ -0,0 +1,514 @@
+/**
+ * OpenAI Direct API runtime adapter.
+ *
+ * Calls the OpenAI Responses API directly via `openai` SDK
+ * (no Codex binary needed). Supports streaming, hybrid tool use
+ * (server-side + client-side), and session resume via
+ * `previous_response_id`.
+ */
+
+import { db } from "@/lib/db";
+import { tasks, agentLogs, notifications } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { setExecution, removeExecution, getExecution } from "../execution-manager";
+import { DEFAULT_MAX_TURNS, DEFAULT_MAX_BUDGET_USD } from "@/lib/constants/task-status";
+import {
+  buildTaskQueryContext,
+  createTaskUsageState,
+} from "../claude-agent";
+import { createToolServer } from "@/lib/chat/stagent-tools";
+import type { OpenAIFunctionDef } from "@/lib/chat/tool-registry";
+import { handleToolPermission, clearPermissionCache } from "../tool-permissions";
+import {
+  runAgenticLoop,
+  type LoopMessage,
+  type ModelTurnResult,
+  type TurnUsage,
+  type AgentStreamEvent,
+} from "../agentic-loop";
+import { getRuntimeCatalogEntry } from "./catalog";
+import type {
+  AgentRuntimeAdapter,
+  RuntimeConnectionResult,
+  TaskAssistInput,
+} from "./types";
+import type { TaskAssistResponse } from "./task-assist-types";
+import type { ProfileTestReport } from "../profiles/test-types";
+import { getProfile, listProfiles } from "../profiles/registry";
+import {
+  recordUsageLedgerEntry,
+  resolveUsageActivityType,
+} from "@/lib/usage/ledger";
+
+// ── SDK lazy import ──────────────────────────────────────────────────
+
+type OpenAISDK = typeof import("openai");
+let _sdk: OpenAISDK | null = null;
+
+async function getOpenAISDK(): Promise<OpenAISDK> {
+  if (!_sdk) {
+    _sdk = await import("openai");
+  }
+  return _sdk;
+}
+
+// ── API key resolution ───────────────────────────────────────────────
+
+async function getOpenAIApiKeyValue(): Promise<string> {
+  const { getOpenAIApiKey } = await import("@/lib/settings/openai-auth");
+  const { apiKey } = await getOpenAIApiKey();
+  if (apiKey) return apiKey;
+  throw new Error("No OpenAI API key configured. Set one in Settings > Authentication.");
+}
+
+// ── Model call via Responses API ─────────────────────────────────────
+
+/** Options for OpenAI model call. */
+interface OpenAICallOptions {
+  modelId?: string;
+  previousResponseId?: string | null;
+  /** Server-side tools to enable (e.g., { web_search_preview: true, code_interpreter: true }). */
+  serverTools?: Record<string, boolean>;
+}
+
+async function callOpenAIModel(
+  client: InstanceType<OpenAISDK["default"]>,
+  instructions: string,
+  input: LoopMessage[],
+  tools: OpenAIFunctionDef[],
+  _signal: AbortSignal,
+  emitEvent: (event: AgentStreamEvent) => void,
+  options: OpenAICallOptions = {},
+): Promise<ModelTurnResult & { responseId?: string }> {
+  const modelId = options.modelId ?? "gpt-4.1";
+
+  // Build tool array: Stagent function tools + enabled server-side tools
+  const serverToolConfig = options.serverTools ?? { web_search_preview: true };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const allTools: any[] = [...tools];
+  for (const [toolType, enabled] of Object.entries(serverToolConfig)) {
+    if (enabled) allTools.push({ type: toolType });
+  }
+
+  const response = await client.responses.create({
+    model: modelId,
+    instructions,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: input as any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tools: allTools as any,
+    ...(options.previousResponseId ? { previous_response_id: options.previousResponseId } : {}),
+  });
+
+  emitEvent({ type: "status", phase: "running" });
+
+  let text = "";
+  const toolCalls: ModelTurnResult["toolCalls"] = [];
+  const usage: TurnUsage = { modelId };
+  let responseId: string | undefined;
+
+  // Process response output
+  responseId = response.id;
+
+  if (response.usage) {
+    usage.inputTokens = response.usage.input_tokens;
+    usage.outputTokens = response.usage.output_tokens;
+    usage.totalTokens = response.usage.input_tokens + response.usage.output_tokens;
+  }
+
+  for (const item of response.output) {
+    if (item.type === "message") {
+      for (const part of item.content) {
+        if (part.type === "output_text") {
+          text += part.text;
+          emitEvent({ type: "delta", content: part.text });
+        }
+      }
+    } else if (item.type === "function_call") {
+      // Client-side Stagent tool call — needs HITL
+      let parsedArgs: Record<string, unknown> = {};
+      try {
+        parsedArgs = JSON.parse(item.arguments);
+      } catch {
+        parsedArgs = {};
+      }
+      toolCalls.push({
+        id: item.call_id,
+        name: item.name,
+        arguments: parsedArgs,
+      });
+      emitEvent({ type: "status", phase: "tool_use", message: item.name });
+    }
+    // Server-side tool results (web_search_call etc.) are in output
+    // but already handled by the API — just log them
+  }
+
+  const isComplete = response.status === "completed" && toolCalls.length === 0;
+
+  return {
+    text,
+    toolCalls,
+    isComplete,
+    needsContinuation: false, // Responses API handles continuations internally
+    usage,
+    responseId,
+  };
+}
+
+// ── Session persistence ──────────────────────────────────────────────
+
+async function saveResponseId(taskId: string, profileId: string, responseId: string) {
+  await db.insert(agentLogs).values({
+    id: crypto.randomUUID(),
+    taskId,
+    agentType: profileId,
+    event: "openai_response_id",
+    payload: JSON.stringify({ responseId }),
+    timestamp: new Date(),
+  });
+}
+
+async function loadResponseId(taskId: string): Promise<string | null> {
+  const [log] = await db
+    .select()
+    .from(agentLogs)
+    .where(eq(agentLogs.taskId, taskId))
+    .orderBy(agentLogs.timestamp)
+    .limit(1);
+
+  if (!log?.payload) return null;
+  try {
+    const data = JSON.parse(log.payload);
+    return data.responseId ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Core task execution ──────────────────────────────────────────────
+
+async function executeOpenAIDirectTask(taskId: string, isResume = false): Promise<void> {
+  const [task] = await db.select().from(tasks).where(eq(tasks.id, taskId));
+  if (!task) throw new Error(`Task ${taskId} not found`);
+
+  const agentProfileId = task.agentProfile ?? "general";
+  const usageState = createTaskUsageState(task, isResume);
+  const abortController = new AbortController();
+
+  setExecution(taskId, {
+    abortController,
+    sessionId: null,
+    taskId,
+    startedAt: new Date(),
+  });
+
+  try {
+    await db
+      .update(tasks)
+      .set({ status: "running", updatedAt: new Date() })
+      .where(eq(tasks.id, taskId));
+
+    const ctx = await buildTaskQueryContext(task, agentProfileId);
+    const apiKey = await getOpenAIApiKeyValue();
+    const sdk = await getOpenAISDK();
+    const client = new sdk.default({ apiKey });
+
+    const toolServer = createToolServer(task.projectId);
+    const { tools, executeHandler } = toolServer.forProvider("openai");
+
+    // Resolve model
+    const { getSetting } = await import("@/lib/settings/helpers");
+    const modelId = (await getSetting("openai_direct_model")) ?? "gpt-4.1";
+    const maxTurns = ctx.maxTurns ?? DEFAULT_MAX_TURNS;
+
+    // For resume: load previous response ID
+    let previousResponseId: string | null = null;
+    if (isResume) {
+      previousResponseId = await loadResponseId(taskId);
+    }
+
+    const initialMessages: LoopMessage[] = [
+      { role: "user", content: ctx.userPrompt },
+    ];
+
+    // Log start
+    await db.insert(agentLogs).values({
+      id: crypto.randomUUID(),
+      taskId,
+      agentType: agentProfileId,
+      event: isResume ? "resumed" : "started",
+      payload: JSON.stringify({
+        runtime: "openai-direct",
+        model: modelId,
+        maxTurns,
+      }),
+      timestamp: new Date(),
+    });
+
+    // Track last response ID for resume
+    let lastResponseId: string | null = previousResponseId;
+
+    const result = await runAgenticLoop(initialMessages, {
+      async callModel(messages, signal) {
+        // Resolve capability overrides from profile
+        const profile = getProfile(agentProfileId);
+        const capOverrides = profile?.capabilityOverrides?.["openai-direct"];
+
+        const turnResult = await callOpenAIModel(
+          client,
+          ctx.systemInstructions,
+          messages,
+          tools as OpenAIFunctionDef[],
+          signal,
+          (evt) => {
+            void db.insert(agentLogs).values({
+              id: crypto.randomUUID(),
+              taskId,
+              agentType: agentProfileId,
+              event: "stream",
+              payload: JSON.stringify(evt),
+              timestamp: new Date(),
+            });
+          },
+          {
+            modelId: capOverrides?.modelId ?? modelId,
+            previousResponseId: lastResponseId,
+            serverTools: capOverrides?.serverTools,
+          },
+        );
+
+        // Store response ID for resume
+        if (turnResult.responseId) {
+          lastResponseId = turnResult.responseId;
+          await saveResponseId(taskId, agentProfileId, turnResult.responseId);
+        }
+
+        return turnResult;
+      },
+
+      formatToolResult(toolCallId, _toolName, result) {
+        return {
+          type: "function_call_output",
+          call_id: toolCallId,
+          output: result.content.map((c) => c.text).join("\n"),
+        };
+      },
+
+      formatContinuation() {
+        return { role: "user", content: "Please continue." };
+      },
+
+      async executeTool(name, args) {
+        return executeHandler(name, args);
+      },
+
+      async checkPermission(toolName, args) {
+        return handleToolPermission(taskId, toolName, args, ctx.canUseToolPolicy);
+      },
+
+      emitEvent(_event) {
+        // Events logged in callModel
+      },
+
+      maxTurns,
+      maxBudgetUsd: DEFAULT_MAX_BUDGET_USD,
+      signal: abortController.signal,
+    });
+
+    const finalStatus = result.stopReason === "complete" ? "completed" : "failed";
+    const resultText = result.stopReason === "complete"
+      ? result.finalText
+      : `Task stopped: ${result.stopReason}`;
+
+    await db
+      .update(tasks)
+      .set({ status: finalStatus, result: resultText, updatedAt: new Date() })
+      .where(eq(tasks.id, taskId));
+
+    await db.insert(notifications).values({
+      id: crypto.randomUUID(),
+      taskId,
+      type: finalStatus === "completed" ? "task_completed" : "task_failed",
+      title: `Task ${finalStatus}: ${task.title}`,
+      body: resultText.slice(0, 500),
+      createdAt: new Date(),
+    });
+
+    await db.insert(agentLogs).values({
+      id: crypto.randomUUID(),
+      taskId,
+      agentType: agentProfileId,
+      event: finalStatus,
+      payload: JSON.stringify({
+        result: resultText.slice(0, 1000),
+        turns: result.turnCount,
+        usage: result.totalUsage,
+      }),
+      timestamp: new Date(),
+    });
+
+    await recordUsageLedgerEntry({
+      taskId,
+      workflowId: task.workflowId ?? null,
+      scheduleId: task.scheduleId ?? null,
+      projectId: task.projectId ?? null,
+      activityType: resolveUsageActivityType({
+        workflowId: task.workflowId,
+        scheduleId: task.scheduleId,
+        isResume,
+      }),
+      runtimeId: "openai-direct",
+      providerId: "openai",
+      modelId: result.totalUsage.modelId ?? modelId,
+      inputTokens: result.totalUsage.inputTokens ?? null,
+      outputTokens: result.totalUsage.outputTokens ?? null,
+      totalTokens: result.totalUsage.totalTokens ?? null,
+      status: finalStatus,
+      startedAt: usageState.startedAt,
+      finishedAt: new Date(),
+    });
+  } catch (err) {
+    if (!abortController.signal.aborted) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      await db
+        .update(tasks)
+        .set({ status: "failed", result: errorMsg, updatedAt: new Date() })
+        .where(eq(tasks.id, taskId));
+
+      await db.insert(notifications).values({
+        id: crypto.randomUUID(),
+        taskId,
+        type: "task_failed",
+        title: `Task failed: ${task.title}`,
+        body: errorMsg.slice(0, 500),
+        createdAt: new Date(),
+      });
+    }
+  } finally {
+    clearPermissionCache(taskId);
+    removeExecution(taskId);
+  }
+}
+
+// ── Task Assist ──────────────────────────────────────────────────────
+
+async function runOpenAITaskAssist(input: TaskAssistInput): Promise<TaskAssistResponse> {
+  const apiKey = await getOpenAIApiKeyValue();
+  const sdk = await getOpenAISDK();
+  const client = new sdk.default({ apiKey });
+
+  const profileIds = listProfiles().map((p) => p.id);
+  const profileList = profileIds.length > 0
+    ? `Available agent profiles: ${profileIds.join(", ")}`
+    : "No explicit profiles available.";
+
+  const instructions = `You are an AI task definition assistant. Analyze the given task and return ONLY a JSON object (no markdown) with:
+- "improvedDescription", "breakdown", "recommendedPattern", "complexity", "needsCheckpoint", "reasoning"
+
+${profileList}`;
+
+  const userContent = [
+    input.title ? `Task title: ${input.title}` : "",
+    input.description ? `Description: ${input.description}` : "",
+  ].filter(Boolean).join("\n");
+
+  const response = await client.responses.create({
+    model: "gpt-4.1",
+    instructions,
+    input: userContent || "Analyze this task",
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const text = (response.output as any[])
+    .filter((item) => item.type === "message")
+    .flatMap((item) =>
+      (item.content ?? [])
+        .filter((p: { type: string }) => p.type === "output_text")
+        .map((p: { text?: string }) => p.text ?? ""),
+    )
+    .join("");
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {
+      improvedDescription: text,
+      breakdown: [],
+      recommendedPattern: "single",
+      complexity: "simple",
+      needsCheckpoint: false,
+      reasoning: "Failed to parse structured response",
+    };
+  }
+}
+
+// ── Connection Test ──────────────────────────────────────────────────
+
+async function testOpenAIConnection(): Promise<RuntimeConnectionResult> {
+  try {
+    const apiKey = await getOpenAIApiKeyValue();
+    const sdk = await getOpenAISDK();
+    const client = new sdk.default({ apiKey });
+
+    // Simple validation
+    await client.responses.create({
+      model: "gpt-4.1-mini",
+      input: "ping",
+    });
+
+    return { connected: true, apiKeySource: "db" };
+  } catch (err) {
+    return {
+      connected: false,
+      error: err instanceof Error ? err.message : "Connection failed",
+    };
+  }
+}
+
+// ── Adapter export ───────────────────────────────────────────────────
+
+export const openAIDirectRuntimeAdapter: AgentRuntimeAdapter = {
+  metadata: getRuntimeCatalogEntry("openai-direct" as never), // Registered in catalog.ts
+
+  async executeTask(taskId: string) {
+    return executeOpenAIDirectTask(taskId, false);
+  },
+
+  async resumeTask(taskId: string) {
+    return executeOpenAIDirectTask(taskId, true);
+  },
+
+  async cancelTask(taskId: string) {
+    const execution = getExecution(taskId);
+    if (execution?.abortController) {
+      execution.abortController.abort();
+    }
+    await db
+      .update(tasks)
+      .set({ status: "cancelled", updatedAt: new Date() })
+      .where(eq(tasks.id, taskId));
+    removeExecution(taskId);
+  },
+
+  async runTaskAssist(input: TaskAssistInput) {
+    return runOpenAITaskAssist(input);
+  },
+
+  async runProfileTests(profileId: string): Promise<ProfileTestReport> {
+    const profile = getProfile(profileId);
+    return {
+      profileId,
+      profileName: profile?.name ?? profileId,
+      runtimeId: "openai-direct",
+      results: [],
+      totalPassed: 0,
+      totalFailed: 0,
+      unsupported: true,
+      unsupportedReason: "Profile smoke tests not yet implemented for OpenAI Direct runtime",
+    };
+  },
+
+  async testConnection() {
+    return testOpenAIConnection();
+  },
+};

package/src/lib/agents/runtime/profile-assist-types.ts

@@ -0,0 +1,30 @@
+export interface ProfileAssistRequest {
+  /** Natural language description of desired agent */
+  goal: string;
+  /** Optional domain hint */
+  domain?: "work" | "personal";
+  /** Operation mode */
+  mode: "generate" | "refine-skillmd" | "suggest-tests";
+  /** Existing SKILL.md for refine/suggest-tests modes */
+  existingSkillMd?: string;
+  /** Existing tags for context */
+  existingTags?: string[];
+}
+
+export interface ProfileAssistResponse {
+  name: string;
+  description: string;
+  domain: "work" | "personal";
+  tags: string[];
+  skillMd: string;
+  allowedTools: string[];
+  canUseToolPolicy: {
+    autoApprove: string[];
+    autoDeny: string[];
+  };
+  maxTurns: number;
+  outputFormat: string;
+  supportedRuntimes: string[];
+  tests: Array<{ task: string; expectedKeywords: string[] }>;
+  reasoning: string;
+}

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

@@ -2,6 +2,7 @@ import type { ApiKeySource } from "@/lib/constants/settings";
 import type { ProfileTestReport } from "@/lib/agents/profiles/test-types";
 import type { RuntimeCapabilities, RuntimeCatalogEntry } from "./catalog";
 import type { TaskAssistResponse } from "./task-assist-types";
+import type { ProfileAssistRequest, ProfileAssistResponse } from "./profile-assist-types";
 
 export interface RuntimeConnectionResult {
   connected: boolean;
@@ -20,6 +21,7 @@ export interface AgentRuntimeAdapter {
   resumeTask(taskId: string): Promise<void>;
   cancelTask(taskId: string): Promise<void>;
   runTaskAssist?(input: TaskAssistInput): Promise<TaskAssistResponse>;
+  runProfileAssist?(input: ProfileAssistRequest): Promise<ProfileAssistResponse>;
   runProfileTests?(profileId: string): Promise<ProfileTestReport>;
   testConnection?(): Promise<RuntimeConnectionResult>;
 }