@tai42/api-client 2.0.0 → 4.0.0

package/src/client.ts

@@ -213,12 +213,14 @@ export interface ValidatePresetBody {
  * untouched — there is no full-row replace, so a display-name+tags editor sends
  * ONLY those two keys with no risk to `folder_id`/`hidden`. At least one field must
  * be present. A blank/whitespace-only `display_name` is rejected by the API (422) —
- * callers map an emptied label to `null`, never `""`.
+ * callers map an emptied label to `null`, never `""`. A present `badges` array
+ * replaces the whole overlay set (INFORMATIONAL labels, never an enforced gate).
  */
 export interface ToolMetaPatch {
   readonly display_name?: string | null;
   readonly folder_id?: string | null;
   readonly tags?: readonly string[];
+  readonly badges?: readonly string[];
   readonly hidden?: boolean | null;
 }
 
@@ -234,11 +236,23 @@ export interface StorageUploadBody {
   readonly content_base64?: string;
 }
 
+/**
+ * The thread-list filter set (GET `/api/conversations/{route}/threads` query
+ * params, alongside `page`/`pageSize`). `status` narrows to threads whose newest
+ * record sits in one delivery state; `address` is a SUBSTRING match over the
+ * client address. Both omitted when undefined — an unfiltered listing.
+ */
+export interface ConversationThreadFilters {
+  readonly status?: s.ConversationDeliveryStatus;
+  readonly address?: string;
+}
+
 /**
  * One transcript read (GET `/api/conversations/{route}/transcript` query params).
  * `order` is not a default the caller may skip: `asc` reads the thread from its
  * beginning and `desc` from its newest end, and which one a screen wants is a
- * decision that screen must make.
+ * decision that screen must make. `q` narrows the page to records whose text
+ * matches it (a SUBSTRING), omitted for an unfiltered read.
  */
 export interface ConversationTranscriptQuery {
   readonly routeName: string;
@@ -246,6 +260,20 @@ export interface ConversationTranscriptQuery {
   readonly page: number;
   readonly pageSize: number;
   readonly order: s.TranscriptOrder;
+  readonly q?: string;
+}
+
+/**
+ * A route-scoped message search (GET
+ * `/api/conversations/{route}/messages/search` query params). `q` is the required
+ * needle — a substring over record text, across every thread on the route; `page`
+ * is supplied per-request by the infinite query.
+ */
+export interface ConversationMessageSearchQuery {
+  readonly routeName: string;
+  readonly q: string;
+  readonly page: number;
+  readonly pageSize: number;
 }
 
 /**
@@ -318,12 +346,31 @@ export interface MarketplaceSearchQuery {
  * the same transaction that writes the entry: `env` supplies the values,
  * `secret_keys` marks which land in the secret band. Both omitted for a plain
  * install (no required markers).
+ *
+ * `route_mounts` maps a route-carrying item name to the base prefix its routes
+ * mount under (the default or the operator's remap); `accept_public_routes`
+ * explicitly consents to the routes served without authentication. Omitted for a
+ * plugin that registers no routes.
  */
 export interface MarketplaceInstallBody {
   readonly ref: string;
   readonly version?: string;
   readonly env?: Record<string, string>;
   readonly secret_keys?: string[];
+  readonly route_mounts?: Record<string, string>;
+  readonly accept_public_routes?: boolean;
+}
+
+/**
+ * Body for previewing an install / update (`POST /api/marketplace/install/preview`):
+ * resolves the spec and computes the routes, collisions, and public rows WITHOUT
+ * side effects. `route_mounts` applies base overrides so the operator sees the
+ * effect of a remap before committing.
+ */
+export interface MarketplaceInstallPreviewBody {
+  readonly ref: string;
+  readonly version?: string;
+  readonly route_mounts?: Record<string, string>;
 }
 
 /** Body for uninstalling a plugin. */
@@ -771,11 +818,12 @@ export function createApiClient(config: ApiConfig) {
       routeName: string,
       page: number,
       pageSize: number,
+      filters: ConversationThreadFilters = {},
       signal?: AbortSignal,
     ) =>
       req(`/api/conversations/${encodeSegment(routeName)}/threads`, s.conversationThreadsPage, {
         signal,
-        query: { page, pageSize },
+        query: { page, pageSize, status: filters.status, address: filters.address },
       }),
     // One thread's transcript, caller-scoped, read in the asked-for direction.
     // The `thread_id` rides the QUERY STRING, never the path: it embeds the api
@@ -794,9 +842,19 @@ export function createApiClient(config: ApiConfig) {
             page: query.page,
             pageSize: query.pageSize,
             order: query.order,
+            q: query.q,
           },
         },
       ),
+    // Search every record on a route by text, across threads, newest first. The
+    // needle rides the QUERY (`q`); paging is the infinite query's own window. The
+    // page's `truncated` flag says the match set outran the door's scan cap.
+    searchConversationMessages: (query: ConversationMessageSearchQuery, signal?: AbortSignal) =>
+      req(
+        `/api/conversations/${encodeSegment(query.routeName)}/messages/search`,
+        s.conversationMessageSearchPage,
+        { signal, query: { q: query.q, page: query.page, pageSize: query.pageSize } },
+      ),
     // Send a human message into a thread. The `thread_id` rides the BODY (a POST,
     // never a path segment) — same encode-once reasoning as the transcript read.
     sendConversationThreadMessage: (routeName: string, body: ConversationThreadMessageBody) =>
@@ -1167,6 +1225,15 @@ export function createApiClient(config: ApiConfig) {
       req('/api/marketplace/kinds', s.marketplaceKinds, { signal }),
     listInstalledMarketplacePlugins: (signal?: AbortSignal) =>
       req('/api/marketplace/installed', s.marketplaceInstalled, { signal }),
+    // Preview resolves the spec and computes routes/collisions/public rows with
+    // NO side effects, so the install dialog can show absolute paths, block on a
+    // collision, and surface the public routes before the operator commits.
+    previewMarketplaceInstall: (body: MarketplaceInstallPreviewBody, signal?: AbortSignal) =>
+      req('/api/marketplace/install/preview', s.marketplaceInstallPreview, {
+        method: 'POST',
+        body,
+        signal,
+      }),
     installMarketplacePlugin: (body: MarketplaceInstallBody) =>
       req('/api/marketplace/install', s.marketplaceInstallResult, { method: 'POST', body }),
     uninstallMarketplacePlugin: (body: MarketplaceUninstallBody) =>

package/src/index.ts

@@ -25,12 +25,15 @@ export type {
   ValidatePresetBody,
   ToolMetaPatch,
   StorageUploadBody,
+  ConversationThreadFilters,
   ConversationTranscriptQuery,
+  ConversationMessageSearchQuery,
   ConversationThreadMessageBody,
   MetricsQuery,
   RunsQuery,
   MarketplaceSearchQuery,
   MarketplaceInstallBody,
+  MarketplaceInstallPreviewBody,
   MarketplaceUninstallBody,
 } from './client';
 export type { ApiConfig, RequestOptions } from './http';
@@ -127,6 +130,7 @@ export type {
   ConversationRecordOrigin,
   TranscriptOrder,
   ConversationTranscriptPage,
+  ConversationMessageSearchPage,
   ConversationThreadMode,
   ConversationThreadModeState,
   ConversationThreadMessageSent,
@@ -182,6 +186,8 @@ export type {
   RunSpan,
   RunTrace,
   MarketplaceItem,
+  MarketplaceRouteDecl,
+  MarketplaceRoutesDecl,
   MarketplaceSearchKind,
   MarketplaceSearchGroup,
   MarketplaceSearchRow,
@@ -197,5 +203,11 @@ export type {
   MarketplaceUpgradeAllRow,
   MarketplaceUpgradeAllResult,
   MarketplaceInstallResult,
+  MarketplaceMountedRoute,
+  MarketplacePreviewRoute,
+  MarketplacePreviewItem,
+  MarketplacePreviewCollision,
+  MarketplacePreviewPublicRoute,
+  MarketplaceInstallPreview,
   MarketplaceUninstallResult,
 } from './schemas';

package/src/schemas.ts

@@ -58,10 +58,15 @@ export type ToolMediaResult = z.infer<typeof toolMediaResult>;
  * FastMCP `meta` under `tai42/hidden`; a tool that never declared it is not hidden).
  * The tool_meta overlay's tri-state override is merged on top client-side; this read
  * exposes only the declaration.
+ *
+ * `badges` are the tool's plugin-DECLARED capability labels — purely INFORMATIONAL
+ * (e.g. `network`, `filesystem`), never a gate the server enforces. The overlay's
+ * own badges are merged on top client-side; this read exposes only the declaration.
  */
 export const toolTagEntry = z.object({
   name: z.string(),
   tags: z.array(z.string()),
+  badges: z.array(z.string()),
   hidden: z.boolean(),
 });
 export const toolTags = z.array(toolTagEntry);
@@ -238,7 +243,9 @@ export type FolderRecord = z.infer<typeof folderRecord>;
  * The organizational overlay for one tool, keyed by `tool_name`. `display_name`
  * overrides the rendered label (`display_name ?? name`); `folder_id` places the tool
  * in a folder (`null` = unfiled); `tags` is the user's editable categorization,
- * merged with the tool's read-only native tags by the UI; `hidden` is TRI-STATE —
+ * merged with the tool's read-only native tags by the UI; `badges` is the operator's
+ * editable capability-label overlay, merged with the tool's read-only plugin-declared
+ * badges by the UI (INFORMATIONAL, never an enforced gate); `hidden` is TRI-STATE —
  * `null` = defer to the plugin declaration, `true` = force hidden, `false` = force
  * visible. A drift throws `ApiSchemaError`.
  */
@@ -247,6 +254,7 @@ export const toolMetaRecord = z.object({
   display_name: z.string().nullable(),
   folder_id: z.string().nullable(),
   tags: z.array(z.string()),
+  badges: z.array(z.string()),
   hidden: z.boolean().nullable(),
 });
 export type ToolMetaRecord = z.infer<typeof toolMetaRecord>;
@@ -1056,12 +1064,18 @@ export const conversationThread = z.object({
 });
 export type ConversationThread = z.infer<typeof conversationThread>;
 
-/** The page window both thread read doors carry; `next_page` is null on the last. */
+/**
+ * The page window every conversation read door carries; `next_page` is null on the
+ * last page. `truncated` is TRUE when the door had more matches than it would scan
+ * or return under its filter/search cap — the UI must surface that LOUDLY, never a
+ * silent cut — and false whenever the window is exhaustive.
+ */
 const conversationPageWindow = {
   total: z.number(),
   page: z.number(),
   page_size: z.number(),
   next_page: z.number().nullable(),
+  truncated: z.boolean(),
 };
 
 export const conversationThreadsPage = z.object({
@@ -1117,6 +1131,19 @@ export const conversationTranscriptPage = z.object({
 });
 export type ConversationTranscriptPage = z.infer<typeof conversationTranscriptPage>;
 
+/**
+ * A route-scoped message search (`GET /api/conversations/{route}/messages/search?q`):
+ * every record on the route whose text matches `q`, across threads, newest first.
+ * The record shape is the transcript's exactly, so a hit renders with the same
+ * projection. `truncated` says the match set outran the door's scan cap — surfaced
+ * loudly, never a silent cut.
+ */
+export const conversationMessageSearchPage = z.object({
+  items: z.array(conversationMessage),
+  ...conversationPageWindow,
+});
+export type ConversationMessageSearchPage = z.infer<typeof conversationMessageSearchPage>;
+
 /**
  * Who answers a thread's incoming messages: `agent` lets the flow reply on its
  * own; `manual` holds the flow back so a human answers. `source` says whether the
@@ -1857,10 +1884,43 @@ export type RunTrace = z.infer<typeof runTrace>;
 
 // -- marketplace -------------------------------------------------------------
 
+/**
+ * The CLOSED HTTP-method enum fixed by the contract's RouteMethod, the one source
+ * for every route-method field (declaration and install/preview responses alike):
+ * a wire method the contract does not define fails loudly as drift rather than
+ * passing through silently.
+ */
+export const routeMethod = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export type RouteMethod = z.infer<typeof routeMethod>;
+
+/**
+ * One HTTP route an item declares in its `tai-plugin.yml`: a `path` relative to
+ * the item's mount base, the `methods` it answers, and whether it is served
+ * `public` (without authentication). The absolute path an operator sees is
+ * resolved from the base at install time.
+ */
+export const marketplaceRouteDecl = z.object({
+  path: z.string(),
+  methods: z.array(routeMethod),
+  public: z.boolean(),
+});
+export type MarketplaceRouteDecl = z.infer<typeof marketplaceRouteDecl>;
+
+/**
+ * A route-carrying item's declared mount: the default `base` prefix the routes
+ * hang off (an operator may remap it at install) and the `paths` it registers.
+ */
+export const marketplaceRoutesDecl = z.object({
+  base: z.string(),
+  paths: z.array(marketplaceRouteDecl),
+});
+export type MarketplaceRoutesDecl = z.infer<typeof marketplaceRoutesDecl>;
+
 /**
  * One contained item of a marketplace plugin's published version: its kind
  * (tool / agent / extension / …), name, description, free-form tags, and the
- * logical group it belongs to (`null` when ungrouped).
+ * logical group it belongs to (`null` when ungrouped). `routes` is present only
+ * on a route-carrying item (a router or channel); absent/null on every other.
  */
 export const marketplaceItem = z.object({
   kind: z.string(),
@@ -1868,6 +1928,7 @@ export const marketplaceItem = z.object({
   description: z.string(),
   tags: z.array(z.string()),
   group: z.string().nullable(),
+  routes: marketplaceRoutesDecl.nullish(),
 });
 export type MarketplaceItem = z.infer<typeof marketplaceItem>;
 
@@ -2071,6 +2132,10 @@ export const marketplaceInstalledPlugin = z
     // (local truth). The McpTab joins the mcp-server item names against the
     // manifest's mcp-entry titles to render an installer-written entry read-only.
     items: z.array(marketplaceItem.pick({ kind: true, name: true })),
+    // The persisted `{item_name: base}` mount this plugin is installed at (local
+    // truth; `{}` means every item at its declared base). Studio seeds the update
+    // flow and renders routes at the ACTUAL mounted base from this.
+    route_mounts: z.record(z.string(), z.string()),
   })
   .strict();
 export type MarketplaceInstalledPlugin = z.infer<typeof marketplaceInstalledPlugin>;
@@ -2130,22 +2195,98 @@ export const marketplaceCategories = z.array(z.string());
 /** The registry's controlled item-kind list, proxied through the skeleton. */
 export const marketplaceKinds = z.array(z.string());
 
+/**
+ * One route the install / update actually mounted: the item that owns it, the
+ * absolute `full_path` it now answers, the `methods`, and whether it is served
+ * `public`. The receipt lists these so the operator sees what was opened where.
+ */
+export const marketplaceMountedRoute = z.object({
+  item: z.string(),
+  full_path: z.string(),
+  methods: z.array(routeMethod),
+  public: z.boolean(),
+});
+export type MarketplaceMountedRoute = z.infer<typeof marketplaceMountedRoute>;
+
 /**
  * The receipt of an install / update: what landed and at which version.
  * `notes` (env-selected items naming their activating env var) and any
- * non-critical `advisories` ride BOTH the install and update receipts. The wire
- * also carries `package`, `reload`, and `pip_output`, which the receipt does not
- * model — zod's default strip drops them; the UI renders the receipt, not the
- * raw install log.
+ * non-critical `advisories` ride BOTH the install and update receipts.
+ * `routes` is the mounted-route list — empty for a plugin that registers none.
+ * The wire also carries `package`, `reload`, and `pip_output`, which the receipt
+ * does not model — zod's default strip drops them; the UI renders the receipt,
+ * not the raw install log.
  */
 export const marketplaceInstallResult = z.object({
   ref: z.string(),
   version: z.string(),
   notes: z.array(z.string()),
   advisories: z.array(marketplaceAdvisory),
+  routes: z.array(marketplaceMountedRoute),
 });
 export type MarketplaceInstallResult = z.infer<typeof marketplaceInstallResult>;
 
+/** One resolved route in an install preview: the declared `path`, its resolved
+ * absolute `full_path`, the `methods`, and whether it is `public`. */
+export const marketplacePreviewRoute = z.object({
+  path: z.string(),
+  full_path: z.string(),
+  methods: z.array(routeMethod),
+  public: z.boolean(),
+});
+export type MarketplacePreviewRoute = z.infer<typeof marketplacePreviewRoute>;
+
+/** One route-carrying item in an install preview: its resolved `base` (the
+ * override or the default), the `default_base` it declares, and the routes that
+ * mount under it. */
+export const marketplacePreviewItem = z.object({
+  item: z.string(),
+  kind: z.string(),
+  base: z.string(),
+  default_base: z.string(),
+  routes: z.array(marketplacePreviewRoute),
+});
+export type MarketplacePreviewItem = z.infer<typeof marketplacePreviewItem>;
+
+/** One collision the preview found: a route whose resolved shape+method clashes
+ * with an already-owned route. `conflict_owner` is `core` or `plugin:<ref>`; the
+ * remedy is to remap the item's base. */
+export const marketplacePreviewCollision = z.object({
+  item: z.string(),
+  full_path: z.string(),
+  methods: z.array(routeMethod),
+  conflict_owner: z.string(),
+  conflict_path: z.string(),
+});
+export type MarketplacePreviewCollision = z.infer<typeof marketplacePreviewCollision>;
+
+/** One public route the operator is asked to accept: served WITHOUT
+ * authentication once installed. */
+export const marketplacePreviewPublicRoute = z.object({
+  item: z.string(),
+  full_path: z.string(),
+  methods: z.array(routeMethod),
+});
+export type MarketplacePreviewPublicRoute = z.infer<typeof marketplacePreviewPublicRoute>;
+
+/**
+ * The install preview (`POST /api/marketplace/install/preview`): the resolved
+ * routes per item with any base overrides applied, the collisions against the
+ * live registry, the public routes requiring acceptance, and whether acceptance
+ * is required at all. `new_public_routes` narrows to rows not already approved
+ * (the update case); on a fresh install it equals `public_routes`.
+ */
+export const marketplaceInstallPreview = z.object({
+  ref: z.string(),
+  version: z.string(),
+  items: z.array(marketplacePreviewItem),
+  collisions: z.array(marketplacePreviewCollision),
+  public_routes: z.array(marketplacePreviewPublicRoute),
+  new_public_routes: z.array(marketplacePreviewPublicRoute),
+  requires_public_acceptance: z.boolean(),
+});
+export type MarketplaceInstallPreview = z.infer<typeof marketplaceInstallPreview>;
+
 /**
  * The receipt of an uninstall. `notes` carries operator warnings (e.g. a config
  * provider still selected by its env var); render them like the install