@abot-ai/runtime 1.0.0

package/plugins/project-orientation/plugin.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "project-orientation",
+  "version": "0.3.1",
+  "description": "Inspect a bounded project tree and its manifest metadata.",
+  "extensions": {
+    "ai.abot.runtime": {
+      "version": 1,
+      "entrypoint": "./src/index.cjs",
+      "catalogGroups": ["read"],
+      "settings": {
+        "defaults": {
+          "defaultDepth": 3,
+          "maxEntries": 200
+        }
+      },
+      "capabilities": {
+        "inspect_project": {
+          "description": "Inspect a bounded project tree. Path `.` and relative paths resolve inside the configured agent work directory; `workspace/...` targets configured workspace sources.",
+          "routingCapability": "semantic_lookup",
+          "runtimePathBindings": [
+            {
+              "operationId": "inspect_project",
+              "param": "path",
+              "base": "worker_working_directory",
+              "default": "."
+            }
+          ],
+          "skills": ["project_orientation_skill"],
+          "operations": {
+            "inspect_project": {
+              "summary": "Inspect structure and manifest metadata 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": 0,
+                    "maxLength": 1024
+                  },
+                  "depth": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 6
+                  },
+                  "maxEntries": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 250
+                  }
+                },
+                "required": []
+              },
+              "effect": "read_only",
+              "approval": "request_policy"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/project-orientation/skills/project_orientation_skill/SKILL.md

@@ -0,0 +1,11 @@
+# Project Orientation Skill
+
+Use `inspect_project` before changing an unfamiliar existing project when its
+structure, entrypoints, or package scripts are not yet known. Prefer this
+bounded orientation before broad file reads. It returns a tree and manifest
+summary, not full source content; use the result to choose focused follow-up
+reads and preserve the existing project root.
+
+Use `path` as the location contract: `.` targets the configured agent work
+directory, relative paths target content beneath it, and `workspace/...`
+targets configured workspace sources.

package/plugins/project-orientation/source/index.ts

@@ -0,0 +1,118 @@
+import { stat } from "node:fs/promises";
+
+import {
+  boundText,
+  defineRuntimePlugin,
+  failureFromError,
+  failureResult,
+  readBoundedInteger,
+  readOptionalString,
+  resolvePluginPath,
+  successResult,
+} from "../../../src/plugin-sdk/index.js";
+
+import { readProjectManifests } from "./manifest-summary.js";
+import { collectProjectTree } from "./tree.js";
+
+const DEFAULT_DEPTH = 3;
+const DEFAULT_MAX_ENTRIES = 200;
+const MAX_DEPTH = 6;
+const MAX_ENTRIES = 250;
+const OUTPUT_MAX_CHARS = 8_000;
+
+export default defineRuntimePlugin((context) => {
+  const defaultDepth = readBoundedInteger(context.config?.defaultDepth, {
+    defaultValue: DEFAULT_DEPTH,
+    minimum: 0,
+    maximum: MAX_DEPTH,
+    name: "defaultDepth",
+  });
+  const defaultMaxEntries = readBoundedInteger(context.config?.maxEntries, {
+    defaultValue: DEFAULT_MAX_ENTRIES,
+    minimum: 1,
+    maximum: MAX_ENTRIES,
+    name: "maxEntries",
+  });
+
+  return {
+    handlers: {
+      async inspect_project(params) {
+        try {
+          const requestedPath = readOptionalString(params.path) ?? ".";
+          const target = resolvePluginPath(context, requestedPath, {
+            defaultPath: ".",
+            allowedLocations: ["agent_work", "workspace"],
+          });
+          const info = await stat(target.absolutePath);
+          if (!info.isDirectory()) {
+            return failureResult({
+              errorCode: "project_target_not_directory",
+              message: "The requested project target is not a directory.",
+            });
+          }
+          const depth = readBoundedInteger(params.depth, {
+            defaultValue: defaultDepth,
+            minimum: 0,
+            maximum: MAX_DEPTH,
+            name: "depth",
+          });
+          const maxEntries = readBoundedInteger(params.maxEntries, {
+            defaultValue: defaultMaxEntries,
+            minimum: 1,
+            maximum: MAX_ENTRIES,
+            name: "maxEntries",
+          });
+          const [tree, manifests] = await Promise.all([
+            collectProjectTree(context, target, depth, maxEntries),
+            readProjectManifests(context, target),
+          ]);
+          const packageManifest = manifests.find(
+            ({ file }) => file === "package.json",
+          );
+          const rawOutput = [
+            `Project target: ${target.logicalPath}`,
+            `Directories (${tree.directories.length}${tree.truncated ? ", bounded sample" : ""}): ${tree.directories.join(", ") || "none"}`,
+            `Files (${tree.files.length}${tree.truncated ? ", bounded sample" : ""}): ${tree.files.join(", ") || "none"}`,
+            `Manifests: ${manifests.map(({ file }) => file).join(", ") || "none"}`,
+            packageManifest?.scripts?.length
+              ? `Package scripts: ${packageManifest.scripts.join(", ")}`
+              : "",
+          ]
+            .filter(Boolean)
+            .join("\n");
+          const output = boundText(rawOutput, {
+            maxChars: OUTPUT_MAX_CHARS,
+            marker: "\n[project orientation output truncated]",
+          });
+          return successResult({
+            output: output.text,
+            producedNewInformation: true,
+            data: {
+              location: target.location,
+              target: target.logicalPath,
+              depth,
+              maxEntries,
+              tree,
+              manifests,
+              truncation: {
+                output: output.metadata,
+                tree: tree.truncated,
+                pathCount: tree.truncatedPathCount,
+              },
+              observationMeta: {
+                kind: "volatile_external",
+                carryPolicy: "never",
+              },
+            },
+          });
+        } catch (error) {
+          return failureFromError(error, {
+            fallbackCode: "project_orientation_failed",
+            fallbackMessage: "Project orientation failed.",
+            operation: "inspect_project",
+          });
+        }
+      },
+    },
+  };
+});

package/plugins/project-orientation/source/manifest-summary.ts

@@ -0,0 +1,153 @@
+import { stat } from "node:fs/promises";
+import { posix } from "node:path";
+
+import type {
+  ResolvedRuntimeToolPath,
+  RuntimePluginLoadContext,
+} from "../../../src/plugin-sdk/index.js";
+import {
+  isRuntimeToolPathError,
+  readBoundedRegularFile,
+  resolvePluginPath,
+  sanitizeJsonText,
+} from "../../../src/plugin-sdk/index.js";
+
+const PACKAGE_JSON_MAX_BYTES = 256 * 1024;
+const PACKAGE_SCRIPT_LIMIT = 100;
+const MANIFEST_IDENTITY_MAX_CHARS = 256;
+const SCRIPT_NAME_MAX_CHARS = 32;
+const KNOWN_MANIFESTS = Object.freeze([
+  "package.json",
+  "pyproject.toml",
+  "requirements.txt",
+  "Cargo.toml",
+  "go.mod",
+  "tsconfig.json",
+  "vite.config.ts",
+  "vite.config.js",
+]);
+
+export type ProjectManifestSummary = Readonly<{
+  file: string;
+  name?: string;
+  version?: string;
+  private?: boolean;
+  scripts?: readonly string[];
+  scriptsTruncated?: boolean;
+  status?: "invalid_json" | "too_large";
+}>;
+
+function logicalChild(parent: ResolvedRuntimeToolPath, name: string): string {
+  return parent.logicalPath === "."
+    ? name
+    : posix.join(parent.logicalPath, name);
+}
+
+function stringField(
+  record: Readonly<Record<string, unknown>>,
+  key: string,
+): string | undefined {
+  const value = record[key];
+  return typeof value === "string"
+    ? sanitizeJsonText(value).slice(0, MANIFEST_IDENTITY_MAX_CHARS)
+    : undefined;
+}
+
+function boundedScriptName(value: string): string {
+  return [...sanitizeJsonText(value)].slice(0, SCRIPT_NAME_MAX_CHARS).join("");
+}
+
+async function existingChild(
+  context: RuntimePluginLoadContext,
+  root: ResolvedRuntimeToolPath,
+  name: string,
+): Promise<ResolvedRuntimeToolPath | undefined> {
+  try {
+    const child = resolvePluginPath(context, logicalChild(root, name), {
+      requirePath: true,
+      allowedLocations: ["agent_work", "workspace"],
+    });
+    const info = await stat(child.absolutePath);
+    return info.isFile() ? child : undefined;
+  } catch (error) {
+    if (isRuntimeToolPathError(error)) throw error;
+    const code =
+      error && typeof error === "object" && "code" in error
+        ? String((error as { code?: unknown }).code)
+        : "";
+    if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+    throw error;
+  }
+}
+
+export async function readProjectManifests(
+  context: RuntimePluginLoadContext,
+  root: ResolvedRuntimeToolPath,
+): Promise<readonly ProjectManifestSummary[]> {
+  const summaries: ProjectManifestSummary[] = [];
+  for (const name of KNOWN_MANIFESTS) {
+    const target = await existingChild(context, root, name);
+    if (!target) continue;
+    if (name !== "package.json") {
+      summaries.push(Object.freeze({ file: name }));
+      continue;
+    }
+    const file = await readBoundedRegularFile(target.absolutePath, {
+      maxBytes: PACKAGE_JSON_MAX_BYTES,
+      rootPath: target.rootPath,
+    });
+    if (!file.ok && file.reason === "too_large") {
+      summaries.push(
+        Object.freeze({ file: name, status: "too_large" as const }),
+      );
+      continue;
+    }
+    if (!file.ok)
+      throw new Error("Project manifest changed while it was being read.");
+    try {
+      const parsed = JSON.parse(file.bytes.toString("utf8")) as unknown;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        summaries.push(
+          Object.freeze({ file: name, status: "invalid_json" as const }),
+        );
+        continue;
+      }
+      const record = parsed as Readonly<Record<string, unknown>>;
+      const rawScriptNames =
+        record.scripts &&
+        typeof record.scripts === "object" &&
+        !Array.isArray(record.scripts)
+          ? Object.keys(record.scripts as Record<string, unknown>).sort(
+              (left, right) => left.localeCompare(right),
+            )
+          : [];
+      const scriptNames = rawScriptNames.map(boundedScriptName);
+      summaries.push(
+        Object.freeze({
+          file: name,
+          ...(stringField(record, "name")
+            ? { name: stringField(record, "name") }
+            : {}),
+          ...(stringField(record, "version")
+            ? { version: stringField(record, "version") }
+            : {}),
+          ...(record.private === true ? { private: true } : {}),
+          scripts: Object.freeze(scriptNames.slice(0, PACKAGE_SCRIPT_LIMIT)),
+          ...(rawScriptNames.length > PACKAGE_SCRIPT_LIMIT ||
+          rawScriptNames.some((name, index) => name !== scriptNames[index])
+            ? { scriptsTruncated: true }
+            : {}),
+        }),
+      );
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        summaries.push(
+          Object.freeze({ file: name, status: "invalid_json" as const }),
+        );
+        continue;
+      }
+      throw error;
+    }
+  }
+  return Object.freeze(summaries);
+}

package/plugins/project-orientation/source/tree.ts

@@ -0,0 +1,126 @@
+import { opendir, stat } from "node:fs/promises";
+import { posix } from "node:path";
+
+import type {
+  ResolvedRuntimeToolPath,
+  RuntimePluginLoadContext,
+} from "../../../src/plugin-sdk/index.js";
+import { resolvePluginPath } from "../../../src/plugin-sdk/index.js";
+import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
+
+const IGNORED_NAMES = new Set([".git", "node_modules", "dist", "coverage"]);
+const DISPLAY_PATH_MAX_CHARS = 64;
+
+export type ProjectTree = Readonly<{
+  directories: readonly string[];
+  files: readonly string[];
+  entries: number;
+  truncated: boolean;
+  truncatedPathCount: number;
+  sampling: "bounded_directory_iteration";
+}>;
+
+function childLogicalPath(
+  parent: ResolvedRuntimeToolPath,
+  childName: string,
+): string {
+  if (parent.logicalPath === ".") return childName;
+  return posix.join(parent.logicalPath, childName);
+}
+
+function relativeDisplayPath(
+  root: ResolvedRuntimeToolPath,
+  child: ResolvedRuntimeToolPath,
+): string {
+  if (child.logicalPath === root.logicalPath) return ".";
+  if (root.logicalPath === ".") return child.logicalPath;
+  const prefix = `${root.logicalPath}/`;
+  return child.logicalPath.startsWith(prefix)
+    ? child.logicalPath.slice(prefix.length)
+    : child.logicalPath;
+}
+
+function boundedDisplayPath(path: string): Readonly<{
+  path: string;
+  truncated: boolean;
+}> {
+  const characters = [...sanitizeJsonText(path)];
+  if (characters.length <= DISPLAY_PATH_MAX_CHARS) {
+    return Object.freeze({ path, truncated: false });
+  }
+  const separator = "…";
+  const sideChars = Math.floor((DISPLAY_PATH_MAX_CHARS - separator.length) / 2);
+  return Object.freeze({
+    path: `${characters.slice(0, sideChars).join("")}${separator}${characters.slice(-sideChars).join("")}`,
+    truncated: true,
+  });
+}
+
+export async function collectProjectTree(
+  context: RuntimePluginLoadContext,
+  root: ResolvedRuntimeToolPath,
+  depth: number,
+  maxEntries: number,
+): Promise<ProjectTree> {
+  const directories: string[] = [];
+  const files: string[] = [];
+  let entries = 0;
+  let truncated = false;
+  let truncatedPathCount = 0;
+  const queue: Readonly<{
+    target: ResolvedRuntimeToolPath;
+    remainingDepth: number;
+  }>[] = [{ target: root, remainingDepth: depth }];
+
+  while (queue.length > 0 && entries < maxEntries) {
+    const current = queue.shift();
+    if (!current) break;
+    const sampled: Readonly<{ name: string; isDirectory: boolean }>[] = [];
+    const directory = await opendir(current.target.absolutePath);
+    for await (const entry of directory) {
+      if (entry.isDirectory() && IGNORED_NAMES.has(entry.name)) continue;
+      if (entries + sampled.length >= maxEntries) {
+        truncated = true;
+        break;
+      }
+      sampled.push({ name: entry.name, isDirectory: entry.isDirectory() });
+    }
+    sampled.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of sampled) {
+      const child = resolvePluginPath(
+        context,
+        childLogicalPath(current.target, entry.name),
+        {
+          requirePath: true,
+          allowedLocations: ["agent_work", "workspace"],
+        },
+      );
+      const info = await stat(child.absolutePath);
+      const display = boundedDisplayPath(relativeDisplayPath(root, child));
+      if (display.truncated) truncatedPathCount += 1;
+      entries += 1;
+      if (info.isDirectory()) {
+        directories.push(display.path);
+        if (current.remainingDepth > 0) {
+          queue.push({
+            target: child,
+            remainingDepth: current.remainingDepth - 1,
+          });
+        }
+      } else if (info.isFile()) {
+        files.push(display.path);
+      }
+    }
+  }
+  if (queue.length > 0) truncated = true;
+  directories.sort((left, right) => left.localeCompare(right));
+  files.sort((left, right) => left.localeCompare(right));
+  return Object.freeze({
+    directories: Object.freeze(directories),
+    files: Object.freeze(files),
+    entries,
+    truncated,
+    truncatedPathCount,
+    sampling: "bounded_directory_iteration" as const,
+  });
+}