@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/assistant/routine-runtime.ts

@@ -0,0 +1,477 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import type { ExecutionJobOrigin } from '../execution/jobs/types';
+import { executeAssistantPluginAction } from '../plugins/store';
+import { isAssistantPluginError } from '../plugins/errors';
+import {
+  createAssistantActionProposals,
+  listAssistantActionProposals,
+  type AssistantActionProposal,
+  type AssistantActionProposalInput,
+} from './action-proposals';
+import { addAssistantInboxItem, getAssistantRoutine, touchAssistantRoutineRun } from './store';
+import { analyzeAssistantMessages, type AssistantModelAnalysis } from './model-provider';
+import { applyAssistantStandingGrants, type StandingGrantExecutionResult } from './standing-grants';
+
+export type AssistantRoutineRunStatus = 'collecting' | 'completed' | 'failed' | 'auth_required';
+
+export interface AssistantRoutineRun {
+  schemaVersion: 1;
+  runId: string;
+  routineId: string;
+  requestId: string;
+  occurrenceId?: string;
+  status: AssistantRoutineRunStatus;
+  windowStart: string;
+  windowEnd: string;
+  collectedItems: number;
+  processedItems: number;
+  proposedActions: number;
+  autoSubmittedActions?: number;
+  analysis?: {
+    usedModel: boolean;
+    provider: AssistantModelAnalysis['provider'];
+    model?: string;
+    promptVersion: string;
+    fallbackReason?: string;
+    warnings: string[];
+  };
+  summary?: string;
+  error?: string;
+  createdAt: string;
+  completedAt?: string;
+}
+
+interface GmailRoutineCursor {
+  schemaVersion: 1;
+  routineId: string;
+  lastSuccessfulAt?: string;
+  historyId?: string;
+  continuation?: { mode: 'history' | 'query'; pageToken: string };
+  processedMessageIds: string[];
+  updatedAt: string;
+}
+
+export interface GmailMessageSummary {
+  id: string;
+  threadId?: string;
+  from: string;
+  subject: string;
+  date?: string;
+  snippet: string;
+  bodyPreview?: string;
+  labelIds: string[];
+}
+
+function now(): string { return new Date().toISOString(); }
+function assistantRoot(repoRoot: string): string { return join(repoRoot, '.forge', 'assistant'); }
+function runsPath(repoRoot: string): string { return join(assistantRoot(repoRoot), 'routine-runs.json'); }
+function cursorsPath(repoRoot: string): string { return join(assistantRoot(repoRoot), 'gmail-cursors.json'); }
+
+function readJson<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try { return JSON.parse(readFileSync(path, 'utf-8')) as T; } catch { return fallback; }
+}
+
+function writeJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+  renameSync(tmp, path);
+}
+
+function saveRun(repoRoot: string, run: AssistantRoutineRun): AssistantRoutineRun {
+  const current = readJson<{ schemaVersion: 1; updatedAt: string; runs: AssistantRoutineRun[] }>(runsPath(repoRoot), {
+    schemaVersion: 1,
+    updatedAt: now(),
+    runs: [],
+  });
+  current.runs = [run, ...current.runs.filter((entry) => entry.runId !== run.runId)].slice(0, 500);
+  current.updatedAt = now();
+  writeJson(runsPath(repoRoot), current);
+  return run;
+}
+
+function readCursor(repoRoot: string, routineId: string): GmailRoutineCursor {
+  const current = readJson<{ schemaVersion: 1; updatedAt: string; cursors: GmailRoutineCursor[] }>(cursorsPath(repoRoot), {
+    schemaVersion: 1,
+    updatedAt: now(),
+    cursors: [],
+  });
+  return current.cursors.find((entry) => entry.routineId === routineId) ?? {
+    schemaVersion: 1,
+    routineId,
+    processedMessageIds: [],
+    updatedAt: now(),
+  };
+}
+
+function saveCursor(repoRoot: string, cursor: GmailRoutineCursor): void {
+  const current = readJson<{ schemaVersion: 1; updatedAt: string; cursors: GmailRoutineCursor[] }>(cursorsPath(repoRoot), {
+    schemaVersion: 1,
+    updatedAt: now(),
+    cursors: [],
+  });
+  current.cursors = [{ ...cursor, updatedAt: now() }, ...current.cursors.filter((entry) => entry.routineId !== cursor.routineId)].slice(0, 200);
+  current.updatedAt = now();
+  writeJson(cursorsPath(repoRoot), current);
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+
+function decodeBase64Url(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  try {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    return Buffer.from(normalized, 'base64').toString('utf-8');
+  } catch {
+    return undefined;
+  }
+}
+
+function bodyText(payload: Record<string, unknown>, depth = 0): string | undefined {
+  if (depth > 8) return undefined;
+  const body = recordValue(payload.body);
+  const direct = decodeBase64Url(stringValue(body.data));
+  if (direct) return direct;
+  const parts = Array.isArray(payload.parts) ? payload.parts : [];
+  const preferred = parts
+    .map((entry) => recordValue(entry))
+    .sort((left, right) => String(left.mimeType) === 'text/plain' ? -1 : String(right.mimeType) === 'text/plain' ? 1 : 0);
+  for (const part of preferred) {
+    const decoded = bodyText(part, depth + 1);
+    if (decoded) return decoded;
+  }
+  return undefined;
+}
+
+function summarizeMessage(raw: Record<string, unknown>): GmailMessageSummary {
+  const payload = recordValue(raw.payload);
+  const headers = Array.isArray(payload.headers) ? payload.headers.map(recordValue) : [];
+  const header = (name: string): string | undefined => stringValue(headers.find((entry) => String(entry.name).toLowerCase() === name.toLowerCase())?.value);
+  const decoded = bodyText(payload)?.replace(/\s+/g, ' ').trim();
+  return {
+    id: String(raw.id ?? ''),
+    threadId: stringValue(raw.threadId),
+    from: header('From') ?? 'unknown sender',
+    subject: header('Subject') ?? '(no subject)',
+    date: header('Date'),
+    snippet: String(raw.snippet ?? '').replace(/\s+/g, ' ').trim(),
+    bodyPreview: decoded?.slice(0, 1_500),
+    labelIds: stringArray(raw.labelIds),
+  };
+}
+
+function senderAddress(value: string): string | undefined {
+  return value.match(/<([^>]+@[^>]+)>/)?.[1] ?? value.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i)?.[0];
+}
+
+function protectedMessageSummary(message: GmailMessageSummary): boolean {
+  return /(security|authentication|password|login|billing|invoice|incident|production|quota|permission|dependabot|gift[ -]?card|安全|登录|账单|故障|告警|权限|礼品卡|禮品卡)/i
+    .test(`${message.subject} ${message.snippet}`);
+}
+
+function promotionalMessageSummary(message: GmailMessageSummary): boolean {
+  if (message.labelIds.includes('CATEGORY_PROMOTIONS')) return true;
+  return /(newsletter|digest|marketing|unsubscribe|推广|营销|周报)/i
+    .test(`${message.subject} ${message.snippet} ${message.bodyPreview ?? ''}`);
+}
+
+export function buildDeterministicAssistantProposals(messages: GmailMessageSummary[]): AssistantActionProposalInput[] {
+  const proposals: AssistantActionProposalInput[] = [];
+  for (const message of messages) {
+    const text = `${message.subject} ${message.snippet} ${message.bodyPreview ?? ''}`.toLowerCase();
+    const protectedMessage = protectedMessageSummary(message);
+    const promotionsCategory = message.labelIds.includes('CATEGORY_PROMOTIONS');
+    if (/(please reply|reply requested|请回复|需要回复|your response)/i.test(text)) {
+      const to = senderAddress(message.from);
+      proposals.push({
+        pluginId: 'gmail', actionId: 'create_draft', evidenceMessageIds: [message.id],
+        reason: `Prepare a reviewable reply draft for “${message.subject}”.`, confidence: 0.75,
+        executable: false,
+        context: { sender: to ?? message.from, subject: message.subject, protected: protectedMessage },
+        arguments: to ? { to: [to], subject: message.subject.startsWith('Re:') ? message.subject : `Re: ${message.subject}`, body_text: '[Draft response pending review]' } : {},
+      });
+    }
+    if (/(action required|todo|deadline|due date|需要处理|截止|待办)/i.test(text)) {
+      proposals.push({
+        pluginId: 'google_tasks', actionId: 'create_task', evidenceMessageIds: [message.id],
+        reason: `Create a task from “${message.subject}”.`, confidence: 0.8,
+        context: { sender: message.from, subject: message.subject, protected: protectedMessage },
+        arguments: { title: message.subject, notes: `${message.from}\n${message.snippet}`.slice(0, 2_000) },
+      });
+    }
+    if (promotionalMessageSummary(message) && !protectedMessage) {
+      proposals.push({
+        pluginId: 'gmail', actionId: 'archive_message', evidenceMessageIds: [message.id],
+        reason: promotionsCategory
+          ? `Archive Gmail Promotions candidate: “${message.subject}”.`
+          : `Archive marketing/newsletter candidate: “${message.subject}”.`,
+        confidence: promotionsCategory ? 0.98 : 0.7,
+        context: { sender: message.from, subject: message.subject, protected: false },
+        arguments: { message_id: message.id },
+      });
+    }
+  }
+  return proposals.slice(0, 50);
+}
+
+export function renderAssistantRoutineReport(
+  messages: GmailMessageSummary[],
+  proposals: AssistantActionProposal[],
+  windowStart: string,
+  windowEnd: string,
+  analysis: AssistantModelAnalysis,
+  standingGrantResults: StandingGrantExecutionResult[],
+): string {
+  const important = messages.filter((message) => /(security|alert|billing|invoice|jira|github|production|incident|安全|账单|故障|告警)/i.test(`${message.subject} ${message.snippet}`));
+  const promotional = messages.filter(promotionalMessageSummary);
+  const archiveProposals = proposals.filter((proposal) => proposal.pluginId === 'gmail' && proposal.actionId === 'archive_message');
+  const proposalById = new Map(proposals.map((proposal) => [proposal.proposalId, proposal]));
+  const submitted = standingGrantResults.filter((entry) => entry.status === 'submitted');
+  const autoArchiveSubmitted = submitted.filter((entry) => {
+    const proposal = proposalById.get(entry.proposalId);
+    return proposal?.pluginId === 'gmail' && proposal.actionId === 'archive_message';
+  });
+  const lines = [
+    `窗口：${windowStart} — ${windowEnd}`,
+    `读取邮件：${messages.length} 封；重要候选：${important.length} 封；推广候选：${promotional.length} 封；归档建议：${archiveProposals.length} 项；自动归档：${autoArchiveSubmitted.length} 项；自动提交总计：${submitted.length} 项。`,
+    `分析方式：${analysis.usedModel ? `${analysis.provider}${analysis.model ? ` (${analysis.model})` : ''}` : 'deterministic rules'}.`,
+    ...(analysis.summary ? ['', '模型摘要：', analysis.summary] : []),
+    '',
+    '重要邮件候选：',
+    ...(important.length > 0
+      ? important.slice(0, 15).map((message) => `- ${message.subject} — ${message.from}`)
+      : ['- 未发现明确的重要邮件候选。']),
+    '',
+    '最近邮件：',
+    ...messages.slice(0, 20).map((message) => `- ${message.subject} — ${message.from}${message.snippet ? `：${message.snippet.slice(0, 160)}` : ''}`),
+    '',
+    '行动建议（仅提议，不会自动发送或删除）：',
+    ...(proposals.length > 0 ? proposals.slice(0, 20).map((proposal) => `- ${proposal.reason}`) : ['- 暂无。']),
+    '',
+    '自动执行结果：',
+    ...(standingGrantResults.length > 0
+      ? standingGrantResults.slice(0, 20).map((entry) => `- ${entry.status}: ${entry.proposalId}${entry.reason ? ` — ${entry.reason}` : ''}`)
+      : ['- 没有匹配 Standing Grant。']),
+    ...(analysis.warnings.length > 0 ? ['', '分析警告：', ...analysis.warnings.map((warning) => `- ${warning}`)] : []),
+  ];
+  return lines.join('\n');
+}
+
+async function gmailAction(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  origin: ExecutionJobOrigin,
+  requestId: string,
+  actionId: string,
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const executed = await executeAssistantPluginAction({
+    controllerHome,
+    repoId: repository.repoId,
+    repoRoot: repository.canonicalRoot,
+    pluginId: 'gmail',
+    actionId,
+    requestId,
+    args,
+    origin,
+  });
+  return recordValue(executed.result);
+}
+
+export async function executeAssistantRoutineRuntime(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  routineId: string;
+  requestId: string;
+  origin: ExecutionJobOrigin;
+  occurrenceId?: string;
+}): Promise<{
+  run: AssistantRoutineRun;
+  messages: GmailMessageSummary[];
+  proposals: AssistantActionProposal[];
+  analysis?: AssistantModelAnalysis;
+  standingGrantResults?: StandingGrantExecutionResult[];
+}> {
+  const routine = getAssistantRoutine(input.repository.canonicalRoot, input.routineId);
+  if (routine.status !== 'enabled') throw new Error(`ASSISTANT_ROUTINE_NOT_ENABLED: ${routine.routineId}`);
+  const cursor = readCursor(input.repository.canonicalRoot, routine.routineId);
+  const windowEnd = now();
+  const fallbackStart = new Date(Date.now() - 24 * 60 * 60_000).toISOString();
+  const windowStart = cursor.lastSuccessfulAt ?? fallbackStart;
+  const runId = input.occurrenceId ? `routine-run-${input.occurrenceId}` : `routine-run-${routine.routineId}-${Date.now()}`;
+  let run = saveRun(input.repository.canonicalRoot, {
+    schemaVersion: 1,
+    runId,
+    routineId: routine.routineId,
+    requestId: input.requestId,
+    occurrenceId: input.occurrenceId,
+    status: 'collecting',
+    windowStart,
+    windowEnd,
+    collectedItems: 0,
+    processedItems: 0,
+    proposedActions: 0,
+    createdAt: now(),
+  });
+  try {
+    if (!routine.dataSources.includes('gmail')) {
+      throw new Error('ASSISTANT_ROUTINE_GMAIL_REQUIRED: this runtime currently finalizes Gmail-backed routines');
+    }
+    const profile = await gmailAction(input.controllerHome, input.repository, input.origin, `${input.requestId}:profile`, 'get_profile', {});
+    const known = new Set(cursor.processedMessageIds);
+    const messageIds: string[] = [];
+    const startingContinuation = cursor.continuation;
+    let nextContinuation: GmailRoutineCursor['continuation'];
+    let historyFallback = !cursor.historyId;
+    let historyInvalid = false;
+    if (cursor.historyId) {
+      try {
+        let historyPageToken = startingContinuation?.mode === 'history' ? startingContinuation.pageToken : undefined;
+        for (let page = 0; page < 5 && messageIds.length < 100; page += 1) {
+          const history = await gmailAction(input.controllerHome, input.repository, input.origin, `${input.requestId}:history:${page}`, 'list_history', {
+            start_history_id: cursor.historyId, max_results: 100, label_id: 'INBOX', history_type: 'messageAdded',
+            ...(historyPageToken ? { page_token: historyPageToken } : {}),
+          });
+          for (const entry of Array.isArray(history.history) ? history.history.map(recordValue) : []) {
+            for (const added of Array.isArray(entry.messagesAdded) ? entry.messagesAdded.map(recordValue) : []) {
+              const id = stringValue(recordValue(added.message).id);
+              if (id && !known.has(id) && !messageIds.includes(id)) messageIds.push(id);
+            }
+          }
+          historyPageToken = stringValue(history.nextPageToken);
+          if (!historyPageToken) break;
+        }
+        if (historyPageToken) nextContinuation = { mode: 'history', pageToken: historyPageToken };
+      } catch (error) {
+        const status = isAssistantPluginError(error) ? Number(error.details?.status) : undefined;
+        if (status !== 404) throw error;
+        historyFallback = true;
+        historyInvalid = true;
+        nextContinuation = undefined;
+      }
+    }
+    if (historyFallback) {
+      const overlapStart = Math.max(0, Date.parse(windowStart) - 5 * 60_000);
+      const query = `in:inbox -in:spam -in:trash after:${Math.floor(overlapStart / 1000)}`;
+      let pageToken = startingContinuation?.mode === 'query' ? startingContinuation.pageToken : undefined;
+      for (let page = 0; page < 5 && messageIds.length < 100; page += 1) {
+        const listed = await gmailAction(input.controllerHome, input.repository, input.origin, `${input.requestId}:list:${page}`, 'list_messages', {
+          query, max_results: 25, ...(pageToken ? { page_token: pageToken } : {}),
+        });
+        for (const message of Array.isArray(listed.messages) ? listed.messages.map(recordValue) : []) {
+          const id = stringValue(message.id);
+          if (id && !known.has(id) && !messageIds.includes(id)) messageIds.push(id);
+        }
+        pageToken = stringValue(listed.nextPageToken);
+        if (!pageToken) break;
+      }
+      nextContinuation = pageToken ? { mode: 'query', pageToken } : undefined;
+    }
+    const messages: GmailMessageSummary[] = [];
+    for (const messageId of messageIds.slice(0, 50)) {
+      const fetched = await gmailAction(input.controllerHome, input.repository, input.origin, `${input.requestId}:message:${messageId}`, 'get_message', {
+        message_id: messageId,
+        format: 'full',
+      });
+      const raw = recordValue(fetched.message && typeof fetched.message === 'object' ? fetched.message : fetched);
+      messages.push(summarizeMessage(raw));
+    }
+    const modelAnalysis = await analyzeAssistantMessages({ messages, routineGoal: routine.naturalLanguageGoal });
+    const proposalInputs = modelAnalysis.usedModel ? modelAnalysis.proposals : buildDeterministicAssistantProposals(messages);
+    const proposals = createAssistantActionProposals(input.controllerHome, input.repository, { routineId: routine.routineId, runId, proposals: proposalInputs });
+    const standingGrantApplication = await applyAssistantStandingGrants(input.controllerHome, input.repository, { routineId: routine.routineId, runId, proposals });
+    const persistedProposals = listAssistantActionProposals(input.controllerHome, input.repository, { limit: 500 }).proposals
+      .filter((proposal) => proposal.runId === runId);
+    const analysis: AssistantModelAnalysis = {
+      ...modelAnalysis,
+      warnings: [...modelAnalysis.warnings, ...standingGrantApplication.warnings],
+    };
+    const hydrationTruncated = messageIds.length > messages.length;
+    const paginationIncomplete = Boolean(nextContinuation);
+    const truncated = hydrationTruncated || paginationIncomplete;
+    const savedContinuation = truncated
+      ? hydrationTruncated ? startingContinuation : nextContinuation
+      : undefined;
+    const report = renderAssistantRoutineReport(messages, persistedProposals, windowStart, windowEnd, analysis, standingGrantApplication.results);
+    run = saveRun(input.repository.canonicalRoot, {
+      ...run,
+      status: 'completed',
+      collectedItems: messageIds.length,
+      processedItems: messages.length,
+      proposedActions: persistedProposals.length,
+      autoSubmittedActions: standingGrantApplication.results.filter((entry) => entry.status === 'submitted').length,
+      analysis: {
+        usedModel: analysis.usedModel,
+        provider: analysis.provider,
+        model: analysis.model,
+        promptVersion: analysis.promptVersion,
+        fallbackReason: analysis.fallbackReason,
+        warnings: analysis.warnings,
+      },
+      summary: report,
+      completedAt: now(),
+    });
+    touchAssistantRoutineRun(input.repository.canonicalRoot, routine.routineId);
+    addAssistantInboxItem(input.repository.canonicalRoot, {
+      kind: 'routine_result',
+      title: `Routine 已完成：${routine.name}`,
+      summary: `读取 ${messages.length} 封新邮件，生成 ${persistedProposals.length} 项行动建议，自动提交 ${standingGrantApplication.results.filter((entry) => entry.status === 'submitted').length} 项。`,
+      body: report,
+      source: 'routine',
+      relatedRoutineId: routine.routineId,
+      relatedRequestId: input.requestId,
+      jobIds: standingGrantApplication.results.flatMap((entry) => entry.executionJobId ? [entry.executionJobId] : []),
+      recommendations: [
+        ...(truncated ? ['本次达到正文读取上限，下一次将从相同时间窗口继续处理剩余邮件。'] : []),
+        '发送邮件和移入垃圾箱仍需单独明确确认。',
+        '可基于行动建议创建草稿、任务或归档审批。',
+        ...(analysis.fallbackReason ? ['模型分析不可用，本次已安全回退到规则引擎。'] : []),
+      ],
+      data: { run, messages, proposals: persistedProposals, truncated, analysis, standingGrantResults: standingGrantApplication.results },
+    });
+    saveCursor(input.repository.canonicalRoot, {
+      schemaVersion: 1,
+      routineId: routine.routineId,
+      lastSuccessfulAt: truncated ? windowStart : windowEnd,
+      historyId: truncated ? historyInvalid ? undefined : cursor.historyId : stringValue(profile.historyId) ?? cursor.historyId,
+      continuation: savedContinuation,
+      processedMessageIds: [...messages.map((message) => message.id), ...cursor.processedMessageIds].slice(0, 1_000),
+      updatedAt: now(),
+    });
+    return { run, messages, proposals: persistedProposals, analysis, standingGrantResults: standingGrantApplication.results };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const authRequired = /PLUGIN_AUTH|UNAUTHENTICATED|invalid credentials/i.test(message);
+    run = saveRun(input.repository.canonicalRoot, {
+      ...run,
+      status: authRequired ? 'auth_required' : 'failed',
+      error: message,
+      completedAt: now(),
+    });
+    addAssistantInboxItem(input.repository.canonicalRoot, {
+      kind: 'system_note',
+      title: authRequired ? `Routine 需要重新授权：${routine.name}` : `Routine 执行失败：${routine.name}`,
+      summary: message,
+      source: 'routine',
+      relatedRoutineId: routine.routineId,
+      relatedRequestId: input.requestId,
+      jobIds: [],
+      recommendations: authRequired ? ['重新完成 Google Workspace 授权后再恢复 Routine。'] : ['检查 Routine Run 和 Execution Job 证据后重试。'],
+      data: { run },
+    });
+    throw error;
+  }
+}

package/src/runtime/assistant/schedule-binding.ts

@@ -0,0 +1,171 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { createSchedule, getSchedule, saveSchedule } from '../workflow/schedules/store';
+import type { ScheduleTrigger } from '../workflow/schedules/types';
+import { getAssistantRoutine, updateAssistantRoutineStatus } from './store';
+import type { AssistantRoutine, AssistantRoutineStatus } from './types';
+
+export interface AssistantRoutineScheduleBinding {
+  schemaVersion: 1;
+  routineId: string;
+  scheduleId: string;
+  repoId: string;
+  timezone: string;
+  normalizedSchedule: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface BindingStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  bindings: AssistantRoutineScheduleBinding[];
+}
+
+function now(): string { return new Date().toISOString(); }
+function bindingPath(repoRoot: string): string { return join(repoRoot, '.forge', 'assistant', 'routine-schedules.json'); }
+
+function readBindings(repoRoot: string): BindingStore {
+  const path = bindingPath(repoRoot);
+  if (!existsSync(path)) return { schemaVersion: 1, updatedAt: now(), bindings: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<BindingStore>;
+    return {
+      schemaVersion: 1,
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : now(),
+      bindings: Array.isArray(parsed.bindings)
+        ? parsed.bindings.filter((entry): entry is AssistantRoutineScheduleBinding => Boolean(
+            entry && typeof entry === 'object'
+            && typeof entry.routineId === 'string'
+            && typeof entry.scheduleId === 'string'
+            && typeof entry.repoId === 'string',
+          ))
+        : [],
+    };
+  } catch {
+    return { schemaVersion: 1, updatedAt: now(), bindings: [] };
+  }
+}
+
+function writeBindings(repoRoot: string, store: BindingStore): void {
+  const path = bindingPath(repoRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ ...store, schemaVersion: 1, updatedAt: now() }, null, 2)}\n`, 'utf-8');
+  renameSync(tmp, path);
+}
+
+const WEEKDAYS: Array<[RegExp, number]> = [
+  [/(?:周|星期)(?:日|天)|sunday/i, 0],
+  [/(?:周|星期)一|monday/i, 1],
+  [/(?:周|星期)二|tuesday/i, 2],
+  [/(?:周|星期)三|wednesday/i, 3],
+  [/(?:周|星期)四|thursday/i, 4],
+  [/(?:周|星期)五|friday/i, 5],
+  [/(?:周|星期)六|saturday/i, 6],
+];
+
+export function parseAssistantScheduleText(
+  scheduleText: string,
+  timezone = 'UTC',
+): { trigger: ScheduleTrigger; normalized: string; timezone: string } {
+  const text = scheduleText.trim();
+  const time = text.match(/(?:^|\D)([01]?\d|2[0-3])(?:\s*[:点时]\s*([0-5]?\d))?/);
+  const hour = time ? Number(time[1]) : 9;
+  const minute = time?.[2] ? Number(time[2]) : 0;
+  const weekday = WEEKDAYS.find(([pattern]) => pattern.test(text))?.[1];
+  const cronExpression = `${minute} ${hour} * * ${weekday ?? '*'}`;
+  const normalized = `${weekday === undefined ? 'daily' : `weekly:${weekday}`} ${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')} ${timezone}`;
+  return {
+    trigger: {
+      type: 'cron',
+      cronExpression,
+      timezone,
+      catchUpMinutes: 12 * 60,
+    },
+    normalized,
+    timezone,
+  };
+}
+
+export function getAssistantRoutineScheduleBinding(
+  repoRoot: string,
+  routineId: string,
+): AssistantRoutineScheduleBinding | undefined {
+  return readBindings(repoRoot).bindings.find((entry) => entry.routineId === routineId);
+}
+
+export function bindAssistantRoutineSchedule(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  routine: AssistantRoutine,
+): AssistantRoutineScheduleBinding {
+  const existing = getAssistantRoutineScheduleBinding(repository.canonicalRoot, routine.routineId);
+  if (existing) return existing;
+  const parsed = parseAssistantScheduleText(routine.scheduleText, routine.timezone || 'UTC');
+  const schedule = createSchedule(controllerHome, {
+    requestId: `assistant-routine:${repository.repoId}:${routine.routineId}`,
+    repoId: repository.repoId,
+    name: `Assistant Routine: ${routine.name}`,
+    enabled: routine.status === 'enabled',
+    trigger: parsed.trigger,
+    policy: {
+      maxActiveOccurrences: 1,
+      maxFailures: 5,
+      cooldownMinutes: 1,
+      dailyBudgetMinutes: 30,
+      shadowMode: false,
+      backoffBaseMinutes: 5,
+      backoffMaxMinutes: 12 * 60,
+    },
+    action: {
+      operation: 'assistant_routine_execute',
+      target: 'runtime',
+      arguments: { routineId: routine.routineId },
+      priority: 'P3',
+      resourceClaims: [{ resourceKey: `assistant-routine:${repository.repoId}:${routine.routineId}`, mode: 'exclusive' }],
+    },
+    stopConditions: [],
+  });
+  const at = now();
+  const binding: AssistantRoutineScheduleBinding = {
+    schemaVersion: 1,
+    routineId: routine.routineId,
+    scheduleId: schedule.scheduleId,
+    repoId: repository.repoId,
+    timezone: parsed.timezone,
+    normalizedSchedule: parsed.normalized,
+    createdAt: at,
+    updatedAt: at,
+  };
+  const store = readBindings(repository.canonicalRoot);
+  store.bindings.unshift(binding);
+  writeBindings(repository.canonicalRoot, store);
+  return binding;
+}
+
+export function updateAssistantRoutineLifecycle(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  routineId: string,
+  status: AssistantRoutineStatus,
+): { routine: AssistantRoutine; binding?: AssistantRoutineScheduleBinding } {
+  const routine = updateAssistantRoutineStatus(repository.canonicalRoot, routineId, status);
+  let binding = getAssistantRoutineScheduleBinding(repository.canonicalRoot, routineId);
+  if (!binding && status === 'enabled') binding = bindAssistantRoutineSchedule(controllerHome, repository, routine);
+  if (binding) {
+    const schedule = getSchedule(controllerHome, repository.repoId, binding.scheduleId);
+    const enabled = status === 'enabled';
+    saveSchedule(controllerHome, {
+      ...schedule,
+      enabled,
+      pausedReason: enabled ? undefined : `Assistant Routine ${status}: ${routineId}`,
+    });
+    binding = { ...binding, updatedAt: now() };
+    const store = readBindings(repository.canonicalRoot);
+    store.bindings = [binding, ...store.bindings.filter((entry) => entry.routineId !== routineId)];
+    writeBindings(repository.canonicalRoot, store);
+  }
+  return { routine, binding };
+}