ability-file-local

Local filesystem operations

ability-file-local is a kadi-ability that exposes local filesystem operations to the AGENTS orchestration platform. It provides tools for listing, creating, copying, moving, deleting, and watching files and directories, plus helpers for packing/unpacking (archive/tar/unzip) used by local file workflows. The ability runs in “native” mode and connects to a local broker (configurable) to receive tool invocations and emit events.

Architecture

• Entry point: dist/index.js (built from the TypeScript source).
• Runtime: runs as a kadi ability and registers a “file” network so other agents can call file-related tools.
• Broker connectivity: uses broker configuration in config.toml to connect to a local websocket broker (default ws://localhost:8080/kadi).
• Key libraries:
  • @kadi.build/core — ability framework integration and tool registration.
  • chokidar — filesystem watching.
  • archiver, tar, unzipper — packing/unpacking support for zip/tar workflows.
• Data flow:
  1. An orchestrator or another agent calls a file tool via the Kadi broker (or native invocation).
  2. ability-file-local receives the RPC, performs the local filesystem operation using Node fs APIs and helper libs (chokidar, archiver, etc.).
  3. Results or events (e.g., file change events from watch) are returned to the caller or published on the broker for other agents to consume.
• How it fits in AGENTS:
  • Acts as a local resource ability providing file-system primitives to higher-level abilities (e.g., build, deploy, archive).
  • Can be run as a standalone ability or as part of an agent process that multiplexes multiple abilities.

Tools / API

The ability exposes a set of file operation tools (RPC-style). The source description lists the primary operations below. Use these tool names when invoking the ability via Kadi (@kadi.build/core) or via the broker.

Tool name	Purpose	Key parameters
list	Enumerate files and directories under a path	path: string, glob?: string, recursive?: boolean, stat?: boolean
create	Create files or directories	path: string, type?: “file"
copy	Copy file(s) or directories	src: string, dest: string, overwrite?: boolean
move	Move/rename file(s) or directories	src: string, dest: string, overwrite?: boolean
delete	Remove file(s) or directories	path: string, recursive?: boolean, force?: boolean
watch	Watch a path for changes and emit events	path: string, events?: string[], persistent?: boolean, options?: object

Notes:

• Tool parameters above are illustrative names taken from the ability description (list, move, copy, delete, create, watch). The ability is implemented to support these operations; callers should pass path-like arguments and optional flags to control behavior (overwrite, recursive, filters).
• The ability also pulls in archiver/tar/unzipper to support packing/unpacking operations; these may be exposed as additional tools (pack, unpack, compress) if your deployment requires them.

If you inspect the built entrypoint (dist/index.js) it registers these tools via @kadi.build/core tool registration APIs (standard kadi ability pattern).

Configuration

Primary configuration is in config.toml and controls broker connectivity and network registration.

Example config.toml (from the package):

# Ability File Local Configuration

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

Fields:

• broker.local.URL
  • Type: string
  • Purpose: WebSocket URL to the Kadi broker the ability should connect to when running in broker mode.
  • Default in repo: “ws://localhost:8080/kadi”
• broker.local.NETWORKS
  • Type: array[string]
  • Purpose: Names of networks this ability registers on (e.g., “file”). Other agents use this network name to discover file tools.
• broker.local.MODE
  • Type: string
  • Purpose: Mode of operation. “native” indicates local/native mode (the ability runs locally and registers directly). Other kadi modes are available in the framework, but this ability ships configured for native.

Environment variables and secrets:

• The source tree for this ability does not declare specific environment variables or secrets vault fields. The ability reads broker configuration from config.toml. If your deployment uses a secrets manager or environment overrides for the broker URL, follow your platform conventions to provide broker credentials/URLs (the @kadi.build/core runtime will pick up environment-driven configuration if wired in your orchestration environment).

Code Examples

Below are the exact configuration and package manifest snippets from the source to show scripts and configuration shipped with the package.

agent.json (package manifest — exact content from source):

{
  "name": "ability-file-local",
  "type": "ability",
  "version": "0.1.1",
  "description": "Local file operations - list, move, copy, delete, create, watch",
  "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 (exact content from source):

# Ability File Local Configuration

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

Scripts you will commonly use during development:

• npm run setup — installs deps and builds
• npm run build — compiles TypeScript to dist/
• npm run dev — runs index.ts with tsx for fast dev iteration
• npm run serve — run in stdio mode (useful for local testing with stdin/stdout)
• npm run serve:broker — connect to the configured broker

Because the library uses chokidar/archiver/tar/unzipper, typical implementation code (found in the source index.ts) will:

• register tools via @kadi.build/core,
• use chokidar to implement watch and emit events,
• use archiver/tar/unzipper to implement archive/unarchive tools,
• use Node fs/promises for atomic file ops.

(If you need concrete call signatures for consumers, inspect dist/index.js or the TypeScript source index.ts in the package; tool registrations are performed through @kadi.build/core APIs.)

Dependencies

Direct runtime dependencies (from package manifest):

• @kadi.build/core — core ability framework (required)
• archiver — zip archive creation
• chokidar — file system watching (watch tool)
• tar — tar archive creation/extraction
• unzipper — unzip support
• tsx — dev runner (dev-time)

Dev dependencies:

• @types/archiver, @types/tar, @types/unzipper, @types/node, typescript

What depends on it:

• Any higher-level agent or ability that needs local file operations (build, deploy, asset management) should call this ability on the “file” network. Typical consumers are CI/CD pipeline abilities, packager/archiver abilities, or any orchestrated step that requires access to the node’s filesystem.

Notes for developers

• Entry point: follow the agent.json entrypoint (dist/index.js). Build via npm run build to refresh the dist bundle.
• Watch behavior: chokidar is used; be mindful of platform-specific semantics (macOS vs Linux). Provide ignore patterns when registering watchers if you want to skip node_modules/build artifacts.
• Tests and iteration: use npm run dev to run index.ts directly via tsx during development.
• When adding new tools, register them via @kadi.build/core consistent with existing tool names and add entries to the network list if introducing new network names.

If you need deeper examples of tool registration or the exact runtime API surface, inspect the built artifact dist/index.js or consult @kadi.build/core documentation for ability tool registration patterns.