skill-hub-gateway

name	skill-hub-gateway
description	Unified gateway skill for async execute/poll, portal user closure, and telemetry feedback workflows.

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.