@extrovert.dev/sdk 0.1.0-pre.7 → 0.1.0-pre.8

package/README.md

@@ -30,7 +30,7 @@ for a stable release:
 npm install @extrovert.dev/sdk@next
 ```
 
-Pin `@extrovert.dev/sdk@0.1.0-pre.7` when a dogfood test needs a reproducible contract snapshot.
+Pin `@extrovert.dev/sdk@0.1.0-pre.8` when a dogfood test needs a reproducible contract snapshot.
 Requires Node 18+ for global `fetch` and Web Crypto.
 
 ## Build and use from source
@@ -529,7 +529,7 @@ a wire protocol (there is no `/v1/contract` endpoint).
 ```ts
 import { CONTRACT_VERSION, CONTRACT_MANIFEST } from "@extrovert.dev/sdk";
 
-CONTRACT_VERSION;            // "0.1.0-pre.7": provisional, pre-1.0; pin it
+CONTRACT_VERSION;            // "0.1.0-pre.8": provisional, pre-1.0; pin it
 CONTRACT_MANIFEST.stability; // "provisional"
 CONTRACT_MANIFEST.core_shapes; // ["ReviewIntent","ReviewFeedback","DiffJson","Rule","ReviewEvent"]
 ```
@@ -550,7 +550,7 @@ page and the agent skills (`extrovert-send-email`, `extrovert-writing-rules`).
 The Review-Loop shapes are an **open, documented contract: versioned *with* this SDK** (not a wire
 protocol; there is no `/v1/contract` endpoint). Three guarantees:
 
-- **One version, everywhere.** `CONTRACT_VERSION` is **`0.1.0-pre.7`**, reconciled across the SDK package
+- **One version, everywhere.** `CONTRACT_VERSION` is **`0.1.0-pre.8`**, reconciled across the SDK package
   version, the MCP server, and the OpenAPI `info.version`. Pin it; pin `CONTRACT_MANIFEST` for the
   exact shape set you built against.
 - **Named, documented types.** The five canonical shapes: `ReviewIntent`, `ReviewFeedback`,
@@ -581,7 +581,7 @@ EXTROVERT_API_BASE_URL=mock npx tsx examples/wait-for-otp.ts
 
 ## Status
 
-> **Note.** This source SDK tracks the `/v1` contract at `CONTRACT_VERSION` `0.1.0-pre.7`: a
+> **Note.** This source SDK tracks the `/v1` contract at `CONTRACT_VERSION` `0.1.0-pre.8`: a
 > deliberate **prerelease**, pre-1.0, expect additive change. The offline `mock` transport models the
 > live server closely enough to reproduce a 422 `intent_required` and a queued review, so build and
 > test against it before you have a key. Install from the `next` tag until a stable release is cut.

package/dist/index.cjs

@@ -268,7 +268,7 @@ var CURRENT_API_VERSION = "2026-06-23";
 var API_VERSION_HEADER = "Extrovert-Version";
 
 // src/http.ts
-var SDK_VERSION = "0.1.0-pre.7";
+var SDK_VERSION = "0.1.0-pre.8";
 function buildUrl(baseUrl, path, query) {
   const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   const rel = path.startsWith("/") ? path : `/${path}`;
@@ -938,6 +938,8 @@ ${parent.text}`;
 var MockBackend = class {
   constructor() {
     this.state = freshState();
+    /** Save / edit a rule (mock) - append-only by supersession (D11). */
+    this.learnedRules = /* @__PURE__ */ new Map();
   }
   reset() {
     this.state = freshState();
@@ -2042,7 +2044,27 @@ var MockBackend = class {
       composition_token_expires_at: params.scope ? void 0 : new Date(Date.now() + 6e5).toISOString()
     };
   }
-  /** Save / edit a rule (mock) - append-only by supersession (D11). */
+  learnReviewRule(reviewId, req) {
+    const fingerprint = JSON.stringify({ reviewId, req });
+    const prior = this.learnedRules.get(req.client_id);
+    if (prior) {
+      if (prior.fingerprint !== fingerprint) throw new ValidationError({ status: 409, code: "conflict", message: "learning retry identity changed" });
+      return structuredClone(prior.result);
+    }
+    const turn = (this.state.reviewTurns.get(reviewId) ?? []).find((t) => t.id === req.source_turn_id);
+    if (!turn || turn.actor_kind !== "human" || !turn.actor_id) throw new ValidationError({ status: 403, code: "forbidden_scope", message: "learning requires authenticated human feedback" });
+    const rule = this.saveRule({ ...req, scope: req.target === "category" ? "category" : "general", source_review_id: reviewId, source_turn_id: turn.id });
+    rule.source_turn_id = turn.id;
+    rule.rule_layer = req.target === "org_house" ? "org" : "project";
+    if (req.target === "org_house") delete rule.project_id;
+    rule.source_review_id = reviewId;
+    rule.source_turn_id = turn.id;
+    const audit = [...this.state.ruleAudit.values()].find((entry) => entry.entity_id === rule.id);
+    audit.after_json = ruleSnapshotJSON(rule);
+    const result = { rule, source_review_id: reviewId, source_turn_id: turn.id, human_id: turn.actor_id, audit_id: audit.id, propagation: "queued" };
+    this.learnedRules.set(req.client_id, { fingerprint, result: structuredClone(result) });
+    return result;
+  }
   saveRule(req) {
     const text = req.rule_text.trim();
     if (!text) {
@@ -3683,6 +3705,7 @@ var HttpTransport = class {
       state: Array.isArray(params.state) ? params.state.join(",") : params.state,
       category_id: params.category_id,
       inbox: params.inbox,
+      composer: params.composer,
       limit: params.limit,
       page: params.page
     };
@@ -3765,10 +3788,12 @@ var HttpTransport = class {
     });
   }
   waitForReviewEvent(params, signal) {
+    const waitSeconds = Math.min(55, Math.max(1, params.wait_seconds ?? 55));
     return this.call({
       method: "GET",
       path: "/v1/reviews/events/wait",
-      query: { review_id: params.review_id, limit: params.limit, wait_seconds: params.wait_seconds },
+      query: { review_id: params.review_id, limit: params.limit, wait_seconds: waitSeconds },
+      timeoutMs: (waitSeconds + 10) * 1e3,
       signal
     });
   }
@@ -3837,6 +3862,9 @@ var HttpTransport = class {
       signal
     });
   }
+  learnReviewRule(reviewId, req, signal) {
+    return this.call({ method: "POST", path: `/v1/reviews/${encodeURIComponent(reviewId)}/learned-rules`, body: req, signal });
+  }
   saveRule(req, signal) {
     return this.call({
       method: "PUT",
@@ -4244,6 +4272,9 @@ var MockTransport = class {
   async getRules(params) {
     return this.backend.getRules(params);
   }
+  async learnReviewRule(reviewId, req) {
+    return this.backend.learnReviewRule(reviewId, req);
+  }
   async saveRule(req) {
     return this.backend.saveRule(req);
   }
@@ -5273,6 +5304,10 @@ var Rules = class {
   constructor(ctx) {
     this.ctx = ctx;
   }
+  /** Learn category or organization house rules from verified human review feedback. */
+  learnFromReview(reviewId, req, signal) {
+    return this.ctx.transport.learnReviewRule(reviewId, req, signal);
+  }
   /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
   get(params = {}, signal) {
     return this.ctx.transport.getRules(params, signal);
@@ -5280,7 +5315,7 @@ var Rules = class {
   /**
    * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
    * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
-   * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
+   * key's project. For org-layer house rules use learnFromReview with an authenticated human source; this method cannot author (`rule_layer:"org"`)
    * rules in v1: that is a console/admin action.
    */
   save(req, signal) {
@@ -5558,7 +5593,7 @@ async function signWebhook(secret, body, timestampSeconds) {
 }
 
 // src/contract.ts
-var CONTRACT_VERSION = "0.1.0-pre.7";
+var CONTRACT_VERSION = "0.1.0-pre.8";
 var CONTRACT_MANIFEST = {
   name: "extrovert.review-loop",
   version: CONTRACT_VERSION,
@@ -5589,6 +5624,8 @@ var CONTRACT_MANIFEST = {
     // realtime (M3)
     "ReviewEventReason",
     "ReviewEventsResult",
+    "LearnReviewRuleRequest",
+    "LearnedReviewRule",
     "ReviewEventCursor",
     // chat / revision / restamp (M5/M7)
     "PostReviewChatRequest",