ability-file-cloud

Cloud storage operations

ability-file-cloud is a kadi “ability” package that implements cloud file operations (Dropbox, Google Drive, Box). It is an ability-level component intended to be loaded by the AGENTS runtime. The package provides an entrypoint (dist/index.js) and relies on a secret provider ability to obtain credentials. It exists to centralize cloud-file orchestration for agents that need upload/download/list/delete semantics across multiple providers.

Architecture

• Entry point: dist/index.js (as declared in agent.json). The runtime will load this file when the ability is started.
• Broker connectivity:
  • The ability is configured to connect to a broker (remote broker URL is declared in agent.json and a local broker configuration exists in config.toml).
  • The broker/network configuration exposes this ability on the “file” network (see config.toml broker.local.NETWORKS).
• Dependencies:
  • Declares a dependency on a “secret-ability” (agent.json) to fetch encrypted credentials (OAuth tokens, API keys) for each cloud provider.
  • Uses node libraries declared in package dependencies (node-fetch, form-data).
• Data flow (high level):
  1. Agent requests a file operation (upload/list/download) via the broker on the “file” network.
  2. The ability entrypoint (dist/index.js) handles the request, retrieves provider credentials from the secret-ability, and performs HTTP requests to the cloud provider API using node-fetch/form-data.
  3. Results and statuses are returned via the broker back to the requesting agent.
• How it fits in the AGENTS ecosystem:
  • This ability serves as a provider-focused utility for other agents to perform cloud file operations without embedding provider-specific logic into each agent.
  • It acts as a shared backend service (ability) reachable over the broker networks.

Tools / API

The source context does not contain explicit tool registration metadata (no tool names exported in agent.json). The package entrypoint is dist/index.js and any exported tools or functions are expected to be defined there. The only explicit ability/dependency declared is:

Name	Type	Notes
secret-ability	ability dependency	Declared in agent.json: this ability is required to fetch provider secrets/credentials.
Entry point	file	dist/index.js — consumers should inspect this file to learn exported tools/API.

If you are modifying or extending this ability:

• Add tool registrations (tools exported to the AGENTS runtime) in dist/index.ts / index.ts before building so tools are discoverable at runtime.
• Make sure any tool names you register are documented and that they call into the secret-ability for credentials.

Configuration

Configuration is minimal in the repository source. Key config fields (from config.toml and agent.json):

• agent.json

  • name: “ability-file-cloud”
  • type: “ability”
  • version: “0.2.0”
  • entrypoint: “dist/index.js”
  • abilities: { “secret-ability”: ”*” } — declares dependency on a secrets provider ability.
  • brokers.remote: “wss://broker.dadavidtseng.com/kadi” — remote broker used by this ability.

• config.toml (package config that will be read by the runtime)

  • [broker.local]
    • URL: “wss://broker.dadavidtseng.com/kadi”
    • NETWORKS: [“file”]
    • MODE: “broker”

Secrets

• The repository indicates “Secrets go in secrets.toml (encrypted vault)”. The ability expects provider API keys / OAuth tokens to be stored in the Kadi secrets vault (secrets.toml) and retrieved via the secret-ability. Do not hardcode provider credentials in config.toml or agent.json.

Environment variables

• No environment variables are declared in the source context. The runtime or your deployment can set standard Node environment variables as needed. Credentials should be supplied via the secrets vault accessed through secret-ability.

Code Examples

Below are the actual configuration and scripts from the source. Inspect dist/index.js (entrypoint) for concrete exported tools and runtime handlers.

agent.json (actual package manifest)

{
  "name": "ability-file-cloud",
  "type": "ability",
  "version": "0.2.0",
  "description": "Cloud file operations - Dropbox, Google Drive, Box",
  "entrypoint": "dist/index.js",
  "abilities": {
    "secret-ability": "*"
  },
  "brokers": {
    "remote": "wss://broker.dadavidtseng.com/kadi"
  },
  "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 (actual configuration file)

# Ability File Cloud Configuration
# Secrets go in secrets.toml (encrypted vault)

[broker.local]
URL = "wss://broker.dadavidtseng.com/kadi"
NETWORKS = ["file"]
MODE = "broker"

Common development/build commands (from agent.json scripts)

// Build
npx tsc

// Run compiled entrypoint
node dist/index.js

// Development (run TypeScript with tsx)
npx tsx index.ts

// Run in stdio mode (useful for local testing)
npx tsx index.ts stdio

// Start broker-mode for local testing
npx tsx index.ts broker

Note: For concrete API usage (function names, tool registrations) open dist/index.js (or index.ts before build) in this package to see exactly which tools this ability exposes and their parameter shapes.

Dependencies

Direct runtime dependencies (from package metadata in source context):

• @kadi.build/core — AGENTS/Kadi core integration (used to register abilities/tools, interact with broker)
• form-data — for multipart uploads to provider APIs
• node-fetch@^2.7.0 — for HTTP requests to cloud provider APIs
• tsx — development runner for TypeScript

Dev dependencies:

• @types/node
• typescript

Declared ability relationships:

• Depends on: secret-ability (ability declared in agent.json)
• No explicit abilities declared to depend on ability-file-cloud in the provided source; other agents should declare a dependency on this ability to leverage its tools.

Notes for Developers

• Inspect dist/index.js (or the TypeScript source index.ts) to:
  • Determine which tools/functions are exported.
  • See how secret-ability is called to fetch provider credentials.
  • Confirm how requests are routed to provider APIs (Dropbox, Google Drive, Box).
• When adding a new cloud provider:
  • Add provider-specific credentials to the secrets vault and document the secret keys.
  • Add provider client logic using node-fetch/form-data or a provider SDK as needed.
  • Register any new tools with the AGENTS runtime through @kadi.build/core so they are discoverable by other agents.
• Keep credentials out of config.toml/agent.json; use secret-ability and the encrypted secrets.toml vault.

If you need the exact tool names and function signatures, open the source entrypoint (index.ts / dist/index.js) in this package — that file contains the concrete exported tools and usage patterns.