@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/assistant/standing-grants.ts

@@ -1,375 +0,0 @@
-import { randomUUID } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
-import type { RepositoryRecord } from '../../cli/repositories/types';
-import { withControllerLock } from '../../cli/repositories/locks';
-import { appendRuntimeEvent } from '../evidence/event-ledger';
-import {
-  approveAssistantActionProposal,
-  listAssistantActionProposals,
-  type AssistantActionProposal,
-} from './action-proposals';
-
-export type AssistantStandingGrantStatus = 'active' | 'revoked' | 'expired';
-export type AssistantStandingGrantSurface = 'mcp' | 'local-ui';
-
-export interface AssistantStandingGrantConstraints {
-  routineIds: string[];
-  senderAllowlist: string[];
-  subjectContains: string[];
-  minConfidence: number;
-  maxPerRun: number;
-}
-
-export interface AssistantStandingGrant {
-  schemaVersion: 1;
-  grantId: string;
-  name: string;
-  pluginId: string;
-  actionId: string;
-  status: AssistantStandingGrantStatus;
-  constraints: AssistantStandingGrantConstraints;
-  expiresAt: string;
-  createdAt: string;
-  updatedAt: string;
-  createdBy: { surface: AssistantStandingGrantSurface; actor: string };
-  revokedAt?: string;
-  revokedBy?: { surface: AssistantStandingGrantSurface; actor: string };
-  revokeReason?: string;
-}
-
-export interface CreateAssistantStandingGrantInput {
-  name?: string;
-  pluginId: string;
-  actionId: string;
-  routineIds?: string[];
-  senderAllowlist?: string[];
-  subjectContains?: string[];
-  minConfidence?: number;
-  maxPerRun?: number;
-  expiresInDays?: number;
-  confirmAuthorization: boolean;
-  origin: { surface: AssistantStandingGrantSurface; actor: string };
-}
-
-interface StandingGrantStore {
-  schemaVersion: 1;
-  updatedAt: string;
-  grants: AssistantStandingGrant[];
-}
-
-export interface StandingGrantExecutionResult {
-  grantId: string;
-  proposalId: string;
-  status: 'submitted' | 'skipped' | 'failed';
-  executionJobId?: string;
-  reason?: string;
-}
-
-const ELIGIBLE_ACTIONS = new Set([
-  'gmail/create_draft',
-  'gmail/archive_message',
-  'gmail/mark_message_read',
-  'gmail/mark_message_unread',
-  'google_tasks/create_task',
-]);
-
-function now(): string { return new Date().toISOString(); }
-function storePath(repoRoot: string): string { return join(repoRoot, '.forge', 'assistant', 'standing-grants.json'); }
-
-function uniqueStrings(value: unknown, max = 100): string[] {
-  if (!Array.isArray(value)) return [];
-  return [...new Set(value.map((entry) => String(entry).trim()).filter(Boolean))].slice(0, max);
-}
-
-function normalizeEmailRule(value: string): string {
-  return value.trim().toLowerCase().replace(/^mailto:/, '');
-}
-
-function normalizeGrant(raw: unknown): AssistantStandingGrant | undefined {
-  if (!raw || typeof raw !== 'object') return undefined;
-  const value = raw as Record<string, unknown>;
-  const grantId = typeof value.grantId === 'string' && value.grantId.trim() ? value.grantId.trim() : undefined;
-  const pluginId = typeof value.pluginId === 'string' && value.pluginId.trim() ? value.pluginId.trim() : undefined;
-  const actionId = typeof value.actionId === 'string' && value.actionId.trim() ? value.actionId.trim() : undefined;
-  const expiresAt = typeof value.expiresAt === 'string' ? value.expiresAt : undefined;
-  if (!grantId || !pluginId || !actionId || !expiresAt || !isStandingGrantEligibleAction(pluginId, actionId)) return undefined;
-  const constraints = value.constraints && typeof value.constraints === 'object' && !Array.isArray(value.constraints)
-    ? value.constraints as Record<string, unknown>
-    : {};
-  const createdBy = value.createdBy && typeof value.createdBy === 'object' && !Array.isArray(value.createdBy)
-    ? value.createdBy as Record<string, unknown>
-    : {};
-  const status: AssistantStandingGrantStatus = value.status === 'revoked' || value.status === 'expired' ? value.status : 'active';
-  return {
-    schemaVersion: 1,
-    grantId,
-    name: typeof value.name === 'string' && value.name.trim() ? value.name.trim() : `${pluginId}.${actionId}`,
-    pluginId,
-    actionId,
-    status,
-    constraints: {
-      routineIds: uniqueStrings(constraints.routineIds, 100),
-      senderAllowlist: uniqueStrings(constraints.senderAllowlist, 100).map(normalizeEmailRule),
-      subjectContains: uniqueStrings(constraints.subjectContains, 50),
-      minConfidence: typeof constraints.minConfidence === 'number' && Number.isFinite(constraints.minConfidence)
-        ? Math.max(0, Math.min(1, constraints.minConfidence))
-        : 0.8,
-      maxPerRun: typeof constraints.maxPerRun === 'number' && Number.isFinite(constraints.maxPerRun)
-        ? Math.max(1, Math.min(50, Math.trunc(constraints.maxPerRun)))
-        : 1,
-    },
-    expiresAt,
-    createdAt: typeof value.createdAt === 'string' ? value.createdAt : now(),
-    updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : now(),
-    createdBy: {
-      surface: createdBy.surface === 'mcp' ? 'mcp' : 'local-ui',
-      actor: typeof createdBy.actor === 'string' && createdBy.actor.trim() ? createdBy.actor.trim() : 'unknown',
-    },
-    revokedAt: typeof value.revokedAt === 'string' ? value.revokedAt : undefined,
-    revokedBy: value.revokedBy && typeof value.revokedBy === 'object' && !Array.isArray(value.revokedBy)
-      ? {
-          surface: (value.revokedBy as Record<string, unknown>).surface === 'mcp' ? 'mcp' : 'local-ui',
-          actor: String((value.revokedBy as Record<string, unknown>).actor ?? 'unknown'),
-        }
-      : undefined,
-    revokeReason: typeof value.revokeReason === 'string' ? value.revokeReason : undefined,
-  };
-}
-
-function readStore(repoRoot: string): StandingGrantStore {
-  const path = storePath(repoRoot);
-  if (!existsSync(path)) return { schemaVersion: 1, updatedAt: now(), grants: [] };
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<StandingGrantStore>;
-    return {
-      schemaVersion: 1,
-      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : now(),
-      grants: Array.isArray(parsed.grants) ? parsed.grants.flatMap((entry) => normalizeGrant(entry) ?? []) : [],
-    };
-  } catch {
-    return { schemaVersion: 1, updatedAt: now(), grants: [] };
-  }
-}
-
-function writeStore(repoRoot: string, store: StandingGrantStore): void {
-  const path = storePath(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);
-}
-
-function expireGrant(grant: AssistantStandingGrant): AssistantStandingGrant {
-  if (grant.status === 'active' && Date.parse(grant.expiresAt) <= Date.now()) {
-    return { ...grant, status: 'expired', updatedAt: now() };
-  }
-  return grant;
-}
-
-export function isStandingGrantEligibleAction(pluginId: string, actionId: string): boolean {
-  return ELIGIBLE_ACTIONS.has(`${pluginId}/${actionId}`);
-}
-
-export function createAssistantStandingGrant(
-  controllerHome: string,
-  repository: RepositoryRecord,
-  input: CreateAssistantStandingGrantInput,
-): AssistantStandingGrant {
-  if (input.confirmAuthorization !== true) throw new Error('ASSISTANT_STANDING_GRANT_AUTHORIZATION_REQUIRED');
-  const pluginId = input.pluginId.trim();
-  const actionId = input.actionId.trim();
-  if (!isStandingGrantEligibleAction(pluginId, actionId)) {
-    throw new Error(`ASSISTANT_STANDING_GRANT_ACTION_NOT_ALLOWED: ${pluginId}/${actionId}`);
-  }
-  const routineIds = uniqueStrings(input.routineIds, 100);
-  const senderAllowlist = uniqueStrings(input.senderAllowlist, 100).map(normalizeEmailRule);
-  const subjectContains = uniqueStrings(input.subjectContains, 50);
-  if (routineIds.length === 0 && senderAllowlist.length === 0 && subjectContains.length === 0) {
-    throw new Error('ASSISTANT_STANDING_GRANT_SCOPE_REQUIRED');
-  }
-  if (pluginId === 'gmail' && actionId === 'create_draft' && senderAllowlist.length === 0) {
-    throw new Error('ASSISTANT_STANDING_GRANT_SENDER_SCOPE_REQUIRED');
-  }
-  return withControllerLock(controllerHome, { scope: 'repository', repoId: repository.repoId }, `assistant-standing-grant-create:${pluginId}:${actionId}`, () => {
-    const store = readStore(repository.canonicalRoot);
-    const at = now();
-    const expiresInDays = Math.max(1, Math.min(365, Math.trunc(input.expiresInDays ?? 30)));
-    const grant: AssistantStandingGrant = {
-      schemaVersion: 1,
-      grantId: `grant-${Date.now()}-${randomUUID().slice(0, 8)}`,
-      name: input.name?.trim() || `${pluginId}.${actionId}`,
-      pluginId,
-      actionId,
-      status: 'active',
-      constraints: {
-        routineIds,
-        senderAllowlist,
-        subjectContains,
-        minConfidence: Math.max(0, Math.min(1, input.minConfidence ?? 0.8)),
-        maxPerRun: Math.max(1, Math.min(50, Math.trunc(input.maxPerRun ?? 1))),
-      },
-      expiresAt: new Date(Date.now() + expiresInDays * 24 * 60 * 60_000).toISOString(),
-      createdAt: at,
-      updatedAt: at,
-      createdBy: { surface: input.origin.surface, actor: input.origin.actor.trim() || 'unknown' },
-    };
-    store.grants.unshift(grant);
-    store.grants = store.grants.slice(0, 500);
-    writeStore(repository.canonicalRoot, store);
-    appendRuntimeEvent(controllerHome, {
-      repoId: repository.repoId,
-      entityType: 'assistant-standing-grant',
-      entityId: grant.grantId,
-      eventType: 'assistant_standing_grant_created',
-      requestId: grant.grantId,
-      revision: 1,
-      data: {
-        pluginId: grant.pluginId,
-        actionId: grant.actionId,
-        expiresAt: grant.expiresAt,
-        constraints: grant.constraints,
-        surface: grant.createdBy.surface,
-      },
-    });
-    return grant;
-  }, 10_000);
-}
-
-export function listAssistantStandingGrants(
-  controllerHome: string,
-  repository: RepositoryRecord,
-  input: { status?: AssistantStandingGrantStatus; limit?: number } = {},
-): { grants: AssistantStandingGrant[] } {
-  const store = readStore(repository.canonicalRoot);
-  const grants = store.grants.map(expireGrant);
-  const limit = Math.max(1, Math.min(500, Math.trunc(input.limit ?? 100)));
-  return {
-    grants: grants
-      .filter((grant) => !input.status || grant.status === input.status)
-      .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
-      .slice(0, limit),
-  };
-}
-
-export function revokeAssistantStandingGrant(
-  controllerHome: string,
-  repository: RepositoryRecord,
-  input: {
-    grantId: string;
-    reason?: string;
-    confirmAuthorization: boolean;
-    origin: { surface: AssistantStandingGrantSurface; actor: string };
-  },
-): AssistantStandingGrant {
-  if (input.confirmAuthorization !== true) throw new Error('ASSISTANT_STANDING_GRANT_AUTHORIZATION_REQUIRED');
-  return withControllerLock(controllerHome, { scope: 'repository', repoId: repository.repoId }, `assistant-standing-grant-revoke:${input.grantId}`, () => {
-    const store = readStore(repository.canonicalRoot);
-    const grant = store.grants.find((entry) => entry.grantId === input.grantId);
-    if (!grant) throw new Error(`ASSISTANT_STANDING_GRANT_NOT_FOUND: ${input.grantId}`);
-    if (grant.status === 'revoked') return grant;
-    grant.status = 'revoked';
-    grant.revokedAt = now();
-    grant.updatedAt = grant.revokedAt;
-    grant.revokedBy = { surface: input.origin.surface, actor: input.origin.actor.trim() || 'unknown' };
-    grant.revokeReason = input.reason?.trim() || 'Revoked by user.';
-    writeStore(repository.canonicalRoot, store);
-    appendRuntimeEvent(controllerHome, {
-      repoId: repository.repoId,
-      entityType: 'assistant-standing-grant',
-      entityId: grant.grantId,
-      eventType: 'assistant_standing_grant_revoked',
-      requestId: grant.grantId,
-      revision: 1,
-      data: { reason: grant.revokeReason, surface: grant.revokedBy.surface },
-    });
-    return grant;
-  }, 10_000);
-}
-
-function normalizedSender(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined;
-  return value.match(/<([^>]+@[^>]+)>/)?.[1]?.trim().toLowerCase()
-    ?? value.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i)?.[0]?.toLowerCase();
-}
-
-function senderMatches(sender: string | undefined, rules: string[]): boolean {
-  if (rules.length === 0) return true;
-  if (!sender) return false;
-  return rules.some((rule) => {
-    const normalized = normalizeEmailRule(rule);
-    if (!normalized) return false;
-    if (normalized.startsWith('@')) return sender.endsWith(normalized);
-    if (!normalized.includes('@')) return sender.endsWith(`@${normalized}`);
-    return sender === normalized;
-  });
-}
-
-function subjectMatches(subject: string | undefined, fragments: string[]): boolean {
-  if (fragments.length === 0) return true;
-  if (!subject) return false;
-  const normalized = subject.toLowerCase();
-  return fragments.some((fragment) => normalized.includes(fragment.toLowerCase()));
-}
-
-function grantMatches(grant: AssistantStandingGrant, proposal: AssistantActionProposal, routineId: string): boolean {
-  if (grant.status !== 'active' || !isStandingGrantEligibleAction(grant.pluginId, grant.actionId)) return false;
-  if (grant.pluginId !== proposal.pluginId || grant.actionId !== proposal.actionId) return false;
-  if (proposal.status !== 'proposed' || !proposal.executable || proposal.executionJobId) return false;
-  if (proposal.confidence < grant.constraints.minConfidence) return false;
-  if (proposal.context?.protected === true && proposal.actionId === 'archive_message') return false;
-  if (grant.constraints.routineIds.length > 0 && !grant.constraints.routineIds.includes(routineId)) return false;
-  const sender = normalizedSender(proposal.context?.sender);
-  if (!senderMatches(sender, grant.constraints.senderAllowlist)) return false;
-  return subjectMatches(proposal.context?.subject, grant.constraints.subjectContains);
-}
-
-export async function applyAssistantStandingGrants(
-  controllerHome: string,
-  repository: RepositoryRecord,
-  input: { routineId: string; runId: string; proposals: AssistantActionProposal[] },
-): Promise<{ results: StandingGrantExecutionResult[]; warnings: string[] }> {
-  const active = listAssistantStandingGrants(controllerHome, repository, { status: 'active', limit: 500 }).grants;
-  const current = listAssistantActionProposals(controllerHome, repository, { limit: 500 }).proposals;
-  const byId = new Map(current.map((proposal) => [proposal.proposalId, proposal]));
-  const results: StandingGrantExecutionResult[] = [];
-  const warnings: string[] = [];
-  for (const grant of active) {
-    let applied = current.filter((proposal) => proposal.runId === input.runId && proposal.standingGrantId === grant.grantId).length;
-    for (const supplied of input.proposals) {
-      if (applied >= grant.constraints.maxPerRun) break;
-      const proposal = byId.get(supplied.proposalId) ?? supplied;
-      if (proposal.runId !== input.runId || !grantMatches(grant, proposal, input.routineId)) continue;
-      try {
-        const approved = await approveAssistantActionProposal(controllerHome, repository, {
-          proposalId: proposal.proposalId,
-          requestId: `standing-grant:${grant.grantId}:${proposal.proposalId}`,
-          origin: { surface: 'standing-grant', actor: `standing-grant:${grant.grantId}` },
-          standingGrantId: grant.grantId,
-        });
-        applied += 1;
-        byId.set(approved.proposalId, approved);
-        results.push({
-          grantId: grant.grantId,
-          proposalId: proposal.proposalId,
-          status: 'submitted',
-          executionJobId: approved.executionJobId,
-        });
-        appendRuntimeEvent(controllerHome, {
-          repoId: repository.repoId,
-          entityType: 'assistant-standing-grant',
-          entityId: grant.grantId,
-          eventType: 'assistant_standing_grant_applied',
-          requestId: input.runId,
-          revision: 1,
-          data: { proposalId: proposal.proposalId, executionJobId: approved.executionJobId },
-        });
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        results.push({ grantId: grant.grantId, proposalId: proposal.proposalId, status: 'failed', reason });
-        warnings.push(`Standing Grant ${grant.grantId} could not apply proposal ${proposal.proposalId}: ${reason}`);
-      }
-    }
-  }
-  return { results, warnings };
-}

package/src/runtime/assistant/store.ts

@@ -1,243 +0,0 @@
-import { randomUUID } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
-import type {
-  AssistantInboxItem,
-  AssistantInboxStore,
-  AssistantMemoryEntry,
-  AssistantMemoryStore,
-  AssistantRoutine,
-  AssistantRoutineDraft,
-  AssistantRoutineStatus,
-  AssistantRoutinesStore,
-} from './types';
-
-function now(): string { return new Date().toISOString(); }
-function assistantRoot(repoRoot: string): string { return join(repoRoot, '.forge', 'assistant'); }
-function routinesPath(repoRoot: string): string { return join(assistantRoot(repoRoot), 'routines.json'); }
-function inboxPath(repoRoot: string): string { return join(assistantRoot(repoRoot), 'inbox.json'); }
-function memoryPath(repoRoot: string): string { return join(assistantRoot(repoRoot), 'memory.json'); }
-function safeId(prefix: string): string { return `${prefix}-${Date.now()}-${randomUUID().slice(0, 8)}`; }
-
-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 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 normalizeStrings(value: unknown): string[] {
-  return Array.isArray(value) ? [...new Set(value.map((entry) => String(entry).trim()).filter(Boolean))] : [];
-}
-
-function normalizeRoutine(value: unknown): AssistantRoutine | undefined {
-  if (!value || typeof value !== 'object') return undefined;
-  const raw = value as Record<string, unknown>;
-  const routineId = typeof raw.routineId === 'string' && raw.routineId.trim() ? raw.routineId.trim() : undefined;
-  const name = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : undefined;
-  const naturalLanguageGoal = typeof raw.naturalLanguageGoal === 'string' && raw.naturalLanguageGoal.trim() ? raw.naturalLanguageGoal.trim() : undefined;
-  const scheduleText = typeof raw.scheduleText === 'string' && raw.scheduleText.trim() ? raw.scheduleText.trim() : undefined;
-  if (!routineId || !name || !naturalLanguageGoal || !scheduleText) return undefined;
-  const status = raw.status === 'paused' || raw.status === 'deleted' ? raw.status : 'enabled';
-  const output = raw.output === 'gmail_draft' || raw.output === 'none' ? raw.output : 'assistant_inbox';
-  return {
-    schemaVersion: 1,
-    routineId,
-    name,
-    naturalLanguageGoal,
-    scheduleText,
-    timezone: typeof raw.timezone === 'string' ? raw.timezone : undefined,
-    dataSources: normalizeStrings(raw.dataSources),
-    output,
-    allowedActions: normalizeStrings(raw.allowedActions),
-    forbiddenActions: normalizeStrings(raw.forbiddenActions),
-    status,
-    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : now(),
-    updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : now(),
-    lastRunAt: typeof raw.lastRunAt === 'string' ? raw.lastRunAt : undefined,
-    nextRunHint: typeof raw.nextRunHint === 'string' ? raw.nextRunHint : undefined,
-  };
-}
-
-function normalizeInboxItem(value: unknown): AssistantInboxItem | undefined {
-  if (!value || typeof value !== 'object') return undefined;
-  const raw = value as Record<string, unknown>;
-  const itemId = typeof raw.itemId === 'string' && raw.itemId.trim() ? raw.itemId.trim() : undefined;
-  const title = typeof raw.title === 'string' && raw.title.trim() ? raw.title.trim() : undefined;
-  const summary = typeof raw.summary === 'string' && raw.summary.trim() ? raw.summary.trim() : undefined;
-  if (!itemId || !title || !summary) return undefined;
-  const kind = raw.kind === 'routine_result' || raw.kind === 'approval_request' || raw.kind === 'system_note' ? raw.kind : 'intent_result';
-  const status = raw.status === 'read' || raw.status === 'archived' ? raw.status : 'unread';
-  return {
-    schemaVersion: 1,
-    itemId,
-    kind,
-    status,
-    title,
-    summary,
-    body: typeof raw.body === 'string' ? raw.body : undefined,
-    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : now(),
-    updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : now(),
-    source: raw.source === 'chatgpt' || raw.source === 'mcp' || raw.source === 'local-ui' || raw.source === 'mobile' || raw.source === 'routine' ? raw.source : 'system',
-    relatedRoutineId: typeof raw.relatedRoutineId === 'string' ? raw.relatedRoutineId : undefined,
-    relatedRequestId: typeof raw.relatedRequestId === 'string' ? raw.relatedRequestId : undefined,
-    jobIds: normalizeStrings(raw.jobIds),
-    recommendations: normalizeStrings(raw.recommendations),
-    data: raw.data && typeof raw.data === 'object' && !Array.isArray(raw.data) ? raw.data as Record<string, unknown> : undefined,
-  };
-}
-
-function readRoutines(repoRoot: string): AssistantRoutinesStore {
-  const parsed = readJson<Partial<AssistantRoutinesStore>>(routinesPath(repoRoot), { schemaVersion: 1, updatedAt: now(), routines: [] });
-  return {
-    schemaVersion: 1,
-    updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : now(),
-    routines: Array.isArray(parsed.routines) ? parsed.routines.flatMap((entry) => normalizeRoutine(entry) ?? []) : [],
-  };
-}
-
-function writeRoutines(repoRoot: string, store: AssistantRoutinesStore): AssistantRoutinesStore {
-  const next = { schemaVersion: 1 as const, updatedAt: now(), routines: store.routines };
-  writeJson(routinesPath(repoRoot), next);
-  return next;
-}
-
-function readInbox(repoRoot: string): AssistantInboxStore {
-  const parsed = readJson<Partial<AssistantInboxStore>>(inboxPath(repoRoot), { schemaVersion: 1, updatedAt: now(), items: [] });
-  return {
-    schemaVersion: 1,
-    updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : now(),
-    items: Array.isArray(parsed.items) ? parsed.items.flatMap((entry) => normalizeInboxItem(entry) ?? []) : [],
-  };
-}
-
-function writeInbox(repoRoot: string, store: AssistantInboxStore): AssistantInboxStore {
-  const next = { schemaVersion: 1 as const, updatedAt: now(), items: store.items.slice(0, 500) };
-  writeJson(inboxPath(repoRoot), next);
-  return next;
-}
-
-export function listAssistantRoutines(repoRoot: string, includeDeleted = false): { routines: AssistantRoutine[] } {
-  const store = readRoutines(repoRoot);
-  return { routines: store.routines.filter((routine) => includeDeleted || routine.status !== 'deleted').sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)) };
-}
-
-export function createAssistantRoutine(repoRoot: string, draft: AssistantRoutineDraft): AssistantRoutine {
-  const store = readRoutines(repoRoot);
-  const at = now();
-  const routine: AssistantRoutine = {
-    schemaVersion: 1,
-    routineId: safeId('routine'),
-    name: draft.name,
-    naturalLanguageGoal: draft.naturalLanguageGoal,
-    scheduleText: draft.scheduleText,
-    timezone: draft.timezone,
-    dataSources: [...new Set(draft.dataSources)],
-    output: draft.output,
-    allowedActions: [...new Set(draft.allowedActions)],
-    forbiddenActions: [...new Set(draft.forbiddenActions)],
-    status: 'enabled',
-    createdAt: at,
-    updatedAt: at,
-    nextRunHint: draft.scheduleText,
-  };
-  store.routines.unshift(routine);
-  writeRoutines(repoRoot, store);
-  return routine;
-}
-
-export function updateAssistantRoutineStatus(repoRoot: string, routineId: string, status: AssistantRoutineStatus): AssistantRoutine {
-  const store = readRoutines(repoRoot);
-  const routine = store.routines.find((entry) => entry.routineId === routineId);
-  if (!routine) throw new Error(`ASSISTANT_ROUTINE_NOT_FOUND: ${routineId}`);
-  routine.status = status;
-  routine.updatedAt = now();
-  writeRoutines(repoRoot, store);
-  return routine;
-}
-
-export function touchAssistantRoutineRun(repoRoot: string, routineId: string): AssistantRoutine {
-  const store = readRoutines(repoRoot);
-  const routine = store.routines.find((entry) => entry.routineId === routineId && entry.status !== 'deleted');
-  if (!routine) throw new Error(`ASSISTANT_ROUTINE_NOT_FOUND: ${routineId}`);
-  routine.lastRunAt = now();
-  routine.updatedAt = routine.lastRunAt;
-  writeRoutines(repoRoot, store);
-  return routine;
-}
-
-export function getAssistantRoutine(repoRoot: string, routineId: string): AssistantRoutine {
-  const routine = readRoutines(repoRoot).routines.find((entry) => entry.routineId === routineId && entry.status !== 'deleted');
-  if (!routine) throw new Error(`ASSISTANT_ROUTINE_NOT_FOUND: ${routineId}`);
-  return routine;
-}
-
-export function listAssistantInbox(repoRoot: string, limit = 50): { items: AssistantInboxItem[] } {
-  const store = readInbox(repoRoot);
-  return { items: store.items.sort((a, b) => b.createdAt.localeCompare(a.createdAt)).slice(0, Math.max(1, Math.min(limit, 200))) };
-}
-
-export function addAssistantInboxItem(repoRoot: string, input: Omit<AssistantInboxItem, 'schemaVersion' | 'itemId' | 'createdAt' | 'updatedAt' | 'status'> & { status?: AssistantInboxItem['status'] }): AssistantInboxItem {
-  const store = readInbox(repoRoot);
-  const at = now();
-  const item: AssistantInboxItem = {
-    schemaVersion: 1,
-    itemId: safeId('inbox'),
-    createdAt: at,
-    updatedAt: at,
-    status: input.status ?? 'unread',
-    kind: input.kind,
-    title: input.title,
-    summary: input.summary,
-    body: input.body,
-    source: input.source,
-    relatedRoutineId: input.relatedRoutineId,
-    relatedRequestId: input.relatedRequestId,
-    jobIds: input.jobIds,
-    recommendations: input.recommendations,
-    data: input.data,
-  };
-  store.items.unshift(item);
-  writeInbox(repoRoot, store);
-  return item;
-}
-
-export function updateAssistantInboxStatus(repoRoot: string, itemId: string, status: AssistantInboxItem['status']): AssistantInboxItem {
-  const store = readInbox(repoRoot);
-  const item = store.items.find((entry) => entry.itemId === itemId);
-  if (!item) throw new Error(`ASSISTANT_INBOX_ITEM_NOT_FOUND: ${itemId}`);
-  item.status = status;
-  item.updatedAt = now();
-  writeInbox(repoRoot, store);
-  return item;
-}
-
-export function listAssistantMemory(repoRoot: string): { entries: AssistantMemoryEntry[] } {
-  const parsed = readJson<Partial<AssistantMemoryStore>>(memoryPath(repoRoot), { schemaVersion: 1, updatedAt: now(), entries: [] });
-  const entries = Array.isArray(parsed.entries)
-    ? parsed.entries.flatMap((entry) => {
-      if (!entry || typeof entry !== 'object') return [];
-      const raw = entry as unknown as Record<string, unknown>;
-      const key = typeof raw.key === 'string' && raw.key.trim() ? raw.key.trim() : undefined;
-      const value = typeof raw.value === 'string' && raw.value.trim() ? raw.value.trim() : undefined;
-      if (!key || !value) return [];
-      return [{ key, value, updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : now(), source: typeof raw.source === 'string' ? raw.source : undefined }];
-    })
-    : [];
-  return { entries };
-}
-
-export function upsertAssistantMemory(repoRoot: string, entry: { key: string; value: string; source?: string }): AssistantMemoryEntry {
-  const current = listAssistantMemory(repoRoot).entries;
-  const at = now();
-  const normalized: AssistantMemoryEntry = { key: entry.key.trim(), value: entry.value.trim(), source: entry.source, updatedAt: at };
-  if (!normalized.key || !normalized.value) throw new Error('ASSISTANT_MEMORY_INVALID: key and value are required');
-  const next = [normalized, ...current.filter((item) => item.key !== normalized.key)];
-  writeJson(memoryPath(repoRoot), { schemaVersion: 1, updatedAt: at, entries: next } satisfies AssistantMemoryStore);
-  return normalized;
-}