Module completions 

agent-exec v0.1 — core library

Provides JSON output types, job-directory management, and the implementation of the sub-commands: create, run, start, status, tail, wait, kill, list, schema, install-skills, and completions. Dynamic shell completion support for job ID arguments.

API choice

Uses clap_complete’s unstable-dynamic engine with ArgValueCompleter. Each job-ID argument is annotated with a context-specific completer function. At runtime, when the shell calls the binary with COMPLETE=<shell> set, CompleteEnv::complete() intercepts the invocation and returns candidates.

Root resolution

Completers use resolve_root(None) as the primary path, which respects the AGENT_EXEC_ROOT environment variable. For --root flag awareness, resolve_root_for_completion additionally parses COMP_LINE / COMP_WORDS (bash) and _CLAP_COMPLETE_ARGS to extract a --root value when present.

Resilience

All completers are best-effort: if the root is unreadable, if state.json is missing or malformed, or if any directory entry fails to read, the offending entry is silently skipped and the remaining candidates are returned.

Functions

complete_all_jobs

Complete all job IDs regardless of state. Used by: status, tail, tag set, notify set.

complete_created_jobs

Complete only jobs in created state. Used by: start (only un-started jobs can be started).

complete_running_jobs

Complete only jobs in running state. Used by: kill (only running jobs can be killed).

complete_terminal_jobs

Complete only jobs in terminal states (exited, killed, failed). Used by: delete (only finished jobs can be deleted).

complete_waitable_jobs

Complete jobs in non-terminal states (created, running). Used by: wait (waiting on a terminal job is a no-op).

list_job_candidates

List completion candidates under root, optionally filtered by job state.

resolve_root_for_completion

Resolve the root directory to use during a completion invocation.