@fluidframework/tree-agent 2.63.0 → 2.70.0-360753

package/src/api.ts

@@ -4,9 +4,13 @@
  */
 
 import type { ImplicitFieldSchema, TreeNode } from "@fluidframework/tree";
-// This is used for doc links
+// These are used for doc links
 import type { FactoryContentObject, ReadableField } from "@fluidframework/tree/alpha";
 
+// This is used for doc links
+// eslint-disable-next-line unused-imports/no-unused-imports
+import type { bindEditor, defaultEditor } from "./agent.js";
+
 /**
  * Logger interface for logging events from a {@link SharedTreeSemanticAgent}.
  * @alpha
@@ -18,6 +22,26 @@ export interface Logger {
 	log(message: string): void;
 }
 
+/**
+ * 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.
+ * @param code - The JavaScript code that should be executed.
+ * @remarks To simulate the execution of an editor outside of an {@link SharedTreeSemanticAgent | agent}, you can use {@link bindEditor | bindEditor} to bind an editor to a specific subtree.
+ * @alpha
+ */
+export type SynchronousEditor = (context: Record<string, unknown>, code: string) => void;
+/**
+ * An asynchronous 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.
+ * @param code - The JavaScript code that should be executed.
+ * @remarks To simulate the execution of an editor outside of an {@link SharedTreeSemanticAgent | agent}, you can use {@link bindEditor | bindEditor} to bind an editor to a specific subtree.
+ * @alpha
+ */
+export type AsynchronousEditor = (
+	context: Record<string, unknown>,
+	code: string,
+) => Promise<void>;
+
 /**
  * Options used to parameterize the creation of a {@link SharedTreeSemanticAgent}.
  * @alpha
@@ -28,22 +52,14 @@ export interface SemanticAgentOptions {
 	 */
 	domainHints?: string;
 	/**
-	 * Validates any generated JavaScript created by the {@link SharedTreeChatModel.editToolName | model's editing tool}.
-	 * @remarks This happens before the code is executed - execution can be intercepted by using the {@link SemanticAgentOptions.executeEdit | executeEdit} callback.
-	 * @param code - The generated JavaScript code as a string.
-	 * @throws If the code is invalid, this function should throw an error with a human-readable message describing why it is invalid.
-	 */
-	validateEdit?: (code: string) => void | Promise<void>;
-	/**
-	 * Evaluates/runs any generated JavaScript created by the {@link SharedTreeChatModel.editToolName | model's editing tool}.
-	 * @remarks This happens only after the code has been successfully validated by the optional {@link SemanticAgentOptions.validateEdit | validateEdit} function.
-	 * @param context - An object that must be provided to the generated code as a variable named "context" in its top-level scope.
-	 * @param code - The generated JavaScript code as a string.
-	 * @throws If an error is thrown while executing the code, it will be caught and the message will be forwarded to the model for debugging.
-	 * @remarks If this function is not provided, the generated code will be executed using a simple `eval` call, which may not provide sufficient security guarantees for some environments.
+	 * Executes any generated JavaScript created by the {@link SharedTreeChatModel.editToolName | model's editing tool}.
+	 * @remarks If an error is thrown while executing the code, it will be caught and the message will be forwarded to the {@link SharedTreeChatModel | model} for debugging.
+	 * @remarks If this function is not provided, the generated code will be executed using a {@link defaultEditor | simple default} which may not provide sufficient security guarantees for some environments.
 	 * Use a library such as SES to provide a more secure implementation - see `@fluidframework/tree-agent-ses` for a drop-in implementation.
+	 *
+	 * To simulate the execution of an editor outside of an {@link SharedTreeSemanticAgent | agent}, you can use {@link bindEditor | bindEditor} to bind an editor to a specific subtree.
 	 */
-	executeEdit?: (context: Record<string, unknown>, code: string) => void | Promise<void>;
+	editor?: SynchronousEditor | AsynchronousEditor;
 	/**
 	 * The maximum number of sequential edits the LLM can make before we assume it's stuck in a loop.
 	 */
@@ -56,23 +72,19 @@ export interface SemanticAgentOptions {
 
 /**
  * A result from an edit attempt via the {@link SharedTreeChatQuery.edit} function.
- * @remarks
- * - `success`: The edit was successfully applied.
- * - `disabledError`: The model is not allowed to edit the tree (i.e. {@link SharedTreeChatModel.editToolName} was not provided).
- * - `validationError`: The provided JavaScript did not pass the optional {@link SemanticAgentOptions.validateEdit} function.
- * - `executionError`: An error was thrown while parsing or executing the provided JavaScript.
- * - `tooManyEditsError`: The {@link SharedTreeChatQuery.edit} function has been called more than the number of times specified by {@link SemanticAgentOptions.maximumSequentialEdits} for the same message.
- * - `expiredError`: The {@link SharedTreeChatQuery.edit} function was called after the issuing query has already completed.
  * @alpha
  */
 export interface EditResult {
-	type:
-		| "success"
-		| "disabledError"
-		| "validationError"
-		| "executionError"
-		| "tooManyEditsError"
-		| "expiredError";
+	/**
+	 * The type of the edit result.
+	 * @remarks
+	 * - `success`: The edit was successfully applied.
+	 * - `disabledError`: The model is not allowed to edit the tree (i.e. {@link SharedTreeChatModel.editToolName} was not provided).
+	 * - `editingError`: An error was thrown while parsing or executing the provided JavaScript.
+	 * - `tooManyEditsError`: The {@link SharedTreeChatQuery.edit} function has been called more than the number of times specified by {@link SemanticAgentOptions.maximumSequentialEdits} for the same message.
+	 * - `expiredError`: The {@link SharedTreeChatQuery.edit} function was called after the issuing query has already completed.
+	 */
+	type: "success" | "disabledError" | "editingError" | "tooManyEditsError" | "expiredError";
 
 	/**
 	 * A human-readable message describing the result of the edit attempt.
@@ -107,6 +119,9 @@ export interface SharedTreeChatQuery {
 	/**
 	 * Edit the tree with the provided JavaScript function code.
 	 * @remarks Attempting an edit may fail for a variety of reasons which are captured in the {@link EditResult | returned object}.
+	 * If an edit fails, the tree will not be modified and the model may attempt another edit if desired.
+	 * When the query ends, if the last edit attempt was successful, all edits made during the query will be merged into the agent's SharedTree.
+	 * Otherwise, all edits made during the query will be discarded.
 	 */
 	edit(js: string): Promise<EditResult>;
 }

package/src/index.ts

@@ -9,13 +9,20 @@
  * @packageDocumentation
  */
 
-export { SharedTreeSemanticAgent } from "./agent.js";
+export {
+	SharedTreeSemanticAgent,
+	bindEditor,
+	bindEditorImpl,
+	defaultEditor,
+} from "./agent.js";
 export type {
 	EditResult,
 	SharedTreeChatModel,
 	SharedTreeChatQuery,
 	Logger,
 	SemanticAgentOptions,
+	SynchronousEditor,
+	AsynchronousEditor,
 } from "./api.js";
 export { type TreeView, llmDefault } from "./utils.js";
 export {

package/src/prompt.ts

@@ -87,6 +87,49 @@ const ${communize(exampleObjectName)} = context.create.${exampleObjectName}({ /*
 // const ${communize(exampleObjectName)} = { /* ...properties... */ };
 \`\`\`\n\n`;
 
+	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.
+${
+	exampleObjectName === undefined
+		? ""
+		: `For example:
+
+\`\`\`javascript
+// Data is removed from the tree:
+const ${communize(exampleObjectName)} = parent.${communize(exampleObjectName)};
+parent.${communize(exampleObjectName)} = undefined;
+// \`${communize(exampleObjectName)}\` cannot be directly re-inserted into the tree - this will throw an error:
+// parent.${communize(exampleObjectName)} = ${communize(exampleObjectName)}; // ❌ A node may not be inserted into the tree more than once
+// Instead, it must be deep cloned and recreated before insertion:
+parent.${communize(exampleObjectName)} = context.create.${exampleObjectName}({ /*... deep clone all properties from \`${communize(exampleObjectName)}\` */ });
+\`\`\`${
+				hasArrays
+					? `\n\nThe same applies when using arrays:\n\`\`\`javascript
+// Data is removed from the tree:
+const item = arrayOf${exampleObjectName}[0];
+arrayOf${exampleObjectName}.removeAt(0);
+// \`item\` cannot be directly re-inserted into the tree - this will throw an error:
+arrayOf${exampleObjectName}.insertAt(0, item); // ❌ A node may not be inserted into the tree more than once
+// Instead, it must be deep cloned and recreated before insertion:
+arrayOf${exampleObjectName}.insertAt(0, context.create.${exampleObjectName}({ /*... deep clone all properties from \`item\` */ }));
+\`\`\``
+					: ""
+			}${
+				hasMaps
+					? `\n\nThe same applies when using maps:
+\`\`\`javascript
+// Data is removed from the tree:
+const value = mapOf${exampleObjectName}.get("someKey");
+mapOf${exampleObjectName}.delete("someKey");
+// \`value\` cannot be directly re-inserted into the tree - this will throw an error:
+mapOf${exampleObjectName}.set("someKey", value); // ❌ A node may not be inserted into the tree more than once
+// Instead, it must be deep cloned and recreated before insertion:
+mapOf${exampleObjectName}.set("someKey", context.create.${exampleObjectName}({ /*... deep clone all properties from \`value\` */ }));
+\`\`\``
+					: ""
+			}`
+}`;
+
 	const arrayEditing = `#### Editing Arrays
 
 The arrays in the tree are somewhat different than normal JavaScript \`Array\`s.
@@ -133,14 +176,13 @@ This \`context\` variable holds the current state of the tree in the \`root\` pr
 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 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.
+${builderExplanation}${reinsertionExplanation}
 
-${builderExplanation}Finally, double check that the edits would accomplish the user's request (if it is possible).
+Finally, double check that the edits would accomplish the user's request (if it is possible).
 
 `;