@tai42/api-client 3.0.0 → 5.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;
 }
 
 /**
@@ -790,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
@@ -813,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) =>

package/src/index.ts

@@ -25,7 +25,9 @@ export type {
   ValidatePresetBody,
   ToolMetaPatch,
   StorageUploadBody,
+  ConversationThreadFilters,
   ConversationTranscriptQuery,
+  ConversationMessageSearchQuery,
   ConversationThreadMessageBody,
   MetricsQuery,
   RunsQuery,
@@ -128,6 +130,7 @@ export type {
   ConversationRecordOrigin,
   TranscriptOrder,
   ConversationTranscriptPage,
+  ConversationMessageSearchPage,
   ConversationThreadMode,
   ConversationThreadModeState,
   ConversationThreadMessageSent,
@@ -183,6 +186,9 @@ export type {
   RunSpan,
   RunTrace,
   MarketplaceItem,
+  MarketplaceDelivery,
+  MarketplaceSource,
+  MarketplaceRequiredEnvVar,
   MarketplaceRouteDecl,
   MarketplaceRoutesDecl,
   MarketplaceSearchKind,

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>;
@@ -750,7 +758,10 @@ export const providerView = z.object({
   id: z.string(),
   display_name: z.string(),
   description: z.string(),
-  icon_url: z.string(),
+  // Required and a real URL: the contract's `ProviderDescriptor.icon_url` runs
+  // `check_web_url(schemes=("https",))`, which rejects an empty/relative value, so
+  // an empty or malformed one here is drift and fails the parse loudly.
+  icon_url: z.string().url(),
   kind: z.enum(['oauth', 'none']),
   origin: z.enum(['system', 'community']),
   category: z.string(),
@@ -1056,12 +1067,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 +1134,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
@@ -1866,6 +1896,31 @@ export type RunTrace = z.infer<typeof runTrace>;
 export const routeMethod = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 export type RouteMethod = z.infer<typeof routeMethod>;
 
+/**
+ * How the plugin is delivered, derived server-side from whether its spec names a
+ * package: `package` is pip-installed, `descriptor` (marketplace `source` `spec`)
+ * installs nothing but the manifest entry. A CLOSED enum, so a wire value the
+ * server does not derive fails loudly as drift.
+ */
+export const marketplaceDelivery = z.enum(['package', 'descriptor']);
+export type MarketplaceDelivery = z.infer<typeof marketplaceDelivery>;
+
+/**
+ * The install-provenance vocabulary a listing/version resolves from: a pip index
+ * (`pypi`), a git tag (`github`), or a descriptor yml (`spec`). CLOSED, so a wire
+ * value outside it fails as drift.
+ */
+export const marketplaceSource = z.enum(['pypi', 'github', 'spec']);
+export type MarketplaceSource = z.infer<typeof marketplaceSource>;
+
+/**
+ * One env var an item requires before install: its `name` and whether its value is
+ * a `secret` (an OAuth client secret is; a client id or a plain marker var is not).
+ * The install dialog seeds each toggle from `secret` and collects the missing ones.
+ */
+export const marketplaceRequiredEnvVar = z.object({ name: z.string(), secret: z.boolean() });
+export type MarketplaceRequiredEnvVar = z.infer<typeof marketplaceRequiredEnvVar>;
+
 /**
  * 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
@@ -1894,6 +1949,12 @@ export type MarketplaceRoutesDecl = z.infer<typeof marketplaceRoutesDecl>;
  * (tool / agent / extension / …), name, description, free-form tags, and the
  * 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.
+ * `required_env` is the env vars the item needs before install — but the REGISTRY's
+ * plugin-detail body does NOT carry it per item: required-env is server-computed
+ * (`required_env_for_spec`) and rides the install PREVIEW, never the listing detail,
+ * so the registry OMITS it here and it parses as `undefined`. Optional (not
+ * defaulted) so the type mirrors the wire; the authority the install dialog collects
+ * from is the preview's `required_env`/`missing_env`, never this field.
  */
 export const marketplaceItem = z.object({
   kind: z.string(),
@@ -1902,6 +1963,7 @@ export const marketplaceItem = z.object({
   tags: z.array(z.string()),
   group: z.string().nullable(),
   routes: marketplaceRoutesDecl.nullish(),
+  required_env: z.array(marketplaceRequiredEnvVar).optional(),
 });
 export type MarketplaceItem = z.infer<typeof marketplaceItem>;
 
@@ -1943,7 +2005,8 @@ export const marketplaceSearchRow = z.object({
   name: z.string(),
   display_name: z.string().nullable(),
   icon_url: z.string().nullable(),
-  package: z.string(),
+  // Null for a descriptor listing (`source` `spec`): it names no package.
+  package: z.string().nullable(),
   description: z.string(),
   categories: z.array(z.string()),
   tags: z.array(z.string()),
@@ -1987,35 +2050,16 @@ export const marketplaceVersion = z.object({
 export type MarketplaceVersion = z.infer<typeof marketplaceVersion>;
 
 /**
- * The listing's latest published version as embedded in its detail: the version,
- * the items it contains, and a minimal typed passthrough of the published spec.
- *
- * `spec` is carried so the install dialog can read an mcp-server item's public
- * `mcp.env` marker strings (`provides[].mcp.env`) and collect its required `!ENV`
- * vars before install. Only that path is typed; everything else on the spec is
- * `.passthrough()`-preserved but unmodelled (zod would otherwise strip the whole
- * `spec` as an unknown key). Nullable + optional: a listing with nothing published
- * carries no spec.
+ * The listing's latest published version as embedded in its detail: the version
+ * (with the `marketplaceVersion` lifecycle fields) and the items it contains. The
+ * registry's detail body carries NO per-version `delivery` field — delivery is
+ * server-computed from whether the spec names a package, and the detail surface
+ * derives it from the listing's `package` (null ⇒ `descriptor`, else `package`).
+ * Env to collect comes from the install preview (`required_env` / `missing_env`),
+ * never from these items.
  */
 export const marketplaceLatestVersion = marketplaceVersion.extend({
   items: z.array(marketplaceItem),
-  spec: z
-    .object({
-      provides: z.array(
-        z
-          .object({
-            kind: z.string(),
-            name: z.string(),
-            mcp: z
-              .object({ env: z.record(z.string(), z.string()).nullish() })
-              .passthrough()
-              .nullish(),
-          })
-          .passthrough(),
-      ),
-    })
-    .passthrough()
-    .nullish(),
 });
 export type MarketplaceLatestVersion = z.infer<typeof marketplaceLatestVersion>;
 
@@ -2043,7 +2087,11 @@ export const marketplacePluginDetail = z.object({
   name: z.string(),
   display_name: z.string().nullable(),
   icon_url: z.string().nullable(),
-  package: z.string(),
+  // Null for a descriptor listing (`source` `spec`): it names no package.
+  package: z.string().nullable(),
+  // The install-provenance vocabulary (`pypi` / `github` / `spec`). Nullish: an
+  // older registry omits it, and a listing with nothing published carries none.
+  source: marketplaceSource.nullish(),
   description: z.string(),
   readme_md: z.string().nullable(),
   license: z.string().nullable(),
@@ -2095,6 +2143,9 @@ export const marketplaceInstalledPlugin = z
     ref: z.string(),
     version: z.string(),
     source: z.string(),
+    // How the row was delivered: `package` for a pip-installed plugin, `descriptor`
+    // for a descriptor-only plugin whose stored spec names no package.
+    delivery: marketplaceDelivery,
     installed_at: z.string(),
     latest: z.string().nullable(),
     update_available: z.boolean(),
@@ -2248,6 +2299,11 @@ export type MarketplacePreviewPublicRoute = z.infer<typeof marketplacePreviewPub
  * 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`.
+ *
+ * `required_env` is every env var the spec requires with its derived secret-ness;
+ * `missing_env` is the bare names not already present in the env store union
+ * process env (server-computed — the ONE authority the dialog collects), and
+ * `delivery` is the one word the surface shows (`package` / `descriptor`).
  */
 export const marketplaceInstallPreview = z.object({
   ref: z.string(),
@@ -2257,6 +2313,9 @@ export const marketplaceInstallPreview = z.object({
   public_routes: z.array(marketplacePreviewPublicRoute),
   new_public_routes: z.array(marketplacePreviewPublicRoute),
   requires_public_acceptance: z.boolean(),
+  required_env: z.array(marketplaceRequiredEnvVar),
+  missing_env: z.array(z.string()),
+  delivery: marketplaceDelivery,
 });
 export type MarketplaceInstallPreview = z.infer<typeof marketplaceInstallPreview>;