@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/workflow/schedules/types.ts

@@ -1,127 +1,2 @@
-import type { ExecutionJobPriority, ResourceClaimSpec } from '../../execution/jobs/types';
-
-export type ScheduleTriggerType =
-  | 'interval'
-  | 'cron'
-  | 'calendar'
-  | 'condition'
-  | 'repository-event'
-  | 'dependency-checkpoint'
-  | 'manual';
-
-export interface ScheduleCondition {
-  kind: 'repository_clean' | 'job_succeeded' | 'job_terminal';
-  jobId?: string;
-}
-
-export interface ScheduleTrigger {
-  type: ScheduleTriggerType;
-  everyMinutes?: number;
-  cronExpression?: string;
-  timezone?: string;
-  catchUpMinutes?: number;
-  calendarAt?: string;
-  condition?: ScheduleCondition;
-  eventName?: string;
-  dependencyJobIds?: string[];
-}
-
-export interface ScheduleTriggerContext {
-  source?: 'timer' | 'manual' | 'repository-event' | 'dependency-checkpoint' | 'condition';
-  eventName?: string;
-  eventId?: string;
-  data?: Record<string, unknown>;
-}
-
-export interface SchedulePolicy {
-  maxActiveOccurrences: number;
-  maxFailures: number;
-  cooldownMinutes: number;
-  dailyBudgetMinutes: number;
-  shadowMode: boolean;
-  backoffBaseMinutes?: number;
-  backoffMaxMinutes?: number;
-}
-
-export interface ScheduleAction {
-  operation: string;
-  target?: 'repository-tool' | 'mcp-tool' | 'runtime' | 'workspace-agent';
-  arguments?: Record<string, unknown>;
-  priority?: ExecutionJobPriority;
-  resourceClaims?: ResourceClaimSpec[];
-}
-
-export interface RepositorySchedule {
-  schemaVersion: 1;
-  revision: number;
-  scheduleId: string;
-  requestId: string;
-  repoId: string;
-  name: string;
-  enabled: boolean;
-  trigger: ScheduleTrigger;
-  policy: SchedulePolicy;
-  action: ScheduleAction;
-  stopConditions: string[];
-  createdAt: string;
-  updatedAt: string;
-  lastTriggeredAt?: string;
-  lastOccurrenceId?: string;
-  consecutiveFailures: number;
-  consecutiveNoops?: number;
-  nextEligibleAt?: string;
-  pausedReason?: string;
-  /** Last deterministic external observation for browser or issue watchers. */
-  lastObservationAt?: string;
-  lastObservationFingerprint?: string;
-  lastObservationChangedAt?: string;
-  lastObservationStatus?: 'baseline' | 'unchanged' | 'changed' | 'keepalive' | 'auth_required';
-}
-
-export type ScheduleDecisionType =
-  | 'nothing_to_do'
-  | 'would_execute'
-  | 'execute'
-  | 'cooldown'
-  | 'budget_exhausted'
-  | 'active_occurrence'
-  | 'stopped'
-  | 'operation_blocked'
-  | 'maintenance_not_ready'
-  | 'trigger_not_due'
-  | 'condition_not_met'
-  | 'dependency_not_ready'
-  | 'event_not_matched';
-
-export interface ScheduleDecision {
-  schemaVersion: 1;
-  revision: number;
-  decisionId: string;
-  occurrenceId: string;
-  scheduleId: string;
-  repoId: string;
-  requestId: string;
-  decision: ScheduleDecisionType;
-  reason?: string;
-  triggerContext?: ScheduleTriggerContext;
-  evidence?: Record<string, unknown>;
-  createdAt: string;
-}
-
-export interface ScheduleOccurrence {
-  schemaVersion: 1;
-  revision: number;
-  occurrenceId: string;
-  scheduleId: string;
-  repoId: string;
-  windowKey: string;
-  status: 'created' | 'shadowed' | 'queued' | 'running' | 'succeeded' | 'failed' | 'skipped';
-  decision: ScheduleDecisionType;
-  decisionId?: string;
-  triggerContext?: ScheduleTriggerContext;
-  createdAt: string;
-  updatedAt: string;
-  jobId?: string;
-  handoffId?: string;
-  reason?: string;
-}
+/** @deprecated Kernel V2 compatibility shim. Import from packages/kernel/scheduler/api. */
+export * from '../../../../packages/kernel/scheduler/domain/schedule';

package/src/runtime/workflow/schedules/work-continuation.ts

@@ -1,5 +1,12 @@
 import { createHash } from 'crypto';
-import { getWorkContract, isTerminalWorkContractStatus, type WorkContract } from '../../control-plane/facade';
+import { getWorkContract, semanticWorkState, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { getControllerRoundRelay, getRetainedControllerSession, rearmControllerRoundAfterProviderUserAction, type ControllerRoundRelayRecord, type ControllerType } from '../../../../packages/kernel/controller/api/index';
+import { ensureScheduledControllerBinding } from '../../root/scheduled-controller-composition';
+import { resolveHandoffItem } from '../../control-plane/facade/handoff-inbox-store';
+import type { HandoffItem } from '../../control-plane/facade/types';
+import { readWorkHandle, type WorkHandleState } from '../../control-plane/execution/work-handle-store';
+import { touchSchedulerWakeSignal } from '../../control-plane/global-scheduler/wake-signal';
+
 import { assertAutomatedOperationAllowed } from '../../control-plane/governance/external-effects';
 import { evaluateSchedule } from './engine';
 import {
@@ -8,7 +15,7 @@ import {
   listOccurrences,
   listSchedules,
   saveSchedule,
-} from './store';
+} from '../../../../packages/kernel/scheduler/api/index';
 import type {
   RepositorySchedule,
   ScheduleCondition,
@@ -16,15 +23,17 @@ import type {
   ScheduleTrigger,
   ScheduleTriggerContext,
   ScheduleTriggerType,
-} from './types';
+} from '../../../../packages/kernel/scheduler/api/index';
 
-export type ContinuationControllerType = 'chatgpt' | 'codex' | 'claude' | 'grok';
+export type ContinuationControllerType = Exclude<ControllerType, 'human'>;
 export type WorkScheduleMode = 'continuation' | 'browser_watch' | 'browser_keepalive';
 
 export interface WorkContinuationScheduleInput {
   workId?: string;
   scheduleMode?: WorkScheduleMode;
   controllerType?: ContinuationControllerType;
+  /** Exact interactive Browser grants to carry into the scheduled Controller binding. */
+  authorizationGrantRefs?: string[];
   executable?: string;
   launchArgs?: string[];
   launchReservationMs?: number;
@@ -79,7 +88,7 @@ function requiredWork(controllerHome: string, repoId: string, workId: string): W
 
 function activeWork(controllerHome: string, repoId: string, workId: string): WorkContract {
   const work = requiredWork(controllerHome, repoId, workId);
-  if (isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ALREADY_TERMINAL: ${work.workId}:${work.status}`);
+  if (semanticWorkState(work) !== 'open') throw new Error(`WORK_ALREADY_TERMINAL: ${work.workId}:${semanticWorkState(work)}`);
   return work;
 }
 
@@ -105,18 +114,34 @@ function normalizedTrigger(input: WorkContinuationScheduleInput): ScheduleTrigge
   };
 }
 
-function wakeArguments(input: WorkContinuationScheduleInput, controllerType: ContinuationControllerType): Record<string, unknown> {
+function providerSeedArguments(input: WorkContinuationScheduleInput, controllerType: ContinuationControllerType): Record<string, unknown> {
   const workId = input.workId?.trim();
   return {
     ...(workId ? { work_id: workId } : {}),
     controller_type: controllerType,
+    ...(input.authorizationGrantRefs?.length
+      ? { authorization_grant_refs: [...new Set(input.authorizationGrantRefs.map(String).map(value => value.trim()).filter(Boolean))] }
+      : {}),
     ...(input.executable?.trim() ? { executable: input.executable.trim() } : {}),
     ...(input.launchArgs ? { launch_args: input.launchArgs.map(String) } : {}),
     ...(input.launchReservationMs !== undefined ? { launch_reservation_ms: input.launchReservationMs } : {}),
     ...(input.handoffId?.trim() ? { handoff_id: input.handoffId.trim() } : {}),
     ...(input.browserSessionId?.trim() ? { browser_session_id: input.browserSessionId.trim() } : {}),
     ...(input.conversationUrl?.trim() ? { conversation_url: input.conversationUrl.trim() } : {}),
-    ...(input.continuationPrompt?.trim() ? { continuation_prompt: input.continuationPrompt.trim() } : {}),
+  };
+}
+
+function exactContinuationArguments(input: {
+  workId: string;
+  controllerType: ContinuationControllerType;
+  controllerBindingId: string;
+  continuationHint?: string;
+}): Record<string, unknown> {
+  return {
+    work_id: input.workId,
+    controller_type: input.controllerType,
+    controller_binding_id: input.controllerBindingId,
+    ...(input.continuationHint?.trim() ? { continuation_hint: input.continuationHint.trim() } : {}),
   };
 }
 
@@ -125,7 +150,7 @@ function probeArguments(input: WorkContinuationScheduleInput, controllerType: Co
     throw new Error('SCHEDULE_BROWSER_PROBE_TARGET_REQUIRED');
   }
   return {
-    ...wakeArguments(input, controllerType),
+    ...providerSeedArguments(input, controllerType),
     ...(input.probeUrl?.trim() ? { probe_url: input.probeUrl.trim() } : {}),
     ...(input.probeBrowserSessionId?.trim() ? { probe_session_id: input.probeBrowserSessionId.trim() } : {}),
     ...(input.probeSelector?.trim() ? { selector: input.probeSelector.trim() } : {}),
@@ -148,23 +173,56 @@ export function createWorkContinuationSchedule(
   repoId: string,
   input: WorkContinuationScheduleInput,
 ): { schedule: RepositorySchedule; work?: WorkContract } {
-  const controllerType = input.controllerType ?? 'chatgpt';
   const scheduleMode = input.scheduleMode ?? 'continuation';
   const requestedWorkId = input.workId?.trim();
+  const requestedControllerType = input.controllerType;
   if (!requestedWorkId && scheduleMode !== 'browser_keepalive') throw new Error('WORK_ID_REQUIRED');
-  if (!requestedWorkId && scheduleMode === 'browser_keepalive' && controllerType !== 'chatgpt') throw new Error('STANDALONE_BROWSER_KEEPALIVE_CHATGPT_REQUIRED');
   const work = requestedWorkId ? activeWork(controllerHome, repoId, requestedWorkId) : undefined;
+  const retainedSession = (scheduleMode === 'continuation' || scheduleMode === 'browser_watch') && work
+    ? getRetainedControllerSession({ controllerHome, repoId }, work.workId)
+    : undefined;
+  if (scheduleMode === 'continuation' && !retainedSession) {
+    throw new Error(`SCHEDULE_CONTINUATION_CONTROLLER_SESSION_REQUIRED: ${work!.workId}`);
+  }
+  if (scheduleMode === 'browser_watch' && !retainedSession) {
+    throw new Error(`SCHEDULE_BROWSER_WATCH_CONTROLLER_SESSION_REQUIRED: ${work!.workId}`);
+  }
+  if (retainedSession?.controllerType === 'human') throw new Error('SCHEDULE_CONTINUATION_HUMAN_HOST_UNSUPPORTED');
+  const controllerType = (retainedSession?.controllerType ?? requestedControllerType ?? 'chatgpt') as ContinuationControllerType;
+  if (requestedControllerType && retainedSession && requestedControllerType !== retainedSession.controllerType) {
+    throw new Error(`SCHEDULE_CONTINUATION_CONTROLLER_TYPE_MISMATCH: ${work!.workId}:expected=${retainedSession.controllerType}:requested=${requestedControllerType}`);
+  }
+  if (!requestedWorkId && scheduleMode === 'browser_keepalive' && controllerType !== 'chatgpt') throw new Error('STANDALONE_BROWSER_KEEPALIVE_CHATGPT_REQUIRED');
   const trigger = normalizedTrigger(input);
   const operation = scheduleMode === 'continuation' ? 'external_controller_wake' : 'browser_probe';
-  const actionArguments = scheduleMode === 'continuation'
-    ? wakeArguments(input, controllerType)
-    : probeArguments(input, controllerType, scheduleMode === 'browser_keepalive');
-  assertAutomatedOperationAllowed(operation, actionArguments);
   const name = input.scheduleName?.trim()
     || (scheduleMode === 'browser_watch' ? `Watch external state for Work ${work!.workId}`
       : scheduleMode === 'browser_keepalive'
         ? (work ? `Keep browser session alive for Work ${work.workId}` : 'Keep browser session alive')
         : `Continue Work ${work!.workId}`);
+  const controllerBinding = (scheduleMode === 'continuation' || scheduleMode === 'browser_watch')
+    ? ensureScheduledControllerBinding(
+        { controllerHome, repoId },
+        {
+          workId: work!.workId,
+          session: retainedSession!,
+          scheduleName: name,
+          args: providerSeedArguments(input, controllerType),
+        },
+      )
+    : undefined;
+  const actionArguments = scheduleMode === 'continuation'
+    ? exactContinuationArguments({
+        workId: work!.workId,
+        controllerType,
+        controllerBindingId: controllerBinding!.bindingId,
+        continuationHint: input.continuationPrompt,
+      })
+    : {
+        ...probeArguments(input, controllerType, scheduleMode === 'browser_keepalive'),
+        ...(scheduleMode === 'browser_watch' ? { controller_binding_id: controllerBinding!.bindingId } : {}),
+      };
+  assertAutomatedOperationAllowed(operation, actionArguments);
   const policy = {
     maxActiveOccurrences: 1,
     maxFailures: input.maxFailures !== undefined ? Math.max(1, Math.trunc(input.maxFailures)) : 3,
@@ -230,8 +288,8 @@ export function createWorkContinuationSchedule(
     enabled: true,
     trigger,
     policy,
-    // Work-bound schedules only perform a deterministic wake or a bounded read-only
-    // browser probe. Controller/Work write ownership is acquired separately.
+    // Work-bound continuation schedules persist only exact Work/ControllerSession/ControllerBinding identities.
+    // Browser/process launch metadata lives in ControllerHost adapter stores; browser probes remain adapter actions.
     action: { operation, target: 'runtime', arguments: actionArguments, resourceClaims: [] },
     stopConditions,
   });
@@ -302,3 +360,149 @@ export async function triggerWorkContinuationSchedule(
   const schedule = continuationSchedule(getSchedule(controllerHome, repoId, scheduleId));
   return evaluateSchedule(controllerHome, schedule, true, context);
 }
+
+export function repositoryCleanContinuationEventName(targetBranch: string): string {
+  return `repository-clean:${targetBranch.trim() || 'main'}`;
+}
+
+export function handoffResolvedContinuationEventName(handoffId: string): string {
+  return `handoff-resolved:${handoffId.trim()}`;
+}
+
+export async function triggerWorkContinuationRepositoryEvent(
+  controllerHome: string,
+  repoId: string,
+  eventName: string,
+  eventId: string,
+  input: { workId?: string; data?: Record<string, unknown> } = {},
+): Promise<Array<{ scheduleId: string; occurrenceId?: string; status?: string }>> {
+  const schedules = listWorkContinuationSchedules(controllerHome, repoId, { workId: input.workId }).schedules
+    .filter((schedule) => schedule.enabled)
+    .filter((schedule) => schedule.action.operation === 'external_controller_wake')
+    .filter((schedule) => schedule.trigger.type === 'repository-event' && schedule.trigger.eventName === eventName);
+  const triggered: Array<{ scheduleId: string; occurrenceId?: string; status?: string }> = [];
+  for (const schedule of schedules) {
+    const occurrence = await triggerWorkContinuationSchedule(controllerHome, repoId, schedule.scheduleId, {
+      source: 'repository-event',
+      eventName,
+      eventId: `${eventId}:${schedule.scheduleId}`,
+      data: input.data,
+    });
+    triggered.push({ scheduleId: schedule.scheduleId, occurrenceId: occurrence?.occurrenceId, status: occurrence?.status });
+  }
+  return triggered;
+}
+
+export function eventDrivenContinuationSchedule(
+  controllerHome: string,
+  repoId: string,
+  input: {
+    workId: string;
+    eventName: string;
+    reason: string;
+  },
+): RepositorySchedule {
+  const workSchedules = listWorkContinuationSchedules(controllerHome, repoId, { workId: input.workId }).schedules;
+  const existing = workSchedules
+    .filter((schedule) => schedule.action.operation === 'external_controller_wake')
+    .reverse()
+    .find((schedule) => schedule.enabled)
+    ?? workSchedules.at(-1);
+  return createWorkContinuationSchedule(controllerHome, repoId, {
+    workId: input.workId,
+    continuationPrompt: `Resume exact Work ${input.workId}. Mechanical blocker changed: ${input.reason}`,
+    scheduleName: `Event continuation for ${input.workId}`,
+    triggerType: 'repository-event',
+    eventName: input.eventName,
+    maxFailures: existing?.policy.maxFailures,
+    cooldownMinutes: existing?.policy.cooldownMinutes,
+    dailyBudgetMinutes: existing?.policy.dailyBudgetMinutes,
+    shadowMode: false,
+    backoffBaseMinutes: existing?.policy.backoffBaseMinutes,
+    backoffMaxMinutes: existing?.policy.backoffMaxMinutes,
+    stopConditions: existing?.stopConditions,
+  }).schedule;
+}
+
+
+function dirtyTargetBranchFromWorkHandle(handle: WorkHandleState | undefined): string | undefined {
+  const reason = handle?.finalization.lastError ?? handle?.failureReason ?? '';
+  const match = /WORK_TARGET_DIRTY_OWNERSHIP_REQUIRED: target ([^\s]+) has dirty path/.exec(reason);
+  return match?.[1]?.trim() || undefined;
+}
+
+export function ensureControllerDispositionContinuation(
+  controllerHome: string,
+  repoId: string,
+  relay: Pick<ControllerRoundRelayRecord, 'originWorkId' | 'status' | 'handoffId'>,
+): RepositorySchedule | undefined {
+  if (relay.status === 'waiting') {
+    const targetBranch = dirtyTargetBranchFromWorkHandle(readWorkHandle(controllerHome, repoId, relay.originWorkId));
+    if (!targetBranch) return undefined;
+    return eventDrivenContinuationSchedule(controllerHome, repoId, {
+      workId: relay.originWorkId,
+      eventName: repositoryCleanContinuationEventName(targetBranch),
+      reason: `target ${targetBranch} is clean after WORK_TARGET_DIRTY_OWNERSHIP_REQUIRED`,
+    });
+  }
+  if (relay.status === 'waiting_for_user' && relay.handoffId) {
+    return eventDrivenContinuationSchedule(controllerHome, repoId, {
+      workId: relay.originWorkId,
+      eventName: handoffResolvedContinuationEventName(relay.handoffId),
+      reason: `handoff ${relay.handoffId} was resolved`,
+    });
+  }
+  return undefined;
+}
+
+export async function resolveHandoffAndTriggerContinuation(
+  controllerHome: string,
+  repoId: string,
+  handoffId: string,
+  input: { decision: string; resolver: string },
+): Promise<{ item: HandoffItem; continuationOccurrences: Array<{ scheduleId: string; occurrenceId?: string; status?: string }> }> {
+  const item = resolveHandoffItem({ controllerHome, repoId }, handoffId, input);
+  const continuationOccurrences = await triggerResolvedHandoffContinuation(controllerHome, repoId, item);
+  return { item, continuationOccurrences };
+}
+
+/**
+ * The Inbox application resolves persistence before it calls its continuation
+ * port. Keep the post-resolution transition here so every transport re-arms
+ * the exact ControllerRound before it can wake its Work schedule.
+ */
+export async function triggerResolvedHandoffContinuation(
+  controllerHome: string,
+  repoId: string,
+  item: HandoffItem,
+): Promise<Array<{ scheduleId: string; occurrenceId?: string; status?: string }>> {
+  const relay = item.workId ? getControllerRoundRelay({ controllerHome, repoId }, item.workId) : undefined;
+  const rearmedRelay = item.workId && relay?.status === 'waiting_for_user' && relay.blockedReason === 'provider_user_action_required' && relay.handoffId === item.id
+    ? rearmControllerRoundAfterProviderUserAction({ controllerHome, repoId }, { workId: item.workId, handoffId: item.id })
+    : undefined;
+  if (rearmedRelay) {
+    // The ControllerRound itself is the continuation authority. A repository-event
+    // Schedule is optional policy, not the wake mechanism for an already rearmed
+    // provider dispatch. Wake the canonical Scheduler immediately so a resolved
+    // provider blocker resumes the same occurrence even when no Schedule exists.
+    touchSchedulerWakeSignal(controllerHome, `provider-user-action-resolved:${item.workId}`);
+  }
+  const continuationOccurrences = item.workId
+    ? await triggerWorkContinuationRepositoryEvent(
+        controllerHome,
+        repoId,
+        handoffResolvedContinuationEventName(item.id),
+        `handoff:${item.id}:${item.updatedAt}`,
+        {
+          workId: item.workId,
+          data: {
+            handoffId: item.id,
+            status: item.status,
+            decision: item.decision,
+            ...(rearmedRelay?.occurrenceId ? { controllerRoundOccurrenceId: rearmedRelay.occurrenceId } : {}),
+          },
+        },
+      )
+    : [];
+  return continuationOccurrences;
+}

package/src/runtime/workflows/first-party/xiaohongshu.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { materializeWorkflowAsset, type WorkflowAssetDefinition, type WorkflowAssetDraft, type WorkflowJsonValue } from '../../../../packages/workflow-runtime/api/index';
+import { writeWorkflowAssetContent } from '../../control-plane/persistence/workflow-content-store';
+import { readWorkflowRegistryEntry, recordWorkflowBindings, registerWorkflowAsset, type WorkflowCapabilityBinding } from '../../control-plane/persistence/workflow-registry-store';
+
+export const XIAOHONGSHU_WORKFLOW_IDS = {
+  imageNote: 'xiaohongshu.publish-image-note',
+  longText: 'xiaohongshu.publish-long-text',
+  metrics: 'xiaohongshu.collect-metrics',
+} as const;
+
+export type XiaohongshuPublishMode = 'image_note' | 'generated_image_note' | 'long_text';
+
+const ASSET_FILES: Record<string, string> = {
+  [XIAOHONGSHU_WORKFLOW_IDS.imageNote]: 'xiaohongshu.publish-image-note.v1.draft.json',
+  [XIAOHONGSHU_WORKFLOW_IDS.longText]: 'xiaohongshu.publish-long-text.v1.draft.json',
+  [XIAOHONGSHU_WORKFLOW_IDS.metrics]: 'xiaohongshu.collect-metrics.v1.draft.json',
+};
+
+function assetPath(workflowId: string): string {
+  const filename = ASSET_FILES[workflowId];
+  if (!filename) throw new Error(`XHS_WORKFLOW_UNKNOWN: ${workflowId}`);
+  return resolve(import.meta.dir, '../../../../assets/workflows/xiaohongshu', filename);
+}
+
+export function readAuthoredXiaohongshuWorkflowDraft(workflowId: string): WorkflowAssetDraft {
+  const parsed = JSON.parse(readFileSync(assetPath(workflowId), 'utf8')) as WorkflowAssetDraft;
+  return parsed;
+}
+
+export function materializedXiaohongshuWorkflow(workflowId: string): WorkflowAssetDefinition {
+  return materializeWorkflowAsset(readAuthoredXiaohongshuWorkflowDraft(workflowId));
+}
+
+function browserBindings(asset: WorkflowAssetDefinition): WorkflowCapabilityBinding[] {
+  return (asset.requiredCapabilities ?? []).map((capabilityId) => {
+    if (!capabilityId.startsWith('browser.')) throw new Error(`XHS_WORKFLOW_CAPABILITY_UNSUPPORTED: ${capabilityId}`);
+    const actionId = capabilityId.slice('browser.'.length);
+    if (!actionId) throw new Error(`XHS_WORKFLOW_CAPABILITY_INVALID: ${capabilityId}`);
+    return { capabilityId, pluginId: 'browser', actionId };
+  });
+}
+
+/**
+ * Materialize authored first-party content into Controller Home and bind only
+ * generic Browser capabilities. This is idempotent and never owns Browser auth.
+ */
+export function ensureXiaohongshuWorkflowInstalled(controllerHome: string, workflowId: string) {
+  const draft = readAuthoredXiaohongshuWorkflowDraft(workflowId);
+  const written = writeWorkflowAssetContent({ kind: 'controller', controllerHome }, draft);
+  const scope = { kind: 'controller' } as const;
+  const existing = readWorkflowRegistryEntry(controllerHome, scope, workflowId);
+  const registered = registerWorkflowAsset({
+    controllerHome,
+    scope,
+    asset: written.asset,
+    contentLocation: { kind: 'controller', path: written.path },
+    status: 'active',
+    expectedRevision: existing?.revision ?? null,
+  });
+  return recordWorkflowBindings({
+    controllerHome,
+    scope,
+    expectedIdentity: written.asset,
+    bindings: browserBindings(written.asset),
+    expectedRevision: registered.revision,
+  });
+}
+
+export function ensureAllXiaohongshuWorkflowsInstalled(controllerHome: string): void {
+  for (const workflowId of Object.values(XIAOHONGSHU_WORKFLOW_IDS)) ensureXiaohongshuWorkflowInstalled(controllerHome, workflowId);
+}
+
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`XHS_${label.toUpperCase()}_REQUIRED`);
+  return value.trim();
+}
+
+function imagePaths(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim()) || value.length > 18) {
+    throw new Error('XHS_IMAGE_PATHS_INVALID');
+  }
+  return value.map((entry) => String(entry).trim());
+}
+
+export interface XiaohongshuWorkflowInvocation {
+  workflowId: string;
+  registryScope: { kind: 'controller' };
+  inputs: Record<string, WorkflowJsonValue>;
+  generationRequired: boolean;
+  normalizedMode: 'image_note' | 'long_text';
+}
+
+/** Compatibility translation only. It never dispatches Browser effects. */
+export function translateXiaohongshuPublishToWorkflow(args: Record<string, unknown>): XiaohongshuWorkflowInvocation {
+  const mode = args.mode;
+  if (mode !== 'image_note' && mode !== 'generated_image_note' && mode !== 'long_text') throw new Error('XHS_MODE_INVALID');
+  const normalizedMode = mode === 'long_text' ? 'long_text' : 'image_note';
+  const paths = imagePaths(args.image_paths);
+  if (mode === 'image_note' && paths.length < 1) throw new Error('XHS_IMAGE_PATHS_REQUIRED');
+  const profileUrl = text(args.profile_url, 'profile_url');
+  const account = typeof args.account === 'string' && args.account.trim() ? args.account.trim() : profileUrl;
+  const generationRequired = mode === 'generated_image_note' && paths.length === 0;
+  return {
+    workflowId: normalizedMode === 'long_text' ? XIAOHONGSHU_WORKFLOW_IDS.longText : XIAOHONGSHU_WORKFLOW_IDS.imageNote,
+    registryScope: { kind: 'controller' },
+    generationRequired,
+    normalizedMode,
+    inputs: {
+      account,
+      session_id: text(args.session_id, 'session_id'),
+      profile_url: profileUrl,
+      title: text(args.title, 'title'),
+      body: text(args.body, 'body'),
+      image_paths: paths,
+      ...(typeof args.summary === 'string' && args.summary.trim() ? { summary: args.summary.trim() } : {}),
+      ...(typeof args.template_text === 'string' && args.template_text.trim() ? { template_text: args.template_text.trim() } : {}),
+    },
+  };
+}