@mercury-fw/kit 0.53.2 → 0.55.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @mercury-fw/kit
 
+## 0.55.0
+
+### Minor Changes
+
+- eac72fa: Every plugin says what it lets the agent do, and the agent can tell. Plugin contract version 6:
+
+  - A plugin declares a `description`: one sentence, in English, for the model, on what it lets the assistant do (`{{assistant}}` stands for its name). How to use it stays in its fragment and skills.
+  - The core doesn't load a plugin whose description is missing, blank or more than one line, and the log says why.
+  - The system prompt lists the plugins offered to the person, each with its description, right after the persona's identity, and tells the model to answer "what can you do?" from that list. A plugin the person may not use isn't listed; with no plugin offered there's no list.
+  - The first-party plugins released with this change carry a description each, are written for contract 6 and need the framework at 0.55.0 or later: the peer range on `@mercury-fw/plugin-types` starts there.
+
+  A plugin written for contract 5 isn't loaded by this core, and the log says why: add a `description` and rebuild it against `PLUGIN_API_VERSION` 6.
+
+### Patch Changes
+
+- Updated dependencies [eac72fa]
+  - @mercury-fw/plugin-types@0.55.0
+  - @mercury-fw/channel-types@0.55.0
+
+## 0.54.0
+
+### Patch Changes
+
+- Updated dependencies [e00ff73]
+- Updated dependencies [5015642]
+  - @mercury-fw/channel-types@0.54.0
+  - @mercury-fw/plugin-types@0.54.0
+
 ## 0.53.2
 
 ### Patch Changes

package/README.md

@@ -23,8 +23,14 @@ An app then runs `mfw credentials setup <plugin>`, which runs `setup` in a one-o
 
 A plugin also says whose identity its tools act with (`actsAs`). `"person"`: the person the turn is for, who logs in to the service through Mercury; the plugin contributes a `login` (`start` and `complete`, which `createCliPersonLogin` from `@mercury-fw/cli-engine` builds for a CLI with a two-step remote login), and its tools get the person and `requireLogin` in their context (`createCliTool` takes both, adds `--user` to every command and asks for the login when the CLI exits with code 3). `"mercury"`, or nothing declared: Mercury's own identity, whoever asks, which only someone allowed to make Mercury act as itself may use: a person holding `mercury.act-as-self` (every plugin) or `mercury.act-as-self.<plugin>` (that one), and the terminal. Those people also get each tool of a plugin acting as the person a second time, as `<tool>AsSelf`, run with Mercury's identity. `"anyone"`: no identity at all, for a public service with no login (web search, for example). Everyone gets such a plugin, with no second version of its tools, and its tools still get the person the turn is for (on the terminal, the operator), to keep what belongs to each one; they can't ask for a login. Roles come from the directory the app declares (`DirectoryPlugin` in the channel contract: given who a channel says is talking, it returns the person and their roles, or `null` for someone it doesn't know).
 
+Every plugin says what it lets the agent do in its `description`: one sentence, in English, for the model. The system prompt lists the plugins offered to the person with their descriptions, and the model answers "what can you do?" from that list. It says what, never how: how to use the plugin belongs to its fragment and skills. The core doesn't load a plugin without one.
+
 The assistant has the name the app gives it (`persona.name`), so a plugin never writes one into what the model reads. Its fragment, its skills and its tools' descriptions say `{{assistant}}`, which the core replaces with that name. A text the plugin builds while running gets the name as `assistantName` in its `build()` context (a channel gets it in its runtime context too). Where the one acting is the system around the model (a list it appends, an account it picks), the text says "the system" and no name at all.
 
+What a plugin shows the person in its own words (a status line while its tool runs, a choice's label, a heading it adds) is written once, in English, in the plugin's `messages`, every key under its name (`web-search.choice.once`); the core refuses a plugin with a key outside it, and `core` and `app` can't be plugin names (their keys are the core's and the app's). While a turn runs the plugin gets `t`, the texts of the person the turn is for, and asks for each text by its key: in `SessionToolContext.t`, as the second argument of a status describer, the third of a post-processor, and in a post-turn guard (`statusLabel(t)`, `run(text, steps, t)`). The app translates the keys in its language files. The core's own keys (`core.…`) are always there, `core.status.command` for a CLI command's default status line among them. This came with version 5 of the plugin contract; version 6 makes the `description` required. A plugin written for an older version isn't loaded, and the log says why.
+
+A channel's texts work the same way (channel contract version 6): its English in `messages`, under its name; `ctx.i18n.forRequest(principal, hint)` gives the texts for a request, in the person's language, else the `hint` (an `Accept-Language` value the channel passes on, also as `InboundTurn.languageHint`), else the app's default. `ctx.confirm` and `ctx.resolveConfirmation` hand back what to tell the person (`{ text, resume? }`), so a channel never words a confirmation itself, and `finalize(text, { pendingNote })` says when the text begins with the core's stand-in for an answer the model didn't write, which a channel showing its own confirmation UI drops.
+
 A proper workflow for writing plugins, with an SDK on top of these contracts, is planned ([#27](https://github.com/lucabro81/mercury-fw/issues/27)).
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/kit",
-  "version": "0.53.2",
+  "version": "0.55.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -27,8 +27,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.53.2",
-    "@mercury-fw/plugin-types": "0.53.2"
+    "@mercury-fw/channel-types": "0.55.0",
+    "@mercury-fw/plugin-types": "0.55.0"
   },
   "devDependencies": {
     "@mercury-fw/typescript-config": "*",