@crewhaus/spec 0.4.0 → 0.5.0

package/dist/index.js

@@ -1110,7 +1110,8 @@ const continuityBlock = z.union([z.boolean(), continuityObject]).optional();
 /**
  * v0.3.0 Goal 3 (§4.1) — the top-level `thredz:` block: ONE knob that flips
  * the memory fabric's wiki backend to a hosted Thredz wiki over the published
- * `thredz-mcp` stdio server (npm, v0.2.0 — 25 tools incl. `goal_*`/`task_*`).
+ * `thredz-mcp` stdio server (npm, v0.3.0 — 27 tools incl. `goal_*`/`task_*`
+ * and the `wiki_space_*` pair).
  *
  * Forms:
  *   - boolean shorthand: `thredz: true` ≡ `{ api_key: "$THREDZ_API_KEY" }`
@@ -1142,6 +1143,22 @@ const thredzObject = z
     api_key: z.string().min(1),
     base_url: z.string().url().optional(),
     visibility: z.enum(["private", "shared"]).optional(),
+    /**
+     * 0.5.0 — a Thredz **wiki space** (Pro/Scale) to scope this agent's memory
+     * to; becomes the synthesized server's `THREDZ_DEFAULT_SPACE`. A `shared`
+     * space is readable by every wiki-enabled key on the account; an
+     * `individual` space only by the key that owns it.
+     *
+     * The space TYPE is chosen when the space is created (over the API, or via
+     * the model-callable `wiki_space_create`), not here — so this cannot be
+     * validated at compile time and `visibility` is not cross-checked against
+     * it. Inside a space the space's type decides visibility outright.
+     *
+     * ONE individual space per API KEY is a hard Thredz limit, so per-agent
+     * private memory means a per-agent `api_key`. That is one `thredz:` block
+     * per spec today; a crew gives each role its own (see the role-keyed form).
+     */
+    space: z.string().min(1).optional(),
     goals: z.boolean().optional(),
     agents: z
         .union([
@@ -1162,6 +1179,48 @@ const thredzObject = z
 })
     .strict();
 const thredzBlock = z.union([z.boolean(), z.string().min(1), thredzObject]).optional();
+/**
+ * 0.5.0 — the CREW-ONLY superset of {@link thredzObject}. `roles` fans the
+ * block out per role so each role can carry its OWN `api_key` and its own
+ * `space`; every other field at this level is the DEFAULT a role inherits and
+ * may override.
+ *
+ * WHY THE MAP LIVES HERE, under `thredz.roles.<role>`, and NOT on the role as
+ * `roles.<role>.thredz` — this is load-bearing, not taste. Two security
+ * surfaces prefix-match on `["thredz"]`:
+ *
+ *   - `@crewhaus/spec-patch`'s `OPTIMIZABLE_PATHS.crew` allows `["roles"]`
+ *     (whole-role replacement) and matches by PREFIX. Under `roles.*`, a
+ *     role's `api_key` would become optimizer-reachable and
+ *     `optimize --write-back` could rewrite a credential.
+ *   - the hangar's spec editor denies the `["thredz"]` prefix outright
+ *     ("thredz crosses the harness boundary to a hosted wiki"). Under
+ *     `roles.*`, `api_key` would be editable from a browser.
+ *
+ * Keeping the fan-out under `thredz.` inherits both protections with zero
+ * code change. The `^thredz:` header/badge regexes keep matching too.
+ *
+ * `api_key` is optional ONLY here: a pure fan-out crew gives every role its
+ * own key and needs no crew-wide one. The refinement below enforces that at
+ * least one of the two exists.
+ */
+const crewThredzObject = thredzObject
+    .extend({
+    api_key: z.string().min(1).optional(),
+    roles: z.record(safeName, thredzObject.partial({ api_key: true })).optional(),
+})
+    .strict()
+    .superRefine((t, ctx) => {
+    const fanOut = t.roles !== undefined && Object.keys(t.roles).length > 0;
+    if (!fanOut && t.api_key === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "thredz.api_key is required unless thredz.roles gives each role its own key (one individual wiki space per API key is a hard Thredz limit, so per-role private memory needs per-role keys)",
+        });
+    }
+});
+/** The crew mount: the shorthands still work, plus the role-keyed superset. */
+const crewThredzBlock = z.union([z.boolean(), z.string().min(1), crewThredzObject]).optional();
 /**
  * v0.3.0 Goal 2 (§3.3, PR 17) — the top-level `learning:` block: continual
  * learning as a first-class capability. Presence (with `enabled` not `false`)
@@ -1325,6 +1384,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 +1506,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 +1715,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 +1825,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 +1916,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 +1944,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 +2002,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 +2132,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 +2156,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,
 })
@@ -2136,7 +2309,7 @@ const crewSchema = z
     // surface, §2.7).
     memory: memoryBlock,
     continuity: continuityBlock,
-    thredz: thredzBlock,
+    thredz: crewThredzBlock,
     learning: learningBlock,
     // Loop contract 0.4 (Batch C, G26) — crew joins the observability-carrying
     // shapes (cli/channel/managed): the orchestrator's cost/trace/metrics/
@@ -2287,6 +2460,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
@@ -2517,6 +2706,48 @@ function crossFieldIssues(data) {
         if (roleNames.length > 0 && !roleNames.includes(data.entry)) {
             custom(["entry"], `crew.entry "${data.entry}" must name one of crew.roles (got: ${roleNames.join(", ")})`);
         }
+        // 0.5.0 — the role-keyed thredz fan-out. Both checks are cross-field, so
+        // they cannot live in the schema: `thredz.roles` and `roles` are siblings.
+        const crewThredz = data.thredz;
+        if (typeof crewThredz === "object" && crewThredz !== null && "roles" in crewThredz) {
+            const fanOut = crewThredz.roles;
+            const inheritedKey = crewThredz.api_key;
+            if (fanOut !== undefined) {
+                for (const name of Object.keys(fanOut)) {
+                    if (!roleNames.includes(name)) {
+                        custom(["thredz", "roles", name], `thredz.roles["${name}"]: no such role — crew.roles declares ${roleNames.join(", ")}`);
+                    }
+                }
+                // Every role must resolve to a key: its own, or the inherited one. A
+                // role with neither would silently get NO hosted wiki while its
+                // siblings got one, which is the kind of gap you find in production.
+                if (inheritedKey === undefined) {
+                    for (const name of roleNames) {
+                        if (fanOut[name]?.api_key === undefined) {
+                            custom(["thredz", "roles", name], `role "${name}" has no Thredz api_key and thredz.api_key is not set — give it one, or set a crew-wide thredz.api_key for the roles that share a wiki`);
+                        }
+                    }
+                }
+                // Two role names that slugify to the same MCP server name would make
+                // one silently overwrite the other's server entry.
+                const slugs = new Map();
+                for (const name of Object.keys(fanOut)) {
+                    const slug = name
+                        .toLowerCase()
+                        .replace(/[^a-z0-9]+/g, "-")
+                        .replace(/^-+|-+$/g, "");
+                    if (slug === "") {
+                        custom(["thredz", "roles", name], `thredz.roles["${name}"]: the role name has no characters usable in an MCP server name — rename the role`);
+                        continue;
+                    }
+                    const clash = slugs.get(slug);
+                    if (clash !== undefined) {
+                        custom(["thredz", "roles", name], `thredz.roles["${name}"] and thredz.roles["${clash}"] both reduce to the MCP server name "thredz-${slug}" — rename one`);
+                    }
+                    slugs.set(slug, name);
+                }
+            }
+        }
         if (data.routing !== undefined && data.routing.kind === "match" && data.routing.match) {
             for (const [from, rules] of Object.entries(data.routing.match)) {
                 if (!roleNames.includes(from)) {
@@ -2597,6 +2828,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.5.0",
   "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.5.0",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5"