crewly 1.20.194 → 1.20.196

package/dist/cli/backend/src/services/trace/trace-markers.js

@@ -0,0 +1,162 @@
+/**
+ * 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 { TRACE_CONSTANTS } from '../../constants.js';
+import { redactSensitive } from '../wiki/wiki-redaction.js';
+import { parseTicketMarkers } from '../../types/v2/ticket.types.js';
+import { isTraceId } from './trace.types.js';
+/** `[TRACE:tr-…]` anywhere in a text. */
+const TRACE_MARKER = /\[TRACE:(tr-\d{8}-[0-9a-f]+)\]/g;
+/** A UUID (work item ids). */
+const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+/** A decision id (`D-12`). */
+const DECISION_ID = /\bD-\d+\b/g;
+/** A project ticket id (`CE-7`, `APP-12`) or a Request label (`TKT-12`). */
+const TICKET_ID = /\b[A-Z][A-Z0-9]{1,9}-\d+\b/g;
+/** `…TOKEN=value`, `…_KEY=value`, `…SECRET=value`, `…PASSWORD=value` assignments. */
+const SECRET_ASSIGNMENT = /\b([A-Za-z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY))=(\S+)/gi;
+/** Routing prefixes the harness puts in front of a delivered message. */
+const ROUTING_PREFIX = /^\s*(\[(?:G?CHAT|SLACK|SLACK-THREAD|TICKET|TRACE|REMOTE):[^\]]*\]\s*)+/;
+/**
+ * The marker for a trace.
+ *
+ * @param traceId - Trace id
+ * @returns `[TRACE:<id>]`
+ */
+export function formatTraceMarker(traceId) {
+    return `[TRACE:${traceId}]`;
+}
+/**
+ * Trace ids named by `[TRACE:…]` markers in a text, in order, de-duplicated.
+ *
+ * @param text - Delivered text
+ * @returns Trace ids
+ */
+export function parseTraceMarkers(text) {
+    const out = [];
+    for (const m of text.matchAll(TRACE_MARKER)) {
+        if (isTraceId(m[1]) && !out.includes(m[1]))
+            out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * 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 function appendTraceMarker(text, traceId) {
+    if (!traceId || !isTraceId(traceId) || parseTraceMarkers(text).includes(traceId))
+        return text;
+    return `${text}\n${formatTraceMarker(traceId)}`;
+}
+/** A line holding only a marker (optionally labelled `Trace:`), with its newline. */
+const TRACE_MARKER_LINE = /^[ \t]*(?:Trace:[ \t]*)?\[TRACE:tr-\d{8}-[0-9a-f]+\][ \t]*(?:\r?\n|$)/gm;
+/** A marker inside a line, with one space before it. */
+const TRACE_MARKER_INLINE = /[ \t]?\[TRACE:tr-\d{8}-[0-9a-f]+\]/g;
+/**
+ * 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 function stripTraceMarkers(text) {
+    if (typeof text !== 'string' || !text.includes('[TRACE:'))
+        return text;
+    return text.replace(TRACE_MARKER_LINE, '').replace(TRACE_MARKER_INLINE, '').replace(/\n+$/, '');
+}
+/**
+ * Every id in a text that the trace index might know.
+ *
+ * @param text - Delivered text
+ * @returns Ids by kind, each de-duplicated
+ */
+export function extractTextRefs(text) {
+    const uniq = (values) => [...new Set(values)];
+    const requestIds = uniq(parseTicketMarkers(text).map((r) => r.id));
+    const workItemIds = uniq([...text.matchAll(UUID)].map((m) => m[0].toLowerCase()));
+    const decisionIds = uniq([...text.matchAll(DECISION_ID)].map((m) => m[0]));
+    const ticketIds = uniq([...text.matchAll(TICKET_ID)].map((m) => m[0]).filter((id) => !/^D-\d+$/.test(id)));
+    return { requestIds, workItemIds, decisionIds, ticketIds };
+}
+/**
+ * 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 function safeSummary(text, max = TRACE_CONSTANTS.SUMMARY_MAX_CHARS) {
+    if (!text)
+        return '';
+    const flat = String(text).replace(ROUTING_PREFIX, '').replace(TRACE_MARKER, '').replace(/\s+/g, ' ').trim();
+    // Pattern-only redaction (no constants read at import time, so modules
+    // that stub the constants in tests can still load this one).
+    const redacted = redactSensitive(flat.replace(SECRET_ASSIGNMENT, '$1=[REDACTED]'));
+    return redacted.length > max ? `${redacted.slice(0, max - 1)}…` : redacted;
+}
+/**
+ * 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 function cleanTraceData(data) {
+    if (!data)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            out[key] = value;
+        else if (typeof value === 'boolean')
+            out[key] = value;
+        else if (typeof value === 'string' && value.length > 0)
+            out[key] = safeSummary(value, TRACE_CONSTANTS.DATA_VALUE_MAX_CHARS);
+    }
+    return Object.keys(out).length > 0 ? out : 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 function skillLabel(method, apiPath) {
+    const pathOnly = apiPath.split('?')[0] || '/';
+    const segments = pathOnly.split('/').map((seg, i, all) => {
+        if (!seg)
+            return seg;
+        if (all[i - 1] === 'terminal')
+            return ':session';
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(seg) || /^\d+$/.test(seg) || /^[0-9a-f]{12,}$/i.test(seg))
+            return ':id';
+        if (/^[A-Z][A-Z0-9]{0,9}-\d+$/.test(seg))
+            return ':id';
+        if (isTraceId(seg))
+            return ':id';
+        return seg;
+    });
+    return `${method.toUpperCase()} ${segments.join('/')}`;
+}
+//# sourceMappingURL=trace-markers.js.map

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

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

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

@@ -0,0 +1,338 @@
+/**
+ * Run trace hooks: the one-line calls the rest of the backend makes to start
+ * traces, carry them onto entities, and record what happened.
+ *
+ * Every function here is fire-and-forget: it catches its own errors and never
+ * throws, so a trace problem can never break a turn, a delivery or a request.
+ *
+ * specs/2026-10-03-run-traces.md
+ *
+ * @module services/trace/trace-recorder
+ */
+import type { Request } from '../../types/v2/request.types.js';
+import type { WorkItem, WorkItemStatus } from '../../types/v2/work-item.types.js';
+import type { OwnerDecision } from '../../types/decision.types.js';
+import { type TraceEventType, type TraceOutcome, type TraceRefs } from './trace.types.js';
+/**
+ * The trace a session's turn is on (no pending root is materialised).
+ *
+ * @param session - Agent session
+ * @returns Trace id, or null
+ */
+export declare function currentTraceOf(session: string | null | undefined): string | null;
+/**
+ * The trace a session's turn is on; a waiting owner message becomes a root now
+ * because the turn is starting work.
+ *
+ * @param session - Agent session
+ * @returns Trace id, or null
+ */
+export declare function ensureTraceForSession(session: string | null | undefined): string | null;
+/**
+ * A message was written into an agent turn (PTY or in-process).
+ *
+ * @param session - Agent session
+ * @param text - Exactly what was delivered
+ * @param runtime - `pty` or `in-process`
+ * @returns The trace the turn is now on, or null
+ */
+export declare function noteTurnDelivery(session: string, text: string, runtime?: string): string | null;
+/**
+ * An in-process turn failed.
+ *
+ * @param session - Agent session
+ * @param error - What failed
+ */
+export declare function traceTurnError(session: string, error: unknown): void;
+/**
+ * An agent's turn became busy or idle; records `turn.ended` with the busy
+ * time when it ends (see {@link TraceContext.noteTurnActivity}).
+ *
+ * @param session - Agent session
+ * @param busy - True when the turn started, false when it ended
+ * @param runtime - `pty` or `in-process`
+ * @returns True when an event was recorded
+ */
+export declare function traceTurnActivity(session: string, busy: boolean, runtime?: string): boolean;
+/** Why a runtime stopped serving a session. */
+export type RuntimeBlockReason = 'usage_limit' | 'billing' | 'login';
+/**
+ * A session's runtime ran out of usage or credit, or its login expired:
+ * record `runtime.blocked` in the trace the session is on.
+ *
+ * @param session - Agent session
+ * @param reason - usage_limit, billing or login
+ * @param runtime - Runtime (target) that is blocked
+ * @param detail - Short detail (rule id, reset time)
+ * @returns True when recorded
+ */
+export declare function traceRuntimeBlocked(session: string, reason: RuntimeBlockReason, runtime: string, detail?: string): boolean;
+/**
+ * The subagent guard (#852) sent a no-op subagent of this session back to
+ * work: record `harness.subagent_sendback` in the session's trace.
+ *
+ * @param session - Parent agent session
+ * @returns True when recorded
+ */
+export declare function traceSubagentSendBack(session: string): boolean;
+/**
+ * The owner changed something from the dashboard (a write with no agent
+ * session): when a path segment is an entity the trace index knows, record
+ * `owner.action` in that trace — a manual intervention.
+ *
+ * @param input.method - HTTP method
+ * @param input.path - Path relative to /api
+ * @param input.status - Response status
+ * @returns The trace it was recorded in, or null
+ */
+export declare function traceOwnerAction(input: {
+    method: string;
+    path: string;
+    status: number;
+}): string | null;
+/**
+ * Start a goal or experiment trace (POST /api/traces, #986 experiment cards).
+ *
+ * @param input - Kind, summary, who, refs, session to bind
+ * @returns Trace id, or null
+ */
+export declare function startGoalTrace(input: {
+    kind: 'goal' | 'experiment';
+    summary: string;
+    session?: string;
+    refs?: TraceRefs;
+}): string | null;
+/**
+ * Give a new Request its trace (call before its first save): an explicit or
+ * creator trace, the parent ticket's trace, or a new `request` root. Sets
+ * `request.traceId` and records `request.created`.
+ *
+ * @param request - The Request about to be saved (mutated)
+ * @param opts.traceId - Trace to join (e.g. the creating agent's)
+ * @param opts.creatorSession - Agent creating it, when known
+ * @returns The trace id, or null
+ */
+export declare function assignRequestTrace(request: Request, opts?: {
+    traceId?: string;
+    creatorSession?: string;
+}): string | null;
+/**
+ * A Request (ticket) changed status: submitted for review, accepted, sent
+ * back, reopened, cancelled.
+ *
+ * @param request - The Request after the change
+ * @param previous - Its status before
+ */
+export declare function traceRequestStatus(request: Request, previous: string): void;
+/**
+ * A project ticket was created: link it to the trace of its Request or of the
+ * creating agent's turn, and record `ticket.created`.
+ *
+ * @param ticket - The ticket
+ * @param actor - Who created it (agent session, or a non-agent label)
+ * @returns The trace id, or null
+ */
+export declare function traceProjectTicketCreated(ticket: {
+    id: string;
+    title: string;
+    requestId?: string | null;
+    assignee?: string | null;
+}, actor: string): string | null;
+/**
+ * Give a work item its trace before it is stored. Order: its own `traceId`;
+ * the item it continues (parent / verify-of / source); its Request; its
+ * project ticket; the creating agent's turn. Sets `workItem.traceId`.
+ *
+ * @param workItem - The item (mutated)
+ * @param creatorSession - Agent creating it (X-Agent-Session), when known
+ * @returns The trace id, or null
+ */
+export declare function assignWorkItemTrace(workItem: WorkItem, creatorSession?: string): string | null;
+/**
+ * A work item entered the pool (PoolStorage.addWorkItem): fill in its trace if
+ * the caller did not, and record `workitem.created`.
+ *
+ * @param workItem - The stored item (mutated when its trace is filled in)
+ */
+export declare function traceWorkItemCreated(workItem: WorkItem): void;
+/**
+ * A work item changed status (PoolStorage.updateWorkItem). `running` is the
+ * claim.
+ *
+ * @param workItem - The item after the change
+ * @param previous - Its status before
+ */
+export declare function traceWorkItemStatus(workItem: WorkItem, previous: WorkItemStatus): void;
+/**
+ * The `[TRACE:…]` header line for a work item's prompt.
+ *
+ * @param workItem - The item
+ * @returns The marker, or '' when the item has no trace
+ */
+export declare function workItemTraceMarker(workItem: Pick<WorkItem, 'traceId'>): string;
+/**
+ * Append a work item's trace marker as the last line of a hand-over message,
+ * unless it is already there. Appended, never prepended: routing parsers
+ * anchor on the start of a delivered message (`[CHAT:…]`, `[TASK]`).
+ *
+ * @param message - The hand-over text
+ * @param workItem - The item handed over
+ * @returns The text with the marker last
+ */
+export declare function withWorkItemTraceMarker(message: string, workItem: Pick<WorkItem, 'traceId'>): string;
+/**
+ * One agent messaged another through `/terminal/:to/*`: return the text with
+ * the sender's trace appended so the receiving turn joins it, and record
+ * `message.agent`.
+ *
+ * @param sender - Sending agent session
+ * @param target - Receiving session
+ * @param text - Message text
+ * @param maxLength - Longest text the endpoint accepts; the marker is skipped when it would not fit
+ * @returns The text to deliver (unchanged when the sender has no trace)
+ */
+export declare function carryAgentMessageTrace(sender: string, target: string, text: string, maxLength?: number): string;
+/**
+ * A status report was routed. Returns the trace so the routed text can carry
+ * its marker.
+ *
+ * @param input.sender - Reporting agent
+ * @param input.content - Report text
+ * @param input.workItem - The work item it is about, if found
+ * @param input.action - Route (`orc`, `team-lead`, `digest`, `record`)
+ * @param input.target - Who receives it
+ * @returns The trace id, or null
+ */
+export declare function traceStatusRouted(input: {
+    sender: string;
+    content: string;
+    workItem?: Pick<WorkItem, 'id' | 'traceId'> | null;
+    action: string;
+    target?: string;
+}): string | null;
+/**
+ * Append the trace marker to a routed status text.
+ *
+ * @param text - Status text
+ * @param traceId - Trace (no-op when null)
+ * @returns The text with the marker last
+ */
+export declare function withTraceMarker(text: string, traceId: string | null): string;
+/** What the reply resolver did with an agent message (subset of ReplyDelivery). */
+export interface OutboundReplyResult {
+    ok: boolean;
+    error?: string;
+    messageId?: string;
+    conversationId?: string;
+    slackChannelId?: string;
+    messageTs?: string;
+    destination?: {
+        kind?: string;
+        source?: string;
+    };
+}
+/**
+ * The reply resolver (#954) delivered or refused an agent message.
+ *
+ * @param input.session - Agent
+ * @param input.content - Message text
+ * @param input.reference - The reference it named (ticket / work item / decision / message)
+ * @param result - The delivery
+ */
+export declare function traceOutboundReply(input: {
+    session: string;
+    content: string;
+    reference?: {
+        messageId?: string;
+        ticket?: string;
+        workItemId?: string;
+        decisionId?: string;
+    };
+}, result: OutboundReplyResult): void;
+/**
+ * A decision card was asked: link it to the trace of its work item, Request,
+ * project ticket or asker's turn, and record `decision.created`.
+ *
+ * @param decision - The stored decision
+ */
+export declare function traceDecisionCreated(decision: OwnerDecision): void;
+/**
+ * A decision changed state (answered, defaulted, cancelled, …).
+ *
+ * @param previous - Before
+ * @param next - After
+ */
+export declare function traceDecisionChanged(previous: Pick<OwnerDecision, 'status'>, next: OwnerDecision): void;
+/** Input of {@link traceHarness}. */
+export interface HarnessEventInput {
+    /** Session acted on */
+    session?: string;
+    workItemId?: string;
+    workItem?: Pick<WorkItem, 'id' | 'traceId'> | null;
+    /** Trace, when the caller knows it */
+    traceId?: string | null;
+    summary: string;
+    outcome?: TraceOutcome;
+    data?: Record<string, unknown>;
+}
+/**
+ * The harness intervened (redelivery, wake, correction, nudge, guard block):
+ * record it in the trace of the work item, else of the session's turn.
+ *
+ * @param type - Event type
+ * @param input - What and on whom
+ * @returns True when recorded
+ */
+export declare function traceHarness(type: Extract<TraceEventType, `harness.${string}` | 'guard.block'>, input: HarnessEventInput): boolean;
+/** A token-ledger entry (subset of TokenUsageEvent). */
+export interface UsageEntry {
+    timestamp: string;
+    input: number;
+    output: number;
+    model: string;
+    cachedInput?: number;
+    /** Cache-write tokens (part of cachedInput for Claude Code turns), for the cost */
+    cacheWrite?: number;
+    runtime?: string;
+}
+/**
+ * A token-ledger entry was recorded: find the trace the session was on at
+ * that time, record `usage`, and return the id to stamp on the entry.
+ *
+ * @param session - Agent session
+ * @param entry - The usage
+ * @returns Trace id, or null
+ */
+export declare function traceUsage(session: string, entry: UsageEntry): string | null;
+/** The part of an experiment card the trace needs. */
+export interface ExperimentTraceInput {
+    /** `EXP-n` */
+    id: string;
+    title: string;
+    /** The ticket it rides on: a project ticket id, or a TKT-n label / request id */
+    ticket?: {
+        kind: 'project' | 'harness';
+        id: string;
+    };
+}
+/**
+ * An experiment card was created: join its ticket's trace when the ticket
+ * has one, else start an `experiment` root. Links `experiment:<EXP-n>` (and
+ * the ticket) in the index.
+ *
+ * @param experiment - The new card
+ * @param caller - Who created it (agent session, or `owner`)
+ * @returns The trace id, or null
+ */
+export declare function startExperimentTrace(experiment: ExperimentTraceInput, caller: string): string | null;
+/**
+ * Mirror one experiment timeline entry (created, shipped, baseline, measured,
+ * verdict, …) into its trace.
+ *
+ * @param traceId - The card's trace
+ * @param experimentId - `EXP-n`
+ * @param event - Timeline event name
+ * @param detail - Optional detail
+ */
+export declare function traceExperimentEvent(traceId: string, experimentId: string, event: string, detail?: string): void;
+//# sourceMappingURL=trace-recorder.d.ts.map

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

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