ability-file-remote

Remote filesystem operations

ability-file-remote is a kadi-ability that provides remote file sharing and tunneling capabilities for AGENTS. It centralizes temporary URL generation and tunnel management (primary: kadi; fallbacks: ssh, frpc, ngrok, localtunnel), allowing other agents to expose local files or short-lived HTTP endpoints to remote peers via the AGENTS broker. The ability exists to standardize remote-file transport over the “file” network and to provide configurable fallbacks when the primary tunnel service is unavailable.

Architecture

• Key components
  • Broker connector (configured at broker.local): registers available tunnels/temporary URLs with the AGENTS broker so other agents can discover file endpoints.
  • Tunnel manager (tunnel.SERVICE + FALLBACK_SERVICES): attempts to create a public endpoint using the configured primary service (kadi) and, optionally, fallback backends (ssh, frpc, ngrok, localtunnel).
  • Lifecycle controller: issues temporary URLs, records expiration/metadata, and tears down tunnels when they are no longer needed.
• Data flow
  1. A local agent requests a file share or temporary URL from the ability (via broker or direct RPC).
  2. The ability consults config.toml to select tunnel.SERVICE (e.g., “kadi”). If that fails and AUTO_FALLBACK is true, it iterates FALLBACK_SERVICES.
  3. The chosen backend (ngrok/localtunnel/ssh/frpc/kadi) opens a public endpoint pointing at the local file-serving port or resource.
  4. The ability registers the endpoint metadata with the broker (broker.local.URL) on the configured NETWORKS ([“file”]) so other agents can fetch it.
  5. On teardown or expiry, the ability closes the tunnel and updates broker state.
• How it fits in the AGENTS ecosystem
  • ability-file-remote is an ability (type: kadi-ability) intended to be consumed by other agents that need to expose local files or temporary HTTP endpoints.
  • It uses the AGENTS broker (broker.local) to publish endpoints to the network(s) listed in broker.local.NETWORKS (notably “file”).

Tools / API

(This package exposes tunnel and temporary-URL management functionality to consumers. The source registers tunnel backends via configuration and packages listed under Dependencies.)

Exposed capabilities (conceptual — actual registration happens in the ability entrypoint):

• Tunnel orchestration
  • Purpose: open/close public tunnels that map to local file-serving endpoints.
  • Key config fields: tunnel.SERVICE, tunnel.FALLBACK_SERVICES, tunnel.AUTO_FALLBACK
• Broker registration
  • Purpose: publish temporary URLs and tunnel metadata to the broker at broker.local.URL so other agents can discover file endpoints.
  • Key config fields: broker.local.URL, broker.local.NETWORKS, broker.local.MODE

Note: The source does not include explicit function names in the provided context. Integrators should inspect dist/index.js (entrypoint) for exported tool names and RPC registrations when integrating with other agents.

Configuration

ability-file-remote reads configuration from config.toml (and environment for any third-party tunnel backends as appropriate).

Provided config.toml (copied from source):

# Ability File Remote Configuration

[broker.local]
URL = "ws://localhost:8080/kadi"
NETWORKS = ["file"]
MODE = "native"

[tunnel]
SERVICE = "kadi"
FALLBACK_SERVICES = ["ssh", "frpc"]
AUTO_FALLBACK = true

• broker.local.URL (string)
  • WebSocket URL used to connect to the local broker for registering tunnels and temporary URLs.
• broker.local.NETWORKS (array of strings)
  • Networks on which to register endpoints. Default from source: [“file”].
• broker.local.MODE (string)
  • Mode for broker connector (example value from source: “native”).
• tunnel.SERVICE (string)
  • Primary tunnel service to use. Source default: “kadi”.
• tunnel.FALLBACK_SERVICES (array of strings)
  • Ordered list of fallback tunnel backends. Source default: [“ssh”, “frpc”].
• tunnel.AUTO_FALLBACK (boolean)
  • Whether to automatically attempt fallbacks if the primary SERVICE fails. Source default: true.

Environment variables and secrets

• The source does not declare explicit environment variables in config.toml or agent.json. However, individual tunnel backends used by this ability commonly require credentials or tokens:
  • ngrok: NGROK_AUTH_TOKEN (if ngrok is used as a fallback/backend).
  • localtunnel: may accept options such as subdomain but commonly does not require a secret.
• Secrets vault
  • If you store service tokens (ngrok, ssh keys, frpc credentials), keep them in the AGENTS secret store / vault and make them available to the ability at runtime (consult your AGENTS operator patterns). The ability will need access to those credentials to initialize respective tunnel backends.

Code Examples

Below are exact-copy excerpts from the package metadata and configuration so you can see how the ability is packaged and configured.

agent.json (package metadata / scripts)

{
  "name": "ability-file-remote",
  "type": "ability",
  "version": "0.1.1",
  "description": "Remote file sharing - tunneling and temporary URL management",
  "entrypoint": "dist/index.js",
  "scripts": {
    "preflight": "node --version",
    "setup": "npm install && npm run build",
    "build": "npx tsc",
    "start": "node dist/index.js",
    "dev": "npx tsx index.ts",
    "serve": "npx tsx index.ts stdio",
    "serve:broker": "npx tsx index.ts broker",
    "clean": "rm -rf node_modules abilities agent-lock.json package-lock.json dist"
  }
}

config.toml (configuration)

# Ability File Remote Configuration

[broker.local]
URL = "ws://localhost:8080/kadi"
NETWORKS = ["file"]
MODE = "native"

[tunnel]
SERVICE = "kadi"
FALLBACK_SERVICES = ["ssh", "frpc"]
AUTO_FALLBACK = true

Common run patterns (from agent.json scripts)

// development
// npm run dev -> delegates to: npx tsx index.ts

// run in stdio mode (useful for direct testing)
// npm run serve -> npx tsx index.ts stdio

// build and run compiled entrypoint
// npm run build -> npx tsc
// npm run start -> node dist/index.js

Integration note

• Check dist/index.js (entrypoint) to identify exact RPC or tool registration names used by this ability. When writing consumers (other agents), call the ability’s registered RPC endpoints or use broker discovery (broker.local) to find temporary URLs published into the “file” network.

Dependencies

Exact runtime dependencies from the package manifest:

• @kadi.build/core ^0.9.0
• chalk ^5.3.0
• debug ^4.3.7
• fs-extra ^11.2.0
• localtunnel ^2.0.2
• ngrok ^4.3.3
• tsx ^4.21.0

Dev dependencies:

• @types/node ^25.3.1
• typescript ^5.9.3

What this ability depends on

• AGENTS core / broker: broker.local.URL (WebSocket broker) — needed to register and advertise endpoints.
• Tunnel backends (packages listed above) to actually open public endpoints (ngrok, localtunnel, ssh/frpc integrations).
• @kadi.build/core — ability glue for Kadi/AGENTS runtime.

What depends on this ability

• Any agent that needs to make local files or ephemeral HTTP endpoints reachable to remote peers on the “file” network should depend on ability-file-remote to manage tunnel lifecycle and broker registration.
• Higher-level file-transfer or collaboration agents that implement transfers over public endpoints will use this ability to avoid duplicating tunnel and URL management logic.

Notes for developers who will modify this ability

• Entry point: dist/index.js (source entry likely index.ts). Inspect the compiled entry to discover exported tool names and RPC handlers.
• Configuration is intentionally minimal: extend config.toml to add specific per-backend options (ngrok authtoken, localtunnel subdomain, ssh/frpc credential paths) if you add additional functionality.
• When adding new fallback services, update tunnel.FALLBACK_SERVICES and implement the corresponding backend adapter to match the same lifecycle API used by the primary service (open/start, status, close).
• Keep broker.local.NETWORKS aligned with the networks consumers expect (default: [“file”]). When registering endpoints, populate metadata with expiry TTL and origin agent ID so consumers can validate and tear down appropriately.