Plugin Capability Services Implementation Checklist

Companion design: docs/PLUGIN_CAPABILITY_SERVICES.md

Status: implementation substantially complete; compatibility metadata and manual verification pending

1. Core Contract Foundation

• Add src/capabilities/types.ts with capability references, canonical operation IDs, operation definitions, contracts, resource references, and helper types.
• Add a typed defineCapability(...) helper that preserves operation input and output inference.
• Add canonical operation-ID validation for capability:v<major>:<capability>.<operation>.
• Add exact capability-major matching.
• Add contract validation for duplicate or malformed operation IDs.
• Document each contract's minimum AppWeaver core version in its file header and exported metadata.

2. Runtime Registry

• Add src/core/capabilities/registry.ts.
• Add src/core/capabilities/errors.ts with typed registration, selection, validation, invocation, and resource failures.
• Add src/core/capabilities/selection.ts for explicit, single, multiple, and missing-provider resolution.
• Extend BotPlugin with capabilityProviders.
• Define CapabilityProviderDefinition without providerKey or plugin-supplied source metadata.
• Enforce one provider registration per plugin package, capability name, and major version.
• Derive provider IDs as <plugin-package-name>/<capability-name>/v<major>.
• Build CapabilityProviderSource from trusted plugin identity and installed package metadata.
• Include plugin name, alias, version, title, description, and icon URL in registered source metadata.
• Register providers after plugin onInit so handlers can use initialized plugin state.
• Validate required operations and reject unknown provider operations.
• Validate operation input before invocation and output after invocation.
• Attribute invocation logs and failures to consumer and provider identities.

3. Plugin-Scoped Capability Client

• Add a typed capability client to PluginContext.
• Create a plugin-scoped context in registerPlugin() so core knows the invoking consumer identity.
• Support invocation using exported operation definitions rather than manually typed strings.
• Support provider: 'auto' for new resources.
• Support explicit stable provider IDs for existing provider-owned resources.
• Return typed missing-provider and selection-required results for consumer handling.
• Prevent capability invocation during incomplete startup registration, or define a two-phase registration/finalization lifecycle.

4. Capability Relations And Catalog Discovery

• Extend plugin package.json parsing with appweaver.capabilities.provides, uses, and requires arrays.
• Accept several capabilities and several versions of the same capability.
• Deduplicate exact repeated declarations without collapsing distinct versions.
• Extend plugin publishing to emit namespaced NIP-32 capability labels on kind 32107 events.
• Parse capability labels only from kind 32107 events with the AppWeaver capability namespace.
• Extend plugin catalog parsing with relation and version metadata.
• Add capability:<name>:v<major> provider filtering.
• Add explicit provides:, uses, and requires: filters.
• Preserve existing publisher, repository, release, signature, and core compatibility checks.
• Log missing requires relations after all installed providers have registered.
• Keep missing uses relations non-blocking.

5. Provider Selection And Generic Web Flow

• Keep provider preferences in consumer-owned state rather than core-global persistence.
• Add a generic capability WebAction with operation ID, input, optional provider ID, and selection policy.
• Implement the missing-provider result and plugin-manager search action.
• Implement the single-provider direct route.
• Implement explicit provider routing for consumer-owned preferences.
• Implement the multiple-provider chooser flow on the requested WebAction surface.
• Display plugin icon, title, alias, description, and version in chooser entries.
• Add a generic Use provider chooser action.
• Route existing resource operations to the provider ID stored in CapabilityResourceRef.
• Keep chooser and missing-provider UI generic and plugin-agnostic.

6. Scheduler V1 Contract

• Add src/capabilities/scheduler.v1.ts with its minimum core version header.
• Define capability:v1:scheduler.create input and output schemas.
• Define capability:v1:scheduler.list input and output schemas.
• Define capability:v1:scheduler.show input and output schemas.
• Define required versus optional scheduler operations explicitly.
• Define provider-scoped scheduler resource references.
• Define the initial agent-prompt task type.
• Allow provider-owned review output without coupling the contract to Job-specific nodes.

7. Job Scheduler Provider

• Declare Job as providing scheduler:v1 in package metadata.
• Raise Job's appweaver.coreApiVersion to a range that includes the scheduler contract's minimum core version, 10.0.1.
• Register Job's scheduler provider on BotPlugin.
• Map capability:v1:scheduler.create to Job's existing draft or creation flow.
• Map capability:v1:scheduler.list to Job's existing query and rendering logic.
• Map capability:v1:scheduler.show to Job's existing detail UI.
• Return stable Job resource IDs inside complete CapabilityResourceRef values.
• Keep Job responsible for persistence, execution, retries, logs, and result delivery.
• Preserve existing Job commands and AI tools.

8. NR Scheduler Consumer

• Declare NR as using scheduler:v1 in package metadata.
• Add a Schedule fetch action to the appropriate NR UI.
• Raise NR's appweaver.coreApiVersion to a range that includes capability contracts introduced in core 10.0.1.
• Invoke capability:v1:scheduler.create with schedule defaults and the existing generated CLI tool prompt.
• Use the prompt Run \bun src/cli.ts nr fetch_evaluate '{}'` to fetch and evaluate the user's Nostr posts.`
• Store the returned complete CapabilityResourceRef in NR persistence.
• Display registered schedule status in NR.
• Add Show scheduled job using capability:v1:scheduler.show with the stored provider ID and resource ID.
• Handle missing provider by opening plugin manager with capability:scheduler:v1.
• Handle stale or removed provider references without preventing NR from loading.

9. Verification And Rollout

• Run targeted ESLint on the capability-related core and plugin files.
• Run root TypeScript checking after shared contract and BotPlugin changes.
• Manually verify registration with no providers, one provider, and two providers.
• Manually verify chooser icons, aliases, explicit selection, and stale consumer-owned provider IDs.
• Manually verify missing-provider plugin-manager filtering.
• Manually verify Job draft review, schedule creation, NR resource persistence, and Job detail reopening.
• Manually verify a due Job executes NR through the existing CLI tool path.
• Verify existing commands, AI tools, generated skills, and web widgets still work.
• Signal restart.requested after native core or plugin changes are ready.
• Update affected module READMEs and local docs after implementation is stable; use Memory for committed documentation discovery. This supersedes the declined bottom-up regeneration step.

Remaining Work

• Update Job and NR package compatibility ranges for the scheduler:v1 contract introduced in core 10.0.1.
• Manually exercise provider registration with zero, one, and two scheduler providers.
• Verify chooser metadata, explicit selection, stale provider IDs, and catalog filtering in the Web UI.
• Complete the Job draft, creation, persistence, detail reopening, and due-run flow through NR's existing CLI tool.
• Smoke-test existing commands, AI tools, generated skills, and web widgets for regressions.

10. Translation V1 And AI Translate

• Add a provider-neutral translation:v1 contract with BCP 47 source and target languages.
• Keep AI backend and model settings outside the capability contract.
• Register AI Translate as a translation:v1 provider.
• Add optional backend and model settings with current-default fallback.
• Add the model-options datalist used by the regular Web settings form.
• Add the translate command for plain text and Markdown.
• Accept standard structured and flat JSON payloads when the command source is Web.
• Use isolated backend sessions with runtime context disabled for translation.
• Add a generic translation icon action to nostrPost cards.
• Let NR invoke translation:v1 for post content with automatic source-language detection.
• Store NR's optional translation target language and default it to English.

Deferred Work

• Pending capability-request continuation after plugin installation and restart.
• Provider-specific settings navigation from the chooser.
• Capability invocation audit UI.
• Hard startup blocking for missing requires relations.
• Process isolation or sandboxing for installed providers.