Keeper

This repository packages Keeper as a Wippy module monorepo.

• keeper/ publishes keeper/keeper, the core Wippy control plane.
• usage/ publishes keeper/usage, the optional usage analytics module.

Each child directory is an independent Wippy module with its own wippy.yaml, wippy.lock, source tree, tests, and optional frontend bundle.

Modules

keeper/keeper@0.5.18

Keeper provides the operator surface for a Wippy app:

• registry and namespace governance
• task orchestration and agent workflows
• MCP token management and MCP transport
• Hub dependency install/uninstall planning
• frontend component discovery, builds, screenshots, and UI automation tools
• logs, process/system inspection, tests, knowledge, changesets, and state graph APIs

The compiled Keeper UI is embedded in the module as keeper.components:ui_static_fs. Consumer apps should install the module and serve the embedded UI; they should not rebuild Keeper from stale app-local source unless they are actively developing this repository.

keeper/usage

Keeper Usage adds analytics pages and APIs on top of wippy/usage. It is separate so deployments can install or remove usage analytics independently.

Requirements

Keeper requires Wippy v0.3.44a or newer. Hub install previews use registry.snapshot():changes():plan() to resolve module sources and requirements before registry changes apply.

keeper/keeper is configured through namespace requirements, so app projects can bind Keeper to their own runtime resources without editing Keeper entries:

• keeper:api_router defaults to app:api and is applied to Keeper HTTP APIs.
• keeper:app_db defaults to app:db and is used for Keeper app-owned tables.
• keeper:admin_scope defaults to app.security:admin.
• keeper:env_storage defaults to app.env:store and stores Keeper settings and MCP flags.
• keeper:public_gateway defaults to app:gateway and hosts the Keeper MCP HTTP router.
• keeper:mcp_route defaults to /keeper-mcp/ and controls the MCP client path.
• keeper:ui_server defaults to app:gateway and serves embedded Keeper UI assets.
• keeper:process_host defaults to app:processes for Keeper-spawned runtime work.

The MCP client URL is the host application's public API base plus keeper:mcp_route (for example /keeper-mcp/). Keeper does not require or document a hardcoded local port for user connections.

The module also declares dependency requirements for Wippy runtime modules such as wippy/agent, wippy/dataflow, wippy/llm, wippy/migration, wippy/security, wippy/session, wippy/test, and wippy/views.

See RELEASES.md for release notes.

Hub Flow

The Keeper Hub APIs are designed for runtime dependency management:

• browse modules and versions
• read module README content
• inspect installed dependencies
• plan installs, including transitive requirements and required parameters
• install or uninstall dependencies
• list and run migrations when the installed module provides them

Install planning should be used before install so the UI can show the complete requirement list and keep the user in the loop. Do not guess requirement values.

The planner keeps existing exact bindings, then uses a compatible declared default, then binds a sole compatible meta.value_kind registry candidate. Agreeing bare application profile values remain reusable. Multiple candidates remain suggestions for users and MCP agents to select explicitly. The install API rejects unbound or invalid required values with the requirement id and expected kind; the dialog shows the same requirement state and disables Apply until it is complete.

Declared defaults remain resolved values in requirement rows and recommended parameters. Native previews and install payloads leave those defaults implicit in dependency entries. A supplied or recorded binding is not removed merely because its value equals a declared default.

Resource validation includes entries introduced by the selected package graph. The selected kind takes precedence when a package replaces an existing entry. meta.value_type declares a literal value: boolean, number, integer, string, object, or array. It takes precedence over meta.value_kind, which can retain a semantic hint for a literal descriptor. Object and array defaults accept JSON text; malformed defaults reject the plan. Requirements without value_type retain their existing binding behavior.

The plan and install actions accept a dependencies array. Keeper resolves all requested roots together before requirement validation and commits them in one governance changeset. Request order does not determine which dependency capabilities are available. Existing single-component requests keep their shape.

Verify

Run the stored timestamp regressions in timezones on both sides of UTC:

TZ=Etc/GMT-4 make test SUITES=keeper.timestamps:test
TZ=Etc/GMT+7 make test SUITES=keeper.timestamps:test

make lint
make publish-dry-run

Publish

make publish-keeper
make publish-usage

License

Keeper modules are distributed under the Mozilla Public License 2.0. See LICENSE. The module metadata in keeper/wippy.yaml and usage/wippy.yaml uses the same MPL-2.0 identifier.