Example agents, bug fixes (#566)

Example external agents:
* echo: Improved echo example
* measures: Track user measurements in a sqlite database ; first cut
* Improved documentation
* Better handling of Bing errors

ts/examples/agentExamples/echo/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

ts/examples/agentExamples/echo/README.md

@@ -0,0 +1,11 @@
+# Echo Agent
+
+The Echo Agent demonstrates how to use the [agent-sdk](../../../packages/agentSdk/ExternalAgents_README.md) to write agents as installable packages.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

ts/examples/agentExamples/echo/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "echo",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Echo example for TypeAgent",
+  "homepage": "https://github.com/microsoft/TypeAgent#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/TypeAgent.git",
+    "directory": "ts/examples/agentExamples/echo"
+  },
+  "license": "MIT",
+  "author": "Microsoft",
+  "type": "module",
+  "exports": {
+    "./agent/handlers": "./dist/echoActionHandler.js",
+    "./agent/manifest": "./dist/echoManifest.json"
+  },
+  "scripts": {
+    "build": "npm run tsc",
+    "postbuild": "copyfiles -u 1 \"src/**/*Schema*.ts\" \"src/**/*Manifest*.json\" dist",
+    "clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log",
+    "prettier": "prettier --check . --ignore-path ../../../.prettierignore",
+    "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore",
+    "tsc": "tsc -b"
+  },
+  "dependencies": {
+    "@typeagent/agent-sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "copyfiles": "^2.4.1",
+    "prettier": "^3.2.5",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.2"
+  }
+}

ts/examples/agentExamples/echo/src/echoActionHandler.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+    ActionContext,
+    AppAction,
+    AppAgent,
+    SessionContext,
+    ActionResult,
+} from "@typeagent/agent-sdk";
+import {
+    createActionResultFromTextDisplay,
+    createActionResultFromError,
+} from "@typeagent/agent-sdk/helpers/action";
+
+import { EchoAction } from "./echoActionsSchema.js";
+
+export function instantiate(): AppAgent {
+    return {
+        initializeAgentContext: initializeEchoContext,
+        updateAgentContext: updateEchoContext,
+        executeAction: executeEchoAction,
+    };
+}
+
+type EchoActionContext = {
+    echoCount: number;
+    echoRequests: Set<string> | undefined;
+};
+
+async function initializeEchoContext() {
+    return {
+        echoCount: 0,
+        echoRequests: undefined,
+    };
+}
+
+async function updateEchoContext(
+    enable: boolean,
+    context: SessionContext<EchoActionContext>,
+): Promise<void> {
+    if (enable) {
+        context.agentContext.echoRequests = new Set<string>();
+        context.agentContext.echoCount = 0;
+    }
+    context.agentContext.echoCount++;
+}
+
+async function executeEchoAction(
+    action: AppAction,
+    context: ActionContext<EchoActionContext>,
+) {
+    let result = await handleEchoAction(
+        action as EchoAction,
+        context.sessionContext.agentContext,
+    );
+    return result;
+}
+
+async function handleEchoAction(
+    action: EchoAction,
+    echoContext: EchoActionContext,
+) {
+    let result: ActionResult | undefined = undefined;
+    let displayText: string | undefined = undefined;
+    switch (action.actionName) {
+        case "echoGen":
+            displayText = `>> Echo: ${action.parameters.text}`;
+            result = createActionResultFromTextDisplay(
+                displayText,
+                displayText,
+            );
+            break;
+        default:
+            result = createActionResultFromError(
+                "Unable to process the action",
+            );
+            break;
+    }
+    return result;
+}

ts/examples/agentExamples/echo/src/echoActionsSchema.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export type EchoAction = GenEchoAction;
+
+// If the user asks to echo a message back, the system will return a GenEchoAction. The text parameter is the message to be echoed back.
+// will contain the text to be echoed back to the user.
+export type GenEchoAction = {
+    actionName: "echoGen";
+    parameters: {
+        text?: string;
+        // Generate an alternate response based on the request
+        altResponse?: string;
+    };
+};

ts/examples/agentExamples/echo/src/echoManifest.json

@@ -0,0 +1,8 @@
+{
+  "emojiChar": "🦜",
+  "schema": {
+    "description": "A basic echo agent.",
+    "schemaFile": "echoActionsSchema.ts",
+    "schemaType": "EchoAction"
+  }
+}

ts/examples/agentExamples/echo/src/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": ".",
+    "outDir": "../dist"
+  },
+  "ts-node": {
+    "esm": true
+  }
+}

ts/examples/agentExamples/echo/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+  },
+  "include": [],
+  "references": [
+    { "path": "./src" },
+  ],
+  "ts-node": {
+    "esm": true
+  }
+}

ts/examples/agentExamples/measure/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

ts/examples/agentExamples/measure/README.md

@@ -0,0 +1,17 @@
+# Measure
+
+Measure is an example agent that implements actions to add and search a database of measurements. Examples: steps, pushups. cups of coffee, etc. Data is stored in a sqlite database.
+
+Work in progress.
+
+## Installation
+
+- Follow the standard exteneral [Agent installation steps](../../../packages/agentSdk/ExternalAgents_README.md#install_agent)
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

ts/examples/agentExamples/measure/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "measure",
+  "version": "0.0.1",
+  "description": "Measure is an agent that maintains a simple database of measurements.",
+  "homepage": "https://github.com/microsoft/TypeAgent#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/TypeAgent.git",
+    "directory": "ts/examples/agentExamples/measure"
+  },
+  "license": "MIT",
+  "author": "Microsoft",
+  "type": "module",
+  "exports": {
+    "./agent/manifest": "./dist/measureManifest.json",
+    "./agent/handlers": "./dist/measureActionHandler.js"
+  },
+  "scripts": {
+    "build": "npm run tsc",
+    "postbuild": "copyfiles -u 1 \"src/**/*Schema*.ts\" \"src/**/*Manifest*.json\" dist",
+    "clean": "rimraf --glob dist *.tsbuildinfo *.done.build.log",
+    "prettier": "prettier --check . --ignore-path ../../../.prettierignore",
+    "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore",
+    "tsc": "tsc -b"
+  },
+  "dependencies": {
+    "@typeagent/agent-sdk": "workspace:*",
+    "better-sqlite3": "11.5.0",
+    "typeagent": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.11",
+    "copyfiles": "^2.4.1",
+    "prettier": "^3.2.5",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.2"
+  }
+}

ts/examples/agentExamples/measure/src/database.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import Database, * as sqlite from "better-sqlite3";
+import { removeFile } from "typeagent";
+
+export async function createDatabase(
+    filePath: string,
+    createNew: boolean,
+): Promise<sqlite.Database> {
+    if (createNew) {
+        await deleteDatabase(filePath);
+    }
+    const db = new Database(filePath);
+    db.pragma("journal_mode = WAL");
+    return db;
+}
+
+async function deleteDatabase(filePath: string): Promise<void> {
+    await removeFile(filePath);
+    await removeFile(filePath + "-shm");
+    await removeFile(filePath + "-wal");
+}
+
+export function sql_makeInClause(values: any[]): string {
+    let sql = "";
+    for (let i = 0; i < values.length; ++i) {
+        if (i > 0) {
+            sql += ", ";
+        }
+        sql += `'${values[i]}'`;
+    }
+    return sql;
+}
+
+export function sql_appendCondition(
+    sql: string,
+    condition: string,
+    and: boolean = true,
+) {
+    if (sql) {
+        sql += and ? " AND " : " OR ";
+    }
+    sql += condition;
+    sql += "\n";
+    return sql;
+}