@iloveagents/foundry-web-ui 0.1.0 → 0.1.2

package/src/lib/__tests__/ag-ui-adapter.test.ts

@@ -15,6 +15,14 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import type { RunnerEvent } from "@iloveagents/foundry-agent";
 
+const appStoreMock = vi.hoisted(() => ({
+  agentState: {
+    contextItems: [] as Array<Record<string, unknown>>,
+    navigation: { contextInstructions: null as string | null },
+  },
+  consumedMessageIds: [] as string[],
+}));
+
 const runMock = vi.fn();
 const runnerMock = vi.fn().mockImplementation(() => ({
   threadId: "thread-1",
@@ -46,8 +54,10 @@ vi.mock("../app-store.ts", () => ({
   useAppStore: {
     getState: () => ({
       markThreadActive: () => {},
-      getAgentState: () => ({ contextItems: [] }),
-      consumeContextForMessage: () => {},
+      getAgentState: () => appStoreMock.agentState,
+      consumeContextForMessage: (messageId: string) => {
+        appStoreMock.consumedMessageIds.push(messageId);
+      },
     }),
   },
 }));
@@ -66,7 +76,9 @@ import { AGUIAdapterSDK } from "../ag-ui-adapter.ts";
 
 function makeRunInput() {
   return {
-    messages: [{ id: "u-1", role: "user" as const, content: [{ type: "text" as const, text: "hi" }] }],
+    messages: [
+      { id: "u-1", role: "user" as const, content: [{ type: "text" as const, text: "hi" }] },
+    ],
     abortSignal: undefined as AbortSignal | undefined,
   };
 }
@@ -75,6 +87,11 @@ describe("AGUIAdapterSDK", () => {
   beforeEach(() => {
     runMock.mockReset();
     runnerMock.mockClear();
+    appStoreMock.agentState = {
+      contextItems: [],
+      navigation: { contextInstructions: null },
+    };
+    appStoreMock.consumedMessageIds = [];
   });
 
   it("yields a terminal complete after a text-only run", async () => {
@@ -174,6 +191,80 @@ describe("AGUIAdapterSDK", () => {
 
     expect(out[out.length - 1].status).toEqual({ type: "complete", reason: "stop" });
   });
+
+  it("forwards app context items through the native AG-UI context field", async () => {
+    appStoreMock.agentState = {
+      navigation: { contextInstructions: null },
+      contextItems: [
+        {
+          type: "ref",
+          refType: "block",
+          refId: "entity-1:block-2",
+          preview: "A selected table cell",
+          targetPath: "$.blocks[?(@.id=='block-2')].rows[0].cells[1]",
+          sourcePage: "/spaces/entity-1#block-block-2",
+        },
+      ],
+    };
+    runMock.mockImplementation(async function* (): AsyncGenerator<RunnerEvent> {});
+
+    const adapter = new AGUIAdapterSDK();
+    for await (const _ of adapter.run(makeRunInput())) {
+      // Drain the adapter.
+    }
+
+    expect(runMock).toHaveBeenCalledTimes(1);
+    expect(runMock.mock.calls[0][0].context).toEqual([
+      {
+        description:
+          "Selected block atom. Use targetPath as the exact edit target when the user asks to modify, rewrite, or transform selected content.",
+        value: JSON.stringify(appStoreMock.agentState.contextItems[0]),
+      },
+    ]);
+    expect(appStoreMock.consumedMessageIds).toEqual(["u-1"]);
+  });
+
+  it("describes typed JSON ref targets without losing the stable ref handle", async () => {
+    appStoreMock.agentState = {
+      navigation: { contextInstructions: null },
+      contextItems: [
+        {
+          type: "ref",
+          label: "Page Instructions · Test Page",
+          refType: "entity-field",
+          refId: "entity-1:instructions.agent_instructions",
+          preview: "Current: old\nProposed: new",
+          targetPath: "$.instructions.agent_instructions",
+          target: {
+            kind: "json-field",
+            path: "$.instructions.agent_instructions",
+            label: "Page Instructions",
+            scope: "entity-field",
+            containerId: "entity-1",
+            containerLabel: "Test Page",
+            currentValue: "old",
+            proposedValue: "new",
+            changeIds: ["change-1"],
+          },
+          sourcePage: "/spaces/entity-1",
+        },
+      ],
+    };
+    runMock.mockImplementation(async function* (): AsyncGenerator<RunnerEvent> {});
+
+    const adapter = new AGUIAdapterSDK();
+    for await (const _ of adapter.run(makeRunInput())) {
+      // Drain the adapter.
+    }
+
+    expect(runMock.mock.calls[0][0].context).toEqual([
+      {
+        description:
+          "Selected entity-field Page Instructions. Use targetPath as the exact JSON edit target when the user asks to modify, rewrite, or transform this reference.",
+        value: JSON.stringify(appStoreMock.agentState.contextItems[0]),
+      },
+    ]);
+  });
 });
 
 interface ChatModelRunResultLike {

package/src/lib/__tests__/app-store.test.ts

@@ -54,6 +54,27 @@ const refItem = (refId = "entity-1:block-1", preview = "Introduction") => ({
   persistence: "persistent" as const,
 });
 
+const scopedRefItem = (
+  selectionScope: "block" | "text" | "atom",
+  preview = "Introduction",
+  targetPath?: string,
+) => ({
+  type: "ref" as const,
+  label: preview,
+  payload: {
+    kind: "ref" as const,
+    refType: "block",
+    refId: "entity-1:block-1",
+    preview,
+    meta: {
+      selectionScope,
+      ...(targetPath ? { targetPath } : {}),
+    },
+  },
+  sourcePage: "/spaces/entity-1#block-block-1",
+  persistence: selectionScope === "block" ? ("persistent" as const) : ("ephemeral" as const),
+});
+
 describe("app-store", () => {
   beforeEach(reset);
 
@@ -108,6 +129,27 @@ describe("app-store", () => {
       expect(store().contextItems).toHaveLength(1);
     });
 
+    it("allows scoped refs for the same block alongside the durable block ref", () => {
+      store().addContextItem(scopedRefItem("block", "Whole block"));
+      store().addContextItem(scopedRefItem("text", "Specific phrase"));
+      store().addContextItem(
+        scopedRefItem("atom", "Table cell", "$.blocks[?(@.id=='block-1')].rows[0].cells[0]"),
+      );
+      expect(store().contextItems).toHaveLength(3);
+    });
+
+    it("deduplicates scoped refs by their actual scope key", () => {
+      store().addContextItem(scopedRefItem("text", "Specific phrase"));
+      store().addContextItem(scopedRefItem("text", "Specific phrase"));
+      store().addContextItem(
+        scopedRefItem("atom", "Table cell", "$.blocks[?(@.id=='block-1')].rows[0].cells[0]"),
+      );
+      store().addContextItem(
+        scopedRefItem("atom", "Updated table cell", "$.blocks[?(@.id=='block-1')].rows[0].cells[0]"),
+      );
+      expect(store().contextItems).toHaveLength(2);
+    });
+
     it("allows ref items with different refIds", () => {
       store().addContextItem(refItem("e1:b1"));
       store().addContextItem(refItem("e1:b2"));
@@ -297,6 +339,39 @@ describe("app-store", () => {
       expect(projection.navigation.groupMeta).toEqual({ orgId: "org-1" });
       expect(projection.navigation.group).toBe("Contracts");
     });
+
+    it("compacts reference target values within the documented context limit", () => {
+      const longValue = "x".repeat(2_001);
+
+      store().addContextItem({
+        type: "ref",
+        label: "Long field",
+        sourcePage: "/spaces/entity-1",
+        persistence: "ephemeral",
+        payload: {
+          kind: "ref",
+          refType: "entity-field",
+          refId: "entity-1",
+          target: {
+            path: "$.instructions.page",
+            label: "Page Instructions",
+            currentValue: longValue,
+            proposedValue: longValue,
+          },
+        },
+      });
+
+      const projection = store().getAgentState();
+      const target = projection.contextItems[0].target as {
+        currentValue: string;
+        proposedValue: string;
+      };
+
+      expect(target.currentValue).toHaveLength(2_000);
+      expect(target.currentValue.endsWith("...")).toBe(true);
+      expect(target.proposedValue).toHaveLength(2_000);
+      expect(target.proposedValue.endsWith("...")).toBe(true);
+    });
   });
 
   describe("resetAll", () => {

package/src/lib/__tests__/selection-context.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  registerSelectionContextResolver,
+  resolveSelectionContext,
+  type SelectionContextResolver,
+} from "../selection-context.ts";
+
+const unregisters: Array<() => void> = [];
+
+function register(resolver: SelectionContextResolver) {
+  const unregister = registerSelectionContextResolver(resolver);
+  unregisters.push(unregister);
+  return unregister;
+}
+
+function input(text = "selected text") {
+  const node = document.createElement("span");
+  const range = document.createRange();
+  range.selectNodeContents(node);
+  return {
+    text,
+    anchorNode: node,
+    focusNode: node,
+    range,
+    sourcePage: "Current page",
+  };
+}
+
+describe("selection-context", () => {
+  afterEach(() => {
+    for (const unregister of unregisters.splice(0)) unregister();
+    document.body.innerHTML = "";
+  });
+
+  it("falls back to a plain text selection context", () => {
+    const resolved = resolveSelectionContext(input("hello"));
+
+    expect(resolved.item).toMatchObject({
+      type: "selection",
+      label: "hello",
+      payload: { kind: "text", text: "hello" },
+      persistence: "ephemeral",
+    });
+    expect(resolved.supportsModify).toBeUndefined();
+  });
+
+  it("lets modules resolve richer selection context and opt into Modify", () => {
+    register({
+      id: "test-rich-selection",
+      resolve: (selection) => ({
+        item: {
+          type: "ref",
+          label: `Field · ${selection.text}`,
+          payload: {
+            kind: "ref",
+            refType: "block",
+            refId: "entity:block",
+            preview: selection.text,
+            meta: { selectionScope: "atom", targetPath: "$.blocks[0].field" },
+          },
+          sourcePage: "/spaces/entity#block-block",
+          persistence: "ephemeral",
+        },
+        supportsModify: true,
+      }),
+    });
+
+    const resolved = resolveSelectionContext(input("cell"));
+
+    expect(resolved.item).toMatchObject({
+      type: "ref",
+      label: "Field · cell",
+      payload: {
+        kind: "ref",
+        refType: "block",
+        refId: "entity:block",
+        meta: { targetPath: "$.blocks[0].field" },
+      },
+    });
+    expect(resolved.supportsModify).toBe(true);
+  });
+
+  it("uses resolver priority before falling through to lower priority resolvers", () => {
+    register({
+      id: "low",
+      priority: 1,
+      resolve: (selection) => ({
+        item: {
+          type: "selection",
+          label: `low ${selection.text}`,
+          payload: { kind: "text", text: selection.text },
+          sourcePage: selection.sourcePage,
+          persistence: "ephemeral",
+        },
+      }),
+    });
+    register({
+      id: "high",
+      priority: 100,
+      resolve: (selection) => ({
+        item: {
+          type: "selection",
+          label: `high ${selection.text}`,
+          payload: { kind: "text", text: selection.text },
+          sourcePage: selection.sourcePage,
+          persistence: "ephemeral",
+        },
+      }),
+    });
+
+    expect(resolveSelectionContext(input("x")).item.label).toBe("high x");
+  });
+});
+

package/src/lib/ag-ui-adapter.ts

@@ -24,14 +24,10 @@ import type {
   TextMessagePart,
   ToolCallMessagePart,
 } from "@assistant-ui/react";
-import type { Message as AGUIMessage } from "@ag-ui/core";
-import {
-  AGUIRunner,
-  clientToolRegistry,
-  streamingStatusStore,
-} from "@iloveagents/foundry-agent";
+import type { Context, Message as AGUIMessage } from "@ag-ui/core";
+import { AGUIRunner, clientToolRegistry, streamingStatusStore } from "@iloveagents/foundry-agent";
 import { tokenFetch } from "@iloveagents/foundry-agent/msal";
-import { useAppStore } from "./app-store.ts";
+import { useAppStore, type AgentStateProjection } from "./app-store.ts";
 import { useDevStore } from "./dev-store.ts";
 
 interface ToolCallSnapshot {
@@ -45,10 +41,7 @@ interface ToolCallSnapshot {
 export class AGUIAdapterSDK implements ChatModelAdapter {
   private readonly runner: AGUIRunner;
 
-  constructor(
-    url: string = "/api/agent",
-    options?: { threadId?: string; fetchFn?: typeof fetch },
-  ) {
+  constructor(url: string = "/api/agent", options?: { threadId?: string; fetchFn?: typeof fetch }) {
     this.runner = new AGUIRunner({
       url,
       threadId: options?.threadId,
@@ -71,6 +64,7 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
     // ephemeral context off the last user message.
     useAppStore.getState().markThreadActive();
     const appState = useAppStore.getState().getAgentState();
+    const context = buildAGUIContext(appState);
     const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
     if (lastUserMsg) {
       useAppStore.getState().consumeContextForMessage(lastUserMsg.id);
@@ -90,9 +84,7 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
      * generator returns. assistant-ui leaves the message stuck in the
      * loading state if the last yield's status is `running`.
      */
-    const buildResult = (
-      statusOverride?: ChatModelRunResult["status"],
-    ): ChatModelRunResult => {
+    const buildResult = (statusOverride?: ChatModelRunResult["status"]): ChatModelRunResult => {
       const content: (ToolCallMessagePart | TextMessagePart)[] = [];
 
       for (const [id, tc] of toolCalls) {
@@ -136,6 +128,7 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
       for await (const event of this.runner.run({
         messages: aguiMessages,
         state: appState as unknown as Record<string, unknown>,
+        context,
         registry: clientToolRegistry.getState(),
         abortSignal,
       })) {
@@ -263,6 +256,63 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
   }
 }
 
+function buildAGUIContext(appState: AgentStateProjection): Context[] {
+  return appState.contextItems.map((item, index) => ({
+    description: describeContextItem(item, index),
+    value: stringifyContextItem(item),
+  }));
+}
+
+function describeContextItem(item: Record<string, unknown>, index: number): string {
+  const type = typeof item.type === "string" ? item.type : "context";
+  const label = typeof item.label === "string" ? item.label : "";
+
+  if (type === "ref") {
+    const refType = typeof item.refType === "string" ? item.refType : "reference";
+    const target = isRecord(item.target) ? item.target : undefined;
+    const targetPath =
+      typeof item.targetPath === "string"
+        ? item.targetPath
+        : typeof target?.path === "string"
+          ? target.path
+          : undefined;
+    const targetLabel = typeof target?.label === "string" ? target.label : undefined;
+    const targetScope = typeof target?.scope === "string" ? target.scope : undefined;
+    if (targetPath) {
+      if (!targetLabel && !targetScope) {
+        return `Selected ${refType} atom. Use targetPath as the exact edit target when the user asks to modify, rewrite, or transform selected content.`;
+      }
+      const targetText = targetLabel || targetScope || "JSON atom";
+      return `Selected ${refType} ${targetText}. Use targetPath as the exact JSON edit target when the user asks to modify, rewrite, or transform this reference.`;
+    }
+    return `Selected ${refType} reference. Use refId as the edit target when the user asks to modify, rewrite, or transform selected content.`;
+  }
+
+  if (type === "selection") {
+    return "Selected text from the current UI. Use it as the focus when the user asks about, rewrites, or modifies selected content.";
+  }
+
+  if (type === "page") {
+    return `Pinned page context${label ? `: ${label}` : ""}.`;
+  }
+
+  return `Context item ${index + 1}${label ? `: ${label}` : ""}.`;
+}
+
+function stringifyContextItem(item: Record<string, unknown>): string {
+  try {
+    return JSON.stringify(item);
+  } catch {
+    const type = typeof item.type === "string" ? item.type : "context";
+    const label = typeof item.label === "string" ? item.label : "";
+    return JSON.stringify({ type, label });
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * Convert assistant-ui's `Message[]` into AG-UI's wire format.
  *

package/src/lib/app-store.ts

@@ -33,6 +33,25 @@ export interface ReferencePayload {
   refId: string;
   /** Optional display text (~100 chars) */
   preview?: string;
+  /**
+   * Optional exact JSON target inside the referenced domain object.
+   *
+   * This keeps the existing refType/refId contract stable for deep links
+   * while allowing feature modules to target one schema-declared field,
+   * table cell, JSON atom, or app-defined custom value precisely.
+   */
+  target?: {
+    kind?: string;
+    path?: string;
+    label?: string;
+    scope?: string;
+    containerId?: string;
+    containerLabel?: string;
+    currentValue?: unknown;
+    proposedValue?: unknown;
+    changeIds?: string[];
+    meta?: Record<string, unknown>;
+  };
   /** Domain-specific data the agent can use */
   meta?: Record<string, unknown>;
 }
@@ -82,6 +101,8 @@ export interface AgentStateProjection {
 
 const MAX_ITEMS = 10;
 const MAX_LABEL_LENGTH = 500;
+const MAX_CONTEXT_VALUE_LENGTH = 2_000;
+const TRUNCATION_SUFFIX = "...";
 
 const DEFAULT_NAV_CONTEXT: NavContext = {
   group: null,
@@ -93,6 +114,43 @@ const DEFAULT_NAV_CONTEXT: NavContext = {
   contextInstructions: null,
 };
 
+function refDedupKey(payload: ReferencePayload): string {
+  const selectionScope =
+    typeof payload.meta?.selectionScope === "string" ? payload.meta.selectionScope : "block";
+  const targetPath =
+    typeof payload.target?.path === "string"
+      ? payload.target.path
+      : typeof payload.meta?.targetPath === "string"
+        ? payload.meta.targetPath
+        : undefined;
+
+  if (selectionScope === "atom" && targetPath) {
+    return `${payload.refType}:${payload.refId}:atom:${targetPath}`;
+  }
+  if (selectionScope === "text") {
+    return `${payload.refType}:${payload.refId}:text:${payload.preview ?? ""}`;
+  }
+  return `${payload.refType}:${payload.refId}:block`;
+}
+
+function compactContextValue(value: unknown): unknown {
+  if (typeof value === "string" && value.length > MAX_CONTEXT_VALUE_LENGTH) {
+    return `${value.slice(0, MAX_CONTEXT_VALUE_LENGTH - TRUNCATION_SUFFIX.length)}${TRUNCATION_SUFFIX}`;
+  }
+  return value;
+}
+
+function compactReferenceTarget(
+  target: ReferencePayload["target"],
+): ReferencePayload["target"] {
+  if (!target) return undefined;
+  return {
+    ...target,
+    currentValue: compactContextValue(target.currentValue),
+    proposedValue: compactContextValue(target.proposedValue),
+  };
+}
+
 interface AppState {
   // Thread state
   threadActive: boolean;
@@ -188,7 +246,7 @@ export const useAppStore = create<AppState>((set, get) => ({
       if (item.type === "ref" && existing.type === "ref") {
         const a = item.payload as ReferencePayload;
         const b = existing.payload as ReferencePayload;
-        return a.refId === b.refId;
+        return refDedupKey(a) === refDedupKey(b);
       }
       // selection / note: dedup by label + sourcePage
       return existing.label === item.label && existing.sourcePage === item.sourcePage;
@@ -267,9 +325,18 @@ export const useAppStore = create<AppState>((set, get) => ({
           case "ref":
             return {
               type,
+              label: label.slice(0, 200),
               refType: payload.refType,
               refId: payload.refId,
               preview: payload.preview?.slice(0, 100),
+              target: compactReferenceTarget(payload.target),
+              meta: payload.meta,
+              targetPath:
+                typeof payload.target?.path === "string"
+                  ? payload.target.path
+                  : typeof payload.meta?.targetPath === "string"
+                    ? payload.meta.targetPath
+                    : undefined,
               sourcePage,
             };
           default:

package/src/lib/composer-submit-store.ts

@@ -0,0 +1,32 @@
+import { create } from "zustand";
+
+interface PendingComposerSubmit {
+  id: number;
+  text: string;
+}
+
+interface ComposerSubmitState {
+  pending: PendingComposerSubmit | null;
+  submit: (text: string) => void;
+  consume: (id: number) => void;
+}
+
+let nextSubmitId = 1;
+
+export const useComposerSubmitStore = create<ComposerSubmitState>((set) => ({
+  pending: null,
+  submit: (text) => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    set({ pending: { id: nextSubmitId++, text: trimmed } });
+  },
+  consume: (id) =>
+    set((state) => ({
+      pending: state.pending?.id === id ? null : state.pending,
+    })),
+}));
+
+export function submitComposerText(text: string): void {
+  useComposerSubmitStore.getState().submit(text);
+}
+

package/src/lib/nav-config.ts

@@ -55,6 +55,11 @@ export interface NavItem {
   dimmed?: boolean;
   /** Small text badge after the label (e.g., "managed", "locked"). */
   badge?: string;
+  /** Small status dot after the label for quiet state hints such as pending review impact. */
+  statusDot?: {
+    tone?: "neutral" | "info" | "low-impact" | "medium-impact" | "high-impact" | "pending";
+    label?: string;
+  };
   /** Page description sent to the agent for context */
   description?: string;
   /** Arbitrary metadata sent to the agent (e.g., workspace IDs, entity types) */

package/src/lib/selection-context.ts

@@ -0,0 +1,65 @@
+import type { ContextItem } from "./app-store.ts";
+
+export type SelectionContextItem = Omit<ContextItem, "id" | "createdAt">;
+
+export interface SelectionContextInput {
+  text: string;
+  anchorNode: Node;
+  focusNode: Node | null;
+  range: Range;
+  sourcePage: string;
+}
+
+export interface SelectionContextResult {
+  item: SelectionContextItem;
+  supportsModify?: boolean;
+  formatModifyPrompt?: (prompt: string) => string;
+}
+
+export interface SelectionContextResolver {
+  id: string;
+  priority?: number;
+  resolve: (input: SelectionContextInput) => SelectionContextResult | null;
+}
+
+const resolvers = new Map<string, SelectionContextResolver>();
+
+function defaultSelectionContext(input: SelectionContextInput): SelectionContextResult {
+  return {
+    item: {
+      type: "selection",
+      label: input.text,
+      payload: { kind: "text", text: input.text },
+      sourcePage: input.sourcePage,
+      persistence: "ephemeral",
+    },
+  };
+}
+
+export function registerSelectionContextResolver(
+  resolver: SelectionContextResolver,
+): () => void {
+  resolvers.set(resolver.id, resolver);
+  return () => {
+    if (resolvers.get(resolver.id) === resolver) {
+      resolvers.delete(resolver.id);
+    }
+  };
+}
+
+export function resolveSelectionContext(input: SelectionContextInput): SelectionContextResult {
+  const sortedResolvers = [...resolvers.values()].sort(
+    (a, b) => (b.priority ?? 0) - (a.priority ?? 0),
+  );
+
+  for (const resolver of sortedResolvers) {
+    try {
+      const resolved = resolver.resolve(input);
+      if (resolved) return resolved;
+    } catch {
+      // A module resolver must never break the generic selection flow.
+    }
+  }
+
+  return defaultSelectionContext(input);
+}

package/src/lib/theme-runtime.ts

@@ -595,8 +595,8 @@ export const FOUNDRY_VIOLET_THEME: ThemeDefinition = {
     radius: "0.875rem",
   },
   branding: {
-    appName: "LastSpace.ai",
-    appTitle: "LastSpace.ai",
+    appName: "eomi",
+    appTitle: "eomi",
   },
 };