README

SSH Tool is a bridge between AdachSoft AiToolCall and SSH operations. It implements the ToolInterface and uses the Strategy pattern to provide clean, testable SSH actions (login, logout, command execution, account management, etc.).

Features

• Full SSH session management (login/logout)
• Remote command execution with stdout/stderr/exit code handling
• Optional per-call timeout for command execution (in milliseconds)
• Configurable maximum size of returned stdout/stderr (max_output_length) with safe truncation
• Account listing and details retrieval
• Strategy/Command pattern for easy extension
• Strict type safety and comprehensive error handling
• PHPUnit tests (unit + functional)

Installation

composer require adachsoft/ssh-tool

Usage

1. Configuration

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\SshTool\Config\SshToolConfigKeyEnum;

$config = new ConfigMap([
    // Required: JSON repository with SSH accounts
    SshToolConfigKeyEnum::JSON_REPOSITORY_FILE_PATH->value => '/path/to/accounts.json',

    // Required: base URL of the SSH HTTP API used by ssh-gate
    SshToolConfigKeyEnum::SSH_API_BASE_URL->value => 'https://your-ssh-api.example.com',

    // Optional: maximum length of stdout/stderr returned to the LLM (default: 10000)
    SshToolConfigKeyEnum::MAX_OUTPUT_LENGTH->value => 10_000,
]);

2. Registering the Tool

use AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\SshTool\Factory\SshToolFactory;

$facade = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([new SshToolFactory()])
    ->withToolConfigs(['ssh' => $config])
    ->build();

3. Available Actions

The tool supports the following actions via the action parameter:

• login – Authenticates and returns a session token
• logout – Ends an active SSH session
• executeCommand – Runs a command on a remote host
• getAccount – Retrieves details of a specific account
• listAccounts – Lists all configured accounts (without passwords)
• listSessions – Lists active sessions

Example call:

use AdachSoft\AiToolCall\SPI\Collection\KeyValueMap;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallRequestDto;

$result = $facade->callTool(new ToolCallRequestDto(
    'ssh',
    new KeyValueMap([
        'action' => 'executeCommand',
        'sessionToken' => 'abc123',
        'command' => 'ls -la',
        // Optional: timeout in milliseconds
        'timeout' => 5_000,
    ])
));

echo $result->result->get('stdout');

4. Timeout and output truncation

• The optional timeout parameter is validated as a positive integer (in milliseconds) and passed directly to the underlying SshCommandRequest.
• To protect the conversation context, both stdout and stderr are truncated when their length exceeds max_output_length from configuration (default: 10000).
• When truncation happens, a notice is appended to the output:
  • "[Output truncated due to length limit]" for stdout
  • "[Error output truncated due to length limit]" for stderr

Development

Running Tests

# Unit + Functional tests
vendor/bin/phpunit

# Production/end-to-end tests (if available)
vendor/bin/phpunit --group production

Code Quality

vendor/bin/rector process --config=rector.php
vendor/bin/php-cs-fixer fix
vendor/bin/phpstan analyse src tests

Architecture

• SshTool – thin router/delegator
• SshActionInterface + concrete *Action classes – each action is a separate, testable strategy
• SshToolFactory – creates facade and injects actions
• All public documentation is in English per project rules.

License

MIT License – see the LICENSE file for details.

Part of the AdachSoft ecosystem. For more information see adachsoft.com.