Extension Install

本 Skill 為 Agenvoy 內部最佳化版本，依 Agenvoy 的執行環境撰寫（run_command 的 CWD、~/.config/agenvoy/skills/.system/ 安裝位置、edit_skill／schedules／find_edit_tool 等工具、subagent 與排程的觸發路徑），不保證適配其他 AI harness。

Extension Installer

Takes a packager-produced tarball, installs it as an extension visible to the runtime scanner.

Input

tarball (optional): absolute path to a tar.gz.

• Provided → skip to §1 and extract the local file (offline / already-downloaded case)
• Missing → run §0 list + pick + download, then proceed to §1

pkg.agenvoy.com is the fixed registry endpoint — it is not a choice, so there is nothing to ask about.

Flow

0. Browse and download from registry (when no tarball)

0.1 GET /list — fetch the catalog

Call http_request:

{
  "url": "https://pkg.agenvoy.com/list?limit=100",
  "method": "GET",
  "content_type": "json"
}

Expect 200 with body {"ok":true,"items":[{...}],"count":N,"limit":100,"offset":0}.

Each item carries name / type / email / version / summary / description / dependence / api_key_name / files / r2_key / size_bytes / sha256 / created_at.

status_code != 200 or items empty → abort with "registry unavailable or no packages".

0.2 ask_user singleSelect to pick a package

Convert items into display strings, one per line:

<item.name>@<item.version> (<item.email>) · <item.type> · <item.summary>

Example: yt_dlp_youtube_downloader@1.0.0 (chiu@example.com) · script · Download a YouTube video...

ask_user (singleSelect):

Pick the extension to install (N total):

options are the display strings. Record the user's chosen item index → extract that item's r2_key / name / email / version.

User cancel → abort.

0.3 GET /download — pull the tar locally

Call download_file (not http_request — binary doesn't belong in a string body):

{
  "url": "https://pkg.agenvoy.com/download?key=<selected item.r2_key>",
  "output_file": "~/.config/agenvoy/download/<name>@<version>.tar.gz",
  "timeout": 300
}

Response: {ok, output_file, size_bytes, sha256, ...}.

Verify the download:

• size_bytes > 0
• If the response carries sha256, compare to the picked item's sha256; mismatch → abort and rm the file
• Any other failure → abort with the error

Use output_file as the tarball variable and proceed to §1.

1. Extract into staging

Fixed staging directory: ~/.config/agenvoy/tools/.extension/.staging/ (cleaned and recreated on every install).

rm -rf ~/.config/agenvoy/tools/.extension/.staging

mkdir -p ~/.config/agenvoy/tools/.extension/.staging

tar -xzf <tarball> -C ~/.config/agenvoy/tools/.extension/.staging

After extraction, the staging directory should contain exactly one subdirectory <original-basename>/ (the packager uses -C <parent> to keep the outer dir in the tarball). run_command: ls ~/.config/agenvoy/tools/.extension/.staging gets <original-basename>.

If extraction fails, or staging contains 0 / >1 subdirectories, abort with:

❌ Tarball contents are invalid (cannot find a single root dir). Verify the tarball was produced by the extension-upload skill.

2. Read and validate manifest.json

read_files: ~/.config/agenvoy/tools/.extension/.staging/<original-basename>/manifest.json

Missing file → abort with "manifest.json missing in tarball, refuse to install".

Validate each field (any failure aborts; a broken manifest is a packager-side defect, so abort and report it):

Every path in files must exist in the staging subdirectory; any missing file → abort.

3. Install system dependencies

For each <dep> in manifest.dependence, call:

pkg_manage(action="install", package="<dep>")

The tool internally:

• exec.LookPath(<dep>) already present → returns already_installed:true, this step is satisfied
• Linux only — probes apt/apt-get/dnf/yum/pacman/apk (first found) and runs sudo -n <pm> install -y <dep>; the sudo ticket comes from the password collected during confirmation
• macOS → the tool is not registered; use run_command(["brew","install","<dep>"], write_paths=["/opt/homebrew"])
• After install, LookPath re-checks

Response is JSON {"ok": true/false, ...}. ok:false or tool error → abort immediately and rm -rf .staging.

Each call triggers a KindToolConfirm popup (AlwaysAllow=false); the user sees "About to run sudo apt install -y ffmpeg — confirm?". User decline → tool fails → skill aborts.

Note: pkg_manage is Linux-only (not registered on macOS) and available on every channel. Root actions go through the same system-password confirmation run_command uses for write_paths, so no terminal is needed.

4. Check and fill keychain keys

For each <KEY> in manifest.api_key_name, call:

store_secret(key="<KEY>", prompt="<extension name> needs <KEY>; enter the value (re-enter to overwrite an existing one):")

store_secret calls keychain.Set internally. User cancels / empty value → tool returns error → skill aborts and removes staging.

Note: Agenvoy has no read-only key check tool, so even an existing key is re-prompted. The user can re-enter the same value or a new one; cancelling (empty) aborts the install.

5. Derive install directory

Directory name (no author/email prefix):

<manifest.name>@<manifest.version>

Examples: yt-dlp-info@1.0.0, yt_dlp_youtube_downloader@1.0.0.

Full install path:

~/.config/agenvoy/tools/.extension/<manifest.type>/<manifest.name>@<manifest.version>/

Never rewrite tool.json::name — keep the value the manifest already carries. The runtime tool registry uses that value as the key.

Collisions (same name + version from two authors) are resolved uniformly in §6 collision check (Overwrite / Rename / Cancel popup).

6. Collision check

Define <final-dir> = <name>@<version> (the default install directory name derived in §5).

ls ~/.config/agenvoy/tools/.extension/<type>/<final-dir> 2>/dev/null

If the directory already exists → ask_user singleSelect:

<final-dir> is already installed.
- Overwrite · remove the old version and install the new one
- Rename · pick a new directory name (keep both on disk)
- Cancel · abort install