dsh-agent-plugins-market 0.7.0 → 0.7.2

package/lib/types/application/queries.d.ts

@@ -5,6 +5,7 @@ import type { OverviewPayload, SkillContent, SourceProgress, SuiteDetail } from
 import type { SourceRef, SuiteSurfaceKey } from '../model/types.js';
 import type { McpServerOverride, McpSuiteOverrides } from '../runtime/mcp-overrides.js';
 import type { McpBackend } from '../runtime/mcp-backend.js';
+import type { McpImportResult } from '../runtime/mcp-direct-config.js';
 import type { ServerConfigPayload } from '../contracts/market.js';
 import type { LspServerTable, McpBackendInfo, SourceInput, SourcePatch } from './ports.js';
 /** Read-only market operations required by HTTP routes. */
@@ -22,8 +23,10 @@ export interface MarketQueries {
 }
 /** Mutating market operations required by HTTP routes. */
 export interface MarketMutations {
-    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown): Promise<void>;
+    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown, policy?: unknown): Promise<void>;
     addMcpServer(name: string, server: unknown): Promise<void>;
+    /** Import several pasted services in one write; each entry reports its own outcome. */
+    importMcpServers(servers: unknown, overwrite: boolean): Promise<McpImportResult>;
     addLspServer(name: string, config: unknown): Promise<void>;
     addSource(input: SourceInput): Promise<SourceRef>;
     updateSource(sourceId: string, patch: SourcePatch): Promise<void>;
@@ -40,6 +43,10 @@ export interface MarketMutations {
     setEnabled(sourceId: string, suiteId: string, enabled: boolean): Promise<void>;
     setSurface(sourceId: string, suiteId: string, surface: SuiteSurfaceKey, enabled: boolean): Promise<void>;
     setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
+    /** Enable or disable one declared MCP server by its source-qualified suite id. */
+    setMcpServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
+    /** Allow or deny one tool of a declared MCP server by its source-qualified suite id. */
+    setMcpServerToolEnabled(suiteKey: string, serverKey: string, tool: string, enabled: boolean): Promise<void>;
     /** Validate and persist the user's direct LSP server table. */
     setLspServers(raw: unknown): Promise<LspServerTable>;
     setLspServerEnabled(id: string, enabled: boolean): Promise<void>;

package/lib/types/catalog/manifests.d.ts

@@ -1,5 +1,5 @@
-import type { SuiteManifest, SuiteComponents } from '../model/types.js';
 import { type ManifestKind } from '../model/layouts.js';
+import type { SuiteManifest, SuiteComponents } from '../model/types.js';
 export type { ManifestKind } from '../model/layouts.js';
 /** One manifest candidate: its file path and the dialect it selects. */
 export interface ManifestCandidate {
@@ -27,12 +27,16 @@ export declare function componentDeclarations(record: object): SuiteComponents;
  * go to `fallbacks`, so the winner stays usable while the caller can still
  * report why the higher-priority declaration was ignored. The winner's own
  * diagnostics stay in `errors` and remain fatal.
+ *
+ * `notes` carries the winner's non-fatal diagnostics — §5.2 unknown
+ * top-level fields, §8.1 extension data problems. Callers surface them
+ * without failing the suite.
  */
 export declare function readManifest(root: string, errors: string[], hint: ({
     name?: string;
     version?: string;
     description?: string;
-} & SuiteComponents) | undefined, fallbacks?: string[]): Promise<SuiteManifest | undefined>;
+} & SuiteComponents) | undefined, fallbacks?: string[], notes?: string[]): Promise<SuiteManifest | undefined>;
 export interface MarketplaceEntry extends SuiteComponents {
     layout?: ManifestKind;
     strict?: boolean;

package/lib/types/catalog/paths.d.ts

@@ -45,6 +45,12 @@ export declare function sourceCheckoutDir(dimensionRoot: string, sourceId: strin
  * bare suite id silently collides across sources.
  */
 export declare function qualifiedSuiteId(sourceId: string, suiteId: string): string;
+/**
+ * The data directory `${PLUGIN_DATA}` resolves to for one suite: a
+ * source-qualified directory under the plugin storage root, shared by every
+ * surface of that suite so MCP servers, skills and commands see one location.
+ */
+export declare function suiteDataDir(dataRoot: string, sourceId: string, suiteId: string): string;
 /** The slice of a `node:path` implementation a containment test needs. */
 export interface PathFlavor {
     relative(from: string, to: string): string;

package/lib/types/catalog/plugin-variables.d.ts

@@ -0,0 +1,16 @@
+import type { Suite } from '../model/types.js';
+/** The absolute paths one expansion can supply; an absent entry leaves its variable verbatim. */
+export interface PluginPathContext {
+    /** Suite checkout root: `${PLUGIN_ROOT}` and its dialect aliases. */
+    root?: string;
+    /** Per-suite data directory: `${PLUGIN_DATA}` and its aliases. */
+    data?: string;
+    /** Directory holding the skill file: `${CLAUDE_SKILL_DIR}`. */
+    skillDir?: string;
+    /** Calling session's project directory: `${CLAUDE_PROJECT_DIR}` and its aliases. */
+    projectDir?: string;
+}
+/** The suite root `${PLUGIN_ROOT}` and its dialect aliases resolve to. */
+export declare function pluginRootOf(suite: Pick<Suite, 'manifest' | 'root'>): string | undefined;
+/** Replace every path variable the context can resolve; other text stays exactly as written. */
+export declare function expandPluginPaths(text: string, context: PluginPathContext): string;

package/lib/types/catalog/skills-parse.d.ts

@@ -11,5 +11,18 @@ export interface ParsedSkillFrontmatter {
  *   skill must be dropped from discovery.
  */
 export declare function parseSkillFrontmatter(text: string, expectedName: string | undefined): ParsedSkillFrontmatter | string;
+/**
+ * Rejection for a user skill document the harness's own `dsh-skill-filesystem`
+ * reader would drop from `~/.agents/skills`, or `undefined` when that reader
+ * accepts it.
+ *
+ * The two readers share the directory, so the panel publishes only documents
+ * both accept: a listed entry never becomes a skill that loads in a
+ * market-equipped session alone. The checks mirror the shipped reader rather
+ * than the lenient suite scan — strict YAML, no display-name normalization,
+ * and a `name` the reader compares only against its kebab grammar.
+ * @returns the drop reason, phrased as the reader's own diagnostic.
+ */
+export declare function skillEntryRejection(text: string): string | undefined;
 /** Strip the frontmatter block, returning the instruction body. */
 export declare function stripFrontmatter(text: string): string;

package/lib/types/catalog/source-catalog.d.ts

@@ -1,8 +1,13 @@
 import type { DiscoveredSuite, SourceRef, SuiteDimension } from '../model/types.js';
 /** Discover suites from the selected configured or project checkouts. */
 export declare function discoverSourceList(sources: SourceRef[], dimension: SuiteDimension, dimensionRoot: string): Promise<DiscoveredSuite[]>;
-/** Discover suites plus per-source scan diagnostics for one dimension. */
-export declare function discoverSourceListWithNotes(sources: SourceRef[], dimension: SuiteDimension, dimensionRoot: string, scanProjectLayouts?: boolean): Promise<{
+/**
+ * Discover suites plus per-source scan diagnostics for one dimension.
+ * @param scanProjectLayouts - whether the project's own native Agent directories
+ *   join the scan. Required on purpose: the switch has one owner (the host
+ *   settings document), so a default here would be a second copy of it.
+ */
+export declare function discoverSourceListWithNotes(sources: SourceRef[], dimension: SuiteDimension, dimensionRoot: string, scanProjectLayouts: boolean): Promise<{
     suites: DiscoveredSuite[];
     scanNotes: Record<string, string[]>;
 }>;

package/lib/types/catalog/surfaces.d.ts

@@ -1,8 +1,18 @@
 import type { LspSuiteConfig, McpSuiteConfig, SuiteManifest, SuiteSkill, SuiteSurfaceCounts } from '../model/types.js';
-/** Discover SKILL.md files under the suite's skills directory, up to 3 levels deep. */
-export declare function discoverSkills(root: string, errors: string[], declared?: unknown): Promise<SuiteSkill[]>;
-/** Read the suite's MCP config: `mcp.json` or `.mcp.json`, else the winning manifest's inline `mcpServers`. */
-export declare function discoverMcp(root: string, errors: string[], manifest?: SuiteManifest): Promise<McpSuiteConfig | undefined>;
+/**
+ * Discover SKILL.md files under the suite's skills directory, up to 3 levels
+ * deep. Portable v1 suites (§7.1) instead discover exactly one level of
+ * `skills/` subdirectories each carrying a `SKILL.md` — the spec forbids
+ * recursive deeper search and root-level or flat skill files are outside the
+ * portable discovery shape.
+ */
+export declare function discoverSkills(root: string, errors: string[], declared?: unknown, portable?: boolean): Promise<SuiteSkill[]>;
+/**
+ * Read the suite's MCP config: `mcp.json` or `.mcp.json`, else the winning
+ * manifest's inline `mcpServers`. Portable v1 suites read only `mcp.json` at
+ * the plugin root (§7.2.1: no alternative core path, no inline declarations).
+ */
+export declare function discoverMcp(root: string, errors: string[], manifest?: SuiteManifest, portable?: boolean): Promise<McpSuiteConfig | undefined>;
 /** Count surfaces for a suite; mcp counts only validated servers, lsp counts inline servers plus directory entries. */
 export declare function countSurfaces(root: string, skills: SuiteSkill[], mcp: McpSuiteConfig | undefined, lsp?: LspSuiteConfig): Promise<SuiteSurfaceCounts>;
 export interface LspEntry {

package/lib/types/catalog/validate.d.ts

@@ -1,10 +1,32 @@
 import type { McpSuiteConfig } from '../model/types.js';
-export declare const PLUGIN_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
-export declare const MCP_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
-/** Validate one JSON document against a vendored schema; errors joined for surfacing. */
-export declare function validateAgainstSchema(schemaId: string, document: unknown): Promise<string[]>;
-/** Whether a `$schema` value selects the local v1.0.0 ruleset. */
+/** One vendored Agent Plugins release: the canonical manifest and MCP schema ids. */
+export interface SpecVersion {
+    version: string;
+    pluginSchemaId: string;
+    mcpSchemaId: string;
+}
+/** The canonical plugin manifest schema identifier of the baseline release. */
+export declare const PLUGIN_SCHEMA_ID: string;
+/** The canonical MCP configuration schema identifier of the baseline release. */
+export declare const MCP_SCHEMA_ID: string;
+/** The spec version a recognized `$schema` id selects, or undefined when unrecognized. */
+export declare function recognizedSpecVersion(schemaId: unknown): SpecVersion | undefined;
+/** Whether a `$schema` value selects a locally supported ruleset. */
 export declare function isRecognizedSchema(value: unknown): boolean;
+/**
+ * One structured schema violation. Structured instead of pre-formatted so
+ * callers can classify by location and keyword before rendering text.
+ */
+export interface SchemaError {
+    keyword: string;
+    instancePath: string;
+    message: string;
+    params?: Record<string, unknown>;
+}
+/** Validate one JSON document against a vendored schema; structured errors. */
+export declare function validateAgainstSchema(schemaId: string, document: unknown): Promise<SchemaError[]>;
+/** Render structured errors as one diagnostic string per error for surfacing. */
+export declare function formatSchemaErrors(errors: SchemaError[]): string[];
 /**
  * Spec §4 containment: a plugin-relative path must begin with `./` and, after
  * resolution against the plugin root, stay inside the filesystem-resolved
@@ -12,8 +34,18 @@ export declare function isRecognizedSchema(value: unknown): boolean;
  * @returns `undefined` when contained, or the rejection reason.
  */
 export declare function pathContainmentError(pluginRoot: string, value: string): Promise<string | undefined>;
-/** Validate a plugin manifest per the vendored schema plus `$schema` recognition. */
-export declare function validatePluginManifest(raw: unknown): Promise<string[]>;
+/**
+ * Classification of one plugin manifest against the vendored schema:
+ * `fatal` violations reject the manifest (§5.2), `ignored` violations are
+ * reported and loading continues (unknown top-level fields per §5.2, the
+ * whole `extensions` subtree per §8.1).
+ */
+export interface ManifestVerdict {
+    fatal: SchemaError[];
+    ignored: SchemaError[];
+}
+/** Validate a plugin manifest against its declared spec version's schema and split the verdict. */
+export declare function validatePluginManifest(raw: unknown): Promise<ManifestVerdict>;
 export interface McpValidateOptions {
     /** Project-owned config may name external executables and working directories. */
     pathMode?: 'plugin' | 'project';
@@ -21,14 +53,43 @@ export interface McpValidateOptions {
      *  Lenient mode (`.mcp.json`, native client file): no `$schema` requirement,
      *  unknown transports skipped per server, known transports still validated. */
     strict?: boolean;
+    /**
+     * Whether the data is a distributable package: the closed field set, bare
+     * command names and plugin-relative paths apply. User-owned files are local
+     * data, so those package rules stay off while every shape and required field
+     * the client does know is still validated. Defaults to `strict`.
+     */
+    packageRules?: boolean;
+    /** The spec version the suite's `plugin.json` declared; mismatched `mcp.json`
+     *  versions disable MCP for the plugin (§7.2.2 rule 2, §10.1). */
+    manifestVersion?: string;
 }
+/**
+ * §7.2.1 remote URL rules: absolute http/https, no user information, no
+ * fragment, HTTPS everywhere except loopback hosts.
+ */
+export declare function remoteUrlError(value: string): string | undefined;
+/**
+ * §7.2.1 header rules: valid field names, and a duplicate name under
+ * different casing makes the entry invalid.
+ */
+export declare function headersError(headers: Record<string, string>): string | undefined;
+/**
+ * Parse and validate an `mcp.json` document.
+ *
+ * Strict mode applies the two-level failure boundary of §7.2.2: a file-level
+ * violation (bad `$schema`, version mismatch with the manifest, non-object
+ * `mcpServers`) disables MCP for the whole plugin, while a per-server
+ * violation skips only that server. Lenient mode keeps the native-client
+ * behavior: no `$schema` requirement, unknown transports skipped per server.
+ *
+ * @returns the validated config plus per-problem strings; `config` stays
+ *   defined whenever at least the file shell was valid, even when some
+ *   servers were skipped.
+ */
 export declare function validateMcpJson(pluginRoot: string, raw: unknown, options?: McpValidateOptions): Promise<{
     config?: McpSuiteConfig;
     errors: string[];
 }>;
-/** Expand `${PLUGIN_ROOT}`, `${PLUGIN_DATA}`, and `${NAME}` (process env) in one string.
- *  Claude Code aliases `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}` and
- *  `${NAME:-default}` fallbacks are honored for unset/empty env vars. */
-export declare function expandPlaceholders(value: string, pluginRoot: string, pluginData: string, env?: NodeJS.ProcessEnv): string;
 /** Resolve an expanded plugin-relative cwd to an absolute path. */
 export declare function resolveCwd(value: string, pluginRoot: string, pluginData: string): string;

package/lib/types/contracts/market.d.ts

@@ -6,6 +6,7 @@ export declare const MARKET_ROUTES: {
     readonly overview: "/api/agent-plugins/overview";
     readonly mcpStatus: "/api/agent-plugins/mcp-status";
     readonly addMcpServer: "/api/agent-plugins/mcp-servers/add";
+    readonly importMcpServers: "/api/agent-plugins/mcp-servers/import";
     readonly lspStatus: "/api/agent-plugins/lsp-status";
     readonly lspServers: "/api/agent-plugins/lsp-servers";
     readonly addLspServer: "/api/agent-plugins/lsp-servers/add";
@@ -28,18 +29,82 @@ export declare const MARKET_ROUTES: {
     readonly setSurface: "/api/agent-plugins/set-surface";
     readonly mcpOverrides: "/api/agent-plugins/mcp-overrides";
     readonly setMcpOverride: "/api/agent-plugins/set-mcp-override";
+    readonly setMcpServerEnabled: "/api/agent-plugins/set-mcp-server-enabled";
+    readonly setMcpServerTool: "/api/agent-plugins/set-mcp-server-tool";
     readonly mcpRetry: "/api/agent-plugins/mcp-retry";
     readonly mcpReauthorize: "/api/agent-plugins/mcp-reauthorize";
     readonly mcpBackend: "/api/agent-plugins/mcp-backend";
     readonly setMcpBackend: "/api/agent-plugins/set-mcp-backend";
     readonly userPanel: "/api/agent-plugins/user-panel";
 };
+/** One timeout's three layers: the user's value, the suite declaration, and the value in force. */
+export interface ServerTimeoutPolicy {
+    /** The user's stored value; null when the user inherits. */
+    user: number | null;
+    /** The suite's declared value; null when the suite declares none. */
+    suite: number | null;
+    /** The value in force. */
+    effective: number;
+    /** Which layer supplied `effective`. */
+    source: 'user' | 'suite' | 'default';
+}
+/** One tool list's layers: what the user stored and what the suite declares. */
+export interface ServerToolPolicy {
+    /** The user's stored list; null when the user set none. */
+    user: string[] | null;
+    /** The suite's declared list; null when the suite declares none. */
+    suite: string[] | null;
+    /** The list in force. */
+    effective: string[];
+}
+/** The OAuth opt-in's two layers. */
+export interface ServerAuthPolicy {
+    /** The user's stored value; null when the user set none. */
+    user: boolean | null;
+    /** The suite's declared value; null when the suite declares none. */
+    suite: boolean | null;
+    /** The value in force. */
+    effective: boolean;
+}
+/** The MCP per-server client policy as the service editor renders it. */
+export interface ServerPolicyPayload {
+    /** Per-tool-call timeout. */
+    toolCallTimeout: ServerTimeoutPolicy;
+    /** Startup timeout. */
+    startupTimeout: ServerTimeoutPolicy;
+    /** The tools the service denies. */
+    deniedTools: ServerToolPolicy;
+    /** The OAuth opt-in. */
+    auth: ServerAuthPolicy;
+}
 /** Editable service configuration; masked values are preserved when unchanged. */
 export interface ServerConfigPayload {
     kind: 'mcp' | 'lsp';
     id: string;
+    /** The declaration key this service carries, used to compose the document view. */
+    key: string;
     editable: boolean;
     config: Record<string, unknown>;
+    /** The stored policy and the suite declaration behind it; present for MCP services. */
+    policy?: ServerPolicyPayload;
+    /** The MCP mount backend; `host` cannot enforce startup timeouts or tool filters. */
+    backend?: 'builtin' | 'host';
+}
+/** The policy a service-config save sets (`number`/value) or clears back to inheritance (`null`). */
+export interface ServerPolicyRequest {
+    toolCallTimeoutMs?: number | null;
+    startupTimeoutMs?: number | null;
+    /** The user's deny list; null clears it. The suite's own entries stay in force. */
+    disabledTools?: string[] | null;
+    /** The user's OAuth opt-in; null clears it back to the suite's declaration. */
+    auth?: {
+        enabled: boolean;
+    } | null;
+}
+/** One rejected value as the API reports it: the field it belongs to and why. */
+export interface MarketFieldError {
+    field: string;
+    message: string;
 }
 /** Public model identities and exact-model reasoning options; never provider configuration. */
 export interface ModelCatalogPayload {
@@ -134,6 +199,9 @@ export type McpServerOverrideWire = {
     headers?: Record<string, string>;
     env?: Record<string, string>;
     args?: string[];
+    toolCallTimeoutMs?: number;
+    startupTimeoutMs?: number;
+    disabledTools?: string[];
 };
 /** Overrides for one suite keyed by mcp.json server key. */
 export type McpSuiteOverridesWire = Record<string, McpServerOverrideWire>;
@@ -243,6 +311,8 @@ export interface SuiteDetail {
     description: string | null;
     author: string | null;
     keywords: string[];
+    /** Last modification of the suite checkout, as an ISO timestamp; null when it cannot be read. */
+    updatedAt: string | null;
     layout: string;
     dimension: string;
     root: string;
@@ -273,6 +343,7 @@ export interface SkillContent {
 }
 /** A user panel entry (skills / commands / agent personas) over HTTP. */
 export interface UserPanelEntryWire {
+    /** Entry name: the name its document declares, else the file's base name. */
     name: string;
     description: string;
     disabled: boolean;
@@ -284,7 +355,13 @@ export interface UserPanelEntryWire {
     suiteName?: string;
     metadata: Record<string, unknown>;
     path: string;
+    /** The entry file's last modification, as an ISO timestamp. */
+    updatedAt?: string | null;
     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 user panel surface the market exposes. */
 export type UserPanelKind = 'skills' | 'commands' | 'agents';

package/lib/types/contracts/mcp-status.d.ts

@@ -3,6 +3,8 @@
 export interface McpStatusTool {
     name: string;
     description?: string;
+    /** The advertised input schema, kept only while it stays small enough to transport; absent otherwise. */
+    parameters?: unknown;
 }
 /** Whether an MCP row comes from a suite or direct host observation. */
 export type McpStatusKind = 'plugin' | 'direct';
@@ -39,6 +41,12 @@ export interface McpStatusEntry {
      *  runs the OAuth flow when the server answers 401, which the redacted
      *  configuration alone cannot show. */
     oauthDefault?: boolean;
+    /** Suite allow-list for this server's tools; absent when the suite narrows nothing. */
+    suiteEnabledTools?: string[];
+    /** Tools the suite's own declaration leaves out. */
+    suiteDisabledTools?: string[];
+    /** Tools the user turned off through the panel. */
+    userDisabledTools?: string[];
 }
 /** The MCP status response returned by the host. */
 export interface McpStatusPayload {
@@ -55,4 +63,7 @@ export interface McpStatusPayload {
         foreign: number;
     };
     directObservationOnly: boolean;
+    /** 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';
 }

package/lib/types/contracts/settings.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ *
+ * @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;
+}
+/**
+ * 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.
+ */
+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;
+/**
+ * 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 declared
+ * 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.
+ * @param section - the stored (or absent) namespace section, untrusted.
+ */
+export declare function resolveMarketSettings(section: unknown): MarketSettings;

package/lib/types/model/layouts.d.ts

@@ -39,9 +39,26 @@ export declare const PLUGIN_LAYOUTS: readonly [{
 export type ManifestKind = (typeof PLUGIN_LAYOUTS)[number]['kind'];
 /** Kimi Code's primary spelling precedes its compatibility spelling within that dialect. */
 export declare const MANIFEST_ALIASES: Partial<Record<ManifestKind, readonly string[]>>;
+/**
+ * This client's Agent Plugins extension namespace (§8): manifest data rides
+ * `plugin.json` `extensions` under this key, and file-based extensions live
+ * in the top-level directory named exactly this. The namespace contract
+ * version is declared inside the manifest data.
+ */
+export declare const EXTENSION_NAMESPACE = "com.deepseek.harness";
+/** Namespace contract versions this manager implements. */
+export declare const NAMESPACE_SCHEMA_VERSIONS: ReadonlySet<string>;
+/** Namespace directory locations, relative to the plugin root. */
+export declare const NAMESPACE_DIR = "com.deepseek.harness";
+export declare const NAMESPACE_HOOKS_FILE: string;
+export declare const NAMESPACE_LSP_FILE: string;
 /** Equivalent plugin-owned path variables; these never resolve as credentials. */
 export declare const PLUGIN_ROOT_VARIABLES: ReadonlySet<string>;
 export declare const PLUGIN_DATA_VARIABLES: ReadonlySet<string>;
+/** Equivalent session project-directory variables; only a calling session supplies the directory. */
+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";
 /** Explicit project document formats and portable surfaces; execution stays in the runtime adapters. */
 export type ProjectMcpFormat = 'mcpServers' | 'zcode' | 'codex';
 export type ProjectHookFormat = 'claude' | 'zcode';
@@ -50,6 +67,11 @@ export interface ProjectLayout {
     label: string;
     subdirs: readonly string[];
     mcpFiles?: readonly string[];
+    /**
+     * Project-root-relative hook documents, read in order. A `settings.json`
+     * layer carries a `hooks` key; a standalone `hooks.json` may instead be the
+     * bare event table, the same file shape a suite ships under `hooks/`.
+     */
     hookFiles?: readonly string[];
     mcpFormat?: ProjectMcpFormat;
     hookFormat?: ProjectHookFormat;
@@ -64,6 +86,7 @@ export declare const PROJECT_LAYOUTS: readonly [{
     readonly dirName: ".agents";
     readonly label: "agents";
     readonly subdirs: readonly ["skills", "agents", "commands"];
+    readonly hookFiles: readonly [".agents/hooks/hooks.json", ".agents/hooks.json"];
 }, {
     readonly dirName: ".codex";
     readonly label: "Codex";
@@ -100,3 +123,10 @@ export declare const PROJECT_LAYOUTS: readonly [{
 }];
 /** Marketplace catalogs follow manifest layout order; the shared root catalog is the fallback. */
 export declare const MARKETPLACE_PATHS: readonly string[];
+/**
+ * Inline top-level manifest keys this manager reads for the portable v1
+ * dialect. The specification's closed manifest schema carries none of them
+ * (§5.2, §6.1), so under `agent-plugin-v1` they are reported as unknown
+ * top-level fields and ignored; every other dialect keeps reading them.
+ */
+export declare const V1_IGNORED_MANIFEST_KEYS: readonly string[];

package/lib/types/model/preset-source.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The source record this plugin presets.
+ *
+ * The first-party collection lives in its own repository. The plugin ships one
+ * registration pointing at it, so a fresh install lists the repository without
+ * anyone pasting a URL; from there it is an ordinary Git source — refresh to
+ * clone, then install and toggle its suites. Nothing marks it as different, and
+ * no setting owns it.
+ *
+ * @module model/preset-source
+ */
+import type { SourceRef } from './types.js';
+/** Source id the preset record registers under. */
+export declare const PRESET_SOURCE_ID = "dsh-agent-plugins";
+/** Repository the preset record points at. */
+export declare const PRESET_SOURCE_URL = "https://github.com/Sivan757/dsh-agent-plugins.git";
+/** The preset registration, as the market stores it. */
+export declare function presetSourceRef(): SourceRef;

package/lib/types/model/types.d.ts

@@ -67,6 +67,8 @@ export interface SuiteManifest {
     keywords?: string[];
     /** For agent-plugin-v1: the recognized `$schema` identifier. */
     schemaVersion?: string;
+    /** Parsed `com.deepseek.harness` extension data; present when the suite declares the namespace. */
+    harness?: HarnessNamespace;
 }
 /** Raw layout declarations are resolved once by the catalog into runtime resources. */
 export interface SuiteComponents {
@@ -110,6 +112,40 @@ export interface SuiteSurfaceCounts {
     agents: number;
     lsp: number;
 }
+/**
+ * Client-specific manifest data under the `com.deepseek.harness` extension
+ * namespace (Agent Plugins §8.1), carried by `plugin.json` `extensions`.
+ */
+export interface HarnessExtension {
+    /** Namespace contract version this suite was written against. */
+    schemaVersion: string;
+    /**
+     * Client policy for portable `mcp.json` servers, keyed by the server's own
+     * name in `mcp.json`; entries without a matching server are reported and
+     * ignored.
+     */
+    mcpServers?: Record<string, HarnessMcpPolicy>;
+}
+/**
+ * dsh-owned per-server policy for a portable MCP server: OAuth 2.1
+ * authorization for servers that answer `401` with a challenge, tool
+ * allow/deny lists, and timeout policies. These fields are outside the
+ * portable `mcp.json` schema by design (§7.2.1), so they ride the extension
+ * namespace instead of the package file.
+ */
+export interface HarnessMcpPolicy extends McpServerPolicy {
+    /** Opt in to OAuth 2.1 authorization (on by default; `enabled: false` opts out). */
+    auth?: {
+        enabled: boolean;
+        scope?: string;
+    };
+}
+/** Parsed namespace extension data of one suite, with server names pre-matched. */
+export interface HarnessNamespace {
+    schemaVersion: string;
+    /** Policy applied on top of the suite's portable MCP servers. */
+    mcpServers: Record<string, HarnessMcpPolicy>;
+}
 /** agent-plugins.org v1 `mcp.json` server variants. */
 export interface McpServerPolicy {
     enabledTools?: string[];
@@ -128,7 +164,7 @@ export interface McpServerStreamableHttp extends McpServerPolicy {
     type: 'streamable-http';
     url: string;
     headers?: Record<string, string>;
-    /** Opt in to OAuth 2.1 authorization for servers that answer `401` with a challenge (on by default; `enabled: false` opts out). */
+    /** OAuth 2.1 authorization; portable files take it from the namespace policy, dialect-native files declare it inline. */
     auth?: {
         enabled: boolean;
         scope?: string;