RunLens

RunLens is a lightweight Agent Runtime for learning, portfolio demonstrations, and local experiments. It started with a user-feedback CSV analysis use case, then evolved into a reusable runtime where business logic is provided by plugins and model calls, tool execution, skills, permissions, plans, recovery, hooks, events, and artifact validation share one execution chain.

The project focuses on more than generating an answer. It makes an Agent run safely executable, reliably terminable, and inspectable through both result artifacts and process evidence.

Why the Project Is RunLens

RunLens is a general Agent Runtime rather than a single business application. Feedback analysis is the complete example plugin, while the same runtime also executes the smaller file_summary plugin. New business modules declare inputs, tools, skills, plans, artifacts, and validation rules without duplicating the Agent Loop, ToolExecutor, or API.

The RunLens name reflects the current architecture:

• Run is the unit that owns task state, files, capabilities, and events.
• Lens represents the trace, event, metric, and manifest views used to inspect and review execution.
• feedbacklens remains a full plugin example for structured input, multiple tools, cross-artifact contracts, and source-evidence validation.

Execution Chain

API Request
→ Plugin Registry
→ BusinessPlugin
→ Skill Activation
→ ResolvedRunCapabilities
→ Prompt / Plan / Todo
→ LLM Call
→ Tool Schema / Permission / Hooks
→ Tool Execution / Observation
→ Artifact and Evidence Validation
→ Events / Metrics / Manifest
→ Completed or Failed

The model proposes ToolCalls. Deterministic runtime code decides whether a tool exists, its arguments are valid, the requested path is allowed, the handler succeeded, and the final artifacts satisfy their delivery contracts.

Key Capabilities

Plugin-extensible Runtime

BusinessPlugin combines business input, tools, prompts, plans, skills, and artifact contracts. The generic runtime does not import business implementations. Two trusted built-in plugins validate the design:

• feedbacklens reads feedback CSV files and produces analysis, product backlog, and insight-report artifacts with cross-artifact evidence checks.
• file_summary reads local text and produces structural analysis and summaries as a minimal example of tool and artifact isolation.

Capability Resolution and Permissions

ResolvedRunCapabilities creates an immutable capability snapshot for each run and drives the system prompt, LLM tool allowlist, permission policy, and persisted runtime configuration. Skills can further narrow tools and filesystem access.

Agent Loop, Recovery, and Termination

The runtime covers model calls, tool calls, observation write-back, and multi-turn progress. Its state machine and policies handle provider retries, invalid tool arguments, permission denial, repeated calls, recovery exhaustion, and time limits. Completion never relies only on the model claiming that the task is finished.

Tool Execution Safety

ToolExecutor applies registry lookup, input-schema validation, permission checks, PreToolUse hooks, handler execution, output-schema validation, and PostToolUse hooks. Reads stay within approved directories, while writes are restricted to the current run workspace.

Artifact and Evidence Validation

ArtifactContract is the single source of truth for required files, JSON schemas, Markdown headings, and evidence fields. The feedbacklens plugin creates a run-level Evidence Index from the source CSV; feedback IDs and quoted evidence in final artifacts must resolve back to the original input.

Events, Trace, Metrics, and Manifest

An append-only events.jsonl file stores the authoritative runtime timeline and supports derived traces, metrics, and the frontend Inspector. The manifest exposes only approved artifacts, while raw model events, permissions, and tool details remain outside the public Documents API.

Engineering Work

• FastAPI backend and React frontend.
• DeepSeek, OpenAI, and automatic provider selection; missing real credentials produce explicit errors instead of fake results.
• Deterministic test-only LLM fakes keep automated tests offline.
• pytest scenarios, TypeScript checks, frontend builds, a unified verification script, Docker Compose, and reproducible demos.
• Run Launcher, Run Viewer, and Artifact Inspector interfaces for status, plans, events, metrics, and published artifacts.

Scope

The current version is intentionally synchronous, single-process, and file-backed. It demonstrates a clear and testable Agent runtime chain rather than claiming production-grade high availability. Asynchronous queues, long-term memory, multi-tenancy, third-party plugin sandboxing, and multi-agent collaboration remain future work.