From ccb2d4da901f5f7a66c3bf1a43bedef42ce5001d Mon Sep 17 00:00:00 2001 From: Lucas1479 Date: Fri, 23 Oct 2026 20:39:20 +1300 Subject: [PATCH] docs: define connector and complete-plugin installation commitments --- catalog/REVIEW_CHECKLIST.md | 26 ++++++++++++++++ spec/extension-protocol-v0.1.md | 53 +++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) diff --git a/catalog/REVIEW_CHECKLIST.md b/catalog/REVIEW_CHECKLIST.md index d59bb6c..3e7eedc 100644 --- a/catalog/REVIEW_CHECKLIST.md +++ b/catalog/REVIEW_CHECKLIST.md @@ -6,6 +6,22 @@ warranty, an OS sandbox, a permission grant or approval of future versions. Record reviewer, date, policy version, digest and evidence on every version. An author/publisher maintainer cannot be their own reviewer. +- [ ] Identify the package's [installation commitment](../spec/extension-protocol-v0.1.md#821-connector-and-complete-plugin-installation-commitments) + as connector or complete plugin in its documentation and proposed catalog + presentation before installation. Do not infer it from HTTP/stdio or + `runtime.kind`, or require a new manifest field. +- [ ] For a connector, verify that external application/service prerequisites, + compatible versions or protocols, connection configuration and lifecycle owner + are disclosed before installation. Test both a working connection and the + missing/unavailable or incompatible service case; missing/invalid credentials must + remain visible. Installing the connector must not claim to install its service. +- [ ] For a complete plugin, test with an installed, supported Host and only + that Host's documented platform prerequisites. The installation flow must + provision all runtimes, dependencies and assets required for the advertised initial + capability without manual commands, environment preparation, another software + installation or manual background-service startup. Login, API credentials and + model selection may remain user configuration. Check first-use downloads and + setup failures; required deployment must not be hidden as optional setup. - [ ] Fetch the exact wheel, verify digest, and retain its full file inventory. Confirm package ownership/transfer independently of manifest author text or PR account. - [ ] Run the fixed Windows/CPython/Host checker. Record its commit and environment. @@ -33,6 +49,10 @@ An author/publisher maintainer cannot be their own reviewer. - [ ] Review install, use, update, cancellation/close, disable, uninstall/reinstall evidence for this contribution. Label static, process, native Agent, GUI and paid/real-service coverage separately. Do not promise automatic startup rollback. + Verify lifecycle ownership against the installation commitment: a complete + plugin's provisioned processes/components are Host-managed; a connector releases + its own resources without claiming to stop, uninstall or delete the external + service. Distinguish retained data from data explicitly selected for deletion. - [ ] Compare with the previous reviewed wheel using check_catalog.py. Read the complete changed files when the diff is truncated, and review unchanged code as needed. Initial versions require full review; every later version still @@ -41,6 +61,12 @@ An author/publisher maintainer cannot be their own reviewer. - [ ] Record remaining limitations and the independent approval in the review PR. A CI pass alone must never create a reviewed record. +These requirements do not expand curated-v1 artifact or dependency support. +Automatic installation must use an existing supported Host mechanism, not a +package hook, a README/Skill command or an unreviewed installer download. A +complete plugin requiring an unsupported mechanism is ineligible for this +catalog; a connector must be reviewed and presented with its external prerequisite. + For later removal, use copyright withdrawal for asset/license complaints, maintainer withdrawal for ordinary retirement, and security decisions for unsafe artifacts. Do not relabel copyright removal as a security ban or delete user data. diff --git a/spec/extension-protocol-v0.1.md b/spec/extension-protocol-v0.1.md index 8fd0a32..6a425e7 100644 --- a/spec/extension-protocol-v0.1.md +++ b/spec/extension-protocol-v0.1.md @@ -905,6 +905,59 @@ A Host installs a package as one transaction: Installation runs no package hooks. A Host never executes commands from a package's documentation, such as "prerequisites" in a README or `SKILL.md`. +#### 8.2.1 Connector and complete-plugin installation commitments + +Package documentation and any catalog listing MUST identify the installation +commitment before the user confirms installation: **connector** or **complete +plugin**. These describe deployment responsibility, not manifest fields, trust +tiers, transports, or `runtime.kind` values. An HTTP contribution is not, by +itself, evidence of either commitment. + +A **connector** integrates an independently installed or operated application +or service. It MUST disclose the required application/service, compatible +versions or protocol requirements, required connection configuration, and who +owns installation, startup, updates, shutdown and removal of that external +component. Separate setup instructions MAY be linked, but MUST be presented as +external prerequisites before installation, not discovered as hidden plugin +setup afterwards. + +Installing a connector means the connector is installed; it MUST NOT be reported +as a working connection until its required service and configuration are +available. A missing, unreachable or incompatible service, or missing/invalid +credentials, MUST remain visible as an unmet connection requirement. The Host +manages the connector's own resources under [§4](#4-lifecycle), including its +existing rules for draining, secret retention and removal. Disabling or removing +the connector MUST NOT imply that the external service was stopped or +uninstalled, or that its data was deleted. + +A **complete plugin** MUST provision the components needed for its advertised +initial capability through one Host-supported installation flow, starting from +an installed, supported Host and that Host's documented platform prerequisites. +Required local runtimes, executable components, dependencies and assets MUST be +included in that responsibility. +The user MUST NOT need to install another program, prepare a Python environment, +run shell commands or manually maintain a background service to finish the +plugin's deployment. The Host owns installation and the lifecycle of the +provisioned components under [§4](#4-lifecycle). + +One installation flow MAY retrieve multiple declared artifacts; it need not be +one file or one network transfer. The transaction, validation and confirmation +rules in §8.2 still apply. Download or setup failure MUST remain observable and +MUST NOT be reported as completed deployment. An optional feature or model MAY +require a separately disclosed setup flow, but a component required for the +advertised initial capability MUST NOT be labelled optional to avoid this rule. + +Both commitments MAY require explicit user configuration, such as login, API +credentials or model selection. This does not permit manual runtime deployment +to be relabelled as configuration. Installation remains distinct from enabling, +binding, granting authority and becoming ready for work; this section adds no +lifecycle state and does not change those existing boundaries. + +These commitments do not add an installation mechanism or relax a Host profile +or catalog policy. Unsupported runtime/dependency delivery MUST NOT be presented +as supported complete-plugin installation. In particular, neither commitment +permits package install hooks or executing setup instructions from documentation. + ### 8.3 Development mode A developer adds a source directory to the Host. The Host creates the package's