PacketAgentDocs

Operate Worker runs#

PacketAgent records run status, events, checkpoints, provider usage, attention requests, notifications, and artifacts. Use those records to distinguish a queued run, a paused approval, a provider failure, and a terminal result.

Before you start#

  • Confirm readiness and store backups.
  • Assign an operator for approvals and dead-letter recovery.
  • Configure scheduler leadership when more than one instance is running.
  • Decide retention periods for prompts, tool payloads, summaries, and artifacts.

Watch a run#

Open the run detail and read, in order:

  1. current status and terminal reason;
  2. attention or approval state;
  3. event stream and latest checkpoint;
  4. provider usage and budget counters;
  5. artifacts and notification deliveries.

Use the event stream for live progress and the stored summary for later review. Do not treat a disconnected browser stream as proof that the Worker stopped.

Configure notifications#

Define notification routes on the Worker version, then verify delivery for each terminal event the operator needs. Webhook delivery should use HTTPS and a dedicated secret. Failed deliveries retry and eventually enter a dead-letter state that requires an operator decision.

Back up and retain data#

Back up the selected store together with generated applications, published applications, and artifacts. Pause writes or use the database-native consistent backup mechanism. Test restoration to an isolated installation.

Retention jobs are opt-in. Start with dry-run output, review the candidate counts, then enable deletion during a quiet window.

Recover a failed run#

  1. Preserve the run record and external side-effect evidence.
  2. Identify the latest safe checkpoint.
  3. Confirm whether any tool call reached an external system.
  4. Retry only when the trigger and tool operations are safe to repeat.
  5. Otherwise create a new run with a new deduplication identifier and a clear handoff note.

Verify#

  • A controlled run appears in live events and stored history.
  • A test approval reaches the assigned operator.
  • A test notification is delivered and recorded.
  • A failed notification can be redriven.
  • A backup restores into an isolated instance and passes readiness.
  • The retention dry run reports only data older than the intended horizon.

If it does not work#

Symptom Check Recovery
A run cannot be recovered Whether its state survived the failure See Common failures
Notifications never arrive The channel independently of the run A completed run with no notification is a notification fault
Storage fills faster than retention frees it The retention setting against actual volume See Check health and storage
A backup restores but runs will not resume Whether the worker version matches Restore the matching version before resuming work