@foldspace_npm/harness 0.1.2 → 0.1.4

package/src/diagnostics.mjs

@@ -0,0 +1,482 @@
+import {
+  CAPABILITIES,
+  ERROR_CODES,
+  createDiagnosticRequest,
+  diagnosticFailure,
+  diagnosticSuccess,
+} from "./protocol.mjs";
+
+// Diagnostic run functions are deliberately self-contained: CDP and extension
+// adapters serialize them into the page, so they cannot close over this module.
+export const DIAGNOSTICS = Object.freeze({
+  inspectSdkState: Object.freeze({
+    description:
+      "Report Foldspace SDK presence, configured key, script sources, and existing agent instance IDs.",
+    risk: "observe",
+    capabilities: Object.freeze([CAPABILITIES.PAGE_EVALUATE]),
+    run: function inspectSdkState(args = {}) {
+      const root = globalThis.window || globalThis;
+      const namespace =
+        typeof root.__FOLD_SPACE__ === "string" && root.__FOLD_SPACE__
+          ? root.__FOLD_SPACE__
+          : "foldspace";
+      const sdk = root[namespace];
+      let agentIds = [];
+      let agentIdsError = null;
+      try {
+        if (typeof sdk?.agentIds === "function") {
+          const value = sdk.agentIds();
+          if (Array.isArray(value)) {
+            agentIds = value
+              .filter((id) => typeof id === "string")
+              .slice(0, 50);
+          }
+        }
+      } catch (error) {
+        agentIdsError = String(error?.message || error).slice(0, 500);
+      }
+
+      let scripts = [];
+      try {
+        scripts = Array.from(root.document?.scripts || [])
+          .map((script) => script?.src)
+          .filter(
+            (source) =>
+              typeof source === "string" &&
+              /foldspace|eucera/i.test(source),
+          )
+          .slice(0, 20)
+          .map((source) => source.slice(0, 2_000));
+      } catch {
+        // A document is optional for SDK-only fixtures.
+      }
+      let trackerKey = null;
+      try {
+        const value = sdk?.getTracker?.()?.getOriginalKey?.();
+        if (typeof value === "string") trackerKey = value.slice(0, 500);
+      } catch {
+        // Older SDKs may not expose their tracker.
+      }
+
+      const expectedApiName =
+        typeof args.expectedApiName === "string" ? args.expectedApiName : null;
+      const expectedMode =
+        typeof args.expectedMode === "string"
+          ? args.expectedMode.toLowerCase()
+          : null;
+      const matchingAgentIds = expectedApiName
+        ? agentIds.filter((id) => {
+            const separator = id.indexOf("-");
+            if (separator < 1) return false;
+            const mode = id.slice(0, separator).toLowerCase();
+            const apiName = id.slice(separator + 1);
+            return (
+              apiName === expectedApiName &&
+              (expectedMode === null || mode === expectedMode)
+            );
+          })
+        : [];
+
+      return {
+        pageUrl:
+          typeof root.location?.href === "string"
+            ? root.location.href.slice(0, 2_000)
+            : null,
+        documentReadyState:
+          typeof root.document?.readyState === "string"
+            ? root.document.readyState
+            : null,
+        sdkPresent: sdk !== undefined && sdk !== null,
+        sdkReady: typeof sdk?.agent === "function",
+        namespace,
+        sdkKey:
+          typeof sdk?.k === "string" ? sdk.k.slice(0, 500) : null,
+        trackerKey,
+        agentIds,
+        agentIdsError,
+        scripts,
+        expectedApiName,
+        expectedMode,
+        matchingAgentIds,
+      };
+    },
+  }),
+
+  inspectRegistration: Object.freeze({
+    description:
+      "Read the exact action names registered on an existing Foldspace agent instance.",
+    risk: "observe",
+    capabilities: Object.freeze([CAPABILITIES.PAGE_EVALUATE]),
+    run: async function inspectRegistration(args = {}) {
+      const root = globalThis.window || globalThis;
+      const namespace =
+        typeof root.__FOLD_SPACE__ === "string" && root.__FOLD_SPACE__
+          ? root.__FOLD_SPACE__
+          : "foldspace";
+      const sdk = root[namespace];
+      if (typeof sdk?.agentIds !== "function" || typeof sdk?.agent !== "function") {
+        return {
+          sdkPresent: sdk !== undefined && sdk !== null,
+          sdkReady: false,
+          agentFound: false,
+          actionNames: [],
+        };
+      }
+
+      const apiName =
+        typeof args.apiName === "string" ? args.apiName : "";
+      const requestedMode =
+        typeof args.mode === "string" ? args.mode.toLowerCase() : null;
+      const ownerAgentId =
+        typeof args.ownerAgentId === "string" ? args.ownerAgentId : null;
+      const ids = sdk
+        .agentIds()
+        .filter((id) => typeof id === "string")
+        .slice(0, 50);
+      const matchedId = ownerAgentId
+        ? ids.find((id) => id === ownerAgentId)
+        : ids.find((id) => {
+            const separator = id.indexOf("-");
+            if (separator < 1) return false;
+            const mode = id.slice(0, separator).toLowerCase();
+            const name = id.slice(separator + 1);
+            return (
+              name === apiName &&
+              (requestedMode === null || requestedMode === mode)
+            );
+          });
+      if (!matchedId) {
+        return {
+          sdkPresent: true,
+          sdkReady: true,
+          agentFound: false,
+          agentIds: ids,
+          actionNames: [],
+        };
+      }
+
+      const separator = matchedId.indexOf("-");
+      const mode = matchedId.slice(0, separator);
+      const agent = sdk.agent({
+        apiName: matchedId.slice(separator + 1),
+        mode: mode.toUpperCase(),
+      });
+      const available = await agent?.getAvailableActions?.();
+      const actionNames =
+        available && typeof available === "object"
+          ? Object.keys(available).sort().slice(0, 200)
+          : [];
+      const expectedActionNames = Array.isArray(args.expectedActionNames)
+        ? args.expectedActionNames
+            .filter((name) => typeof name === "string")
+            .slice(0, 200)
+        : [];
+      const actionSet = new Set(actionNames);
+      const expectedSet = new Set(expectedActionNames);
+
+      return {
+        sdkPresent: true,
+        sdkReady: true,
+        agentFound: true,
+        agentId: matchedId,
+        actionNames,
+        expectedActionNames,
+        missingActionNames: expectedActionNames.filter(
+          (name) => !actionSet.has(name),
+        ),
+        unexpectedActionNames: actionNames.filter(
+          (name) => !expectedSet.has(name),
+        ),
+      };
+    },
+  }),
+
+  verifyWidgetVisible: Object.freeze({
+    description:
+      "Report whether a Foldspace widget candidate is mounted and has a visible bounding box.",
+    risk: "observe",
+    capabilities: Object.freeze([CAPABILITIES.PAGE_EVALUATE]),
+    run: function verifyWidgetVisible(args = {}) {
+      const root = globalThis.window || globalThis;
+      const selectors =
+        Array.isArray(args.selectors) && args.selectors.length
+          ? args.selectors
+              .filter((selector) => typeof selector === "string")
+              .slice(0, 10)
+          : [
+              "#eucera-agent-view",
+              "#foldspace-container",
+              "[data-foldspace-agent]",
+            ];
+
+      const candidates = [];
+      const seen = new Set();
+      for (const selector of selectors) {
+        let elements = [];
+        try {
+          if (typeof root.document?.querySelectorAll === "function") {
+            elements = Array.from(root.document.querySelectorAll(selector));
+          } else {
+            const element = root.document?.querySelector?.(selector);
+            if (element) elements = [element];
+          }
+        } catch {
+          continue;
+        }
+        for (const element of elements.slice(0, 30)) {
+          if (!element || seen.has(element)) continue;
+          seen.add(element);
+          const rect = element.getBoundingClientRect?.();
+          const width = Math.max(0, Math.round(rect?.width || 0));
+          const height = Math.max(0, Math.round(rect?.height || 0));
+          candidates.push({
+            selector,
+            visible: width > 0 && height > 0,
+            size: { width, height },
+            ownerAgentId:
+              element.getAttribute?.("data-foldspace-dev-agent-id") || null,
+          });
+        }
+      }
+
+      const visibleCandidates = candidates.filter(
+        (candidate) => candidate.visible,
+      );
+      const expectedOwner =
+        typeof args.ownerAgentId === "string" ? args.ownerAgentId : null;
+      const first = candidates[0] || null;
+      return {
+        mounted: candidates.length > 0,
+        visible: visibleCandidates.length > 0,
+        soleVisible: visibleCandidates.length === 1,
+        visibleCount: visibleCandidates.length,
+        ownerMatches:
+          expectedOwner === null ||
+          (visibleCandidates.length === 1 &&
+            visibleCandidates[0].ownerAgentId === expectedOwner),
+        expectedOwner,
+        selector: first?.selector || null,
+        size: first?.size || null,
+        candidates,
+      };
+    },
+  }),
+
+  inspectActionObservation: Object.freeze({
+    description:
+      "Report the local action registry and bounded passive action lifecycle evidence captured in the page.",
+    risk: "observe",
+    capabilities: Object.freeze([CAPABILITIES.PAGE_EVALUATE]),
+    run: function inspectActionObservation(args = {}) {
+      const root = globalThis.window || globalThis;
+      const state = root.__FOLDSPACE_DEV_ACTION_OBSERVER__;
+      if (!state || state.version !== 1) {
+        return {
+          installed: false,
+          targetAgentId: null,
+          expectedActionNames: [],
+          actionNameLimitExceeded: false,
+          captureCount: 0,
+          subscribed: false,
+          eventCount: 0,
+          droppedEvents: 0,
+          events: [],
+        };
+      }
+
+      const expectedTarget =
+        typeof args.ownerAgentId === "string" ? args.ownerAgentId : null;
+      const events = Array.isArray(state.events)
+        ? state.events.slice(-100).map((event) => ({
+            source:
+              typeof event?.source === "string"
+                ? event.source.slice(0, 100)
+                : "unknown",
+            actionName:
+              typeof event?.actionName === "string"
+                ? event.actionName.slice(0, 200)
+                : null,
+            phase:
+              typeof event?.phase === "string"
+                ? event.phase.slice(0, 100)
+                : "unknown",
+            status:
+              typeof event?.status === "string"
+                ? event.status.slice(0, 100)
+                : "unknown",
+            durationMs: Number.isFinite(event?.durationMs)
+              ? Math.max(0, Math.round(event.durationMs))
+              : null,
+            parameterKeys: Array.isArray(event?.parameterKeys)
+              ? event.parameterKeys
+                  .filter((key) => typeof key === "string")
+                  .slice(0, 50)
+              : [],
+          }))
+        : [];
+
+      return {
+        installed: true,
+        targetAgentId:
+          typeof state.targetAgentId === "string"
+            ? state.targetAgentId.slice(0, 200)
+            : null,
+        ownerMatches:
+          expectedTarget === null || state.targetAgentId === expectedTarget,
+        expectedActionNames: Array.isArray(state.expectedActionNames)
+          ? state.expectedActionNames
+              .filter((name) => typeof name === "string")
+              .sort()
+              .slice(0, 200)
+          : [],
+        actionNameLimitExceeded:
+          state.actionNameLimitExceeded === true,
+        captureCount: Number.isFinite(state.captureCount)
+          ? Math.max(0, Math.round(state.captureCount))
+          : 0,
+        subscribed: state.subscribed === true,
+        eventCount: Array.isArray(state.events) ? state.events.length : 0,
+        droppedEvents: Number.isFinite(state.droppedEvents)
+          ? Math.max(0, Math.round(state.droppedEvents))
+          : 0,
+        events,
+      };
+    },
+  }),
+
+  runActionCheck: Object.freeze({
+    description:
+      "Invoke one action on an existing Foldspace instance without relying on model action selection.",
+    risk: "test",
+    capabilities: Object.freeze([
+      CAPABILITIES.PAGE_EVALUATE,
+      CAPABILITIES.PAGE_MUTATE,
+    ]),
+    run: async function runActionCheck(args = {}) {
+      const root = globalThis.window || globalThis;
+      const namespace =
+        typeof root.__FOLD_SPACE__ === "string" && root.__FOLD_SPACE__
+          ? root.__FOLD_SPACE__
+          : "foldspace";
+      const sdk = root[namespace];
+      if (typeof sdk?.agentIds !== "function" || typeof sdk?.agent !== "function") {
+        return { invoked: false, reason: "SDK_NOT_FOUND" };
+      }
+
+      const apiName =
+        typeof args.apiName === "string" ? args.apiName : "";
+      const actionName =
+        typeof args.actionName === "string" ? args.actionName : "";
+      const requestedMode =
+        typeof args.mode === "string" ? args.mode.toLowerCase() : null;
+      const matchedId = sdk.agentIds().find((id) => {
+        if (typeof id !== "string") return false;
+        const separator = id.indexOf("-");
+        if (separator < 1) return false;
+        const mode = id.slice(0, separator).toLowerCase();
+        const name = id.slice(separator + 1);
+        return (
+          name === apiName &&
+          (requestedMode === null || requestedMode === mode)
+        );
+      });
+      if (!matchedId) {
+        return { invoked: false, reason: "AGENT_NOT_FOUND" };
+      }
+
+      const separator = matchedId.indexOf("-");
+      const agent = sdk.agent({
+        apiName: matchedId.slice(separator + 1),
+        mode: matchedId.slice(0, separator).toUpperCase(),
+      });
+      if (typeof agent?.runAction !== "function") {
+        return { invoked: false, reason: "RUN_ACTION_UNAVAILABLE" };
+      }
+
+      const value = await agent.runAction(
+        actionName,
+        args.params && typeof args.params === "object" ? args.params : {},
+      );
+      return { invoked: true, agentId: matchedId, actionName, value };
+    },
+  }),
+});
+
+export function diagnosticCatalogue() {
+  return Object.entries(DIAGNOSTICS).map(([name, diagnostic]) => ({
+    name,
+    description: diagnostic.description,
+    risk: diagnostic.risk,
+    capabilities: [...diagnostic.capabilities],
+  }));
+}
+
+export function serializeDiagnostic(name, args = {}) {
+  const diagnostic = DIAGNOSTICS[name];
+  if (!diagnostic) {
+    throw new Error(`Unknown diagnostic: ${name}`);
+  }
+  return `Promise.resolve((${diagnostic.run.toString()})(${JSON.stringify(args)}))`;
+}
+
+export async function executeDiagnostic(input, options = {}) {
+  let request;
+  try {
+    request = createDiagnosticRequest(input);
+  } catch (error) {
+    const fallback = {
+      id: typeof input?.id === "string" ? input.id : "invalid-request",
+      name: typeof input?.name === "string" ? input.name : "invalid-diagnostic",
+    };
+    return diagnosticFailure(fallback, {
+      code: ERROR_CODES.INVALID_REQUEST,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  const diagnostic = DIAGNOSTICS[request.name];
+  if (!diagnostic) {
+    return diagnosticFailure(request, {
+      code: ERROR_CODES.INVALID_REQUEST,
+      message: `Unknown diagnostic: ${request.name}`,
+    });
+  }
+
+  const availableCapabilities = new Set(options.capabilities || []);
+  const missingCapabilities = diagnostic.capabilities.filter(
+    (capability) => !availableCapabilities.has(capability),
+  );
+  if (missingCapabilities.length) {
+    return diagnosticFailure(request, {
+      code: ERROR_CODES.CAPABILITY_DISABLED,
+      message: `Diagnostic requires: ${missingCapabilities.join(", ")}`,
+    });
+  }
+
+  const startedAt = Date.now();
+  let timeout;
+  try {
+    const result = await Promise.race([
+      Promise.resolve(diagnostic.run(request.args)),
+      new Promise((_, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error("Diagnostic timed out")),
+          request.timeoutMs,
+        );
+      }),
+    ]);
+    return diagnosticSuccess(request, result, {
+      durationMs: Date.now() - startedAt,
+    });
+  } catch (error) {
+    return diagnosticFailure(request, {
+      code:
+        error instanceof Error && error.message === "Diagnostic timed out"
+          ? ERROR_CODES.TIMEOUT
+          : ERROR_CODES.DIAGNOSTIC_FAILED,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/init.mjs

@@ -4,15 +4,21 @@ import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
+import { commandByName } from "./cli-registry.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const defaultTemplateRoot = path.join(packageRoot, "templates", "agent-starter");
-const allowedFlags = new Set(["name", "product-id", "agent-api-name", "domain"]);
+const allowedFlags = new Set([
+  "name",
+  "product-id",
+  "agent-key",
+  "agent-api-name",
+  "domain",
+]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
 const defaultDirectory = "my-agent";
 
-export const initUsage =
-  "foldspace init [<directory>] [--product-id <id>] [--agent-api-name <name>] [--domain <host>] [--name <display-name>]";
+export const initUsage = commandByName("init").usage;
 
 function assertSupportedNode() {
   const major = Number.parseInt(process.versions.node.split(".", 1)[0], 10);
@@ -75,12 +81,17 @@ export function parseInitArgs(argv) {
   if (positional.length > 1) {
     throw new Error(`Usage: ${initUsage}`);
   }
+  if (flags["agent-key"] && flags["agent-api-name"]) {
+    throw new Error(
+      "Use --agent-key only; --agent-api-name is its deprecated alias.",
+    );
+  }
 
   return {
     directory: positional[0] || null,
     displayName: flags.name || null,
     productId: flags["product-id"] || null,
-    agentApiName: flags["agent-api-name"] || null,
+    agentApiName: flags["agent-key"] || flags["agent-api-name"] || null,
     domain: flags.domain || null,
   };
 }
@@ -89,7 +100,7 @@ function missingInitFields(parsed) {
   const missing = [];
   if (!parsed.directory) missing.push("directory");
   if (!parsed.productId) missing.push("product-id");
-  if (!parsed.agentApiName) missing.push("agent-api-name");
+  if (!parsed.agentApiName) missing.push("agent-key");
   if (!parsed.domain) missing.push("domain");
   return missing;
 }
@@ -208,8 +219,8 @@ async function promptForMissingFields(parsed, options = {}) {
 
   if (!next.agentApiName) {
     next.agentApiName = await askUntilValid(
-      "Agent API name",
-      (value) => validateIdentifier(value, "Agent API name"),
+      "Agent Key",
+      (value) => validateIdentifier(value, "Agent Key"),
       options,
     );
   }
@@ -243,7 +254,7 @@ function finalizeInitConfig(parsed) {
 
   for (const [key, label] of [
     ["productId", "product-id"],
-    ["agentApiName", "agent-api-name"],
+    ["agentApiName", "agent-key"],
     ["domain", "domain"],
   ]) {
     if (!parsed[key]) {
@@ -282,7 +293,7 @@ function createTemplateValues(config, harnessVersion) {
   }
 
   const productId = validateProductId(config.productId);
-  const agentApiName = validateIdentifier(config.agentApiName, "Agent API name");
+  const agentApiName = validateIdentifier(config.agentApiName, "Agent Key");
   const target = normalizeTarget(config.domain);
   const hosts =
     target.domain === "localhost" || /^\d+(?:\.\d+){3}$/.test(target.domain)

package/src/project-config.mjs

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function readProjectConfig(projectDir) {
+  const configPath = path.join(projectDir, "foldspace.dev.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error("foldspace.dev.json not found");
+  }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `foldspace.dev.json is invalid: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  return config;
+}
+
+export function resolveConfiguredTarget(config, requestedTarget) {
+  const targetName = requestedTarget || config?.defaultTarget;
+  if (typeof targetName !== "string" || !targetName) {
+    throw new Error("foldspace.dev.json must define defaultTarget");
+  }
+  const target = config?.targets?.[targetName];
+  if (!target || typeof target !== "object") {
+    throw new Error(`target "${targetName}" is not defined`);
+  }
+  for (const field of ["productId", "agentApiName"]) {
+    if (typeof target[field] !== "string" || !target[field]) {
+      throw new Error(`target "${targetName}" must define ${field}`);
+    }
+  }
+  return { targetName, target };
+}