Skill: chinasilva/skill-hub-gateway (version 2.4.2)

--- name: skill-hub-gateway description: Unified gateway skill for async execute/poll, portal user closure, and telemetry feedback workflows. version: 2.4.2 metadata: openclaw: skillKey: skill-hub-gateway emoji: "🧩" homepage: https://gateway.binaryworks.app requires: bins: - node --- # Skill Hub Gateway Default API base URL: `https://gateway-api.binaryworks.app` Default site base URL (for upload route): `https://gateway.binaryworks.app` Chinese documentation: `SKILL.zh-CN.md` ## Version Check Protocol (Agent) - Official latest version source: `GET /skills/manifest.json` -> `data.version`. - Local current version source: this installed `SKILL.md` frontmatter `version`. - Compare versions using semantic version order (`major.minor.patch`). - Check timing: once at session start, then at most once every 24 hours within the same session. - If version check fails (network/timeout/parse error), do not block runtime execution. Continue current workflow and retry at the next allowed check window. ## Agent Decision Flow - If `latest_version > current_version`, read the matching section under `Release Notes` in this document to build `update_summary`. - Agent should show the user: - `current_version` - `latest_version` - `update_summary` - User decision options: - `Update now` - `Remind me later in this session` - If user chooses `Remind me later in this session`, suppress repeated prompts for the same target version until a new session starts. ## First-Time Onboarding (install_code) Scripts auto-complete onboarding by default: 1. `POST /agent/install-code/issue` with `{"channel":"local"}` or `{"channel":"clawhub"}`. 2. Read `data.install_code`. 3. `POST /agent/bootstrap` with `{"agent_uid":"<agent_uid>","install_code":"<install_code>"}`. 4. Read `data.api_key`, then call runtime APIs with `X-API-Key` or `Authorization: Bearer <api_key>`. Manual override: - You can still provide `api_key` explicitly. - If `agent_uid` and `owner_uid_hint` are omitted, scripts derive stable local defaults from the current workspace path. ## Legacy Runtime Contract (Compatibility) - Execute: `POST /skill/execute` - Poll: `GET /skill/runs/:run_id` ## Portal Actions (User Closure) Action catalog (single default path per action): - `portal.me` -> `GET /user/me` - `portal.balance` -> `GET /user/points/balance` - `portal.ledger.query` -> `GET /user/points/ledger` - `portal.usage.query` -> `GET /user/usage` - `portal.skill.execute` -> `POST /user/skills/execute` - `portal.skill.poll` -> `GET /user/skills/runs/:runId` - `portal.skill.presentation` -> `GET /user/skills/runs/:runId/presentation` - `portal.voucher.redeem` -> `POST /user/vouchers/redeem` (write) - `portal.recharge.create` -> `POST /user/recharge/orders` (write) - `portal.recharge.get` -> `GET /user/recharge/orders/:orderId` Write safety gate: - `portal.voucher.redeem` and `portal.recharge.create` require `payload.confirm === true`. - If `confirm` is missing or not `true`, action runner rejects the call locally and does not send write traffic. ## Payload Contract Default payload conventions: - `payload.input` is the primary input object for `portal.skill.execute`. - `payload.request_id` is optional and passed through as-is. - Query actions use `payload` fields directly as query params (`date_from`, `date_to`, `service_id`, `channel`). Media normalization conventions: - Prefer explicit URL fields already present in input: `image_url`, `audio_url`, `file_url`. - If `attachment.url` exists, map it to the capability target URL field. - If `file_path` exists, auto-upload through `{site_base}/api/blob/upload`, with fallback to `{site_base}/api/blob/upload-file` when `@vercel/blob/client` is unavailable, then backfill URL into input before execution. - For agent runtimes that do not include `@vercel/blob/client`, you can also pre-upload media via your backend (for example Vercel Blob) and pass `attachment.url` or explicit URL fields. - `site_base_url` is a guarded field: runtime only accepts the trusted configured site base URL (default `https://gateway.binaryworks.app` or env `SKILL_SITE_BASE_URL`). - Users should not need to manually paste media URLs in normal product flows. Presentation files: - `portal.skill.presentation` accepts optional `include_files=true` to return `visual.files.assets` with rendered file URLs. - `portal-action.mjs` defaults `include_files=true` for `portal.skill.presentation` unless explicitly disabled. - Image runs return `overlay` (boxed image), plus `mask` / `cutout` assets when available. - Audio runs normalize data URLs to `output.media_files.assets` with uploaded file URLs when blob storage is configured. ## Runtime Auth Bridge User-scoped actions use a fixed auth bridge: 1. Resolve runtime API key context (`api_key`, `agent_uid`, `owner_uid_hint`, `base_url`). 2. `GET /agent/me` with `X-API-Key` + `x-agent-uid` to resolve `user_id`. 3. `POST /user/api-key-login` with `user_id + api_key` to obtain `userToken`. 4. Execute Portal Action with `Authorization: Bearer <userToken>`. ## Insufficient Points Recovery For `POINTS_INSUFFICIENT` responses: - Keep `error.code` and `error.message` unchanged. - Preserve and surface `error.details.recharge_url` when available. - Diagnostic logs should recommend `portal.recharge.create` or direct open of `recharge_url`. ## Bundled Files - `scripts/execute.mjs` (CLI args: `[api_key] [capability] [input_payload] [base_url] [agent_uid] [owner_uid_hint]`) - `scripts/poll.mjs` (CLI args: `[api_key] <run_id> [base_url] [agent_uid] [owner_uid_hint]`) - `scripts/feedback.mjs` (CLI args: `[api_key] [payload_json] [base_url] [agent_uid] [owner_uid_hint]`) - `scripts/telemetry.mjs` (shared best-effort telemetry helper) - `scripts/runtime-auth.mjs` (shared auto-bootstrap helper) - `scripts/portal-auth.mjs` (api-key -> user session bridge) - `scripts/portal-action.mjs` (CLI args: `[api_key] <action> <payload_json> [base_url] [agent_uid] [owner_uid_hint]`) - `scripts/attachment-normalize.mjs` (attachment URL/path normalization + upload) - `references/capabilities.json` - `references/openapi.json` - `SKILL.zh-CN.md` ## Telemetry and Feedback - Bundled scripts now support best-effort telemetry emit for auth/execute/poll/feedback flows. - Telemetry is non-blocking and does not change runtime exit semantics if telemetry delivery fails. - Optional environment variables: - `SKILL_TELEMETRY_ENABLED` (`true` by default) - `SKILL_TELEMETRY_BASE_URL` (defaults to runtime `base_url`) - `SKILL_TELEMETRY_TIMEOUT_MS` (`2000` by default) - Feedback script posts to `POST /feedback/submit` with runtime auth (`X-API-Key`) and attaches `agent_uid` + `owner_uid_hint` in metadata. ## Capability IDs - `human_detect` - `image_tagging` - `tts_report` - `embeddings` - `reranker` - `asr` - `tts_low_cost` - `markdown_convert` - `face-detect` - `person-detect` - `hand-detect` - `body-keypoints-2d` - `body-contour-63pt` - `face-keypoints-106pt` - `head-pose` - `face-feature-classification` - `face-action-classification` - `face-image-quality` - `face-emotion-recognition` - `face-physical-attributes` - `face-social-attributes` - `political-figure-recognition` - `designated-person-recognition` - `exhibit-image-recognition` - `person-instance-segmentation` - `person-semantic-segmentation` - `concert-cutout` - `full-body-matting` - `head-matting` - `product-cutout` ## Release Notes When publishing a new version, add a new section here. Agent update summaries must be generated from this block. ### 2.4.2 (2026-03-12) **What's New** - Added `/api/blob/upload-file` direct-upload fallback for `file_path` flows when `@vercel/blob/client` is unavailable. - Added `portal.skill.presentation` file rendering (`visual.files.assets`) for overlay/mask/cutout URLs. - Added audio output normalization to return `output.media_files.assets` with uploaded file URLs when blob storage is configured. **Breaking/Behavior Changes** - None. **Migration Notes** - For agent runtimes without `@vercel/blob/client`, send `file_path` as before; the runtime now falls back to direct upload. - To receive rendered files, call `portal.skill.presentation` with `include_files=true` or rely on the portal default. ### 2.4.1 (2026-03-12) **What's New** - Added server-side `portal.skill.execute` input normalization for `attachment.url` (both `input.attachment.url` and top-level `attachment.url`). - Added explicit media URL precedence guard (`image_url`/`audio_url`/`file_url` take priority over `attachment.url` when both are present). - Added end-to-end tests for upload-first execution payload compatibility and precedence behavior. - Clarified fallback guidance for runtimes missing `@vercel/blob/client` to use backend pre-upload URLs. **Breaking/Behavior Changes** - None. **Migration Notes** - Existing `portal-action.mjs` workflows remain compatible. - For local file workflows in constrained agent runtimes, prefer backend pre-upload then pass `attachment.url` or explicit media URL. ### 2.4.0 (2026-03-12) **What's New** - Added Portal Actions contract for single-skill user closure flows (`portal.me`, balance/ledger/usage, execute/poll/presentation, voucher and recharge actions). - Added local double-confirm write gate: `portal.voucher.redeem` and `portal.recharge.create` require `confirm=true`. - Added runtime auth bridge script (`portal-auth.mjs`) for `api_key -> user session`. - Added action runner (`portal-action.mjs`) and attachment normalization script (`attachment-normalize.mjs`) with `attachment.url` and `file_path` support. - Standardized insufficient-points diagnostics to preserve `recharge_url` in passthrough envelopes. **Breaking/Behavior Changes** - Write actions now fail fast locally when `confirm=true` is absent. **Migration Notes** - Existing `execute.mjs` and `poll.mjs` workflows remain available. - Portal users should call `portal-action.mjs` for user closure actions. ### 2.3.4 (2026-03-11) **What's New** - Added best-effort telemetry emit in runtime scripts for auth/execute/poll flows. - Added `scripts/feedback.mjs` to submit structured feedback via runtime auth (`X-API-Key`). - Added shared telemetry helper with optional env controls (`SKILL_TELEMETRY_*`). **Breaking/Behavior Changes** - None. **Migration Notes** - Existing execute/poll calls remain unchanged. - If you run scripts in constrained environments, allow optional telemetry calls to `/agent/telemetry/ingest` and `/telemetry/ingest`. ### 2.3.3 (2026-03-11) **What's New** - Standardized user-facing guidance around upload-based flows: do not expose manual URL/JSON fields for media/document inputs. - Updated capability reference examples and wording to match upload-first product UX. - Renamed CLI argument label from `input_json` to `input_payload` for consistency with structured payload semantics. **Breaking/Behavior Changes** - None. **Migration Notes** - Existing runtime API calls remain unchanged. - If your integration shows custom input forms, prefer file/attachment inputs instead of manual URL/JSON text fields.


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)