Inspect a candidate
Is this package available?
A task needs a utility, and you want to know whether the environment can get it, and in which version, before anything changes.
Illustrative conversation
YouIs curl available here, and what does it depend on?
Tool callapt_search { "pattern": "curl" }
What happensThe matching package names with version, architecture and description; the match is on the name only.
Tool callapt_show { "packages": ["curl"] }
What happensThe candidate's version, architecture and dependency information.
Tool callapt_depends { "package": "curl" }
What happensThe dependency clauses, each with its type, as written in the package.
Agentcurl is available. Its declared dependencies are listed; that is not a computed install plan, so the install result is what shows what is added.
Find the owner
Which package does this file belong to?
A file turned up on the system and you want to know which package it came from.
Illustrative conversation
YouWhich package owns /usr/bin/curl, and which files does that package have?
Tool callapt_search_file { "path": "/usr/bin/curl" }
What happensThe owner is the curl package.
Tool callapt_list_files { "package": "curl" }
What happensThe paths recorded for the package.
Agent/usr/bin/curl belongs to curl according to the package records. I did not scan the disk.
Install
Install what the task needs, and check it
The environment lacks a tool the task needs, and you have allowed installing it.
Illustrative conversation
YouInstall curl, and tell me whether it really works afterwards.
Tool callapt_list { "installed": true, "pattern": "curl" }
What happensNo recorded package matches; existing files and the needed capability still require a baseline check.
Tool callapt_mark_show { "action": "showhold", "packages": ["curl"] }
What happensNo hold is recorded for curl.
Tool callapt_show { "packages": ["curl"] }
What happensThe candidate version and its declared dependencies.
Tool callapt_install { "packages": ["curl"] }
What happensThe outcome lists curl under installed, with any errors and warnings, the requested packages and any removed_for_conflicts.
Tool callapt_status { "package": "curl" }
What happensThe package, version and status Installed.
Agentcurl is recorded as Installed. I will run it once, because a record alone does not prove the program works.
Hold a package
Keep a package where it is
A package must not change during a task, such as a library a build depends on.
Illustrative conversation
YouHold curl at its current version until I say otherwise.
Tool callapt_hold { "package": "curl" }
What happensThe hold is set on the recorded package.
Tool callapt_mark_show { "action": "showhold", "packages": ["curl"] }
What happenscurl is in the list of held packages, with a count of one.
Agentcurl is held. A dependency of another install could still move it, so I will check it after any change.
Inspect an archive
Look inside a package file before you trust it
Someone gave you a package file and you want to know what it is before you use it.
Illustrative conversation
YouWhat is in /downloads/tool.deb, and what does its control file say?
Tool callapt_info { "file": "/downloads/tool.deb" }
What happensThe package's control text and the file path.
Tool callapt_contents { "file": "/downloads/tool.deb" }
What happensThe file paths inside the archive.
AgentThe control file names the package and its version, and the archive holds the listed files. I only read it; nothing was installed, and I cannot tell you it is authentic.
Fetch source
Get a package's source
You want to read how a package is built, or change it.
Illustrative conversation
YouFetch the source of curl into a new directory and unpack it.
Tool callapt_source { "package": "curl", "output_dir": "/work/curl-src", "extract": true }
What happensThe result has the package, version, directory and files, any fetch_warnings, and extracted_to when unpacking worked.
AgentThe source is in /work/curl-src. extracted_to is present, so unpacking completed; with it missing I would have told you it was downloaded only.
Remove
Remove a package, and check what stayed
A package is no longer needed and the task allows removing it.
Illustrative conversation
YouRemove curl, but keep its configuration.
Tool callapt_remove { "packages": ["curl"] }
What happensA results entry for curl with files_removed and the configuration files kept.
Tool callapt_status { "package": "curl" }
What happensThe record shows the package's state after removal, with its configuration files kept.
Agentcurl has a ConfigFiles record after removal. That does not prove every removal script succeeded or the original configuration survived; I still need to compare retained files with the baseline.