@mytegroupinc/myte-core 0.0.15 → 0.0.17

package/README.md

@@ -76,7 +76,8 @@ Notes:
 - `sync-qaqc` keeps QAQC state in one deterministic file so the working set grows and shrinks with current active-mission reality.
 - `sync-qaqc` fully rewrites `MyteCommandCenter/data/qaqc.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`.
 - `feedback-sync` writes one deterministic feedback snapshot under `MyteCommandCenter/data/feedback.yml`.
-- `feedback-sync` includes readable PRD text inline when PRD text exists.
+- `feedback-sync` keeps feedback metadata plus comment turns in `MyteCommandCenter/data/feedback.yml`.
+- `feedback-sync` writes full PRD context into `MyteCommandCenter/PRD/feedback-sync/*.md` and points to those files from `feedback.yml`.
 - `feedback-sync` fully replaces the feedback-owned sync file to avoid stale local feedback noise.
 - `feedback-sync` fully rewrites `MyteCommandCenter/data/feedback.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`.
 - `suggestions sync` writes one merge-safe workflow file at `MyteCommandCenter/data/mission-ops.yml`.
@@ -138,3 +139,5 @@ Examples:
 - `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
 
 This package is published under the org scope for governance; the public `myte` wrapper delegates here.
+
+`--json-response` sends both the Myte convenience flag (`myte_json_response: true`) and the OpenAI-compatible chat-completions shape (`response_format: { type: "json_object" }`). On the public developer API, that strict-JSON path also defaults to `medium` reasoning unless the caller explicitly overrides reasoning.

package/cli.js

@@ -266,7 +266,8 @@ function printHelp() {
     "",
     "feedback-sync contract:",
     "  - Runs from the wrapper root that contains the project's configured repo folders",
-    "  - Writes open project feedback and inline PRD context into one deterministic file: MyteCommandCenter/data/feedback.yml",
+    "  - Writes open project feedback metadata and conversation turns into MyteCommandCenter/data/feedback.yml",
+    "  - Stores full PRD context in MyteCommandCenter/PRD/feedback-sync/*.md and points to those files from feedback.yml",
     "",
     "Options:",
     "  --with-diff           Include deterministic git diffs (project-scoped)",
@@ -274,7 +275,7 @@ function printHelp() {
     "  --timeout-ms <ms>     Request timeout (default: 300000)",
     "  --base-url <url>      API base (default: https://api.myte.dev)",
     "  --payload-file <path> Raw OpenAI-style chat-completions payload for `myte ai`",
-    "  --json-response       Ask the Myte AI gateway to return clean JSON only",
+    "  --json-response       Ask the Myte AI gateway to return clean JSON only and send OpenAI-compatible response_format",
     "  --max-output-tokens   Output token cap for `myte ai` simple queries",
     "  --temperature <num>   Temperature for `myte ai` simple queries",
     "  --output-dir <path>   Command Center output directory (default: <wrapper-root>/MyteCommandCenter)",
@@ -290,7 +291,7 @@ function printHelp() {
     "  --target-contact-ids  Comma-separated client contact ObjectIds",
     "  --status <value>      Feedback status filter for feedback-sync (default: Pending)",
     "  --source <value>      Feedback source filter for feedback-sync",
-    "  --with-prd-text       Include extracted PRD text in feedback-sync (default: on)",
+    "  --with-prd-text       Include extracted PRD text so local PRD files can be materialized during feedback-sync (default: on)",
     "  --mission-ids <ids>   Comma-separated mission business ids for run-qaqc (quote multi-id values on PowerShell)",
     "  --actor-scope <id>    Actor workspace key inside mission-ops.yml (defaults to machine-cwd slug)",
     "  --wait                Poll batch status until terminal completion for run-qaqc",
@@ -1066,9 +1067,15 @@ async function fetchQaqcSyncSnapshot({ apiBase, key, timeoutMs }) {
   );
 
   if (!resp.ok || body.status !== "success") {
+    const retryAfter = resp.headers?.get?.("retry-after");
     const msg = body?.message || `QAQC sync request failed (${resp.status})`;
-    const err = new Error(msg);
+    const err = new Error(
+      retryAfter
+        ? `${msg} Retry after ${retryAfter}s.`
+        : msg
+    );
     err.status = resp.status;
+    if (retryAfter) err.retryAfter = retryAfter;
     throw err;
   }
   return body.data || {};
@@ -1082,6 +1089,9 @@ async function fetchFeedbackSyncSnapshot({ apiBase, key, timeoutMs, filters = {}
   if (filters.includePrdText !== undefined) {
     url.searchParams.set("include_prd_text", filters.includePrdText ? "true" : "false");
   }
+  if (filters.includeCommentTurns !== undefined) {
+    url.searchParams.set("include_comment_turns", filters.includeCommentTurns ? "true" : "false");
+  }
   const { resp, body } = await fetchJsonWithTimeout(
     fetchFn,
     url.toString(),
@@ -1223,15 +1233,30 @@ async function fetchRunQaqcBatchStatus({ apiBase, key, timeoutMs, batchId }) {
   );
 
   if (!resp.ok || body.status !== "success") {
+    const retryAfter = resp.headers?.get?.("retry-after");
     const msg = body?.message || `Run QAQC status request failed (${resp.status})`;
-    const err = new Error(msg);
+    const err = new Error(
+      retryAfter
+        ? `${msg} Retry after ${retryAfter}s.`
+        : msg
+    );
     err.status = resp.status;
+    if (retryAfter) err.retryAfter = retryAfter;
     throw err;
   }
   return body.data || {};
 }
 
-async function callAssistantQuery({ apiBase, key, payload, timeoutMs, endpoint = "/project-assistant/query" }) {
+function resolveRetryAfterMs(err, fallbackMs = 5_000) {
+  const retryAfterRaw = firstNonEmptyString(err?.retryAfter);
+  const retryAfterSeconds = Number.parseInt(String(retryAfterRaw || ""), 10);
+  if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
+    return Math.min(retryAfterSeconds * 1_000, 60_000);
+  }
+  return fallbackMs;
+}
+
+async function createAssistantQueryJob({ apiBase, key, payload, timeoutMs, endpoint = "/project-assistant/query" }) {
   const fetchFn = await getFetch();
   const url = `${apiBase}${endpoint}`;
   const { resp, body } = await fetchJsonWithTimeout(
@@ -1249,9 +1274,35 @@ async function callAssistantQuery({ apiBase, key, payload, timeoutMs, endpoint =
   );
 
   if (!resp.ok || body.status !== "success") {
+    const retryAfter = resp.headers?.get?.("retry-after");
     const msg = body?.message || `Query failed (${resp.status})`;
-    const err = new Error(msg);
+    const err = new Error(retryAfter ? `${msg} Retry after ${retryAfter}s.` : msg);
+    err.status = resp.status;
+    if (retryAfter) err.retryAfter = retryAfter;
+    throw err;
+  }
+  return body.data || {};
+}
+
+async function fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId }) {
+  const fetchFn = await getFetch();
+  const url = `${apiBase}/project-assistant/query/${encodeURIComponent(String(jobId || ""))}`;
+  const { resp, body } = await fetchJsonWithTimeout(
+    fetchFn,
+    url,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${key}` },
+    },
+    timeoutMs
+  );
+
+  if (!resp.ok || body.status !== "success") {
+    const retryAfter = resp.headers?.get?.("retry-after");
+    const msg = body?.message || `Query status request failed (${resp.status})`;
+    const err = new Error(retryAfter ? `${msg} Retry after ${retryAfter}s.` : msg);
     err.status = resp.status;
+    if (retryAfter) err.retryAfter = retryAfter;
     throw err;
   }
   return body.data || {};
@@ -1322,6 +1373,10 @@ async function runRunQaqc(args) {
       try {
         finalStatus = await fetchRunQaqcBatchStatus({ apiBase, key, timeoutMs, batchId: data.batch_id });
       } catch (err) {
+        if (Number(err?.status) === 429) {
+          await sleep(resolveRetryAfterMs(err));
+          continue;
+        }
         console.error("Failed to fetch QAQC batch status:", err?.message || err);
         process.exit(1);
       }
@@ -1337,11 +1392,18 @@ async function runRunQaqc(args) {
 
     if (shouldSync && ["completed", "completed_with_errors"].includes(String(finalStatus.status || "").trim())) {
       let snapshot;
-      try {
-        snapshot = await fetchQaqcSyncSnapshot({ apiBase, key, timeoutMs });
-      } catch (err) {
-        console.error("Failed to fetch QAQC sync snapshot after batch completion:", err?.message || err);
-        process.exit(1);
+      for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+          snapshot = await fetchQaqcSyncSnapshot({ apiBase, key, timeoutMs });
+          break;
+        } catch (err) {
+          if (Number(err?.status) === 429 && attempt < 4) {
+            await sleep(resolveRetryAfterMs(err));
+            continue;
+          }
+          console.error("Failed to fetch QAQC sync snapshot after batch completion:", err?.message || err);
+          process.exit(1);
+        }
       }
 
       let resolved;
@@ -1664,6 +1726,20 @@ function stableItemId(item, keys, fallback) {
   return fallback;
 }
 
+function bootstrapPathId(item, preferredKeys, fallbackKeys, fallback) {
+  return stableItemId(item, preferredKeys, stableItemId(item, fallbackKeys, fallback));
+}
+
+function bootstrapScopedPathId(item, preferredKeys, scopeKeys, fallbackKeys, fallback) {
+  const preferred = stableItemId(item, preferredKeys, "");
+  if (preferred) return preferred;
+  const fallbackId = stableItemId(item, fallbackKeys, fallback);
+  const scopeParts = (Array.isArray(scopeKeys) ? scopeKeys : [])
+    .map((key) => String(item?.[key] || "").trim())
+    .filter(Boolean);
+  return [...scopeParts, fallbackId].filter(Boolean).join("__") || fallbackId;
+}
+
 function stringifyYaml(value) {
   // eslint-disable-next-line global-require
   const YAML = require("yaml");
@@ -1704,6 +1780,44 @@ function writeTextFile(filePath, value) {
   fs.writeFileSync(filePath, String(value || ""), "utf8");
 }
 
+function sanitizeFileSegment(value, fallback = "item") {
+  const cleaned = String(value || "")
+    .trim()
+    .replace(/[<>:"/\\|?*\x00-\x1F]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^\.+|\.+$/g, "")
+    .replace(/^-+|-+$/g, "");
+  return cleaned || fallback;
+}
+
+function toPosixRelativePath(rootPath, targetPath) {
+  return path.relative(rootPath, targetPath).split(path.sep).join("/");
+}
+
+function ensureTrailingNewline(value) {
+  const text = String(value || "");
+  if (!text) return "";
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+function normalizeFeedbackConversationTurns(turns) {
+  if (!Array.isArray(turns)) return [];
+  return turns
+    .map((turn) => {
+      const content = String(turn?.content || "").trim();
+      if (!content) return null;
+      const normalized = {
+        sender_name: firstNonEmptyString(turn?.sender_name, turn?.user_name, turn?.author_name) || "Unknown",
+        content,
+      };
+      const createdAt = firstNonEmptyString(turn?.created_at, turn?.timestamp);
+      if (createdAt) normalized.created_at = createdAt;
+      return normalized;
+    })
+    .filter(Boolean);
+}
+
 function readJsonFile(filePath) {
   if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return null;
   try {
@@ -1847,20 +1961,42 @@ function writeBootstrapSnapshot({ snapshot, wrapperRoot, outputDir }) {
   const missions = Array.isArray(snapshot.missions) ? snapshot.missions.map((item) => scrubBootstrapValue(item)) : [];
 
   phases.forEach((phase, index) => {
-    const phaseId = stableItemId(phase, ["phase_id", "id"], `P${String(index + 1).padStart(3, "0")}`);
-    writeYamlFile(path.join(phasesDir, `${phaseId}.yml`), phase);
+    const phasePathId = bootstrapPathId(
+      phase,
+      ["phase_key", "id"],
+      ["phase_id"],
+      `phase-${String(index + 1).padStart(3, "0")}`
+    );
+    writeYamlFile(path.join(phasesDir, `${phasePathId}.yml`), phase);
   });
   epics.forEach((epic, index) => {
-    const epicId = stableItemId(epic, ["epic_id", "id"], `E${String(index + 1).padStart(3, "0")}`);
-    writeYamlFile(path.join(epicsDir, `${epicId}.yml`), epic);
+    const epicPathId = bootstrapScopedPathId(
+      epic,
+      ["epic_key", "id"],
+      ["phase_key", "phase_id"],
+      ["epic_id"],
+      `epic-${String(index + 1).padStart(3, "0")}`
+    );
+    writeYamlFile(path.join(epicsDir, `${epicPathId}.yml`), epic);
   });
   stories.forEach((story, index) => {
-    const storyId = stableItemId(story, ["story_id", "id"], `S${String(index + 1).padStart(3, "0")}`);
-    writeYamlFile(path.join(storiesDir, `${storyId}.yml`), story);
+    const storyPathId = bootstrapScopedPathId(
+      story,
+      ["story_key", "id"],
+      ["phase_key", "phase_id", "epic_key", "epic_id"],
+      ["story_id"],
+      `story-${String(index + 1).padStart(3, "0")}`
+    );
+    writeYamlFile(path.join(storiesDir, `${storyPathId}.yml`), story);
   });
   missions.forEach((mission, index) => {
-    const missionId = stableItemId(mission, ["mission_id", "id"], `M${String(index + 1).padStart(3, "0")}`);
-    writeYamlFile(path.join(missionsDir, `${missionId}.yml`), mission);
+    const missionPathId = bootstrapPathId(
+      mission,
+      ["mission_key", "id"],
+      ["mission_id"],
+      `mission-${String(index + 1).padStart(3, "0")}`
+    );
+    writeYamlFile(path.join(missionsDir, `${missionPathId}.yml`), mission);
   });
 
   if (snapshot.project && typeof snapshot.project === "object") {
@@ -1921,8 +2057,11 @@ function writeQaqcSnapshot({ snapshot, wrapperRoot, outputDir }) {
 
 function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
   const { targetRoot, dataRoot } = resolveCommandCenterRoots(wrapperRoot, outputDir);
+  const prdSyncDir = path.join(targetRoot, "PRD", "feedback-sync");
 
   ensureDir(dataRoot);
+  ensureDir(prdSyncDir);
+  clearFileDirectory(prdSyncDir, [".md", ".markdown", ".txt"]);
   pruneLegacyCommandCenterArtifacts(dataRoot, { bootstrap: true, feedback: true });
 
   if (snapshot.project && typeof snapshot.project === "object") {
@@ -1930,15 +2069,58 @@ function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
   }
 
   const items = Array.isArray(snapshot.items) ? snapshot.items : [];
+  let prdFileCount = 0;
+  const materializedItems = items.map((rawItem, index) => {
+    const item = isPlainObject(rawItem) ? { ...rawItem } : {};
+    const feedbackId = stableItemId(item, ["feedback_id", "id"], `F${String(index + 1).padStart(3, "0")}`);
+    const conversationTurns = normalizeFeedbackConversationTurns(item.conversation_turns);
+    const prdText = String(item.prd_text || "").trim();
+
+    let contextSource = "description_only";
+    let contextNote = "No separate PRD. Use feedback_text as the context for this feedback item.";
+    let prdFile = null;
+
+    if (prdText) {
+      const prdFilename = `${sanitizeFileSegment(feedbackId, `feedback-${index + 1}`)}.md`;
+      const prdPath = path.join(prdSyncDir, prdFilename);
+      writeTextFile(prdPath, ensureTrailingNewline(prdText));
+      prdFile = toPosixRelativePath(targetRoot, prdPath);
+      contextSource = "prd_file";
+      contextNote = "Full PRD context is stored in the linked file.";
+      prdFileCount += 1;
+    } else if (item.has_prd_text) {
+      contextSource = "prd_declared_but_unavailable";
+      contextNote = "A separate PRD exists for this feedback item, but readable PRD text was not included in this sync snapshot.";
+    }
+
+    return {
+      ...item,
+      feedback_id: feedbackId,
+      conversation_turns: conversationTurns,
+      context_source: contextSource,
+      context_note: contextNote,
+      prd_file: prdFile,
+    };
+  });
+  const snapshotCounts = snapshot.counts && typeof snapshot.counts === "object"
+    ? { ...snapshot.counts }
+    : { total_feedback: materializedItems.length };
+  snapshotCounts.with_prd_files = prdFileCount;
+  if (snapshotCounts.with_conversation_turns === undefined) {
+    snapshotCounts.with_conversation_turns = materializedItems.filter((item) => Array.isArray(item?.conversation_turns) && item.conversation_turns.length > 0).length;
+  }
+
   const payload = scrubBootstrapValue({
-    schema_version: snapshot.schema_version || 1,
+    schema_version: snapshot.schema_version || 2,
     project: snapshot.project || null,
     repo_names: Array.isArray(snapshot.repo_names) ? snapshot.repo_names : [],
     filters: snapshot.filters && typeof snapshot.filters === "object" ? snapshot.filters : {},
-    counts: snapshot.counts && typeof snapshot.counts === "object"
-      ? snapshot.counts
-      : { total_feedback: items.length },
-    queue: items
+    counts: snapshotCounts,
+    artifacts: {
+      feedback_prd_root: "PRD/feedback-sync",
+      with_prd_files: prdFileCount,
+    },
+    queue: materializedItems
       .filter((item) => String(item?.status || "").trim().toLowerCase() !== "resolved")
       .map((item, index) => ({
         feedback_id: stableItemId(item, ["feedback_id", "id"], `F${String(index + 1).padStart(3, "0")}`),
@@ -1946,7 +2128,11 @@ function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
         priority: item?.priority || null,
         title: item?.title || null,
       })),
-    items,
+    items: materializedItems.map((item) => {
+      const nextItem = { ...item };
+      delete nextItem.prd_text;
+      return nextItem;
+    }),
     pagination: snapshot.pagination && typeof snapshot.pagination === "object" ? snapshot.pagination : undefined,
     generated_at: snapshot.generated_at || null,
     snapshot_hash: snapshot.snapshot_hash || null,
@@ -1956,6 +2142,7 @@ function writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir }) {
   return {
     targetRoot,
     dataRoot,
+    prdSyncDir,
     manifest: payload,
   };
 }
@@ -3024,6 +3211,7 @@ async function runFeedbackSync(args) {
     status: firstNonEmptyString(args.status) || "Pending",
     source: firstNonEmptyString(args.source) || "",
     includePrdText,
+    includeCommentTurns: true,
   };
 
   let snapshot;
@@ -3079,7 +3267,7 @@ async function runFeedbackSync(args) {
       console.log(`Configured repos: ${summary.repo_names.join(", ") || "(none)"}`);
       console.log(`Found locally: ${summary.local.found.join(", ") || "(none)"}`);
       if (summary.local.missing.length) console.log(`Missing locally: ${summary.local.missing.join(", ")}`);
-      console.log(`Counts: total_feedback=${summary.counts.total_feedback || 0}, with_prd_text=${summary.counts.with_prd_text || 0}`);
+      console.log(`Counts: total_feedback=${summary.counts.total_feedback || 0}, with_prd_text=${summary.counts.with_prd_text || 0}, with_conversation_turns=${summary.counts.with_conversation_turns || 0}`);
       console.log("Dry run only - no files written.");
     }
     return;
@@ -3087,6 +3275,9 @@ async function runFeedbackSync(args) {
 
   const writeResult = writeFeedbackSnapshot({ snapshot, wrapperRoot, outputDir });
   summary.data_root = writeResult.dataRoot;
+  summary.prd_root = writeResult.prdSyncDir;
+  summary.counts = writeResult.manifest?.counts || summary.counts;
+  summary.artifacts = writeResult.manifest?.artifacts || null;
 
   if (args.json) {
     console.log(JSON.stringify(summary, null, 2));
@@ -3099,7 +3290,8 @@ async function runFeedbackSync(args) {
   console.log(`Configured repos: ${summary.repo_names.join(", ") || "(none)"}`);
   console.log(`Found locally: ${summary.local.found.join(", ") || "(none)"}`);
   if (summary.local.missing.length) console.log(`Missing locally: ${summary.local.missing.join(", ")}`);
-  console.log(`Wrote feedback: total_feedback=${summary.counts.total_feedback || 0}, with_prd_text=${summary.counts.with_prd_text || 0}`);
+  console.log(`Wrote feedback: total_feedback=${summary.counts.total_feedback || 0}, with_prd_text=${summary.counts.with_prd_text || 0}, with_conversation_turns=${summary.counts.with_conversation_turns || 0}`);
+  console.log(`PRD root: ${summary.prd_root}`);
   console.log(`Snapshot: ${summary.snapshot_hash || "n/a"}`);
 }
 
@@ -3717,7 +3909,46 @@ async function runQuery(args) {
 
   let data;
   try {
-    data = await callAssistantQuery({ apiBase, key, payload, timeoutMs });
+    const queued = await createAssistantQueryJob({ apiBase, key, payload, timeoutMs });
+    if (queued.answer) {
+      data = queued;
+    } else {
+      const jobId = firstNonEmptyString(queued.job_id, queued.id);
+      if (!jobId) {
+        throw new Error("Query job was accepted without a job_id.");
+      }
+      const pollTimeoutMs = Math.max(timeoutMs, 900_000);
+      const startedAt = Date.now();
+      let finalStatus = null;
+      do {
+        await sleep(2_000);
+        try {
+          finalStatus = await fetchAssistantQueryJobStatus({ apiBase, key, timeoutMs, jobId });
+        } catch (err) {
+          if (Number(err?.status) === 429) {
+            await sleep(resolveRetryAfterMs(err));
+            continue;
+          }
+          throw err;
+        }
+        if (["completed", "failed"].includes(String(finalStatus.status || "").trim())) {
+          break;
+        }
+      } while (Date.now() - startedAt < pollTimeoutMs);
+
+      if (!finalStatus || !["completed", "failed"].includes(String(finalStatus.status || "").trim())) {
+        throw new Error(`Timed out waiting for query job ${jobId}`);
+      }
+      if (String(finalStatus.status || "").trim() === "failed") {
+        const detail = firstNonEmptyString(finalStatus?.error?.message, finalStatus?.error?.code);
+        throw new Error(detail || `Query job ${jobId} failed`);
+      }
+      data = {
+        answer: finalStatus.answer,
+        context_blocks: finalStatus.context_blocks,
+        telemetry: finalStatus.telemetry,
+      };
+    }
   } catch (err) {
     if (err?.name === "AbortError") {
       console.error(`Request timed out after ${timeoutMs}ms`);

package/lib/ai-gateway.js

@@ -16,7 +16,10 @@ function buildSimpleAiPayload({ query, jsonResponse = false, maxOutputTokens, te
   const payload = {
     messages: [{ role: "user", content: String(query || "").trim() }],
   };
-  if (jsonResponse) payload.myte_json_response = true;
+  if (jsonResponse) {
+    payload.myte_json_response = true;
+    payload.response_format = { type: "json_object" };
+  }
   if (Number.isFinite(Number(maxOutputTokens)) && Number(maxOutputTokens) > 0) {
     payload.max_tokens = Number(maxOutputTokens);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mytegroupinc/myte-core",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Myte CLI core implementation (Project Assistant + Myte AI gateway).",
   "type": "commonjs",
   "main": "cli.js",