@mengruo/dsh-vision-toolkit 0.0.1

package/lib/evidence-cache.js

@@ -0,0 +1,350 @@
+/** Durable, Session-scoped cache for image descriptions used by model variants. */
+import { createHash } from 'node:crypto';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+import { UPSTREAM_COMMIT } from "./version.js";
+/** Bump only when the model-visible evidence contract changes incompatibly. */
+export const EVIDENCE_CONTRACT_VERSION = 1;
+/** Persistent cache bounds keep the Profile storage proportional and predictable. */
+const DEFAULT_PERSISTED_ENTRY_LIMIT = 512;
+const DEFAULT_PERSISTED_BYTE_LIMIT = 8 * 1024 * 1024;
+const DEFAULT_PERSISTED_ENTRY_BYTE_LIMIT = 64 * 1024;
+const MAX_SCHEMA_TEXT_CHARS = 256 * 1024;
+const MAX_SCHEMA_RECORD_CHARS = 512 * 1024;
+const hexDigestSchema = z.string().regex(/^[0-9a-f]{64}$/u);
+const sessionIdentitySchema = z.object({
+    createdAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    cwd: z.string().optional(),
+});
+const evidenceRecordSchema = z.object({
+    contractVersion: z.number().int().nonnegative(),
+    sessionId: z.string().min(1),
+    session: sessionIdentitySchema,
+    attachmentId: z.string().min(1),
+    promptHash: hexDigestSchema,
+    runtimeHash: hexDigestSchema,
+    text: z.string().min(1).max(MAX_SCHEMA_TEXT_CHARS),
+    storedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+});
+/** Plugin-owned sidecar domain; the host backend handles atomicity and file safety. */
+export const evidenceCacheDomainSpec = defineDomain({
+    name: 'vision_toolkit_evidence',
+    version: 0,
+    tables: {
+        // Keep the durable boundary tolerant of one damaged cache payload: each
+        // record is parsed and validated independently below, so corruption causes
+        // a miss instead of preventing the entire optional domain from opening.
+        evidence: domainTable(z.string().max(MAX_SCHEMA_RECORD_CHARS)),
+    },
+});
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Fingerprint every runtime setting that can change the generated description. */
+export function evidenceRuntimeFingerprint(config, credentialSha256, sslVerify) {
+    return hash(JSON.stringify({
+        upstreamCommit: UPSTREAM_COMMIT,
+        provider: {
+            baseUrl: config.provider.baseUrl,
+            credential: {
+                ref: String(config.provider.credential),
+                sha256: credentialSha256 ?? null,
+            },
+            model: config.provider.model,
+            protocol: config.provider.protocol,
+            anthropicThinking: config.provider.anthropicThinking,
+            sslVerify: sslVerify ?? null,
+            userAgent: config.provider.userAgent,
+        },
+        language: config.language,
+        timeoutMs: config.timeoutMs,
+        concurrency: config.concurrency,
+        maxImageBytes: config.maxImageBytes,
+        maxImagePixels: config.maxImagePixels,
+        runtime: config.runtime,
+    }));
+}
+/** Build a non-secret cache key from the Session, attachment, focus, and runtime contract. */
+export function createEvidenceCacheKey(input) {
+    const promptHash = hash(input.prompt);
+    const digest = hash(JSON.stringify([
+        EVIDENCE_CONTRACT_VERSION,
+        input.sessionId ?? '',
+        input.sessionIdentity?.createdAt ?? '',
+        input.sessionIdentity?.cwd ?? '',
+        input.attachmentId,
+        promptHash,
+        input.runtimeHash,
+    ]));
+    return Object.freeze({
+        digest,
+        contractVersion: EVIDENCE_CONTRACT_VERSION,
+        ...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
+        ...(input.sessionIdentity === undefined ? {} : { sessionCreatedAt: input.sessionIdentity.createdAt }),
+        ...(input.sessionIdentity?.cwd === undefined ? {} : { sessionCwd: input.sessionIdentity.cwd }),
+        attachmentId: input.attachmentId,
+        promptHash,
+        runtimeHash: input.runtimeHash,
+    });
+}
+/** Bounded promise cache; concurrent readers join one load and rejected loads are evicted. */
+export class EvidenceCache {
+    limit;
+    persistence;
+    entries = new Map();
+    constructor(limit, persistence) {
+        this.limit = limit;
+        this.persistence = persistence;
+    }
+    /** Read a memory/durable hit or compute and persist one model-visible result. */
+    read(key, load) {
+        const memoryKey = typeof key === 'string' ? key : key.digest;
+        const existing = this.entries.get(memoryKey);
+        if (existing !== undefined) {
+            // Refresh recency: Map iteration order is insertion order.
+            this.entries.delete(memoryKey);
+            this.entries.set(memoryKey, existing);
+            return existing;
+        }
+        const pending = (async () => {
+            if (typeof key !== 'string' && this.persistence !== undefined) {
+                try {
+                    const persisted = await this.persistence.read(key);
+                    if (persisted !== undefined)
+                        return persisted;
+                }
+                catch {
+                    // Persistence is an optimization; a damaged/unavailable sidecar must
+                    // never block the model request from recomputing evidence.
+                }
+            }
+            const block = await load();
+            if (typeof key !== 'string' && this.persistence !== undefined) {
+                try {
+                    await this.persistence.write(key, block);
+                }
+                catch {
+                    // Keep the process-local result even when durability fails.
+                }
+            }
+            return block;
+        })().then(block => block, (error) => {
+            // Only evict our own entry: this promise may have been LRU-evicted and
+            // the key re-populated by a newer read meanwhile.
+            if (this.entries.get(memoryKey) === pending) {
+                this.entries.delete(memoryKey);
+            }
+            throw error;
+        });
+        this.entries.set(memoryKey, pending);
+        while (this.entries.size > this.limit) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        return pending;
+    }
+    /** Drop process-local descriptions; durable rows stay versioned by their runtime fingerprint. */
+    clear() {
+        this.entries.clear();
+    }
+}
+function identityOf(header) {
+    return Object.freeze({
+        createdAt: header.createdAt,
+        ...(header.cwd === undefined ? {} : { cwd: header.cwd }),
+    });
+}
+function sameIdentity(record, header) {
+    return record.session.createdAt === header.createdAt && record.session.cwd === header.cwd;
+}
+function matchesKey(record, key) {
+    return record.contractVersion === key.contractVersion
+        && record.sessionId === key.sessionId
+        && record.attachmentId === key.attachmentId
+        && record.promptHash === key.promptHash
+        && record.runtimeHash === key.runtimeHash;
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function parseRecord(value) {
+    try {
+        const parsed = JSON.parse(value);
+        const result = evidenceRecordSchema.safeParse(parsed);
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Official DSH storage-domain sidecar used to survive Profile restarts. */
+export class SessionEvidenceStore {
+    ctx;
+    storage;
+    storageFiber;
+    storageReady;
+    mutationTail = Promise.resolve();
+    flushes = new Map();
+    warned = false;
+    maxEntries;
+    maxBytes;
+    maxEntryBytes;
+    now;
+    constructor(ctx, options = {}) {
+        this.ctx = ctx;
+        this.maxEntries = options.maxEntries ?? DEFAULT_PERSISTED_ENTRY_LIMIT;
+        this.maxBytes = options.maxBytes ?? DEFAULT_PERSISTED_BYTE_LIMIT;
+        this.maxEntryBytes = options.maxEntryBytes ?? DEFAULT_PERSISTED_ENTRY_BYTE_LIMIT;
+        this.now = options.now ?? Date.now;
+        if (typeof ctx.inject !== 'function')
+            return;
+        this.storageFiber = ctx.inject(['storageDomain'], async (storageCtx) => {
+            const domain = await storageCtx.storageDomain.open(evidenceCacheDomainSpec);
+            const binding = { table: domain.table('evidence') };
+            try {
+                await this.enqueueMutation(async () => { await this.prune(binding.table); });
+                this.storage = binding;
+            }
+            catch (error) {
+                await domain.close();
+                throw error;
+            }
+            return async () => {
+                if (this.storage === binding)
+                    this.storage = undefined;
+                await this.mutationTail;
+                await domain.close();
+            };
+        });
+        this.storageReady = Promise.resolve(this.storageFiber).then(() => undefined, (error) => { this.warnOnce(error); });
+    }
+    /** Release the optional storage binding with the owning variant lifecycle. */
+    dispose() {
+        const fiber = this.storageFiber;
+        this.storageFiber = undefined;
+        this.storageReady = undefined;
+        if (fiber !== undefined)
+            void fiber.dispose().catch(error => { this.warnOnce(error); });
+    }
+    async read(key) {
+        const session = this.sessionFor(key);
+        if (session === undefined)
+            return undefined;
+        const binding = await this.prepareStorage();
+        if (binding === undefined)
+            return undefined;
+        const stored = binding.table.get(key.digest);
+        const record = stored === undefined ? undefined : parseRecord(stored);
+        if (record === undefined || !matchesKey(record, key) || !sameIdentity(record, session.header)) {
+            return undefined;
+        }
+        if (byteLength(record.text) > this.maxEntryBytes)
+            return undefined;
+        return { type: 'text', text: record.text };
+    }
+    async write(key, block) {
+        if (block.type !== 'text' || block.text.length === 0 || byteLength(block.text) > this.maxEntryBytes)
+            return;
+        const session = this.sessionFor(key);
+        if (session === undefined)
+            return;
+        const binding = await this.prepareStorage();
+        if (binding === undefined)
+            return;
+        try {
+            const participated = await this.flushSession(session);
+            if (!participated)
+                return;
+            const record = Object.freeze({
+                contractVersion: key.contractVersion,
+                sessionId: key.sessionId,
+                session: identityOf(session.header),
+                attachmentId: key.attachmentId,
+                promptHash: key.promptHash,
+                runtimeHash: key.runtimeHash,
+                text: block.text,
+                storedAt: this.now(),
+            });
+            await this.enqueueMutation(async () => {
+                await binding.table.put(key.digest, JSON.stringify(record));
+                await this.prune(binding.table);
+            });
+        }
+        catch (error) {
+            this.warnOnce(error);
+        }
+    }
+    sessionFor(key) {
+        if (key.sessionId === undefined)
+            return undefined;
+        const session = this.ctx.sessions.get(key.sessionId);
+        if (session === undefined)
+            return undefined;
+        if (key.sessionCreatedAt !== undefined
+            && (session.header.createdAt !== key.sessionCreatedAt || session.header.cwd !== key.sessionCwd)) {
+            return undefined;
+        }
+        return session;
+    }
+    async prepareStorage() {
+        if (this.storage !== undefined)
+            return this.storage;
+        if (this.ctx.get('storageDomain') === undefined)
+            return undefined;
+        await this.storageReady;
+        return this.storage;
+    }
+    enqueueMutation(operation) {
+        const result = this.mutationTail.then(operation);
+        this.mutationTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    flushSession(session) {
+        const key = `${session.id}\u0000${session.header.createdAt}\u0000${session.header.cwd ?? ''}`;
+        const existing = this.flushes.get(key);
+        if (existing !== undefined)
+            return existing;
+        const pending = this.ctx.sessions.flush(session).finally(() => {
+            if (this.flushes.get(key) === pending)
+                this.flushes.delete(key);
+        });
+        this.flushes.set(key, pending);
+        return pending;
+    }
+    async prune(table) {
+        const records = [...table.entries()].map(([key, stored]) => {
+            const record = parseRecord(stored);
+            return {
+                key,
+                bytes: byteLength(stored),
+                storedAt: record?.storedAt ?? -1,
+                valid: record !== undefined && byteLength(record.text) <= this.maxEntryBytes,
+            };
+        });
+        let totalBytes = records.reduce((sum, record) => sum + record.bytes, 0);
+        let totalEntries = records.length;
+        records.sort((left, right) => Number(left.valid) - Number(right.valid)
+            || left.storedAt - right.storedAt
+            || left.key.localeCompare(right.key));
+        for (const record of records) {
+            if (record.valid && totalEntries <= this.maxEntries && totalBytes <= this.maxBytes)
+                break;
+            if (await table.delete(record.key)) {
+                totalEntries -= 1;
+                totalBytes -= record.bytes;
+            }
+        }
+    }
+    warnOnce(error) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        this.ctx.logger?.warn('dsh-vision-toolkit: persistent image evidence cache is unavailable; using the process cache only. %s', messageOf(error).slice(0, 500));
+    }
+}
+//# sourceMappingURL=evidence-cache.js.map

package/lib/evidence-cache.js.map

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

package/lib/exposure.js

@@ -0,0 +1,247 @@
+/**
+ * Agent-scoped progressive exposure for the model-facing visual tools.
+ * Runtime readiness is global, while tool schemas enter only an Agent through
+ * the matching Skill or its bootstrap tool; administrative diagnostics stay on
+ * the Web seam.
+ * @module dsh-vision-toolkit/exposure
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { VISION_SKILLS_CONTENT, VISION_SKILLS_NAME } from "./skill.js";
+import { VISION_TOOL_NAMES } from "./tools.js";
+/** Small bootstrap tool retained only until the current Agent gains visual tools. */
+export const VISION_TOOLKIT_ACTIVATE = 'vision_toolkit_activate';
+/** Skill name used by releases before the rename to vision-skills. */
+export const LEGACY_VISION_TOOLS_SKILL_NAME = 'vision-tools';
+/** Unique pre-rename line in bundled instructions, kept for Session restore. */
+export const LEGACY_VISION_TOOLS_SKILL_MARKER = 'If this content arrived through a direct `/vision-tools` invocation and the';
+function renderJson(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isBundledSkillName(name) {
+    return name === VISION_SKILLS_NAME || name === LEGACY_VISION_TOOLS_SKILL_NAME;
+}
+function isBundledSkillContent(text) {
+    return text.includes(VISION_SKILLS_CONTENT) || text.includes(LEGACY_VISION_TOOLS_SKILL_MARKER);
+}
+function isVisionSkillArguments(value) {
+    return isRecord(value) && isBundledSkillName(value.name);
+}
+function nativeSkillCall(raw) {
+    try {
+        return isVisionSkillArguments(JSON.parse(raw));
+    }
+    catch {
+        return false;
+    }
+}
+function containsBundledSkillContent(blocks) {
+    return blocks.some(block => isRecord(block)
+        && block.type === 'text'
+        && typeof block.text === 'string'
+        && isBundledSkillContent(block.text));
+}
+function isBundledSkillResult(value) {
+    return isRecord(value)
+        && isBundledSkillName(value.name)
+        && typeof value.content === 'string'
+        && isBundledSkillContent(value.content);
+}
+/** Whether durable history proves that this Session loaded the bundled Skill. */
+function hasLoadedVisionSkill(session) {
+    const nativeCalls = new Set();
+    for (const event of session.events) {
+        if (event.type === 'user/message') {
+            const source = event.data.source;
+            if (source.kind === 'skill-invocation'
+                && isBundledSkillName(source.name)
+                && containsBundledSkillContent(event.data.content))
+                return true;
+            continue;
+        }
+        if (event.type === 'tool/call') {
+            if (event.data.name === 'skill' && nativeSkillCall(event.data.arguments)) {
+                nativeCalls.add(String(event.data.callId));
+            }
+            continue;
+        }
+        if (event.type === 'tool/result') {
+            const [block] = event.data.message.content;
+            if (block?.type === 'tool-result'
+                && block.isError !== true
+                && nativeCalls.has(String(block.toolCallId))
+                && containsBundledSkillContent(block.content))
+                return true;
+            continue;
+        }
+        if (event.type === 'tool/code-dispatch'
+            && event.data.name === 'skill'
+            && event.data.isError === false
+            && isVisionSkillArguments(event.data.arguments)
+            && containsBundledSkillContent(event.data.content))
+            return true;
+    }
+    return false;
+}
+/**
+ * Owns one progressive-exposure generation for a ready Vision Toolkit runtime.
+ * The bootstrap tool is global; visual definitions are created and registered
+ * in an Agent scope after the Skill load is durable, just succeeded, or the
+ * model explicitly invokes the bootstrap fallback.
+ */
+export class VisionToolExposure {
+    ctx;
+    createTools;
+    activationTool;
+    states = new Map();
+    installed = false;
+    /**
+     * @param ctx - Plugin context with Tool and Agent registries.
+     * @param createTools - Fresh definitions bound to the current runtime generation.
+     */
+    constructor(ctx, createTools) {
+        this.ctx = ctx;
+        this.createTools = createTools;
+        this.activationTool = defineTool({
+            name: VISION_TOOLKIT_ACTIVATE,
+            description: `Activate the independent Vision Toolkit execution tools for this Agent: ${Object.values(VISION_TOOL_NAMES).join(', ')}. `
+                + `Loading the ${VISION_SKILLS_NAME} Skill normally activates them automatically; call this once when the visual tools are still absent, then use them for image understanding, OCR, UI detection, and related tasks. `
+                + 'It is safe to call before the Skill is loaded, and this activation tool disappears after success.',
+            parameters: {},
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        activated: { type: 'boolean', required: true },
+                        tools: { type: 'array', items: { type: 'string' }, required: true },
+                    },
+                },
+                render: renderJson,
+            },
+            execute: (_args, exec) => {
+                if (exec.agent === undefined) {
+                    throw new Error(`${VISION_TOOLKIT_ACTIVATE}: an Agent Session is required`);
+                }
+                return Promise.resolve(this.activate(exec.agent));
+            },
+            presentCall: () => ({ card: 'generic', title: 'Activate vision tools', kind: 'execute' }),
+        });
+    }
+    /** Install lifecycle listeners and adopt Agents that already exist. */
+    install() {
+        if (this.installed)
+            throw new Error('dsh-vision-toolkit: progressive exposure is already installed');
+        this.installed = true;
+        const listeners = [
+            this.ctx.on('agent/created', ({ agent }) => { this.attach(agent); }),
+            this.ctx.on('agent/disposed', ({ agent }) => { this.detach(agent); }),
+            this.ctx.on('session/event', (session, event) => {
+                if (event.type === 'step/end')
+                    this.applyHideActivationForSession(session);
+            }),
+            this.ctx.on('tools/result', (exec, result) => {
+                if (result.isError === false
+                    && exec.name === 'skill'
+                    && exec.agent !== undefined
+                    && isVisionSkillArguments(exec.arguments)
+                    && isBundledSkillResult(result.value)) {
+                    this.activate(exec.agent);
+                }
+                return undefined;
+            }),
+        ];
+        try {
+            for (const agent of this.ctx.agents.list())
+                this.attach(agent);
+        }
+        catch (error) {
+            for (const dispose of listeners.reverse())
+                dispose();
+            this.disposeStates();
+            this.installed = false;
+            throw error;
+        }
+        return () => {
+            if (!this.installed)
+                return;
+            this.installed = false;
+            for (const dispose of listeners.reverse())
+                dispose();
+            this.disposeStates();
+        };
+    }
+    attach(agent) {
+        if (this.states.has(agent))
+            return;
+        this.states.set(agent, { active: false, toolDisposers: [], toolNames: [] });
+        if (hasLoadedVisionSkill(agent.session))
+            this.activate(agent);
+    }
+    activate(agent) {
+        this.attach(agent);
+        const state = this.states.get(agent);
+        /* v8 ignore next -- attach() synchronously creates this exact entry. */
+        if (state === undefined)
+            throw new Error(`dsh-vision-toolkit: Agent ${String(agent.id)} has no exposure state`);
+        if (state.active)
+            return { activated: false, tools: [...state.toolNames] };
+        const definitions = this.createTools();
+        const toolDisposers = [];
+        try {
+            for (const definition of definitions)
+                toolDisposers.push(agent.ctx.tools.register(definition));
+            // A Skill call and the bootstrap can be issued in the same model step.
+            // Restricting immediately would turn the still-in-flight bootstrap call
+            // into an UNKNOWN_TOOL error, so live sessions hide at step/end.
+            if (!this.isLiveSession(agent.session))
+                this.applyHideActivation(agent);
+        }
+        catch (error) {
+            for (const dispose of toolDisposers.reverse())
+                dispose();
+            throw error;
+        }
+        state.active = true;
+        state.toolDisposers = toolDisposers;
+        state.toolNames = definitions.map(definition => definition.name);
+        return { activated: true, tools: [...state.toolNames] };
+    }
+    /** Whether the session is attached to the live SessionStore (production). */
+    isLiveSession(session) {
+        return this.ctx.sessions.get(session.id) === session;
+    }
+    applyHideActivationForSession(session) {
+        for (const agent of this.ctx.agents.list()) {
+            if (agent.session === session && this.states.get(agent)?.active === true) {
+                this.applyHideActivation(agent);
+            }
+        }
+    }
+    applyHideActivation(agent) {
+        const state = this.states.get(agent);
+        if (state === undefined || state.liftRestriction !== undefined)
+            return;
+        state.liftRestriction = agent.ctx.tools.restrict({ deny: [VISION_TOOLKIT_ACTIVATE] });
+    }
+    detach(agent) {
+        const state = this.states.get(agent);
+        if (state === undefined)
+            return;
+        this.states.delete(agent);
+        this.disposeState(state);
+    }
+    disposeStates() {
+        for (const state of this.states.values())
+            this.disposeState(state);
+        this.states.clear();
+    }
+    disposeState(state) {
+        state.liftRestriction?.();
+        for (const dispose of state.toolDisposers.reverse())
+            dispose();
+    }
+}
+//# sourceMappingURL=exposure.js.map

package/lib/exposure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposure.js","sourceRoot":"","sources":["../src/exposure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,UAAU,EAAuB,MAAM,wBAAwB,CAAA;AAExE,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C,qFAAqF;AACrF,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAA;AAEhE,sEAAsE;AACtE,MAAM,CAAC,MAAM,8BAA8B,GAAG,cAAc,CAAA;AAE5D,gFAAgF;AAChF,MAAM,CAAC,MAAM,gCAAgC,GAAG,6EAA6E,CAAA;AAe7H,SAAS,UAAU,CAAC,KAAc,EAAE,KAAc;IAChD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;AACjE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAa;IACvC,OAAO,IAAI,KAAK,kBAAkB,IAAI,IAAI,KAAK,8BAA8B,CAAA;AAC/E,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,gCAAgC,CAAC,CAAA;AAChG,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAc;IAC5C,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AAC1D,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,CAAC,MAA0B;IAC7D,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;WACtC,KAAK,CAAC,IAAI,KAAK,MAAM;WACrB,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;WAC9B,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;AACzC,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,QAAQ,CAAC,KAAK,CAAC;WACjB,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC;WAC9B,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;WACjC,qBAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,iFAAiF;AACjF,SAAS,oBAAoB,CAAC,OAAgB;IAC5C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IACrC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAA;YAChC,IAAI,MAAM,CAAC,IAAI,KAAK,kBAAkB;mBACjC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC;mBAC/B,2BAA2B,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAA;YACjE,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBACzE,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;YAC5C,CAAC;YACD,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACjC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAA;YAC1C,IAAI,KAAK,EAAE,IAAI,KAAK,aAAa;mBAC5B,KAAK,CAAC,OAAO,KAAK,IAAI;mBACtB,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;mBACzC,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC5D,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,oBAAoB;eAClC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO;eAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK;eAC5B,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;eAC5C,2BAA2B,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAA;IACnE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAUV;IACA;IAVV,cAAc,CAAgB;IACtB,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAA;IACjD,SAAS,GAAG,KAAK,CAAA;IAEzB;;;OAGG;IACH,YACmB,GAAY,EACZ,WAAmC;QADnC,QAAG,GAAH,GAAG,CAAS;QACZ,gBAAW,GAAX,WAAW,CAAwB;QAEpD,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC;YAC/B,IAAI,EAAE,uBAAuB;YAC7B,WAAW,EAAE,2EAA2E,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;kBACnI,eAAe,kBAAkB,oLAAoL;kBACrN,mGAAmG;YACvG,UAAU,EAAE,EAAE;YACd,MAAM,EAAE;gBACN,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,oBAAoB,EAAE,KAAK;oBAC3B,UAAU,EAAE;wBACV,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;wBAC9C,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;qBACpE;iBACF;gBACD,MAAM,EAAE,UAAU;aACnB;YACD,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAA0C,EAAE;gBAC/D,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,gCAAgC,CAAC,CAAA;gBAC7E,CAAC;gBACD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;YACnD,CAAC;YACD,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,uBAAuB,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;SAC1F,CAAC,CAAA;IACJ,CAAC;IAED,uEAAuE;IACvE,OAAO;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAA;QACpG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,MAAM,SAAS,GAAG;YAChB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC,CAAC;YACnE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,gBAAgB,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC,CAAC;YACpE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;gBAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;oBAAE,IAAI,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAAA;YAC5E,CAAC,CAAC;YACF,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;gBAC3C,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK;uBACvB,IAAI,CAAC,IAAI,KAAK,OAAO;uBACrB,IAAI,CAAC,KAAK,KAAK,SAAS;uBACxB,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC;uBACtC,oBAAoB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;oBACxC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBAC3B,CAAC;gBACD,OAAO,SAAS,CAAA;YAClB,CAAC,CAAC;SACH,CAAA;QACD,IAAI,CAAC;YACH,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;gBAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAChE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE;gBAAE,OAAO,EAAE,CAAA;YACpD,IAAI,CAAC,aAAa,EAAE,CAAA;YACpB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAA;YACtB,MAAM,KAAK,CAAA;QACb,CAAC;QACD,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,CAAC,SAAS;gBAAE,OAAM;YAC3B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAA;YACtB,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE;gBAAE,OAAO,EAAE,CAAA;YACpD,IAAI,CAAC,aAAa,EAAE,CAAA;QACtB,CAAC,CAAA;IACH,CAAC;IAEO,MAAM,CAAC,KAAY;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAM;QAClC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAA;QAC3E,IAAI,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC/D,CAAC;IAEO,QAAQ,CAAC,KAAY;QAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACpC,wEAAwE;QACxE,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,wBAAwB,CAAC,CAAA;QAC/G,IAAI,KAAK,CAAC,MAAM;YAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,CAAA;QAE1E,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QACtC,MAAM,aAAa,GAAsB,EAAE,CAAA;QAC3C,IAAI,CAAC;YACH,KAAK,MAAM,UAAU,IAAI,WAAW;gBAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAA;YAC9F,uEAAuE;YACvE,wEAAwE;YACxE,iEAAiE;YACjE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAA;QACzE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,KAAK,MAAM,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE;gBAAE,OAAO,EAAE,CAAA;YACxD,MAAM,KAAK,CAAA;QACb,CAAC;QAED,KAAK,CAAC,MAAM,GAAG,IAAI,CAAA;QACnB,KAAK,CAAC,aAAa,GAAG,aAAa,CAAA;QACnC,KAAK,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QAChE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,CAAA;IACzD,CAAC;IAED,6EAA6E;IACrE,aAAa,CAAC,OAAgB;QACpC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,OAAO,CAAA;IACtD,CAAC;IAEO,6BAA6B,CAAC,OAAgB;QACpD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC;gBACzE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAA;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IAEO,mBAAmB,CAAC,KAAY;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACpC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS;YAAE,OAAM;QACtE,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,uBAAuB,CAAC,EAAE,CAAC,CAAA;IACvF,CAAC;IAEO,MAAM,CAAC,KAAY;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACpC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAM;QAC/B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACzB,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;IAC1B,CAAC;IAEO,aAAa;QACnB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;QAClE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAEO,YAAY,CAAC,KAAoB;QACvC,KAAK,CAAC,eAAe,EAAE,EAAE,CAAA;QACzB,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE;YAAE,OAAO,EAAE,CAAA;IAChE,CAAC;CACF"}