adachsoft / task-tool
AI SPI tool for managing tasks and comments via adachsoft/task-contracts.
Requires
- php: >=8.3
- adachsoft/ai-tool-call: ^2.0
- adachsoft/collection: ^3.0
- adachsoft/file-tool-security-policy: ^1.0
- adachsoft/normalized-safe-path: ^0.1
- adachsoft/sandbox-contracts: ^0.1
- adachsoft/task-contracts: ^3.0
- psr/clock: ^1.0
Requires (Dev)
- adachsoft/php-code-style: ^0.7.1
- adachsoft/rule-evaluator-expression-language: ^0.1
- friendsofphp/php-cs-fixer: ^3.89
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.4
- rector/rector: ^2.3
- symplify/phpstan-rules: ^14.9
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 04:35:43 UTC
README
adachsoft/task-tool exposes the task tool through adachsoft/ai-tool-call. It provides an AI host with a controlled interface for task workflows, hierarchy, dependencies, comments, checklists, search, task types, and file attachments. Persistence and authorization are supplied through adachsoft/task-contracts interfaces.
Requirements
- PHP
>= 8.3 adachsoft/ai-tool-call^2.0adachsoft/collection^3.0adachsoft/task-contracts^3.0@rcadachsoft/sandbox-contracts^0.1adachsoft/file-tool-security-policy^1.0adachsoft/normalized-safe-path^0.1psr/clock^1.0
Installation
composer require adachsoft/task-tool
Host integration
Actor identity
The host implements AdachSoft\TaskTool\Actor\ActorProviderInterface::currentActor(): UserId and supplies the authenticated actor. The model cannot choose or impersonate the actor: mutating operations obtain the author/actor from this provider. Do not include a caller-supplied author_id in create or add_comment; the host supplies the actor. author_id remains available as task data and as a search filter.
AdachSoft\TaskTool\Actor\FixedActorProvider provides one fixed UserId and is suitable for tests or hosts with a single known identity. For a multi-user application, implement ActorProviderInterface using the host's authenticated request/session instead.
Factory and configuration
TaskToolFactory takes these dependencies in order:
TaskRepositoryInterfaceCommentRepositoryInterfaceAttachmentRepositoryInterfaceAttachmentContentStorageInterfaceTaskTypeDefinitionRepositoryInterfaceWorkflowDefinitionRepositoryInterfaceRuleEvaluatorInterfaceActorProviderInterface- Optional
TaskAuthorizationInterface(defaults toAllowAllTaskAuthorization) - Optional
Psr\Clock\ClockInterface(defaults to the task-contracts system clock)
TaskToolFactory::withDefaults() is also available and accepts the first eight dependencies, using the default authorization and clock.
create() takes an AdachSoft\AiToolCall\SPI\Collection\ConfigMap. The sandbox root and an allow-list are required. All supported configuration keys are listed below; omitted optional values use the defaults shown.
| Key | Required | Default | Description |
|---|---|---|---|
base_path | Yes | — | Non-empty sandbox root path for file operations. |
allowed_files | One of allowed_files or allow_extensions must be non-empty. | Unset (null) | List of allowed relative-path glob patterns. |
allow_extensions | One of allowed_files or allow_extensions must be non-empty. | Unset (null) | List of allowed extensions without leading dots, for example md. |
forbidden_files | No | Unset (null) | Relative-path glob patterns that are always denied. |
deny_extensions | No | Unset (null) | Extensions without leading dots that are always denied. |
max_title_length | No | 120 | Maximum task title length. |
max_description_length | No | 2000 | Maximum task description length; also limits text read by create_from_file. |
max_content_length | No | 32000 | Maximum comment content length. |
max_attachment_size | No | 10485760 (10 MiB) | Maximum uploaded attachment size in bytes. |
allowed_attachment_mime_types | No | [] (all MIME types) | Allowed attachment MIME types. An empty list allows any MIME type. |
max_inline_attachment_bytes | No | 65536 (64 KiB) | Maximum size for returning attachment content inline. |
search_default_limit | No | 50 | Default result count for search; must be between 1 and 500. |
An omitted allow-list is disabled; an explicitly empty allow-list denies all paths or extensions for that rule. Forbidden paths and extensions take precedence over their corresponding allow-lists. max_author_id_length is not a supported configuration key in 3.0.
Example
This complete composition example uses the in-memory repositories from task-memory. Replace them with your host's persistent implementations in production. The example is exercised by tests/Functional/ReadmeExampleTest.php.
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\AiToolCall\SPI\Collection\KeyValueMap;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallRequestDto;
use AdachSoft\RuleEvaluatorExpressionLanguage\ExpressionLanguageRuleEvaluatorFactory;
use AdachSoft\TaskContracts\ValueObject\UserId;
use AdachSoft\TaskMemory\Repository\InMemoryAttachmentContentStorage;
use AdachSoft\TaskMemory\Repository\InMemoryAttachmentRepository;
use AdachSoft\TaskMemory\Repository\InMemoryCommentRepository;
use AdachSoft\TaskMemory\Repository\InMemoryTaskRepository;
use AdachSoft\TaskMemory\Repository\InMemoryTaskTypeDefinitionRepository;
use AdachSoft\TaskMemory\Repository\InMemoryWorkflowDefinitionRepository;
use AdachSoft\TaskTool\Actor\FixedActorProvider;
use AdachSoft\TaskTool\Tool\TaskToolFactory;
$taskRepository = new InMemoryTaskRepository();
$commentRepository = new InMemoryCommentRepository();
$attachmentRepository = new InMemoryAttachmentRepository();
$attachmentContentStorage = new InMemoryAttachmentContentStorage();
$taskTypeDefinitionRepository = new InMemoryTaskTypeDefinitionRepository();
$workflowDefinitionRepository = new InMemoryWorkflowDefinitionRepository();
$ruleEvaluator = (new ExpressionLanguageRuleEvaluatorFactory())->createDefault();
$actorProvider = new FixedActorProvider(new UserId('readme-example'));
$taskTool = (new TaskToolFactory(
$taskRepository,
$commentRepository,
$attachmentRepository,
$attachmentContentStorage,
$taskTypeDefinitionRepository,
$workflowDefinitionRepository,
$ruleEvaluator,
$actorProvider,
))->create(new ConfigMap([
'base_path' => __DIR__,
'allow_extensions' => ['md', 'txt'],
]));
$createResult = $taskTool->callTool(new ToolCallRequestDto(
'task',
new KeyValueMap([
'operation' => 'create',
'title' => 'README example task',
'description' => 'Created by the README integration example.',
'type_id' => 'task',
]),
))->result->toArray();
$taskId = $createResult['task']['id'];
$searchResult = $taskTool->callTool(new ToolCallRequestDto(
'task',
new KeyValueMap([
'operation' => 'search',
'query' => 'README example task',
]),
))->result->toArray();
Operations
Requests are objects containing an operation and that operation's parameters. In this table, ? marks optional parameters. A missing parent_id in search means any parent; null means root tasks only.
The compact task result used by create, update, and set_status is TaskSummary = {id, status, type_id, author_id, created_at, edited_at}. Checklist mutations return ChecklistResult = {task_id, checklist: [{id, text, done, position, done_at}], checklist_total, checklist_done}. Attachment metadata is {id, task_id, file_name, mime_type, size, author_id, created_at}.
| Operation | Parameters | Result payload |
|---|---|---|
create | title, description; id?, parent_id? (string or null), depends_on_task_ids? (string list), type_id?, attributes? (scalar-value object), checklist? (non-empty strings) | {task: TaskSummary} |
create_from_file | file_path, title?, type_id? | {task_id}; title defaults to the file name. |
update | id, title?, description?, parent_id? (string or null; null makes it a root task), type_id?, attributes? (merged object), remove_attributes? (string list) | {task: TaskSummary} |
set_status | id, status (workflow status identifier) | {task: TaskSummary} |
delete | id | {deleted: true, id} |
read | id | {task: TaskDetails, comments_count, subtasks_count, attachments_count, checklist_total, checklist_done, available_transitions: [{id, name, category}]}; TaskDetails contains id, title, parent_id, description, status, type_id, author_id, attributes, checklist, created_at, edited_at, deleted_at, and depends_on_task_ids. Checklist entries have id, text, done, position, and done_at. |
find_tree | root_id | {tree: TaskTree or null}; each node is {id, title, parent_id, status, type_id, author_id, created_at, edited_at, deleted_at, depends_on_task_ids, sub_tasks: TaskTree[]}. |
add_dependency | task_id, depends_on_task_id | {added: true, task_id, depends_on_task_id} |
remove_dependency | task_id, depends_on_task_id | {removed: true, task_id, depends_on_task_id} |
list_dependencies | task_id | {task_id, depends_on_task_ids: string[], total} |
add_comment | task_id, content | {comment: {id, created_at, edited_at}} |
edit_comment | comment_id, content | {comment: {id, created_at, edited_at}} |
delete_comment | comment_id | {deleted: true, comment_id} |
list_comments | task_id | {task_id, comments: Comment[], total} |
find_comment | comment_id | {comment: Comment or null} |
add_checklist_item | task_id, text | ChecklistResult |
edit_checklist_item | task_id, item_id, text | ChecklistResult |
set_checklist_item_done | task_id, item_id, done (boolean) | ChecklistResult |
remove_checklist_item | task_id, item_id | ChecklistResult |
reorder_checklist | task_id, item_ids (string list in the desired order) | ChecklistResult |
attach_file | task_id, file_path; file_name?, mime_type? | Attachment metadata; file name and MIME type default to the source file name and detected type. |
list_attachments | task_id | {attachments: AttachmentMetadata[]} |
read_attachment | attachment_id, save_to? | Inline: {attachment: AttachmentMetadata, content}; saved: {attachment: AttachmentMetadata, saved_to}. |
delete_attachment | attachment_id | {deleted: true} |
search | query?; status? (one status ID or list); category? (list of TODO, IN_PROGRESS, BLOCKED, DONE, CANCELLED); type_id? (one ID or list); parent_id?; author_id?; attributes? (exact-match object); sort_by?; sort_dir?; limit?; offset?; include_deleted? | {items: [{id, title, status, category, type_id, parent_id, comments_count}], total, limit, offset, has_more} |
list_task_types | None | {task_types: [{id, name, workflow_id}]} |
get_workflow | Exactly one of type_id or workflow_id | {id, name, initial_status, statuses: [{id, name, category}], transitions: [{from, to, condition}]} |
For search, sort_by is id, created_at, edited_at, or title; sort_dir is asc or desc; limit is 1–500 and defaults to search_default_limit; offset defaults to 0; and include_deleted defaults to false. Query text matches task titles and descriptions. status filters by workflow status IDs, while category filters by the status categories listed above. Search results are compact; use read for descriptions and full task data.
Comment is {id, task_id, author_id, content, created_at, edited_at, deleted_at}. find_tree returns lightweight recursive nodes without descriptions, attributes, or checklist details. create and add_comment derive authorship from the host actor; do not send author_id. Task status is assigned from the selected workflow on creation, not from a create parameter.
Security
- File paths are relative to the required
base_pathsandbox root.create_from_fileandattach_fileread files from it;read_attachmentwrites only whensave_tois provided. - Normalized paths are checked against the configured file security policy.
forbidden_filesanddeny_extensionsoverride the corresponding allow-lists. If both path and extension allow-lists are configured, a file must satisfy both. - Resolved paths are checked against the real sandbox root. Symlinks that resolve outside the sandbox, including symlinks in an existing parent path, are rejected.
- Attachments are limited by
max_attachment_size(10 MiB by default);allowed_attachment_mime_typesis unrestricted by default ([]). - Inline attachment reads are limited by
max_inline_attachment_bytes(64 KiB by default) and only allowtext/*,application/json,application/xml, orapplication/x-yaml. Usesave_tofor other MIME types or larger files. The destination must be a new path inside the sandbox and pass the same file policy; existing files are not overwritten.
Error mapping
TaskTool::callTool() maps rejected calls to AdachSoft\AiToolCall\SPI\Exception\InvalidToolCallException. This includes missing or invalid parameters, unknown operations, denied access, invalid task data, file-policy rejection, and status transitions that the workflow does not permit.
AdachSoft\AiToolCall\SPI\Exception\ToolExecutionException represents execution failures such as missing entities, concurrency conflicts, and unexpected failures. A concurrency conflict includes a hint to read the task again and retry. Lookup operations that define nullable results, such as find_tree and find_comment, return null in their result instead of raising a not-found error.
Upgrading from 2.x
- Remove
author_idfrom task creation and comment creation calls. The host'sActorProviderInterfacenow supplies the actor;FixedActorProvideris available for a fixed identity. - Remove
statusfromcreate. The workflow assigns its initial status. Useset_statusto request a transition; the selected workflow and its transition rules decide whether it is allowed. - Update
TaskToolFactoryconstruction to provide task, comment, attachment, task-type, and workflow repositories, a rule evaluator, and an actor provider.TaskAuthorizationInterfaceandClockInterfaceare optional trailing arguments;withDefaults()is available when their defaults are appropriate. - Remove the
max_author_id_lengthconfiguration entry. It is no longer used. - New operations include task search and workflow/type discovery, checklist management, and attachment management (
attach_file,list_attachments,read_attachment, anddelete_attachment). CheckgetDefinition()for the complete current operation schema.
License
This project is licensed under the MIT License. See the LICENSE file for details.