bashJobTool function

AgentTool bashJobTool(ShellJobRegistry jobs)

Creates the bash_job tool: inspect and stop the session's background shell jobs (see ShellJobRegistry).

Implementation

AgentTool bashJobTool(ShellJobRegistry jobs) {
  return AgentTool(
    name: 'bash_job',
    label: 'bash job',
    // `stop` kills a process, so the whole tool sits at the write tier
    // (task_send precedent); status/output are plain reads.
    tier: ApprovalTier.write,
    description:
        'Manage background shell jobs (from bash background: true). '
        'Actions: "status" lists running + last 20 exited (all: true = '
        'every job; id = one), "output" tails a log (id, lines), "stop" '
        'kills a running job (id).',
    parameters: const {
      'type': 'object',
      'properties': {
        'action': {
          'type': 'string',
          'enum': ['status', 'output', 'stop'],
          'description': 'What to do with the job(s)',
        },
        'id': {
          'type': 'string',
          'description': 'The job id (e.g. sh-1); required for output/stop',
        },
        'lines': {
          'type': 'number',
          'description': 'Log tail size for output (default 50)',
        },
        'all': {
          'type': 'boolean',
          'description': 'status without id: list every exited job too',
        },
      },
      'required': ['action'],
    },
    execute: (arguments, cancelToken, onUpdate) async {
      final action = arguments['action'] as String;
      final id = arguments['id'] as String?;
      final lines = (arguments['lines'] as num?)?.toInt();
      final all = arguments['all'] as bool? ?? false;
      return switch (action) {
        'status' => _bashJobStatusResult(jobs, id, all: all),
        'output' => await _bashJobOutputResult(jobs, id, lines),
        'stop' => await _bashJobStopResult(jobs, id),
        _ => throw StateError('unknown bash_job action: $action'),
      };
    },
  );
}