@lerianstudio/matcher-mcp 1.3.0 → 1.4.0-beta.2

package/dist/observability/otel.js

@@ -19,8 +19,14 @@
 // Token-relay rule (NON-NEGOTIABLE): telemetry records ONLY the tool name, the
 // call outcome (ok / error), and — on a matcher API failure — the matcher HTTP
 // status. It NEVER records the caller's bearer token, raw arguments, or request
-// headers, in any span attribute, metric attribute, event, or log. No tenant
-// identifier is read or emitted anywhere.
+// headers, in any span attribute, metric attribute, event, or log.
+//
+// Tenant labelling (copilot loop, task 4.2.1): the copilot span tree MAY carry a
+// `copilot.tenant` attribute — the UNVERIFIED, key-only org identifier decoded
+// from the relayed JWT (getRequestTenantId). It is an organization label for
+// scoping/aggregation, token-free and not a credential; matcher still owns
+// enforcement via the relayed token. It is kept on SPANS only (per-turn), never
+// pushed as a metric label (cardinality), and NEVER accompanies a token/secret.
 import { context, metrics, propagation, SpanStatusCode, trace, ValueType, } from '@opentelemetry/api';
 import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
@@ -35,6 +41,17 @@ const INSTRUMENTATION_SCOPE = 'matcher-mcp';
 const ATTR_TOOL_NAME = 'mcp.tool.name';
 const ATTR_OUTCOME = 'mcp.tool.outcome';
 const ATTR_MATCHER_STATUS = 'matcher.http.status';
+/**
+ * Copilot-loop attribute keys (task 4.2.1). `copilot.tenant` is the key-only org
+ * identifier — a span label only, never a metric label or a credential.
+ */
+const ATTR_COPILOT_PROVIDER = 'copilot.provider';
+const ATTR_COPILOT_MODEL = 'copilot.model';
+const ATTR_COPILOT_TENANT = 'copilot.tenant';
+const ATTR_COPILOT_MAX_ITERATIONS = 'copilot.max_iterations';
+const ATTR_COPILOT_STOP = 'copilot.stop';
+const ATTR_COPILOT_TOOL_OUTCOME = 'copilot.tool.outcome';
+const ATTR_COPILOT_TOKEN_DIRECTION = 'copilot.token.direction';
 /** Outcome attribute values — the only two states a tool call reports. */
 const OUTCOME_OK = 'ok';
 const OUTCOME_ERROR = 'error';
@@ -205,6 +222,171 @@ export async function instrumentToolCall(name, fn) {
         }
     });
 }
+// --- Copilot agent-loop instrumentation (task 4.2.1) ---------------------------
+//
+// The copilot loop opens a `copilot.turn` parent span with `copilot.provider.stream`
+// and `copilot.tool.<name>` children. Wrapping the tool execution in an ACTIVE
+// child span ALSO fixes the previously-dead matcher trace correlation: with a
+// span active, `injectTraceContext` in the matcher client writes a real
+// traceparent instead of an empty context.
+//
+// The tool wrapper deliberately does NOT reuse `instrumentToolCall`: the copilot
+// read executor (`executeReadTool`) swallows every error into an `isError` result
+// rather than throwing, so `instrumentToolCall`'s catch never fires and every
+// span would falsely read `ok`. `instrumentCopilotTool` inspects the returned
+// result's `isError` instead.
+/** Lazily-created copilot metrics, shared across turns (no-op when telemetry off). */
+let copilotTurnCounter;
+let copilotTurnDuration;
+let copilotTokenCounter;
+function getCopilotTurnCounter() {
+    copilotTurnCounter ??= getMeter().createCounter('copilot.turns', {
+        description: 'Count of copilot agent turns, labeled by provider + stop reason.',
+        valueType: ValueType.INT,
+    });
+    return copilotTurnCounter;
+}
+function getCopilotTurnDuration() {
+    copilotTurnDuration ??= getMeter().createHistogram('copilot.turn.duration', {
+        description: 'Latency of a copilot agent turn in milliseconds.',
+        unit: 'ms',
+        valueType: ValueType.DOUBLE,
+    });
+    return copilotTurnDuration;
+}
+function getCopilotTokenCounter() {
+    copilotTokenCounter ??= getMeter().createCounter('copilot.tokens', {
+        description: 'Copilot LLM token usage, labeled by provider + direction (input/output).',
+        valueType: ValueType.INT,
+    });
+    return copilotTokenCounter;
+}
+/**
+ * Wrap one agent turn in a `copilot.turn` active parent span + turn metrics. The
+ * span carries provider/model/tenant/max_iterations and, set on exit via the
+ * `setStop` callback, `copilot.stop` (`end` | `proposal` | `token_limit` |
+ * `iteration_limit` | `aborted`). Records `copilot.turns` + `copilot.turn.duration`
+ * labeled by provider + stop (tenant is NOT a metric label — cardinality). No-op
+ * safe: with telemetry disabled this is just `fn(setStop)`.
+ */
+export async function instrumentCopilotTurn(attrs, fn) {
+    const tracer = getTracer();
+    const counter = getCopilotTurnCounter();
+    const histogram = getCopilotTurnDuration();
+    const startedAt = Date.now();
+    let stop = 'end';
+    const setStop = (next) => {
+        stop = next;
+    };
+    return tracer.startActiveSpan('copilot.turn', async (span) => {
+        span.setAttribute(ATTR_COPILOT_PROVIDER, attrs.provider);
+        if (attrs.model !== undefined) {
+            span.setAttribute(ATTR_COPILOT_MODEL, attrs.model);
+        }
+        if (attrs.tenant !== undefined) {
+            span.setAttribute(ATTR_COPILOT_TENANT, attrs.tenant);
+        }
+        span.setAttribute(ATTR_COPILOT_MAX_ITERATIONS, attrs.maxIterations);
+        try {
+            await fn(setStop);
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        catch (err) {
+            // A crashed turn is its own terminal label: without this it defaults to
+            // 'end' and records under the clean-completion series, hiding the error
+            // rate in the very copilot.turns counter that scopes it.
+            stop = 'error';
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw err;
+        }
+        finally {
+            span.setAttribute(ATTR_COPILOT_STOP, stop);
+            counter.add(1, { [ATTR_COPILOT_PROVIDER]: attrs.provider, [ATTR_COPILOT_STOP]: stop });
+            histogram.record(Date.now() - startedAt, { [ATTR_COPILOT_PROVIDER]: attrs.provider });
+            span.end();
+        }
+    });
+}
+/**
+ * Wrap one provider round-trip in a `copilot.provider.stream` child span. Records
+ * only provider/model (no prompt content, no token). No-op safe.
+ */
+export async function instrumentProviderStream(attrs, fn) {
+    const tracer = getTracer();
+    return tracer.startActiveSpan('copilot.provider.stream', async (span) => {
+        span.setAttribute(ATTR_COPILOT_PROVIDER, attrs.provider);
+        if (attrs.model !== undefined) {
+            span.setAttribute(ATTR_COPILOT_MODEL, attrs.model);
+        }
+        try {
+            const result = await fn();
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Wrap one tool execution in a `copilot.tool.<name>` active child span. The tool
+ * result is inspected for `isError` (the read executor never throws — it swallows
+ * every error into `isError`), so a swallowed matcher failure records
+ * `outcome=error`, not a false `ok`. The active span also gives the inner matcher
+ * HTTP call a real parent for trace correlation. No-op safe. Rethrows only on an
+ * unexpected throw (defensive; the executor does not throw).
+ */
+export async function instrumentCopilotTool(name, fn) {
+    const tracer = getTracer();
+    return tracer.startActiveSpan(`copilot.tool.${name}`, async (span) => {
+        span.setAttribute(ATTR_TOOL_NAME, name);
+        try {
+            const result = await fn();
+            const outcome = result.isError === true ? OUTCOME_ERROR : OUTCOME_OK;
+            span.setAttribute(ATTR_COPILOT_TOOL_OUTCOME, outcome);
+            span.setStatus({
+                code: result.isError === true ? SpanStatusCode.ERROR : SpanStatusCode.OK,
+            });
+            return result;
+        }
+        catch (err) {
+            span.setAttribute(ATTR_COPILOT_TOOL_OUTCOME, OUTCOME_ERROR);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Record a round's token usage on the `copilot.tokens` counter, split by
+ * direction (input/output) and labeled by provider. A no-op when usage is
+ * undefined (a provider that omits it) — metering fails open, never throws.
+ */
+export function recordCopilotTokens(provider, usage) {
+    if (usage === undefined) {
+        return;
+    }
+    const counter = getCopilotTokenCounter();
+    // Coalesce a non-finite field to 0 — symmetric with the running-sum path's
+    // usageTokens (agent.ts). Providers already coalesce, so this is defense in
+    // depth: a misreporting NaN/±Infinity never reaches the counter as NaN.
+    const input = Number.isFinite(usage.inputTokens) ? usage.inputTokens : 0;
+    const output = Number.isFinite(usage.outputTokens) ? usage.outputTokens : 0;
+    counter.add(input, {
+        [ATTR_COPILOT_PROVIDER]: provider,
+        [ATTR_COPILOT_TOKEN_DIRECTION]: 'input',
+    });
+    counter.add(output, {
+        [ATTR_COPILOT_PROVIDER]: provider,
+        [ATTR_COPILOT_TOKEN_DIRECTION]: 'output',
+    });
+}
 /**
  * Inject the current W3C trace context into an outbound header object so the
  * matcher call is a child of the tool-call span (MCP → matcher correlation in

package/dist/observability/otel.js.map

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

package/dist/spec/openapi.yaml

@@ -3834,7 +3834,7 @@ components:
         droppedDuplicateReason:
           description: "Display-only explanation of why droppedDuplicateRows rows were dropped: names the (source, external_id) collapsing key and the field mapping to check so the count does not read as silent data loss. Empty unless droppedDuplicateRows > 0"
           examples:
-            - Rows repeated a (source, external_id) key already present in this source and were dropped under the keep-first policy.
+            - Rows repeated a (source, external_id) key already present in this source and were dropped as duplicates. If unexpected, verify the field mapped to external_id is unique per row (a coarse or truncated mapping collapses distinct rows onto one key).
           type: string
         droppedDuplicateRows:
           description: Number of rows dropped as duplicates under the keep-first policy (same external_id within the upload or already persisted)
@@ -6279,6 +6279,66 @@ components:
       required:
         - total
       type: object
+    SetupProgressNextResponse:
+      additionalProperties: false
+      properties:
+        action:
+          description: Stable semantic label of the action.
+          enum:
+            - add_left_source
+            - add_right_source
+            - add_field_map
+            - add_match_rule
+          examples:
+            - add_left_source
+          type: string
+        forSource:
+          $ref: "#/components/schemas/SetupProgressSourceRef"
+          description: Source the action targets; set only for the field_maps action, naming the unmapped source.
+        method:
+          description: HTTP method of the create endpoint.
+          examples:
+            - POST
+          type: string
+        operationId:
+          description: OpenAPI operationId of the create endpoint to call.
+          examples:
+            - createSource
+          type: string
+        path:
+          description: Path template of the create endpoint.
+          examples:
+            - /v1/contexts/{contextId}/sources
+          type: string
+        requiredFields:
+          description: Names of the fields the create request requires; the caller supplies the values.
+          examples:
+            - - name
+              - type
+              - side
+          items:
+            type: string
+          type:
+            - array
+            - "null"
+        slug:
+          description: Readiness slug this action satisfies.
+          enum:
+            - sources_left
+            - sources_right
+            - field_maps
+            - match_rules
+          examples:
+            - sources_left
+          type: string
+      required:
+        - slug
+        - action
+        - operationId
+        - method
+        - path
+        - requiredFields
+      type: object
     SetupProgressReadinessResponse:
       additionalProperties: false
       properties:
@@ -6318,6 +6378,9 @@ components:
         matchRules:
           $ref: "#/components/schemas/SetupProgressMatchRulesResponse"
           description: Match-rule count for the context.
+        next:
+          $ref: "#/components/schemas/SetupProgressNextResponse"
+          description: Deterministic next setup action derived from readiness; null when the context is ready.
         readiness:
           $ref: "#/components/schemas/SetupProgressReadinessResponse"
           description: Activation readiness summary.
@@ -6346,6 +6409,7 @@ components:
         - schedules
         - lastRun
         - readiness
+        - next
       type: object
     SetupProgressSchedulesResponse:
       additionalProperties: false
@@ -6359,6 +6423,23 @@ components:
       required:
         - total
       type: object
+    SetupProgressSourceRef:
+      additionalProperties: false
+      properties:
+        id:
+          description: Identifier of the referenced source.
+          examples:
+            - 550e8400-e29b-41d4-a716-446655440000
+          type: string
+        name:
+          description: Human-readable name of the referenced source.
+          examples:
+            - Bank statement
+          type: string
+      required:
+        - id
+        - name
+      type: object
     SetupProgressSourcesResponse:
       additionalProperties: false
       properties:

package/dist/tools/context/create.js

@@ -106,7 +106,9 @@ export function registerContextCreateTool(server) {
             'open-item aging (agedBreakThresholdDays business-day SLA + ' +
             'agedBreakCalendar, e.g. BR_ANBIMA), and inline rules[] (≤50) / ' +
             'sources[] (≤10). Returns the created context, or a structured RFC 9457 ' +
-            'error.',
+            'error. A bare create is a DRAFT that cannot activate; after applying, ' +
+            'call next_step with the returned contextId and perform the action it ' +
+            'names, repeating until ready.',
         inputSchema: createContextInputShape,
     }, async (args, extra) => {
         return dispatchContext({ method: 'POST', path: CONTEXTS_PATH, body: args }, extra);

package/dist/tools/context/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/tools/context/create.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,mFAAmF;AACnF,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,+BAA+B;AAC/B,EAAE;AACF,iFAAiF;AACjF,8DAA8D;AAE9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAU,CAAA;AAE3D,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,CAAU,CAAA;AAE3D,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAElC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAA;AAEpC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,CAAC,kEAAkE,CAAC;IAC/E,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,aAAa,CAAC;SACnB,QAAQ,CACP,qEAAqE;QACnE,uEAAuE;QACvE,gEAAgE,CACnE;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,CACP,qEAAqE;QACnE,gBAAgB,CACnB;IACH,iBAAiB,EAAE,CAAC;SACjB,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE;QACtE,YAAY,CACf;IACH,gBAAgB,EAAE,CAAC;SAChB,IAAI,CAAC,kBAAkB,CAAC;SACxB,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE;QACtE,qCAAqC,CACxC;IACH,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,sEAAsE;QACpE,cAAc,CACjB;IACH,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,4EAA4E,CAC7E;IACH,sBAAsB,EAAE,CAAC;SACtB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACP,yEAAyE;QACvE,yEAAyE;QACzE,gCAAgC,CACnC;IACH,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,sEAAsE;QACpE,uEAAuE,CAC1E;IACH,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;SACxC,GAAG,CAAC,gBAAgB,CAAC;SACrB,QAAQ,EAAE;SACV,QAAQ,CACP,uEAAuE;QACrE,kEAAkE;QAClE,uCAAuC,CAC1C;IACH,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;SACxC,GAAG,CAAC,kBAAkB,CAAC;SACvB,QAAQ,EAAE;SACV,QAAQ,CACP,qEAAqE;QACnE,oEAAoE;QACpE,mCAAmC,CACtC;CACJ,CAAA;AAOD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,WAAW,EACT,iEAAiE;YACjE,yEAAyE;YACzE,oEAAoE;YACpE,wEAAwE;YACxE,iEAAiE;YACjE,kEAAkE;YAClE,6DAA6D;YAC7D,iEAAiE;YACjE,yEAAyE;YACzE,QAAQ;QACV,WAAW,EAAE,uBAAuB;KACrC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,eAAe,CACpB,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,EACnD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/tools/context/create.ts"],"names":[],"mappings":"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"}

package/dist/tools/context/index.js

@@ -15,14 +15,16 @@
 import { registerContextCreateTool } from './create.js';
 import { registerContextGetTool } from './get.js';
 import { registerContextListTool } from './list.js';
+import { registerContextNextStepTool } from './next-step.js';
 import { registerContextSetupProgressTool } from './setup-progress.js';
 import { registerContextUpdateTool } from './update.js';
-/** Register all five curated context tools on the given server. */
+/** Register all six curated context tools on the given server. */
 export function registerContextTools(server) {
     registerContextCreateTool(server);
     registerContextListTool(server);
     registerContextGetTool(server);
     registerContextUpdateTool(server);
     registerContextSetupProgressTool(server);
+    registerContextNextStepTool(server);
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/context/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/context/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,0EAA0E;AAC1E,qEAAqE;AACrE,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,sDAAsD;AACtD,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,iEAAiE;AACjE,4DAA4D;AAI5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAEvD,mEAAmE;AACnE,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,yBAAyB,CAAC,MAAM,CAAC,CAAA;IACjC,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAC/B,sBAAsB,CAAC,MAAM,CAAC,CAAA;IAC9B,yBAAyB,CAAC,MAAM,CAAC,CAAA;IACjC,gCAAgC,CAAC,MAAM,CAAC,CAAA;AAC1C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/context/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,0EAA0E;AAC1E,qEAAqE;AACrE,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,sDAAsD;AACtD,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,iEAAiE;AACjE,4DAA4D;AAI5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAEvD,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,yBAAyB,CAAC,MAAM,CAAC,CAAA;IACjC,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAC/B,sBAAsB,CAAC,MAAM,CAAC,CAAA;IAC9B,yBAAyB,CAAC,MAAM,CAAC,CAAA;IACjC,gCAAgC,CAAC,MAAM,CAAC,CAAA;IACxC,2BAA2B,CAAC,MAAM,CAAC,CAAA;AACrC,CAAC"}

package/dist/tools/context/next-step.js

@@ -0,0 +1,93 @@
+// `next_step` — curated GET /v1/contexts/{contextId}/setup-progress projected
+// to the ONE thing an operator-driving LLM needs to advance setup:
+// `{ ready, next, thenCall }`.
+//
+// `context_setup_progress` already relays the FULL setup-progress blob (counts,
+// last-run, readiness, next), so this tool's value is NOT "make `next` visible"
+// — it is the focused shape plus the auto-conduction (`thenCall`) that tells the
+// caller to loop. The auto-conduction is the only agent-specific knowledge here
+// and it is STATIC (no per-context values are ever invented): the deterministic
+// `next` action itself comes verbatim from the backend readiness gate (Phase 1).
+//
+// Because it projects, it does NOT use the shared dispatchContext stringify-
+// everything path; it resolves the client the same fail-closed way
+// (requireMatcherClient) and maps a matcher error through the SAME toToolError as
+// its siblings. contextId is the only input (a UUID path param); no tenant field
+// is accepted (matcher scopes to the relayed token's tenant).
+import { z } from 'zod';
+import { requireMatcherClient, UnauthenticatedError, } from '../../auth/request-token.js';
+import { isMatcherApiError, toToolError } from '../tool-error.js';
+import { contextSetupProgressPath } from './setup-progress.js';
+/**
+ * Static auto-conduction string returned alongside a non-null `next`. It never
+ * carries per-context values — just the loop instruction. The concrete action to
+ * take is the backend `next`, not this string.
+ */
+export const NEXT_STEP_CONDUCTION = 'After applying this action, call next_step again with the same contextId to ' +
+    'get the following step. Repeat until ready is true.';
+/** Zod raw shape for `next_step` input — just the context id. */
+export const nextStepInputShape = {
+    contextId: z
+        .string()
+        .min(1)
+        .describe('The reconciliation context id (UUID) to get the next setup step for.'),
+};
+/**
+ * Register `next_step`. Fetches setup-progress through the fail-closed relay and
+ * projects it to `{ ready, next, thenCall }`. A matcher error (e.g. 404) surfaces
+ * via the shared toToolError; a missing credential fails closed identically to
+ * the sibling context tools.
+ */
+export function registerContextNextStepTool(server) {
+    server.registerTool('next_step', {
+        description: 'Get the deterministic next setup action for a context, projected from ' +
+            'its readiness gate. Provide contextId (UUID path param, not a tenant ' +
+            'field). Returns { ready, next, thenCall }: ready is true only when the ' +
+            'context satisfies every activation requirement; next is the exact ' +
+            'action to take (slug, action, operationId, method, path, requiredFields ' +
+            '— field NAMES only, never values; you supply the values), or null when ' +
+            'ready; thenCall instructs you to apply next and call next_step again ' +
+            'with the same contextId, repeating until ready is true (null when ' +
+            'ready). Prefer this over context_setup_progress when you just need the ' +
+            'next action to advance setup. Returns a structured RFC 9457 error on ' +
+            'failure (e.g. 404 if the context does not exist or is not yours).',
+        inputSchema: nextStepInputShape,
+    }, async (args, extra) => {
+        let client;
+        try {
+            // Fail-closed on a missing / empty / non-Bearer credential.
+            client = requireMatcherClient(extra);
+        }
+        catch (err) {
+            if (err instanceof UnauthenticatedError) {
+                return { isError: true, content: [{ type: 'text', text: err.message }] };
+            }
+            throw err;
+        }
+        try {
+            const body = await client.request({
+                method: 'GET',
+                path: contextSetupProgressPath(args.contextId),
+            });
+            // Nil-safe projection: a malformed body (missing readiness) defaults to
+            // not-ready rather than throwing. `next` is relayed verbatim.
+            const ready = body?.readiness?.ready ?? false;
+            const next = body?.next ?? null;
+            const thenCall = next ? NEXT_STEP_CONDUCTION : null;
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify({ ready, next, thenCall }) },
+                ],
+            };
+        }
+        catch (err) {
+            // RFC 9457 problem → the SHARED structured tool error. A non-matcher
+            // error is a bug, not a matcher failure, and is re-thrown.
+            if (isMatcherApiError(err)) {
+                return toToolError(err);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=next-step.js.map

package/dist/tools/context/next-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-step.js","sourceRoot":"","sources":["../../../src/tools/context/next-step.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mEAAmE;AACnE,+BAA+B;AAC/B,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,EAAE;AACF,6EAA6E;AAC7E,mEAAmE;AACnE,kFAAkF;AAClF,iFAAiF;AACjF,8DAA8D;AAE9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,8EAA8E;IAC9E,qDAAqD,CAAA;AAEvD,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,sEAAsE,CAAC;CACpF,CAAA;AAWD;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,CAAC,YAAY,CACjB,WAAW,EACX;QACE,WAAW,EACT,wEAAwE;YACxE,uEAAuE;YACvE,yEAAyE;YACzE,oEAAoE;YACpE,0EAA0E;YAC1E,yEAAyE;YACzE,uEAAuE;YACvE,oEAAoE;YACpE,yEAAyE;YACzE,uEAAuE;YACvE,mEAAmE;QACrE,WAAW,EAAE,kBAAkB;KAChC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,IAAI,MAAM,CAAA;QACV,IAAI,CAAC;YACH,4DAA4D;YAC5D,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAA;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;gBACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAA;YAC1E,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAoB;gBACnD,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,SAAS,CAAC;aAC/C,CAAC,CAAA;YACF,wEAAwE;YACxE,8DAA8D;YAC9D,MAAM,KAAK,GAAG,IAAI,EAAE,SAAS,EAAE,KAAK,IAAI,KAAK,CAAA;YAC7C,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,IAAI,CAAA;YAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAA;YACnD,OAAO;gBACL,OAAO,EAAE;oBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE;iBAClE;aACF,CAAA;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,2DAA2D;YAC3D,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,OAAO,WAAW,CAAC,GAAG,CAAC,CAAA;YACzB,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/source/create.js

@@ -74,7 +74,9 @@ export function registerSourceCreateTool(server) {
             'optional type-specific config object (validated server-side; defaults ' +
             'to an empty object when omitted). The source is ' +
             "created for your token's tenant (no tenant field is accepted). Returns " +
-            'the created source, or a structured RFC 9457 error.',
+            'the created source, or a structured RFC 9457 error. Adding a source ' +
+            'rarely completes setup on its own; after applying, call next_step with ' +
+            'that contextId and perform the action it names, repeating until ready.',
         inputSchema: createSourceInputShape,
     }, async (args, extra) => {
         return dispatchSource({

package/dist/tools/source/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/tools/source/create.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,iFAAiF;AACjF,6EAA6E;AAC7E,gFAAgF;AAChF,mBAAmB;AACnB,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEhE,+FAA+F;AAC/F,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,MAAM;IACN,SAAS;IACT,QAAQ;IACR,SAAS;CACD,CAAA;AAEV,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,OAAO,CAAU,CAAA;AAEtD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,wEAAwE;QACtE,yEAAyE;QACzE,iCAAiC,CACpC;IACH,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,CAAC,iDAAiD,CAAC;IAC9D,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,YAAY,CAAC;SAClB,QAAQ,CACP,2EAA2E;QACzE,0EAA0E;QAC1E,qCAAqC,CACxC;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,YAAY,CAAC;SAClB,QAAQ,CACP,oEAAoE;QAClE,gCAAgC,CACnC;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CACP,0EAA0E;QACxE,sEAAsE;QACtE,gEAAgE,CACnE;CACJ,CAAA;AAOD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAuB;IAEvB,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,UAAU,CAAA;IACf,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAiB;IACxD,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EACT,oEAAoE;YACpE,4DAA4D;YAC5D,kEAAkE;YAClE,wEAAwE;YACxE,kDAAkD;YAClD,yEAAyE;YACzE,qDAAqD;QACvD,WAAW,EAAE,sBAAsB;KACpC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,cAAc,CACnB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC;YACxC,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC;SAC5B,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/tools/source/create.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,iFAAiF;AACjF,6EAA6E;AAC7E,gFAAgF;AAChF,mBAAmB;AACnB,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEhE,+FAA+F;AAC/F,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,MAAM;IACN,SAAS;IACT,QAAQ;IACR,SAAS;CACD,CAAA;AAEV,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,OAAO,CAAU,CAAA;AAEtD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,wEAAwE;QACtE,yEAAyE;QACzE,iCAAiC,CACpC;IACH,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,CAAC,iDAAiD,CAAC;IAC9D,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,YAAY,CAAC;SAClB,QAAQ,CACP,2EAA2E;QACzE,0EAA0E;QAC1E,qCAAqC,CACxC;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,YAAY,CAAC;SAClB,QAAQ,CACP,oEAAoE;QAClE,gCAAgC,CACnC;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CACP,0EAA0E;QACxE,sEAAsE;QACtE,gEAAgE,CACnE;CACJ,CAAA;AAOD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAuB;IAEvB,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,UAAU,CAAA;IACf,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAiB;IACxD,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EACT,oEAAoE;YACpE,4DAA4D;YAC5D,kEAAkE;YAClE,wEAAwE;YACxE,kDAAkD;YAClD,yEAAyE;YACzE,sEAAsE;YACtE,yEAAyE;YACzE,wEAAwE;QAC1E,WAAW,EAAE,sBAAsB;KACpC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,cAAc,CACnB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC;YACxC,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC;SAC5B,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/transport/body-limit.js

@@ -79,4 +79,31 @@ export class BodySizeGuard {
         }
     }
 }
+/**
+ * Read the request body and return it as a string, bounded by `maxBodyBytes`.
+ * The SDK's Node transport can parse the body itself, but reading it here lets
+ * callers pass a pre-parsed JSON body and keeps the handler in control of
+ * malformed input — and, critically, lets us cap an unbounded read.
+ *
+ * The size guard is checked BEFORE each chunk is retained, so an over-limit
+ * payload is rejected (via `BodyTooLargeError`) without ever buffering more than
+ * the limit (+ one chunk) of an attacker's body. The guard counts only bytes —
+ * it never inspects body content, headers, or any token.
+ *
+ * Lives here (next to `BodySizeGuard`, which it uses) rather than in
+ * `transport/http.ts` so the copilot's `turns-handler.ts` can import it without
+ * creating an import cycle with `http.ts` (which imports the turns handler).
+ */
+export async function readBody(req, maxBodyBytes) {
+    const guard = new BodySizeGuard(maxBodyBytes);
+    const chunks = [];
+    for await (const chunk of req) {
+        const buf = chunk;
+        // Throws BodyTooLargeError the moment the running total exceeds the limit,
+        // before the over-limit chunk is appended to memory.
+        guard.add(buf.length);
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 //# sourceMappingURL=body-limit.js.map

package/dist/transport/body-limit.js.map

@@ -1 +1 @@
-{"version":3,"file":"body-limit.js","sourceRoot":"","sources":["../../src/transport/body-limit.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,8CAA8C;AAE9C,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAA,CAAC,QAAQ;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAExC;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,kEAAkE;IACzD,MAAM,GAAG,GAAG,CAAA;IACrB,wCAAwC;IAC/B,UAAU,CAAQ;IAC3B,2DAA2D;IAClD,aAAa,CAAQ;IAE9B,YAAY,UAAkB,EAAE,aAAqB;QACnD,KAAK,CACH,4BAA4B,UAAU,cAAc;YAClD,sBAAsB,aAAa,SAAS,CAC/C,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;IACpC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IACP,YAAY,CAAQ;IAC7B,KAAK,GAAG,CAAC,CAAA;IAEjB,YAAY,eAAuB,sBAAsB;QACvD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CACb,yBAAyB,YAAY,gCAAgC,CACtE,CAAA;QACH,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAED,gCAAgC;IAChC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,WAAmB;QACrB,IAAI,CAAC,KAAK,IAAI,WAAW,CAAA;QACzB,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACnC,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"body-limit.js","sourceRoot":"","sources":["../../src/transport/body-limit.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,8CAA8C;AAI9C,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAA,CAAC,QAAQ;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAExC;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,kEAAkE;IACzD,MAAM,GAAG,GAAG,CAAA;IACrB,wCAAwC;IAC/B,UAAU,CAAQ;IAC3B,2DAA2D;IAClD,aAAa,CAAQ;IAE9B,YAAY,UAAkB,EAAE,aAAqB;QACnD,KAAK,CACH,4BAA4B,UAAU,cAAc;YAClD,sBAAsB,aAAa,SAAS,CAC/C,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;IACpC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IACP,YAAY,CAAQ;IAC7B,KAAK,GAAG,CAAC,CAAA;IAEjB,YAAY,eAAuB,sBAAsB;QACvD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CACb,yBAAyB,YAAY,gCAAgC,CACtE,CAAA;QACH,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAED,gCAAgC;IAChC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,WAAmB;QACrB,IAAI,CAAC,KAAK,IAAI,WAAW,CAAA;QACzB,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACnC,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAoB,EAAE,YAAoB;IACvE,MAAM,KAAK,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAe,CAAA;QAC3B,2EAA2E;QAC3E,qDAAqD;QACrD,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACrB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAClB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC"}