Search by

adachsoft / task-tool

Arkadiusz Adach

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

Package info

gitlab.com/a.adach/task-tool

Issues

pkg:composer/adachsoft/task-tool

Statistics

Installs: 92

Dependents: 0

Suggesters: 0

Stars: 0

v3.0.0 2026-11-16 05:31 UTC

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.0
  • adachsoft/collection ^3.0
  • adachsoft/task-contracts ^3.0@rc
  • adachsoft/sandbox-contracts ^0.1
  • adachsoft/file-tool-security-policy ^1.0
  • adachsoft/normalized-safe-path ^0.1
  • psr/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:

  1. TaskRepositoryInterface
  2. CommentRepositoryInterface
  3. AttachmentRepositoryInterface
  4. AttachmentContentStorageInterface
  5. TaskTypeDefinitionRepositoryInterface
  6. WorkflowDefinitionRepositoryInterface
  7. RuleEvaluatorInterface
  8. ActorProviderInterface
  9. Optional TaskAuthorizationInterface (defaults to AllowAllTaskAuthorization)
  10. 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.

KeyRequiredDefaultDescription
base_pathYes—Non-empty sandbox root path for file operations.
allowed_filesOne of allowed_files or allow_extensions must be non-empty.Unset (null)List of allowed relative-path glob patterns.
allow_extensionsOne of allowed_files or allow_extensions must be non-empty.Unset (null)List of allowed extensions without leading dots, for example md.
forbidden_filesNoUnset (null)Relative-path glob patterns that are always denied.
deny_extensionsNoUnset (null)Extensions without leading dots that are always denied.
max_title_lengthNo120Maximum task title length.
max_description_lengthNo2000Maximum task description length; also limits text read by create_from_file.
max_content_lengthNo32000Maximum comment content length.
max_attachment_sizeNo10485760 (10 MiB)Maximum uploaded attachment size in bytes.
allowed_attachment_mime_typesNo[] (all MIME types)Allowed attachment MIME types. An empty list allows any MIME type.
max_inline_attachment_bytesNo65536 (64 KiB)Maximum size for returning attachment content inline.
search_default_limitNo50Default 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}.

OperationParametersResult payload
createtitle, 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_filefile_path, title?, type_id?{task_id}; title defaults to the file name.
updateid, 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_statusid, status (workflow status identifier){task: TaskSummary}
deleteid{deleted: true, id}
readid{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_treeroot_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_dependencytask_id, depends_on_task_id{added: true, task_id, depends_on_task_id}
remove_dependencytask_id, depends_on_task_id{removed: true, task_id, depends_on_task_id}
list_dependenciestask_id{task_id, depends_on_task_ids: string[], total}
add_commenttask_id, content{comment: {id, created_at, edited_at}}
edit_commentcomment_id, content{comment: {id, created_at, edited_at}}
delete_commentcomment_id{deleted: true, comment_id}
list_commentstask_id{task_id, comments: Comment[], total}
find_commentcomment_id{comment: Comment or null}
add_checklist_itemtask_id, textChecklistResult
edit_checklist_itemtask_id, item_id, textChecklistResult
set_checklist_item_donetask_id, item_id, done (boolean)ChecklistResult
remove_checklist_itemtask_id, item_idChecklistResult
reorder_checklisttask_id, item_ids (string list in the desired order)ChecklistResult
attach_filetask_id, file_path; file_name?, mime_type?Attachment metadata; file name and MIME type default to the source file name and detected type.
list_attachmentstask_id{attachments: AttachmentMetadata[]}
read_attachmentattachment_id, save_to?Inline: {attachment: AttachmentMetadata, content}; saved: {attachment: AttachmentMetadata, saved_to}.
delete_attachmentattachment_id{deleted: true}
searchquery?; 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_typesNone{task_types: [{id, name, workflow_id}]}
get_workflowExactly 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_path sandbox root. create_from_file and attach_file read files from it; read_attachment writes only when save_to is provided.
  • Normalized paths are checked against the configured file security policy. forbidden_files and deny_extensions override 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_types is unrestricted by default ([]).
  • Inline attachment reads are limited by max_inline_attachment_bytes (64 KiB by default) and only allow text/*, application/json, application/xml, or application/x-yaml. Use save_to for 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_id from task creation and comment creation calls. The host's ActorProviderInterface now supplies the actor; FixedActorProvider is available for a fixed identity.
  • Remove status from create. The workflow assigns its initial status. Use set_status to request a transition; the selected workflow and its transition rules decide whether it is allowed.
  • Update TaskToolFactory construction to provide task, comment, attachment, task-type, and workflow repositories, a rule evaluator, and an actor provider. TaskAuthorizationInterface and ClockInterface are optional trailing arguments; withDefaults() is available when their defaults are appropriate.
  • Remove the max_author_id_length configuration 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, and delete_attachment). Check getDefinition() for the complete current operation schema.

License

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