README

AI SPI tool for managing tasks, hierarchies, dependencies, and comments through adachsoft/task-contracts.

The package provides TaskTool, a ready-to-use implementation of the adachsoft/ai-tool-call tool interface, and TaskToolFactory, which wires task and comment services from repository implementations.

Features

AI SPI tool named task.
Task creation, update, status changes, reading, deletion, and tree retrieval.
Task dependency management.
Task comment creation, editing, deletion, listing, and lookup.
Input validation and AI-facing error mapping.
Repository-based storage through adachsoft/task-contracts.
Sandboxed file access for the create_from_file operation.

Installation

composer require adachsoft/task-tool

The package requires:

PHP >= 8.3
adachsoft/ai-tool-call ^2.0
adachsoft/collection ^3.0
adachsoft/task-contracts ^2.0
adachsoft/sandbox-contracts ^0.1
adachsoft/file-tool-security-policy ^1.0
adachsoft/normalized-safe-path ^0.1
psr/clock ^1.0

Usage

TaskToolFactory::withDefaults() is the simplest way to create a factory:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\TaskTool\Tool\TaskToolFactory;

$factory = TaskToolFactory::withDefaults(
    $taskRepository,
    $commentRepository,
);

$tool = $factory->create(new ConfigMap([
    'base_path' => __DIR__ . '/repository',
    'allowed_files' => ['.tasks/*.md', '.tasks/*.txt'],
]));

The repository arguments must implement the interfaces from adachsoft/task-contracts:

AdachSoft\TaskContracts\Interface\TaskRepositoryInterface
AdachSoft\TaskContracts\Interface\CommentRepositoryInterface

For explicit clock configuration, instantiate TaskToolFactory directly with the two repositories and a nullable Psr\Clock\ClockInterface instance.

Configuration

TaskToolFactory::create() requires a non-empty base_path and at least one non-empty allowed_files or allow_extensions list for sandboxed file operations.

Optional file security settings are:

forbidden_files — forbidden normalized relative path patterns.
deny_extensions — denied file extensions without a leading dot.

Optional service settings are:

max_title_length — maximum task title length; default 120.
max_description_length — maximum task description length; default 2000.
max_author_id_length — maximum comment author identifier length; default 200.
max_content_length — maximum comment content length; default 32000.

Supported operations

The tool accepts a JSON object with an operation field. Supported operations are:

create
create_from_file
update
set_status
delete
read
find_tree
add_dependency
remove_dependency
list_dependencies
add_comment
edit_comment
delete_comment
list_comments
find_comment

Operation-specific identifiers use the task-contracts formats, such as task1 for tasks and task1_c1 for comments.

`create_from_file`

create_from_file reads a file relative to the configured sandbox and creates a task from its contents. The path is checked by the configured file security policy before it is read. The operation does not expose the absolute path or sandbox root in its result.

Error handling

TaskTool::callTool() maps invalid input to InvalidToolCallException and domain or execution failures to ToolExecutionException from adachsoft/ai-tool-call.

Mapped domain failures include missing tasks or comments, invalid task data, duplicate entities, missing dependencies, and concurrent modification conflicts.

Testing

Run the complete test suite with:

vendor/bin/phpunit

Static analysis and code quality commands are available through Composer:

composer run stan
composer run rector
composer run cs:check

License

This project is licensed under the MIT License. See the LICENSE file for details.

adachsoft / task-tool

Package info

Security

Statistics