@popmelt.com/core 0.9.0 → 0.10.0

package/README.md

@@ -39,6 +39,25 @@ Your agent can detect the framework, add the provider and integration, and prese
 
 Each annotation owns its thread. Status stays attached to the relevant part of the page while work is queued or running, and you can reopen any thread from its badge. Tool and Imprint receipts show what helped the agent reach its result.
 
+## Ambient Popmelt in Codex
+
+Popmelt can also pair ordinary project-bound Codex conversations with the same local project memory. Install the bundled Codex plugin once:
+
+```bash
+npx @popmelt.com/core codex install
+```
+
+Restart Codex completely, then begin a new conversation in the project. Popmelt will orient the conversation automatically when one store applies. If multiple stores apply, Codex will ask you to choose one writable primary store and any read-only mounted stores; it never infers write authority from directory nesting, recency, or store size.
+
+Ambient capture stays out of toolbar-owned runs, so opening a thread from the in-page toolbar still produces exactly one toolbar job. Popmelt tools remain available for intentional context expansion, decision review, and Imprint grounding.
+
+Useful diagnostics:
+
+```bash
+npx @popmelt.com/core codex status
+npx @popmelt.com/core codex doctor
+```
+
 ## Imprint
 
 As you work, Popmelt recognizes choices that may be useful beyond the current thread and proposes an Imprint update:

package/codex-plugin/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "popmelt-core",
+  "version": "0.10.0",
+  "description": "Ambient project memory and shared understanding for Codex",
+  "author": {
+    "name": "Popmelt",
+    "email": "reb@popmelt.com",
+    "url": "https://popmelt.com"
+  },
+  "homepage": "https://popmelt.com",
+  "repository": "https://github.com/popmelt/core",
+  "license": "PolyForm-Shield-1.0.0",
+  "keywords": [
+    "codex",
+    "memory",
+    "design",
+    "collaboration",
+    "knowledge"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Popmelt Core",
+    "shortDescription": "Ambient project memory for Codex",
+    "longDescription": "Pairs Codex conversations with Popmelt threads, retrieves accepted product truth and provisional explanations, records implementation evidence, and preserves explicit human authority over decisions and grounding.",
+    "developerName": "Popmelt",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://popmelt.com",
+    "defaultPrompt": [
+      "Show the Popmelt context relevant to this task.",
+      "Inspect the current Popmelt thread.",
+      "Help me review the surfaced product decision."
+    ],
+    "brandColor": "#111111",
+    "composerIcon": "./assets/popmelt-logo.svg",
+    "logo": "./assets/popmelt-logo.svg",
+    "logoDark": "./assets/popmelt-logo.svg"
+  }
+}

package/codex-plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "popmelt-core": {
+      "command": "node",
+      "args": ["./scripts/mcp.mjs"],
+      "cwd": ".",
+      "env_vars": ["POPMELT_CODEX_ORIENTATION_DIR", "POPMELT_CODEX_SESSION_DIR", "POPMELT_EXECUTION_OWNER", "POPMELT_PARENT_JOB_ID"],
+      "startup_timeout_sec": 40,
+      "tool_timeout_sec": 60
+    }
+  }
+}

package/codex-plugin/assets/popmelt-logo.svg

@@ -0,0 +1,4 @@
+<svg width="256" height="256" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="40" height="40" fill="#F1F1F1"/>
+<path d="M11.1406 31.2559C11.2407 31.3875 11.351 31.5132 11.4697 31.6338L3.10449 40H2.39746L11.1406 31.2559ZM8.05371 40H7.34668L14.5498 32.7959C14.8554 32.7706 15.1541 32.7063 15.4414 32.6113L8.05371 40ZM18.2197 34.0762C18.3788 34.1569 18.5445 34.2272 18.7168 34.2861L13.0039 40H12.2969L18.2197 34.0762ZM17.9531 40H17.2461L26.1338 31.1113C26.438 31.0829 26.7427 31.0148 27.0439 30.9082L17.9531 40ZM40 22.9023L22.9033 40H22.1963L40 22.1953V22.9023ZM40 27.8525L27.8525 40H27.1455L40 27.1455V27.8525ZM40 32.8027L32.8027 40H32.0957L40 32.0957V32.8027ZM40 37.752L37.752 40H37.0449L40 37.0449V37.752ZM9.06543 28.3809C9.25255 28.4332 9.45183 28.4715 9.66504 28.4883L0 38.1543V37.4473L9.06543 28.3809ZM6.59375 25.9023C6.65822 26.0626 6.73171 26.2263 6.81445 26.3896L0 33.2041V32.4971L6.59375 25.9023ZM20.25 8.00293H20.249C21.5098 8.0286 22.7219 8.25094 23.8584 8.63672L23.8604 8.63574C23.8961 8.64787 23.9312 8.66145 23.9668 8.67383C24.0611 8.70686 24.1548 8.74106 24.248 8.77637C24.2915 8.79273 24.3357 8.80727 24.3789 8.82422L24.376 8.82617C27.6145 10.0955 30.1646 12.7301 31.3213 16.0234L31.3232 16.0225C31.3327 16.0493 31.3404 16.0766 31.3496 16.1035C31.7691 17.3256 32 18.6356 32 20C32 20.8726 31.9366 21.6706 31.7598 22.4902L31.7197 22.6328C31.6412 23.0066 31.5136 23.6108 31.3408 24.2217L31.3398 24.2246C31.2967 24.377 31.251 24.5299 31.2021 24.6797C30.9215 25.5403 30.5473 26.2998 30.0879 26.2998C29.7613 26.2996 29.5995 25.9674 29.4316 25.6221C29.2501 25.2487 29.0614 24.8605 28.6484 24.8604C27.8532 24.8604 27.2081 25.5046 27.208 26.2998V27.0771C27.2079 27.6079 26.9661 28.112 26.5205 28.4004C25.9146 28.7925 25.2357 28.6462 24.7959 28.2061L24.7949 28.208C24.7897 28.2028 24.7854 28.1967 24.7803 28.1914C24.7654 28.1761 24.7507 28.1606 24.7363 28.1445C24.7105 28.1156 24.6858 28.0857 24.6621 28.0547C24.6461 28.0339 24.6302 28.013 24.6152 27.9912C24.5931 27.9591 24.5726 27.9257 24.5527 27.8916C24.5392 27.8685 24.5261 27.8452 24.5137 27.8213C24.5093 27.8128 24.5043 27.8045 24.5 27.7959L24.501 27.7939C24.3932 27.5763 24.3282 27.3276 24.3281 27.0576V26.2998C24.328 25.5993 23.8278 25.0158 23.165 24.8867V24.8877C23.0752 24.8702 22.9826 24.8604 22.8877 24.8604C22.8446 24.8604 22.8019 24.8624 22.7598 24.8662C22.0247 24.9312 21.4483 25.5479 21.4482 26.2998C21.4482 26.9127 21.4608 27.5305 21.4736 28.1494L21.4951 29.3135C21.5 29.7013 21.5015 30.089 21.4971 30.4756C21.4874 31.3103 20.8426 32 20.0078 32C19.1732 31.9998 18.5292 31.3102 18.5195 30.4756C18.5159 30.1613 18.5176 29.8464 18.5205 29.5312V29.5322C18.5212 29.4593 18.5206 29.3864 18.5215 29.3135L18.5303 28.8154V28.8145C18.5343 28.5927 18.5384 28.371 18.543 28.1494C18.5558 27.5305 18.5684 28.1129 18.5684 27.5C18.5684 26.7047 17.9232 26.0596 17.1279 26.0596C16.907 26.0596 16.6978 26.1103 16.5107 26.1992C16.2161 26.3393 15.9767 26.5769 15.834 26.8701C15.8269 26.8846 15.8201 26.8993 15.8135 26.9141C15.7821 26.9845 15.7562 27.0579 15.7363 27.1338C15.7243 27.1798 15.7155 27.2267 15.708 27.2744C15.7012 27.3175 15.6953 27.361 15.6924 27.4053C15.6903 27.4366 15.6885 27.4681 15.6885 27.5V28.7383C15.6883 29.9234 14.4911 30.7248 13.4961 30.0811C13.0505 29.7926 12.8086 29.2886 12.8086 28.7578V26.2998C12.8086 25.9737 12.6984 25.674 12.5156 25.4326C12.4437 25.3381 12.3612 25.2521 12.2686 25.1777V25.1768C12.0219 24.9788 11.709 24.8604 11.3682 24.8604C10.9892 24.8604 10.8622 24.8872 10.7295 25.2295C10.5837 25.6055 10.4302 26 9.92773 26C9.33081 25.9996 8.95963 25.2403 8.71484 24.3799C8.5591 23.8325 8.45907 23.571 8.3623 23.0107C8.3501 22.9401 8.33284 22.8403 8.31738 22.7529C8.12812 21.9466 8.02043 21.1089 8.00293 20.249V20.25L8 20C8 19.8617 8.00317 19.724 8.00781 19.5869C8.00837 19.5703 8.00816 19.5537 8.00879 19.5371L8.00977 19.5352C8.0998 17.1716 8.87444 14.9844 10.1396 13.1631C10.1488 13.1499 10.1587 13.1372 10.168 13.124C12.255 10.1453 15.6582 8.15745 19.5352 8.00977L19.5371 8.00879C19.5537 8.00816 19.5703 8.00837 19.5869 8.00781C19.724 8.00317 19.8617 8 20 8L20.25 8.00293ZM5.72266 22.5303L0 28.2539V27.5469L5.62793 21.918C5.6553 22.1234 5.6868 22.3275 5.72266 22.5303ZM16.2637 26.8398L16.2617 26.8408C16.2784 26.8013 16.2954 26.7627 16.3135 26.7256C16.3203 26.7116 16.3275 26.6982 16.334 26.6855C16.3125 26.7277 16.289 26.7808 16.2637 26.8398ZM40 17.9531L33.9854 23.9668C34.051 23.6832 34.1043 23.4321 34.1445 23.2412L34.1641 23.1748L34.1865 23.0967L34.1963 23.0488L40 17.2461V17.9531ZM5.87012 16.7266C5.80321 17.0165 5.74649 17.3101 5.69727 17.6064L0 23.3047V22.5977L5.87012 16.7266ZM40 13.0039L34.4297 18.5732C34.409 18.3615 34.3832 18.1513 34.3535 17.9424L40 12.2969V13.0039ZM0 18.3555V17.6484L17.6484 0H18.3555L0 18.3555ZM40 8.05371L33.458 14.5947C33.3909 14.4277 33.3202 14.2625 33.2471 14.0986L40 7.34668V8.05371ZM0 13.4053V12.6982L12.6992 0H13.4062L0 13.4053ZM40 3.10352L31.6865 11.416C31.5868 11.2805 31.4851 11.1465 31.3809 11.0146L40 2.39648V3.10352ZM29.2881 8.86523C29.1595 8.75783 29.0288 8.65278 28.8965 8.5498L37.4473 0H38.1543L29.2881 8.86523ZM0 8.45508V7.74805L7.74805 0H8.45508L0 8.45508ZM26.2783 6.92578C26.1183 6.84878 25.9562 6.77534 25.793 6.7041L32.498 0H33.2051L26.2783 6.92578ZM17.6064 5.69727C17.3101 5.74649 17.0165 5.80321 16.7266 5.87012L22.5977 0H23.3047L17.6064 5.69727ZM22.5322 5.7207C22.3295 5.685 22.1254 5.65316 21.9199 5.62598L27.5469 0H28.2539L22.5322 5.7207ZM0 3.50586V2.79883L2.79883 0H3.50586L0 3.50586Z" fill="black"/>
+</svg>

package/codex-plugin/hooks/hooks.json

@@ -0,0 +1,41 @@
+{
+  "description": "Ambient Popmelt Core turn lifecycle",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 40,
+            "statusMessage": "Loading Popmelt context",
+            "additionalContextLimit": 12000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 15,
+            "statusMessage": "Recording the Popmelt turn"
+          }
+        ]
+      }
+    ]
+  }
+}

package/codex-plugin/scripts/hook.mjs

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import { locatePopmeltCli } from './locate-cli.mjs';
+
+const input = readFileSync(0, 'utf8');
+const cli = locatePopmeltCli();
+const result = spawnSync(cli.command, [...cli.prefix, 'codex', 'hook'], {
+  cwd: process.cwd(),
+  env: process.env,
+  input,
+  encoding: 'utf8',
+  timeout: 45_000,
+});
+if (result.status === 0 && result.stdout?.trim()) {
+  process.stdout.write(result.stdout);
+} else {
+  process.stdout.write('{}\n');
+}

package/codex-plugin/scripts/locate-cli.mjs

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function locatePopmeltCli(start = process.cwd()) {
+  try {
+    const runtimePath = join(dirname(fileURLToPath(import.meta.url)), '..', 'runtime.json');
+    const runtime = JSON.parse(readFileSync(runtimePath, 'utf8'));
+    if (typeof runtime.cliPath === 'string' && existsSync(runtime.cliPath)) {
+      return { command: process.execPath, prefix: [runtime.cliPath] };
+    }
+  } catch {
+    // Source checkouts do not have an installed-runtime pointer yet.
+  }
+  let current = resolve(start);
+  const root = parse(current).root;
+  while (true) {
+    const candidates = [
+      join(current, 'node_modules', '@popmelt.com', 'core', 'dist', 'cli.mjs'),
+      join(current, 'packages', 'popmelt', 'dist', 'cli.mjs'),
+    ];
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return { command: process.execPath, prefix: [candidate] };
+    }
+    const packagePath = join(current, 'package.json');
+    if (existsSync(packagePath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+        if (pkg.name === '@popmelt.com/core') {
+          const local = join(current, 'dist', 'cli.mjs');
+          if (existsSync(local)) return { command: process.execPath, prefix: [local] };
+        }
+      } catch {
+        // Ignore malformed package metadata and continue searching upward.
+      }
+    }
+    if (current === root) break;
+    current = dirname(current);
+  }
+  return { command: 'popmelt', prefix: [] };
+}

package/codex-plugin/scripts/mcp.mjs

@@ -0,0 +1,15 @@
+import { spawn } from 'node:child_process';
+
+import { locatePopmeltCli } from './locate-cli.mjs';
+
+const cli = locatePopmeltCli();
+const child = spawn(cli.command, [...cli.prefix, 'codex', 'mcp'], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+});
+child.on('error', () => process.exit(1));
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/codex-plugin/skills/popmelt-core/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: popmelt-core
+description: Use Popmelt Core when the user asks to inspect project memory, expand relevant product context, review a surfaced decision candidate, ground a surfaced Imprint explanation, or discuss the current Popmelt thread.
+---
+
+# Popmelt Core
+
+Popmelt pairs the current Codex conversation with a durable project thread. Ambient hooks already retrieve context and capture ordinary turns, so do not call tools merely to announce or duplicate that automatic work.
+
+Use the tools deliberately:
+
+- Pass the exact `tool session` ID supplied by the Ambient Popmelt Core context as `sessionId` on every tool call. This routes the call to the correct project even when the MCP process has a different working directory.
+
+- Use `popmelt_orient_stores` only after the human explicitly chooses the writable primary store and any mounted read stores from an ambient orientation packet. Save that choice as the workspace default unless the human explicitly requests a session-only override. Store proximity, nesting, size, or recency never implies that choice.
+- Use `popmelt_expand_context` when the automatically supplied packet is truncated or the user explicitly asks for broader history.
+- Use `popmelt_inspect_thread` when the user asks to inspect the paired thread or its evidence.
+- Use `popmelt_review_decision` only after the human explicitly resolves the exact surfaced candidate. Preserve the actions `accept`, `edit_and_accept`, `reject`, and `defer`. Never infer acceptance from implementation, praise, silence, or ambiguity.
+- Use `popmelt_ground_imprint` only after the human explicitly answers a surfaced grounding question. Preserve the actions `yes`, `this_time`, and `no`.
+- Use `popmelt_assess_turn` only when the current collaboration changed reusable shared understanding. Ordinary completion and tool evidence are captured automatically.
+
+Accepted product decisions are authoritative within scope. Imprint explanations are provisional and advisory. The human remains the authority for both decision acceptance and Imprint grounding.
+
+If Popmelt reports `already_managed_by_bridge`, stop calling Popmelt Core tools for that run; the toolbar bridge owns the turn lifecycle.