pilotctl

Overview ¶

SPDX-License-Identifier: AGPL-3.0-or-later

Call-time "next steps" rendering — the dynamic context an agent sees after EVERY `pilotctl appstore call`, on success and on failure.

The problem: an autonomous agent installs an app and then stops caring. The product demo (appstore_demo.go) addresses the install→first-call step, once. This addresses every call after it: when a call lands, the agent is told the small set of RECOMMENDED commands for where it now stands — the next step in the flow on success, and the specific fix on failure (402 → top up, 401 → signup, missing param → the schema).

Where the data comes from, and why the call path never touches the network ¶

The graph is authored in submission.json beside product_demo and flows verbatim into the catalogue's metadata.json, whose bytes are pinned by metadata_sha256 under the catalogue signature. At install we cache the graph to $APP/next-steps.json (see cacheNextSteps). Every call then resolves against that local file: no fetch, no DNS, no added latency, and it works offline. A call is the hottest path in the app store — it must not grow a network dependency to print a hint.

Trust ¶

The cached bytes came out of the sha-verified metadata.json, so this adds no new trust surface. $APP is already the app's own confined directory holding its signed manifest; a graph is strictly less privileged than the manifest sitting next to it — it produces text, never an action. Nothing here ever executes a recommended command; it prints it for the agent to decide on.

Failure posture ¶

Everything is additive and best-effort, and every entry point is guarded: an absent, unreadable, malformed, future-schema, or simply unmatched graph means the call behaves EXACTLY as it does today. A hint is a nicety; a call is not. Under no circumstances may this file's code turn a working call into a failed one — hence the recover() in renderNextSteps and the silent error drops.