@matatbread/matbot-plugin-api 0.3.8 → 0.4.0

package/src/types/typescript.ts

@@ -0,0 +1,50 @@
+// ── TypeScript ──────────────────────────────────────────────────────────────
+
+/**
+ * Erases TypeScript types from a source string, returning runnable JavaScript. Type-stripping is
+ * foundational — the harness ships raw `.ts` and any code compiled at runtime must have its types
+ * removed before it can execute — so every execution environment provides one, and it lives as a fixed
+ * runtime capability (on {@link MatbotRuntime}) the host supplies per platform, not a swappable service:
+ * node uses its built-in `stripTypeScriptTypes`, the browser bundle uses sucrase. A consumer that
+ * compiles source at runtime (e.g. `tool_function`) calls this instead of importing a platform stripper.
+ *
+ * `strip` may be async: a platform whose stripper loads lazily (the browser fetches sucrase on first use)
+ * returns a promise; a synchronous stripper (node) returns the string directly — callers `await` either.
+ * It is type-erasure, not full transpilation: node's stripper is erasable-only (enums/namespaces throw),
+ * sucrase is more permissive, so authors should keep to erasable TypeScript to stay portable.
+ */
+export interface TypeScriptStripper {
+  strip(source: string): string | Promise<string>;
+}
+
+/**
+ * Optional, node-only developer-experience service: the live `.d.ts` of the types the loaded tools
+ * expose — what `toolResult(invokeTool(…, name, …))`, or a `function-tools` `await tool.name(…)`, resolves
+ * to — derived by compiling each loaded plugin's `declare module '@matatbread/matbot-plugin-api'`
+ * augmentations. The runtime registry can't supply this (result types are erased); only a TypeScript
+ * program reading the source can. Consumers that generate or compose tool-calling code use it so the model
+ * isn't guessing return shapes. Absent where no TypeScript program can run (the browser today) — a consumer
+ * must degrade (guess-and-run) when `services.ToolTypeIndex` is undefined.
+ *
+ * The result is rebuilt lazily and cached, invalidated when the tool set changes. Tools the source scan
+ * can't reach (a `function-tools` function) contribute their types by declaring a `toolContract` string on
+ * their registered {@link Tool} — identical in shape to a `ToolContracts` arm; the index splices it off the
+ * live registry, so no separate registration step is needed.
+ */
+export interface ToolTypeIndex {
+  /** Self-contained type declarations as a `.d.ts` string: the source-derived `ToolContracts` augmentations
+   *  merged with the arms of every other live tool, plus `declare const tool: ToolProxy` — the overloaded
+   *  proxy a generator writes `await tool.x(params)` against. */
+  dts(): Promise<string>;
+  /** Type-check a TypeScript `snippet` against exactly the {@link dts} above — the `tool` proxy ({@link
+   *  ToolProxy}: each multi-action tool an overload set, so `await tool.x(params)` narrows its result by the
+   *  params) is in scope. Returns human-readable diagnostics scoped to the snippet ([] means clean). A
+   *  composer uses it to catch bad tool-call code before running/registering it. */
+  check(snippet: string): Promise<string[]>;
+  /** Per live tool (that has a contract): the `params`/`result` wire text, flattened from the one contract —
+   *  a source tool's `ToolContracts` arms (via the source scan) or a source-less tool's `toolContract` string.
+   *  The single contract is thus also the source of the wire description; the host folds this into the
+   *  outgoing tool descriptions at the turn's dispatch edge. A tool with only a loose `inputSchema` (no
+   *  contract) is absent. */
+  wireContracts(): Promise<Record<string, { params: string; result: string }>>;
+}

package/src/types/vault.ts

@@ -0,0 +1,37 @@
+// ── Vault ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The primitives a vault backend must implement. Resolution, redaction, and the three
+ * low-level store operations the smart `createSecret` policy composes. A backend implements
+ * `Vault` (which is `VaultSpec` plus that policy); plugins are handed a `Vault`.
+ */
+export interface VaultSpec {
+  /** Resolve ${NAME} placeholders by looking up the named value; throws MissingSecretError for any miss. */
+  resolve(ref: string): Promise<string>;
+  scrub(text: string): string;
+  /**
+   * Store `value` under exactly `name`, overwriting. The literal write; no reference/dedup logic.
+   * An empty `value` removes the key instead — there is no such thing as an empty secret, so the
+   * empty string is the removal signal (idempotent: removing an absent name is a no-op).
+   */
+  writeSecret(name: string, value: string): Promise<void>;
+  /** Whether a secret is stored under this exact name. */
+  hasKey(name: string): boolean;
+  /**
+   * The name a value is already stored under, if any. Optional: backends that can't (or won't)
+   * reverse-index omit it, and `createSecret`'s dedup step is skipped.
+   */
+  findByValue?(value: string): string | undefined;
+}
+
+export interface Vault extends VaultSpec {
+  /**
+   * Store a secret coming (often) from a user via the LLM, where we cannot tell a real value
+   * from a key name they typed by mistake. Returns the key name callers MUST reference — not
+   * necessarily the `name` requested:
+   *   - `value` is already a known key name → returns `value` (it was a reference, not a secret)
+   *   - `value` already stored under another name → returns that name (dedup)
+   *   - otherwise → writes under `name` and returns `name`
+   */
+  createSecret(name: string, value: string): Promise<string>;
+}