Added

• Implemented dependency validation and resolution utilities with corresponding unit tests
• Implemented user ownership validation for task linking and copying
• Added assertions for task_tree_id in TaskCreator tests
• Add project URLs for homepage and source in pyproject.toml

Changed

• Standardized parameter names in dependency validation functions and enhanced tests for task inclusion validation
• Updated circular dependency detection function signature and tests for consistency
• Refactored dependency validation and resolution logic for clarity and maintainability
• Remove unused imports from test files
• Update directory structure documentation for clarity and organization
• Simplified 'apflow serve' command usage in documentation

Fixed

• Improved dependency cycle and edge case handling in task linking/copying

Added

• Task Model Enhancements

• Added task_tree_id field to TaskModel for managing task hierarchy and relationships

• Introduced origin_type field to track task origin (own, link, copy, reference, archive)

• Implemented SchemaMigration model to track migration history for schema evolution

• Added has_references flag validation in task creation tests

• Executor Access Control System

• Implemented executor access control via APFLOW_EXTENSIONS environment variable

• Added functions to retrieve allowed executor IDs and filter available executors

• Created new API endpoint (/system/executors) to list available executors with restriction support

• Introduced CLI commands to list executors with various output formats (table, json, yaml)

• Added permission checks in TaskManager to enforce executor access control during task execution

• Comprehensive test coverage for executor permissions and API functionality

• CLI Extension System Enhancements

• Automatic Root Command Detection: All single functions registered via @cli_register are now automatically treated as root commands (e.g., apflow version, apflow server --port 8000)

• Removed root_command parameter - no longer needed

• Functions are always root commands, classes are always groups

• Simplified API: @cli_register(name="hello") creates a root command automatically

• Group Extension Support: Added group parameter to @cli_register decorator for extending existing CLI groups

• Extend custom groups: @cli_register(group="my-group", name="new-command")

• Extend built-in groups: @cli_register(group="tasks", name="custom-action")

• Override subcommands: @cli_register(group="my-group", name="existing", override=True)

• New get_cli_group() Function: Convenient API for accessing and extending CLI groups

• Supports both registered extensions and built-in groups (tasks, config, etc.)

• Usage: group = get_cli_group("my-group"); @group.command() def new_cmd(): ...

• Clear error messages when group doesn't exist

• Improved Override Behavior: Clear distinction between different override scenarios

• name="my-group", override=True - Override entire group

• group="my-group", name="cmd", override=True - Override subcommand in group

• name="my-cmd", override=True - Override root command

• Comprehensive test coverage (8 tests) for all extension scenarios

• CLI Documentation

• Added comprehensive CLI documentation with configuration management guide (cli/configuration.md)

• Created practical usage examples (cli/examples.md)

• Developed detailed CLI usage guide covering installation, modes, and best practices (cli.md)

• Introduced CLI documentation index for improved navigation

• TaskCreator hanldeing different origin types

• Added comprehensive tests for TaskCreator methods handling different origin types:
  from_link, from_copy, from_archive, and from_mixed methods.

• Removed create_task_copy* moethods

• Includes test cases for single tasks, recursive trees, field overrides, dependency handling, and edge cases (error conditions, immutability).

Changed

• TaskCreator Logic Refactoring

• Refactored and clarified the logic for from_link, from_copy, from_archive, and from_mixed methods in TaskCreator.

• Improved type annotations, docstrings, and error handling for all task creation methods.

• Enhanced dependency and subtree validation logic for recursive copy/link/archive operations.

• Improved handling of parent/child relationships and task tree construction.

• Updated internal helper methods for better maintainability and testability.

• Extension Management Refactoring

• Moved executor-related functions from apflow.api.extensions to apflow.core.extensions.manager for better code organization

• Updated import paths across the entire codebase to reflect new structure

• Enhanced TaskManager to load executors dynamically with permission checks

• Improved on-demand extension loading for better performance and security

• Decorator Override Logic

• All decorators.py override logic has been changed to force logic for consistency and clarity across the codebase.

• Task Execution Improvements

• Enhanced task execution logic with improved error handling

• Implemented priority grouping for better task scheduling

• Optimized task tree retrieval using task_tree_id with fallback mechanism

• TaskRepository Refactored

• Refactored task update methods in TaskRepository for improved maintainability and clarity.

• Use the method task_update(self, task_id: str, **kwargs) instead of all update_task_* series functions.

• Refactored TaskModel to TaskModelType and enhanced task creation methods for better type safety and extensibility.

Fixed

• Database Schema Management
• Simplified TaskRepository initialization by removing custom column checks
• Added migration tests to ensure proper schema evolution and idempotent execution
• Improved database schema handling for more reliable operations
• Fixed edge cases in recursive copy/link/archive logic where tasks with external dependencies or disconnected subtrees could cause errors.
• Improved error messages for invalid task trees and dependency cycles.

Added

• Fluent API (TaskBuilder) for streamlined task creation and execution documents

Changed

• Removed tasks command aliases from CLI documentation and implementation

Added

• Distributed core enablement for multi-node orchestration (experimental)
• CLI: implement task history command and add short aliases for all major tasks subcommands:
• list → ls, status → st, cancel → c, watch → w, history → hi
• All aliases are documented and tested
• gRPC executor: support multiple backends and improved channel management

Changed

• Updated gRPC dependencies and test references from grpcio to grpclib

Added

• Standard Installation Profile - New [standard] extra providing recommended feature set
• Combines A2A server, CLI tools, CrewAI, and LLM support in single installation command
• Installation: pip install apflow[standard] or pip install -e ".[standard,dev]" for development
• Simplifies setup for most common use cases without requiring manual feature selection
• Test Infrastructure Improvements
• Fixed event loop conflicts in pytest-asyncio test environment via ThreadPoolExecutor-based async isolation
• New test fixtures: disable_api_for_tests for API gateway testing, run_async helper for sync test context
• All 59 CLI tests now passing without hangs (fixed exit code 130 issues)
• A2A tests excluded by default (added to pytest.ini ignore list since a2a is optional dependency)
• Full test suite stable: 861 tests passing
• Security Enhancement: Token Masking
• Improved token masking in CLI config display from 8-character preview to 3-character preview
• Prevents sensitive words from leaking in masked token display
• Example: "very-secret-token-12345" now masked as "ver..." instead of "very-sec..."

Changed

• Documentation Updates
• Updated README.md to highlight [standard] as recommended installation option
• Updated docs/development/setup.md to recommend [standard,dev] for development environment
• Enhanced installation documentation to explain standard profile benefits
• Improved test documentation with note about A2A tests being optional
• Added detailed [standard] configuration documentation in setup.md
• API Client Enhancement
• APIClient.list_tasks() now supports offset parameter for pagination beyond initial limit

Fixed

• Event Loop Conflict Resolution
• Fixed hangs in async CLI tests by implementing ThreadPoolExecutor-based event loop isolation in conftest.py
• Root cause: run_async_safe() was attempting nested event loop execution in pytest-asyncio context
• Solution: Patched run_async_safe() to use separate thread with independent event loop
• Resolves issue where @pytest.mark.asyncio + runner.invoke() caused tests to hang with exit code 130

TaskBuilder dependency coverage**

• Added tests for TaskBuilder handling multiple dependencies and multi-level dependency chains to prevent regressions when wiring dependent tasks.
• ConfigManager integration validation
• New integration test verifies .env loading and dynamic hook registration work end-to-end via distribute_task_tree.
• CLI → API Gateway Architecture (Priority 2)
• New APIClient class (src/apflow/cli/api_client.py) for CLI to communicate with API server via HTTP
• ConfigManager extended with API configuration: api_server_url, api_auth_token, use_local_db, api_timeout, api_retry_attempts, api_retry_backoff
• APIClient supports exponential backoff retry (configurable attempts and initial backoff)
• APIClient supports auth token injection via Bearer header
• Comprehensive error handling for connection failures, timeouts, and API errors with custom exception types
• Added httpx>=0.27.0 to CLI optional dependencies for HTTP communication
• Integration tests for APIClient initialization, context manager, and ConfigManager API methods (8 tests)
• Enables single source of truth (API) for task data when both CLI and API are running
• Solves DuckDB concurrent write limitation (all writes go through API)
• Foundation for future protocol adapters (GraphQL, MQTT, WebSocket)
• CLI Command Layer Refactoring for API Gateway Integration
• Created api_gateway_helper.py with helper functions for transparent API usage and fallback to local database
• should_use_api(): Check if API is configured
• get_api_client_if_configured(): Async context manager yielding APIClient when configured, None otherwise
• api_with_fallback_decorator(): Try API first, fall back to local database if unavailable
• log_api_usage(): Log whether command is using API or local database
• Refactored CLI task commands to use API gateway when configured:
• tasks list: Supports API via client.list_tasks() with status and user filters
• tasks get: Supports API via client.get_task()
• tasks status: Supports API via client.get_task_status()
• tasks cancel: Supports API via client.cancel_task()
• All commands automatically fall back to local database if API is not configured
• Graceful error handling with warning logs when API unavailable but fallback enabled
• Added property accessors to ConfigManager for convenience: api_server_url, api_auth_token, use_local_db, api_timeout, api_retry_attempts, api_retry_backoff
• Integration tests for CLI API gateway with fallback scenarios (13 tests)
• All existing CLI tests pass without modification (59 tests, backward compatible)
• CLI Configuration Management System with Multi-Location & Separated Secrets
• New apflow config command with 13 subcommands for comprehensive configuration management
• Basic Config: set, get, unset, list, reset - Full CRUD operations with alias support
• Token Management: gen-token, verify-token - Generate and verify JWT tokens with role-based claims
• Quick Setup: init, init-server - Interactive wizard and one-command server setup
• Utilities: path, show-path, edit, validate - Config file management and validation
• Multi-location configuration support:
• Priority 1 (highest): APFLOW_CONFIG_DIR environment variable
• Priority 2: Project-local .data/ directory (if in project with pyproject.toml/.git)
• Priority 3: User-global ~/.aipartnerup/apflow/ (default fallback)
• Separated secrets architecture:
• config.cli.yaml (600 permissions) - Unified configuration (all settings: api_server_url, timeouts, tokens, jwt_secret, etc.)
• Single file with multi-location priority system (project-local and user-global)
• API server can also read from same multi-location config structure
• gen-token --save parameter to save tokens to config.cli.yaml
• Token security: Automatic masking in all outputs, expiry validation, signature verification
• Alias support for convenience: api-server/api-url → api_server_url, api-token/token → admin_auth_token
• apflow config validate checks YAML syntax, API server connectivity, and token validity
• apflow config verify-token displays token details (subject, issuer, expiry, role) with status indicators
• apflow config init provides interactive wizard for first-time setup
• Added PyJWT>=2.8.0 to CLI dependencies for JWT token support
• 19 new tests for config persistence and CLI commands (all passing)

Changed

• Refactor import paths from aipartnerupflow to apflow across test files
• Updated import statements in various test files to reflect the new module structure under apflow.
• Ensured all references to aipartnerupflow are replaced with apflow in test modules related to extensions, including but not limited to:
• crewai
• docker
• generate
• grpc
• http
• llm
• mcp
• ssh
• stdio
• websocket
• Adjusted integration tests to align with the new import paths.

Added

• Hook Execution Context for Database Access

• New get_hook_repository() function allows hooks to access database within task execution context

• New get_hook_session() function provides direct access to database session in hooks

• Hooks now share the same database session/transaction as TaskManager (no need for separate sessions)

• Auto-persistence for task.inputs modifications in pre-hooks (detected and saved automatically)

• Explicit repository methods available for other field modifications (name, priority, status, etc.)

• Thread-safe context isolation using Python's ContextVar (similar to Flask/Celery patterns)

• Added set_hook_context() and clear_hook_context() internal functions for context management

• Exported to public API: aipartnerupflow.get_hook_repository and aipartnerupflow.get_hook_session

• Added comprehensive test coverage (16 tests):

• Hook context basic operations and lifecycle

• Multiple hooks sharing same session instance

• Hooks sharing transaction context and seeing uncommitted changes

• Hooks cooperating via shared session

• Auto-persistence of task.inputs modifications

• Explicit field updates via repository methods

• Database Session Safety Enhancements

• Added flag_modified() calls for all JSON fields (result, inputs, dependencies, params, schemas) to ensure SQLAlchemy detects in-place modifications

• Added db.refresh() after critical status updates to ensure fresh data from database

• Added concurrent execution protection: same task_tree cannot run multiple times simultaneously

• Returns {"status": "already_running"} when attempting concurrent execution of same task tree

• Added 12 new tests for concurrent protection and JSON field persistence

• CLI Extension Decorator (cli_register)

• New @cli_register() decorator for registering CLI extensions, similar to @executor_register()

• Decorator supports name, help, and override parameters

• Auto-derives command name from class name (converts _ to -)

• New get_cli_registry() function to access registered CLI extensions

• CLI extensions are loaded from decorator registry before entry_points discovery

• Added comprehensive test coverage (18 tests) for CLI extension decorators

• Exception Handling Architecture

• New exception hierarchy based on FastAPI/production framework best practices

• ApflowError base exception for all framework-specific errors

• BusinessError for expected user/configuration errors (logged without stack traces)

• ValidationError for input validation failures

• ConfigurationError for missing configuration/dependencies

• SystemError for unexpected system-level errors (logged with stack traces)

• ExecutorError for executor runtime failures

• StorageError for database/storage failures

• Created core/execution/errors.py with comprehensive exception documentation

• Created docs/development/exception-handling-standards.md with implementation guidelines

Changed

• Executor Error Handling Refactoring

• All executors now raise exceptions instead of returning error dictionaries

• Technical exceptions (TimeoutError, ConnectionError, etc.) now propagate naturally to TaskManager

• Executors validate inputs and raise ValidationError or ConfigurationError for expected failures

• Updated executors: DockerExecutor, GrpcExecutor, RestExecutor, SshExecutor, CommandExecutor, LLMExecutor

• TaskManager now catches all exceptions, marks tasks as failed, and logs appropriately based on exception type

• BusinessError logged without stack trace (clean logs), other exceptions logged with full stack trace

• CrewAI Executor/Batch Executor Renaming and Test Fixes

• crewai/crew_manager.py → crewai/crewai_executor.py, with the class name updated to CrewaiExecutor

• crewai/batch_manager.py → crewai/batch_crewai_executor.py, with the class name updated to BatchCrewaiExecutor

• All related test cases (test_crewai_executor.py, test_batch_crewai_executor.py, etc.) have been batch-updated with corrected patch paths, mocks, imports, and class names to align with the new naming

• Resolved AttributeError: module 'aipartnerupflow.extensions.crewai' has no attribute 'crew_manager' and similar test failures caused by the renaming

Added

• LLM Executor Integration

• Added LLMExecutor (llm_executor) for direct LLM interaction via LiteLLM

• Supports unified model parameter for 100+ providers (OpenAI, Anthropic, Gemini, etc.)

• Support for stream=True in inputs or context metadata for Server-Sent Events (SSE)

• Automatic API key handling via LLMKeyConfigManager or environment variables

• Auto-registration via extensions mechanism

• Added [llm] optional dependency including litellm

• CLI: Plugin Mechanism for Extensions

• Added CLIExtension class to facilitate creating CLI subcommands in external projects.

• Implemented dynamic subcommands discovery using Python entry_points (aipartnerupflow.cli_plugins).

• Allows projects like aipartnerupflow-demo to register commands (e.g., apflow users stat) without modifying the core library.

• Supports both full typer.Typer apps and single-command callables as plugins.

• CLI: Improved Task Count Output

• Changed default output format of apflow tasks count from json to table for better terminal readability.

Changed

• CLI: Simplified apflow tasks commands
• apflow tasks count now defaults to providing comprehensive database statistics grouped by status.
• Removed redundant --all and --status flags from count command (database statistics are now the default).
• Renamed apflow tasks all command to apflow tasks list for better alignment with API naming conventions.
• Removed the legacy apflow tasks list command (which only showed running tasks).
• The new apflow tasks list command now lists all tasks from the database with support for filtering and pagination.

Fixed

• Tests: Infrastructure and LLM Integration
• Updated tests/conftest.py to automatically load .env file environment variables at the start of the test session.
• Added auto-registration for LLMExecutor in the test conftest.py fixture.
• Fixed LLMExecutor integration tests to correctly use real API keys from .env when available.

Fixed

• CLI: event-loop handling for async database operations

• Ensured async database sessions and repositories are created and closed inside
  the same event loop to avoid "no running event loop" and "Event loop is closed" errors

• Updated apflow tasks commands to run async work in a safe context

• Added nest_asyncio support for nested event loops in test environments

• Logging: clean CLI output by default

• Default log level for the library is now ERROR to keep CLI output clean

• Support LOG_LEVEL and DEBUG environment variables to override logging when needed

• Debug logs can be enabled with LOG_LEVEL=DEBUG apflow ...

• Extensions registration noise reduced

• Demoted expected registration instantiation messages to DEBUG (no longer printed by default)

• This prevents benign initialization messages from appearing during normal CLI runs

• Miscellaneous

• Added nest_asyncio to CLI optional dependencies to improve compatibility in nested-loop contexts

Fixed

• Documentation Corrections for schemas.method Field

• Clarified that schemas.method is a required field when schemas is provided

• Updated documentation to explicitly state that schemas.method must match an executor ID from the extensions registry

• Fixed all documentation examples to use real executor IDs instead of placeholder values

• Updated examples across all documentation files:

• docs/api/http.md: Replaced generic "executor_id" with concrete IDs like "system_info_executor", "rest_executor", "command_executor"

• docs/getting-started/quick-start.md: Updated all task examples to use valid executor IDs

• docs/guides/cli.md: Fixed CLI command examples with correct executor IDs

• docs/development/design/cli-design.md: Updated design documentation examples

• docs/development/setup.md: Fixed setup guide examples

• Fixed generate_executor.py LLM prompt to correctly instruct LLM to use schemas.method (not name) as executor ID

• Updated task structure examples in LLM prompt to reflect correct usage

• API Endpoint Test Coverage

• Added missing test cases for API endpoints:

• test_jsonrpc_tasks_list: Tests tasks.list endpoint with pagination

• test_jsonrpc_tasks_running_status: Tests tasks.running.status endpoint with array format

• test_jsonrpc_tasks_running_count: Tests tasks.running.count endpoint

• test_jsonrpc_tasks_cancel: Tests tasks.cancel endpoint with array format

• test_jsonrpc_tasks_generate: Tests tasks.generate endpoint for task tree generation

• Fixed test parameter format issues:

• tasks.running.status and tasks.cancel now correctly use task_ids array parameter instead of single task_id

• Tests now expect array responses instead of single object responses

• All API endpoints now have comprehensive test coverage

• CLI Command Test Coverage

• Added test_tasks_watch test cases for tasks watch CLI command

• Uses mock to avoid interactive Live display component issues in automated tests

• Tests parameter validation and basic functionality

• Properly handles error messages in stderr

• API Documentation Completeness

• Added missing response example for tasks.running.status endpoint

• Includes complete response format with all fields (task_id, context_id, status, progress, error, is_running, timestamps)

• Documents error cases (not_found, permission_denied)

• Clarifies that method returns array format even for single task queries

Added

• Comprehensive Documentation Review
• Verified all documentation examples use valid executor IDs
• Ensured all examples are functional and can be parsed correctly
• Validated that all CLI commands have corresponding test cases
• Confirmed API endpoint documentation matches actual implementation