@yeaft/webchat-agent 1.0.156 → 1.0.158

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.156",
+  "version": "1.0.158",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/llm/openai-responses.js

@@ -41,6 +41,7 @@ import {
 } from './adapter.js';
 import {
   normalizeEffort,
+  getModelEffortOptions,
   getThinkingCapability,
   mapEffortToOpenAIReasoning,
 } from '../models.js';
@@ -57,10 +58,9 @@ function thinkingV1Enabled() {
 }
 
 /**
- * Translate a normalised effort ('minimal'|'low'|'medium'|'high'|'xhigh'|'max') into the value
- * accepted by the OpenAI Responses `reasoning.effort` field. Responses today
- * accepts 'minimal'|'low'|'medium'|'high'|'xhigh'. Unsupported Anthropic-only
- * adaptive efforts must be dropped, not downgraded.
+ * Translate a normalised effort into the OpenAI Responses `reasoning.effort`
+ * field. Model capability filtering happens at the call site because `max` is
+ * supported by GPT-5.6 but not by older OpenAI reasoning models.
  */
 function effortForResponses(effort) {
   return mapEffortToOpenAIReasoning(effort);
@@ -248,7 +248,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
   // ─── Streaming ──────────────────────────────────────────
 
   /**
-   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, effort?: 'minimal'|'low'|'medium'|'high'|'xhigh'|'max', effortSource?: 'user'|'auto', extraBody?: object, signal?: AbortSignal, onRawExchange?: ({rawRequest, rawResponse}) => void }} params
+   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, effort?: 'minimal'|'low'|'medium'|'high'|'xhigh'|'max', effortSource?: 'user'|'auto', effortContext?: object, extraBody?: object, signal?: AbortSignal, onRawExchange?: ({rawRequest, rawResponse}) => void, onRequestStart?: () => void }} params
    *
    * NOTE on `extraBody`: any keys you spread here are merged verbatim into
    * the wire body and — because the verbatim debug feature is intentionally
@@ -257,7 +257,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
    * `api-key` headers are auto-redacted (see `redactRawRequest` in
    * `adapter.js`); request-body fields are caller-controlled.
    */
-  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, effortSource, extraBody, signal, onRawExchange, onRequestStart }) {
+  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, effortSource, effortContext = {}, extraBody, signal, onRawExchange, onRequestStart }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -276,8 +276,9 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
     // Unknown / unsupported models silently drop the field.
     const normEffort = normalizeEffort(effort);
     if ((thinkingV1Enabled() || effortSource === 'user') && normEffort) {
-      const cap = getThinkingCapability(model);
-      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning') {
+      const cap = getThinkingCapability(model, effortContext);
+      const supportedEfforts = getModelEffortOptions(model, effortContext);
+      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning' && supportedEfforts.includes(normEffort)) {
         const wireEffort = effortForResponses(normEffort);
         if (wireEffort) body.reasoning = { effort: wireEffort };
       }
@@ -517,7 +518,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
    * expose them, mirror the stream() instrumentation. Parity with
    * anthropic.js's `call()`.
    */
-  async call({ model, system, messages, maxTokens = 4096, effort, effortSource, extraBody, signal, onRequestStart }) {
+  async call({ model, system, messages, maxTokens = 4096, effort, effortSource, effortContext = {}, extraBody, signal, onRequestStart }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -530,8 +531,9 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
     // Mirror stream()'s thinking injection for non-streaming side queries.
     const normEffort = normalizeEffort(effort);
     if ((thinkingV1Enabled() || effortSource === 'user') && normEffort) {
-      const cap = getThinkingCapability(model);
-      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning') {
+      const cap = getThinkingCapability(model, effortContext);
+      const supportedEfforts = getModelEffortOptions(model, effortContext);
+      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning' && supportedEfforts.includes(normEffort)) {
         const wireEffort = effortForResponses(normEffort);
         if (wireEffort) body.reasoning = { effort: wireEffort };
       }

package/yeaft/models.js

@@ -34,7 +34,7 @@ import { lookupModelLimitSync } from './llm/models-dev.js';
  * @property {'anthropic' | 'anthropic-adaptive' | 'openai-reasoning' | 'none'} [thinkingProtocol] — task-327a:
  *   'anthropic' → thinking:{type:'enabled', budget_tokens:N}
  *   'anthropic-adaptive' → thinking:{type:'adaptive'} + output_config:{effort}
- *   'openai-reasoning' → reasoning:{effort:'minimal'|'low'|'medium'|'high'|'xhigh'}
+ *   'openai-reasoning' → reasoning:{effort:'minimal'|'low'|'medium'|'high'|'xhigh'|'max'}
  *   'none' (default) → parameter silently dropped by router
  * @property {'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null} [defaultEffort] — adapter-level default
  *   when caller doesn't specify effort (null = no default / decision-tree decides).
@@ -405,12 +405,12 @@ export const ANTHROPIC_THINKING_BUDGETS = {
 };
 
 /**
- * Map a Yeaft effort level to the OpenAI reasoning.effort enum. Current
- * OpenAI APIs expose xhigh, but not Anthropic's 'max'. Unsupported values are
- * dropped by returning null; the adapter MUST NOT error.
+ * Map a Yeaft effort level to the OpenAI reasoning.effort enum. Supported
+ * values are model-dependent; capability filtering happens before this wire
+ * translation. Unsupported values are dropped; the adapter MUST NOT error.
  *
  * @param {Effort} effort
- * @returns {'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null}
+ * @returns {'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null}
  */
 export function mapEffortToOpenAIReasoning(effort) {
   if (!effort) return null;
@@ -420,11 +420,13 @@ export function mapEffortToOpenAIReasoning(effort) {
     case 'medium': return 'medium';
     case 'high': return 'high';
     case 'xhigh': return 'xhigh';
+    case 'max': return 'max';
     default: return null;
   }
 }
 
 export const OPENAI_REASONING_EFFORT_OPTIONS = ['minimal', 'low', 'medium', 'high', 'xhigh'];
+export const OPENAI_MAX_REASONING_EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
 export const ANTHROPIC_MANUAL_EFFORT_OPTIONS = ['low', 'medium', 'high'];
 export const ANTHROPIC_ADAPTIVE_EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
 export const ANTHROPIC_ADAPTIVE_MAX_EFFORT_OPTIONS = ['low', 'medium', 'high', 'max'];
@@ -454,6 +456,19 @@ function inferThinkingCapability(model) {
   const id = parseModelRef(model).modelId.toLowerCase();
   if (!id) return null;
 
+  // GPT-5.6 adds the model-specific `max` tier. Keep this ahead of the generic
+  // GPT inference so older OpenAI models do not advertise a value they reject.
+  // Provider suffixes such as gpt-5.6-sol are variants of the same model family.
+  if (/^gpt-5\.6($|[-.])/.test(id)) {
+    return {
+      supportsThinking: true,
+      thinkingProtocol: 'openai-reasoning',
+      defaultEffort: null,
+      maxBudgetTokens: null,
+      effortOptions: OPENAI_MAX_REASONING_EFFORT_OPTIONS,
+    };
+  }
+
   if (/^(gpt-5|o1|o3|o4|chatgpt-|codex-)/.test(id)) {
     return { supportsThinking: true, thinkingProtocol: 'openai-reasoning', defaultEffort: null, maxBudgetTokens: null };
   }

package/yeaft/tools/create-work-item.js

@@ -32,6 +32,10 @@ Use this when work must continue beyond the current turn, needs role handoffs, r
         items: { type: 'string' },
         description: { en: 'Verifiable completion criteria', zh: '可验证的完成条件' },
       },
+      workItemType: {
+        type: 'string',
+        description: { en: 'Optional explicit Work Item type; omit or use auto for LLM inference', zh: '可选的工作项类型；省略或填写 auto 时由 LLM 推断' },
+      },
       workDir: {
         type: 'string',
         description: { en: 'Existing project directory for execution', zh: '执行时使用的已存在项目目录' },
@@ -59,6 +63,7 @@ Use this when work must continue beyond the current turn, needs role handoffs, r
       title,
       goal,
       acceptanceCriteria: cleanCriteria(input.acceptanceCriteria),
+      workItemType: typeof input.workItemType === 'string' ? input.workItemType.trim() : 'auto',
       workDir: typeof input.workDir === 'string' ? input.workDir.trim() : (ctx.cwd || ''),
       // The Agent-local Work Center settings choose the default workflow and
       // freeze its policy snapshot. Tool callers create the contract; they do

package/yeaft/work-center/bridge.js

@@ -22,7 +22,7 @@ const BROWSER_DETAIL_OPS = new Set(['get', 'create', 'update', 'start', 'cancel'
 // client-supplied value and only emits files resolved from owned upload ids.
 const BROWSER_FILE_FIELDS = Object.freeze({
   create: [
-    'title', 'goal', 'acceptanceCriteria', 'workDir', 'reuseMemory', 'origin',
+    'title', 'goal', 'acceptanceCriteria', 'workItemType', 'workDir', 'reuseMemory', 'origin',
     'linkedSessionIds', 'files', 'start',
   ],
   guide: ['id', 'guidance', 'actionId', 'revision', 'files'],

package/yeaft/work-center/controller.js

@@ -195,6 +195,7 @@ export class WorkflowController {
         assignmentPolicy: previous.assignmentPolicy,
         modelPolicy: previous.modelPolicy,
         requiredRole: previous.requiredRole,
+        brief: previous.brief,
       };
       return {
         ...step,
@@ -220,6 +221,7 @@ export class WorkflowController {
             assignmentPolicy: previous.assignmentPolicy,
             modelPolicy: previous.modelPolicy,
             requiredRole: previous.requiredRole,
+            brief: previous.brief,
           }
         : initialActionFor(workItem);
       const context = Array.isArray(previous?.context) ? [...previous.context] : [];

package/yeaft/work-center/projection.js

@@ -1,3 +1,5 @@
+import { normalizeActionBrief } from './workflow.js';
+
 function currentAction(detail) {
   if (!detail?.currentActionId || !Array.isArray(detail.actions)) return null;
   return detail.actions.find(action => action.id === detail.currentActionId) || null;
@@ -43,6 +45,7 @@ function actionExecution(action, runs) {
       ...executionStats(action),
       response: '',
       progressRevision: 0,
+      messages: [],
     };
   }
   const stats = sumExecutionStats(matchingRuns);
@@ -50,10 +53,21 @@ function actionExecution(action, runs) {
     count(right.progressRevision) - count(left.progressRevision)
       || count(right.startedAt) - count(left.startedAt)
   ))[0];
+  const messages = [...matchingRuns]
+    .sort((left, right) => count(left.startedAt) - count(right.startedAt))
+    .map((run, index) => ({
+      id: `${action.id}:${index + 1}`,
+      status: run.status || 'running',
+      text: typeof run.response === 'string' ? run.response.trim().slice(0, 16_000) : '',
+      createdAt: count(run.startedAt),
+      updatedAt: count(run.endedAt || run.startedAt),
+    }))
+    .filter(message => message.text);
   return {
     ...stats,
     response: typeof latest?.response === 'string' ? latest.response : '',
     progressRevision: count(latest?.progressRevision),
+    messages,
   };
 }
 
@@ -87,12 +101,14 @@ function projectAction(action, runs) {
     stageId: action.stageId || action.type,
     assignmentPolicy: projectAssignmentPolicy(action.assignmentPolicy),
     requiredRole: action.requiredRole || '',
+    brief: normalizeActionBrief(action.brief, action.type),
     status: action.status,
     executionStats: executionStats(execution),
     loopCount: execution.loopCount,
     toolCount: execution.toolCount,
     response: execution.response,
     progressRevision: execution.progressRevision,
+    messages: execution.messages,
   };
 }
 
@@ -108,6 +124,7 @@ function projectActionStats(detail) {
       toolCount: projected.toolCount,
       response: projected.response,
       progressRevision: projected.progressRevision,
+      messages: projected.messages,
     };
   });
 }
@@ -145,6 +162,10 @@ export function projectWorkItemDetail(detail) {
     attachments: projectAttachments(detail.attachments),
     createdAt: detail.createdAt,
     updatedAt: detail.updatedAt,
+    actionCount: Array.isArray(detail.actions) ? detail.actions.length : 0,
+    actionSummary: Array.isArray(detail.actions)
+      ? detail.actions.map(action => action.type).filter(Boolean).join(' → ')
+      : '',
     actions: Array.isArray(detail.actions)
       ? detail.actions.map(action => projectAction(action, detail.runs))
       : [],

package/yeaft/work-center/runner.js

@@ -315,7 +315,7 @@ function completionContract(action, workItem) {
     ? ',\n  "contractPatch": { "goal": "optional refined goal", "acceptanceCriteria": ["optional refined criterion"] }'
     : '';
   const planField = action.type === 'triage' && workItem?.workflowSnapshot?.planningMode === 'ai'
-    ? ',\n  "plan": { "workItemType": "specific-lowercase-slug", "actions": [{ "id": "stable-id", "name": "User-facing name", "type": "extensible-lowercase-slug (built-ins include research|design|diagnose|implement|migrate|test|review|document|operate|deliver|write|custom)", "capability": "specific executor capability", "objective": "independently executable and verifiable Action objective", "separateFromActionTypes": ["optional prior Action type"], "changesRequestedActionId": "for review: optional earlier editable Action id; omit to use nearest", "maxAttempts": 2 }] }'
+    ? ',\n  "plan": { "workItemType": "specific-lowercase-slug", "actions": [{ "id": "stable-id", "name": "User-facing name", "type": "extensible-lowercase-slug (built-ins include research|design|diagnose|implement|migrate|test|review|document|operate|deliver|write|custom)", "capability": "specific executor capability", "objective": "what this Action must do", "approach": "how this Action should do it", "expectedOutcome": "verifiable result this Action must produce", "separateFromActionTypes": ["optional prior Action type"], "changesRequestedActionId": "for review: optional earlier editable Action id; omit to use nearest", "maxAttempts": 2 }] }'
     : '';
   const acceptanceChecks = (workItem?.acceptanceCriteria || []).map(criterion => ({
     criterion,

package/yeaft/work-center/service.js

@@ -15,6 +15,7 @@ import { projectWorkItemDetail, projectWorkItemSummary } from './projection.js';
 import { readWorkCenterSettings, writeWorkCenterSettings } from './settings.js';
 import {
   defaultWorkCenterStageInstructions,
+  listWorkItemTypeTemplates,
   resolvePlanningWorkflowSnapshot,
   resolveWorkflowSnapshot,
 } from './workflow.js';
@@ -45,10 +46,14 @@ export class WorkCenterService {
     this.runtimeInfoProvider = typeof options.runtimeInfoProvider === 'function'
       ? options.runtimeInfoProvider
       : async () => ({ vps: [], models: [], primaryModel: null, fastModel: null });
-    this.runtimeInfo = async () => ({
-      ...(await this.runtimeInfoProvider()),
-      defaultStageInstructions: defaultWorkCenterStageInstructions(),
-    });
+    this.runtimeInfo = async () => {
+      const settings = this.settingsReader(this.yeaftDir);
+      return {
+        ...(await this.runtimeInfoProvider()),
+        defaultStageInstructions: defaultWorkCenterStageInstructions(),
+        workItemTypes: listWorkItemTypeTemplates(settings),
+      };
+    };
     this.ownerBootId = options.ownerBootId || randomUUID();
     this.attachmentRoot = options.attachmentRoot || join(yeaftDir, 'work-center', 'attachments');
     this.store = options.store || new WorkItemStore(join(yeaftDir, 'work-center', 'work-center.db'));
@@ -92,7 +97,7 @@ export class WorkCenterService {
         const workflowTemplate = explicitWorkflow || 'ai-planned';
         const workflowSnapshot = explicitWorkflow
           ? resolveWorkflowSnapshot(settings, explicitWorkflow, payload.stageOverrides)
-          : resolvePlanningWorkflowSnapshot(settings);
+          : resolvePlanningWorkflowSnapshot(settings, payload.workItemType);
         const runtime = !Object.hasOwn(payload, 'workDir') && !settings.defaultWorkDir
           ? await this.runtimeInfo()
           : null;

package/yeaft/work-center/store.js

@@ -5,7 +5,7 @@ import { randomUUID } from 'node:crypto';
 import { normalizeEvidence } from './evidence.js';
 import { normalizeActionCheckpoint } from './action-checkpoint.js';
 
-const SCHEMA_VERSION = 7;
+const SCHEMA_VERSION = 8;
 const OPEN_ACTION_STATUSES = "'ready','running','waiting'";
 const MAX_REUSABLE_CONTEXT_ITEMS = 12;
 const MAX_RUN_RESPONSE_CHARS = 65_536;
@@ -75,6 +75,7 @@ function mapAction(row) {
     modelPolicy: parseJson(row.model_policy, null),
     requiredRole: row.required_role || '',
     instruction: row.instruction,
+    brief: parseJson(row.brief, null),
     context: parseJson(row.context, []),
     contractRevision: row.contract_revision,
     status: row.status,
@@ -202,6 +203,7 @@ export class WorkItemStore {
         assignment_policy TEXT,
         model_policy TEXT,
         instruction TEXT NOT NULL,
+        brief TEXT,
         context TEXT NOT NULL DEFAULT '[]',
         contract_revision INTEGER NOT NULL DEFAULT 1,
         status TEXT NOT NULL,
@@ -275,6 +277,9 @@ export class WorkItemStore {
     if (!hasColumn(this.db, 'work_items', 'reuse_memory')) {
       this.db.exec('ALTER TABLE work_items ADD COLUMN reuse_memory INTEGER NOT NULL DEFAULT 1');
     }
+    if (!hasColumn(this.db, 'actions', 'brief')) {
+      this.db.exec('ALTER TABLE actions ADD COLUMN brief TEXT');
+    }
     if (!hasColumn(this.db, 'actions', 'context')) {
       this.db.exec("ALTER TABLE actions ADD COLUMN context TEXT NOT NULL DEFAULT '[]'");
     }
@@ -401,6 +406,7 @@ export class WorkItemStore {
       modelPolicy: input.modelPolicy || null,
       requiredRole: input.requiredRole || '',
       instruction: input.instruction || '',
+      brief: input.brief && typeof input.brief === 'object' ? input.brief : null,
       context: Array.isArray(input.context) ? input.context : [],
       contractRevision: Number.isInteger(input.contractRevision) ? input.contractRevision : 1,
       status: input.status || 'ready',
@@ -413,9 +419,9 @@ export class WorkItemStore {
     };
     this.db.prepare(`INSERT INTO actions
       (id, work_item_id, sequence, type, required_role, stage_id, assignment_policy, model_policy,
-       instruction, context, contract_revision, status, attempt, max_attempts, current_run_id,
+       instruction, brief, context, contract_revision, status, attempt, max_attempts, current_run_id,
        lease_epoch, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, ?, ?)`).run(
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, ?, ?)`).run(
       action.id,
       workItemId,
       action.sequence,
@@ -425,6 +431,7 @@ export class WorkItemStore {
       stringify(action.assignmentPolicy),
       stringify(action.modelPolicy),
       action.instruction,
+      stringify(action.brief),
       stringify(action.context),
       action.contractRevision,
       action.status,

package/yeaft/work-center/workflow.js

@@ -34,6 +34,38 @@ const DEFAULT_STAGE_INSTRUCTIONS = Object.freeze({
   custom: 'Complete the Action objective using repository facts and the WorkItem contract. State the approach, handle relevant risks and boundary conditions, produce the requested artifact or change, verify the result, and return concrete evidence plus any residual uncertainty.',
 });
 
+const DEFAULT_ACTION_BRIEFS = Object.freeze({
+  triage: ['Turn the request into a precise, executable Work Item contract and plan.', 'Inspect the relevant facts, resolve scope and risks, then select the smallest reliable Action sequence.', 'A frozen Work Item type, validated contract, and executable Action plan.'],
+  research: ['Resolve the question or uncertainty named by this Action with verifiable evidence.', 'Inspect repository facts and authoritative sources, separating observations from inference.', 'A concise evidence-backed conclusion that the next Action can use.'],
+  design: ['Define the smallest maintainable solution for this Action.', 'Inspect existing architecture, data flow, compatibility constraints, and failure boundaries.', 'Concrete implementation guidance with explicit trade-offs and risks.'],
+  diagnose: ['Establish the root cause of the reported behavior.', 'Reproduce the behavior, trace the responsible path, and distinguish evidence from hypotheses.', 'A proven root cause, minimal correction, and regression-test plan.'],
+  implement: ['Implement the required change with the smallest correct diff.', 'Follow repository conventions, handle relevant boundaries, and add focused tests while making the change.', 'A maintainable implementation with focused verification evidence.'],
+  migrate: ['Move existing data or behavior to the required shape without losing semantics.', 'Fence compatibility and rollback boundaries, then validate legacy and already-current states.', 'A repeatable or safely fenced migration with representative evidence.'],
+  test: ['Verify the current result against the Work Item acceptance criteria.', 'Run focused checks first, then broader risk-appropriate tests including failure and compatibility cases.', 'Reproducible pass/fail evidence for every applicable acceptance criterion.'],
+  review: ['Review the current result independently against the Work Item contract.', 'Prioritize correctness, security, data loss, compatibility, and missing tests over style preferences.', 'An approval or concrete change request supported by evidence.'],
+  document: ['Update the documentation required by this Action.', 'Align terminology and examples with actual behavior and verify links, commands, and language requirements.', 'Accurate, usable documentation that matches the delivered behavior.'],
+  operate: ['Perform the requested operational change safely.', 'Check preconditions, apply safety fences, preserve rollback options, and verify authoritative state.', 'A verified operational postcondition with handoff and rollback evidence.'],
+  deliver: ['Deliver the approved Work Item result using repository release policy.', 'Recheck immutable reviewed state, run final gates, and publish only the requested artifacts.', 'A traceable delivery with commit, artifact, deployment, and residual-risk evidence.'],
+  write: ['Produce the written deliverable requested by this Action.', 'Use available evidence, the intended audience, and the required terminology and structure.', 'A complete written artifact verified against the acceptance criteria.'],
+  custom: ['Complete the domain-specific objective defined for this Action.', 'Use repository facts, handle relevant risks and boundaries, and verify the produced result.', 'The requested artifact or change with concrete evidence and residual uncertainty.'],
+});
+
+function defaultActionBrief(type) {
+  const [objective, approach, expectedOutcome] = DEFAULT_ACTION_BRIEFS[STAGE_TYPES.has(type) ? type : 'custom'];
+  return { objective, approach, expectedOutcome };
+}
+
+export function normalizeActionBrief(value, type) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const defaults = defaultActionBrief(type);
+  return Object.fromEntries(Object.keys(defaults).map(key => [
+    key,
+    typeof source[key] === 'string' && source[key].trim()
+      ? source[key].trim().slice(0, 2_000)
+      : defaults[key],
+  ]));
+}
+
 const DEFAULT_SOFTWARE_CHANGE_STAGES = Object.freeze([
   {
     id: 'triage', name: 'Triage', type: 'triage',
@@ -145,6 +177,7 @@ export function normalizeWorkflowDefinition(value, index = 0) {
       id: stageId,
       name: String(source.name || stageId).trim() || stageId,
       type,
+      ...normalizeActionBrief(source, type),
       instruction: typeof source.instruction === 'string' && source.instruction.trim()
         ? source.instruction.trim()
         : defaultWorkCenterStageInstruction(type),
@@ -179,6 +212,9 @@ export function normalizeWorkflowDefinition(value, index = 0) {
     globalInstructions: normalizeGlobalInstructions(value.globalInstructions),
     modelPolicy: normalizeModelPolicy(value.modelPolicy),
     actionInstructions: normalizeActionInstructions(value.actionInstructions),
+    actionTemplates: Array.isArray(value.actionTemplates)
+      ? value.actionTemplates.map(template => normalizeWorkflowDefinition(template))
+      : [],
     stages,
   };
 }
@@ -243,20 +279,52 @@ export function normalizeWorkCenterSettings(value) {
   };
 }
 
-export function resolvePlanningWorkflowSnapshot(settings) {
+export function listWorkItemTypeTemplates(settings) {
   const normalized = normalizeWorkCenterSettings(settings);
-  const triageInstruction = `${normalized.actionInstructions.triage}\n\nChoose a specific workItemType and the smallest reliable sequence of 1 to 8 Actions for this WorkItem. Action types are extensible lowercase slugs: use a built-in type when its reusable policy fits, or define a precise domain type when it does not. For every Action, provide an objective that is independently executable and verifiable, plus the capability needed to select the right VP. Add research, design, diagnosis, migration, documentation, operations, testing, independent review, or delivery only when the task requires them. Do not copy a generic workflow.`;
+  return normalized.workflows.map(workflow => ({
+    id: workflow.workItemType || workflow.id,
+    name: workflow.name,
+    actionCount: workflow.stages.length,
+  }));
+}
+
+export function resolvePlanningWorkflowSnapshot(settings, requestedWorkItemType = null) {
+  const normalized = normalizeWorkCenterSettings(settings);
+  const requestedType = typeof requestedWorkItemType === 'string'
+    && requestedWorkItemType.trim()
+    && requestedWorkItemType.trim().toLowerCase() !== 'auto'
+    ? cleanId(requestedWorkItemType, '').slice(0, 64)
+    : '';
+  const actionTemplates = normalized.workflows.map(workflow => normalizeWorkflowDefinition({
+    ...workflow,
+    workItemType: workflow.workItemType || workflow.id,
+  }));
+  const matchingTemplate = requestedType
+    ? actionTemplates.find(template => template.workItemType === requestedType)
+    : null;
+  if (matchingTemplate) return matchingTemplate;
+
+  const catalog = actionTemplates
+    .map(template => `${template.workItemType}: ${template.name} (${template.stages.map(stage => stage.type).join(' -> ')})`)
+    .join('\n');
+  const typeInstruction = requestedType
+    ? `The user explicitly selected workItemType "${requestedType}". Keep that exact type.`
+    : 'Infer one specific workItemType from the contract.';
+  const triageInstruction = `${normalized.actionInstructions.triage}\n\n${typeInstruction}\nReusable Action templates:\n${catalog || '(none)'}\nIf the final type matches a reusable template, return its workItemType and omit actions so Work Center can apply that frozen template. Otherwise generate the smallest reliable sequence of 1 to 8 Actions. Action types are extensible lowercase slugs: use a built-in type when its reusable policy fits, or define a precise domain type when it does not. Every generated Action must state objective (what to do), approach (how to do it), expectedOutcome (the verifiable result), and capability. Add only Actions required by this task. Do not copy a generic workflow.`;
   return normalizeWorkflowDefinition({
     id: 'ai-planned',
     name: 'AI planned',
     planningMode: 'ai',
+    workItemType: requestedType || null,
     globalInstructions: normalized.globalInstructions,
     modelPolicy: normalized.modelPolicy,
     actionInstructions: normalized.actionInstructions,
+    actionTemplates,
     stages: [{
       id: 'triage',
       name: 'Triage',
       type: 'triage',
+      ...defaultActionBrief('triage'),
       instruction: triageInstruction,
       assignmentPolicy: {
         mode: 'auto', capability: 'triage', candidateVpIds: [], fixedVpId: null,
@@ -305,8 +373,24 @@ export function applyGeneratedPlan(workItem, rawPlan) {
   }
   const workItemType = cleanId(rawPlan.workItemType, '').slice(0, 64);
   if (!workItemType) throw new Error('AI-planned triage requires a valid workItemType');
+  if (source.workItemType && workItemType !== source.workItemType) {
+    throw new Error(`AI-planned triage must keep the selected workItemType "${source.workItemType}"`);
+  }
+  const reusableTemplate = source.actionTemplates.find(template => template.workItemType === workItemType);
+  if (reusableTemplate) {
+    const templateActions = reusableTemplate.stages.filter(stage => stage.type !== 'triage');
+    if (templateActions.length === 0) {
+      throw new Error(`Reusable Action template "${workItemType}" has no executable Actions`);
+    }
+    return normalizeWorkflowDefinition({
+      ...source,
+      workItemType,
+      actionTemplates: [],
+      stages: [source.stages[0], ...templateActions],
+    });
+  }
   if (!Array.isArray(rawPlan.actions) || rawPlan.actions.length < 1 || rawPlan.actions.length > 8) {
-    throw new Error('AI-planned triage requires between 1 and 8 Actions');
+    throw new Error('AI-planned triage requires between 1 and 8 Actions when no reusable template exists');
   }
   const seen = new Set(['triage']);
   const generated = rawPlan.actions.map((rawAction, index) => {
@@ -318,6 +402,13 @@ export function applyGeneratedPlan(workItem, rawPlan) {
     seen.add(id);
     const objective = typeof input.objective === 'string' ? input.objective.trim().slice(0, 2_000) : '';
     if (!objective) throw new Error(`AI-planned Action "${id}" requires an objective`);
+    const defaults = defaultActionBrief(type);
+    const approach = typeof input.approach === 'string' && input.approach.trim()
+      ? input.approach.trim().slice(0, 2_000)
+      : defaults.approach;
+    const expectedOutcome = typeof input.expectedOutcome === 'string' && input.expectedOutcome.trim()
+      ? input.expectedOutcome.trim().slice(0, 2_000)
+      : defaults.expectedOutcome;
     const actionInstruction = Object.hasOwn(source.actionInstructions, type)
       ? source.actionInstructions[type]
       : source.actionInstructions.custom;
@@ -325,7 +416,10 @@ export function applyGeneratedPlan(workItem, rawPlan) {
       id,
       name: String(input.name || id).trim().slice(0, 120) || id,
       type,
-      instruction: `${actionInstruction}\n\nAction type: ${type}\nAction objective for this WorkItem:\n${objective}`,
+      objective,
+      approach,
+      expectedOutcome,
+      instruction: actionInstruction,
       assignmentPolicy: {
         mode: 'auto',
         capability: cleanId(input.capability, type),
@@ -448,7 +542,10 @@ function renderContext(context = []) {
 export function actionInstruction(stage, workItem, context = []) {
   const criteria = (workItem.acceptanceCriteria || []).map(item => `- ${item}`).join('\n') || '- No explicit criteria';
   const common = `WorkItem: ${workItem.title}\nGoal: ${workItem.goal}\nAcceptance criteria:\n${criteria}${renderContext(context)}`;
-  return `${common}\n\n${stage.instruction || defaultWorkCenterStageInstruction(stage.type)}`;
+  const policy = stage.instruction || defaultWorkCenterStageInstruction(stage.type);
+  const brief = normalizeActionBrief(stage.brief || stage, stage.type);
+  const contract = `Action type: ${stage.type}\nWhat to do:\n${brief.objective}\n\nHow to do it:\n${brief.approach}\n\nExpected result:\n${brief.expectedOutcome}`;
+  return `${common}\n\n${policy}\n\n${contract}`;
 }
 
 export function actionForStage(stage, workItem, context = []) {
@@ -459,6 +556,7 @@ export function actionForStage(stage, workItem, context = []) {
     modelPolicy: stage.modelPolicy,
     // Storage compatibility for databases created before assignment policies.
     requiredRole: stage.assignmentPolicy.mode === 'fixed' ? stage.assignmentPolicy.fixedVpId : '',
+    brief: normalizeActionBrief(stage, stage.type),
     context,
     instruction: actionInstruction(stage, workItem, context),
     maxAttempts: stage.maxAttempts,