replicas-cli 0.2.335 → 0.2.337

package/dist/index.mjs

@@ -8681,8 +8681,67 @@ var GOOGLE_ABILITY = {
   referenceFile: { name: "GOOGLE.md", content: REFERENCE5 }
 };
 
+// ../shared/src/default-skills/replicas-agent/abilities/learnings.ts
+var SECTION6 = `### Learnings
+Curated, human-approved organization knowledge that helps you execute correctly \u2014 conventions, gotchas, environment facts, and past user corrections that the codebase alone can't tell you.
+
+**Reference:** \`references/LEARNINGS.md\`
+
+Use this when:
+- You are starting a substantive task and have gathered enough context to write a meaningful query
+- A user corrects you about a durable fact, preference, or process worth keeping
+- You find an existing learning contradicted by the current code or docs`;
+var REFERENCE6 = `# Learnings
+
+Learnings are curated, human-approved knowledge entries your organization maintains: conventions, gotchas, environment facts, and process rules. Some entries always apply; contextual entries are retrieved by matching your query against their trigger descriptions.
+
+## Reading Learnings
+
+\`\`\`bash
+replicas learnings read --query "<enriched query>"
+\`\`\`
+
+**When to read:** once you've collected enough context to write a meaningful query \u2014 typically after your first look at the relevant code. Don't wait until you're deep into execution; learnings are most valuable before you commit to an approach.
+
+**Enrich the query.** Use codebase specifics (feature area, module/component names), not the raw user request. Triggers describe *situations*, so a query grounded in what the task actually touches matches far better.
+
+Example: the user asks "remove the PRs chart projections". After locating the chart you know it lives in the platform admin dashboard, so query:
+
+\`\`\`bash
+replicas learnings read --query "Remove the PRs chart in the platform admin dashboard"
+\`\`\`
+
+This matches a learning triggered on "UI/UX work on the admin panel" that the raw request would have missed.
+
+Output is a list of blocks \u2014 id, name, and content. Use the ids to propose updates or deletions.
+
+## Proposing changes
+
+All writes are proposals: a human reviews them in the dashboard, and nothing takes effect until approved.
+
+\`\`\`bash
+replicas learnings add --name "<short name>" --content "<the knowledge>" [--trigger "<when to surface it>"] [--always] [--global]
+replicas learnings update <id> [--name "..."] [--content "..."] [--trigger "..."] [--always true|false]
+replicas learnings delete <id>
+\`\`\`
+
+\`--always\` marks an entry as always-returned (no trigger needed); \`--global\` proposes org-wide scope instead of this workspace's environment.
+
+**Be very conservative:**
+- Propose \`add\` only for durable, org-useful facts: explicit user corrections, hard-won environment or process knowledge.
+- Never store task-specific details, anything derivable by reading the repo, or secrets/credentials.
+- Propose \`update\` or \`delete\` when a learning is contradicted by the current code or docs \u2014 flag outdated knowledge instead of silently ignoring it.
+- Write narrow triggers describing when the entry should surface (e.g. "UI/UX work on the admin panel"), not vague topics.`;
+var LEARNINGS_ABILITY = {
+  label: "Learnings",
+  description: "Fetch curated org knowledge and propose new learnings for human review.",
+  bullet: "- Fetching organization Learnings (curated, human-approved knowledge) before executing, or proposing new ones",
+  section: SECTION6,
+  referenceFile: { name: "LEARNINGS.md", content: REFERENCE6 }
+};
+
 // ../shared/src/default-skills/replicas-agent/abilities/linear.ts
-var SECTION6 = `### Linear
+var SECTION7 = `### Linear
 Fetch issues, update state, add comments, and search via the Linear GraphQL API.
 
 **Reference:** \`references/LINEAR.md\`
@@ -8691,7 +8750,7 @@ Use this when:
 - You encounter a Linear issue link and need to understand the task
 - You need to update an issue's state (e.g. mark as done)
 - You need to comment on or search for Linear issues`;
-var REFERENCE6 = `# Linear Integration
+var REFERENCE7 = `# Linear Integration
 
 This guide covers how to interact with Linear from within your Replicas workspace.
 
@@ -8780,12 +8839,12 @@ var LINEAR_ABILITY = {
   label: "Linear",
   description: "Fetch issues, post comments, update states via the Linear GraphQL API.",
   bullet: "- Interacting with Linear (fetching issues, updating state, commenting, etc.)",
-  section: SECTION6,
-  referenceFile: { name: "LINEAR.md", content: REFERENCE6 }
+  section: SECTION7,
+  referenceFile: { name: "LINEAR.md", content: REFERENCE7 }
 };
 
 // ../shared/src/default-skills/replicas-agent/abilities/media.ts
-var SECTION7 = `### Media
+var SECTION8 = `### Media
 Share screenshots, screen recordings, generated diagrams, and audio clips inline in the Replicas chat and natively embedded in external messages.
 
 **Reference:** \`references/MEDIA.md\`
@@ -8794,7 +8853,7 @@ Use this when:
 - You produce a screenshot, recording, generated image, or audio clip the user should see
 - You record video output (browser automation, screen capture) \u2014 including the recommended aspect ratio and FPS
 - You need to embed media in a Slack/Linear/GitHub message AND keep a referenceable copy in the Replicas dashboard`;
-var REFERENCE7 = `# Media (Screenshots, Recordings, Audio)
+var REFERENCE8 = `# Media (Screenshots, Recordings, Audio)
 
 This guide covers how to share screenshots, screen recordings, generated diagrams, and audio clips \u2014 both inline in the Replicas chat and natively embedded in external surfaces (Slack, Linear, GitHub).
 
@@ -9046,12 +9105,12 @@ var MEDIA_ABILITY = {
   label: "Media",
   description: "Share screenshots, recordings, generated images, and audio clips.",
   bullet: "- Producing or showing the user any media \u2014 screenshots, screen recordings, generated images or diagrams, audio clips \u2014 including in your Replicas chat reply, PR descriptions/comments, and other external platforms",
-  section: SECTION7,
-  referenceFile: { name: "MEDIA.md", content: REFERENCE7 }
+  section: SECTION8,
+  referenceFile: { name: "MEDIA.md", content: REFERENCE8 }
 };
 
 // ../shared/src/default-skills/replicas-agent/abilities/previews.ts
-var SECTION8 = `### Previews
+var SECTION9 = `### Previews
 Expose locally running services (web apps, APIs, databases) as public preview URLs so humans can interact with them directly.
 
 **Reference:** \`references/PREVIEWS.md\`
@@ -9060,7 +9119,7 @@ Use this when:
 - You need to start a service that a human should view or interact with
 - The task involves UI work that benefits from human review
 - You are verifying frontend/backend integrations visually`;
-var REFERENCE8 = `# Preview URLs
+var REFERENCE9 = `# Preview URLs
 
 When you run services on ports \u2014 such as a web app, API server, or database \u2014 humans may want to interact with them directly. You can expose your locally running services as public preview URLs.
 
@@ -9142,12 +9201,12 @@ var PREVIEWS_ABILITY = {
   label: "Previews",
   description: "Expose locally running services on public preview URLs for humans.",
   bullet: "- Creating preview URLs for locally running services",
-  section: SECTION8,
-  referenceFile: { name: "PREVIEWS.md", content: REFERENCE8 }
+  section: SECTION9,
+  referenceFile: { name: "PREVIEWS.md", content: REFERENCE9 }
 };
 
 // ../shared/src/default-skills/replicas-agent/abilities/replicas.ts
-var SECTION9 = `### Replicas (in-workspace CLI)
+var SECTION10 = `### Replicas (in-workspace CLI)
 Take action *with* Replicas itself \u2014 manage automations, environments (variables, files), repos, and \`replicas.json\` config \u2014 using the pre-installed, pre-authenticated \`replicas\` CLI.
 
 **Reference:** \`references/REPLICAS.md\`
@@ -9157,7 +9216,7 @@ Use this when:
 - The user asks you to manage environments, environment variables, or environment files
 - The user asks "what envs / repos / automations do I have?"
 - The user asks you to scaffold a \`replicas.json\` / \`replicas.yaml\` in a repo`;
-var REFERENCE9 = `# Replicas (in-workspace CLI)
+var REFERENCE10 = `# Replicas (in-workspace CLI)
 
 This guide covers how to take action *with* Replicas itself from inside a Replicas workspace \u2014 managing automations, environments (and their variables/files), repos, previews, and the user's \`replicas.json\` config \u2014 using the pre-installed \`replicas\` CLI.
 
@@ -9359,13 +9418,13 @@ var REPLICAS_ABILITY = {
   description: "Teach the agent about Replicas itself \u2014 automations, environments, the in-workspace CLI.",
   // No bullet — help_instructions covers the `replicas` CLI surface in detail.
   bullet: "",
-  section: SECTION9,
-  referenceFile: { name: "REPLICAS.md", content: REFERENCE9 },
+  section: SECTION10,
+  referenceFile: { name: "REPLICAS.md", content: REFERENCE10 },
   locked: true
 };
 
 // ../shared/src/default-skills/replicas-agent/abilities/slack.ts
-var SECTION10 = `### Slack
+var SECTION11 = `### Slack
 Send messages, read threads, search conversations, and upload files via the Slack Web API.
 
 **Reference:** \`references/SLACK.md\`
@@ -9375,7 +9434,7 @@ Use this when:
 - You need to read or fetch a Slack conversation
 - You encounter a Slack message link and need to retrieve its content
 - The task asks you to notify, update, or communicate via Slack`;
-var REFERENCE10 = `# Slack Integration
+var REFERENCE11 = `# Slack Integration
 
 This guide covers how to interact with Slack from within your Replicas workspace.
 
@@ -9476,8 +9535,8 @@ var SLACK_ABILITY = {
   label: "Slack",
   description: "Send messages, read threads, search conversations, upload files.",
   bullet: "- Interacting with Slack (sending messages, reading threads, etc.)",
-  section: SECTION10,
-  referenceFile: { name: "SLACK.md", content: REFERENCE10 }
+  section: SECTION11,
+  referenceFile: { name: "SLACK.md", content: REFERENCE11 }
 };
 
 // ../shared/src/default-skills/replicas-agent/registry.ts
@@ -9488,6 +9547,7 @@ var REPLICAS_AGENT_ABILITY_REGISTRY = {
   github: GITHUB_ABILITY,
   gitlab: GITLAB_ABILITY,
   google: GOOGLE_ABILITY,
+  learnings: LEARNINGS_ABILITY,
   linear: LINEAR_ABILITY,
   media: MEDIA_ABILITY,
   previews: PREVIEWS_ABILITY,
@@ -9537,7 +9597,7 @@ var HOOK_EXEC_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 var REPLICAS_CONFIG_FILENAMES = ["replicas.json", "replicas.yaml", "replicas.yml"];
 
 // ../shared/src/cli-version.ts
-var CLI_VERSION = "0.2.335";
+var CLI_VERSION = "0.2.337";
 
 // ../shared/src/engine/environment.ts
 var DESKTOP_NOVNC_PORT = 6080;
@@ -11004,6 +11064,7 @@ function messageForItem(item) {
       description: item.description,
       prompt: item.prompt,
       subagentType: item.subagentType,
+      ...item.receiverThreadIds ? { receiverThreadIds: item.receiverThreadIds } : {},
       ...item.model ? { model: item.model } : {},
       status: normalizeCodexAspTranscriptStatus(item.status),
       ...item.output ? { output: item.output } : {},
@@ -11082,8 +11143,11 @@ function duplicateMessage(a, b) {
 function mergeCodexAspDisplayMessages(primary, supplemental) {
   const merged = [...primary];
   for (const message of supplemental) {
-    if (!merged.some((existing) => duplicateMessage(existing, message))) {
+    const duplicateIndex = merged.findIndex((existing) => duplicateMessage(existing, message));
+    if (duplicateIndex === -1) {
       merged.push(message);
+    } else if (message.type === "user") {
+      merged[duplicateIndex] = { ...merged[duplicateIndex], timestamp: message.timestamp };
     }
   }
   return merged.map((message, index) => ({ message, index })).sort((a, b) => parseTimestampMs(a.message.timestamp) - parseTimestampMs(b.message.timestamp) || a.index - b.index).map(({ message }) => message);
@@ -14489,6 +14553,76 @@ async function mediaListCommand(options) {
   }
 }
 
+// src/commands/learnings.ts
+function printBlocks(learnings) {
+  for (const learning of learnings) {
+    const labels = [
+      learning.scope === "global" ? "org-wide" : "environment",
+      ...learning.always_apply ? ["always applies"] : []
+    ];
+    console.log(`## ${learning.name} (id: ${learning.id}, ${labels.join(", ")})`);
+    console.log(learning.content);
+    console.log("");
+  }
+}
+async function learningsReadCommand(options) {
+  const query = options.query?.trim();
+  if (!query) {
+    throw new Error("--query is required. Enrich it with codebase specifics (feature area, module names).");
+  }
+  const response = await agentFetch("/v1/agent/learnings/read", {
+    method: "POST",
+    body: { query }
+  });
+  if (response.learnings.length === 0) {
+    console.log("No learnings matched this query.");
+  } else {
+    printBlocks(response.learnings);
+  }
+  if (response.matching_degraded) {
+    console.log("Note: trigger matching was unavailable \u2014 only always-apply learnings are shown.");
+  }
+}
+async function propose(request) {
+  const { proposal } = await agentFetch("/v1/agent/learnings/proposals", {
+    method: "POST",
+    body: request
+  });
+  console.log(
+    `Proposal submitted for human review (${proposal.action}, id: ${proposal.id}). It only takes effect once approved in the dashboard.`
+  );
+}
+async function learningsAddCommand(options) {
+  await propose({
+    action: "add",
+    name: options.name,
+    content: options.content,
+    trigger: options.trigger,
+    always_apply: options.always || void 0,
+    global: options.global || void 0
+  });
+}
+function parseAlways(value) {
+  if (value === void 0) return void 0;
+  if (value !== "true" && value !== "false") {
+    throw new Error("--always must be 'true' or 'false'");
+  }
+  return value === "true";
+}
+async function learningsUpdateCommand(id, options) {
+  await propose({
+    action: "update",
+    target_learning_id: id,
+    name: options.name,
+    content: options.content,
+    trigger: options.trigger,
+    always_apply: parseAlways(options.always)
+  });
+}
+async function learningsDeleteCommand(id) {
+  await propose({ action: "delete", target_learning_id: id });
+}
+
 // src/commands/computer/index.ts
 import { spawn as spawn4, spawnSync as spawnSync3 } from "child_process";
 import { createHash as createHash2 } from "crypto";
@@ -20429,6 +20563,55 @@ if (isAgentMode()) {
       if (error instanceof Error) {
         console.error(chalk23.red(`
 \u2717 ${error.message}
+`));
+      }
+      process.exit(1);
+    }
+  });
+  const learnings = program.command("learnings").description("Fetch curated org knowledge and propose changes for human review");
+  learnings.command("read").description("Fetch learnings relevant to a task. Enrich the query with codebase specifics, not the raw user request.").requiredOption("-q, --query <query>", "Enriched task description to match against learning triggers").action(async (options) => {
+    try {
+      await learningsReadCommand(options);
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(chalk23.red(`
+\u2717 ${error.message}
+`));
+      }
+      process.exit(1);
+    }
+  });
+  learnings.command("add").description("Propose a new learning (pending human review)").requiredOption("-n, --name <name>", "Short name for the learning").requiredOption("-c, --content <content>", "The knowledge itself").option("-t, --trigger <trigger>", "When this learning should surface (required unless --always)").option("-a, --always", "Always apply instead of trigger-matching").option("-g, --global", "Propose org-wide scope instead of this workspace environment").action(async (options) => {
+    try {
+      await learningsAddCommand(options);
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(chalk23.red(`
+\u2717 ${error.message}
+`));
+      }
+      process.exit(1);
+    }
+  });
+  learnings.command("update <id>").description("Propose changes to an existing learning (pending human review)").option("-n, --name <name>", "New name").option("-c, --content <content>", "New content").option("-t, --trigger <trigger>", "New trigger").option("-a, --always <bool>", "Set always-apply: 'true' or 'false'").action(async (id, options) => {
+    try {
+      await learningsUpdateCommand(id, options);
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(chalk23.red(`
+\u2717 ${error.message}
+`));
+      }
+      process.exit(1);
+    }
+  });
+  learnings.command("delete <id>").description("Propose deleting an outdated learning (pending human review)").action(async (id) => {
+    try {
+      await learningsDeleteCommand(id);
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(chalk23.red(`
+\u2717 ${error.message}
 `));
       }
       process.exit(1);
@@ -20474,7 +20657,8 @@ if (isAgentMode()) {
     "computer",
     "automation",
     "repos",
-    "environment"
+    "environment",
+    "learnings"
   ]);
   const kept = program.commands.filter((cmd) => allowed.has(cmd.name()));
   const cmds = program.commands;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-cli",
-  "version": "0.2.335",
+  "version": "0.2.337",
   "description": "CLI for managing Replicas workspaces - SSH into cloud dev environments with automatic port forwarding",
   "main": "dist/index.mjs",
   "bin": {