From 42838d0fa5d8a283c8a74a28a74ec7be1ee505ed Mon Sep 17 00:00:00 2001 From: TypeAgent-Bot Date: Wed, 1 Jul 2026 09:09:29 +0000 Subject: [PATCH] docs: regenerate package README.AUTOGEN.md files (2026-07-01) Automated by the docs-generate workflow. AI body authored via GitHub Models; deterministic Reference computed from source. 11 file(s) updated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ts/packages/actionGrammar/README.AUTOGEN.md | 133 ++++++++++----- ts/packages/agentSdk/README.AUTOGEN.md | 82 ++++----- ts/packages/cache/README.AUTOGEN.md | 110 +++++++----- ts/packages/config/README.AUTOGEN.md | 88 ++++++---- ts/packages/dispatcher/rpc/README.AUTOGEN.md | 84 +++++---- .../dispatcher/types/README.AUTOGEN.md | 59 ++++--- ts/packages/shell/README.AUTOGEN.md | 73 +++++--- ts/packages/studio-service/README.AUTOGEN.md | 60 +++---- ts/packages/typeagent-core/README.AUTOGEN.md | 104 ++++++----- .../typeagent-studio/README.AUTOGEN.md | 161 ++++++++++++------ ts/packages/vscode-shell/README.AUTOGEN.md | 96 +++++++---- 11 files changed, 643 insertions(+), 407 deletions(-) diff --git a/ts/packages/actionGrammar/README.AUTOGEN.md b/ts/packages/actionGrammar/README.AUTOGEN.md index ac2e359bf..b957e43c0 100644 --- a/ts/packages/actionGrammar/README.AUTOGEN.md +++ b/ts/packages/actionGrammar/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/action-grammar — AI-generated documentation @@ -12,85 +12,130 @@ ## Overview -The `@typeagent/action-grammar` package is a TypeScript library that provides a grammar engine for the TypeAgent framework. It parses, compiles, and matches natural language input against predefined grammar rules to produce structured JSON action objects. This allows user utterances to be converted into typed actions that can be processed by agents. +The `@typeagent/action-grammar` package is a TypeScript library that provides a grammar engine for the TypeAgent framework. It enables parsing, compiling, and matching natural language input against grammar rules defined in `.agr` files. These rules are used to convert user input, such as natural language commands, into structured JSON action objects that can be processed by agents. + +This package is a core component of the TypeAgent ecosystem and is used by several other packages, including `@typeagent/core`, `@typeagent/action-grammar-compiler`, and `agent-cli`. ## What it does -The package supports defining grammar rules in `.agr` files, a custom DSL designed for natural language processing. These rules can include literals, wildcards, alternation, optionals, repetition, rule references, imports, and entity declarations. The main functionalities include: +The primary purpose of this package is to process natural language input and match it against predefined grammar rules to produce structured actions. These actions are represented as JSON objects with a specific structure, such as: + +```json +{ + "actionName": "play", + "parameters": { + "track": "Shape of You", + "artist": "Ed Sheeran" + } +} +``` + +### Key Features + +1. **Grammar Parsing**: + + - The package parses `.agr` files, which are written in a custom domain-specific language (DSL) designed for defining natural language grammar rules. These rules can include constructs like literals, wildcards, alternation, optionals, repetition, rule references, imports, and entity declarations. + - The `parseGrammarRules` function converts `.agr` files into an Abstract Syntax Tree (AST). + +2. **Grammar Compilation**: + + - The parsed grammar rules are compiled into an in-memory `Grammar` representation using the `compileGrammar` function. This representation is optimized for efficient matching. + +3. **Matching**: + + - The package provides two matching backends: + - **Recursive Backtracking Matcher**: Operates directly on the `Grammar` AST and supports complex patterns with wildcards and nested rules. + - **NFA/DFA Pipeline**: Compiles grammar into a token-based Non-deterministic Finite Automaton (NFA) and optionally further into a Deterministic Finite Automaton (DFA) for faster matching. -- **Parsing**: Converting `.agr` files into an Abstract Syntax Tree (AST) using `parseGrammarRules`. -- **Compilation**: Transforming the AST into an in-memory `Grammar` representation with `compileGrammar`. -- **Matching**: Two matching backends are available: - - **Recursive backtracking matcher** (`matchGrammar`): Operates directly on the `Grammar` AST. - - **NFA/DFA pipeline** (`compileGrammarToNFA`, `matchNFA`, `compileNFAToDFA`, `matchDFA`): Compiles grammar to a token-based NFA and optionally further to a DFA for faster matching. +4. **Entity Management**: -The package also includes utilities for grammar serialization, dynamic loading, and entity management. + - The package includes an entity system for defining and managing entities such as dates, times, and numbers. These entities can be used within grammar rules to capture and validate specific types of input. + +5. **Dynamic Grammar Loading**: + + - The package supports dynamic loading and caching of grammar rules at runtime, enabling flexible and efficient updates to the grammar. + +6. **Grammar Generation**: + - The package includes tools for generating grammar rules from schemas and examples using large language models (LLMs) like Claude. ## Setup -To use the `@typeagent/action-grammar` package, ensure you have the following dependencies installed: +To use the `@typeagent/action-grammar` package, ensure the following dependencies are installed in your project: - `@anthropic-ai/claude-agent-sdk` - `debug` - `dotenv` - `regexp.escape` -You can install these dependencies using `pnpm install`. For detailed setup instructions, refer to the hand-written README. +You can install these dependencies using `pnpm install`. If additional setup steps are required, refer to the hand-written README for detailed instructions. ## Key Files -The package is structured into several key components: +The package is organized into several key components, each responsible for specific functionality: + +### Parsing and Compilation -- **Parsing and Compilation**: +- [grammarRuleParser.ts](./src/grammarRuleParser.ts): Implements a recursive descent parser for `.agr` files, converting them into an AST. +- [grammarCompiler.ts](./src/grammarCompiler.ts): Compiles the AST into an in-memory `Grammar` representation. +- [grammarTypes.ts](./src/grammarTypes.ts): Defines types for both in-memory and serialized grammar representations. - - [grammarRuleParser.ts](./src/grammarRuleParser.ts): Parses `.agr` files into AST. - - [grammarCompiler.ts](./src/grammarCompiler.ts): Compiles AST into in-memory `Grammar`. +### Matching -- **Matching**: +- [grammarMatcher.ts](./src/grammarMatcher.ts): Implements the recursive backtracking matcher for grammar rules. +- [nfaCompiler.ts](./src/nfaCompiler.ts): Compiles `Grammar` into a token-based NFA. +- [nfaInterpreter.ts](./src/nfaInterpreter.ts): Executes the NFA with parallel threads and priority-based result selection. +- [dfaCompiler.ts](./src/dfaCompiler.ts): Converts NFA to DFA using subset construction. +- [dfaMatcher.ts](./src/dfaMatcher.ts): Implements DFA-based matching for faster performance. - - [grammarMatcher.ts](./src/grammarMatcher.ts): Implements recursive backtracking matcher. - - [nfaCompiler.ts](./src/nfaCompiler.ts): Compiles `Grammar` to NFA. - - [nfaInterpreter.ts](./src/nfaInterpreter.ts): Executes NFA with parallel threads. - - [dfaCompiler.ts](./src/dfaCompiler.ts): Converts NFA to DFA. - - [dfaMatcher.ts](./src/dfaMatcher.ts): Implements DFA-based matching. +### Entity Management -- **Entity Management**: +- [entityRegistry.ts](./src/entityRegistry.ts): Manages entities, including their validators and converters. +- [builtInEntities.ts](./src/builtInEntities.ts): Provides built-in entity converters for common types like dates, times, and ordinals. - - [entityRegistry.ts](./src/entityRegistry.ts): Manages entities with validators and converters. - - [builtInEntities.ts](./src/builtInEntities.ts): Provides built-in entity converters. +### Dynamic Loading -- **Dynamic Loading**: +- [dynamicGrammarLoader.ts](./src/dynamicGrammarLoader.ts): Handles runtime loading and validation of grammar rules. - - [dynamicGrammarLoader.ts](./src/dynamicGrammarLoader.ts): Handles runtime rule loading and validation. +### Utilities -- **Utilities**: - - [grammarRuleWriter.ts](./src/grammarRuleWriter.ts): Pretty-prints grammar rules. - - [grammarOptimizer.ts](./src/grammarOptimizer.ts): Provides optimization utilities for grammar. +- [grammarRuleWriter.ts](./src/grammarRuleWriter.ts): Provides utilities for pretty-printing grammar rules. +- [grammarOptimizer.ts](./src/grammarOptimizer.ts): Includes optimization utilities for grammar rules. + +### Benchmarks + +- [dfaBenchmark.ts](./src/bench/dfaBenchmark.ts): Benchmarks DFA vs. NFA performance for various grammars. +- [grammarOptimizerBenchmark.ts](./src/bench/grammarOptimizerBenchmark.ts): Measures the impact of grammar optimization passes. +- [grammarOptimizerSyntheticBenchmark.ts](./src/bench/grammarOptimizerSyntheticBenchmark.ts): Tests synthetic grammars designed to stress specific optimizations. ## How to extend -To extend the `@typeagent/action-grammar` package, follow these steps: +To extend the functionality of the `@typeagent/action-grammar` package, follow these steps: -1. **Add new grammar rules**: +1. **Add New Grammar Rules**: - Create or modify `.agr` files with new rules. - - Use `parseGrammarRules` to parse the new rules into AST. + - Use `parseGrammarRules` to parse the new rules into an AST. + - Compile the rules into a `Grammar` object using `compileGrammar`. -2. **Implement custom matchers or optimizers**: +2. **Implement Custom Matchers or Optimizers**: - Extend existing matchers in [grammarMatcher.ts](./src/grammarMatcher.ts) or [dfaMatcher.ts](./src/dfaMatcher.ts). - Add new optimization passes in [grammarOptimizer.ts](./src/grammarOptimizer.ts). -3. **Add new entities**: +3. **Define New Entities**: - - Define new entities in [entityRegistry.ts](./src/entityRegistry.ts). + - Add new entity definitions in [entityRegistry.ts](./src/entityRegistry.ts). - Implement converters and validators for the new entities. -4. **Test your changes**: - - Write unit tests for new functionalities. - - Run benchmarks using scripts in the `bench` directory, such as [dfaBenchmark.ts](./src/bench/dfaBenchmark.ts). +4. **Enhance Dynamic Loading**: + + - Modify [dynamicGrammarLoader.ts](./src/dynamicGrammarLoader.ts) to support additional runtime loading scenarios. + +5. **Test Your Changes**: + - Write unit tests for any new functionality. + - Use the benchmark scripts in the `bench` directory to evaluate performance impacts. -For a starting point, open [grammarRuleParser.ts](./src/grammarRuleParser.ts) to understand the parsing logic, and [grammarMatcher.ts](./src/grammarMatcher.ts) for matching logic. Ensure all changes are thoroughly tested before integration. +For contributors new to the package, a good starting point is [grammarRuleParser.ts](./src/grammarRuleParser.ts) to understand how `.agr` files are parsed, and [grammarMatcher.ts](./src/grammarMatcher.ts) for the matching logic. Be sure to follow the existing patterns and conventions in the codebase. ## Reference @@ -98,10 +143,10 @@ For a starting point, open [grammarRuleParser.ts](./src/grammarRuleParser.ts) to ### Entry points -- default → [./dist/index.js](./dist/index.js) -- `./completion` → [./dist/completion.js](./dist/completion.js) -- `./rules` → [./dist/indexRules.js](./dist/indexRules.js) -- `./generation` → [./dist/generation/index.js](./dist/generation/index.js) +- default → `./dist/index.js` _(not found on disk)_ +- `./completion` → `./dist/completion.js` _(not found on disk)_ +- `./rules` → `./dist/indexRules.js` _(not found on disk)_ +- `./generation` → `./dist/generation/index.js` _(not found on disk)_ ### Dependencies @@ -142,6 +187,6 @@ External: `@anthropic-ai/claude-agent-sdk`, `debug`, `dotenv`, `regexp.escape` --- -_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/action-grammar docs:verify-links` to spot-check._ +_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/action-grammar docs:verify-links` to spot-check._ diff --git a/ts/packages/agentSdk/README.AUTOGEN.md b/ts/packages/agentSdk/README.AUTOGEN.md index 57644cc1b..eb5a37a5f 100644 --- a/ts/packages/agentSdk/README.AUTOGEN.md +++ b/ts/packages/agentSdk/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/agent-sdk — AI-generated documentation @@ -12,63 +12,67 @@ ## Overview -The `@typeagent/agent-sdk` package provides the essential interfaces and utilities for implementing a Dispatcher Agent within the TypeAgent ecosystem. It serves as the foundation for creating agents that can interact with the TypeAgent Dispatcher, handle commands, execute actions, and manage agent contexts. +The `@typeagent/agent-sdk` package provides interfaces and utilities for building Dispatcher Agents within the TypeAgent ecosystem. It serves as the core library for creating agents that can interact with the TypeAgent Dispatcher, handle commands and actions, and manage agent-specific contexts. ## What it does -The `@typeagent/agent-sdk` package offers a comprehensive set of tools for building dispatcher agents. These tools include: +The `@typeagent/agent-sdk` package enables developers to create and manage Dispatcher Agents by providing the following capabilities: -- **Manifest and Instantiation Entry Points**: Defines the agent's manifest and the entry point for instantiation. -- **Lifecycle APIs**: Methods for initializing, updating, and closing the agent context. -- **Command APIs**: Functions for defining and executing commands. -- **Action APIs**: Methods for executing actions and handling partial action streams. -- **Readiness and Setup APIs**: Functions for checking the agent's readiness and performing setup tasks. -- **Display Utilities**: Tools for managing how information is displayed to the user. +- **Manifest and Instantiation**: Define the agent's manifest (`AppAgentManifest`) and specify an instantiation entry point for the agent. The manifest includes metadata such as the agent's emoji, description, and translator configuration. +- **Lifecycle Management**: Implement lifecycle methods like `initializeAgentContext`, `updateAgentContext`, and `closeAgentContext` to manage the agent's runtime state and resources. +- **Command Handling**: Define commands using `CommandDescriptors` and implement methods like `getCommands` and `executeCommand` to handle user commands routed by the Dispatcher. +- **Action Execution**: Implement `executeAction` and `streamPartialAction` to handle actions triggered by the Dispatcher. These methods allow agents to process user requests and provide results or stream partial responses. +- **Readiness and Setup**: Use `checkReadiness` to determine if the agent is ready to operate and `setup` to guide users through any required configuration steps. +- **Display Management**: Leverage utilities for managing how information is displayed to users, including support for dynamic and periodic updates. -Agents built using this SDK can be registered with the TypeAgent Dispatcher and can be integrated into various TypeAgent components such as the Shell and CLI. +This package is used by a wide range of TypeAgent components, including the Shell, CLI, and other agents, making it a critical part of the ecosystem. ## Setup -To set up a dispatcher agent using the `@typeagent/agent-sdk`, you need to provide a manifest and an instantiation entry point for your agent. These are declared in the `package.json` as export paths: +To set up a Dispatcher Agent using the `@typeagent/agent-sdk`, you need to define two key components in your `package.json`: -- `./agent/manifest`: The location of the JSON file for the manifest. -- `./agent/handlers`: An ESM module with an instantiation entry point. +1. **Manifest**: Specify the path to the agent's manifest file under the `./agent/manifest` export path. The manifest is a JSON file that includes metadata about the agent, such as its emoji, description, and translator configuration. Refer to the `AppAgentManifest` type for details on the required structure. -For detailed setup instructions, including how to register a dispatcher agent with the TypeAgent Dispatcher, refer to the hand-written README. +2. **Instantiation Entry Point**: Define the path to the agent's instantiation entry point under the `./agent/handlers` export path. This entry point should export an `instantiate` function that returns an instance of the `AppAgent` interface. + +For additional guidance on registering a Dispatcher Agent with the TypeAgent Dispatcher, consult the hand-written README. ## Key Files -The internal structure of the `@typeagent/agent-sdk` package is organized into several key files: +The `@typeagent/agent-sdk` package is organized into several key files, each responsible for specific functionality: -- **[index.ts](./src/index.ts)**: Exports the main interfaces and types used throughout the SDK. -- **[action.ts](./src/action.ts)**: Defines the structure and types for actions, including `AppAction`, `ActionResult`, and `PendingChoice`. -- **[agentInterface.ts](./src/agentInterface.ts)**: Contains the core interfaces for agents, such as `AppAgent`, `SessionContext`, and `ActionContext`. -- **[command.ts](./src/command.ts)**: Provides the types and interfaces for command handling, including `CommandDescriptor`, `CommandDescriptors`, and `AppAgentCommandInterface`. -- **[display.ts](./src/display.ts)**: Defines the types for managing display content, such as `DisplayType`, `DynamicDisplay`, and `TypedDisplayContent`. -- **Helpers**: Utility functions for handling actions, commands, and display content are located in the `helpers` directory: - - **[actionHelpers.ts](./src/helpers/actionHelpers.ts)** - - **[commandHelpers.ts](./src/helpers/commandHelpers.ts)** - - **[displayHelpers.ts](./src/helpers/displayHelpers.ts)** +- **[index.ts](./src/index.ts)**: The main entry point for the package, exporting core interfaces and types. +- **[action.ts](./src/action.ts)**: Defines the structure and types for actions, including `AppAction`, `ActionResult`, and `PendingChoice`. These are essential for implementing the `executeAction` and `streamPartialAction` methods. +- **[agentInterface.ts](./src/agentInterface.ts)**: Contains the primary interfaces for agents, such as `AppAgent`, `SessionContext`, and `ActionContext`. These interfaces define the contract between the agent and the Dispatcher. +- **[command.ts](./src/command.ts)**: Provides types and interfaces for command handling, including `CommandDescriptor`, `CommandDescriptors`, and `AppAgentCommandInterface`. These are used to define and execute commands. +- **[display.ts](./src/display.ts)**: Defines types for managing display content, such as `DisplayType`, `DynamicDisplay`, and `TypedDisplayContent`. These are used to control how information is presented to users. +- **Helpers**: A set of utility functions for common tasks: + - **[actionHelpers.ts](./src/helpers/actionHelpers.ts)**: Utilities for creating and managing action results. + - **[commandHelpers.ts](./src/helpers/commandHelpers.ts)**: Functions for handling commands and their parameters. + - **[displayHelpers.ts](./src/helpers/displayHelpers.ts)**: Tools for managing display content and formatting. + - **[choiceManager.ts](./src/helpers/choiceManager.ts)**: Manages user choices and callbacks, enabling interactive workflows. ## How to extend -To extend the functionality of a dispatcher agent using the `@typeagent/agent-sdk`, follow these steps: +To extend the functionality of a Dispatcher Agent using the `@typeagent/agent-sdk`, follow these steps: + +1. **Implement the `AppAgent` Interface**: Create a class that implements the `AppAgent` interface. This class will define the agent's behavior, including lifecycle, command, and action handling methods. -1. **Implement the `AppAgent` Interface**: Start by creating a class that implements the `AppAgent` interface. This class will define the agent's behavior and lifecycle methods. +2. **Define the Manifest**: Create a JSON file that adheres to the `AppAgentManifest` type. This file should include metadata about the agent, such as its emoji, description, and translator configuration. -2. **Define Commands and Actions**: Implement the `getCommands` and `executeCommand` methods to define and handle commands. Similarly, implement the `executeAction` and `streamPartialAction` methods to handle actions. +3. **Handle Commands**: Use the `getCommands` method to define the commands your agent supports. Implement the `executeCommand` method to handle these commands when invoked by the Dispatcher. -3. **Manage Agent Context**: Use the `initializeAgentContext`, `updateAgentContext`, and `closeAgentContext` methods to manage the agent's context throughout its lifecycle. +4. **Handle Actions**: Implement the `executeAction` and `streamPartialAction` methods to process actions routed by the Dispatcher. Use the `actionHelpers.ts` utilities to simplify the creation of action results. -4. **Handle Readiness and Setup**: Implement the `checkReadiness` and `setup` methods to manage the agent's readiness state and perform any necessary setup tasks. +5. **Manage Context**: Use the `initializeAgentContext`, `updateAgentContext`, and `closeAgentContext` methods to manage the agent's runtime context. This context can store state information that persists across multiple calls. -5. **Utilize Display Utilities**: Use the display utilities provided in the `displayHelpers.ts` file to manage how information is displayed to the user. +6. **Implement Readiness and Setup**: Define the `checkReadiness` method to report the agent's readiness state. If setup is required, implement the `setup` method to guide users through the configuration process. -6. **Test Your Agent**: Ensure your agent is functioning correctly by writing tests and running them to validate the agent's behavior. +7. **Leverage Display Utilities**: Use the utilities in `displayHelpers.ts` to manage how information is displayed to users. This includes support for dynamic and periodic updates. -For a practical example and initial template for building a dispatcher agent, refer to the [List agent](../agents/list/). For detailed instructions on creating agents as NPM packages, see the [tutorial](../../../docs/content/tutorial/agent.md). +8. **Test Your Agent**: Write and run tests to ensure your agent behaves as expected. Use the provided interfaces and utilities to simplify testing. -By following these steps and utilizing the provided interfaces and utilities, you can extend and customize your dispatcher agent to meet specific requirements within the TypeAgent ecosystem. +For a practical example, refer to the [List agent](../agents/list/), which serves as a template for building Dispatcher Agents. Additional resources and tutorials are available in the TypeAgent documentation. ## Reference @@ -76,11 +80,11 @@ By following these steps and utilizing the provided interfaces and utilities, yo ### Entry points -- default → [./dist/index.js](./dist/index.js) -- `./helpers/action` → [./dist/helpers/actionHelpers.js](./dist/helpers/actionHelpers.js) -- `./helpers/command` → [./dist/helpers/commandHelpers.js](./dist/helpers/commandHelpers.js) -- `./helpers/display` → [./dist/helpers/displayHelpers.js](./dist/helpers/displayHelpers.js) -- `./node` → [./dist/node/cliPath.js](./dist/node/cliPath.js) +- default → `./dist/index.js` _(not found on disk)_ +- `./helpers/action` → `./dist/helpers/actionHelpers.js` _(not found on disk)_ +- `./helpers/command` → `./dist/helpers/commandHelpers.js` _(not found on disk)_ +- `./helpers/display` → `./dist/helpers/displayHelpers.js` _(not found on disk)_ +- `./node` → `./dist/node/cliPath.js` _(not found on disk)_ ### Dependencies @@ -120,6 +124,6 @@ External: `debug`, `type-fest` --- -_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-sdk docs:verify-links` to spot-check._ +_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/agent-sdk docs:verify-links` to spot-check._ diff --git a/ts/packages/cache/README.AUTOGEN.md b/ts/packages/cache/README.AUTOGEN.md index b7d144c90..e20ab5b8a 100644 --- a/ts/packages/cache/README.AUTOGEN.md +++ b/ts/packages/cache/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # agent-cache — AI-generated documentation @@ -12,72 +12,98 @@ ## Overview -The `agent-cache` package is a TypeScript library designed to manage the construction cache for TypeAgent requests. It facilitates the caching of parsed grammar and rules derived from user requests, enabling local translations of user requests without relying on the LLM (Large Language Model). This package is essential for optimizing the performance and efficiency of TypeAgent by reducing the dependency on external LLM services. +The `agent-cache` package is a TypeScript library that provides a construction cache for TypeAgent requests. It enables efficient local processing of user requests by caching parsed grammar and rules derived from these requests. This reduces the dependency on external Large Language Models (LLMs) for request translation, improving performance and reducing latency. ## What it does -The `agent-cache` package provides functionalities to explain how user requests are transformed into actions and to create constructions that can be cached. These constructions are used to perform translations of user requests locally, bypassing the LLM. The package supports multiple explainers, each with its own validator and construction creator, allowing for exploration of changes to the explainer prompt and schema. +The primary purpose of the `agent-cache` package is to optimize the handling of user requests by caching "constructions" — parsed grammar and rules derived from user inputs. These constructions allow the system to process similar requests locally without repeatedly querying an LLM. This is achieved through the following key functionalities: -Key actions supported by the package include: +- **Explanation**: The package can explain how a user request is transformed into an action using the `explainRequest` action. This explanation is used to generate constructions. +- **Caching**: Constructions derived from explanations are cached using the `cacheConstruction` action. This allows for efficient reuse of previously processed requests. +- **Local Translation**: Cached constructions are used to perform local translations of user requests, bypassing the need for LLM interaction. +- **Loading and Managing Cache**: The `loadConstructionCacheFile` action allows loading pre-existing construction cache files, while other utilities manage the storage and retrieval of cached constructions. -- `createMessage`: Creates a message based on user input. -- `explainRequest`: Explains how a user request is transformed into an action. -- `cacheConstruction`: Caches the construction derived from the explanation. -- `loadConstructionCacheFile`: Loads a construction cache file for use. - -These actions enable the creation, explanation, caching, and loading of constructions, respectively. +The package supports multiple explainers, each with its own validator and construction creator. This modularity allows for experimentation with different explainer prompts and schemas to optimize the translation process. ## Setup -To set up the `agent-cache` package, ensure you have the necessary environment variables and dependencies configured. The package relies on several internal and external dependencies, including `async`, `chalk`, `debug`, `regexp.escape`, and `typechat`. +The `agent-cache` package does not require extensive setup beyond installing its dependencies. However, it relies on several internal and external dependencies, including: -For detailed setup instructions, including environment variables and configuration steps, refer to the hand-written README. +- Internal dependencies: `@typeagent/action-grammar`, `@typeagent/action-schema`, `@typeagent/agent-sdk`, `@typeagent/aiclient`, `@typeagent/common-utils`, `telemetry`, `test-lib`, and `typechat-utils`. +- External dependencies: `async`, `chalk`, `debug`, `regexp.escape`, and `typechat`. -## Key Files +Ensure that these dependencies are installed and properly configured in your development environment. For additional setup details, refer to the hand-written README. -The `agent-cache` package is organized into several key components: +## Key Files -- **Cache**: Manages the construction cache, including loading and storing constructions. Key files include [cache.ts](./src/cache/cache.ts), [constructionStore.ts](./src/cache/constructionStore.ts), and [grammarStore.ts](./src/cache/grammarStore.ts). -- **Explanation**: Handles the explanation of user requests and the creation of constructions. Key files include [explainerFactories.ts](./src/explanation/explainerFactories.ts), [genericExplainer.ts](./src/explanation/genericExplainer.ts), and [schemaInfoProvider.ts](./src/explanation/schemaInfoProvider.ts). -- **Constructions**: Defines the structure and management of constructions. Key files include [constructionCache.ts](./src/constructions/constructionCache.ts), [constructionJSONTypes.ts](./src/constructions/constructionJSONTypes.ts), and [matchPart.ts](./src/constructions/matchPart.ts). -- **Grammar**: Converts constructions to grammar and manages grammar matching. Key files include [exportGrammar.ts](./src/grammar/exportGrammar.ts) and [grammarStore.ts](./src/cache/grammarStore.ts). +The `agent-cache` package is organized into several key modules, each responsible for specific aspects of the caching and explanation process. Below is an overview of the key files and their responsibilities: -### Key Files and Their Responsibilities +### Cache Management -- [index.ts](./src/index.ts): Main entry point, exporting types and functionalities. -- [indexBrowser.ts](./src/indexBrowser.ts): Browser-specific entry point, exporting constructions and match parts. -- [indexGrammar.ts](./src/indexGrammar.ts): Grammar-specific entry point, exporting grammar conversion functionalities. - [cache.ts](./src/cache/cache.ts): Manages the construction cache, including loading and storing constructions. - [constructionStore.ts](./src/cache/constructionStore.ts): Handles the storage and retrieval of constructions. - [explainWorkQueue.ts](./src/cache/explainWorkQueue.ts): Manages the work queue for processing explanations. - [factory.ts](./src/cache/factory.ts): Provides factory methods for creating explainers and caches. - [grammarStore.ts](./src/cache/grammarStore.ts): Manages grammar storage and matching. +- [sortMatches.ts](./src/cache/sortMatches.ts): Implements sorting logic for matching results. +- [types.ts](./src/cache/types.ts): Defines types and interfaces for cache and grammar management. + +### Explanation + +- [explainerFactories.ts](./src/explanation/explainerFactories.ts): Maintains a registry of supported explainers and their configurations. +- [genericExplainer.ts](./src/explanation/genericExplainer.ts): Provides a generic implementation for explainers. +- [schemaInfoProvider.ts](./src/explanation/schemaInfoProvider.ts): Supplies schema-related information for explanations. + +### Constructions + +- [constructionCache.ts](./src/constructions/constructionCache.ts): Defines the structure and management of constructions. +- [constructionJSONTypes.ts](./src/constructions/constructionJSONTypes.ts): Specifies JSON types for serializing and deserializing constructions. +- [matchPart.ts](./src/constructions/matchPart.ts): Handles matching logic for construction parts. + +### Grammar + +- [exportGrammar.ts](./src/grammar/exportGrammar.ts): Converts constructions to grammar for local processing. +- [grammarStore.ts](./src/cache/grammarStore.ts): Manages grammar storage and matching. + +### Entry Points + +- [index.ts](./src/index.ts): Main entry point, exporting core types and functionalities. +- [indexBrowser.ts](./src/indexBrowser.ts): Browser-specific entry point, exporting constructions and match parts. +- [indexGrammar.ts](./src/indexGrammar.ts): Grammar-specific entry point, exporting grammar conversion functionalities. ## How to extend -To extend the `agent-cache` package, follow these steps: +The `agent-cache` package is designed to be extensible, allowing contributors to add new explainers, modify existing components, or enhance its functionality. Below are some guidelines for extending the package: + +### Adding a New Explainer + +1. **Clone an Existing Explainer**: + + - Navigate to the [./src/explanation](./src/explanation) directory. + - Copy the code and schema files of an existing explainer (e.g., `explanationV4.ts`, `explanationSchemaV4.ts`, and `actionExplanationSchemaV4.ts`) and rename them with a new version suffix (e.g., `V5`). + - Update all references to the old version (e.g., `V4`) in the new files to the new version (e.g., `V5`). + +2. **Register the New Explainer**: -### Adding a new explainer + - Add an entry for the new explainer in [explainerFactories.ts](./src/explanation/explainerFactories.ts). + - Use the new explainer's name as the key and its factory function as the value. -1. Locate the list of supported explainers in [explainerFactories.ts](./src/explanation/explainerFactories.ts). -2. Create a new explainer by cloning an existing one. For example, to create `v5` from `v4`: - - Copy the code and schemas from `explanationV4.ts`, `explanationSchemaV4.ts`, and `actionExplanationSchemaV4.ts` to new files with `V5` suffix. - - Rename all `V4` suffixes in the new files to `V5`. - - Add the new explainer to `explainerFactories.ts` by adding a new entry in the `explainerFactories` array. - - Use `@config explainer v5` in the CLI or shell to start using the new explainer. +3. **Activate the New Explainer**: + - Use the CLI or shell command `@config explainer v5` to start using the new explainer. -### Modifying existing components +### Modifying Existing Components -- To modify the cache management, start with [cache.ts](./src/cache/cache.ts) and [constructionStore.ts](./src/cache/constructionStore.ts). -- To update the explanation logic, refer to [genericExplainer.ts](./src/explanation/genericExplainer.ts) and [schemaInfoProvider.ts](./src/explanation/schemaInfoProvider.ts). -- For changes to constructions, look into [constructionCache.ts](./src/constructions/constructionCache.ts) and [matchPart.ts](./src/constructions/matchPart.ts). -- To adjust grammar handling, review [exportGrammar.ts](./src/grammar/exportGrammar.ts) and [grammarStore.ts](./src/cache/grammarStore.ts). +- **Cache Management**: To modify how constructions are cached, start with [cache.ts](./src/cache/cache.ts) and [constructionStore.ts](./src/cache/constructionStore.ts). +- **Explanation Logic**: To update how user requests are explained, refer to [genericExplainer.ts](./src/explanation/genericExplainer.ts) and [schemaInfoProvider.ts](./src/explanation/schemaInfoProvider.ts). +- **Constructions**: For changes to the structure or handling of constructions, look into [constructionCache.ts](./src/constructions/constructionCache.ts) and [matchPart.ts](./src/constructions/matchPart.ts). +- **Grammar Handling**: To adjust grammar-related functionalities, review [exportGrammar.ts](./src/grammar/exportGrammar.ts) and [grammarStore.ts](./src/cache/grammarStore.ts). ### Testing -Ensure that any new or modified components are thoroughly tested. The package relies on the `test-lib` dependency for testing utilities. Run tests to verify the functionality and integration of your changes. +- Use the `test-lib` dependency to write and run tests for any new or modified components. +- Ensure that all changes are thoroughly tested to maintain the package's reliability and functionality. -By following these steps, you can effectively extend and customize the `agent-cache` package to meet your specific requirements. For more detailed instructions and examples, refer to the hand-written README. +By following these guidelines, you can effectively extend and customize the `agent-cache` package to meet specific requirements. For additional details, refer to the hand-written README. ## Reference @@ -85,9 +111,9 @@ By following these steps, you can effectively extend and customize the `agent-ca ### Entry points -- default → [./dist/index.js](./dist/index.js) -- default → [./dist/indexBrowser.js](./dist/indexBrowser.js) -- `./grammar` → [./dist/indexGrammar.js](./dist/indexGrammar.js) +- default → `./dist/index.js` _(not found on disk)_ +- default → `./dist/indexBrowser.js` _(not found on disk)_ +- `./grammar` → `./dist/indexGrammar.js` _(not found on disk)_ ### Dependencies @@ -115,7 +141,7 @@ External: `async`, `chalk`, `debug`, `regexp.escape`, `typechat` - [cache-rest-endpoint](../../examples/cacheRESTEndpoint/README.md) - [default-agent-provider](../../packages/defaultAgentProvider/README.md) - [desktop-automation](../../packages/agents/desktop/README.md) -- [schema-studio](../../examples/schemaStudio/README.md) +- schema-studio ### Files of interest @@ -133,6 +159,6 @@ External: `async`, `chalk`, `debug`, `regexp.escape`, `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 agent-cache docs:verify-links` to spot-check._ +_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 agent-cache docs:verify-links` to spot-check._ diff --git a/ts/packages/config/README.AUTOGEN.md b/ts/packages/config/README.AUTOGEN.md index baa490bd1..03fba7cad 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,69 +12,83 @@ ## Overview -The `@typeagent/config` package is a layered YAML configuration loader for TypeAgent. It provides a mechanism to load configuration settings from various sources, including default YAML files, local overrides, environment variables, and Azure Key Vault. This package ensures that configuration settings are merged in a specific order of precedence and supports schema validation using `zod`. +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. ## What it does -The `@typeagent/config` package offers several key features: +The `@typeagent/config` package provides the following functionality: -1. **Layered Configuration Loading**: It reads configuration settings from multiple sources, including `ts/config.defaults.yaml`, `ts/config.local.yaml`, environment variables, and optionally Azure Key Vault. The settings are merged in a specific order of precedence to ensure the correct values are used. +1. **Layered Configuration Loading**: The package supports loading configuration from multiple sources, including: -2. **Flattening Configuration**: The package flattens nested YAML configuration trees into flat key-value pairs that match the existing `EnvVars` convention used by other TypeAgent packages. This allows existing code that relies on `process.env` to continue working without changes. + - `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. -3. **Schema Validation**: Lightweight schema validation is performed using `zod` to ensure the configuration settings are valid. +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`. -4. **CLI Support**: The package includes a CLI for importing `.env` files into YAML format and for displaying the merged configuration. +3. **Schema Validation**: The package uses `zod` to validate configuration settings, ensuring they conform to expected schemas. -5. **Azure Key Vault Integration**: Future phases will include support for fetching configuration settings from Azure Key Vault and caching them locally in an encrypted format. +4. **CLI Commands**: A CLI is included for tasks such as importing `.env` files into YAML format and displaying the merged configuration. + +5. **Merge Precedence**: Configuration values are merged in the following order (lowest to highest precedence): + + - `.env` (legacy fallback) + - `ts/config.defaults.yaml` + - _Future_: Key Vault YAML blob or encrypted cache + - `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. ## Setup -To use the `@typeagent/config` package, you need to set up the following environment variables: +To use the `@typeagent/config` package, ensure the following environment variables are set: -- `AZURE_OPENAI_`: This variable is used to configure Azure OpenAI settings. -- `JEST_WORKER_ID`: This variable is used for Jest testing. -- `TYPEAGENT_ALLOW_KEYVAULT_IN_TESTS`: This variable allows Key Vault integration during tests. -- `TYPEAGENT_CONFIG_DEFAULTS`: This variable specifies the path to the default configuration YAML file. -- `TYPEAGENT_CONFIG_DIR`: This variable specifies the directory where configuration files are located. -- `TYPEAGENT_CONFIG_LOCAL`: This variable specifies the path to the local configuration YAML file. -- `TYPEAGENT_CONFIG_SECRET`: This variable specifies the secret name for the configuration in Azure Key Vault. -- `TYPEAGENT_CONFIG_VAULT`: This variable specifies the Azure Key Vault name. -- `TYPEAGENT_DOTENV`: This variable specifies the path to the `.env` file. -- `TYPEAGENT_USER_DATA_DIR`: This variable specifies the directory for user data. +- `AZURE_OPENAI_`: Used for Azure OpenAI configuration. +- `JEST_WORKER_ID`: Used 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. -Refer to the hand-written README for detailed instructions on obtaining these values. +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 several key files: +The package's source code is organized into the following key files: -- [index.ts](./src/index.ts): Exports the main functions and types used by the package, including `loadConfig`, `flatten`, and `fetchKeyVaultConfig`. -- [cli.ts](./src/cli.ts): Implements the CLI commands for importing `.env` files and displaying the merged configuration. -- [flatten.ts](./src/flatten.ts): Contains the logic for flattening nested YAML configuration trees into flat key-value pairs. -- [import.ts](./src/import.ts): Handles the import of `.env` files and their conversion to YAML format. +- [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. +- [flatten.ts](./src/flatten.ts): Handles the flattening of nested YAML configuration trees into flat key-value pairs. - [keyVault.ts](./src/keyVault.ts): Provides functions for fetching configuration settings from Azure Key Vault. -- [loader.ts](./src/loader.ts): Implements the main configuration loading logic, including merging settings from various sources. -- [redact.ts](./src/redact.ts): Contains functions for redacting sensitive values in the configuration. -- [runtime/build.ts](./src/runtime/build.ts): Builds a typed `Config` from a flat env-var map. +- [cli.ts](./src/cli.ts): Implements CLI commands for importing `.env` files and displaying the merged configuration. +- [import.ts](./src/import.ts): Manages the conversion of `.env` files into YAML format and ensures compatibility with the existing configuration structure. +- [redact.ts](./src/redact.ts): Contains logic for identifying and redacting sensitive values in configuration data. +- [runtime/build.ts](./src/runtime/build.ts): Builds a typed `Config` object from a flat environment variable map. ## How to extend -To extend the `@typeagent/config` package, follow these steps: +To extend the functionality of the `@typeagent/config` package, consider the following approaches: -1. **Add New Configuration Sources**: If you need to add new sources for configuration settings, modify the [loader.ts](./src/loader.ts) file to include the new source and update the merge logic accordingly. +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. -2. **Update Flattening Rules**: If you need to change how configuration settings are flattened, update the [flatten.ts](./src/flatten.ts) file. Ensure that the new rules are consistent with the existing `EnvVars` convention. +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. -3. **Enhance Schema Validation**: To add new validation rules or update existing ones, modify the [schema.ts](./src/schema.ts) file. Use `zod` to define the new schema and validation logic. +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. **Extend CLI Commands**: If you need to add new CLI commands, update the [cli.ts](./src/cli.ts) file. Implement the new commands and ensure they integrate with the existing configuration loading and merging 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. -5. **Integrate with Azure Key Vault**: To enhance the Azure Key Vault integration, update the [keyVault.ts](./src/keyVault.ts) file. Add new functions for fetching and caching configuration settings from Key Vault. +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. -6. **Redact Sensitive Values**: If you need to update the redaction logic for sensitive values, modify the [redact.ts](./src/redact.ts) file. Ensure that the new logic correctly identifies and redacts sensitive values. +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. -By following these steps, you can extend the functionality of the `@typeagent/config` package to meet your specific requirements. +When extending the package, ensure that new functionality adheres to the existing patterns and conventions to maintain consistency and compatibility across the TypeAgent ecosystem. ## Reference @@ -126,6 +140,6 @@ _10 environment variables referenced from `./src/` (set in `ts/.env` or your she --- -_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/config docs:verify-links` to spot-check._ +_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._ diff --git a/ts/packages/dispatcher/rpc/README.AUTOGEN.md b/ts/packages/dispatcher/rpc/README.AUTOGEN.md index 98a6463e3..98dda0462 100644 --- a/ts/packages/dispatcher/rpc/README.AUTOGEN.md +++ b/ts/packages/dispatcher/rpc/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/dispatcher-rpc — AI-generated documentation @@ -12,55 +12,81 @@ ## Overview -The `@typeagent/dispatcher-rpc` package provides Remote Procedure Call (RPC) functionality for the TypeAgent dispatcher. It facilitates communication between different components of the TypeAgent system, enabling them to invoke methods and exchange data over RPC channels. +The `@typeagent/dispatcher-rpc` package provides Remote Procedure Call (RPC) functionality for the TypeAgent dispatcher. It enables communication between different components of the TypeAgent system, allowing them to invoke methods and exchange data over RPC channels. ## What it does -This package offers RPC clients and servers for two main components: `ClientIO` and `Dispatcher`. It allows these components to communicate with each other and perform various actions. The package includes functions for handling user requests, managing display information, processing commands, and more. +This package implements RPC clients and servers for two primary components: `ClientIO` and `Dispatcher`. These components facilitate communication and coordination within the TypeAgent system. ### ClientIO -The `ClientIO` component handles user interactions and display management. It includes actions such as `clear`, `exit`, `shutdown`, `setUserRequest`, `setDisplayInfo`, `setDisplay`, `appendDisplay`, `appendDiagnosticData`, and `setDynamicDisplay`. These actions enable the client to manage the display and respond to user inputs. +The `ClientIO` component is responsible for managing user interactions and display updates. It supports actions such as: + +- `clear`, `exit`, and `shutdown` for managing session state. +- `setUserRequest` for handling user input. +- `setDisplayInfo`, `setDisplay`, and `appendDisplay` for updating display content. +- `appendDiagnosticData` and `setDynamicDisplay` for managing diagnostic and dynamic display data. + +These actions allow the `ClientIO` component to handle user-facing operations and maintain the display state. ### Dispatcher -The `Dispatcher` component processes commands and manages dynamic displays. It includes actions such as `submitCommand`, `getDynamicDisplay`, `getTemplateSchema`, `getTemplateCompletion`, `getCommandCompletion`, `checkCache`, `close`, and `getStatus`. These actions allow the dispatcher to handle commands, retrieve display information, and manage templates. +The `Dispatcher` component focuses on processing commands and managing dynamic displays. It includes actions such as: + +- `submitCommand` for submitting commands to the dispatcher. +- `getDynamicDisplay`, `getTemplateSchema`, and `getTemplateCompletion` for retrieving display and template-related data. +- `getCommandCompletion` and `checkCache` for managing command execution and caching. +- `close` and `getStatus` for managing the dispatcher lifecycle and retrieving its status. + +The `Dispatcher` component is central to coordinating command execution and managing templates within the system. ## Setup -To set up the `@typeagent/dispatcher-rpc` package, ensure you have the necessary dependencies installed. The package relies on `@typeagent/agent-rpc`, `@typeagent/agent-sdk`, and `@typeagent/dispatcher-types`. You can install these dependencies using `pnpm install`. +To use the `@typeagent/dispatcher-rpc` package, ensure the following dependencies are installed: -No additional environment variables or external accounts are required for this package. For detailed setup instructions, see the hand-written README. +- `@typeagent/agent-rpc` +- `@typeagent/agent-sdk` +- `@typeagent/dispatcher-types` + +You can install these dependencies using `pnpm install`. No additional environment variables or external accounts are required. For more details, refer to the hand-written README. ## Key Files -The package is organized into several key files: +The package is organized into several key files, each serving a specific purpose: -- [clientIOClient.ts](./src/clientIOClient.ts): Defines the RPC client for `ClientIO`. -- [clientIOServer.ts](./src/clientIOServer.ts): Defines the RPC server for `ClientIO`. -- [dispatcherClient.ts](./src/dispatcherClient.ts): Defines the RPC client for `Dispatcher`. -- [dispatcherServer.ts](./src/dispatcherServer.ts): Defines the RPC server for `Dispatcher`. -- [clientIOTypes.ts](./src/clientIOTypes.ts): Contains type definitions for `ClientIO` RPC functions. -- [dispatcherTypes.ts](./src/dispatcherTypes.ts): Contains type definitions for `Dispatcher` RPC functions. -- [types.ts](./src/types.ts): Re-exports types from `@typeagent/dispatcher-types` and `@typeagent/agent-sdk`. +- [clientIOClient.ts](./src/clientIOClient.ts): Implements the RPC client for the `ClientIO` component, enabling it to send requests and receive responses. +- [clientIOServer.ts](./src/clientIOServer.ts): Implements the RPC server for the `ClientIO` component, handling incoming requests and invoking the appropriate actions. +- [dispatcherClient.ts](./src/dispatcherClient.ts): Implements the RPC client for the `Dispatcher` component, providing methods to interact with the dispatcher remotely. +- [dispatcherServer.ts](./src/dispatcherServer.ts): Implements the RPC server for the `Dispatcher` component, processing incoming commands and managing dispatcher state. +- [clientIOTypes.ts](./src/clientIOTypes.ts): Defines type information for `ClientIO` RPC functions, including both callable and invokable actions. +- [dispatcherTypes.ts](./src/dispatcherTypes.ts): Defines type information for `Dispatcher` RPC functions, including wire-side variants of certain types. +- [types.ts](./src/types.ts): Re-exports types from `@typeagent/dispatcher-types` and `@typeagent/agent-sdk` for convenience. -The package uses the `createRpc` function from `@typeagent/agent-rpc` to create RPC clients and servers. The clients and servers are responsible for sending and receiving RPC calls, invoking functions, and handling responses. +The package uses the `createRpc` function from `@typeagent/agent-rpc` to establish RPC communication between clients and servers. This function is central to the implementation of the RPC layer. ## How to extend -To extend the `@typeagent/dispatcher-rpc` package, follow these steps: +To extend the functionality of the `@typeagent/dispatcher-rpc` package, follow these steps: + +1. **Determine the target component**: Decide whether you need to extend the `ClientIO` or `Dispatcher` component based on your requirements. + +2. **Define new actions**: Add the new actions to the appropriate type definition file: + + - Use [clientIOTypes.ts](./src/clientIOTypes.ts) for `ClientIO` actions. + - Use [dispatcherTypes.ts](./src/dispatcherTypes.ts) for `Dispatcher` actions. -1. **Identify the component to extend**: Determine whether you need to extend `ClientIO` or `Dispatcher`. +3. **Implement the actions**: Add the implementation for the new actions in the corresponding client and server files: -2. **Add new actions**: Define new actions in the appropriate type definition file (`clientIOTypes.ts` or `dispatcherTypes.ts`). Ensure the actions are correctly typed. + - For `ClientIO`, modify [clientIOClient.ts](./src/clientIOClient.ts) and [clientIOServer.ts](./src/clientIOServer.ts). + - For `Dispatcher`, modify [dispatcherClient.ts](./src/dispatcherClient.ts) and [dispatcherServer.ts](./src/dispatcherServer.ts). -3. **Implement the actions**: Implement the new actions in the corresponding client and server files (`clientIOClient.ts`, `clientIOServer.ts`, `dispatcherClient.ts`, `dispatcherServer.ts`). Use the `createRpc` function to handle RPC communication. +4. **Update the RPC layer**: Use the `createRpc` function from `@typeagent/agent-rpc` to handle the new actions in the RPC communication layer. -4. **Test the changes**: Write tests to verify the new actions work as expected. Ensure the tests cover both client and server functionality. +5. **Write tests**: Create unit tests to verify the functionality of the new actions. Ensure that both client and server behaviors are tested. -5. **Run the tests**: Execute the tests to validate your changes. Ensure all tests pass before committing your code. +6. **Run tests**: Execute the test suite to confirm that your changes work as expected and do not introduce regressions. -By following these steps, you can extend the functionality of the `@typeagent/dispatcher-rpc` package to meet your specific requirements. +By following these steps, you can extend the `@typeagent/dispatcher-rpc` package to support additional functionality or integrate new features into the TypeAgent system. ## Reference @@ -68,11 +94,11 @@ By following these steps, you can extend the functionality of the `@typeagent/di ### Entry points -- `./types` → [./dist/types.js](./dist/types.js) -- `./clientio/client` → [./dist/clientIOClient.js](./dist/clientIOClient.js) -- `./clientio/server` → [./dist/clientIOServer.js](./dist/clientIOServer.js) -- `./dispatcher/client` → [./dist/dispatcherClient.js](./dist/dispatcherClient.js) -- `./dispatcher/server` → [./dist/dispatcherServer.js](./dist/dispatcherServer.js) +- `./types` → `./dist/types.js` _(not found on disk)_ +- `./clientio/client` → `./dist/clientIOClient.js` _(not found on disk)_ +- `./clientio/server` → `./dist/clientIOServer.js` _(not found on disk)_ +- `./dispatcher/client` → `./dist/dispatcherClient.js` _(not found on disk)_ +- `./dispatcher/server` → `./dist/dispatcherServer.js` _(not found on disk)_ ### Dependencies @@ -108,6 +134,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/dispatcher-rpc docs:verify-links` to spot-check._ +_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/dispatcher-rpc docs:verify-links` to spot-check._ diff --git a/ts/packages/dispatcher/types/README.AUTOGEN.md b/ts/packages/dispatcher/types/README.AUTOGEN.md index 97b373578..3fac30aa0 100644 --- a/ts/packages/dispatcher/types/README.AUTOGEN.md +++ b/ts/packages/dispatcher/types/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/dispatcher-types — AI-generated documentation @@ -12,48 +12,59 @@ ## Overview -The `@typeagent/dispatcher-types` package defines TypeScript types used by the TypeAgent dispatcher. These types are essential for ensuring consistent communication and data handling across various components of the TypeAgent system. By providing a standardized set of types, this package facilitates reliable interactions between different parts of the system, such as agents, clients, and dispatchers. +The `@typeagent/dispatcher-types` package provides a centralized collection of TypeScript type definitions for the TypeAgent dispatcher. These types are critical for ensuring consistent and type-safe communication between various components of the TypeAgent ecosystem, such as agents, clients, and dispatchers. By standardizing the data structures and interfaces, this package helps maintain compatibility and reliability across the system. ## What it does -This package provides a collection of TypeScript types that are used by the dispatcher to manage interactions, messages, and statuses. The types defined here are utilized by other packages within the TypeAgent monorepo, such as `@typeagent/agent-server-protocol`, `@typeagent/copilot-plugin`, and `agent-dispatcher`. Key functionalities include: +The primary purpose of this package is to define and export TypeScript types that are used throughout the TypeAgent dispatcher and its related components. These types are consumed by multiple packages in the TypeAgent monorepo, including `@typeagent/agent-server-protocol`, `@typeagent/copilot-plugin`, and `agent-dispatcher`. The key functionalities provided by this package include: -- **Defining the structure of dispatcher requests and responses**: Types such as `RequestId`, `PendingInteractionRequest`, and `PendingInteractionResponse` are used to manage the flow of requests and responses between clients and the dispatcher. -- **Managing client interactions and messages**: Types like `IAgentMessage`, `TemplateEditConfig`, and `NotifyExplainedData` help in handling client input/output operations and message formatting. -- **Handling dispatcher statuses and summaries**: Types and helper functions in [src/helpers/status.ts](./src/helpers/status.ts) provide mechanisms to summarize and manage dispatcher statuses. +- **Dispatcher Requests and Responses**: Types such as `RequestId`, `PendingInteractionRequest`, and `PendingInteractionResponse` define the structure of requests and responses handled by the dispatcher. +- **Client Input/Output Operations**: Types like `IAgentMessage`, `TemplateEditConfig`, and `NotifyExplainedData` are used to manage client interactions, including message formatting and data exchange. +- **Dispatcher Status Management**: The package includes types and helper functions (e.g., `getStatusSummary` in [status.ts](./src/helpers/status.ts)) to represent and summarize the state of the dispatcher. +- **Queue Management**: Types such as `QueuedRequest`, `QueueCancelReason`, and `QueueRequestState` define the structure and lifecycle of server-side message queues. +- **Logging and Display**: Types like `SetDisplayEntry` and `AppendDisplayEntry` in [displayLogEntry.ts](./src/displayLogEntry.ts) are used for managing and formatting log entries for display purposes. + +These types are foundational for the operation of the TypeAgent dispatcher and its integration with other components in the system. ## Setup -No additional setup is required beyond installing the package. Simply run `pnpm install` to include this package in your workspace. For detailed setup instructions, see the hand-written README. +This package does not require any special setup beyond installation. To include it in your project, simply run: + +```bash +pnpm install +``` + +For additional details, refer to the hand-written README. ## Key Files -The package is structured into several key files, each responsible for different aspects of the dispatcher types: +The `@typeagent/dispatcher-types` package is organized into several key files, each focusing on a specific aspect of the dispatcher: -- [src/index.ts](./src/index.ts): The main entry point that exports types from other modules. -- [src/clientIO.ts](./src/clientIO.ts): Defines types related to client input/output operations, such as `IAgentMessage` and `TemplateEditConfig`. -- [src/dispatcher.ts](./src/dispatcher.ts): Contains core dispatcher types like `RequestId` and constants such as `DispatcherName` and `DispatcherEmoji`. -- [src/displayLogEntry.ts](./src/displayLogEntry.ts): Defines types for logging display entries, including `SetDisplayEntry` and `AppendDisplayEntry`. -- [src/pendingInteraction.ts](./src/pendingInteraction.ts): Manages types for pending interactions, such as `PendingInteractionRequest` and `PendingInteractionResponse`. -- [src/helpers/status.ts](./src/helpers/status.ts): Provides helper functions for summarizing dispatcher statuses. -- [src/queue.ts](./src/queue.ts): Defines types related to the server-side message queue, such as `QueuedRequest` and `QueueCancelReason`. +- [src/index.ts](./src/index.ts): The main entry point for the package, exporting all the types and utilities defined in other modules. +- [src/clientIO.ts](./src/clientIO.ts): Contains types related to client input/output operations, such as `IAgentMessage`, `TemplateEditConfig`, and `NotifyExplainedData`. +- [src/dispatcher.ts](./src/dispatcher.ts): Defines core dispatcher types, including `RequestId`, `DispatcherName`, and `DispatcherEmoji`. +- [src/displayLogEntry.ts](./src/displayLogEntry.ts): Provides types for logging and displaying information, such as `SetDisplayEntry` and `AppendDisplayEntry`. +- [src/pendingInteraction.ts](./src/pendingInteraction.ts): Manages types for pending interactions, including `PendingInteractionRequest` and `PendingInteractionResponse`. +- [src/helpers/status.ts](./src/helpers/status.ts): Implements helper functions for summarizing dispatcher statuses, such as `getStatusSummary`. +- [src/queue.ts](./src/queue.ts): Defines types for the server-side message queue, including `QueuedRequest`, `QueueCancelReason`, and `QueueRequestState`. - [src/queueStateMirror.ts](./src/queueStateMirror.ts): Implements the client-side mirror of the server's per-conversation queue. +- [src/awaitCommand.ts](./src/awaitCommand.ts): Provides a utility function `awaitCommand` for submitting commands to the dispatcher and awaiting their completion. ## How to extend To extend the `@typeagent/dispatcher-types` package, follow these steps: -1. **Identify the type to extend**: Determine which type or module needs modification or extension. For example, if you need to add a new type related to client interactions, you would start with [clientIO.ts](./src/clientIO.ts). +1. **Identify the type to extend**: Determine which type or module you need to modify or extend. For example, if you need to add a new type for client interactions, start with [clientIO.ts](./src/clientIO.ts). -2. **Modify or add new types**: Open the relevant file and add your new type definitions or modify existing ones. Ensure that your changes are consistent with the existing structure and naming conventions. +2. **Modify or add new types**: Open the relevant file and add your new type definitions or modify existing ones. Ensure that your changes align with the existing structure and naming conventions. -3. **Export new types**: If you add new types, make sure they are exported in [index.ts](./src/index.ts) to be accessible from other packages. +3. **Export new types**: If you add new types, ensure they are exported in [index.ts](./src/index.ts) so they can be accessed by other packages. -4. **Test your changes**: Write tests to validate your new types and ensure they integrate correctly with the rest of the system. You can add tests in a new file or an existing test suite. +4. **Write tests**: Create or update test cases to validate your changes. This ensures that your modifications work as intended and do not introduce regressions. -5. **Run the tests**: Execute the test suite to verify that your changes do not break existing functionality. Use the command `pnpm test` to run the tests. +5. **Run tests**: Use the command `pnpm test` to execute the test suite and verify the correctness of your changes. -By following these steps, you can effectively extend the functionality of the `@typeagent/dispatcher-types` package and contribute to the TypeAgent monorepo. +By following these steps, you can effectively contribute to the `@typeagent/dispatcher-types` package and ensure its continued utility and reliability within the TypeAgent monorepo. ## Reference @@ -61,8 +72,8 @@ By following these steps, you can effectively extend the functionality of the `@ ### Entry points -- default → [./dist/index.js](./dist/index.js) -- `./helpers/status` → [./dist/helpers/status.js](./dist/helpers/status.js) +- default → `./dist/index.js` _(not found on disk)_ +- `./helpers/status` → `./dist/helpers/status.js` _(not found on disk)_ ### Dependencies @@ -92,6 +103,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/dispatcher-types docs:verify-links` to spot-check._ +_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/dispatcher-types docs:verify-links` to spot-check._ diff --git a/ts/packages/shell/README.AUTOGEN.md b/ts/packages/shell/README.AUTOGEN.md index dff77afab..ffaa861f6 100644 --- a/ts/packages/shell/README.AUTOGEN.md +++ b/ts/packages/shell/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # agent-shell — AI-generated documentation @@ -12,51 +12,68 @@ ## Overview -The `agent-shell` package is a TypeScript library that serves as the UI entry point for the TypeAgent sample code. It explores architectures for building interactive agents with natural language interfaces using structured prompting and large language models (LLMs). The shell acts as a personal agent that processes user requests, performs actions, answers questions, and engages in conversations using an extensible set of agents. +The `agent-shell` package is a TypeScript library that serves as the UI entry point for the TypeAgent sample code. It demonstrates architectures for building interactive agents with natural language interfaces using structured prompting and large language models (LLMs). The shell functions as a personal agent, capable of processing user requests, performing actions, answering questions, and engaging in conversations through an extensible set of agents. ## What it does -The `agent-shell` package provides a graphical interface for interacting with TypeAgent. It supports various actions such as managing conversations, processing speech input, and handling commands. Key functionalities include: +The `agent-shell` package provides a graphical interface for interacting with TypeAgent. Its key features include: -- **Conversation Management**: Create, switch, rename, and delete conversations using commands like `conversation list`, `conversation new [name]`, `conversation switch `, `conversation rename `, and `conversation delete `. -- **Speech Processing**: Utilize Azure Speech Services or Local Whisper Service for voice input. -- **Command Handling**: Execute various commands through the shell interface. -- **Multi-client Notifications**: Display status messages when multiple clients are connected to the same conversation. +- **Conversation Management**: Users can create, switch, rename, and delete conversations. Commands such as `conversation list`, `conversation new [name]`, `conversation switch `, `conversation rename `, and `conversation delete ` allow for flexible conversation handling. Conversations persist across sessions, and the shell supports multi-conversation management when connected to an agent server. +- **Speech Input**: The shell supports voice input through Azure Speech Services or a Local Whisper Service, enabling users to interact with the system using speech in addition to text input. +- **Command Execution**: The shell processes various commands, including natural language inputs, to perform tasks or retrieve information. +- **Multi-client Notifications**: When multiple clients are connected to the same conversation, the shell displays status messages to inform users of client activity. +- **Local Mode**: In the absence of an agent server, the shell operates in local mode, hosting a WebSocket for in-process port discovery and enabling external clients to connect to in-process agents. + +The shell integrates with other components of the TypeAgent ecosystem, such as the dispatcher and agent server, to provide a cohesive and interactive user experience. ## Setup -To set up the `agent-shell` package, you need to configure several environment variables and follow specific instructions for building and running the shell. The required environment variables are: +To set up the `agent-shell` package, follow these steps: + +1. **Install Dependencies**: Ensure you have all required dependencies installed. The shell is built using Electron, so you may need to install additional libraries for your operating system. For Linux/WSL users, refer to the build instructions provided in the Electron documentation (`https://www.electronjs.org/docs/latest/development/build-instructions-linux`). + +2. **Configure Environment Variables**: Set the following environment variables in your `.env` file or system environment: + + - `ELECTRON_RENDERER_URL`: The URL for the Electron renderer. + - `SPEECH_SDK_ENDPOINT`: The service URL or speech API resource ID for Azure Speech Services. + - `SPEECH_SDK_KEY`: The API key for Azure Speech Services. + - `SPEECH_SDK_REGION`: The region of the Azure Speech Services (e.g., `westus2`). + - `WEBSOCKET_HOST`: The host for WebSocket connections. + +3. **Run the Shell**: Use the following command to start the shell: -- `ELECTRON_RENDERER_URL`: URL for the Electron renderer. -- `SPEECH_SDK_ENDPOINT`: Service URL or speech API resource ID for Azure Speech Services. -- `SPEECH_SDK_KEY`: API key for Azure Speech Services. -- `SPEECH_SDK_REGION`: Region of the Azure Speech Services (e.g., `westus2`). -- `WEBSOCKET_HOST`: Host for WebSocket connections. + ```shell + pnpm run shell + ``` -Additionally, you need to install the necessary libraries for building and using Electron in a Linux/WSL environment. Follow the instructions provided in the Electron documentation (`https://www.electronjs.org/docs/latest/development/build-instructions-linux`) to complete this setup. +4. **Optional Configuration for Azure Speech Services**: To enable voice input via Azure Speech Services, additional setup is required: + - Set `SPEECH_SDK_KEY` to `identity` in your `.env` file or `config.local.yaml` for keyless API access. + - Replace the `SPEECH_SDK_ENDPOINT` value with the Azure resource ID of your cognitive service instance (e.g., `/subscriptions//resourceGroups/myResourceGroup/providers/Microsoft.CognitiveServices/accounts/speechapi`). + - Configure your Azure Speech API to support identity-based authentication. -For detailed setup steps, including keyless API access for Azure Speech Services, refer to the hand-written README. +For more details on setup, including troubleshooting tips for Windows users, refer to the hand-written README. ## Key Files The `agent-shell` package is organized into several key components: -- **Main Entry Point**: The main entry point is located at [./src/main/index.ts](./src/main/index.ts), which initializes the shell and sets up the necessary configurations. -- **Command Handlers**: Command handlers are defined in files like [localWhisperCommandHandler.ts](./src/main/localWhisperCommandHandler.ts) and [commands/pen.ts](./src/main/commands/pen.ts). These handlers process specific commands and actions. -- **Speech Processing**: Speech processing functionalities are implemented in [azureSpeech.ts](./src/main/azureSpeech.ts), which handles interactions with Azure Speech Services. -- **Browser IPC**: The browser IPC component, defined in [browserIpc.ts](./src/main/browserIpc.ts), manages inter-process communication between the shell and the browser. -- **Chat Server**: The chat server, implemented in [chatServer.ts](./src/main/chatServer.ts), handles WebSocket connections and serves the HTML page for the shell interface. +- **Main Entry Point**: The primary entry point is [index.ts](./src/main/index.ts), which initializes the shell and sets up configurations. +- **Command Handlers**: Command processing is implemented in files such as [localWhisperCommandHandler.ts](./src/main/localWhisperCommandHandler.ts) and [commands/pen.ts](./src/main/commands/pen.ts). These files define the logic for handling specific commands. +- **Speech Processing**: The [azureSpeech.ts](./src/main/azureSpeech.ts) file manages interactions with Azure Speech Services, including token handling and speech-to-text processing. +- **Browser IPC**: The [browserIpc.ts](./src/main/browserIpc.ts) file handles inter-process communication between the shell and the browser. +- **Chat Server**: The [chatServer.ts](./src/main/chatServer.ts) file implements the WebSocket server for managing chat interactions and serving the shell's HTML interface. ## How to extend To extend the `agent-shell` package, follow these steps: -1. **Open the main entry point**: Start by examining [index.ts](./src/main/index.ts) to understand the initialization process and overall structure. -2. **Add new command handlers**: Implement new command handlers in appropriate files, such as [commands/pen.ts](./src/main/commands/pen.ts). Follow the existing patterns for defining and registering command handlers. -3. **Integrate new services**: If you need to integrate new services (e.g., speech processing), modify or add files like [azureSpeech.ts](./src/main/azureSpeech.ts) to handle interactions with the new service. -4. **Test your changes**: Ensure that your changes are thoroughly tested. Run the shell using `pnpm run shell` and verify that the new functionalities work as expected. +1. **Understand the Initialization Process**: Start by reviewing [index.ts](./src/main/index.ts) to understand how the shell is initialized and configured. +2. **Add New Command Handlers**: Implement new command handlers in files like [commands/pen.ts](./src/main/commands/pen.ts). Use the existing patterns for defining and registering handlers. +3. **Integrate Additional Services**: If you need to add new services (e.g., for speech processing or external APIs), modify or create files such as [azureSpeech.ts](./src/main/azureSpeech.ts) to handle the integration. +4. **Test Your Changes**: Run the shell using `pnpm run shell` and verify that your changes work as intended. Ensure that all new functionality is thoroughly tested. +5. **Follow Existing Patterns**: Adhere to the established coding conventions and patterns in the project to maintain consistency and readability. -By following these steps, you can effectively extend the capabilities of the `agent-shell` package and contribute to its development. +By following these guidelines, you can effectively contribute to the development and enhancement of the `agent-shell` package. ## Reference @@ -64,7 +81,7 @@ By following these steps, you can effectively extend the capabilities of the `ag ### Entry points -- default → [./out/main/index.js](./out/main/index.js) +- default → `./out/main/index.js` _(not found on disk)_ ### Dependencies @@ -95,7 +112,7 @@ External: `@azure/identity`, `@azure/msal-node-extensions`, `@electron-toolkit/p ### Files of interest -`./src/main/index.ts`, `./src/main/localWhisperCommandHandler.ts`, `./src/main/speechProcessingSchema.ts`, …and 66 more under `./src/`. +`./src/main/index.ts`, `./src/main/localWhisperCommandHandler.ts`, `./src/main/speechProcessingSchema.ts`, …and 65 more under `./src/`. ### Environment variables @@ -109,6 +126,6 @@ _5 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-shell docs:verify-links` to spot-check._ +_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 agent-shell docs:verify-links` to spot-check._ diff --git a/ts/packages/studio-service/README.AUTOGEN.md b/ts/packages/studio-service/README.AUTOGEN.md index aa02c1f60..2719d75a9 100644 --- a/ts/packages/studio-service/README.AUTOGEN.md +++ b/ts/packages/studio-service/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # studio-service — AI-generated documentation @@ -12,38 +12,38 @@ ## Overview -The `studio-service` package is the standalone, per-workspace host of the TypeAgent Studio runtime (`@typeagent/core/runtime`) and its typed `agent-rpc` service channel. It is designed to run independently within a developer's workspace, providing a dedicated environment for the Studio runtime. This package is launched by the `typeagent-studio` extension or the `typeagent-studio serve` CLI, and serves as the backend for the `studio` agent and the extension. +The `studio-service` package is a standalone, per-workspace host for the TypeAgent Studio runtime (`@typeagent/core/runtime`) and its typed `agent-rpc` service channel. It is designed to operate independently within a developer's workspace, providing a dedicated environment for managing workspace state and facilitating communication between the Studio runtime and its clients. This service is typically launched by the `typeagent-studio` extension or the `typeagent-studio serve` CLI. ## What it does -The `studio-service` package provides several key functionalities: +The `studio-service` package provides the following core functionalities: -- **Studio Runtime Hosting**: It hosts the Studio runtime, which is responsible for managing the workspace state and executing various actions within the developer's workspace. -- **Service Channel**: It establishes a typed `agent-rpc` service channel that allows communication between the Studio runtime and its clients (the `studio` agent and the extension). -- **Workspace State Management**: It uses a durable, file-backed `StudioWorkspaceState` to persist runtime state across service restarts. -- **Service Discovery and Registry**: It includes mechanisms for announcing the service and discovering its port and token, enabling clients to connect and interact with the service. -- **Proxy Client**: It provides a minimal client for the `studio` agent to forward read-only actions to the standalone Studio service. +- **Hosting the Studio Runtime**: The package runs the Studio runtime, which is responsible for managing workspace state and executing actions within the developer's workspace. +- **Typed Service Channel**: It establishes a typed `agent-rpc` service channel, enabling communication between the Studio runtime and its clients, such as the `studio` agent and the `typeagent-studio` extension. +- **Workspace State Management**: The service uses a durable, file-backed `StudioWorkspaceState` to persist runtime state across service restarts, ensuring continuity. +- **Service Discovery and Registration**: The service includes mechanisms for announcing its availability, discovering its port and token, and enabling clients to connect securely. +- **Proxy Client**: A minimal client is provided for the `studio` agent to forward read-only actions to the standalone Studio service. -The package supports actions such as `createMessage`, `deleteMessage`, `updateMessage`, and `fetchMessages`, among others, which are grouped thematically to manage messages within the workspace. +The package supports a range of actions, including workspace state management and communication with the Studio runtime. These actions are exposed through typed `agent-rpc` handlers, which are defined in the [studioRpcHandlers.ts](./src/studioRpcHandlers.ts) file. ## Setup -To set up the `studio-service` package, you need to configure the following environment variable: +To configure and run the `studio-service` package, you need to set the following environment variable: -- `TYPEAGENT_STUDIO_REPO_ROOT`: This variable specifies the root directory of the repository that the Studio service should inspect. It can be set to an explicit path if the agent runs outside the repository it should inspect. If not set, the service will use the current working directory. +- `TYPEAGENT_STUDIO_REPO_ROOT`: Specifies the root directory of the repository that the Studio service should inspect. If this variable is not set, the service defaults to using the current working directory. You can set this variable in your shell or `.env` file. -Ensure that this environment variable is correctly set in your shell or `.env` file before launching the service. +Ensure that this environment variable is correctly configured before launching the service. The service can be started using the `typeagent-studio serve` CLI or programmatically via its API. ## Key Files -The `studio-service` package consists of several key files, each responsible for different aspects of the service: +The `studio-service` package is organized into several key files, each responsible for specific aspects of the service: -- [`index.ts`](./src/index.ts): The entry point of the package, exposing the external surface consumed by the `studio` agent. -- [`main.ts`](./src/main.ts): The process entry point for launching the standalone Studio service. It parses command-line arguments and starts the service. -- [`fileWorkspaceState.ts`](./src/fileWorkspaceState.ts): Manages the durable, file-backed workspace state, ensuring that runtime state persists across service restarts. -- [`runtime.ts`](./src/runtime.ts): Contains functions for resolving repository root candidates and creating the Studio runtime core. -- [`studioRegistry.ts`](./src/studioRegistry.ts): Implements the service registry relay, allowing the service to announce itself and enabling clients to discover it. -- [`studioRpcHandlers.ts`](./src/studioRpcHandlers.ts): Defines the typed invoke handlers exposed by the Studio service over the channel. +- [`index.ts`](./src/index.ts): The main entry point of the package, exposing the external API consumed by the `studio` agent and other clients. +- [`main.ts`](./src/main.ts): The process entry point for launching the standalone Studio service. It handles command-line arguments and initializes the service. +- [`fileWorkspaceState.ts`](./src/fileWorkspaceState.ts): Implements a durable, file-backed workspace state to persist runtime data across service restarts. +- [`runtime.ts`](./src/runtime.ts): Provides functions for resolving repository root candidates and creating the Studio runtime core. +- [`studioRegistry.ts`](./src/studioRegistry.ts): Implements the service registry, enabling the service to announce itself and allowing clients to discover and connect to it. +- [`studioRpcHandlers.ts`](./src/studioRpcHandlers.ts): Defines the typed `agent-rpc` handlers that expose the service's functionality to clients. - [`studioService.ts`](./src/studioService.ts): Contains the logic for starting and managing a running Studio service instance. - [`studioServiceProxyClient.ts`](./src/studioServiceProxyClient.ts): Provides a minimal client for the `studio` agent to forward read-only actions to the Studio service. @@ -51,16 +51,16 @@ The `studio-service` package consists of several key files, each responsible for To extend the `studio-service` package, follow these steps: -1. **Open the `index.ts` file**: This file serves as the entry point and exposes the package's external surface. Start here to understand the overall structure and exported functions. -2. **Explore the `main.ts` file**: This file contains the logic for launching the service. If you need to modify the startup process or add new command-line arguments, this is the place to do it. -3. **Modify `fileWorkspaceState.ts`**: If you need to change how the workspace state is managed or add new state persistence mechanisms, update this file. -4. **Enhance `runtime.ts`**: To add new runtime functionalities or modify repository root resolution, make changes in this file. -5. **Update `studioRegistry.ts`**: If you need to change how the service announces itself or how clients discover it, this is the file to modify. -6. **Add new RPC handlers in `studioRpcHandlers.ts`**: To extend the set of actions exposed by the service, define new handlers in this file. -7. **Extend `studioService.ts`**: To add new functionalities to the running service instance, update this file. -8. **Modify `studioServiceProxyClient.ts`**: If you need to change how the `studio` agent interacts with the service, make changes in this file. +1. **Understand the entry point**: Start with [index.ts](./src/index.ts) to understand the external API and how the package is structured. +2. **Modify the service startup**: If you need to change how the service is launched or add new command-line options, update [main.ts](./src/main.ts). +3. **Enhance workspace state management**: To modify how the workspace state is persisted or add new features, work on [fileWorkspaceState.ts](./src/fileWorkspaceState.ts). +4. **Extend runtime capabilities**: To add new runtime features or modify repository root resolution, update [runtime.ts](./src/runtime.ts). +5. **Update service discovery**: If you need to change how the service announces itself or how clients discover it, modify [studioRegistry.ts](./src/studioRegistry.ts). +6. **Add new actions**: Define additional `agent-rpc` handlers in [studioRpcHandlers.ts](./src/studioRpcHandlers.ts) to expose new functionalities. +7. **Enhance service logic**: To add new features to the running service instance, update [studioService.ts](./src/studioService.ts). +8. **Modify the proxy client**: If the `studio` agent's interaction with the service needs to change, update [studioServiceProxyClient.ts](./src/studioServiceProxyClient.ts). -After making your changes, ensure that you run the tests to verify that everything works as expected. The package's tests import the necessary modules directly and can be found alongside the implementation files. +After making changes, ensure that you run the package's tests to verify the functionality. Tests are located alongside the implementation files and are designed to validate the behavior of individual components. ## Reference @@ -68,7 +68,7 @@ After making your changes, ensure that you run the tests to verify that everythi ### Entry points -- default → [./dist/index.js](./dist/index.js) +- default → `./dist/index.js` _(not found on disk)_ ### Dependencies @@ -97,6 +97,6 @@ _1 environment variable referenced from `./src/` (set in `ts/.env` or your shell --- -_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 studio-service docs:verify-links` to spot-check._ +_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 studio-service docs:verify-links` to spot-check._ diff --git a/ts/packages/typeagent-core/README.AUTOGEN.md b/ts/packages/typeagent-core/README.AUTOGEN.md index c968e3770..7d4dca778 100644 --- a/ts/packages/typeagent-core/README.AUTOGEN.md +++ b/ts/packages/typeagent-core/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # @typeagent/core — AI-generated documentation @@ -12,58 +12,67 @@ ## Overview -The `@typeagent/core` package is a shared engine library for TypeAgent Studio extensions. It provides core functionalities and services that are used across various TypeAgent subsystems. This package is essential for managing the sandbox lifecycle, federating corpora, handling structured event streams, providing feedback mechanisms, ensuring health rules, detecting collisions, replaying corpora, and bridging onboarding processes. +The `@typeagent/core` package is a foundational TypeScript library that provides shared functionality for TypeAgent Studio extensions. It serves as the engine for managing key subsystems such as sandbox lifecycles, federated corpora, structured event streams, feedback mechanisms, health rule engines, collision detection, corpus replay, and onboarding processes. This package is consumed by other components in the TypeAgent ecosystem, including `typeagent-studio`, `agr-language`, and `vscode-shell`. ## What it does -The `@typeagent/core` package offers a variety of features that are grouped into different modules: +The package is organized into modular subsystems, each addressing a specific aspect of the TypeAgent Studio's functionality. These subsystems include: -- **Events**: Manages structured event streams (`createEventStream`, `logEvent`). -- **Sandbox**: Handles sandbox lifecycle management (`createSandbox`, `destroySandbox`). -- **Corpus**: Manages federated corpora (`createCorpus`, `addDocumentToCorpus`). -- **Feedback**: Provides feedback mechanisms (`sendFeedback`, `getFeedback`). -- **Health**: Implements health rule engines (`checkHealth`, `updateHealthStatus`). -- **Collisions**: Detects and manages collision events (`scanCollisions`, `resolveCollision`). -- **Replay**: Facilitates corpus replay functionalities (`replayCorpus`, `pauseReplay`). -- **Onboarding Bridge**: Manages snapshot and restore processes (`createSnapshot`, `restoreSnapshot`). +- **Events**: Provides tools for managing structured event streams, such as creating and logging events. +- **Sandbox**: Manages the lifecycle of sandboxes, including creation and destruction. +- **Corpus**: Handles federated corpora, enabling the creation and management of corpora and their associated documents. +- **Feedback**: Implements feedback mechanisms for collecting and processing user feedback. +- **Health**: Provides a rule engine for monitoring and maintaining the health of the system. +- **Collisions**: Detects and manages collision events, including grammar-based and dispatcher-based collisions. +- **Replay**: Supports replaying corpora for testing and debugging purposes. +- **Onboarding Bridge**: Facilitates snapshot and restore operations for onboarding workflows. -These modules are consumed by other packages such as `typeagent-studio`, `agr-language`, and `vscode-shell`. +Each subsystem is implemented in its own directory under `src/`, with a clear separation of concerns. These modules are designed to be lightweight and reusable across the TypeAgent ecosystem. ## Setup -To set up the `@typeagent/core` package, you need to configure the following environment variable: +To use the `@typeagent/core` package, you need to configure the following environment variable: -- `TYPEAGENT_USER_DATA_DIR`: This variable specifies the directory where user data is stored. Ensure that this directory exists and is accessible by the application. +- `TYPEAGENT_USER_DATA_DIR`: This environment variable specifies the directory where user data is stored. Ensure that the directory exists and is accessible by the application. For more details on how to configure this variable, refer to the hand-written README. -Refer to the hand-written README for detailed instructions on obtaining and setting up this environment variable. +No additional setup steps are required beyond setting this environment variable. ## Key Files -The package is organized into several key files and directories, each responsible for different functionalities: +The `@typeagent/core` package is structured into several key directories and files, each responsible for specific functionalities: -- **[src/index.ts](./src/index.ts)**: The main entry point that exports core type definitions and services shared across TypeAgent subsystems. -- **[src/events/index.ts](./src/events/index.ts)**: Manages structured event streams. -- **[src/sandbox/index.ts](./src/sandbox/index.ts)**: Handles sandbox lifecycle management. -- **[src/corpus/index.ts](./src/corpus/index.ts)**: Manages federated corpora. -- **[src/feedback/index.ts](./src/feedback/index.ts)**: Provides feedback mechanisms. -- **[src/health/index.ts](./src/health/index.ts)**: Implements health rule engines. -- **[src/collisions/index.ts](./src/collisions/index.ts)**: Detects and manages collision events. -- **[src/collisions/scanner.ts](./src/collisions/scanner.ts)**: Repository-backed grammar collision scanner. -- **[src/replay/index.ts](./src/replay/index.ts)**: Facilitates corpus replay functionalities. -- **[src/onboardingBridge/index.ts](./src/onboardingBridge/index.ts)**: Manages snapshot and restore processes. +### Core Modules + +- **[src/index.ts](./src/index.ts)**: The main entry point for the package, exporting shared types and services. +- **[src/events/index.ts](./src/events/index.ts)**: Manages structured event streams, including event creation and logging. +- **[src/sandbox/index.ts](./src/sandbox/index.ts)**: Handles the lifecycle of sandboxes, such as creation and destruction. +- **[src/corpus/index.ts](./src/corpus/index.ts)**: Provides tools for managing federated corpora, including file-based corpus services and utilities for handling JSONL data. +- **[src/feedback/index.ts](./src/feedback/index.ts)**: Implements feedback mechanisms for collecting and processing user input. +- **[src/health/index.ts](./src/health/index.ts)**: Contains the health rule engine for monitoring system health and status. +- **[src/collisions/index.ts](./src/collisions/index.ts)**: Detects and manages collision events, with support for both dispatcher and grammar-based collisions. +- **[src/replay/index.ts](./src/replay/index.ts)**: Facilitates corpus replay functionalities for testing and debugging. +- **[src/onboardingBridge/index.ts](./src/onboardingBridge/index.ts)**: Manages snapshot and restore processes for onboarding workflows. + +### Supporting Files + +- **[src/collisions/scanner.ts](./src/collisions/scanner.ts)**: Implements a repository-backed grammar collision scanner that integrates with the `grammar-tools-core` library. +- **[src/corpus/fileCorpusService.ts](./src/corpus/fileCorpusService.ts)**: Provides a filesystem-backed service for managing corpora, including support for multiple data sources. +- **[src/corpus/id.ts](./src/corpus/id.ts)**: Contains utilities for generating unique identifiers for corpus entries. +- **[src/corpus/jsonl.ts](./src/corpus/jsonl.ts)**: Includes utilities for parsing and formatting JSONL files, which are used to store corpus data. ## How to extend -To extend the `@typeagent/core` package, follow these steps: +To extend the functionality of the `@typeagent/core` package, follow these steps: -1. **Identify the module**: Determine which module you need to extend (e.g., events, sandbox, corpus). -2. **Open the relevant file**: Navigate to the corresponding directory and open the relevant file (e.g., [src/events/index.ts](./src/events/index.ts)). -3. **Add new functionality**: Implement the new functionality by following the existing patterns and structures. Ensure that your code adheres to the project's coding standards. -4. **Update exports**: If you add new functions or classes, make sure to export them in the module's index file. -5. **Write tests**: Add tests for your new functionality to ensure it works as expected. Place your tests in the appropriate test directory. -6. **Run tests**: Execute the test suite to verify that your changes do not break existing functionality. +1. **Identify the subsystem**: Determine which subsystem (e.g., events, sandbox, corpus) you need to modify or extend. +2. **Locate the relevant files**: Navigate to the corresponding directory under `src/` (e.g., `src/events/` for event-related functionality). +3. **Follow existing patterns**: Review the existing code to understand the structure and conventions used in the package. For example, most subsystems have a clear separation between types, services, and utility functions. +4. **Add new functionality**: Implement your changes or new features in the appropriate files. Ensure that your code adheres to the project's coding standards and is consistent with the existing implementation. +5. **Update exports**: If you add new functions, classes, or types, make sure to export them in the module's `index.ts` file. +6. **Write tests**: Add unit tests for your new functionality. Place the tests in the appropriate test directory, following the existing test structure. +7. **Run the test suite**: Execute the test suite to ensure that your changes do not introduce any regressions or break existing functionality. -By following these steps, you can effectively extend the capabilities of the `@typeagent/core` package and contribute to its development. +By following these steps, you can effectively contribute to the development of the `@typeagent/core` package and extend its capabilities. ## Reference @@ -71,18 +80,19 @@ By following these steps, you can effectively extend the capabilities of the `@t ### Entry points -- default → [./dist/index.js](./dist/index.js) -- `./events` → [./dist/events/index.js](./dist/events/index.js) -- `./sandbox` → [./dist/sandbox/index.js](./dist/sandbox/index.js) -- `./corpus` → [./dist/corpus/index.js](./dist/corpus/index.js) -- `./feedback` → [./dist/feedback/index.js](./dist/feedback/index.js) -- `./health` → [./dist/health/index.js](./dist/health/index.js) -- `./collisions` → [./dist/collisions/index.js](./dist/collisions/index.js) -- `./collisionScanner` → [./dist/collisions/scanner.js](./dist/collisions/scanner.js) -- `./replay` → [./dist/replay/index.js](./dist/replay/index.js) +- default → `./dist/index.js` _(not found on disk)_ +- `./events` → `./dist/events/index.js` _(not found on disk)_ +- `./sandbox` → `./dist/sandbox/index.js` _(not found on disk)_ +- `./corpus` → `./dist/corpus/index.js` _(not found on disk)_ +- `./feedback` → `./dist/feedback/index.js` _(not found on disk)_ +- `./health` → `./dist/health/index.js` _(not found on disk)_ +- `./collisions` → `./dist/collisions/index.js` _(not found on disk)_ +- `./collisionScanner` → `./dist/collisions/scanner.js` _(not found on disk)_ +- `./replay` → `./dist/replay/index.js` _(not found on disk)_ - `./replayResolver` → `./dist/replay/grammarResolver.js` _(not found on disk)_ -- `./onboardingBridge` → [./dist/onboardingBridge/index.js](./dist/onboardingBridge/index.js) -- `./runtime` → [./dist/runtime/index.js](./dist/runtime/index.js) +- `./onboardingBridge` → `./dist/onboardingBridge/index.js` _(not found on disk)_ +- `./webview` → `./dist/webview/index.js` _(not found on disk)_ +- `./runtime` → `./dist/runtime/index.js` _(not found on disk)_ ### Dependencies @@ -115,7 +125,7 @@ External: `debug` - [./src/replay/index.ts](./src/replay/index.ts) - [./src/runtime/index.ts](./src/runtime/index.ts) - [./src/sandbox/index.ts](./src/sandbox/index.ts) -- _…and 36 more under `./src/`._ +- _…and 38 more under `./src/`._ ### Environment variables @@ -125,6 +135,6 @@ _1 environment variable referenced from `./src/` (set in `ts/.env` or your shell --- -_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/core docs:verify-links` to spot-check._ +_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/core docs:verify-links` to spot-check._ diff --git a/ts/packages/typeagent-studio/README.AUTOGEN.md b/ts/packages/typeagent-studio/README.AUTOGEN.md index 121b4da1c..fc91f524d 100644 --- a/ts/packages/typeagent-studio/README.AUTOGEN.md +++ b/ts/packages/typeagent-studio/README.AUTOGEN.md @@ -3,7 +3,7 @@ - + # typeagent-studio — AI-generated documentation @@ -12,94 +12,153 @@ ## Overview -The `typeagent-studio` package is a TypeScript library that provides a developer experience for authoring, tuning, and validating TypeAgent agents. It includes features such as compare-and-replay regression detection, schema/grammar tuning, trace investigation, and live observation. This package is designed to be used as a VS Code extension, offering various views and commands to facilitate the development and debugging of TypeAgent agents. +The `typeagent-studio` package is a TypeScript library that serves as the backbone for the TypeAgent developer experience within Visual Studio Code. It provides tools and interfaces for authoring, debugging, and optimizing TypeAgent agents. Key features include schema and grammar tuning, compare-and-replay regression detection, trace investigation, and live observation of agent behavior. This package is designed to streamline the development and validation of TypeAgent agents, making it an essential tool for developers working within the TypeAgent ecosystem. ## What it does -The `typeagent-studio` package offers a comprehensive set of tools and views to enhance the developer experience when working with TypeAgent agents. Key functionalities include: - -- **Agent Authoring**: Provides commands and views to create and manage TypeAgent agents. -- **Schema/Grammar Tuning**: Tools for adjusting and validating agent schemas and grammars. -- **Compare-and-Replay Regression Detection**: Allows developers to replay corpora and compare results to detect regressions. -- **Trace Investigation**: Tools for investigating traces and debugging agent behavior. -- **Live Observation**: Real-time monitoring of agent activity and health. +The `typeagent-studio` package integrates with Visual Studio Code to provide a rich set of features for working with TypeAgent agents. These features are organized into commands and views, which are accessible through the VS Code interface. ### Commands -The package includes a variety of commands accessible via the VS Code command palette, such as: +The package offers a wide range of commands, accessible via the VS Code command palette, to support various stages of agent development and debugging. Some of the key commands include: + +- **Onboarding and Sandbox Management**: + + - `TypeAgent Studio: Start onboarding session` + - `TypeAgent Studio: Run onboarding phase` + - `TypeAgent Studio: Start sandbox` + - `TypeAgent Studio: Stop sandbox` + - `TypeAgent Studio: Refresh sandboxes` + +- **Agent and Corpus Management**: -- `TypeAgent Studio: Start onboarding session` -- `TypeAgent Studio: Install latest onboarding session to sandbox` -- `TypeAgent Studio: Check packaging health gate` -- `TypeAgent Studio: Run onboarding phase` -- `TypeAgent Studio: Start sandbox` -- `TypeAgent Studio: Refresh sandboxes` -- `TypeAgent Studio: Replay corpus` + - `TypeAgent Studio: Install latest onboarding session to sandbox` + - `TypeAgent Studio: Replay corpus` + - `TypeAgent Studio: Refresh corpora` + +- **Health and Diagnostics**: + - `TypeAgent Studio: Check packaging health gate` + - `TypeAgent Studio: Enforce packaging health gate` + - `TypeAgent Studio: Export onboarding artifact...` + +These commands enable developers to manage sandboxes, run onboarding sessions, replay corpora, and monitor the health of their agents. ### Views -The package provides several views within the **TypeAgent Studio** activity-bar container: +The package provides several specialized views within the **TypeAgent Studio** activity-bar container: + +1. **Sandboxes View**: + + - Displays running sandboxes and their loaded agents. + - Provides inline actions for starting, stopping, restarting, and refreshing sandboxes. + - Shows agent health badges derived from the `FileHealthService`. + +2. **Corpora View**: + + - Lists corpus entries for agents, grouped by source (e.g., in-repo, captures, external, feedback). + - Allows users to explore and manage corpora associated with loaded agents. + +3. **Feedback Capture**: + + - Enables users to record feedback on agent performance, including ratings, comments, and categories. + - Feedback is integrated into the Corpora view for further analysis. + +4. **Event Log View**: + + - Displays a chronological list of recent events related to agent activity. + - Provides a quick overview of events with timestamps, icons, and tooltips. + +5. **Collisions View**: + + - Lists detected schema/grammar collisions, categorized by type (e.g., overlap, shadow, ambiguity). + - Allows users to investigate and resolve conflicts in agent definitions. -- **Sandboxes View**: Displays running sandboxes and their loaded agents, with options to start, stop, restart, and refresh sandboxes. -- **Corpora View**: Shows the corpus entries for agents, grouped by source (in-repo, captures, external, feedback). -- **Feedback Capture**: Allows users to record feedback on agent performance. -- **Event Log View**: Lists recent events related to agent activity. -- **Collisions View**: Displays detected schema/grammar collisions. +6. **Health Status Bar**: + - Summarizes the health of all agents loaded into running sandboxes. + - Provides a quick visual indicator of the overall system health. ## Setup -To set up the `typeagent-studio` package, follow these steps: +To get started with the `typeagent-studio` package, follow these steps: 1. **Build the package**: + Navigate to the package directory and run the build command: ```sh cd packages/typeagent-studio pnpm run build ``` - This command produces the `dist/extension.js` file. + This will generate the `dist/extension.js` file. + +2. **Run the local test loop**: + To test and rebuild the package locally, use the following commands: -2. **Local Test Loop**: ```sh cd packages/typeagent-studio pnpm run test:local pnpm run build ``` - This sequence runs local tests and rebuilds the package. + +3. **Install dependencies**: + Ensure all required dependencies are installed by running: + ```sh + pnpm install + ``` + +For additional setup details, refer to the hand-written README or the relevant documentation in the repository. ## Key Files -The package's source code is organized into several key files, each responsible for different aspects of the functionality: +The `typeagent-studio` package is organized into several key files and modules, each responsible for specific functionality: -- **[extension.ts](./src/extension.ts)**: The main entry point for the VS Code extension, responsible for registering commands and initializing the runtime. -- **[collisionsPresentation.ts](./src/collisionsPresentation.ts)**: Handles the presentation logic for collision events, mapping them to tree rows. -- **[collisionsSource.ts](./src/collisionsSource.ts)**: Defines the interface for collision sources and manages collision detection and scanning. -- **[collisionsTreeProvider.ts](./src/collisionsTreeProvider.ts)**: A thin VS Code adapter that provides collision data to the tree view. -- **[commands.ts](./src/commands.ts)**: Registers and implements the various commands available in the command palette. -- **[corpusTreePresentation.ts](./src/corpusTreePresentation.ts)**: Manages the presentation logic for corpus entries, grouping them into tree nodes. -- **[corpusTreeProvider.ts](./src/corpusTreeProvider.ts)**: A thin VS Code adapter that provides corpus data to the tree view. -- **[eventLogPresentation.ts](./src/eventLogPresentation.ts)**: Handles the presentation logic for event log entries, mapping them to tree rows. +- **[extension.ts](./src/extension.ts)**: The main entry point for the VS Code extension. It initializes the extension, registers commands, and sets up views. +- **[commands.ts](./src/commands.ts)**: Contains the implementation of all commands available in the VS Code command palette. +- **[sandboxTreePresentation.ts](./src/sandboxTreePresentation.ts)** and **[sandboxTreeProvider.ts](./src/sandboxTreeProvider.ts)**: Handle the presentation and data provisioning for the Sandboxes view. +- **[corpusTreePresentation.ts](./src/corpusTreePresentation.ts)** and **[corpusTreeProvider.ts](./src/corpusTreeProvider.ts)**: Manage the presentation and data provisioning for the Corpora view. +- **[eventLogPresentation.ts](./src/eventLogPresentation.ts)** and **[eventLogTreeProvider.ts](./src/eventLogTreeProvider.ts)**: Handle the Event Log view, summarizing and displaying recent events. +- **[collisionsPresentation.ts](./src/collisionsPresentation.ts)** and **[collisionsTreeProvider.ts](./src/collisionsTreeProvider.ts)**: Manage the Collisions view, including collision detection and presentation. +- **[healthStatusPresentation.ts](./src/healthStatusPresentation.ts)** and **[studioStatusBar.ts](./src/studioStatusBar.ts)**: Handle the health status bar, aggregating and displaying agent health information. ## How to extend -To extend the `typeagent-studio` package, follow these steps: +To contribute to or extend the `typeagent-studio` package, follow these guidelines: -1. **Start with the main entry point**: Open the [extension.ts](./src/extension.ts) file to understand how commands and views are registered and initialized. +1. **Understand the architecture**: -2. **Add new commands**: Implement new commands in the [commands.ts](./src/commands.ts) file. Register them in the `registerStudioCommands` function. + - Start by reviewing the [extension.ts](./src/extension.ts) file to understand how the extension is initialized and how commands and views are registered. -3. **Extend views**: To add or modify views, update the corresponding presentation and provider files. For example, to extend the Sandboxes view, modify [sandboxTreePresentation.ts](./src/sandboxTreePresentation.ts) and [sandboxTreeProvider.ts](./src/sandboxTreeProvider.ts). +2. **Add new commands**: -4. **Unit tests**: Ensure that new functionality is covered by unit tests. The presentation logic is separated from VS Code-specific code to facilitate testing without the editor host. + - Implement new commands in the [commands.ts](./src/commands.ts) file. + - Register the new commands in the `registerStudioCommands` function. -5. **Run tests**: Use the local test loop to run tests and build the package: - ```sh - cd packages/typeagent-studio - pnpm run test:local - pnpm run build - ``` +3. **Extend existing views**: + + - To modify or enhance a view, update its corresponding presentation and provider files. For example: + - Sandboxes view: [sandboxTreePresentation.ts](./src/sandboxTreePresentation.ts) and [sandboxTreeProvider.ts](./src/sandboxTreeProvider.ts). + - Corpora view: [corpusTreePresentation.ts](./src/corpusTreePresentation.ts) and [corpusTreeProvider.ts](./src/corpusTreeProvider.ts). + +4. **Add new views**: + + - Create a new presentation module for the view's logic (e.g., `newViewPresentation.ts`). + - Implement a `TreeDataProvider` adapter for the view (e.g., `newViewTreeProvider.ts`). + - Register the new view in the `extension.ts` file. + +5. **Write unit tests**: + + - Ensure that all new functionality is covered by unit tests. + - Presentation logic is separated from VS Code-specific code to facilitate testing without the editor host. + +6. **Test and build**: + - Use the local test loop to verify your changes: + ```sh + cd packages/typeagent-studio + pnpm run test:local + pnpm run build + ``` -By following these steps, you can effectively extend the functionality of the `typeagent-studio` package and contribute to its development. +By following these steps, you can effectively contribute to the `typeagent-studio` package and enhance its capabilities. For more details, refer to the hand-written README or the source code. ## Reference @@ -107,7 +166,7 @@ By following these steps, you can effectively extend the functionality of the `t ### Entry points -- default → [./dist/extension.js](./dist/extension.js) +- default → `./dist/extension.js` _(not found on disk)_ ### Dependencies @@ -122,10 +181,10 @@ External: `debug`, `ws` ### Files of interest -`./src/collisionsPresentation.ts`, `./src/collisionsSource.ts`, `./src/collisionsTreeProvider.ts`, …and 48 more under `./src/`. +`./src/baseTreeProvider.ts`, `./src/collisionsPresentation.ts`, `./src/collisionsSource.ts`, …and 54 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-studio docs:verify-links` to spot-check._ +_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-studio 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 670475070..e0451ea0b 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 @@ -12,39 +12,40 @@ ## Overview -The `vscode-shell` package embeds the TypeAgent shell chat directly into Visual Studio Code, providing a side panel and editor tabs for interacting with TypeAgent conversations. Each chat panel is backed by a TypeAgent conversation hosted by the running TypeAgent agent server. +The `vscode-shell` package integrates the TypeAgent shell chat into Visual Studio Code, providing a side panel and editor tabs for interacting with TypeAgent conversations. Each chat panel is backed by a TypeAgent conversation hosted by a running TypeAgent agent server. ## What it does -The `vscode-shell` package integrates TypeAgent's chat functionality into VS Code, allowing users to open and manage conversations directly within the editor. It supports various actions such as `newConversation`, `renameConversation`, `switchConversation`, and `deleteConversation`. Users can interact with the chat through the activity bar icon, keyboard shortcuts, and command palette commands. The package also provides IntelliSense features like inline ghost text and dropdown menus for command completions. +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: -### Key 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. +- **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. -- **Activity Bar Integration**: Opens the persistent **Chat** side panel. -- **Editor Tabs**: Allows multiple chat tabs, each representing a separate conversation. -- **Command Palette**: Provides commands for managing conversations, 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**: Offers inline ghost text and dropdown menus for command completions. -- **Conversation Management**: Supports chat-driven commands to manage conversations, such as creating, renaming, switching, and deleting conversations. +The extension also supports a `vscode-shell-action` client action, which can be enabled or disabled per session using the `@config schema` command. ## Setup -To set up the `vscode-shell` package, ensure you have the following prerequisites: +To use the `vscode-shell` package, ensure the following prerequisites are met: -- Visual Studio Code version 1.90 or newer. -- A running TypeAgent agent server reachable on `ws://localhost:8999`. +1. **Visual Studio Code**: Version 1.90 or newer is required. +2. **TypeAgent Agent Server**: A running instance of the TypeAgent agent server is needed, accessible at `ws://localhost:8999` by default. -Start the agent server from the TypeAgent monorepo: +To start the agent server: ```sh cd ts/packages/agentServer/server pnpm run start ``` -The agent server depends on the rest of the TypeAgent stack being built. See the top-level TypeAgent README for setup. +The agent server requires the rest of the TypeAgent stack to be built. Refer to the top-level TypeAgent README for detailed setup instructions. ### Installation -#### Build & install locally (recommended for development) +#### Build & Install Locally (Recommended for Development) From the `vscode-shell` directory: @@ -53,15 +54,17 @@ npm install npm run deploy:local ``` -`deploy:local` packages the extension and installs it into your active `code` CLI in one step. Reload the VS Code window after the first install. +This command packages the extension and installs it into your active `code` CLI in one step. After the first installation, reload the VS Code window. -To uninstall a previous version (e.g. the legacy `typeagent-shell` package): +To remove a previously installed version (e.g., the legacy `typeagent-shell` package): ```sh code --uninstall-extension typeagent.typeagent-shell ``` -#### Install a prebuilt VSIX +#### Install a Prebuilt VSIX + +Alternatively, you can install a prebuilt VSIX package: ```sh npm run package @@ -70,30 +73,50 @@ code --install-extension dist-pub/vscode-shell.vsix --force ## Key Files -The `vscode-shell` package consists of several key components: - -- **Extension Host**: Manages the WebSocket connection to the agent server and bridges messages to/from webview panels. Key files include [agentServerBridge.ts](./src/agentServerBridge.ts) and [clientIO.ts](./src/bridge/clientIO.ts). -- **Webview UI**: Provides the chat interface within VS Code. The main entry point is [main.ts](./src/webview/main.ts). -- **Chat View Provider**: Handles the creation and management of webview panels for the chat interface. See [chatViewProvider.ts](./src/chatViewProvider.ts). -- **Extension Activation**: Initializes the extension and sets up the necessary commands and keybindings. See [extension.ts](./src/extension.ts). +The `vscode-shell` package is organized into several key components, each responsible for specific functionality: -### Key Files and Their Responsibilities +- **[agentServerBridge.ts](./src/agentServerBridge.ts)**: Manages the WebSocket connection to the agent server and bridges messages between the extension host and the webview panels. +- **[clientIO.ts](./src/bridge/clientIO.ts)**: Implements the `ClientIO` interface, forwarding calls to the webview and handling request IDs for cancellation and message routing. +- **[main.ts](./src/webview/main.ts)**: The entry point for the webview, responsible for rendering the chat interface within VS Code. +- **[chatViewProvider.ts](./src/chatViewProvider.ts)**: Provides the chat webview for the sidebar and manages the creation of editor panels for individual chat sessions. +- **[extension.ts](./src/extension.ts)**: Contains the activation logic for the extension, including setting up commands, keybindings, and the status bar integration. -- **[agentServerBridge.ts](./src/agentServerBridge.ts)**: Manages the RPC connection to the agent server from the extension host and bridges messages to/from webview panels. -- **[clientIO.ts](./src/bridge/clientIO.ts)**: Implements the ClientIO interface that forwards calls to the webview. -- **[chatViewProvider.ts](./src/chatViewProvider.ts)**: Provides the chat webview for the sidebar and helper for editor panels. -- **[extension.ts](./src/extension.ts)**: Contains the activation logic for the extension, setting up commands and keybindings. +These files work together to provide a cohesive experience for interacting with TypeAgent conversations in VS Code. ## How to extend -To extend the `vscode-shell` package, follow these steps: +To extend the functionality of the `vscode-shell` package, follow these steps: + +1. **Understand the Extension Host**: + + - Start by reviewing [agentServerBridge.ts](./src/agentServerBridge.ts) to understand how the WebSocket connection to the agent server is established and how messages are handled. + +2. **Modify the Webview UI**: + + - If you need to change the chat interface, begin with [main.ts](./src/webview/main.ts). This file is the main entry point for the webview and contains the logic for rendering the chat UI. + +3. **Add or Modify Commands**: + + - To introduce new commands or modify existing ones, update [extension.ts](./src/extension.ts). This file is responsible for registering commands and keybindings. + - If the new functionality involves the chat interface, you may also need to update [chatViewProvider.ts](./src/chatViewProvider.ts). + +4. **Test Your Changes**: + + - Use the following commands to build and test your changes: + ```sh + npm run compile + npm run watch + ``` + - To test the extension in VS Code, use the `npm run deploy:local` command to install the updated extension locally. + +5. **Extend Conversation Management**: + + - If you need to add or modify conversation management features, review the `manageConversation` and related methods in [agentServerBridge.ts](./src/agentServerBridge.ts). These methods handle actions like creating, switching, and deleting conversations. -1. **Start with the Extension Host**: Open [agentServerBridge.ts](./src/agentServerBridge.ts) to understand how the WebSocket connection and message handling are implemented. -2. **Modify the Webview UI**: If you need to change the chat interface, start with [main.ts](./src/webview/main.ts). -3. **Add New Commands**: To add new commands or keybindings, modify [extension.ts](./src/extension.ts) and [chatViewProvider.ts](./src/chatViewProvider.ts). -4. **Testing**: Run `npm run compile` and `npm run watch` to build and test your changes. Use `npm run deploy:local` to install the extension locally and verify its functionality in VS Code. +6. **Update the Bridge**: + - For changes related to message routing or request handling, examine [clientIO.ts](./src/bridge/clientIO.ts) and [messages.ts](./src/bridge/messages.ts). These files define the communication protocol between the extension host and the webview. -By following these steps, you can effectively extend the functionality of the `vscode-shell` package to meet your specific needs. +By following these guidelines, you can effectively extend and customize the `vscode-shell` package to suit your needs. Be sure to test your changes thoroughly to ensure compatibility and functionality. ## Reference @@ -115,6 +138,7 @@ Workspace: - [@typeagent/core](../../packages/typeagent-core/README.md) - [@typeagent/dispatcher-rpc](../../packages/dispatcher/rpc/README.md) - [@typeagent/dispatcher-types](../../packages/dispatcher/types/README.md) +- [@typeagent/websocket-utils](../../packages/utils/webSocketUtils/README.md) - [agent-dispatcher](../../packages/dispatcher/dispatcher/README.md) - [chat-ui](../../packages/chat-ui/README.md) @@ -126,6 +150,6 @@ External: `ansi_up`, `debug`, `dompurify`, `isomorphic-ws`, `markdown-it`, `ws` --- -_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 vscode-shell docs:verify-links` to spot-check._ +_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._