feat(workflow): select configured agent profiles

Author: Waishnav

src/db/migrations.ts

@@ -42,6 +42,11 @@ const migrations: Migration[] = [
     name: "workflow-exact-replay",
     up: migrateWorkflowExactReplay,
   },
+  {
+    version: 8,
+    name: "workflow-agent-profiles",
+    up: migrateWorkflowAgentProfiles,
+  },
 ];
 
 export function migrateDatabase(sqlite: Database.Database): void {
@@ -268,6 +273,8 @@ function migrateWorkflowJournal(sqlite: Database.Database): void {
       provider text not null,
       model text,
       effort text,
+      profile_name text,
+      profile_fingerprint text,
       label text,
       phase text,
       status text not null,
@@ -312,6 +319,11 @@ function migrateWorkflowExactReplay(sqlite: Database.Database): void {
   addColumnIfMissing(sqlite, "workflow_agent_calls", "return_value_json", "text");
 }
 
+function migrateWorkflowAgentProfiles(sqlite: Database.Database): void {
+  addColumnIfMissing(sqlite, "workflow_agent_calls", "profile_name", "text");
+  addColumnIfMissing(sqlite, "workflow_agent_calls", "profile_fingerprint", "text");
+}
+
 function addColumnIfMissing(
   sqlite: Database.Database,
   table: "workspace_sessions" | "local_agent_sessions" | "workflow_agent_calls",

src/db/schema.ts

@@ -162,6 +162,8 @@ export const workflowAgentCalls = sqliteTable(
     provider: text("provider").notNull(),
     model: text("model"),
     effort: text("effort"),
+    profileName: text("profile_name"),
+    profileFingerprint: text("profile_fingerprint"),
     label: text("label"),
     phase: text("phase"),
     status: text("status").notNull(),

src/oauth-store.test.ts

@@ -48,6 +48,7 @@ async function testDatabaseConfiguration(stateDir: string): Promise<void> {
       { version: 5, name: "workflow-journal" },
       { version: 6, name: "workflow-replay-provenance" },
       { version: 7, name: "workflow-exact-replay" },
+      { version: 8, name: "workflow-agent-profiles" },
     ]);
   } finally {
     database.close();

src/workflow-api.ts

@@ -1,7 +1,12 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import type { WorkflowSandboxApi } from "./workflow-sandbox.js";
-import type { LocalAgentProvider } from "./local-agent-profiles.js";
+import {
+  buildLocalAgentProfilePrompt,
+  fingerprintLocalAgentProfile,
+  type LocalAgentProfile,
+  type LocalAgentProvider,
+} from "./local-agent-profiles.js";
 import type { JsonSchema, JsonValue } from "./json-types.js";
 import { jsonValueSchema } from "./json-types.js";
 import {
@@ -109,6 +114,8 @@ export interface WorkflowJournal {
     provider: LocalAgentProvider;
     model?: string;
     effort?: string;
+    profileName?: string;
+    profileFingerprint?: string;
     label?: string;
     phase?: string;
     isolation?: AgentIsolationMode;
@@ -151,6 +158,8 @@ export interface WorkflowApiDeps {
   baseSha?: string;
   /** Already-filtered enabled ∩ live provider ids, preference order. */
   enabledProviders: LocalAgentProvider[];
+  /** Loaded, enabled profiles exposed by open_workspace for this project. */
+  agentProfiles?: LocalAgentProfile[];
   runProvider: WorkflowRunProvider;
   createWorktree?: CreateAgentWorktree;
   replay?: WorkflowReplay;
@@ -177,6 +186,7 @@ export class WorkflowEngineError extends Error {
       | "provider_disabled"
       | "provider_unavailable"
       | "no_provider"
+      | "profile"
       | "nest_depth"
       | "worktree"
       | "schema"
@@ -250,7 +260,15 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
     const agentOpts = normalizeAgentOpts(opts);
     throwIfCancelled(deps);
 
-    const provider = resolveProvider(agentOpts.provider, deps.meta, deps.enabledProviders);
+    const target = resolveAgentTarget(prompt, agentOpts, deps);
+    const {
+      provider,
+      model,
+      effort,
+      profileName,
+      profileFingerprint,
+      providerPrompt,
+    } = target;
     const phase = agentOpts.phase ?? phaseAls.getStore();
     const isolation: AgentIsolationMode =
       agentOpts.isolation === "worktree" ? "worktree" : "shared";
@@ -259,9 +277,11 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
 
     const cacheKeyInput = buildAgentCacheKeyInput({
       prompt,
+      profileName,
+      profileFingerprint,
       provider,
-      model: agentOpts.model,
-      effort: agentOpts.effort,
+      model,
+      effort,
       schema: agentOpts.schema,
       isolation,
     });
@@ -277,8 +297,10 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
           prompt,
           schemaJson: agentOpts.schema ? JSON.stringify(agentOpts.schema) : undefined,
           provider,
-          model: agentOpts.model,
-          effort: agentOpts.effort,
+          model,
+          effort,
+          profileName,
+          profileFingerprint,
           label: agentOpts.label,
           phase,
           isolation,
@@ -349,8 +371,10 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
         prompt,
         schemaJson: agentOpts.schema ? JSON.stringify(agentOpts.schema) : undefined,
         provider,
-        model: agentOpts.model,
-        effort: agentOpts.effort,
+        model,
+        effort,
+        profileName,
+        profileFingerprint,
         label: agentOpts.label,
         phase,
         isolation,
@@ -377,9 +401,9 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
       const cwd = worktreePath ?? deps.workspaceRoot;
       const providerBase = {
         provider,
-        prompt,
-        model: agentOpts.model,
-        effort: agentOpts.effort,
+        prompt: providerPrompt,
+        model,
+        effort,
         workspace: cwd,
         signal: deps.signal,
         label: agentOpts.label,
@@ -395,7 +419,7 @@ export function createWorkflowApi(deps: WorkflowApiDeps): WorkflowApi {
         const { enforceAgentSchema } = await import("./workflow-schema.js");
         const enforced = await enforceAgentSchema({
           schema: agentOpts.schema,
-          prompt,
+          prompt: providerPrompt,
           provider,
           run: (p, options) =>
             deps.runProvider({
@@ -690,6 +714,54 @@ export function resolveProvider(
   return first;
 }
 
+interface ResolvedAgentTarget {
+  provider: LocalAgentProvider;
+  model?: string;
+  effort?: string;
+  profileName?: string;
+  profileFingerprint?: string;
+  providerPrompt: string;
+}
+
+function resolveAgentTarget(
+  prompt: string,
+  opts: AgentOpts,
+  deps: Pick<WorkflowApiDeps, "agentProfiles" | "enabledProviders" | "meta">,
+): ResolvedAgentTarget {
+  if (!opts.profile) {
+    return {
+      provider: resolveProvider(opts.provider, deps.meta, deps.enabledProviders),
+      model: opts.model,
+      effort: opts.effort,
+      providerPrompt: prompt,
+    };
+  }
+
+  const profile = deps.agentProfiles?.find((candidate) => candidate.name === opts.profile);
+  if (!profile) {
+    const available = deps.agentProfiles?.map((candidate) => candidate.name).join(", ");
+    throw new WorkflowEngineError(
+      "profile",
+      `Unknown agent profile: ${opts.profile}${available ? `. Available profiles: ${available}` : ""}`,
+    );
+  }
+  if (!deps.enabledProviders.includes(profile.provider)) {
+    throw new WorkflowEngineError(
+      "provider_unavailable",
+      `Agent profile ${profile.name} requires unavailable provider ${profile.provider}`,
+    );
+  }
+
+  return {
+    provider: profile.provider,
+    model: opts.model ?? profile.model,
+    effort: opts.effort ?? profile.effort,
+    profileName: profile.name,
+    profileFingerprint: fingerprintLocalAgentProfile(profile),
+    providerPrompt: buildLocalAgentProfilePrompt(profile, prompt),
+  };
+}
+
 function normalizeAgentOpts(opts: unknown): AgentOpts {
   if (opts === undefined || opts === null) return {};
   if (typeof opts === "object" && opts !== null && "writeMode" in opts) {
@@ -699,7 +771,13 @@ function normalizeAgentOpts(opts: unknown): AgentOpts {
   if (parsed.success) return parsed.data;
   const issue = parsed.error.issues[0];
   const path = issue?.path.join(".") || "opts";
-  const kind = path === "schema" ? "schema" : path === "isolation" ? "worktree" : "internal";
+  const kind = path === "schema"
+    ? "schema"
+    : path === "isolation"
+      ? "worktree"
+      : path === "profile" || issue?.message.includes("profile and provider")
+        ? "profile"
+        : "internal";
   throw new WorkflowEngineError(
     kind,
     `Invalid agent ${path}: ${issue?.message ?? "validation failed"}`,

src/workflow-cli.ts

@@ -9,6 +9,7 @@ import { runLocalAgentProviderResult } from "./local-agent-adapters.js";
 import { getLocalAgentProviderAvailabilitySnapshot } from "./local-agent-availability.js";
 import {
   isLocalAgentProvider,
+  loadLocalAgentProfiles,
   LOCAL_AGENT_PROVIDERS,
   type LocalAgentProvider,
 } from "./local-agent-profiles.js";
@@ -346,6 +347,7 @@ export async function runWorkflowWorker(
     const source = await readFile(claimed.scriptPath, "utf8");
     const parsed = parseWorkflowScript(source, { filename: claimed.scriptPath });
     const enabledProviders = resolveEnabledProviders(config.agentProviders);
+    const agentProfiles = await loadLocalAgentProfiles(config, claimed.workspaceRoot);
     const concurrency = resolveWorkflowConcurrency(
       parsed.meta.concurrency,
       availableParallelism(),
@@ -378,6 +380,7 @@ export async function runWorkflowWorker(
       workspaceRoot: claimed.workspaceRoot,
       baseSha: claimed.baseSha,
       enabledProviders,
+      agentProfiles,
       createWorktree,
       replay,
       runProvider: async (input) => {

src/workflow-contracts.ts

@@ -60,10 +60,20 @@ export const agentOptsSchema = z
     schema: jsonSchemaSchema.optional(),
     model: z.string().trim().min(1).optional(),
     effort: z.string().trim().min(1).optional(),
+    profile: z.string().trim().min(1).optional(),
     provider: localAgentProviderSchema.optional(),
     isolation: z.literal("worktree").optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((value, context) => {
+    if (value.profile && value.provider) {
+      context.addIssue({
+        code: "custom",
+        path: ["provider"],
+        message: "profile and provider are mutually exclusive",
+      });
+    }
+  });
 
 export type AgentOpts<S extends JsonSchema | undefined = JsonSchema | undefined> = Omit<
   z.infer<typeof agentOptsSchema>,
@@ -115,6 +125,7 @@ export const workflowErrorKindSchema = z.enum([
   "provider_unavailable",
   "no_provider",
   "provider",
+  "profile",
   "schema",
   "cancelled",
   "timeout",

src/workflow-engine.test.ts

@@ -13,6 +13,7 @@ import {
   type CreateAgentWorktree,
 } from "./workflow-api.js";
 import { createStubBudget, WORKFLOW_LIMITS } from "./workflow-types.js";
+import type { LocalAgentProfile } from "./local-agent-profiles.js";
 
 // ---------------------------------------------------------------------------
 // Semaphore
@@ -327,6 +328,96 @@ import { createStubBudget, WORKFLOW_LIMITS } from "./workflow-types.js";
   await rm(dir, { recursive: true, force: true });
 }
 
+// ---------------------------------------------------------------------------
+// configured profile selection, defaults, overrides, and prompt instructions
+// ---------------------------------------------------------------------------
+{
+  const dir = await mkdtemp(join(tmpdir(), "wf-profile-"));
+  const store = new WorkflowStore(dir);
+  const run = store.createRun({
+    name: "profile",
+    source: "inline",
+    scriptPath: "inline",
+    scriptHash: "h",
+    workspaceRoot: dir,
+  });
+  const profile: LocalAgentProfile = {
+    name: "reviewer",
+    description: "Review changes",
+    provider: "claude",
+    model: "sonnet",
+    effort: "medium",
+    filePath: join(dir, "reviewer.md"),
+    body: "Act as an adversarial reviewer.",
+    disabled: false,
+  };
+  const calls: WorkflowProviderRunInput[] = [];
+  const api = createWorkflowApi({
+    runId: run.id,
+    journal: store,
+    meta: { name: "profile", description: "d", defaultProvider: "codex" },
+    args: undefined,
+    concurrency: 1,
+    signal: new AbortController().signal,
+    workspaceRoot: dir,
+    enabledProviders: ["codex", "claude"],
+    agentProfiles: [profile],
+    runProvider: async (input) => {
+      calls.push(input);
+      return { finalResponse: "reviewed" };
+    },
+  });
+
+  assert.equal(
+    await api.agent("Review auth", {
+      profile: "reviewer",
+      model: "opus",
+      effort: "high",
+    }),
+    "reviewed",
+  );
+  assert.equal(calls[0]?.provider, "claude");
+  assert.equal(calls[0]?.model, "opus");
+  assert.equal(calls[0]?.effort, "high");
+  assert.equal(
+    calls[0]?.prompt,
+    "Act as an adversarial reviewer.\n\nTask:\nReview auth",
+  );
+  assert.equal(store.getAgentCall(run.id, 0)?.profileName, "reviewer");
+  assert.equal(store.getAgentCall(run.id, 0)?.profileFingerprint?.length, 64);
+
+  const callAgent = api.agent as (prompt: string, opts?: unknown) => Promise<unknown>;
+  await assert.rejects(
+    () => callAgent("x", { profile: "reviewer", provider: "codex" }),
+    /mutually exclusive/,
+  );
+  await assert.rejects(() => callAgent("x", { profile: "missing" }), /Unknown agent profile/);
+
+  const unavailableApi = createWorkflowApi({
+    runId: run.id,
+    journal: store,
+    meta: { name: "profile", description: "d" },
+    args: undefined,
+    concurrency: 1,
+    signal: new AbortController().signal,
+    workspaceRoot: dir,
+    enabledProviders: ["codex"],
+    agentProfiles: [profile],
+    runProvider: async () => ({ finalResponse: "unreachable" }),
+  });
+  await assert.rejects(
+    () =>
+      (unavailableApi.agent as (prompt: string, opts?: unknown) => Promise<unknown>)(
+        "x",
+        { profile: "reviewer" },
+      ),
+    /requires unavailable provider claude/,
+  );
+
+  store.close();
+  await rm(dir, { recursive: true, force: true });
+}
+
 // ---------------------------------------------------------------------------
 // schema retry: native schema only on first attempt + provider session reuse
 // ---------------------------------------------------------------------------