@fluidframework/tree-agent 2.63.0-359286 → 2.63.0-359734

package/src/prompt.ts

@@ -25,11 +25,10 @@ import {
  */
 export function getPrompt<TRoot extends ImplicitFieldSchema>(args: {
 	subtree: Subtree<TRoot>;
-	editToolName?: string;
-	editFunctionName?: string;
+	editToolName: string | undefined;
 	domainHints?: string;
 }): string {
-	const { subtree, editToolName, editFunctionName, domainHints } = args;
+	const { subtree, editToolName, domainHints } = args;
 	const { field, schema } = subtree;
 	const arrayInterfaceName = "TreeArray";
 	const mapInterfaceName = "TreeMap";
@@ -70,7 +69,7 @@ export function getPrompt<TRoot extends ImplicitFieldSchema>(args: {
 	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 the application helper methods exposed on the schema TypeScript types if the goal can be accomplished that way.
+		? `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.`
 		: "";
 
@@ -78,16 +77,14 @@ It will often not be possible to fully accomplish the goal using those helpers.
 		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 first argument of the \`${editFunctionName}\` function and are named according to the type that they create.
+The builders are available on the \`create\` property on the context object and are named according to the type that they create.
 For example:
 
 \`\`\`javascript
-function ${editFunctionName}({ root, create }) {
-	// This creates a new ${exampleObjectName} object:
-	const ${communize(exampleObjectName)} = create.${exampleObjectName}({ /* ...properties... */ });
-	// Don't do this:
-	// const ${communize(exampleObjectName)} = { /* ...properties... */ };
-}
+// This creates a new ${exampleObjectName} object:
+const ${communize(exampleObjectName)} = context.create.${exampleObjectName}({ /* ...properties... */ });
+// Don't do this:
+// const ${communize(exampleObjectName)} = { /* ...properties... */ };
 \`\`\`\n\n`;
 
 	const arrayEditing = `#### Editing Arrays
@@ -121,26 +118,25 @@ ${getTreeMapNodeDocumentation(mapInterfaceName)}
 `;
 
 	const rootTypes = normalizeFieldSchema(schema).allowedTypeSet;
-	const editing = `If the user asks you to edit the tree, you should author a JavaScript function to accomplish the user-specified goal, following the instructions for editing detailed below.
-${editToolName === undefined ? "Use an applicable tool to perform the edit (if one is available)." : `You must use the "${editToolName}" tool to perform the edit.`}
+	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.
 If it does not, or if you receive an error, you may try again with a different approach.
 Once the tree is in the desired state, you should inform the user that the request has been completed.
 
 ### Editing
 
-If the user asks you to edit the document, you will write a JavaScript function that mutates the data in-place to achieve the user's goal.
-The function must be named "${editFunctionName}".
-It may be synchronous or asynchronous.
-The ${editFunctionName} function must have a first parameter which has a \`root\` property.
-This \`root\` property holds the current state of the tree as shown above.
-You may mutate any part of the tree as necessary, taking into account the caveats around arrays and maps detailed below.
-You may also set the \`root\` property 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(" | ")}\`).
+If the user asks you to edit the document, you will write a snippet of JavaScript code that mutates the data in-place to achieve the user's goal.
+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(" | ")}\`).
 ${helperMethodExplanation}
 
 ${hasArrays ? arrayEditing : ""}${hasMaps ? mapEditing : ""}#### Additional Notes
 
-Before outputting the ${editFunctionName} 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.
+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.
 
 Once 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.
 
@@ -158,14 +154,14 @@ ${typescriptSchemaTypes}
 If the user asks you a question about the tree, you should inspect the state of the tree and answer the question.
 When answering such a question, DO NOT answer with information that is not part of the document unless requested to do so.
 
-${editFunctionName === undefined ? "" : editing}### Application data
+${editToolName === undefined ? "" : editing}### Application data
 
 ${
 	domainHints === undefined
 		? ""
 		: `\nThe application supplied the following additional instructions: ${domainHints}`
 }
-The current state of the application tree (a \`${field === undefined ? "undefined" : getFriendlyName(Tree.schema(field))}\`) is:
+The current state of \`context.root\` (a \`${field === undefined ? "undefined" : getFriendlyName(Tree.schema(field))}\`) is:
 
 \`\`\`JSON
 ${stringified}

package/src/ses.ts

@@ -0,0 +1,73 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { CompartmentOptions, LockdownOptions } from "ses";
+
+import type { SemanticAgentOptions } from "./api.js";
+import { toErrorString } from "./utils.js";
+
+const lockdownSymbol = Symbol.for("tree-agent.ses.locked");
+
+/**
+ * Create an implementation of {@link SemanticAgentOptions.executeEdit} that uses the SES library to run the provided code in a secure environment.
+ * @param createCompartment - This function can be used to optionally configure the SES Compartment used to execute the code.
+ * The provided globals must be included in the compartment's globals and must not conflict with any additional globals passed in.
+ * @param lockdownOptions - Optional configuration passed to the SES `lockdown` function.
+ * @returns A function that can be used as the {@link SemanticAgentOptions.executeEdit | executeEdit} callback.
+ * @remarks This function will both import the SES library and call its `lockdown` function the first time it is called.
+ * Therefore, this function should be called only once, early in an application's lifetime.
+ * @alpha
+ */
+export async function createSesEditEvaluator(options?: {
+	compartmentOptions?: CompartmentOptions;
+	lockdownOptions?: LockdownOptions;
+}): Promise<SemanticAgentOptions["executeEdit"]> {
+	const optionsGlobals: Map<string, unknown> =
+		options?.compartmentOptions?.globals ?? new Map<string, unknown>();
+	if (optionsGlobals.has("context") === true) {
+		throw new Error(
+			"The 'context' global is reserved and cannot be overridden in the compartment options.",
+		);
+	}
+
+	// Importing 'ses' has side effects, so we do it lazily to avoid impacting environments that don't use this evaluator.
+	await import("ses");
+
+	if (!(lockdownSymbol in globalThis)) {
+		try {
+			lockdown(options?.lockdownOptions);
+			Object.defineProperty(globalThis, lockdownSymbol, {
+				value: true,
+				writable: false,
+				configurable: false,
+				enumerable: false,
+			});
+		} catch (error: unknown) {
+			if (toErrorString(error).includes("SES_ALREADY_LOCKED_DOWN")) {
+				Object.defineProperty(globalThis, lockdownSymbol, {
+					value: true,
+					writable: false,
+					configurable: false,
+					enumerable: false,
+				});
+			} else {
+				throw error;
+			}
+		}
+	}
+
+	return async (context: Record<string, unknown>, code: string) => {
+		const compartmentOptions = {
+			...options?.compartmentOptions,
+			globals: {
+				...Object.fromEntries(optionsGlobals),
+				context,
+			},
+		};
+
+		const compartment = new Compartment({ ...compartmentOptions, __options__: true });
+		await compartment.evaluate(code);
+	};
+}

package/src/utils.ts

@@ -619,3 +619,17 @@ export function findNamedSchemas(
 export function communize(str: string): string {
 	return str.charAt(0).toLowerCase() + str.slice(1);
 }
+
+/**
+ * Stringify an unknown error value
+ */
+export function toErrorString(error: unknown): string {
+	if (error instanceof Error) {
+		return error.message;
+	}
+	try {
+		return JSON.stringify(error);
+	} catch {
+		return String(error);
+	}
+}