@ramarivera/coding-agent-langfuse 0.1.46 → 0.1.47

package/README.md

@@ -51,6 +51,68 @@ 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.
 
+## Project tags and metadata
+
+Backfills and live followers can attach stable Langfuse dimensions based on the
+session cwd. Use this for client/workstream dashboards like ITSynch without
+guessing from host names or Windows paths in the Langfuse UI.
+
+There are two config layers:
+
+- Global host config: `~/.config/coding-agent-langfuse/path-tags.json`
+- Optional project-local overlay: `.langfuse-ca.json` in the project directory
+  or any parent of the session cwd
+
+Global config uses prefix rules:
+
+```json
+{
+  "rules": [
+    {
+      "pathPrefix": "/Users/ramarivera/dev/itsynch",
+      "tags": ["itsynch", "client:itsynch"],
+      "metadata": {
+        "project_group": "itsynch",
+        "project_owner": "ramiro"
+      },
+      "projectName": "itsynch",
+      "projectFolder": "itsynch"
+    }
+  ]
+}
+```
+
+Project-local config is intentionally smaller and overrides/extends the matched
+global rule:
+
+```json
+{
+  "tags": ["repo:portal"],
+  "metadata": {
+    "service": "portal"
+  },
+  "projectName": "itsynch-portal"
+}
+```
+
+Matched values are emitted on root trace metadata, observation metadata, and
+top-level OTLP attributes such as `project.tags`, `project.group`, and
+`project.owner`. The root span also sets `langfuse.trace.tags`, so Langfuse
+custom dashboards can filter/group by tags or metadata. Historical repair runs
+use the same OTLP builder as live follow mode, so rerunning with `--force` can
+backfill newly added tags for existing sessions.
+
+Use a non-default global config path with:
+
+```sh
+npx @ramarivera/coding-agent-langfuse@latest \
+  --path-tags-config "$HOME/.config/coding-agent-langfuse/path-tags.json"
+```
+
+Generated services pass `--path-tags-config` when provided to
+`service install`; otherwise the package reads the default global config path if
+it exists.
+
 ## Cost calculation
 
 Backfill cost calculation follows Langfuse's OpenTelemetry mapping: generation

package/dist/backfill.d.ts

@@ -50,6 +50,8 @@ type BackfillOptions = {
     maxFieldBytes: number;
     postDelayMs: number;
     costRates: CostCatalog;
+    pathTagsConfigPath?: string;
+    pathTagsConfig: PathTagsConfig;
 };
 type CostRates = {
     input?: number;
@@ -64,6 +66,25 @@ type CostCatalog = Record<string, CostRates>;
 type OtlpOptions = {
     maxFieldBytes?: number;
     costRates?: CostCatalog;
+    pathTagsConfig?: PathTagsConfig;
+};
+type PathTagRule = {
+    pathPrefix: string;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    projectName?: string;
+    projectFolder?: string;
+};
+type PathTagsConfig = {
+    rules: PathTagRule[];
+    project?: ProjectTagOverlay;
+};
+type ProjectTagOverlay = {
+    tags: string[];
+    metadata: Record<string, unknown>;
+    projectName?: string;
+    projectFolder?: string;
+    sourcePath?: string;
 };
 type RunSummary = {
     discovered: Record<string, number>;

package/dist/backfill.js

@@ -31,7 +31,10 @@ const deadRemoteEndpoint = "http://langfuse.ai.roxasroot.net:14318/v1/traces";
 const defaultMaxRequestBytes = 12 * 1024 * 1024;
 const defaultMaxFieldBytes = 512 * 1024;
 const defaultStatePath = join(homedir(), ".local/state/coding-agent-langfuse/backfill-v6.json");
+const defaultPathTagsConfigPath = join(homedir(), ".config/coding-agent-langfuse/path-tags.json");
 const currentHost = hostname();
+const projectLocalConfigFile = ".langfuse-ca.json";
+const projectLocalConfigCache = new Map();
 const kimiFirepassRates = {
     input: 2,
     output: 8,
@@ -192,6 +195,57 @@ function projectMetadata(cwd) {
         projectFolder: projectName,
     };
 }
+function matchPathTags(cwd, config) {
+    if (!cwd)
+        return { tags: [], metadata: {} };
+    const normalizedCwd = normalizeRulePath(cwd);
+    const matched = config.rules.filter((rule) => {
+        const prefix = normalizeRulePath(rule.pathPrefix);
+        return normalizedCwd === prefix || normalizedCwd.startsWith(`${prefix}/`);
+    });
+    const globalMatch = matched.reduce((acc, rule) => ({
+        tags: [...new Set([...acc.tags, ...rule.tags])],
+        metadata: { ...acc.metadata, ...rule.metadata },
+        projectName: rule.projectName ?? acc.projectName,
+        projectFolder: rule.projectFolder ?? acc.projectFolder,
+    }), {
+        tags: [],
+        metadata: {},
+        projectName: undefined,
+        projectFolder: undefined,
+    });
+    const overlays = [
+        globalMatch,
+        config.project,
+        loadProjectLocalOverlay(cwd),
+    ].filter((overlay) => overlay !== undefined);
+    return overlays.reduce((acc, overlay) => {
+        if (!overlay)
+            return acc;
+        return {
+            tags: [...new Set([...acc.tags, ...overlay.tags])],
+            metadata: { ...acc.metadata, ...overlay.metadata },
+            projectName: overlay.projectName ?? acc.projectName,
+            projectFolder: overlay.projectFolder ?? acc.projectFolder,
+        };
+    }, {
+        tags: [],
+        metadata: {},
+        projectName: undefined,
+        projectFolder: undefined,
+    });
+}
+function mergeProjectMetadata(cwd, config) {
+    const project = projectMetadata(cwd);
+    const pathTags = matchPathTags(cwd, config);
+    return {
+        ...project,
+        projectName: pathTags.projectName ?? project.projectName,
+        projectFolder: pathTags.projectFolder ?? project.projectFolder,
+        tags: pathTags.tags,
+        metadata: pathTags.metadata,
+    };
+}
 function usage() {
     return `Usage: coding-agent-langfuse-backfill [options]
 
@@ -211,6 +265,7 @@ Options:
   --post-delay-ms N       Delay after each successful OTLP POST (default: 0)
   --cost-rates PATH       JSON model cost-rate overrides in USD per 1M tokens
   --cost-rates-json JSON  Inline JSON model cost-rate overrides in USD per 1M tokens
+  --path-tags-config PATH JSON path-prefix rules that add Langfuse tags/metadata
   --follow                Keep scanning and sending newly written events
   --poll-interval-ms N    Delay between --follow scans (default: 5000)
   --idle-exit-after-ms N  Stop --follow after this much time without new sends
@@ -241,6 +296,9 @@ function parseArgs(argv) {
     if (!Number.isFinite(postDelayMs))
         postDelayMs = 0;
     let costRates = loadCostCatalogFromEnv();
+    let pathTagsConfigPath = process.env.CODING_AGENT_LANGFUSE_PATH_TAGS_CONFIG ??
+        process.env.LANGFUSE_BACKFILL_PATH_TAGS_CONFIG ??
+        defaultPathTagsConfigPath;
     let follow = false;
     let pollIntervalMs = 5_000;
     let idleExitAfterMs;
@@ -307,6 +365,9 @@ function parseArgs(argv) {
         else if (arg === "--cost-rates-json") {
             costRates = mergeCostCatalog(costRates, parseCostCatalogJson(next()));
         }
+        else if (arg === "--path-tags-config") {
+            pathTagsConfigPath = next();
+        }
         else if (arg === "--follow") {
             follow = true;
         }
@@ -378,8 +439,110 @@ function parseArgs(argv) {
         maxFieldBytes,
         postDelayMs,
         costRates,
+        pathTagsConfigPath,
+        pathTagsConfig: loadPathTagsConfig(pathTagsConfigPath),
     };
 }
+function loadPathTagsConfig(path) {
+    if (!path || !existsSync(path))
+        return { rules: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Invalid path tags config ${path}: ${describeError(error)}`);
+    }
+    const root = asRecord(parsed);
+    const rawRules = Array.isArray(root.rules) ? root.rules : [];
+    const rules = rawRules.map((rawRule, index) => {
+        const rule = asRecord(rawRule);
+        const pathPrefix = asString(rule.pathPrefix) ?? asString(rule.path_prefix);
+        if (!pathPrefix) {
+            throw new Error(`Invalid path tags config ${path}: rules[${index}].pathPrefix is required`);
+        }
+        const tags = Array.isArray(rule.tags)
+            ? rule.tags.filter((tag) => typeof tag === "string" && tag.trim().length > 0)
+            : [];
+        const metadata = asRecord(rule.metadata);
+        return {
+            pathPrefix,
+            tags,
+            metadata,
+            projectName: asString(rule.projectName) ?? asString(rule.project_name),
+            projectFolder: asString(rule.projectFolder) ?? asString(rule.project_folder),
+        };
+    });
+    return { rules, project: normalizeProjectTagOverlay(root, path) };
+}
+function loadProjectLocalOverlay(cwd) {
+    const configPath = findProjectLocalConfig(cwd);
+    if (!configPath)
+        return undefined;
+    const cached = projectLocalConfigCache.get(configPath);
+    if (projectLocalConfigCache.has(configPath))
+        return cached;
+    let overlay;
+    try {
+        overlay = normalizeProjectTagOverlay(JSON.parse(readFileSync(configPath, "utf8")), configPath);
+    }
+    catch (error) {
+        throw new Error(`Invalid project Langfuse config ${configPath}: ${describeError(error)}`);
+    }
+    projectLocalConfigCache.set(configPath, overlay);
+    return overlay;
+}
+function findProjectLocalConfig(cwd) {
+    if (!cwd)
+        return undefined;
+    let current = cwd;
+    while (true) {
+        try {
+            current = statSync(current).isDirectory() ? current : dirname(current);
+            break;
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return undefined;
+            current = parent;
+        }
+    }
+    while (true) {
+        const candidate = join(current, projectLocalConfigFile);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function normalizeProjectTagOverlay(value, sourcePath) {
+    const root = asRecord(value);
+    const rawTags = Array.isArray(root.tags) ? root.tags : [];
+    const tags = rawTags.filter((tag) => typeof tag === "string" && tag.trim().length > 0);
+    const metadata = asRecord(root.metadata);
+    const projectName = asString(root.projectName) ?? asString(root.project_name);
+    const projectFolder = asString(root.projectFolder) ?? asString(root.project_folder);
+    if (tags.length === 0 &&
+        Object.keys(metadata).length === 0 &&
+        !projectName &&
+        !projectFolder) {
+        return undefined;
+    }
+    return {
+        tags,
+        metadata,
+        projectName,
+        projectFolder,
+        sourcePath,
+    };
+}
+function normalizeRulePath(path) {
+    const normalized = path.replace(/\\/g, "/").replace(/\/+$/, "");
+    return /^[a-z]:\//i.test(normalized) ? normalized.toLowerCase() : normalized;
+}
 function loadCostCatalogFromEnv() {
     let catalog = { ...defaultCostRates };
     const path = process.env.CODING_AGENT_LANGFUSE_COST_RATES_PATH ??
@@ -1613,6 +1776,12 @@ function attr(key, value) {
         return { key, value: { stringValue: value } };
     return { key, value: { stringValue: JSON.stringify(value).slice(0, 8000) } };
 }
+function nonEmptyArray(value) {
+    return value.length > 0 ? value : undefined;
+}
+function nonEmptyRecord(value) {
+    return Object.keys(value).length > 0 ? value : undefined;
+}
 function utf8Bytes(value) {
     return Buffer.byteLength(value, "utf8");
 }
@@ -1645,6 +1814,7 @@ function limitEventPayload(event, maxFieldBytes) {
 function toOtlp(events, options = {}) {
     const maxFieldBytes = options.maxFieldBytes ?? defaultMaxFieldBytes;
     const costRates = options.costRates ?? loadCostCatalogFromEnv();
+    const pathTagsConfig = options.pathTagsConfig ?? { rules: [] };
     const spansByTrace = new Map();
     for (const rawEvent of events) {
         const event = limitEventPayload(rawEvent, maxFieldBytes);
@@ -1659,7 +1829,7 @@ function toOtlp(events, options = {}) {
         const traceStartMs = sortedEvents[0]?.startMs ?? Date.now();
         const traceEndMs = Math.max(...sortedEvents.map((event) => event.endMs ?? event.startMs + 1), traceStartMs + 1);
         const shouldEmitRootSpan = sortedEvents.some((event) => event.recordId === "session");
-        const firstProject = projectMetadata(first.cwd);
+        const firstProject = mergeProjectMetadata(first.cwd, pathTagsConfig);
         const rootAttributes = [
             attr("service.name", `agent.${first.agent}`),
             attr("deployment.environment", "local"),
@@ -1682,6 +1852,9 @@ function toOtlp(events, options = {}) {
             attr("langfuse.trace.metadata.project_path", firstProject.projectPath),
             attr("langfuse.trace.metadata.project_name", firstProject.projectName),
             attr("langfuse.trace.metadata.project_folder", firstProject.projectFolder),
+            attr("langfuse.trace.metadata.project_tags", nonEmptyArray(firstProject.tags)),
+            attr("langfuse.trace.metadata.path_tags", nonEmptyRecord(firstProject.metadata)),
+            attr("langfuse.trace.tags", nonEmptyArray(firstProject.tags)),
             attr("langfuse.trace.metadata.import_payload_version", payloadVersion(first)),
             attr("langfuse.trace.metadata.import_state_identity", importIdentity(first)),
             attr("langfuse.trace.metadata.langfuse_id_identity", langfuseIdIdentity(first)),
@@ -1695,6 +1868,8 @@ function toOtlp(events, options = {}) {
             attr("langfuse.observation.metadata.project_path", firstProject.projectPath),
             attr("langfuse.observation.metadata.project_name", firstProject.projectName),
             attr("langfuse.observation.metadata.project_folder", firstProject.projectFolder),
+            attr("langfuse.observation.metadata.project_tags", nonEmptyArray(firstProject.tags)),
+            attr("langfuse.observation.metadata.path_tags", nonEmptyRecord(firstProject.metadata)),
             attr("langfuse.observation.metadata.import_payload_version", payloadVersion(first)),
             attr("langfuse.observation.metadata.import_state_identity", importIdentity(first)),
             attr("langfuse.observation.metadata.langfuse_id_identity", langfuseIdIdentity(first)),
@@ -1703,6 +1878,9 @@ function toOtlp(events, options = {}) {
             attr("project.path", firstProject.projectPath),
             attr("project.name", firstProject.projectName),
             attr("project.folder", firstProject.projectFolder),
+            attr("project.tags", nonEmptyArray(firstProject.tags)),
+            attr("project.group", firstProject.metadata.project_group),
+            attr("project.owner", firstProject.metadata.project_owner),
         ].filter((item) => Boolean(item));
         const rootSpan = {
             traceId: traceId(first),
@@ -1722,7 +1900,7 @@ function toOtlp(events, options = {}) {
             const generation = isGenerationEvent(event);
             const usage = usageDetails(event.usage);
             const cost = generation ? calculateCost(event, usage, costRates) : undefined;
-            const eventProject = projectMetadata(event.cwd);
+            const eventProject = mergeProjectMetadata(event.cwd, pathTagsConfig);
             const attributes = [
                 attr("service.name", `agent.${event.agent}`),
                 attr("deployment.environment", "local"),
@@ -1747,6 +1925,8 @@ function toOtlp(events, options = {}) {
                 attr("langfuse.observation.metadata.project_path", eventProject.projectPath),
                 attr("langfuse.observation.metadata.project_name", eventProject.projectName),
                 attr("langfuse.observation.metadata.project_folder", eventProject.projectFolder),
+                attr("langfuse.observation.metadata.project_tags", nonEmptyArray(eventProject.tags)),
+                attr("langfuse.observation.metadata.path_tags", nonEmptyRecord(eventProject.metadata)),
                 attr("langfuse.observation.metadata.model", modelName ?? event.model),
                 attr("langfuse.observation.metadata.provider", event.provider),
                 attr("langfuse.observation.metadata.import_payload_version", payloadVersion(event)),
@@ -1770,6 +1950,9 @@ function toOtlp(events, options = {}) {
                 attr("project.path", eventProject.projectPath),
                 attr("project.name", eventProject.projectName),
                 attr("project.folder", eventProject.projectFolder),
+                attr("project.tags", nonEmptyArray(eventProject.tags)),
+                attr("project.group", eventProject.metadata.project_group),
+                attr("project.owner", eventProject.metadata.project_owner),
                 attr("role", event.role),
                 attr("agent.model", event.model),
                 attr("agent.provider", event.provider),
@@ -1953,6 +2136,7 @@ async function run(options) {
                 maxRequestBytes: options.maxRequestBytes,
                 maxFieldBytes: options.maxFieldBytes,
                 costRates: options.costRates,
+                pathTagsConfig: options.pathTagsConfig,
             });
         }
         catch (error) {
@@ -1979,6 +2163,7 @@ async function run(options) {
                 await postOtlp(options.endpoint, batch, {
                     maxFieldBytes: options.maxFieldBytes,
                     costRates: options.costRates,
+                    pathTagsConfig: options.pathTagsConfig,
                     auth: options.auth,
                 });
                 for (const event of batch) {

package/dist/service.d.ts

@@ -15,6 +15,7 @@ type ServiceOptions = {
     postDelayMs: number;
     costRatesPath?: string;
     costRatesJson?: string;
+    pathTagsConfigPath?: string;
     npxPath: string;
     since?: string;
     dryRun: boolean;

package/dist/service.js

@@ -26,6 +26,7 @@ Service options:
   --post-delay-ms N       Delay after each successful OTLP POST (default: 0)
   --cost-rates PATH       JSON model cost-rate overrides in USD per 1M tokens
   --cost-rates-json JSON  Inline JSON model cost-rate overrides in USD per 1M tokens
+  --path-tags-config PATH JSON path-prefix rules that add Langfuse tags/metadata
   --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
@@ -55,6 +56,8 @@ function parseServiceArgs(argv) {
         process.env.LANGFUSE_BACKFILL_COST_RATES_PATH;
     let costRatesJson = process.env.CODING_AGENT_LANGFUSE_COST_RATES_JSON ??
         process.env.LANGFUSE_BACKFILL_COST_RATES_JSON;
+    let pathTagsConfigPath = process.env.CODING_AGENT_LANGFUSE_PATH_TAGS_CONFIG ??
+        process.env.LANGFUSE_BACKFILL_PATH_TAGS_CONFIG;
     let since;
     let dryRun = false;
     let start = true;
@@ -107,6 +110,9 @@ function parseServiceArgs(argv) {
         else if (arg === "--cost-rates-json") {
             costRatesJson = next();
         }
+        else if (arg === "--path-tags-config") {
+            pathTagsConfigPath = next();
+        }
         else if (arg === "--since") {
             since = next();
         }
@@ -148,6 +154,7 @@ function parseServiceArgs(argv) {
         postDelayMs,
         costRatesPath,
         costRatesJson,
+        pathTagsConfigPath,
         since,
         dryRun,
         start,
@@ -300,6 +307,8 @@ function buildFollowCommand(options) {
         command.push("--cost-rates", options.costRatesPath);
     if (options.costRatesJson)
         command.push("--cost-rates-json", options.costRatesJson);
+    if (options.pathTagsConfigPath)
+        command.push("--path-tags-config", options.pathTagsConfigPath);
     return command;
 }
 function renderSystemdUnit(options, command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramarivera/coding-agent-langfuse",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "Universal coding-agent Langfuse backfiller and live OTLP helpers",
   "type": "module",
   "license": "MIT",