@peac/adapter-openclaw 0.10.7

package/README.md

@@ -0,0 +1,190 @@
+# @peac/adapter-openclaw
+
+OpenClaw adapter for PEAC interaction evidence capture.
+
+## Overview
+
+`@peac/adapter-openclaw` provides a complete capture pipeline for recording OpenClaw tool calls as PEAC interaction evidence. It includes:
+
+- **Mapper**: OpenClaw tool call events -> PEAC `CapturedAction`
+- **Hooks**: Sync capture bindings (< 10ms target)
+- **Emitter**: Background receipt signing and persistence
+- **Tailer**: Session history fallback for resilience
+
+## Installation
+
+```bash
+pnpm add @peac/adapter-openclaw
+```
+
+## Quick Start
+
+```typescript
+import { createCaptureSession, createHasher } from '@peac/capture-core';
+import { createInMemorySpoolStore, createInMemoryDedupeIndex } from '@peac/capture-core/testkit';
+import { createHookHandler, mapToolCallEvent } from '@peac/adapter-openclaw';
+
+// Create a capture session
+const session = createCaptureSession({
+  store: createInMemorySpoolStore(),
+  dedupe: createInMemoryDedupeIndex(),
+  hasher: createHasher(),
+});
+
+// Create a hook handler
+const handler = createHookHandler({
+  session,
+  config: {
+    platform: 'openclaw',
+    platform_version: '0.2.0',
+  },
+});
+
+// Handle OpenClaw tool call events
+const result = await handler.afterToolCall({
+  tool_call_id: 'call_123',
+  run_id: 'run_abc',
+  tool_name: 'web_search',
+  started_at: '2024-02-01T10:00:00Z',
+  completed_at: '2024-02-01T10:00:01Z',
+  status: 'ok',
+  input: { query: 'hello world' },
+  output: { results: ['result1'] },
+});
+
+if (result.success) {
+  console.log('Captured:', result.entry.entry_digest);
+}
+
+await handler.close();
+```
+
+## Architecture
+
+### Two-Stage Pipeline
+
+1. **Capture Stage** (sync, < 10ms target)
+   - Map OpenClaw event to `CapturedAction`
+   - Hash payloads inline (truncate large payloads)
+   - Write to tamper-evident spool
+
+2. **Emit Stage** (async background)
+   - Drain spool periodically
+   - Convert to `InteractionEvidenceV01`
+   - Sign with configured key
+   - Write receipt to output
+
+### OpenClaw to PEAC Mapping
+
+| OpenClaw Concept      | PEAC Location               |
+| --------------------- | --------------------------- |
+| Session key           | `workflow_id` (correlation) |
+| Run ID + tool_call_id | `interaction_id` (dedupe)   |
+| Tool call params      | `input.digest`              |
+| Tool call result      | `output.digest`             |
+| Tool name             | `tool.name`                 |
+| Sandbox mode          | `policy.sandbox_enabled`    |
+| Elevated flag         | `policy.elevated`           |
+
+## API Reference
+
+### Mapper
+
+```typescript
+import { mapToolCallEvent, mapToolCallEventBatch } from '@peac/adapter-openclaw';
+
+// Map single event
+const result = mapToolCallEvent(event, config);
+if (result.success) {
+  console.log(result.action);
+}
+
+// Map batch
+const results = mapToolCallEventBatch(events, config);
+```
+
+### Hook Handler
+
+```typescript
+import { createHookHandler, captureBatch, captureParallel } from '@peac/adapter-openclaw';
+
+const handler = createHookHandler({
+  session,
+  config: { platform: 'openclaw' },
+  onCapture: (result, event) => {
+    console.log('Captured:', result);
+  },
+});
+
+// Single event
+await handler.afterToolCall(event);
+
+// Batch (sequential)
+await captureBatch(handler, events);
+
+// Batch (parallel - non-deterministic order)
+await captureParallel(handler, events);
+```
+
+### Background Emitter
+
+```typescript
+import { createReceiptEmitter, createBackgroundService } from '@peac/adapter-openclaw';
+
+const emitter = createReceiptEmitter({
+  signer,
+  writer,
+  config: { platform: 'openclaw' },
+});
+
+const service = createBackgroundService({
+  emitter,
+  getPendingEntries: () => spoolStore.getPending(),
+  markEmitted: (digest) => dedupeIndex.markEmitted(digest),
+  drainIntervalMs: 1000,
+});
+
+service.start();
+// ... later
+service.stop();
+```
+
+### Session History Tailer (Fallback)
+
+```typescript
+import { createSessionHistoryTailer } from '@peac/adapter-openclaw';
+
+const tailer = createSessionHistoryTailer({
+  handler,
+  sessionId: 'session_123',
+  fetchHistory: async (sessionId, afterEventId) => {
+    return openclaw.sessions.getHistory(sessionId, { after: afterEventId });
+  },
+  pollIntervalMs: 1000,
+});
+
+tailer.start();
+// ... later
+tailer.stop();
+```
+
+## Error Codes
+
+| Code                              | Description                     |
+| --------------------------------- | ------------------------------- |
+| `E_OPENCLAW_MISSING_FIELD`        | Required field missing in event |
+| `E_OPENCLAW_INVALID_FIELD`        | Invalid field value in event    |
+| `E_OPENCLAW_SERIALIZATION_FAILED` | Payload serialization failed    |
+| `E_OPENCLAW_SIGNING_FAILED`       | Receipt signing failed          |
+
+## Warning Codes
+
+| Code                                | Description                 |
+| ----------------------------------- | --------------------------- |
+| `W_OPENCLAW_PAYLOAD_TRUNCATED`      | Payload exceeded size limit |
+| `W_OPENCLAW_OPTIONAL_FIELD_MISSING` | Optional field missing      |
+| `W_OPENCLAW_UNKNOWN_PROVIDER`       | Unknown tool provider       |
+
+## License
+
+Apache-2.0

package/dist/emitter.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @peac/adapter-openclaw - Background Emitter
+ *
+ * Background service for converting captured actions to signed PEAC receipts.
+ * Runs asynchronously to avoid blocking the sync capture path.
+ */
+import type { SpoolEntry } from '@peac/capture-core';
+import type { ReceiptEmitter, EmitResult, OpenClawAdapterConfig } from './types.js';
+/**
+ * Signer interface for receipt signing.
+ *
+ * Different implementations can support various key storage mechanisms:
+ * - Level 1: Environment variable (dev only)
+ * - Level 2: OS Keychain
+ * - Level 3: Sidecar process
+ * - Level 4: Hardware module (YubiKey, TPM, HSM)
+ *
+ * IMPORTANT: Implementations MUST include the key ID (kid) in the JWS header.
+ * The getKeyId() method allows callers to inspect which kid will be used
+ * without parsing the resulting JWS.
+ */
+export interface Signer {
+    /**
+     * Sign a payload and return JWS compact serialization.
+     * The JWS header MUST include the 'kid' claim for verifier key selection.
+     */
+    sign(payload: unknown): Promise<string>;
+    /** Get the key ID (kid) that will be included in the JWS header */
+    getKeyId(): string;
+    /** Get the issuer URI */
+    getIssuer(): string;
+    /** Get the audience URI (optional) */
+    getAudience(): string | undefined;
+}
+/**
+ * Receipt writer interface for persisting signed receipts.
+ */
+export interface ReceiptWriter {
+    /** Write a signed receipt */
+    write(receipt: SignedReceipt): Promise<string>;
+    /** Close the writer */
+    close(): Promise<void>;
+}
+/**
+ * Signed receipt ready for persistence.
+ */
+export interface SignedReceipt {
+    /** Receipt ID (rid) */
+    rid: string;
+    /** JWS compact serialization */
+    jws: string;
+    /** Interaction ID (for correlation) */
+    interaction_id: string;
+    /** Entry digest (for verification) */
+    entry_digest: string;
+}
+/**
+ * Configuration for creating a receipt emitter.
+ */
+export interface EmitterConfig {
+    /** Signer for receipt signing */
+    signer: Signer;
+    /** Writer for receipt persistence */
+    writer: ReceiptWriter;
+    /** Adapter configuration */
+    config?: OpenClawAdapterConfig;
+    /** Callback for emit events */
+    onEmit?: (result: EmitResult, entry: SpoolEntry) => void;
+    /** Callback for emit errors */
+    onError?: (error: Error, entry: SpoolEntry) => void;
+}
+/**
+ * Create a receipt emitter.
+ *
+ * @param emitterConfig - Configuration for the emitter
+ * @returns Receipt emitter instance
+ */
+export declare function createReceiptEmitter(emitterConfig: EmitterConfig): ReceiptEmitter;
+/**
+ * Background emitter service that periodically drains a spool.
+ */
+export interface BackgroundEmitterService {
+    /** Start the background service */
+    start(): void;
+    /** Stop the background service */
+    stop(): void;
+    /** Trigger immediate drain */
+    drain(): Promise<void>;
+    /** Whether the service is running */
+    isRunning(): boolean;
+    /** Get emit statistics */
+    getStats(): EmitterStats;
+}
+/**
+ * Emitter statistics.
+ */
+export interface EmitterStats {
+    /** Total entries emitted */
+    emitted: number;
+    /** Total entries failed */
+    failed: number;
+    /** Last emit time */
+    lastEmitTime?: Date;
+    /** Last error */
+    lastError?: string;
+}
+/**
+ * Configuration for background emitter service.
+ */
+export interface BackgroundServiceConfig {
+    /** Receipt emitter */
+    emitter: ReceiptEmitter;
+    /** Function to get pending spool entries */
+    getPendingEntries: () => Promise<SpoolEntry[]>;
+    /** Function to mark entry as emitted */
+    markEmitted: (entryDigest: string) => Promise<void>;
+    /** Drain interval in milliseconds (default: 1000) */
+    drainIntervalMs?: number;
+    /** Callback for service errors */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a background emitter service.
+ *
+ * @param serviceConfig - Configuration for the service
+ * @returns Background emitter service instance
+ */
+export declare function createBackgroundService(serviceConfig: BackgroundServiceConfig): BackgroundEmitterService;
+//# sourceMappingURL=emitter.d.ts.map

package/dist/emitter.d.ts.map

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

package/dist/emitter.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * @peac/adapter-openclaw - Background Emitter
+ *
+ * Background service for converting captured actions to signed PEAC receipts.
+ * Runs asynchronously to avoid blocking the sync capture path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReceiptEmitter = createReceiptEmitter;
+exports.createBackgroundService = createBackgroundService;
+const capture_core_1 = require("@peac/capture-core");
+const types_js_1 = require("./types.js");
+/**
+ * Create a receipt emitter.
+ *
+ * @param emitterConfig - Configuration for the emitter
+ * @returns Receipt emitter instance
+ */
+function createReceiptEmitter(emitterConfig) {
+    const { signer, writer, onEmit, onError } = emitterConfig;
+    let closed = false;
+    return {
+        async emit(entry) {
+            if (closed) {
+                return {
+                    success: false,
+                    error_code: 'E_EMITTER_CLOSED',
+                    error_message: 'Emitter has been closed',
+                };
+            }
+            try {
+                // Convert SpoolEntry to InteractionEvidence
+                // Note: Platform info is already in the entry.action from the mapper
+                const interaction = (0, capture_core_1.toInteractionEvidence)(entry);
+                // Build the receipt payload
+                const receiptPayload = buildReceiptPayload(interaction, entry, signer);
+                // Sign the receipt
+                const jws = await signer.sign(receiptPayload);
+                // Build signed receipt
+                const signedReceipt = {
+                    rid: receiptPayload.rid,
+                    jws,
+                    interaction_id: entry.action.id,
+                    entry_digest: entry.entry_digest,
+                };
+                // Write the receipt
+                const receiptPath = await writer.write(signedReceipt);
+                const result = {
+                    success: true,
+                    receipt_path: receiptPath,
+                    receipt_id: receiptPayload.rid,
+                };
+                if (onEmit) {
+                    onEmit(result, entry);
+                }
+                return result;
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (onError) {
+                    onError(error instanceof Error ? error : new Error(errorMessage), entry);
+                }
+                return {
+                    success: false,
+                    error_code: types_js_1.OPENCLAW_ERROR_CODES.SIGNING_FAILED,
+                    error_message: `Failed to emit receipt: ${errorMessage}`,
+                };
+            }
+        },
+        async flush() {
+            // No-op: entries are emitted immediately via emit()
+            // This method exists for API consistency
+        },
+        async close() {
+            closed = true;
+            await writer.close();
+        },
+    };
+}
+/**
+ * Build the receipt payload from interaction evidence.
+ */
+function buildReceiptPayload(interaction, entry, signer) {
+    const now = Math.floor(Date.now() / 1000);
+    const rid = generateReceiptId(entry.entry_digest);
+    const payload = {
+        iss: signer.getIssuer(),
+        iat: now,
+        rid,
+        evidence: {
+            extensions: {
+                'org.peacprotocol/interaction@0.1': interaction,
+            },
+        },
+    };
+    const audience = signer.getAudience();
+    if (audience) {
+        payload.aud = audience;
+    }
+    return payload;
+}
+/**
+ * Generate a deterministic receipt ID from entry digest.
+ *
+ * Using a deterministic ID (derived from entry_digest) provides:
+ * - Idempotency: same entry always produces same rid
+ * - Replay safety: retries don't create duplicates
+ * - Correlation: rid can be traced back to spool entry
+ *
+ * Format: r_{first 32 chars of entry_digest}
+ */
+function generateReceiptId(entryDigest) {
+    // Use first 32 chars of entry digest for reasonable uniqueness
+    // while keeping the ID short enough for practical use
+    return `r_${entryDigest.slice(0, 32)}`;
+}
+/**
+ * Create a background emitter service.
+ *
+ * @param serviceConfig - Configuration for the service
+ * @returns Background emitter service instance
+ */
+function createBackgroundService(serviceConfig) {
+    const { emitter, getPendingEntries, markEmitted, drainIntervalMs = 1000, onError, } = serviceConfig;
+    let running = false;
+    let stopping = false;
+    let inFlight = false;
+    let intervalHandle;
+    const stats = {
+        emitted: 0,
+        failed: 0,
+    };
+    const drainOnce = async () => {
+        // Prevent overlapping drains - if a drain takes longer than the
+        // interval, skip this tick rather than double-processing
+        if (inFlight)
+            return;
+        inFlight = true;
+        try {
+            const entries = await getPendingEntries();
+            for (const entry of entries) {
+                // Check if service is being stopped during processing
+                if (stopping)
+                    break;
+                const result = await emitter.emit(entry);
+                if (result.success) {
+                    await markEmitted(entry.entry_digest);
+                    stats.emitted++;
+                    stats.lastEmitTime = new Date();
+                }
+                else {
+                    stats.failed++;
+                    stats.lastError = result.error_message;
+                }
+            }
+        }
+        catch (error) {
+            stats.lastError = error instanceof Error ? error.message : String(error);
+            if (onError) {
+                onError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            intervalHandle = setInterval(drainOnce, drainIntervalMs);
+            // Run immediately on start
+            drainOnce();
+        },
+        stop() {
+            if (!running)
+                return;
+            stopping = true;
+            running = false;
+            if (intervalHandle) {
+                clearInterval(intervalHandle);
+                intervalHandle = undefined;
+            }
+        },
+        async drain() {
+            await drainOnce();
+        },
+        isRunning() {
+            return running;
+        },
+        getStats() {
+            return { ...stats };
+        },
+    };
+}
+//# sourceMappingURL=emitter.js.map

package/dist/emitter.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @peac/adapter-openclaw - Hook Bindings
+ *
+ * Hook bindings for OpenClaw tool call capture.
+ * Designed for sync capture (< 10ms target).
+ */
+import type { CaptureSession, SpoolEntry } from '@peac/capture-core';
+import type { OpenClawToolCallEvent, OpenClawAdapterConfig, MappingResult } from './types.js';
+/**
+ * Result of a hook capture operation.
+ * More flexible than CaptureResult to allow adapter-specific error codes.
+ */
+export type HookCaptureResult = {
+    success: true;
+    entry: SpoolEntry;
+} | {
+    success: false;
+    code: string;
+    message: string;
+};
+/**
+ * Hook handler for OpenClaw tool call events.
+ */
+export interface OpenClawHookHandler {
+    /** Handle after_tool_call hook */
+    afterToolCall(event: OpenClawToolCallEvent): Promise<HookCaptureResult>;
+    /** Get the underlying capture session */
+    getSession(): CaptureSession;
+    /** Close the handler */
+    close(): Promise<void>;
+}
+/**
+ * Configuration for creating a hook handler.
+ */
+export interface HookHandlerConfig {
+    /** Capture session to use */
+    session: CaptureSession;
+    /** Adapter configuration */
+    config?: OpenClawAdapterConfig;
+    /** Callback for capture events (for telemetry/logging) */
+    onCapture?: (result: HookCaptureResult, event: OpenClawToolCallEvent) => void;
+    /** Callback for mapping errors */
+    onMappingError?: (result: MappingResult, event: OpenClawToolCallEvent) => void;
+}
+/**
+ * Create a hook handler for OpenClaw tool call events.
+ *
+ * @param handlerConfig - Configuration for the handler
+ * @returns Hook handler instance
+ */
+export declare function createHookHandler(handlerConfig: HookHandlerConfig): OpenClawHookHandler;
+/**
+ * Capture multiple tool call events in sequence.
+ *
+ * Note: Events are captured in order. For parallel capture, use individual
+ * afterToolCall calls with Promise.all.
+ *
+ * @param handler - Hook handler
+ * @param events - Array of tool call events
+ * @returns Array of capture results (same order as events)
+ */
+export declare function captureBatch(handler: OpenClawHookHandler, events: OpenClawToolCallEvent[]): Promise<HookCaptureResult[]>;
+/**
+ * Capture multiple tool call events in parallel.
+ *
+ * Warning: Parallel capture may result in non-deterministic chain ordering.
+ * Use captureBatch for deterministic ordering.
+ *
+ * @param handler - Hook handler
+ * @param events - Array of tool call events
+ * @returns Array of capture results (same order as events)
+ */
+export declare function captureParallel(handler: OpenClawHookHandler, events: OpenClawToolCallEvent[]): Promise<HookCaptureResult[]>;
+/**
+ * Session history tailer for fallback capture.
+ *
+ * If OpenClaw hooks don't provide complete event data, this can poll
+ * the session history API to backfill missed events.
+ */
+export interface SessionHistoryTailer {
+    /** Start tailing session history */
+    start(): void;
+    /** Stop tailing */
+    stop(): void;
+    /** Get the last processed event ID */
+    getLastEventId(): string | undefined;
+    /** Whether the tailer is running */
+    isRunning(): boolean;
+}
+/**
+ * Configuration for session history tailer.
+ */
+export interface TailerConfig {
+    /** Hook handler to use for capture */
+    handler: OpenClawHookHandler;
+    /** Session ID to tail */
+    sessionId: string;
+    /** Polling interval in milliseconds (default: 1000) */
+    pollIntervalMs?: number;
+    /** Function to fetch session history */
+    fetchHistory: (sessionId: string, afterEventId?: string) => Promise<OpenClawToolCallEvent[]>;
+    /** Callback for tailer errors */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a session history tailer.
+ *
+ * @param tailerConfig - Configuration for the tailer
+ * @returns Session history tailer instance
+ */
+export declare function createSessionHistoryTailer(tailerConfig: TailerConfig): SessionHistoryTailer;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAiB,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAO9F;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAMtD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,aAAa,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAExE,yCAAyC;IACzC,UAAU,IAAI,cAAc,CAAC;IAE7B,wBAAwB;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,OAAO,EAAE,cAAc,CAAC;IAExB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAE/B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAE9E,kCAAkC;IAClC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAChF;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,iBAAiB,GAAG,mBAAmB,CA6CvF;AAMD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,qBAAqB,EAAE,GAC9B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAS9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,qBAAqB,EAAE,GAC9B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAE9B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,KAAK,IAAI,IAAI,CAAC;IAEd,mBAAmB;IACnB,IAAI,IAAI,IAAI,CAAC;IAEb,sCAAsC;IACtC,cAAc,IAAI,MAAM,GAAG,SAAS,CAAC;IAErC,oCAAoC;IACpC,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,OAAO,EAAE,mBAAmB,CAAC;IAE7B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAElB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wCAAwC;IACxC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAE7F,iCAAiC;IACjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,YAAY,GAAG,oBAAoB,CA2D3F"}