@ramarivera/coding-agent-langfuse 0.1.29 → 0.1.30

package/README.md

@@ -34,3 +34,50 @@ npx @ramarivera/coding-agent-langfuse@latest \
 
 The importer is fail-fast: the first failed OTLP POST stops the run, prints the
 real network cause, and preserves local state so reruns resume cleanly.
+
+## Follow as a host service
+
+Install a live follower directly from npm. The generated service keeps inference
+outside any gateway: agents keep calling their normal providers, while this tool
+tails local histories and posts Langfuse OTLP traces.
+
+Preview the service without touching the host:
+
+```sh
+npx @ramarivera/coding-agent-langfuse@latest service print \
+  --platform linux \
+  --agents codex,pi \
+  --endpoint https://langfuse.ai.roxasroot.net/otel/v1/traces
+```
+
+Install and start it on the current host:
+
+```sh
+npx @ramarivera/coding-agent-langfuse@latest service install \
+  --agents codex,pi \
+  --endpoint https://langfuse.ai.roxasroot.net/otel/v1/traces
+```
+
+The service installer supports:
+
+- macOS: LaunchAgent under `~/Library/LaunchAgents`
+- Linux: systemd user unit under `~/.config/systemd/user`
+- Windows: scheduled task installer script under `%APPDATA%\\coding-agent-langfuse`
+
+Use `--dry-run` to print the exact file and commands, `--no-start` to only write
+the service file, and `service uninstall` to remove the service registration.
+
+## Backfill windows
+
+Backfill only a timeframe when repairing a host or replaying a recent window:
+
+```sh
+npx @ramarivera/coding-agent-langfuse@latest \
+  --agents claude,codex,grok,pi,opencode \
+  --since 2026-05-31T00:00:00Z \
+  --until 2026-06-01T00:00:00Z \
+  --endpoint https://langfuse.ai.roxasroot.net/otel/v1/traces
+```
+
+Deduplication is state-file based and keyed by agent, session id, and source
+record id. Reuse the same `--state` path for repeat repairs on a host.

package/bin/coding-agent-langfuse.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const moduleUrl = new URL("../dist/backfill.js", import.meta.url);
+const moduleUrl = new URL("../dist/cli.js", import.meta.url);
 const { main } = await import(moduleUrl.href);
 
 await main(process.argv.slice(2));

package/dist/backfill.d.ts

@@ -60,6 +60,8 @@ type FollowSummary = RunSummary & {
     iterations: number;
     follow: true;
 };
+declare const allAgents: AgentName[];
+declare const defaultEndpoint = "https://langfuse.ai.roxasroot.net/otel/v1/traces";
 declare function parseArgs(argv: string[]): BackfillOptions;
 declare function codexEvents(homeDir: string): BackfillEvent[];
 declare function claudeEvents(homeDir: string): BackfillEvent[];
@@ -78,4 +80,4 @@ declare function discoverEvents(options: BackfillOptions): BackfillEvent[];
 declare function run(options: BackfillOptions): Promise<RunSummary>;
 declare function follow(options: BackfillOptions): Promise<FollowSummary>;
 declare function main(argv?: string[]): Promise<RunSummary | FollowSummary>;
-export { type BackfillEvent, type BackfillOptions, claudeEvents, codexEvents, discoverEvents, fingerprint, follow, grokEvents, main, opencodeEvents, parseArgs, piEvents, run, toOtlp, };
+export { type BackfillEvent, type BackfillOptions, type AgentName, allAgents, claudeEvents, codexEvents, defaultEndpoint, discoverEvents, fingerprint, follow, grokEvents, main, opencodeEvents, parseArgs, piEvents, run, toOtlp, };

package/dist/backfill.js

@@ -1593,4 +1593,4 @@ if (import.meta.url === `file://${process.argv[1]}`) {
         process.exit(1);
     }
 }
-export { claudeEvents, codexEvents, discoverEvents, fingerprint, follow, grokEvents, main, opencodeEvents, parseArgs, piEvents, run, toOtlp, };
+export { allAgents, claudeEvents, codexEvents, defaultEndpoint, discoverEvents, fingerprint, follow, grokEvents, main, opencodeEvents, parseArgs, piEvents, run, toOtlp, };

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+declare function main(argv?: string[]): Promise<void>;
+export { main };

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { main as backfillMain } from "./backfill.js";
+import { serviceMain } from "./service.js";
+async function main(argv = process.argv.slice(2)) {
+    if (argv[0] === "service") {
+        await serviceMain(argv.slice(1));
+        return;
+    }
+    await backfillMain(argv);
+}
+await main();
+export { main };

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { codexEvents, discoverEvents, fingerprint, parseArgs, piEvents, run, toOtlp, } from "./backfill.js";
+export { buildServicePlan, parseServiceArgs, serviceMain, } from "./service.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { codexEvents, discoverEvents, fingerprint, parseArgs, piEvents, run, toOtlp, } from "./backfill.js";
+export { buildServicePlan, parseServiceArgs, serviceMain, } from "./service.js";

package/dist/service.d.ts

@@ -0,0 +1,35 @@
+type AgentName = "claude" | "codex" | "grok" | "opencode" | "pi";
+type ServicePlatform = "darwin" | "linux" | "win32";
+type ServiceAction = "install" | "uninstall" | "print";
+type ServiceOptions = {
+    action: ServiceAction;
+    platform: ServicePlatform;
+    agents: AgentName[];
+    endpoint: string;
+    statePath: string;
+    homeDir: string;
+    name: string;
+    packageSpec: string;
+    batchSize: number;
+    pollIntervalMs: number;
+    postDelayMs: number;
+    since?: string;
+    dryRun: boolean;
+    start: boolean;
+    workingDirectory: string;
+    pathEnv: string;
+};
+type ServicePlan = {
+    platform: ServicePlatform;
+    action: ServiceAction;
+    name: string;
+    path: string;
+    content?: string;
+    command: string[];
+    postInstallCommands: string[][];
+    uninstallCommands: string[][];
+};
+declare function parseServiceArgs(argv: string[]): ServiceOptions;
+declare function buildServicePlan(options: ServiceOptions): ServicePlan;
+declare function serviceMain(argv?: string[]): Promise<ServicePlan>;
+export { type ServiceOptions, type ServicePlan, buildServicePlan, parseServiceArgs, serviceMain, };

package/dist/service.js

@@ -0,0 +1,422 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir, platform as osPlatform } from "node:os";
+import { dirname, join } from "node:path";
+const defaultPackageSpec = "@ramarivera/coding-agent-langfuse@latest";
+const defaultEndpoint = "https://langfuse.ai.roxasroot.net/otel/v1/traces";
+const allAgents = ["claude", "codex", "grok", "opencode", "pi"];
+function serviceUsage() {
+    return `Usage:
+  coding-agent-langfuse service install [options]
+  coding-agent-langfuse service print [options]
+  coding-agent-langfuse service uninstall [options]
+
+Service options:
+  --platform NAME         Target platform: darwin, linux, win32 (default: current)
+  --name NAME             Service name/label/unit name
+  --agents LIST           Comma-separated agents: claude,codex,grok,opencode,pi
+  --endpoint URL          OTLP HTTP traces endpoint (default: ${defaultEndpoint})
+  --state PATH            Dedupe state file
+  --home PATH             Home directory to scan (default: current user home)
+  --package-spec SPEC     npx package spec (default: ${defaultPackageSpec})
+  --batch-size N          OTLP spans per POST (default: 10)
+  --poll-interval-ms N    Delay between --follow scans (default: 5000)
+  --post-delay-ms N       Delay after each successful OTLP POST (default: 0)
+  --since ISO_OR_MS       Optional lower bound for events the follower may send
+  --working-directory DIR Directory the service starts in (default: --home)
+  --path VALUE            PATH value injected into the service environment
+  --dry-run               Print the service plan without writing or running commands
+  --no-start              Write the service but do not enable/start it
+  --help                  Show this help
+`;
+}
+function parseServiceArgs(argv) {
+    const action = parseServiceAction(argv[0]);
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(serviceUsage());
+        process.exit(0);
+    }
+    let platform = currentServicePlatform();
+    let agents = [...allAgents];
+    let endpoint = process.env.LANGFUSE_BACKFILL_ENDPOINT ?? defaultEndpoint;
+    let homeDir = process.env.HOME ?? homedir();
+    let statePath = "";
+    let name = "";
+    let packageSpec = defaultPackageSpec;
+    let batchSize = 10;
+    let pollIntervalMs = 5_000;
+    let postDelayMs = 0;
+    let since;
+    let dryRun = false;
+    let start = true;
+    let workingDirectory = "";
+    let pathEnv = "";
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = () => {
+            const value = argv[++i];
+            if (!value)
+                throw new Error(`Missing value for ${arg}`);
+            return value;
+        };
+        if (arg === "--platform") {
+            platform = parsePlatform(next());
+        }
+        else if (arg === "--name") {
+            name = next();
+        }
+        else if (arg === "--agents") {
+            agents = parseAgents(next());
+        }
+        else if (arg === "--endpoint") {
+            endpoint = next();
+        }
+        else if (arg === "--state") {
+            statePath = next();
+        }
+        else if (arg === "--home") {
+            homeDir = next();
+        }
+        else if (arg === "--package-spec") {
+            packageSpec = next();
+        }
+        else if (arg === "--batch-size") {
+            batchSize = parsePositiveInt(arg, next());
+        }
+        else if (arg === "--poll-interval-ms") {
+            pollIntervalMs = parsePositiveInt(arg, next());
+        }
+        else if (arg === "--post-delay-ms") {
+            postDelayMs = parseNonNegativeInt(arg, next());
+        }
+        else if (arg === "--since") {
+            since = next();
+        }
+        else if (arg === "--working-directory") {
+            workingDirectory = next();
+        }
+        else if (arg === "--path") {
+            pathEnv = next();
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--no-start") {
+            start = false;
+        }
+        else {
+            throw new Error(`Unknown service argument '${arg}'`);
+        }
+    }
+    if (agents.length === 0)
+        throw new Error("--agents must include at least one agent");
+    name ||= defaultServiceName(agents, platform);
+    workingDirectory ||= homeDir;
+    pathEnv ||= defaultPathEnv(homeDir, platform);
+    statePath ||= join(homeDir, ".local/state/coding-agent-langfuse", `${name}.json`);
+    return {
+        action,
+        platform,
+        agents,
+        endpoint,
+        statePath,
+        homeDir,
+        name,
+        packageSpec,
+        batchSize,
+        pollIntervalMs,
+        postDelayMs,
+        since,
+        dryRun,
+        start,
+        workingDirectory,
+        pathEnv,
+    };
+}
+function buildServicePlan(options) {
+    const command = buildFollowCommand(options);
+    if (options.platform === "darwin") {
+        const path = join(options.homeDir, "Library/LaunchAgents", `${options.name}.plist`);
+        return {
+            platform: options.platform,
+            action: options.action,
+            name: options.name,
+            path,
+            content: renderLaunchdPlist(options, command),
+            command,
+            postInstallCommands: options.start
+                ? [
+                    ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? 501}`, path],
+                    ["launchctl", "kickstart", "-k", `gui/${process.getuid?.() ?? 501}/${options.name}`],
+                ]
+                : [],
+            uninstallCommands: [
+                ["launchctl", "bootout", `gui/${process.getuid?.() ?? 501}`, path],
+            ],
+        };
+    }
+    if (options.platform === "linux") {
+        const path = join(options.homeDir, ".config/systemd/user", `${options.name}.service`);
+        return {
+            platform: options.platform,
+            action: options.action,
+            name: options.name,
+            path,
+            content: renderSystemdUnit(options, command),
+            command,
+            postInstallCommands: options.start
+                ? [
+                    ["systemctl", "--user", "daemon-reload"],
+                    ["systemctl", "--user", "enable", "--now", `${options.name}.service`],
+                ]
+                : [["systemctl", "--user", "daemon-reload"]],
+            uninstallCommands: [
+                ["systemctl", "--user", "disable", "--now", `${options.name}.service`],
+                ["systemctl", "--user", "daemon-reload"],
+            ],
+        };
+    }
+    const path = join(process.env.APPDATA ?? join(options.homeDir, "AppData/Roaming"), "coding-agent-langfuse", `${options.name}.ps1`);
+    const taskName = `CodingAgentLangfuse-${options.name}`;
+    return {
+        platform: options.platform,
+        action: options.action,
+        name: options.name,
+        path,
+        content: renderWindowsScript(command),
+        command,
+        postInstallCommands: options.start
+            ? [
+                [
+                    "powershell.exe",
+                    "-NoProfile",
+                    "-ExecutionPolicy",
+                    "Bypass",
+                    "-File",
+                    path,
+                    "-Install",
+                    "-TaskName",
+                    taskName,
+                ],
+            ]
+            : [],
+        uninstallCommands: [
+            [
+                "powershell.exe",
+                "-NoProfile",
+                "-Command",
+                `Unregister-ScheduledTask -TaskName ${powershellString(taskName)} -Confirm:$false -ErrorAction SilentlyContinue`,
+            ],
+        ],
+    };
+}
+async function serviceMain(argv = process.argv.slice(2)) {
+    const options = parseServiceArgs(argv);
+    const plan = buildServicePlan(options);
+    if (options.action === "print" || options.dryRun) {
+        console.log(JSON.stringify(plan, null, 2));
+        return plan;
+    }
+    if (options.action === "install") {
+        if (!plan.content)
+            throw new Error("Service plan is missing content");
+        mkdirSync(dirname(plan.path), { recursive: true });
+        writeFileSync(plan.path, plan.content);
+        runCommands(plan.postInstallCommands);
+        console.log(JSON.stringify(plan, null, 2));
+        return plan;
+    }
+    runCommands(plan.uninstallCommands, { ignoreFailure: true });
+    if (existsSync(plan.path))
+        rmSync(plan.path);
+    console.log(JSON.stringify(plan, null, 2));
+    return plan;
+}
+function buildFollowCommand(options) {
+    const command = [
+        options.platform === "win32" ? "npx.cmd" : "npx",
+        "--yes",
+        options.packageSpec,
+        "--agents",
+        options.agents.join(","),
+        "--endpoint",
+        options.endpoint,
+        "--state",
+        options.statePath,
+        "--home",
+        options.homeDir,
+        "--batch-size",
+        String(options.batchSize),
+        "--poll-interval-ms",
+        String(options.pollIntervalMs),
+        "--post-delay-ms",
+        String(options.postDelayMs),
+        "--follow",
+    ];
+    if (options.since)
+        command.push("--since", options.since);
+    return command;
+}
+function renderSystemdUnit(options, command) {
+    return `[Unit]
+Description=Coding Agent Langfuse follower (${options.agents.join(",")})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${systemdCommand(command)}
+Restart=always
+RestartSec=15
+StartLimitIntervalSec=60
+StartLimitBurst=10
+WorkingDirectory=${systemdQuote(options.workingDirectory)}
+Environment=${systemdQuote(`PATH=${options.pathEnv}`)}
+Environment=LANGFUSE_BACKFILL_ENDPOINT=${options.endpoint}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function renderLaunchdPlist(options, command) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(options.name)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${command.map((part) => `    <string>${escapeXml(part)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(options.pathEnv)}</string>
+    <key>LANGFUSE_BACKFILL_ENDPOINT</key>
+    <string>${escapeXml(options.endpoint)}</string>
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(options.workingDirectory)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(join(options.homeDir, "Library/Logs", `${options.name}.out.log`))}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(join(options.homeDir, "Library/Logs", `${options.name}.err.log`))}</string>
+</dict>
+</plist>
+`;
+}
+function renderWindowsScript(command) {
+    const commandArray = command.map(powershellString).join(", ");
+    return `param(
+  [switch]$Install,
+  [string]$TaskName = "CodingAgentLangfuse"
+)
+
+$Command = @(${commandArray})
+$Action = New-ScheduledTaskAction -Execute $Command[0] -Argument (($Command | Select-Object -Skip 1) -join " ")
+$Trigger = New-ScheduledTaskTrigger -AtLogOn
+$Settings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1)
+
+if ($Install) {
+  Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $Trigger -Settings $Settings -Force | Out-Null
+  Start-ScheduledTask -TaskName $TaskName
+}
+`;
+}
+function parseServiceAction(value) {
+    if (value === "install" || value === "uninstall" || value === "print")
+        return value;
+    throw new Error(`Expected service action install, uninstall, or print; got '${value ?? ""}'`);
+}
+function parsePlatform(value) {
+    if (value === "darwin" || value === "linux" || value === "win32")
+        return value;
+    throw new Error(`Unsupported platform '${value}'`);
+}
+function currentServicePlatform() {
+    return parsePlatform(osPlatform());
+}
+function parseAgents(value) {
+    return value.split(",").map((item) => {
+        const agent = item.trim();
+        if (!allAgents.includes(agent))
+            throw new Error(`Unknown agent '${item}'`);
+        return agent;
+    });
+}
+function defaultServiceName(agents, platform) {
+    const suffix = agents.join("-");
+    return platform === "darwin"
+        ? `net.roxasroot.coding-agent-langfuse.${suffix}`
+        : `coding-agent-langfuse-${suffix}`;
+}
+function defaultPathEnv(homeDir, platform) {
+    if (platform === "win32") {
+        return [
+            "%APPDATA%\\npm",
+            "%ProgramFiles%\\nodejs",
+            "%SystemRoot%\\System32",
+            "%SystemRoot%",
+        ].join(";");
+    }
+    return [
+        join(homeDir, ".local/share/mise/shims"),
+        join(homeDir, ".local/bin"),
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+    ].join(":");
+}
+function parsePositiveInt(flag, value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`${flag} must be a positive integer`);
+    }
+    return parsed;
+}
+function parseNonNegativeInt(flag, value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${flag} must be a non-negative integer`);
+    }
+    return parsed;
+}
+function runCommands(commands, options = {}) {
+    for (const command of commands) {
+        try {
+            execFileSync(command[0], command.slice(1), { stdio: "inherit" });
+        }
+        catch (error) {
+            if (!options.ignoreFailure)
+                throw error;
+        }
+    }
+}
+function systemdCommand(command) {
+    return ["/usr/bin/env", ...command].map(systemdQuote).join(" ");
+}
+function systemdQuote(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value))
+        return value;
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function powershellString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+export { buildServicePlan, parseServiceArgs, serviceMain, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramarivera/coding-agent-langfuse",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Universal coding-agent Langfuse backfiller and live OTLP helpers",
   "type": "module",
   "license": "MIT",
@@ -11,7 +11,8 @@
   },
   "exports": {
     ".": "./dist/index.js",
-    "./backfill": "./dist/backfill.js"
+    "./backfill": "./dist/backfill.js",
+    "./service": "./dist/service.js"
   },
   "files": [
     "bin",
@@ -23,7 +24,7 @@
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc --noEmit",
     "test": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test test/**/*.test.ts",
-    "test:e2e": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test e2e/test/**/*.test.ts",
+    "test:e2e": "npm run build && node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test e2e/test/**/*.test.ts",
     "pack:dry-run": "npm pack --dry-run",
     "prepack": "npm run build"
   },