@klars/agentobs 0.1.3 → 0.1.4

package/dist/adapters/process-wrap.js

@@ -82,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) => {
@@ -105,6 +117,16 @@ 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.
  *

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.3",
+  "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",