@malv/runtime

Runtime utilities and server templates for MALV applications.

Purpose

This package provides the server entry points that run MALV apps in development and production. It supports two runtimes:

• Node.js (default) - No external dependencies, runs with standard Node.js
• Cloudflare Workers - Requires Wrangler, provides access to Cloudflare AI binding

It contains:

• Worker entry point and request routing
• Capability creators (storage, token, AI, events, objects, etc.)
• Request handlers for tool execution, events, and batch operations
• SSE streaming utilities
• Request-scoped logging

Installation

yarn add -D @malv/runtime

Usage

This package is used by @malv/cli during app setup. The CLI copies the appropriate template files based on the runtime:

# Default: Node.js runtime
malv dev

# Cloudflare Workers runtime
malv dev --cloudflare

Template Structure

cloudflare-worker/
├── node.ts                      # Node.js entry point (HTTP server)
├── worker.ts                    # Cloudflare Workers entry point
├── Env.ts                       # Environment interface
├── appName.ts                   # App name utilities
├── executeTool.ts               # Tool execution logic
├── createSSEStream.ts           # SSE streaming
├── ProxiedStorage.ts            # Storage proxy
├── errors.ts                    # Error types
├── devLogger.ts                 # Development logging
├── toolExecutionContext.ts      # Async context for logging
├── setupConsoleCapture.ts       # Console.log capture
├── capabilities/                # Capability creators
│   ├── createAICapability.ts
│   ├── createStorageCapability.ts
│   ├── createTokenCapability.ts
│   ├── createObjectCapability.ts
│   ├── createEventCapability.ts
│   ├── createToolCapability.ts
│   ├── createAppsCapability.ts
│   ├── createCryptoCapability.ts
│   ├── createEnvironmentCapability.ts
│   ├── createRequestCapability.ts
│   ├── createSearchCapability.ts
│   └── createEventHandlerCapabilities.ts
├── handlers/                    # Request handlers
│   ├── handleToolRequest.ts
│   ├── handleBatchRequest.ts
│   ├── handleEventStart.ts
│   ├── handleEventStop.ts
│   ├── handleEventHandler.ts
│   └── loadEventDefinition.ts
├── event/                       # Event utilities
│   ├── generateKey.ts
│   ├── loadEventDefinitions.ts
│   └── eventDefinitionCache.ts
└── object/                      # Object utilities
    ├── loadObjectDefinitions.ts
    ├── objectDefinitionCache.ts
    ├── objectStorageHelpers.ts
    └── validateObjectMetadata.ts

Related Packages

• @malv/cli - Command-line interface that uses this runtime template
• @malv/types - TypeScript type definitions
• @malv/base - Core framework implementation

Migration from @malv/base-app

This package was extracted from @malv/base-app to separate runtime code from build-time tools. If you were previously using @malv/base-app:

1. Replace @malv/base-app with @malv/runtime in your devDependencies
2. Remove rollup dependencies from your app (they're now in @malv/cli)
3. The CLI handles all build operations - no changes needed to your workflow

License

MIT