@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,375 @@
+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

@@ -0,0 +1,243 @@
+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;
+}