@monster-orange/den 0.0.0 → 0.2.0

package/src/pillars/journeys/spec/schema.ts

@@ -0,0 +1,208 @@
+/**
+ * Zod schema for *.journey.yml journey specs (journeys pillar).
+ *
+ * Design rules (plan: agent-e2e-journeys, packet jrn-spec-schema):
+ * - STRICT everywhere: unknown keys are rejected at every level, so typos
+ *   and unsupported fields fail loudly at load time.
+ * - Budgets are fail-closed: max_turns, timeout_s, and max_total_tokens are
+ *   all REQUIRED with sanity bounds only — no default values are ever
+ *   injected; spec authors set every budget explicitly.
+ * - `model` is an optional spec field — the journey's declared default
+ *   agent model. The JOURNEYS_MODEL env var, when set, overrides every
+ *   spec's model (operator control for cost pinning / CI). A journey with
+ *   neither source configured is refused at run time (fail-closed).
+ * - persona.role is limited to admin|user|beta: browser session minting via
+ *   headlessLogin only supports those roles
+ *   (src/shared/auth/headless-login.ts). root_admin is excluded until a
+ *   browser login path exists for it.
+ * - success.assertions is the sole pass/fail authority: a discriminated
+ *   union on `kind`, each carrying a deterministic API probe request
+ *   ({method, path, body?} — POST probes with bodies are first-class).
+ */
+
+import { z } from "zod";
+
+// ── Budgets ──────────────────────────────────────────────────────────────────
+
+// HLD catalog rule: an individual journey must complete within 10 minutes.
+export const MAX_TIMEOUT_S = 600;
+
+const budgetsSchema = z
+  .strictObject({
+    /** Hard cap on agent turns; exceeded → run.cancel(). */
+    max_turns: z.int().positive(),
+    /** Wall-clock cap in seconds; bounded by the HLD's 10-minute catalog rule. */
+    timeout_s: z.int().positive().max(MAX_TIMEOUT_S),
+    /** Cumulative TokenUsage.totalTokens cap; exceeded → run.cancel(). */
+    max_total_tokens: z.int().positive(),
+  })
+  .describe(
+    "All budgets are required and fail-closed; no defaults are injected.",
+  );
+
+// ── Persona / surface / environments ────────────────────────────────────────
+
+// Roles supported by headlessLogin (browser session minting); root_admin
+// intentionally excluded — no headless browser login path exists for it.
+const personaRoleSchema = z.enum(["admin", "user", "beta"]);
+
+const personaSchema = z.strictObject({
+  role: personaRoleSchema,
+  /** Natural-language brief the synthetic user acts on. */
+  brief: z.string().min(1),
+});
+
+const surfaceSchema = z.enum(["browser", "api", "mixed"]);
+
+// ── HTTP capabilities (review finding R2-1) ─────────────────────────────────
+
+// Only POST/PUT/PATCH are grantable: GET stays origin-wide on the scoped
+// HTTP tool (reads are its purpose) and DELETE is harness-only (teardown).
+const httpCapabilityMethodSchema = z.enum(["POST", "PUT", "PATCH"]);
+
+/**
+ * One journey-scoped mutating-capability grant for the agent's HTTP tool.
+ * `path_pattern` matches the full request path; `*` matches exactly one
+ * path segment (e.g. `/api/v1/items/{*}/notes`, written without the
+ * braces in real patterns).
+ */
+const httpCapabilitySchema = z.strictObject({
+  methods: z.array(httpCapabilityMethodSchema).min(1),
+  path_pattern: z.string().min(1),
+});
+
+// Must match config/environments/*.json (env-selector's known set).
+// The runner additionally hard-refuses production and prod regardless of spec content.
+const environmentNameSchema = z.enum([
+  "local",
+  "dev",
+  "sandbox",
+  "staging",
+  "beta",
+  "prod",
+  "production",
+]);
+
+// ── Assertion probe request ──────────────────────────────────────────────────
+
+const probeMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+
+/**
+ * Deterministic API probe executed by the verifier (harness-side,
+ * allowlist + JWT client). `{placeholders}` in `path` bind to
+ * ledger-extracted resource ids at verification time.
+ */
+const probeRequestSchema = z.strictObject({
+  method: probeMethodSchema,
+  path: z.string().min(1),
+  /** Optional JSON request body (e.g. search POST probes). */
+  body: z.record(z.string(), z.unknown()).optional(),
+});
+
+// JSON literal usable in equality / containment / match predicates.
+const jsonLiteralSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+
+// ── Assertion discriminated union ────────────────────────────────────────────
+
+const httpStatusAssertion = z.strictObject({
+  kind: z.literal("http_status"),
+  request: probeRequestSchema,
+  /** Expected HTTP status code. */
+  equals: z.int().min(100).max(599),
+});
+
+const jsonPathExistsAssertion = z.strictObject({
+  kind: z.literal("json_path_exists"),
+  request: probeRequestSchema,
+  /** JSONPath that must resolve to a value. */
+  path: z.string().min(1),
+});
+
+const jsonPathEqualsAssertion = z.strictObject({
+  kind: z.literal("json_path_equals"),
+  request: probeRequestSchema,
+  path: z.string().min(1),
+  /** Literal the JSONPath value must equal. */
+  equals: jsonLiteralSchema,
+});
+
+const jsonPathContainsAssertion = z.strictObject({
+  kind: z.literal("json_path_contains"),
+  request: probeRequestSchema,
+  path: z.string().min(1),
+  /** String/array containment target at the JSONPath. */
+  contains: jsonLiteralSchema,
+});
+
+const arrayMinLengthAssertion = z.strictObject({
+  kind: z.literal("array_min_length"),
+  request: probeRequestSchema,
+  path: z.string().min(1),
+  /** Minimum number of items the array at the JSONPath must contain. */
+  min: z.int().positive(),
+});
+
+const arrayContainsMatchAssertion = z.strictObject({
+  kind: z.literal("array_contains_match"),
+  request: probeRequestSchema,
+  path: z.string().min(1),
+  /** Field predicates at least one array item must match. */
+  match: z
+    .record(z.string(), jsonLiteralSchema)
+    .refine((m) => Object.keys(m).length > 0, {
+      message: "match must declare at least one field predicate",
+    }),
+});
+
+export const journeyAssertionSchema = z.discriminatedUnion("kind", [
+  httpStatusAssertion,
+  jsonPathExistsAssertion,
+  jsonPathEqualsAssertion,
+  jsonPathContainsAssertion,
+  arrayMinLengthAssertion,
+  arrayContainsMatchAssertion,
+]);
+
+// ── Journey spec ─────────────────────────────────────────────────────────────
+
+const successSchema = z.strictObject({
+  /** Deterministic assertions — the sole pass/fail authority. Min 1. */
+  assertions: z.array(journeyAssertionSchema).min(1),
+  /** Optional advisory rubric lines for the (advisory-only) LLM judge. */
+  rubric: z.array(z.string()).optional(),
+});
+
+export const journeySpecSchema = z.strictObject({
+  name: z.string().min(1),
+  persona: personaSchema,
+  surface: surfaceSchema,
+  /**
+   * Default agent model for this journey (e.g. "composer"). The
+   * JOURNEYS_MODEL env var overrides it when set; with neither configured
+   * the runner refuses the journey (fail-closed, no invented default).
+   */
+  model: z.string().min(1).optional(),
+  /** Environments this journey may run against. The runner targets exactly one per invocation. */
+  environments: z.array(environmentNameSchema).min(1),
+  budgets: budgetsSchema,
+  /**
+   * Mutating grants for the scoped HTTP tool (api/mixed surfaces).
+   * OMITTED → the tool is read-only for mutations (safe default): every
+   * POST/PUT/PATCH is rejected before fetching. GET needs no grant.
+   */
+  http_capabilities: z.array(httpCapabilitySchema).optional(),
+  success: successSchema,
+});
+
+export type JourneySpec = z.infer<typeof journeySpecSchema>;
+export type JourneyHttpCapability = z.infer<typeof httpCapabilitySchema>;
+export type JourneyAssertion = z.infer<typeof journeyAssertionSchema>;
+export type JourneyProbeRequest = z.infer<typeof probeRequestSchema>;
+export type JourneyBudgets = z.infer<typeof budgetsSchema>;
+export type JourneyPersonaRole = z.infer<typeof personaRoleSchema>;
+export type JourneySurface = z.infer<typeof surfaceSchema>;

package/src/pillars/journeys/teardown.ts

@@ -0,0 +1,98 @@
+/**
+ * Journeys teardown executor — pure library over the run ledger (plan:
+ * jrn-runner packet, Approach §Isolation and teardown for Phase-1 pilots).
+ *
+ * INVOKED ONLY BY THE CALLER (the pilot entrypoint, jrn-pilot-journeys),
+ * strictly after runJourney → verify → report, in a finally block. Never
+ * called from inside runJourney.
+ *
+ * Deletes recognized ledger resources — from BOTH feeds (http-tool and
+ * browser network interception) — in REVERSE creation order, executing
+ * each entry's explicit cleanup descriptor through the caller-supplied
+ * allowlisted+authenticated HTTP client. Deletion failures and
+ * unmanaged-mutation warnings surface in the TeardownReport; nothing is
+ * swallowed, and unmanaged mutations are reported, never guessed-deleted.
+ *
+ * Run identity note: the runner injects the runId (`jrn-<journey>-<ts>-
+ * <rand4>`) into the persona brief as a required display-name prefix —
+ * best-effort labeling for humans; the ledger stays the teardown source
+ * of truth.
+ */
+
+import type {
+  CleanupRequest,
+  LedgerEntry,
+  RunLedger,
+  UnmanagedMutationWarning,
+} from "./tools/ledger.js";
+
+/**
+ * Caller-supplied HTTP client executing one cleanup request. The pilot
+ * entrypoint wires this to the allowlisted+JWT client so teardown carries
+ * the same auth and reach constraints as the journey itself.
+ */
+export type TeardownHttpClient = (
+  request: CleanupRequest,
+) => Promise<{ status: number }>;
+
+/** Outcome of one attempted deletion. */
+export interface TeardownResultItem {
+  entry: LedgerEntry;
+  ok: boolean;
+  /** HTTP status when the request completed. */
+  status?: number;
+  /** Error message when the client threw (transport failure etc.). */
+  error?: string;
+}
+
+export interface TeardownReport {
+  /** Every attempted deletion, in execution (reverse-creation) order. */
+  results: TeardownResultItem[];
+  /** Subset of results that did not succeed — never swallowed. */
+  failures: TeardownResultItem[];
+  /** Unmanaged mutations observed during the run (reported, not deleted). */
+  unmanagedWarnings: readonly UnmanagedMutationWarning[];
+  /**
+   * Browser interception-processing failures — a creation MAY have gone
+   * unrecorded, so these surface as report warnings (finding 7).
+   */
+  interceptionErrors: readonly string[];
+}
+
+/**
+ * Delete every recognized ledger resource in reverse creation order via
+ * its explicit cleanup descriptor. A failed deletion (non-2xx or thrown
+ * client error) is recorded and execution continues with the remaining
+ * entries — partial teardown is better than none, and the report carries
+ * the full picture.
+ */
+export async function teardownLedger(
+  ledger: RunLedger,
+  httpClient: TeardownHttpClient,
+): Promise<TeardownReport> {
+  const results: TeardownResultItem[] = [];
+
+  for (const entry of [...ledger.entries].reverse()) {
+    try {
+      const response = await httpClient(entry.cleanup);
+      results.push({
+        entry,
+        ok: response.status >= 200 && response.status < 300,
+        status: response.status,
+      });
+    } catch (error) {
+      results.push({
+        entry,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    results,
+    failures: results.filter((result) => !result.ok),
+    unmanagedWarnings: ledger.warnings,
+    interceptionErrors: ledger.interceptionErrors,
+  };
+}

package/src/pillars/journeys/tools/browser-session.ts

@@ -0,0 +1,219 @@
+/**
+ * Journeys browser-session provisioning — mints a FRESH Playwright
+ * storageState at every run start via the existing den machinery
+ * (getCredentials → headlessLogin), exactly mirroring
+ * src/pillars/browser/global-setup.ts, which re-mints every run. There is
+ * deliberately NO staleness heuristic.
+ *
+ * Ordering note for the runner (jrn-runner packet): getCredentials reads
+ * E2E_* env vars in CI, so this MUST run BEFORE sanitizeEnvironment().
+ * The return value is ONLY the auth-file path — credential values never
+ * leave this function, and downstream code (browser toolset) consumes the
+ * path alone.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { getDistRoot } from "../../../shared/paths.js";
+import {
+  getCredentials,
+  headlessLogin,
+} from "../../../shared/auth/headless-login.js";
+import { envSelector } from "../../../shared/environment/env-selector.js";
+import {
+  resolveAuthPath,
+  type Role,
+} from "../../../shared/environment/playwright-env.js";
+import type { Environment } from "../../../shared/types/index.js";
+import type { JourneysSessionTokenConfig } from "../app-config.js";
+
+import { product } from "../../../shared/product.js";
+/**
+ * Mint a fresh authenticated browser session for `role` against `env`'s
+ * web surface and return the storageState auth-file path (and nothing
+ * else). Throws a loud, actionable error when credentials cannot be
+ * sourced — naming both the 1Password path (local) and the E2E_* env-var
+ * path (CI), mirroring browser/global-setup.ts.
+ */
+export async function provisionBrowserSession(
+  role: Role,
+  env: Environment,
+): Promise<string> {
+  const envConfig = await envSelector.loadEnvironment(env);
+  const webBaseUrl = envConfig.baseUrls.web;
+  const authFile = resolveAuthPath(role, env, getDistRoot());
+
+  const credentials = await getCredentials(role, env);
+  if (!credentials) {
+    const localHint =
+      role === "admin"
+        ? `  Local: make auth-configure env=${env}  (handles 1Password sign-in automatically)\n`
+        : `  Local: sign in to the secrets backend (make ${product().cli}-setup-secrets); the ${role} account comes from test_accounts in the org config\n`;
+    throw new Error(
+      `No credentials for ${role}.\n` +
+        localHint +
+        `  CI: set E2E_${role.toUpperCase()}_EMAIL / E2E_${role.toUpperCase()}_PASSWORD`,
+    );
+  }
+
+  fs.mkdirSync(path.dirname(authFile), { recursive: true });
+
+  try {
+    await headlessLogin(
+      role,
+      webBaseUrl,
+      credentials.email,
+      credentials.password,
+      authFile,
+      envConfig.auth?.browser,
+    );
+  } catch (error) {
+    // Re-throw with a credential-free message: headlessLogin failures can
+    // carry page/URL context but must never leak email or password values
+    // into transcripts or reports.
+    const raw = error instanceof Error ? error.message : String(error);
+    const scrubbed = raw
+      .split(credentials.password)
+      .join("[REDACTED]")
+      .split(credentials.email)
+      .join("[REDACTED]");
+    throw new Error(
+      `Browser session mint failed for ${role} against ${webBaseUrl}: ${scrubbed}`,
+    );
+  }
+
+  return authFile;
+}
+
+/** Bearer + extra headers for API-assertion probes, from a browser session. */
+export interface SessionApiToken {
+  /** Bearer token for the app's API. */
+  apiToken: string;
+  /**
+   * Extra headers every API call carries (`session_token.headers`: header
+   * name -> response field), e.g. the org or workspace the session resolves
+   * to. Not secrets; empty when none are declared.
+   */
+  headers: Record<string, string>;
+}
+
+/** Injectable HTTP layer for {@link deriveApiTokenFromSession} (unit tests). */
+export interface DeriveApiTokenDeps {
+  /**
+   * GET `tokenPath` on the web origin with the saved session cookies. The
+   * default drives a short-lived Playwright request context seeded from the
+   * storageState auth file, so HttpOnly session cookies are replayed exactly
+   * as a browser would.
+   */
+  fetchAccessToken?: (
+    webBaseUrl: string,
+    authFilePath: string,
+    tokenPath: string,
+  ) => Promise<{ status: number; body: unknown }>;
+}
+
+/* istanbul ignore next - Playwright request context tested via E2E */
+async function defaultFetchAccessToken(
+  webBaseUrl: string,
+  authFilePath: string,
+  tokenPath: string,
+): Promise<{ status: number; body: unknown }> {
+  const { request } = await import("playwright");
+  const context = await request.newContext({
+    baseURL: webBaseUrl,
+    storageState: authFilePath,
+  });
+  try {
+    const response = await context.get(tokenPath, {
+      timeout: 15000,
+    });
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      body = await response.text();
+    }
+    return { status: response.status(), body };
+  } finally {
+    await context.dispose();
+  }
+}
+
+/**
+ * Derive an API Bearer token (and any declared scoping headers) from a
+ * minted browser session — no password grant. Calls the app's own
+ * session-token route (`journeys.app.session_token.path` in the manifest)
+ * on the web origin with the session cookies from `authFilePath`: the token
+ * comes from the same real-user session the agent navigates with.
+ *
+ * Fails loudly (never returns a partial/absent token) so a missing token can
+ * never silently degrade a deterministic API assertion into a false pass.
+ */
+export async function deriveApiTokenFromSession(
+  authFilePath: string,
+  env: Environment,
+  sessionToken: JourneysSessionTokenConfig | undefined,
+  deps: DeriveApiTokenDeps = {},
+): Promise<SessionApiToken> {
+  if (sessionToken === undefined) {
+    throw new Error(
+      "No journeys.app.session_token in the spec-hosting repo's manifest: " +
+        "the journeys pillar needs the app's route that returns an API " +
+        "token for a browser session (path, token_field, headers) to run " +
+        "deterministic API assertions.",
+    );
+  }
+  const fetchAccessToken = deps.fetchAccessToken ?? defaultFetchAccessToken;
+  const envConfig = await envSelector.loadEnvironment(env);
+  const webBaseUrl = envConfig.baseUrls.web;
+  const tokenPath = sessionToken.path;
+  const tokenField = sessionToken.token_field ?? "access_token";
+
+  const { status, body } = await fetchAccessToken(
+    webBaseUrl,
+    authFilePath,
+    tokenPath,
+  );
+
+  if (status !== 200) {
+    const detail =
+      status === 401
+        ? "session not authenticated (storageState has no valid session cookie)"
+        : status === 403
+          ? "session is authenticated but has no API access"
+          : `unexpected status ${status}`;
+    throw new Error(
+      `Failed to derive an API token from the browser session against ` +
+        `${webBaseUrl}${tokenPath}: ${detail}. Deterministic API ` +
+        `assertions require a real-user token minted from the session.`,
+    );
+  }
+
+  const parsed =
+    typeof body === "object" && body !== null
+      ? (body as Record<string, unknown>)
+      : {};
+  const field = (name: string): string => {
+    const v = parsed[name];
+    return typeof v === "string" ? v.trim() : "";
+  };
+
+  const apiToken = field(tokenField);
+  const headers: Record<string, string> = {};
+  const missing: string[] = apiToken.length === 0 ? [tokenField] : [];
+  for (const [header, name] of Object.entries(sessionToken.headers ?? {})) {
+    const value = field(name);
+    if (value.length === 0) missing.push(name);
+    else headers[header] = value;
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `The browser session's ${tokenPath} response was missing ` +
+        `${missing.join(", ")}. Cannot run deterministic API assertions ` +
+        `without a real-user token.`,
+    );
+  }
+
+  return { apiToken, headers };
+}