agent-failure-modes.md

Agent Failure Modes and Expected Behavior

Stable candidate testing should confirm that failures are clear and safe.

Agent disabled

Expected:

EasyLibrary loads normally
/easyagent is not registered
AgentRuntimeAPI::isAvailable() returns false
consumer plugins can fallback locally

Agent offline or wrong address

Expected:

health/report show connection failure
API calls return false or ok=false instead of crashing
delivery/RPC/compute requests are not silently considered complete

Wrong secret

Expected:

Agent rejects requests
PMMP reports failed ping/request
secret value is not printed in output

Agent restart / stale PubSub cursor

Expected after 0.9.2.2+:

Agent detects stale after_id
pubsub.poll returns cursor_reset metadata
PMMP resets local cursor and receives new events
command/RPC no longer stay waiting due to old cursor IDs

Target server offline

Expected:

target resolution excludes offline/stale servers
delivery record shows pending/expired instead of executed
retry remains manual unless explicitly configured later

RPC timeout

Expected:

rpc status becomes failed/expired after timeout
request_id remains inspectable while retention keeps it
consumer plugin handles missing response

Compute invalid method

Expected:

PHP API rejects methods not in AgentComputeMethods
Agent Go also rejects methods not in allowed_methods
no arbitrary code execution path exists

Compute payload too large

Expected:

Agent returns error
PMMP does not crash
consumer plugin receives ok=false or failed task status

KV/flags expired

Expected:

get returns absent/default-like result after TTL
flag active=false or found=false depending response
listeners should not assume permanent state without refreshing