@klars/agentobs 0.1.2 → 0.1.4

package/dist/adapters/process-wrap.js

@@ -61,14 +61,20 @@ export async function runWrapped(command, opts = {}) {
         // Resolving the .cmd/.bat shim directly keeps npm-installed CLIs working
         // (`agentobs run -- claude`) while spawn still escapes each argument.
         const executable = process.platform === 'win32' ? resolveWindowsExecutable(command[0]) : command[0];
-        const child = spawn(executable, command.slice(1), {
-            cwd,
-            stdio: 'inherit',
-            // A .cmd shim is a batch script, so it does need a shell interpreter -
-            // but only for the shim itself, and cmd.exe applies its own escaping.
-            shell: /\.(cmd|bat)$/i.test(executable),
-            windowsHide: true,
-        });
+        // A .cmd/.bat file is a batch script: Windows cannot exec it directly, it
+        // must run through cmd.exe. Spawning cmd.exe explicitly with /d /s /c and
+        // a quoted command line is the only form that survives BOTH a path
+        // containing spaces (C:\Program Files\nodejs\npm.cmd) and arguments
+        // containing spaces. `shell: true` cannot do this - it concatenates
+        // without quoting (Node DEP0190), so the path breaks at the first space.
+        const isBatch = process.platform === 'win32' && /\.(cmd|bat)$/i.test(executable);
+        const child = isBatch
+            ? spawn(process.env.COMSPEC ?? 'cmd.exe', ['/d', '/s', '/c', `"${quoteWindows(executable, command.slice(1))}"`], { cwd, stdio: 'inherit', windowsHide: true, windowsVerbatimArguments: true })
+            : spawn(executable, command.slice(1), {
+                cwd,
+                stdio: 'inherit',
+                windowsHide: true,
+            });
         const finish = (code) => {
             sink({ type: 'session_end', sessionId, exitCode: code });
             resolve(code);
@@ -76,7 +82,19 @@ export async function runWrapped(command, opts = {}) {
         child.on('error', (err) => {
             // Spawn failure (command not found) - record it as a failed session
             // rather than losing the attempt entirely.
-            console.error(`[agentobs] failed to start ${command[0]}: ${err.message}`);
+            // A shell builtin (dir, echo, cd, type) is not a program on disk, so
+            // there is nothing to spawn. Saying only "ENOENT" sends the user
+            // hunting for a broken install; naming the actual cause and the
+            // workaround is the difference between a dead end and a fix.
+            if (process.platform === 'win32' && WINDOWS_BUILTINS.has(command[0].toLowerCase())) {
+                console.error(`[agentobs] "${command[0]}" is a cmd.exe builtin, not a program, so there is ` +
+                    `nothing to wrap.\n` +
+                    `           Try:  agentobs run -- cmd /c ${command.join(' ')}`);
+            }
+            else {
+                console.error(`[agentobs] failed to start ${command[0]}: ${err.message}\n` +
+                    `           Check the command exists and is on your PATH.`);
+            }
             finish(127);
         });
         child.on('close', (code, signal) => {
@@ -99,6 +117,28 @@ export async function runWrapped(command, opts = {}) {
         }
     });
 }
+/**
+ * cmd.exe builtins - commands that exist only inside the shell, with no
+ * executable on disk. Spawning them always fails with ENOENT, so they get a
+ * message that explains why rather than one that looks like a broken install.
+ */
+const WINDOWS_BUILTINS = new Set([
+    'dir', 'echo', 'cd', 'chdir', 'type', 'copy', 'move', 'del', 'erase', 'md',
+    'mkdir', 'rd', 'rmdir', 'ren', 'rename', 'cls', 'set', 'ver', 'vol', 'path',
+    'pause', 'title', 'prompt', 'assoc', 'ftype', 'exit', 'call', 'start',
+]);
+/**
+ * Builds a cmd.exe command line, quoting each part that needs it.
+ *
+ * Used with windowsVerbatimArguments so Node passes this string through
+ * untouched; cmd.exe then does its own parsing. Each element is quoted only
+ * when it contains a space or a quote, because unnecessary quoting can change
+ * how some batch scripts interpret their arguments.
+ */
+function quoteWindows(executable, args) {
+    const quote = (s) => /[\s"]/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
+    return [quote(executable), ...args.map(quote)].join(' ');
+}
 /**
  * Finds the real file behind a bare command name on Windows.
  *
@@ -117,14 +157,23 @@ function resolveWindowsExecutable(command) {
     const exts = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
     const dirs = (process.env.PATH ?? '').split(';').filter(Boolean);
     for (const dir of dirs) {
-        for (const ext of ['', ...exts]) {
-            const candidate = join(dir, command + ext.toLowerCase());
-            if (existsSync(candidate))
-                return candidate;
+        // Try the PATHEXT extensions BEFORE the bare name. Node ships both `npm`
+        // (an extensionless shell script, for Git Bash) and `npm.cmd` in the same
+        // directory; the bare file exists but Windows cannot execute it, so
+        // checking it first resolves to something that fails with ENOENT.
+        for (const ext of exts) {
+            const lower = join(dir, command + ext.toLowerCase());
+            if (existsSync(lower))
+                return lower;
             const upper = join(dir, command + ext);
             if (existsSync(upper))
                 return upper;
         }
+        // Only fall back to the bare name if no extension matched - covers a real
+        // extensionless executable, which is rare on Windows but not impossible.
+        const bare = join(dir, command);
+        if (existsSync(bare))
+            return bare;
     }
     return command;
 }

package/dist/cli.js

@@ -48,6 +48,12 @@ export function buildProgram() {
         .command('watch')
         .argument('<file>', 'JSONL file to tail')
         .description('Ingest a newline-delimited JSON agent log')
+        .addHelpText('after', `
+Example:
+  agentobs watch ./agent-log.jsonl --agent my-agent
+
+The file should contain one JSON object per line with a "type" field
+(session_start, tool_call_start, tool_call_end, session_end).`)
         .option('--agent <name>', 'agent name to record', 'generic')
         .option('--no-follow', 'process existing lines then exit')
         .action(async (file, opts) => {
@@ -57,6 +63,14 @@ export function buildProgram() {
     program
         .command('run')
         .description('Run a command under observation (coarse: duration and exit code)')
+        .addHelpText('after', `
+Examples:
+  agentobs run -- npm test
+  agentobs run -- claude
+  agentobs run -- git status
+
+Note the "--": everything after it is the command to observe.
+On Windows, cmd.exe builtins (dir, echo, type) need: agentobs run -- cmd /c dir`)
         .argument('<command...>', 'command to run, after --')
         .option('--agent <name>', 'agent name to record')
         .allowUnknownOption()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klars/agentobs",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Observability and control layer for AI coding agents - see every tool call, token, and dollar your agents spend, and stop them before they do something risky.",
   "license": "MIT",
   "author": "Klars AI",