@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/personal-assistant/gmail-triage-manager.ts

@@ -0,0 +1,231 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import type { AssistantPluginManifest } from '../plugins/types';
+import {
+  defaultTriageRules,
+  normalizeAssistantItem,
+  triageItems,
+  type AssistantItem,
+  type TriageDecision,
+  type TriageRule,
+} from './triage-runtime';
+
+export interface GmailTriageRuleStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  rules: TriageRule[];
+}
+
+export interface GmailTriageSummary {
+  total: number;
+  byPriority: Record<string, number>;
+  byCategory: Record<string, number>;
+  requiresUserInput: number;
+  remoteWriteActions: number;
+}
+
+export interface GmailTriagePlan {
+  repoId: string;
+  generatedAt: string;
+  plugin: {
+    pluginId: 'gmail';
+    configured: boolean;
+    enabled: boolean;
+    ready: boolean;
+    healthState?: string;
+    warnings: string[];
+    next: string[];
+  };
+  query: string;
+  rulesPath: string;
+  ruleCount: number;
+  summary: GmailTriageSummary;
+  decisions: TriageDecision[];
+  actionQueue: Array<{
+    actionId: string;
+    sourceId: string;
+    type: string;
+    risk: string;
+    requiresConfirmation: boolean;
+    summary: string;
+    executableByPlugin: boolean;
+    pluginActionId?: string;
+    arguments?: Record<string, unknown>;
+  }>;
+  next: string[];
+}
+
+export interface GmailTriageRuleUpsertResult {
+  path: string;
+  rule: TriageRule;
+  store: GmailTriageRuleStore;
+}
+
+const RULE_PATH = '.forge/assistant/gmail-triage-rules.json';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function rulePath(repository: RepositoryRecord): string {
+  return join(repository.canonicalRoot, RULE_PATH);
+}
+
+function writeJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+function readStoredRules(repository: RepositoryRecord): GmailTriageRuleStore | undefined {
+  const path = rulePath(repository);
+  if (!existsSync(path)) return undefined;
+  const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<GmailTriageRuleStore>;
+  return {
+    schemaVersion: 1,
+    updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : now(),
+    rules: Array.isArray(parsed.rules) ? parsed.rules : [],
+  };
+}
+
+function normalizeRule(input: Record<string, unknown>, existing?: TriageRule): TriageRule {
+  const id = String(input.id ?? existing?.id ?? '').trim();
+  if (!id) throw new Error('GMAIL_TRIAGE_RULE_ID_REQUIRED');
+  const match = input.match && typeof input.match === 'object' && !Array.isArray(input.match)
+    ? input.match as TriageRule['match']
+    : existing?.match;
+  const decision = input.decision && typeof input.decision === 'object' && !Array.isArray(input.decision)
+    ? input.decision as TriageRule['decision']
+    : existing?.decision;
+  if (!match) throw new Error('GMAIL_TRIAGE_RULE_MATCH_REQUIRED');
+  if (!decision) throw new Error('GMAIL_TRIAGE_RULE_DECISION_REQUIRED');
+  return {
+    id,
+    enabled: input.enabled === undefined ? existing?.enabled ?? true : input.enabled === true,
+    order: typeof input.order === 'number' ? Math.trunc(input.order) : existing?.order ?? 50,
+    match,
+    decision,
+  };
+}
+
+export function readGmailTriageRules(repository: RepositoryRecord): GmailTriageRuleStore {
+  const stored = readStoredRules(repository);
+  if (stored) return stored;
+  return { schemaVersion: 1, updatedAt: now(), rules: defaultTriageRules() };
+}
+
+export function upsertGmailTriageRule(repository: RepositoryRecord, input: Record<string, unknown>): GmailTriageRuleUpsertResult {
+  const store = readGmailTriageRules(repository);
+  const id = String(input.id ?? '').trim();
+  const existing = store.rules.find((rule) => rule.id === id);
+  const rule = normalizeRule(input, existing);
+  const next: GmailTriageRuleStore = {
+    schemaVersion: 1,
+    updatedAt: now(),
+    rules: [rule, ...store.rules.filter((entry) => entry.id !== rule.id)].sort((left, right) => (left.order ?? 0) - (right.order ?? 0)),
+  };
+  writeJson(rulePath(repository), next);
+  return { path: RULE_PATH, rule, store: next };
+}
+
+function normalizedItems(items: unknown): AssistantItem[] {
+  if (!Array.isArray(items)) return [];
+  return items
+    .filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+    .map((entry) => normalizeAssistantItem({
+      source: 'gmail',
+      source_id: String(entry.source_id ?? entry.sourceId ?? entry.id ?? entry.message_id ?? '').trim(),
+      kind: 'email',
+      title: String(entry.title ?? entry.subject ?? entry.snippet ?? '').trim(),
+      body: typeof entry.body === 'string' ? entry.body : typeof entry.snippet === 'string' ? entry.snippet : undefined,
+      actor: typeof entry.actor === 'string' ? entry.actor : typeof entry.from === 'string' ? entry.from : undefined,
+      timestamp: typeof entry.timestamp === 'string' ? entry.timestamp : typeof entry.date === 'string' ? entry.date : undefined,
+      labels: Array.isArray(entry.labels) ? entry.labels.map(String) : Array.isArray(entry.label_ids) ? entry.label_ids.map(String) : undefined,
+      urls: Array.isArray(entry.urls) ? entry.urls.map(String) : undefined,
+      attachments: Array.isArray(entry.attachments) ? entry.attachments as AssistantItem['attachments'] : undefined,
+      metadata: { ...entry },
+    }))
+    .filter((item) => item.source_id && item.title);
+}
+
+function pluginSummary(manifest: AssistantPluginManifest | undefined) {
+  const actions = new Set(manifest?.actions.map((action) => action.actionId) ?? []);
+  const ready = manifest?.enabled === true && manifest.health.ready === true;
+  const next: string[] = [];
+  if (!manifest) next.push('Initialize or enable the Gmail plugin manifest.');
+  else if (!manifest.enabled) next.push('Configure the Gmail plugin before trying to read mail.');
+  else if (!ready) next.push('Fix Gmail plugin health warnings before executing Gmail actions.');
+  return {
+    pluginId: 'gmail' as const,
+    configured: Boolean(manifest),
+    enabled: manifest?.enabled === true,
+    ready,
+    healthState: manifest?.health.state,
+    warnings: [...(manifest?.health.warnings ?? []), ...(manifest?.health.errors ?? [])],
+    next,
+    actions,
+  };
+}
+
+function summarize(decisions: TriageDecision[]): GmailTriageSummary {
+  const byPriority: Record<string, number> = {};
+  const byCategory: Record<string, number> = {};
+  let remoteWriteActions = 0;
+  for (const decision of decisions) {
+    byPriority[decision.priority] = (byPriority[decision.priority] ?? 0) + 1;
+    byCategory[decision.category] = (byCategory[decision.category] ?? 0) + 1;
+    remoteWriteActions += decision.suggested_actions.filter((action) => action.risk !== 'readonly').length;
+  }
+  return {
+    total: decisions.length,
+    byPriority,
+    byCategory,
+    requiresUserInput: decisions.filter((decision) => decision.requires_user_input).length,
+    remoteWriteActions,
+  };
+}
+
+function pluginActionFor(type: string): string | undefined {
+  if (type === 'archive' || type === 'mark_read' || type === 'label') return undefined;
+  if (type === 'draft_reply') return 'create_draft';
+  return undefined;
+}
+
+export function buildGmailTriagePlan(repository: RepositoryRecord, input: { manifest?: AssistantPluginManifest; items?: unknown; query?: unknown } = {}): GmailTriagePlan {
+  const rules = readGmailTriageRules(repository).rules;
+  const items = normalizedItems(input.items);
+  const decisions = triageItems(items, { rules, low_value_action_mode: 'archive_candidate' })
+    .sort((left, right) => left.priority.localeCompare(right.priority) || right.confidence - left.confidence);
+  const plugin = pluginSummary(input.manifest);
+  const actionQueue = decisions.flatMap((decision) => decision.suggested_actions.map((action) => {
+    const pluginActionId = pluginActionFor(action.type);
+    return {
+      actionId: action.id,
+      sourceId: decision.source_id,
+      type: action.type,
+      risk: action.risk,
+      requiresConfirmation: action.requires_confirmation,
+      summary: action.summary,
+      executableByPlugin: Boolean(pluginActionId && plugin.ready && plugin.actions.has(pluginActionId)),
+      pluginActionId,
+      arguments: action.arguments,
+    };
+  }));
+  const next = [
+    ...(items.length === 0 ? ['Fetch messages with the Gmail plugin list_messages action, then pass summaries into gmail_triage_plan.'] : []),
+    ...(actionQueue.some((action) => action.requiresConfirmation) ? ['Review remote-write action proposals before executing any Gmail mutations.'] : []),
+    ...plugin.next,
+  ];
+  return {
+    repoId: repository.repoId,
+    generatedAt: now(),
+    plugin: { pluginId: plugin.pluginId, configured: plugin.configured, enabled: plugin.enabled, ready: plugin.ready, healthState: plugin.healthState, warnings: plugin.warnings, next: plugin.next },
+    query: String(input.query ?? 'in:inbox newer_than:14d').trim(),
+    rulesPath: RULE_PATH,
+    ruleCount: rules.length,
+    summary: summarize(decisions),
+    decisions,
+    actionQueue,
+    next: [...new Set(next)],
+  };
+}

package/src/runtime/personal-assistant/reporting-runtime.ts

@@ -0,0 +1,344 @@
+import type {
+  ActionProposal,
+  AssistantItem,
+  TriageCategory,
+  TriageDecision,
+  TriagePriority,
+} from "./triage-runtime";
+import { triageItems } from "./triage-runtime";
+
+export type ReportSinkKind =
+  | "chatgpt"
+  | "gmail_draft"
+  | "resend_email"
+  | "notion_page"
+  | "github_issue"
+  | "local_file"
+  | "forge_worklog";
+
+export type ReportSinkRisk = "readonly" | "workspace_write" | "remote_write";
+
+export interface ReportSink {
+  id: string;
+  kind: ReportSinkKind;
+  enabled: boolean;
+  risk: ReportSinkRisk;
+  requires_confirmation: boolean;
+  title: string;
+  description?: string;
+  config?: Record<string, unknown>;
+}
+
+export interface AssistantRuleProfile {
+  id: string;
+  name: string;
+  version: number;
+  low_value_marketing: "delete_candidate" | "archive_candidate" | "ignore";
+  learning_mail: "archive" | "keep";
+  tool_updates: "archive" | "keep";
+  security_mail: "keep";
+  quota_mail: "keep";
+  devops_mail: "keep";
+  github_security_mail: "keep";
+  require_confirmation_for_remote_write: boolean;
+  protected_categories: TriageCategory[];
+  delete_sender_allowlist: string[];
+  archive_sender_allowlist: string[];
+}
+
+export interface AssistantBriefOptions {
+  title?: string;
+  now?: string;
+  max_items_per_section?: number;
+  include_action_plan?: boolean;
+  include_ignored?: boolean;
+  report_sink_id?: string;
+  profile?: AssistantRuleProfile;
+}
+
+export interface AssistantBriefSection {
+  id: string;
+  title: string;
+  priority: TriagePriority | "info";
+  items: AssistantBriefItem[];
+}
+
+export interface AssistantBriefItem {
+  source_id: string;
+  title: string;
+  actor?: string;
+  category: TriageCategory;
+  priority: TriagePriority;
+  reason: string;
+  action_summaries: string[];
+}
+
+export interface AssistantBrief {
+  title: string;
+  generated_at: string;
+  sink?: ReportSink;
+  sections: AssistantBriefSection[];
+  proposed_actions: ActionProposal[];
+  protected_count: number;
+  cleanup_candidate_count: number;
+}
+
+export const DEFAULT_REPORT_SINKS: ReportSink[] = [
+  {
+    id: "chatgpt-daily-brief",
+    kind: "chatgpt",
+    enabled: true,
+    risk: "readonly",
+    requires_confirmation: false,
+    title: "ChatGPT daily assistant brief",
+    description: "Default delivery path when no native forge notification sink is configured.",
+  },
+  {
+    id: "gmail-draft-daily-brief",
+    kind: "gmail_draft",
+    enabled: false,
+    risk: "remote_write",
+    requires_confirmation: true,
+    title: "Gmail draft daily assistant brief",
+    description: "Creates a reviewable draft instead of sending mail automatically.",
+  },
+  {
+    id: "resend-daily-brief",
+    kind: "resend_email",
+    enabled: false,
+    risk: "remote_write",
+    requires_confirmation: true,
+    title: "Resend email daily assistant brief",
+    description: "Sends the rendered daily brief through the first-party Resend plugin after strong confirmation.",
+    config: { plugin_id: "resend", action_id: "send_email" },
+  },
+  {
+    id: "notion-daily-brief",
+    kind: "notion_page",
+    enabled: false,
+    risk: "remote_write",
+    requires_confirmation: true,
+    title: "Notion daily assistant journal",
+  },
+  {
+    id: "repo-worklog-daily-brief",
+    kind: "forge_worklog",
+    enabled: false,
+    risk: "workspace_write",
+    requires_confirmation: true,
+    title: "forge worklog report",
+  },
+];
+
+export const DEFAULT_ASSISTANT_RULE_PROFILE: AssistantRuleProfile = {
+  id: "greyson-default-mail-triage",
+  name: "Greyson default assistant triage",
+  version: 1,
+  low_value_marketing: "delete_candidate",
+  learning_mail: "archive",
+  tool_updates: "archive",
+  security_mail: "keep",
+  quota_mail: "keep",
+  devops_mail: "keep",
+  github_security_mail: "keep",
+  require_confirmation_for_remote_write: true,
+  protected_categories: ["security", "quota", "billing", "devops", "repository"],
+  delete_sender_allowlist: [
+    "no-reply@spotify.com",
+    "julie@surveylama.com",
+    "emails@efinancialcareers.com",
+    "jobs-listings@linkedin.com",
+    "hello@builder.io",
+  ],
+  archive_sender_allowlist: [
+    "noreply@trans.preply.com",
+    "noreply@tips.preply.com",
+    "welcome@openrouter.ai",
+    "team@moonshot.ai",
+    "notifications@account.z.ai",
+    "ship@info.vercel.com",
+  ],
+};
+
+export function buildDailyAssistantBrief(
+  items: AssistantItem[],
+  options: AssistantBriefOptions = {},
+): AssistantBrief {
+  const profile = options.profile ?? DEFAULT_ASSISTANT_RULE_PROFILE;
+  const decisions = triageItems(items);
+  const sink = DEFAULT_REPORT_SINKS.find((candidate) => candidate.id === options.report_sink_id)
+    ?? DEFAULT_REPORT_SINKS.find((candidate) => candidate.enabled);
+  const proposed_actions = proposeAssistantActions(items, decisions, profile);
+  const maxItems = options.max_items_per_section ?? 8;
+  const sections = buildBriefSections(items, decisions, proposed_actions, maxItems, Boolean(options.include_ignored));
+
+  return {
+    title: options.title ?? "Daily Assistant Brief",
+    generated_at: options.now ?? new Date().toISOString(),
+    sink,
+    sections,
+    proposed_actions: options.include_action_plan === false ? [] : proposed_actions,
+    protected_count: decisions.filter((decision) => profile.protected_categories.includes(decision.category)).length,
+    cleanup_candidate_count: proposed_actions.filter((action) => action.type === "archive" || action.type === "label").length
+      + proposed_actions.filter((action) => action.type === "ignore" && action.summary.toLowerCase().includes("delete")).length,
+  };
+}
+
+export function proposeAssistantActions(
+  items: AssistantItem[],
+  decisions: TriageDecision[],
+  profile: AssistantRuleProfile = DEFAULT_ASSISTANT_RULE_PROFILE,
+): ActionProposal[] {
+  const itemById = new Map(items.map((item) => [item.source_id, item]));
+  const actions: ActionProposal[] = [];
+
+  for (const decision of decisions) {
+    const item = itemById.get(decision.source_id);
+    if (!item) continue;
+
+    if (profile.protected_categories.includes(decision.category)) {
+      actions.push({
+        id: actionId("keep", item.source_id),
+        type: "summarize",
+        target_source_id: item.source_id,
+        summary: `Keep in inbox and include in brief: ${item.title}`,
+        risk: "readonly",
+        requires_confirmation: false,
+      });
+      continue;
+    }
+
+    const actor = (item.actor ?? "").toLowerCase();
+    const isDeleteAllowed = profile.delete_sender_allowlist.some((sender) => actor.includes(sender));
+    const isArchiveAllowed = profile.archive_sender_allowlist.some((sender) => actor.includes(sender));
+
+    if ((decision.category === "marketing" || decision.category === "job") && profile.low_value_marketing === "delete_candidate" && isDeleteAllowed) {
+      actions.push({
+        id: actionId("delete-candidate", item.source_id),
+        type: "ignore",
+        target_source_id: item.source_id,
+        summary: `Delete candidate: low-value ${decision.category} from ${item.actor ?? "unknown sender"}`,
+        risk: "remote_write",
+        requires_confirmation: true,
+        arguments: { gmail_action: "trash" },
+      });
+      continue;
+    }
+
+    if ((decision.category === "calendar" || isArchiveAllowed) && profile.learning_mail === "archive") {
+      actions.push({
+        id: actionId("archive", item.source_id),
+        type: "archive",
+        target_source_id: item.source_id,
+        summary: `Archive after briefing: ${item.title}`,
+        risk: "remote_write",
+        requires_confirmation: profile.require_confirmation_for_remote_write,
+      });
+      continue;
+    }
+
+    if ((decision.category === "newsletter" || decision.category === "unknown") && isArchiveAllowed && profile.tool_updates === "archive") {
+      actions.push({
+        id: actionId("archive-tool-update", item.source_id),
+        type: "archive",
+        target_source_id: item.source_id,
+        summary: `Archive tool update: ${item.title}`,
+        risk: "remote_write",
+        requires_confirmation: profile.require_confirmation_for_remote_write,
+      });
+    }
+  }
+
+  return actions;
+}
+
+export function renderBriefMarkdown(brief: AssistantBrief): string {
+  const lines: string[] = [];
+  lines.push(`# ${brief.title}`);
+  lines.push("");
+  lines.push(`Generated: ${brief.generated_at}`);
+  if (brief.sink) {
+    lines.push(`Report sink: ${brief.sink.title} (${brief.sink.kind})`);
+  }
+  lines.push(`Protected items: ${brief.protected_count}`);
+  lines.push(`Cleanup candidates: ${brief.cleanup_candidate_count}`);
+
+  for (const section of brief.sections) {
+    lines.push("");
+    lines.push(`## ${section.title}`);
+    if (section.items.length === 0) {
+      lines.push("- None");
+      continue;
+    }
+    for (const item of section.items) {
+      lines.push(`- **${item.title}** — ${item.reason}`);
+      if (item.actor) lines.push(`  - From: ${item.actor}`);
+      if (item.action_summaries.length > 0) lines.push(`  - Actions: ${item.action_summaries.join("; ")}`);
+    }
+  }
+
+  if (brief.proposed_actions.length > 0) {
+    lines.push("");
+    lines.push("## Proposed actions");
+    for (const action of brief.proposed_actions) {
+      const confirmation = action.requires_confirmation ? "requires confirmation" : "no confirmation required";
+      lines.push(`- ${action.summary} [${action.risk}, ${confirmation}]`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function buildBriefSections(
+  items: AssistantItem[],
+  decisions: TriageDecision[],
+  actions: ActionProposal[],
+  maxItems: number,
+  includeIgnored: boolean,
+): AssistantBriefSection[] {
+  const itemById = new Map(items.map((item) => [item.source_id, item]));
+  const actionsByTarget = new Map<string, ActionProposal[]>();
+  for (const action of actions) {
+    const list = actionsByTarget.get(action.target_source_id) ?? [];
+    list.push(action);
+    actionsByTarget.set(action.target_source_id, list);
+  }
+
+  const toBriefItem = (decision: TriageDecision): AssistantBriefItem | null => {
+    const item = itemById.get(decision.source_id);
+    if (!item) return null;
+    return {
+      source_id: item.source_id,
+      title: item.title,
+      actor: item.actor,
+      category: decision.category,
+      priority: decision.priority,
+      reason: decision.reason,
+      action_summaries: (actionsByTarget.get(item.source_id) ?? []).map((action) => action.summary),
+    };
+  };
+
+  const section = (id: string, title: string, priority: TriagePriority | "info", predicate: (d: TriageDecision) => boolean): AssistantBriefSection => ({
+    id,
+    title,
+    priority,
+    items: decisions.filter(predicate).map(toBriefItem).filter((item): item is AssistantBriefItem => item !== null).slice(0, maxItems),
+  });
+
+  const sections = [
+    section("urgent", "Urgent / user attention", "P0", (decision) => decision.priority === "P0" || decision.requires_user_input),
+    section("account-ops", "Account, quota, and DevOps", "P1", (decision) => ["quota", "billing", "devops", "repository"].includes(decision.category)),
+    section("calendar", "Calendar and learning", "P2", (decision) => decision.category === "calendar"),
+    section("cleanup", "Cleanup candidates", "P3", (decision) => ["marketing", "job", "newsletter"].includes(decision.category)),
+  ];
+
+  if (includeIgnored) {
+    sections.push(section("unknown", "Unknown / uncategorized", "info", (decision) => decision.category === "unknown"));
+  }
+
+  return sections;
+}
+
+function actionId(prefix: string, sourceId: string): string {
+  return `${prefix}:${sourceId}`.replace(/[^a-zA-Z0-9:_-]/g, "_");
+}