README

AI SPI tool for managing tasks and comments via adachsoft/task-contracts.

This library provides a ready-to-use AI tool implementation (TaskTool) and a corresponding factory (TaskToolFactory) that expose a task tracker over the adachsoft/ai-tool-call SPI.

It is designed to be plugged into an AI agent so that the agent can create, read, update and delete tasks, manage hierarchies and dependencies, and work with task comments in a structured, validated way.

Features

• AI SPI Tool (TaskTool) compatible with adachsoft/ai-tool-call.
• Full CRUD for tasks:
  • create, update, delete, read, find by ID.
• Hierarchical task management:
  • parent/child relationship, tree retrieval (find_tree), listing tasks (list).
• Dependency management between tasks:
  • add/remove dependencies, list dependencies for a task.
• Comments on tasks:
  • add, edit, delete, list comments, find single comment.
• Strong input validation with clear error messages for invalid operations.
• Pluggable storage via adachsoft/task-contracts interfaces.
• Convenience factory for JSON-file based storage (withJsonFile).

Installation

composer require adachsoft/task-tool

By default this package requires:

• PHP >= 8.3
• adachsoft/ai-tool-call ^2.0
• adachsoft/collection ^3.0
• adachsoft/task-contracts ^1.0
• psr/clock ^1.0

Architecture overview

The main entrypoint for AI systems is the TaskTool class:

• Namespace: AdachSoft\TaskTool\Tool\TaskTool
• Implements: AdachSoft\AiToolCall\SPI\ToolInterface
• Tool name: task
• Tags: task, tracker

TaskTool is not meant to be instantiated directly. Instead, you should use the TaskToolFactory, which wires the dependencies and handlers.

Storage abstraction

This library does not dictate where your tasks are stored. Instead it relies on adachsoft/task-contracts:

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

Any implementation of these interfaces can be used (database, files, in-memory, etc.).

Additionally, if you install adachsoft/task-json-file, you can use a simple JSON-file based storage via TaskToolFactory::withJsonFile().

TaskToolFactory

Namespace: AdachSoft\TaskTool\Tool\TaskToolFactory

The factory conforms to AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface and is responsible for creating configured instances of TaskTool.

Constructor

public function __construct(
    TaskRepositoryInterface $taskRepository,
    CommentRepositoryInterface $commentRepository,
    TaskIdGeneratorInterface $taskIdGenerator,
    CommentIdGeneratorInterface $commentIdGenerator,
    ClockInterface $clock,
)

Use this when you want full control over all collaborators:

• TaskRepositoryInterface and CommentRepositoryInterface – your storage implementation.
• TaskIdGeneratorInterface and CommentIdGeneratorInterface – how IDs for tasks/comments are generated.
• ClockInterface – PSR clock used for timestamps.

withDefaults()

public static function withDefaults(
    TaskRepositoryInterface $taskRepository,
    CommentRepositoryInterface $commentRepository,
): self

Creates a factory with default implementations of ID generators and clock:

• SequentialTaskIdGenerator
• SequentialCommentIdGenerator
• DefaultClock

You provide only the repositories; everything else is wired automatically.

withJsonFile()

public static function withJsonFile(string $filePath): self

Creates a factory configured to use JSON file–based repositories (from adachsoft/task-json-file):

• JsonTaskRepository($filePath)
• JsonCommentRepository($filePath)

Requirements and behaviour:

• $filePath must be a non-empty string.
• If adachsoft/task-json-file is not installed or not autoloadable, a ToolConfigurationException is thrown.

This is the quickest way to start using the tool in experiments or simple setups.

Creating the tool instance

TaskToolFactory implements getToolClass() and create(ConfigMap $config): ToolInterface.

Typical usage with adachsoft/ai-tool-call might look like:

use AdachSoft\TaskJsonFile\Repository\JsonTaskRepository;
use AdachSoft\TaskJsonFile\Repository\JsonCommentRepository;
use AdachSoft\TaskTool\Tool\TaskToolFactory;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

$factory = TaskToolFactory::withJsonFile(__DIR__ . '/tasks.json');

$tool = $factory->create(new ConfigMap([
    // Optional configuration keys
    'max_description_length' => 2000,
    'max_author_id_length'   => 200,
    'max_content_length'     => 32000,
]));

// $tool is an instance of AdachSoft\TaskTool\Tool\TaskTool

Configuration keys (all optional):

• max_description_length – maximum length for task description (default: 2000).
• max_author_id_length – maximum length for comment author_id (default: 200).
• max_content_length – maximum length for comment content (default: 32000).

Tool definition

TaskTool::getDefinition() describes the tool for the AI layer.

• Tool name: task
• Description: Manage tasks and their comments: CRUD, hierarchy, dependencies, status transitions, comments.
• Streaming: enabled (return type is streaming-capable in ai-tool-call).

Parameters schema

The tool expects a JSON object as parameters. The only required field for all calls is:

• operation – string, one of the supported operation names.

Other fields are required or optional depending on the operation.

Common

• operation (string, required) – operation to perform. Must be one of the values from OperationEnum:
  • create
  • update
  • set_status
  • delete
  • find
  • read
  • find_tree
  • list
  • add_dependency
  • remove_dependency
  • list_dependencies
  • add_comment
  • edit_comment
  • delete_comment
  • list_comments
  • find_comment

Task fields

• id (string) – Task ID (task<number>, e.g. task1). Required for: update, set_status, delete, find.
• root_id (string) – Root task ID (task<number>). Used for: find_tree.
• parent_id (string|null) – Parent task ID (task<number>) or null for root tasks. Used in: create, update, list.
• title (string) – Task title (max 120 characters). Required for: create. Optional for: update.
• description (string) – Task description. Required for: create. Optional for: update.
• status (string) – Task status. Required for: set_status. Optional for: create.
  • Values come from AdachSoft\TaskContracts\Enum\TaskStatusEnum (e.g. todo, in_progress, done, depending on that enum definition).
• depends_on_task_ids (string[]) – List of task IDs this task depends on. Optional for: create.

Dependency fields

• task_id (string) – Task ID (task<number>). Required for: add_dependency, remove_dependency, list_dependencies, add_comment, list_comments.
• depends_on_task_id (string) – Dependency task ID (task<number>). Required for: add_dependency, remove_dependency.

Comment fields

• comment_id (string) – Comment ID (task<number>_c<number>). Required for: edit_comment, delete_comment, find_comment.
• author_id (string) – Author identifier. Required for: add_comment.
• content (string) – Comment content. Required for: add_comment, edit_comment.

List scope

• scope (string) – Optional filter for list operation.
  • Allowed value: "all".
  • When set to "all", returns every task (root + sub-tasks).
  • Cannot be combined with parent_id.
  • When omitted, list returns only root tasks (parent_id === null) unless parent_id is provided, in which case sub-tasks of that specific parent are listed.

Operations overview

Below is a conceptual overview. Refer to the tests for detailed payload shapes.

create

Create a new task.

Required parameters:

• operation: "create"
• title: string
• description: string

Optional:

• parent_id: string|null
• depends_on_task_ids: string[]
• status: string (task status enum)

update

Update an existing task (title/description/parent/dependencies/status, depending on implementation).

Required parameters:

• operation: "update"
• id: string (task ID)

Optional:

• Any subset of: title, description, parent_id, depends_on_task_ids, status.

set_status

Update the status of a task.

Required parameters:

• operation: "set_status"
• id: string
• status: string (value from TaskStatusEnum).

delete

Delete a task.

Required parameters:

• operation: "delete"
• id: string

find

Find a task by ID.

Required parameters:

• operation: "find"
• id: string

read

Read a single task (usually including detailed fields; see tests).

Required parameters:

• operation: "read"
• id: string

find_tree

Retrieve a task and its sub-tree.

Required parameters:

• operation: "find_tree"
• root_id: string

list

List tasks.

Typical modes:

• Only root tasks:
  • operation: "list"
  • no parent_id, no scope
• Sub-tasks of a given parent:
  • operation: "list"
  • parent_id: string
• All tasks (root + sub-tasks):
  • operation: "list"
  • scope: "all" (must not combine with parent_id).

add_dependency

Add a dependency to a task.

Required parameters:

• operation: "add_dependency"
• task_id: string
• depends_on_task_id: string

Typical errors:

• DependencyAlreadyExistsException – if the dependency is already present.

remove_dependency

Remove a dependency from a task.

Required parameters:

• operation: "remove_dependency"
• task_id: string
• depends_on_task_id: string

Typical errors:

• DependencyNotFoundException – if the dependency is not present.

list_dependencies

List dependencies for a task.

Required parameters:

• operation: "list_dependencies"
• task_id: string

add_comment

Add a comment to a task.

Required parameters:

• operation: "add_comment"
• task_id: string
• author_id: string
• content: string

Typical errors:

• TaskNotFoundException – if the task does not exist.

edit_comment

Edit an existing comment.

Required parameters:

• operation: "edit_comment"
• comment_id: string
• content: string

Typical errors:

• CommentNotFoundException – if the comment does not exist.

delete_comment

Delete a comment.

Required parameters:

• operation: "delete_comment"
• comment_id: string

list_comments

List comments for a task.

Required parameters:

• operation: "list_comments"
• task_id: string

find_comment

Find a comment by ID.

Required parameters:

• operation: "find_comment"
• comment_id: string

Error handling

TaskTool::callTool() converts domain and validation errors into AI-facing exceptions defined in adachsoft/ai-tool-call:

• InvalidToolCallException – for invalid input or unsupported operation values.
• ToolExecutionException – for domain-level failures or unexpected runtime exceptions.

Examples of domain exceptions that are mapped:

• TaskNotFoundException
• CommentNotFoundException
• DependencyNotFoundException
• DependencyAlreadyExistsException
• InvalidTaskOperationException
• UnknownOperationException

Any other unexpected Throwable is wrapped as a ToolExecutionException with a generic message: "Unexpected error during task operation.".

Testing

The repository contains extensive tests:

• Unit tests for internal components and handlers.
• Functional and smoke tests for the TaskTool itself.

Run all tests with:

vendor/bin/phpunit

License

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