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

package/api-report/tree-agent.alpha.api.md

@@ -21,13 +21,19 @@ export function buildFunc<const Return extends z.ZodTypeAny, const Args extends
 }, ...args: Args): FunctionDef<Args, Return, Rest>;
 
 // @alpha @deprecated
-export function createSemanticAgent<TSchema extends ImplicitFieldSchema_2>(client: BaseChatModel, treeView: TreeView<TSchema>, options?: Readonly<SemanticAgentOptions<TSchema>>): SharedTreeSemanticAgent<TSchema>;
+export function createSemanticAgent<TSchema extends ImplicitFieldSchema_2>(client: BaseChatModel, treeView: TreeView<TSchema>, options?: Readonly<SemanticAgentOptions>): SharedTreeSemanticAgent<TSchema>;
 
 // @alpha @deprecated
-export function createSemanticAgent<TSchema extends ImplicitFieldSchema_2>(client: BaseChatModel, node: ReadableField<TSchema> & TreeNode_2, options?: Readonly<SemanticAgentOptions<TSchema>>): SharedTreeSemanticAgent<TSchema>;
+export function createSemanticAgent<TSchema extends ImplicitFieldSchema_2>(client: BaseChatModel, node: ReadableField<TSchema> & TreeNode_2, options?: Readonly<SemanticAgentOptions>): SharedTreeSemanticAgent<TSchema>;
 
 // @alpha @deprecated
-export function createSemanticAgent<TSchema extends ImplicitFieldSchema_2>(client: BaseChatModel, treeView: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode_2), options?: Readonly<SemanticAgentOptions<TSchema>>): SharedTreeSemanticAgent<TSchema>;
+export function createSemanticAgent<TSchema extends ImplicitFieldSchema_2>(client: BaseChatModel, treeView: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode_2), options?: Readonly<SemanticAgentOptions>): SharedTreeSemanticAgent<TSchema>;
+
+// @alpha
+export function createSesEditEvaluator(options?: {
+    compartmentOptions?: CompartmentOptions;
+    lockdownOptions?: LockdownOptions;
+}): Promise<SemanticAgentOptions["executeEdit"]>;
 
 // @alpha
 export type Ctor<T = any> = new (...args: any[]) => T;
@@ -36,7 +42,7 @@ export type Ctor<T = any> = new (...args: any[]) => T;
 export interface EditResult {
     message: string;
     // (undocumented)
-    type: "success" | "disabledError" | "validationError" | "compileError" | "runtimeError" | "tooManyEditsError" | "expiredError";
+    type: "success" | "disabledError" | "validationError" | "executionError" | "tooManyEditsError" | "expiredError";
 }
 
 // @alpha
@@ -78,8 +84,6 @@ export class LangchainChatModel implements SharedTreeChatModel {
     // (undocumented)
     appendContext(text: string): void;
     // (undocumented)
-    readonly editFunctionName = "editTree";
-    // (undocumented)
     readonly editToolName = "GenerateTreeEditingCode";
     // (undocumented)
     get name(): string | undefined;
@@ -91,9 +95,8 @@ export class LangchainChatModel implements SharedTreeChatModel {
 export const llmDefault: unique symbol;
 
 // @alpha
-export interface Logger<TTree extends ReadableField<ImplicitFieldSchema> = ReadableField<ImplicitFieldSchema>> {
+export interface Logger {
     log(message: string): void;
-    treeToString?(tree: TTree): string;
 }
 
 // @alpha
@@ -102,20 +105,17 @@ export type MethodKeys<T> = {
 };
 
 // @alpha
-export interface SemanticAgentOptions<TSchema extends ImplicitFieldSchema> {
-    // (undocumented)
+export interface SemanticAgentOptions {
     domainHints?: string;
-    // (undocumented)
-    logger?: Logger<ReadableField<TSchema>>;
+    executeEdit?: (context: Record<string, unknown>, code: string) => void | Promise<void>;
+    logger?: Logger;
     maximumSequentialEdits?: number;
-    // (undocumented)
-    validator?: (js: string) => boolean;
+    validateEdit?: (code: string) => void | Promise<void>;
 }
 
 // @alpha
 export interface SharedTreeChatModel {
     appendContext?(text: string): void;
-    editFunctionName?: string;
     editToolName?: string;
     name?: string;
     query(message: SharedTreeChatQuery): Promise<string>;
@@ -129,9 +129,7 @@ export interface SharedTreeChatQuery {
 
 // @alpha @sealed
 export class SharedTreeSemanticAgent<TSchema extends ImplicitFieldSchema> {
-    constructor(client: SharedTreeChatModel, tree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode), options?: Readonly<SemanticAgentOptions<TSchema>> | undefined);
-    // (undocumented)
-    static editFunctionName: string;
+    constructor(client: SharedTreeChatModel, tree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode), options?: Readonly<SemanticAgentOptions> | undefined);
     query(userPrompt: string): Promise<string>;
 }
 

package/dist/agent.d.ts

@@ -15,13 +15,12 @@ import { type TreeView } from "./utils.js";
 export declare class SharedTreeSemanticAgent<TSchema extends ImplicitFieldSchema> {
     private readonly client;
     private readonly options?;
-    static editFunctionName: string;
     private readonly outerTree;
     /**
      * Whether or not the outer tree has changed since the last query finished.
      */
     private outerTreeIsDirty;
-    constructor(client: SharedTreeChatModel, tree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode), options?: Readonly<SemanticAgentOptions<TSchema>> | undefined);
+    constructor(client: SharedTreeChatModel, tree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode), options?: Readonly<SemanticAgentOptions> | undefined);
     /**
      * Given a user prompt, return a response.
      *

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACX,mBAAmB,EAGnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,KAAK,EACX,aAAa,EAIb,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EACX,mBAAmB,EAGnB,oBAAoB,EAEpB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAIN,KAAK,QAAQ,EAGb,MAAM,YAAY,CAAC;AAapB;;;;GAIG;AACH,qBAAa,uBAAuB,CAAC,OAAO,SAAS,mBAAmB;IAUtE,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAX1B,OAAc,gBAAgB,SAAc;IAE5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAS;gBAGf,MAAM,EAAE,mBAAmB,EAC5C,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,EAC5C,OAAO,CAAC,qDAAyC;IAkCnE;;;;;OAKG;IACU,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAsEvD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACX,mBAAmB,EAGnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,KAAK,EACX,aAAa,EAIb,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,mBAAmB,EAAc,oBAAoB,EAAU,MAAM,UAAU,CAAC;AAG9F,OAAO,EAIN,KAAK,QAAQ,EAGb,MAAM,YAAY,CAAC;AAQpB;;;;GAIG;AACH,qBAAa,uBAAuB,CAAC,OAAO,SAAS,mBAAmB;IAStE,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAT1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAS;gBAGf,MAAM,EAAE,mBAAmB,EAC5C,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,EAC5C,OAAO,CAAC,4CAAgC;IAiC1D;;;;;OAKG;IACU,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAsEvD"}

package/dist/agent.js

@@ -15,10 +15,6 @@ const utils_js_1 = require("./utils.js");
  * @remarks This can be overridden by passing {@link SemanticAgentOptions.maximumSequentialEdits | maximumSequentialEdits} to {@link createSemanticAgent}.
  */
 const defaultMaxSequentialEdits = 20;
-/**
- * The name of the parameter passed to the edit function.
- */
-const paramsName = "params";
 /**
  * An agent that uses a {@link SharedTreeChatModel} to interact with a SharedTree.
  * @remarks This class forwards user queries to the chat model, and handles the application of any edits to the tree that the model requests.
@@ -42,7 +38,6 @@ class SharedTreeSemanticAgent {
         const prompt = (0, prompt_js_1.getPrompt)({
             subtree: this.outerTree,
             editToolName: this.client.editToolName,
-            editFunctionName: this.client.editFunctionName,
             domainHints: this.options?.domainHints,
         });
         this.options?.logger?.log(`# Fluid Framework SharedTree AI Agent Log\n\n`);
@@ -84,9 +79,9 @@ class SharedTreeSemanticAgent {
         let active = true;
         let editCount = 0;
         let editFailed = false;
-        const { editFunctionName } = this.client;
-        const edit = async (js) => {
-            if (editFunctionName === undefined) {
+        const { editToolName } = this.client;
+        const edit = async (editCode) => {
+            if (editToolName === undefined) {
                 return {
                     type: "disabledError",
                     message: "Editing is not enabled for this model.",
@@ -105,7 +100,7 @@ class SharedTreeSemanticAgent {
                     message: `The maximum number of edits (${maxEditCount}) for this query has been exceeded.`,
                 };
             }
-            const editResult = await applyTreeFunction(queryTree, js, editFunctionName ?? (0, utils_js_1.fail)("Expected edit function name to be defined"), this.options?.validator, this.options?.logger);
+            const editResult = await applyTreeFunction(queryTree, editCode, this.options?.validateEdit ?? defaultValidateEdit, this.options?.executeEdit ?? defaultExecuteEdit, this.options?.logger);
             editFailed ||= editResult.type !== "success";
             return editResult;
         };
@@ -124,7 +119,6 @@ class SharedTreeSemanticAgent {
     }
 }
 exports.SharedTreeSemanticAgent = SharedTreeSemanticAgent;
-SharedTreeSemanticAgent.editFunctionName = "editTree";
 /**
  * Creates an unhydrated node of the given schema with the given value.
  * @remarks If the schema is an object with {@link llmDefault | default values}, this function populates the node with those defaults.
@@ -157,14 +151,18 @@ function constructTreeNode(schema, value) {
 /**
  * Applies the given function (as a string of JavaScript code or an actual function) to the given tree.
  */
-async function applyTreeFunction(tree, fn, editFunctionName, validator, logger) {
+async function applyTreeFunction(tree, editCode, validateEdit, executeEdit, logger) {
     logger?.log(`### Editing Tool Invoked\n\n`);
-    logger?.log(`#### Generated Code\n\n\`\`\`javascript\n${fn}\n\`\`\`\n\n`);
-    if (validator?.(fn.toString()) === false) {
+    logger?.log(`#### Generated Code\n\n\`\`\`javascript\n${editCode}\n\`\`\`\n\n`);
+    try {
+        await validateEdit(editCode);
+    }
+    catch (error) {
         logger?.log(`#### Code Validation Failed\n\n`);
+        logger?.log(`\`\`\`JSON\n${(0, utils_js_1.toErrorString)(error)}\n\`\`\`\n\n`);
         return {
             type: "validationError",
-            message: "The generated code did not pass validation. Please try again.",
+            message: `The generated code did not pass validation: ${(0, utils_js_1.toErrorString)(error)}`,
         };
     }
     // Stick the tree schema constructors on an object passed to the function so that the LLM can create new nodes.
@@ -175,7 +173,7 @@ async function applyTreeFunction(tree, fn, editFunctionName, validator, logger)
     }
     // Fork a branch to edit. If the edit fails or produces an error, we discard this branch, otherwise we merge it.
     const editTree = tree.fork();
-    const params = {
+    const context = {
         get root() {
             return editTree.field;
         },
@@ -184,55 +182,30 @@ async function applyTreeFunction(tree, fn, editFunctionName, validator, logger)
         },
         create,
     };
-    let editFunction;
-    if (typeof fn === "string") {
-        try {
-            editFunction = processLlmCode(fn, editFunctionName);
-        }
-        catch (error) {
-            logger?.log(`#### Error\n\n`);
-            const errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
-            logger?.log(`\`\`\`JSON\n${errorMessage}\n\`\`\`\n\n`);
-            editTree.branch.dispose();
-            return {
-                type: "compileError",
-                message: `The supplied JavaScript function is not valid: ${errorMessage}`,
-            };
-        }
-    }
-    else {
-        editFunction = fn;
-    }
     try {
-        await editFunction(params);
+        await executeEdit(context, editCode);
     }
     catch (error) {
         logger?.log(`#### Error\n\n`);
-        const errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
-        logger?.log(`\`\`\`JSON\n${errorMessage}\n\`\`\`\n\n`);
+        logger?.log(`\`\`\`JSON\n${(0, utils_js_1.toErrorString)(error)}\n\`\`\`\n\n`);
         editTree.branch.dispose();
         return {
-            type: "runtimeError",
-            message: `Running the function produced an error. The state of the tree will be reset to its previous state as it was before the function ran. Please try again. Here is the error: ${errorMessage}`,
+            type: "executionError",
+            message: `Running the generated code produced an error. The state of the tree will be reset to its previous state as it was before the code ran. Please try again. Here is the error: ${(0, utils_js_1.toErrorString)(error)}`,
         };
     }
     tree.branch.merge(editTree.branch);
     logger?.log(`#### New Tree State\n\n`);
-    logger?.log(`${logger?.treeToString?.(tree.field) ?? `\`\`\`JSON\n${(0, prompt_js_1.stringifyTree)(tree.field)}\n\`\`\``}\n\n`);
+    logger?.log(`${`\`\`\`JSON\n${(0, prompt_js_1.stringifyTree)(tree.field)}\n\`\`\``}\n\n`);
     return {
         type: "success",
-        message: `After running the function, the new state of the tree is:\n\n\`\`\`JSON\n${(0, prompt_js_1.stringifyTree)(tree.field)}\n\`\`\``,
+        message: `After running the code, the new state of the tree is:\n\n\`\`\`JSON\n${(0, prompt_js_1.stringifyTree)(tree.field)}\n\`\`\``,
     };
 }
-function processLlmCode(code, editFunctionName) {
-    // TODO: use a library like Acorn to analyze the code more robustly
-    const regex = new RegExp(`function\\s+${editFunctionName}\\s*\\(`);
-    if (!regex.test(code)) {
-        throw new Error(`Generated code does not contain a function named \`${editFunctionName}\``);
-    }
-    const executionCode = `${code}\n\n${editFunctionName}(${paramsName});`;
+const defaultValidateEdit = () => { };
+const defaultExecuteEdit = async (context, code) => {
     // eslint-disable-next-line no-new-func, @typescript-eslint/no-implied-eval
-    const fn = new Function(paramsName, executionCode);
-    return fn;
-}
+    const fn = new Function("context", code);
+    await fn(context);
+};
 //# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tImplicitFieldSchema,\n\tTreeFieldFromImplicitField,\n\tTreeNodeSchema,\n} from \"@fluidframework/tree\";\nimport { TreeNode } from \"@fluidframework/tree\";\nimport type {\n\tReadableField,\n\tFactoryContentObject,\n\tInsertableContent,\n\tReadSchema,\n} from \"@fluidframework/tree/alpha\";\nimport { ObjectNodeSchema, Tree } from \"@fluidframework/tree/alpha\";\n\nimport type {\n\tSharedTreeChatModel,\n\tEditFunction,\n\tEditResult,\n\tSemanticAgentOptions,\n\tLogger,\n} from \"./api.js\";\nimport { getPrompt, stringifyTree } from \"./prompt.js\";\nimport { Subtree } from \"./subtree.js\";\nimport {\n\tconstructNode,\n\tgetFriendlyName,\n\tllmDefault,\n\ttype TreeView,\n\tfindNamedSchemas,\n\tfail,\n} from \"./utils.js\";\n\n/**\n * The default maximum number of sequential edits the LLM can make before we assume it's stuck in a loop.\n * @remarks This can be overridden by passing {@link SemanticAgentOptions.maximumSequentialEdits | maximumSequentialEdits} to {@link createSemanticAgent}.\n */\nconst defaultMaxSequentialEdits = 20;\n\n/**\n * The name of the parameter passed to the edit function.\n */\nconst paramsName = \"params\";\n\n/**\n * An agent that uses a {@link SharedTreeChatModel} to interact with a SharedTree.\n * @remarks This class forwards user queries to the chat model, and handles the application of any edits to the tree that the model requests.\n * @alpha @sealed\n */\nexport class SharedTreeSemanticAgent<TSchema extends ImplicitFieldSchema> {\n\tpublic static editFunctionName = \"editTree\";\n\t// Converted from ECMAScript private fields (#name) to TypeScript private members for easier debugger inspection.\n\tprivate readonly outerTree: Subtree<TSchema>;\n\t/**\n\t * Whether or not the outer tree has changed since the last query finished.\n\t */\n\tprivate outerTreeIsDirty = false;\n\n\tpublic constructor(\n\t\tprivate readonly client: SharedTreeChatModel,\n\t\ttree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode),\n\t\tprivate readonly options?: Readonly<SemanticAgentOptions<TSchema>>,\n\t) {\n\t\tif (tree instanceof TreeNode) {\n\t\t\tTree.on(tree, \"treeChanged\", () => (this.outerTreeIsDirty = true));\n\t\t} else {\n\t\t\ttree.events.on(\"changed\", () => (this.outerTreeIsDirty = true));\n\t\t}\n\n\t\tthis.outerTree = new Subtree(tree);\n\t\tconst prompt = getPrompt({\n\t\t\tsubtree: this.outerTree,\n\t\t\teditToolName: this.client.editToolName,\n\t\t\teditFunctionName: this.client.editFunctionName,\n\t\t\tdomainHints: this.options?.domainHints,\n\t\t});\n\t\tthis.options?.logger?.log(`# Fluid Framework SharedTree AI Agent Log\\n\\n`);\n\t\tconst now = new Date();\n\t\tconst formattedDate = now.toLocaleString(undefined, {\n\t\t\tweekday: \"long\",\n\t\t\tyear: \"numeric\",\n\t\t\tmonth: \"long\",\n\t\t\tday: \"numeric\",\n\t\t\thour: \"numeric\",\n\t\t\tminute: \"2-digit\",\n\t\t\tsecond: \"2-digit\",\n\t\t});\n\t\tthis.options?.logger?.log(`Agent created: **${formattedDate}**\\n\\n`);\n\t\tif (this.client.name !== undefined) {\n\t\t\tthis.options?.logger?.log(`Model: **${this.client.name}**\\n\\n`);\n\t\t}\n\t\tthis.client.appendContext?.(prompt);\n\t\tthis.options?.logger?.log(`## System Prompt\\n\\n${prompt}\\n\\n`);\n\t}\n\n\t/**\n\t * Given a user prompt, return a response.\n\t *\n\t * @param userPrompt - The prompt to send to the agent.\n\t * @returns The agent's response.\n\t */\n\tpublic async query(userPrompt: string): Promise<string> {\n\t\tthis.options?.logger?.log(`## User Query\\n\\n${userPrompt}\\n\\n`);\n\n\t\t// Notify the llm if the tree has changed since the last query, and if so, provide the new state of the tree.\n\t\tif (this.outerTreeIsDirty) {\n\t\t\tconst stringified = stringifyTree(this.outerTree.field);\n\t\t\tthis.client.appendContext?.(\n\t\t\t\t`The tree has changed since the last query. The new state of the tree is: \\n\\n\\`\\`\\`JSON\\n${stringified}\\n\\`\\`\\``,\n\t\t\t);\n\t\t\tthis.options?.logger?.log(\n\t\t\t\t`### Latest Tree State\\n\\nThe Tree was edited by a local or remote user since the previous query. The latest state is:\\n\\n\\`\\`\\`JSON\\n${stringified}\\n\\`\\`\\`\\n\\n`,\n\t\t\t);\n\t\t}\n\n\t\t// Fork a branch that will live for the lifetime of this query (which can be multiple LLM calls if the there are errors or the LLM decides to take multiple steps to accomplish a task).\n\t\t// The branch will be merged back into the outer branch if and only if the query succeeds.\n\t\tconst queryTree = this.outerTree.fork();\n\t\tconst maxEditCount = this.options?.maximumSequentialEdits ?? defaultMaxSequentialEdits;\n\t\tlet active = true;\n\t\tlet editCount = 0;\n\t\tlet editFailed = false;\n\t\tconst { editFunctionName } = this.client;\n\t\tconst edit = async (js: string): Promise<EditResult> => {\n\t\t\tif (editFunctionName === undefined) {\n\t\t\t\treturn {\n\t\t\t\t\ttype: \"disabledError\",\n\t\t\t\t\tmessage: \"Editing is not enabled for this model.\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (!active) {\n\t\t\t\treturn {\n\t\t\t\t\ttype: \"expiredError\",\n\t\t\t\t\tmessage: `The query has already completed. Further edits are not allowed.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (++editCount > maxEditCount) {\n\t\t\t\teditFailed = true;\n\t\t\t\treturn {\n\t\t\t\t\ttype: \"tooManyEditsError\",\n\t\t\t\t\tmessage: `The maximum number of edits (${maxEditCount}) for this query has been exceeded.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst editResult = await applyTreeFunction(\n\t\t\t\tqueryTree,\n\t\t\t\tjs,\n\t\t\t\teditFunctionName ?? fail(\"Expected edit function name to be defined\"),\n\t\t\t\tthis.options?.validator,\n\t\t\t\tthis.options?.logger,\n\t\t\t);\n\n\t\t\teditFailed ||= editResult.type !== \"success\";\n\t\t\treturn editResult;\n\t\t};\n\n\t\tconst responseMessage = await this.client.query({\n\t\t\ttext: userPrompt,\n\t\t\tedit,\n\t\t});\n\t\tactive = false;\n\n\t\tif (!editFailed) {\n\t\t\tthis.outerTree.branch.merge(queryTree.branch);\n\t\t\tthis.outerTreeIsDirty = false;\n\t\t}\n\t\tthis.options?.logger?.log(`## Response\\n\\n`);\n\t\tthis.options?.logger?.log(`${responseMessage}\\n\\n`);\n\t\treturn responseMessage;\n\t}\n}\n\n/**\n * Creates an unhydrated node of the given schema with the given value.\n * @remarks If the schema is an object with {@link llmDefault | default values}, this function populates the node with those defaults.\n */\nfunction constructTreeNode(schema: TreeNodeSchema, value: FactoryContentObject): TreeNode {\n\tif (schema instanceof ObjectNodeSchema) {\n\t\tconst inputWithDefaults: Record<string, InsertableContent | undefined> = {};\n\t\tfor (const [key, field] of schema.fields) {\n\t\t\tif (value[key] === undefined) {\n\t\t\t\tif (\n\t\t\t\t\ttypeof field.metadata.custom === \"object\" &&\n\t\t\t\t\tfield.metadata.custom !== null &&\n\t\t\t\t\tllmDefault in field.metadata.custom\n\t\t\t\t) {\n\t\t\t\t\tconst defaulter = field.metadata.custom[llmDefault];\n\t\t\t\t\tif (typeof defaulter === \"function\") {\n\t\t\t\t\t\tconst defaultValue: unknown = defaulter();\n\t\t\t\t\t\tif (defaultValue !== undefined) {\n\t\t\t\t\t\t\tinputWithDefaults[key] = defaultValue;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tinputWithDefaults[key] = value[key];\n\t\t\t}\n\t\t}\n\t\treturn constructNode(schema, inputWithDefaults);\n\t}\n\treturn constructNode(schema, value);\n}\n\n/**\n * Applies the given function (as a string of JavaScript code or an actual function) to the given tree.\n */\nasync function applyTreeFunction<TSchema extends ImplicitFieldSchema>(\n\ttree: Subtree<TSchema>,\n\tfn: string | EditFunction<TSchema>,\n\teditFunctionName: string,\n\tvalidator: ((js: string) => boolean) | undefined,\n\tlogger: Logger<ReadableField<TSchema>> | undefined,\n): Promise<EditResult> {\n\tlogger?.log(`### Editing Tool Invoked\\n\\n`);\n\tlogger?.log(`#### Generated Code\\n\\n\\`\\`\\`javascript\\n${fn}\\n\\`\\`\\`\\n\\n`);\n\n\tif (validator?.(fn.toString()) === false) {\n\t\tlogger?.log(`#### Code Validation Failed\\n\\n`);\n\t\treturn {\n\t\t\ttype: \"validationError\",\n\t\t\tmessage: \"The generated code did not pass validation. Please try again.\",\n\t\t};\n\t}\n\n\t// Stick the tree schema constructors on an object passed to the function so that the LLM can create new nodes.\n\tconst create: Record<string, (input: FactoryContentObject) => TreeNode> = {};\n\tfor (const schema of findNamedSchemas(tree.schema)) {\n\t\tconst name = getFriendlyName(schema);\n\t\tcreate[name] = (input: FactoryContentObject) => constructTreeNode(schema, input);\n\t}\n\n\t// Fork a branch to edit. If the edit fails or produces an error, we discard this branch, otherwise we merge it.\n\tconst editTree = tree.fork();\n\tconst params = {\n\t\tget root(): ReadableField<TSchema> {\n\t\t\treturn editTree.field;\n\t\t},\n\t\tset root(value: TreeFieldFromImplicitField<ReadSchema<TSchema>>) {\n\t\t\teditTree.field = value;\n\t\t},\n\t\tcreate,\n\t};\n\n\tlet editFunction: EditFunction<TSchema>;\n\tif (typeof fn === \"string\") {\n\t\ttry {\n\t\t\teditFunction = processLlmCode(fn, editFunctionName);\n\t\t} catch (error) {\n\t\t\tlogger?.log(`#### Error\\n\\n`);\n\t\t\tconst errorMessage = error instanceof Error ? error.message : JSON.stringify(error);\n\t\t\tlogger?.log(`\\`\\`\\`JSON\\n${errorMessage}\\n\\`\\`\\`\\n\\n`);\n\t\t\teditTree.branch.dispose();\n\t\t\treturn {\n\t\t\t\ttype: \"compileError\",\n\t\t\t\tmessage: `The supplied JavaScript function is not valid: ${errorMessage}`,\n\t\t\t};\n\t\t}\n\t} else {\n\t\teditFunction = fn;\n\t}\n\n\ttry {\n\t\tawait editFunction(params);\n\t} catch (error: unknown) {\n\t\tlogger?.log(`#### Error\\n\\n`);\n\t\tconst errorMessage = error instanceof Error ? error.message : JSON.stringify(error);\n\t\tlogger?.log(`\\`\\`\\`JSON\\n${errorMessage}\\n\\`\\`\\`\\n\\n`);\n\t\teditTree.branch.dispose();\n\t\treturn {\n\t\t\ttype: \"runtimeError\",\n\t\t\tmessage: `Running the function produced an error. The state of the tree will be reset to its previous state as it was before the function ran. Please try again. Here is the error: ${errorMessage}`,\n\t\t};\n\t}\n\n\ttree.branch.merge(editTree.branch);\n\tlogger?.log(`#### New Tree State\\n\\n`);\n\tlogger?.log(\n\t\t`${\n\t\t\tlogger?.treeToString?.(tree.field) ?? `\\`\\`\\`JSON\\n${stringifyTree(tree.field)}\\n\\`\\`\\``\n\t\t}\\n\\n`,\n\t);\n\treturn {\n\t\ttype: \"success\",\n\t\tmessage: `After running the function, the new state of the tree is:\\n\\n\\`\\`\\`JSON\\n${stringifyTree(tree.field)}\\n\\`\\`\\``,\n\t};\n}\n\nfunction processLlmCode<TSchema extends ImplicitFieldSchema>(\n\tcode: string,\n\teditFunctionName: string,\n): EditFunction<TSchema> {\n\t// TODO: use a library like Acorn to analyze the code more robustly\n\tconst regex = new RegExp(`function\\\\s+${editFunctionName}\\\\s*\\\\(`);\n\tif (!regex.test(code)) {\n\t\tthrow new Error(\n\t\t\t`Generated code does not contain a function named \\`${editFunctionName}\\``,\n\t\t);\n\t}\n\n\tconst executionCode = `${code}\\n\\n${editFunctionName}(${paramsName});`;\n\t// eslint-disable-next-line no-new-func, @typescript-eslint/no-implied-eval\n\tconst fn = new Function(paramsName, executionCode);\n\treturn fn as EditFunction<TSchema>;\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tImplicitFieldSchema,\n\tTreeFieldFromImplicitField,\n\tTreeNodeSchema,\n} from \"@fluidframework/tree\";\nimport { TreeNode } from \"@fluidframework/tree\";\nimport type {\n\tReadableField,\n\tFactoryContentObject,\n\tInsertableContent,\n\tReadSchema,\n} from \"@fluidframework/tree/alpha\";\nimport { ObjectNodeSchema, Tree } from \"@fluidframework/tree/alpha\";\n\nimport type { SharedTreeChatModel, EditResult, SemanticAgentOptions, Logger } from \"./api.js\";\nimport { getPrompt, stringifyTree } from \"./prompt.js\";\nimport { Subtree } from \"./subtree.js\";\nimport {\n\tconstructNode,\n\tgetFriendlyName,\n\tllmDefault,\n\ttype TreeView,\n\tfindNamedSchemas,\n\ttoErrorString,\n} from \"./utils.js\";\n\n/**\n * The default maximum number of sequential edits the LLM can make before we assume it's stuck in a loop.\n * @remarks This can be overridden by passing {@link SemanticAgentOptions.maximumSequentialEdits | maximumSequentialEdits} to {@link createSemanticAgent}.\n */\nconst defaultMaxSequentialEdits = 20;\n\n/**\n * An agent that uses a {@link SharedTreeChatModel} to interact with a SharedTree.\n * @remarks This class forwards user queries to the chat model, and handles the application of any edits to the tree that the model requests.\n * @alpha @sealed\n */\nexport class SharedTreeSemanticAgent<TSchema extends ImplicitFieldSchema> {\n\t// Converted from ECMAScript private fields (#name) to TypeScript private members for easier debugger inspection.\n\tprivate readonly outerTree: Subtree<TSchema>;\n\t/**\n\t * Whether or not the outer tree has changed since the last query finished.\n\t */\n\tprivate outerTreeIsDirty = false;\n\n\tpublic constructor(\n\t\tprivate readonly client: SharedTreeChatModel,\n\t\ttree: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode),\n\t\tprivate readonly options?: Readonly<SemanticAgentOptions>,\n\t) {\n\t\tif (tree instanceof TreeNode) {\n\t\t\tTree.on(tree, \"treeChanged\", () => (this.outerTreeIsDirty = true));\n\t\t} else {\n\t\t\ttree.events.on(\"changed\", () => (this.outerTreeIsDirty = true));\n\t\t}\n\n\t\tthis.outerTree = new Subtree(tree);\n\t\tconst prompt = getPrompt({\n\t\t\tsubtree: this.outerTree,\n\t\t\teditToolName: this.client.editToolName,\n\t\t\tdomainHints: this.options?.domainHints,\n\t\t});\n\t\tthis.options?.logger?.log(`# Fluid Framework SharedTree AI Agent Log\\n\\n`);\n\t\tconst now = new Date();\n\t\tconst formattedDate = now.toLocaleString(undefined, {\n\t\t\tweekday: \"long\",\n\t\t\tyear: \"numeric\",\n\t\t\tmonth: \"long\",\n\t\t\tday: \"numeric\",\n\t\t\thour: \"numeric\",\n\t\t\tminute: \"2-digit\",\n\t\t\tsecond: \"2-digit\",\n\t\t});\n\t\tthis.options?.logger?.log(`Agent created: **${formattedDate}**\\n\\n`);\n\t\tif (this.client.name !== undefined) {\n\t\t\tthis.options?.logger?.log(`Model: **${this.client.name}**\\n\\n`);\n\t\t}\n\t\tthis.client.appendContext?.(prompt);\n\t\tthis.options?.logger?.log(`## System Prompt\\n\\n${prompt}\\n\\n`);\n\t}\n\n\t/**\n\t * Given a user prompt, return a response.\n\t *\n\t * @param userPrompt - The prompt to send to the agent.\n\t * @returns The agent's response.\n\t */\n\tpublic async query(userPrompt: string): Promise<string> {\n\t\tthis.options?.logger?.log(`## User Query\\n\\n${userPrompt}\\n\\n`);\n\n\t\t// Notify the llm if the tree has changed since the last query, and if so, provide the new state of the tree.\n\t\tif (this.outerTreeIsDirty) {\n\t\t\tconst stringified = stringifyTree(this.outerTree.field);\n\t\t\tthis.client.appendContext?.(\n\t\t\t\t`The tree has changed since the last query. The new state of the tree is: \\n\\n\\`\\`\\`JSON\\n${stringified}\\n\\`\\`\\``,\n\t\t\t);\n\t\t\tthis.options?.logger?.log(\n\t\t\t\t`### Latest Tree State\\n\\nThe Tree was edited by a local or remote user since the previous query. The latest state is:\\n\\n\\`\\`\\`JSON\\n${stringified}\\n\\`\\`\\`\\n\\n`,\n\t\t\t);\n\t\t}\n\n\t\t// Fork a branch that will live for the lifetime of this query (which can be multiple LLM calls if the there are errors or the LLM decides to take multiple steps to accomplish a task).\n\t\t// The branch will be merged back into the outer branch if and only if the query succeeds.\n\t\tconst queryTree = this.outerTree.fork();\n\t\tconst maxEditCount = this.options?.maximumSequentialEdits ?? defaultMaxSequentialEdits;\n\t\tlet active = true;\n\t\tlet editCount = 0;\n\t\tlet editFailed = false;\n\t\tconst { editToolName } = this.client;\n\t\tconst edit = async (editCode: string): Promise<EditResult> => {\n\t\t\tif (editToolName === undefined) {\n\t\t\t\treturn {\n\t\t\t\t\ttype: \"disabledError\",\n\t\t\t\t\tmessage: \"Editing is not enabled for this model.\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (!active) {\n\t\t\t\treturn {\n\t\t\t\t\ttype: \"expiredError\",\n\t\t\t\t\tmessage: `The query has already completed. Further edits are not allowed.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (++editCount > maxEditCount) {\n\t\t\t\teditFailed = true;\n\t\t\t\treturn {\n\t\t\t\t\ttype: \"tooManyEditsError\",\n\t\t\t\t\tmessage: `The maximum number of edits (${maxEditCount}) for this query has been exceeded.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst editResult = await applyTreeFunction(\n\t\t\t\tqueryTree,\n\t\t\t\teditCode,\n\t\t\t\tthis.options?.validateEdit ?? defaultValidateEdit,\n\t\t\t\tthis.options?.executeEdit ?? defaultExecuteEdit,\n\t\t\t\tthis.options?.logger,\n\t\t\t);\n\n\t\t\teditFailed ||= editResult.type !== \"success\";\n\t\t\treturn editResult;\n\t\t};\n\n\t\tconst responseMessage = await this.client.query({\n\t\t\ttext: userPrompt,\n\t\t\tedit,\n\t\t});\n\t\tactive = false;\n\n\t\tif (!editFailed) {\n\t\t\tthis.outerTree.branch.merge(queryTree.branch);\n\t\t\tthis.outerTreeIsDirty = false;\n\t\t}\n\t\tthis.options?.logger?.log(`## Response\\n\\n`);\n\t\tthis.options?.logger?.log(`${responseMessage}\\n\\n`);\n\t\treturn responseMessage;\n\t}\n}\n\n/**\n * Creates an unhydrated node of the given schema with the given value.\n * @remarks If the schema is an object with {@link llmDefault | default values}, this function populates the node with those defaults.\n */\nfunction constructTreeNode(schema: TreeNodeSchema, value: FactoryContentObject): TreeNode {\n\tif (schema instanceof ObjectNodeSchema) {\n\t\tconst inputWithDefaults: Record<string, InsertableContent | undefined> = {};\n\t\tfor (const [key, field] of schema.fields) {\n\t\t\tif (value[key] === undefined) {\n\t\t\t\tif (\n\t\t\t\t\ttypeof field.metadata.custom === \"object\" &&\n\t\t\t\t\tfield.metadata.custom !== null &&\n\t\t\t\t\tllmDefault in field.metadata.custom\n\t\t\t\t) {\n\t\t\t\t\tconst defaulter = field.metadata.custom[llmDefault];\n\t\t\t\t\tif (typeof defaulter === \"function\") {\n\t\t\t\t\t\tconst defaultValue: unknown = defaulter();\n\t\t\t\t\t\tif (defaultValue !== undefined) {\n\t\t\t\t\t\t\tinputWithDefaults[key] = defaultValue;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tinputWithDefaults[key] = value[key];\n\t\t\t}\n\t\t}\n\t\treturn constructNode(schema, inputWithDefaults);\n\t}\n\treturn constructNode(schema, value);\n}\n\n/**\n * Applies the given function (as a string of JavaScript code or an actual function) to the given tree.\n */\nasync function applyTreeFunction<TSchema extends ImplicitFieldSchema>(\n\ttree: Subtree<TSchema>,\n\teditCode: string,\n\tvalidateEdit: Required<SemanticAgentOptions>[\"validateEdit\"],\n\texecuteEdit: Required<SemanticAgentOptions>[\"executeEdit\"],\n\tlogger: Logger | undefined,\n): Promise<EditResult> {\n\tlogger?.log(`### Editing Tool Invoked\\n\\n`);\n\tlogger?.log(`#### Generated Code\\n\\n\\`\\`\\`javascript\\n${editCode}\\n\\`\\`\\`\\n\\n`);\n\n\ttry {\n\t\tawait validateEdit(editCode);\n\t} catch (error: unknown) {\n\t\tlogger?.log(`#### Code Validation Failed\\n\\n`);\n\t\tlogger?.log(`\\`\\`\\`JSON\\n${toErrorString(error)}\\n\\`\\`\\`\\n\\n`);\n\t\treturn {\n\t\t\ttype: \"validationError\",\n\t\t\tmessage: `The generated code did not pass validation: ${toErrorString(error)}`,\n\t\t};\n\t}\n\n\t// Stick the tree schema constructors on an object passed to the function so that the LLM can create new nodes.\n\tconst create: Record<string, (input: FactoryContentObject) => TreeNode> = {};\n\tfor (const schema of findNamedSchemas(tree.schema)) {\n\t\tconst name = getFriendlyName(schema);\n\t\tcreate[name] = (input: FactoryContentObject) => constructTreeNode(schema, input);\n\t}\n\n\t// Fork a branch to edit. If the edit fails or produces an error, we discard this branch, otherwise we merge it.\n\tconst editTree = tree.fork();\n\tconst context = {\n\t\tget root(): ReadableField<TSchema> {\n\t\t\treturn editTree.field;\n\t\t},\n\t\tset root(value: TreeFieldFromImplicitField<ReadSchema<TSchema>>) {\n\t\t\teditTree.field = value;\n\t\t},\n\t\tcreate,\n\t};\n\n\ttry {\n\t\tawait executeEdit(context, editCode);\n\t} catch (error: unknown) {\n\t\tlogger?.log(`#### Error\\n\\n`);\n\t\tlogger?.log(`\\`\\`\\`JSON\\n${toErrorString(error)}\\n\\`\\`\\`\\n\\n`);\n\t\teditTree.branch.dispose();\n\t\treturn {\n\t\t\ttype: \"executionError\",\n\t\t\tmessage: `Running the generated code produced an error. The state of the tree will be reset to its previous state as it was before the code ran. Please try again. Here is the error: ${toErrorString(error)}`,\n\t\t};\n\t}\n\n\ttree.branch.merge(editTree.branch);\n\tlogger?.log(`#### New Tree State\\n\\n`);\n\tlogger?.log(`${`\\`\\`\\`JSON\\n${stringifyTree(tree.field)}\\n\\`\\`\\``}\\n\\n`);\n\treturn {\n\t\ttype: \"success\",\n\t\tmessage: `After running the code, the new state of the tree is:\\n\\n\\`\\`\\`JSON\\n${stringifyTree(tree.field)}\\n\\`\\`\\``,\n\t};\n}\n\nconst defaultValidateEdit: Required<SemanticAgentOptions>[\"validateEdit\"] = () => {};\n\nconst defaultExecuteEdit: Required<SemanticAgentOptions>[\"executeEdit\"] = async (\n\tcontext,\n\tcode,\n) => {\n\t// eslint-disable-next-line no-new-func, @typescript-eslint/no-implied-eval\n\tconst fn = new Function(\"context\", code);\n\tawait fn(context);\n};\n"]}

package/dist/alpha.d.ts

@@ -35,6 +35,7 @@ export {
 	TreeView, 
 	buildFunc, 
 	createSemanticAgent, 
+	createSesEditEvaluator, 
 	exposeMethodsSymbol, 
 	llmDefault
 	// #endregion

package/dist/api.d.ts

@@ -8,43 +8,60 @@ import type { FactoryContentObject, ReadableField } from "@fluidframework/tree/a
  * Logger interface for logging events from a {@link SharedTreeSemanticAgent}.
  * @alpha
  */
-export interface Logger<TTree extends ReadableField<ImplicitFieldSchema> = ReadableField<ImplicitFieldSchema>> {
+export interface Logger {
     /**
      * Log a message.
      */
     log(message: string): void;
-    /**
-     * Optional function to override the default tree stringification (JSON) when logging tree state.
-     */
-    treeToString?(tree: TTree): string;
 }
 /**
  * Options used to parameterize the creation of a {@link SharedTreeSemanticAgent}.
  * @alpha
  */
-export interface SemanticAgentOptions<TSchema extends ImplicitFieldSchema> {
+export interface SemanticAgentOptions {
+    /**
+     * Additional information about the application domain that will be included in the context provided to the {@link SharedTreeChatModel | model}.
+     */
     domainHints?: string;
-    validator?: (js: string) => boolean;
+    /**
+     * 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 (executes) 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 evaluating 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.
+     * Use a library such as SES to provide a more secure implementation - see {@link createSesEditEvaluator} for a drop-in option.
+     */
+    executeEdit?: (context: Record<string, unknown>, code: string) => void | Promise<void>;
     /**
      * The maximum number of sequential edits the LLM can make before we assume it's stuck in a loop.
      */
     maximumSequentialEdits?: number;
-    logger?: Logger<ReadableField<TSchema>>;
+    /**
+     * If supplied, generates human-readable markdown text describing the actions taken by the {@link SharedTreeSemanticAgent | agent} as it performs queries.
+     */
+    logger?: Logger;
 }
 /**
  * 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.editFunctionName} was not provided).
- * - `validationError`: The provided JavaScript did not pass the optional {@link SemanticAgentOptions.validator} function.
- * - `compileError`: The provided JavaScript could not be parsed or compiled.
- * - `runtimeError`: An error was thrown while executing the provided JavaScript.
+ * - `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" | "compileError" | "runtimeError" | "tooManyEditsError" | "expiredError";
+    type: "success" | "disabledError" | "validationError" | "executionError" | "tooManyEditsError" | "expiredError";
     /**
      * A human-readable message describing the result of the edit attempt.
      * @remarks In the case of an error, this message is appropriate to include in a model's chat history.
@@ -73,6 +90,7 @@ export interface SharedTreeChatQuery {
 }
 /**
  * A plugin interface that handles queries from a {@link SharedTreeSemanticAgent}.
+ * @remarks This wraps an underlying communication with an LLM and receives all necessary {@link SharedTreeChatModel.appendContext | context} from the {@link SharedTreeSemanticAgent | agent} for the LLM to properly analyze and edit the tree.
  * @alpha
  */
 export interface SharedTreeChatModel {
@@ -83,18 +101,18 @@ export interface SharedTreeChatModel {
      */
     name?: string;
     /**
-     * The name of the tool that the model should use to edit the tree, if any.
-     * @remarks If supplied, this will be mentioned in the context provided to the model and the model will be encouraged to use it when a user query requires an edit.
+     * The name of the tool that the model should use to edit the tree.
+     * @remarks If supplied, this will be mentioned in the context provided to the model so that the underlying LLM will be encouraged to use it when a user query requires an edit.
+     * The model should "implement" the tool by registering it with the underlying LLM API.
+     * The tool should take an LLM-generated JavaScript function as input and supply it to the {@link SharedTreeChatQuery.edit | edit} function.
+     * Instructions for generating the proper function signature and implementation will be provided by the {@link SharedTreeSemanticAgent | agent} via {@link SharedTreeChatModel.appendContext | context}.
+     * If not supplied, the model will not be able to edit the tree (running the {@link SharedTreeChatQuery.edit | edit} function will fail).
      */
     editToolName?: string;
-    /**
-     * The name of the function that the model should generate to edit the tree.
-     * @remarks If not supplied, the model will not be allowed to edit the tree.
-     */
-    editFunctionName?: string;
     /**
      * Add contextual information to the model that may be relevant to future queries.
      * @remarks In practice, this may be implemented by e.g. appending a "system" message to an LLM's chat/message history.
+     * This context must be present in the context window of every {@link SharedTreeChatModel.query | query} for e.g. {@link SharedTreeChatModel.editToolName | editing} to work.
      * @param text - The message or context to append.
      */
     appendContext?(text: string): void;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,MAAM,CACtB,KAAK,SAAS,aAAa,CAAC,mBAAmB,CAAC,GAAG,aAAa,CAAC,mBAAmB,CAAC;IAErF;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;OAEG;IACH,YAAY,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,mBAAmB;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EACD,SAAS,GACT,eAAe,GACf,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,mBAAmB,GACnB,cAAc,CAAC;IAElB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAQhE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,SAAS,mBAAmB,IAAI,CAAC,EAChE,IAAI,EACJ,MAAM,GACN,EAAE;IACF,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,QAAQ,CAAC,CAAC;CAClE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,MAAM;IACtB;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EACD,SAAS,GACT,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAChB,mBAAmB,GACnB,cAAc,CAAC;IAElB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAQhE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,SAAS,mBAAmB,IAAI,CAAC,EAChE,IAAI,EACJ,MAAM,GACN,EAAE;IACF,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,QAAQ,CAAC,CAAC;CAClE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiEH;;GAEG;AACH,SAAgB,YAAY,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,CACN,OAAQ,KAAoB,CAAC,IAAI,KAAK,QAAQ;QAC9C,OAAQ,KAAoB,CAAC,OAAO,KAAK,QAAQ,CACjD,CAAC;AACH,CAAC;AARD,oCAQC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ImplicitFieldSchema, TreeNode } from \"@fluidframework/tree\";\nimport type { FactoryContentObject, ReadableField } from \"@fluidframework/tree/alpha\";\n\n/**\n * Logger interface for logging events from a {@link SharedTreeSemanticAgent}.\n * @alpha\n */\nexport interface Logger<\n\tTTree extends ReadableField<ImplicitFieldSchema> = ReadableField<ImplicitFieldSchema>,\n> {\n\t/**\n\t * Log a message.\n\t */\n\tlog(message: string): void;\n\t/**\n\t * Optional function to override the default tree stringification (JSON) when logging tree state.\n\t */\n\ttreeToString?(tree: TTree): string;\n}\n\n/**\n * Options used to parameterize the creation of a {@link SharedTreeSemanticAgent}.\n * @alpha\n */\nexport interface SemanticAgentOptions<TSchema extends ImplicitFieldSchema> {\n\tdomainHints?: string;\n\tvalidator?: (js: string) => boolean;\n\t/**\n\t * The maximum number of sequential edits the LLM can make before we assume it's stuck in a loop.\n\t */\n\tmaximumSequentialEdits?: number;\n\tlogger?: Logger<ReadableField<TSchema>>;\n}\n\n/**\n * A result from an edit attempt via the {@link SharedTreeChatQuery.edit} function.\n * @remarks\n * - `success`: The edit was successfully applied.\n * - `disabledError`: The model is not allowed to edit the tree (i.e. {@link SharedTreeChatModel.editFunctionName} was not provided).\n * - `validationError`: The provided JavaScript did not pass the optional {@link SemanticAgentOptions.validator} function.\n * - `compileError`: The provided JavaScript could not be parsed or compiled.\n * - `runtimeError`: An error was thrown while executing the provided JavaScript.\n * - `tooManyEditsError`: The {@link SharedTreeChatQuery.edit} function has been called more than the number of times specified by {@link SemanticAgentOptions.maximumSequentialEdits} for the same message.\n * - `expiredError`: The {@link SharedTreeChatQuery.edit} function was called after the issuing query has already completed.\n * @alpha\n */\nexport interface EditResult {\n\ttype:\n\t\t| \"success\"\n\t\t| \"disabledError\"\n\t\t| \"validationError\"\n\t\t| \"compileError\"\n\t\t| \"runtimeError\"\n\t\t| \"tooManyEditsError\"\n\t\t| \"expiredError\";\n\n\t/**\n\t * A human-readable message describing the result of the edit attempt.\n\t * @remarks In the case of an error, this message is appropriate to include in a model's chat history.\n\t */\n\tmessage: string;\n}\n\n/**\n * Type guard for {@link EditResult}.\n */\nexport function isEditResult(value: unknown): value is EditResult {\n\tif (value === null || typeof value !== \"object\") {\n\t\treturn false;\n\t}\n\treturn (\n\t\ttypeof (value as EditResult).type === \"string\" &&\n\t\ttypeof (value as EditResult).message === \"string\"\n\t);\n}\n\n/**\n * A query from a user to a {@link SharedTreeSemanticAgent}.\n * @remarks Processing a query may involve editing the SharedTree via the provided {@link SharedTreeChatQuery.edit} function.\n * @alpha\n */\nexport interface SharedTreeChatQuery {\n\t/**\n\t * The user's query.\n\t */\n\ttext: string;\n\t/**\n\t * Edit the tree with the provided JavaScript function code.\n\t * @remarks Attempting an edit may fail for a variety of reasons which are captured in the {@link EditResult | returned object}.\n\t */\n\tedit(js: string): Promise<EditResult>;\n}\n\n/**\n * A plugin interface that handles queries from a {@link SharedTreeSemanticAgent}.\n * @alpha\n */\nexport interface SharedTreeChatModel {\n\t/**\n\t * A optional name of this chat model.\n\t * @remarks If supplied, this may be used in logging or debugging information.\n\t * @example \"gpt-5\"\n\t */\n\tname?: string;\n\t/**\n\t * The name of the tool that the model should use to edit the tree, if any.\n\t * @remarks If supplied, this will be mentioned in the context provided to the model and the model will be encouraged to use it when a user query requires an edit.\n\t */\n\teditToolName?: string;\n\t/**\n\t * The name of the function that the model should generate to edit the tree.\n\t * @remarks If not supplied, the model will not be allowed to edit the tree.\n\t */\n\teditFunctionName?: string;\n\t/**\n\t * Add contextual information to the model that may be relevant to future queries.\n\t * @remarks In practice, this may be implemented by e.g. appending a \"system\" message to an LLM's chat/message history.\n\t * @param text - The message or context to append.\n\t */\n\tappendContext?(text: string): void;\n\t/**\n\t * Queries the chat model with a request from the user.\n\t * @remarks This model may simply return a text response to the query, or it may first call the {@link SharedTreeChatQuery.edit} function (potentially multiple times) to modify the tree in response to the query.\n\t */\n\tquery(message: SharedTreeChatQuery): Promise<string>;\n}\n\n/**\n * A function that edits a SharedTree.\n */\nexport type EditFunction<TSchema extends ImplicitFieldSchema> = ({\n\troot,\n\tcreate,\n}: {\n\troot: ReadableField<TSchema>;\n\tcreate: Record<string, (input: FactoryContentObject) => TreeNode>;\n}) => void | Promise<void>;\n"]}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAgFH;;GAEG;AACH,SAAgB,YAAY,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,CACN,OAAQ,KAAoB,CAAC,IAAI,KAAK,QAAQ;QAC9C,OAAQ,KAAoB,CAAC,OAAO,KAAK,QAAQ,CACjD,CAAC;AACH,CAAC;AARD,oCAQC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ImplicitFieldSchema, TreeNode } from \"@fluidframework/tree\";\n// This is used for doc links\nimport type { FactoryContentObject, ReadableField } from \"@fluidframework/tree/alpha\";\n\n/**\n * Logger interface for logging events from a {@link SharedTreeSemanticAgent}.\n * @alpha\n */\nexport interface Logger {\n\t/**\n\t * Log a message.\n\t */\n\tlog(message: string): void;\n}\n\n/**\n * Options used to parameterize the creation of a {@link SharedTreeSemanticAgent}.\n * @alpha\n */\nexport interface SemanticAgentOptions {\n\t/**\n\t * Additional information about the application domain that will be included in the context provided to the {@link SharedTreeChatModel | model}.\n\t */\n\tdomainHints?: string;\n\t/**\n\t * Validates any generated JavaScript created by the {@link SharedTreeChatModel.editToolName | model's editing tool}.\n\t * @remarks This happens before the code is executed - execution can be intercepted by using the {@link SemanticAgentOptions.executeEdit | executeEdit} callback.\n\t * @param code - The generated JavaScript code as a string.\n\t * @throws If the code is invalid, this function should throw an error with a human-readable message describing why it is invalid.\n\t */\n\tvalidateEdit?: (code: string) => void | Promise<void>;\n\t/**\n\t * Evaluates (executes) any generated JavaScript created by the {@link SharedTreeChatModel.editToolName | model's editing tool}.\n\t * @remarks This happens only after the code has been successfully validated by the optional {@link SemanticAgentOptions.validateEdit | validateEdit} function.\n\t * @param context - An object that must be provided to the generated code as a variable named \"context\" in its top-level scope.\n\t * @param code - The generated JavaScript code as a string.\n\t * @throws If an error is thrown while evaluating the code, it will be caught and the message will be forwarded to the model for debugging.\n\t * @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.\n\t * Use a library such as SES to provide a more secure implementation - see {@link createSesEditEvaluator} for a drop-in option.\n\t */\n\texecuteEdit?: (context: Record<string, unknown>, code: string) => void | Promise<void>;\n\t/**\n\t * The maximum number of sequential edits the LLM can make before we assume it's stuck in a loop.\n\t */\n\tmaximumSequentialEdits?: number;\n\t/**\n\t * If supplied, generates human-readable markdown text describing the actions taken by the {@link SharedTreeSemanticAgent | agent} as it performs queries.\n\t */\n\tlogger?: Logger;\n}\n\n/**\n * A result from an edit attempt via the {@link SharedTreeChatQuery.edit} function.\n * @remarks\n * - `success`: The edit was successfully applied.\n * - `disabledError`: The model is not allowed to edit the tree (i.e. {@link SharedTreeChatModel.editToolName} was not provided).\n * - `validationError`: The provided JavaScript did not pass the optional {@link SemanticAgentOptions.validateEdit} function.\n * - `executionError`: An error was thrown while parsing or executing the provided JavaScript.\n * - `tooManyEditsError`: The {@link SharedTreeChatQuery.edit} function has been called more than the number of times specified by {@link SemanticAgentOptions.maximumSequentialEdits} for the same message.\n * - `expiredError`: The {@link SharedTreeChatQuery.edit} function was called after the issuing query has already completed.\n * @alpha\n */\nexport interface EditResult {\n\ttype:\n\t\t| \"success\"\n\t\t| \"disabledError\"\n\t\t| \"validationError\"\n\t\t| \"executionError\"\n\t\t| \"tooManyEditsError\"\n\t\t| \"expiredError\";\n\n\t/**\n\t * A human-readable message describing the result of the edit attempt.\n\t * @remarks In the case of an error, this message is appropriate to include in a model's chat history.\n\t */\n\tmessage: string;\n}\n\n/**\n * Type guard for {@link EditResult}.\n */\nexport function isEditResult(value: unknown): value is EditResult {\n\tif (value === null || typeof value !== \"object\") {\n\t\treturn false;\n\t}\n\treturn (\n\t\ttypeof (value as EditResult).type === \"string\" &&\n\t\ttypeof (value as EditResult).message === \"string\"\n\t);\n}\n\n/**\n * A query from a user to a {@link SharedTreeSemanticAgent}.\n * @remarks Processing a query may involve editing the SharedTree via the provided {@link SharedTreeChatQuery.edit} function.\n * @alpha\n */\nexport interface SharedTreeChatQuery {\n\t/**\n\t * The user's query.\n\t */\n\ttext: string;\n\t/**\n\t * Edit the tree with the provided JavaScript function code.\n\t * @remarks Attempting an edit may fail for a variety of reasons which are captured in the {@link EditResult | returned object}.\n\t */\n\tedit(js: string): Promise<EditResult>;\n}\n\n/**\n * A plugin interface that handles queries from a {@link SharedTreeSemanticAgent}.\n * @remarks This wraps an underlying communication with an LLM and receives all necessary {@link SharedTreeChatModel.appendContext | context} from the {@link SharedTreeSemanticAgent | agent} for the LLM to properly analyze and edit the tree.\n * @alpha\n */\nexport interface SharedTreeChatModel {\n\t/**\n\t * A optional name of this chat model.\n\t * @remarks If supplied, this may be used in logging or debugging information.\n\t * @example \"gpt-5\"\n\t */\n\tname?: string;\n\t/**\n\t * The name of the tool that the model should use to edit the tree.\n\t * @remarks If supplied, this will be mentioned in the context provided to the model so that the underlying LLM will be encouraged to use it when a user query requires an edit.\n\t * The model should \"implement\" the tool by registering it with the underlying LLM API.\n\t * The tool should take an LLM-generated JavaScript function as input and supply it to the {@link SharedTreeChatQuery.edit | edit} function.\n\t * Instructions for generating the proper function signature and implementation will be provided by the {@link SharedTreeSemanticAgent | agent} via {@link SharedTreeChatModel.appendContext | context}.\n\t * If not supplied, the model will not be able to edit the tree (running the {@link SharedTreeChatQuery.edit | edit} function will fail).\n\t */\n\teditToolName?: string;\n\t/**\n\t * Add contextual information to the model that may be relevant to future queries.\n\t * @remarks In practice, this may be implemented by e.g. appending a \"system\" message to an LLM's chat/message history.\n\t * This context must be present in the context window of every {@link SharedTreeChatModel.query | query} for e.g. {@link SharedTreeChatModel.editToolName | editing} to work.\n\t * @param text - The message or context to append.\n\t */\n\tappendContext?(text: string): void;\n\t/**\n\t * Queries the chat model with a request from the user.\n\t * @remarks This model may simply return a text response to the query, or it may first call the {@link SharedTreeChatQuery.edit} function (potentially multiple times) to modify the tree in response to the query.\n\t */\n\tquery(message: SharedTreeChatQuery): Promise<string>;\n}\n\n/**\n * A function that edits a SharedTree.\n */\nexport type EditFunction<TSchema extends ImplicitFieldSchema> = ({\n\troot,\n\tcreate,\n}: {\n\troot: ReadableField<TSchema>;\n\tcreate: Record<string, (input: FactoryContentObject) => TreeNode>;\n}) => void | Promise<void>;\n"]}

package/dist/index.d.ts

@@ -7,9 +7,10 @@
  *
  * @packageDocumentation
  */
-export type { SharedTreeSemanticAgent } from "./agent.js";
+export { SharedTreeSemanticAgent } from "./agent.js";
 export type { EditResult, SharedTreeChatModel, SharedTreeChatQuery, Logger, SemanticAgentOptions, } from "./api.js";
 export { type TreeView, llmDefault } from "./utils.js";
 export { buildFunc, exposeMethodsSymbol, type ArgsTuple, type ExposedMethods, type Arg, type FunctionDef, type MethodKeys, type BindableSchema, type Ctor, type Infer, type IExposedMethods, } from "./methodBinding.js";
 export { LangchainChatModel, createSemanticAgent } from "./langchain.js";
+export { createSesEditEvaluator } from "./ses.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,YAAY,EACX,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,MAAM,EACN,oBAAoB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EACN,SAAS,EACT,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,eAAe,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EACX,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,MAAM,EACN,oBAAoB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EACN,SAAS,EACT,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,eAAe,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -4,7 +4,14 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSemanticAgent = exports.LangchainChatModel = exports.exposeMethodsSymbol = exports.buildFunc = exports.llmDefault = void 0;
+exports.createSesEditEvaluator = exports.createSemanticAgent = exports.LangchainChatModel = exports.exposeMethodsSymbol = exports.buildFunc = exports.llmDefault = exports.SharedTreeSemanticAgent = void 0;
+/**
+ * A library for creating AI agents to interact with a {@link SharedTree | https://fluidframework.com/docs/data-structures/tree/}.
+ *
+ * @packageDocumentation
+ */
+var agent_js_1 = require("./agent.js");
+Object.defineProperty(exports, "SharedTreeSemanticAgent", { enumerable: true, get: function () { return agent_js_1.SharedTreeSemanticAgent; } });
 var utils_js_1 = require("./utils.js");
 Object.defineProperty(exports, "llmDefault", { enumerable: true, get: function () { return utils_js_1.llmDefault; } });
 var methodBinding_js_1 = require("./methodBinding.js");
@@ -13,4 +20,6 @@ Object.defineProperty(exports, "exposeMethodsSymbol", { enumerable: true, get: f
 var langchain_js_1 = require("./langchain.js");
 Object.defineProperty(exports, "LangchainChatModel", { enumerable: true, get: function () { return langchain_js_1.LangchainChatModel; } });
 Object.defineProperty(exports, "createSemanticAgent", { enumerable: true, get: function () { return langchain_js_1.createSemanticAgent; } });
+var ses_js_1 = require("./ses.js");
+Object.defineProperty(exports, "createSesEditEvaluator", { enumerable: true, get: function () { return ses_js_1.createSesEditEvaluator; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAgBH,uCAAuD;AAA/B,sGAAA,UAAU,OAAA;AAClC,uDAY4B;AAX3B,6GAAA,SAAS,OAAA;AACT,uHAAA,mBAAmB,OAAA;AAWpB,+CAAyE;AAAhE,kHAAA,kBAAkB,OAAA;AAAE,mHAAA,mBAAmB,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A library for creating AI agents to interact with a {@link SharedTree | https://fluidframework.com/docs/data-structures/tree/}.\n *\n * @packageDocumentation\n */\n\nexport type { SharedTreeSemanticAgent } from \"./agent.js\";\nexport type {\n\tEditResult,\n\tSharedTreeChatModel,\n\tSharedTreeChatQuery,\n\tLogger,\n\tSemanticAgentOptions,\n} from \"./api.js\";\nexport { type TreeView, llmDefault } from \"./utils.js\";\nexport {\n\tbuildFunc,\n\texposeMethodsSymbol,\n\ttype ArgsTuple,\n\ttype ExposedMethods,\n\ttype Arg,\n\ttype FunctionDef,\n\ttype MethodKeys,\n\ttype BindableSchema,\n\ttype Ctor,\n\ttype Infer,\n\ttype IExposedMethods,\n} from \"./methodBinding.js\";\nexport { LangchainChatModel, createSemanticAgent } from \"./langchain.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;GAIG;AAEH,uCAAqD;AAA5C,mHAAA,uBAAuB,OAAA;AAQhC,uCAAuD;AAA/B,sGAAA,UAAU,OAAA;AAClC,uDAY4B;AAX3B,6GAAA,SAAS,OAAA;AACT,uHAAA,mBAAmB,OAAA;AAWpB,+CAAyE;AAAhE,kHAAA,kBAAkB,OAAA;AAAE,mHAAA,mBAAmB,OAAA;AAChD,mCAAkD;AAAzC,gHAAA,sBAAsB,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A library for creating AI agents to interact with a {@link SharedTree | https://fluidframework.com/docs/data-structures/tree/}.\n *\n * @packageDocumentation\n */\n\nexport { SharedTreeSemanticAgent } from \"./agent.js\";\nexport type {\n\tEditResult,\n\tSharedTreeChatModel,\n\tSharedTreeChatQuery,\n\tLogger,\n\tSemanticAgentOptions,\n} from \"./api.js\";\nexport { type TreeView, llmDefault } from \"./utils.js\";\nexport {\n\tbuildFunc,\n\texposeMethodsSymbol,\n\ttype ArgsTuple,\n\ttype ExposedMethods,\n\ttype Arg,\n\ttype FunctionDef,\n\ttype MethodKeys,\n\ttype BindableSchema,\n\ttype Ctor,\n\ttype Infer,\n\ttype IExposedMethods,\n} from \"./methodBinding.js\";\nexport { LangchainChatModel, createSemanticAgent } from \"./langchain.js\";\nexport { createSesEditEvaluator } from \"./ses.js\";\n"]}

package/dist/langchain.d.ts

@@ -17,7 +17,6 @@ export declare class LangchainChatModel implements SharedTreeChatModel {
     private readonly messages;
     constructor(model: BaseChatModel);
     readonly editToolName = "GenerateTreeEditingCode";
-    readonly editFunctionName = "editTree";
     get name(): string | undefined;
     appendContext(text: string): void;
     query(query: SharedTreeChatQuery): Promise<string>;
@@ -28,17 +27,17 @@ export declare class LangchainChatModel implements SharedTreeChatModel {
  * @alpha
  * @deprecated Use {@link SharedTreeSemanticAgent} with a {@link LangchainChatModel} instead.
  */
-export declare function createSemanticAgent<TSchema extends ImplicitFieldSchema>(client: BaseChatModel, treeView: TreeView<TSchema>, options?: Readonly<SemanticAgentOptions<TSchema>>): SharedTreeSemanticAgent<TSchema>;
+export declare function createSemanticAgent<TSchema extends ImplicitFieldSchema>(client: BaseChatModel, treeView: TreeView<TSchema>, options?: Readonly<SemanticAgentOptions>): SharedTreeSemanticAgent<TSchema>;
 /**
  * Create a {@link SharedTreeSemanticAgent} using a Langchain chat model.
  * @alpha
  * @deprecated Use {@link SharedTreeSemanticAgent} with a {@link LangchainChatModel} instead.
  */
-export declare function createSemanticAgent<TSchema extends ImplicitFieldSchema>(client: BaseChatModel, node: ReadableField<TSchema> & TreeNode, options?: Readonly<SemanticAgentOptions<TSchema>>): SharedTreeSemanticAgent<TSchema>;
+export declare function createSemanticAgent<TSchema extends ImplicitFieldSchema>(client: BaseChatModel, node: ReadableField<TSchema> & TreeNode, options?: Readonly<SemanticAgentOptions>): SharedTreeSemanticAgent<TSchema>;
 /**
  * Create a {@link SharedTreeSemanticAgent} using a Langchain chat model.
  * @alpha
  * @deprecated Use {@link SharedTreeSemanticAgent} with a {@link LangchainChatModel} instead.
  */
-export declare function createSemanticAgent<TSchema extends ImplicitFieldSchema>(client: BaseChatModel, treeView: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode), options?: Readonly<SemanticAgentOptions<TSchema>>): SharedTreeSemanticAgent<TSchema>;
+export declare function createSemanticAgent<TSchema extends ImplicitFieldSchema>(client: BaseChatModel, treeView: TreeView<TSchema> | (ReadableField<TSchema> & TreeNode), options?: Readonly<SemanticAgentOptions>): SharedTreeSemanticAgent<TSchema>;
 //# sourceMappingURL=langchain.d.ts.map

package/dist/langchain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../src/langchain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAYjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAE1C,OAAO,CAAC,QAAQ,CAAC,KAAK;IADzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;gBACvC,KAAK,EAAE,aAAa;IAExD,SAAgB,YAAY,6BAA6B;IACzD,SAAgB,gBAAgB,cAAc;IAE9C,IAAW,IAAI,IAAI,MAAM,GAAG,SAAS,CAGpC;IAEM,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;YAKjD,SAAS;CA4CvB;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,mBAAmB,EACtE,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,GAC/C,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACpC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,mBAAmB,EACtE,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,EACvC,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,GAC/C,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACpC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,mBAAmB,EACtE,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,EACjE,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,GAC/C,uBAAuB,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../src/langchain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAYjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAE1C,OAAO,CAAC,QAAQ,CAAC,KAAK;IADzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;gBACvC,KAAK,EAAE,aAAa;IAExD,SAAgB,YAAY,6BAA6B;IAEzD,IAAW,IAAI,IAAI,MAAM,GAAG,SAAS,CAGpC;IAEM,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;YAKjD,SAAS;CA2CvB;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,mBAAmB,EACtE,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GACtC,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACpC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,mBAAmB,EACtE,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,EACvC,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GACtC,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACpC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,mBAAmB,EACtE,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,EACjE,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GACtC,uBAAuB,CAAC,OAAO,CAAC,CAAC"}