README

Tools for safe file read/write operations integrated with adachsoft/ai-tool-call SPI.

Namespaces: AdachSoft\AiFileTool
Tools:
- file_read: read multiple files with extension policy and size limits
- file_write: write multiple files with modes (create_new/overwrite/append)
Global configuration driven at factory time (ConfigMap)
Safe paths (normalized-safe-path) and filesystem operations (adachsoft/filesystem)
Binary support via Base64 with global toggle
Per-file results: ok/status/message/content without mixing content with error messages

Requirements

PHP >= 8.3
ext-mbstring
adachsoft/ai-tool-call 1.0.0
adachsoft/ai-tool-call-plugin >= 0.2.0

Installation

composer require adachsoft/ai-file-tool

Enable the composer plugin discovery in your root project and ensure entry-file points to resources/ai-tool-call.php.

Factories (entry-file)

resources/ai-tool-call.php returns SPI factories for this package:

<?php

declare(strict_types=1);

use AdachSoft\AiFileTool\Factory\FileReadToolFactory;
use AdachSoft\AiFileTool\Factory\FileWriteToolFactory;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

return [
    'factories' => [
        [
            'factory' => FileReadToolFactory::class,
            'config' => new ConfigMap([
                'baseDir' => '.',
                'allowExtensions' => null,
                'denyExtensions' => null,
                'allowBinary' => true,
                'defaultEncoding' => 'text',
                'maxFileSizeBytes' => 65536,
                'allowOverwrite' => false,
                'createDirectories' => true,
            ]),
        ],
        [
            'factory' => FileWriteToolFactory::class,
            'config' => new ConfigMap([
                'baseDir' => '.',
                'allowExtensions' => null,
                'denyExtensions' => null,
                'allowBinary' => true,
                'defaultEncoding' => 'text',
                'maxFileSizeBytes' => 65536,
                'allowOverwrite' => false,
                'createDirectories' => true,
            ]),
        ],
    ],
];

Configuration (global)

See AdachSoft\AiFileTool\Config\FileToolConfigDto for available options. Typical values:

baseDir: "var/data"
allowExtensions: ["md","txt","php"]
denyExtensions: ["php","js"] => final allowed: ["md","txt"]
allowOverwrite: false, createDirectories: true
allowBinary: true, defaultEncoding: "text", maxFileSizeBytes: 65536

Configuration is applied by the factories using ConfigMap when creating the SPI tools.

Parameters & Results

file_read
- parameters: { paths: string[], encoding?: 'text'|'base64' }
- result: { files: [ { path, ok, status, message?, content?, size_bytes? } ] }
file_write
- parameters: { files: [ { path, content, encoding?: 'text'|'base64', mode?: 'create_new'|'overwrite'|'append' } ] }
- result: { files: [ { path, ok, status, message?, bytes_written? } ] }

Note: The public API accepts strings for encoding/mode; internally the library uses enums for strictness.

Notes

All path operations go through normalized-safe-path and AdachSoft FileSystem implementations.
"File not found" as a literal content is not treated as error.
Deny list subtracts from allow list. When allow is null => all allowed except deny.

Versioning

This project is versioned exclusively via Git tags. The composer.json does not contain the version field.

adachsoft / ai-file-tool

Maintainers

Details