crewly 1.20.194 → 1.20.196

package/dist/backend/backend/src/services/trace/trace-http.middleware.js

@@ -0,0 +1,176 @@
+/**
+ * Run trace HTTP middleware (mounted first in `createApiRoutes`).
+ *
+ * - **Skill calls.** Skills call the backend with `X-Agent-Session`. When that
+ *   session's turn has a trace, the call is recorded on `finish`:
+ *   `skill.call` (2xx/3xx), `guard.block` (403/409/423/429) or `error`
+ *   (other 4xx/5xx), with `refs.skill = "<METHOD> <path>"` and the response's
+ *   `error` text. No skill sends anything extra.
+ * - **Agent → agent.** A message-mode write to `/terminal/:to/write|deliver`
+ *   from an agent session gets the sender's `[TRACE:…]` appended, so the
+ *   receiving turn joins the trace however the message is queued. The marker
+ *   is skipped when it would push the text over the terminal input limit.
+ * - **Activity.** Every agent call keeps the session's trace from ending on
+ *   the idle gap.
+ * - **Owner actions** (#984). An owner write (an owner credential — the
+ *   dashboard session, relay or API token, #999; POST/PUT/PATCH/DELETE that succeeded) whose path names
+ *   an entity of a trace is recorded there as `owner.action` — a manual
+ *   intervention in the autonomy metrics.
+ *
+ * Never fails a request: every step is wrapped.
+ *
+ * specs/2026-10-03-run-traces.md
+ *
+ * @module services/trace/trace-http.middleware
+ */
+import { TRACE_CONSTANTS } from '../../constants.js';
+import { isOwnerDashboardRequest, readAgentSessionHeader } from '../../utils/agent-caller.utils.js';
+import { getTraceContext } from './trace-context.service.js';
+import { skillLabel } from './trace-markers.js';
+import { carryAgentMessageTrace, traceOwnerAction } from './trace-recorder.js';
+/** `/terminal/<session>/write|deliver` relative to /api. */
+const TERMINAL_MESSAGE_PATH = /^\/terminal\/([^/]+)\/(write|deliver)\/?$/;
+/**
+ * Path of the request relative to `/api` (works mounted at `/api` or below).
+ *
+ * @param req - Request
+ * @returns e.g. `/task-pool/add`
+ */
+function apiPath(req) {
+    const full = (req.originalUrl || req.url || '').split('?')[0];
+    const idx = full.indexOf('/api/');
+    return idx >= 0 ? full.slice(idx + '/api'.length) : full;
+}
+/**
+ * Append the sender's trace to an agent → agent message body.
+ *
+ * @param req - Request (body mutated)
+ * @param sender - Calling agent session
+ * @param path - Path relative to /api
+ */
+function carryAgentMessage(req, sender, path) {
+    if (req.method !== 'POST')
+        return;
+    const m = TERMINAL_MESSAGE_PATH.exec(path);
+    if (!m)
+        return;
+    const target = decodeURIComponent(m[1]);
+    const body = req.body;
+    if (!body || typeof body !== 'object')
+        return;
+    if (m[2] === 'write') {
+        if (body.mode !== 'message' || typeof body.data !== 'string')
+            return;
+        body.data = carryAgentMessageTrace(sender, target, body.data);
+    }
+    else if (typeof body.message === 'string') {
+        body.message = carryAgentMessageTrace(sender, target, body.message);
+    }
+}
+/**
+ * Event type and outcome for a response status.
+ *
+ * @param status - HTTP status
+ * @returns Type and outcome
+ */
+export function classifySkillStatus(status) {
+    if (status < 400)
+        return { type: 'skill.call', outcome: status === 202 ? 'queued' : 'ok' };
+    if (TRACE_CONSTANTS.GUARD_BLOCK_STATUSES.includes(status))
+        return { type: 'guard.block', outcome: 'blocked' };
+    return { type: 'error', outcome: 'failed' };
+}
+/** Methods that change something. */
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/**
+ * Record a successful dashboard write on a traced entity as `owner.action`.
+ *
+ * @param req - Request (an owner credential — #999)
+ * @param res - Response
+ */
+function watchOwnerAction(req, res) {
+    if (!WRITE_METHODS.has(req.method.toUpperCase()) || !isOwnerDashboardRequest(req))
+        return;
+    const path = apiPath(req);
+    if (TRACE_CONSTANTS.SKIPPED_SKILL_PATH_PREFIXES.some((p) => path === p || path.startsWith(`${p}/`)))
+        return;
+    res.once('finish', () => {
+        try {
+            if (res.statusCode >= 400)
+                return;
+            traceOwnerAction({ method: req.method, path, status: res.statusCode });
+        }
+        catch {
+            // Recording is best-effort.
+        }
+    });
+}
+/**
+ * Express middleware; see the module doc.
+ *
+ * @param req - Request
+ * @param res - Response
+ * @param next - Next handler
+ */
+export function traceHttpMiddleware(req, res, next) {
+    try {
+        const session = readAgentSessionHeader(req);
+        if (!session) {
+            watchOwnerAction(req, res);
+            next();
+            return;
+        }
+        const path = apiPath(req);
+        // Any agent API call (hooks included) shows the session is still working,
+        // which keeps its current trace from ending on the idle gap.
+        getTraceContext().touch(session);
+        carryAgentMessage(req, session, path);
+        if (TRACE_CONSTANTS.SKIPPED_SKILL_PATH_PREFIXES.some((p) => path === p || path.startsWith(`${p}/`))) {
+            next();
+            return;
+        }
+        const ctx = getTraceContext();
+        const skill = skillLabel(req.method, path);
+        let errorText;
+        const originalJson = res.json.bind(res);
+        res.json = ((body) => {
+            try {
+                const err = body?.error;
+                if (typeof err === 'string')
+                    errorText = err;
+            }
+            catch {
+                // Reading the body is best-effort.
+            }
+            return originalJson(body);
+        });
+        const startedAt = Date.now();
+        res.once('finish', () => {
+            try {
+                // Looked up at the end: the call itself may have started the trace
+                // (a delegation materialises a pending owner-message root).
+                const traceId = ctx.currentTrace(session);
+                if (!traceId)
+                    return;
+                const { type, outcome } = classifySkillStatus(res.statusCode);
+                ctx.record({
+                    traceId,
+                    type,
+                    actor: { kind: 'agent', session },
+                    summary: type === 'skill.call' ? `${session} called ${skill}` : `${session} ${type === 'guard.block' ? 'was refused' : 'failed'} ${skill}: ${errorText ?? `HTTP ${res.statusCode}`}`,
+                    outcome,
+                    refs: { skill, session },
+                    data: { status: res.statusCode, ms: Date.now() - startedAt },
+                });
+            }
+            catch {
+                // Recording is best-effort.
+            }
+        });
+    }
+    catch {
+        // Tracing never fails a request.
+    }
+    next();
+}
+//# sourceMappingURL=trace-http.middleware.js.map

package/dist/backend/backend/src/services/trace/trace-http.middleware.js.map

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

package/dist/backend/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/backend/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"}

package/dist/backend/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/backend/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":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAkB,MAAM,kBAAkB,CAAC;AAE7D,yCAAyC;AACzC,MAAM,YAAY,GAAG,iCAAiC,CAAC;AAEvD,8BAA8B;AAC9B,MAAM,IAAI,GAAG,oEAAoE,CAAC;AAElF,8BAA8B;AAC9B,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC,4EAA4E;AAC5E,MAAM,SAAS,GAAG,6BAA6B,CAAC;AAEhD,qFAAqF;AACrF,MAAM,iBAAiB,GAAG,wEAAwE,CAAC;AAEnG,yEAAyE;AACzE,MAAM,cAAc,GAAG,wEAAwE,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAChD,OAAO,UAAU,OAAO,GAAG,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC7C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7C,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAkC;IACjF,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9F,OAAO,GAAG,IAAI,KAAK,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,qFAAqF;AACrF,MAAM,iBAAiB,GAAG,yEAAyE,CAAC;AAEpG,wDAAwD;AACxD,MAAM,mBAAmB,GAAG,qCAAqC,CAAC;AAElE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjG,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC3C,MAAM,IAAI,GAAG,CAAC,MAAwB,EAAY,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAClF,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3G,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAA+B,EAAE,MAAc,eAAe,CAAC,iBAAiB;IAC3G,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5G,uEAAuE;IACvE,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC,CAAC;IACnF,OAAO,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAyC;IACvE,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;aACrE,IAAI,OAAO,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;aACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAC;IAC7H,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,OAAe;IACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE;QACxD,IAAI,CAAC,GAAG;YAAE,OAAO,GAAG,CAAC;QACrB,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,UAAU;YAAE,OAAO,UAAU,CAAC;QACjD,IAAI,4BAA4B,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9G,IAAI,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvD,IAAI,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,OAAO,GAAG,CAAC;IACZ,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACxD,CAAC"}