agentapp-ref

Agent App

Agent App is a draft standard for complete installable intelligent applications in the Agent standards ecosystem. It packages real app implementation - UI bundles, workers, storage schemas, workflows, agent entries, Skills, Knowledge bindings, tool requirements, artifact contracts, policies, evals, presentation metadata, v0.7 requirement-boundary files, and v0.8 standalone installation metadata - without moving agent execution into the cloud or forcing every user through Lime Desktop.

Agent Runtime answers how tasks execute. Agent UI answers how interaction surfaces render. Agent Context answers how context is assembled. Skills answer how reusable work is done. Knowledge answers what trusted facts are. Tools connect external capabilities; Artifacts persist deliverables; Evidence, Policy, and QC make results trustworthy. Agent App answers how all of those become a complete installable application with host capabilities, UI, data boundaries, entries, lifecycle, v0.7 requirement handoff, and v0.8 install modes.

v0.8 makes one product boundary explicit: Agent App is the product, Lime Runtime is the capability substrate, Lime Desktop is one host, and Lime App Shell is the standalone single-app host. Users can install an Agent App inside Lime Desktop, download it as a standalone branded app, or run it against a shared system Lime Runtime.

Core boundary

Agent App is the business workspace. Lime Agent is the intelligent runtime capability that apps orchestrate. Users should be able to finish a business workflow inside the app surface instead of being forced back into a generic chat UI. Chat and expert entries are valid app surfaces, but they are optional interaction modes rather than the required container for product work.

Standard / layer	Owns	Entry point	Runtime behavior
Agent Runtime	Task lifecycle, model routing, sessions, checkpoints, event streams, structured output.	Runtime contract	Runs under host policy; App declares intent through app.runtime.yaml.
Agent UI	Pages, panels, commands, viewers, Host Bridge interaction surfaces.	UI descriptors / entries	Rendered in host-controlled surfaces through lime.ui.
Agent Context	Context assembly, budget, priority, compression, missing-context requests.	Context descriptors	Resolved by host/runtime for each entry or task.
Agent Skills	Reusable procedures, scripts, rubrics, and executable process fragments.	SKILL.md	Activated by an agent after trust checks.
Agent Knowledge	Source-grounded facts, status, provenance, freshness, and safe context.	KNOWLEDGE.md	Loaded as fenced data or retrieval context; never executed.
Agent Tool / Connector	External callable capabilities, MCP, CLI, API, browser adapters, auth, side effects.	Tool / connector descriptor	Invoked by Host/Cloud policy and evidence surfaces.
Agent Artifact	Durable deliverables, schemas, viewers, exporters, state.	Artifact schema	Stored and displayed by host artifact services.
Agent Evidence / Policy / QC	Provenance, permissions, risk, quality gates, audits, waivers.	Evidence, policy, eval descriptors	Enforced and recorded by Host/Cloud; App declares inputs and gates.
Agent Expert	Chat-first entry composed from persona, context, tools, and app state.	Expert entry	Runs inside a host conversation surface; optional App entry, not the App itself.
Agent App	Complete installable app package: UI, workers, storage, workflows, entries, permissions, artifacts, evals, lifecycle, v0.7 boundaries, and v0.8 install modes.	APP.md + runtime package	Runs in a compatible host through @lime/app-sdk capability handles.
Lime Runtime Core	Agent execution, storage, tools, connectors, secrets, policy, evidence, artifacts, and local governance.	lime.* capabilities	Shared by Lime Desktop, Lime App Shell, runtime-backed apps, and compatible hosts.
Lime Host / Cloud	Local shells, sandbox, registry, tenant policy, OAuth, webhook, scheduled sync.	Host shell + lime.* capabilities	Injected into apps as authorized handles; apps do not import host internals.

App and Lime responsibilities

Area	Agent App owns	Lime owns
Product experience	Business UI, pages, tables, forms, dashboards, review steps, and delivery views.	Host shell, navigation, theme, locale, installation, and app lifecycle.
Business logic	Workflow state, domain rules, storage schema, structured result write-back, and human confirmation.	Agent task runtime, capability enforcement, retries, cancellation, cost limits, and telemetry.
Data boundary	App-local records, package assets, overlays, and references to workspace data.	Namespaced storage, files, Knowledge binding, secrets, policy, cleanup, and audit.
Agent execution	Decides when to call an agent task and how the result updates product state.	Runs lime.agent tasks, model calls, tools, traces, artifacts, and evidence through SDK contracts.

The boundary is intentionally strict: business should not leave the app context, and agents should not leave Lime capability governance. If an app bypasses Lime to build its own model gateway, permission system, or evidence store, it is becoming an independent SaaS instead of an Agent App. If an app sends users back to generic chat for core work, it is only a chat wrapper rather than a product-level app.

Pack shape

my-agent-app/
├── APP.md                    # required: discovery manifest + app guide
├── app.manifest.json         # optional: separated machine manifest
├── dist/
│   ├── ui/                   # optional: UI bundle and route manifest
│   ├── worker/               # optional: business workers and background jobs
│   └── tools/                # optional: packaged tool adapters
├── storage/
│   ├── schema.json           # optional: app namespace data model
│   └── migrations/           # optional: versioned migrations
├── workflows/                # optional: business workflows and state machines
├── agents/                   # optional: expert-chat personas
├── skills/                   # optional: bundled or referenced Agent Skill packages
├── knowledge-templates/      # optional: required knowledge slots and starter templates
├── artifacts/                # optional: output contracts, viewers, exporters
├── evals/                    # optional: readiness and quality checks
├── policies/                 # optional: permissions and data boundaries
├── app.runtime.yaml          # optional: v0.6 agent task runtime control plane
├── app.requirements.yaml     # optional: v0.7 requirements, MVP, non-goals, acceptance
├── app.boundary.yaml         # optional: v0.7 App / Host / Cloud / Connector / Human boundary
├── app.integrations.yaml     # optional: v0.7 Host/Cloud-managed external integrations
├── app.operations.yaml       # optional: v0.7 side effects, approvals, evidence
├── app.install.yaml          # optional: v0.8 in-Lime, standalone, runtime-backed install modes
├── overlay-templates/        # optional: tenant / workspace overlay schemas
├── app.lock.json             # optional: package file hashes and signatures
└── examples/                 # optional: sample workspaces, prompts, outputs

APP.md is not the app implementation. It is the discovery and review surface. Product-level functionality belongs in the runtime package and calls host services through the Capability SDK.

Capability SDK contract

Compatible hosts should expose versioned, authorized, mockable capabilities such as:

• lime.ui for pages, panels, commands, settings, artifact viewers
• lime.storage for app namespaces, tables, indexes, migrations
• lime.files for user-selected files and parsing
• lime.agent for local agent tasks, streaming, retries, traces
• lime.knowledge for Knowledge Pack binding and retrieval
• lime.tools for Tool Broker / ToolHub invocation
• lime.connectors for Host/Cloud-managed MCP, CLI, API, browser, OAuth, webhook, and sync adapters
• lime.artifacts for persistent deliverables
• lime.workflow for business state and background tasks
• lime.policy for permissions, cost, risk, data boundary
• lime.evidence for provenance and replay
• lime.secrets for credentials without plaintext app access

Apps must not import host internals. They declare capability requirements in the manifest and receive runtime handles from the host. v0.8 keeps the layered manifest model, keeps v0.6 app.runtime.yaml for the lime.agent task control plane, keeps v0.7 requirement-boundary files, and adds app.install.yaml so packages can declare in_lime, standalone, runtime_backed, and web_host install modes.

v0.8 install modes

Mode	User experience	Runtime relationship
in_lime	Install and launch from Lime Desktop.	Uses the Desktop-hosted Lime Runtime.
standalone	Download a branded business app directly.	Bundles a compatible Lime Runtime profile through Lime App Shell.
runtime_backed	Install a lightweight app package.	Requires an already installed system lime-runtime.
web_host	Open in a compatible hosted environment.	Host provides web capability handles and policy.

Runtime contract

Compatible hosts should:

• Discover apps by APP.md.
• Verify package hash, signatures, manifest shape, and capability versions.
• Install or activate an app only after user, tenant, or workspace consent.
• Resolve declared UI, storage, workers, Runtime, Context, Skills, Knowledge templates, Tools, Connectors, Artifacts, Evidence, Policy, Evals, and permissions into host catalogs.
• Inject Capability SDK handles at runtime instead of exposing host internals.
• Keep agent execution inside the host runtime; cloud registries may distribute and authorize apps but must not become a hidden Agent Runtime.
• Keep customer data in Agent Knowledge packs, workspace files, app storage namespaces, secrets, or overlays rather than official app packages.
• Record app provenance on every projected entry, task, tool call, artifact, migration, and eval.

Documentation

• Specification
• What is Agent App?
• Runtime package design
• Capability SDK
• Agent App and Standards Ecosystem Boundary
• Runtime model
• 中文规范

Reference CLI

npx agentapp-ref@0.8.0 validate ./my-agent-app --version 0.8
npx agentapp-ref@0.8.0 to-catalog ./my-agent-app
npx agentapp-ref@0.8.0 project ./my-agent-app
npx agentapp-ref@0.8.0 readiness ./my-agent-app --workspace ./workspace
npx agentapp-ref@0.8.0 migrate-check ./my-agent-app
npx agentapp-ref@0.8.0 migrate-generate ./my-agent-app --target 0.8.0

Local development

npm install
npm run dev
npm run build