crewly 1.20.193 → 1.20.195

package/dist/cli/backend/src/services/trace/trace-context.service.js

@@ -0,0 +1,432 @@
+/**
+ * Trace context: which trace each agent session's turn is working on.
+ *
+ * Every message written into an agent turn passes through
+ * {@link TraceContext.noteTurnDelivery}. The trace of the text (a
+ * `[TRACE:…]` marker, a ticket marker, or a work item / decision / ticket id
+ * the index knows) becomes the session's current trace, and later events of
+ * that session (skill calls, replies, usage) are attributed to it.
+ *
+ * An owner message that names no trace is kept as a *pending root*: the trace
+ * is only created when the turn starts work ({@link TraceContext.ensureTraceForSession}),
+ * so chit-chat makes no trace.
+ *
+ * The current trace ends (so nothing later is billed to a finished run) when:
+ * - a delivery names no trace (cron / scheduled prompts, system notices,
+ *   digests, an untraced owner message);
+ * - the session's work item in that trace reaches a terminal status
+ *   ({@link TraceContext.clearIfCurrent});
+ * - the session shows no activity (deliveries, API calls) for the idle gap
+ *   ({@link defaultIdleClearMs}).
+ *
+ * All state is in memory; a restart starts clean (new deliveries set it again).
+ *
+ * specs/2026-10-03-run-traces.md
+ *
+ * @module services/trace/trace-context.service
+ */
+import { TRACE_CONSTANTS } from '../../constants.js';
+import { LoggerService } from '../core/logger.service.js';
+import { getTraceStore } from './trace-store.js';
+import { cleanTraceData, extractTextRefs, parseTraceMarkers, safeSummary } from './trace-markers.js';
+import { isTraceId, newTraceId, } from './trace.types.js';
+/**
+ * Idle gap after which a session's current trace is dropped: the
+ * `CREWLY_TRACE_IDLE_CLEAR_MINUTES` env var, else
+ * {@link TRACE_CONSTANTS.IDLE_CLEAR_MS}.
+ *
+ * @returns Milliseconds
+ */
+export function defaultIdleClearMs() {
+    const minutes = Number(process.env.CREWLY_TRACE_IDLE_CLEAR_MINUTES);
+    return Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : TRACE_CONSTANTS.IDLE_CLEAR_MS;
+}
+/** A `[CHAT:…]` / `[GCHAT:…]` routing prefix (owner or chat-routed message). */
+const CHAT_PREFIX = /^\s*\[G?CHAT:[^\]]*\]/;
+/**
+ * Classify a delivered text.
+ *
+ * @param text - Exactly what was written into the turn
+ * @returns The delivery kind
+ */
+export function classifyDelivery(text) {
+    if (/\[TASK RE-DELIVERY\]|\[CREWLY-DISPATCH\] \d+ WorkItems are still queued/.test(text))
+        return 'redelivery';
+    if (/\[CREWLY-DISPATCH\]|\[TASK ASSIGNMENT\]|^\s*\[TASK\]/.test(text))
+        return 'dispatch';
+    if (/Agent status:|Status from \S+ \(reports to you\)|\[STATUS DIGEST\]|\[STATUS REPORT\]/.test(text))
+        return 'status';
+    if (/\[DECISION\b/.test(text))
+        return 'decision';
+    if (/\[FOLLOW-UP\b/.test(text))
+        return 'follow_up';
+    if (/^\s*\[SYSTEM\b|\[EVENT:/.test(text))
+        return 'system';
+    if (CHAT_PREFIX.test(text))
+        return 'owner_message';
+    return 'system';
+}
+/**
+ * Per-session trace context. Singleton (see {@link getTraceContext}).
+ */
+export class TraceContext {
+    storeOf;
+    logger;
+    spans = new Map();
+    pending = new Map();
+    now;
+    idleClearMs;
+    /**
+     * @param storeOf - Store accessor (default: the process-wide store)
+     * @param now - Clock (ms)
+     * @param idleClearMs - Idle gap that ends a session's current trace (default {@link defaultIdleClearMs})
+     */
+    constructor(storeOf = getTraceStore, now, idleClearMs) {
+        this.storeOf = storeOf;
+        this.logger = LoggerService.getInstance().createComponentLogger('TraceContext');
+        this.now = now ?? (() => Date.now());
+        this.idleClearMs = idleClearMs ?? defaultIdleClearMs();
+    }
+    /** The store. */
+    get store() {
+        return this.storeOf();
+    }
+    /**
+     * Start a trace and write its root event.
+     *
+     * @param input - Root kind, summary, actor, refs, optional session to bind
+     * @returns The new trace id, or null when the store refused it
+     */
+    startTrace(input) {
+        try {
+            const at = input.now ?? new Date(this.now());
+            const traceId = newTraceId(at);
+            const ok = this.store.createRoot({
+                traceId,
+                kind: input.kind,
+                summary: safeSummary(input.summary) || input.kind,
+                createdAt: at.toISOString(),
+                actor: input.actor,
+                refs: input.refs ?? {},
+            });
+            if (!ok)
+                return null;
+            if (input.session)
+                this.setCurrent(input.session, traceId, at.getTime());
+            this.logger.debug('Trace started', { traceId, kind: input.kind, session: input.session });
+            return traceId;
+        }
+        catch (err) {
+            this.logger.debug('Trace could not be started', { error: errText(err) });
+            return null;
+        }
+    }
+    /**
+     * Append an event (summary cleaned, data trimmed). Never throws.
+     *
+     * @param input - The event
+     * @returns True when queued
+     */
+    record(input) {
+        try {
+            if (!isTraceId(input.traceId))
+                return false;
+            const refs = {};
+            for (const [k, v] of Object.entries(input.refs ?? {})) {
+                if (typeof v === 'string' && v.length > 0)
+                    refs[k] = v;
+            }
+            const data = cleanTraceData(input.data);
+            const event = {
+                ts: (input.at ?? new Date(this.now())).toISOString(),
+                traceId: input.traceId,
+                type: input.type,
+                actor: input.actor,
+                refs,
+                summary: safeSummary(input.summary),
+                outcome: input.outcome ?? 'info',
+                ...(data ? { data } : {}),
+            };
+            return this.store.append(event);
+        }
+        catch (err) {
+            this.logger.debug('Trace event dropped', { type: input.type, error: errText(err) });
+            return false;
+        }
+    }
+    /**
+     * The trace the session's turn is working on now.
+     *
+     * @param session - Agent session
+     * @returns Trace id, or null
+     */
+    currentTrace(session) {
+        if (!session)
+            return null;
+        const last = this.expireIfIdle(session);
+        if (!last?.traceId)
+            return null;
+        return this.store.has(last.traceId) ? last.traceId : null;
+    }
+    /**
+     * The session did something (an API call, a delivery): keep its current
+     * trace alive. A trace already past the idle gap is ended first, so a
+     * session coming back after a long pause does not revive it.
+     *
+     * @param session - Agent session
+     * @param at - When (ms)
+     */
+    touch(session, at = this.now()) {
+        if (!session)
+            return;
+        const last = this.expireIfIdle(session, at);
+        if (last?.traceId && at > last.lastActive)
+            last.lastActive = at;
+    }
+    /**
+     * End the session's current trace if it is this one (its work item
+     * reached a terminal status).
+     *
+     * @param session - Agent session
+     * @param traceId - The trace that finished for it
+     * @returns True when it was cleared
+     */
+    clearIfCurrent(session, traceId) {
+        if (!session || !traceId)
+            return false;
+        const spans = this.spans.get(session);
+        const last = spans?.[spans.length - 1];
+        if (last?.traceId !== traceId)
+            return false;
+        this.setCurrent(session, null);
+        return true;
+    }
+    /**
+     * The session's last span, after ending it when the session has been idle
+     * longer than the idle gap (a null span then starts where the gap ended).
+     *
+     * @param session - Agent session
+     * @param at - Now (ms)
+     * @returns The last span after the check, or undefined
+     */
+    expireIfIdle(session, at = this.now()) {
+        const spans = this.spans.get(session);
+        const last = spans?.[spans.length - 1];
+        if (!spans || !last?.traceId || at - last.lastActive <= this.idleClearMs)
+            return last;
+        const since = last.lastActive + this.idleClearMs;
+        spans.push({ since, traceId: null, lastActive: since });
+        while (spans.length > TRACE_CONSTANTS.SESSION_HISTORY_SPANS)
+            spans.shift();
+        return spans[spans.length - 1];
+    }
+    /**
+     * The trace the session was working on at a given time (usage entries are
+     * often recorded after the turn, e.g. by the Claude transcript sync).
+     *
+     * @param session - Agent session
+     * @param at - Time of the entry (ms); default now
+     * @returns Trace id, or null
+     */
+    traceAt(session, at) {
+        if (!session)
+            return null;
+        const spans = this.spans.get(session);
+        if (!spans || spans.length === 0)
+            return null;
+        const t = at ?? this.now();
+        for (let i = spans.length - 1; i >= 0; i--) {
+            if (spans[i].since <= t) {
+                const id = spans[i].traceId;
+                // Past the idle gap of that span: the session had stopped working on it.
+                if (id && t - spans[i].lastActive > this.idleClearMs)
+                    return null;
+                return id && this.store.has(id) ? id : null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Set (or clear) the session's current trace.
+     *
+     * @param session - Agent session
+     * @param traceId - Trace, or null for none
+     * @param at - Since when (ms)
+     */
+    setCurrent(session, traceId, at = this.now()) {
+        const spans = this.spans.get(session) ?? [];
+        const last = spans[spans.length - 1];
+        if (last && last.traceId === traceId) {
+            if (at > last.lastActive)
+                last.lastActive = at;
+            return;
+        }
+        spans.push({ since: at, traceId, lastActive: at });
+        while (spans.length > TRACE_CONSTANTS.SESSION_HISTORY_SPANS)
+            spans.shift();
+        this.spans.set(session, spans);
+    }
+    /**
+     * The session's current trace; when it has none but an owner message is
+     * waiting, that message becomes the root of a new trace now (the turn is
+     * starting work).
+     *
+     * @param session - Agent session
+     * @returns Trace id, or null
+     */
+    ensureTraceForSession(session) {
+        if (!session)
+            return null;
+        const current = this.currentTrace(session);
+        if (current)
+            return current;
+        const pending = this.pending.get(session);
+        if (!pending)
+            return null;
+        this.pending.delete(session);
+        if (this.now() - pending.at > TRACE_CONSTANTS.PENDING_ROOT_TTL_MS)
+            return null;
+        const traceId = this.startTrace({
+            kind: 'owner_message',
+            summary: pending.summary,
+            actor: { kind: 'owner' },
+            refs: { session },
+            now: new Date(pending.at),
+        });
+        if (!traceId)
+            return null;
+        this.record({
+            traceId,
+            type: 'turn.delivered',
+            actor: { kind: 'owner' },
+            summary: `Owner message delivered to ${session}: ${pending.summary}`,
+            refs: { session },
+            data: { kind: 'owner_message' },
+            at: new Date(pending.at),
+        });
+        this.setCurrent(session, traceId);
+        return traceId;
+    }
+    /**
+     * Traces a text refers to: `[TRACE:…]` markers win; otherwise ticket
+     * markers, then work item / decision / ticket ids the index knows.
+     *
+     * @param text - Any text
+     * @returns Trace ids, in order, de-duplicated
+     */
+    resolveTracesFromText(text) {
+        const store = this.store;
+        const markers = parseTraceMarkers(text).filter((id) => store.has(id));
+        if (markers.length > 0)
+            return markers;
+        const refs = extractTextRefs(text);
+        const out = [];
+        const add = (id) => {
+            if (id && !out.includes(id))
+                out.push(id);
+        };
+        for (const id of refs.requestIds)
+            add(store.traceByRef('request', id));
+        for (const id of refs.workItemIds)
+            add(store.traceByRef('workItem', id));
+        for (const id of refs.decisionIds)
+            add(store.traceByRef('decision', id));
+        for (const id of refs.ticketIds)
+            add(store.traceByRef('ticket', id));
+        return out;
+    }
+    /**
+     * A message was written into an agent's turn. Sets the session's current
+     * trace and records `turn.delivered` (see the module doc). Never throws.
+     *
+     * @param session - Agent session written to
+     * @param text - Exactly what was delivered
+     * @param runtime - `pty` or `in-process`
+     * @returns The trace the turn is now on, or null
+     */
+    noteTurnDelivery(session, text, runtime = 'pty') {
+        try {
+            if (!session || typeof text !== 'string' || text.length === 0)
+                return null;
+            const kind = classifyDelivery(text);
+            const traces = this.resolveTracesFromText(text);
+            const now = this.now();
+            if (traces.length === 0) {
+                // Nothing in the text names a run. An owner message may start one
+                // (pending root); anything else — a cron / scheduled prompt, a system
+                // notice, a digest — is not part of the run the session was on, so
+                // later calls and usage must not be billed to it.
+                this.setCurrent(session, null, now);
+                if (kind === 'owner_message')
+                    this.pending.set(session, { summary: safeSummary(text), at: now });
+                return null;
+            }
+            const current = this.currentTrace(session);
+            const next = current && traces.includes(current) ? current : traces[0];
+            this.setCurrent(session, next, now);
+            this.pending.delete(session);
+            const actor = kind === 'owner_message' ? { kind: 'owner' } : { kind: 'system' };
+            for (const traceId of traces) {
+                this.record({
+                    traceId,
+                    type: 'turn.delivered',
+                    actor,
+                    summary: `${DELIVERY_LABELS[kind]} delivered to ${session}: ${text}`,
+                    refs: { session },
+                    data: { kind, runtime },
+                });
+            }
+            return next;
+        }
+        catch (err) {
+            this.logger.debug('Turn delivery not traced', { session, error: errText(err) });
+            return null;
+        }
+    }
+    /**
+     * Forget everything (tests).
+     */
+    reset() {
+        this.spans.clear();
+        this.pending.clear();
+    }
+}
+/** Human labels of delivery kinds (summaries). */
+const DELIVERY_LABELS = {
+    owner_message: 'Owner message',
+    dispatch: 'Work item brief',
+    redelivery: 'Work item redelivery',
+    status: 'Status report',
+    decision: 'Decision answer',
+    follow_up: 'Follow-up',
+    system: 'System message',
+};
+/**
+ * Error text.
+ *
+ * @param err - Anything thrown
+ * @returns Message
+ */
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+let instance = null;
+/**
+ * The process-wide trace context.
+ *
+ * @returns The context (created on first use)
+ */
+export function getTraceContext() {
+    if (!instance)
+        instance = new TraceContext();
+    return instance;
+}
+/**
+ * Replace the process-wide context (tests).
+ *
+ * @param context - Context, or null to rebuild the default lazily
+ */
+export function setTraceContextForTesting(context) {
+    instance = context;
+}
+//# sourceMappingURL=trace-context.service.js.map

package/dist/cli/backend/src/services/trace/trace-context.service.js.map

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

package/dist/cli/backend/src/services/trace/trace-markers.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Text helpers for run traces: the `[TRACE:<id>]` prompt marker, the ids a
+ * delivered text refers to, safe summaries, and skill-call path labels.
+ *
+ * All pure; no I/O.
+ *
+ * @module services/trace/trace-markers
+ */
+import { type TraceData } from './trace.types.js';
+/**
+ * The marker for a trace.
+ *
+ * @param traceId - Trace id
+ * @returns `[TRACE:<id>]`
+ */
+export declare function formatTraceMarker(traceId: string): string;
+/**
+ * Trace ids named by `[TRACE:…]` markers in a text, in order, de-duplicated.
+ *
+ * @param text - Delivered text
+ * @returns Trace ids
+ */
+export declare function parseTraceMarkers(text: string): string[];
+/**
+ * Append the trace marker as the last line, unless the text already names
+ * this trace. Used where a prefix could disturb routing parsers (status
+ * reports, agent-to-agent messages).
+ *
+ * @param text - Message text
+ * @param traceId - Trace to carry (no-op when absent)
+ * @returns The text with the marker
+ */
+export declare function appendTraceMarker(text: string, traceId: string | null | undefined): string;
+/**
+ * Remove every `[TRACE:…]` marker from text going to the owner or an outside
+ * channel (Slack, chat, the portal). Trace ids are harness plumbing; an
+ * agent that copies a prompt's marker into its reply must not show it.
+ *
+ * @param text - Outgoing text
+ * @returns The text without markers (unchanged when it had none)
+ *
+ * @example
+ * stripTraceMarkers('Done.\n[TRACE:tr-20261003-0123abcd]') // 'Done.'
+ */
+export declare function stripTraceMarkers(text: string): string;
+/** Ids a delivered text refers to, by kind. */
+export interface TextRefs {
+    /** Request ids from `[TICKET:TKT-n <id>]` markers */
+    requestIds: string[];
+    /** UUIDs (candidate work item ids) */
+    workItemIds: string[];
+    /** `D-n` */
+    decisionIds: string[];
+    /** `CE-7`, `TKT-12`, … (not `D-n`) */
+    ticketIds: string[];
+}
+/**
+ * Every id in a text that the trace index might know.
+ *
+ * @param text - Delivered text
+ * @returns Ids by kind, each de-duplicated
+ */
+export declare function extractTextRefs(text: string): TextRefs;
+/**
+ * A summary safe to store: one line, routing prefixes and trace markers
+ * removed, secrets redacted, cut to {@link TRACE_CONSTANTS.SUMMARY_MAX_CHARS}.
+ *
+ * @param text - Raw text (a message body, an error, a title)
+ * @param max - Character limit
+ * @returns The summary
+ */
+export declare function safeSummary(text: string | null | undefined, max?: number): string;
+/**
+ * Keep only small values in an event's data map: strings are summarised,
+ * non-finite numbers and empty values are dropped.
+ *
+ * @param data - Raw data
+ * @returns Cleaned data, or undefined when nothing is left
+ */
+export declare function cleanTraceData(data: Record<string, unknown> | undefined): TraceData | undefined;
+/**
+ * The label of a skill call: method plus API path with ids replaced, so calls
+ * group by endpoint.
+ *
+ * @param method - HTTP method
+ * @param apiPath - Path relative to `/api` (query string ignored)
+ * @returns e.g. `POST /task-pool/:id/complete`
+ *
+ * @example
+ * skillLabel('post', '/terminal/crewly-orc/write?x=1') // 'POST /terminal/:session/write'
+ */
+export declare function skillLabel(method: string, apiPath: string): string;
+//# sourceMappingURL=trace-markers.d.ts.map

package/dist/cli/backend/src/services/trace/trace-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-markers.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/trace/trace-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAoB7D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAG1F;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACxB,qDAAqD;IACrD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sCAAsC;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY;IACZ,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sCAAsC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAOtD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,GAAE,MAA0C,GAAG,MAAM,CAOpH;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAS/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWlE"}