@matatbread/matbot-plugin-api 0.4.12 → 0.4.13

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.12",
+  "version": "0.4.13",
   "engines": {
     "node": ">=24.0.0"
   },

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './bytes.js';
 export * from './store-query.js';
 export * from './errors.js';
 export * from './vault.js';
+export * from './provider-patch.js';
 export * from './session.js';
 export * from './invoke-tool.js';
 

package/src/provider-patch.ts

@@ -0,0 +1,33 @@
+import type { ProviderConfig } from './types.js';
+import type { ProviderPatch } from './types/builtin-tools.js';
+
+/**
+ * The `provider update` policy, written once so every implementer of it behaves identically — the same
+ * reasoning as `applyCreateSecret` in `vault.ts`. Two hosts apply this patch (the node `provider` tool
+ * against matbot.yaml, the browser bootstrap against its persisted map) and the *semantics* of a patch
+ * must not be one of the things they differ on: `null` clears a field, absent leaves it alone.
+ *
+ * `parameters` is replaced wholesale rather than merged per key. Its values are forwarded to the
+ * endpoint unmodified and so have no shape to merge against — and `provider list` reports them in full,
+ * which is what makes a read-modify-write something a caller can actually carry out. (Contrast
+ * `default_settings`, which merges per key: there the keys are matbot's own.)
+ *
+ * `credentials` and `module` are absent from `ProviderPatch` and therefore ride through untouched; see
+ * that type for why neither belongs in an update.
+ */
+export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): ProviderConfig {
+  const next: ProviderConfig = { ...cur };
+  // Spelled out per field rather than looped: `exactOptionalPropertyTypes` makes "assign, or delete if
+  // null" a different statement for each type, and a loop only reaches them through a cast that would
+  // stop the compiler checking the one thing worth checking here.
+  if (patch.model      !== undefined) next.model = patch.model;
+  if (patch.endpoint   !== undefined) { if (patch.endpoint   === null) delete next.endpoint;   else next.endpoint   = patch.endpoint;   }
+  if (patch.parameters !== undefined) { if (patch.parameters === null) delete next.parameters; else next.parameters = patch.parameters; }
+  if (patch.maxRounds  !== undefined) { if (patch.maxRounds  === null) delete next.maxRounds;  else next.maxRounds  = patch.maxRounds;  }
+  return next;
+}
+
+/** The fields a patch actually changes, in a stable order — for a confirmation prompt or a result message. */
+export function patchedFields(patch: ProviderPatch): readonly ('model' | 'endpoint' | 'parameters' | 'maxRounds')[] {
+  return (['model', 'endpoint', 'parameters', 'maxRounds'] as const).filter(f => patch[f] !== undefined);
+}

package/src/types/builtin-tools.ts

@@ -174,6 +174,31 @@ export interface ProviderActionResult {
   message: string;
 }
 
+/**
+ * The fields `provider update` can change on an existing profile, and the whole of them.
+ *
+ * `null` clears a field, absent leaves it alone — `undefined` cannot mean "clear", since it is already
+ * what an unsupplied optional looks like. `model` takes no `null`: a profile without one is unrunnable.
+ *
+ * Two fields are deliberately absent. **`credentials`**, because it is the one member of a profile that
+ * `provider list` does not report back (it projects to `hasCredentials`, and a secret must not ride the
+ * transcript) — so a caller cannot read-modify-write it, and an `update` that accepted it would have to
+ * guess between rewriting a `${NAME}` reference and replacing a literal. Credentials are
+ * `plugin store-key`'s, which addresses the vault name directly. And **`module`**, because changing the
+ * adapter re-opens every resolution question `add` answers (is it loaded, does it resolve by package
+ * name, is it even a provider adapter); `remove` + `add` is the honest route for that.
+ *
+ * A named shape rather than an inline arm because the browser's `ProviderAdmin.update` takes the same
+ * patch, and because it is the augmentable half — a host whose profiles carry an extra field adds it
+ * here without touching `ToolContracts`.
+ */
+export interface ProviderPatch {
+  model?:      string;
+  endpoint?:   string | null;
+  parameters?: ModelParameters | null;
+  maxRounds?:  number | null;
+}
+
 /**
  * The `provider` tool's contract. Both implementations declare `provider: ProviderToolContract`.
  *
@@ -181,6 +206,8 @@ export interface ProviderActionResult {
  * supplies its own, while node's executor requires one; `credentialKey`/`credentialEnvVar` name where
  * node's vault should hold the secret, and the browser (which prompts and stores under its own key)
  * ignores them.
+ *
+ * `update` carries no credential of any kind — see {@link ProviderPatch}.
  */
 export type ProviderToolContract =
   | ToolContract<ProviderListResult,   { action: 'list' }>
@@ -195,4 +222,5 @@ export type ProviderToolContract =
       parameters?:       ModelParameters;
       maxRounds?:        number;
     }>
+  | ToolContract<ProviderActionResult, { action: 'update'; name: string } & ProviderPatch>
   | ToolContract<ProviderActionResult, { action: 'remove'; name: string }>;