@tai42/studio-sdk 20.0.0 → 21.0.0

package/src/hooks/useCapabilities.ts

@@ -131,8 +131,8 @@ export function isFullProjection(projection: MeProjection): boolean {
 
 /**
  * Whether a concrete path is `prefix` itself or nested beneath it at a PATH-SEGMENT
- * boundary — the client mirror of the server's segment-aware coverage rule
- * (access_control/settings.py: `a == b or a.startswith(b + '/')`). Matching on a
+ * boundary — the client mirror of the server's segment-aware coverage rule, held to
+ * the platform's published path-coverage vectors by the shell's tests. Matching on a
  * bare `startsWith` would let a sibling route like `/api/tools-schema` satisfy the
  * `/api/tools` token; the boundary keeps them distinct.
  */
@@ -144,22 +144,18 @@ function pathUnderPrefix(path: string, prefix: string): boolean {
  * Whether the projection reaches ANY route under one of `prefixes` — the
  * declarative test behind nav filtering and plugin `requiredCapabilities`. A
  * concrete `routes[].path` covers a prefix when it is that prefix or a
- * segment-nested descendant of it; a dynamic `route_patterns[].pattern` covers a
- * prefix only when it is a simple anchored open-wildcard pattern (`^<literal>.*$`)
- * whose open literal overlaps the prefix at a segment boundary.
- *
- * Under-showing is safe (projection is UX; the server is the authority);
- * over-showing is the bug. So any non-anchored or otherwise complex pattern
- * (alternation, char class, bounded quantifier) is conservatively treated as NOT
- * covering — its matched set is not a clean prefix, so we never infer reach from
- * it.
+ * segment-nested descendant of it; a dynamic `route_patterns[]` entry covers a
+ * prefix through its served `open_prefix` — the literal the server rules every
+ * path starting with is reachable — when it overlaps the prefix at a segment
+ * boundary. A `null` open prefix (a pattern whose matched set is not a clean
+ * prefix) covers nothing by prefix: under-showing is safe, over-showing is the bug.
  */
 export function coversAnyRoute(projection: MeProjection, prefixes: readonly string[]): boolean {
   return prefixes.some(
     (prefix) =>
       projection.routes.some((route) => pathUnderPrefix(route.path, prefix)) ||
       projection.route_patterns.some((entry) => {
-        const open = patternOpenPrefix(entry.pattern);
+        const open = entry.open_prefix;
         // The open literal L means "every path starting with L is reachable". That
         // set reaches something under `prefix` when the prefix itself lies in it
         // (`prefix.startsWith(open)`) or when the literal already dives under the
@@ -221,22 +217,3 @@ export function useCanWrite(path: string, method = 'POST'): boolean {
   const { state } = useCapabilities();
   return coversWrite(state, path, method);
 }
-
-const REGEX_METACHARACTERS = /[.*+?()[\]{}|\\^$]/;
-
-/**
- * The literal prefix of a simple anchored open-wildcard pattern (`^<literal>.*$`,
- * the `$` optional), or `null` when the pattern is not exactly that shape. A
- * returned literal `L` means "every path starting with `L` is reachable"; only
- * that open-wildcard form yields a sound prefix, so a bare literal, an
- * alternation, a char class, or any other construct declines (returns `null`).
- */
-function patternOpenPrefix(pattern: string): string | null {
-  if (!pattern.startsWith('^')) return null;
-  let body = pattern.slice(1);
-  if (body.endsWith('$')) body = body.slice(0, -1);
-  if (!body.endsWith('.*')) return null;
-  body = body.slice(0, -2);
-  if (body.length === 0 || REGEX_METACHARACTERS.test(body)) return null;
-  return body;
-}

package/src/host.ts

@@ -5,6 +5,7 @@
  * carries no way to forge, wipe, or enumerate the registry. Only the host bundle
  * imports this. See SECURITY.md for the trust boundary.
  */
+export { contributionCovered } from './plugin/coverage';
 export type {
   LoadedPlugin,
   PluginContributionsSnapshot,
@@ -16,4 +17,5 @@ export {
   subscribePluginHost,
   usePluginContributions,
 } from './plugin/host-state';
+export type { PluginLoadInputs } from './plugin/registry';
 export { getContributions, loadPlugin } from './plugin/registry';

package/src/index.ts

@@ -41,6 +41,7 @@ import './components/components.css';
 
 // -- Plugin API --------------------------------------------------------------
 export type {
+  ChannelConversationRoute,
   NavEntryContribution,
   NavEntrySection,
   PageContribution,
@@ -51,8 +52,11 @@ export type {
   PluginPageProps,
   RegisteredNavEntry,
   RegisteredPage,
+  RegisteredRoutePanel,
   RegisteredSettingsTab,
   RequiredCapabilities,
+  RoutePanelContribution,
+  RoutePanelProps,
   SettingsTabContribution,
   SettingsTabProps,
   ToolPanelContribution,
@@ -60,6 +64,8 @@ export type {
 } from './plugin/types';
 export type { VersionGateResult } from './plugin/version';
 export { checkPluginApiVersion, STUDIO_PLUGIN_API_VERSION } from './plugin/version';
+/** What `useApi().runTool` resolves with: the run-tool door's answer, read by its `kind`. */
+export type { RunAnswer } from '@tai42/api-client';
 
 // -- Hooks -------------------------------------------------------------------
 export type { ApiClient } from './hooks/useApi';
@@ -133,6 +139,8 @@ export {
 
 // -- Utilities ---------------------------------------------------------------
 export { downloadBlob } from './download';
+export type { EnvRef } from './env-markers';
+export { collectEnvRefs, ENV_MARKER_PREFIX, formatEnvMarker, parseEnvMarker } from './env-markers';
 export { errorMessage } from './errors';
 
 // -- Disabled-feature idiom (one helper + component, every consumer) ----------
@@ -292,11 +300,18 @@ export type { HeadingLevel, MarkdownBlock, MarkdownProps } from './components/ma
 export { Markdown, parseMarkdown } from './components/markdown';
 export type { OpenTargetOptions, OpenTargetProps } from './components/open-target';
 export { openTargetProps } from './components/open-target';
-export type { MediaImageProps } from './components/served-media';
+export type {
+  MediaDocumentProps,
+  MediaImageProps,
+  MediaPlayerProps,
+  ServedMediaGrammar,
+} from './components/served-media';
 export {
   isRenderableMediaSrc,
   isServedMediaUrl,
+  MediaDocument,
   MediaImage,
+  MediaPlayer,
   resolveMediaSrc,
 } from './components/served-media';
 // The URL half of the link-safety pair: `isSafeHttpUrl` answers yes/no, this one
@@ -313,7 +328,6 @@ export {
   groupByKind,
   groupIntoFamilies,
   kindVariant,
-  NON_STACKABLE_KIND,
 } from './components/extension-grouping';
 export type { ExtensionPickerProps } from './components/extension-picker';
 export { ExtensionPicker } from './components/extension-picker';

package/src/plugin/coverage.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether a plugin contribution is visible under a capability projection — the one
+ * evaluator every host surface applies to a contribution's optional
+ * `requiredCapabilities`. Host-only (`@tai42/studio-sdk/host`).
+ */
+import type { MeProjection } from '@tai42/api-client';
+
+import { coversAnyRoute, isFullProjection } from '../hooks/useCapabilities';
+import type { RequiredCapabilities } from './types';
+
+/**
+ * A full projection shows every contribution; an ABSENT requirement renders only for a
+ * full projection (safe-by-default); a declared requirement renders when the projection
+ * reaches at least one of its routes.
+ */
+export function contributionCovered(
+  projection: MeProjection,
+  required: RequiredCapabilities | undefined,
+): boolean {
+  if (isFullProjection(projection)) return true;
+  if (required === undefined) return false;
+  return coversAnyRoute(projection, required.routes);
+}

package/src/plugin/registry.ts

@@ -14,7 +14,9 @@ import type {
   PluginEntry,
   RegisteredNavEntry,
   RegisteredPage,
+  RegisteredRoutePanel,
   RegisteredSettingsTab,
+  RoutePanelContribution,
   SettingsTabContribution,
   ToolPanelContribution,
 } from './types';
@@ -23,6 +25,18 @@ const toolPanels = new Map<string, ToolPanelContribution>();
 const pages: RegisteredPage[] = [];
 const settingsTabs: RegisteredSettingsTab[] = [];
 const navEntries: RegisteredNavEntry[] = [];
+const routePanels = new Map<string, RegisteredRoutePanel>();
+
+/**
+ * What the host knows about a plugin from its registry listing entry: `mounts`, the
+ * plugin's own route items and their resolved absolute bases (`{item: "/api/<base>"}`),
+ * and `declaredRoutePanels`, the channels its manifest lists under
+ * `contributions.route_panels`.
+ */
+export interface PluginLoadInputs {
+  readonly mounts: Readonly<Record<string, string>>;
+  readonly declaredRoutePanels: readonly string[];
+}
 
 /** The contributions one plugin stages before they commit as a batch. */
 interface StagedContributions {
@@ -31,6 +45,7 @@ interface StagedContributions {
   readonly settingsTabs: RegisteredSettingsTab[];
   readonly tabIds: Set<string>;
   readonly navEntries: RegisteredNavEntry[];
+  readonly routePanels: Map<string, RegisteredRoutePanel>;
 }
 
 /**
@@ -48,6 +63,7 @@ function emptyStaged(): StagedContributions {
     settingsTabs: [],
     tabIds: new Set(),
     navEntries: [],
+    routePanels: new Map(),
   };
 }
 
@@ -63,6 +79,7 @@ function makeStagingContext(
   pluginId: string,
   staged: StagedContributions,
   seal: Seal,
+  host: PluginLoadInputs,
 ): PluginContext {
   const assertOpen = (): void => {
     if (seal.closed) {
@@ -120,6 +137,16 @@ function makeStagingContext(
       }
       staged.navEntries.push({ ...contribution, pluginId });
     },
+    registerRoutePanel(contribution: RoutePanelContribution): void {
+      assertOpen();
+      if (staged.routePanels.has(contribution.channel) || routePanels.has(contribution.channel)) {
+        throw new Error(`a route panel is already registered for channel ${contribution.channel}`);
+      }
+      staged.routePanels.set(contribution.channel, { ...contribution, pluginId });
+    },
+    routeBase(itemName: string): string | null {
+      return Object.hasOwn(host.mounts, itemName) ? (host.mounts[itemName] ?? null) : null;
+    },
   };
 }
 
@@ -142,6 +169,27 @@ function assertNavEntriesHavePages(pluginId: string, staged: StagedContributions
   }
 }
 
+/**
+ * The channels a plugin registered route panels for must be exactly the channels its
+ * manifest declares: a bundle and its manifest are built together, so a mismatch is a
+ * build fault. Throwing BEFORE any commit keeps atomicity.
+ */
+function assertRoutePanelsDeclared(
+  pluginId: string,
+  staged: StagedContributions,
+  declared: readonly string[],
+): void {
+  const registered = [...staged.routePanels.keys()].sort();
+  const manifest = [...new Set(declared)].sort();
+  const same =
+    registered.length === manifest.length && registered.every((c, i) => c === manifest[i]);
+  if (!same) {
+    throw new Error(
+      `plugin “${pluginId}” registered route panels [${registered.join(', ')}] but its manifest declares [${manifest.join(', ')}]`,
+    );
+  }
+}
+
 /**
  * Commit the staged contributions as one batch, so the registry only ever holds a
  * plugin's complete set — never a partial set left behind by a mid-registration failure.
@@ -151,6 +199,7 @@ function commitStaged(staged: StagedContributions): void {
   for (const [toolName, contribution] of staged.toolPanels) toolPanels.set(toolName, contribution);
   for (const tab of staged.settingsTabs) settingsTabs.push(tab);
   for (const navEntry of staged.navEntries) navEntries.push(navEntry);
+  for (const [channel, panel] of staged.routePanels) routePanels.set(channel, panel);
 }
 
 /**
@@ -164,10 +213,14 @@ function commitStaged(staged: StagedContributions): void {
  * during `entry`'s synchronous body — including a microtask it enqueues then — are
  * still captured and committed. A `register` that throws commits nothing.
  */
-export async function loadPlugin(pluginId: string, entry: PluginEntry): Promise<void> {
+export async function loadPlugin(
+  pluginId: string,
+  entry: PluginEntry,
+  host: PluginLoadInputs,
+): Promise<void> {
   const staged = emptyStaged();
   const seal: Seal = { closed: false };
-  const context = makeStagingContext(pluginId, staged, seal);
+  const context = makeStagingContext(pluginId, staged, seal, host);
 
   try {
     await entry(context);
@@ -178,12 +231,13 @@ export async function loadPlugin(pluginId: string, entry: PluginEntry): Promise<
   }
 
   assertNavEntriesHavePages(pluginId, staged);
+  assertRoutePanelsDeclared(pluginId, staged, host.declaredRoutePanels);
   commitStaged(staged);
 }
 
 /** The shell reads this after loading every installed plugin bundle. */
 export function getContributions(): PluginContributions {
-  return { toolPanels, pages, settingsTabs, navEntries };
+  return { toolPanels, pages, settingsTabs, navEntries, routePanels };
 }
 
 /** Tests reset the module-level registry between cases. */
@@ -192,4 +246,5 @@ export function __resetContributions(): void {
   pages.length = 0;
   settingsTabs.length = 0;
   navEntries.length = 0;
+  routePanels.clear();
 }

package/src/plugin/types.ts

@@ -2,7 +2,7 @@
  * The Studio-plugin authoring contract. A platform plugin ships an ESM bundle
  * that exports a `register(context)` entry ({@link PluginEntry}); the host calls
  * it with a {@link PluginContext} through which the plugin contributes tool
- * panels, pages, settings tabs, and sidebar nav entries.
+ * panels, pages, settings tabs, sidebar nav entries and conversation route panels.
  *
  * Two styling paths are sanctioned, and only these two:
  *  1. SDK components plus inline styles that read the design-system tokens
@@ -20,6 +20,7 @@
  *     its own. Bundled third-party base CSS is exempt from rule (c) but rules
  *     (a) and (b) still bind it.
  */
+import type { ConversationRouteView } from '@tai42/api-client';
 import type { ComponentType } from 'react';
 
 /**
@@ -219,12 +220,43 @@ export interface RegisteredSettingsTab extends SettingsTabContribution {
   readonly pluginId: string;
 }
 
+/** A conversation route row as `GET /api/conversations` lists it, on the `channel` door. */
+export type ChannelConversationRoute = Extract<ConversationRouteView, { readonly door: 'channel' }>;
+
+/** Props a contributed route panel receives. */
+export interface RoutePanelProps {
+  readonly pluginId: string;
+  /** The route row the panel decorates; its `channel` is the contribution's channel. */
+  readonly route: ChannelConversationRoute;
+}
+
+/**
+ * A panel the conversations drill-in renders above the thread list of every route on
+ * one channel. One panel per channel deployment-wide.
+ */
+export interface RoutePanelContribution {
+  /** The channel name whose routes this panel decorates (`ConversationRouteView.channel`). */
+  readonly channel: string;
+  /** Names the panel region (its aria-label and the error card label). */
+  readonly title: string;
+  readonly component: ComponentType<RoutePanelProps>;
+  /** Capability gate (see {@link RequiredCapabilities}); absent ⇒ full-only. */
+  readonly requiredCapabilities?: RequiredCapabilities;
+}
+
+/** A route panel as stored in the registry, stamped with the plugin that registered it. */
+export interface RegisteredRoutePanel extends RoutePanelContribution {
+  readonly pluginId: string;
+}
+
 /** Everything a single plugin bundle has registered at import time. */
 export interface PluginContributions {
   readonly toolPanels: ReadonlyMap<string, ToolPanelContribution>;
   readonly pages: readonly RegisteredPage[];
   readonly settingsTabs: readonly RegisteredSettingsTab[];
   readonly navEntries: readonly RegisteredNavEntry[];
+  /** Route panels keyed by the channel they decorate. */
+  readonly routePanels: ReadonlyMap<string, RegisteredRoutePanel>;
 }
 
 /**
@@ -250,6 +282,18 @@ export interface PluginContext {
    * registers (a nav entry with no page is a dead link and is rejected loudly).
    */
   registerNavEntry(contribution: NavEntryContribution): void;
+  /**
+   * Register a panel for the routes of one channel. The plugin's manifest must list the
+   * same channels under `contributions.route_panels`, or the plugin fails to load.
+   */
+  registerRoutePanel(contribution: RoutePanelContribution): void;
+  /**
+   * The resolved absolute base of one of this plugin's route items, e.g. `/api/channels/web`,
+   * or `null` when the item has no mount on this deployment (an optional router not listed, a
+   * channel not loaded). Never throws; a feature that needs the base shows its own unavailable
+   * state for `null`. Call it during `register` and keep the value.
+   */
+  routeBase(itemName: string): string | null;
 }
 
 /**

package/src/state-binding/README.md

@@ -9,12 +9,14 @@ it; holds no edge to jq (the jq fields render through the host's ambient
 
 - **template `input` jq** — input is the record (`.`), declared params bound as
   `$params`; returns the injected value.
-- **custom injection jq** — over `{ record, input }`; returns the value placed at `into`.
-- **adapter** — over `{ output, input }`; CONSTRUCTS the update jq's declared input
-  object.
-- **template `update` jq** — over `{ record, input }` where `input` is the adapter's
-  output; returns a template-relative op batch.
-- **custom `update` jq** — over `{ record, output, input }`; returns `[{op, path, value}]`.
+- **custom injection jq** — over the record (`.`), the run input bound as `$input`; returns
+  the value placed at `into`.
+- **adapter** — over the tool output (`.`), the run input bound as `$input`; CONSTRUCTS the
+  update jq's declared input object.
+- **template `update` jq** — over the record subtree (`.`), the adapter's output bound as
+  `$input`; returns a template-relative op batch.
+- **custom `update` jq** — over the tool output (`.`), the run input bound as `$input` and the
+  record as `$record`; returns `[{op, path, value}]`.
 - **`subject_expr`** — a jq yielding the record KEY: a bare key string, or a full subject object.
 - **`scope_expr`** — optional; a boolean jq predicate. When it is false, the state is skipped for the run.
 
@@ -28,7 +30,8 @@ canonical, parseable object so a stored adapter reopens as the form it was autho
 ```
 
 - `<key>` — a bare identifier, or a JSON string when it is not one.
-- `<value>` — one of: a field path (`.output…` / `.input…`), a JSON literal, or a raw
+- `<value>` — one of: a field path (an output field `.…`, the whole output `.`, an input
+  field `$input…`), a JSON literal, or a raw
   jq expression, each wrapped in `(…)`.
 
 `parseAdapter` inverts it: `parseAdapter(compileAdapter(rows).jq) === rows` for every

package/src/state-binding/UpdateRow.tsx

@@ -1,8 +1,8 @@
 /**
  * The update list of one attached state. Each update applies AFTER the run: either
  * a template `update` jq (picked by name, whose declared input is authored through
- * the adapter mapping) or a custom jq over `{ record, output, input }` that authors
- * the whole op batch itself. An optional op-id expression carries idempotency.
+ * the adapter mapping) or a custom jq over the tool output (its `.`, with the run input
+ * bound as `$input` and the record as `$record`) that authors the whole op batch itself. An optional op-id expression carries idempotency.
  */
 import type { ReactNode } from 'react';
 
@@ -114,7 +114,7 @@ function UpdateRowEditor({
         <BindingTemplatedJqField
           label={`Custom update jq ${String(index + 1)}`}
           required
-          description="A jq over `{ record, output, input }` returning a template-relative op batch."
+          description="A jq over the tool output (`.`), with `$input` and `$record` bound, returning a template-relative op batch."
           value={update.jq}
           onChange={(next) => {
             onChange({

package/src/state-binding/adapter.ts

@@ -3,9 +3,9 @@
  *
  * A named template `update` jq declares an input object (its `params` / declared
  * input keys). A binding must map the run's OUTPUT (and the run's INPUT) into that
- * object; that mapping is the `adapter` — a single jq program over `{ output, input }`
- * that CONSTRUCTS the update jq's declared input (which the update jq then reads as
- * `.input` alongside the record).
+ * object; that mapping is the `adapter` — a single jq program over the tool output
+ * (its `.`) with the run input bound as `$input`, that CONSTRUCTS the update jq's
+ * declared input (which the update jq then reads as `$input`, over the record).
  *
  * The editor authors the adapter as a ROW form: one row per declared input key,
  * each row picking one of three value sources — a picked field (from the run's
@@ -17,10 +17,10 @@
  * object.
  */
 
-/** Which root of `{ output, input }` a picked field reads. */
+/** Which value a picked field reads: the tool output (the program's `.`) or the run input (`$input`). */
 export type FieldRoot = 'output' | 'input';
 
-/** A picked field: a path into `output` or `input`. */
+/** A picked field: a path into the tool output or the run input. */
 export interface FieldSource {
   readonly kind: 'field';
   readonly root: FieldRoot;
@@ -33,7 +33,7 @@ export interface LiteralSource {
   readonly json: string;
 }
 
-/** A raw jq expression over `{ output, input }`. */
+/** A raw jq expression over the tool output (its `.`), with the run input bound as `$input`. */
 export interface JqSource {
   readonly kind: 'jq';
   readonly expr: string;
@@ -59,13 +59,19 @@ export function jqKey(key: string): string {
   return IDENTIFIER.test(key) ? key : JSON.stringify(key);
 }
 
-/** A picked field rendered as a jq path, e.g. `.output.user.name` / `.input["odd key"]`. */
+/**
+ * A picked field rendered as a jq path: an output field reads off the program root
+ * (`.user.name`, `.["odd key"]`, the whole output `.`), an input field off the bound run
+ * input (`$input.user.name`, the whole input `$input`).
+ */
 export function fieldPathToJq(root: FieldRoot, path: readonly string[]): string {
-  let out = `.${root}`;
+  let out = root === 'input' ? '$input' : '';
   for (const segment of path) {
-    out += IDENTIFIER.test(segment) ? `.${segment}` : `[${JSON.stringify(segment)}]`;
+    out += IDENTIFIER.test(segment)
+      ? `.${segment}`
+      : `${out === '' ? '.' : ''}[${JSON.stringify(segment)}]`;
   }
-  return out;
+  return out === '' ? '.' : out;
 }
 
 /** The jq fragment ONE row's value compiles to — the row's "show jq". */
@@ -95,7 +101,7 @@ export function rowValueJq(source: MappingSource): AdapterCompileResult {
 
 /**
  * Compile a mapping form into ONE adapter jq that constructs the update jq's
- * declared input over `{ output, input }`. An empty form compiles to the
+ * declared input over the tool output and `$input`. An empty form compiles to the
  * empty object `{}`; a blank target, a duplicate target, or an invalid source is a
  * loud error.
  */
@@ -128,7 +134,7 @@ export function defaultRowsForInput(params: readonly string[]): MappingRow[] {
 // `compileAdapter` emits a canonical, PARSEABLE shape so a stored adapter reopens as
 // the form it was authored in (never UI-only state): the object
 // `{ <key>: (<value>), … }` where `<key>` is a bare identifier or a JSON string and
-// `<value>` is one of — a field path `.output…` / `.input…`, a JSON literal, or a raw
+// `<value>` is one of — a field path `.…` (output) / `$input…` (input), a JSON literal, or a raw
 // jq expression. `parseAdapter` inverts it; `parse(compileAdapter(rows).jq) === rows`
 // for every row kind whose literal is already canonical JSON. A shape it does not
 // recognise returns `null` — the editor falls back to the raw-jq escape hatch.
@@ -139,10 +145,19 @@ const ADAPTER_KEY = /^("(?:[^"\\]|\\.)*"|[A-Za-z_][A-Za-z0-9_]*)\s*:\s*\(/;
 
 /** Recover a field source from a pure path expression, or `null` if it is not one. */
 export function parseFieldPath(value: string): FieldSource | null {
-  const head = /^\.(output|input)/.exec(value);
-  if (head === null) return null;
-  const root = head[1] as FieldRoot;
-  let rest = value.slice(head[0].length);
+  let root: FieldRoot;
+  let rest: string;
+  if (value === '.') return { kind: 'field', root: 'output', path: [] };
+  if (value.startsWith('$input')) {
+    root = 'input';
+    rest = value.slice('$input'.length);
+  } else if (value.startsWith('.')) {
+    root = 'output';
+    // A root bracket (`.["odd key"]`) drops its leading dot; a root key keeps it (`.a`).
+    rest = value.startsWith('.[') ? value.slice(1) : value;
+  } else {
+    return null;
+  }
   const path: string[] = [];
   while (rest.length > 0) {
     if (rest.startsWith('.')) {