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

package/dist/src/tools/admin-install-local.d.ts

@@ -0,0 +1,30 @@
+import { type LocalInstallRuntime } from "@honua/sdk-js/local-install";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    directory: z.ZodString;
+    profile: z.ZodDefault<z.ZodEnum<["quickstart", "gp-dev"]>>;
+    httpPort: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    confirm: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    directory: string;
+    profile: "quickstart" | "gp-dev";
+    httpPort: number;
+    timeoutMs: number;
+    confirm: true;
+}, {
+    directory: string;
+    confirm: true;
+    profile?: "quickstart" | "gp-dev" | undefined;
+    httpPort?: number | undefined;
+    timeoutMs?: number | undefined;
+}>;
+export type AdminInstallLocalInput = z.infer<typeof schema>;
+export declare function execute(input: AdminInstallLocalInput, runtime?: LocalInstallRuntime): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+}>;
+//# sourceMappingURL=admin-install-local.d.ts.map

package/dist/src/tools/admin-install-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-install-local.d.ts","sourceRoot":"","sources":["../../../src/tools/admin-install-local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAqB,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;EAMjB,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE5D,wBAAsB,OAAO,CAAC,KAAK,EAAE,sBAAsB,EAAE,OAAO,GAAE,mBAAwB;;;;;;GAe7F"}

package/dist/src/tools/admin-install-local.js

@@ -0,0 +1,22 @@
+import { installHonuaLocal } from "@honua/sdk-js/local-install";
+import { z } from "zod";
+export const schema = z.object({
+    directory: z.string().min(1).describe("Directory that will own compose.yaml, .env, and MCP configuration."),
+    profile: z.enum(["quickstart", "gp-dev"]).default("quickstart"),
+    httpPort: z.number().int().min(1).max(65535).default(8080),
+    timeoutMs: z.number().int().min(1_000).max(600_000).default(180_000),
+    confirm: z.literal(true).describe("Explicit approval to create files and start Docker containers."),
+});
+export async function execute(input, runtime = {}) {
+    const result = await installHonuaLocal({
+        directory: input.directory,
+        profile: input.profile,
+        httpPort: input.httpPort,
+        timeoutMs: input.timeoutMs,
+    }, runtime);
+    const structuredContent = { ...result };
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent,
+    };
+}

package/dist/src/tools/control-plane-command.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The MCP transport adapter for the shared control-plane command layer.
+ *
+ * Every tool registered here is *generated* from `HONUA_COMMANDS` in
+ * `@honua/sdk-js/control-plane`: the name, title, description, and argument
+ * schema are projections of the command's own declaration, and the handler
+ * does exactly three things — build a `HonuaCommandInvocation`, call
+ * `HonuaCommandRuntime.execute`, and render the returned receipt. There is no
+ * MCP-side sequencing, no MCP-side validation beyond the projected schema, and
+ * no MCP-side authorization: an equivalent `honua map publish` invocation, an
+ * equivalent Studio invocation, and a direct `runtime.execute(...)` call all
+ * produce the same receipt and the same `auditKey`, differing only in the
+ * recorded `transport`.
+ *
+ * ## Why the projected object is `passthrough`
+ *
+ * A Zod object strips unknown keys by default. Stripping here would mean an
+ * agent that sent `approvedBy` got a *silent success* instead of the shared
+ * typed refusal, and MCP would then be the one transport where a sealed input
+ * schema is enforced by omission rather than by the command. So the projection
+ * lets unknown keys through to the runtime, where the command's closed schema
+ * (`additionalProperties: false`) rejects them with the same `validation`
+ * `HonuaCommandError` every other transport gets.
+ *
+ * ## What an agent may not assert
+ *
+ * The tool arguments carry no identity fields and no request headers. Acting
+ * identity and tenant come from the host that constructed the runtime — a
+ * model-supplied `actor` would be an authority claim dressed as an argument.
+ * `Idempotency-Key` and `If-Match` are likewise not header inputs: `ifMatch`
+ * and `idempotencyKey` travel as invocation fields so the value on the wire is
+ * the value the receipt records.
+ *
+ * @module
+ */
+import { type HonuaAnyCommand, type HonuaCommandIdentity, type HonuaCommandRuntime } from "@honua/sdk-js/control-plane";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+/** Prefix every generated command tool carries. */
+export declare const CONTROL_PLANE_COMMAND_TOOL_PREFIX = "honua_command_";
+/**
+ * Host wiring for the command tools.
+ *
+ * The host owns the credential (through the runtime's client) and the acting
+ * identity echo. Neither is reachable from tool arguments.
+ */
+export interface ControlPlaneCommandMcpHost {
+    /** Runtime built from the caller's own `HonuaClient`; never a shared admin key. */
+    readonly runtime: HonuaCommandRuntime;
+    /** Acting identity echoed onto every receipt. Host-supplied, never model-supplied. */
+    readonly identity?: HonuaCommandIdentity;
+}
+/** `map-package.publish` → `honua_command_map_package_publish`. */
+export declare function controlPlaneCommandToolName(commandId: string): string;
+/**
+ * Project a command's JSON-schema input into the tool's argument schema.
+ *
+ * `input` is the command's own declared shape; the three siblings are the
+ * invocation fields a caller is allowed to set. The outer object is `strict`
+ * so an unknown *invocation* field is an MCP-level mistake, while the inner
+ * object is `passthrough` so an unknown *input* field reaches the command's
+ * sealed schema and is refused there.
+ */
+export declare function controlPlaneCommandToolSchema(command: HonuaAnyCommand): z.ZodObject<{
+    input: z.ZodTypeAny;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    ifMatch: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    input?: any;
+    dryRun?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    ifMatch?: string | undefined;
+}, {
+    input?: any;
+    dryRun?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    ifMatch?: string | undefined;
+}>;
+type ControlPlaneCommandToolArgs = z.infer<ReturnType<typeof controlPlaneCommandToolSchema>>;
+/**
+ * Run one command for the MCP transport and render its receipt.
+ *
+ * A {@link HonuaCommandError} is returned as a tool error carrying the shared
+ * serialized taxonomy, not rethrown as an opaque MCP failure: an agent has to
+ * be able to tell a `validation` refusal from a `conflict` it should retry.
+ */
+export declare function execute(host: ControlPlaneCommandMcpHost, command: HonuaAnyCommand, args: ControlPlaneCommandToolArgs): Promise<CallToolResult>;
+/**
+ * Register one MCP tool per catalog command.
+ *
+ * Opt-in, exactly like the NL map-control tools: the platform-free standalone
+ * catalog stays read-only and Honua-server-free unless a host supplies a
+ * control-plane runtime.
+ */
+export declare function registerControlPlaneCommandTools(server: McpServer, host: ControlPlaneCommandMcpHost): void;
+export {};
+//# sourceMappingURL=control-plane-command.d.ts.map

package/dist/src/tools/control-plane-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane-command.d.ts","sourceRoot":"","sources":["../../../src/tools/control-plane-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAEL,KAAK,eAAe,EAEpB,KAAK,oBAAoB,EAGzB,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,mDAAmD;AACnD,eAAO,MAAM,iCAAiC,mBAAmB,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC1C;AAED,mEAAmE;AACnE,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,eAAe;;;;;;;;;;;;;;;GAgBrE;AAED,KAAK,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,6BAA6B,CAAC,CAAC,CAAC;AAE7F;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,2BAA2B,GAChC,OAAO,CAAC,cAAc,CAAC,CAsBzB;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,0BAA0B,GAAG,IAAI,CAkB1G"}

package/dist/src/tools/control-plane-command.js

@@ -0,0 +1,180 @@
+/**
+ * The MCP transport adapter for the shared control-plane command layer.
+ *
+ * Every tool registered here is *generated* from `HONUA_COMMANDS` in
+ * `@honua/sdk-js/control-plane`: the name, title, description, and argument
+ * schema are projections of the command's own declaration, and the handler
+ * does exactly three things — build a `HonuaCommandInvocation`, call
+ * `HonuaCommandRuntime.execute`, and render the returned receipt. There is no
+ * MCP-side sequencing, no MCP-side validation beyond the projected schema, and
+ * no MCP-side authorization: an equivalent `honua map publish` invocation, an
+ * equivalent Studio invocation, and a direct `runtime.execute(...)` call all
+ * produce the same receipt and the same `auditKey`, differing only in the
+ * recorded `transport`.
+ *
+ * ## Why the projected object is `passthrough`
+ *
+ * A Zod object strips unknown keys by default. Stripping here would mean an
+ * agent that sent `approvedBy` got a *silent success* instead of the shared
+ * typed refusal, and MCP would then be the one transport where a sealed input
+ * schema is enforced by omission rather than by the command. So the projection
+ * lets unknown keys through to the runtime, where the command's closed schema
+ * (`additionalProperties: false`) rejects them with the same `validation`
+ * `HonuaCommandError` every other transport gets.
+ *
+ * ## What an agent may not assert
+ *
+ * The tool arguments carry no identity fields and no request headers. Acting
+ * identity and tenant come from the host that constructed the runtime — a
+ * model-supplied `actor` would be an authority claim dressed as an argument.
+ * `Idempotency-Key` and `If-Match` are likewise not header inputs: `ifMatch`
+ * and `idempotencyKey` travel as invocation fields so the value on the wire is
+ * the value the receipt records.
+ *
+ * @module
+ */
+import { HONUA_COMMANDS, HonuaCommandError, } from "@honua/sdk-js/control-plane";
+import { z } from "zod";
+/** Prefix every generated command tool carries. */
+export const CONTROL_PLANE_COMMAND_TOOL_PREFIX = "honua_command_";
+/** `map-package.publish` → `honua_command_map_package_publish`. */
+export function controlPlaneCommandToolName(commandId) {
+    return `${CONTROL_PLANE_COMMAND_TOOL_PREFIX}${commandId.replace(/[.-]/g, "_")}`;
+}
+/**
+ * Project a command's JSON-schema input into the tool's argument schema.
+ *
+ * `input` is the command's own declared shape; the three siblings are the
+ * invocation fields a caller is allowed to set. The outer object is `strict`
+ * so an unknown *invocation* field is an MCP-level mistake, while the inner
+ * object is `passthrough` so an unknown *input* field reaches the command's
+ * sealed schema and is refused there.
+ */
+export function controlPlaneCommandToolSchema(command) {
+    return z
+        .object({
+        input: zodForSchema(command.inputSchema),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("Preview the plan without contacting the server. The command never reaches `execute`."),
+        idempotencyKey: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Explicit Idempotency-Key. Derived deterministically from the input when omitted."),
+        ifMatch: z.string().min(1).optional().describe("Optimistic-concurrency validator, sent as If-Match."),
+    })
+        .strict();
+}
+/**
+ * Run one command for the MCP transport and render its receipt.
+ *
+ * A {@link HonuaCommandError} is returned as a tool error carrying the shared
+ * serialized taxonomy, not rethrown as an opaque MCP failure: an agent has to
+ * be able to tell a `validation` refusal from a `conflict` it should retry.
+ */
+export async function execute(host, command, args) {
+    const invocation = {
+        transport: "mcp",
+        ...(host.identity ? { identity: host.identity } : {}),
+        ...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}),
+        ...(args.ifMatch ? { ifMatch: args.ifMatch } : {}),
+        ...(args.dryRun ? { dryRun: true } : {}),
+    };
+    try {
+        const receipt = await host.runtime.execute(command, args.input, invocation);
+        return { content: [{ type: "text", text: JSON.stringify(receipt, null, 2) }] };
+    }
+    catch (error) {
+        if (error instanceof HonuaCommandError) {
+            return {
+                isError: true,
+                content: [
+                    { type: "text", text: JSON.stringify({ ...error.toJSON(), message: error.message }, null, 2) },
+                ],
+            };
+        }
+        throw error;
+    }
+}
+/**
+ * Register one MCP tool per catalog command.
+ *
+ * Opt-in, exactly like the NL map-control tools: the platform-free standalone
+ * catalog stays read-only and Honua-server-free unless a host supplies a
+ * control-plane runtime.
+ */
+export function registerControlPlaneCommandTools(server, host) {
+    for (const command of Object.values(HONUA_COMMANDS)) {
+        server.registerTool(controlPlaneCommandToolName(command.id), {
+            title: command.title,
+            description: `${command.description} Runs the shared \`${command.id}\` control-plane command and returns its deterministic receipt; the receipt's auditKey matches the equivalent CLI, Studio, or direct-JS invocation.`,
+            inputSchema: controlPlaneCommandToolSchema(command),
+            annotations: {
+                readOnlyHint: command.mode === "read",
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async (args) => execute(host, command, args));
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON Schema → Zod projection
+// ---------------------------------------------------------------------------
+function zodForSchema(schema) {
+    const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+    let base;
+    switch (type) {
+        case "string": {
+            let value = z.string();
+            if (schema.minLength !== undefined)
+                value = value.min(schema.minLength);
+            if (schema.maxLength !== undefined)
+                value = value.max(schema.maxLength);
+            base = value;
+            break;
+        }
+        case "integer":
+        case "number": {
+            let value = z.number();
+            if (type === "integer")
+                value = value.int();
+            if (schema.minimum !== undefined)
+                value = value.min(schema.minimum);
+            if (schema.maximum !== undefined)
+                value = value.max(schema.maximum);
+            base = value;
+            break;
+        }
+        case "boolean":
+            base = z.boolean();
+            break;
+        case "array":
+            base = z.array(schema.items ? zodForSchema(schema.items) : z.unknown());
+            break;
+        case "object":
+            base = zodForObject(schema);
+            break;
+        default:
+            base = z.unknown();
+            break;
+    }
+    return schema.description ? base.describe(schema.description) : base;
+}
+function zodForObject(schema) {
+    const properties = schema.properties;
+    // An object with no declared properties (`options` on `import.create`) is a
+    // free-form bag the command passes through verbatim.
+    if (!properties)
+        return z.record(z.unknown());
+    const required = new Set(schema.required ?? []);
+    const shape = {};
+    for (const [name, property] of Object.entries(properties)) {
+        const value = zodForSchema(property);
+        shape[name] = required.has(name) ? value : value.optional();
+    }
+    // Passthrough is deliberate — see this module's header.
+    return z.object(shape).passthrough();
+}

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"}