@fluidframework/tree-agent 2.70.0-360753 → 2.70.0-361092

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree-agent",
-  "version": "2.70.0-360753",
+  "version": "2.70.0-361092",
   "description": "Experimental package to simplify integrating AI into Fluid-based applications",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -70,24 +70,24 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
-    "@fluidframework/core-utils": "2.70.0-360753",
-    "@fluidframework/runtime-utils": "2.70.0-360753",
-    "@fluidframework/telemetry-utils": "2.70.0-360753",
-    "@fluidframework/tree": "2.70.0-360753",
+    "@fluidframework/core-utils": "2.70.0-361092",
+    "@fluidframework/runtime-utils": "2.70.0-361092",
+    "@fluidframework/telemetry-utils": "2.70.0-361092",
+    "@fluidframework/tree": "2.70.0-361092",
     "uuid": "^11.1.0",
     "zod": "^3.25.32"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "2.70.0-360753",
+    "@fluid-internal/mocha-test-setup": "2.70.0-361092",
     "@fluid-tools/build-cli": "^0.58.3",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.58.3",
-    "@fluidframework/eslint-config-fluid": "^6.0.0",
-    "@fluidframework/id-compressor": "2.70.0-360753",
-    "@fluidframework/runtime-utils": "2.70.0-360753",
-    "@fluidframework/test-runtime-utils": "2.70.0-360753",
+    "@fluidframework/eslint-config-fluid": "^6.1.0",
+    "@fluidframework/id-compressor": "2.70.0-361092",
+    "@fluidframework/runtime-utils": "2.70.0-361092",
+    "@fluidframework/test-runtime-utils": "2.70.0-361092",
     "@langchain/anthropic": "^0.3.24",
     "@langchain/core": "^0.3.78",
     "@langchain/google-genai": "^0.2.16",
@@ -100,8 +100,8 @@
     "concurrently": "^8.2.1",
     "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
-    "eslint": "~8.55.0",
-    "eslint-config-prettier": "~9.0.0",
+    "eslint": "~8.57.1",
+    "eslint-config-prettier": "~10.1.8",
     "mocha": "^10.8.2",
     "mocha-multi-reporters": "^1.5.1",
     "prettier": "~3.0.3",

package/src/agent.ts

@@ -24,6 +24,7 @@ import type {
 	Logger,
 	SynchronousEditor,
 	AsynchronousEditor,
+	Context,
 } from "./api.js";
 import { getPrompt, stringifyTree } from "./prompt.js";
 import { Subtree } from "./subtree.js";
@@ -248,25 +249,25 @@ export const defaultEditor: AsynchronousEditor = async (context, code) => {
 };
 
 /**
- * Binds the given {@link SynchronousEditor | editor} to the given view or tree.
+ * Binds the given {@link AsynchronousEditor | editor} to the given view or tree.
  * @returns A function that takes a string of JavaScript code and executes it on the given view or tree using the given editor function.
  * @remarks This is useful for testing/debugging code execution without needing to set up a full {@link SharedTreeSemanticAgent | agent}.
  * @alpha
  */
 export function bindEditorImpl<TSchema extends ImplicitFieldSchema>(
 	tree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode),
-	editor: SynchronousEditor,
-): (code: string) => void;
+	editor: AsynchronousEditor,
+): (code: string) => Promise<void>;
 /**
- * Binds the given {@link AsynchronousEditor | editor} to the given view or tree.
+ * Binds the given {@link SynchronousEditor | editor} to the given view or tree.
  * @returns A function that takes a string of JavaScript code and executes it on the given view or tree using the given editor function.
  * @remarks This is useful for testing/debugging code execution without needing to set up a full {@link SharedTreeSemanticAgent | agent}.
  * @alpha
  */
 export function bindEditorImpl<TSchema extends ImplicitFieldSchema>(
 	tree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode),
-	editor: AsynchronousEditor,
-): (code: string) => Promise<void>;
+	editor: SynchronousEditor,
+): (code: string) => void;
 /**
  * Binds the given {@link SynchronousEditor | editor} or {@link AsynchronousEditor | editor} to the given view or tree.
  * @returns A function that takes a string of JavaScript code and executes it on the given view or tree using the given editor function.
@@ -296,9 +297,11 @@ function bindEditorToSubtree<TSchema extends ImplicitFieldSchema>(
 ): (code: string) => void | Promise<void> {
 	// Stick the tree schema constructors on an object passed to the function so that the LLM can create new nodes.
 	const create: Record<string, (input: FactoryContentObject) => TreeNode> = {};
+	const is: Record<string, <T extends TreeNode>(input: unknown) => input is T> = {};
 	for (const schema of findNamedSchemas(tree.schema)) {
 		const name = getFriendlyName(schema);
 		create[name] = (input: FactoryContentObject) => constructTreeNode(schema, input);
+		is[name] = <T extends TreeNode>(input: unknown): input is T => Tree.is(input, schema);
 	}
 
 	const context = {
@@ -309,7 +312,10 @@ function bindEditorToSubtree<TSchema extends ImplicitFieldSchema>(
 			tree.field = value;
 		},
 		create,
-	};
+		is,
+		parent: (child: TreeNode): TreeNode | undefined => Tree.parent(child),
+		key: (child: TreeNode): string | number => Tree.key(child),
+	} satisfies Context<TSchema>;
 
 	// eslint-disable-next-line @typescript-eslint/promise-function-async
 	return (code: string) => executeEdit(context, code);

package/src/api.ts

@@ -22,6 +22,71 @@ export interface Logger {
 	log(message: string): void;
 }
 
+/**
+ * The context object available to generated code when editing a tree.
+ * @remarks This object is provided to JavaScript code executed by the {@link SynchronousEditor | editor} as a variable named `context`.
+ * It contains the current state of the tree and utilities for creating and inspecting tree nodes.
+ * @alpha
+ */
+export interface Context<TSchema extends ImplicitFieldSchema> {
+	/**
+	 * The root of the tree that can be read or modified.
+	 * @remarks
+	 * You can read properties and navigate through the tree starting from this root.
+	 * You can also assign a new value to this property to replace the entire tree, as long as the new value is one of the types allowed at the root.
+	 *
+	 * Example: Read the current root with `const currentRoot = context.root;`
+	 *
+	 * Example: Replace the entire root with `context.root = context.create.MyRootType({ });`
+	 */
+	root: ReadableField<TSchema>;
+
+	/**
+	 * A collection of builder functions for creating new tree nodes.
+	 * @remarks
+	 * Each property on this object is named after a type in the tree schema.
+	 * Call the corresponding function to create a new node of that type.
+	 * Always use these builder functions when creating new nodes rather than plain JavaScript objects.
+	 *
+	 * Example: Create a new Person node with `context.create.Person({ name: "Alice", age: 30 })`
+	 *
+	 * Example: Create a new Task node with `context.create.Task({ title: "Buy groceries", completed: false })`
+	 */
+	create: Record<string, (input: FactoryContentObject) => TreeNode>;
+
+	/**
+	 * A collection of type-checking functions for tree nodes.
+	 * @remarks
+	 * Each property on this object is named after a type in the tree schema.
+	 * Call the corresponding function to check if a node is of that specific type.
+	 * This is useful when working with nodes that could be one of multiple types.
+	 *
+	 * Example: Check if a node is a Person with `if (context.is.Person(node)) { console.log(node.name); }`
+	 */
+	is: Record<string, <T extends TreeNode>(input: T) => input is T>;
+
+	/**
+	 * Returns the parent node of the given child node.
+	 * @param child - The node whose parent you want to find.
+	 * @returns The parent node, or `undefined` if the node is the root or is not in the tree.
+	 * @remarks
+	 * Example: Get the parent with `const parent = context.parent(childNode);`
+	 */
+	parent(child: TreeNode): TreeNode | undefined;
+
+	/**
+	 * Returns the key or index of the given node within its parent.
+	 * @param child - The node whose key you want to find.
+	 * @returns A string key if the node is in an object or map, or a numeric index if the node is in an array.
+	 * @remarks
+	 * For a node in an object, this might return a string like "firstName".
+	 * For a node in an array, this might return a number like 0, 1, 2, etc.
+	 *
+	 * Example: `const key = context.key(childNode);`
+	 */
+	key(child: TreeNode): string | number;
+}
+
 /**
  * A synchronous function that executes a string of JavaScript code to perform an edit within a {@link SharedTreeSemanticAgent}.
  * @param context - An object that must be provided to the generated code as a variable named "context" in its top-level scope.

package/src/prompt.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { oob } from "@fluidframework/core-utils/internal";
 import { NodeKind, Tree, TreeNode } from "@fluidframework/tree";
 import type { ImplicitFieldSchema, TreeMapNode } from "@fluidframework/tree";
 import type { ReadableField } from "@fluidframework/tree/alpha";
@@ -34,10 +35,20 @@ export function getPrompt<TRoot extends ImplicitFieldSchema>(args: {
 	const mapInterfaceName = "TreeMap";
 	const simpleSchema = getSimpleSchema(schema);
 	// Inspect the schema to determine what kinds of nodes are possible - this will affect how much information we need to include in the prompt.
+	const rootTypes = [...normalizeFieldSchema(schema).allowedTypeSet];
+	const rootTypeUnion = `${rootTypes.map((t) => getFriendlyName(t)).join(" | ")}`;
+	let nodeTypeUnion: string | undefined;
 	let hasArrays = false;
 	let hasMaps = false;
 	let exampleObjectName: string | undefined;
 	for (const [definition, nodeSchema] of simpleSchema.definitions) {
+		if (nodeSchema.kind !== NodeKind.Leaf) {
+			nodeTypeUnion =
+				nodeTypeUnion === undefined
+					? unqualifySchema(definition)
+					: `${nodeTypeUnion} | ${unqualifySchema(definition)}`;
+		}
+
 		switch (nodeSchema.kind) {
 			case NodeKind.Array: {
 				hasArrays = true;
@@ -68,24 +79,81 @@ export function getPrompt<TRoot extends ImplicitFieldSchema>(args: {
 	const stringified = stringifyTree(field);
 	const details: SchemaDetails = { hasHelperMethods: false };
 	const typescriptSchemaTypes = getZodSchemaAsTypeScript(domainTypes, details);
-	const helperMethodExplanation = details.hasHelperMethods
-		? `Manipulating the data using the APIs described below is allowed, but when possible ALWAYS prefer to use any application helper methods exposed on the schema TypeScript types if the goal can be accomplished that way.
-It will often not be possible to fully accomplish the goal using those helpers. When this is the case, mutate the objects as normal, taking into account the following guidance.`
-		: "";
 
-	const builderExplanation =
+	const create =
+		exampleObjectName === undefined
+			? ""
+			: `\n	/**
+	 * A collection of builder functions for creating new tree nodes.
+	 * @remarks
+	 * Each property on this object is named after a type in the tree schema.
+	 * Call the corresponding function to create a new node of that type.
+	 * Always use these builder functions when creating new nodes rather than plain JavaScript objects.
+	 *
+	 * For example:
+	 *
+	 * \`\`\`javascript
+	 * // This creates a new ${exampleObjectName} object:
+	 * const ${communize(exampleObjectName)} = context.create.${exampleObjectName}({ ...properties });
+	 * // Don't do this:
+	 * // const ${communize(exampleObjectName)} = { ...properties };
+	 * \`\`\`
+	 */
+	create: Record<string, <T extends TreeData>(input: T) => T>;\n`;
+
+	const isDocs =
 		exampleObjectName === undefined
 			? ""
-			: `When constructing new objects, you should wrap them in the appropriate builder function rather than simply making a javascript object.
-The builders are available on the \`create\` property on the context object and are named according to the type that they create.
-For example:
+			: `\n	/**
+	 * A collection of type-guard functions for data in the tree.
+	 * @remarks
+	 * Each property on this object is named after a type in the tree schema.
+	 * Call the corresponding function to check if a node is of that specific type.
+	 * This is useful when working with nodes that could be one of multiple types.
+	 *
+	 * ${`Example: Check if a node is a ${exampleObjectName} with \`if (context.is.${exampleObjectName}(node)) {}\``}
+	 */
+	is: Record<string, <T extends TreeData>(input: unknown) => input is T>;\n`;
 
-\`\`\`javascript
-// This creates a new ${exampleObjectName} object:
-const ${communize(exampleObjectName)} = context.create.${exampleObjectName}({ /* ...properties... */ });
-// Don't do this:
-// const ${communize(exampleObjectName)} = { /* ...properties... */ };
-\`\`\`\n\n`;
+	const context = `\`\`\`typescript
+	${nodeTypeUnion === undefined ? "" : `type TreeData = ${nodeTypeUnion};\n\n`}	/**
+	 * An object available to generated code which provides read and write access to the tree as well as utilities for creating and inspecting data in the tree.
+	 * @remarks This object is available as a variable named \`context\` in the scope of the generated JavaScript snippet.
+	 */
+	interface Context<TSchema extends ImplicitFieldSchema> {
+	/**
+	 * The root of the tree that can be read or mutated.
+	 * @remarks
+	 * You can read properties and navigate through the tree starting from this root.
+	 * You can also assign a new value to this property to replace the entire tree, as long as the new value is one of the types allowed at the root.
+	 *
+	 * Example: Read the current root with \`const currentRoot = context.root;\`
+	 *${rootTypes.length > 0 ? ` Example: Replace the entire root with \`context.root = context.create.${getFriendlyName(rootTypes[0] ?? oob())}({ });\`\n	 *` : ""}/
+	root: ReadableField<TSchema>;
+	${create}
+	${isDocs}
+	/**
+	 * Returns the parent object/array/map of the given object/array/map, if there is one.
+	 * @returns The parent node, or \`undefined\` if the node is the root or is not in the tree.
+	 * @remarks
+	 * Example: Get the parent with \`const parent = context.parent(child);\`
+	 */
+	parent(child: TreeData): TreeData | undefined;
+
+	/**
+	 * Returns the property key or index of the given object/array/map within its parent.
+	 * @returns A string key if the child is in an object or map, or a numeric index if the child is in an array.
+	 *
+	 * Example: \`const key = context.key(child);\`
+	 */
+	key(child: TreeData): string | number;
+}
+\`\`\``;
+
+	const helperMethodExplanation = details.hasHelperMethods
+		? `Manipulating the data using the APIs described below is allowed, but when possible ALWAYS prefer to use any application helper methods exposed on the schema TypeScript types if the goal can be accomplished that way.
+It will often not be possible to fully accomplish the goal using those helpers. When this is the case, mutate the objects as normal, taking into account the following guidance.`
+		: "";
 
 	const reinsertionExplanation = `Once non-primitive data has been removed from the tree (e.g. replaced via assignment, or removed from an array), that data cannot be re-inserted into the tree.
 Instead, it must be deep cloned and recreated.
@@ -160,7 +228,6 @@ ${getTreeMapNodeDocumentation(mapInterfaceName)}
 
 `;
 
-	const rootTypes = normalizeFieldSchema(schema).allowedTypeSet;
 	const editing = `If the user asks you to edit the tree, you should author a snippet of JavaScript code to accomplish the user-specified goal, following the instructions for editing detailed below.
 You must use the "${editToolName}" tool to run the generated code.
 After editing the tree, review the latest state of the tree to see if it satisfies the user's request.
@@ -173,14 +240,18 @@ If the user asks you to edit the document, you will write a snippet of JavaScrip
 The snippet may be synchronous or asynchronous (i.e. it may \`await\` functions if necessary).
 The snippet has a \`context\` variable in its scope.
 This \`context\` variable holds the current state of the tree in the \`root\` property.
-You may mutate any part of the root tree as necessary, taking into account the caveats around${hasArrays ? ` arrays${hasMaps ? " and" : ""}` : ""}${hasMaps ? " maps" : ""} detailed below.
-You may also set the \`root\` property of the context to be an entirely new value as long as it is one of the types allowed at the root of the tree (\`${Array.from(rootTypes.values(), (t) => getFriendlyName(t)).join(" | ")}\`).
+You may mutate any part of this tree as necessary, taking into account the caveats around${hasArrays ? ` arrays${hasMaps ? " and" : ""}` : ""}${hasMaps ? " maps" : ""} detailed below.
+You may also set the \`root\` property of the context to be an entirely new value as long as it is one of the types allowed at the root of the tree (\`${rootTypeUnion}\`).
+You should also use the \`context\` object to create new data to insert into the tree, using the builder functions available on the \`create\` property.
+There are other additional helper functions available on the \`context\` object to help you analyze the tree.
+Here is the definition of the \`Context\` interface:
+${context}
 ${helperMethodExplanation}
 ${hasArrays ? arrayEditing : ""}${hasMaps ? mapEditing : ""}#### Additional Notes
 
 Before outputting the edit function, you should check that it is valid according to both the application tree's schema and any restrictions of the editing APIs described above.
 
-${builderExplanation}${reinsertionExplanation}
+${reinsertionExplanation}
 
 Finally, double check that the edits would accomplish the user's request (if it is possible).