oh-my-codex 0.18.1 → 0.18.2

package/src/scripts/__tests__/docs-site-contract.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { describe, it } from 'node:test';
+
+const root = process.cwd();
+
+function read(path: string): string {
+  return readFileSync(join(root, path), 'utf-8');
+}
+
+const docsPages = ['docs/index.html', 'docs/getting-started.html', 'docs/agents.html', 'docs/skills.html', 'docs/integrations.html'];
+
+describe('public docs site contract', () => {
+  it('keeps every repo-owned docs HTML page linked to an existing stylesheet', () => {
+    for (const page of docsPages) {
+      const content = read(page);
+      const hrefs = [...content.matchAll(/<link\s+[^>]*rel="stylesheet"[^>]*href="([^"]+)"/g)].map((match) => match[1]);
+      assert.ok(hrefs.length > 0, `${page} should link a stylesheet`);
+      for (const href of hrefs) {
+        assert.ok(!href.startsWith('http'), `${page} should use a repo-owned relative stylesheet, got ${href}`);
+        const resolved = join(root, dirname(page), href);
+        assert.ok(existsSync(resolved), `${page} stylesheet must exist: ${href}`);
+      }
+    }
+  });
+
+  it('defines CSS for the layout classes used by the static docs pages', () => {
+    const css = read('docs/style.css');
+    assert.match(css, /(^|\n)\.grid\s*,\s*\n\.card-grid\s*\{/, 'docs/style.css must style .grid cards used by docs pages');
+    for (const page of docsPages) {
+      const content = read(page);
+      if (content.includes('class="grid"')) {
+        assert.match(css, /(^|\n)\.grid\s*,/, `${page} uses .grid, so docs/style.css must style it`);
+      }
+    }
+  });
+
+  it('documents research workflow boundaries on the public skills page', () => {
+    const content = read('docs/skills.html');
+    assert.match(content, /Research and Planning Boundaries/);
+    assert.match(content, /\$best-practice-research[\s\S]*ordinary pre-planning wrapper/);
+    assert.match(content, /\$autoresearch[\s\S]*bounded validator-gated research deliverable/);
+    assert.match(content, /\$autoresearch-goal[\s\S]*Codex goal-mode version/);
+    assert.match(content, /Autoresearch findings gathered before planning should feed into <code>\$ralplan<\/code> as evidence/);
+  });
+});

package/src/scripts/__tests__/notify-dispatcher.test.ts

@@ -6,16 +6,145 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 
-function runDispatcher(metadataPath: string): void {
+function runDispatcher(
+	metadataPath: string,
+	payload: Record<string, unknown> = { type: "test" },
+	env: NodeJS.ProcessEnv = {},
+): void {
 	const dispatcherScript = join(process.cwd(), "dist", "scripts", "notify-dispatcher.js");
 	const result = spawnSync(
 		process.execPath,
-		[dispatcherScript, "--metadata", metadataPath, JSON.stringify({ type: "test" })],
-		{ encoding: "utf-8", windowsHide: true },
+		[dispatcherScript, "--metadata", metadataPath, JSON.stringify(payload)],
+		{ encoding: "utf-8", env: { ...process.env, ...env }, windowsHide: true },
 	);
 	assert.equal(result.status, 0, result.stderr || result.stdout);
 }
 
+describe("notify dispatcher turn-ended storm guard", () => {
+	it("coalesces rapid turn-ended dispatcher callbacks to one OMX notify run", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-rapid-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			for (let index = 0; index < 10; index += 1) {
+				runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "desktop-thread", turn_id: `queued-${index}` });
+			}
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("allows separate turn-ended identities to dispatch independently", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-identities-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "desktop-thread-a", turn_id: "queued-a" });
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "desktop-thread-b", turn_id: "queued-b" });
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("coalesces same-identity turn-ended callbacks after a slow notify hook completes", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-slow-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; await new Promise((resolve) => setTimeout(resolve, 1500)); appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+			const env = { OMX_NOTIFY_DISPATCH_MIN_INTERVAL_MS: "1000" };
+
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "slow-thread", turn_id: "queued-a" }, env);
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "slow-thread", turn_id: "queued-b" }, env);
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("prunes expired turn-ended identity guard state", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-prune-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			const guardPath = join(wd, "notify-dispatch.guard.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+			writeFileSync(guardPath, JSON.stringify({
+				lastDispatchByIdentity: {
+					"thread_id:expired": Date.now() - 11 * 60_000,
+					"thread_id:recent": Date.now(),
+				},
+			}));
+
+			runDispatcher(metadataPath, { type: "agent-turn-complete", thread_id: "fresh-thread", turn_id: "queued-fresh" });
+
+			const guard = JSON.parse(readFileSync(guardPath, "utf-8"));
+			assert.equal("thread_id:expired" in guard.lastDispatchByIdentity, false);
+			assert.equal(typeof guard.lastDispatchByIdentity["thread_id:recent"], "number");
+			assert.equal(typeof guard.lastDispatchByIdentity["thread_id:fresh-thread"], "number");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("drops stale turn-ended dispatcher callbacks before spawning notify hooks", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-stale-event-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { writeFileSync } from "node:fs"; writeFileSync(${JSON.stringify(omxMarker)}, "ran");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			runDispatcher(metadataPath, {
+				type: "agent-turn-complete",
+				timestamp: new Date(Date.now() - 10 * 60_000).toISOString(),
+				thread_id: "desktop-thread",
+				turn_id: "stale-turn",
+			});
+
+			assert.equal(existsSync(omxMarker), false);
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+
+	it("preserves normal non-turn notify dispatches", () => {
+		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-normal-"));
+		try {
+			const omxMarker = join(wd, "omx-ran");
+			const omxHook = join(wd, "current-notify-hook.js");
+			writeFileSync(omxHook, `import { appendFileSync } from "node:fs"; appendFileSync(${JSON.stringify(omxMarker)}, "omx|");\n`);
+			const metadataPath = join(wd, "notify-dispatch.json");
+			writeFileSync(metadataPath, JSON.stringify({ managedBy: "oh-my-codex", version: 1, omxNotify: [process.execPath, omxHook] }));
+
+			runDispatcher(metadataPath, { type: "test", id: 1 });
+			runDispatcher(metadataPath, { type: "test", id: 2 });
+
+			assert.equal(readFileSync(omxMarker, "utf-8"), "omx|omx|");
+		} finally {
+			rmSync(wd, { recursive: true, force: true });
+		}
+	});
+});
+
 describe("notify dispatcher previousNotify guard", () => {
 	it("skips stale OMX-managed previousNotify dispatcher entries", () => {
 		const wd = mkdtempSync(join(tmpdir(), "omx-notify-dispatcher-stale-"));

package/src/scripts/__tests__/run-test-files.test.ts

@@ -147,4 +147,71 @@ describe('run-test-files diagnostics', () => {
       rmSync(wd, { recursive: true, force: true });
     }
   });
+
+  it('sanitizes live OMX runtime state env from child test processes by default', () => {
+    const wd = mkdtempSync(join(tmpdir(), 'omx-run-test-files-'));
+    try {
+      const testsDir = join(wd, '__tests__');
+      mkdirSync(testsDir, { recursive: true });
+      writeFileSync(
+        join(testsDir, 'env-clean.test.js'),
+        [
+          "import { test } from 'node:test';",
+          "import assert from 'node:assert/strict';",
+          "test('runtime env is clean', () => {",
+          "  assert.equal(process.env.OMX_ROOT, undefined);",
+          "  assert.equal(process.env.OMX_STATE_ROOT, undefined);",
+          "  assert.equal(process.env.OMX_TEAM_STATE_ROOT, undefined);",
+          "  assert.equal(process.env.OMX_SESSION_ID, undefined);",
+          "  assert.equal(process.env.CODEX_SESSION_ID, undefined);",
+          "  assert.equal(process.env.SESSION_ID, undefined);",
+          "});",
+          '',
+        ].join('\n'),
+      );
+
+      const result = runCompiledRunner(wd, {
+        OMX_ROOT: '/tmp/live-omx-root',
+        OMX_STATE_ROOT: '/tmp/live-omx-state-root',
+        OMX_TEAM_STATE_ROOT: '/tmp/live-team-state-root',
+        OMX_SESSION_ID: 'live-omx-session',
+        CODEX_SESSION_ID: 'live-codex-session',
+        SESSION_ID: 'live-shell-session',
+      });
+
+      assert.equal(result.status, 0, result.stderr || result.stdout);
+    } finally {
+      rmSync(wd, { recursive: true, force: true });
+    }
+  });
+
+  it('can preserve live OMX runtime state env for explicit diagnostics', () => {
+    const wd = mkdtempSync(join(tmpdir(), 'omx-run-test-files-'));
+    try {
+      const testsDir = join(wd, '__tests__');
+      mkdirSync(testsDir, { recursive: true });
+      writeFileSync(
+        join(testsDir, 'env-preserve.test.js'),
+        [
+          "import { test } from 'node:test';",
+          "import assert from 'node:assert/strict';",
+          "test('runtime env is preserved', () => {",
+          "  assert.equal(process.env.OMX_ROOT, '/tmp/live-omx-root');",
+          "  assert.equal(process.env.OMX_SESSION_ID, 'live-omx-session');",
+          "});",
+          '',
+        ].join('\n'),
+      );
+
+      const result = runCompiledRunner(wd, {
+        OMX_NODE_TEST_PRESERVE_RUNTIME_ENV: '1',
+        OMX_ROOT: '/tmp/live-omx-root',
+        OMX_SESSION_ID: 'live-omx-session',
+      });
+
+      assert.equal(result.status, 0, result.stderr || result.stdout);
+    } finally {
+      rmSync(wd, { recursive: true, force: true });
+    }
+  });
 });

package/src/scripts/__tests__/verify-native-agents.test.ts

@@ -174,13 +174,13 @@ describe("verify-native-agents", () => {
     );
   });
 
-  it("fails if the plugin manifest declares setup-owned native-agent fields", async () => {
+  it("allows plugin-scoped hooks but fails if the plugin manifest declares setup-owned native-agent fields", async () => {
     await rejectsWithCode("native_agent_plugin_boundary_violation", () =>
       verifyNativeAgents({
         manifest: manifest([{ name: "executor", category: "build", status: "active" }]),
         definitions: { executor: definition },
         promptNames: new Set(["executor"]),
-        pluginManifest: { agents: "./agents/" },
+        pluginManifest: { agents: "./agents/", hooks: "./hooks/hooks.json" },
       }),
     );