forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/dev/types.ts

@@ -1,7 +1,9 @@
 import type { DevRoute } from "../compiler/types/dev-manifest.ts";
 import type { DbAdapter } from "../runtime/db/adapter.ts";
+import type { AmbientDeltaRecorder } from "../delta/recorder.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
 
-export type DevDbMode = "pglite" | "postgres" | "none";
+export type DevDbMode = "memory" | "pglite" | "postgres" | "none";
 
 export interface DevServerOptions {
   workspaceRoot: string;
@@ -18,6 +20,7 @@ export interface DevServerOptions {
   mode?: "dev" | "serve";
   allowDevAuth?: boolean;
   webUrl?: string;
+  deltaRecorder?: AmbientDeltaRecorder;
 }
 
 export interface DevServerDbState {
@@ -41,9 +44,20 @@ export interface DevServerHandle {
   routes: DevRoute[];
   state: DevServerState;
   outboxWorker?: DevServerState["outboxWorker"];
+  reload: (reason?: string) => Promise<DevServerReloadResult>;
   stop: () => void;
 }
 
+export interface DevServerReloadResult {
+  ok: boolean;
+  reason: string;
+  migrated: boolean;
+  routes: number;
+  runtimeEntries: number;
+  worker: "running" | "stopped";
+  diagnostics: Diagnostic[];
+}
+
 export interface DevWatchHandle {
   stop: () => void;
 }

package/src/forge/dev/watch.ts

@@ -21,28 +21,38 @@ export function shouldSkipWatchPath(absolutePath: string): boolean {
 
 export function createDebouncedCallback(
   debounceMs: number,
-  callback: (changedCount: number) => void | Promise<void>,
-): (increment?: number) => void {
+  callback: (changedCount: number, changedPaths: string[]) => void | Promise<void>,
+): (incrementOrPath?: number | string) => void {
   let pendingChanges = 0;
+  const pendingPaths = new Set<string>();
   let timer: ReturnType<typeof setTimeout> | null = null;
 
-  return (increment = 1) => {
-    pendingChanges += increment;
+  return (incrementOrPath) => {
+    if (typeof incrementOrPath === "number") {
+      pendingChanges += incrementOrPath;
+    } else {
+      pendingChanges += 1;
+    }
+    if (typeof incrementOrPath === "string") {
+      pendingPaths.add(incrementOrPath);
+    }
     if (timer !== null) {
       clearTimeout(timer);
     }
     timer = setTimeout(async () => {
       const count = pendingChanges;
+      const paths = [...pendingPaths].sort();
       pendingChanges = 0;
+      pendingPaths.clear();
       timer = null;
-      await callback(count);
+      await callback(count, paths);
     }, debounceMs);
   };
 }
 
 export function startDevWatch(
   workspaceRoot: string,
-  onRegenerate: (changedCount: number) => void | Promise<void>,
+  onRegenerate: (changedCount: number, changedPaths: string[]) => void | Promise<void>,
 ): DevWatchHandle {
   const roots = getSourceRoots(workspaceRoot);
   const watchers: FSWatcher[] = [];
@@ -71,7 +81,7 @@ export function startDevWatch(
             return;
           }
 
-          debounced();
+          debounced(relativePath);
         },
       );
 

package/src/forge/dev-console/cycle.ts

@@ -1,5 +1,5 @@
 import { nodeFileSystem } from "../compiler/fs/index.ts";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { buildAppGraph } from "../compiler/app-graph/build.ts";
 import { classify } from "../compiler/classifier/classify.ts";
 import { buildRuntimeMatrix } from "../compiler/classifier/runtime-matrix.ts";
@@ -26,8 +26,12 @@ import { runImpactCommand } from "../impact/index.ts";
 import type { TestRunRecord } from "../impact/types.ts";
 import { loadSecretRegistry } from "../runtime/secrets/check.ts";
 import type { UiRunReport } from "../ui/types.ts";
+import { buildDiffPlanFromChangeSummary, categorizeFiles, summarizeChangeTypes } from "../workspace/change-summary.ts";
+import { forgeCliCommandForWorkspace, forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
 import type {
   DevConsoleCycle,
+  DevConsoleAgentContext,
+  DevConsoleGeneratedSummary,
   DevConsoleNextAction,
   DevConsoleOptions,
   DevConsolePhase,
@@ -117,17 +121,30 @@ function skippedPhase(
   };
 }
 
+function compactFileList(files: string[], sampleSize = 12): {
+  count: number;
+  sample: string[];
+  hidden: number;
+} {
+  return {
+    count: files.length,
+    sample: files.slice(0, sampleSize),
+    hidden: Math.max(0, files.length - sampleSize),
+  };
+}
+
 async function runGeneratedPhase(workspaceRoot: string): Promise<DevConsolePhase> {
   const start = performance.now();
   const result = await runGenerate({
     workspaceRoot,
-    check: true,
+    check: false,
     dryRun: false,
     json: false,
     concurrency: 4,
   });
   const diagnostics = [...result.errors, ...result.warnings];
   const durationMs = msSince(start);
+  const changed = compactFileList(result.changed);
   return {
     name: "generated",
     ok: result.exitCode === 0,
@@ -135,11 +152,18 @@ async function runGeneratedPhase(workspaceRoot: string): Promise<DevConsolePhase
     diagnostics,
     durationMs,
     details: {
-      changed: result.changed,
+      changed: changed.count,
+      sampleChanged: changed.sample,
+      hiddenChanged: changed.hidden,
       unchangedCount: result.unchanged.length,
+      fullCommand: forgeCliCommandForWorkspace(workspaceRoot, "forge generate --json"),
       ...(result.cache ? { cache: result.cache } : {}),
     },
-    message: result.exitCode === 0 ? "generated artifacts are up to date" : "generated artifacts are stale",
+    message: result.exitCode === 0
+      ? result.changed.length > 0
+        ? `regenerated ${result.changed.length} generated artifacts`
+        : "generated artifacts are up to date"
+      : "generated artifacts could not be regenerated",
   };
 }
 
@@ -179,6 +203,8 @@ function requiredGeneratedArtifacts(workspaceRoot: string): Array<{ name: string
     { name: "agents-md", path: "AGENTS.md", ok: nodeFileSystem.exists(join(workspaceRoot, "AGENTS.md")) },
     { name: "forge-lock", path: "forge.lock", ok: nodeFileSystem.exists(join(workspaceRoot, "forge.lock")) },
     { name: "agent-contract", path: `${GENERATED_DIR}/agentContract.json`, ok: nodeFileSystem.exists(join(workspaceRoot, GENERATED_DIR, "agentContract.json")) },
+    { name: "agent-quickstart", path: `${GENERATED_DIR}/agentQuickstart.md`, ok: nodeFileSystem.exists(join(workspaceRoot, GENERATED_DIR, "agentQuickstart.md")) },
+    { name: "agent-cair-guide", path: `${GENERATED_DIR}/agentCairGuide.md`, ok: nodeFileSystem.exists(join(workspaceRoot, GENERATED_DIR, "agentCairGuide.md")) },
     { name: "capability-map", path: `${GENERATED_DIR}/capabilityMap.json`, ok: nodeFileSystem.exists(join(workspaceRoot, GENERATED_DIR, "capabilityMap.json")) },
     { name: "runtime-matrix", path: `${GENERATED_DIR}/runtimeMatrix.json`, ok: nodeFileSystem.exists(join(workspaceRoot, GENERATED_DIR, "runtimeMatrix.json")) },
     { name: "data-graph", path: `${GENERATED_DIR}/dataGraph.json`, ok: nodeFileSystem.exists(join(workspaceRoot, GENERATED_DIR, "dataGraph.json")) },
@@ -260,7 +286,21 @@ function runDoctorPhase(workspaceRoot: string): DevConsolePhase {
   );
 }
 
-function runFrontendPhase(workspaceRoot: string): DevConsolePhase {
+function withRuntimeFrontendUrls(
+  summary: FrontendSummary,
+  options: { apiUrl?: string; webUrl?: string },
+): FrontendSummary {
+  return {
+    ...summary,
+    ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+    ...(options.webUrl ? { devUrl: options.webUrl } : {}),
+  };
+}
+
+function runFrontendPhase(
+  workspaceRoot: string,
+  options: { apiUrl?: string; webUrl?: string } = {},
+): DevConsolePhase {
   const start = performance.now();
   const frontend = readJson<FrontendGraph>(workspaceRoot, `${GENERATED_DIR}/frontendGraph.json`);
   if (!frontend) {
@@ -274,7 +314,7 @@ function runFrontendPhase(workspaceRoot: string): DevConsolePhase {
     };
   }
 
-  const summary: FrontendSummary = {
+  const summary: FrontendSummary = withRuntimeFrontendUrls({
     present: frontend.present,
     framework: frontend.framework,
     routes: frontend.routes.map((route) => route.path),
@@ -282,7 +322,7 @@ function runFrontendPhase(workspaceRoot: string): DevConsolePhase {
     bridgeFiles: frontend.bridgeFiles,
     apiUrl: frontend.webManifest.urls.api,
     ...(frontend.dev ? { devUrl: frontend.dev.url, apiUrlEnv: frontend.dev.apiUrlEnv } : {}),
-  };
+  }, options);
   const diagnostics = frontend.diagnostics ?? [];
   const message = frontend.present
     ? `frontend ${frontend.framework} with ${frontend.routes.length} routes and ${frontend.clientBindings.length} bindings`
@@ -305,23 +345,102 @@ function defaultFrontendSummary(workspaceRoot: string): FrontendSummary {
   };
 }
 
+function nextPreviewPort(webUrl?: string): number {
+  if (!webUrl) {
+    return 5174;
+  }
+  try {
+    const parsed = new URL(webUrl);
+    const port = parsed.port ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80;
+    return Number.isFinite(port) && port > 0 ? port + 1 : 5174;
+  } catch {
+    return 5174;
+  }
+}
+
+function isForgeStudioWorkspace(workspaceRoot: string): boolean {
+  return basename(workspaceRoot).toLowerCase() === "forge-studio";
+}
+
+function previewSummaryFor(input: {
+  workspaceRoot: string;
+  webUrl?: string;
+}): DevConsoleSummary["preview"] {
+  if (input.webUrl && !isForgeStudioWorkspace(input.workspaceRoot)) {
+    const parsed = new URL(input.webUrl);
+    const targetAppPort = parsed.port ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80;
+    return {
+      targetAppUrl: input.webUrl,
+      targetAppPort,
+      isStudioSelfPreview: false,
+      note: `Web app preview is running at ${input.webUrl}.`,
+    };
+  }
+
+  const targetAppPort = nextPreviewPort(input.webUrl);
+  const targetAppUrl = `http://127.0.0.1:${targetAppPort}`;
+  const isStudioSelfPreview = Boolean(input.webUrl && input.webUrl === targetAppUrl);
+  return {
+    ...(input.webUrl ? { studioUrl: input.webUrl } : {}),
+    targetAppUrl,
+    targetAppPort,
+    isStudioSelfPreview,
+    note: input.webUrl
+      ? `Use ${targetAppUrl} for the app being built when ${input.webUrl} is Forge Studio itself.`
+      : `No web app was detected; ${targetAppUrl} is the default target app preview URL for Studio attach flows.`,
+  };
+}
+
+function buildGeneratedSummary(workspaceRoot: string, phaseItem: DevConsolePhase | undefined): DevConsoleGeneratedSummary {
+  const changedFiles = Number(phaseItem?.details?.changed ?? 0);
+  const sampleChanged = Array.isArray(phaseItem?.details?.sampleChanged)
+    ? phaseItem.details.sampleChanged.filter((item): item is string => typeof item === "string")
+    : [];
+  const hiddenChanged = Number(phaseItem?.details?.hiddenChanged ?? 0);
+  return {
+    ok: phaseItem?.ok === true,
+    state: phaseItem?.ok === true
+      ? changedFiles > 0 ? "regenerated" : "fresh"
+      : "stale-risk",
+    changedFiles,
+    sampleChanged,
+    hiddenChanged,
+    message: phaseItem?.message ?? "generated phase did not report a message",
+    command: forgeCliCommandForWorkspace(workspaceRoot, "forge generate"),
+    checkCommand: forgeCliCommandForWorkspace(workspaceRoot, "forge generate --check --json"),
+  };
+}
+
 function buildDevSummary(input: {
   workspaceRoot: string;
   ok: boolean;
   phases: DevConsolePhase[];
   diagnostics: Diagnostic[];
   nextActions: DevConsoleNextAction[];
+  apiUrl?: string;
+  webUrl?: string;
 }): DevConsoleSummary {
   const frontendPhase = input.phases.find((item) => item.name === "frontend");
-  const frontend =
+  const frontendBase =
     (frontendPhase?.details?.summary as FrontendSummary | undefined) ??
     defaultFrontendSummary(input.workspaceRoot);
+  const frontend = withRuntimeFrontendUrls(frontendBase, {
+    ...(input.apiUrl ? { apiUrl: input.apiUrl } : {}),
+    ...(input.webUrl ? { webUrl: input.webUrl } : {}),
+  });
   const capabilityMap = readJson<AgentCapabilityMap>(
     input.workspaceRoot,
     `${GENERATED_DIR}/capabilityMap.json`,
   );
   const warnings = input.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
   const errors = input.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+  const apiUrl = input.apiUrl ?? frontend.apiUrl ?? "http://127.0.0.1:3765";
+  const webUrl = input.webUrl ?? frontend.devUrl;
+  const generated = buildGeneratedSummary(input.workspaceRoot, input.phases.find((item) => item.name === "generated"));
+  const preview = previewSummaryFor({
+    workspaceRoot: input.workspaceRoot,
+    ...(webUrl ? { webUrl } : {}),
+  });
   return {
     project: {
       root: input.workspaceRoot,
@@ -333,9 +452,12 @@ function buildDevSummary(input: {
       skipped: input.phases.filter((item) => item.status === "skipped").length,
     },
     urls: {
-      api: frontend.apiUrl ?? "http://127.0.0.1:3765",
-      ...(frontend.devUrl ? { web: frontend.devUrl } : {}),
+      api: apiUrl,
+      ...(webUrl ? { web: webUrl } : {}),
+      suggestedPreview: preview.targetAppUrl,
     },
+    preview,
+    generated,
     frontend,
     capabilities: capabilityMap?.summary ?? {
       covered: 0,
@@ -343,6 +465,12 @@ function buildDevSummary(input: {
       frontendOnly: 0,
       warnings: 0,
     },
+    agentContext: buildAgentContext({
+      workspaceRoot: input.workspaceRoot,
+      phases: input.phases,
+      diagnostics: input.diagnostics,
+      nextActions: input.nextActions,
+    }),
     ...(input.nextActions[0] ? { primaryAction: input.nextActions[0] } : {}),
   };
 }
@@ -370,18 +498,28 @@ function runImpactPhase(workspaceRoot: string): DevConsolePhase {
   }
   const report = result.report;
   const summary: ImpactSummary | undefined = report
-    ? {
-      changedFiles: report.changedFiles,
-      risk: report.risk.level,
-      recommendedChecks: report.recommendedChecks,
-    }
+    ? (() => {
+      const changeSummary = categorizeFiles(report.changedFiles);
+      return {
+        changedFiles: report.changedFiles.length,
+        sampleChangedFiles: report.changedFiles.slice(0, 12),
+        hiddenChangedFiles: Math.max(0, report.changedFiles.length - 12),
+        changeSummary,
+        risk: report.risk.level,
+        recommendedChecks: report.recommendedChecks,
+        fullCommand: "forge impact --changed --json",
+      };
+    })()
     : undefined;
+  const changeTypes = summary ? summarizeChangeTypes(summary.changeSummary) : "";
   return phase(
     "impact",
     result.diagnostics,
     msSince(start),
     summary ? { summary } : undefined,
-    summary && summary.changedFiles.length > 0 ? `${summary.changedFiles.length} changed files detected` : "no changed files detected",
+    summary && summary.changedFiles > 0
+      ? `${summary.changedFiles} changed files detected${changeTypes ? `: ${changeTypes}` : ""}`
+      : "no changed files detected",
   );
 }
 
@@ -469,7 +607,7 @@ function uniqueActions(actions: DevConsoleNextAction[]): DevConsoleNextAction[]
   return result;
 }
 
-function nextActionsFromPhases(phases: DevConsolePhase[]): DevConsoleNextAction[] {
+function nextActionsFromPhases(workspaceRoot: string, phases: DevConsolePhase[]): DevConsoleNextAction[] {
   const actions: DevConsoleNextAction[] = [];
   const diagnostics = phases.flatMap((item) => item.diagnostics);
   if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
@@ -512,7 +650,12 @@ function nextActionsFromPhases(phases: DevConsolePhase[]): DevConsoleNextAction[
 
   const impact = phases.find((item) => item.name === "impact");
   const summary = impact?.details?.summary as ImpactSummary | undefined;
-  if (summary && summary.changedFiles.length > 0) {
+  if (summary && summary.changedFiles > 0) {
+    actions.push({
+      command: "forge changed --json",
+      reason: "changed files were detected; inspect grouped human and generated changes first",
+      confidence: "high",
+    });
     actions.push({
       command: "forge do verify --json",
       reason: "changed files were detected; use the guided verification path",
@@ -538,7 +681,60 @@ function nextActionsFromPhases(phases: DevConsolePhase[]): DevConsoleNextAction[
     });
   }
 
-  return uniqueActions(actions).slice(0, 12);
+  return uniqueActions(actions).slice(0, 12).map((action) => ({
+    ...action,
+    command: forgeCliCommandForWorkspace(workspaceRoot, action.command),
+  }));
+}
+
+function phaseDetails<T>(phases: DevConsolePhase[], name: DevConsolePhase["name"], key: string): T | undefined {
+  return phases.find((item) => item.name === name)?.details?.[key] as T | undefined;
+}
+
+function buildAgentContext(input: {
+  workspaceRoot: string;
+  phases: DevConsolePhase[];
+  diagnostics: Diagnostic[];
+  nextActions: DevConsoleNextAction[];
+}): DevConsoleAgentContext {
+  const generated = input.phases.find((item) => item.name === "generated");
+  const frontend = phaseDetails<FrontendSummary>(input.phases, "frontend", "summary");
+  const impact = phaseDetails<ImpactSummary>(input.phases, "impact", "summary");
+  const errorDiagnostics = input.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  const warningDiagnostics = input.diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+  const generatedChangedFiles = Number(generated?.details?.changed ?? 0);
+  const suggestedReadFiles = [
+    "AGENTS.md",
+    "src/forge/_generated/agentContract.json",
+    "src/forge/_generated/appMap.md",
+    "src/forge/_generated/runtimeRules.md",
+    "src/forge/_generated/operationPlaybooks.md",
+    ...(frontend?.present ? ["src/forge/_generated/frontendGraph.json"] : []),
+    ...input.diagnostics.flatMap((diagnostic) => diagnostic.docs ?? []),
+    ...input.diagnostics.flatMap((diagnostic) => diagnostic.file ? [diagnostic.file] : []),
+  ];
+  const fullCommands = forgeCliCommandsForWorkspace(input.workspaceRoot, [
+    "forge inspect all --full --json",
+    "forge changed --json",
+    "forge impact --changed --json",
+    "forge generate --json",
+  ]);
+  return {
+    safeToEdit: generated?.ok === true && errorDiagnostics.length === 0,
+    generatedFresh: generated?.ok === true,
+    generatedChanged: generatedChangedFiles > 0,
+    generatedChangedFiles,
+    frontendReady: frontend?.present ? frontend.bridgeFiles.length > 0 : false,
+    changedFiles: impact?.changedFiles ?? 0,
+    ...(impact?.changeSummary ? { changeSummary: impact.changeSummary } : {}),
+    ...(impact?.changeSummary ? { diffPlan: buildDiffPlanFromChangeSummary(impact.changeSummary) } : {}),
+    blockingIssues: errorDiagnostics.map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`).slice(0, 8),
+    recommendedReadFiles: [...new Set(suggestedReadFiles)].slice(0, 12),
+    recommendedCommands: input.nextActions.map((action) => action.command).slice(0, 8),
+    useFullCommands: warningDiagnostics.length > 0 || (impact?.hiddenChangedFiles ?? 0) > 0
+      ? fullCommands
+      : fullCommands.slice(0, 1),
+  };
 }
 
 export async function runDevConsoleCycle(options: DevConsoleOptions): Promise<DevConsoleCycle> {
@@ -549,7 +745,10 @@ export async function runDevConsoleCycle(options: DevConsoleOptions): Promise<De
   phases.push(generated);
   if (generated.ok) {
     phases.push(await runCheckPhase(workspaceRoot, options.strictSecrets ?? false));
-    phases.push(runFrontendPhase(workspaceRoot));
+    phases.push(runFrontendPhase(workspaceRoot, {
+      ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+      ...(options.webUrl ? { webUrl: options.webUrl } : {}),
+    }));
   } else {
     phases.push(
       skippedPhase(
@@ -573,13 +772,15 @@ export async function runDevConsoleCycle(options: DevConsoleOptions): Promise<De
 
   const diagnostics = phases.flatMap((item) => item.diagnostics);
   const ok = phases.every((item) => item.ok);
-  const nextActions = nextActionsFromPhases(phases);
+  const nextActions = nextActionsFromPhases(workspaceRoot, phases);
   const summary = buildDevSummary({
     workspaceRoot,
     ok,
     phases,
     diagnostics,
     nextActions,
+    ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+    ...(options.webUrl ? { webUrl: options.webUrl } : {}),
   });
   return {
     schemaVersion: "0.1.0",
@@ -603,6 +804,17 @@ export function formatDevConsoleHuman(cycle: DevConsoleCycle): string {
   lines.push(`Project: ${cycle.summary.project.root}`);
   lines.push(`API: ${cycle.summary.urls.api}`);
   lines.push(`Web: ${cycle.summary.urls.web ?? "none detected"}`);
+  lines.push(`Target preview: ${cycle.summary.preview.targetAppUrl}`);
+  lines.push(
+    `Generated: ${cycle.summary.generated.state}` +
+      (cycle.summary.generated.changedFiles > 0 ? ` (${cycle.summary.generated.changedFiles} changed)` : ""),
+  );
+  if (cycle.summary.agentContext.diffPlan) {
+    lines.push(`Diff focus: ${cycle.summary.agentContext.diffPlan.summary}`);
+  }
+  if (cycle.summary.preview.isStudioSelfPreview) {
+    lines.push("Preview warning: target preview points at the Studio URL");
+  }
   lines.push(
     `Frontend: ${cycle.summary.frontend.present ? cycle.summary.frontend.framework : "none"} ` +
       `(${cycle.summary.frontend.routes.length} routes, ${cycle.summary.frontend.bindings.length} bindings)`,

package/src/forge/dev-console/types.ts

@@ -1,5 +1,6 @@
 import type { Diagnostic } from "../compiler/types/diagnostic.ts";
 import type { ImpactRiskLevel } from "../impact/types.ts";
+import type { CategorizedFileSummary, DiffPlan } from "../workspace/change-summary.ts";
 
 export type DevConsolePhaseName =
   | "generated"
@@ -39,7 +40,16 @@ export interface DevConsoleSummary {
   urls: {
     api: string;
     web?: string;
+    suggestedPreview?: string;
   };
+  preview: {
+    studioUrl?: string;
+    targetAppUrl: string;
+    targetAppPort: number;
+    isStudioSelfPreview: boolean;
+    note: string;
+  };
+  generated: DevConsoleGeneratedSummary;
   frontend: FrontendSummary;
   capabilities: {
     covered: number;
@@ -47,6 +57,7 @@ export interface DevConsoleSummary {
     frontendOnly: number;
     warnings: number;
   };
+  agentContext: DevConsoleAgentContext;
   primaryAction?: DevConsoleNextAction;
 }
 
@@ -66,6 +77,8 @@ export interface DevConsoleOptions {
   mode: DevConsoleCycle["mode"];
   strictSecrets?: boolean;
   includeImpact?: boolean;
+  apiUrl?: string;
+  webUrl?: string;
 }
 
 export interface LastTestRunSummary {
@@ -82,9 +95,41 @@ export interface LastUiRunSummary {
 }
 
 export interface ImpactSummary {
-  changedFiles: string[];
+  changedFiles: number;
+  sampleChangedFiles: string[];
+  hiddenChangedFiles: number;
+  changeSummary: CategorizedFileSummary;
   risk: ImpactRiskLevel;
   recommendedChecks: string[];
+  fullCommand: string;
+}
+
+export interface DevConsoleGeneratedSummary {
+  ok: boolean;
+  state: "fresh" | "regenerated" | "stale-risk";
+  changedFiles: number;
+  sampleChanged: string[];
+  hiddenChanged: number;
+  message: string;
+  command: string;
+  checkCommand: string;
+}
+
+export type DevConsoleDiffPlan = DiffPlan;
+
+export interface DevConsoleAgentContext {
+  safeToEdit: boolean;
+  generatedFresh: boolean;
+  generatedChanged: boolean;
+  generatedChangedFiles: number;
+  frontendReady: boolean;
+  changedFiles: number;
+  changeSummary?: CategorizedFileSummary;
+  diffPlan?: DevConsoleDiffPlan;
+  blockingIssues: string[];
+  recommendedReadFiles: string[];
+  recommendedCommands: string[];
+  useFullCommands: string[];
 }
 
 export interface FrontendSummary {