gm-skill 2.0.1615 → 2.0.1617

package/gm-plugkit/instructions/browser.md

@@ -12,21 +12,26 @@ YOU drive the browser through the spool: plugkit holds the Chromium handle, per-
 
 ## Body shapes
 
-The body is a string, six shapes only:
+The body is a string, these shapes:
 
 ```
 session new
 session list
 session close <id>
 <arbitrary JS expression evaluated in page context>
+<https://... bare URL>
+url=<url>\n<expression>
 timeout=<ms>\n<expression>
 capture\n<expression>
+profile\n<expression>
 ```
 
-A bare expression with no live session opens one against `about:blank`; with a live session it reuses it. `session new` returns the id you carry; with more than one open, target it via `session=<id>\n<expr>`. (`session close` and `session kill` are aliases.) Default per-eval timeout 120000ms; operations that legitimately exceed it prefix `timeout=<ms>\n` (wrapper clamps to 120000ms). The response carries `timeout_ms_used`; `browser.runner-timeout` fires at the cap -- read `stderr`, narrow or raise, never retry blind at the same budget.
+**Open on the page you want to test, not a blank one.** A bare `https://...` URL body navigates the session straight to that page and returns `{url, title}` -- the simplest "show me this page." `url=<url>\n<expression>` navigates first, then runs your expression on the loaded page, so the global/DOM you assert is already there in one dispatch instead of a blank surface you must `page.goto` yourself. `url=` composes with `timeout=` and `capture` -- stack the prefix lines in order `timeout=`, then `url=`, then `capture`, the expression last; the prepended `page.goto` rides inside the capture so its navigation console/network is captured too. A bare expression with no URL prefix and no live session opens against `about:blank`; with a live session it reuses it. `session new` returns the id you carry; with more than one open, target it via `session=<id>\n<expr>`. (`session close` and `session kill` are aliases.) Default per-eval timeout 120000ms; operations that legitimately exceed it prefix `timeout=<ms>\n` (wrapper clamps to 120000ms). The response carries `timeout_ms_used`; `browser.runner-timeout` fires at the cap -- read `stderr`, narrow or raise, never retry blind at the same budget.
 
 **`capture\n<expression>` is the zero-boilerplate debug path -- prefer it.** Prefix your script with `capture` (or `profile`) on its own line and the wrapper auto-attaches `page.on('console'|'pageerror'|'requestfinished')` before your code runs, runs your script in an async wrapper (your top-level `await`/`return` work unchanged), and returns `{result: <your return>, debug: {console, pageErrors, network, performance}}` -- page console logs, uncaught errors, per-request network timing, and navigation performance, captured for free. Combine with timeout via `timeout=<ms>\ncapture\n<expr>`. Use the bare expression only when you do not want the capture overhead.
 
+**`profile\n<expression>` is the bottom-up CPU profiler -- worst-20 culprits by file location across init and code-execution.** Prefix your script with `profile` on its own line: the wrapper opens a CDP `Profiler` (`newCDPSession` + `Profiler.start` BEFORE the prepended `page.goto`, so navigation, script-parse, and init are sampled, not only steady-state), runs your script, `Profiler.stop`s, and aggregates the v8 CPU profile into `{result, profile: {timeframe: {start_us, end_us, total_us, sample_count}, culprits: [{location, function, self_us, self_pct, hits}]}, profile_error, debug: {...}}`. `culprits` is the bottom-up self-time ranking capped at the worst 20 `url:line` locations; `timeframe` is the capture window in microseconds. Composes with `url=`/`timeout=` in the same prefix order. Page scripts loaded from `.js` files carry real `file:line`; `page.evaluate` anonymous frames bucket to `(program)`/`(native)`. On a CDP failure `profile` is `null` with `profile_error` set and your `result` still returns. The identical `{timeframe, culprits}` shape comes back from `exec_js` with `opts.profile:true`, so the cli and browser bottom-up views read the same.
+
 ## Envelope
 
 `{ok, stdout, stderr, exit_code, session_id?}`. `stdout` = stringified eval result; `stderr` = page errors + launch diagnostics; `exit_code` non-zero = the dispatch did not land -- read `stderr` and re-dispatch, never blind.

package/gm-plugkit/instructions/execute.md

@@ -36,7 +36,7 @@ First emit = closure of the transform; scaffold + IOU externalizes residual cost
 
 Data first -- get the structures and their invariants right and the code writes itself; convoluted control flow means the data model is wrong, so fix the model. Make invalid state unrepresentable -- pass parameters over hidden globals, encode the constraint in the type/shape so the bad combination cannot be constructed. Reason from physical constraints (latency, bandwidth, memory, coordination, the worst node) before designing within them. Keep the spine flat, each unit single-focus and understandable at its call site. Make misuse structurally impossible, not documented-against. Optimize the worst case, not the average; design every failure path explicitly (full -> degraded -> safe-fail -> explicit-error), never a silent catastrophic mode. Measure, do not assume -- profile before optimizing, implement both and compare on real input when in genuine dispute. When a change regresses something that worked, revert first and investigate second: restore green, then diagnose from a known-good base. Fail fast and loud over limping on bad state.
 
-**Process of elimination is the debugging paradigm on every surface, and manual labour against real services is how you witness.** Never guess-and-restart, a/b-test, or shotgun variants: enumerate the candidate causes as mutables, then eliminate each by a witness read against REAL input -- `exec_js` against the real service, `codesearch`/`Read` against the real source, the `browser` verb's `page.evaluate` against a `window.*` global on the live page. Each elimination reveals the next mutable; record it and keep going until one cause survives every other's refutation. Reading the live runtime once observes more than a hundred blind restarts. Profile on the real surface, not from intuition: wrap the suspect node and read the live numbers. In node, `exec_js` carries `duration_ms` for free, surfaces your own timing and `process.memoryUsage()` on stdout, and lands the thrown-error `stack` on stderr -- read both channels (numbers on stdout, stack on stderr). In the browser, a body prefixed `capture\n<script>` auto-returns `{result, debug:{console, pageErrors, network, performance}}` with zero boilerplate. Profile to LOCATE the slow/broken node, then eliminate hypotheses by live measurement. Verification is the same labour: run the real thing and witness the real output (the single mock-free `test.js`, the live page, the real service), never an automated unit/mock harness standing in for the real-services witness. Apparent tooling failure is part of this -- it is your mechanical self-recovery by elimination, never a question for the user.
+**Process of elimination is the debugging paradigm on every surface, and manual labour against real services is how you witness.** Never guess-and-restart, a/b-test, or shotgun variants: enumerate the candidate causes as mutables, then eliminate each by a witness read against REAL input -- `exec_js` against the real service, `codesearch`/`Read` against the real source, the `browser` verb's `page.evaluate` against a `window.*` global on the live page. Each elimination reveals the next mutable; record it and keep going until one cause survives every other's refutation. Reading the live runtime once observes more than a hundred blind restarts. Profile on the real surface, not from intuition: wrap the suspect node and read the live numbers. In node, `exec_js` carries `duration_ms` for free, surfaces your own timing and `process.memoryUsage()` on stdout, and lands the thrown-error `stack` on stderr -- read both channels (numbers on stdout, stack on stderr). In the browser, a body prefixed `capture\n<script>` auto-returns `{result, debug:{console, pageErrors, network, performance}}` with zero boilerplate. When the slow node is not obvious, sample it bottom-up: `exec_js` with `opts.profile:true` and the browser `profile\n<script>` prefix both return `{result, profile:{timeframe:{start_us,end_us,total_us,sample_count}, culprits:[{location,function,self_us,self_pct,hits}]}}` -- the worst-20 `file:line` by self-time across init and code-execution, identical shape on both surfaces, so the culprit ranking points straight at the line to fix. Profile to LOCATE the slow/broken node, then eliminate hypotheses by live measurement. Verification is the same labour: run the real thing and witness the real output (the single mock-free `test.js`, the live page, the real service), never an automated unit/mock harness standing in for the real-services witness. Apparent tooling failure is part of this -- it is your mechanical self-recovery by elimination, never a question for the user.
 
 ## Memorize
 

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1615",
+  "version": "2.0.1617",
   "description": "Bootstrap and daemon-spawn tool for gm plugkit binary. Downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Includes plugkit-wasm-wrapper for WASM-based spool watching.",
   "main": "index.js",
   "bin": {

package/gm-plugkit/plugkit-wasm-wrapper.js

@@ -621,6 +621,56 @@ function writeJsonFile(fp, value) {
   try { atomicWriteJson(fp, value); } catch (_) {}
 }
 
+const AGGREGATE_CPU_PROFILE_SRC = `function aggregateCpuProfile(profile, topN) {
+  const N = topN || 20;
+  if (!profile || !Array.isArray(profile.nodes) || !Array.isArray(profile.samples)) {
+    return { timeframe: null, culprits: [] };
+  }
+  const byId = new Map();
+  for (const node of profile.nodes) byId.set(node.id, node);
+  const deltas = Array.isArray(profile.timeDeltas) ? profile.timeDeltas : [];
+  const acc = new Map();
+  let total = 0;
+  const sampleCount = profile.samples.length;
+  for (let i = 0; i < profile.samples.length; i++) {
+    const node = byId.get(profile.samples[i]);
+    const dt = deltas[i] || 0;
+    total += dt;
+    if (!node) continue;
+    const cf = node.callFrame || {};
+    let url = cf.url || '';
+    if (!url) url = cf.functionName ? '(native)' : '(program)';
+    const line = (typeof cf.lineNumber === 'number' && cf.lineNumber >= 0) ? cf.lineNumber + 1 : 0;
+    const loc = url + ':' + line;
+    let e = acc.get(loc);
+    if (!e) { e = { location: loc, function: cf.functionName || '(anonymous)', self_us: 0, hits: 0 }; acc.set(loc, e); }
+    e.self_us += dt;
+    e.hits += 1;
+  }
+  const culprits = Array.from(acc.values())
+    .sort((a, b) => b.self_us - a.self_us)
+    .slice(0, N)
+    .map(c => ({ location: c.location, function: c.function, self_us: c.self_us, self_pct: total ? Math.round((c.self_us / total) * 1000) / 10 : 0, hits: c.hits }));
+  return {
+    timeframe: {
+      start_us: typeof profile.startTime === 'number' ? profile.startTime : 0,
+      end_us: typeof profile.endTime === 'number' ? profile.endTime : 0,
+      total_us: total,
+      sample_count: sampleCount,
+    },
+    culprits,
+  };
+}`;
+
+let execProfileSeq = 0;
+let _aggregateCpuProfileFn = null;
+function aggregateCpuProfile(profile, topN) {
+  if (!_aggregateCpuProfileFn) {
+    _aggregateCpuProfileFn = new Function(AGGREGATE_CPU_PROFILE_SRC + '\nreturn aggregateCpuProfile;')();
+  }
+  return _aggregateCpuProfileFn(profile, topN);
+}
+
 const BROWSER_RUNNER_BIN = process.env.GM_BROWSER_RUNNER_BIN || 'playwriter';
 
 function findBrowserRunner() {
@@ -1870,14 +1920,62 @@ function makeHostFunctions(instanceRef) {
           });
         }
         const timeoutMs = rawTimeout;
+        const wantProfile = opts.profile === true && (lang === 'nodejs' || lang === 'js' || lang === undefined);
+        let profileUserFile = null;
         let cmd, args;
-        if (lang === 'nodejs' || lang === 'js') { cmd = process.execPath; args = ['-e', code]; }
+        if (lang === 'nodejs' || lang === 'js') {
+          if (wantProfile) {
+            profileUserFile = path.join(os.tmpdir(), `gm-prof-${process.pid}-${execProfileSeq++}.js`);
+            fs.writeFileSync(profileUserFile, `module.exports = (async () => {\n${code}\n});`, 'utf-8');
+            const runnerCode = `${AGGREGATE_CPU_PROFILE_SRC}\n`
+              + `const __inspector = require('inspector');\n`
+              + `const __session = new __inspector.Session();\n`
+              + `__session.connect();\n`
+              + `const __post = (m, p) => new Promise((res, rej) => __session.post(m, p || {}, (e, r) => e ? rej(e) : res(r)));\n`
+              + `(async () => {\n`
+              + `  let __profile = null, __profileError = null, __userResult = null, __userError = null;\n`
+              + `  try {\n`
+              + `    await __post('Profiler.enable');\n`
+              + `    await __post('Profiler.setSamplingInterval', { interval: ${Number.isFinite(opts.sampleIntervalUs) && opts.sampleIntervalUs > 0 ? Math.floor(opts.sampleIntervalUs) : 100} });\n`
+              + `    await __post('Profiler.start');\n`
+              + `    try { __userResult = await require(${JSON.stringify(profileUserFile)})(); } catch (ue) { __userError = String(ue && ue.stack || ue); }\n`
+              + `    const __r = await __post('Profiler.stop');\n`
+              + `    __profile = __r && __r.profile || null;\n`
+              + `  } catch (pe) { __profileError = String(pe && pe.message || pe); }\n`
+              + `  const __agg = __profile ? aggregateCpuProfile(__profile) : { timeframe: null, culprits: [] };\n`
+              + `  process.stdout.write('__GM_PROFILE__' + JSON.stringify({ result: __userResult, user_error: __userError, profile: __agg, profile_error: __profileError }));\n`
+              + `  __session.disconnect();\n`
+              + `})();\n`;
+            cmd = process.execPath; args = ['-e', runnerCode];
+          } else {
+            cmd = process.execPath; args = ['-e', code];
+          }
+        }
         else if (lang === 'python') { cmd = 'python'; args = ['-c', code]; }
         else if (lang === 'bash') { cmd = 'bash'; args = ['-c', code]; }
         else if (lang === 'deno') { cmd = 'deno'; args = ['eval', code]; }
         else { return writeWasmJson(instanceRef.value, { ok: false, error: `unsupported lang: ${lang}` }); }
         const __execT0 = Date.now();
         const result = spawnSync(cmd, args, { encoding: 'utf-8', timeout: timeoutMs, cwd, env: process.env });
+        if (profileUserFile) { try { fs.unlinkSync(profileUserFile); } catch (_) {} }
+        if (wantProfile) {
+          const raw = result.stdout || '';
+          const idx = raw.indexOf('__GM_PROFILE__');
+          let parsed = null;
+          if (idx >= 0) { try { parsed = JSON.parse(raw.slice(idx + '__GM_PROFILE__'.length)); } catch (_) {} }
+          return writeWasmJson(instanceRef.value, {
+            ok: result.status === 0 && parsed !== null && !parsed.user_error,
+            stdout: idx >= 0 ? raw.slice(0, idx) : raw,
+            stderr: result.stderr || '',
+            exit_code: result.status === null ? -1 : result.status,
+            timed_out: result.signal === 'SIGTERM',
+            duration_ms: Date.now() - __execT0,
+            result: parsed ? parsed.result : null,
+            profile: parsed ? parsed.profile : { timeframe: null, culprits: [] },
+            profile_error: parsed ? parsed.profile_error : 'profile sentinel not found in stdout',
+            user_error: parsed ? parsed.user_error : null,
+          });
+        }
         return writeWasmJson(instanceRef.value, {
           ok: result.status === 0,
           stdout: result.stdout || '',
@@ -2000,16 +2098,49 @@ function makeHostFunctions(instanceRef) {
             evalBody = timeoutMatch[2];
           }
         }
-        const captureMatch = evalBody.match(/^(?:capture|profile)[ \t]*\n([\s\S]*)$/);
-        if (captureMatch) {
-          const userScript = captureMatch[1];
-          evalBody = `const __logs=[],__errs=[],__net=[];\n`
-            + `try{page.on('console',m=>{try{__logs.push({type:m.type(),text:m.text()});}catch(_){}});`
-            + `page.on('pageerror',e=>{try{__errs.push(String(e&&e.message||e));}catch(_){}});`
-            + `page.on('requestfinished',r=>{try{const t=r.timing();__net.push({url:String(r.url()).slice(0,120),dur_ms:Math.round(t.responseEnd),ttfb_ms:Math.round(t.responseStart)});}catch(_){}});}catch(_){}\n`
-            + `const __result = await (async () => {\n${userScript}\n})();\n`
-            + `let __perf=null;try{__perf=await page.evaluate(()=>{const n=performance.getEntriesByType('navigation')[0];return n?{load_ms:Math.round(n.loadEventEnd||0),dcl_ms:Math.round(n.domContentLoadedEventEnd||0),resources:performance.getEntriesByType('resource').length,now:Math.round(performance.now())}:null;});}catch(_){}\n`
+        let startUrl = null;
+        const urlMatch = evalBody.match(/^url=(\S+)[ \t]*\n([\s\S]*)$/);
+        if (urlMatch) {
+          startUrl = urlMatch[1];
+          evalBody = urlMatch[2];
+        } else {
+          const bare = evalBody.trim();
+          if (/^https?:\/\/\S+$/.test(bare)) {
+            startUrl = bare;
+            evalBody = 'return {url: page.url(), title: await page.title()};';
+          }
+        }
+        const navTimeout = Math.min(timeoutMs, 60000);
+        const gotoPrefix = startUrl
+          ? `await page.goto(${JSON.stringify(startUrl)},{waitUntil:'load',timeout:${navTimeout}});\n`
+          : '';
+        const modeMatch = evalBody.match(/^(capture|profile)[ \t]*\n([\s\S]*)$/);
+        const debugSetup = `const __logs=[],__errs=[],__net=[];\n`
+          + `try{page.on('console',m=>{try{__logs.push({type:m.type(),text:m.text()});}catch(_){}});`
+          + `page.on('pageerror',e=>{try{__errs.push(String(e&&e.message||e));}catch(_){}});`
+          + `page.on('requestfinished',r=>{try{const t=r.timing();__net.push({url:String(r.url()).slice(0,120),dur_ms:Math.round(t.responseEnd),ttfb_ms:Math.round(t.responseStart)});}catch(_){}});}catch(_){}\n`;
+        const perfRead = `let __perf=null;try{__perf=await page.evaluate(()=>{const n=performance.getEntriesByType('navigation')[0];return n?{load_ms:Math.round(n.loadEventEnd||0),dcl_ms:Math.round(n.domContentLoadedEventEnd||0),resources:performance.getEntriesByType('resource').length,now:Math.round(performance.now())}:null;});}catch(_){}\n`;
+        if (modeMatch && modeMatch[1] === 'profile') {
+          const userScript = modeMatch[2];
+          const intervalUs = 100;
+          evalBody = debugSetup
+            + `let __profile=null,__profileError=null;\n`
+            + `let __cdp=null;\n`
+            + `try{__cdp=await page.context().newCDPSession(page);await __cdp.send('Profiler.enable');await __cdp.send('Profiler.setSamplingInterval',{interval:${intervalUs}});await __cdp.send('Profiler.start');}catch(e){__profileError=String(e&&e.message||e);__cdp=null;}\n`
+            + `const __result = await (async () => {\n${gotoPrefix}${userScript}\n})();\n`
+            + `if(__cdp){try{const __r=await __cdp.send('Profiler.stop');__profile=__r&&__r.profile||null;}catch(e){__profileError=String(e&&e.message||e);}}\n`
+            + perfRead
+            + AGGREGATE_CPU_PROFILE_SRC + `\n`
+            + `const __agg = __profile ? aggregateCpuProfile(__profile) : {timeframe:null,culprits:[]};\n`
+            + `return {result:__result,profile:__agg,profile_error:__profileError,debug:{console:__logs,pageErrors:__errs,network:__net.slice(0,30),performance:__perf}};`;
+        } else if (modeMatch && modeMatch[1] === 'capture') {
+          const userScript = modeMatch[2];
+          evalBody = debugSetup
+            + `const __result = await (async () => {\n${gotoPrefix}${userScript}\n})();\n`
+            + perfRead
             + `return {result:__result,debug:{console:__logs,pageErrors:__errs,network:__net.slice(0,30),performance:__perf}};`;
+        } else if (startUrl) {
+          evalBody = `${gotoPrefix}${evalBody}`;
         }
         const outerTimeoutMs = Math.min(timeoutMs + 6000, 126000);
         const r = runBrowserRunner(pw, ['-s', pwSessionId, '--timeout', String(timeoutMs), '-e', evalBody], outerTimeoutMs, cwd, sessionId);

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1615",
+  "version": "2.0.1617",
   "description": "Spool-dispatch orchestration engine with unified state machine, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1615",
+  "version": "2.0.1617",
   "description": "Canonical universal harness — AI-native software engineering via skill-driven orchestration; bootstraps plugkit for task execution and session isolation. Install in any AI coding agent host.",
   "author": "AnEntrypoint",
   "license": "MIT",