Extension Upload

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

Extension Uploader

Packages an Agenvoy script tool directory into a marketplace tarball and uploads it to pkg.agenvoy.com. The source root is fixed at ~/.config/agenvoy/tools/script/. If the user provides a keyword (e.g. yt), only matching subdirectories are listed.

Input

keyword (optional): substring filter (case-insensitive) over subdirectories under ~/.config/agenvoy/tools/script/. Examples: yt, dlp, tts.

• With keyword → list filtered matches
• Without keyword (e.g. plain /extension-upload) → list ALL subdirectories for the user to pick; do not ask for a keyword

0. Select extension_dir (picker)

Fixed source root:

SCRIPT_ROOT=~/.config/agenvoy/tools/script

find_files(mode=list) lists all first-level subdirectories under SCRIPT_ROOT (non-recursive). Skip names starting with . or _.

Branch by input:

Branch by candidate count:

extension_dir is the absolute path <SCRIPT_ROOT>/<basename>, used by every step below.

Note: this skill only packages script tools (fixed type: "script"). Packaging api tools requires a separate skill. The worker does not accept mcp type.

Flow

1. Read the directory

find_files(mode=list, recursive=true) enumerates every file under extension_dir (relative paths).

Collect into raw_files, excluding:

• .DS_Store, Thumbs.db, .git*
• *.tar, *.tar.gz, *.tgz, *.zip
• An existing manifest.json (this skill will regenerate it)

read_files reads (if present):

• tool.json (required — if missing, abort with "tool.json missing in <extension_dir>, refuse to package")
• All script.{js,py,sh} / *.js / *.py / *.sh

1.5 Generic structure check (gate)

Check root-level files under extension_dir. Abort immediately on any violation:

Abort message:

❌ Structure check failed: script.py and script.js cannot coexist (keep only one).

2. Infer type

Fixed type: "script" (this skill only packages tools under ~/.config/agenvoy/tools/script/).

2.5 Type-specific structure check (gate)

For type: script:

Abort message:

❌ Structure check failed: type:script requires script.py or script.js.

2.7 Health check (gate)

Verify the script can be parsed by its interpreter so consumers don't install something that immediately crashes. Any failure aborts and prints the stderr.

Branch on the script file confirmed in §2.5:

• script.py:

  python3 -m py_compile <extension_dir>/script.py

• script.js:

  node --check <extension_dir>/script.js

exit code ≠ 0 → abort:

❌ Health check failed: script cannot be parsed by the interpreter.
<first line of stderr>

Note: only syntax-level. Top-level code is not executed; import errors / runtime errors / missing API keys are not checked. The author must test runtime behavior before packaging.

3. Detect dependence and api_key_name

Dependence (system binary names)

Scan every script file for these patterns to extract binaries:

• JavaScript: spawn("X" / exec("X" / execSync("X" / spawnSync("X"
• Python: subprocess.run(["X" / subprocess.Popen(["X" / os.system("X " / shell=True + "X "
• Shell: the first non-reserved-word token

Exclude:

• Shell builtins: cd, echo, test, [, export, set, shift, pwd, true, false
• Interpreters themselves: node, python, python3, bash, sh, /usr/bin/env
• Tools whitelisted by default: ls, cat, head, tail, mkdir, cp, mv, rm, grep, sed, awk, find, jq, which, date, git (almost always present; not counted as a dependence)

What remains (e.g. yt-dlp, ffmpeg, imagemagick, pandoc, tesseract) is the dependence candidate set.

Api_key_name (keychain key names)

Scan every script file for these patterns to extract key names:

• find-generic-password -s agenvoy -a ([A-Z][A-Z0-9_]*_API_KEY)
• secret-tool lookup service agenvoy account ([A-Z][A-Z0-9_]*_API_KEY)
• process\.env\.([A-Z][A-Z0-9_]*_API_KEY)
• os\.environ\[["']([A-Z][A-Z0-9_]*_API_KEY)["']\]
• os\.environ\.get\(["']([A-Z][A-Z0-9_]*_API_KEY)["']
• \$([A-Z][A-Z0-9_]*_API_KEY) (shell scripts)

Dedupe and sort all hits.

Confirm detection results

Call ask_user. Put the detection list in the detail field (hint-style subtitle); keep question short:

{
  "questions": [
    {
      "question": "Are the detections above correct?",
      "detail": "dependence: [yt-dlp, ffmpeg]\napi_key_name: []",
      "options": ["Yes, continue", "No, let me edit dependence", "No, let me edit api_key_name", "No, edit both"]
    }
  ]
}

detail is multi-line hint text; question is the short prompt. The popup renders detail with hint style (subtitle) and question with bold (title). Never stuff detail content into question — they will render together and become unreadable.

4. Take name and summary from tool.json

tool.json is the source of truth for these fields:

• manifest.name = tool.json::name verbatim
• manifest.summary = first line of tool.json::description, truncated to 120 chars

If either fails §6 validation (name pattern / summary length), §6 handles it with ask_user.

4.5 Ask version

Pre-read <extension_dir>/manifest.json if it exists and use its version as the default; otherwise default to 1.0.0.

ask_user (single free-text):

Enter version (semver `MAJOR.MINOR.PATCH`, e.g. 1.0.0; blank = use default <default>):
default: <existing manifest version or 1.0.0>

Reply handling:

Never treat blank as an error — a deliberate blank means "use default".

5. Get registry email (from config; ask if missing)

read_files("~/.config/agenvoy/config.json") → parse JSON → check email field:

• Non-empty string → use directly, do not re-prompt, jump to §6
• Missing / empty → fall through to §5.1 first-time setup

5.1 First-time setup

ask_user (single free-text):

First publish needs a marketplace registry email (stored in ~/.config/agenvoy/config.json, reused next time):

Validate against ^[^@\s]+@[^@\s]+\.[^@\s]+$:

• Pass → lowercase first, then read_files → edit_file(mode=patch) to persist "email": "<lowercased>" into config.json (worker normalizes to lowercase, client must match)
• Fail → re-prompt; abort after 3 attempts with "email format invalid"
• Blank / cancel → abort with "no email provided, cannot upload"

The entire username / git config user.name chain is gone — marketplace identity uses email only. The manifest uses the email field (not author); its value is the lowercased pure email string.

6. Fill in any missing manifest fields

Assemble the candidate manifest:

{
  "name": "<tool.json::name>",
  "type": "script",
  "version": "<from §4.5>",
  "summary": "<first line of tool.json::description, truncated to 120>",
  "email": "<§5.1/5.2 registry email, lowercased>",
  "dependence": <confirmed in §3>,
  "api_key_name": <confirmed in §3>,
  "files": <raw_files from §1>
}

Validate field by field; any failure triggers ask_user to fix that field:

Re-validate after each fix; only proceed once everything passes.

7. Write manifest.json and package

Fixed output directory: ~/.config/agenvoy/tools/.extension/.package/ — not $HOME/Downloads, not ~/.config/agenvoy/download/, not the current work dir, not the source dir.

Fixed filename format: <name>@<version>.tar.gz (e.g. yt-dlp-info@1.0.0.tar.gz).

edit_file(mode=write):

• Path: <extension_dir>/manifest.json
• Content: the manifest that passed §6 validation, pretty-printed (2-space indent), trailing newline

run_command:

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

tar --no-xattrs -czf ~/.config/agenvoy/tools/.extension/.package/<name>@<version>.tar.gz -C <extension_dir>/.. <basename(extension_dir)>/

Where <basename> is the last segment of extension_dir (e.g. yt_dlp_youtube_downloader).

• --no-xattrs: mandatory. macOS bsdtar tries to read xattrs (e.g. com.apple.quarantine) by default; the sandbox can't read them and prints "Operation not permitted" warnings. Marketplace packages shouldn't carry OS-local metadata anyway.
• -C <parent>: points to the parent so the tarball stores <basename>/<file>... rather than absolute paths.

7.5 Disk verify (gate — the only success check)

run_command returns a merged stdout+stderr string to the LLM. The LLM cannot see the exit code by itself, and must not guess from stderr substrings like "not permitted" / "error" / "warning". tar can print xattr/ACL warnings yet still exit 0 with a valid tarball.

The only reliable check:

ls -l ~/.config/agenvoy/tools/.extension/.package/<name>@<version>.tar.gz

Do not branch on "stderr contains a warning → failure". A tarball on disk = success.

If tar is blocked, tell the user:

⚠️ tar is blocked. Check whether it is listed under denied_command in ~/.agenvoy/config.json.

8. Upload to pkg.agenvoy.com (registry)

Fixed endpoint: https://pkg.agenvoy.com/upload — it is not configurable.

manifest.email is the registration email (pure email string); keep it for the §9 report. read_files <extension_dir>/manifest.json to obtain the full JSON string for fields.manifest below (the worker will JSON.parse(manifest) and re-validate).

8.1 First POST — trigger verification email

Call http_request. All four fields are required (url / method / content_type / body); missing any one of them and the worker returns multipart parse failed:

{
  "url": "https://pkg.agenvoy.com/upload",
  "method": "POST",
  "content_type": "multipart",
  "body": {
    "fields": {
      "manifest": "<full JSON string written in §7>"
    },
    "files": [
      {
        "name": "tar",
        "path": "~/.config/agenvoy/tools/.extension/.package/<name>@<version>.tar.gz",
        "content_type": "application/gzip"
      }
    ]
  }
}

Do not simplify the payload:

• Never omit content_type: "multipart" (defaults to json, worker won't see multipart, fails)
• Never omit body (must contain both fields and files)
• Never put the manifest JSON into files[] (manifest is a text field, goes under fields.manifest)
• Never put tar bytes into fields (tar is binary, goes under files[].path and is read from disk by the handler)

Response is the http_request envelope: {status_code, headers, body}. status_code is the only branching signal — do not guess from the body string.