Extensibility

All extensibility is through tools:

  • Custom metadata. Place a tool whose name matches the metadata key in the search path (e.g., tool rate-limit handles metadata.rate-limit).
  • Custom directives. Place a tool whose name matches the directive in the search path (e.g., :chart triggers tool chart).
  • Custom middleware. Write a tool with before/after constraints, reference it as a metadata key.
  • Error handling. Middleware with try/catch around target.manager.next(), ordered after: ["$pre-execute"] to wrap execution.
  • Override anything. Same name, earlier in path, wins.

Security

By default, all tools run in-process with full host access. Path traversal prevention on file operations. allowed-tools is enforced by validate-allowed-tools in the pipeline — denied calls throw. The trust middleware gates tool execution with user approval.

Sandboxed execution is available via the sandbox metadata middleware and Docker-based engine. Skills can declare metadata.sandbox with filesystem mounts, network access, environment variables, and resource limits. The sandbox-app skill runs the entire project in a container. See docs/operations/sandbox.md for details.

Design Principles

  1. Everything is a tool. One interface, one discovery mechanism, one override mechanism.
  2. The orchestrator is the kernel. Resolve a tool, cascade its metadata, build a sorted chain, pop and call, handle returns and throws.
  3. Middleware is the extension model. Onion pattern with ctx.manager.next(), try/catch/finally, dynamic injection.
  4. Context is the bus. All information flows through it. No side channels.
  5. Config is metadata. The main skill's frontmatter IS the config.
  6. Search path is the override mechanism. Same name, earlier in path, wins.
  7. Minimal kernel, maximal surface. One builtin. Everything else is replaceable.
  8. Isomorphism. Code tools and markdown skills are interchangeable.
  9. No magic. Every behavior traces to a tool invocation.
  10. Lazy resolution. Tools are found on demand, not pre-discovered. No global mutable state.

Runtime Resolution

The Agent Apps runtime is installed to a standard location. All consumers — the CLI, the Desktop editor, the VS Code extension, and the contrib skill for external agents — find it using the same resolution order:

Priority Source Value
1 AGENT_APPS_ROOT env var Points to the installation directory. CLI entry point: $AGENT_APPS_ROOT/dist/src/cli.js.
2 Local project install ./node_modules/.bin/agent-apps
3 Global standard location ~/.agent-apps/cli (created by install.sh)
4 PATH Bare agent-apps command

The VS Code extension also accepts an explicit agent-apps.cliPath setting (highest priority).

AGENT_APPS_ROOT points to the root of the installation — the directory containing dist/, skills/, docs/, and package.json. Consumers derive specific paths from it: $AGENT_APPS_ROOT/dist/src/cli.js for the CLI entry point, $AGENT_APPS_ROOT/docs/ for documentation.

See Also

Ask AI