@agentapps/station 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +58 -2
  3. package/dist/api-key-store.d.ts +46 -0
  4. package/dist/api-key-store.d.ts.map +1 -0
  5. package/dist/api-key-store.js +84 -0
  6. package/dist/api-key-store.js.map +1 -0
  7. package/dist/app-station.d.ts +129 -0
  8. package/dist/app-station.d.ts.map +1 -0
  9. package/dist/app-station.js +706 -0
  10. package/dist/app-station.js.map +1 -0
  11. package/dist/approval-manager.d.ts +75 -0
  12. package/dist/approval-manager.d.ts.map +1 -0
  13. package/dist/approval-manager.js +96 -0
  14. package/dist/approval-manager.js.map +1 -0
  15. package/dist/document-store.d.ts +86 -0
  16. package/dist/document-store.d.ts.map +1 -0
  17. package/dist/document-store.js +230 -0
  18. package/dist/document-store.js.map +1 -0
  19. package/dist/file-handlers/object-store.d.ts +113 -0
  20. package/dist/file-handlers/object-store.d.ts.map +1 -0
  21. package/dist/file-handlers/object-store.js +273 -0
  22. package/dist/file-handlers/object-store.js.map +1 -0
  23. package/dist/file-handlers/signed-url.d.ts +44 -0
  24. package/dist/file-handlers/signed-url.d.ts.map +1 -0
  25. package/dist/file-handlers/signed-url.js +68 -0
  26. package/dist/file-handlers/signed-url.js.map +1 -0
  27. package/dist/file-handlers/volume-handlers.d.ts +136 -0
  28. package/dist/file-handlers/volume-handlers.d.ts.map +1 -0
  29. package/dist/file-handlers/volume-handlers.js +426 -0
  30. package/dist/file-handlers/volume-handlers.js.map +1 -0
  31. package/dist/in-process-runtime.d.ts +49 -0
  32. package/dist/in-process-runtime.d.ts.map +1 -0
  33. package/dist/in-process-runtime.js +50 -0
  34. package/dist/in-process-runtime.js.map +1 -0
  35. package/dist/index.d.ts +27 -0
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +34 -0
  38. package/dist/index.js.map +1 -0
  39. package/dist/local-process-runtime.d.ts +28 -0
  40. package/dist/local-process-runtime.d.ts.map +1 -0
  41. package/dist/local-process-runtime.js +134 -0
  42. package/dist/local-process-runtime.js.map +1 -0
  43. package/dist/oauth-manager.d.ts +90 -0
  44. package/dist/oauth-manager.d.ts.map +1 -0
  45. package/dist/oauth-manager.js +148 -0
  46. package/dist/oauth-manager.js.map +1 -0
  47. package/dist/oauth-pages.d.ts +9 -0
  48. package/dist/oauth-pages.d.ts.map +1 -0
  49. package/dist/oauth-pages.js +59 -0
  50. package/dist/oauth-pages.js.map +1 -0
  51. package/dist/permission-enforcer.d.ts +52 -0
  52. package/dist/permission-enforcer.d.ts.map +1 -0
  53. package/dist/permission-enforcer.js +144 -0
  54. package/dist/permission-enforcer.js.map +1 -0
  55. package/dist/policy-store.d.ts +34 -0
  56. package/dist/policy-store.d.ts.map +1 -0
  57. package/dist/policy-store.js +35 -0
  58. package/dist/policy-store.js.map +1 -0
  59. package/dist/secrets-manager.d.ts +32 -0
  60. package/dist/secrets-manager.d.ts.map +1 -0
  61. package/dist/secrets-manager.js +12 -0
  62. package/dist/secrets-manager.js.map +1 -0
  63. package/dist/server.d.ts +383 -0
  64. package/dist/server.d.ts.map +1 -0
  65. package/dist/server.js +1974 -0
  66. package/dist/server.js.map +1 -0
  67. package/dist/telemetry.d.ts +9 -0
  68. package/dist/telemetry.d.ts.map +1 -0
  69. package/dist/telemetry.js +9 -0
  70. package/dist/telemetry.js.map +1 -0
  71. package/dist/types.d.ts +47 -0
  72. package/dist/types.d.ts.map +1 -0
  73. package/dist/types.js +9 -0
  74. package/dist/types.js.map +1 -0
  75. package/package.json +40 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Agent Apps
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,59 @@
1
- # Temporary Holding Version
1
+ # @agentapps/station
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Agent App AppStation — instance lifecycle, traffic proxy, runtime adapters, and backpressure management.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @agentapps/station
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```ts
14
+ import { AppStation, InProcessRuntime } from '@agentapps/station';
15
+ import type { AppFactory } from '@agentapps/station';
16
+
17
+ const appFactory: AppFactory = (transport) => {
18
+ // Wire your app to the transport
19
+ };
20
+
21
+ const runtime = new InProcessRuntime(appFactory);
22
+
23
+ const controller = new AppStation({
24
+ appId: 'app.hello',
25
+ appVersion: '1.0.0',
26
+ runtime,
27
+ mode: 'on-demand',
28
+ openTimeoutMs: 60_000,
29
+ maxInflightPerSession: 32,
30
+ idleTimeoutMs: 30 * 60 * 1000,
31
+ maxInstances: 10,
32
+ });
33
+ ```
34
+
35
+ ```ts
36
+ import { AppStation, InProcessRuntime } from '@agentapps/station';
37
+
38
+ // Standalone mode — one shared instance
39
+ const controller = new AppStation({
40
+ appId: 'app.hello',
41
+ appVersion: '1.0.0',
42
+ runtime: new InProcessRuntime(appFactory),
43
+ mode: 'standalone',
44
+ });
45
+ ```
46
+
47
+ ## API
48
+
49
+ - **`AppStation`** — Core controller class. Manages control plane (handshake, sessions, health), session plane (proxy to instances), callbacks (secret/auth proxy with session validation), lifecycle (spawn, idle teardown, watchdog), and backpressure (max in-flight per session, max instances).
50
+ - **`AppStationConfig`** — Configuration: `appId`, `appVersion`, `runtime`, `openTimeoutMs`, `maxInflightPerSession`, `idleTimeoutMs`, `maxInstances`.
51
+ - **`InProcessRuntime`** — Runtime adapter that runs the app factory in the same process. Useful for testing and dev mode.
52
+ - **`RuntimeAdapter`** — Interface for custom runtime adapters (in-process, child process).
53
+ - **`AppFactory`** — Factory function `(transport: Transport) => void | Promise<void>` that wires an app to a transport.
54
+ - **`InstanceHandle`** — Handle to a running instance: `send(msg)`, `onMessage(handler)`, `terminate()`.
55
+ - **`SpawnConfig`** — Spawn configuration passed to the runtime adapter.
56
+
57
+ ## License
58
+
59
+ MIT
@@ -0,0 +1,46 @@
1
+ /**
2
+ * ApiKeyStore — persistence layer for API key records.
3
+ *
4
+ * API keys authenticate callers and link them to a Policy (permission
5
+ * policy). Keys are stored as SHA-256 hashes — the raw key is returned
6
+ * exactly once at creation and never persisted.
7
+ *
8
+ * Pluggable: in-memory for dev/tests, database-backed for production.
9
+ */
10
+ import type { ApiKeyRecord } from '@agentapps/protocol';
11
+ /** Compute the SHA-256 hex digest of a raw API key. */
12
+ export declare function hashApiKey(raw: string): string;
13
+ /** Generate a new API key with `aak_` prefix (32 random hex chars). */
14
+ export declare function generateApiKey(): {
15
+ raw: string;
16
+ hash: string;
17
+ prefix: string;
18
+ };
19
+ export interface ApiKeyStore {
20
+ /** Store a new API key record. */
21
+ create(record: ApiKeyRecord): Promise<void>;
22
+ /** Look up by key hash (the hot-path for every authenticated request). */
23
+ getByHash(keyHash: string): Promise<ApiKeyRecord | null>;
24
+ /** Look up by ID (for management). */
25
+ getById(id: string): Promise<ApiKeyRecord | null>;
26
+ /** List all keys (optionally filtered). Returns records without keyHash. */
27
+ list(filter?: {
28
+ userId?: string;
29
+ }): Promise<ApiKeyRecord[]>;
30
+ /** Soft-revoke a key by ID. Returns true if found. */
31
+ revoke(id: string): Promise<boolean>;
32
+ }
33
+ export declare class InMemoryApiKeyStore implements ApiKeyStore {
34
+ private readonly byId;
35
+ private readonly byHash;
36
+ create(record: ApiKeyRecord): Promise<void>;
37
+ getByHash(keyHash: string): Promise<ApiKeyRecord | null>;
38
+ getById(id: string): Promise<ApiKeyRecord | null>;
39
+ list(filter?: {
40
+ userId?: string;
41
+ }): Promise<ApiKeyRecord[]>;
42
+ revoke(id: string): Promise<boolean>;
43
+ /** Test helper: get the current count. */
44
+ get size(): number;
45
+ }
46
+ //# sourceMappingURL=api-key-store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api-key-store.d.ts","sourceRoot":"","sources":["../src/api-key-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMxD,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAK9E;AAMD,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C,0EAA0E;IAC1E,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAEzD,sCAAsC;IACtC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAElD,4EAA4E;IAC5E,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE5D,sDAAsD;IACtD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAMD,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAE9C,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA4BxD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAKjD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAW3D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1C,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
@@ -0,0 +1,84 @@
1
+ /**
2
+ * ApiKeyStore — persistence layer for API key records.
3
+ *
4
+ * API keys authenticate callers and link them to a Policy (permission
5
+ * policy). Keys are stored as SHA-256 hashes — the raw key is returned
6
+ * exactly once at creation and never persisted.
7
+ *
8
+ * Pluggable: in-memory for dev/tests, database-backed for production.
9
+ */
10
+ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
11
+ // ---------------------------------------------------------------------------
12
+ // Helpers
13
+ // ---------------------------------------------------------------------------
14
+ /** Compute the SHA-256 hex digest of a raw API key. */
15
+ export function hashApiKey(raw) {
16
+ return createHash('sha256').update(raw).digest('hex');
17
+ }
18
+ /** Generate a new API key with `aak_` prefix (32 random hex chars). */
19
+ export function generateApiKey() {
20
+ const bytes = randomBytes(16); // 16 bytes = 32 hex chars
21
+ const hex = bytes.toString('hex');
22
+ const raw = `aak_${hex}`;
23
+ return { raw, hash: hashApiKey(raw), prefix: raw.slice(0, 12) };
24
+ }
25
+ // ---------------------------------------------------------------------------
26
+ // In-memory implementation (dev/test)
27
+ // ---------------------------------------------------------------------------
28
+ export class InMemoryApiKeyStore {
29
+ byId = new Map();
30
+ byHash = new Map(); // hash -> id
31
+ async create(record) {
32
+ this.byId.set(record.id, { ...record });
33
+ this.byHash.set(record.keyHash, record.id);
34
+ }
35
+ async getByHash(keyHash) {
36
+ // Walk the hash index using timing-safe comparison to avoid
37
+ // leaking which hash prefix matched via timing side-channels.
38
+ const keyHashBuf = Buffer.from(keyHash, 'hex');
39
+ let matchedId;
40
+ for (const [storedHash, id] of this.byHash) {
41
+ const storedBuf = Buffer.from(storedHash, 'hex');
42
+ if (storedBuf.length === keyHashBuf.length && timingSafeEqual(storedBuf, keyHashBuf)) {
43
+ matchedId = id;
44
+ break;
45
+ }
46
+ }
47
+ if (!matchedId)
48
+ return null;
49
+ const record = this.byId.get(matchedId);
50
+ if (!record)
51
+ return null;
52
+ // Skip revoked keys.
53
+ if (record.revokedAt)
54
+ return null;
55
+ // Skip expired keys.
56
+ if (record.expiresAt && new Date(record.expiresAt) <= new Date())
57
+ return null;
58
+ return { ...record };
59
+ }
60
+ async getById(id) {
61
+ const record = this.byId.get(id);
62
+ return record ? { ...record } : null;
63
+ }
64
+ async list(filter) {
65
+ let records = [...this.byId.values()];
66
+ if (filter?.userId) {
67
+ records = records.filter((r) => r.identity.userId === filter.userId);
68
+ }
69
+ // Return copies without keyHash.
70
+ return records.map(({ keyHash: _, ...rest }) => rest);
71
+ }
72
+ async revoke(id) {
73
+ const record = this.byId.get(id);
74
+ if (!record)
75
+ return false;
76
+ record.revokedAt = new Date().toISOString();
77
+ return true;
78
+ }
79
+ /** Test helper: get the current count. */
80
+ get size() {
81
+ return this.byId.size;
82
+ }
83
+ }
84
+ //# sourceMappingURL=api-key-store.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api-key-store.js","sourceRoot":"","sources":["../src/api-key-store.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Agent App AppStation — core logic.
3
+ *
4
+ * The per-app-family component that owns instance lifecycle and proxies
5
+ * all traffic between host and instances. Handles:
6
+ * - Control plane: initialize, session_open/close, controller_health
7
+ * - Session plane: proxy to/from the correct instance
8
+ * - Requests: proxy instance→host secret/auth requests (with security)
9
+ * - Lifecycle: spawn timeout, idle teardown, session_status notifications
10
+ * - Backpressure: max in-flight per session, max instances
11
+ *
12
+ * Spec: docs/specs/agent-apps/controller-protocol.md
13
+ */
14
+ import { type Transport } from '@agentapps/protocol';
15
+ import { type TelemetryProvider } from './telemetry.js';
16
+ import type { RuntimeAdapter } from './types.js';
17
+ /** AppStation configuration. */
18
+ export interface AppStationConfig {
19
+ /** App catalog id (e.g., 'app.hello'). */
20
+ appId: string;
21
+ /** App version. */
22
+ appVersion: string;
23
+ /** Runtime adapter for spawning instances. */
24
+ runtime: RuntimeAdapter;
25
+ /** Session open timeout in ms (default: 60 000). */
26
+ openTimeoutMs?: number;
27
+ /** Max in-flight requests per session (default: 32). */
28
+ maxInflightPerSession?: number;
29
+ /** Idle timeout before instance teardown in ms (default: 30 min). */
30
+ idleTimeoutMs?: number;
31
+ /** Max concurrent instances (default: Infinity). */
32
+ maxInstances?: number;
33
+ /** Optional telemetry provider for metrics and tracing. */
34
+ telemetry?: TelemetryProvider;
35
+ /**
36
+ * Decide the Volume mount path for a new Instance from its `session_open`
37
+ * (VOL-REQ-5). Returning `undefined` means no mount.
38
+ */
39
+ resolveMountPath?: (open: {
40
+ installationId: string;
41
+ tenant: {
42
+ userId: string;
43
+ workspaceId?: string;
44
+ };
45
+ effectivePermissions?: {
46
+ permissions?: {
47
+ volume?: boolean;
48
+ };
49
+ };
50
+ }) => string | undefined;
51
+ }
52
+ /**
53
+ * Agent App AppStation.
54
+ *
55
+ * Usage:
56
+ * ```ts
57
+ * const ctrl = new AppStation({ appId, appVersion, runtime });
58
+ * ctrl.accept(transport); // host connects
59
+ * // ... host sends initialize, session_open, tool_call, etc.
60
+ * await ctrl.shutdown();
61
+ * ```
62
+ */
63
+ export declare class AppStation {
64
+ private readonly config;
65
+ private initialized;
66
+ /** The Host behind this connection, as declared at initialize (HOSTCAP-REQ-2). */
67
+ private host;
68
+ /** Tenant a single-user Host is bound to by its first session (HOSTCAP-REQ-6). */
69
+ private boundUserId;
70
+ private sessions;
71
+ private instances;
72
+ private hostTransport;
73
+ private hostUnsub;
74
+ private readonly openTimeoutMs;
75
+ private readonly maxInflight;
76
+ private readonly idleTimeoutMs;
77
+ private readonly maxInstances;
78
+ private readonly telemetry;
79
+ /** Track promptIds per session to prevent replay attacks. */
80
+ private readonly promptIds;
81
+ constructor(config: AppStationConfig);
82
+ /** Accept a host connection on the given transport. */
83
+ accept(transport: Transport): void;
84
+ /** Shut down the app station and all sessions. */
85
+ shutdown(): Promise<void>;
86
+ /** Number of active sessions. */
87
+ get sessionCount(): number;
88
+ /** Number of live instances. */
89
+ get instanceCount(): number;
90
+ private handleHostMessage;
91
+ /** REQ-2: Handshake and capability negotiation. */
92
+ private handleInitialize;
93
+ /** REQ-4, REQ-5: Tenant session open (idempotent, with instance reuse). */
94
+ private handleSessionOpen;
95
+ /** REQ-4: Session close. Does NOT immediately stop the instance (REQ-4). */
96
+ private handleSessionClose;
97
+ /** REQ-8: Aggregated app station health. */
98
+ private handleControllerHealth;
99
+ private routeToInstance;
100
+ /**
101
+ * Relay a message from an instance to the host.
102
+ *
103
+ * Security (REQ-7): validates sessionId on request types to prevent
104
+ * a compromised instance from reading another tenant's secrets.
105
+ */
106
+ private relayInstanceMessage;
107
+ private resetIdleTimer;
108
+ private handleIdleTimeout;
109
+ /** Emit a session_status notification to the host (REQ-5). */
110
+ private emitSessionStatus;
111
+ /** Send a message to the host. */
112
+ /**
113
+ * Answer an Instance's Request with PERMISSION_DENIED when the Permission
114
+ * it needs is not among the session's Effective Permissions. Returns true
115
+ * when the Request was answered here and must not reach the Host.
116
+ *
117
+ * @spec POLICY-REQ-8
118
+ */
119
+ private denyByPermission;
120
+ private hostSend;
121
+ /**
122
+ * Tell the Instance its session is established and which Host is behind it
123
+ * (HOSTCAP-REQ-2), so the SDK can expose `ctx.host`.
124
+ */
125
+ private notifySessionOpened;
126
+ /** Send an error response to the host. */
127
+ private sendError;
128
+ }
129
+ //# sourceMappingURL=app-station.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app-station.d.ts","sourceRoot":"","sources":["../src/app-station.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAKL,KAAK,SAAS,EAEf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjE,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,OAAO,EAAE,cAAc,CAAC;IACxB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACjD,oBAAoB,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE;gBAAE,MAAM,CAAC,EAAE,OAAO,CAAA;aAAE,CAAA;SAAE,CAAC;KAC/D,KAAK,MAAM,GAAG,SAAS,CAAC;CAC1B;AAwFD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IAwBT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAvBnC,OAAO,CAAC,WAAW,CAAS;IAC5B,kFAAkF;IAClF,OAAO,CAAC,IAAI,CAIoC;IAChD,kFAAkF;IAClF,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,SAAS,CAA4B;IAE7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAE9C,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;gBAE/B,MAAM,EAAE,gBAAgB;IAYrD,uDAAuD;IACvD,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAUlC,kDAAkD;IAC5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB/B,iCAAiC;IACjC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,gCAAgC;IAChC,IAAI,aAAa,IAAI,MAAM,CAE1B;YAMa,iBAAiB;IAiC/B,mDAAmD;IACnD,OAAO,CAAC,gBAAgB;IA4CxB,2EAA2E;YAC7D,iBAAiB;IA6L/B,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB;IA2C1B,4CAA4C;IAC5C,OAAO,CAAC,sBAAsB;IAkE9B,OAAO,CAAC,eAAe;IA4EvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAkE5B,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,iBAAiB;IAqBzB,8DAA8D;IAC9D,OAAO,CAAC,iBAAiB;IAQzB,kCAAkC;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,QAAQ;IAIhB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAe3B,0CAA0C;IAC1C,OAAO,CAAC,SAAS;CAQlB"}