@foldspace_npm/harness 0.1.2 → 0.1.3

package/src/protocol.mjs

@@ -0,0 +1,181 @@
+// Browser-safe request/result contracts shared by local CDP and future
+// extension adapters. This module describes evidence; it does not inspect a
+// page or select a transport.
+export const HARNESS_PROTOCOL_VERSION = 1;
+
+export const CAPABILITIES = Object.freeze({
+  PAGE_EVALUATE: "page.evaluate",
+  PAGE_MUTATE: "page.mutate",
+  ARTIFACT_LOAD: "artifact.load",
+  CDP: "browser.cdp",
+});
+
+export const ERROR_CODES = Object.freeze({
+  INVALID_REQUEST: "INVALID_REQUEST",
+  CAPABILITY_DISABLED: "CAPABILITY_DISABLED",
+  SDK_NOT_FOUND: "SDK_NOT_FOUND",
+  AGENT_NOT_FOUND: "AGENT_NOT_FOUND",
+  REGISTRATION_MISMATCH: "REGISTRATION_MISMATCH",
+  DIAGNOSTIC_FAILED: "DIAGNOSTIC_FAILED",
+  TIMEOUT: "TIMEOUT",
+  EVIDENCE_LIMIT: "EVIDENCE_LIMIT",
+  TRANSPORT_ERROR: "TRANSPORT_ERROR",
+});
+
+export const LIFECYCLE_OPERATIONS = Object.freeze([
+  "prepare_page",
+  "load_artifact",
+  "inspect_registration",
+  "run_diagnostic",
+  "cleanup",
+]);
+
+export const PROTOCOL_LIMITS = Object.freeze({
+  maxRequestBytes: 16 * 1024,
+  maxResultBytes: 64 * 1024,
+  maxIdentifierLength: 128,
+});
+
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function jsonByteLength(value, label) {
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    throw new TypeError(`${label} must be JSON serializable`);
+  }
+  if (json === undefined) {
+    throw new TypeError(`${label} must be JSON serializable`);
+  }
+  return new TextEncoder().encode(json).length;
+}
+
+function assertIdentifier(value, label) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > PROTOCOL_LIMITS.maxIdentifierLength ||
+    !identifierPattern.test(value)
+  ) {
+    throw new TypeError(
+      `${label} must be a non-empty identifier of at most ${PROTOCOL_LIMITS.maxIdentifierLength} characters`,
+    );
+  }
+}
+
+export function createDiagnosticRequest({
+  id,
+  name,
+  args = {},
+  timeoutMs = 10_000,
+}) {
+  assertIdentifier(id, "Diagnostic request id");
+  assertIdentifier(name, "Diagnostic name");
+  if (!isRecord(args)) {
+    throw new TypeError("Diagnostic args must be an object");
+  }
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000) {
+    throw new TypeError("Diagnostic timeoutMs must be an integer between 1 and 60000");
+  }
+
+  const request = {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    id,
+    name,
+    args,
+    timeoutMs,
+  };
+  if (jsonByteLength(request, "Diagnostic request") > PROTOCOL_LIMITS.maxRequestBytes) {
+    throw new RangeError("Diagnostic request exceeds the protocol size limit");
+  }
+  return request;
+}
+
+export function diagnosticSuccess(request, result, metadata = {}) {
+  if (!isRecord(metadata)) {
+    throw new TypeError("Diagnostic metadata must be an object");
+  }
+  const response = {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    id: request.id,
+    name: request.name,
+    ok: true,
+    result,
+    metadata,
+  };
+  if (jsonByteLength(response, "Diagnostic result") > PROTOCOL_LIMITS.maxResultBytes) {
+    return diagnosticFailure(request, {
+      code: ERROR_CODES.EVIDENCE_LIMIT,
+      message: "Diagnostic result exceeded the protocol size limit",
+    });
+  }
+  return response;
+}
+
+export function diagnosticFailure(request, error) {
+  const code = Object.values(ERROR_CODES).includes(error?.code)
+    ? error.code
+    : ERROR_CODES.DIAGNOSTIC_FAILED;
+  const message =
+    typeof error?.message === "string" && error.message.trim()
+      ? error.message.slice(0, 2_000)
+      : "Diagnostic failed";
+
+  return {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    id: request.id,
+    name: request.name,
+    ok: false,
+    error: { code, message },
+  };
+}
+
+export function createLifecycleResult({
+  operation,
+  ok,
+  state,
+  error,
+  details = {},
+}) {
+  if (!LIFECYCLE_OPERATIONS.includes(operation)) {
+    throw new TypeError(`Unknown lifecycle operation: ${operation}`);
+  }
+  if (typeof ok !== "boolean") {
+    throw new TypeError("Lifecycle ok must be a boolean");
+  }
+  assertIdentifier(state, "Lifecycle state");
+  if (!isRecord(details)) {
+    throw new TypeError("Lifecycle details must be an object");
+  }
+
+  const result = {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    operation,
+    ok,
+    state,
+    details,
+    ...(ok
+      ? {}
+      : {
+          error: {
+            code: Object.values(ERROR_CODES).includes(error?.code)
+              ? error.code
+              : ERROR_CODES.TRANSPORT_ERROR,
+            message:
+              typeof error?.message === "string" && error.message.trim()
+                ? error.message.slice(0, 2_000)
+                : "Lifecycle operation failed",
+          },
+        }),
+  };
+
+  if (jsonByteLength(result, "Lifecycle result") > PROTOCOL_LIMITS.maxResultBytes) {
+    throw new RangeError("Lifecycle result exceeds the protocol size limit");
+  }
+  return result;
+}

package/src/session-summary.mjs

@@ -0,0 +1,133 @@
+import { ACTION_LOG_PREFIX } from "./action-observer.mjs";
+
+function normalizeConsoleText(value) {
+  return String(value ?? "")
+    .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<id>")
+    .replace(/\b(?:bearer\s+)?[A-Za-z0-9_-]{40,}\b/gi, "<redacted>")
+    .replace(/([?&](?:token|key|secret|code)=)[^&\s]+/gi, "$1<redacted>")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 1_000);
+}
+
+export function parseActionObservation(text) {
+  const value = String(text ?? "");
+  if (!value.startsWith(`${ACTION_LOG_PREFIX} `)) return null;
+  try {
+    const parsed = JSON.parse(value.slice(ACTION_LOG_PREFIX.length + 1));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatActionObservation(event) {
+  const action = event.actionName ? ` ${event.actionName}` : "";
+  const duration = Number.isFinite(event.durationMs)
+    ? ` ${event.durationMs}ms`
+    : "";
+  const keys =
+    Array.isArray(event.parameterKeys) && event.parameterKeys.length
+      ? ` keys=[${event.parameterKeys.join(",")}]`
+      : "";
+  if (event.phase === "registration") {
+    const count = Array.isArray(event.actionNames)
+      ? event.actionNames.length
+      : 0;
+    return `[actions] local artifact ${event.status} (${count} action${count === 1 ? "" : "s"})`;
+  }
+  return `[actions] ${event.source}:${event.phase}${action} ${event.status}${duration}${keys}`;
+}
+
+export function createSessionCollector({
+  maxErrorGroups = 50,
+  maxActionEvents = 200,
+} = {}) {
+  const errorGroups = new Map();
+  const actionEvents = [];
+  let droppedErrorGroups = 0;
+  let droppedActionEvents = 0;
+
+  function recordConsole({ level = "log", text = "" } = {}) {
+    const action = parseActionObservation(text);
+    if (action) {
+      if (actionEvents.length >= maxActionEvents) {
+        actionEvents.shift();
+        droppedActionEvents += 1;
+      }
+      actionEvents.push(action);
+      return action;
+    }
+
+    const normalized = normalizeConsoleText(text);
+    const normalizedLevel = String(level).toLowerCase();
+    const isFailure =
+      normalizedLevel === "error" ||
+      normalizedLevel === "warning" ||
+      normalizedLevel === "warn" ||
+      /\b(?:error|failed|failure|status\s+[45]\d\d)\b/i.test(normalized);
+    if (!normalized || !isFailure) return null;
+
+    const key = `${normalizedLevel}:${normalized}`;
+    const existing = errorGroups.get(key);
+    if (existing) {
+      existing.count += 1;
+    } else if (errorGroups.size < maxErrorGroups) {
+      errorGroups.set(key, {
+        level: normalizedLevel,
+        text: normalized,
+        count: 1,
+      });
+    } else {
+      droppedErrorGroups += 1;
+    }
+    return null;
+  }
+
+  function snapshot() {
+    return {
+      actionEvents: actionEvents.map((event) => ({ ...event })),
+      errorGroups: Array.from(errorGroups.values()).map((group) => ({
+        ...group,
+      })),
+      droppedActionEvents,
+      droppedErrorGroups,
+    };
+  }
+
+  return { recordConsole, snapshot };
+}
+
+export function formatSessionSummary(snapshot) {
+  const lines = [];
+  if (snapshot.actionEvents.length) {
+    lines.push(
+      `Action observations (${snapshot.actionEvents.length}${
+        snapshot.droppedActionEvents
+          ? `, ${snapshot.droppedActionEvents} older dropped`
+          : ""
+      }):`,
+    );
+    for (const event of snapshot.actionEvents.slice(-20)) {
+      lines.push(`  ${formatActionObservation(event)}`);
+    }
+  }
+  if (snapshot.errorGroups.length) {
+    lines.push(
+      `Page failures (${snapshot.errorGroups.length} group${
+        snapshot.errorGroups.length === 1 ? "" : "s"
+      }):`,
+    );
+    for (const group of snapshot.errorGroups) {
+      lines.push(
+        `  [${group.level} x${group.count}] ${group.text}`,
+      );
+    }
+    if (snapshot.droppedErrorGroups) {
+      lines.push(
+        `  ${snapshot.droppedErrorGroups} additional failure group(s) omitted`,
+      );
+    }
+  }
+  return lines.join("\n");
+}

package/templates/agent-starter/CLAUDE.md

@@ -8,10 +8,13 @@ changes there.
 
 ## Before building
 
-1. Connect Product MCP and verify that `list_agents` works.
-2. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
+1. Run `npx foldspace help --json` before an unfamiliar harness operation.
+   Treat its risk, prerequisites, effects, and next-step fields as the current
+   CLI contract.
+2. Connect Product MCP and verify that `list_agents` works.
+3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
    `list_task_agents`.
-3. Use `discover_actions` to identify candidate experiences, then let the user
+4. Use `discover_actions` to identify candidate experiences, then let the user
    choose what to build.
 
 ## Build workflow
@@ -51,12 +54,18 @@ npm run attach
 ```
 
 `inject` launches an isolated Chrome profile and records its debug port.
-`attach` loads the SDK and the local `dist/index.js` bundle. Use
-`npm run attach -- --bootstrap` when the target page does not already embed the
-Foldspace SDK.
+It does not generate or load an application extension. `attach` prepares the
+page and loads the local `dist/index.js` bundle through CDP.
 
-The attach log must report `actions attached: N` before treating the page as
-running local action code.
+Use the default swap only when the page already has the configured product and
+agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
+`--replace` when it embeds a different product or agent, or when an SDK is
+present without the configured agent.
+
+The attach log must report `inspect_registration:registration_ok` before
+treating the page as registered. Prove the experience through the visible agent
+and require both an SDK action callback and local execute/render evidence; do
+not invoke the handler directly.
 
 ## Verification gates
 
@@ -76,9 +85,23 @@ Do not report success without all six:
 - `agent/constants.ts` — agent, product, and domain identifiers
 - `agent/utils.ts` — Foldspace agent lookup
 - `foldspace.dev.json` — local harness target configuration
+- `docs/` — optional coding-agent learnings; create on demand
 
 Do not introduce another bundler or bundle format.
 
+## Agent learnings
+
+Use `docs/` to record durable, repository-specific lessons so later sessions do
+not repeat the same mistakes.
+
+- Before similar work, read any relevant notes already in `docs/`.
+- After non-obvious discoveries, add a short note covering verified gotchas,
+  failed approaches, design rationale, or useful verification commands.
+- Keep notes concise and evidence-based. Create `docs/` when the first note is
+  useful; do not leave an empty directory.
+- Do not store secrets, cookies, HAR files, browser storage, or other transient
+  session data in `docs/`.
+
 ## Safety
 
 - Do not commit secrets, cookies, HAR files, browser storage, or

package/templates/agent-starter/README.md

@@ -26,22 +26,45 @@ agent/
   api/         one file per HTTP helper
   constants.ts product, agent, and domain identifiers
   utils.ts     Foldspace agent lookup
+docs/          optional notes for coding-agent learnings (create when needed)
 foldspace.dev.json
 CLAUDE.md
 ```
 
+## Agent learnings
+
+Coding agents may keep durable, repository-specific lessons under `docs/` so
+later sessions do not repeat the same mistakes. Create the folder when the first
+note is useful; do not commit an empty `docs/` directory.
+
+Good notes cover verified gotchas, failed approaches, design rationale, and
+useful verification commands. Keep them concise and evidence-based. Before
+similar work, read any relevant notes in `docs/`. Do not store secrets, cookies,
+HAR files, browser storage, or other transient session data there.
+
 ## Commands
 
 ```bash
+npx foldspace help # discover commands, risks, and next steps
 npm run build    # create dist/index.js
 npm run dev      # rebuild dist/index.js on changes
 npm run inject   # launch the dedicated Chrome profile
-npm run attach   # load the SDK and local actions over CDP
+npm run attach   # load local actions and observe the agent over CDP
 ```
 
 Run `inject` before `attach`. Sign in to the product in the Chrome window that
-`inject` opens. For a product that does not already embed the Foldspace SDK, run
-`npm run attach -- --bootstrap`.
+`inject` opens. `inject` does not generate an application extension; `attach`
+loads `dist/index.js` directly through CDP.
+
+Choose the attach mode from the state of the target page:
+
+- Default swap: the page already has the configured product and agent.
+- `npm run attach -- --bootstrap`: the page has no Foldspace SDK.
+- `npm run attach -- --replace`: the page has a different product or agent, or
+  an SDK without the configured agent.
+
+Run `npx foldspace help attach` for full requirements and safety options. Coding
+agents can read the versioned contract with `npx foldspace help --json`.
 
 ## Add an action
 

package/templates/agent-starter/foldspace.dev.json

@@ -2,7 +2,6 @@
   "$comment": "Generated by foldspace init. Use the bare product ID, not the EU-… SDK key.",
   "defaultTarget": "app",
   "sdkUrl": "https://script.eucerahive.io/web/sdk/foldspace.js",
-  "localActionsUrl": "http://localhost:3007/dist/index.js",
   "targets": {
     "app": {
       "name": "App",
@@ -10,8 +9,7 @@
       "productId": {{PRODUCT_ID_JSON}},
       "agentApiName": {{AGENT_API_NAME_JSON}},
       "hosts": {{HOSTS_JSON}},
-      "mode": "OVERLAY",
-      "loadLocally": true
+      "mode": "OVERLAY"
     }
   }
 }

package/bin/buildExtension.mjs

@@ -1,90 +0,0 @@
-import { execFileSync } from "child_process";
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
-const indexPath = path.join(projectDir, "extension", "index.js");
-
-const LOAD_LOCALLY_TRUE = "const LOAD_LOCALLY = true;";
-const LOAD_LOCALLY_FALSE = "const LOAD_LOCALLY = false;";
-const REMOTE_ENV_DEV = 'const REMOTE_ACTIONS_ENV = "DEV";';
-const REMOTE_ENV_PROD = 'const REMOTE_ACTIONS_ENV = "PROD";';
-
-function parseArgs(argv) {
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--env" && argv[i + 1]) return argv[++i];
-  }
-  return null;
-}
-
-const env = parseArgs(process.argv.slice(2));
-if (!env || (env !== "dev" && env !== "prod")) {
-  console.error('buildExtension: --env <dev|prod> is required');
-  process.exit(1);
-}
-
-function replaceInIndex(from, to, label) {
-  const source = fs.readFileSync(indexPath, "utf8");
-
-  if (!source.includes(from)) {
-    if (source.includes(to)) {
-      console.log(`buildExtension: ${label} already set`);
-      return;
-    }
-    console.error(
-      `buildExtension: expected ${label} pattern not found in index.js`,
-    );
-    process.exit(1);
-  }
-
-  fs.writeFileSync(indexPath, source.replace(from, to), "utf8");
-  console.log(`buildExtension: ${label} → ${to}`);
-}
-
-function setLoadLocally(value) {
-  if (!fs.existsSync(indexPath)) {
-    console.error("buildExtension: extension/index.js not found");
-    process.exit(1);
-  }
-  const from = value ? LOAD_LOCALLY_FALSE : LOAD_LOCALLY_TRUE;
-  const to = value ? LOAD_LOCALLY_TRUE : LOAD_LOCALLY_FALSE;
-  replaceInIndex(from, to, "LOAD_LOCALLY");
-}
-
-function setRemoteActionsEnv(targetEnv) {
-  const from = targetEnv === "dev" ? REMOTE_ENV_PROD : REMOTE_ENV_DEV;
-  const to = targetEnv === "dev" ? REMOTE_ENV_DEV : REMOTE_ENV_PROD;
-  replaceInIndex(from, to, "REMOTE_ACTIONS_ENV");
-}
-
-let failed = false;
-
-try {
-  execFileSync("tsx", ["scripts/build.ts"], {
-    cwd: projectDir,
-    stdio: "inherit",
-  });
-
-  setLoadLocally(false);
-  setRemoteActionsEnv(env);
-
-  execFileSync("node", ["scripts/packageExtension.mjs"], {
-    cwd: projectDir,
-    stdio: "inherit",
-  });
-} catch {
-  failed = true;
-} finally {
-  try {
-    setLoadLocally(true);
-    setRemoteActionsEnv("prod");
-  } catch {
-    failed = true;
-  }
-}
-
-if (failed) {
-  process.exit(1);
-}

package/bin/packageExtension.mjs

@@ -1,29 +0,0 @@
-import { execFileSync } from "child_process";
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
-const projectName = path.basename(projectDir);
-const extensionDir = path.join(projectDir, "extension");
-const zipPath = path.join(projectDir, `${projectName}-extension.zip`);
-
-if (!fs.existsSync(extensionDir)) {
-  console.error("packageExtension: extension/ directory not found");
-  process.exit(1);
-}
-
-try {
-  if (fs.existsSync(zipPath)) {
-    fs.rmSync(zipPath);
-  }
-  execFileSync("zip", ["-r", zipPath, "."], {
-    cwd: extensionDir,
-    stdio: "inherit",
-  });
-  console.log(`packageExtension: created ${zipPath}`);
-} catch {
-  console.error("packageExtension: failed to create extension.zip");
-  process.exit(1);
-}