Cola, programaciones y tareas
Ámbito: SessionRpc (operaciones por sesión vinculadas a una Session) Para una visión general de RPC y la lista de todas las páginas de RPC, consulta RPC.// queue: consultar y gestionar los elementos para el usuario encolados
$pending = $session->rpc()->queue()->pendingItems();
// $pending->items - array de QueuePendingItems
// $pending->items[0]->kind - QueuePendingItemsKind (Command / Message)
$removed = $session->rpc()->queue()->removeMostRecent();
// $removed->removed - si se pudo eliminar el elemento más reciente
$session->rpc()->queue()->clear();
// Insertar un elemento en la posición indicada (position empieza en 0)
use Revolution\Copilot\Types\Rpc\QueueInsertAtRequest;
use Revolution\Copilot\Types\Rpc\QueueInsertMessage;
$queue = $session->rpc()->queue();
$inserted = $queue->insertAt(new QueueInsertAtRequest(
position: 0,
message: new QueueInsertMessage(prompt: 'Review the changes'),
));
// $inserted->id - ID del elemento insertado
$queue->moveItem(['id' => $inserted->id, 'toPosition' => 1]);
$duplicated = $queue->duplicateAt(['id' => $inserted->id]);
$queue->updateText(['id' => $duplicated->id, 'prompt' => 'Review and test the changes']);
$removedAt = $queue->removeAt(['id' => $duplicated->id]);
// $removedAt->removed - si se pudo eliminar el elemento
$sent = $queue->sendNow(['id' => $inserted->id]);
// $sent->steered - si se envió al turno en ejecución
// Pausar el drenado. La pausa no se levanta automáticamente, así que reanúdalo siempre con false
$queue->setDrainPaused(['paused' => true]);
$queue->setDrainPaused(['paused' => false]);
// schedule (experimental: gestión de prompts programados)
$schedule = $session->rpc()->schedule()->list();
// $schedule->entries - array de ScheduleEntry
use Revolution\Copilot\Types\Rpc\ScheduleStopRequest;
$stopped = $session->rpc()->schedule()->stop(new ScheduleStopRequest(id: 1));
// $stopped->stopped - si se detuvo correctamente
// tasks (experimental: gestión de tareas en segundo plano)
// Iniciar una tarea de agente y obtener su ID
use Revolution\Copilot\Types\Rpc\TasksStartAgentRequest;
$result = $session->rpc()->tasks()->startAgent(new TasksStartAgentRequest(
agentType: 'explore',
prompt: 'Search for all TODO comments in the codebase',
name: 'todo-search',
description: 'Find TODO items', // Opcional
model: 'gpt-4o', // Opcional
));
// $result->agentId - ID de la tarea en segundo plano
// Obtener la lista de tareas actual
$list = $session->rpc()->tasks()->list();
// $list->tasks - array de TaskAgentInfo, TaskShellInfo y TaskClientInfo
// Leer de forma incremental con cursor la salida de un shell desacoplado
use Revolution\Copilot\Types\Rpc\TasksReadOutputRequest;
$cursor = null;
do {
$output = $session->rpc()->tasks()->readOutput(new TasksReadOutputRequest(
id: 'shell-1',
cursor: $cursor,
waitMs: 1000,
));
echo $output->text;
$cursor = $output->cursor;
} while ($output->exit === null);
// $output->exit->status - estado de finalización de la tarea
// $output->exit->exitCode - código de salida del proceso (nullable)
// Cada lectura es de 64 KiB como máximo. waitMs vale 0 por defecto, con un máximo de 30000 ms.
// stdout y stderr se combinan. Si el cursor deja de ser válido, vuelve a leer sin cursor.
// Registrar como tarea un trabajo propiedad de la aplicación
use Revolution\Copilot\Types\Rpc\TasksRegisterRequest;
$registered = $session->rpc()->tasks()->register(new TasksRegisterRequest(
clientTaskId: 'import-123',
description: 'Import customer data',
cancellable: true,
displayName: 'Customer import', // Opcional
));
// $registered->task->id - ID de tarea asignado por la CLI
// $registered->created / $registered->reclaimed - estado de creación nueva o recuperación de una tarea huérfana
// Actualizar el progreso de una tarea propiedad del cliente
use Revolution\Copilot\Enums\TaskClientActiveStatus;
use Revolution\Copilot\Enums\TaskClientUpdateKind;
use Revolution\Copilot\Types\Rpc\TaskClientUpdate;
use Revolution\Copilot\Types\Rpc\TasksUpdateRequest;
$updated = $session->rpc()->tasks()->update(new TasksUpdateRequest(
id: $registered->task->id,
sequence: 1,
update: new TaskClientUpdate(
kind: TaskClientUpdateKind::Progress,
status: TaskClientActiveStatus::Running,
phase: 'importing',
percentage: 25,
),
));
// sequence se incrementa en cada actualización
// Informar de la finalización
$completed = $session->rpc()->tasks()->update(new TasksUpdateRequest(
id: $registered->task->id,
sequence: 2,
update: new TaskClientUpdate(
kind: TaskClientUpdateKind::Completed,
result: ['imported' => 100],
),
));
// Obtener el progreso de la tarea (null si no se está siguiendo)
$progress = $session->rpc()->tasks()->getProgress(['id' => $registered->task->id])->progress;
// TaskAgentProgress, TaskClientProgress, TaskShellProgress o null
// Actualizar el estado de los shells desacoplados y esperar a que termine el trabajo en segundo plano
$session->rpc()->tasks()->refresh();
$session->rpc()->tasks()->waitForPending();
// Obtener las tareas que se pueden pasar a segundo plano ahora, o pasarlas inmediatamente a segundo plano
$promotable = $session->rpc()->tasks()->getCurrentPromotable()->task;
$promotedCurrent = $session->rpc()->tasks()->promoteCurrentToBackground()->task;
// Pasar una tarea a modo en segundo plano (deja de esperar de forma síncrona)
use Revolution\Copilot\Types\Rpc\TasksPromoteToBackgroundRequest;
$promoted = $session->rpc()->tasks()->promoteToBackground(
new TasksPromoteToBackgroundRequest(id: $result->agentId)
);
// $promoted->promoted - si el paso tuvo éxito
// Cancelar una tarea
use Revolution\Copilot\Types\Rpc\TasksCancelRequest;
$cancelled = $session->rpc()->tasks()->cancel(
new TasksCancelRequest(id: $result->agentId)
);
// $cancelled->cancelled - si la cancelación tuvo éxito
// Eliminar tareas completadas o canceladas
use Revolution\Copilot\Types\Rpc\TasksRemoveRequest;
$removed = $session->rpc()->tasks()->remove(
new TasksRemoveRequest(id: $result->agentId)
);
// $removed->removed - si la eliminación tuvo éxito
// Enviar un mensaje a una tarea de agente en ejecución (steering)
use Revolution\Copilot\Types\Rpc\TasksSendMessageRequest;
$sent = $session->rpc()->tasks()->sendMessage(
new TasksSendMessageRequest(id: $result->agentId, message: 'Please search other directories too')
);
// $sent->sent - si el mensaje se envió correctamente
// $sent->error - mensaje de error si falla el envío (nullable)
// Interrumpir solo el turno principal y conservar los prompts de la cola para el siguiente turno
use Revolution\Copilot\Types\Rpc\InterruptMainTurnRequest;
$interrupted = $session->rpc()->interruptMainTurn(
new InterruptMainTurnRequest(flushQueued: true)
);
// $interrupted->interrupted - si se pudo interrumpir el turno principal en ejecución
// Cancelar todos los agentes en segundo plano en ejecución sin interrumpir el turno principal
$cancelledCount = $session->rpc()->cancelAllBackgroundAgents();
// Número de agentes cancelados