@vinhnt-sdk/tools 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Thanh Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/arity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract the "human-understandable command prefix" from shell tokens.
+ *
+ * Examples:
+ *   prefix(["npm", "install", "express", "--save"]) → ["npm", "install"]
+ *   prefix(["git", "checkout", "main"])             → ["git", "checkout"]
+ *   prefix(["docker", "compose", "up", "-d"])       → ["docker", "compose", "up"]
+ *   prefix(["cat", "file.txt"])                     → ["cat"]
+ *   prefix([])                                      → []
+ */
+export declare function prefix(tokens: string[]): string[];
+/**
+ * Convert a shell command string into a permission save pattern.
+ * The pattern with trailing " *" allows exact-match or prefix-match in saved rules.
+ *
+ * Examples:
+ *   commandPattern("npm install express --save") → "npm install *"
+ *   commandPattern("git checkout main")         → "git checkout *"
+ *   commandPattern("cat file.txt")              → "cat *"
+ */
+export declare function commandPattern(command: string): string;
+//# sourceMappingURL=arity.d.ts.map

package/dist/arity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arity.d.ts","sourceRoot":"","sources":["../src/arity.ts"],"names":[],"mappings":"AAuEA;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAItD"}

package/dist/arity.js

@@ -0,0 +1,96 @@
+/**
+ * ARITY dictionary: maps command prefixes to their "human-understandable" token count.
+ *
+ * When a user runs a command like "npm install express --save", the arity tells us
+ * that the meaningful prefix is ["npm", "install"] (arity 2). This enables:
+ * - Cleaner permission prompts ("Allow npm install?")
+ * - Smarter "always allow" patterns ("npm install *" matches any npm install variant)
+ */
+const ARITY = {
+    // Single-arity commands
+    cat: 1, cd: 1, chmod: 1, chown: 1, cp: 1, echo: 1, env: 1,
+    export: 1, git: 2, "git config": 3, "git remote": 3, "git stash": 3, grep: 1, kill: 1, killall: 1, ln: 1, ls: 1,
+    mkdir: 1, mv: 1, ps: 1, pwd: 1, rm: 1, rmdir: 1, sleep: 1,
+    source: 1, tail: 1, touch: 1, unset: 1, which: 1,
+    // Cloud / infrastructure
+    aws: 3, az: 3, gcloud: 3, gh: 3, doctl: 3, eksctl: 2,
+    "eksctl create": 3, cdk: 2, cf: 2, heroku: 2, vercel: 2,
+    pulumi: 2, "pulumi stack": 3, terraform: 2,
+    "terraform workspace": 3, vault: 2, "vault auth": 3,
+    "vault kv": 3, consul: 2, "consul kv": 3, nomad: 2,
+    serverless: 2, sls: 2, sst: 2, flyctl: 2, sfdx: 3,
+    // Containers / orchestration
+    docker: 2, "docker builder": 3, "docker compose": 3,
+    "docker container": 3, "docker image": 3, "docker network": 3,
+    "docker volume": 3, podman: 2, "podman container": 3,
+    "podman image": 3, kubectl: 2, "kubectl kustomize": 3,
+    "kubectl rollout": 3, kustomize: 2, helm: 2,
+    minikube: 2, kind: 2, "kind create": 3, crictl: 2,
+    skaffold: 2, compose: 2,
+    // Languages / runtimes
+    node: 2, python: 2, python3: 2, ruby: 2, rake: 2,
+    go: 2, cargo: 2, "cargo add": 3, "cargo run": 3,
+    rustup: 2, dotnet: 2, mvn: 2, gradle: 2, swift: 2,
+    deno: 2, "deno task": 3, bun: 2, "bun run": 3, "bun x": 3,
+    // JavaScript / Node ecosystem
+    npm: 2, "npm exec": 3, "npm init": 3, "npm run": 3,
+    "npm view": 3, npx: 2, yarn: 2, "yarn dlx": 3, "yarn run": 3,
+    pnpm: 2, "pnpm dlx": 3, "pnpm exec": 3, "pnpm run": 3,
+    nvm: 2, volta: 2, ng: 2, nx: 2, turbo: 2,
+    // Python
+    pip: 2, pip3: 2, pipenv: 2, poetry: 2, pyenv: 2,
+    // PHP
+    composer: 2, wp: 2,
+    // Databases
+    psql: 2, mysql: 2, mongosh: 2, "redis-cli": 2,
+    sqlite3: 2, pg_dump: 2, pg_restore: 2,
+    // Build tools
+    make: 2, cmake: 2, bazel: 2, meson: 2,
+    // System / network
+    systemctl: 2, journalctl: 2, ufw: 2, ip: 2, "ip addr": 3,
+    "ip link": 3, "ip netns": 3, "ip route": 3, tmux: 2,
+    screen: 2, openssl: 2, "openssl req": 3, "openssl x509": 3,
+    // Firestore / GCP
+    firebase: 2, gsutil: 2, bq: 2,
+    // Misc
+    brew: 2, "brew bundle": 3, "brew services": 3, mc: 2,
+    "mc admin": 3, vagrant: 2, packer: 2, sdkmanager: 2,
+    adb: 2, fastlane: 2, cocoapods: 2,
+};
+/**
+ * Extract the "human-understandable command prefix" from shell tokens.
+ *
+ * Examples:
+ *   prefix(["npm", "install", "express", "--save"]) → ["npm", "install"]
+ *   prefix(["git", "checkout", "main"])             → ["git", "checkout"]
+ *   prefix(["docker", "compose", "up", "-d"])       → ["docker", "compose", "up"]
+ *   prefix(["cat", "file.txt"])                     → ["cat"]
+ *   prefix([])                                      → []
+ */
+export function prefix(tokens) {
+    for (let len = tokens.length; len > 0; len--) {
+        const key = tokens.slice(0, len).join(" ");
+        const arity = ARITY[key];
+        if (arity !== undefined)
+            return tokens.slice(0, arity);
+    }
+    if (tokens.length === 0)
+        return [];
+    return tokens.slice(0, 1);
+}
+/**
+ * Convert a shell command string into a permission save pattern.
+ * The pattern with trailing " *" allows exact-match or prefix-match in saved rules.
+ *
+ * Examples:
+ *   commandPattern("npm install express --save") → "npm install *"
+ *   commandPattern("git checkout main")         → "git checkout *"
+ *   commandPattern("cat file.txt")              → "cat *"
+ */
+export function commandPattern(command) {
+    const tokens = command.trim().split(/\s+/);
+    if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === ""))
+        return "*";
+    return prefix(tokens).join(" ") + " *";
+}
+//# sourceMappingURL=arity.js.map

package/dist/arity.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,43 @@
+/** Reply from human-in-the-loop approval */
+export type PermissionReply = "once" | "always" | "reject";
+import type { RequestContext } from "@vinhnt-sdk/schema";
+/** Context passed to every tool execution — replaces bare AbortSignal */
+export interface ToolContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly agentId: string;
+    readonly agentName: string;
+    readonly signal: AbortSignal;
+    /**
+     * The parent run's request context (traceId/actorId/tenantId/requestId).
+     * Lets handoff tools (delegate/spawn) propagate identity + parent-run
+     * linkage to child agents instead of inventing a synthetic context.
+     */
+    readonly parentContext?: RequestContext;
+    /** Environment variables for subprocess execution (shell tool) */
+    readonly env: Record<string, string>;
+    /**
+     * Request human approval for a permission-bound operation.
+     * Returns the user's decision: "once" (allow once), "always" (approve forever), or "reject".
+     * When reply is "always", savePatterns are persisted as allow rules for future requests.
+     */
+    ask(input: {
+        permission: string;
+        resource: string;
+        reason: string;
+        /** Patterns to save as "always allow" rules if user replies "always". Uses arity-based truncation. */
+        savePatterns?: readonly string[];
+    }): Promise<PermissionReply>;
+    /** Attach metadata to the current tool call (for observability) */
+    metadata(input: {
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Register a compensation action for saga rollback.
+     * If the current run fails or is cancelled, this action will be called
+     * to undo the tool's side effect (e.g., restore original file content).
+     */
+    setCompensation(action: () => Promise<void>): void;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IAExC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,sGAAsG;QACtG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,IAAI,CAAC;IAET;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACpD"}

package/dist/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/define-tool.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolRisk } from "./definitions.js";
+import type { NestedJsonSchema } from "./json-schema.js";
+/**
+ * ── Schema-first tool authoring (OpenCode-style `Tool.make`) ──────────────
+ * The tool OWNS its validation schema (`input`) instead of importing a
+ * standalone static schema. `toDefinition()` derives the provider-facing
+ * `ToolDefinition` (JSON Schema) from that schema, so there is exactly one
+ * source of truth per tool. Domain namespacing is applied via `name`.
+ */
+export interface ToolConfig<TInput = unknown, TOutput = unknown> {
+    /** Tool name / id. Use dot-prefixed names for domains: "coding.read_file". */
+    name: string;
+    description: string;
+    risk: ToolRisk;
+    /** Runtime validation schema — owned by this tool, not a shared file. */
+    input: z.ZodType<TInput>;
+    /** Optional output validation schema. */
+    output?: z.ZodType<TOutput>;
+    /** Per-tool timeout in ms (overrides global default). */
+    timeoutMs?: number;
+    /** Permission action key for the gate (e.g. "edit", "shell"). Optional; defaults to risk. */
+    permissionAction?: string;
+    /** Optional LLM-facing JSON Schema override (e.g. to advertise `path` aliases). */
+    jsonSchema?: NestedJsonSchema;
+    /** Coerce raw model-agnostic input before validation (e.g. snake_case aliases). */
+    normalize?(raw: unknown): unknown;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+export interface Tool<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly risk: ToolRisk;
+    readonly timeoutMs?: number;
+    readonly permissionAction?: string;
+    readonly input: z.ZodType<TInput>;
+    /** Derive the provider-facing ToolDefinition (registers as `name`). */
+    toDefinition(): ToolDefinition<TInput, TOutput>;
+}
+/** Map a Zod schema to the codebase's `NestedJsonSchema` shape (best effort). */
+export declare function zodSchemaToNestedJsonSchema(schema: z.ZodTypeAny): NestedJsonSchema | undefined;
+export declare function defineTool<TInput = unknown, TOutput = unknown>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+/** Convenience: build a ToolDefinition directly from a ToolConfig. */
+export declare function toolToDefinition<TInput = unknown, TOutput = unknown>(config: ToolConfig<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+//# sourceMappingURL=define-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../src/define-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC7D,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,mFAAmF;IACnF,SAAS,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IAClC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,uEAAuE;IACvE,YAAY,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAID,iFAAiF;AACjF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,gBAAgB,GAAG,SAAS,CAI9F;AAgFD,wBAAgB,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC5D,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BvB;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAClE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}

package/dist/define-tool.js

@@ -0,0 +1,120 @@
+import { validateInput } from "./validate.js";
+/** Map a Zod schema to the codebase's `NestedJsonSchema` shape (best effort). */
+export function zodSchemaToNestedJsonSchema(schema) {
+    if (!schema)
+        return undefined;
+    const out = convert(schema);
+    return out ? Object.assign({}, out) : undefined;
+}
+function convert(schema) {
+    if (!schema)
+        return undefined;
+    // Unwrap effects (refine/transform) and optional/default wrappers.
+    while (schema._def.type === "effects" || schema._def.type === "optional" || schema._def.type === "default") {
+        if (schema._def.type === "effects")
+            schema = schema._def.schema;
+        else
+            schema = schema._def.innerType;
+    }
+    const base = {};
+    const desc = schema.description ?? schema._def.description;
+    if (desc)
+        base.description = desc;
+    switch (schema._def.type) {
+        case "string":
+            base.type = "string";
+            return base;
+        case "number":
+            base.type = "number";
+            return base;
+        case "boolean":
+            base.type = "boolean";
+            return base;
+        case "enum": {
+            const entries = schema._def.entries ?? {};
+            base.type = "string";
+            base.enum = Object.keys(entries);
+            return base;
+        }
+        case "literal":
+            base.type = typeof schema._def.value === "string" ? "string" : "number";
+            return base;
+        case "array": {
+            base.type = "array";
+            base.items = convert(schema._def.innerType) ?? { type: "string" };
+            return base;
+        }
+        case "record":
+            base.type = "object";
+            return base;
+        case "object": {
+            base.type = "object";
+            const raw = schema._def.shape;
+            const shape = typeof raw === "function" ? raw() : (raw ?? {});
+            const properties = {};
+            const required = [];
+            for (const [key, child] of Object.entries(shape)) {
+                properties[key] = convert(child) ?? { type: "string" };
+                if (!child.isOptional?.() && child._def?.type !== "optional" && child._def?.type !== "default") {
+                    required.push(key);
+                }
+            }
+            base.properties = properties;
+            if (required.length)
+                base.required = required;
+            return base;
+        }
+        case "union": {
+            const options = schema._def.options ?? [];
+            if (options.every((o) => o._def?.type === "string")) {
+                base.type = "string";
+                return base;
+            }
+            if (options.every((o) => o._def?.type === "number")) {
+                base.type = "number";
+                return base;
+            }
+            base.type = "string";
+            return base;
+        }
+        default:
+            base.type = "string";
+            return base;
+    }
+}
+export function defineTool(config) {
+    return {
+        name: config.name,
+        description: config.description,
+        risk: config.risk,
+        timeoutMs: config.timeoutMs,
+        permissionAction: config.permissionAction,
+        input: config.input,
+        toDefinition() {
+            return {
+                id: config.name,
+                description: config.description,
+                risk: config.risk,
+                inputSchema: config.jsonSchema ?? zodSchemaToNestedJsonSchema(config.input),
+                timeoutMs: config.timeoutMs,
+                permissionAction: config.permissionAction,
+                inputZodSchema: config.input,
+                outputZodSchema: config.output,
+                async execute(raw, ctx) {
+                    const normalized = config.normalize ? config.normalize(raw) : raw;
+                    const input = validateInput(config.name, config.input, normalized);
+                    const result = await config.execute(input, ctx);
+                    if (config.output) {
+                        return validateInput(config.name, config.output, result);
+                    }
+                    return result;
+                },
+            };
+        },
+    };
+}
+/** Convenience: build a ToolDefinition directly from a ToolConfig. */
+export function toolToDefinition(config) {
+    return defineTool(config).toDefinition();
+}
+//# sourceMappingURL=define-tool.js.map

package/dist/define-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.js","sourceRoot":"","sources":["../src/define-tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA2C9C,iFAAiF;AACjF,MAAM,UAAU,2BAA2B,CAAC,MAAoB;IAC9D,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,MAAiB,CAAC,CAAC;IACvC,OAAO,GAAG,CAAC,CAAC,CAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,CAAsB,CAAC,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC;AAKD,SAAS,OAAO,CAAC,MAAe;IAC9B,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,mEAAmE;IACnE,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3G,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAiB,CAAC;;YACtE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAoB,CAAC;IACjD,CAAC;IAED,MAAM,IAAI,GAAkB,EAAmB,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;IAC3D,IAAI,IAAI;QAAE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAElC,QAAQ,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,KAAK,QAAQ;YACX,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,KAAK,SAAS;YACZ,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,SAAS;YACZ,IAAI,CAAC,IAAI,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;YACxE,OAAO,IAAI,CAAC;QACd,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;YACpB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,SAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC7E,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,QAAQ;YACX,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;YAC9B,MAAM,KAAK,GAAwB,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;YACnF,MAAM,UAAU,GAAqC,EAAE,CAAC;YACxD,MAAM,QAAQ,GAAa,EAAE,CAAC;YAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,UAAU,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,KAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;gBAClE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;oBAC/F,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;YAC7B,IAAI,QAAQ,CAAC,MAAM;gBAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAC9C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YAC1C,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAC7D,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;gBACrB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAC7D,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;gBACrB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QACD;YACE,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,MAAmC;IAEnC,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,YAAY;YACV,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,IAAI;gBACf,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,WAAW,EAAE,MAAM,CAAC,UAAU,IAAI,2BAA2B,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC3E,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,cAAc,EAAE,MAAM,CAAC,KAAK;gBAC5B,eAAe,EAAE,MAAM,CAAC,MAAM;gBAC9B,KAAK,CAAC,OAAO,CAAC,GAAY,EAAE,GAAgB;oBAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;oBAClE,MAAM,KAAK,GAAG,aAAa,CAAS,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;oBAC3E,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;oBAChD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;wBAClB,OAAO,aAAa,CAAU,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;oBACpE,CAAC;oBACD,OAAO,MAAM,CAAC;gBAChB,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAC9B,MAAmC;IAEnC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,CAAC;AAC3C,CAAC"}

package/dist/definitions.d.ts

@@ -0,0 +1,24 @@
+import type { z } from "zod";
+import type { ToolDefinitionLike } from "@vinhnt-sdk/schema";
+import type { ToolContext } from "./context.js";
+export type { ToolContext };
+import type { NestedJsonSchema } from "./json-schema.js";
+export type ToolRisk = "read" | "write" | "destructive" | "external";
+export interface ToolDefinition<TInput = unknown, TOutput = unknown> extends ToolDefinitionLike {
+    readonly inputSchema?: NestedJsonSchema | undefined;
+    readonly risk: ToolRisk;
+    /** Per-tool timeout in ms (overrides global default). */
+    readonly timeoutMs?: number;
+    /** Permission action key for the gate (e.g. "edit", "shell"). Optional; defaults to risk. */
+    readonly permissionAction?: string;
+    /** Zod schema for runtime input validation (carried from defineTool). */
+    readonly inputZodSchema?: z.ZodType<TInput>;
+    /** Zod schema for runtime output validation (carried from defineTool). */
+    readonly outputZodSchema?: z.ZodType<TOutput>;
+    /** If true, tool is not loaded into context until explicitly requested via search. */
+    readonly deferred?: boolean;
+    /** Tags for tool search (e.g. ["file", "read", "search"]). */
+    readonly tags?: readonly string[];
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+//# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,GAAG,UAAU,CAAC;AAErE,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,CAAE,SAAQ,kBAAkB;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6FAA6F;IAC7F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D"}

package/dist/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/definitions.js.map

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

package/dist/description-lint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ── Tool description lint (Phase 5) ──────────────────────────────────────
+ * LLM tool-selection accuracy depends on description quality: a bad or vague
+ * description ("Do stuff") makes the model pick the wrong tool or skip it.
+ * This module flags the common "smells" in tool descriptions so authors and
+ * CI can catch them early, mirroring API-doc review practices.
+ */
+export type DescriptionIssueCode = "empty" | "too-short" | "no-verb" | "vague" | "placeholder" | "too-long";
+export interface ToolDescriptionIssue {
+    readonly code: DescriptionIssueCode;
+    readonly message: string;
+}
+export interface ToolDescriptionReport {
+    readonly tool: string;
+    readonly description: string;
+    readonly issues: readonly ToolDescriptionIssue[];
+}
+/** Lint a single tool description. Returns the report (empty `issues` = clean). */
+export declare function lintToolDescription(tool: string, description: string): ToolDescriptionReport;
+/** Lint a list of tool definitions, returning only the ones with issues. */
+export declare function lintToolDefinitions(definitions: readonly {
+    id: string;
+    description: string;
+}[]): ToolDescriptionReport[];
+//# sourceMappingURL=description-lint.d.ts.map

package/dist/description-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"description-lint.d.ts","sourceRoot":"","sources":["../src/description-lint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,UAAU,CAAC;AAE5G,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAwCD,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,qBAAqB,CA6C5F;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,GAC1D,qBAAqB,EAAE,CAIzB"}

package/dist/description-lint.js

@@ -0,0 +1,90 @@
+/**
+ * ── Tool description lint (Phase 5) ──────────────────────────────────────
+ * LLM tool-selection accuracy depends on description quality: a bad or vague
+ * description ("Do stuff") makes the model pick the wrong tool or skip it.
+ * This module flags the common "smells" in tool descriptions so authors and
+ * CI can catch them early, mirroring API-doc review practices.
+ */
+/** Curated imperative verbs a tool description should start with. */
+const ACTION_VERBS = new Set([
+    "abort", "accept", "add", "analyze", "apply", "ask", "attach", "authenticate", "authorize",
+    "build", "calculate", "cancel", "check", "clear", "close", "commit", "compile", "convert",
+    "copy", "count", "create", "decode", "delete", "deploy", "describe", "detect", "diff",
+    "download", "edit", "encode", "execute", "explain", "export", "fetch", "find", "fix",
+    "format", "generate", "get", "initialize", "install", "invoke", "join", "launch", "list",
+    "load", "login", "manage", "merge", "monitor", "move", "open", "optimize", "parse",
+    "patch", "plan", "preview", "publish", "push", "query", "read", "rebuild", "refactor",
+    "register", "reload", "remove", "rename", "replace", "resolve", "restart", "restore",
+    "review", "rollback", "run", "save", "scan", "schedule", "search", "select", "send",
+    "set", "show", "simulate", "sort", "spawn", "stage", "start", "stop", "subscribe",
+    "summarize", "sync", "test", "trace", "track", "translate", "trigger", "undo", "update",
+    "upload", "use", "validate", "verify", "view", "wait", "write", "zoom",
+]);
+/** Leading adverbs that should be skipped when checking the first verb. */
+const LEADING_ADVERBS = new Set([
+    "recursively", "automatically", "quickly", "quietly", "silently", "lazily", "eagerly",
+    "simply", "always", "never", "only", "just", "also", "finally", "first", "then", "once",
+]);
+const MIN_DESCRIPTION_LENGTH = 12;
+const MAX_DESCRIPTION_LENGTH = 220;
+const MIN_WORDS = 4;
+const PLACEHOLDER_RE = /\b(todo|tbd|fixme|placeholder|lorem|coming soon)\b|\byour (tool|plugin)\b|\betc\.?\.?\s*$/i;
+function firstSignificantWord(description) {
+    const words = description.split(/\s+/);
+    for (const word of words) {
+        const normalized = word.toLowerCase().replace(/[^a-z]/g, "");
+        if (!normalized)
+            continue;
+        if (LEADING_ADVERBS.has(normalized))
+            continue;
+        return normalized;
+    }
+    return undefined;
+}
+/** Lint a single tool description. Returns the report (empty `issues` = clean). */
+export function lintToolDescription(tool, description) {
+    const issues = [];
+    const trimmed = description.trim();
+    if (!trimmed) {
+        return { tool, description: trimmed, issues: [{ code: "empty", message: "Tool description is empty — the model cannot decide when to use this tool." }] };
+    }
+    if (trimmed.length < MIN_DESCRIPTION_LENGTH) {
+        issues.push({
+            code: "too-short",
+            message: `Description is only ${trimmed.length} chars (min ${MIN_DESCRIPTION_LENGTH}) — too little signal for tool selection.`,
+        });
+    }
+    if (trimmed.length > MAX_DESCRIPTION_LENGTH) {
+        issues.push({
+            code: "too-long",
+            message: `Description is ${trimmed.length} chars (max ${MAX_DESCRIPTION_LENGTH}) — wasteful for the context window; keep the first sentence scannable.`,
+        });
+    }
+    const verb = firstSignificantWord(trimmed);
+    if (!verb || !ACTION_VERBS.has(verb)) {
+        issues.push({
+            code: "no-verb",
+            message: `Description should start with an imperative verb (e.g. "Fetch", "Create", "Search") but starts with "${verb ?? "nothing"}".`,
+        });
+    }
+    if (trimmed.split(/\s+/).length < MIN_WORDS) {
+        issues.push({
+            code: "vague",
+            message: `Description is too vague (${trimmed.split(/\s+/).length} words) — state what it does and on what input.`,
+        });
+    }
+    if (PLACEHOLDER_RE.test(trimmed)) {
+        issues.push({
+            code: "placeholder",
+            message: "Description contains placeholder/TODO text — replace with a real description.",
+        });
+    }
+    return { tool, description: trimmed, issues };
+}
+/** Lint a list of tool definitions, returning only the ones with issues. */
+export function lintToolDefinitions(definitions) {
+    return definitions
+        .map((d) => lintToolDescription(d.id, d.description))
+        .filter((report) => report.issues.length > 0);
+}
+//# sourceMappingURL=description-lint.js.map

package/dist/description-lint.js.map

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

package/dist/diff.d.ts

@@ -0,0 +1,7 @@
+export interface UnifiedDiff {
+    readonly diff: string;
+    readonly additions: number;
+    readonly removals: number;
+}
+export declare function generateDiff(filePath: string, oldContent: string, newContent: string): UnifiedDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CA6Bb"}

package/dist/diff.js

@@ -0,0 +1,26 @@
+export function generateDiff(filePath, oldContent, newContent) {
+    const oldLines = oldContent.split("\n");
+    const newLines = newContent.split("\n");
+    const maxLen = Math.max(oldLines.length, newLines.length);
+    const result = [];
+    let additions = 0;
+    let removals = 0;
+    for (let i = 0; i < maxLen; i++) {
+        const oldLine = i < oldLines.length ? oldLines[i] : "";
+        const newLine = i < newLines.length ? newLines[i] : "";
+        if (oldLine !== newLine) {
+            if (oldLines[i] !== undefined) {
+                result.push(`-${i + 1}: ${oldLine}`);
+                removals++;
+            }
+            if (newLines[i] !== undefined) {
+                result.push(`+${i + 1}: ${newLine}`);
+                additions++;
+            }
+        }
+    }
+    result.unshift(`--- a/${filePath}`);
+    result.unshift(`+++ b/${filePath}`);
+    return { diff: result.join("\n"), additions, removals };
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,UAAkB,EAClB,UAAkB;IAElB,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAEvD,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACxB,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;gBACrC,QAAQ,EAAE,CAAC;YACb,CAAC;YACD,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;gBACrC,SAAS,EAAE,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IACpC,MAAM,CAAC,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IAEpC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAC1D,CAAC"}