@useactor/core 0.1.0

package/dist/skills.js

@@ -0,0 +1,333 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { resolveActorHome } from "@useactor/storage";
+const skillFileName = "SKILL.md";
+const builtInSkills = [
+    {
+        name: "Skill Creator",
+        invocationName: "skill-creator",
+        description: "Create or update Actor skills. Use when the user asks to create a new skill, improve an existing skill, or make a workflow reusable.",
+        path: "builtin:skill-creator",
+        scope: "user",
+        origin: "builtin",
+        instructions: "When the user asks to create a skill and scope is unclear, ask whether it should be project-specific or global. Use the skill tool. Project-specific skills save to the current project's .actor/skills directory. Global skills save to ACTOR_HOME/skills. Do not write skills into Codex directories. If a skill already exists, ask before overwriting and set overwrite only after explicit confirmation. Skills must include concise frontmatter name and description plus actionable Markdown instructions.",
+    },
+];
+export async function listSkills(options = {}) {
+    const homedirPath = resolveSkillHomedir(options);
+    const roots = [
+        ...(options.projectRoot
+            ? [
+                {
+                    root: path.join(options.projectRoot, ".actor", "skills"),
+                    scope: "project",
+                    origin: "project",
+                },
+            ]
+            : []),
+        {
+            root: path.join(resolveActorHome(options), "skills"),
+            scope: "user",
+            origin: "actor",
+        },
+        {
+            root: path.join(homedirPath, ".codex", "skills"),
+            scope: "user",
+            origin: "codex",
+        },
+        {
+            root: path.join(homedirPath, ".agents", "skills"),
+            scope: "user",
+            origin: "agents",
+        },
+    ];
+    const skills = [];
+    const errors = [];
+    const seenNames = new Set();
+    for (const root of roots) {
+        const loaded = await loadSkillsFromRoot(root.root, root.scope, root.origin);
+        for (const skill of loaded.skills) {
+            const key = skillIdentityKey(skill);
+            if (seenNames.has(key))
+                continue;
+            seenNames.add(key);
+            skills.push(skill);
+        }
+        errors.push(...loaded.errors);
+    }
+    for (const skill of builtInSkills) {
+        const key = skillIdentityKey(skill);
+        if (seenNames.has(key))
+            continue;
+        seenNames.add(key);
+        skills.push(skill);
+    }
+    skills.sort((first, second) => {
+        const origin = originRank(first.origin) - originRank(second.origin);
+        if (origin !== 0)
+            return origin;
+        return first.name.localeCompare(second.name);
+    });
+    return { skills, errors };
+}
+export function buildSkillsPromptSection(skills) {
+    if (skills.length === 0)
+        return undefined;
+    return [
+        "Actor skills:",
+        "A skill is a local instruction pack. File-backed skills live in `SKILL.md`; built-in skills include their instructions inline. If the user names a skill with `$skill-name` or the task clearly matches a skill description, follow that skill for the turn.",
+        "Available skills:",
+        ...skills.flatMap(formatSkillPromptLines),
+    ].join("\n");
+}
+export async function createActorSkill(input, options = {}) {
+    const name = normalizeSkillSlug(input.name);
+    const description = input.description.trim();
+    const body = input.body.trim();
+    if (!description)
+        throw new Error("Skill description is required.");
+    if (!body)
+        throw new Error("Skill body is required.");
+    const root = input.scope === "global"
+        ? path.join(resolveActorHome(options), "skills")
+        : options.projectRoot
+            ? path.join(options.projectRoot, ".actor", "skills")
+            : undefined;
+    if (!root) {
+        throw new Error("Project skill creation requires a project root.");
+    }
+    const skillPath = path.join(root, name, skillFileName);
+    const existing = await readExistingSkill(skillPath);
+    if (existing !== undefined && !input.overwrite) {
+        throw new Error(`Skill already exists: ${name}. Ask the user before overwriting it.`);
+    }
+    await mkdir(path.dirname(skillPath), { recursive: true });
+    await writeFile(skillPath, [
+        "---",
+        `name: ${JSON.stringify(name)}`,
+        `description: ${JSON.stringify(description)}`,
+        "---",
+        "",
+        body,
+        "",
+    ].join("\n"), "utf8");
+    return {
+        path: skillPath,
+        name,
+        scope: input.scope,
+        overwritten: existing !== undefined,
+    };
+}
+export function createSkillTool(options = {}) {
+    return {
+        id: "skill",
+        name: "Create Actor skill",
+        description: "Create or update an Actor skill. Ask whether the skill is project-specific or global if the user did not say. Project skills are saved in the project .actor/skills directory; global skills are saved in ACTOR_HOME/skills.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name", "description", "body", "scope"],
+            properties: {
+                name: { type: "string" },
+                description: { type: "string" },
+                body: { type: "string" },
+                scope: { type: "string", enum: ["project", "global"] },
+                overwrite: { type: "boolean" },
+            },
+        },
+        permissionPolicy: "on-request",
+        async executor(input, context) {
+            const result = await createActorSkill(parseCreateSkillInput(input), {
+                ...options,
+                ...(context.project?.rootPath
+                    ? { projectRoot: context.project.rootPath }
+                    : {}),
+            });
+            return {
+                content: JSON.stringify(result),
+                metadata: {
+                    artifactKind: "actor_skill",
+                    artifactPath: result.path,
+                    scope: result.scope,
+                    overwritten: result.overwritten,
+                },
+            };
+        },
+    };
+}
+async function loadSkillsFromRoot(root, scope, origin) {
+    let entries = [];
+    try {
+        entries = await readdir(root);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return { skills: [], errors: [] };
+        }
+        return {
+            skills: [],
+            errors: [{ path: root, message: safeErrorMessage(error) }],
+        };
+    }
+    const skills = [];
+    const errors = [];
+    for (const entry of entries) {
+        if (shouldSkipSkillDirectory(entry, origin))
+            continue;
+        const skillPath = path.join(root, entry, skillFileName);
+        try {
+            const parsed = parseSkillMarkdown(await readFile(skillPath, "utf8"));
+            skills.push({
+                name: parsed.name,
+                description: parsed.description,
+                path: skillPath,
+                scope,
+                origin,
+            });
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                continue;
+            errors.push({ path: skillPath, message: safeErrorMessage(error) });
+        }
+    }
+    return { skills, errors };
+}
+function parseSkillMarkdown(markdown) {
+    if (!markdown.startsWith("---\n")) {
+        throw new Error("missing YAML frontmatter");
+    }
+    const end = markdown.indexOf("\n---", 4);
+    if (end === -1) {
+        throw new Error("unterminated YAML frontmatter");
+    }
+    const frontmatter = parseSimpleFrontmatter(markdown.slice(4, end));
+    const name = frontmatter.name?.trim();
+    const description = frontmatter.description?.trim();
+    if (!name)
+        throw new Error("missing frontmatter field: name");
+    if (!description)
+        throw new Error("missing frontmatter field: description");
+    return { name, description };
+}
+function parseSimpleFrontmatter(value) {
+    const parsed = {};
+    for (const line of value.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const colon = trimmed.indexOf(":");
+        if (colon === -1)
+            continue;
+        const key = trimmed.slice(0, colon).trim();
+        const rawValue = trimmed.slice(colon + 1).trim();
+        if (key === "name" || key === "description") {
+            parsed[key] = unquoteYamlScalar(rawValue);
+        }
+    }
+    return parsed;
+}
+function unquoteYamlScalar(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function originRank(origin) {
+    switch (origin) {
+        case "project":
+            return 0;
+        case "actor":
+            return 1;
+        case "builtin":
+            return 2;
+        case "codex":
+            return 3;
+        case "agents":
+            return 4;
+    }
+}
+function shouldSkipSkillDirectory(entry, origin) {
+    return origin === "codex" && entry.startsWith(".");
+}
+function normalizeSkillName(name) {
+    return name.trim().toLowerCase();
+}
+function skillIdentityKey(skill) {
+    return normalizeSkillName(skill.invocationName ?? skill.name);
+}
+function formatSkillPromptLines(skill) {
+    const invocation = skill.invocationName ?? skill.name;
+    const header = skill.origin === "builtin"
+        ? `- ${skill.name} ($${invocation}): ${skill.description} (built-in)`
+        : `- ${skill.name}: ${skill.description} (file: ${skill.path})`;
+    return skill.instructions
+        ? [header, `  Instructions: ${skill.instructions}`]
+        : [header];
+}
+function normalizeSkillSlug(name) {
+    const normalized = name.trim();
+    if (!/^[a-z0-9][a-z0-9_-]*$/u.test(normalized)) {
+        throw new Error("Skill name must be a lowercase path-safe slug using letters, numbers, dashes, or underscores.");
+    }
+    return normalized;
+}
+function parseCreateSkillInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Skill tool input must be an object.");
+    }
+    const record = input;
+    const name = requiredString(record, "name");
+    const description = requiredString(record, "description");
+    const body = requiredString(record, "body");
+    const rawScope = requiredString(record, "scope");
+    if (rawScope !== "global" && rawScope !== "project") {
+        throw new Error("Skill scope must be either project or global.");
+    }
+    const overwrite = typeof record.overwrite === "boolean" ? record.overwrite : undefined;
+    return {
+        name,
+        description,
+        body,
+        scope: rawScope,
+        ...(overwrite !== undefined ? { overwrite } : {}),
+    };
+}
+function requiredString(record, key) {
+    const value = record[key];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Skill ${key} is required.`);
+    }
+    return value;
+}
+async function readExistingSkill(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return undefined;
+        throw error;
+    }
+}
+function resolveSkillHomedir(options) {
+    if (options?.homedirPath) {
+        return options.homedirPath;
+    }
+    if (options?.homedirResolver) {
+        return options.homedirResolver();
+    }
+    return os.homedir();
+}
+function safeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isNotFoundError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

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

package/dist/test/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/test/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":""}

package/dist/test/setup.js

@@ -0,0 +1,17 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll } from "vitest";
+let tempHomeRoot;
+beforeAll(async () => {
+    tempHomeRoot = await mkdtemp(path.join(tmpdir(), "actor-core-test-home-"));
+    process.env.ACTOR_HOME = tempHomeRoot;
+    delete process.env.OPENAI_API_KEY;
+    delete process.env.ANTHROPIC_API_KEY;
+});
+afterAll(async () => {
+    if (tempHomeRoot) {
+        await rm(tempHomeRoot, { recursive: true, force: true });
+    }
+});
+//# sourceMappingURL=setup.js.map

package/dist/test/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE7C,IAAI,YAAgC,CAAC;AAErC,SAAS,CAAC,KAAK,IAAI,EAAE;IACnB,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC,CAAC,CAAC;IAC3E,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC;IACtC,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAClC,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;AACvC,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,KAAK,IAAI,EAAE;IAClB,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,EAAE,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/tool-requests.d.ts

@@ -0,0 +1,58 @@
+import { type PermissionGrantRequest, type PermissionGrantStore } from "./permission-grants.js";
+import { type ApprovalDecisionType, type ApprovalResultEvent, type EventContext, type ToolRequestEvent } from "./events.js";
+import type { ActorId } from "./runtime.js";
+export type { ApprovalDecisionType } from "./events.js";
+export interface ToolRequestDescriptor {
+    readonly toolId: ActorId;
+    readonly action: string;
+    readonly target?: string;
+    readonly reason: string;
+    readonly preview?: string;
+}
+export interface PendingToolRequest {
+    readonly runId: ActorId;
+    readonly requestId: ActorId;
+    readonly sessionId: ActorId;
+    readonly descriptor: ToolRequestDescriptor;
+    readonly permissionRequest?: PermissionGrantRequest;
+    readonly context: EventContext;
+}
+export interface ApprovalDecisionInput {
+    readonly runId: ActorId;
+    readonly requestId: ActorId;
+    readonly decision: ApprovalDecisionType;
+    readonly instruction?: string;
+}
+export interface UnknownToolRequestResult {
+    readonly status: "unknown_request";
+}
+export interface ApprovedToolRequestResult {
+    readonly status: "approved";
+    readonly event: ApprovalResultEvent;
+    readonly toolResult?: unknown;
+}
+export interface DeniedToolRequestResult {
+    readonly status: "denied";
+    readonly event: ApprovalResultEvent;
+}
+export interface RedirectedToolRequestResult {
+    readonly status: "redirected";
+    readonly event: ApprovalResultEvent;
+    readonly instruction: string;
+}
+export type ApprovalDecisionResult = UnknownToolRequestResult | ApprovedToolRequestResult | DeniedToolRequestResult | RedirectedToolRequestResult;
+export declare class ToolRequestLifecycle {
+    private readonly options;
+    private readonly pendingByRun;
+    constructor(options?: {
+        readonly grantStore?: PermissionGrantStore;
+    });
+    createPendingRequest(input: PendingToolRequest): ToolRequestEvent;
+    requestToolExecution(input: PendingToolRequest, execute: (request: PendingToolRequest) => Promise<unknown>): {
+        readonly event: ToolRequestEvent;
+        readonly result: Promise<ApprovalDecisionResult>;
+    };
+    executeWithMatchingGrant(request: PendingToolRequest, execute: (request: PendingToolRequest) => Promise<unknown>): Promise<ApprovedToolRequestResult | undefined>;
+    submitApprovalDecision(input: ApprovalDecisionInput, execute?: (request: PendingToolRequest) => Promise<void>): Promise<ApprovalDecisionResult>;
+}
+//# sourceMappingURL=tool-requests.d.ts.map

package/dist/tool-requests.d.ts.map

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

package/dist/tool-requests.js

@@ -0,0 +1,122 @@
+import { createPermissionGrant, findMatchingPermissionGrant, shouldPersistPermissionGrant } from "./permission-grants.js";
+import { createApprovalResultEvent, createToolRequestEvent } from "./events.js";
+export class ToolRequestLifecycle {
+    options;
+    pendingByRun = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    createPendingRequest(input) {
+        const runRequests = this.pendingByRun.get(input.runId) ?? new Map();
+        runRequests.set(input.requestId, input);
+        this.pendingByRun.set(input.runId, runRequests);
+        return createToolRequestEvent(input.context, input.requestId, input.descriptor);
+    }
+    requestToolExecution(input, execute) {
+        let resolveResult;
+        let rejectResult;
+        const result = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        const runRequests = this.pendingByRun.get(input.runId) ?? new Map();
+        runRequests.set(input.requestId, {
+            ...input,
+            execute,
+            resolve: resolveResult,
+            reject: rejectResult
+        });
+        this.pendingByRun.set(input.runId, runRequests);
+        return {
+            event: createToolRequestEvent(input.context, input.requestId, input.descriptor),
+            result
+        };
+    }
+    async executeWithMatchingGrant(request, execute) {
+        if (!request.permissionRequest || !this.options.grantStore) {
+            return undefined;
+        }
+        const grants = await this.options.grantStore.listPermissionGrants();
+        const grant = findMatchingPermissionGrant(grants, request.permissionRequest);
+        if (!grant) {
+            return undefined;
+        }
+        const toolResult = await execute(request);
+        return {
+            status: "approved",
+            event: createApprovalResultEvent(request.context, request.requestId, true, grant.type),
+            ...(toolResult !== undefined ? { toolResult } : {})
+        };
+    }
+    async submitApprovalDecision(input, execute = async () => { }) {
+        const runRequests = this.pendingByRun.get(input.runId);
+        const request = runRequests?.get(input.requestId);
+        if (!request) {
+            return { status: "unknown_request" };
+        }
+        if (input.decision === "redirect") {
+            runRequests?.delete(input.requestId);
+            if (runRequests?.size === 0) {
+                this.pendingByRun.delete(input.runId);
+            }
+            const result = {
+                status: "redirected",
+                event: createApprovalResultEvent(request.context, input.requestId, false, "redirect"),
+                instruction: input.instruction ?? request.descriptor.reason
+            };
+            resolvePendingExecution(request, result);
+            return result;
+        }
+        if (input.decision === "deny") {
+            runRequests?.delete(input.requestId);
+            if (runRequests?.size === 0) {
+                this.pendingByRun.delete(input.runId);
+            }
+            const result = {
+                status: "denied",
+                event: createApprovalResultEvent(request.context, input.requestId, false, "deny")
+            };
+            resolvePendingExecution(request, result);
+            return result;
+        }
+        let toolResult;
+        try {
+            toolResult = await (isPendingToolExecution(request) ? request.execute(request) : execute(request));
+            if (input.decision === "allow_always" &&
+                request.permissionRequest &&
+                this.options.grantStore &&
+                shouldPersistPermissionGrant(input.decision)) {
+                await this.options.grantStore.savePermissionGrant(createPermissionGrant({
+                    ...request.permissionRequest,
+                    type: "allow_always"
+                }));
+            }
+        }
+        catch (error) {
+            if (isPendingToolExecution(request)) {
+                request.reject(error);
+            }
+            throw error;
+        }
+        runRequests?.delete(input.requestId);
+        if (runRequests?.size === 0) {
+            this.pendingByRun.delete(input.runId);
+        }
+        const result = {
+            status: "approved",
+            event: createApprovalResultEvent(request.context, input.requestId, true, input.decision),
+            ...(toolResult !== undefined ? { toolResult } : {})
+        };
+        resolvePendingExecution(request, result);
+        return result;
+    }
+}
+function isPendingToolExecution(request) {
+    return "execute" in request;
+}
+function resolvePendingExecution(request, result) {
+    if (isPendingToolExecution(request)) {
+        request.resolve(result);
+    }
+}
+//# sourceMappingURL=tool-requests.js.map

package/dist/tool-requests.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,45 @@
+import type { ProjectRef, ActorId } from "./runtime.js";
+export type ToolPermissionPolicy = "never" | "on-request" | "always";
+export interface ToolExecutionContext {
+    readonly sessionId: ActorId;
+    readonly runId: ActorId;
+    readonly project?: ProjectRef;
+}
+export interface ToolExecutionResult {
+    readonly content: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export type ToolExecutor = (input: unknown, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
+export interface ToolDefinition {
+    readonly id: ActorId;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: unknown;
+    readonly permissionPolicy: ToolPermissionPolicy;
+    readonly projectFilter?: {
+        readonly projectIds?: readonly ActorId[];
+    };
+    readonly executor: ToolExecutor;
+}
+export interface ToolDescriptor {
+    readonly id: ActorId;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: unknown;
+    readonly permissionPolicy: ToolPermissionPolicy;
+}
+export interface ListToolsOptions {
+    readonly project?: ProjectRef;
+}
+export interface ToolRegistry {
+    registerTool(tool: ToolDefinition): void;
+    listTools(options?: ListToolsOptions): readonly ToolDefinition[];
+    listToolDescriptors(options?: ListToolsOptions): readonly ToolDescriptor[];
+    getTool(toolId: ActorId): ToolDefinition | undefined;
+}
+export declare class DuplicateToolIdError extends Error {
+    constructor(toolId: ActorId);
+}
+export declare function createToolRegistry(initialTools?: readonly ToolDefinition[]): ToolRegistry;
+export declare function toToolDescriptor(tool: ToolDefinition): ToolDescriptor;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;KAC1C,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;CACjD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,cAAc,EAAE,CAAC;IACjE,mBAAmB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,cAAc,EAAE,CAAC;IAC3E,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAAC;CACtD;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,MAAM,EAAE,OAAO;CAI5B;AAED,wBAAgB,kBAAkB,CAAC,YAAY,GAAE,SAAS,cAAc,EAAO,GAAG,YAAY,CA8B7F;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAQrE"}