feat: add renderEntityContext for semi-structured LLM prompt text

Author: MaxLinCode

packages/core/src/entity-context.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   buildEntityContext,
+  renderEntityContext,
   type ConversationEntity,
   type Task,
 } from "./index";
@@ -200,4 +201,37 @@ describe("entity context", () => {
       prompt: "What time should I schedule it?",
     });
   });
+
+  it("renders deterministic prompt text with explicit empty sections", () => {
+    const rendered = renderEntityContext({
+      knownEntities: [
+        {
+          id: "task-1",
+          label: "Gym session",
+          expectedType: "task",
+          state: "scheduled",
+        },
+      ],
+      focusedEntityId: "task-1",
+      activeProposal: null,
+      openClarification: null,
+    });
+
+    expect(rendered).toBe(
+      'Known entities:\n- "Gym session" (task, scheduled) [id: task-1]\n\nCurrently focused: "Gym session" [id: task-1]\n\nNo active proposal.\n\nNo open clarification.',
+    );
+  });
+
+  it("renders an explicit no-known-entities line when the context is empty", () => {
+    expect(
+      renderEntityContext({
+        knownEntities: [],
+        focusedEntityId: null,
+        activeProposal: null,
+        openClarification: null,
+      }),
+    ).toBe(
+      "Known entities:\nNo known entities.\n\nNo focused entity.\n\nNo active proposal.\n\nNo open clarification.",
+    );
+  });
 });

packages/core/src/entity-context.ts

@@ -170,3 +170,59 @@ export function buildEntityContext(
     openClarification,
   };
 }
+
+export function renderEntityContext(context: EntityContext): string {
+  const lines = ["Known entities:"];
+
+  if (context.knownEntities.length === 0) {
+    lines.push("No known entities.");
+  } else {
+    for (const entity of context.knownEntities) {
+      lines.push(
+        `- "${entity.label}" (${entity.expectedType}, ${entity.state}) [id: ${entity.id}]`,
+      );
+    }
+  }
+
+  lines.push("");
+
+  if (context.focusedEntityId) {
+    const focusedEntity = context.knownEntities.find(
+      (entity) => entity.id === context.focusedEntityId,
+    );
+    lines.push(
+      focusedEntity
+        ? `Currently focused: "${focusedEntity.label}" [id: ${focusedEntity.id}]`
+        : "No focused entity.",
+    );
+  } else {
+    lines.push("No focused entity.");
+  }
+
+  lines.push("");
+
+  if (context.activeProposal) {
+    const missingFields =
+      context.activeProposal.missingFields &&
+      context.activeProposal.missingFields.length > 0
+        ? ` - still needs: ${context.activeProposal.missingFields.join(", ")}`
+        : "";
+    lines.push(
+      `Active proposal: "${context.activeProposal.summary}"${missingFields} [id: ${context.activeProposal.id}]`,
+    );
+  } else {
+    lines.push("No active proposal.");
+  }
+
+  lines.push("");
+
+  if (context.openClarification) {
+    lines.push(
+      `Open clarification: "${context.openClarification.prompt}" [id: ${context.openClarification.id}]`,
+    );
+  } else {
+    lines.push("No open clarification.");
+  }
+
+  return lines.join("\n");
+}