crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/services/monitoring/token-usage.service.js

@@ -0,0 +1,391 @@
+/**
+ * Token Usage Storage Service
+ *
+ * Tracks token usage per agent session with in-memory storage and
+ * optional periodic flush to ~/.crewly/token-usage.json.
+ *
+ * @module services/monitoring/token-usage.service
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+/** File name for persisting token usage data */
+const TOKEN_USAGE_FILE = 'token-usage.json';
+/** Interval in milliseconds between periodic flushes to disk (5 minutes) */
+const FLUSH_INTERVAL_MS = 300_000;
+/**
+ * Per-model token cost rates in USD per token.
+ * Used for server-side cost calculation.
+ */
+export const TOKEN_COSTS = {
+    'claude-3-opus': { input: 0.000015, output: 0.000075 },
+    'claude-3-5-sonnet': { input: 0.000003, output: 0.000015 },
+    'claude-3-haiku': { input: 0.00000025, output: 0.00000125 },
+    'claude-opus-4-20250514': { input: 0.000015, output: 0.000075 },
+    'claude-sonnet-4-20250514': { input: 0.000003, output: 0.000015 },
+    'claude-haiku-4-20250506': { input: 0.00000025, output: 0.00000125 },
+    'gemini-3-flash-preview': { input: 0.0000001, output: 0.0000004 },
+    'gemini-2.5-flash-preview-05-20': { input: 0.00000015, output: 0.0000006 },
+    'gemini-2.0-flash': { input: 0.0000001, output: 0.0000004 },
+    'gpt-4o': { input: 0.000005, output: 0.000015 },
+    'gpt-4o-mini': { input: 0.00000015, output: 0.0000006 },
+    default: { input: 0.000003, output: 0.000015 },
+};
+/**
+ * Calculate the cost for a given number of tokens and model.
+ *
+ * @param inputTokens - Number of input tokens (excluding cache tokens)
+ * @param outputTokens - Number of output tokens
+ * @param model - Model identifier
+ * @returns Cost in USD
+ */
+export function calculateCost(inputTokens, outputTokens, model) {
+    const rates = TOKEN_COSTS[model] || TOKEN_COSTS.default;
+    return inputTokens * rates.input + outputTokens * rates.output;
+}
+/**
+ * Stores a pre-calculated cost override for a session.
+ * Used when the caller has more accurate cost data (e.g., cache-aware pricing
+ * from Claude Code JSONL files).
+ */
+const sessionCostOverrides = new Map();
+/**
+ * Set a cost override for a session. When present, getSummary() uses this
+ * instead of recalculating from events.
+ */
+export function setSessionCostOverride(sessionName, cost) {
+    sessionCostOverrides.set(sessionName, cost);
+}
+/**
+ * Get a cost override if one exists.
+ */
+export function getSessionCostOverride(sessionName) {
+    return sessionCostOverrides.get(sessionName);
+}
+/**
+ * Service for tracking and aggregating token usage across agent sessions.
+ *
+ * Uses an in-memory Map keyed by sessionName, with optional periodic
+ * flush to ~/.crewly/token-usage.json for persistence across restarts.
+ *
+ * @example
+ * ```typescript
+ * const service = TokenUsageService.getInstance();
+ * service.recordUsage('session-1', 'agent-a', 500, 200, 'claude-3-opus');
+ * const summary = service.getUsageByAgent('agent-a');
+ * ```
+ */
+export class TokenUsageService {
+    static instance = null;
+    /** In-memory storage keyed by session name */
+    sessions = new Map();
+    /** Active task context per session (sessionName → { taskId, runId }) */
+    taskContexts = new Map();
+    /** Timer handle for periodic flush */
+    flushTimer = null;
+    /** Directory for persisting usage data */
+    storageDir;
+    /**
+     * Create a new TokenUsageService instance
+     *
+     * @param storageDir - Directory for persistence file (defaults to ~/.crewly)
+     */
+    constructor(storageDir) {
+        this.storageDir = storageDir ?? path.join(process.env.HOME || '~', '.crewly');
+    }
+    /**
+     * Get the singleton TokenUsageService instance
+     *
+     * @returns The shared TokenUsageService instance
+     */
+    static getInstance() {
+        if (!TokenUsageService.instance) {
+            TokenUsageService.instance = new TokenUsageService();
+        }
+        return TokenUsageService.instance;
+    }
+    /**
+     * Reset the singleton instance (for testing)
+     */
+    static resetInstance() {
+        if (TokenUsageService.instance) {
+            TokenUsageService.instance.stopPeriodicFlush();
+        }
+        TokenUsageService.instance = null;
+    }
+    /**
+     * Record a single token usage event for a session.
+     *
+     * Creates the session record if it doesn't exist, then appends the event
+     * and updates running totals.
+     *
+     * @param sessionName - The session name (e.g. 'crewly-orc')
+     * @param agentId - The agent identifier
+     * @param input - Number of input tokens consumed
+     * @param output - Number of output tokens generated
+     * @param model - AI model identifier used
+     */
+    recordUsage(sessionName, agentId, input, output, model, taskId) {
+        let record = this.sessions.get(sessionName);
+        if (!record) {
+            record = {
+                sessionName,
+                agentId,
+                totalInput: 0,
+                totalOutput: 0,
+                eventCount: 0,
+                events: [],
+            };
+            this.sessions.set(sessionName, record);
+        }
+        // Auto-apply task context if no explicit taskId provided
+        const ctx = this.taskContexts.get(sessionName);
+        const effectiveTaskId = taskId ?? ctx?.taskId ?? undefined;
+        const event = {
+            timestamp: new Date().toISOString(),
+            agentId,
+            input,
+            output,
+            model,
+            taskId: effectiveTaskId,
+        };
+        record.events.push(event);
+        record.totalInput += input;
+        record.totalOutput += output;
+        record.eventCount += 1;
+    }
+    /**
+     * Set a cache-aware cost override for a session.
+     * Used when the caller has pre-calculated cost with proper cache pricing.
+     */
+    overrideSessionCost(sessionName, cost) {
+        setSessionCostOverride(sessionName, cost);
+    }
+    /**
+     * Get aggregated token usage for a specific agent across all sessions.
+     *
+     * @param agentId - The agent identifier to query
+     * @returns Aggregated usage summary for the agent
+     */
+    getUsageByAgent(agentId) {
+        let totalInput = 0;
+        let totalOutput = 0;
+        let eventCount = 0;
+        for (const record of this.sessions.values()) {
+            if (record.agentId === agentId) {
+                totalInput += record.totalInput;
+                totalOutput += record.totalOutput;
+                eventCount += record.eventCount;
+            }
+        }
+        return { totalInput, totalOutput, eventCount };
+    }
+    /**
+     * Get per-session usage summaries for the dashboard.
+     *
+     * @returns Array of session usage summaries
+     */
+    getUsageBySessions(taskId) {
+        const summaries = [];
+        for (const record of this.sessions.values()) {
+            // Filter events by taskId if provided
+            const events = taskId
+                ? record.events.filter(e => e.taskId === taskId)
+                : record.events;
+            if (taskId && events.length === 0)
+                continue;
+            // Compute per-model breakdown
+            const modelMap = new Map();
+            let filteredInput = 0;
+            let filteredOutput = 0;
+            for (const event of events) {
+                const existing = modelMap.get(event.model) || { input: 0, output: 0 };
+                existing.input += event.input;
+                existing.output += event.output;
+                modelMap.set(event.model, existing);
+                filteredInput += event.input;
+                filteredOutput += event.output;
+            }
+            const modelBreakdown = [];
+            for (const [model, usage] of modelMap) {
+                modelBreakdown.push({
+                    model,
+                    inputTokens: usage.input,
+                    outputTokens: usage.output,
+                    cost: calculateCost(usage.input, usage.output, model),
+                });
+            }
+            const calculatedCost = modelBreakdown.reduce((sum, m) => sum + m.cost, 0);
+            // Use cache-aware cost override if available (from Claude JSONL sync)
+            const costOverride = !taskId ? getSessionCostOverride(record.sessionName) : undefined;
+            const totalCost = costOverride ?? calculatedCost;
+            summaries.push({
+                sessionName: record.sessionName,
+                agentId: record.agentId,
+                totalInput: taskId ? filteredInput : record.totalInput,
+                totalOutput: taskId ? filteredOutput : record.totalOutput,
+                eventCount: taskId ? events.length : record.eventCount,
+                cost: totalCost,
+                modelBreakdown,
+            });
+        }
+        return summaries;
+    }
+    /**
+     * Set the current task context for a session.
+     * All subsequent recordUsage calls for this session will be tagged with the taskId.
+     *
+     * @param sessionName - Session name
+     * @param taskId - Task ID to associate, or null to clear
+     * @param runId - Optional run ID for precise run-level attribution
+     */
+    setTaskContext(sessionName, taskId, runId) {
+        if (taskId === null) {
+            this.taskContexts.set(sessionName, null);
+        }
+        else {
+            this.taskContexts.set(sessionName, { taskId, runId });
+        }
+    }
+    /**
+     * Get the current task context for a session (taskId only, backward compatible).
+     *
+     * @param sessionName - Session name
+     * @returns Current task ID or null
+     */
+    getTaskContext(sessionName) {
+        const ctx = this.taskContexts.get(sessionName);
+        return ctx?.taskId ?? null;
+    }
+    /**
+     * Get the full task+run context for a session.
+     *
+     * @param sessionName - Session name
+     * @returns Object with taskId and optional runId, or null if no context
+     */
+    getRunContext(sessionName) {
+        return this.taskContexts.get(sessionName) ?? null;
+    }
+    /**
+     * Get aggregated token usage grouped by task ID.
+     *
+     * @returns Map of taskId to aggregated token totals
+     */
+    getUsageByTask() {
+        const taskMap = new Map();
+        for (const record of this.sessions.values()) {
+            for (const event of record.events) {
+                const tid = event.taskId ?? 'unassigned';
+                const existing = taskMap.get(tid) ?? { taskId: tid, totalInput: 0, totalOutput: 0, eventCount: 0, cost: 0 };
+                existing.totalInput += event.input;
+                existing.totalOutput += event.output;
+                existing.eventCount += 1;
+                existing.cost += calculateCost(event.input, event.output, event.model);
+                taskMap.set(tid, existing);
+            }
+        }
+        return taskMap;
+    }
+    /**
+     * Get token usage events for a specific session recorded after a given timestamp.
+     * Used to compute the token delta for a single Request when the orchestrator
+     * handles the work directly (no WorkItem delegation).
+     *
+     * @param sessionName - The session to query (e.g. 'crewly-orc')
+     * @param since - Only return events recorded at or after this time
+     * @param until - Only return events before this time (defaults to now)
+     * @returns Aggregated input tokens, output tokens, and cost in the window
+     */
+    getSessionUsageSince(sessionName, since, until) {
+        const record = this.sessions.get(sessionName);
+        if (!record)
+            return { inputTokens: 0, outputTokens: 0, cost: 0 };
+        const sinceMs = since.getTime();
+        const untilMs = until ? until.getTime() : Infinity;
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let cost = 0;
+        for (const event of record.events) {
+            const eventMs = new Date(event.timestamp).getTime();
+            if (eventMs >= sinceMs && eventMs <= untilMs) {
+                inputTokens += event.input;
+                outputTokens += event.output;
+                cost += calculateCost(event.input, event.output, event.model);
+            }
+        }
+        return { inputTokens, outputTokens, cost };
+    }
+    /**
+     * Clear all tracked token usage data.
+     */
+    resetUsage() {
+        this.sessions.clear();
+    }
+    /**
+     * Start periodic flush of usage data to disk.
+     *
+     * Writes the current in-memory state to ~/.crewly/token-usage.json
+     * at a fixed interval.
+     */
+    startPeriodicFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(() => {
+            this.flushToDisk().catch(() => {
+                // Silently ignore flush errors — data is still in memory
+            });
+        }, FLUSH_INTERVAL_MS);
+        // Allow Node to exit even if timer is running
+        if (this.flushTimer.unref) {
+            this.flushTimer.unref();
+        }
+    }
+    /**
+     * Stop the periodic flush timer.
+     */
+    stopPeriodicFlush() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /**
+     * Flush current usage data to disk.
+     *
+     * Writes sessions as a JSON array to the storage directory.
+     */
+    async flushToDisk() {
+        const filePath = path.join(this.storageDir, TOKEN_USAGE_FILE);
+        const data = Array.from(this.sessions.values());
+        await fs.mkdir(this.storageDir, { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    /**
+     * Load previously persisted usage data from disk.
+     *
+     * Merges loaded data into the current in-memory state.
+     */
+    async loadFromDisk() {
+        const filePath = path.join(this.storageDir, TOKEN_USAGE_FILE);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            const records = JSON.parse(raw);
+            for (const record of records) {
+                if (!this.sessions.has(record.sessionName)) {
+                    this.sessions.set(record.sessionName, record);
+                }
+            }
+        }
+        catch {
+            // File doesn't exist or is invalid — start fresh
+        }
+    }
+    /**
+     * Get the number of tracked sessions (for testing).
+     *
+     * @returns Number of sessions in the store
+     */
+    getSessionCount() {
+        return this.sessions.size;
+    }
+}
+//# sourceMappingURL=token-usage.service.js.map

package/dist/cli/backend/src/services/monitoring/token-usage.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/monitoring/token-usage.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/observability/agent-behavior-log.service.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Agent Behavior Log — write/read service.
+ *
+ * Translates strongly-typed `BehaviorLogEvent` values into rows of the
+ * `agent_behavior_log` table and reads them back as typed records.
+ *
+ * Design choices:
+ * - One service instance owns one DB handle; tests pass `:memory:`.
+ * - All writes are append-only inserts; no updates, no deletes.
+ * - Best-effort logging — `record()` swallows DB errors after logging
+ *   them, so observability never takes the request path down.
+ * - Read APIs are minimal: this PR ships the schema + write surface.
+ *   Digest/aggregation queries land in a follow-up.
+ *
+ * Wiring of producers (Slack-failure listener, prompt-size sampler,
+ * orchestrator action logger) is intentionally out of scope for this
+ * PR — see P0-5 / prompt-generator follow-ups.
+ *
+ * @module services/observability/agent-behavior-log.service
+ */
+import { type ObservabilityDatabase, type OpenObservabilityDatabaseOptions } from './observability-db.js';
+import { type BehaviorLogEvent, type BehaviorLogEventType } from './agent-behavior-log.types.js';
+import { type ComponentLogger } from '../core/logger.service.js';
+/**
+ * Decoded behavior log row — `details_json` is parsed back into an
+ * object, and `event_type` is narrowed to the discriminator union.
+ */
+export interface BehaviorLogRecord {
+    id: number;
+    ts: number;
+    eventType: BehaviorLogEventType;
+    agent: string;
+    subject: string;
+    taskId: string;
+    reason: string;
+    amount: number;
+    details: Record<string, unknown>;
+}
+/**
+ * Options for constructing an `AgentBehaviorLogService`. Either pass an
+ * existing DB handle (preferred for tests) or a set of opener options
+ * the service should use to open its own handle.
+ */
+export interface AgentBehaviorLogServiceOptions {
+    /** Pre-opened database handle. Service does NOT take ownership. */
+    db?: ObservabilityDatabase;
+    /** Opener options used when `db` is not supplied. */
+    openOptions?: OpenObservabilityDatabaseOptions;
+    /** Optional time source — defaults to `Date.now`. Used in tests. */
+    now?: () => number;
+    /** Optional logger override. */
+    logger?: ComponentLogger;
+}
+/**
+ * Append-only writer + minimal reader for the `agent_behavior_log`
+ * table.
+ *
+ * @example
+ * ```ts
+ * const svc = new AgentBehaviorLogService();
+ * svc.record({
+ *   type: 'agent.action',
+ *   agent: 'crewly-orc',
+ *   actionType: 'delegate',
+ *   taskId: 'req-123',
+ *   details: { recipient: 'sam' },
+ * });
+ * ```
+ */
+export declare class AgentBehaviorLogService {
+    private readonly db;
+    private readonly ownsDb;
+    private readonly now;
+    private readonly logger;
+    private insertStmt;
+    constructor(options?: AgentBehaviorLogServiceOptions);
+    /**
+     * Lazily prepare and cache the insert statement. Avoids paying the
+     * prepare cost for callers that only ever read.
+     */
+    private getInsertStmt;
+    /**
+     * Record one behavior event.
+     *
+     * Translates the discriminated `BehaviorLogEvent` into a
+     * `BehaviorLogRow`-compatible parameter object and inserts. Errors
+     * are caught and logged — observability writes must NEVER throw into
+     * the calling code path.
+     *
+     * @param event - The strongly-typed event to record
+     * @returns The newly inserted row id, or `null` if the write failed
+     */
+    record(event: BehaviorLogEvent): number | null;
+    /**
+     * Translate a `BehaviorLogEvent` into the parameter object expected
+     * by the prepared insert statement.
+     *
+     * The discriminator branch is exhaustive — adding a new event type
+     * forces a TypeScript error here until the new branch is added.
+     */
+    private toRowParams;
+    /** Build params for an `agent.action` event. */
+    private buildAgentActionParams;
+    /** Build params for an `agent.escalation` event. */
+    private buildEscalationParams;
+    /** Build params for a `slack.delivery.failed` event. */
+    private buildSlackFailureParams;
+    /** Build params for a `prompt.size.bytes` event. */
+    private buildPromptSizeParams;
+    /**
+     * Return the most recent N rows, newest first. Optionally filter by
+     * event type. Intended for diagnostics and tests; production digest
+     * code should use a dedicated aggregation query.
+     *
+     * @param limit - Max rows to return (capped at 1000)
+     * @param eventType - Optional event-type filter
+     */
+    listRecent(limit?: number, eventType?: BehaviorLogEventType): BehaviorLogRecord[];
+    /**
+     * Count rows by event type since a given timestamp. Useful for the
+     * weekly digest's per-event totals.
+     *
+     * @param sinceTs - Inclusive ms-since-epoch lower bound (default 0 = all time)
+     */
+    countByEvent(sinceTs?: number): Record<string, number>;
+    /**
+     * Close the underlying DB handle if this service opened it. Safe to
+     * call multiple times.
+     */
+    close(): void;
+}
+//# sourceMappingURL=agent-behavior-log.service.d.ts.map

package/dist/cli/backend/src/services/observability/agent-behavior-log.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-behavior-log.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/observability/agent-behavior-log.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,gCAAgC,EACtC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAI1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAMhF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,oBAAoB,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAMD;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C,mEAAmE;IACnE,EAAE,CAAC,EAAE,qBAAqB,CAAC;IAC3B,qDAAqD;IACrD,WAAW,CAAC,EAAE,gCAAgC,CAAC;IAC/C,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gCAAgC;IAChC,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAMD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,UAAU,CAAmD;gBAEzD,OAAO,GAAE,8BAAmC;IAexD;;;OAGG;IACH,OAAO,CAAC,aAAa;IAYrB;;;;;;;;;;OAUG;IACI,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI;IAcrD;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAiCnB,gDAAgD;IAChD,OAAO,CAAC,sBAAsB;IAgB9B,oDAAoD;IACpD,OAAO,CAAC,qBAAqB;IAgB7B,wDAAwD;IACxD,OAAO,CAAC,uBAAuB;IAgB/B,oDAAoD;IACpD,OAAO,CAAC,qBAAqB;IAoB7B;;;;;;;OAOG;IACI,UAAU,CACf,KAAK,SAAM,EACX,SAAS,CAAC,EAAE,oBAAoB,GAC/B,iBAAiB,EAAE;IAoBtB;;;;;OAKG;IACI,YAAY,CAAC,OAAO,SAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAgBxD;;;OAGG;IACI,KAAK,IAAI,IAAI;CAWrB"}