@nifrajs/agent-protocol 3.2.0

package/README.md

@@ -0,0 +1,33 @@
+# @nifrajs/agent-protocol
+
+Small, backend-neutral contracts for local coding-agent sessions.
+
+The package contains versioned session snapshots, streamed assistant/tool/approval
+events, bounded live event streams, and backend interfaces. It has no runtime
+dependencies and does not import Nifra framework packages, model SDKs, or UI code.
+
+```ts
+import { createAgentEventStream } from "@nifrajs/agent-protocol"
+
+const events = createAgentEventStream(256)
+events.push(/* a versioned AgentEvent */)
+```
+
+Use `@nifrajs/pi` for the Pi backend or implement `AgentBackend` for another
+runtime. The protocol is intentionally small so CLI, desktop, mobile, and CI
+clients can share it without pulling in the Nifra application framework.
+
+## Version 1 compatibility
+
+Version 1 is additive. Hosts advertise capabilities and clients use only the negotiated intersection;
+an unsupported command is a stable `feature_unsupported` result. Optional fields are ignored by older
+peers, while a cursor gap returns `resync_required` instead of silently skipping evidence. A future
+major requires a recorded semantic incompatibility, dual decoders, cross-version fixtures, and an
+approved migration plan.
+
+Run evidence and lifecycle values are structural only: identifiers, statuses, counters, timestamps,
+digests, and opaque references. Prompts, model output, tool arguments, and filesystem paths do not
+belong in these public contracts.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Backend-neutral protocol for local coding-agent hosts.
+ *
+ * This package deliberately has no runtime dependencies. A Pi adapter, a Nifra-native backend,
+ * the CLI, and the Workbench can all implement or consume these contracts without pulling any
+ * framework, model provider, or UI code into an application.
+ */
+export declare const AGENT_PROTOCOL_VERSION: 1;
+export type AgentSessionStatus = "idle" | "running" | "waiting" | "completed" | "failed" | "stopped";
+export type AgentEventType = "session.started" | "session.updated" | "turn.started" | "assistant.delta" | "assistant.message" | "tool.started" | "tool.delta" | "tool.completed" | "approval.required" | "approval.resolved" | "repair.required" | "verification.completed" | "memory.compacted" | "extension.reloaded" | "session.completed" | "session.failed" | "session.stopped";
+export interface AgentSessionSnapshot {
+    readonly version: typeof AGENT_PROTOCOL_VERSION;
+    readonly id: string;
+    readonly backend: string;
+    readonly cwd: string;
+    readonly status: AgentSessionStatus;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly lastSeq: number;
+    readonly activeTurnId?: string;
+    readonly extensionRevision?: string;
+    readonly capabilities: readonly string[];
+}
+export interface AgentBackendInfo {
+    readonly name: string;
+    readonly version?: string;
+    readonly capabilities: readonly string[];
+}
+export interface AgentSessionEventBase {
+    readonly version: typeof AGENT_PROTOCOL_VERSION;
+    readonly sessionId: string;
+    readonly seq: number;
+    readonly at: number;
+    readonly type: AgentEventType;
+}
+export interface AgentSessionStartedEvent extends AgentSessionEventBase {
+    readonly type: "session.started";
+    readonly snapshot: AgentSessionSnapshot;
+}
+export interface AgentSessionUpdatedEvent extends AgentSessionEventBase {
+    readonly type: "session.updated";
+    readonly snapshot: AgentSessionSnapshot;
+}
+export interface AgentTurnStartedEvent extends AgentSessionEventBase {
+    readonly type: "turn.started";
+    readonly turnId: string;
+    readonly prompt: string;
+}
+export interface AgentAssistantDeltaEvent extends AgentSessionEventBase {
+    readonly type: "assistant.delta";
+    readonly turnId: string;
+    readonly text: string;
+}
+export interface AgentAssistantMessageEvent extends AgentSessionEventBase {
+    readonly type: "assistant.message";
+    readonly turnId: string;
+    readonly text: string;
+}
+export interface AgentToolStartedEvent extends AgentSessionEventBase {
+    readonly type: "tool.started";
+    readonly turnId: string;
+    readonly callId: string;
+    readonly name: string;
+    readonly input?: unknown;
+}
+export interface AgentToolDeltaEvent extends AgentSessionEventBase {
+    readonly type: "tool.delta";
+    readonly turnId: string;
+    readonly callId: string;
+    readonly text: string;
+}
+export interface AgentToolCompletedEvent extends AgentSessionEventBase {
+    readonly type: "tool.completed";
+    readonly turnId: string;
+    readonly callId: string;
+    readonly name: string;
+    readonly ok: boolean;
+    readonly output?: unknown;
+    readonly error?: AgentError;
+}
+export interface AgentApprovalRequiredEvent extends AgentSessionEventBase {
+    readonly type: "approval.required";
+    readonly turnId: string;
+    readonly approvalId: string;
+    readonly action: string;
+    readonly capability: string;
+    readonly reason?: string;
+}
+export interface AgentApprovalResolvedEvent extends AgentSessionEventBase {
+    readonly type: "approval.resolved";
+    readonly turnId?: string;
+    readonly approvalId: string;
+    readonly approved: boolean;
+    readonly reason?: string;
+}
+export interface AgentRepairTask {
+    readonly id: string;
+    readonly verification: "check" | "assure" | "test";
+    readonly cwd: string;
+    readonly reason: string;
+    readonly capabilities: readonly string[];
+    readonly output?: string;
+    readonly report?: unknown;
+}
+export interface AgentRepairRequiredEvent extends AgentSessionEventBase {
+    readonly type: "repair.required";
+    readonly turnId?: string;
+    readonly task: AgentRepairTask;
+}
+export interface AgentVerificationCompletedEvent extends AgentSessionEventBase {
+    readonly type: "verification.completed";
+    readonly name: string;
+    readonly ok: boolean;
+    readonly report?: unknown;
+}
+export interface AgentMemoryCompactedEvent extends AgentSessionEventBase {
+    readonly type: "memory.compacted";
+    readonly before: number;
+    readonly after: number;
+    readonly reason: "manual" | "threshold" | "overflow" | "workflow";
+}
+export interface AgentExtensionReloadedEvent extends AgentSessionEventBase {
+    readonly type: "extension.reloaded";
+    readonly revision: string;
+    readonly loaded: readonly string[];
+    readonly disabled: readonly string[];
+    readonly rolledBack: boolean;
+}
+export interface AgentSessionCompletedEvent extends AgentSessionEventBase {
+    readonly type: "session.completed";
+    readonly snapshot: AgentSessionSnapshot;
+}
+export interface AgentSessionFailedEvent extends AgentSessionEventBase {
+    readonly type: "session.failed";
+    readonly error: AgentError;
+    readonly recoverable: boolean;
+}
+export interface AgentSessionStoppedEvent extends AgentSessionEventBase {
+    readonly type: "session.stopped";
+    readonly reason?: string;
+}
+export type AgentEvent = AgentSessionStartedEvent | AgentSessionUpdatedEvent | AgentTurnStartedEvent | AgentAssistantDeltaEvent | AgentAssistantMessageEvent | AgentToolStartedEvent | AgentToolDeltaEvent | AgentToolCompletedEvent | AgentApprovalRequiredEvent | AgentApprovalResolvedEvent | AgentRepairRequiredEvent | AgentVerificationCompletedEvent | AgentMemoryCompactedEvent | AgentExtensionReloadedEvent | AgentSessionCompletedEvent | AgentSessionFailedEvent | AgentSessionStoppedEvent;
+/** Event payload before the transport adds protocol version, session id, sequence, and timestamp. */
+export type AgentEventPayload = Omit<AgentSessionStartedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentSessionUpdatedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentTurnStartedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentAssistantDeltaEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentAssistantMessageEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentToolStartedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentToolDeltaEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentToolCompletedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentApprovalRequiredEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentApprovalResolvedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentRepairRequiredEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentVerificationCompletedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentMemoryCompactedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentExtensionReloadedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentSessionCompletedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentSessionFailedEvent, "version" | "sessionId" | "seq" | "at"> | Omit<AgentSessionStoppedEvent, "version" | "sessionId" | "seq" | "at">;
+export interface AgentError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: unknown;
+}
+export interface CreateSessionInput {
+    readonly cwd: string;
+    readonly backend?: string;
+    readonly capabilities?: readonly string[];
+    readonly sessionId?: string;
+}
+export interface SendMessageInput {
+    readonly sessionId: string;
+    readonly message: string;
+    readonly signal?: AbortSignal;
+}
+export interface ForkSessionInput {
+    readonly sessionId: string;
+    readonly targetSessionId?: string;
+}
+export interface ForkSessionResult {
+    readonly sessionId: string;
+    readonly parentSessionId: string;
+}
+export interface AgentSessionCheckpoint {
+    readonly version: 1;
+    readonly sessionId: string;
+    readonly at: number;
+    readonly payload?: unknown;
+}
+export interface ReloadResult {
+    readonly revision: string;
+    readonly loaded: readonly string[];
+    readonly disabled: readonly string[];
+    readonly rolledBack: boolean;
+    readonly error?: AgentError;
+}
+export interface AgentBackend {
+    readonly info: AgentBackendInfo;
+    createSession(input: CreateSessionInput): Promise<AgentSessionSnapshot>;
+    send(input: SendMessageInput): AsyncIterable<AgentEvent>;
+    cancel(sessionId: string, reason?: string): Promise<void>;
+    snapshot(sessionId: string): Promise<AgentSessionSnapshot>;
+    /** Backends may provide native branching; the host can fall back to its session store. */
+    fork?(input: ForkSessionInput): Promise<ForkSessionResult>;
+    checkpoint?(sessionId: string, payload?: unknown): Promise<AgentSessionCheckpoint>;
+    reload(sessionId: string): Promise<ReloadResult>;
+    /** Resolve an approval surfaced by a backend UI/tool, when that backend supports interactive approvals. */
+    resolveApproval?(sessionId: string, approvalId: string, approved: boolean, reason?: string): Promise<boolean | undefined>;
+    close(sessionId: string): Promise<void>;
+}
+export interface AgentEventSink {
+    push(event: AgentEvent): void;
+    complete(): void;
+    fail(error: unknown): void;
+}
+export interface AgentEventStream extends AgentEventSink, AsyncIterableIterator<AgentEvent> {
+    readonly dropped: number;
+}
+/**
+ * Small bounded event stream for RPC clients and UIs. The authoritative event history belongs to
+ * the backend/session store; this live view may drop old transient events if a consumer falls behind.
+ */
+export declare function createAgentEventStream(maxQueueSize?: number): AgentEventStream;
+export declare function agentError(code: string, message: string, details?: unknown): AgentError;
+/**
+ * Orchestration value contracts (run plans, content-free evidence, artifact refs, effect keys).
+ * Additive to the session protocol; carries no behavior and no payload content.
+ */
+export * from "./orchestration.js";
+/**
+ * Additive run-lifecycle contracts (run snapshots, evidence-event envelopes, handoff snapshots,
+ * feature negotiation, cursor resume). Additive to the session protocol; carries no payload content.
+ */
+export * from "./run-lifecycle.js";
+export declare function isAgentEvent(value: unknown): value is AgentEvent;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,112 @@
+/**
+ * Backend-neutral protocol for local coding-agent hosts.
+ *
+ * This package deliberately has no runtime dependencies. A Pi adapter, a Nifra-native backend,
+ * the CLI, and the Workbench can all implement or consume these contracts without pulling any
+ * framework, model provider, or UI code into an application.
+ */
+export const AGENT_PROTOCOL_VERSION = 1;
+/**
+ * Small bounded event stream for RPC clients and UIs. The authoritative event history belongs to
+ * the backend/session store; this live view may drop old transient events if a consumer falls behind.
+ */
+export function createAgentEventStream(maxQueueSize = 256) {
+    if (!Number.isSafeInteger(maxQueueSize) || maxQueueSize < 1)
+        throw new RangeError("agent event stream: maxQueueSize must be a positive safe integer");
+    const queue = [];
+    const waiters = [];
+    let completed = false;
+    let failure;
+    let failed = false;
+    let dropped = 0;
+    const finish = () => {
+        if (!completed || queue.length > 0)
+            return;
+        while (waiters.length > 0) {
+            const waiter = waiters.shift();
+            if (failed)
+                waiter?.reject(failure);
+            else
+                waiter?.resolve({ done: true, value: undefined });
+        }
+    };
+    const stream = {
+        get dropped() {
+            return dropped;
+        },
+        push(event) {
+            if (completed)
+                return;
+            const waiter = waiters.shift();
+            if (waiter !== undefined) {
+                waiter.resolve({ done: false, value: event });
+                return;
+            }
+            if (queue.length >= maxQueueSize) {
+                queue.shift();
+                dropped += 1;
+            }
+            queue.push(event);
+        },
+        complete() {
+            completed = true;
+            finish();
+        },
+        fail(error) {
+            if (completed)
+                return;
+            failure = error;
+            failed = true;
+            completed = true;
+            finish();
+        },
+        next() {
+            const event = queue.shift();
+            if (event !== undefined)
+                return Promise.resolve({ done: false, value: event });
+            if (completed) {
+                if (failed)
+                    return Promise.reject(failure);
+                return Promise.resolve({ done: true, value: undefined });
+            }
+            return new Promise((resolve, reject) => waiters.push({ resolve, reject }));
+        },
+        return() {
+            queue.length = 0;
+            completed = true;
+            finish();
+            return Promise.resolve({ done: true, value: undefined });
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+    return stream;
+}
+export function agentError(code, message, details) {
+    return details === undefined ? { code, message } : { code, message, details };
+}
+/**
+ * Orchestration value contracts (run plans, content-free evidence, artifact refs, effect keys).
+ * Additive to the session protocol; carries no behavior and no payload content.
+ */
+export * from "./orchestration.js";
+/**
+ * Additive run-lifecycle contracts (run snapshots, evidence-event envelopes, handoff snapshots,
+ * feature negotiation, cursor resume). Additive to the session protocol; carries no payload content.
+ */
+export * from "./run-lifecycle.js";
+export function isAgentEvent(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (record.version === AGENT_PROTOCOL_VERSION &&
+        typeof record.sessionId === "string" &&
+        typeof record.seq === "number" &&
+        Number.isSafeInteger(record.seq) &&
+        typeof record.at === "number" &&
+        Number.isFinite(record.at) &&
+        typeof record.type === "string" &&
+        record.type.includes("."));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/orchestration.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Orchestration value contracts: declarative run plans, content-free run evidence, artifact
+ * references, and the effect-key identity. Additive to the session protocol; carries no behavior,
+ * no runtime dependency, and - by construction - no payload content.
+ *
+ * The privacy invariant lives in the parsers here: {@link parseRunEvidence} and
+ * {@link parseArtifactRef} accept only the declared content-free keys and reject any record over
+ * {@link EVIDENCE_MAX_BYTES}. A prompt, model output, or tool payload cannot round-trip through
+ * these contracts. Raw payloads travel only through an {@link ArtifactPort} the caller owns.
+ */
+/** Orchestration contract version. Additive to the session `AGENT_PROTOCOL_VERSION`. */
+export declare const RUN_PLAN_VERSION: 1;
+/** Hard cap on a single serialized evidence record. A content-free record never approaches this. */
+export declare const EVIDENCE_MAX_BYTES = 4096;
+/**
+ * Keys that would carry payload content. They are never valid on evidence or artifact records and
+ * are rejected by the strict parsers even if they would otherwise fit the size cap.
+ */
+export declare const FORBIDDEN_CONTENT_KEYS: readonly string[];
+/** A content-free pointer to a payload the caller chose to retain out of band. */
+export interface ArtifactRef {
+    /** Caller-namespaced id. Opaque to nifra. */
+    readonly id: string;
+    /** SHA-256 hex of the payload, for integrity and correlation. Content-free. */
+    readonly digest: string;
+    readonly bytes: number;
+    readonly mediaType: string;
+    /** Optional caller-opaque locator (e.g. a private URI). nifra never dereferences it. */
+    readonly locator?: string;
+}
+/** What a payload is and where it came from, handed to the port at `put` time. */
+export interface ArtifactContext {
+    readonly planDigest: string;
+    readonly nodeId: string;
+    /** e.g. "prompt" | "model_output" | "tool_input" | "tool_output". */
+    readonly kind: string;
+}
+/**
+ * Caller-owned sink for raw payloads - the ONLY place payload bytes leave transient execution.
+ * The public repo ships only a discarding no-op and a disposable in-memory test port. No public
+ * implementation persists.
+ */
+export interface ArtifactPort {
+    put(payload: Uint8Array, ctx: ArtifactContext): ArtifactRef | Promise<ArtifactRef>;
+}
+/** The stable, content-free identity of one side-effecting node attempt-boundary. */
+export interface NodeEffectKey {
+    /** SHA-256 hex over the canonical effect material. 64 lowercase hex chars. */
+    readonly digest: string;
+    /** Non-secret structural coordinates, safe to log. */
+    readonly planDigest: string;
+    readonly nodeId: string;
+}
+/** Leaf kinds resolve a StepCatalog handler; structural kinds compose child nodes. */
+export type RunLeafKind = "task" | "verify" | "approve" | "checkpoint" | "handoff" | "subagent";
+export type RunStructuralKind = "sequence" | "parallel" | "retry" | "branch";
+/** Declarative node kinds. Each maps to an existing workflow primitive at compile time. */
+export type RunNodeKind = RunLeafKind | RunStructuralKind;
+/** Bounded retry policy for a leaf node. Attempts map to the kernel's retry step. */
+export interface RunRetryPolicy {
+    readonly attempts: number;
+    readonly backoffMs?: number;
+}
+/** A leaf plan node. `step` names a handler resolved locally through a StepCatalog. */
+export interface RunLeafNode {
+    readonly id: string;
+    readonly kind: RunLeafKind;
+    /** StepCatalog key. The handler is registered locally and never persisted in the plan. */
+    readonly step: string;
+    /** Only meaningful on top-level nodes; nested children may not declare it. */
+    readonly dependsOn?: readonly string[];
+    /** Required for `approve`; ignored otherwise. */
+    readonly reason?: string;
+    /** When set, the compiler asserts the resolved catalog step declares this exact version. */
+    readonly stepVersion?: number;
+    /** Wraps this leaf's compiled step in a bounded retry. */
+    readonly retry?: RunRetryPolicy;
+}
+/** An ordered composite. Children run in declaration order. */
+export interface RunSequenceNode {
+    readonly id: string;
+    readonly kind: "sequence";
+    readonly children: readonly RunNode[];
+    readonly dependsOn?: readonly string[];
+}
+/** A bounded fan-out. Effective concurrency is the lower of this, the host, and the child count. */
+export interface RunParallelNode {
+    readonly id: string;
+    readonly kind: "parallel";
+    readonly children: readonly RunNode[];
+    readonly maxConcurrency?: number;
+    readonly dependsOn?: readonly string[];
+}
+/** A bounded retry wrapping a single child node. */
+export interface RunRetryNode {
+    readonly id: string;
+    readonly kind: "retry";
+    readonly child: RunNode;
+    readonly attempts: number;
+    readonly backoffMs?: number;
+    readonly dependsOn?: readonly string[];
+}
+/** A conditional. `step` names a predicate catalog handler selecting `then` or `otherwise`. */
+export interface RunBranchNode {
+    readonly id: string;
+    readonly kind: "branch";
+    readonly step: string;
+    readonly then: RunNode;
+    readonly otherwise?: RunNode;
+    readonly dependsOn?: readonly string[];
+}
+/** A serializable, closure-free plan node. Structural kinds nest into a tree. */
+export type RunNode = RunLeafNode | RunSequenceNode | RunParallelNode | RunRetryNode | RunBranchNode;
+/** A serializable, closure-free run plan. Top-level nodes form a DAG; each node may nest a tree. */
+export interface RunPlan {
+    readonly version: typeof RUN_PLAN_VERSION;
+    readonly id: string;
+    readonly nodes: readonly RunNode[];
+}
+export type RunEvidenceStatus = "started" | "completed" | "failed";
+/** The content-free projection of one run transition. Every field is id/hash/counter/status/timing. */
+export interface RunEvidence {
+    readonly version: typeof RUN_PLAN_VERSION;
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly nodeId: string;
+    readonly status: RunEvidenceStatus;
+    readonly seq: number;
+    /** NodeEffectKey.digest when the node declared an effect selector; absent otherwise. */
+    readonly effectKey?: string;
+    /** Whether the step declared an idempotency selector. */
+    readonly idempotent: boolean;
+    readonly artifacts?: readonly ArtifactRef[];
+    readonly errorCode?: string;
+    readonly durationMs?: number;
+}
+/** Thrown by every parser in this module on malformed or content-bearing input. Fails closed. */
+export declare class RunContractError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** Parse a content-free artifact reference. Rejects any non-schema or content key. */
+export declare function parseArtifactRef(value: unknown): ArtifactRef;
+/** Parse a declarative run plan. Rejects closures, unknown keys, and structural errors. */
+export declare function parseRunPlan(value: unknown): RunPlan;
+/** Parse a content-free evidence record. Rejects content keys and any record over the size cap. */
+export declare function parseRunEvidence(value: unknown): RunEvidence;
+/** Assert a record serializes within the hard cap. Public reference records are content-free. */
+export declare function assertEvidenceSize(evidence: RunEvidence): void;
+//# sourceMappingURL=orchestration.d.ts.map

package/dist/orchestration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration.d.ts","sourceRoot":"","sources":["../src/orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,EAAG,CAAU,CAAA;AAE1C,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAalD,CAAA;AAIF,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,eAAe,GAAG,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACnF;AAID,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAID,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,CAAA;AAC/F,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE5E,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,iBAAiB,CAAA;AAEzD,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAA;CAChC;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,iFAAiF;AACjF,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,GAAG,YAAY,GAAG,aAAa,CAAA;AAEpG,oGAAoG;AACpG,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,gBAAgB,CAAA;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;CACnC;AAID,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;AAElE,uGAAuG;AACvG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,gBAAgB,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAID,iGAAiG;AACjG,qBAAa,gBAAiB,SAAQ,KAAK;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAsCD,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAkB5D;AAwHD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAkBpD;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CA4C5D;AAaD,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAI9D"}