@honua/mcp-server 0.1.2-beta.0 → 0.1.4-beta.0

package/dist/src/neutral/source-ref.js

@@ -0,0 +1,267 @@
+import { HonuaCapabilityNotSupportedError } from "@honua/sdk-js";
+import { PROTOCOL_DEFAULT_CAPABILITIES, createDataset } from "@honua/sdk-js/contract";
+import { z } from "zod";
+/**
+ * PROTOCOL-NEUTRAL source addressing for the MCP tool contract (issue #1005).
+ *
+ * The tool surface used to address data the way GeoServices does — a required
+ * `serviceId` string plus a required numeric `layerId`. That vocabulary is
+ * meaningless on OGC API Features, STAC, WFS, and OData, so a "vendor-neutral"
+ * server whose only addressing mode is Esri-shaped concedes the claim on
+ * inspection.
+ *
+ * A source is now addressed the way the SDK addresses one: a
+ * `SourceDescriptor` (protocol + locator) resolved into a canonical
+ * `Source` through `createDataset`. Over the wire that descriptor is carried as
+ * one compact string:
+ *
+ * ```text
+ * <protocol>:<address>
+ * ```
+ *
+ * | protocol                        | address form          | example                                |
+ * | ------------------------------- | --------------------- | -------------------------------------- |
+ * | `geoservices-feature-service`   | `<serviceId>/<layer>` | `geoservices-feature-service:Parks/0`  |
+ * | `geoservices-map-service`       | `<serviceId>/<layer>` | `geoservices-map-service:Basemap/2`    |
+ * | `ogc-features`                  | `<collectionId>`      | `ogc-features:hotels`                  |
+ * | `ogc-records`                   | `<collectionId>`      | `ogc-records:catalog`                  |
+ * | `stac`                          | `<collectionId>`      | `stac:sentinel-2-l2a`                  |
+ * | `wfs`                           | `<typeName>`          | `wfs:topp:states`                      |
+ * | `odata`                         | `<entitySet>`         | `odata:People`                         |
+ *
+ * `honua_list_sources` emits exactly these strings, so the normal agent flow is
+ * discover-then-address with no parsing on the client side. The reference is
+ * deliberately fail-closed: an unrecognized protocol token is refused with the
+ * accepted forms rather than guessed at, because guessing "which protocol did
+ * they mean" is how a neutral surface silently becomes a single-vendor one.
+ *
+ * The legacy `serviceId` + `layerId` pair is still accepted (see
+ * {@link legacyGeoServicesRef}) but is deprecated and is no longer *required* by
+ * any schema.
+ */
+/** Protocols reachable through a `<protocol>:<address>` source reference. */
+export const SOURCE_REF_PROTOCOLS = [
+    "geoservices-feature-service",
+    "geoservices-map-service",
+    "ogc-features",
+    "ogc-records",
+    "stac",
+    "wfs",
+    "odata",
+];
+/** Short, human-friendly aliases accepted in place of the canonical token. */
+const PROTOCOL_ALIASES = {
+    geoservices: "geoservices-feature-service",
+    "feature-service": "geoservices-feature-service",
+    featureserver: "geoservices-feature-service",
+    "map-service": "geoservices-map-service",
+    mapserver: "geoservices-map-service",
+    ogc: "ogc-features",
+    "ogc-api-features": "ogc-features",
+    features: "ogc-features",
+    records: "ogc-records",
+};
+/** Endpoint layouts an OGC API / STAC source may be published under. */
+export const SOURCE_LAYOUTS = ["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"];
+export class SourceRefError extends Error {
+    code = "INVALID_SOURCE_REFERENCE";
+    constructor(message) {
+        super(message);
+        this.name = "SourceRefError";
+    }
+}
+const ACCEPTED_FORMS = SOURCE_REF_PROTOCOLS.map((protocol) => {
+    switch (protocol) {
+        case "geoservices-feature-service":
+        case "geoservices-map-service":
+            return `${protocol}:<serviceId>/<layerId>`;
+        case "wfs":
+            return `${protocol}:<typeName>`;
+        case "odata":
+            return `${protocol}:<entitySet>`;
+        default:
+            return `${protocol}:<collectionId>`;
+    }
+}).join(", ");
+function normalizeProtocolToken(token) {
+    const normalized = token.trim().toLowerCase();
+    if (SOURCE_REF_PROTOCOLS.includes(normalized)) {
+        return normalized;
+    }
+    return PROTOCOL_ALIASES[normalized];
+}
+/**
+ * Parse a `<protocol>:<address>` source reference. Fails closed: an omitted or
+ * unrecognized protocol token is refused with the accepted forms instead of
+ * being inferred, so a mistyped reference can never silently resolve against
+ * the wrong protocol.
+ */
+export function parseSourceRef(raw, layout) {
+    const value = raw.trim();
+    if (value.length === 0) {
+        throw new SourceRefError(`source must be a non-empty "<protocol>:<address>" reference. Accepted: ${ACCEPTED_FORMS}`);
+    }
+    const separator = value.indexOf(":");
+    if (separator < 0) {
+        throw new SourceRefError(`source "${raw}" is missing its protocol prefix. Use "<protocol>:<address>" (accepted: ${ACCEPTED_FORMS}), or call honua_list_sources to discover exact source references.`);
+    }
+    const protocol = normalizeProtocolToken(value.slice(0, separator));
+    if (!protocol) {
+        throw new SourceRefError(`source "${raw}" names an unknown protocol "${value.slice(0, separator)}". Accepted: ${ACCEPTED_FORMS}.`);
+    }
+    // The address keeps every remaining colon: a WFS typeName is namespace-qualified
+    // (`topp:states`) and splitting it again would corrupt the identifier.
+    const address = value.slice(separator + 1).trim();
+    if (address.length === 0) {
+        throw new SourceRefError(`source "${raw}" is missing its address. Accepted: ${ACCEPTED_FORMS}.`);
+    }
+    return { ref: `${protocol}:${address}`, protocol, address, ...(layout ? { layout } : {}) };
+}
+/** Build the canonical reference for the deprecated GeoServices `serviceId`/`layerId` pair. */
+export function legacyGeoServicesRef(serviceId, layerId) {
+    return `geoservices-feature-service:${serviceId}/${layerId}`;
+}
+function splitGeoServicesAddress(ref) {
+    const slash = ref.address.lastIndexOf("/");
+    if (slash <= 0 || slash === ref.address.length - 1) {
+        throw new SourceRefError(`source "${ref.ref}" must address a layer as "<serviceId>/<layerId>" (e.g. "${ref.protocol}:Parks/0").`);
+    }
+    const serviceId = ref.address.slice(0, slash);
+    const rawLayer = ref.address.slice(slash + 1);
+    if (!/^\d+$/.test(rawLayer)) {
+        throw new SourceRefError(`source "${ref.ref}" has a non-numeric layer id "${rawLayer}"; expected a whole number.`);
+    }
+    return { serviceId, layerId: Number.parseInt(rawLayer, 10) };
+}
+/** Project a parsed reference onto the SDK's protocol-neutral `SourceLocator`. */
+export function toSourceLocator(ref, baseUrl) {
+    const layout = ref.layout && ref.layout !== "honua-facade" ? { layout: ref.layout } : {};
+    switch (ref.protocol) {
+        case "geoservices-feature-service":
+        case "geoservices-map-service": {
+            const { serviceId, layerId } = splitGeoServicesAddress(ref);
+            return { url: baseUrl, serviceId, layerId };
+        }
+        case "ogc-features":
+        case "ogc-records":
+        case "stac":
+            return { url: baseUrl, collectionId: ref.address, ...layout };
+        case "wfs":
+            return { url: baseUrl, typeName: ref.address };
+        case "odata":
+            return { url: baseUrl, entitySet: ref.address };
+    }
+}
+/** Build the `SourceDescriptor` a reference denotes, without contacting the endpoint. */
+export function toSourceDescriptor(ref, baseUrl) {
+    return {
+        id: ref.ref,
+        protocol: ref.protocol,
+        locator: toSourceLocator(ref, baseUrl),
+        capabilities: PROTOCOL_DEFAULT_CAPABILITIES[ref.protocol],
+    };
+}
+/**
+ * Zod fields every source-addressed tool mixes into its input schema.
+ *
+ * `source` is the protocol-neutral reference; `serviceId`/`layerId` remain as
+ * OPTIONAL, deprecated compatibility inputs so existing MCP clients keep
+ * working. No Esri-only field is required by any tool schema.
+ */
+export const sourceRefFields = {
+    source: z
+        .string()
+        .optional()
+        .describe('Protocol-neutral source reference "<protocol>:<address>" as emitted by honua_list_sources — e.g. "ogc-features:hotels", "stac:sentinel-2-l2a", "wfs:topp:states", "odata:People", "geoservices-feature-service:Parks/0". Preferred over the deprecated serviceId/layerId pair.'),
+    layout: z
+        .enum(SOURCE_LAYOUTS)
+        .optional()
+        .describe('Endpoint layout for OGC API / STAC sources: "honua-facade" (default, Honua server paths), "ogc-api"/"auto" (third-party OGC API root), "stac-api"/"stac-static" (STAC). Ignored by other protocols.'),
+    serviceId: z
+        .string()
+        .optional()
+        .describe("[DEPRECATED — use `source`] GeoServices service id. Only meaningful on an Esri FeatureServer/MapServer."),
+    layerId: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("[DEPRECATED — use `source`] GeoServices layer id within the service. Required with `serviceId`."),
+};
+/** Resolve the neutral reference an input addresses (without building a `Source`). */
+export function resolveSourceRef(input) {
+    if (input.source !== undefined && input.source.trim().length > 0) {
+        return { ref: parseSourceRef(input.source, input.layout), legacyAddressing: false };
+    }
+    if (input.serviceId !== undefined && input.serviceId.trim().length > 0) {
+        if (input.layerId === undefined) {
+            throw new SourceRefError(`serviceId "${input.serviceId}" was given without layerId. Pass both, or (preferred) a protocol-neutral \`source\` reference such as "geoservices-feature-service:${input.serviceId}/0".`);
+        }
+        return {
+            ref: parseSourceRef(legacyGeoServicesRef(input.serviceId, input.layerId), input.layout),
+            legacyAddressing: true,
+        };
+    }
+    if (input.layerId !== undefined) {
+        throw new SourceRefError("layerId was given without serviceId. Pass both, or (preferred) a protocol-neutral `source` reference.");
+    }
+    throw new SourceRefError(`no source was addressed. Pass \`source\` as "<protocol>:<address>" (accepted: ${ACCEPTED_FORMS}); call honua_list_sources to discover the exact references this endpoint serves.`);
+}
+/**
+ * Resolve an input onto a canonical `Source`.
+ *
+ * The dataset runs under the `degraded` capability policy so a protocol that
+ * cannot serve a request first-party (OGC API Features has no server-side
+ * aggregation, for example) answers with an explicit `Result.degraded` reason
+ * instead of failing outright. Capabilities the protocol cannot serve at all
+ * still throw `HonuaCapabilityNotSupportedError`, which the tool layer turns
+ * into a structured tool error — never a silent empty result.
+ */
+export function resolveSource(client, input) {
+    const { ref, legacyAddressing } = resolveSourceRef(input);
+    const descriptor = toSourceDescriptor(ref, client.serverBaseUrl);
+    const dataset = createDataset({
+        id: `honua-mcp:${ref.ref}`,
+        client,
+        sources: [descriptor],
+        capabilityPolicy: "degraded",
+        // The standalone server points at arbitrary public endpoints; a Honua
+        // server-version handshake is neither available nor meaningful there.
+        skipCompatibilityCheck: true,
+    });
+    let source;
+    try {
+        source = dataset.source(descriptor.id);
+    }
+    catch (error) {
+        // A capability refusal is the SDK's own honest signal and travels as-is.
+        // Anything else (an incomplete locator, a runtime that cannot construct the
+        // protocol adapter) becomes an actionable addressing error rather than an
+        // opaque stack trace.
+        if (error instanceof HonuaCapabilityNotSupportedError) {
+            throw error;
+        }
+        throw new SourceRefError(`source "${ref.ref}" could not be resolved to a runtime adapter: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!source) {
+        throw new SourceRefError(`source "${ref.ref}" could not be resolved to a runtime adapter.`);
+    }
+    return { ref, descriptor, source, legacyAddressing };
+}
+/** True when a resolved source speaks a GeoServices (Esri) protocol. */
+export function isGeoServicesProtocol(protocol) {
+    return protocol.startsWith("geoservices-") || protocol === "grpc";
+}
+/**
+ * Resolve the OGC API Features endpoint layout a metadata call must use.
+ *
+ * `honua-facade` (the default) needs no resolution; a third-party OGC API root
+ * is discovered from its landing page once and cached on the client. STAC
+ * layouts are not OGC API Features layouts and resolve to `undefined`.
+ */
+export function ogcLayoutFor(client, layout) {
+    if (layout === "ogc-api" || layout === "auto") {
+        return client.resolveOgcFeaturesLayout(layout);
+    }
+    return Promise.resolve(undefined);
+}

package/dist/src/nl-map-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nl-map-control.d.ts","sourceRoot":"","sources":["../../src/nl-map-control.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nl-map-control.d.ts","sourceRoot":"","sources":["../../src/nl-map-control.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/count-features.d.ts

@@ -1,32 +1,106 @@
 import type { HonuaClient } from "@honua/sdk-js";
+import type { CapabilityAwareSource, Query } from "@honua/sdk-js/contract";
 import { z } from "zod";
+import { projectDegraded } from "../neutral/result.js";
+/**
+ * `honua_count_features` — protocol-neutral cardinality check (#1005).
+ *
+ * There is no single "count" verb across the protocols, so the count is taken
+ * from whichever canonical path the source's declared capabilities support:
+ *
+ *  1. `queryExtent` (GeoServices, WFS, gRPC) returns an exact server count
+ *     alongside the envelope in one round trip.
+ *  2. otherwise a single-record `query` reports `totalCount`, which is where
+ *     OGC API Features / STAC / OData carry `numberMatched`.
+ *
+ * When neither path yields a number the tool refuses with a structured
+ * capability error rather than reporting `0`.
+ */
 export declare const schema: z.ZodObject<{
-    serviceId: z.ZodString;
-    layerId: z.ZodNumber;
+    filter: z.ZodOptional<z.ZodType<import("../neutral/filter.js").FilterNode, z.ZodTypeDef, import("../neutral/filter.js").FilterNode>>;
     where: z.ZodOptional<z.ZodString>;
+    bbox: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    bboxSrid: z.ZodOptional<z.ZodNumber>;
     geometry: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     geometryType: z.ZodOptional<z.ZodEnum<["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"]>>;
-    spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within"]>>;
+    spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within", "crosses", "touches", "overlaps", "bbox-intersects"]>>;
+    temporal: z.ZodOptional<z.ZodObject<{
+        instant: z.ZodOptional<z.ZodString>;
+        start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        end: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        field: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    }, {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    }>>;
+    source: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"]>>;
+    serviceId: z.ZodOptional<z.ZodString>;
+    layerId: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    serviceId: string;
-    layerId: number;
-    where?: string | undefined;
+    filter?: import("../neutral/filter.js").FilterNode | undefined;
+    serviceId?: string | undefined;
     geometry?: Record<string, unknown> | undefined;
+    bbox?: number[] | undefined;
     geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
-    spatialRel?: "intersects" | "contains" | "within" | undefined;
-}, {
-    serviceId: string;
-    layerId: number;
+    temporal?: {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    } | undefined;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    layerId?: number | undefined;
+    source?: string | undefined;
     where?: string | undefined;
+    bboxSrid?: number | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | "crosses" | "touches" | "overlaps" | "bbox-intersects" | undefined;
+}, {
+    filter?: import("../neutral/filter.js").FilterNode | undefined;
+    serviceId?: string | undefined;
     geometry?: Record<string, unknown> | undefined;
+    bbox?: number[] | undefined;
     geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
-    spatialRel?: "intersects" | "contains" | "within" | undefined;
+    temporal?: {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    } | undefined;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    layerId?: number | undefined;
+    source?: string | undefined;
+    where?: string | undefined;
+    bboxSrid?: number | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | "crosses" | "touches" | "overlaps" | "bbox-intersects" | undefined;
 }>;
 export type Input = z.infer<typeof schema>;
+interface CountOutcome {
+    count: number;
+    strategy: "queryExtent" | "totalCount";
+    degraded: ReturnType<typeof projectDegraded>;
+}
+/** Resolve a feature count through the canonical `Source` surface. */
+export declare function countThroughSource(source: CapabilityAwareSource, query: Query, protocol: string, sourceId: string): Promise<CountOutcome>;
 export declare function execute(client: HonuaClient, input: Input): Promise<{
     content: Array<{
         type: "text";
         text: string;
     }>;
+} | {
+    structuredContent: Record<string, unknown>;
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
 }>;
+export {};
 //# sourceMappingURL=count-features.d.ts.map

package/dist/src/tools/count-features.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"count-features.d.ts","sourceRoot":"","sources":["../../../src/tools/count-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;EAajB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAqB9D"}
+{"version":3,"file":"count-features.d.ts","sourceRoot":"","sources":["../../../src/tools/count-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,UAAU,YAAY;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,GAAG,YAAY,CAAC;IACvC,QAAQ,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;CAC9C;AAED,sEAAsE;AACtE,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAevB;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;GAmB9D"}

package/dist/src/tools/count-features.js

@@ -1,36 +1,54 @@
+import { HonuaCapabilityNotSupportedError } from "@honua/sdk-js";
 import { z } from "zod";
-import { GEOMETRY_TYPES, coerceCount, jsonText, mapSpatialRel, resolveGeometryType } from "../helpers.js";
+import { jsonText } from "../helpers.js";
+import { withCapabilityHonesty } from "../neutral/errors.js";
+import { queryFilterFields, toQuery } from "../neutral/query.js";
+import { projectDegraded } from "../neutral/result.js";
+import { resolveSource, sourceRefFields } from "../neutral/source-ref.js";
+/**
+ * `honua_count_features` — protocol-neutral cardinality check (#1005).
+ *
+ * There is no single "count" verb across the protocols, so the count is taken
+ * from whichever canonical path the source's declared capabilities support:
+ *
+ *  1. `queryExtent` (GeoServices, WFS, gRPC) returns an exact server count
+ *     alongside the envelope in one round trip.
+ *  2. otherwise a single-record `query` reports `totalCount`, which is where
+ *     OGC API Features / STAC / OData carry `numberMatched`.
+ *
+ * When neither path yields a number the tool refuses with a structured
+ * capability error rather than reporting `0`.
+ */
 export const schema = z.object({
-    serviceId: z.string().describe("The feature service ID"),
-    layerId: z.number().int().nonnegative().describe("The layer ID within the service"),
-    where: z.string().optional().describe("SQL WHERE clause, e.g. \"status = 'active'\""),
-    geometry: z.record(z.unknown()).optional().describe("Esri JSON geometry for spatial filter"),
-    geometryType: z
-        .enum(GEOMETRY_TYPES)
-        .optional()
-        .describe("Esri geometry type. If omitted, inferred from geometry when possible."),
-    spatialRel: z
-        .enum(["intersects", "contains", "within"])
-        .optional()
-        .describe("Spatial relationship (default: intersects)"),
+    ...sourceRefFields,
+    ...queryFilterFields,
 });
-export async function execute(client, input) {
-    const response = (await client.queryFeatures({
-        serviceId: input.serviceId,
-        layerId: input.layerId,
-        where: input.where,
-        geometry: input.geometry,
-        geometryType: resolveGeometryType(input.geometry, input.geometryType),
-        spatialRel: mapSpatialRel(input.spatialRel),
-        returnGeometry: false,
-        outFields: "OBJECTID",
-        extraParams: { returnCountOnly: true },
-    }));
-    // The default grpc-web transport returns very large counts as a string to
-    // preserve precision beyond Number.MAX_SAFE_INTEGER; accept both forms.
-    const count = coerceCount(response.count);
-    if (count === undefined) {
-        throw new Error("Count query did not return a numeric count.");
+/** Resolve a feature count through the canonical `Source` surface. */
+export async function countThroughSource(source, query, protocol, sourceId) {
+    if (source.capabilities.has("queryExtent")) {
+        const extent = await source.queryExtent(query);
+        if (typeof extent.count === "number" && Number.isFinite(extent.count)) {
+            return { count: extent.count, strategy: "queryExtent", degraded: undefined };
+        }
+    }
+    const probe = { ...query, returnGeometry: false, pagination: { ...query.pagination, limit: 1 } };
+    const result = await source.query(probe);
+    if (typeof result.totalCount === "number" && Number.isFinite(result.totalCount)) {
+        return { count: result.totalCount, strategy: "totalCount", degraded: projectDegraded(result.degraded) };
     }
-    return jsonText({ count });
+    throw new HonuaCapabilityNotSupportedError("count", protocol, sourceId);
+}
+export async function execute(client, input) {
+    return withCapabilityHonesty(async () => {
+        const resolved = resolveSource(client, input);
+        const query = toQuery(input, { protocol: resolved.descriptor.protocol, paginate: false });
+        const outcome = await countThroughSource(resolved.source, query, resolved.descriptor.protocol, resolved.descriptor.id);
+        return jsonText({
+            source: resolved.ref.ref,
+            protocol: resolved.descriptor.protocol,
+            count: outcome.count,
+            countStrategy: outcome.strategy,
+            ...(outcome.degraded ? { degraded: outcome.degraded } : {}),
+        });
+    });
 }

package/dist/src/tools/describe-layer.d.ts

@@ -1,14 +1,31 @@
 import type { HonuaClient } from "@honua/sdk-js";
 import { z } from "zod";
+/**
+ * `honua_describe_layer` — protocol-neutral source description (#1005).
+ *
+ * The envelope is the same for every protocol: the neutral source reference,
+ * its protocol, the capabilities the runtime will actually honor, and a field
+ * schema. Where the schema comes from is protocol-specific (GeoServices layer
+ * metadata, an OGC collection + its queryables); the shape the agent reads is
+ * not. Protocols with no metadata document report `schemaAvailable: false`
+ * with a reason instead of an empty field list, which would read as "this
+ * source has no attributes".
+ */
 export declare const schema: z.ZodObject<{
-    serviceId: z.ZodString;
-    layerId: z.ZodNumber;
+    source: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"]>>;
+    serviceId: z.ZodOptional<z.ZodString>;
+    layerId: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    serviceId: string;
-    layerId: number;
+    serviceId?: string | undefined;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    layerId?: number | undefined;
+    source?: string | undefined;
 }, {
-    serviceId: string;
-    layerId: number;
+    serviceId?: string | undefined;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    layerId?: number | undefined;
+    source?: string | undefined;
 }>;
 export type Input = z.infer<typeof schema>;
 export declare function execute(client: HonuaClient, input: Input): Promise<{
@@ -16,5 +33,12 @@ export declare function execute(client: HonuaClient, input: Input): Promise<{
         type: "text";
         text: string;
     }>;
+} | {
+    structuredContent: Record<string, unknown>;
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
 }>;
 //# sourceMappingURL=describe-layer.d.ts.map

package/dist/src/tools/describe-layer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-layer.d.ts","sourceRoot":"","sources":["../../../src/tools/describe-layer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;EAGjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAa9D"}
+{"version":3,"file":"describe-layer.d.ts","sourceRoot":"","sources":["../../../src/tools/describe-layer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;EAEjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AA+F3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;GAoB9D"}