@skaile/workspaces 0.8.5

package/dist/types/src/capabilities.d.ts

@@ -0,0 +1,398 @@
+/**
+ * Capability layer — Protocol v2's unified registry of LLM-invokable entry points.
+ *
+ * A {@link Capability} is a named, schema-typed entry point that the LLM can call
+ * during a session. Capabilities are registered into a per-session
+ * registry by either side (host platform via `side: 'client'` or runtime via
+ * `side: 'agent'`) and routed by the bridge at invocation time.
+ *
+ * This module defines the wire types only; the runtime registry, the
+ * `defineCapability` helper, and the per-handler logger live in
+ * `@skaile/workspaces/runner`.
+ *
+ * @see {@link MessageV2} envelope that carries capability commands and events
+ * @see {@link ProtocolVersion} for the version contract
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ */
+/**
+ * Visibility scope for a capability. Determines which surfaces the capability
+ * appears on and which callers can invoke it.
+ *
+ * - `'llm'`: registered as an LLM tool, surfaced in the `<CAPABILITIES>` system
+ *   prompt section. The agent driver can invoke it.
+ * - `'user'`: appears in user-facing surfaces — the command palette (cmdK),
+ *   debug menus, capability lists.
+ * - `'runtime'`: invocable only by trusted runner / platform code paths. Never
+ *   reaches the LLM tool list. Never reaches the command palette. Used for
+ *   host RPCs (`host.refresh_credential`, `host.audit`, `host.notify_user`,
+ *   `host.persist_compaction_attempt`) and runner RPCs (`runner.add_mount`,
+ *   `runner.set_log_level`, `runner.lifecycle`, ...).
+ *
+ * Multiple audiences are allowed (e.g. `['llm', 'user']`). The default when
+ * {@link Capability.audience} is omitted is `['llm', 'user']`, preserving the
+ * v2.x default visibility for capabilities that haven't migrated yet.
+ *
+ * @category Capabilities
+ * @since 3.0.0
+ * @docLink packages/types/capabilities#capability-audience
+ */
+export type CapabilityAudience = "llm" | "user" | "runtime";
+/**
+ * Source of truth for who registered a capability. Used for trust enforcement
+ * (the bridge rejects mismatches between registering side and origin kind)
+ * and for the `capability:<origin>:<name>` log taxonomy.
+ *
+ * Variants:
+ * - `framework`: built-in (e.g. `__capabilities.list`)
+ * - `client`: host platform (e.g. `platform.react`)
+ * - `agent`: self-registered by the agent runtime
+ * - `flow`: injected by an active flow execution
+ * - `skill`: from a skill's MCP surface
+ * - `mcp`: from a generic MCP server
+ * - `connector`: from a connector (e.g. `postgres.query`)
+ * - `mount`: surfaced by a filesystem mount
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-origin
+ */
+export type CapabilityOrigin = {
+    kind: "framework";
+} | {
+    kind: "client";
+} | {
+    kind: "agent";
+} | {
+    kind: "flow";
+    flowId: string;
+} | {
+    kind: "skill";
+    skillId: string;
+} | {
+    kind: "mcp";
+    serverId: string;
+} | {
+    kind: "connector";
+    connectorId: string;
+} | {
+    kind: "mount";
+    mountId: string;
+};
+/**
+ * Render contract for a capability that produces a UI surface when invoked.
+ *
+ * When the LLM invokes a capability whose `render` is set, the bridge emits
+ * a {@link RenderInvokedEvent} carrying the capability name and props. The
+ * client renders the configured `source` at the chosen `target`. Clients
+ * without a render layer can fall back to the markdown `fallback` template.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#render-spec
+ */
+export type RenderSpec = {
+    /** Where the rendered component lives. */
+    source: {
+        kind: "web-component";
+        url: string;
+        tagName: string;
+    } | {
+        kind: "iframe";
+        url: string;
+    };
+    /** Render placements supported by the component. */
+    targets: ("chat" | "preview" | "modal" | "input-extension")[];
+    /** Markdown template with `{{prop}}` placeholders for clients without a render layer. */
+    fallback?: string;
+    /** True when props may be partial during streaming. */
+    streaming?: boolean;
+    /** Interaction names the rendered component may fire back as state events. */
+    interactions?: string[];
+};
+/**
+ * A named, schema-typed entry point that the LLM can invoke during a session.
+ *
+ * Capabilities can be declared statically (via `ConfigureCommand.capabilities`)
+ * or dynamically (via {@link CapabilityRegisterCommand} /
+ * {@link CapabilityRegisterEvent}). They are cached for replay across
+ * subscriber reconnects and session hibernation.
+ *
+ * @example Defining a client-side fire-and-forget tool (uses the runner's
+ * `defineCapability` helper, which serializes a {@link Capability} to the wire):
+ * ```ts
+ * const reactTool = defineCapability({
+ *   name: 'platform.react',
+ *   description: 'Acknowledge a user message with a Unicode emoji.',
+ *   side: 'client',
+ *   origin: { kind: 'client' },
+ *   fireAndForget: true,
+ *   input: z.object({ emoji: z.string(), targetSeq: z.number().optional() }),
+ *   handler: async ({ emoji, targetSeq }, ctx) => { ... },
+ * });
+ * ```
+ *
+ * @see {@link RenderCapability} for capabilities that render UI components
+ * @see {@link CapabilityOrigin} for who-registered-it metadata
+ * @see {@link isRenderCapability} for the type-guard
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability
+ */
+export type Capability = {
+    /** Unique within a session. Convention: namespaced as `<origin>.<name>` (e.g. `platform.react`, `ui.gif`). */
+    name: string;
+    /**
+     * Human-readable label for user-facing surfaces (cmdK action palette,
+     * capability menus, debug panels). Falls back to {@link Capability.name}
+     * when omitted. Pure presentation — the LLM sees `name`, not `displayName`.
+     */
+    displayName?: string;
+    /** Human/LLM-readable summary. Shown to the LLM as part of tool registration. */
+    description: string;
+    /** JSON Schema validating the invocation arguments. Authored as Zod, converted at register time. */
+    inputSchema: Record<string, unknown>;
+    /** Optional return shape. Omit for fire-and-forget effects. */
+    outputSchema?: Record<string, unknown>;
+    /** Where the handler runs. `client` = host platform, `agent` = runtime/skill/connector. */
+    side: "client" | "agent";
+    /** Discriminated tag identifying who registered the capability. Used for trust enforcement and audit. */
+    origin: CapabilityOrigin;
+    /** Lifetime: `session` survives the whole session, `turn` is dropped at end-of-turn. */
+    scope?: "session" | "turn";
+    /** When true, the bridge auto-resolves with `{}` immediately and runs the handler in the background. */
+    fireAndForget?: boolean;
+    /** When true, the platform shows a confirm UI before dispatch and waits for {@link CapabilityApproveCommand}. */
+    requiresApproval?: boolean;
+    /** Documentation hint (not enforced) describing whether this is a side-effect, render, or pure query. */
+    kind?: "effect" | "render" | "query";
+    /**
+     * Whether this capability should be exposed in user-facing surfaces (cmdK
+     * action palette, capability menus). When omitted, the consumer applies a
+     * default per-origin via {@link isUserInvokable}.
+     *
+     * - `true`: surface in cmdK and capability menus.
+     * - `false`: hide from user surfaces (LLM-only or low-level).
+     * - `undefined`: defer to {@link isUserInvokable}'s inference rules.
+     *
+     * @deprecated Set {@link Capability.audience} instead. `userInvokable` is
+     * kept as a read-only shim for v2.x consumers and is honoured by
+     * {@link isUserInvokable} when {@link Capability.audience} is absent.
+     */
+    userInvokable?: boolean;
+    /**
+     * Audience scoping for this capability. See {@link CapabilityAudience} for
+     * the meaning of each value and combinations.
+     *
+     * When omitted, consumers treat the capability as `['llm', 'user']` (the
+     * v2.x default). Host RPCs and runner RPCs MUST set this to `['runtime']`
+     * so they never leak to the LLM tool list or the user-facing surfaces.
+     *
+     * @category Capabilities
+     * @since 3.0.0
+     */
+    audience?: CapabilityAudience[];
+    /** Appended to the system prompt's `<CAPABILITIES>` section. Use for usage hints the LLM should always see. */
+    promptFragment?: string;
+    /** Present iff this is a render capability — see {@link RenderCapability}. */
+    render?: RenderSpec;
+};
+/**
+ * A {@link Capability} that produces a UI surface when invoked. The narrowed
+ * type guarantees `render` is set, which simplifies frontend lookup.
+ *
+ * @see {@link isRenderCapability}
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#render-capability
+ */
+export type RenderCapability = Capability & {
+    render: NonNullable<Capability["render"]>;
+};
+/**
+ * Type-guard for {@link RenderCapability}. Use after {@link Capability}
+ * lookup to narrow the type before reading `render`.
+ *
+ * @example
+ * ```ts
+ * for (const cap of registry.list()) {
+ *   if (isRenderCapability(cap)) console.log(cap.render.targets);
+ * }
+ * ```
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#is-render-capability
+ */
+export declare function isRenderCapability(cap: Capability): cap is RenderCapability;
+/**
+ * Decide whether a capability should be surfaced in user-facing actions
+ * (cmdK action palette, capability menus).
+ *
+ * Resolution order (first match wins):
+ *
+ * 1. {@link Capability.audience} is set — return `audience.includes('user')`.
+ *    Capabilities scoped to `'runtime'` only never appear in user surfaces.
+ * 2. {@link Capability.userInvokable} is set (v2.x shim) — return that value.
+ * 3. Default per-origin inference table below.
+ *
+ * Default-inference rules (when both `audience` and `userInvokable` are
+ * omitted):
+ * | Origin       | Default                                                                |
+ * | ------------ | ---------------------------------------------------------------------- |
+ * | `framework`  | `false` (LLM discovery surfaces, e.g. `__capabilities.list`)           |
+ * | `client`     | `false` (platform ack tools — `platform.react`, `platform.pass`)       |
+ * | `agent`      | `false` (agent-defined; assume internal unless flagged)                |
+ * | `flow`       | `false` (per-cap opt-in)                                               |
+ * | `connector`  | `false` (low-level FS / data ops)                                      |
+ * | `mount`      | `false` (low-level FS ops)                                             |
+ * | `mcp`        | `true` if `kind === 'effect'`, else `false`                            |
+ * | `skill`      | `true` if `kind` ∈ {`effect`, `render`}, else `false`                  |
+ *
+ * @example
+ * ```ts
+ * for (const cap of capabilities.values()) {
+ *   if (isUserInvokable(cap)) registerCommandPaletteAction(cap);
+ * }
+ * ```
+ *
+ * @category Capabilities
+ * @since 2.1.0
+ * @docLink packages/types/capabilities#is-user-invokable
+ */
+export declare function isUserInvokable(cap: Capability): boolean;
+/**
+ * Register one or more capabilities mid-session (client → agent).
+ *
+ * The platform sends this when a new client-side tool becomes available
+ * after `configure` has already returned (e.g. a user installs a new
+ * extension during the session).
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-register-command
+ */
+export type CapabilityRegisterCommand = {
+    type: "capability_register";
+    capabilities: Capability[];
+};
+/**
+ * Deregister capabilities by name (client → agent). Names that are not
+ * currently registered are ignored silently.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-deregister-command
+ */
+export type CapabilityDeregisterCommand = {
+    type: "capability_deregister";
+    names: string[];
+};
+/**
+ * Return the result of a previously {@link CapabilityInvokedEvent | invoked} client-side
+ * capability (client → agent). Bridges that registered the capability with
+ * `fireAndForget: true` MAY skip this command; the bridge auto-resolves with `{}`.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-result-command
+ */
+export type CapabilityResultCommand = {
+    type: "capability_result";
+    /** Correlation token matching the {@link CapabilityInvokedEvent.callId}. */
+    callId: string;
+    /** Successful result payload, or an error envelope. */
+    result: unknown | {
+        error: string;
+    };
+};
+/**
+ * Approve or reject a capability call that was invoked with
+ * `requiresApproval: true` (client → agent). The platform shows a confirm
+ * UI and forwards the user's decision via this command.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-approve-command
+ */
+export type CapabilityApproveCommand = {
+    type: "capability_approve";
+    /** Correlation token matching the {@link CapabilityInvokedEvent.callId}. */
+    callId: string;
+    /** User's decision. */
+    decision: "approved" | "rejected";
+    /** Optional rationale stored alongside the decision for audit. */
+    feedback?: string;
+    /** User ID of the decider (informational — framework enforces no policy). */
+    decidedBy: string;
+};
+/**
+ * Register one or more capabilities mid-session (agent → client). Mirrors
+ * {@link CapabilityRegisterCommand} for the agent-initiated direction; used
+ * when the runtime adds a capability after `configure` (e.g. when a flow
+ * starts and injects flow-scoped tools).
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-register-event
+ */
+export type CapabilityRegisterEvent = {
+    type: "capability_register";
+    capabilities: Capability[];
+};
+/**
+ * Deregister capabilities by name (agent → client).
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-deregister-event
+ */
+export type CapabilityDeregisterEvent = {
+    type: "capability_deregister";
+    names: string[];
+};
+/**
+ * Notify the client that a capability has been invoked by the LLM (agent →
+ * client). For client-side capabilities the platform's handler runs in
+ * response to this event and replies with {@link CapabilityResultCommand}.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#capability-invoked-event
+ */
+export type CapabilityInvokedEvent = {
+    type: "capability_invoked";
+    /** Correlation token for the eventual {@link CapabilityResultCommand}. */
+    callId: string;
+    /** Name of the invoked {@link Capability}. */
+    name: string;
+    /** Validated input payload (already conforms to the capability's `inputSchema`). */
+    input: unknown;
+    /** In v2.0.0 the LLM is the only invoker. */
+    invokedBy: "agent";
+};
+/**
+ * Notify the client that a render capability should be drawn (agent →
+ * client). Emitted alongside {@link CapabilityInvokedEvent} when the
+ * invoked capability's `render` block is populated.
+ *
+ * Clients without a render layer can fall back to the capability's
+ * `render.fallback` markdown template.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ * @docLink packages/types/capabilities#render-invoked-event
+ */
+export type RenderInvokedEvent = {
+    type: "render_invoked";
+    /** Name of the invoked render capability. */
+    capabilityName: string;
+    /** Props passed to the rendered component (already conforms to `inputSchema`). */
+    props: unknown;
+    /** Correlation token shared with the matching {@link CapabilityInvokedEvent}. */
+    callId: string;
+};
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/types/src/capabilities.d.ts.map

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

package/dist/types/src/envelope.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Envelope layer — the v2/v3 message envelope wrapping every command and event.
+ *
+ * {@link MessageV2} is the canonical envelope; the name is retained from the
+ * v2 rollout for symbol stability. Protocol v3 keeps the envelope structure
+ * unchanged but swaps the payload contents:
+ *
+ *   - `ConfigureCommandV2` (deleted) is replaced by {@link SessionInitCommand}.
+ *   - Several v2 commands (`provision_secrets`, `request_access_token`,
+ *     `add_resource`, `remove_resource`, `set_log_level`, `state_action`,
+ *     `lifecycle`, `remount_mount`, `compact`, `reconfigure_agent`) are
+ *     removed; their semantics ride on `session_init` and the
+ *     `host.*` / `runner.*` capability families.
+ *
+ * Spec: `_devlog/specs/2026-05-10-deterministic-session-bootstrap.md`.
+ *
+ * @see {@link MessageMeta} for the metadata block carried under `meta`
+ * @see {@link Capability} for the new wire surface
+ *
+ * @category Envelope
+ * @since 2.0.0
+ */
+import type { CapabilityApproveCommand, CapabilityDeregisterCommand, CapabilityDeregisterEvent, CapabilityInvokedEvent, CapabilityRegisterCommand, CapabilityRegisterEvent, CapabilityResultCommand, RenderInvokedEvent } from "./capabilities.js";
+import type { IncompatibleProtocolEvent, ProtocolInfoEvent, SessionInitAckEvent, SessionInitCommand, SessionInitMismatchEvent } from "./lifecycle.js";
+import type { MessageMeta } from "./messaging.js";
+import type { AgentCommand } from "./protocol.js";
+import type { AgentEvent } from "./events.js";
+/**
+ * Capability commands added in v2. These are appended to the v2 payload
+ * union; the v1 {@link AgentCommand} is left untouched.
+ *
+ * @category Envelope
+ * @since 2.0.0
+ * @docLink packages/types/protocol-v2#envelope-unions
+ */
+export type CapabilityCommand = CapabilityRegisterCommand | CapabilityDeregisterCommand | CapabilityResultCommand | CapabilityApproveCommand;
+/**
+ * Capability and lifecycle events carried in the v2/v3 envelope.
+ *
+ * Adds the v3 session-init lifecycle events alongside the v2 protocol
+ * info / mismatch events.
+ *
+ * @category Envelope
+ * @since 2.0.0
+ * @docLink packages/types/protocol-v3#envelope-unions
+ */
+export type CapabilityEvent = CapabilityRegisterEvent | CapabilityDeregisterEvent | CapabilityInvokedEvent | RenderInvokedEvent | IncompatibleProtocolEvent | ProtocolInfoEvent | SessionInitAckEvent | SessionInitMismatchEvent;
+/**
+ * Union of every command the v2/v3 envelope can carry. Plain
+ * {@link AgentCommand} plus the capability commands plus the v3
+ * {@link SessionInitCommand}.
+ *
+ * @category Envelope
+ * @since 2.0.0
+ * @docLink packages/types/protocol-v3#envelope-unions
+ */
+export type AgentCommandV2 = AgentCommand | CapabilityCommand | SessionInitCommand;
+/**
+ * Union of every event the v2/v3 envelope can carry. Equivalent to plain
+ * {@link AgentEvent} plus the v2/v3 capability/lifecycle events.
+ *
+ * @category Envelope
+ * @since 2.0.0
+ * @docLink packages/types/protocol-v3#envelope-unions
+ */
+export type AgentEventV2 = AgentEvent | CapabilityEvent;
+/**
+ * The v2 message envelope. A structural superset of v1's {@link Message}:
+ * `senderId`, `mentions`, and `reactions` move under `meta` (typed via
+ * {@link MessageMeta}), and `recipientIds` plus `reply` are added.
+ *
+ * The envelope is **generic over a `TMetaExtensions` type parameter** so
+ * host platforms can attach typed metadata fields (e.g. `priority`,
+ * `archived`) without forking the framework. Framework-side code uses the
+ * default form (`MessageV2` with no type argument).
+ *
+ * @example Framework-side usage:
+ * ```ts
+ * const msg: MessageV2 = {
+ *   id: 'msg_01',
+ *   seq: 7,
+ *   timestamp: new Date().toISOString(),
+ *   sessionId: 'sess_42',
+ *   payload: { type: 'text', content: 'hi' },
+ * };
+ * ```
+ *
+ * @example Platform-side usage with typed extensions:
+ * ```ts
+ * type PlatformMetaExtensions = { priority?: 'low' | 'normal' | 'high' };
+ * type PlatformMessage = MessageV2<PlatformMetaExtensions>;
+ * const msg: PlatformMessage = {
+ *   ...,
+ *   meta: { priority: 'high', senderId: 'u_42' },
+ * };
+ * ```
+ *
+ * @typeParam TMetaExtensions - platform-specific extension fields on `meta`.
+ *
+ * @see {@link MessageMeta} for the meta block contract (round-trip preservation)
+ *
+ * @category Envelope
+ * @since 2.0.0
+ * @docLink packages/types/messages#message-v2
+ */
+export type MessageV2<TMetaExtensions extends object = Record<string, never>> = {
+    /** UUID — stable identity for this envelope. */
+    id: string;
+    /** Monotonic per-session sequence number. */
+    seq: number;
+    /** ISO 8601 emission timestamp. */
+    timestamp: string;
+    /** Session this envelope belongs to. */
+    sessionId: string;
+    /** The wrapped command or event payload. Discriminate via `payload.type`. */
+    payload: AgentCommandV2 | AgentEventV2;
+    /** Optional metadata block; minimal clients omit. See round-trip contract on {@link MessageMeta}. */
+    meta?: MessageMeta<TMetaExtensions>;
+};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/types/src/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../types/src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,yBAAyB,GACzB,2BAA2B,GAC3B,uBAAuB,GACvB,wBAAwB,CAAC;AAE7B;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GACvB,uBAAuB,GACvB,yBAAyB,GACzB,sBAAsB,GACtB,kBAAkB,GAClB,yBAAyB,GACzB,iBAAiB,GACjB,mBAAmB,GACnB,wBAAwB,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,eAAe,CAAC;AAMxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,MAAM,SAAS,CAAC,eAAe,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI;IAC9E,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,cAAc,GAAG,YAAY,CAAC;IACvC,qGAAqG;IACrG,IAAI,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC;CACrC,CAAC"}