agent-profiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dudley Ablorh-Bryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapters/codex.js

@@ -0,0 +1,111 @@
+import { estimateTokens } from "../core/tokens.js";
+function pickFirstString(values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function stringifyToolPayload(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function estimateTokensForRole(role, text) {
+    const estimatedInputTokens = role === "user_prompt" || role === "tool_call" || role === "shell_command"
+        ? estimateTokens(text)
+        : 0;
+    const estimatedOutputTokens = role === "assistant_output" ||
+        role === "tool_result" ||
+        role === "tool_failure" ||
+        role === "shell_output" ||
+        role === "file_edit" ||
+        role === "session_stop"
+        ? estimateTokens(text)
+        : 0;
+    return { estimatedInputTokens, estimatedOutputTokens };
+}
+export function normalizeCodexEvent(eventName, rawPayload) {
+    const payload = asRecord(rawPayload);
+    const cwd = pickFirstString([payload.cwd]);
+    const sessionId = pickFirstString([payload.session_id]);
+    const turnId = pickFirstString([payload.turn_id]);
+    const model = pickFirstString([payload.model]);
+    let role = "unknown";
+    let observableText = "";
+    switch (eventName) {
+        case "SessionStart": {
+            role = "session_start";
+            observableText = pickFirstString([payload.source]) ?? "";
+            break;
+        }
+        case "UserPromptSubmit": {
+            role = "user_prompt";
+            observableText = pickFirstString([payload.prompt]) ?? "";
+            break;
+        }
+        case "PreToolUse": {
+            role = "tool_call";
+            const toolName = pickFirstString([payload.tool_name]) ?? "";
+            observableText = [toolName, stringifyToolPayload(payload.tool_input)]
+                .filter(Boolean)
+                .join("\n");
+            break;
+        }
+        case "PostToolUse": {
+            const toolName = (pickFirstString([payload.tool_name]) ?? "").trim();
+            const responseStr = stringifyToolPayload(payload.tool_response);
+            observableText = [toolName, responseStr].filter(Boolean).join("\n");
+            const lower = toolName.toLowerCase();
+            if (toolName === "Bash" || lower === "bash") {
+                role = "shell_output";
+            }
+            else if (toolName === "apply_patch" ||
+                toolName === "Edit" ||
+                toolName === "Write") {
+                role = "file_edit";
+            }
+            else {
+                role = "tool_result";
+            }
+            break;
+        }
+        case "Stop": {
+            role = "session_stop";
+            observableText = pickFirstString([payload.last_assistant_message]) ?? "";
+            break;
+        }
+        default: {
+            observableText = stringifyToolPayload(rawPayload);
+        }
+    }
+    const { estimatedInputTokens, estimatedOutputTokens } = estimateTokensForRole(role, observableText);
+    return {
+        source: "codex",
+        sourceEvent: eventName,
+        repoPath: cwd,
+        sessionId,
+        turnId,
+        model,
+        role,
+        observableText,
+        estimatedInputTokens,
+        estimatedOutputTokens,
+        estimatedTotalTokens: estimatedInputTokens + estimatedOutputTokens,
+        rawPayload,
+    };
+}

package/dist/adapters/cursor.js

@@ -0,0 +1,98 @@
+import { estimateTokens } from "../core/tokens.js";
+const cursorRoleMap = {
+    beforeSubmitPrompt: "user_prompt",
+    afterAgentResponse: "assistant_output",
+    afterAgentThought: "assistant_output",
+    afterShellExecution: "shell_output",
+    afterFileEdit: "file_edit",
+    preToolUse: "tool_call",
+    postToolUse: "tool_result",
+    postToolUseFailure: "tool_failure",
+    beforeMCPExecution: "tool_call",
+    afterMCPExecution: "tool_result",
+    beforeShellExecution: "shell_command",
+    beforeReadFile: "tool_call",
+    start: "session_start",
+    sessionStart: "session_start",
+    stop: "session_stop",
+    sessionEnd: "session_stop",
+    preCompact: "unknown",
+};
+function pickFirstString(values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function stringifyJsonish(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    try {
+        const s = JSON.stringify(value);
+        return s.length > 0 ? s : undefined;
+    }
+    catch {
+        return String(value);
+    }
+}
+function extractObservableText(payload) {
+    const content = pickFirstString([
+        payload.prompt,
+        payload.response,
+        payload.output,
+        payload.stderr,
+        payload.stdout,
+        payload.command,
+        payload.text,
+        payload.message,
+        typeof payload.result === "string" ? payload.result : undefined,
+    ]);
+    if (content)
+        return content;
+    const toolResponse = stringifyJsonish(payload.tool_response ?? payload.toolResponse ?? payload.result);
+    if (toolResponse)
+        return toolResponse;
+    const toolInput = stringifyJsonish(payload.tool_input ?? payload.toolInput ?? payload.input ?? payload.args ?? payload.arguments);
+    if (toolInput)
+        return toolInput;
+    return JSON.stringify(payload);
+}
+export function normalizeCursorEvent(eventName, rawPayload) {
+    const payload = asRecord(rawPayload);
+    const role = cursorRoleMap[eventName] ?? "unknown";
+    const observableText = extractObservableText(payload);
+    const estimatedInputTokens = role === "user_prompt" || role === "tool_call" || role === "shell_command"
+        ? estimateTokens(observableText)
+        : 0;
+    const estimatedOutputTokens = role === "assistant_output" ||
+        role === "tool_result" ||
+        role === "tool_failure" ||
+        role === "shell_output" ||
+        role === "file_edit"
+        ? estimateTokens(observableText)
+        : 0;
+    return {
+        source: "cursor",
+        sourceEvent: eventName,
+        repoPath: pickFirstString([payload.repoPath, payload.workspacePath]),
+        sessionId: pickFirstString([payload.sessionId, payload.session]),
+        turnId: pickFirstString([payload.turnId, payload.turn]),
+        model: pickFirstString([payload.model, payload.modelName]),
+        role,
+        observableText,
+        estimatedInputTokens,
+        estimatedOutputTokens,
+        estimatedTotalTokens: estimatedInputTokens + estimatedOutputTokens,
+        rawPayload,
+    };
+}

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { getAuditContextReport, runAuditContext } from "./commands/auditContext.js";
+import { runHook } from "./commands/hook.js";
+import { runInit } from "./commands/init.js";
+import { getLastReport, runLast } from "./commands/last.js";
+import { getStatusReport, runStatus } from "./commands/status.js";
+const program = new Command();
+program
+    .name("agent-profiler")
+    .description("Local-first profiling for AI coding agents.")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize Agent Profiler for a supported source.")
+    .argument("<source>", "supported: cursor | codex")
+    .option("--mode <mode>", "init mode: dev or prod", "dev")
+    .action((source, options) => {
+    const allowed = ["cursor", "codex"];
+    if (!allowed.includes(source)) {
+        console.error(`Unsupported source: ${source}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.mode !== "dev" && options.mode !== "prod") {
+        console.error(`Unsupported mode: ${options.mode}`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        runInit(source, options.mode);
+    }
+    catch (error) {
+        console.error("Failed to initialize Agent Profiler.");
+        console.error(error);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("hook")
+    .description("Ingest a hook event from an adapter.")
+    .argument("<source>", "adapter source: cursor | codex")
+    .argument("<eventName>", "source event name")
+    .action(async (source, eventName) => {
+    const allowed = ["cursor", "codex"];
+    if (!allowed.includes(source)) {
+        console.error(`Unsupported source: ${source}`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await runHook(source, eventName);
+    }
+    catch (error) {
+        console.error("Failed to process hook event.");
+        console.error(error);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("status")
+    .description("Show local Agent Profiler setup and ingest status.")
+    .option("--mode <mode>", "status mode: dev or prod", "dev")
+    .option("--json", "Output status as JSON")
+    .action((options) => {
+    if (options.mode !== "dev" && options.mode !== "prod") {
+        console.error(`Unsupported mode: ${options.mode}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(getStatusReport(options.mode), null, 2));
+        return;
+    }
+    runStatus(options.mode);
+});
+program
+    .command("last")
+    .description("Generate a report for the most recent observed session.")
+    .option("--json", "Output last-session report as JSON")
+    .action((options) => {
+    if (options.json) {
+        console.log(JSON.stringify(getLastReport(), null, 2));
+        return;
+    }
+    runLast();
+});
+program
+    .command("audit")
+    .description("Audit profiler-related workspace signals.")
+    .command("context")
+    .description("Estimate always-on instruction/context token footprint.")
+    .option("--json", "Output context audit as JSON")
+    .action((options) => {
+    if (options.json) {
+        console.log(JSON.stringify(getAuditContextReport(), null, 2));
+        return;
+    }
+    runAuditContext();
+});
+void program.parseAsync(process.argv);

package/dist/commands/auditContext.js

@@ -0,0 +1,46 @@
+import { runContextAudit } from "../core/contextAudit.js";
+function formatTokens(value) {
+    return `~${new Intl.NumberFormat("en-US").format(value)}`;
+}
+export function getAuditContextReport() {
+    const result = runContextAudit(process.cwd());
+    const recommendations = result.totalEstimatedTokens > 6000
+        ? [
+            "Move large reference docs from always-on rules into on-demand skills.",
+            "Keep always-on rules short, direct, and behavioral.",
+            "Trim long examples from core instruction files.",
+        ]
+        : [
+            "Context footprint is currently in a healthy range.",
+            "Re-run this audit after major rule or skill updates.",
+        ];
+    return {
+        totalEstimatedTokens: result.totalEstimatedTokens,
+        files: result.files,
+        recommendations,
+    };
+}
+export function runAuditContext() {
+    const report = getAuditContextReport();
+    const lines = [];
+    lines.push("Agent Profiler: Context Audit");
+    lines.push("");
+    lines.push("Estimated always-on / agent-adjacent context:");
+    lines.push(`  ${formatTokens(report.totalEstimatedTokens)} tokens`);
+    lines.push("");
+    lines.push("Largest contributors:");
+    if (report.files.length === 0) {
+        lines.push("  none found");
+    }
+    else {
+        for (const file of report.files.slice(0, 8)) {
+            lines.push(`  ${file.path.padEnd(40, " ")} ${formatTokens(file.estimatedTokens)}`);
+        }
+    }
+    lines.push("");
+    lines.push("Recommendations:");
+    report.recommendations.forEach((recommendation, index) => {
+        lines.push(`  ${index + 1}. ${recommendation}`);
+    });
+    console.log(lines.join("\n"));
+}

package/dist/commands/hook.js

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import { normalizeCodexEvent } from "../adapters/codex.js";
+import { normalizeCursorEvent } from "../adapters/cursor.js";
+import { resolveHookWorkspacePath, resolveWorkspaceGitMeta, } from "../core/gitWorkspace.js";
+import { deriveIngestFields, } from "../core/eventMetadata.js";
+import { getDefaultDbPath, insertEvent, mergeInteractionSpan, openDb, } from "../core/db.js";
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+function parseRawPayload(stdinText) {
+    const trimmed = stdinText.trim();
+    if (!trimmed)
+        return {};
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return { _unparsed: trimmed };
+    }
+}
+function normalizeEvent(source, eventName, rawPayload) {
+    if (source === "cursor") {
+        return normalizeCursorEvent(eventName, rawPayload);
+    }
+    if (source === "codex") {
+        return normalizeCodexEvent(eventName, rawPayload);
+    }
+    return {
+        source: "generic",
+        sourceEvent: eventName,
+        role: "unknown",
+        observableText: "",
+        estimatedInputTokens: 0,
+        estimatedOutputTokens: 0,
+        estimatedTotalTokens: 0,
+        rawPayload,
+    };
+}
+function hashPayload(payload) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify(payload))
+        .digest("hex");
+}
+/** Codex Stop hook requires JSON on stdout; see OpenAI Codex hooks docs. */
+function writeCodexHookAck(source, eventName) {
+    if (source !== "codex" || eventName !== "Stop")
+        return;
+    process.stdout.write(`${JSON.stringify({ continue: true })}\n`);
+}
+export async function runHook(source, eventName) {
+    const stdinText = await readStdin();
+    const rawPayload = parseRawPayload(stdinText);
+    const normalized = normalizeEvent(source, eventName, rawPayload);
+    const payloadHash = hashPayload(rawPayload);
+    const db = openDb(getDefaultDbPath());
+    try {
+        const workspacePath = resolveHookWorkspacePath(normalized.repoPath, rawPayload);
+        const workspaceGit = resolveWorkspaceGitMeta(workspacePath);
+        const derived = deriveIngestFields(source, eventName, rawPayload, stdinText, normalized);
+        const eventId = insertEvent(db, normalized, payloadHash, workspaceGit, derived);
+        mergeInteractionSpan(db, eventId, normalized, workspaceGit, derived);
+    }
+    finally {
+        db.close();
+    }
+    writeCodexHookAck(source, eventName);
+}