From f4af000d42a912dca003fcbf24c93e3b68e9ae2b Mon Sep 17 00:00:00 2001 From: TypeAgent-Bot Date: Fri, 3 Jul 2026 09:09:11 +0000 Subject: [PATCH] docs: regenerate package README.AUTOGEN.md files (2026-07-03) Automated by the docs-generate workflow. AI body authored via GitHub Models; deterministic Reference computed from source. 19 file(s) updated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../agentServer/client/README.AUTOGEN.md | 112 +++++++++----- .../agentServer/protocol/README.AUTOGEN.md | 97 ++++++------ .../agentServer/server/README.AUTOGEN.md | 90 +++++++---- .../agentUtils/graphUtils/README.AUTOGEN.md | 62 ++++---- ts/packages/agents/browser/README.AUTOGEN.md | 103 +++++++------ ts/packages/agents/desktop/README.AUTOGEN.md | 143 ++++++++++++------ ts/packages/agents/list/README.AUTOGEN.md | 56 +++---- ts/packages/agents/montage/README.AUTOGEN.md | 69 ++++++--- .../agents/screencapture/README.AUTOGEN.md | 91 ++++++----- ts/packages/aiclient/README.AUTOGEN.md | 75 ++++----- ts/packages/chat-ui/README.AUTOGEN.md | 83 +++++----- ts/packages/config/README.AUTOGEN.md | 62 ++++---- .../dispatcher/dispatcher/README.AUTOGEN.md | 119 ++++++++++----- ts/packages/knowPro/README.AUTOGEN.md | 88 ++++++++--- .../knowledgeProcessor/README.AUTOGEN.md | 88 ++++++++--- .../memory/conversation/README.AUTOGEN.md | 68 +++++---- ts/packages/memory/image/README.AUTOGEN.md | 110 ++++++++++---- ts/packages/typeagent/README.AUTOGEN.md | 56 +++---- ts/packages/vscode-shell/README.AUTOGEN.md | 8 +- 19 files changed, 964 insertions(+), 616 deletions(-) diff --git a/ts/packages/agentServer/client/README.AUTOGEN.md b/ts/packages/agentServer/client/README.AUTOGEN.md index 63af87fce..2ae1e0c5b 100644 --- a/ts/packages/agentServer/client/README.AUTOGEN.md +++ b/ts/packages/agentServer/client/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/agent-server-client — AI-generated documentation @@ -12,58 +12,84 @@ ## Overview -The `@typeagent/agent-server-client` package is a TypeScript library designed to facilitate connections to a running agentServer. It is used by various components such as the Shell and CLI to manage conversations and ensure the server is running. +The `@typeagent/agent-server-client` package is a TypeScript library that provides tools for connecting to and interacting with a running `agentServer`. It is a core component of the TypeAgent ecosystem, enabling clients such as the Shell, CLI, and other integrations to manage conversations and ensure the availability of the agentServer. ## What it does -This package provides several key functionalities for interacting with an agentServer: +This package offers a comprehensive set of features for managing connections and interactions with an `agentServer`. Key functionalities include: -- **Connection Management**: Establishes WebSocket connections to the agentServer using `connectAgentServer`. -- **Conversation Management**: Supports creating, listing, renaming, and deleting conversations through methods on the `AgentServerConnection` object. -- **Server Management**: Ensures the agentServer is running, spawns it if necessary, and checks its status using functions like `ensureAgentServer` and `isServerRunning`. -- **Convenience Wrappers**: Provides simplified methods to ensure the server is running and connect to conversations in one call, such as `ensureAndConnectConversation`. +- **Connection Management**: The `connectAgentServer` function establishes WebSocket connections to an `agentServer` and provides an `AgentServerConnection` object for further interaction. +- **Conversation Management**: The `AgentServerConnection` object supports operations such as creating, listing, renaming, and deleting conversations. It also allows clients to join and leave conversations. +- **Server Lifecycle Management**: Functions like `ensureAgentServer` and `stopAgentServer` allow clients to ensure the server is running, spawn it if necessary, and shut it down when no longer needed. +- **Port Discovery**: The `discovery` module provides utilities for discovering the dynamically assigned port of an in-process agent. +- **Convenience Wrappers**: Functions like `ensureAndConnectConversation` simplify common workflows by combining server management, connection, and conversation joining into a single call. + +This package is used by various other components in the TypeAgent ecosystem, including the CLI, Shell, and browser-based clients. ## Setup -To use this package, you need to install it along with its dependencies. Ensure you have the following environment variables and prerequisites set up: +To use this package, you need to configure the following: -- **Environment Variables**: None required specifically for this package. -- **Dependencies**: Install the required dependencies using `pnpm install`. This package depends on other TypeAgent packages such as `@typeagent/agent-rpc`, `@typeagent/agent-server-protocol`, and `@typeagent/dispatcher-rpc`. +### Environment Variables -For detailed setup instructions, see the hand-written README. +- `TYPEAGENT_TUNNEL_TOKEN`: This token is required for secure communication with the agentServer. Refer to the hand-written README for details on how to obtain and configure this token. -## Key Files +### Installation + +Install the package and its dependencies using `pnpm`: -The package is structured into several key files: +```bash +pnpm install +``` -- **[index.ts](./src/index.ts)**: Exports the main functions and types used by external clients. -- **[agentServerClient.ts](./src/agentServerClient.ts)**: Contains the core implementation for connecting to the agentServer, managing conversations, and ensuring the server is running. -- **[discovery.ts](./src/discovery.ts)**: Provides functionality for discovering the dynamically-assigned port of an in-process agent. -- **[conversation/index.ts](./src/conversation/index.ts)**: Contains shared conversation-lifecycle helpers for clients of the agent server. -- **[conversation/lifecycle.ts](./src/conversation/lifecycle.ts)**: Implements connection-level lifecycle helpers shared by every client that joins an agent server. -- **[conversation/manage.ts](./src/conversation/manage.ts)**: Implements the dispatcher's `manage-conversation` client-action surface. -- **[conversation/naming.ts](./src/conversation/naming.ts)**: Provides conversation name primitives and utilities. +This package depends on the following workspace packages: -### Key Functions and Classes +- `@typeagent/agent-rpc` +- `@typeagent/agent-server-protocol` +- `@typeagent/dispatcher-rpc` +- `websocket-channel-server` -- **`connectAgentServer(url, onDisconnect?)`**: Opens a WebSocket connection to the agentServer and returns an `AgentServerConnection`. -- **`AgentServerConnection`**: Manages conversations with methods like `joinConversation`, `leaveConversation`, `createConversation`, `listConversations`, `renameConversation`, and `deleteConversation`. -- **`ensureAgentServer(port?, hidden?, idleTimeout?)`**: Ensures the agentServer is running, spawning it if needed. -- **`isServerRunning(url)`**: Checks if a server is already listening at the given WebSocket URL. -- **`stopAgentServer(port?)`**: Sends a shutdown RPC to the running server. -- **`ensureAndConnectConversation(clientIO, port?, options?, onDisconnect?, hidden?, idleTimeout?)`**: Ensures the server is running, connects, and joins a conversation in one call. +Additionally, it uses the external libraries `debug` and `isomorphic-ws`. + +## Key Files + +The package is organized into several key files, each responsible for specific functionality: + +- **[index.ts](./src/index.ts)**: The main entry point of the package, exporting core functions and types for external use. +- **[agentServerClient.ts](./src/agentServerClient.ts)**: Implements the primary logic for connecting to the agentServer, managing conversations, and handling server lifecycle operations. +- **[discovery.ts](./src/discovery.ts)**: Provides a discovery client for identifying the dynamically assigned port of an in-process agent. +- **[conversation/index.ts](./src/conversation/index.ts)**: Aggregates and exports conversation-related utilities and helpers. +- **[conversation/lifecycle.ts](./src/conversation/lifecycle.ts)**: Implements lifecycle management for conversations, including joining, leaving, and switching between conversations. +- **[conversation/manage.ts](./src/conversation/manage.ts)**: Contains the implementation of the `manage-conversation` client-action surface, including operations like creating, listing, renaming, and deleting conversations. +- **[conversation/naming.ts](./src/conversation/naming.ts)**: Provides utilities for handling conversation names, such as normalization, validation, and sorting. ## How to extend -To extend the functionality of this package, follow these steps: +To extend the functionality of the `@typeagent/agent-server-client` package, follow these steps: + +1. **Identify the area to extend**: + + - For connection and conversation management, start with [agentServerClient.ts](./src/agentServerClient.ts). + - For port discovery, refer to [discovery.ts](./src/discovery.ts). + - For conversation lifecycle or management, explore the files in the [conversation](./src/conversation/) directory. -1. **Open the relevant file**: Depending on what you want to extend, start with either [agentServerClient.ts](./src/agentServerClient.ts) for connection and conversation management or [discovery.ts](./src/discovery.ts) for port discovery. -2. **Add new methods or modify existing ones**: Implement new features or enhance existing functionalities by adding or modifying methods in the appropriate file. -3. **Update exports**: Ensure that any new functions or types are exported in [index.ts](./src/index.ts) for external use. -4. **Write tests**: Add tests for your new functionality to ensure it works as expected. Follow the existing test patterns in the repository. -5. **Run tests**: Execute the test suite to verify your changes. Use `pnpm test` or the equivalent command configured in the project. +2. **Add or modify functionality**: -By following these steps, you can effectively extend the capabilities of the `@typeagent/agent-server-client` package. + - Implement new methods or enhance existing ones in the relevant file. + - For example, to add a new conversation management feature, you might start by modifying [conversation/manage.ts](./src/conversation/manage.ts). + +3. **Update exports**: + + - Ensure that any new functions or types are exported in [index.ts](./src/index.ts) so they are accessible to external clients. + +4. **Write tests**: + + - Add tests for your new functionality to ensure it behaves as expected. Follow the existing test patterns in the repository. + +5. **Run tests**: + - Execute the test suite using `pnpm test` or the equivalent command configured in the project. + +By following these steps, you can effectively extend the capabilities of the `@typeagent/agent-server-client` package while maintaining consistency with its existing architecture. ## Reference @@ -71,9 +97,9 @@ By following these steps, you can effectively extend the capabilities of the `@t ### Entry points -- default → [./dist/index.js](./dist/index.js) -- `./conversation` → [./dist/conversation/index.js](./dist/conversation/index.js) -- `./discovery` → [./dist/discovery.js](./dist/discovery.js) +- default → `./dist/index.js` _(not found on disk)_ +- `./conversation` → `./dist/conversation/index.js` _(not found on disk)_ +- `./discovery` → `./dist/discovery.js` _(not found on disk)_ ### Dependencies @@ -96,9 +122,9 @@ External: `debug`, `isomorphic-ws` - [browser-typeagent](../../../packages/agents/browser/README.md) - [coder-wrapper](../../../packages/coderWrapper/README.md) - [command-executor-mcp](../../../packages/commandExecutor/README.md) +- [remote-client-example](../../../examples/remoteClient/README.md) - [studio-service](../../../packages/studio-service/README.md) -- tools-scripts -- _…and 4 more workspace consumers._ +- _…and 5 more workspace consumers._ ### Files of interest @@ -111,8 +137,14 @@ External: `debug`, `isomorphic-ws` - [./src/discovery.ts](./src/discovery.ts) - [./src/tsconfig.json](./src/tsconfig.json) +### Environment variables + +_1 environment variable referenced from `./src/` (set in `ts/.env` or your shell). See the `## Setup` section above for guidance on obtaining each value._ + +- `TYPEAGENT_TUNNEL_TOKEN` + --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/agent-server-client docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/agent-server-client docs:verify-links` to spot-check._ diff --git a/ts/packages/agentServer/protocol/README.AUTOGEN.md b/ts/packages/agentServer/protocol/README.AUTOGEN.md index 1856adce2..2e68a9254 100644 --- a/ts/packages/agentServer/protocol/README.AUTOGEN.md +++ b/ts/packages/agentServer/protocol/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/agent-server-protocol — AI-generated documentation @@ -12,82 +12,76 @@ ## Overview -The `@typeagent/agent-server-protocol` package defines the WebSocket RPC contract between agentServer clients and the server. It provides the necessary types, channel names, and methods for managing conversations and client connections within the Type Agent Server ecosystem. +The `@typeagent/agent-server-protocol` package defines the WebSocket RPC contract between the agentServer and its clients. It provides the types, channel names, and methods necessary for managing conversations and client connections within the Type Agent Server ecosystem. ## What it does -This package primarily handles the protocol definitions for communication between the agentServer and its clients. It includes: +This package serves as the protocol layer for communication between the agentServer and its clients. It defines the structure and behavior of the interactions, ensuring consistent and predictable communication. Key features include: -- **Channel Names**: Fixed and session-namespaced channels for conversation lifecycle RPC. -- **Conversation Types**: Definitions for conversation metadata and results. -- **RPC Methods**: Methods exposed on the `agent-server` channel for managing conversations. -- **Client-type Registry**: Functions for registering and retrieving client types based on connection IDs. -- **Discovery Channel**: Methods for external clients to look up the live port of any in-process app-agent. +- **Channel Names**: Provides fixed and session-specific channel names for managing conversation lifecycles and client communication. For example: -The package exports several key types and functions, such as `AgentServerChannelName`, `getDispatcherChannelName`, `getClientIOChannelName`, `ConversationInfo`, `JoinConversationResult`, `DispatcherConnectOptions`, and various RPC methods like `joinConversation`, `leaveConversation`, `createConversation`, `listConversations`, `renameConversation`, `deleteConversation`, and `shutdown`. + - `AgentServerChannelName` is the fixed channel name for conversation lifecycle RPC. + - `DiscoveryChannelName` is the fixed channel name for read-only port discovery RPC. + - Helper functions like `getDispatcherChannelName(conversationId)` and `getClientIOChannelName(conversationId)` generate session-specific channel names. + +- **Conversation Management**: Defines types and methods for creating, joining, renaming, listing, and deleting conversations. For instance: + + - `joinConversation` allows clients to join or auto-create a conversation and returns a `JoinConversationResult`. + - `createConversation` creates a new named conversation and returns a `ConversationInfo` object. + - `listConversations` retrieves all conversations, optionally filtered by name. + +- **Client-Type Registry**: Maintains a mapping of `connectionId` to `clientType`, enabling the server to adapt its behavior based on the type of client connected. Functions like `registerClientType`, `getClientType`, and `unregisterClient` manage this registry. + +- **Discovery Channel**: Provides a mechanism for external clients (e.g., Chrome extensions, VS Code extensions, CLI tools) to discover the live port of any in-process app-agent. The `lookupPort` method on the `discovery` channel allows clients to query the port for a specific agent and role. + +This package is used by various components in the Type Agent ecosystem, including `@typeagent/agent-server-client`, `agent-coda`, `agent-server`, and others. ## Setup -No additional setup is required beyond installing the package. Simply run: +No additional setup is required for this package beyond installation. To include it in your project, run: ```sh pnpm install ``` -## Key Files - -The package is structured as follows: +The package does not require any environment variables or external configuration. -- **[index.ts](./src/index.ts)**: This file exports all the necessary types and functions from `protocol.ts`. -- **[protocol.ts](./src/protocol.ts)**: Contains the definitions for types, channel names, and RPC methods. -- **[queue.ts](./src/queue.ts)**: Re-exports queue wire types and errors from `@typeagent/dispatcher-types`. -- **[tsconfig.json](./src/tsconfig.json)**: TypeScript configuration file for the package. +## Key Files -### Channel Names +The package is organized into the following key files: -- **AgentServerChannelName**: The fixed channel name for conversation lifecycle RPC. -- **DiscoveryChannelName**: The fixed channel name for read-only port discovery RPC. -- **getDispatcherChannelName(conversationId: string)**: Constructs session-namespaced channels for dispatcher communication. -- **getClientIOChannelName(conversationId: string)**: Constructs session-namespaced channels for client IO communication. +- **[index.ts](./src/index.ts)**: Serves as the main entry point for the package. It re-exports all the key types, constants, and functions defined in other files, such as `protocol.ts` and `queue.ts`. +- **[protocol.ts](./src/protocol.ts)**: Contains the core protocol definitions, including channel names, conversation types, and RPC methods. This is the primary file for understanding and extending the protocol. +- **[queue.ts](./src/queue.ts)**: Re-exports queue-related types and errors from the `@typeagent/dispatcher-types` package, allowing clients to access these definitions from a single location. +- **[tsconfig.json](./src/tsconfig.json)**: The TypeScript configuration file for the package, specifying compiler options and project structure. -### Conversation Types +## How to extend -- **ConversationInfo**: Describes a conversation with fields like `conversationId`, `name`, `clientCount`, and `createdAt`. -- **JoinConversationResult**: Returned by `joinConversation`, includes `connectionId` and `conversationId`. -- **DispatcherConnectOptions**: Options passed to `joinConversation`, including `conversationId`, `clientType`, and `filter`. +To extend the `@typeagent/agent-server-protocol` package, follow these steps: -### RPC Methods +1. **Understand the existing structure**: -- **AgentServerInvokeFunctions**: Methods exposed on the `agent-server` channel, including: - - `joinConversation(options?)` - - `leaveConversation(conversationId)` - - `createConversation(name)` - - `listConversations(name?)` - - `renameConversation(conversationId, newName)` - - `deleteConversation(conversationId)` - - `shutdown()` + - Start by reviewing the [protocol.ts](./src/protocol.ts) file, which contains the core definitions for channel names, conversation types, and RPC methods. + - Familiarize yourself with the exports in [index.ts](./src/index.ts) to understand how the package is structured. -### Client-type Registry +2. **Add new functionality**: -- **registerClientType(connectionId: string, clientType: string)**: Registers a client type based on connection ID. -- **getClientType(connectionId: string)**: Retrieves the client type for a given connection ID. -- **unregisterClient(connectionId: string)**: Unregisters a client based on connection ID. + - To introduce new RPC methods, define them in `protocol.ts` under the appropriate channel (e.g., `agent-server` or `discovery`). + - If new types or constants are needed, define them in `protocol.ts` and ensure they are exported in `index.ts`. -### Discovery Channel +3. **Update the client-type registry**: -- **DiscoveryInvokeFunctions**: Methods exposed on the `discovery` channel, including: - - `lookupPort(param: { agentName: string; role?: string })`: Looks up the live port of any in-process app-agent. + - If your changes involve new client types or modifications to the client-type registry, update the relevant functions (`registerClientType`, `getClientType`, `unregisterClient`) in `protocol.ts`. -## How to extend +4. **Test your changes**: -To extend the functionality of this package, follow these steps: + - Write unit tests to validate the new functionality. Ensure that all existing tests pass and that the new tests cover the added features. -1. **Open `protocol.ts`**: This file contains the core definitions and is the starting point for any modifications or additions. -2. **Add new types or methods**: Define new types or RPC methods as needed. Ensure they are well-documented and follow the existing structure. -3. **Export new additions**: Update `index.ts` to export any new types or methods added to `protocol.ts`. -4. **Test your changes**: Write tests to validate the new functionality. Ensure that all existing tests pass and cover the new additions. +5. **Document your changes**: + - Update the hand-written README or other documentation to reflect the new functionality. + - Ensure that any new types, methods, or constants are clearly described and include examples where applicable. -By following these steps, you can effectively extend the capabilities of the `@typeagent/agent-server-protocol` package. +By following these steps, you can effectively contribute to and extend the `@typeagent/agent-server-protocol` package. ## Reference @@ -95,7 +89,7 @@ By following these steps, you can effectively extend the capabilities of the `@t ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -113,6 +107,7 @@ External: _None at runtime._ - [agent-server](../../../packages/agentServer/server/README.md) - [agent-shell](../../../packages/shell/README.md) - [browser-typeagent](../../../packages/agents/browser/README.md) +- [remote-client-example](../../../examples/remoteClient/README.md) - visualstudio-extension-webview - [vscode-chat](../../../packages/vscode-chat/README.md) - [vscode-shell](../../../packages/vscode-shell/README.md) @@ -123,6 +118,6 @@ External: _None at runtime._ --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/agent-server-protocol docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/agent-server-protocol docs:verify-links` to spot-check._ diff --git a/ts/packages/agentServer/server/README.AUTOGEN.md b/ts/packages/agentServer/server/README.AUTOGEN.md index 3c31c0c91..8f5562a8e 100644 --- a/ts/packages/agentServer/server/README.AUTOGEN.md +++ b/ts/packages/agentServer/server/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # agent-server — AI-generated documentation @@ -12,51 +12,86 @@ ## Overview -The `agent-server` package is a TypeScript library that provides a long-running WebSocket server for hosting TypeAgent dispatchers with full conversation management capabilities. It listens for connections, manages conversations, and facilitates communication between clients and agents. +The `agent-server` package is a TypeScript library that provides a long-running WebSocket server for hosting TypeAgent dispatchers. It manages conversations, facilitates communication between clients and agents, and supports features like conversation persistence, idle timeouts, and graceful shutdown. ## What it does -The `agent-server` package handles several actions related to conversation management and server control. These actions include `joinConversation`, `leaveConversation`, `createConversation`, `listConversations`, `renameConversation`, `deleteConversation`, and `shutdown`. The server listens on a WebSocket endpoint and processes these actions by interacting with the conversation manager and shared dispatcher components. It also supports graceful shutdown and idle timeout features. +The `agent-server` package is responsible for managing WebSocket connections and enabling communication between clients and agents. It provides a set of actions for conversation management and server control, including: + +- `joinConversation` and `leaveConversation` for managing client participation in conversations. +- `createConversation`, `listConversations`, `renameConversation`, and `deleteConversation` for conversation lifecycle management. +- `shutdown` for gracefully stopping the server. + +The server listens on a WebSocket endpoint and uses a `ConversationManager` to handle conversation-related operations. It also includes a `SharedDispatcher` to manage multiple client connections within a single conversation. The server can be configured to shut down after a specified period of inactivity using the `--idle-timeout` flag. + +Additionally, the package supports integration with Microsoft Dev Tunnels, allowing the server to be exposed to remote devices for cross-device access. ## Setup -To set up the `agent-server`, you need to configure the following environment variables: +To set up the `agent-server`, ensure the following environment variables are configured: -- `AGENT_SERVER_PORT`: The port on which the server will listen for WebSocket connections. -- `TYPEAGENT_USER_NAME`: The username for the TypeAgent user. +- `AGENT_SERVER_PORT`: Specifies the port on which the server will listen for WebSocket connections. The default is `8999`. +- `TYPEAGENT_USER_NAME`: The username for the TypeAgent user. If not set, the server will attempt to use the system's username. +- `XDG_CONFIG_HOME`: Specifies the base directory for configuration files. If not set, the default is typically `~/.config`. -Ensure these variables are set in your environment or in a `.env` file. For detailed setup instructions, see the hand-written README. +You can set these variables in your environment or define them in a `.env` file. For more details on starting the server and configuring it, refer to the hand-written README. ## Key Files -The `agent-server` package is structured around several key components: +The `agent-server` package is organized into several key files, each responsible for specific functionality: + +### [server.ts](./src/server.ts) — WebSocket Listener + +This file initializes the WebSocket server and manages incoming connections. It creates a `ConversationManager` instance and uses `createWebSocketChannelServer` to start listening for WebSocket connections. It also exposes the `AgentServerInvokeFunctions` over the `agent-server` RPC channel, enabling actions such as: + +- Managing conversations (e.g., `joinConversation`, `createConversation`, `listConversations`). +- Handling server control actions like `shutdown`. + +### [conversationManager.ts](./src/conversationManager.ts) — Conversation Pool + +This file manages a pool of `SharedDispatcher` instances, each corresponding to a conversation. Key responsibilities include: + +- **Persistence**: Stores conversation metadata and data in the file system under the `~/.typeagent/profiles/dev/conversations/` directory. +- **Lazy Initialization**: Creates `SharedDispatcher` instances on demand and tears them down after a period of inactivity. +- **Default Conversations**: Automatically creates a default conversation if none exists. +- **Ephemeral Cleanup**: Removes temporary conversations left over from crashed processes during server startup. +- **Idle Shutdown**: Supports shutting down the server after a specified period of inactivity. + +### [sharedDispatcher.ts](./src/sharedDispatcher.ts) — Routing Layer + +This file manages multiple client connections within a single conversation. It wraps a dispatcher context and routes client IO methods based on connection IDs. Key features include: + +- **Connection Management**: Assigns unique `connectionId`s to clients and maintains a routing table. +- **Client Isolation**: Ensures that each client's display output is isolated while sharing the same dispatcher and conversation context. +- **Routing Logic**: Routes client IO methods (e.g., `setDisplay`, `askYesNo`, `requestChoice`) to the appropriate client based on the `connectionId`. -### `server.ts` — WebSocket listener +### [connectionHandler.ts](./src/connectionHandler.ts) — Connection Management -The `server.ts` file is responsible for setting up the WebSocket server and managing connections. It creates a `ConversationManager` at startup and calls `createWebSocketChannelServer` to accept connections. For each connection, it exposes `AgentServerInvokeFunctions` over the `agent-server` RPC channel, handling actions such as joining and leaving conversations, creating and listing conversations, and shutting down the server. +This file defines the logic for handling individual WebSocket connections. It interacts with the `ConversationManager` to manage conversations and uses the `agent-server` RPC channel to expose server functions to connected clients. -### `conversationManager.ts` — Conversation pool +### [copilot/displayLogSynthesis.ts](./src/copilot/displayLogSynthesis.ts) — Display Log Synthesis -The `conversationManager.ts` file maintains a pool of per-conversation `SharedDispatcher` instances. It handles persistence of conversation metadata, lazy initialization of dispatchers, automatic creation of default conversations, and cleanup of ephemeral conversations. It also supports idle shutdown based on the `--idle-timeout` flag. +This file provides utilities for synthesizing display logs from Copilot session data. It converts Copilot session turns into `DisplayLogEntry` streams, enabling imported sessions to render in the conversation UI. -### `sharedDispatcher.ts` — Routing layer +### [copilot/mirrorImporter.ts](./src/copilot/mirrorImporter.ts) — Copilot Session Importer -The `sharedDispatcher.ts` file manages multiple client connections within a single conversation. It wraps a dispatcher context and routes client IO methods based on connection IDs. This ensures that each client's display output is isolated while sharing the same dispatcher and conversation context. +This file handles the import of Copilot sessions into the conversation manager. It reads session data from a SQLite database and creates corresponding conversations in the `agent-server`. -### `status.ts` and `stop.ts` — Server control +### [inProcessAgentServer.ts](./src/inProcessAgentServer.ts) — In-Process Server -The `status.ts` and `stop.ts` files provide utilities for checking the server status and stopping the server, respectively. They use the `@typeagent/agent-server-client` package to interact with the server. +This file provides an in-process implementation of the agent server, allowing it to run within the same process as the client. It is useful for scenarios where a separate server process is not required. ## How to extend To extend the `agent-server` package, follow these steps: -1. **Start with `server.ts`**: This file sets up the WebSocket server and manages connections. You can add new RPC functions or modify existing ones to handle additional actions. -2. **Modify `conversationManager.ts`**: If you need to change how conversations are managed, this is the file to edit. You can add new behaviors or modify existing ones related to conversation persistence, initialization, and cleanup. -3. **Update `sharedDispatcher.ts`**: To change how client connections are routed within a conversation, modify this file. You can add new routing logic or adjust the existing methods for handling client IO. -4. **Test your changes**: Ensure that your modifications are working correctly by running the server and testing the new or modified actions. You can use the provided `status.ts` and `stop.ts` utilities to control the server during testing. +1. **Understand the architecture**: Start by reviewing the key files mentioned above to understand how the server, conversation manager, and dispatcher components interact. +2. **Add new actions**: To introduce new server actions, modify the `server.ts` file to expose additional RPC functions. Implement the corresponding logic in the appropriate files, such as `conversationManager.ts` or `sharedDispatcher.ts`. +3. **Enhance conversation management**: If you need to change how conversations are handled, edit `conversationManager.ts`. For example, you can add new persistence mechanisms or modify the behavior of default conversations. +4. **Modify routing logic**: To customize how client IO methods are routed within a conversation, update `sharedDispatcher.ts`. You can add new routing rules or adjust existing ones. +5. **Test your changes**: Use the provided utilities in `status.ts` and `stop.ts` to test your modifications. Ensure that the server behaves as expected and that new features work correctly. -By following these steps, you can extend the functionality of the `agent-server` package to meet your specific needs. +By following these guidelines, you can effectively extend the functionality of the `agent-server` package to meet your specific requirements. ## Reference @@ -64,8 +99,8 @@ By following these steps, you can extend the functionality of the `agent-server` ### Entry points -- default → [./dist/server.js](./dist/server.js) -- `./in-process` → [./dist/inProcessAgentServer.js](./dist/inProcessAgentServer.js) +- default → `./dist/server.js` _(not found on disk)_ +- `./in-process` → `./dist/inProcessAgentServer.js` _(not found on disk)_ ### Dependencies @@ -83,7 +118,7 @@ Workspace: - [dispatcher-node-providers](../../../packages/dispatcher/nodeProviders/README.md) - [websocket-channel-server](../../../packages/utils/webSocketChannelServer/README.md) -External: `@azure/identity`, `debug`, `dotenv`, `ws` +External: `@azure/identity`, `better-sqlite3`, `debug`, `dotenv`, `ws` ### Used by @@ -91,17 +126,18 @@ External: `@azure/identity`, `debug`, `dotenv`, `ws` ### Files of interest -`./src/connectionHandler.ts`, `./src/conversationManager.ts`, `./src/inProcessAgentServer.ts`, …and 6 more under `./src/`. +`./src/connectionHandler.ts`, `./src/conversationManager.ts`, `./src/copilot/displayLogSynthesis.ts`, …and 10 more under `./src/`. ### Environment variables -_2 environment variables referenced from `./src/` (set in `ts/.env` or your shell). See the `## Setup` section above for guidance on obtaining each value._ +_3 environment variables referenced from `./src/` (set in `ts/.env` or your shell). See the `## Setup` section above for guidance on obtaining each value._ - `AGENT_SERVER_PORT` - `TYPEAGENT_USER_NAME` +- `XDG_CONFIG_HOME` --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter agent-server docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter agent-server docs:verify-links` to spot-check._ diff --git a/ts/packages/agents/agentUtils/graphUtils/README.AUTOGEN.md b/ts/packages/agents/agentUtils/graphUtils/README.AUTOGEN.md index 5f2cfaeb5..2052b4fed 100644 --- a/ts/packages/agents/agentUtils/graphUtils/README.AUTOGEN.md +++ b/ts/packages/agents/agentUtils/graphUtils/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # graph-utils — AI-generated documentation @@ -12,47 +12,57 @@ ## Overview -The `graph-utils` package provides utility functions to access Microsoft Graph APIs, facilitating integration with Microsoft services such as calendar and email. It abstracts the complexities of interacting with these APIs, offering a simplified interface for common operations. +The `graph-utils` package provides utility functions for accessing Microsoft Graph APIs, enabling integration with Microsoft services such as calendars and email. It simplifies the process of interacting with these APIs by offering a unified interface for common operations. The package also supports integration with Google Calendar, making it a versatile tool for managing calendar and email functionalities across multiple providers. ## What it does -The `graph-utils` package supports various actions related to calendar and email functionalities. It includes utilities for date range calculations, client creation for calendar and email services, and provider abstractions for multi-provider support (Microsoft Graph and Google Calendar). Key actions include `createCalendarEvent`, `deleteCalendarEvent`, `getCalendarEvents`, `updateCalendarEvent`, `createEmail`, `deleteEmail`, `getEmails`, and `updateEmail`. +The `graph-utils` package is designed to handle operations related to calendar and email services. It provides a set of actions that allow for creating, updating, retrieving, and deleting calendar events and emails. These actions include: + +- Calendar-related actions: `createCalendarEvent`, `deleteCalendarEvent`, `getCalendarEvents`, and `updateCalendarEvent`. +- Email-related actions: `createEmail`, `deleteEmail`, `getEmails`, and `updateEmail`. + +The package also includes utilities for date range calculations, embedding generation for calendar data, and provider abstractions to support multiple services such as Microsoft Graph and Google Calendar. It determines the appropriate provider to use based on the environment variables configured. ## Setup -To use the `graph-utils` package, several environment variables need to be set up. These variables are essential for authenticating and interacting with the Microsoft Graph and Google Calendar APIs. The required environment variables are: +To use the `graph-utils` package, you need to configure the following environment variables: -- `GOOGLE_CALENDAR_CLIENT_ID` -- `GOOGLE_CALENDAR_CLIENT_SECRET` -- `MSGRAPH_APP_CLIENTID` -- `MSGRAPH_APP_TENANTID` +- `GOOGLE_CALENDAR_CLIENT_ID`: The client ID for your Google Calendar API application. +- `GOOGLE_CALENDAR_CLIENT_SECRET`: The client secret for your Google Calendar API application. +- `MSGRAPH_APP_CLIENTID`: The client ID for your Microsoft Graph API application. +- `MSGRAPH_APP_TENANTID`: The tenant ID for your Microsoft Graph API application. -Ensure these variables are correctly configured in your environment. For detailed steps on how to obtain and set these values, refer to the hand-written README. +These environment variables are essential for authenticating and interacting with the respective APIs. To obtain the values for these variables, you may need to register applications in the Google Cloud Console and Microsoft Azure Portal. Refer to the hand-written README for detailed instructions on setting up these credentials. ## Key Files -The `graph-utils` package is structured to provide a clear separation of concerns, with dedicated modules for different functionalities: +The `graph-utils` package is organized into several key files, each responsible for specific functionalities: -- [index.ts](./src/index.ts): Exports utility functions and client creation methods for calendar and email services. -- [calendarClient.ts](./src/calendarClient.ts): Contains the `CalendarClient` class, which handles interactions with the calendar API, including login and data synchronization. -- [calendarDataIndex.ts](./src/calendarDataIndex.ts): Provides methods for managing and searching calendar event embeddings. -- [calendarProvider.ts](./src/calendarProvider.ts): Defines interfaces and types for calendar events, attendees, date range queries, and user information. -- [calendarProviderFactory.ts](./src/calendarProviderFactory.ts): Factory functions to create calendar providers based on configuration. -- [dateUtils.ts](./src/dateUtils.ts): Utility functions for date range calculations. -- [emailProvider.ts](./src/emailProvider.ts): Defines interfaces and types for email messages, addresses, search queries, and user information. -- [emailProviderFactory.ts](./src/emailProviderFactory.ts): Factory functions to create email providers based on configuration. +- [index.ts](./src/index.ts): The main entry point of the package, exporting utility functions and client creation methods for calendar and email services. +- [calendarClient.ts](./src/calendarClient.ts): Implements the `CalendarClient` class, which manages interactions with the calendar API, including login, synchronization, and data management. +- [calendarDataIndex.ts](./src/calendarDataIndex.ts): Provides methods for managing and searching calendar event embeddings, enabling efficient event lookups. +- [calendarProvider.ts](./src/calendarProvider.ts): Defines interfaces and types for calendar-related entities such as events, attendees, and date range queries. +- [calendarProviderFactory.ts](./src/calendarProviderFactory.ts): Contains factory functions to create calendar providers based on the configured environment variables. +- [dateUtils.ts](./src/dateUtils.ts): Offers utility functions for date range calculations, such as determining the current week or month. +- [emailProvider.ts](./src/emailProvider.ts): Defines interfaces and types for email-related entities, including messages, addresses, and search queries. +- [emailProviderFactory.ts](./src/emailProviderFactory.ts): Contains factory functions to create email providers based on the configured environment variables. +- [googleCalendarClient.ts](./src/googleCalendarClient.ts): Implements the `ICalendarProvider` interface for Google Calendar, including OAuth authentication and token management. ## How to extend To extend the `graph-utils` package, follow these steps: -1. **Identify the module to extend**: Determine whether your extension involves calendar functionalities, email functionalities, or general utilities. -2. **Open the relevant file**: For calendar-related extensions, start with [calendarClient.ts](./src/calendarClient.ts) or [calendarProvider.ts](./src/calendarProvider.ts). For email-related extensions, start with [emailProvider.ts](./src/emailProvider.ts). -3. **Follow existing patterns**: Review the existing code to understand the structure and patterns used. Implement your changes following these patterns to maintain consistency. -4. **Add new actions**: If you need to add new actions, ensure they are properly defined and exported in [index.ts](./src/index.ts). -5. **Test your changes**: Write tests to validate your extensions. Ensure that your changes do not break existing functionalities. +1. **Determine the area to extend**: Identify whether your extension involves calendar functionalities, email functionalities, or general utilities. +2. **Locate the relevant file**: + - For calendar-related extensions, start with [calendarClient.ts](./src/calendarClient.ts), [calendarProvider.ts](./src/calendarProvider.ts), or [calendarProviderFactory.ts](./src/calendarProviderFactory.ts). + - For email-related extensions, focus on [emailProvider.ts](./src/emailProvider.ts) or [emailProviderFactory.ts](./src/emailProviderFactory.ts). + - For date-related utilities, refer to [dateUtils.ts](./src/dateUtils.ts). +3. **Follow existing patterns**: Review the existing code to understand the structure, naming conventions, and patterns. Implement your changes in a consistent manner. +4. **Add new actions**: If your extension requires new actions, define them in the appropriate files and ensure they are exported in [index.ts](./src/index.ts). +5. **Update provider factories**: If your extension involves a new provider, update the relevant factory file (e.g., [calendarProviderFactory.ts](./src/calendarProviderFactory.ts) or [emailProviderFactory.ts](./src/emailProviderFactory.ts)) to include logic for detecting and creating the new provider. +6. **Write tests**: Add unit and integration tests to validate your changes. Ensure that your modifications do not introduce regressions or break existing functionality. -By following these steps, you can effectively extend the `graph-utils` package to meet your specific requirements. +By adhering to these guidelines, you can effectively extend the `graph-utils` package to support additional features or integrate with new providers. ## Reference @@ -60,7 +70,7 @@ By following these steps, you can effectively extend the `graph-utils` package t ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -93,6 +103,6 @@ _4 environment variables referenced from `./src/` (set in `ts/.env` or your shel --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter graph-utils docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter graph-utils docs:verify-links` to spot-check._ diff --git a/ts/packages/agents/browser/README.AUTOGEN.md b/ts/packages/agents/browser/README.AUTOGEN.md index ba1f62ee1..9a032cc2d 100644 --- a/ts/packages/agents/browser/README.AUTOGEN.md +++ b/ts/packages/agents/browser/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # browser-typeagent — AI-generated documentation @@ -12,73 +12,82 @@ ## Overview -The `browser-typeagent` package is a TypeAgent application agent designed to control and automate browser actions. It enables the manipulation of browser windows, tabs, and web pages through a set of defined actions. This package is part of the TypeAgent monorepo and integrates with other TypeAgent components to provide a comprehensive browser automation solution. +The `browser-typeagent` package is a TypeAgent application agent designed for browser automation and control. It enables interaction with browser windows, tabs, and web pages through a defined set of actions. This package integrates with other components in the TypeAgent ecosystem, such as the TypeAgent shell and CLI, to provide a unified interface for browser-related tasks. ## What it does -The `browser-typeagent` package provides a range of actions for browser control and automation. These actions include `openWebPage`, `indexPage`, `clickOn`, `captureScreenshot`, `getHtmlFragments`, and more. The package allows for the opening, closing, and navigation of browser tabs, scrolling, zooming, and interacting with web pages. It also supports enhanced website indexing with knowledge extraction capabilities. +The `browser-typeagent` package supports a variety of browser automation actions, including: -The package interacts with other parts of the TypeAgent system, such as the TypeAgent shell and CLI, to receive commands and execute browser actions. It uses WebSocket connections to communicate with clients, including browser extensions and the Electron shell. +- Navigating to web pages (`openWebPage`, `goBack`, `goForward`, `reloadPage`). +- Interacting with web content (`clickOn`, `followLinkByText`, `scrollDown`, `scrollUp`). +- Capturing and extracting information (`captureScreenshot`, `getHtmlFragments`, `indexPage`). +- Managing browser tabs (`changeTabs`, `closeWebPage`, `closeAllWebPages`). +- Performing advanced tasks like executing scripts (`executeAdHocScript`) and indexing websites with AI-enhanced knowledge extraction. -## Setup +The package communicates with clients, such as a browser extension or the Electron shell, via WebSocket connections. It uses `@typeagent/agent-rpc` to multiplex these connections into logical channels for invoking browser actions and controlling the browser. -To set up the `browser-typeagent` package, you need to configure the following environment variables: +## Setup -- `BROWSER_WEBSOCKET_PORT`: This variable allows you to pin the WebSocket server port for debugging. Set it to a specific port number before launching the host. -- `TYPEAGENT_BROWSER_FILES`: This variable should point to the directory containing the browser files required for the agent's operation. +To set up the `browser-typeagent` package, follow these steps: -Additionally, you need to enable developer mode in your browser and load the unpackaged extension. The steps are as follows: +1. **Environment Variables**: -1. Enable developer mode in your browser (Chrome or Edge): + - `BROWSER_WEBSOCKET_PORT`: Set this variable to specify the WebSocket server port for debugging. If not set, the port is dynamically assigned. + - `TYPEAGENT_BROWSER_FILES`: This variable should point to the directory containing the browser files required for the agent's operation. - - Launch the browser. - - Click on the extensions icon next to the address bar and select "Manage extensions." - - Enable the developer mode toggle on the extensions page. +2. **Browser Extension**: -2. Build the extension by running `pnpm run build` in the package folder. + - Enable developer mode in your browser: + - For Chrome or Edge, go to the extensions page by clicking the extensions icon near the address bar and selecting "Manage extensions." + - Enable the "Developer mode" toggle. + - Build the extension by running `pnpm run build` in the package directory. + - Load the unpackaged extension: + - On the extensions page, click "Load unpackaged extension" and select the `dist/extension` folder. -3. Load the unpackaged extension: - - Go to the "Manage extensions" page. - - Click on "Load unpackaged extension" and navigate to the `dist/extension` folder of the browser extension package. +3. **Running the Extension**: + - Launch the browser where the extension is installed. + - Start the TypeAgent shell or CLI, which integrates with the extension to send commands. You can issue commands such as `openWebPage`, `scrollDown`, or `captureScreenshot` to interact with the browser. -For detailed setup instructions, see the hand-written README. +For additional details, refer to the hand-written README. ## Key Files -The `browser-typeagent` package is structured into several key components: - -- **Agent WebSocket Server**: Exposes a WebSocket server (`AgentWebSocketServer`) on a dynamically assigned port, allowing clients to connect and communicate with the browser agent. Clients include the Chrome extension and the Electron shell. - -- **Session Management**: Supports multiple concurrent sessions by registering handlers under unique `sessionId` keys. The session ID is stored in `BrowserActionContext.sessionId` and is set during context initialization. +The `browser-typeagent` package is organized into several key files, each responsible for specific functionality: -- **Client Type Detection**: Differentiates between `extension` and `electron` clients based on their `clientId`. Commands are routed to the active client based on the `preferredClientType`. +- **browserActionHandler.ts**: Implements handlers for browser actions like `openWebPage`, `captureScreenshot`, and `indexPage`. +- **[agentWebSocketServer.ts](./src/agent/agentWebSocketServer.mts)**: Manages WebSocket connections, session routing, and client communication. +- **[browserIndexingService.ts](./src/agent/indexing/browserIndexingService.ts)**: Provides AI-enhanced website indexing and knowledge extraction. +- **[browserActionSchema.mts](./src/agent/browserActionSchema.mts)**: Defines the schema for browser actions, including their parameters and expected behavior. +- **[browserActions.mts](./src/agent/browserActions.mts)**: Contains the core logic for executing browser actions and managing browser state. +- **[browserContentExtractor.mts](./src/agent/browserContentExtractor.mts)**: Extends content extraction capabilities with browser-based downloading and processing. -- **Channel Multiplexing**: Uses `@typeagent/agent-rpc` to multiplex client connections into two logical channels: `agentService` for invoking browser agent actions and `browserControl` for controlling the browser. +## How to extend -- **Client Storage Model**: Stores connected clients in a nested `Map>`, allowing the same `clientId` to exist simultaneously in multiple sessions without collision. +To extend the `browser-typeagent` package, follow these steps: -Key files and their responsibilities include: +1. **Identify the Area to Extend**: -- browserActionHandler.ts: Handles browser actions such as opening web pages and capturing screenshots. -- agentWebSocketServer.ts: Manages WebSocket connections and client routing. -- [browserIndexingService.ts](./src/agent/indexing/browserIndexingService.ts): Provides AI-enhanced indexing with content summarization and quality assessment. -- [crossContextHtmlReducer.ts](./src/common/crossContextHtmlReducer.ts): Reduces HTML size by removing unnecessary elements and attributes. + - For new browser actions, start with browserActionHandler.ts. + - For changes to the WebSocket server or client communication, modify [agentWebSocketServer.ts](./src/agent/agentWebSocketServer.mts). + - To update the action schema, edit [browserActionSchema.mts](./src/agent/browserActionSchema.mts). -## How to extend +2. **Implement the Changes**: -To extend the `browser-typeagent` package, follow these steps: + - Follow the existing patterns in the codebase to ensure consistency. + - For new actions, define the action schema and implement the corresponding handler. -1. Open the relevant file based on the functionality you want to add or modify. For example, to add a new browser action, start with browserActionHandler.ts. +3. **Update the Schema**: -2. Implement the new action or feature following the existing patterns. Ensure that the new functionality integrates with the WebSocket server and session management. + - If your changes involve new actions or parameters, update the schema files in the `src/agent` directory. -3. Update the action schema if necessary. The schema files are located in the `src/agent` directory, such as [browserActionSchema.json](./src/agent/browserActionSchema.json). +4. **Test Your Changes**: -4. Test the new functionality by running the TypeAgent shell or CLI and issuing commands to verify the behavior. + - Use the TypeAgent shell or CLI to test the new functionality. Issue commands to verify the behavior of the added or modified features. -5. Document the new actions and features in the package's README and ensure that the environment variables and setup instructions are updated accordingly. +5. **Document the Changes**: + - Update the package's documentation to reflect the new functionality, including any changes to setup instructions or environment variables. -By following these steps, you can extend the capabilities of the `browser-typeagent` package and integrate new browser automation features. +By following these steps, you can add new capabilities to the `browser-typeagent` package while maintaining compatibility with the existing system. ## Reference @@ -87,12 +96,12 @@ By following these steps, you can extend the capabilities of the `browser-typeag ### Entry points - `./agent/manifest` → [./src/agent/manifest.json](./src/agent/manifest.json) -- `./agent/handlers` → [./dist/agent/browserActionHandler.mjs](./dist/agent/browserActionHandler.mjs) -- `./agent/types` → [./dist/common/browserControl.mjs](./dist/common/browserControl.mjs) -- `./agent/indexing` → [./dist/agent/indexing/browserIndexingService.js](./dist/agent/indexing/browserIndexingService.js) -- `./contentScriptRpc/types` → [./dist/common/contentScriptRpc/types.mjs](./dist/common/contentScriptRpc/types.mjs) -- `./contentScriptRpc/client` → [./dist/common/contentScriptRpc/client.mjs](./dist/common/contentScriptRpc/client.mjs) -- `./htmlReducer` → [./dist/common/crossContextHtmlReducer.js](./dist/common/crossContextHtmlReducer.js) +- `./agent/handlers` → `./dist/agent/browserActionHandler.mjs` _(not found on disk)_ +- `./agent/types` → `./dist/common/browserControl.mjs` _(not found on disk)_ +- `./agent/indexing` → `./dist/agent/indexing/browserIndexingService.js` _(not found on disk)_ +- `./contentScriptRpc/types` → `./dist/common/contentScriptRpc/types.mjs` _(not found on disk)_ +- `./contentScriptRpc/client` → `./dist/common/contentScriptRpc/client.mjs` _(not found on disk)_ +- `./htmlReducer` → `./dist/common/crossContextHtmlReducer.js` _(not found on disk)_ ### Dependencies @@ -145,7 +154,7 @@ _…and 17 more not shown._ - [./src/extension/contentScript/recording/index.ts](./src/extension/contentScript/recording/index.ts) - [./src/extension/serviceWorker/index.ts](./src/extension/serviceWorker/index.ts) - [./src/extension/webagent/crossword/crosswordSchema.agr](./src/extension/webagent/crossword/crosswordSchema.agr) -- _…and 286 more under `./src/`._ +- _…and 284 more under `./src/`._ ### Environment variables @@ -156,6 +165,6 @@ _2 environment variables referenced from `./src/` (set in `ts/.env` or your shel --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter browser-typeagent docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter browser-typeagent docs:verify-links` to spot-check._ diff --git a/ts/packages/agents/desktop/README.AUTOGEN.md b/ts/packages/agents/desktop/README.AUTOGEN.md index 79546c977..907d08679 100644 --- a/ts/packages/agents/desktop/README.AUTOGEN.md +++ b/ts/packages/agents/desktop/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # desktop-automation — AI-generated documentation @@ -12,80 +12,133 @@ ## Overview -The `desktop-automation` package is a TypeAgent application agent designed to manage and control desktop environments on Windows systems. It integrates with Windows shell APIs to perform various actions such as launching programs, managing windows, adjusting display settings, and more. +The `desktop-automation` package is a TypeAgent application agent designed to automate and control desktop environments on Windows systems. It integrates with Windows shell APIs via a .NET component to perform a variety of desktop-related actions, such as managing windows, launching applications, and adjusting system settings. This package is particularly useful for automating repetitive tasks or creating custom workflows for desktop management. ## What it does -This package provides a wide range of actions to control and automate desktop tasks. Some of the key actions include: +The `desktop-automation` package enables a wide range of desktop automation tasks by providing a set of predefined actions. These actions are defined in the [actionsSchema.ts](./src/actionsSchema.ts) file and are processed by the [actionHandler.ts](./src/actionHandler.ts) file. The package communicates with a .NET component (`autoShell.exe`) to execute these actions on a Windows system. -- `LaunchProgram`: Launches a specified program. -- `CloseProgram`: Closes a specified program. -- `TileWindows`: Arranges windows in a specified layout. -- `MaximizeWindow`: Maximizes a specified window. -- `MinimizeWindow`: Minimizes a specified window. -- `SetVolume`: Adjusts the system volume. -- `SetWallpaper`: Changes the desktop wallpaper. -- `ConnectWifi`: Connects to a specified Wi-Fi network. -- `ToggleAirplaneMode`: Toggles the airplane mode on or off. +### Key Capabilities -These actions are defined in the [actionsSchema.ts](./src/actionsSchema.ts) file and are handled by the [actionHandler.ts](./src/actionHandler.ts) file. +The following are some of the key actions supported by this package: -## Setup +- **Program Management**: + + - `LaunchProgram`: Launch a specified program. + - `CloseProgram`: Close a specified program. + - `SwitchToWindow`: Switch focus to a specific window. + +- **Window Management**: + + - `TileWindows`: Arrange windows in a specified layout. + - `MaximizeWindow`: Maximize a specific window. + - `MinimizeWindow`: Minimize a specific window. + - `MoveWindowToDesktop`: Move a window to a different virtual desktop. + +- **System Settings**: -To set up the `desktop-automation` package, you need to configure the following environment variable: + - `SetVolume`, `AdjustVolume`, `MuteVolume`: Manage system volume. + - `SetWallpaper`: Change the desktop wallpaper. + - `SetScreenResolution`: Adjust screen resolution. + - `SetTextSize`: Modify text size on the screen. -- `AUTOSHELL_PATH`: Path to the `autoShell.exe` binary. This binary is built from the .NET code located in the `dotnet/autoShell` directory. +- **Network and Connectivity**: -### Steps to build and configure + - `ConnectWifi`, `DisconnectWifi`, `ListWifiNetworks`: Manage Wi-Fi connections. + - `ToggleAirplaneMode`: Enable or disable airplane mode. + - `BluetoothToggleAction`: Toggle Bluetooth settings. -1. **Build the .NET component**: +- **Desktop Management**: + + - `CreateDesktop`, `SwitchDesktop`, `NextDesktop`, `PreviousDesktop`: Manage virtual desktops. + - `PinWindowToAllDesktops`: Pin a window to all virtual desktops. + +- **Other Utilities**: + - `ToggleNotifications`: Enable or disable system notifications. + - `DebugAutoShell`: Debug the `autoShell.exe` component. + +These actions allow for comprehensive control over the desktop environment, making the package a versatile tool for automation tasks. + +## Setup + +To use the `desktop-automation` package, you need to configure and build both its .NET and TypeAgent components. Additionally, you must set an environment variable to specify the path to the `autoShell.exe` binary. + +### Steps to Build and Configure + +1. **Build the .NET Component**: - Open Visual Studio. - - Navigate to the `dotnet/autoShell` directory. + - Navigate to the `dotnet/autoShell` directory in the repository. - Build the project to generate the `autoShell.exe` binary. -2. **Build the TypeAgent component**: +2. **Build the TypeAgent Component**: - Navigate to the `ts/packages/agents/desktop` directory. - - Run `pnpm run build` to build the TypeAgent application agent. - -3. **Set the environment variable**: - - Ensure the `AUTOSHELL_PATH` environment variable points to the location of the `autoShell.exe` binary. - -For detailed setup instructions, see the hand-written README. + - Run the following command to build the TypeAgent application agent: + ```sh + pnpm run build + ``` + +3. **Set the Environment Variable**: + + - Define the `AUTOSHELL_PATH` environment variable to point to the location of the `autoShell.exe` binary. For example: + ```sh + export AUTOSHELL_PATH=/path/to/autoShell.exe + ``` + +4. **Run the Automation**: + - Launch the [TypeAgent Shell](../../shell) or the [TypeAgent CLI](../../cli). + - Enable the `desktop-automation` agent by running: + ```sh + @config agent desktop + ``` + - You can now issue commands such as: + - `launch calculator` + - `maximize calculator` + - `tile calculator to the left and chrome to the right` + +For additional details, refer to the hand-written README. ## Key Files -The `desktop-automation` package is structured as follows: +The `desktop-automation` package is organized into several key files, each serving a specific purpose: -- **Manifest**: The agent's manifest is defined in [manifest.json](./src/manifest.json), which includes descriptions and schema files for the agent and its sub-actions. -- **Schema**: The actions schema is defined in [actionsSchema.ts](./src/actionsSchema.ts), which lists all possible actions the agent can perform. -- **Grammar**: The grammar for parsing user commands is defined in [desktopSchema.agr](./src/desktopSchema.agr). -- **Handler**: The main action handler is implemented in [actionHandler.ts](./src/actionHandler.ts), which processes incoming actions and interacts with the .NET component. -- **Connector**: The [connector.ts](./src/connector.ts) file manages the connection between the TypeAgent and the .NET component, handling the execution of desktop actions. +- **[manifest.json](./src/manifest.json)**: Defines the agent's metadata, including its description, schema, and grammar files. +- **[actionsSchema.ts](./src/actionsSchema.ts)**: Contains the TypeScript definitions for all supported actions, such as `LaunchProgram`, `CloseProgram`, and `SetVolume`. +- **[desktopSchema.agr](./src/desktopSchema.agr)**: Defines the grammar for parsing user commands into structured actions. +- **[actionHandler.ts](./src/actionHandler.ts)**: Implements the logic for handling actions and interacting with the .NET component. +- **[connector.ts](./src/connector.ts)**: Manages the communication between the TypeAgent and the `autoShell.exe` binary, including executing desktop actions. +- **[readiness.ts](./src/readiness.ts)**: Contains logic to check the readiness of the `autoShell.exe` binary and the overall desktop automation environment. +- **[programNameIndex.ts](./src/programNameIndex.ts)**: Handles program name indexing and similarity matching for user commands. ## How to extend -To extend the `desktop-automation` package, follow these steps: +To add new features or actions to the `desktop-automation` package, follow these steps: -1. **Add new actions**: +1. **Define New Actions**: - - Define new action types in [actionsSchema.ts](./src/actionsSchema.ts). + - Add new action types to [actionsSchema.ts](./src/actionsSchema.ts). - Update the grammar in [desktopSchema.agr](./src/desktopSchema.agr) to include the new actions. -2. **Implement action handlers**: +2. **Implement Action Handlers**: + + - Extend the [actionHandler.ts](./src/actionHandler.ts) file to include the logic for the new actions. + - Use the `connector.ts` file to interact with the `autoShell.exe` binary if the new actions require communication with the .NET component. + +3. **Update the Manifest**: - - Add the logic for handling new actions in [actionHandler.ts](./src/actionHandler.ts). + - Add descriptions and schema references for the new actions in [manifest.json](./src/manifest.json). -3. **Update the manifest**: +4. **Test Your Changes**: - - Modify [manifest.json](./src/manifest.json) to include descriptions and schema files for the new actions. + - Write unit tests for the new actions and their handlers. + - Run the tests to ensure the new functionality works as expected. -4. **Test your changes**: - - Write unit tests for the new actions and handlers. - - Run the tests to ensure everything works as expected. +5. **Build and Deploy**: + - Rebuild the .NET and TypeAgent components as described in the setup section. + - Verify the new actions are correctly recognized and executed by the agent. -By following these steps, you can extend the functionality of the `desktop-automation` package to support additional desktop automation tasks. +By following these steps, you can enhance the `desktop-automation` package to support additional desktop automation capabilities. ## Reference @@ -94,7 +147,7 @@ By following these steps, you can extend the functionality of the `desktop-autom ### Entry points - `./agent/manifest` → [./src/manifest.json](./src/manifest.json) -- `./agent/handlers` → [./dist/actionHandler.js](./dist/actionHandler.js) +- `./agent/handlers` → `./dist/actionHandler.js` _(not found on disk)_ ### Dependencies @@ -137,6 +190,6 @@ _31 actions declared in the schema, none yet implemented in [`./src/actionHandle --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter desktop-automation docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter desktop-automation docs:verify-links` to spot-check._ diff --git a/ts/packages/agents/list/README.AUTOGEN.md b/ts/packages/agents/list/README.AUTOGEN.md index d4595a6c7..bd5bba613 100644 --- a/ts/packages/agents/list/README.AUTOGEN.md +++ b/ts/packages/agents/list/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # list-agent — AI-generated documentation @@ -12,46 +12,46 @@ ## Overview -The `list-agent` package is a TypeAgent application agent designed to manage lists. It provides actions to create, modify, and retrieve lists, making it useful for applications that require list management functionality, such as to-do lists, shopping lists, or any other type of item collection. +The `list-agent` package is a TypeAgent application agent designed to manage lists. It provides functionality to create, modify, and retrieve lists, making it suitable for use cases such as to-do lists, shopping lists, or other item collections. ## What it does -The `list-agent` package offers a set of actions that allow users to interact with lists. These actions include: +The `list-agent` package supports a range of actions for interacting with lists. These actions include: -- `addItems`: Adds one or more items to a specified list. If the list does not exist, it is created. -- `removeItems`: Removes one or more items from a specified list. -- `createList`: Creates a new list with the given name. -- `getList`: Retrieves the contents of a specified list, useful for queries like "What's on my grocery list?". -- `clearList`: Clears all items from a specified list. -- `startEditList`: Initiates the editing of a specified list. +- `addItems`: Add one or more items to a specified list. If the list does not exist, it will be created. +- `removeItems`: Remove one or more items from a specified list. +- `createList`: Create a new list with a given name. +- `getList`: Retrieve the contents of a specified list. This is useful for queries like "What's on my grocery list?" or "What are the contents of my to-do list?" +- `clearList`: Remove all items from a specified list. +- `startEditList`: Begin editing a specified list. -These actions are defined in the [listSchema.ts](./src/listSchema.ts) file and are handled by the [listActionHandler.ts](./src/listActionHandler.ts) file. +These actions are defined in the [listSchema.ts](./src/listSchema.ts) file and implemented in the [listActionHandler.ts](./src/listActionHandler.ts) file. The package also includes grammar definitions in [listSchema.agr](./src/listSchema.agr) to map user utterances to these actions. ## Setup -The `list-agent` package does not require any special setup beyond installing dependencies. Ensure you have the necessary packages installed by running: +The `list-agent` package does not require any special setup beyond installing its dependencies. To get started, run: ```sh pnpm install ``` -For detailed setup instructions, refer to the hand-written README. +For additional details, refer to the hand-written README. ## Key Files -The `list-agent` package is structured around several key files: +The `list-agent` package is organized around several key files that define its functionality: -- **Manifest**: [listManifest.json](./src/listManifest.json) describes the agent, including its emoji representation and schema details. -- **Schema**: [listSchema.ts](./src/listSchema.ts) defines the types and actions supported by the agent. -- **Grammar**: [listSchema.agr](./src/listSchema.agr) contains patterns for user requests that map to actions. -- **Handler**: [listActionHandler.ts](./src/listActionHandler.ts) implements the logic for executing actions. +- **Manifest**: [listManifest.json](./src/listManifest.json) contains metadata about the agent, including its description, emoji representation, and schema details. +- **Schema**: [listSchema.ts](./src/listSchema.ts) defines the actions and their parameters, specifying what the agent can do. +- **Grammar**: [listSchema.agr](./src/listSchema.agr) includes patterns for user input that map to the defined actions. +- **Handler**: [listActionHandler.ts](./src/listActionHandler.ts) implements the logic for executing the actions defined in the schema. -### Key Files and Their Responsibilities +### File Responsibilities -- [listManifest.json](./src/listManifest.json): Contains metadata about the agent, including its description and the schema file locations. -- [listSchema.ts](./src/listSchema.ts): Defines the action types and their parameters. This file is crucial for understanding what actions the agent can perform. -- [listSchema.agr](./src/listSchema.agr): Contains the grammar rules that map user utterances to actions. This file helps in parsing and understanding user requests. -- [listActionHandler.ts](./src/listActionHandler.ts): Implements the logic for handling the actions defined in the schema. This file is where the actual functionality of each action is coded. +- [listManifest.json](./src/listManifest.json): This file provides metadata about the agent, such as its description and the locations of its schema and grammar files. +- [listSchema.ts](./src/listSchema.ts): This file defines the action types (`addItems`, `removeItems`, etc.) and their parameters. It is the primary reference for understanding the agent's capabilities. +- [listSchema.agr](./src/listSchema.agr): This file contains grammar rules that map user utterances to actions. For example, phrases like "Add milk to my grocery list" are parsed here to trigger the `addItems` action. +- [listActionHandler.ts](./src/listActionHandler.ts): This file implements the logic for handling actions. It processes the input parameters and performs the necessary operations, such as adding items to a list or retrieving list contents. ## How to extend @@ -61,7 +61,7 @@ To extend the `list-agent` package, follow these steps: - Define the new action type in [listSchema.ts](./src/listSchema.ts). - Add corresponding grammar patterns in [listSchema.agr](./src/listSchema.agr). - - Implement the action handling logic in [listActionHandler.ts](./src/listActionHandler.ts). + - Implement the action's logic in [listActionHandler.ts](./src/listActionHandler.ts). 2. **Modify existing actions**: @@ -70,10 +70,10 @@ To extend the `list-agent` package, follow these steps: - Modify the handling logic in [listActionHandler.ts](./src/listActionHandler.ts). 3. **Test your changes**: - - Ensure that your changes are covered by tests. Add or update tests in the appropriate test files. - - Run the tests to verify that your changes work as expected. + - Add or update tests to cover your changes. + - Run the tests to ensure that your modifications work as intended. -By following these steps, you can extend the functionality of the `list-agent` package to meet your specific requirements. +By following these steps, you can extend the functionality of the `list-agent` package to meet additional requirements or use cases. ## Reference @@ -82,7 +82,7 @@ By following these steps, you can extend the functionality of the `list-agent` p ### Entry points - `./agent/manifest` → [./src/listManifest.json](./src/listManifest.json) -- `./agent/handlers` → [./dist/listActionHandler.js](./dist/listActionHandler.js) +- `./agent/handlers` → `./dist/listActionHandler.js` _(not found on disk)_ ### Dependencies @@ -124,6 +124,6 @@ _6 actions implemented by this agent, parsed deterministically from `./src/listS --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter list-agent docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter list-agent docs:verify-links` to spot-check._ diff --git a/ts/packages/agents/montage/README.AUTOGEN.md b/ts/packages/agents/montage/README.AUTOGEN.md index 99a89f01f..227aabaa6 100644 --- a/ts/packages/agents/montage/README.AUTOGEN.md +++ b/ts/packages/agents/montage/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # montage-agent — AI-generated documentation @@ -12,43 +12,64 @@ ## Overview -The montage-agent package is a TypeAgent application agent designed to assist in creating photo montages. It facilitates collaborative work between the user and the agent to manage and organize images into montages. +The montage-agent package is a TypeAgent application agent designed to assist users in creating and managing photo montages. It enables collaborative workflows between users and the agent, facilitating tasks such as organizing, editing, and presenting images in a montage format. ## What it does -The montage-agent package provides a set of actions that allow users to create, modify, and manage photo montages. These actions include `createMontage`, `addPhotos`, `removePhotos`, `selectPhotos`, `setMontageViewMode`, and more. The agent interacts with various parts of the system, including image storage and processing, to perform these tasks. It also provides a web interface for users to interact with the montage creation process. +The montage-agent provides a range of actions to support the creation and management of photo montages. These actions include: + +- **Montage Creation and Management**: Actions like `createMontage`, `deleteMontage`, and `listMontage` allow users to create new montages, remove existing ones, and view a list of available montages. +- **Photo Selection and Manipulation**: Actions such as `addPhotos`, `removePhotos`, `selectPhotos`, and `clearSelection` enable users to add images to a montage, remove them, or refine the selection of images. +- **Montage Presentation**: Actions like `startSlideShow` and `setMontageViewMode` allow users to control how montages are displayed, including starting a slideshow or changing the view mode. +- **Search and Filtering**: Actions like `setSearchParameters` and `showSearchParameters` help users filter and search for specific images to include in their montages. + +The agent integrates with other system components, such as image storage, processing utilities, and knowledge processing modules, to perform these tasks. It also provides a web-based interface for users to interact with the montage creation process. ## Setup -To set up the montage-agent package, you need to configure several environment variables and ensure that certain dependencies are installed. The required environment variables include: +To set up the montage-agent package, follow these steps: -- `PORT`: The port number on which the server will run. -- `INDEX_CACHE_PATH`: The path to the image index cache. -- `ROOT_IMAGE_FOLDER`: The root folder where images are stored. +1. **Install Dependencies**: Run `pnpm install` in the package directory to install all required dependencies. +2. **Configure Environment Variables**: Set the following environment variables: + - `PORT`: The port number on which the server will run. + - `INDEX_CACHE_PATH`: The file path to the image index cache. + - `ROOT_IMAGE_FOLDER`: The root directory where images are stored. +3. **Start the Server**: Use the configured port to start the server and access the web interface for montage creation. -Additionally, you need to install the necessary dependencies using `pnpm install`. For detailed setup instructions, refer to the hand-written README. +For additional details, refer to the hand-written README. ## Key Files -The montage-agent package is organized into several key components: +The montage-agent package is organized into several key files, each serving a specific purpose: -- **Agent Manifest**: The [montageManifest.json](./src/agent/montageManifest.json) file defines the agent's schema and description. -- **Action Handler**: The [montageActionHandler.ts](./src/agent/montageActionHandler.ts) file contains the logic for executing actions related to montage creation and management. -- **Action Schema**: The [montageActionSchema.ts](./src/agent/montageActionSchema.ts) file defines the types and structure of actions that the agent can perform. -- **Route Handling**: The [route.ts](./src/route/route.ts) file sets up the Express server and handles HTTP requests. -- **Web Interface**: The [index.html](./src/site/index.html), [index.ts](./src/site/index.ts), and [styles.css](./src/site/styles.css) files provide the user interface for interacting with the montage agent. +- **[montageManifest.json](./src/agent/montageManifest.json)**: Defines the agent's schema, description, and supported actions. +- **[montageActionHandler.ts](./src/agent/montageActionHandler.ts)**: Implements the logic for handling montage-related actions, such as creating montages, adding photos, and starting slideshows. +- **[montageActionSchema.ts](./src/agent/montageActionSchema.ts)**: Specifies the types and structure of actions, activities, and entities that the agent can process. +- **[route.ts](./src/route/route.ts)**: Sets up the Express server, handles HTTP requests, and enforces origin restrictions for security. +- **[originAllowlist.ts](./src/route/originAllowlist.ts)**: Implements an origin allowlist to restrict access to the server, ensuring only trusted sources can interact with it. +- **Web Interface**: + - [index.html](./src/site/index.html): The main HTML file for the user interface. + - [index.ts](./src/site/index.ts): The JavaScript logic for the web interface. + - `styles.css`: The CSS file for styling the interface. ## How to extend To extend the montage-agent package, follow these steps: -1. **Add New Actions**: Define new actions in the [montageActionSchema.ts](./src/agent/montageActionSchema.ts) file. Ensure that the action types and parameters are clearly specified. -2. **Implement Action Logic**: Implement the logic for the new actions in the [montageActionHandler.ts](./src/agent/montageActionHandler.ts) file. Use the existing patterns for handling actions and interacting with other system components. -3. **Update Manifest**: Update the [montageManifest.json](./src/agent/montageManifest.json) file to include the new actions and their descriptions. -4. **Test**: Write tests to verify the functionality of the new actions. Ensure that the tests cover various scenarios and edge cases. -5. **Run the Server**: Start the server using the configured port and test the new actions through the web interface. - -By following these steps, you can extend the capabilities of the montage-agent package to support additional features and functionalities. +1. **Define New Actions**: + - Add new action types to the [montageActionSchema.ts](./src/agent/montageActionSchema.ts) file. Clearly define the action name, parameters, and expected behavior. +2. **Implement Action Logic**: + - Implement the logic for the new actions in the [montageActionHandler.ts](./src/agent/montageActionHandler.ts) file. Use existing patterns for consistency and ensure the new logic integrates with other system components. +3. **Update the Manifest**: + - Add the new actions to the [montageManifest.json](./src/agent/montageManifest.json) file, including descriptions and schema references. +4. **Test the Changes**: + - Write unit tests to verify the functionality of the new actions. Ensure the tests cover a variety of scenarios, including edge cases. +5. **Update the Web Interface** (if applicable): + - Modify the [index.ts](./src/site/index.ts) and [index.html](./src/site/index.html) files to expose the new actions to users through the web interface. +6. **Run and Validate**: + - Start the server and test the new functionality through the web interface or API endpoints. + +By following these steps, you can extend the montage-agent package to support additional features and workflows. ## Reference @@ -56,9 +77,9 @@ By following these steps, you can extend the capabilities of the montage-agent p ### Entry points -- default → [./dist/route/route.js](./dist/route/route.js) +- default → `./dist/route/route.js` _(not found on disk)_ - `./agent/manifest` → [./src/agent/montageManifest.json](./src/agent/montageManifest.json) -- `./agent/handlers` → [./dist/agent/montageActionHandler.js](./dist/agent/montageActionHandler.js) +- `./agent/handlers` → `./dist/agent/montageActionHandler.js` _(not found on disk)_ ### Dependencies @@ -95,6 +116,6 @@ External: `body-parser`, `d3`, `d3-cloud`, `debug`, `express`, `express-rate-lim --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter montage-agent docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter montage-agent docs:verify-links` to spot-check._ diff --git a/ts/packages/agents/screencapture/README.AUTOGEN.md b/ts/packages/agents/screencapture/README.AUTOGEN.md index 5a701b906..9b920f039 100644 --- a/ts/packages/agents/screencapture/README.AUTOGEN.md +++ b/ts/packages/agents/screencapture/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # screencapture-agent — AI-generated documentation @@ -12,71 +12,84 @@ ## Overview -The `screencapture-agent` is a TypeAgent application agent designed for screen capture and recording. It supports taking screenshots and recording the screen on Windows and Linux (X11), including targeting specific program or window names. +The `screencapture-agent` is a TypeAgent application agent that facilitates screen capture and recording. It supports taking screenshots and recording the screen on Windows and Linux (X11), with the ability to target specific programs or window names. ## What it does -This agent provides several actions for screen capture and recording: +The `screencapture-agent` provides functionality for capturing screenshots and recording screen activity. It supports the following actions: -- `takeScreenshot`: Takes a screenshot of the entire screen or a specified window. -- `startRecording`: Starts recording the screen or a specified window. +- `takeScreenshot`: Captures a screenshot of the entire screen or a specific window. If no `target` is specified, the primary screen is captured. If a `target` is provided, the agent attempts to match it to a visible window or program name. +- `startRecording`: Begins recording the screen or a specific window. Similar to `takeScreenshot`, the `target` parameter can be used to specify a particular window or program. - `stopRecording`: Stops the currently active screen recording. -- `listWindows`: Lists all currently visible windows to help users target them by name. -- `recording`: Tracks the activity while a recording is in progress. +- `listWindows`: Lists all currently visible windows, allowing users to identify and target specific windows by name. +- `recording`: Tracks the activity of an ongoing recording, including details such as the target, output path, and start time. -Captured files are stored under the agent's session storage (`screenshots/` and `recordings/` siblings) and surfaced as entities in the action result. +Captured screenshots and recordings are saved in the agent's session storage under `screenshots/` and `recordings/` directories. These files are also surfaced as entities in the action results. + +The agent is designed to work on Windows and Linux (X11) platforms. It uses system-level tools like `ffmpeg`, `wmctrl`, and `xdotool` to perform its operations. Note that Linux Wayland and macOS are not supported in this version. ## Setup -To use the `screencapture-agent`, ensure the following tools are installed on your system: +To use the `screencapture-agent`, you need to install certain system-level tools and configure environment variables. The required setup steps vary depending on your operating system. -### Windows +### Prerequisites -- `ffmpeg`: Install via `winget install Gyan.FFmpeg` or download from `https://ffmpeg.org`. +#### Windows -### Linux +- **`ffmpeg`**: Install using the command `winget install Gyan.FFmpeg` or download it from the official website at `https://ffmpeg.org`. -- `ffmpeg`: Install via `sudo apt install ffmpeg`, `sudo dnf install ffmpeg`, or `sudo pacman -S ffmpeg`. -- `wmctrl`: Install via `sudo apt install wmctrl`. -- `xdotool`: Install via `sudo apt install xdotool`. +#### Linux -Additionally, set the following environment variables: +- **`ffmpeg`**: Install using your package manager. For example: + - Debian/Ubuntu: `sudo apt install ffmpeg` + - Fedora: `sudo dnf install ffmpeg` + - Arch Linux: `sudo pacman -S ffmpeg` +- **`wmctrl`**: Install using `sudo apt install wmctrl` (Debian/Ubuntu). +- **`xdotool`**: Install using `sudo apt install xdotool` (Debian/Ubuntu). -- `DISPLAY` -- `XDG_SESSION_TYPE` +If any required tool is missing, the agent will provide an actionable installation hint when you attempt to use a feature that depends on it. After installing the necessary tools, restart your shell or CLI to ensure the changes take effect. + +### Environment Variables + +The following environment variables must be set for the agent to function correctly: + +- `DISPLAY`: Specifies the display server to use. This is typically set automatically in most Linux environments. +- `XDG_SESSION_TYPE`: Indicates the session type (e.g., `x11` or `wayland`). Note that only `x11` is supported in this version. -For detailed setup instructions, see the hand-written README. +For additional details on setup, refer to the hand-written README. ## Key Files -The `screencapture-agent` is structured into several key files: +The `screencapture-agent` is organized into several key files and directories, each serving a specific purpose: -- [screencaptureActionHandler.ts](./src/screencaptureActionHandler.ts): Contains the logic for handling screen capture and recording actions. -- [screencaptureManifest.json](./src/screencaptureManifest.json): Defines the agent's manifest, including its description and schema. -- [screencaptureSchema.ts](./src/screencaptureSchema.ts): Defines the types and parameters for the actions supported by the agent. -- [screencaptureSchema.agr](./src/screencaptureSchema.agr): Contains the grammar rules for parsing user commands. -- [context.ts](./src/context.ts): Manages the context for active recordings and tool installations. -- [platform/](./src/platform/): Contains platform-specific logic for Windows and Linux, including tool detection and command execution. +- [screencaptureActionHandler.ts](./src/screencaptureActionHandler.ts): Implements the logic for handling the agent's actions, such as taking screenshots, starting/stopping recordings, and listing windows. +- [screencaptureManifest.json](./src/screencaptureManifest.json): Defines the agent's metadata, including its description, schema, and capabilities. +- [screencaptureSchema.ts](./src/screencaptureSchema.ts): Specifies the types and parameters for the actions supported by the agent. +- [screencaptureSchema.agr](./src/screencaptureSchema.agr): Contains grammar rules that map user commands to specific actions. +- [context.ts](./src/context.ts): Manages the agent's runtime context, including active recordings and tool installation states. +- [platform/](./src/platform/): A directory containing platform-specific logic for Windows and Linux, such as tool detection, command execution, and window enumeration. ### Key Components -- **Action Handler**: The [screencaptureActionHandler.ts](./src/screencaptureActionHandler.ts) file is responsible for implementing the logic for each action, such as taking screenshots, starting and stopping recordings, and listing windows. -- **Manifest**: The [screencaptureManifest.json](./src/screencaptureManifest.json) file describes the agent, including its capabilities and the schema it uses. -- **Schema**: The [screencaptureSchema.ts](./src/screencaptureSchema.ts) file defines the types and parameters for the actions, ensuring that the agent can correctly interpret and execute user commands. -- **Grammar**: The [screencaptureSchema.agr](./src/screencaptureSchema.agr) file contains the grammar rules that map user utterances to specific actions. -- **Context Management**: The [context.ts](./src/context.ts) file manages the context for active recordings and tool installations, ensuring that the agent can track ongoing activities and handle tool setup prompts. -- **Platform-Specific Logic**: The [platform/](./src/platform/) directory contains modules for Windows and Linux, handling tasks such as tool detection, command execution, and window enumeration. +1. **Action Handler**: The [screencaptureActionHandler.ts](./src/screencaptureActionHandler.ts) file is the core of the agent, implementing the behavior for all supported actions. +2. **Manifest**: The [screencaptureManifest.json](./src/screencaptureManifest.json) file describes the agent's capabilities and links to its schema and grammar files. +3. **Schema and Grammar**: The [screencaptureSchema.ts](./src/screencaptureSchema.ts) and [screencaptureSchema.agr](./src/screencaptureSchema.agr) files define the structure of actions and the language rules for interpreting user commands. +4. **Platform-Specific Logic**: The [platform/](./src/platform/) directory contains modules for handling platform-specific requirements, such as detecting and using system tools like `ffmpeg`, `wmctrl`, and `xdotool`. ## How to extend To extend the `screencapture-agent`, follow these steps: -1. **Add new actions**: Define new action types in [screencaptureSchema.ts](./src/screencaptureSchema.ts). -2. **Update grammar**: Add corresponding grammar rules in [screencaptureSchema.agr](./src/screencaptureSchema.agr). -3. **Implement handlers**: Extend the logic in [screencaptureActionHandler.ts](./src/screencaptureActionHandler.ts) to handle the new actions. -4. **Test**: Run tests to ensure the new actions work correctly. You can use the TypeAgent Shell or CLI to invoke the actions and verify their behavior. +1. **Define a new action**: + - Add a new action type to [screencaptureSchema.ts](./src/screencaptureSchema.ts). Define the action name and its parameters. +2. **Update the grammar**: + - Add new grammar rules in [screencaptureSchema.agr](./src/screencaptureSchema.agr) to map user commands to the new action. +3. **Implement the action handler**: + - Extend the logic in [screencaptureActionHandler.ts](./src/screencaptureActionHandler.ts) to handle the new action. This may involve adding new methods or modifying existing ones. +4. **Test the new functionality**: + - Use the TypeAgent Shell or CLI to test the new action. Verify that it behaves as expected and integrates correctly with the existing functionality. -By following these steps, you can add new capabilities to the `screencapture-agent` and enhance its functionality. +By following this process, you can add new features to the `screencapture-agent` while maintaining its modular and extensible design. ## Reference @@ -85,7 +98,7 @@ By following these steps, you can add new capabilities to the `screencapture-age ### Entry points - `./agent/manifest` → [./src/screencaptureManifest.json](./src/screencaptureManifest.json) -- `./agent/handlers` → [./dist/screencaptureActionHandler.js](./dist/screencaptureActionHandler.js) +- `./agent/handlers` → `./dist/screencaptureActionHandler.js` _(not found on disk)_ ### Dependencies @@ -135,6 +148,6 @@ _5 actions implemented by this agent, parsed deterministically from `./src/scree --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter screencapture-agent docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter screencapture-agent docs:verify-links` to spot-check._ diff --git a/ts/packages/aiclient/README.AUTOGEN.md b/ts/packages/aiclient/README.AUTOGEN.md index bdf069cb1..26dac3d24 100644 --- a/ts/packages/aiclient/README.AUTOGEN.md +++ b/ts/packages/aiclient/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/aiclient — AI-generated documentation @@ -12,72 +12,77 @@ ## Overview -The `@typeagent/aiclient` package is a TypeScript library designed to facilitate interactions with various AI APIs used by the Microsoft AI Systems team. It is primarily intended for sample agents and examples within the TypeAgent project. +The `@typeagent/aiclient` package is a TypeScript library designed to interact with various AI APIs used by the Microsoft AI Systems team. It is primarily intended for use in sample agents and examples within the TypeAgent project. ## What it does -The `aiclient` package supports calling AI endpoints and other REST services, specifically: +The `aiclient` package provides functionality for calling AI endpoints and other REST services. It supports: -- OpenAI model endpoints, both on Azure and OpenAI. -- Bing search APIs. +- **OpenAI model endpoints**: Works with both Azure-hosted and OpenAI-hosted models. +- **Bing APIs**: Includes support for Bing search services. -The library includes functionality for managing settings required to call these services, which are typically sourced from environment variables. It also features multi-region endpoint pools to handle API requests efficiently, rotating among endpoints to mitigate throttling and ensure high availability. +The library is designed to simplify the process of configuring and managing API calls by leveraging environment variables for settings. It also includes advanced features like multi-region endpoint pools to improve reliability and performance when interacting with AI services. ### Multi-region endpoint pools -The package includes a sophisticated mechanism for managing multi-region endpoint pools. Chat, embedding, and image factories resolve each model into an endpoint pool — a list of endpoints (one per region + variant) that the client rotates among on 429 / 5xx / timeout errors. This helps to survive single-region throttling without user-visible stalls and keeps a PTU reservation preferred when one is configured. +The package includes a mechanism for managing multi-region endpoint pools. These pools allow the client to rotate among multiple endpoints for a given AI model, ensuring high availability and mitigating issues like throttling or regional outages. -### Selection algorithm +- **Endpoint discovery**: Endpoints are automatically discovered based on environment variable naming conventions. For example, for a model `GPT_4_O`, the library scans for variables like `AZURE_OPENAI_ENDPOINT_GPT_4_O_` and `AZURE_OPENAI_API_KEY_GPT_4_O_`. +- **Selection algorithm**: Endpoints are grouped into priority tiers. The client selects an endpoint from the lowest-priority tier that has at least one healthy member. Within a tier, endpoints are chosen randomly to distribute load. +- **Failure handling**: The client handles errors like `429` (rate limiting), `5xx` (server errors), and timeouts by marking endpoints as temporarily unavailable and rotating to the next available endpoint. Non-recoverable errors like `401` (unauthorized) are returned immediately without rotation. -Endpoints are grouped by priority tiers, with random selection within each tier. The lowest-priority tier that still has at least one healthy (non-cooling-down) member wins; within that tier, one member is picked uniformly at random. This ensures that multiple client processes spread across the regions in that tier instead of stampeding the same endpoint. +### Debugging and customization -On failure: - -- **429**: Parses `Retry-After`, marks the member as cooling for `max(Retry-After, base × 2^consecutive_429s)`, capped at 120 seconds, and rotates to the next healthy member. -- **5xx / timeout / network error**: Applies a floor cooldown of 5 seconds and rotates. -- **Non-transient 4xx** (e.g., 401): Returns immediately without rotating. +- **Debug logging**: Developers can enable the `typeagent:pool` namespace to monitor endpoint selection, rotation, and cooldown events. +- **Custom endpoint pools**: Users can override the default endpoint discovery and selection behavior by defining custom pools using the `AZURE_OPENAI_POOL_` environment variable. This allows for explicit control over endpoint priorities and configurations. ## Setup -To use the `aiclient` package, certain environment variables need to be set up. These include: +To use the `aiclient` package, you need to configure several environment variables. These variables provide the necessary settings for connecting to AI services: + +1. **Azure OpenAI endpoints and keys**: + + - `AZURE_OPENAI_ENDPOINT__`: Specifies the endpoint for a given model and region. + - `AZURE_OPENAI_API_KEY__`: Specifies the API key for a given model and region. + + If only the legacy environment variables (`AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY`) are set, the library will default to using a single endpoint. -- `AZURE_OPENAI_ENDPOINT__`: Specifies the endpoint for a given model and region. -- `AZURE_OPENAI_API_KEY__`: Specifies the API key for a given model and region. -- `BING_API_KEY`: Specifies the API key for Bing search APIs. +2. **Bing API key**: + - `BING_API_KEY`: Specifies the API key for accessing Bing search APIs. -For detailed setup instructions, including how to provision more endpoints and configure multi-region deploy and secret-sync tooling, see the hand-written README. +For detailed instructions on provisioning endpoints and setting up multi-region configurations, refer to the hand-written README. ## Key Files -The `aiclient` package is organized into several key files, each responsible for different aspects of the library: +The `aiclient` package is organized into several key files, each responsible for specific functionality: -- [index.ts](./src/index.ts): The main entry point, exporting various modules and functions. +- [index.ts](./src/index.ts): The main entry point, exporting the library's public API, including functions for creating models and managing settings. - [auth.ts](./src/auth.ts): Handles authentication, including token management and Azure credentials. -- [azureSettings.ts](./src/azureSettings.ts): Manages settings for Azure OpenAI services, loading them from environment variables. -- [bing.ts](./src/bing.ts): Contains functions and types for interacting with Bing search APIs. -- [common.ts](./src/common.ts): Utility functions for retrieving and managing environment settings. -- [endpointPool.ts](./src/endpointPool.ts): Manages endpoint pools, including selection algorithms and cooldown mechanisms. -- [modelResource.ts](./src/modelResource.ts): Functions for managing model resources, including concurrency settings. -- [models.ts](./src/models.ts): Types and settings for various AI models, including completion settings and JSON schema definitions. +- [azureSettings.ts](./src/azureSettings.ts): Manages settings for Azure OpenAI services, including loading configurations from environment variables. +- [bing.ts](./src/bing.ts): Provides functions and types for interacting with Bing search APIs. +- [common.ts](./src/common.ts): Contains utility functions for retrieving and managing environment settings. +- [endpointPool.ts](./src/endpointPool.ts): Implements the logic for managing endpoint pools, including selection algorithms and cooldown mechanisms. +- [modelResource.ts](./src/modelResource.ts): Manages model resources, including concurrency settings. +- [models.ts](./src/models.ts): Defines types and settings for various AI models, including completion settings and JSON schema definitions. ## How to extend To extend the `aiclient` package, follow these steps: -1. **Identify the area to extend**: Determine which part of the library you need to modify or add functionality to. For example, if you need to add support for a new AI model, you might start with [models.ts](./src/models.ts). +1. **Identify the area to extend**: Determine which part of the library you need to modify or enhance. For example, to add support for a new AI model, start with [models.ts](./src/models.ts). -2. **Modify or add code**: Open the relevant file and implement your changes. Follow the existing patterns and structures to ensure consistency. For example, if adding a new model, define its settings and types similarly to existing models. +2. **Implement changes**: Modify or add code in the relevant file. For instance, if adding a new model, define its settings and types in a manner consistent with the existing models. 3. **Update environment variables**: If your changes require new environment variables, update the setup instructions and ensure they are correctly loaded in the relevant settings files. -4. **Test your changes**: Write tests to verify your modifications. You can find existing tests in the `./test` directory. Ensure your tests cover various scenarios and edge cases. +4. **Write tests**: Add tests to validate your changes. Use the existing tests in the `./test` directory as a reference. Ensure your tests cover various scenarios and edge cases. -5. **Run tests**: Execute the tests to ensure everything works as expected. You can run the tests using the following command: +5. **Run tests**: Execute the tests to verify that your changes work as expected. Use the following command to run the tests: ```bash pnpm test ``` -By following these steps, you can effectively extend the functionality of the `aiclient` package while maintaining its integrity and consistency. +By following these steps, you can extend the `aiclient` package while maintaining its functionality and compatibility with the rest of the TypeAgent project. ## Reference @@ -94,7 +99,7 @@ Workspace: - [@typeagent/config](../../packages/config/README.md) -External: `@azure/identity`, `@github/copilot-sdk`, `async`, `debug`, `typechat` +External: `@azure/identity`, `@github/copilot-sdk`, `@huggingface/transformers`, `async`, `debug`, `typechat` ### Used by @@ -112,10 +117,10 @@ External: `@azure/identity`, `@github/copilot-sdk`, `async`, `debug`, `typechat` ### Files of interest -`./src/index.ts`, `./src/apiSettingsFromConfig.ts`, `./src/auth.ts`, …and 18 more under `./src/`. +`./src/index.ts`, `./src/apiSettingsFromConfig.ts`, `./src/auth.ts`, …and 20 more under `./src/`. --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/aiclient docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/aiclient docs:verify-links` to spot-check._ diff --git a/ts/packages/chat-ui/README.AUTOGEN.md b/ts/packages/chat-ui/README.AUTOGEN.md index e5d72432c..89d78dae8 100644 --- a/ts/packages/chat-ui/README.AUTOGEN.md +++ b/ts/packages/chat-ui/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # chat-ui — AI-generated documentation @@ -12,63 +12,62 @@ ## Overview -The `chat-ui` package provides shared DOM-based chat rendering for TypeAgent surfaces, including the VS Code shell extension and the browser extension chat panel. It offers a framework-free chat UI that supports rendering user and agent bubbles, streaming display updates, dynamic status, history replay, command completions, and metrics tooltips. +The `chat-ui` package provides a shared, framework-free, DOM-based chat rendering solution for TypeAgent surfaces. It is used by the VS Code shell extension, the browser extension chat panel, and other TypeAgent hosts. The package includes components and utilities for rendering user and agent messages, handling streaming updates, replaying chat history, managing command completions, and displaying dynamic status and feedback. ## What it does -The `chat-ui` package includes several key components and functionalities: +The `chat-ui` package is designed to provide a consistent and customizable chat interface for various TypeAgent hosts. Its primary component, `ChatPanel`, serves as the core of the chat UI, offering the following capabilities: -- **ChatPanel**: The main component for rendering the chat interface. It handles user input, agent messages, and display updates. -- **FeedbackWidget**: A component for collecting user feedback on interactions within the chat panel. -- **PartialCompletion**: Manages command completions using the `@typeagent/completion-ui` package. -- **PlatformAdapter**: Abstracts platform-specific behaviors for handling link clicks and settings. -- **Styles**: Shared CSS styles for consistent chat UI appearance across different hosts. +- **Rendering chat messages**: Display user and agent messages in a structured format, including support for streaming updates. +- **Dynamic status updates**: Show connection status, error messages, and manual recovery options using the `ConnectionStatus` model. +- **History replay**: Load and display previously saved chat history. +- **Command completions**: Integrate with the `@typeagent/completion-ui` package to provide real-time command suggestions. +- **Feedback collection**: Use the `FeedbackWidget` to gather user feedback on interactions within the chat interface. +- **Customizable avatars**: Hosts can use the built-in `DEFAULT_AVATAR_MAP` or override it with their own avatar mappings. +- **Content sanitization**: All HTML content is sanitized using DOMPurify to ensure security. -The package supports actions such as `addAgentMessage`, `setDisplayInfo`, and `replayHistory`, which allow hosts to interact with the chat panel and update its content dynamically. +The package also includes shared CSS styles to maintain a consistent appearance across different platforms and hosts. ## Setup -To use the `chat-ui` package, you need to install it and its dependencies. Ensure you have the following workspace dependencies: +To use the `chat-ui` package, follow these steps: -- `@typeagent/agent-sdk` -- `@typeagent/completion-ui` -- `@typeagent/dispatcher-types` +1. **Install the package**: Add `chat-ui` to your project using your package manager. +2. **Install dependencies**: Ensure the following workspace dependencies are installed: + - `@typeagent/agent-sdk` + - `@typeagent/completion-ui` + - `@typeagent/dispatcher-types` +3. **Include styles**: Import the shared CSS styles from `chat-ui/styles` into your project. These styles are required for the proper rendering of the chat UI. +4. **External dependencies**: The package relies on `ansi_up`, `dompurify`, and `markdown-it`. Ensure these dependencies are available in your project. -Additionally, the package relies on external dependencies such as `ansi_up`, `dompurify`, and `markdown-it`. - -For detailed setup instructions, including environment variables and API keys, refer to the hand-written README. +For additional setup details, refer to the hand-written README. ## Key Files -The `chat-ui` package is organized into several key files: - -- **[index.ts](./src/index.ts)**: Exports the main components and types used by the package. -- **[chatPanel.ts](./src/chatPanel.ts)**: Implements the `ChatPanel` component, handling user input, agent messages, and display updates. -- **[feedbackWidget.ts](./src/feedbackWidget.ts)**: Implements the `FeedbackWidget` component for collecting user feedback. -- **[partialCompletion.ts](./src/partialCompletion.ts)**: Manages command completions using the `@typeagent/completion-ui` package. -- **[platformAdapter.ts](./src/platformAdapter.ts)**: Defines the `PlatformAdapter` interface for handling platform-specific behaviors. -- **[setContent.ts](./src/setContent.ts)**: Contains functions for processing and sanitizing content before rendering. -- **[styles/chat.css](./styles/chat.css)**: Provides shared CSS styles for the chat UI. - -### Key Components +The `chat-ui` package is organized into several key files, each responsible for specific functionality: -- **ChatPanel**: The core component of the chat UI, responsible for rendering user and agent messages, handling user input, and updating the display dynamically. It uses DOMPurify to sanitize HTML content before insertion. -- **FeedbackWidget**: Collects user feedback on interactions within the chat panel. It includes methods for submitting feedback and managing the feedback UI. -- **PartialCompletion**: Integrates with the `@typeagent/completion-ui` package to manage command completions. It handles input updates, completion acceptance, and dismissal. -- **PlatformAdapter**: Abstracts platform-specific behaviors, such as handling link clicks and settings. This allows the chat UI to be adaptable to different environments like Electron and Chrome extensions. -- **Styles**: Shared CSS styles that ensure a consistent appearance of the chat UI across different hosts. +- **[index.ts](./src/index.ts)**: The main entry point of the package, exporting all public components, utilities, and types. +- **[chatPanel.ts](./src/chatPanel.ts)**: Implements the `ChatPanel` component, which is the core of the chat UI. It handles user input, agent messages, streaming updates, and history replay. +- **[feedbackWidget.ts](./src/feedbackWidget.ts)**: Provides the `FeedbackWidget` component for collecting user feedback on chat interactions. +- **[partialCompletion.ts](./src/partialCompletion.ts)**: Manages command completions by integrating with the `@typeagent/completion-ui` package. +- **[platformAdapter.ts](./src/platformAdapter.ts)**: Defines the `PlatformAdapter` interface for handling platform-specific behaviors, such as link clicks and settings. +- **[setContent.ts](./src/setContent.ts)**: Contains utility functions for processing and sanitizing content before rendering. +- **[connectionStatus.ts](./src/connectionStatus.ts)**: Implements the `ConnectionStatus` model and related utilities for managing and displaying connection states. +- **[contextMenu.ts](./src/contextMenu.ts)**: Implements a lightweight context menu for copy/paste and other text-related actions. +- **[styles/chat.css](./styles/chat.css)**: Provides shared CSS styles for the chat UI, ensuring a consistent look and feel across different hosts. ## How to extend -To extend the `chat-ui` package, follow these steps: +To customize or extend the `chat-ui` package, follow these steps: -1. **Start with the main component**: Open the [chatPanel.ts](./src/chatPanel.ts) file to understand how the `ChatPanel` component is implemented. This is the core of the chat UI. -2. **Add new features**: Implement new functionalities or modify existing ones within the `ChatPanel` component. Ensure that any new HTML content is sanitized using DOMPurify. -3. **Update styles**: If you need to change the appearance of the chat UI, modify the [styles/chat.css](./styles/chat.css) file. -4. **Handle platform-specific behaviors**: If your extension needs to handle specific platform behaviors, update the [platformAdapter.ts](./src/platformAdapter.ts) file. -5. **Test your changes**: Run tests to ensure your changes work as expected. You can add new tests or modify existing ones to cover your new functionalities. +1. **Understand the core component**: Start by reviewing the [chatPanel.ts](./src/chatPanel.ts) file, which contains the implementation of the `ChatPanel` component. This is the central piece of the chat UI. +2. **Add new features**: To introduce new functionality, modify or extend the `ChatPanel` or other relevant components. For example, you can add new methods to handle additional types of messages or interactions. +3. **Update styles**: To change the appearance of the chat UI, edit the [styles/chat.css](./styles/chat.css) file. This file contains the shared CSS styles used across all hosts. +4. **Handle platform-specific needs**: If your host requires custom behavior (e.g., handling specific link clicks or settings), update the [platformAdapter.ts](./src/platformAdapter.ts) file to implement the necessary changes. +5. **Leverage existing utilities**: Use the provided utilities, such as `setContent` and `renderConnectionStatus`, to ensure consistency and reduce duplication. +6. **Test your changes**: After making modifications, test your changes thoroughly. Add or update tests to verify the new functionality. -By following these steps, you can effectively extend the `chat-ui` package to meet your specific requirements. For detailed instructions and examples, refer to the hand-written README. +By following these guidelines, you can effectively extend the `chat-ui` package to meet the requirements of your specific TypeAgent host. For further details, consult the hand-written README and the source files mentioned above. ## Reference @@ -76,7 +75,7 @@ By following these steps, you can effectively extend the `chat-ui` package to me ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ - `./styles` → [./styles/chat.css](./styles/chat.css) ### Dependencies @@ -98,10 +97,10 @@ External: `ansi_up`, `dompurify`, `markdown-it` ### Files of interest -`./src/index.ts`, `./src/chatPanel.ts`, `./src/contextMenu.ts`, …and 9 more under `./src/`. +`./src/index.ts`, `./src/chatPanel.ts`, `./src/connectionStatus.ts`, …and 10 more under `./src/`. --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter chat-ui docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter chat-ui docs:verify-links` to spot-check._ diff --git a/ts/packages/config/README.AUTOGEN.md b/ts/packages/config/README.AUTOGEN.md index 03fba7cad..871cfc217 100644 --- a/ts/packages/config/README.AUTOGEN.md +++ b/ts/packages/config/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/config — AI-generated documentation @@ -12,27 +12,27 @@ ## Overview -The `@typeagent/config` package is a TypeScript library designed to provide a layered YAML configuration loader for the TypeAgent ecosystem. It enables the loading and merging of configuration settings from multiple sources, such as default YAML files, local overrides, environment variables, and Azure Key Vault. The package ensures that configuration settings are applied in a defined order of precedence and includes schema validation to maintain data integrity. +The `@typeagent/config` package is a TypeScript library that provides a layered YAML configuration loader for the TypeAgent ecosystem. It enables the loading, merging, and validation of configuration settings from multiple sources, ensuring a consistent and structured approach to managing application configurations. ## What it does -The `@typeagent/config` package provides the following functionality: +The primary purpose of `@typeagent/config` is to manage configuration data for the TypeAgent ecosystem. It achieves this by combining configuration values from various sources in a defined order of precedence. The package supports the following features: -1. **Layered Configuration Loading**: The package supports loading configuration from multiple sources, including: +1. **Layered Configuration Sources**: - - `ts/config.defaults.yaml`: A committed default configuration file. - - `ts/config.local.yaml`: A local, gitignored configuration file for overrides. - - `.env`: A legacy fallback for backward compatibility. - - Environment variables: These take the highest precedence and allow runtime overrides. - - Azure Key Vault: Future phases will include fetching configuration from Key Vault and caching it locally in an encrypted format. + - **Default YAML Configuration**: Reads from `ts/config.defaults.yaml`, a committed file containing default settings. + - **Local Overrides**: Reads from `ts/config.local.yaml`, a gitignored file for local customizations. + - **Environment Variables**: Allows runtime overrides with the highest precedence. + - **.env Fallback**: Supports legacy `.env` files as a fallback mechanism. + - **Azure Key Vault**: Future phases will include fetching configuration from Azure Key Vault and caching it locally in an encrypted format. -2. **Configuration Flattening**: Nested YAML configuration trees are flattened into flat key-value pairs that align with the `EnvVars` convention used by other TypeAgent packages. This ensures compatibility with existing code that relies on `process.env`. +2. **Flattening Configuration**: Converts nested YAML structures into flat key-value pairs that align with the `EnvVars` convention used by other TypeAgent packages. This ensures compatibility with existing code that relies on `process.env`. -3. **Schema Validation**: The package uses `zod` to validate configuration settings, ensuring they conform to expected schemas. +3. **Schema Validation**: Uses `zod` to validate configuration data, ensuring it adheres to predefined schemas and reducing the risk of misconfiguration. -4. **CLI Commands**: A CLI is included for tasks such as importing `.env` files into YAML format and displaying the merged configuration. +4. **Command-Line Interface (CLI)**: Provides commands for tasks such as converting `.env` files to YAML format and displaying the merged configuration. -5. **Merge Precedence**: Configuration values are merged in the following order (lowest to highest precedence): +5. **Merge Precedence**: Configuration values are merged in the following order, from lowest to highest precedence: - `.env` (legacy fallback) - `ts/config.defaults.yaml` @@ -40,28 +40,28 @@ The `@typeagent/config` package provides the following functionality: - `ts/config.local.yaml` - `process.env` (runtime overrides) -6. **Redaction of Sensitive Data**: The package includes functionality to identify and redact sensitive values in configuration data, such as API keys and secrets. +6. **Sensitive Data Handling**: Includes functionality to identify and redact sensitive information, such as API keys and secrets, from configuration data. ## Setup -To use the `@typeagent/config` package, ensure the following environment variables are set: +To use the `@typeagent/config` package, you need to configure the following environment variables: - `AZURE_OPENAI_`: Used for Azure OpenAI configuration. -- `JEST_WORKER_ID`: Used during Jest testing. +- `JEST_WORKER_ID`: Utilized during Jest testing. - `TYPEAGENT_ALLOW_KEYVAULT_IN_TESTS`: Enables Key Vault integration during tests. -- `TYPEAGENT_CONFIG_DEFAULTS`: Path to the default configuration YAML file. -- `TYPEAGENT_CONFIG_DIR`: Directory where configuration files are located. -- `TYPEAGENT_CONFIG_LOCAL`: Path to the local configuration YAML file. -- `TYPEAGENT_CONFIG_SECRET`: Secret name for the configuration in Azure Key Vault. -- `TYPEAGENT_CONFIG_VAULT`: Azure Key Vault name. -- `TYPEAGENT_DOTENV`: Path to the `.env` file. -- `TYPEAGENT_USER_DATA_DIR`: Directory for user data. +- `TYPEAGENT_CONFIG_DEFAULTS`: Specifies the path to the default configuration YAML file. +- `TYPEAGENT_CONFIG_DIR`: Defines the directory where configuration files are located. +- `TYPEAGENT_CONFIG_LOCAL`: Specifies the path to the local configuration YAML file. +- `TYPEAGENT_CONFIG_SECRET`: Indicates the secret name for the configuration in Azure Key Vault. +- `TYPEAGENT_CONFIG_VAULT`: Specifies the Azure Key Vault name. +- `TYPEAGENT_DOTENV`: Points to the `.env` file for legacy fallback. +- `TYPEAGENT_USER_DATA_DIR`: Specifies the directory for user data. Refer to the hand-written README for detailed instructions on obtaining these values and configuring your environment. ## Key Files -The package's source code is organized into the following key files: +The package's source code is organized into several key files, each responsible for specific functionality: - [index.ts](./src/index.ts): Exports the main functions and types, such as `loadConfig`, `flatten`, and `fetchKeyVaultConfig`. - [loader.ts](./src/loader.ts): Implements the core logic for loading and merging configuration settings from various sources. @@ -74,21 +74,21 @@ The package's source code is organized into the following key files: ## How to extend -To extend the functionality of the `@typeagent/config` package, consider the following approaches: +To extend the `@typeagent/config` package, follow these guidelines: -1. **Adding New Configuration Sources**: To include additional configuration sources, modify [loader.ts](./src/loader.ts) to incorporate the new source and update the merging logic. +1. **Adding New Configuration Sources**: To support additional configuration sources, modify [loader.ts](./src/loader.ts) to include the new source and update the merging logic. -2. **Customizing Flattening Rules**: If you need to adjust how configuration settings are flattened, update the logic in [flatten.ts](./src/flatten.ts). Ensure the changes align with the `EnvVars` convention. +2. **Customizing Flattening Rules**: If you need to change how configuration settings are flattened, update the logic in [flatten.ts](./src/flatten.ts). Ensure the changes are consistent with the `EnvVars` convention. 3. **Enhancing Schema Validation**: To add or modify validation rules, update [schema.ts](./src/schema.ts). Use `zod` to define the new schema and validation logic. -4. **Extending CLI Functionality**: To add new CLI commands, modify [cli.ts](./src/cli.ts). Implement the new commands and ensure they integrate with the existing configuration logic. +4. **Extending CLI Functionality**: To introduce new CLI commands, modify [cli.ts](./src/cli.ts). Implement the new commands and ensure they integrate with the existing configuration logic. -5. **Improving Azure Key Vault Integration**: To enhance the integration with Azure Key Vault, update [keyVault.ts](./src/keyVault.ts). You can add new methods for fetching, caching, or managing secrets. +5. **Improving Azure Key Vault Integration**: To enhance Azure Key Vault functionality, update [keyVault.ts](./src/keyVault.ts). You can add new methods for fetching, caching, or managing secrets. 6. **Redacting Additional Sensitive Data**: If new sensitive data types need to be redacted, update the logic in [redact.ts](./src/redact.ts). Ensure the new patterns are comprehensive and tested. -When extending the package, ensure that new functionality adheres to the existing patterns and conventions to maintain consistency and compatibility across the TypeAgent ecosystem. +When making changes, adhere to the existing patterns and conventions to maintain consistency and compatibility with the rest of the TypeAgent ecosystem. ## Reference @@ -140,6 +140,6 @@ _10 environment variables referenced from `./src/` (set in `ts/.env` or your she --- -_Auto-generated against commit `ff379b098decfab4eb45f78b6fa318358d7fbd75` on `2026-07-01T09:05:58.471Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/config docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/config docs:verify-links` to spot-check._ diff --git a/ts/packages/dispatcher/dispatcher/README.AUTOGEN.md b/ts/packages/dispatcher/dispatcher/README.AUTOGEN.md index 079bad8f2..70fe5aab2 100644 --- a/ts/packages/dispatcher/dispatcher/README.AUTOGEN.md +++ b/ts/packages/dispatcher/dispatcher/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # agent-dispatcher — AI-generated documentation @@ -12,15 +12,15 @@ ## Overview -The TypeAgent Dispatcher is a core component of the TypeAgent repository that facilitates the creation of personal agents with natural language interfaces using structured prompting and large language models (LLMs). It can be integrated and hosted in various front ends, such as the TypeAgent Shell and TypeAgent CLI, and supports an extensible application agents architecture. +The TypeAgent Dispatcher is a core component of the TypeAgent repository, designed to process user requests and translate them into structured actions using large language models (LLMs) and structured prompting. It serves as the central hub for managing interactions between users and application agents, enabling natural language interfaces for a variety of tasks. The Dispatcher can be integrated into different front ends, such as the TypeAgent Shell and CLI, and supports an extensible architecture for application agents. ## What it does -The Dispatcher processes user requests and translates them into actions based on schemas provided by application agents. It can automatically switch between different agents to provide a cohesive experience. The Dispatcher supports natural language requests and system commands, enabling users to interact with the system in a flexible manner. +The Dispatcher enables users to interact with application agents through natural language or system commands. It translates user inputs into structured actions based on predefined schemas provided by the application agents. The Dispatcher also facilitates switching between different agents to handle diverse tasks, ensuring a cohesive user experience. ### Natural Language Requests -Users can request actions provided by application agents using natural language. For example, in the CLI: +The Dispatcher allows users to issue natural language requests, which are translated into structured actions. For example, in the CLI: ```bash [calendar]🤖> can you setup a meeting between 2-3PM @@ -29,50 +29,91 @@ Generating translation using GPT for 'can you setup a meeting between 2-3PM' Accept? (y/n) ``` -Other examples include: +Other examples of natural language requests include: - `play some music by Bach for me please` - `create a grocery list` - `add milk to the grocery list` -### Commands +### System Commands -Users can specify system commands with inputs starting with `@`. Examples include toggling dispatcher agents, configuring explainers, and managing conversations. +In addition to natural language, the Dispatcher supports system commands that begin with `@`. These commands allow users to interact directly with the system. Examples include: + +- **Toggling Dispatcher Agents**: Enable or disable specific agents or groups of agents using commands like `@config agent ` or `@config agent --off `. +- **Configuring Explainers**: Change the explainer implementation used by the Dispatcher with commands like `@config explainer name `. +- **Managing Conversations**: Use commands such as `@conversation` to create, switch, rename, or delete conversations. + +### Reasoning and Explanation + +The Dispatcher can invoke reasoning engines like Claude or Copilot to process user requests. The reasoning engine can be configured using the `@reasoning` command. Additionally, the Dispatcher can generate explanations for the actions it translates, which can be configured using the `@config explainer` command. + +### Session Management + +The Dispatcher supports session management, allowing settings and data to persist across application restarts. Sessions are stored in the user's profile directory and can be managed using the `@session` command. ## Setup -The Dispatcher requires several environment variables to be set for proper operation: +To use the Dispatcher, the following environment variables must be configured: -- `CLAUDE_CUSTOM_PROMPT_FILE` -- `CLAUDE_FORCE_REASONING` -- `COPILOT_REASONING_EFFORT` -- `COPILOT_REASONING_MODEL` -- `COSMOSDB_CONNECTION_STRING` -- `INSTANCE_NAME` -- `TYPEAGENT_REASONING_TIMEOUT_MS` -- `TYPEAGENT_REQUEST_ACTION_LOG_DIR` -- `TYPEAGENT_USER_DATA_DIR` +- `CLAUDE_CUSTOM_PROMPT_FILE`: Path to a custom prompt file for the Claude reasoning engine. +- `CLAUDE_FORCE_REASONING`: Boolean flag to force the use of Claude for reasoning. +- `COPILOT_REASONING_EFFORT`: Effort level for the Copilot reasoning engine. +- `COPILOT_REASONING_MODEL`: Model to use for Copilot reasoning. +- `COSMOSDB_CONNECTION_STRING`: Connection string for Azure Cosmos DB. +- `INSTANCE_NAME`: Name of the current instance. +- `TYPEAGENT_REASONING_TIMEOUT_MS`: Timeout (in milliseconds) for reasoning operations. +- `TYPEAGENT_REQUEST_ACTION_LOG_DIR`: Directory for logging request actions. +- `TYPEAGENT_USER_DATA_DIR`: Directory for storing user data. Refer to the hand-written README for detailed instructions on obtaining and setting these values. ## Key Files -The Dispatcher is organized into several key components: +The Dispatcher is organized into several key components, each responsible for specific functionality: + +### Handlers + +Handlers are responsible for processing specific commands. They are located in [./src/context/dispatcher/handlers/](./src/context/dispatcher/handlers/). Key files include: + +- [explainCommandHandler.ts](./src/context/dispatcher/handlers/explainCommandHandler.ts): Handles commands related to explaining actions. +- [matchCommandHandler.ts](./src/context/dispatcher/handlers/matchCommandHandler.ts): Handles matching-related commands. +- [reasonCommandHandler.ts](./src/context/dispatcher/handlers/reasonCommandHandler.ts): Handles reasoning commands. +- [requestCommandHandler.ts](./src/context/dispatcher/handlers/requestCommandHandler.ts): Handles user requests. +- [translateCommandHandler.ts](./src/context/dispatcher/handlers/translateCommandHandler.ts): Handles translation of natural language into structured actions. + +### Schemas + +Schemas define the structure of actions and are located in [./src/context/dispatcher/schema/](./src/context/dispatcher/schema/). Key files include: + +- [activityActionSchema.ts](./src/context/dispatcher/schema/activityActionSchema.ts): Defines the schema for activity-related actions. +- [clarifyActionSchema.ts](./src/context/dispatcher/schema/clarifyActionSchema.ts): Defines the schema for clarification actions. +- [dispatcherActionSchema.ts](./src/context/dispatcher/schema/dispatcherActionSchema.ts): Defines the schema for dispatcher-specific actions. +- [lookupActionSchema.ts](./src/context/dispatcher/schema/lookupActionSchema.ts): Defines the schema for lookup actions. +- [reasoningActionSchema.ts](./src/context/dispatcher/schema/reasoningActionSchema.ts): Defines the schema for reasoning actions. + +### Helpers + +Utility functions and classes are provided in [./src/helpers/](./src/helpers/). Notable files include: -- **Handlers**: Located in [./src/context/dispatcher/handlers/](./src/context/dispatcher/handlers/), these files handle specific commands such as [explainCommandHandler.ts](./src/context/dispatcher/handlers/explainCommandHandler.ts), [matchCommandHandler.ts](./src/context/dispatcher/handlers/matchCommandHandler.ts), [reasonCommandHandler.ts](./src/context/dispatcher/handlers/reasonCommandHandler.ts), [requestCommandHandler.ts](./src/context/dispatcher/handlers/requestCommandHandler.ts), and [translateCommandHandler.ts](./src/context/dispatcher/handlers/translateCommandHandler.ts). -- **Schemas**: Located in [./src/context/dispatcher/schema/](./src/context/dispatcher/schema/), these files define the structure of actions, including [activityActionSchema.ts](./src/context/dispatcher/schema/activityActionSchema.ts), [clarifyActionSchema.ts](./src/context/dispatcher/schema/clarifyActionSchema.ts), [dispatcherActionSchema.ts](./src/context/dispatcher/schema/dispatcherActionSchema.ts), [lookupActionSchema.ts](./src/context/dispatcher/schema/lookupActionSchema.ts), and [reasoningActionSchema.ts](./src/context/dispatcher/schema/reasoningActionSchema.ts). -- **Helpers**: Various utility functions and classes are provided in [./src/helpers/](./src/helpers/), such as [console.ts](./src/helpers/console.ts), [userData.ts](./src/helpers/userData.ts), [userSettings.ts](./src/helpers/userSettings.ts), [config.ts](./src/helpers/config.ts), [status.ts](./src/helpers/status.ts), [command.ts](./src/helpers/command.ts), and [completion/index.ts](./src/helpers/completion/index.ts). +- [console.ts](./src/helpers/console.ts): Handles console-related utilities. +- [userData.ts](./src/helpers/userData.ts): Manages user data operations. +- [userSettings.ts](./src/helpers/userSettings.ts): Manages user settings. +- [config.ts](./src/helpers/config.ts): Handles configuration management. +- [status.ts](./src/helpers/status.ts): Provides status-related utilities. +- [command.ts](./src/helpers/command.ts): Manages command execution. +- [completion/index.ts](./src/helpers/completion/index.ts): Handles command completion logic. ## How to extend -To extend the Dispatcher, follow these steps: +To extend the functionality of the Dispatcher, follow these steps: -1. **Add a new handler**: Create a new file in [./src/context/dispatcher/handlers/](./src/context/dispatcher/handlers/) and implement the necessary logic for the new command. -2. **Define a new schema**: Create a new file in [./src/context/dispatcher/schema/](./src/context/dispatcher/schema/) to define the structure of the new action. -3. **Update the Dispatcher**: Modify the Dispatcher to recognize and process the new command and schema. -4. **Test the changes**: Ensure that the new functionality works as expected by running tests and verifying the integration with existing components. +1. **Create a New Handler**: Add a new file in [./src/context/dispatcher/handlers/](./src/context/dispatcher/handlers/) and implement the logic for the new command. Use existing handlers as a reference for structure and patterns. +2. **Define a New Schema**: Add a new file in [./src/context/dispatcher/schema/](./src/context/dispatcher/schema/) to define the structure of the new action. Ensure the schema aligns with the expected input and output for the action. +3. **Update the Dispatcher**: Modify the Dispatcher to recognize and process the new command and schema. This may involve updating configuration files or modifying existing logic. +4. **Test Your Changes**: Write unit tests for the new functionality and run the test suite to ensure compatibility with existing components. Use the CLI or Shell to manually verify the new functionality. +5. **Document Your Changes**: Update the relevant documentation to include details about the new functionality, including usage examples and any new commands or configuration options. -For more detailed information on the Dispatcher architecture and design, refer to the dispatcher architecture documentation. +For more detailed guidance, refer to the dispatcher architecture documentation and the hand-written README. ## Reference @@ -80,16 +121,16 @@ For more detailed information on the Dispatcher architecture and design, refer t ### Entry points -- default → [./dist/index.js](./dist/index.js) -- `./helpers/console` → [./dist/helpers/console.js](./dist/helpers/console.js) -- `./helpers/data` → [./dist/helpers/userData.js](./dist/helpers/userData.js) -- `./helpers/userSettings` → [./dist/helpers/userSettings.js](./dist/helpers/userSettings.js) -- `./helpers/config` → [./dist/helpers/config.js](./dist/helpers/config.js) -- `./helpers/status` → [./dist/helpers/status.js](./dist/helpers/status.js) -- `./helpers/command` → [./dist/helpers/command.js](./dist/helpers/command.js) -- `./helpers/completion` → [./dist/helpers/completion/index.js](./dist/helpers/completion/index.js) -- `./internal` → [./dist/internal.js](./dist/internal.js) -- `./explorer` → [./dist/explorer.js](./dist/explorer.js) +- default → `./dist/index.js` _(not found on disk)_ +- `./helpers/console` → `./dist/helpers/console.js` _(not found on disk)_ +- `./helpers/data` → `./dist/helpers/userData.js` _(not found on disk)_ +- `./helpers/userSettings` → `./dist/helpers/userSettings.js` _(not found on disk)_ +- `./helpers/config` → `./dist/helpers/config.js` _(not found on disk)_ +- `./helpers/status` → `./dist/helpers/status.js` _(not found on disk)_ +- `./helpers/command` → `./dist/helpers/command.js` _(not found on disk)_ +- `./helpers/completion` → `./dist/helpers/completion/index.js` _(not found on disk)_ +- `./internal` → `./dist/internal.js` _(not found on disk)_ +- `./explorer` → `./dist/explorer.js` _(not found on disk)_ ### Dependencies @@ -144,7 +185,7 @@ External: `@anthropic-ai/claude-agent-sdk`, `@azure/core-client`, `@azure/core-r - [./src/context/dispatcher/schema/dispatcherActionSchema.ts](./src/context/dispatcher/schema/dispatcherActionSchema.ts) - [./src/context/dispatcher/schema/lookupActionSchema.ts](./src/context/dispatcher/schema/lookupActionSchema.ts) - [./src/context/dispatcher/schema/reasoningActionSchema.ts](./src/context/dispatcher/schema/reasoningActionSchema.ts) -- _…and 184 more under `./src/`._ +- _…and 185 more under `./src/`._ ### Environment variables @@ -162,6 +203,6 @@ _9 environment variables referenced from `./src/` (set in `ts/.env` or your shel --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter agent-dispatcher docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter agent-dispatcher docs:verify-links` to spot-check._ diff --git a/ts/packages/knowPro/README.AUTOGEN.md b/ts/packages/knowPro/README.AUTOGEN.md index aa82192f5..88b76171b 100644 --- a/ts/packages/knowPro/README.AUTOGEN.md +++ b/ts/packages/knowPro/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # knowpro — AI-generated documentation @@ -12,45 +12,85 @@ ## Overview -The `knowpro` package is a TypeScript library designed to implement a basic structured Retrieval-Augmented Generation (RAG) system. It is part of the TypeAgent monorepo and is actively developed to explore various types of memory and structured information extraction from conversations and other forms of text. +The `knowpro` package is a TypeScript library that implements a basic structured Retrieval-Augmented Generation (RAG) system. It is part of the TypeAgent monorepo and is actively developed to explore structured information extraction and various types of memory, such as conversation, document, and image memory. ## What it does -The `knowpro` package provides functionalities for structured prompting and leveraging large language models (LLMs) to handle natural language queries and generate answers. It supports the following capabilities: +The `knowpro` package provides tools for working with structured RAG, focusing on extracting and utilizing structured information from conversations and other text-based sources. Its primary capabilities include: -- **Natural language queries**: Translating user requests into structured query expressions. -- **Answer generation**: Using query results to generate natural language answers. -- **Search**: Converting user requests into query expressions and executing them to retrieve relevant entities, topics, and actions. -- **Indexing**: Storing and updating information in suitable indexes for efficient retrieval. +- **Natural Language Querying**: Converts user requests into structured query expressions using large language models (LLMs). This includes handling natural language queries and translating them into precise search expressions. +- **Search and Retrieval**: Executes structured queries to retrieve relevant entities, topics, and actions from indexed data. It supports scope expressions (e.g., time ranges, topic descriptions) and tree-pattern expressions for fine-grained matching. +- **Answer Generation**: Generates natural language answers by combining query results with additional context, such as messages and entities, to create a comprehensive response. +- **Indexing and Data Management**: Manages structured and unstructured data in indexes, enabling efficient search and retrieval. These indexes can be updated incrementally or in the background. -The package interacts with other parts of the system, such as the `conversation-memory` package for agent memory and various memory types including transcripts, documents, emails, and images. +The package integrates with other components in the TypeAgent ecosystem, such as the `conversation-memory` package, to support various memory types, including transcripts, documents, emails, and images. It is designed to work with LLMs, with primary testing conducted using GPT-4o. ## Setup -To set up the `knowpro` package, ensure you have the necessary dependencies installed. The package relies on several internal and external libraries, including `aiclient`, `knowledge-processor`, `typeagent`, and others. +To use the `knowpro` package, follow these steps: -For detailed setup instructions, including environment variables and API keys, refer to the hand-written README. +1. **Install Dependencies**: Ensure that all required dependencies are installed. The package depends on other internal libraries, such as `@typeagent/aiclient`, `knowledge-processor`, and `typeagent`, as well as external libraries like `async`, `debug`, `fast-levenshtein`, and `typechat`. + +2. **Environment Configuration**: If the hand-written README or other documentation specifies environment variables or API keys, ensure they are correctly configured. For example, you may need to set up access to an LLM API like GPT-4o. + +3. **Integration**: The package is designed to work with other components in the TypeAgent monorepo. Ensure that the relevant memory packages (e.g., `conversation-memory`) are properly configured if you plan to use them in conjunction with `knowpro`. + +Refer to the hand-written README for any additional setup details or prerequisites. ## Key Files -The `knowpro` package is organized into several key components: +The `knowpro` package is organized into several key files and modules, each responsible for specific functionality: + +- **Schemas**: + + - [answerContextSchema.ts](./src/answerContextSchema.ts): Defines the structure of the context used for generating answers, including entities, topics, and messages. + - [answerResponseSchema.ts](./src/answerResponseSchema.ts): Specifies the structure of the answer responses, including types like `NoAnswer` and `Answered`. + +- **Search**: + + - [search.ts](./src/search.ts): Handles the conversion of natural language queries into structured query expressions and executes them. + - [searchLang.ts](./src/searchLang.ts): Provides natural language processing capabilities for query generation. + +- **Answer Generation**: + + - [answerGenerator.ts](./src/answerGenerator.ts): Implements the logic for generating answers based on query results and additional context. + +- **Indexes**: -- **Schemas**: Define the structure of the data used in the package, such as [answerContextSchema.ts](./src/answerContextSchema.ts) and [answerResponseSchema.ts](./src/answerResponseSchema.ts). -- **Search**: Handles the conversion of natural language queries into structured query expressions and executes them. Key files include [search.ts](./src/search.ts) and [searchLang.ts](./src/searchLang.ts). -- **Answer Generation**: Generates answers based on the results of executed queries. This is managed by [answerGenerator.ts](./src/answerGenerator.ts). -- **Indexes**: Store and manage the information extracted from conversations and other text sources. Relevant files include [conversationIndex.ts](./src/conversationIndex.ts) and [secondaryIndexes.ts](./src/secondaryIndexes.ts). -- **Common Utilities**: Provide shared functionality across the package, such as [common.ts](./src/common.ts). + - [conversationIndex.ts](./src/conversationIndex.ts): Manages the indexing of conversation data for efficient retrieval. + - [secondaryIndexes.ts](./src/secondaryIndexes.ts): Handles secondary indexes for additional search capabilities, such as related terms and time ranges. + +- **Utilities**: + - [common.ts](./src/common.ts): Contains shared utility functions and types used across the package. + - [collections.ts](./src/collections.ts): Provides internal data structures and methods for managing query results and matches. ## How to extend -To extend the `knowpro` package, follow these steps: +To extend the functionality of the `knowpro` package, follow these steps: + +1. **Understand the Existing Structure**: + + - Review the key files listed above to understand the current implementation. + - Familiarize yourself with the base interfaces and types defined in [interfaces.ts](./src/interfaces.ts). + +2. **Add or Modify Components**: + + - To enhance search capabilities, start with [search.ts](./src/search.ts) or [searchLang.ts](./src/searchLang.ts). + - To introduce new types of structured data, update or create new schemas in files like [answerContextSchema.ts](./src/answerContextSchema.ts). + - To improve answer generation, modify [answerGenerator.ts](./src/answerGenerator.ts) or related files. + +3. **Extend Indexing**: + + - If you need to add new indexing capabilities, consider extending [secondaryIndexes.ts](./src/secondaryIndexes.ts) or [conversationIndex.ts](./src/conversationIndex.ts). + +4. **Testing**: + + - Write tests to validate your changes. The `knowpro-test` package is available for testing the `knowpro` API and its memory implementations. -1. **Identify the component to extend**: Determine whether you need to add new schemas, enhance search capabilities, or improve answer generation. -2. **Modify or add files**: Based on the identified component, modify existing files or add new ones. For example, to add a new type of index, you might start with [secondaryIndexes.ts](./src/secondaryIndexes.ts). -3. **Update interfaces**: Ensure that any new functionality is reflected in the base interfaces and types defined in [interfaces.ts](./src/interfaces.ts). -4. **Test your changes**: Write tests to validate your changes. The `knowpro-test` package can be used to test the `knowpro` API and memory implementations. +5. **Integration**: + - Ensure that your changes integrate smoothly with other components in the TypeAgent monorepo, such as `conversation-memory` or `knowledge-processor`. -For detailed examples and further guidance, refer to the [KnowPro test app](../../examples/chat/README.md) and other related documentation. +For practical examples and additional guidance, refer to the [KnowPro test app](../../examples/chat/README.md) and related documentation. ## Reference @@ -58,7 +98,7 @@ For detailed examples and further guidance, refer to the [KnowPro test app](../. ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -91,6 +131,6 @@ External: `async`, `debug`, `fast-levenshtein`, `typechat` --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter knowpro docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter knowpro docs:verify-links` to spot-check._ diff --git a/ts/packages/knowledgeProcessor/README.AUTOGEN.md b/ts/packages/knowledgeProcessor/README.AUTOGEN.md index 0f327ea0a..27d526790 100644 --- a/ts/packages/knowledgeProcessor/README.AUTOGEN.md +++ b/ts/packages/knowledgeProcessor/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # knowledge-processor — AI-generated documentation @@ -12,45 +12,87 @@ ## Overview -The `knowledge-processor` package is a TypeScript library designed to explore early ideas in Structured Retrieval-Augmented Generation (RAG). It is primarily used by the TypeAgent Dispatcher to implement Agent Memory for the TypeAgent Shell. The package focuses on extracting knowledge from various sources, indexing it for retrieval, generating queries, and producing answers based on the retrieved knowledge. +The `knowledge-processor` package is a TypeScript library designed to explore early concepts in Structured Retrieval-Augmented Generation (RAG). It is primarily used by the TypeAgent Dispatcher to implement Agent Memory for the TypeAgent Shell. The package focuses on extracting, indexing, and utilizing knowledge from various sources such as conversations, documents, images, and transcripts. It also supports generating structured queries and natural language answers based on retrieved knowledge. + +This package is considered sample code and represents an experimental approach to Structured RAG. For the latest developments in this area, refer to the `knowPro` package. ## What it does -The `knowledge-processor` package provides functionalities to: +The `knowledge-processor` package provides a set of tools and actions to facilitate the following: -- **Extract knowledge**: from conversations, transcripts, images, and documents. -- **Index knowledge**: store and index the extracted knowledge and source text for efficient retrieval. -- **Generate queries**: translate natural language questions into structured queries to retrieve relevant knowledge. -- **Generate answers**: use the results of queries to generate natural language answers. +- **Knowledge Extraction**: Extracts structured knowledge from diverse sources, including conversations, documents, images, and transcripts. This is achieved through actions like `extractKnowledge`. +- **Knowledge Indexing**: Organizes and stores extracted knowledge for efficient retrieval. This includes text indexing, key-value indexing, and temporal indexing. +- **Query Generation**: Translates natural language questions into structured queries to retrieve relevant knowledge. Actions like `searchKnowledge` are used for this purpose. +- **Answer Generation**: Produces natural language answers based on the results of queries. Actions such as `generateAnswer` and `createMessage` are central to this functionality. -The package includes several actions related to conversation management, knowledge extraction, and query processing. Key actions include `createMessage`, `extractKnowledge`, `generateAnswer`, and `searchKnowledge`. +The package is tightly integrated with other components in the TypeAgent ecosystem, such as the `@typeagent/aiclient` for AI model interactions and `typechat-utils` for handling structured data. ## Setup -To set up the `knowledge-processor` package, ensure you have the necessary dependencies installed. The package relies on several external libraries such as `@azure-rest/maps-search`, `debug`, `exifreader`, `sharp`, and `typechat`. Additionally, it depends on other workspace packages like `aiclient`, `typeagent`, and `typechat-utils`. +To use the `knowledge-processor` package, ensure the following prerequisites are met: -For detailed setup instructions, including environment variables and API keys, refer to the hand-written README. +1. **Install Dependencies**: The package depends on several internal and external libraries. Use `pnpm install` to install all required dependencies. +2. **Environment Variables**: If any environment variables or API keys are required, refer to the hand-written README for detailed instructions on how to configure them. +3. **External Libraries**: The package relies on external libraries such as `@azure-rest/maps-search`, `debug`, `exifreader`, `sharp`, and `typechat`. Ensure these are correctly installed and configured. ## Key Files -The `knowledge-processor` package is organized into several modules, each responsible for different aspects of knowledge processing: +The `knowledge-processor` package is organized into several key modules, each responsible for a specific aspect of knowledge processing: + +### Conversation Management + +- **[conversationManager.ts](./src/conversation/conversationManager.ts)**: Central to managing conversations and integrating various components like knowledge extraction and indexing. +- **[conversation.ts](./src/conversation/conversation.ts)**: Handles the core logic for managing conversation topics and messages. +- **[answerGenerator.ts](./src/conversation/answerGenerator.ts)**: Responsible for generating natural language answers from query results. +- **[answerContext.ts](./src/conversation/answerContext.ts)**: Defines the structure and handling of context used in answer generation. + +### Knowledge Extraction + +- **[knowledge.ts](./src/conversation/knowledge.ts)**: Implements methods for extracting and managing knowledge from various sources. +- **[knowledgeSchema.ts](./src/conversation/knowledgeSchema.ts)**: Defines the schema for representing extracted knowledge. +- **[knowledgeActions.ts](./src/conversation/knowledgeActions.ts)**: Contains actions related to knowledge extraction and processing. + +### Indexing + +- **[textIndex.ts](./src/textIndex.ts)**: Manages text-based indexing for efficient retrieval. +- **[keyValueIndex.ts](./src/keyValueIndex.ts)**: Implements key-value-based indexing mechanisms. +- **[temporal.ts](./src/temporal.ts)**: Handles temporal indexing and operations on time-based data. + +### Storage + +- **[storageProvider.ts](./src/storageProvider.ts)**: Provides storage solutions for indexed knowledge. +- **[modelCache.ts](./src/modelCache.ts)**: Implements caching mechanisms for AI models and other data. -- **Conversation**: Handles conversation-related functionalities, including managing conversation topics, extracting knowledge from conversations, and generating answers. Key files include [conversationManager.ts](./src/conversation/conversationManager.ts), [conversation.ts](./src/conversation/conversation.ts), and [answerGenerator.ts](./src/conversation/answerGenerator.ts). -- **Knowledge Extraction**: Focuses on extracting knowledge from various sources. This includes schemas for knowledge representation and actions for knowledge extraction. Key files include [knowledgeSchema.ts](./src/conversation/knowledgeSchema.ts), [knowledgeActions.ts](./src/conversation/knowledgeActions.ts), and [knowledge.ts](./src/conversation/knowledge.ts). -- **Indexing**: Manages the indexing of extracted knowledge for efficient retrieval. This includes text indexing, key-value indexing, and temporal indexing. Key files include [textIndex.ts](./src/textIndex.ts), [keyValueIndex.ts](./src/keyValueIndex.ts), and [temporal.ts](./src/temporal.ts). -- **Storage**: Provides storage solutions for the indexed knowledge. Key files include [storageProvider.ts](./src/storageProvider.ts) and [modelCache.ts](./src/modelCache.ts). +### Schemas + +- **[aggregateTopicSchema.ts](./src/conversation/aggregateTopicSchema.ts)**: Defines schemas for managing and aggregating conversation topics. +- **[answerSchema.ts](./src/conversation/answerSchema.ts)**: Specifies the structure of answers, including their relevance and content. +- **[dateTimeSchema.ts](./src/conversation/dateTimeSchema.ts)**: Provides schemas for handling date and time data. ## How to extend To extend the `knowledge-processor` package, follow these steps: -1. **Identify the module to extend**: Determine whether you need to add functionalities related to conversation management, knowledge extraction, indexing, or storage. -2. **Open the relevant file**: Start by opening the file that corresponds to the module you want to extend. For example, if you want to add a new knowledge extraction method, open [knowledge.ts](./src/conversation/knowledge.ts). -3. **Follow existing patterns**: Review the existing code to understand the patterns and structures used. Implement your new functionality following these patterns. -4. **Add tests**: Ensure your new functionality is well-tested. Add unit tests in the corresponding test files to validate your changes. -5. **Run tests**: Execute the tests to verify that your changes work as expected and do not break existing functionalities. +1. **Understand the Existing Structure**: Familiarize yourself with the key files and their responsibilities. For example, if you want to add a new feature for knowledge extraction, start by reviewing [knowledge.ts](./src/conversation/knowledge.ts) and [knowledgeActions.ts](./src/conversation/knowledgeActions.ts). + +2. **Add New Functionality**: + + - For new actions, define the action schema in the appropriate file (e.g., [knowledgeSchema.ts](./src/conversation/knowledgeSchema.ts)). + - Implement the action logic in the corresponding handler file (e.g., [knowledgeActions.ts](./src/conversation/knowledgeActions.ts)). + +3. **Update Indexing or Storage**: + + - If your extension involves new indexing or storage requirements, consider extending the relevant files like [textIndex.ts](./src/textIndex.ts) or [storageProvider.ts](./src/storageProvider.ts). + +4. **Test Your Changes**: + + - Add unit tests to validate your new functionality. Place these tests in the appropriate test files. + - Run the test suite to ensure your changes do not introduce regressions. + +5. **Document Your Changes**: + - Update the hand-written README or other relevant documentation to describe your new functionality and how to use it. -By following these steps, you can effectively extend the `knowledge-processor` package to meet your specific requirements. +By following these guidelines, you can effectively contribute to the `knowledge-processor` package and enhance its capabilities. ## Reference @@ -58,7 +100,7 @@ By following these steps, you can effectively extend the `knowledge-processor` p ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -91,6 +133,6 @@ External: `@azure-rest/maps-search`, `debug`, `exifreader`, `sharp`, `typechat` --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter knowledge-processor docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter knowledge-processor docs:verify-links` to spot-check._ diff --git a/ts/packages/memory/conversation/README.AUTOGEN.md b/ts/packages/memory/conversation/README.AUTOGEN.md index f3108914f..dad286153 100644 --- a/ts/packages/memory/conversation/README.AUTOGEN.md +++ b/ts/packages/memory/conversation/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # conversation-memory — AI-generated documentation @@ -12,55 +12,59 @@ ## Overview -The `conversation-memory` package is a TypeScript library designed to implement various types of conversational memory using Structured Retrieval-Augmented Generation (RAG). It leverages the `KnowPro` package to index and search through sequences of timestamped messages, documents, emails, and other forms of conversational data. +The `conversation-memory` package is a TypeScript library that implements various types of conversational memory using Structured Retrieval-Augmented Generation (RAG). It leverages the `KnowPro` package for indexing and searching through structured data, enabling efficient storage, retrieval, and analysis of conversational and document-based information. + +This package is designed to handle a wide range of conversational data, including chat messages, emails, transcripts, and documents. It supports incremental updates, natural language queries, and the generation of human-readable answers based on indexed knowledge. ## What it does -The `conversation-memory` package provides functionality to manage and query different types of conversational memories, including: +The `conversation-memory` package provides tools to manage and query different types of conversational memories. These include: -- **Conversation Memory**: Interactive chats, agent interaction history, and invocation/response memory. -- **Document Memory**: Transcripts of meetings, videos, chats, markdown, and HTML documents. -- **Email Memory**: Collections of email messages. -- **Podcast Memory**: Transcripts of podcasts. +- **Conversation Memory**: Tracks interactive chats, agent interaction history, and invocation/response memory. New messages can be added and indexed incrementally, with extracted knowledge such as entities, actions, and topics enabling precise search and retrieval. +- **Document Memory**: Manages collections of document parts, such as meeting transcripts, video transcripts, markdown files, and HTML documents. Documents can be imported, indexed, and queried for summaries, lists, or specific information. +- **Email Memory**: Handles collections of email messages. Emails can be imported from `.eml` files, indexed, and queried for specific information, such as conversations between specific participants or topics discussed. +- **Podcast Memory**: Manages transcripts of podcasts, enabling indexing and querying for specific topics or segments. -These memories are indexed incrementally, allowing new messages, emails, transcript chunks, or document parts to be added and indexed as they come in. The package extracts salient knowledge such as entities, actions, and topics from new messages, enabling precise search and retrieval with low latency. Users can query these memories using natural language or structured search expressions, and the package can generate answers, summaries, and analyses based on the indexed data. +The package supports both natural language queries and structured search expressions. It can answer questions, generate summaries, and provide analyses based on the indexed data. Additionally, memories can be persisted to disk and reloaded as needed. ## Setup -To set up the `conversation-memory` package, follow these steps: +To use the `conversation-memory` package, follow these steps: -1. Install the necessary dependencies using `pnpm install`. -2. Set up environment variables as required by the `KnowPro` and `memory-storage` packages. -3. Ensure you have access to external services like OpenAI for embedding models. +1. **Install dependencies**: Run `pnpm install` to install the required dependencies. +2. **Environment variables**: Ensure that any necessary environment variables for the `KnowPro` and `memory-storage` packages are set. Refer to the hand-written README for details on these variables and how to configure them. +3. **External services**: If using embedding models, ensure access to the required external services, such as OpenAI. -For detailed setup instructions, see the hand-written README. +For more detailed setup instructions, consult the hand-written README. ## Key Files -The `conversation-memory` package is organized into several key files and modules: +The `conversation-memory` package is structured into several key files, each responsible for specific functionalities: -- **[index.ts](./src/index.ts)**: Exports the main functionalities of the package, including podcast, memory, conversation memory, email memory, and document memory modules. -- **[conversationMemory.ts](./src/conversationMemory.ts)**: Implements the `ConversationMemory` class, handling interactive chats and agent interaction history. -- **[docMemory.ts](./src/docMemory.ts)**: Implements the `DocMemory` class, managing collections of document parts. -- **[emailMemory.ts](./src/emailMemory.ts)**: Implements the `EmailMemory` class, managing collections of email messages. -- **[podcast.ts](./src/podcast.ts)**: Implements the `PodcastMemory` class, handling podcast transcripts. -- **[common.ts](./src/common.ts)**: Contains common utility functions used across different memory types. -- **[docImport.ts](./src/docImport.ts)**: Handles the import of text documents into `DocMemory`. -- **[emailImport.ts](./src/emailImport.ts)**: Handles the import of email messages into `EmailMemory`. +- **[index.ts](./src/index.ts)**: The main entry point of the package, exporting core functionalities for managing different types of memories. +- **[conversationMemory.ts](./src/conversationMemory.ts)**: Implements the `ConversationMemory` class, which handles interactive chats and agent interaction history. +- **[docMemory.ts](./src/docMemory.ts)**: Implements the `DocMemory` class for managing collections of document parts, such as transcripts and text files. +- **[emailMemory.ts](./src/emailMemory.ts)**: Implements the `EmailMemory` class for managing collections of email messages. +- **[podcast.ts](./src/podcast.ts)**: Implements the `PodcastMemory` class for handling podcast transcripts. +- **[common.ts](./src/common.ts)**: Provides utility functions used across different memory types, such as creating embedding models and managing indexing states. +- **[docImport.ts](./src/docImport.ts)**: Handles the import of text documents into `DocMemory`, supporting formats like `.vtt`, `.md`, `.html`, and `.txt`. +- **[emailImport.ts](./src/emailImport.ts)**: Handles the import of email messages in MIME format into `EmailMemory`. ## How to extend To extend the `conversation-memory` package, follow these steps: -1. **Identify the memory type** you want to extend (e.g., conversation, document, email, podcast). -2. **Open the corresponding file** (e.g., [conversationMemory.ts](./src/conversationMemory.ts), [docMemory.ts](./src/docMemory.ts), [emailMemory.ts](./src/emailMemory.ts), [podcast.ts](./src/podcast.ts)). -3. **Add new functionalities** or modify existing ones. Ensure that new messages or data types are properly indexed and searchable. -4. **Update the schema** if necessary, such as modifying [docSearchQuerySchema.ts](./src/docSearchQuerySchema.ts) for document-related queries. -5. **Write tests** to validate your changes. Use the `test-lib` package for testing utilities. - -For example, to add a new type of conversational memory, you might start by creating a new class similar to `ConversationMemory` and implement methods for adding messages, indexing, and querying. Ensure that the new class integrates with the existing indexing and search mechanisms provided by `KnowPro`. +1. **Determine the memory type**: Identify the type of memory you want to extend or create (e.g., conversation, document, email, podcast). +2. **Locate the relevant file**: Open the corresponding file for the memory type you want to work on: + - Conversation: [conversationMemory.ts](./src/conversationMemory.ts) + - Document: [docMemory.ts](./src/docMemory.ts) + - Email: [emailMemory.ts](./src/emailMemory.ts) + - Podcast: [podcast.ts](./src/podcast.ts) +3. **Add or modify functionality**: Implement new methods or enhance existing ones. Ensure that new data types or messages are properly indexed and can be queried. +4. **Update schemas**: If your changes involve new query types or data structures, update the relevant schema files, such as [docSearchQuerySchema.ts](./src/docSearchQuerySchema.ts). +5. **Test your changes**: Write and run tests to validate your modifications. Use the `test-lib` package for testing utilities. -By following these steps, you can extend the `conversation-memory` package to support additional types of conversational data or enhance its existing capabilities. +For example, to add support for a new type of memory, you could create a new class similar to `ConversationMemory` or `DocMemory`. Implement methods for adding data, indexing, and querying, and ensure integration with the `KnowPro` indexing and search mechanisms. ## Reference @@ -68,7 +72,7 @@ By following these steps, you can extend the `conversation-memory` package to su ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -101,6 +105,6 @@ External: `async`, `debug`, `mailparser`, `typechat`, `webvtt-parser` --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter conversation-memory docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter conversation-memory docs:verify-links` to spot-check._ diff --git a/ts/packages/memory/image/README.AUTOGEN.md b/ts/packages/memory/image/README.AUTOGEN.md index 178ef210d..f6d7672b2 100644 --- a/ts/packages/memory/image/README.AUTOGEN.md +++ b/ts/packages/memory/image/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # image-memory — AI-generated documentation @@ -12,64 +12,108 @@ ## Overview -The `image-memory` package is an experimental TypeScript library designed to implement image memory using structured Retrieval-Augmented Generation (RAG). It leverages the `KnowPro` library to create an image collection that can be queried based on both knowledge content and metadata. This package is part of the TypeAgent monorepo and integrates with several other packages to provide its functionality. +The `image-memory` package is an experimental TypeScript library designed to implement image memory using structured Retrieval-Augmented Generation (RAG). It leverages the `KnowPro` library to create an `ImageCollection` that can be queried using natural language. This package is part of the TypeAgent monorepo and integrates with other packages such as `@typeagent/aiclient`, `knowledge-processor`, and `memory-storage` to provide its functionality. ## What it does -The `image-memory` package provides the capability to index and query images using natural language. It supports actions such as `importImages` to index images from a specified path and `indexingService` to start an indexing service for images. The package allows images to be searched based on their content and metadata, making it possible to ask questions and get answers about the images in natural language. +The primary purpose of the `image-memory` package is to enable the indexing and querying of images based on their metadata and knowledge content. This allows users to interact with an image collection using natural language queries, making it easier to retrieve relevant images and associated information. -Key actions include: +### Key Features -- `importImages`: Indexes images from a specified path. -- `indexingService`: Starts an indexing service for images. +- **Image Indexing**: The `importImages` action allows users to index images from a specified path. This process extracts metadata and knowledge from the images and stores them in a structured format. +- **Indexing Service**: The `indexingService` action starts a service to monitor and index images in a specified folder. This service can handle changes in the folder, such as the addition of new images. +- **Natural Language Querying**: Users can query the indexed images using natural language to retrieve relevant results based on the images' metadata and knowledge content. -These actions enable users to build and maintain a searchable image collection, leveraging natural language processing to enhance the querying capabilities. +These features make the `image-memory` package a foundational component for building applications that require intelligent image search and retrieval capabilities. ## Setup -To set up the `image-memory` package, ensure you have the necessary dependencies installed. The package relies on several internal and external dependencies, including `@azure-rest/maps-search`, `better-sqlite3`, `debug`, `get-folder-size`, and `typechat`. +To use the `image-memory` package, follow these steps: -Environment variables: +1. **Install Dependencies**: Ensure that all required dependencies are installed. The package relies on both internal and external dependencies, including: -- `DEBUG`: Set this variable to enable debug logging. + - Internal: `@typeagent/aiclient`, `knowledge-processor`, `knowPro`, `memory-storage`, `telemetry`, `typeagent`, `typechat-utils` + - External: `@azure-rest/maps-search`, `better-sqlite3`, `debug`, `get-folder-size`, `typechat` -For detailed setup instructions, including how to obtain API keys and configure environment variables, refer to the hand-written README. +2. **Environment Variables**: -## Key Files + - `DEBUG`: Set this environment variable to enable debug logging. For example, you can set it to `typeagent:image-memory` to see debug logs specific to this package. + +3. **Additional Configuration**: + - If you are using the `indexingService` action, ensure that the folder you want to index is accessible and contains the images you wish to process. -The `image-memory` package is structured into several key files, each responsible for different aspects of the functionality: +For more detailed setup instructions, including how to obtain API keys for external dependencies, refer to the hand-written README. -- [index.ts](./src/index.ts): The entry point that exports various modules. -- [imageCollection.ts](./src/imageCollection.ts): Defines the `ImageCollection` class, which represents a collection of images and provides methods for indexing and querying. -- [imageMeta.ts](./src/imageMeta.ts): Defines the `Image` and `ImageMeta` classes, which represent individual images and their metadata. -- [importImages.ts](./src/importImages.ts): Provides the `importImages` function to index images from a specified path. -- [indexingService.ts](./src/indexingService.ts): Starts an indexing service for images. -- [tables.ts](./src/tables.ts): Defines database tables for storing image metadata. +## Key Files -### Detailed File Responsibilities +The `image-memory` package is organized into several key files, each responsible for specific functionality: -- **[index.ts](./src/index.ts)**: Serves as the main entry point, exporting functions and classes from other modules. -- **[imageCollection.ts](./src/imageCollection.ts)**: Contains the `ImageCollection` class, which manages a collection of images, including methods for adding images and querying them. -- **[imageMeta.ts](./src/imageMeta.ts)**: Defines the structure for image metadata and individual image objects, including methods for extracting knowledge from images. +- **[index.ts](./src/index.ts)**: The main entry point of the package, exporting all public modules and functions. +- **[imageCollection.ts](./src/imageCollection.ts)**: Defines the `ImageCollection` class, which serves as the core data structure for managing and querying images. +- **[imageMeta.ts](./src/imageMeta.ts)**: Contains the `Image` and `ImageMeta` classes, which represent individual images and their associated metadata. - **[importImages.ts](./src/importImages.ts)**: Implements the `importImages` function, which indexes images from a specified path and returns an `ImageCollection`. - **[indexingService.ts](./src/indexingService.ts)**: Provides functionality to start and manage an indexing service for images, including monitoring changes in the indexed folder. -- **[tables.ts](./src/tables.ts)**: Defines the `GeoTable` and `ExposureTable` classes for storing geographic and exposure metadata of images in a SQLite database. +- **[tables.ts](./src/tables.ts)**: Defines database tables for storing image metadata, such as geographic and exposure information. + +### File Responsibilities + +1. **[index.ts](./src/index.ts)**: + + - Serves as the main entry point for the package. + - Exports key functions and classes, including `importImages`, `indexingService`, `ImageCollection`, and database table definitions. + +2. **[imageCollection.ts](./src/imageCollection.ts)**: + + - Implements the `ImageCollection` class, which manages a collection of images. + - Provides methods for adding images, querying them, and managing their metadata. + +3. **[imageMeta.ts](./src/imageMeta.ts)**: + + - Defines the `Image` class, which represents an individual image and its associated metadata. + - Implements methods for extracting knowledge from images and managing metadata. + +4. **[importImages.ts](./src/importImages.ts)**: + + - Provides the `importImages` function, which allows users to index images from a specified path. + - Supports recursive indexing of directories and handles metadata extraction. + +5. **[indexingService.ts](./src/indexingService.ts)**: + + - Starts an indexing service for images, enabling continuous monitoring and indexing of a specified folder. + - Tracks the state of the indexing process and provides progress updates. + +6. **[tables.ts](./src/tables.ts)**: + - Defines the `GeoTable` and `ExposureTable` classes for storing geographic and exposure metadata of images in a SQLite database. ## How to extend -To extend the `image-memory` package, follow these steps: +To extend the `image-memory` package, follow these guidelines: + +1. **Understand the Existing Codebase**: + + - Start by reviewing the key files, especially [imageCollection.ts](./src/imageCollection.ts) and [imageMeta.ts](./src/imageMeta.ts), to understand how images and their metadata are managed. + +2. **Add New Features**: + + - To add new functionality, such as additional metadata extraction or new querying capabilities, consider extending the `ImageCollection` or `ImageMeta` classes. + - For example, you can add new methods to `ImageCollection` to support advanced search features or integrate additional metadata fields in `ImageMeta`. + +3. **Modify the Indexing Service**: + + - If you need to enhance the indexing service, start with [indexingService.ts](./src/indexingService.ts). You can add support for new data sources or improve the monitoring capabilities. -1. **Open the relevant file**: Depending on the functionality you want to add or modify, open the appropriate file. For example, to add new indexing capabilities, start with [indexingService.ts](./src/indexingService.ts). +4. **Update Database Schema**: -2. **Follow existing patterns**: Review the existing code to understand the patterns used for indexing and querying images. For example, the `ImageCollection` class in [imageCollection.ts](./src/imageCollection.ts) provides a good example of how to structure a collection of images. + - If your changes require new database tables or modifications to existing ones, update [tables.ts](./src/tables.ts) accordingly. Ensure that your changes are backward-compatible and well-documented. -3. **Add new functionality**: Implement the new functionality by extending the existing classes or adding new ones. Ensure that your code integrates well with the existing structure and follows the established patterns. +5. **Write Tests**: -4. **Test your changes**: Write tests to verify your changes. Ensure that your new functionality works as expected and does not break existing features. + - Add unit tests for your new functionality to ensure it works as expected. Use the existing test cases as a reference for writing your tests. -5. **Run tests**: Execute the tests to validate your changes. Make sure all tests pass before submitting your changes. +6. **Run Tests**: + - Execute the test suite to verify that your changes do not introduce any regressions. Address any issues before submitting your changes. -By following these steps, you can effectively extend the `image-memory` package to add new features or improve existing ones. +By following these steps, you can contribute to the `image-memory` package effectively and ensure that your changes align with the existing codebase and project goals. ## Reference @@ -77,7 +121,7 @@ By following these steps, you can effectively extend the `image-memory` package ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -106,6 +150,6 @@ External: `@azure-rest/maps-search`, `better-sqlite3`, `debug`, `get-folder-size --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter image-memory docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter image-memory docs:verify-links` to spot-check._ diff --git a/ts/packages/typeagent/README.AUTOGEN.md b/ts/packages/typeagent/README.AUTOGEN.md index 9cd0457d9..6c89a16e9 100644 --- a/ts/packages/typeagent/README.AUTOGEN.md +++ b/ts/packages/typeagent/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # typeagent — AI-generated documentation @@ -12,19 +12,19 @@ ## Overview -The `typeagent` package is a sample library code used by and intended only for the example agents and apps in the TypeAgent project. It provides various utilities and components that facilitate async processing, vectors and embeddings, storage, text processing, and collections. +The `typeagent` package is a sample library designed to support the development of agents and applications within the TypeAgent project. It provides a collection of utilities and components for tasks such as asynchronous processing, vector and embedding operations, storage management, text processing, and collection utilities. While it is primarily intended for internal use within the TypeAgent ecosystem, it serves as a foundational library for many other packages and examples in the project. ## What it does -The `typeagent` package offers a range of functionalities that are essential for building and running agents within the TypeAgent ecosystem. Key capabilities include: +The `typeagent` package offers a variety of utilities and components that are essential for building and running agents. These include: -- **Async Processing**: Functions like `mapAsync` in [arrayAsync.ts](./src/arrayAsync.ts) and `callWithRetry` in [async.ts](./src/async.ts) enable concurrent and retryable async operations. -- **Vectors and Embeddings**: Utilities for handling vector operations and embeddings, such as `vectorIndex` and `semanticMap`, found in the `vector` directory. -- **Storage**: Components for managing storage, including `objectFolder`, `objectPage`, and `embeddingFS`, located in the `storage` directory. -- **Text Processing**: Tools for processing text, including `textClassifier` in [textClassifier.ts](./src/classifier/textClassifier.ts) and `createTypeChat` in [chat.ts](./src/chat.ts). -- **Collections**: Various collection utilities provided in [lib/index.ts](./src/lib/index.ts). +- **Async Processing**: Functions like `mapAsync` (in [arrayAsync.ts](./src/arrayAsync.ts)) and `callWithRetry` (in [async.ts](./src/async.ts)) provide tools for concurrent and retryable asynchronous operations. +- **Vectors and Embeddings**: A suite of utilities for working with vectors and embeddings, such as `vectorIndex` and `semanticMap`, located in the `vector` directory. +- **Storage Management**: Tools for managing data storage, including `objectFolder`, `objectPage`, and `embeddingFS`, which are implemented in the `storage` directory. +- **Text Processing**: Functions for text-related tasks, such as `createTypeChat` (in [chat.ts](./src/chat.ts)) for chat interactions and `createTextClassifier` (in [textClassifier.ts](./src/classifier/textClassifier.ts)) for text classification. +- **Collections**: A variety of collection utilities, such as `binarySearch` and `isUndefinedOrEmpty`, provided in [lib/array.ts](./src/lib/array.ts). -These components are used by multiple packages and examples within the TypeAgent project, making `typeagent` a foundational library for the ecosystem. +These components are widely used across the TypeAgent project, making `typeagent` a critical dependency for other packages and examples. ## Setup @@ -34,40 +34,44 @@ The `typeagent` package does not require any special setup beyond installing its pnpm install ``` -For detailed setup instructions, see the hand-written README. +For additional details, refer to the hand-written README. ## Key Files -The `typeagent` package is organized into several key files and directories, each responsible for different aspects of the library: +The `typeagent` package is organized into several key files and directories, each serving a specific purpose: -- **[src/index.ts](./src/index.ts)**: The main entry point that exports various modules and components. -- **[src/arrayAsync.ts](./src/arrayAsync.ts)**: Contains functions for async array processing, such as `mapAsync`. -- **[src/async.ts](./src/async.ts)**: Provides utilities for retrying async operations with `callWithRetry`. -- **[src/chat.ts](./src/chat.ts)**: Implements the `createTypeChat` function for handling chat interactions. -- **[src/classifier/textClassifier.ts](./src/classifier/textClassifier.ts)**: Defines the `createTextClassifier` function for text classification. +- **[src/index.ts](./src/index.ts)**: The main entry point that exports the package's modules and components. +- **[src/arrayAsync.ts](./src/arrayAsync.ts)**: Contains utilities for asynchronous array processing, such as `mapAsync`. +- **[src/async.ts](./src/async.ts)**: Provides functions for retrying asynchronous operations, including `callWithRetry`. +- **[src/chat.ts](./src/chat.ts)**: Implements the `createTypeChat` function, which facilitates chat interactions with context and history. +- **[src/classifier/textClassifier.ts](./src/classifier/textClassifier.ts)**: Defines the `createTextClassifier` function for text classification tasks. - **[src/constraints.ts](./src/constraints.ts)**: Contains the `createConstraintsValidator` function for validating constraints. -- **[src/dateTime.ts](./src/dateTime.ts)**: Provides utilities for handling date and time operations. -- **[src/lib/array.ts](./src/lib/array.ts)**: Includes various array utilities, such as `binarySearch`. +- **[src/dateTime.ts](./src/dateTime.ts)**: Provides utilities for handling and formatting date and time values. +- **[src/lib/array.ts](./src/lib/array.ts)**: Includes various array utilities, such as `binarySearch` and `isUndefinedOrEmpty`. + +Additionally, the `vector` and `storage` directories contain specialized utilities for vector operations and storage management, respectively. ## How to extend To extend the `typeagent` package, follow these steps: -1. **Identify the area to extend**: Determine which component or utility you need to modify or add to. For example, if you need to add a new async processing function, start with [arrayAsync.ts](./src/arrayAsync.ts). +1. **Identify the area to extend**: Determine which component or utility you need to modify or add to. For example, if you need to add a new text processing function, start with [textProcessing.ts](./src/textProcessing.ts). -2. **Create or modify files**: Add new functions or modify existing ones in the appropriate file. Ensure that your code follows the existing patterns and conventions. +2. **Create or modify files**: Add new functions or modify existing ones in the appropriate file. Follow the established patterns and coding conventions in the package. -3. **Export your additions**: Make sure to export your new functions or components in [index.ts](./src/index.ts) so they are accessible to other parts of the TypeAgent project. +3. **Update exports**: Ensure that your new functions or components are exported in [index.ts](./src/index.ts) so they can be accessed by other parts of the TypeAgent project. -4. **Write tests**: Add tests for your new functionality to ensure it works as expected. Place your tests in the corresponding test files or create new ones if necessary. +4. **Write tests**: Create tests for your new functionality to ensure it works as expected. Add these tests to the corresponding test files or create new ones if necessary. -5. **Run tests**: Execute the test suite to verify that your changes do not break existing functionality. Use the following command: +5. **Run tests**: Use the following command to execute the test suite and verify that your changes do not introduce any regressions: ```sh pnpm test ``` -By following these steps, you can effectively extend the `typeagent` package and contribute to the TypeAgent project. +6. **Document your changes**: Update the hand-written README or other relevant documentation to reflect your additions or modifications. + +By following these steps, you can contribute to the `typeagent` package and enhance its functionality for the TypeAgent ecosystem. ## Reference @@ -75,7 +79,7 @@ By following these steps, you can effectively extend the `typeagent` package and ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -106,6 +110,6 @@ External: `async`, `cheerio`, `debug`, `typechat`, `typescript` --- -_Auto-generated against commit `127a36a95a15e918be533d6eaaf08adebe9070d9` on `2026-06-26T03:01:52.873Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter typeagent docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter typeagent docs:verify-links` to spot-check._ diff --git a/ts/packages/vscode-shell/README.AUTOGEN.md b/ts/packages/vscode-shell/README.AUTOGEN.md index e0451ea0b..4fca80fc7 100644 --- a/ts/packages/vscode-shell/README.AUTOGEN.md +++ b/ts/packages/vscode-shell/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # vscode-shell — AI-generated documentation @@ -16,12 +16,12 @@ The `vscode-shell` package integrates the TypeAgent shell chat into Visual Studi ## What it does -This package enables users to interact with TypeAgent conversations directly within the Visual Studio Code environment. It provides a rich set of features for managing and participating in conversations, including: +The `vscode-shell` package allows users to interact with TypeAgent conversations directly within the Visual Studio Code environment. It provides the following features: - **Activity Bar Integration**: A dedicated icon in the activity bar opens the persistent **Chat** side panel. - **Editor Tabs for Chats**: Users can open multiple chat tabs in the editor, each representing a separate conversation. - **Command Palette Commands**: A variety of commands are available under the "TypeAgent" category, such as `Open Chat in Editor`, `New Chat (Side Panel)`, `Focus Chat`, `New Conversation`, `Switch Conversation`, `Rename Conversation`, `Delete Conversation`, and `Clear Chat View`. -- **IntelliSense Support**: Provides inline ghost text suggestions and dropdown menus for command completions. +- **IntelliSense Support**: Offers inline ghost text suggestions and dropdown menus for command completions. - **Conversation Management**: Users can create, rename, switch, and delete conversations using either slash commands (e.g., `@conversation new [name]`) or natural language inputs (e.g., "create a new conversation called Brainstorm"). - **Request Management**: Users can cancel in-progress or queued requests directly from the chat interface, with clear visual indicators for request status. @@ -150,6 +150,6 @@ External: `ansi_up`, `debug`, `dompurify`, `isomorphic-ws`, `markdown-it`, `ws` --- -_Auto-generated against commit `ff379b098decfab4eb45f78b6fa318358d7fbd75` on `2026-07-01T09:05:58.471Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter vscode-shell docs:verify-links` to spot-check._ +_Auto-generated against commit `88f04471002e27f82ae1ddf73a7ae8acdfe09b5d` on `2026-07-03T09:02:51.801Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter vscode-shell docs:verify-links` to spot-check._