dsh-agent-plugins-market 0.9.0 → 0.9.2

package/lib/types/{contracts → packages/market-contracts/src/contracts}/market.d.ts

@@ -4,6 +4,8 @@ export declare const MARKET_API_PREFIX: "/api/agent-plugins/";
 /** Fixed Agent Plugins Market HTTP routes. */
 export declare const MARKET_ROUTES: {
     readonly overview: "/api/agent-plugins/overview";
+    readonly surfaceToggles: "/api/agent-plugins/surface-toggles";
+    readonly setSurfaceToggle: "/api/agent-plugins/surface-toggles/set";
     readonly mcpStatus: "/api/agent-plugins/mcp-status";
     readonly addMcpServer: "/api/agent-plugins/mcp-servers/add";
     readonly lspStatus: "/api/agent-plugins/lsp-status";
@@ -16,7 +18,20 @@ export declare const MARKET_ROUTES: {
     readonly config: "/api/agent-plugins/config";
     readonly modelCatalog: "/api/agent-plugins/model-catalog";
     readonly suite: "/api/agent-plugins/suite";
-    readonly skill: "/api/agent-plugins/skill";
+    /**
+     * One suite document's authored text (GET). The query names the suite, the
+     * surface, and the document — `{ sourceId, suiteId, kind, name }` — and the
+     * body is read server-side when a reader opens the row, so the detail payload
+     * never carries a document's bytes.
+     */
+    readonly suiteDocument: "/api/agent-plugins/suite/document";
+    /**
+     * One suite document's translation (POST). The body names the suite and the
+     * document — `{ sourceId, suiteId, kind, name }` — and never carries text, so
+     * this is the market detail page's counterpart of
+     * {@link userPanelTranslationRoute}: the file is re-read server-side.
+     */
+    readonly suiteDocumentTranslation: "/api/agent-plugins/suite/document/translation";
     readonly addSource: "/api/agent-plugins/sources/add";
     readonly updateSource: "/api/agent-plugins/sources/update";
     readonly adoptSource: "/api/agent-plugins/sources/adopt";
@@ -35,6 +50,8 @@ export declare const MARKET_ROUTES: {
     readonly mcpBackend: "/api/agent-plugins/mcp-backend";
     readonly setMcpBackend: "/api/agent-plugins/set-mcp-backend";
     readonly userPanel: "/api/agent-plugins/user-panel";
+    readonly menuRowFaces: "/api/agent-plugins/menu-row-faces";
+    readonly clearTranslations: "/api/agent-plugins/translations/clear";
 };
 /** One timeout's three layers: the user's value, the suite declaration, and the value in force. */
 export interface ServerTimeoutPolicy {
@@ -133,6 +150,15 @@ export interface ModelCatalogPayload {
 export type UserPanelMutation = 'create' | 'update' | 'delete';
 /** Build one user-panel list route URL (`GET`, no mutation). */
 export declare function userPanelRoute(kind: UserPanelKind): string;
+/**
+ * Build the document-translation route URL for one panel's entries (POST).
+ *
+ * It sits under the entry segment because it translates one entry's document,
+ * and it is a POST because it queues provider work — the entry it names is the
+ * only input, and the server re-reads that entry rather than trusting text
+ * from the page.
+ */
+export declare function userPanelTranslationRoute(kind: UserPanelKind): string;
 /** Build one user-panel mutation route URL (all POSTs). */
 export declare function userPanelMutationRoute(kind: UserPanelKind, mutation: UserPanelMutation, name?: string): string;
 /** The MCP mount backend state reported to the settings page. */
@@ -211,6 +237,8 @@ export interface SuiteOverviewCard {
     name: string;
     version?: string;
     description?: string;
+    /** The description translated for the panel's locale; absent means render `description`. */
+    translatedDescription?: string;
     keywords: string[];
     surfaces: SuiteSurfaceCounts;
     enabled: boolean;
@@ -238,6 +266,13 @@ export interface OverviewPayload {
     };
     /** Unmanaged `.sources/` checkouts (manual clones) available for adoption. */
     unmanaged?: UnmanagedSource[];
+    /**
+     * Translatable chunks still waiting for a translation, absent or 0 when none
+     * are. One chunk counts once, so a card contributes one per chunk of its
+     * description still in flight. The panel re-reads while this is non-zero so a
+     * translated card replaces the original text without a manual refresh.
+     */
+    translationPending?: number;
 }
 /** Host-side progress of the source mutation currently in flight. */
 export interface SourceProgress {
@@ -252,14 +287,16 @@ export interface SuiteSkillMeta {
     whenToUse?: string;
     path: string;
 }
-/** One command or agent preview in a suite detail response. */
-export interface MarkdownPreview {
+/**
+ * One command or agent as the suite detail payload carries it: the identity its
+ * row renders, never the body. The text is a separate read, made when a reader
+ * opens that row.
+ */
+export interface SuiteDocumentMeta {
     name: string;
+    /** The document's frontmatter `description`, when it declares one. */
     description?: string;
-    content: string;
 }
-/** Claude Code agent preview alias retained for feature-specific readability. */
-export type AgentPreview = MarkdownPreview;
 /** One LSP definition preview in a suite detail response. */
 export interface LspPreview {
     name: string;
@@ -301,11 +338,15 @@ export interface McpServerDetail {
 }
 /** Full suite detail response served by the detail modal. */
 export interface SuiteDetail {
+    /** Description units still pending; absent means settled. */
+    translationPending?: number;
     sourceId: string;
     suiteId: string;
     name: string;
     version: string | null;
     description: string | null;
+    /** The description translated for the panel's locale; absent means render `description`. */
+    translatedDescription?: string;
     author: string | null;
     keywords: string[];
     /** Last modification of the suite checkout, as an ISO timestamp; null when it cannot be read. */
@@ -325,21 +366,21 @@ export interface SuiteDetail {
         count: number;
         entries: HookPreview[];
     };
-    commands: MarkdownPreview[];
-    agents: MarkdownPreview[];
+    commands: SuiteDocumentMeta[];
+    agents: SuiteDocumentMeta[];
     lsp: LspSurfaceDetail;
     errors: string[];
     mcpErrors: string[];
 }
-/** One skill's full file text served by the skill route. */
-export interface SkillContent {
+/** One document's full authored text, served by the suite document route. */
+export interface SuiteDocumentText {
     name: string;
-    description: string;
     content: string;
-    path: string;
 }
 /** A user panel entry (skills / commands / agent personas) over HTTP. */
 export interface UserPanelEntryWire {
+    /** Description units still pending on an entry read; absent means settled. */
+    translationPending?: number;
     /**
      * Entry name: the name its document declares, else its document name — the
      * file's base name, or, on a panel that reads subdirectories, the document's
@@ -347,26 +388,56 @@ export interface UserPanelEntryWire {
      */
     name: string;
     description: string;
+    /** The description translated for the panel's locale; absent means render `description`. */
+    translatedDescription?: string;
     disabled: boolean;
     /** User entries are editable; suite-owned plugin entries answer only to the enable switch. */
     origin: 'user' | 'plugin';
     id?: string;
-    rawText: string;
+    /**
+     * The document's own text, exactly as authored. The list read omits it — it
+     * was the bulk of the response and the client fetches the one entry it opens
+     * — while the single-entry read and the raw user store always carry it.
+     */
+    rawText?: string;
     /** Human-readable suite owner for a plugin-provided entry. */
     suiteName?: string;
     metadata: Record<string, unknown>;
     path: string;
     /** The entry file's last modification, as an ISO timestamp. */
     updatedAt?: string | null;
-    content: string;
+    /**
+     * Frontmatter-stripped body. Supplied by the raw user store, which needs it
+     * for a command's payload; the panel view deliberately omits it, because the
+     * client renders `rawText` and sending both shipped the same document twice.
+     */
+    content?: string;
     /** Suite checkout root of a plugin-provided file; runtime consumers resolve `${PLUGIN_ROOT}` against it. */
     suiteRoot?: string;
     /** The suite's `${PLUGIN_DATA}` directory, for the same runtime resolution. */
     suiteData?: string;
 }
+/** The `/` menu groups whose rows this plugin owns. */
+export type MenuRowSource = 'commands' | 'skills';
+/**
+ * One localized `/` menu row face over HTTP.
+ *
+ * The row's identity fields never travel: the client matches on `source` +
+ * `name` and the host row supplies everything else. Only the description is
+ * translated — a name is an identifier the user types and matches against
+ * upstream documentation, so no field here can override the host's title.
+ */
+export interface MenuRowFaceWire {
+    /** Which menu group the row belongs to: the slash-command group or the skill group. */
+    source: MenuRowSource;
+    /** Command call name or skill name, exactly as the menu row carries it. */
+    name: string;
+    /** Translated description; absent when nothing was translated. */
+    description?: string;
+}
 /** The user panel surface the market exposes. */
 export type UserPanelKind = 'skills' | 'commands' | 'agents';
 /** Build a suite-detail URL without duplicating route or query encoding logic. */
 export declare function suiteRoute(sourceId: string, suiteId: string): string;
-/** Build a skill-content URL without duplicating route or query encoding logic. */
-export declare function skillRoute(sourceId: string, suiteId: string, skill: string): string;
+/** Build a suite-document URL without duplicating route or query encoding logic. */
+export declare function documentRoute(sourceId: string, suiteId: string, kind: UserPanelKind, name: string): string;

package/lib/types/packages/market-contracts/src/contracts/mcp-overrides.d.ts

@@ -0,0 +1,39 @@
+import type { McpServerSse, McpServerStreamableHttp, McpServerStdio } from '../model/types.js';
+/** HTTP-shaped server sources (url + headers carriers) overrides can edit. */
+type McpServerHttp = McpServerStreamableHttp | McpServerSse;
+/** The largest timeout a bridge config and the host timer can hold. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+/** Per-server override record; absent fields pass through from the source. */
+export type McpServerOverride = {
+    /** Validated complete user configuration, retaining source-owned identity. */
+    config?: McpServerStdio | McpServerHttp;
+    /** Disabled servers are not mounted at all (default enabled). */
+    enabled?: boolean;
+    /** Replaces the source URL (streamable-http only). */
+    url?: string;
+    /** Replaces the whole header map (streamable-http only). */
+    headers?: Record<string, string>;
+    /** Replaces the whole env map (stdio). */
+    env?: Record<string, string>;
+    /** Replaces the whole args list (stdio). */
+    args?: string[];
+    /** Replaces the OAuth block (streamable-http only); `enabled: false` disables a source-declared flow. */
+    auth?: {
+        enabled: boolean;
+        scope?: string;
+    };
+    /** Per-tool-call timeout in milliseconds; absent inherits the suite's value or the bridge default. */
+    toolCallTimeoutMs?: number;
+    /** Startup timeout in milliseconds; absent inherits the suite's value or the bridge default. */
+    startupTimeoutMs?: number;
+    /** Tool names the user turned off; the suite's own deny list stays in force beside them. */
+    disabledTools?: string[];
+};
+/** Timeout fields a policy save can set (`number`) or clear back to inheritance (`null`). */
+export interface McpTimeoutPatch {
+    toolCallTimeoutMs?: number | null;
+    startupTimeoutMs?: number | null;
+}
+/** Overrides for one suite, keyed by mcp.json server key. */
+export type McpSuiteOverrides = Record<string, McpServerOverride>;
+export {};

package/lib/types/{contracts → packages/market-contracts/src/contracts}/mcp-status.d.ts

@@ -1,8 +1,11 @@
 /** Browser-safe MCP status records shared by host aggregation and client rendering. */
 /** A tool observed in the host MCP tool registry. */
 export interface McpStatusTool {
+    /** The tool's call name, as the server advertises it; never translated. */
     name: string;
     description?: string;
+    /** The description translated for the panel's locale; absent means render `description`. */
+    translatedDescription?: string;
     /** The advertised input schema, kept only while it stays small enough to transport; absent otherwise. */
     parameters?: unknown;
 }
@@ -85,4 +88,10 @@ export interface McpStatusPayload {
     /** The mount backend the rows were observed under; `host` cannot enforce tool
      *  filters or startup timeouts, so the panel disables those controls. */
     backend?: 'builtin' | 'host';
+    /**
+     * Descriptions this read queued that have not landed yet; absent means the
+     * text is settled. The panel re-reads while it is non-zero, so translated
+     * text appears without the user pressing refresh.
+     */
+    translationPending?: number;
 }

package/lib/types/packages/market-contracts/src/contracts/resource-window.d.ts

@@ -0,0 +1,70 @@
+/** Browser-safe resource-window wire records and route constants. */
+import { type SurfaceToggleKey } from './surface-toggles.js';
+/** Fixed resource-window HTTP routes. */
+export declare const RESOURCE_ROUTES: {
+    readonly inventory: "/api/agent-plugins/resource-window";
+    readonly setEntry: "/api/agent-plugins/resource-window/entry";
+    readonly reset: "/api/agent-plugins/resource-window/reset";
+    readonly applyFavorite: "/api/agent-plugins/resource-window/favorites/apply";
+    readonly saveFavorite: "/api/agent-plugins/resource-window/favorites/save";
+    readonly deleteFavorite: "/api/agent-plugins/resource-window/favorites/delete";
+};
+/**
+ * The window's six tabs, each the facet of one switchable surface. Market rows
+ * are installed suites; the other five list the entries that surface mounts.
+ */
+export type ResourceFace = SurfaceToggleKey;
+/** The tab order the window shows, matching the prototype. */
+export declare const RESOURCE_FACE_ORDER: readonly ResourceFace[];
+/** One inventory row: one already-installed resource this workspace mounts. */
+export interface ResourceEntryWire {
+    /** Stable id: `${face}:${entryKey}` — unique across tabs. */
+    id: string;
+    face: ResourceFace;
+    /** Display name: suite name, skill/command/agent name, or server name. */
+    name: string;
+    /** Version when the source declares one; absent otherwise. */
+    version?: string;
+    /** One provenance word: the owning source, suite, or "direct". */
+    source: string;
+    /** Description for the card view's body line. */
+    description?: string;
+    /** Surface counts for the market tab's footer row; absent elsewhere. */
+    counts?: Array<{
+        label: string;
+        count: number;
+    }>;
+    /** Whether this workspace mounts the entry right now. */
+    enabled: boolean;
+    /**
+     * Whether the user-level (global) state itself has the entry off: the
+     * settings page's own disable, not this workspace's filter. A globally off
+     * entry reads disabled here and its switch locks — this surface can filter
+     * further, never re-enable what the user level turned off.
+     */
+    globalDisabled?: boolean;
+}
+/** The workspace's installed inventory with per-entry filter state. */
+export interface ResourceWindowPayload {
+    workspace: string;
+    entries: ResourceEntryWire[];
+    favorites: ResourceFavoriteWire[];
+}
+/** One cross-project favorite: a complete snapshot of every switch. */
+export interface ResourceFavoriteWire {
+    id: string;
+    name: string;
+    createdAt: string;
+    /** The six surface switches at save time. */
+    surfaces: Record<SurfaceToggleKey, boolean>;
+    /** Entry ids turned off at save time, across all faces. */
+    offEntries: string[];
+}
+/** The favorite payload the save route accepts and stores verbatim. */
+export interface ResourceFavoriteInput {
+    name: string;
+    surfaces: Record<SurfaceToggleKey, boolean>;
+    offEntries: string[];
+}
+/** Read one untrusted favorite input; unknown faces and non-strings drop out. */
+export declare function resolveFavoriteInput(value: unknown): ResourceFavoriteInput | undefined;

package/lib/types/packages/market-contracts/src/contracts/settings.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Browser-safe settings contract of the market's host settings namespace: the
+ * namespace key, the fields with their defaults, and the one reader that turns
+ * a stored section into resolved values.
+ *
+ * The defaults live here and nowhere else. The namespace schema declares them
+ * to the host, the node half reads them back through {@link resolveMarketSettings},
+ * and the browser half — which cannot import `src/runtime` — reads the same
+ * resolved values off the settings snapshot it is handed. Changing a default is
+ * therefore a one-line edit in this module.
+ *
+ * One default is not a constant: `translationEnabled` follows the interface
+ * language, so its reader takes the language as an argument and
+ * {@link interfaceLanguageTranslates} answers that default only. An explicit
+ * preference is independent of language. {@link resolveTranslationTarget}
+ * selects the language of displayed translations, including English.
+ *
+ * @module contracts/settings
+ */
+/** Settings namespace this plugin registers; the key the plugin-config tab pairs our card by. */
+export declare const MARKET_SETTINGS_NAMESPACE = "dsh-agent-plugins-market";
+/** The persisted download-region setting: `auto` follows the interface language. */
+export type DownloadRegionSetting = 'auto' | 'global' | 'china';
+/** Every market setting with the value it resolves to when the document says nothing. */
+export interface MarketSettings {
+    /** ON = the built-in MCP bridge with OAuth and SSE; OFF = host client compat mode. */
+    mcpEnhanced: boolean;
+    /** ON = native project Agent layouts (`.claude/`, `.agents/`) take part in discovery. */
+    scanProjectLayouts: boolean;
+    /** Download region for GitHub acquisition. */
+    downloadRegion: DownloadRegionSetting;
+    /** ON = the `report_market_issue` model tool is registered. */
+    feedbackEnabled: boolean;
+    /** ON = every configured source refreshes in the background. */
+    autoUpdateSources: boolean;
+    /**
+     * ON = suite, skill, command, agent, MCP and LSP text is localized for the
+     * host locale. The stored value while the user has one, the interface
+     * language's default otherwise.
+     */
+    translationEnabled: boolean;
+    /** ON = the composer carries the Agent preset manager entry (experimental). */
+    agentPresetsEnabled: boolean;
+}
+/**
+ * The default of every market setting — the single place one is written.
+ *
+ * These are user-visible behavior: a flip here is a behavior change that ships
+ * with its documentation, not a private implementation detail.
+ *
+ * `translationEnabled` is the one exception: the interface language decides it
+ * (see {@link interfaceLanguageTranslates}), so this constant is not where its
+ * effective default lives. It is what the browser store holds before the host
+ * answers, and that pre-answer state deliberately withholds the translation
+ * control rather than flashing it. The namespace schema declares no default for
+ * the field at all, an absence that is load-bearing: a schema default would
+ * reach the live config reference and erase the difference between "the user
+ * never set this" and "the user turned it off".
+ */
+export declare const MARKET_SETTINGS_DEFAULTS: MarketSettings;
+/** Every field name the market's settings section carries. */
+export type MarketSettingKey = keyof MarketSettings;
+/**
+ * Narrow an untrusted stored region to a setting; anything else reads as the
+ * declared default.
+ * @param value - the stored `downloadRegion` value.
+ * @param fallback - the value an unrecognized input reads as.
+ */
+export declare function narrowDownloadRegion(value: unknown, fallback?: DownloadRegionSetting): DownloadRegionSetting;
+/**
+ * Whether one interface language renders the market's Chinese dictionary.
+ *
+ * This is the host's own rule rather than a second reading of it:
+ * `bindHostLocale` (`runtime/host/host-locale.ts`) answers every preference
+ * that is not English with the Chinese dictionary, so as far as the interface is
+ * concerned everything that is not English is Chinese — an absent preference
+ * included, which the host reads as zh.
+ *
+ * This determines only the default display preference: Chinese starts on and
+ * English starts off. It must not gate an explicitly enabled translation.
+ * @param localePreference - the host `locale.preference`, or undefined while nothing supplies one.
+ */
+export declare function interfaceLanguageTranslates(localePreference: string | undefined): boolean;
+/**
+ * The language the interface renders, as the translation chain names it.
+ *
+ * The target follows the dictionary, not the preference tag. The market ships
+ * exactly one non-English dictionary and {@link bindHostLocale}'s counterpart
+ * resolves every preference that is not English to it, so a `ja` or `zh-Hant`
+ * reader is surrounded by Simplified Chinese copy: translating upstream text
+ * into Japanese, or into Traditional, would put the one part of the page the
+ * layer owns into a language nothing around it is written in. `zh` is the tag
+ * both machine endpoints already map to Simplified Chinese
+ * (`runtime/host/machine-translator.ts`) and the one the model hop names
+ * "Simplified Chinese"; a second dictionary would add a case here rather than a
+ * second reading of the preference somewhere else.
+ *
+ * Target selection is independent of whether translations are displayed.
+ * @param localePreference - the host `locale.preference`, or undefined while nothing supplies one.
+ * @returns the language rendered by the interface.
+ */
+export declare function resolveTranslationTarget(localePreference: string | undefined): 'zh' | 'en';
+/**
+ * Resolve a stored settings section the way the host resolves it: each field
+ * takes its stored value when it is one this field accepts, and its default
+ * otherwise.
+ *
+ * The host hands the resolved section back on its own, but not every caller has
+ * one — the plugin's own halves read a section they may not have received yet,
+ * and a test hands in a bare literal. Funnelling all of them through this
+ * function is what keeps a second reading of "what does missing mean" from
+ * growing somewhere else.
+ *
+ * A stored boolean always wins: the user's own answer is never overridden by
+ * the language. Only a section that says nothing about the field takes the
+ * language's answer, which is what makes a language switch move the default for
+ * a user who never set the field and leave every other user alone.
+ * @param section - the stored (or absent) namespace section, untrusted.
+ * @param localePreference - the host `locale.preference` the language-derived default follows.
+ */
+export declare function resolveMarketSettings(section: unknown, localePreference?: string): MarketSettings;

package/lib/types/packages/market-contracts/src/contracts/surface-toggles.d.ts

@@ -0,0 +1,28 @@
+/** Per-project on/off switches for the six surfaces the plugin mounts. */
+/** The six switchable surfaces, in the order the composer control shows them. */
+export declare const SURFACE_TOGGLE_KEYS: readonly ["market", "skills", "commands", "agents", "mcp", "lsp"];
+/** One switchable surface. */
+export type SurfaceToggleKey = (typeof SURFACE_TOGGLE_KEYS)[number];
+/**
+ * The persisted toggle state for one workspace. Every key defaults to on: the
+ * file only records a project that turned something off, so the common case —
+ * no opinion — costs nothing and an absent file means "all surfaces on".
+ */
+export interface SurfaceToggles {
+    market: boolean;
+    skills: boolean;
+    commands: boolean;
+    agents: boolean;
+    mcp: boolean;
+    lsp: boolean;
+}
+/** The all-on default applied when a workspace has no recorded opinion. */
+export declare const ALL_SURFACES_ON: SurfaceToggles;
+/**
+ * Read one workspace's toggles from an untrusted record.
+ *
+ * Unknown keys are dropped and wrong-typed values fall back to on, so a
+ * hand-edited or future-shaped file degrades to "the known keys apply" the
+ * same way the other state files in this plugin do.
+ */
+export declare function resolveSurfaceToggles(value: unknown): SurfaceToggles;

package/lib/types/packages/market-contracts/src/contracts/translation.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The wire and domain vocabulary of the translation layer.
+ *
+ * A translation unit names one translatable field of one entity — a suite
+ * description, an MCP tool description — and the translated field set carries
+ * the results back to every surface that renders them. Kept free of imports so
+ * both the server layers and the client bundle can depend on it.
+ *
+ * Descriptions and document prose are translated. A name is an identifier the user types,
+ * greps, and matches against upstream documentation, and machine translation
+ * turned them into text that was harder to recognize than the original — so
+ * the layer never touches one.
+ */
+/** One translation backend: a public machine-translation endpoint or the user's own model. */
+export type TranslationProviderId = 'google' | 'microsoft' | 'llm';
+/** One translation backend: a public endpoint or the user's own model. */
+export interface TranslationProvider {
+    /** Which provider this is; also the identity folded into the cache key. */
+    readonly id: TranslationProviderId;
+    /**
+     * Whether this provider can serve a call right now.
+     *
+     * Read per call and never cached: a model route provisions after the plugin's
+     * apply() returns, so an answer captured at composition time would report
+     * "unavailable" for the life of the process.
+     */
+    available(): boolean;
+    /** Translate one batch, preserving order and length. Rejects on any failure. */
+    translate(request: {
+        texts: readonly string[];
+        locale: string;
+        signal: AbortSignal;
+    }): Promise<string[]>;
+}
+/** One surface whose entities are translated; matches the six switchable surfaces. */
+export type TranslationSurfaceKind = 'market' | 'skills' | 'commands' | 'agents' | 'mcp' | 'lsp';
+/**
+ * Which text of one entity a cached translation belongs to.
+ *
+ * The role is a cache-key slot rather than a rendering concern: a description
+ * and a document body retain distinct historical keys. The localizer can reuse
+ * one translation when their source text and target are identical.
+ */
+export type TranslationRole = 'description' | 'document';
+/**
+ * The translated fields of one entity.
+ *
+ * The description is optional because it may be cached, still pending, or
+ * absent upstream. An absent field means "render the upstream text".
+ */
+export interface TranslationFields {
+    translatedDescription?: string;
+}
+/**
+ * One document body on its way to the target language.
+ *
+ * Each paragraph remains authored until every request for it succeeds.
+ * `pending` counts paragraphs with unfinished work. `failed` counts paragraphs
+ * that cannot currently produce a complete translation. Other paragraphs remain
+ * readable while those requests settle.
+ */
+export interface DocumentTranslation {
+    /** The body with complete translated paragraphs and authored fallbacks. */
+    text: string;
+    /** Complete Markdown with each translated paragraph directly after its original. */
+    bilingualText?: string;
+    /** Paragraphs with queued or running work; the client re-reads while this is non-zero. */
+    pending: number;
+    /** Paragraphs left original because translation failed or a sentence exceeds its safe budget. */
+    failed?: number;
+}
+/**
+ * Merge two optional field sets; the later one wins per field.
+ *
+ * A field left undefined in `next` leaves the `base` value in place, so a
+ * caller can layer a partial result over an earlier one without erasing it.
+ * @param base - the field set to start from.
+ * @param next - the field set layered on top.
+ * @returns a new field set holding the merged values.
+ */
+export declare function mergeTranslationFields(base: TranslationFields, next: TranslationFields): TranslationFields;

package/lib/types/{runtime → packages/market-contracts/src}/host/plugin-message-source.d.ts

@@ -4,7 +4,7 @@
  * agent's inbox with their producer identity attached. The host's message
  * sources are merge-extensible — each producer declares its own kind through a
  * module augmentation, and consumers fall through unknown kinds.
- * @module runtime/plugin-message-source
+ * @module contracts/host/plugin-message-source
  */
 import type { UserMessage } from '@deepseek-ai/dsh-llm';
 /** Producer identity of every follow-up message this plugin injects. */

package/lib/types/packages/market-contracts/src/index.d.ts

@@ -0,0 +1,5 @@
+/** Portable public records. Host augmentations are available only through the host subpath. */
+export * from './model/types.js';
+export * from './contracts/settings.js';
+export * from './contracts/extension-presets.js';
+export type { MarketService, MarketQueries, MarketMutations } from './ports/queries.js';

package/lib/types/{model → packages/market-contracts/src/model}/layouts.d.ts

@@ -59,6 +59,13 @@ export declare const PLUGIN_DATA_VARIABLES: ReadonlySet<string>;
 export declare const PROJECT_DIR_VARIABLES: ReadonlySet<string>;
 /** Claude Code names the directory holding the skill's own file; no dialect alias exists. */
 export declare const SKILL_DIR_VARIABLE = "CLAUDE_SKILL_DIR";
+/**
+ * The path names the Claude Code runtime exports to a spawned component. Only
+ * the claude-code spellings: a suite script reads a generic or other-dialect
+ * alias as a runtime marker, so exporting one would select another runtime's
+ * branch. Skill-directory names stay out because no process receives them.
+ */
+export declare const CLAUDE_COMPONENT_ENVIRONMENT: Readonly<Record<'root' | 'data' | 'projectDir', string>>;
 /** Explicit project document formats and portable surfaces; execution stays in the runtime adapters. */
 export type ProjectMcpFormat = 'mcpServers' | 'zcode' | 'codex';
 export type ProjectHookFormat = 'claude' | 'zcode';

package/lib/types/{model → packages/market-contracts/src/model}/types.d.ts

@@ -56,9 +56,9 @@ export interface SuiteManifest {
     systemPrompt?: string;
     systemPromptPath?: string;
     layout: SuiteLayoutKind;
-    /** Absolute manifest file path. */
+    /** Absolute manifest file path, or empty for a metadata-only or aggregate suite. */
     path: string;
-    /** Suite id derived from the manifest name or its root directory, sanitized to `[a-z0-9-]`. */
+    /** Sanitized manifest or directory name, or reserved `@skills` for an aggregate collection. */
     id: string;
     name: string;
     version?: string;