@crewhaus/spec 0.4.0 → 0.4.2

package/dist/index.js

@@ -1325,6 +1325,57 @@ const observabilityBlock = z
 })
     .strict()
     .optional();
+/**
+ * "Watch me" — the sampled phase-2 judge pass of `crewhaus watchme report`,
+ * the ONE model-spending analysis phase. Absent ⇒ deterministic-only reports
+ * (the field defaults below still resolve at lower time, so a budgeted judge
+ * always names a model).
+ */
+const watchmeJudgeBlock = z
+    .object({
+    /** Judge model for the sampled phase-2 quality pass. Refused at runtime
+     *  if unpriced (dream-engine pattern) — the budget cap must be
+     *  enforceable. */
+    model: z.string().min(1).default("claude-haiku-4-5"),
+    /** Fraction of ungraded turns escalated to the judge. */
+    sample_rate: z.number().min(0).max(1).default(0.15),
+    /** Per-report spend cap. 0 (default) = deterministic-only reports. */
+    budget_usd: z.number().min(0).default(0),
+})
+    .strict();
+/**
+ * "Watch me" — observe this harness's interactions and learn from them
+ * (design/watch-me.md). Presence turns on the live capture tap; `crewhaus
+ * watchme report` distills the watched sessions post-hoc. Carried on the
+ * three interactive-loop shapes (cli, channel, managed); the strict unions
+ * reject the key loudly elsewhere (research/crew are a named deferral,
+ * design/watch-me.md §13.1).
+ *
+ * Deliberately a SIBLING of `observability:`, not a sub-key of it:
+ * observability controls the generic telemetry subscribers (ring buffer,
+ * printers, metrics, cost, alerts, otel) while watchme is a learning feature
+ * with its own durable store and spec-synthesis outputs. Capture is
+ * INDEPENDENT of `observability.trace.level` — that knob controls the ring
+ * buffer + printers only, never the watchme tap.
+ *
+ * Every knob defaults, so a bare `watchme: {}` is a complete declaration.
+ * NO `watchme.*` path is optimizer-tunable — see the exclusion note beside
+ * OPTIMIZABLE_PATHS in `@crewhaus/spec-patch`.
+ */
+const watchmeBlock = z
+    .object({
+    enabled: z.boolean().default(true),
+    /** "full" = write the .events.jsonl trace sibling; "mirrors" = rely on the
+     *  default-on advisor mirrors only (retro-analysis grade, no extra file). */
+    capture: z.enum(["full", "mirrors"]).default("full"),
+    judge: watchmeJudgeBlock.optional(),
+    /** "user" additionally registers this harness in the global registry at run time. */
+    scope: z.enum(["harness", "user"]).default("harness"),
+    /** Publish redacted distilled findings to the wiki/Thredz at report time. */
+    share: z.boolean().default(false),
+})
+    .strict()
+    .optional();
 /**
  * Section 47 — blockchain subsystem blocks (cross-cutting). Any shape may
  * declare any subset of `chains` / `wallets` / `contracts` /
@@ -1396,10 +1447,13 @@ const contractsBlock = z.array(contractBindingSchema).optional();
 const transactionPolicyBlock = transactionPolicySchema.optional();
 /**
  * Phase 3 §3.3 — CLI banner with optional tagline rotation. When set,
- * the compiled cli-target bundle prints this banner on cold start
- * (suppressed under `--resume` / `--continue` so resumed sessions
- * don't re-banner). Static mode picks the first tagline; random mode
- * picks one uniformly per startup.
+ * BOTH cli surfaces print this banner on cold start — the compiled
+ * bundle and `crewhaus run` (which used to ignore the block entirely,
+ * making an authored banner invisible to anyone who ran the spec
+ * directly). Suppressed under `--resume` / `--continue` so resumed
+ * sessions don't re-banner, and under `CREWHAUS_RESUMED=1` for a
+ * wrapper re-invoking a compiled bundle. Static mode picks the first
+ * tagline; random mode picks one uniformly per startup.
  */
 const cliBannerBlock = z
     .object({
@@ -1602,6 +1656,8 @@ const cliSchema = z
     thredz: thredzBlock,
     learning: learningBlock,
     observability: observabilityBlock,
+    // "Watch me" — observe-and-learn (sibling of observability, see watchmeBlock).
+    watchme: watchmeBlock,
     cli: cliOptionsBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
@@ -1710,6 +1766,15 @@ const whatsappChannelSchema = z
     phoneNumberId: z.string().min(1),
     accessToken: z.string().min(1),
     appSecret: z.string().min(1),
+    // The token Meta presents on the GET callback-URL verification handshake
+    // (`hub.verify_token`). Optional: a daemon serving an already-verified
+    // subscription does not need it, and without it the handshake fails
+    // closed rather than echoing an unauthenticated challenge.
+    verifyToken: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("shared token echoed back on Meta's GET callback-URL verification handshake; required to verify a new webhook subscription"),
 })
     .strict();
 const imessageChannelSchema = z
@@ -1792,6 +1857,8 @@ const channelSchema = z
     thredz: thredzBlock,
     learning: learningBlock,
     observability: observabilityBlock,
+    // "Watch me" — observe-and-learn (sibling of observability, see watchmeBlock).
+    watchme: watchmeBlock,
     heartbeat: heartbeatBlock,
     // Loop contract 0.4 (Batch F) — cron/interval wake trigger (the general
     // temporal surface beside the interval-only `heartbeat`).
@@ -1818,9 +1885,28 @@ const graphNodeSchema = z
     tools: z.array(z.string().min(1)).optional(),
     tool_config: toolConfigBlock,
     /**
-     * When true, the node calls `ctx.requestApproval(prompt)` before
-     * returning. The engine pauses, persists a checkpoint, and waits for
-     * `resume(checkpointId, decision)` from the operator/CLI.
+     * A human approval gate on this node, and a PRE-condition: the node
+     * calls `ctx.requestApproval(prompt)` BEFORE its model turn, so the
+     * prompt is answered against the UPSTREAM state (which the `hitl_pause`
+     * event and the bundle's pause report both print) and no tokens are
+     * spent until the human answers. The engine pauses, persists a
+     * checkpoint, and waits for `resume(checkpointId, decision)` from the
+     * operator/CLI; the resumed run replays this node from the top and
+     * makes its FIRST model call.
+     *
+     * The decision string is recorded at `state["<node>_decision"]`, which
+     * every downstream node reads as part of the upstream state. (NOTE:
+     * `edges[].when.key` cannot name it yet — that key must name a declared
+     * node; see the `graphEdgeWhenSchema` note below.) A rejecting decision
+     * — `reject`, `no`, `deny`, `decline`, `abort`, `cancel`, `stop`, `veto`
+     * (trimmed, case-insensitive) — cancels this node's turn entirely, so
+     * the node records only its decision and no output; any other string,
+     * including free text, approves it. To halt the run on a rejection,
+     * guard the node's outgoing edge with `when: { key: <node>, exists:
+     * true }` — a cancelled node records no output, so no edge matches.
+     *
+     * To have a human approve a node's OWN output, put the gate on the
+     * DOWNSTREAM node: its upstream state is exactly that output.
      */
     hitl: z
         .object({
@@ -1857,8 +1943,16 @@ const graphAnyNodeSchema = z.union([graphNodeSchema, graphJudgeNodeSchema]);
  *   - `equals` — take the edge when `state[key] === equals` (string/number/
  *     boolean strict equality).
  *   - `exists: true` — take the edge when `state[key] !== undefined` (the
- *     node has produced output; pairs with hitl `_decision` gating in a
- *     follow-up).
+ *     node has produced output — which, for a `hitl:` node, is FALSE when
+ *     the operator rejected the gate, since a rejected node records only
+ *     `state["<node>_decision"]`).
+ *
+ * GAP (unchanged by the pre-condition HITL fix): `key` may not yet name a
+ * hitl node's `<node>_decision` record — the cross-check below pins it to a
+ * declared node name, so a rejection can be observed via `exists` on the
+ * node itself but not matched on the decision string. Widening it means
+ * touching the three mirrored checks (this one, ir-passes' graph
+ * wellformedness, target-graph's validateGraph).
  *
  * Lowered to `IrGraphEdge.when` and emitted as a graph-engine
  * `EdgeCondition` (`(state) => state[key] === equals` / `!== undefined`).
@@ -1979,6 +2073,23 @@ const managedSchema = z
     expose: exposeBlock,
     // Loop contract 0.4 (Batch B, G02) — in-loop output evaluation.
     evaluation: evaluationBlock,
+    // NEW-inloop-coverage — human-rating capture on the GATEWAY shape.
+    //
+    // WHAT MANAGED SUPPORTS: the daemon serves a `feedback.submit` JSON-RPC
+    // method (params = the user-supplied FeedbackRecord subset) that appends
+    // a standard record to `.crewhaus/feedback/<tenant>.jsonl` — the exact
+    // sink `crewhaus distill` / `optimize --ratings` / `judge calibrate`
+    // already read; and `autoDistill: true` registers the janitor step that
+    // turns those ratings into versioned `<name>-ratings` registry datasets
+    // on the daemon's own clock (D39), because a gateway daemon never runs a
+    // `crewhaus run` teardown.
+    //
+    // WHAT IT CANNOT SUPPORT: `exitPrompt` is meaningless here (there is no
+    // REPL to exit — the compiler warns when it is set), and
+    // `channelReactions` is the channel shape's own inbound-reaction gate
+    // (also warned). Both parse for schema uniformity across shapes rather
+    // than being silently honoured.
+    feedback: feedbackBlock,
     memory: memoryBlock,
     // Loop contract 0.4 (Batch E, G22) — agent-shape RAG over doc sources.
     knowledge: knowledgeBlock,
@@ -1986,6 +2097,9 @@ const managedSchema = z
     thredz: thredzBlock,
     learning: learningBlock,
     observability: observabilityBlock,
+    // "Watch me" — observe-and-learn (sibling of observability, see watchmeBlock).
+    // Parse + lower ONLY on this shape in v1: compile() warns accepted-but-unwired.
+    watchme: watchmeBlock,
     // Loop contract 0.4 (Batch F) — cron/interval wake trigger.
     schedule: scheduleBlock,
 })
@@ -2287,6 +2401,22 @@ const browserDriverSchema = z
         .strict()
         .default({ width: 1280, height: 720 }),
     startUrl: z.string().url().optional(),
+    /**
+     * SECURITY — opt in to private/loopback navigation targets. Default false:
+     * the Navigate tool refuses private/loopback/link-local/metadata hosts
+     * before `driver.goto`, and the chromium backend routes every request
+     * through a DNS-pinning proxy that refuses the same floor at the
+     * connection layer. Together they stop a prompt-injected page from
+     * reaching the host's own services.
+     *
+     * Set true ONLY when the browser legitimately must reach a private target
+     * the operator controls AND the page content is trusted — an intranet app
+     * under test, or a locally-served fixture page (what the browser runtime
+     * smoke does). It relaxes BOTH layers for this spec, so it stays a
+     * per-spec reviewed decision and never a global switch. The http/https
+     * scheme allowlist is NOT waived.
+     */
+    allowPrivateTargets: z.boolean().default(false),
 })
     .strict();
 const browserSchema = z
@@ -2597,6 +2727,21 @@ function crossFieldIssues(data) {
             custom(["retrieve", "collection"], `pipeline retrieve.vectorBackend "${vectorBackend}" requires retrieve.collection`);
         }
     }
+    // "Watch me" (design/watch-me.md §4.2) — `watchme.share: true` publishes
+    // co-learning articles, so it conflicts with a thredz OBJECT that declares
+    // an EXPLICIT `visibility: "private"`. The boolean/string shorthands
+    // (default-private) get NO issue in v1 — publishing then lands
+    // private-visibility articles, legal single-agent behaviour — and an
+    // absent `thredz:` block is fine (publish degrades to the local wiki
+    // store, a feature not an error).
+    if (data.target === "cli" || data.target === "channel" || data.target === "managed") {
+        const thredz = data.thredz;
+        if (data.watchme?.share === true &&
+            typeof thredz === "object" &&
+            thredz.visibility === "private") {
+            custom(["watchme", "share"], "watchme.share publishes co-learning articles; thredz.visibility: private blocks cross-agent sharing — set visibility: shared or drop watchme.share");
+        }
+    }
     return issues;
 }
 export function parseSpec(yamlText) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "User-facing spec schema (Zod) + YAML parser",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.4.0",
+    "@crewhaus/errors": "0.4.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5"