@abot-ai/runtime 1.0.0

package/plugins/json-inspector/plugin.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "json-inspector",
+  "version": "0.3.1",
+  "description": "Validate a JSON file and return a bounded structural summary.",
+  "extensions": {
+    "ai.abot.runtime": {
+      "version": 1,
+      "entrypoint": "./src/index.cjs",
+      "catalogGroups": ["read"],
+      "settings": {
+        "defaults": {
+          "defaultDepth": 3
+        }
+      },
+      "capabilities": {
+        "inspect_json": {
+          "description": "Validate one JSON file and return a bounded structural summary. Relative paths resolve inside the configured agent work directory; `workspace/...` targets configured workspace sources.",
+          "routingCapability": "semantic_lookup",
+          "runtimePathBindings": [
+            { "operationId": "inspect_json", "param": "path", "base": "worker_working_directory" }
+          ],
+          "skills": ["json_inspector_skill"],
+          "operations": {
+            "inspect_json": {
+              "summary": "Validate and summarize JSON beneath the configured agent work directory, or beneath configured workspace sources when `workspace/...` is explicit.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  },
+                  "maxDepth": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 6
+                  }
+                },
+                "required": ["path"]
+              },
+              "effect": "read_only",
+              "approval": "request_policy"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/json-inspector/skills/json_inspector_skill/SKILL.md

@@ -0,0 +1,9 @@
+# JSON Inspector Skill
+
+Use `inspect_json` when a JSON artifact or configuration is central to the
+task. Validate its syntax and inspect its bounded shape before relying on or
+editing it. The tool diagnoses only; it never repairs or edits the file.
+
+Use `path` as the location contract: `.` and relative paths target the
+configured agent work directory, `workspace/...` targets configured workspace
+sources.

package/plugins/json-inspector/source/index.ts

@@ -0,0 +1,145 @@
+import { TextDecoder } from "node:util";
+
+import {
+  boundText,
+  defineRuntimePlugin,
+  failureFromError,
+  failureResult,
+  readBoundedRegularFile,
+  readBoundedInteger,
+  readRequiredString,
+  resolvePluginPath,
+  successResult,
+} from "../../../src/plugin-sdk/index.js";
+
+import { parseJsonErrorPosition, summarizeJsonShape } from "./shape.js";
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_DEPTH = 6;
+const OUTPUT_MAX_CHARS = 8_000;
+
+export default defineRuntimePlugin((context) => {
+  const defaultDepth = readBoundedInteger(context.config?.defaultDepth, {
+    defaultValue: 3,
+    minimum: 0,
+    maximum: MAX_DEPTH,
+    name: "defaultDepth",
+  });
+
+  return {
+    handlers: {
+      async inspect_json(params) {
+        try {
+          const requestedPath = readRequiredString(params.path, "path");
+          const target = resolvePluginPath(context, requestedPath, {
+            requirePath: true,
+            allowedLocations: ["agent_work", "workspace"],
+          });
+          const file = await readBoundedRegularFile(target.absolutePath, {
+            maxBytes: MAX_FILE_BYTES,
+            rootPath: target.rootPath,
+          });
+          if (!file.ok && file.reason === "not_regular_file") {
+            return failureResult({
+              errorCode: "json_target_not_file",
+              message: "The requested JSON target is not a regular file.",
+            });
+          }
+          if (!file.ok && file.reason === "too_large") {
+            return failureResult({
+              errorCode: "json_file_too_large",
+              message: `The requested file exceeds the ${MAX_FILE_BYTES}-byte JSON inspection limit.`,
+            });
+          }
+          if (!file.ok) {
+            return failureResult({
+              errorCode: "json_file_changed",
+              message: "The requested JSON file changed while it was read.",
+            });
+          }
+          let source: string;
+          try {
+            source = new TextDecoder("utf-8", { fatal: true }).decode(
+              file.bytes,
+            );
+          } catch {
+            return failureResult({
+              errorCode: "json_invalid_encoding",
+              message: "The requested JSON file must contain valid UTF-8 text.",
+            });
+          }
+          const maxDepth = readBoundedInteger(params.maxDepth, {
+            defaultValue: defaultDepth,
+            minimum: 0,
+            maximum: MAX_DEPTH,
+            name: "maxDepth",
+          });
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(source) as unknown;
+          } catch (error) {
+            const position = parseJsonErrorPosition(error, source);
+            return successResult({
+              output: [
+                `JSON syntax is invalid: ${target.logicalPath}`,
+                position
+                  ? `Location: line ${position.line}, column ${position.column}`
+                  : "Location: unavailable",
+              ].join("\n"),
+              producedNewInformation: true,
+              data: {
+                location: target.location,
+                path: target.logicalPath,
+                valid: false,
+                syntaxValid: false,
+                ...(position ? { position } : {}),
+                observationMeta: {
+                  kind: "volatile_external",
+                  carryPolicy: "never",
+                },
+              },
+            });
+          }
+          const summary = summarizeJsonShape(parsed, maxDepth);
+          const rawOutput = [
+            `Valid JSON: ${target.logicalPath}`,
+            `Bytes: ${Buffer.byteLength(source, "utf8")}`,
+            `Top-level type: ${parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed}`,
+            `Structure (depth ${maxDepth}, ${summary.metadata.visitedNodes}/${summary.metadata.maxNodes} nodes):`,
+            JSON.stringify(summary.shape, null, 2),
+          ].join("\n");
+          const bounded = boundText(rawOutput, {
+            maxChars: OUTPUT_MAX_CHARS,
+            marker: "\n[JSON structure output truncated]",
+          });
+          return successResult({
+            output: bounded.text,
+            producedNewInformation: true,
+            data: {
+              location: target.location,
+              path: target.logicalPath,
+              valid: true,
+              syntaxValid: true,
+              maxDepth,
+              structure: summary.shape,
+              truncation: {
+                ...summary.metadata,
+                output: bounded.metadata,
+              },
+              observationMeta: {
+                kind: "volatile_external",
+                carryPolicy: "never",
+              },
+            },
+          });
+        } catch (error) {
+          return failureFromError(error, {
+            fallbackCode: "json_inspection_failed",
+            fallbackMessage: "JSON inspection failed.",
+            operation: "inspect_json",
+          });
+        }
+      },
+    },
+  };
+});

package/plugins/json-inspector/source/shape.ts

@@ -0,0 +1,144 @@
+import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
+
+export type JsonShape =
+  | string
+  | Readonly<{ type: "primitive"; valueType: string }>
+  | Readonly<{
+      type: "array";
+      length: number;
+      sampledItems: readonly JsonShape[];
+      returnedItems: number;
+      truncated: boolean;
+    }>
+  | Readonly<{
+      type: "object";
+      totalKeys: number;
+      returnedKeys: number;
+      truncated: boolean;
+      keys: readonly Readonly<{ key: string; value: JsonShape }>[];
+    }>;
+
+export type JsonShapeSummary = Readonly<{
+  shape: JsonShape;
+  metadata: Readonly<{
+    maxDepth: number;
+    maxNodes: number;
+    visitedNodes: number;
+    truncatedNodes: number;
+    truncatedKeys: number;
+    arraySampleSize: number;
+    objectKeyLimit: number;
+    objectKeyMaxChars: number;
+  }>;
+}>;
+
+const OBJECT_KEY_LIMIT = 40;
+const OBJECT_KEY_MAX_CHARS = 64;
+const ARRAY_SAMPLE_SIZE = 3;
+const MAX_NODES = 200;
+
+function boundedKey(value: string): string {
+  const safeValue = sanitizeJsonText(value);
+  if (safeValue.length <= OBJECT_KEY_MAX_CHARS) return safeValue;
+  const marker = "...[truncated]";
+  return `${safeValue.slice(0, OBJECT_KEY_MAX_CHARS - marker.length)}${marker}`;
+}
+
+function valueType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+export function summarizeJsonShape(
+  value: unknown,
+  maxDepth: number,
+): JsonShapeSummary {
+  let visitedNodes = 0;
+  let truncatedNodes = 0;
+  let truncatedKeys = 0;
+
+  const visit = (current: unknown, depth: number): JsonShape => {
+    if (visitedNodes >= MAX_NODES) {
+      truncatedNodes += 1;
+      return `[${valueType(current)} omitted: node budget reached]`;
+    }
+    visitedNodes += 1;
+    if (depth >= maxDepth) {
+      if (current !== null && typeof current === "object") truncatedNodes += 1;
+      return `[${valueType(current)} at depth limit]`;
+    }
+    if (Array.isArray(current)) {
+      const sampled = current.slice(0, ARRAY_SAMPLE_SIZE);
+      if (sampled.length < current.length) truncatedNodes += 1;
+      return Object.freeze({
+        type: "array" as const,
+        length: current.length,
+        sampledItems: Object.freeze(
+          sampled.map((item) => visit(item, depth + 1)),
+        ),
+        returnedItems: sampled.length,
+        truncated: sampled.length < current.length,
+      });
+    }
+    if (current && typeof current === "object") {
+      const record = current as Record<string, unknown>;
+      const names = Object.keys(record).sort((left, right) =>
+        left.localeCompare(right),
+      );
+      const returnedNames = names.slice(0, OBJECT_KEY_LIMIT);
+      if (returnedNames.length < names.length) truncatedNodes += 1;
+      return Object.freeze({
+        type: "object" as const,
+        totalKeys: names.length,
+        returnedKeys: returnedNames.length,
+        truncated: returnedNames.length < names.length,
+        keys: Object.freeze(
+          returnedNames.map((key) => {
+            if (key.length > OBJECT_KEY_MAX_CHARS) truncatedKeys += 1;
+            return Object.freeze({
+              key: boundedKey(key),
+              value: visit(record[key], depth + 1),
+            });
+          }),
+        ),
+      });
+    }
+    return Object.freeze({
+      type: "primitive" as const,
+      valueType: valueType(current),
+    });
+  };
+
+  return Object.freeze({
+    shape: visit(value, 0),
+    metadata: Object.freeze({
+      maxDepth,
+      maxNodes: MAX_NODES,
+      visitedNodes,
+      truncatedNodes,
+      truncatedKeys,
+      arraySampleSize: ARRAY_SAMPLE_SIZE,
+      objectKeyLimit: OBJECT_KEY_LIMIT,
+      objectKeyMaxChars: OBJECT_KEY_MAX_CHARS,
+    }),
+  });
+}
+
+export function parseJsonErrorPosition(
+  error: unknown,
+  source: string,
+): Readonly<{ position: number; line: number; column: number }> | undefined {
+  const message = error instanceof Error ? error.message : "";
+  const match = /position\s+(\d+)/iu.exec(message);
+  if (!match?.[1]) return undefined;
+  const position = Number(match[1]);
+  if (!Number.isSafeInteger(position) || position < 0) return undefined;
+  const prefix = source.slice(0, position);
+  const lineStart = prefix.lastIndexOf("\n");
+  return Object.freeze({
+    position,
+    line: prefix.split("\n").length,
+    column: position - lineStart,
+  });
+}